IupScrollBox (since 3.7)

Creates a native container that allows its child to be scrolled. It inherits from IupCanvas.


Ihandle* IupScrollBox(Ihandle* child); [in C]
iup.scrollbox{child: ihandle} -> (ih: ihandle) [in Lua]
scrollbox(child) [in LED]

child: Identifier of an interface element which will receive the box. It can be NULL (nil in Lua), not optional in LED.

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


Inherits all attributes and callbacks of the IupCanvas, but redefines a few attributes.

BGCOLOR: will always use the background color of the native parent.

BORDER (creation only): it is always "NO".

CANFOCUS: is set to NO.

CANVASBOX (non inheritable): enable the behavior of a canvas box instead of a regular container. Can be Yes or No. Default: No. (since 3.20)

CHILDOFFSET: Allow to specify a position offset for the child. Available for native containers only. It will not affect the natural size, and allows to position controls outside the client area. Format "dxxdy", where dx and dy are integer values corresponding to the horizontal and vertical offsets, respectively, in pixels. Default: 0x0. (since 3.14)

EXPAND (non inheritable): The default value is "YES".

LAYOUTDRAG (non inheritable) [Windows Only]: When the scrollbar is moved automatically update the children layout. Default: YES. If set to NO then the layout will be updated only when the mouse drag is released. (since 3.19)

SCROLLBAR (creation only): the default value is "YES".

SCROLLTO (write-only): position the scroll at the given x,y coordinates relative to the box top-left corner. Format "x,y". Value can also be TOP or BOTTOM for a vertical scroll to the top or to the bottom of the scroll range. (since 3.17)

SCROLLTOCHILD (write-only): position the scroll at the top-left corner of the given child located by its name. Use IupSetHandle or IupSetAttributeHandle to associate an Ihandle* to a name. The child must be contained in the Scrollbox hierarchy. (since 3.17)

SCROLLTOCHILD_HANDLE (write-only): same as SCROLLTOCHILD but directly using the child handle. (since 3.17)



The box allows the application to create a virtual space for the dialog that is actually larger than the visible area. The current size of the box defines the visible area. The natural size of the child (and its children) defines the virtual space size.

So the IupScrollBox does not depend on its child size or expansion, and its natural size is always 0x0, except for the first time when it expands to the child natural size (since 3.19).

The user can move the box contents by dragging the background. Also the mouse wheel scrolls the contents vertically.

The box can be created with no elements and be dynamic filled using IupAppend or IupInsert.

Notice that it is possible to use the IupScrollBox to overcome the internal scrollbars of another control like IupMatrix by making all cells visible, but this will force all cells to be drawn all the time even when not visible at the scroll box, which is much slower than the internal IupMatrix optimization.


Browse for Example Files