IupTabs

Creates a native container for composing elements in hidden layers with only one layer visible (just like IupZbox), but its visibility can be interactively controlled. The interaction is done in a line of tabs with titles and arranged according to the tab type. Also known as Notebook in native systems.

Creation

Ihandle* IupTabs(Ihandle* child, ...);
Ihandle* IupTabsV(Ihandle* child, va_list arglist);
Ihandle* IupTabsv(Ihandle** children);

child, ... : List of the elements that will be placed in the box. NULL must be used to define the end of the list in C. It can be empty, but in C must have at least the NULL terminator.

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

Attributes

BGCOLOR: In Win32 the tab buttons background is always defined by the system and cannot be changed; its default also differs from the dialog background. Default: the global attribute DLGBGCOLOR.

CHILDOFFSET: Allow specifying 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.

CHILDSIZEALL (non-inheritable): compute the natural size using all children. If set to NO will compute using only the current tab. Default: YES.

COUNT (read-only) (non-inheritable): returns the number of tabs. Same value returned by IupGetChildCount.

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

FGCOLOR: Tabs title color. Not supported in EFL. In Win32 it is applied only when SHOWCLOSE=YES or in dark mode; in FLTK only the selected tab title is colored. Default: the global attribute DLGFGCOLOR.

ALLOWREORDER (non-inheritable): enables the user to reorder tabs by dragging them. Can be "YES" or "NO". Default: "NO". Not supported in Motif.

MULTILINE [Win32 and Qt Only] (non-inheritable): Enable multiple lines of tab buttons. This will hide the tab scroll and fits to make all tab buttons visible. Can be "YES" or "NO". Default "NO". It is always enabled when TABTYPE=LEFT or TABTYPE=RIGHT.

SHOWCLOSE (non-inheritable): enables the close button on each tab. Default value: "NO". In Windows the close button implies the classic visual for the control. By default, when closed the tab is hidden. To change that behavior, use the TABCLOSE_CB callback.

SHOWCLOSEONHOVER [macOS Only] (non-inheritable): When SHOWCLOSE=YES, close buttons on tabs are only shown when hovering over the tab. Can be "YES" or "NO". Default: "NO".

TABLIST [macOS Only] (non-inheritable): Shows a dropdown menu control in the tab bar that lists all tabs. Useful when there are too many tabs to display. Can be "YES" or "NO". Default: "NO".

SIZE (non-inheritable): The default size is the smallest size that fits its largest child. All child elements are considered even invisible ones.

TABORIENTATION (non-inheritable): Indicates the orientation of tab text, which can be "HORIZONTAL" or "VERTICAL". Default is "HORIZONTAL". VERTICAL can be set in GTK, GTK 4, Qt, macOS and WebAssembly. In Win32 and Haiku VERTICAL is also available but is not set directly: it follows the TABTYPE attribute, with TABTYPE=LEFT or TABTYPE=RIGHT giving VERTICAL and TABTYPE=TOP or TABTYPE=BOTTOM giving HORIZONTAL.

TABPADDING (non-inheritable): internal margin of the tab title. Works just like the MARGIN attribute of the IupHbox and IupVbox containers, but uses a different name to avoid inheritance problems. Default value: "0x0".

TABTYPE (non-inheritable): Indicates the type of tab, which can be "TOP", "BOTTOM", "LEFT" or "RIGHT". Default is "TOP". LEFT and RIGHT are supported in Win32, GTK, GTK 4, Motif, Qt, macOS and Haiku. In iOS, FLTK and Android only TOP and BOTTOM are supported. In EFL and WinUI only TOP is supported. It can be changed after map in GTK, GTK 4, Motif, macOS, iOS, Android and WebAssembly; in Win32, Qt, FLTK and Haiku it is set only before mapping. In Win32, TABTYPE=LEFT or TABTYPE=RIGHT also sets MULTILINE=YES and TABORIENTATION=VERTICAL, and TABTYPE=TOP or TABTYPE=BOTTOM sets TABORIENTATION=HORIZONTAL. In Win32, when not TOP the visual style is removed from the tabs.

Tab Attributes

TABIMAGEn (non-inheritable): image name to be used in the respective tab. Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. n starts at 0. See also IupImage. In Motif, the image is shown only if TABTITLEn is NULL. In Windows and Motif set the BGCOLOR attribute before setting the image. When set after map will update the TABIMAGE attribute on the respective child.

TABIMAGESIZE (non-inheritable): target size for tab icons, as "WxH", "N" (NxN), or "NATIVE" to keep the source size. Default is font-derived. Images larger than the box are downscaled with aspect preserved.

TABVISIBLEn (non-inheritable): Allows to hide a tab. n starts at 0. When a tab is hidden the tabs indices are not changed. Can be YES or NO. Default: YES.

TABTITLEn (non-inheritable): Contains the text to be shown in the respective tab title. n starts at 0. If this value is NULL, it will remain empty. The "&" character can be used to define a mnemonic, the next character will be used as a key. Use "&&" to show the "&" character instead on defining a mnemonic. The button can be activated from any control in the dialog using the "Alt+key" combination. When set after map it will update the TABTITLE attribute on the respective child.

TABTIPn (non-inheritable): tooltip text shown when the cursor hovers over the respective tab. n starts at 0.

Current Tab

VALUE (non-inheritable): Changes the current tab by its name. The value passed must be the name of one of the elements contained in the tabs. Use IupSetHandle or IupSetAttributeHandle to associate a child to a name.

VALUE_HANDLE (non-inheritable): Changes the current tab by its handle. The value passed must be the handle of a child contained in the tabs. When the tabs are created, the first element inserted is set as the visible child.

VALUEPOS (non-inheritable): Changes the current tab by its position, starting at 0. When the tabs are created, the first element inserted is set as the visible child. In GTK, inside the callback the returned value is still the previous one.

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

Attributes (at Children)

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

TABTITLE (non-inheritable) (at children only): Same as TABTITLEn but set in each child. Works only if set before the child is added to the tabs.

TABIMAGE (non-inheritable) (at children only): Same as TABIMAGEn but set in each child. Works only if set before the child is added to the tabs.

Callbacks

TABCHANGE_CB: Callback called when the user changes the current tab. It is not called when the current tab is programmatically changed or removed.

int function(Ihandle* ih, Ihandle* new_tab, Ihandle* old_tab);

ih: identifier of the element that activated the event.
new_tab: the new tab selected by the user
old_tab: the previously selected tab

TABCHANGEPOS_CB: Callback called when the user changes the current tab. Called only when TABCHANGE_CB is not defined.

int function(Ihandle* ih, int new_pos, int old_pos);

ih: identifier of the element that activated the event.
new_pos: the new tab position selected by the user
old_pos: the previously selected tab position

TABCLOSE_CB: Callback called when the user clicks on the close button. Called only when SHOWCLOSE=YES.

int function(Ihandle* ih, int pos);

ih: identifier of the element that activated the event.
pos: the tab position

Returns: the tab will be hidden if the callback returns IUP_DEFAULT or if it does not exists. If IUP_CONTINUE is returned the tab is removed and its children are destroyed. If IUP_IGNORE is returned does nothing.

FOCUS_CB: Called when a child of the container gets or loses the focus. It is called only if PROPAGATEFOCUS is defined in the child.

int function(Ihandle *ih, int focus);

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 losing the focus.

RIGHTCLICK_CB: Callback called when the user clicks on some tab using the right mouse button. Not supported in Android and iOS.

int function(Ihandle* ih, int pos);

ih: identifier of the element that activated the event.
pos: the tab position

REORDER_CB: Callback called when the user reorders a tab by dragging it to a new position. Called only when ALLOWREORDER=YES. Not supported in Motif.

int function(Ihandle* ih, int old_pos, int new_pos);

ih: identifier of the element that activated the event.
old_pos: the original tab position before the reorder.
new_pos: the new tab position after the reorder.

Returns: if IUP_IGNORE is returned the reorder is rejected and the tab returns to its original position.

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

Notes

The Tabs can be created with no children and be dynamic filled using IupAppend.

The ENTERWINDOW_CB and LEAVEWINDOW_CB callbacks are called only when the mouse enters or leaves the tabs buttons area.

Its children automatically receive a name when the child is appended or inserted into the tabs.

Differently from IupZbox, IupTabs does NOT depends on the VISIBLE attribute.

In GTK, when the tabs buttons are scrolled, the current tab is also changed.

When you change the current tab, the focus is usually not changed. If you want to control the focus behavior, call IupSetFocus in the TABCHANGE_CB callback. Unfortunately, this does not work in GTK and in Motif, because in both systems the focus will be set by the system after the callback is called.

Notice that there is no attribute to disable a single tab. This is a design decision of all native toolkits, not an IUP decision.

Utility Functions

These functions can be used to set and get attributes from the element:

void  IupSetAttributeId(Ihandle *ih, const char* name, int id, const char* value);
char* IupGetAttributeId(Ihandle *ih, const char* name, int id);
int   IupGetIntId(Ihandle *ih, const char* name, int id);
float IupGetFloatId(Ihandle *ih, const char* name, int id);
void  IupSetfAttributeId(Ihandle ih, const char* name, int id, const char* format, ...);
void  IupSetIntId(Ihandle* ih, const char* name, int id, int value);
void  IupSetFloatId(Ihandle* ih, const char* name, int id, float value);

They work just like the respective traditional set and get functions. But the attribute string is complemented with the id value. For ex:

IupSetAttributeId(ih, "TABTITLE", 3, value) == IupSetAttribute(ih, "TABTITLE3", value)

But these functions are faster than the traditional functions because they do not need to parse the attribute name string and the application does not need to concatenate the attribute name with the id.

Examples

Browse for Example Files

In Windows, the Visual Styles work only when TABTYPE is TOP. GTK is the only one that supports vertical text in the TOP configuration, but does not support multiple lines of tab buttons. Motif does not support vertical text.

GTK	Qt	Win32	macOS