CD - Canvas Draw

CD_NATIVEWINDOW - Native Window Driver (cdnative.h)

This driver provides access to an existing Native Window, a basic element of the user-interface system. It also provides access to other native handles like HDC handles in Windows.


The canvas is created by means of a call to the function cdCreateCanvas(CD_NATIVEWINDOW, Data), after which other functions in the CD library can be called as usual. This function creates a CD canvas based on an existing system canvas. The parameter Data is a pointer to a handle of the canvas. It is system-dependent, having a different meaning in each platform:

Microsoft Windows: can be the handle of the Windows window (HWND), or the handle of a previously created Device Context (HDC), or can be a string in the format "hdc width height" or, in C, "%p %d %d". To get the entire screen use a NULL data.
X-Windows: It is a string in the format "display window" or, in C, "%p %lu" (uses the default screen).

The given parameters must exists until cdKillCanvas is called. The HDC is released only if created inside cdCreateCanvas from an HWND or when data is NULL.

Any amount of such canvases may exist simultaneously, but they should not use the same window, except if you are using a GDI canvas and a GDI+ canvas at the same time for the same window.

In CDLUA, the creation parameter must be a string in X-Windows and a userdata in Microsoft Windows.

To use this driver in Windows using GDI+ is necessary to call cdUseContextPlus(1) before creating the canvas.

Exclusive Functions

void cdGetScreenSize(int *width, int *height, double *width_mm, double *height_mm); [in C]
ScreenSize() -> (width, heigth, mm_width, mm_height: number) [in Lua]

Equivalent to function cdCanvasGetSize, but returns the values relative to the main screen of the window system. It is not necessary to have an active canvas to call this function.

int cdGetScreenColorPlanes(void); [in C]
cd.GetScreenColorPlanes() -> (bpp: number) [in Lua]

Equivalent to function cdCanvasGetColorPlanes, but returns the value relative to the main screen of the window system. It is not necessary to have an active canvas to call this function.

Behavior of Functions

This driver is greatly platform-dependent. For further detail, see the Behavior of Functions in each platform: Microsoft Windows (GDI), Windows Using GDI+, X-Windows (XLIB). However, it should be noted that some functions behave differently from the basic functions of each platform.


  • cdCanvasActivate: updates the canvas size; the window might have been resized. If the canvas was created using a HDC, the size will not be updated.

    IMPORTANT: For the standard Win32 base driver (not GDI+) if your Windows does not have one of the styles CS_OWNDC or CS_CLASSDC, then a temporary HDC will be created everytime a cdCanvasActivate is called. To release this HDC call cdCanvasDeactivate after drawing. The IupCanvas control of the IUP library always have the CS_CLASSDC style, so this should be ignored for IUP applications.

Exclusive Attributes

  • "WINDOWRGN": set the shape of a window to the current complex clipping region (set only). If data is NULL the region is reset.