IupCanvas

Creates an interface element that is a canvas - a working area for your application.

Creation

Ihandle* IupCanvas(const char *action); [in C]
iup.canvas{} -> (elem: ihandle) [in Lua]
canvas(action) [in LED]

action: Name of the action generated when the canvas needs to be redrawn. It can be NULL.

Returns: the identifier of the created element, or NULL if an error occurs.

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.

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.

DX: Size of the thumb in the horizontal scrollbar. Also the horizontal page size. Default: "0.1".
DY: Size of the thumb in the vertical scrollbar. Also the vertical page size. Default: "0.1".
POSX: Position of the thumb in the horizontal scrollbar. Default: "0.0".
POSY: Position of the thumb in the vertical scrollbar. Default: "0.0".
XMIN: Minimum value of the horizontal scrollbar. Default: "0.0".
XMAX: Maximum value of the horizontal scrollbar. Default: "1.0".
YMIN: Minimum value of the vertical scrollbar. Default: "0.0".
YMAX: Maximum value of the vertical scrollbar. Default: "1.0".
LINEX: The amount the thumb moves when an horizontal step is performed. Default: 1/10th of DX. (since 3.0)
LINEY: The amount the thumb moves when a vertical step is performed. Default: 1/10th of DY. (since 3.0)
XAUTOHIDE: When enabled, if DX >= XMAX-XMIN then the horizontal scrollbar is hidden. Default: "YES". (since 3.0)
YAUTOHIDE: When enabled, if DY >= YMAX-YMIN then the vertical scrollbar is hidden. Default: "YES". (since 3.0)

TOUCH [Windows 7 Only]: enable the multi-touch events processing. (Since 3.3)

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.


ACTIVE, FONT, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, WID, TIP, SIZE, RASTERSIZE, ZORDER, VISIBLE: also accepted.

Drag & Drop attributes and callbacks are supported. 

Callbacks

ACTION: Action generated when the canvas needs to be redrawn.

int function(Ihandle *ih, float posx, float posy); [in C]
elem:action(posx, posy: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
posx: thumb position in the horizontal scrollbar. The POSX attribute value.
posy: thumb position in the vertical scrollbar. The POSY attribute value.

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 KILL_FOCUS_CB.

int function(Ihandle *ih, int focus); [in C]
elem:focus_cb(focus: number) -> (ret: number) [in Lua]

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)

int function(Ihandle* ih, int id, int x, int y, char* state); [in C]
elem:touch_cb(id, x, y: number, state: string) -> (ret: number) [in Lua]

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.
state: the touch point state. 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)

int function(Ihandle *ih, int count, int* pid, int* px, int* py, int* pstate) [in C]
elem:multitouch_cb(count: number, pid, px, py, pstate: table) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
count: Number of touch points in the array.
pid: Array of touch point ids.
px: Array of touch point x coordinates in pixels, relative to the top-left corner of the canvas.
py: Array of touch point y coordinates in pixels, relative to the top-left corner of the canvas.
pstate: Array 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.


MAP_CB, UNMAP_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB: All common callbacks are supported.

Drag & Drop attributes and callbacks are supported.

Notes

Note that some keys might remove the focus from the canvas. To avoid this, return IGNORE in the K_ANY callback.

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

Examples

Browse for Example Files

Windows
Classic
Windows
w/ Styles
Motif GTK