## IupCanvas

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

### Creation

    Ihandle* IupCanvas(const char *action); [in C]
    iup.canvas{} -> (ih: 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 differently to some other controls. Default: YES. (since 3.0)

PROPAGATEFOCUS(non inheritable): enables the focus callback forwarding to the next native parent with FOCUS_CB defined. Default: NO. (since 3.23)

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.

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.

DRAWDRIVER (read-only): returns the name of the draw driver in use by the IupDraw API. Can be: X11 (Motif), GDK (GTK), Cairo (GTK), D2D (Windows), GDI+ (Windows) or GDI (Windows). (since 3.25)

DRAWUSEGDI [Windows Only] (non inheritable): force the use of the old GDI driver, instead of the new DirectD2 driver. Used in the IupGauge, IupMatrix and Flat Scrollbars for better performance and backward compatibility. (since 3.26)

EXPAND (non inheritable): The default value is "YES". The natural size is the size of 1 character.

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)
SCROLLVISIBLE (read-only) [Windows Only]: Returns which scrollbars are visible at the moment. Can be: YES (both), VERTICAL, HORIZONTAL, NO. (since 3.31)

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.

ACTIVE, FONT, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, WID, TIP, SIZE, RASTERSIZE, ZORDER, VISIBLE, THEME: 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]
    ih: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. Old parameter in float format, use POSX attribute to get the value in double format.
posy: thumb position in the vertical scrollbar. The POSY attribute value. Old parameter in float format, use POSX attribute to get the value in double format.

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]
    ih: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]
    ih: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]
    ih: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, DESTROY_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.

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.

The IupDraw API can be used to draw in the canvas. But the ACTION callback function can NOT be called manually from inside the application, it must be invoked by the system, so if you need to redraw then call IupRedraw or IupUpdate.

In GTK uses GtkFixed, in Windows uses a custom window class called "IupCanvas", and in Motif uses xmDrawingArea.

### 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 - calls cdCanvasActivate
             then use CD primitives to draw the scene,
             finally calls cdCanvasFlush if using 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.

### Examples

Browse for Example Files

Windows Classic | Windows w/ Styles
--- | ---
Motif | GTK