Creates a void container for composing elements in a regular grid. It is a box that arranges the elements it contains from top to bottom and from left to right, but can distribute the elements in lines or in columns.
The child elements are added to the control just like a vbox and hbox, sequentially. Then they are distributed accordingly the attributes ORIENTATION and NUMDIV. When ORIENTATION=HORIZONTAL children are distributed from left to right on the first line until NUMDIV, then on the second line, and so on. When ORIENTATION=VERTICAL children are distributed from top to bottom on the first column until NUMDIV, then on the second column, and so on. The number of lines and the number of columns can be easily obtained from the combination of these attributes:
if (orientation==IGBOX_HORIZONTAL) num_lin = child_count / num_div num_col = num_div else num_lin = num_div num_col = child_count / num_div
Notice that the total number of spaces can be larger than the number of actual children, the last line or column can be incomplete.
The column sizes will be based only on the width of the children of the reference line, usually line 0. The line sizes will be based only on the height of the children of the reference column, usually column 0.
It does not have a native representation.
Ihandle* IupGridBox(Ihandle *child, ...); [in C] Ihandle* IupGridBoxv(Ihandle **children); [in C] iup.gridbox{child, ...: ihandle} -> (elem: ihandle) [in Lua] gridbox(child, ...) [in LED]
child, ... : List of the identifiers that will be placed in the box. NULL must be used to define the end of the list in C. It can be empty.
Returns: the identifier of the created element, or NULL if an error occurs.
ALIGNMENTLIN (non inheritable): Vertically aligns the elements within each line. Possible values: "ATOP", "ACENTER", "ABOTTOM". Default: "ATOP". The alignment of a single line can also be set using "ALIGNMENTLINL", where "L" is the line index, starting at 0 from top to bottom.
ALIGNMENTCOL (non inheritable): Horizontally aligns the elements within each column. Possible values: "ALEFT", "ACENTER", "ARIGHT". Default: "ALEFT". The alignment of a single column can also be set using "ALIGNMENTCOLC", where "C" is the column index, starting at 0 from left to right.
EXPAND (non inheritable*): The default value is "YES". See the documentation of the attribute for EXPAND inheritance.
EXPANDCHILDREN (non inheritable): forces all children to expand in the given direction and to fully occupy its space available inside the box. Can be YES (both directions), HORIZONTAL, VERTICAL or NO. Default: "NO". This has the same effect as setting EXPAND on each child, but the box expansion will not be affected.
GAPLIN, CGAPLIN: Defines a vertical space in pixels between lines, CGAPLIN is in the same units of the SIZE attribute for the height. Default: "0".
GAPCOL, CGAPCOL: Defines a horizontal space in pixels between columns, CGAPCOL is in the same units of the SIZE attribute for the height. Default: "0".
NGAPLIN, NCGAPLIN, NGAPCOL, NCGAPCOL (non inheritable): Same as *GAP* but are non inheritable.
HOMOGENEOUSLIN (non inheritable): forces all lines to have the same vertical space, or height. The line height will be based on the highest child of the reference line (See SIZELIN). Default: "NO". Notice that this does not changes the children size, only the available space for each one of them to expand.
HOMOGENEOUSCOL (non inheritable): forces all columns to have the same horizontal space, or width. The column width will be based on the largest child of the reference column (See SIZECOL). Default: "NO". Notice that this does not changes the children size, only the available space for each one of them to expand.
MARGIN, CMARGIN: Defines a margin in pixels, CMARGIN is in the same units of the SIZE attribute. Its value has the format "widthxheight", where width and height are integer values corresponding to the horizontal and vertical margins, respectively. Default: "0x0" (no margin).
NMARGIN, NCMARGIN (non inheritable): Same as MARGIN but are non inheritable.
NUMDIV: controls the number of divisions along the distribution according to ORIENTATION. When ORIENTATION=HORIZONTAL, NUMDIV is the number of columns, when ORIENTATION=VERTICAL, NUMDIV is the number of lines. When value is AUTO, its actual value will be calculated to fit the maximum number of elements in the orientation direction. Default: AUTO.
NUMCOL (read-only): returns the number of columns.
NUMLIN (read-only): returns the number of lines.
NORMALIZESIZE (non inheritable): normalizes all children natural size to be the biggest natural size among the reference line and the reference column. All natural width will be set to the biggest width, and all natural height will be set to the biggest height according to is value. Can be NO, HORIZONTAL, VERTICAL or BOTH. Default: "NO". Same as using IupNormalizer.
ORIENTATION (non inheritable): controls the distribution of the children in lines or in columns. Can be: HORIZONTAL or VERTICAL. Default: HORIZONTAL.
SIZECOL (non inheritable): index of the column that will be used as reference when calculating the height of the lines. Default: 0.
SIZELIN (non inheritable): index of the line that will be used as reference when calculating the width of the columns. Default: 0.
WID (read-only): returns -1 if mapped.
SIZE, RASTERSIZE, FONT, CLIENTSIZE, CLIENTOFFSET, POSITION, MINSIZE, MAXSIZE: also accepted.
FLOATING (non inheritable) (at children only): If a child has FLOATING=YES then its size and position will be ignored by the layout processing. Default: "NO".
The box can be created with no elements and be dynamic filled using IupAppend or IupInsert.
The box will NOT expand its children, it will allow its children to expand according to the space left in the box parent. So for the expansion to occur, the children must be expandable with EXPAND!=NO, and there must be room in the box parent.
![]() |
NORMALIZE=BOTH![]() |
EXPANDCHILDREN=YES![]() |