IupFlatTabs (since 3.21)

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. Identical to the IupTabs control but the decorations and buttons are manually drawn. It inherits from IupCanvas.

Creation

Ihandle* IupFlatTabs(Ihandle* child, ...); [in C]
Ihandle* IupFlatTabsv(Ihandle** children); [in C]
iup.flattabs{child, ...: ihandle} -> (ih: ihandle) [in Lua]
flattabs(child, ...) [in LED]

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 in C or Lua, not in LED.

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

Attributes (non inheritable)

Inherits all attributes and callbacks of the IupCanvas, but redefines a few attributes. CANFOCUS, BORDER and SCROLLBAR are always NO.

BGCOLOR:  background color for the current Tab and the children. Default: "255 255 255". The only attribute that is inheritable.

FORECOLOR: text color for the current Tab. Default: "50 150 255".

HIGHCOLOR: text color for the highlighted Tab. The current Tab is never highlighted, so it affects only the other tabs. If not defined FORECOLOR will be used.

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.

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

EXPAND: The default value is "YES".

EXTRABOX (read-only): returns the extra box name so it can be used to add extra controls to the free area. Use IupSetHandle or IupSetAttributeHandle to associate a child to a name. In Lua you can also use the element reference directly. The extra box is a IupHbox that is usually empty.

EXTRABOX_HANDLE (read-only): returns the handle of the extra box.

FIXEDWIDTH: forces all tabs to use the same width. Default: No.

SHOWCLOSE: enables the close button on each tab. Default value: "NO". By default when closed the tab is hidden. To change that behavior use the TABCLOSE_CB callback.

CLOSEIMAGE: image name to be used in the close button. Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. n starts at 0. See also IupImage. Default: "IMGFLATCLOSE".

CLOSEIMAGEHIGH: image name to be used in the close button in highlight state. Default: "IMGFLATCLOSEHIGH".

CLOSEIMAGEPRESS: image name to be used in the close button in pressed state. Default: "IMGFLATCLOSEPRESS".

CLOSEHIGHCOLOR: background color of the close button in highlight state. Default: "200 220 245".

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

TABCHANGEONCHECK: call the TABCHANGE* callbacks when current tab is removed or hidden. (since 3.22)

TABSPADDING: 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: "10x10".

TABSFORECOLOR: text color of the tabs that are not the current tab. Default: the global attribute DLGFGCOLOR.

TABSBACKCOLOR: background color of the tabs that are not the current tab. Default: the global attribute DLGBGCOLOR.

TABSHIGHCOLOR: background highlight color of the tabs that are not the current tab. When not defined the background is not highlighted.

TABSFONT: text font of the tabs. When not defined FONT is used. It is a non inheritable option for setting the font.

TABSFONTSTYLE: text font style. When change will actually set TABSFONT.

TABSFONTSIZE: text font size. When change will actually set TABSFONT.

TABSTEXTALIGNMENT (non inheritable): Horizontal text alignment for multiple lines. Can be: ALEFT, ARIGHT or ACENTER. Default: ALEFT. (since 3.22)

SHOWLINES: when enabled the current tab will be separated of the other tabs by a line. Can be Yes or No. Default: Yes.

TABSLINECOLOR: color of the separator line. Default: "180 180 180"

TABSIMAGEPOSITION: position of the image relative to the text when both are displayed. Can be: LEFT, RIGHT, TOP, BOTTOM. Default: LEFT.

TABSIMAGESPACING: spacing between the image and the text. Default: "2".

TABSALIGNMENT: horizontal and vertical alignment of the set image+text. Possible values: "ALEFT", "ACENTER" and "ARIGHT",  combined to "ATOP", "ACENTER" and "ABOTTOM". Default: "ACENTER:ACENTER". Partial values are also accepted, like "ARIGHT" or ":ATOP", the other value will be used from the current alignment.

Tab Attributes (non inheritable)

TABIMAGEn: 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. When set after map will update the TABIMAGE attribute on the respective child.

TABVISIBLEn: 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: Contains the text to be shown in the respective tab title. n starts at 0. If this value is NULL, it will remain empty. When set after map will update the TABTITLE attribute on the respective child.

TABACTIVEn: active state of the tab.  Can be Yes or No. Default: Yes.

TABFORECOLORn: text color of the tab. When not defined TABSFORECOLOR is used.

TABBACKCOLORn: background color of the tab. When not defined TABSBACKCOLOR is used.

TABHIGHCOLORn: highlight color of the tab. When not defined TABSHIGHCOLOR is used.

TABFONTn: text font of the tab. When not defined TABSFONT is used.

TABFONTSTYLEn: text font style. When change will actually set TABFONTn.

TABFONTSIZEn: text font size. When change will actually set TABFONTn.

Current Tab (non inheritable)

VALUE: 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. In Lua you can also use the element reference directly.

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

VALUEPOS: Changes the current tab by its position, starting at 0. When the tabs is 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: also accepted.

Attributes (at Children)

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

Inherits all callbacks of the IupCanvas, but redefines a few of them. Including BUTTON_CB, MOTION_CB, and LEAVEWINDOW_CB. To allow the application to use those callbacks the same callbacks are exported with the "FLAT_" prefix using the same parameters. They are all called before the internal callbacks and if they return IUP_IGNORE the internal callbacks are not processed.

TABCHANGE_CB: Callback called when the user changes the current tab.

int function(Ihandle* ih, Ihandle* new_tab, Ihandle* old_tab); [in C]
ih:tabchange_cb(new_tab, old_tab: ihandle) -> (ret: number) [in Lua]

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

Returns: if IUP_IGNORE is returned the current tab is NOT changed.

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); [in C]
ih:tabchange_cb(new_pos, old_pos: number) -> (ret: number) [in Lua]

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

Returns: if IUP_IGNORE is returned the current tab is NOT changed.

TABCLOSE_CB [Windows and GTK Only]: Callback called when the user clicks on the close button. Called only when SHOWCLOSE=Yes.

int function(Ihandle* ih, int pos); [in C]
ih:tabclose_cb(pos: number) -> (ret: number) [in Lua]

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.

RIGHTCLICK_CB: Callback called when the user clicks on some tab using the right mouse button.

int function(Ihandle* ih, int pos); [in C]
ih:rightclick_cb(pos: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
pos: the tab 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.

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

IMPORTANT: Similar to IupZbox, IupFlatTabs does depends on the VISIBLE attribute. To proper functioning we strongly recommend using a IupBackgroundBox for each child.

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.

Differences from IupTabs:

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

 IupSetAttribute(ih, "TABVISIBLE2", "NO");
IupSetAttribute(ih, "TABACTIVE3", "NO");
IupSetAttribute(ih, "SHOWCLOSE", "Yes");
IupSetAttribute(ih, "TABFONTSTYLE4", "Bold");

 IupSetAttribute(ih, "FORECOLOR", "192 0 0");
IupSetAttribute(ih, "TABSBACKCOLOR", "192 0 0");
IupSetAttribute(ih, "HIGHCOLOR", "255 128 128");
IupSetAttribute(ih, "CLOSEHIGHCOLOR", "255 128 128");
IupSetAttribute(ih, "TABSFORECOLOR", "255 255 255");
IupSetAttribute(ih, "SHOWLINES", "NO");
IupSetAttribute(ih, "SHOWCLOSE", "NO");