Expand/Shrink

cdCreateCanvas

Definition: include pGUI.e

cdCanvas res = cdCreateCanvas(cdContext hCdContext, atom_string data, sequence params={})
Description: Creates a CD canvas for a virtual visualization surface (VVS).
pwa/p2js: Supported, for hCdContext of CD_IUP or CD_DBUFFER only. Often requires an explicit platform()=JS, see examples in demo/rosetta/, and there is no need for or (dummy) implementation of cd_context(), cdUseContextPlus(), or cdInitContextPlus().
Comments: A VVS may be the canvas of a user-interface window, the page of a document sent to a printer, an offscreen image, the clipboard, a metafile, and so on. To create the canvas, it is necessary to specify the driver in which each canvas is implemented. The driver is set by the driver variable with additional information provided in the data parameter. Even though it is possible to create more than one canvas with the same driver/data pair, this is not recommended, and its behavior is not specified. Each canvas maintains its own features.

In case of failure, a NULL value is returned. The following predefined drivers (hcdContext values) are available:

Window-Based Drivers
  • CD_IUP = IUP Canvas (cdiup.h).
  • CD_IUPDBUFFER = IUP Canvas Offscreen Drawing("").
  • CD_IUPDRAW = IUP Canvas using the IupDraw API internally (iupdraw_cd.h).
  • CD_NATIVEWINDOW = Native Window (cdnative.h).
  • CD_GL = Native Window (cdgl.h).
Device-Based Drivers
  • CD_CLIPBOARD = Clipboard (cdclipbd.h).
  • CD_PRINTER = Printer (cdprint.h).
  • CD_PICTURE = Picture in memory (cdpicture.h).
Image-Based Drivers
  • CD_IMAGE = Server-Image Drawing (cdimage.h).
  • CD_IMAGERGB = Client-Image Drawing (cdirgb.h).
  • CD_DBUFFER = Offscreen Drawing (cddbuf.h).
  • CD_DBUFFERRGB = Client Offscreen Drawing (cddbuf.h).
File-Based Drivers
  • CD_PDF = Adobe Portable Document Format (cdpdf.h).
  • CD_PS = PostScript File (cdps.h).
  • CD_SVG = Scalable Vector Graphics (cdsvg.h).
  • CD_METAFILE = Internal CD Metafile (cdmf.h).
  • CD_DEBUG = Internal CD Debug Log (cddebug.h).
  • CD_CGM = Computer Graphics Metafile ISO (cdcgm.h).
  • CD_DGN = MicroStation Design File (cddgn.h).
  • CD_DXF = AutoCad Drawing Interchange File (cddxf.h).
  • CD_EMF = Microsoft Windows Enhanced Metafile (cdemf.h). Works only in MS Windows systems.
  • CD_WMF = Microsoft Windows Metafile (cdwmf.h). Works only in MS Windows systems.

Note: The constants CD_IUP etc are initialised with abtruse values: by "abtruse" (not a real word) I mean a value designed to trigger an error if used directly, that makes some sense when debugging said error, and is automatically substituted within the pGUI wrapper by a proper value, ie/eg CD_IUP is {"CD_IUP"}, which is replaced using cd_context(CD_IUP). Should you need the proper values outside pGUI, use a similar function call, see the definition of type cdContext (ie, read pGUI.e, which checks for one of the above CD_XXX constants) for more details, but only if you must - there is a subtle issue here with the order in which things need to be initialised, but it is all quite straightforward really.

Since the third parameter is optional there is no need for a separate cdCreateCanvasf wrapper function in pGUI (simply delete the f).

The procedure cdUseContextPlus(boolean use) activates or deactivates the use of an external context for the next calls of the cdCreateCanvas function.

The procedure cdInitContextPlus() initializes the context driver to use another context replacing the standard drivers.
This function is only available when a library containing a "ContextPlus" context driver is used. See the Cairo, GDI+ and XRender base drivers.
Those libraries do not support XOR write mode, but have support for anti-aliasing and alpha for transparency.