IupBackgroundBox (since 3.10)

Creates a simple native container with no decorations. Useful for controlling children visibility for IupZbox or IupExpander. It inherits from IupCanvas.


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

child: Identifier of an interface element which will receive the box. It can be NULL (nil in Lua), or empty 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.

BACKIMAGE (non inheritable): image name to be used as background. Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. See also IupImage. When defined the ACTION callback of the IupCanvas will be defined. (since 3.26)

BACKIMAGEZOOM (non inheritable): if set the back image will be zoomed to occupy the full background. Aspect ratio is NOT preserved. Can be Yes or No. Default: No. (since 3.26)

BACKCOLOR (non inheritable): if defined used to fill the background color when BACKIMAGE is defined. If not defined BGCOLOR is used. (since 3.26)

BGCOLOR: by default will use the background color of the native parent, but can be set to a custom value (since 3.11).

BORDER (creation only): the default value is "NO".

CANVASBOX (non inheritable): enable the behavior of a canvas box instead of a regular container. This will affect the EXPAND attribute, the Natural size computation, and children layout distribution. Can be Yes or No. Default: No. (since 3.19)

CHILDOFFSET (non inheritable): 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)

DECORATION (non inheritable): Enable a decoration area around the child. Can be Yes or No. Default No. (since 3.20)

DECORSIZE (non inheritable): total size of the decoration in the format "WidthxHeight" (in C "%dx%d). Used only when DECORATION=Yes. (since 3.20)

DECOROFFSET (non inheritable): decoration offset from left border and top border in the format "XxY" (in C "%dx%d). Used only when DECORATION=Yes. (since 3.20)

EXPAND (non inheritable):  behaves as a container. See CANVASBOX attribute.

CANFOCUS> (non inheritable): the default is changed to NO. But it can receive the focus (since 3.19).



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

The ACTION callback can be defined and the application can draw bellow other children inside the BackgroundBox, but only with the IupDraw API. To avoid overlapping the drawing areas it is recommended that children must be inside native containers.


Browse for Example Files