Expand/Shrink

IupCanvas

Definition: include pGUI.e

Ihandle ih = IupCanvas([[nullable_string action=NULL,] cbfunc func=NULL,] string attributes="", dword_seq args={})
Description: Creates an interface element that is a canvas - a working area for your application.

action: name of the action generated when the canvas needs to be redrawn. It can be NULL. A typecheck error occurs if it is not NULL and not a string.
func: a callback address, usually specified as Icallback("name").
For more information on the attributes and args parameters see IupSetAttributes.
This is a paranormalised function.

Returns the identifier of the created element.
pwa/p2js: Supported, but see +x? markers on individual attributes and callbacks.
See Also: IupGLCanvas, IupGLCanvasBox, IupGLSubCanvas
Notes: Note that some keys might remove the focus from the canvas. To avoid this, return IUP_IGNORE in the K_ANY callback.

The mouse cursor position can be programmatically controlled using the global attribute CURSORPOS.

Drag & Drop attributes and callbacks are supported.

When the canvas is displayed for the first time, the callback call order is always:

MAP_CB
RESIZE_CB
ACTION

When the canvas is resized the ACTION callback is always called after the RESIZE_CB callback.

Using with the CD library


When using the CD library to draw in a IupCanvas, you can use the callbacks to manage the canvas. The simplest way is to do:

MAP_CB - calls cdCreateCanvas (current size is not available yet)
UNMAP_CB - calls cdKillCanvas
RESIZE_CB - Calling cdCanvasActivate() and cdCanvasGetSize() returns the same values as given by the callback parameters. Recalculate the drawing size, update the scrollbars if any.
ACTION - call cdCanvasActivate then use CD primitives to draw the scene, and finally call cdCanvasFlush() if using a double buffer.
SCROLL_CB - when using scrollbars, if this callback is defined the canvas must be manually redrawn, call yourself the action callback or call IupUpdate. In other words, if this callback is not defined the canvas is automatically redrawn.
Attributes:
BACKINGSTORE [Motif Only]: Controls the canvas backing store flag. The default value is "YES".
BGCOLOR+ Background color. The background is painted only if the ACTION callback is not defined.
If the callback is defined the application must draw all the canvas contents.
In GTK or Motif if you set the ACTION callback after map then you should also set BGCOLOR to any value just after setting the callback or the first redraw will be lost. Default: "255 255 255".
BORDER? (creation only): Shows a border around the canvas. Default: "YES".
CANFOCUS (creation only) (non inheritable): enables the focus traversal of the control. In Windows the canvas will respect CANFOCUS in opposite to the other controls. Default: YES. (since 3.0)
CAIRO_CR [GTK Only] (non inheritable): Contains the "cairo_t*" parameter of the internal GTK callback.
Valid only during the ACTION callback and onyl when using GTK version 3. (since 3.7)
CLIPRECT [Windows and GTK Only] (only during ACTION): Specifies a rectangle that has its region invalidated for painting, it could be used for clipping. Format: "%d %d %d %d"="x1 y1 x2 y2".
CURSOR (non inheritable): Defines a cursor for the canvas. The Windows SDK recommends that cursors and icons should be implemented as resources rather than created at run time.
EXPAND? (non inheritable): The default value is "YES". The natural size is the size of 1 character.
DROPFILESTARGET [Windows and GTK Only] (non inheritable): Enable or disable the drop of files. Default: NO, but if DROPFILES_CB is defined when the element is mapped then it will be automatically enabled.
DRAWSIZE (non inheritable): The size of the drawing area in pixels. This size is also used in the RESIZE_CB callback.
Notice that the drawing area size is not the same as RASTERSIZE+. The SCROLLBAR and BORDER attributes affect the size of the drawing area.
HDC_WMPAINT [Windows Only] (non inheritable): Contains the HDC created with the BeginPaint inside the WM_PAINT message.
Valid only during the ACTION callback.
HWND [Windows Only] (non inheritable, read-only): Returns the Windows Window handle. Available in the Windows driver or in the GTK driver in Windows.
SCROLLBAR? (creation only): Associates a horizontal and/or vertical scrollbar to the canvas. Default: "NO". The secondary attributes are all non inheritable.
TOUCH [Windows 7 Only]: enable the multi-touch events processing. (Since 3.3)
WHEELDROPFOCUS (non inheritable) when the wheel is used the focus control receives a SHOWDROPDOWN=No. (since 3.28)
XDISPLAY [UNIX Only](non inheritable, read-only): Returns the X-Windows Display. Available in the Motif driver or in the GTK driver in UNIX.
XWINDOW [UNIX Only](non inheritable, read-only): Returns the X-Windows Window (Drawable). Available in the Motif driver or in the GTK driver in UNIX.
also ACTIVE, FONT?, NAME, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, WID, TIP, SIZE+, RASTERSIZE+, ZORDER, VISIBLE: also accepted.
Callbacks:
ACTION Action generated when the canvas needs to be redrawn.

function action_cb(Ihandle ih)
ih: identifier of the element that activated the event.

Note that prior to version 1.0.2 the callback also had atom posx, posy parameters, which must now be replaced (if needed) with locally defined and retrieved values, atom posx = IupGetDouble(ih,"POSX"), posy = IupGetDouble(ih,"POSY"), and pGUI.e/IupSetCallback() now has a specific check for a routine signature of "FN" (and specifically not "FNNN" or "FNII").
BUTTON_CB Action generated when any mouse button is pressed or released.
DROPFILES_CB [Windows and GTK Only]: Action generated when one or more files are dropped in the element.
FOCUS_CB Called when the canvas gets or looses the focus. It is called after the common callbacks GETFOCUS_CB and KILLFOCUS_CB.

function focus_cb(Ihandle ih, integer focus)
ih: identifier of the element that activated the event.
focus: is non zero if the canvas is getting the focus, is zero if it is loosing the focus.
MOTION_CB Action generated when the mouse is moved.
KEYPRESS_CB Action generated when a key is pressed or released. It is called after the common callback K_ANY.

When the canvas has the focus, pressing the arrow keys may change the focus to another control in some systems.
If your callback process the arrow keys, we recommend you to return IUP_IGNORE so it will not lose its focus.
RESIZE_CB Action generated when the canvas size is changed.
SCROLL_CB Called when the scrollbar is manipulated. (GTK 2.8) Also the POSX and POSY values will not be correctly updated for older GTK versions.
TOUCH_CB [Windows 7 Only]: Action generated when a touch event occurred. Multiple touch events will trigger several calls. Must set TOUCH=Yes to receive this event. (Since 3.3)

function touch_cb(Ihandle ih, integer id, x, y, atom pState)
ih: identifies the element that activated the event.
id: identifies the touch point.
x, y: position in pixels, relative to the top-left corner of the canvas.
pState: the touch point state (char*). Can be: DOWN, MOVE or UP. If the point is a "primary" point then "-PRIMARY" is appended to the string.

Returns: IUP_CLOSE will be processed.
MULTITOUCH_CB [Windows 7 Only]: Action generated when multiple touch events occurred. Must set TOUCH=Yes to receive this event. (Since 3.3)

function mulittouch_cb(Ihandle ih, integer count, atom pid, px, py, pstate)
ih: identifier of the element that activated the event.
count: Number of touch points in the array.
pid: Array (int*) of touch point ids.
px: Array (int*) of touch point x coordinates in pixels, relative to the top-left corner of the canvas.
py: Array (int*) of touch point y coordinates in pixels, relative to the top-left corner of the canvas.
pstate: Array (int*) of touch point states. Can be 'D' (DOWN), 'U' (UP) or 'M' (MOVE).

Returns: IUP_CLOSE will be processed.
WHEEL_CB Action generated when the mouse wheel is rotated.
WOM_CB [Windows Only]: Action generated when an audio device receives an event.
also MAP_CB, UNMAP_CB, DESTROY_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB: All common callbacks are supported.