Definition: |
include pGUI.e
Ihandle ih = IupTabs(Ihandles children={}, string attributes="", sequence data={}) |
|||||||||||||||||
Description: |
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.
children: List of the elements that will be placed in the box. It can be empty. For more information on the attributes and data parameters see IupSetAttributes. Returns: the identifier of the created element. |
|||||||||||||||||
Notes: |
The tab control can be created with no children and filled dynamically using IupAppend. There is no "IupTabItem", instead the children can be any standard element, with IupHbox and IupVbox being the most likely/useful. The ENTERWINDOW_CB and LEAVEWINDOW_CB callbacks are called only when the mouse enter or leaves the tabs buttons area. Its children automatically receives a name when the child is appended or inserted into the tabs. Differently from IupZbox, IupTabs does NOT depend on the VISIBLE attribute. In GTK, when the tabs buttons are scrolled, the active tab is also changed. When you change the active 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 works 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 a IUP decision. It is so because a disabled tab is a confusing interface situation. In Windows, when an IupValuator is inside an IupTabs, the tabs disappear when the mouse moves over it after being used in the valuator. A workaround is to put the valuator inside an IupFrame and then inside the IupTabs, so the problem does not occur. The utility functions IupSetAttributeId, IupGetAttributeId, IupGetIntId, IupGetFloatId, IupSetIntId, and IupSetFloatId can also be used here. Note that the C function IupSetfAttributeId is not wrapped by pGUI, however that functionality is covered by the optional parameters of IupSetStrAttributeId. They work just like the respective traditional set and get functions, but the attribute string is complemented with the id value. For example: IupSetAttributeId(ih, "TABTITLE", 3, value) == IupSetAttribute(ih, "TABTITLE3", value) 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. |
|||||||||||||||||
Attributes: | ||||||||||||||||||
BGCOLOR |
In Windows and in GTK when in Windows, the tab buttons background it will be always defined by the system. In Windows the default background is different from the dialog background. Default: the global attribute DLGBGCOLOR. |
|||||||||||||||||
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) | |||||||||||||||||
COUNT | (read-only) (non inheritable) returns the number of tabs. Same value returned by IupGetChildCount. (since 3.3) | |||||||||||||||||
EXPAND | (non inheritable) The default value is "YES". | |||||||||||||||||
FGCOLOR | Tabs title color. Default: the global attribute DLGFGCOLOR. | |||||||||||||||||
MULTILINE | [Windows 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. (since 3.0) | |||||||||||||||||
PADDING | (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". (since 3.0) | |||||||||||||||||
SHOWCLOSE | [Windows and GTK Only] (non inheritable) enables the close button on each tab. Default value: "NO". In Windows the close button imply the classic visual for the control. By default when closed the tab is hidden. To change that behavior use the TABCLOSE_CB callback. (since 3.10) | |||||||||||||||||
SIZE | (non inheritable) The default size is the smallest size that fits its largest child. All child elements are considered even invisible ones. | |||||||||||||||||
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 (since 3.10). (since 3.0) | |||||||||||||||||
TABORIENTATION | (non inheritable) Indicates the orientation of tab text, which can be "HORIZONTAL" or "VERTICAL". Default is "HORIZONTAL". VERTICAL is supported only in GTK and in Windows. In Windows, it can NOT be set, it is dependent on the TABTYPE attribute, if TABTYPE=LEFT or TABTYPE=RIGHT then TABORIENTATION=VERTICAL, if TABTYPE=TOP or TABTYPE=BOTTOM then TABORIENTATION=HORIZONTAL. (GTK 2.6) | |||||||||||||||||
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. (since 3.8) | |||||||||||||||||
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 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. (mnemonic support since 3.3). When set after map will update the TABTITLE attribute on the respective child (since 3.10). (since 3.0) | |||||||||||||||||
TABTYPE | (non inheritable) (creation only in Windows) Indicates the type of tab, which can be "TOP", "BOTTOM", "LEFT" or "RIGHT". Default is "TOP". In Windows, if LEFT or RIGHT then MULTILINE=YES and TABORIENTATION=VERTICAL are set, if TOP or BOTTOM then TABORIENTATION=HORIZONTAL is set. In Windows, when not TOP, then visual style is removed from tabs. | |||||||||||||||||
VALUE | (non inheritable) Changes the active 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 active 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. (since 3.0) | |||||||||||||||||
VALUEPOS | (non inheritable) Changes the active 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. (since 3.0) | |||||||||||||||||
also | 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: | ||||||||||||||||||
TABCHANGE_CB |
Callback called when the user shifts the active tab.
function tabchange_cb(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 shifts the active tab. Called only when TABCHANGE_CB is not defined. (since 3.3)
function tabchangepos_cb(Ihandle ih, integer new_pos, 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 |
[Windows and GTK Only] Callback called when the user clicks on the close button (since 3.10). Called only when SHOWCLOSE=Yes.
function tabclose_cb(Ihandle ih, integer 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. |
|||||||||||||||||
RIGHTCLICK_CB |
Callback called when the user clicks on some tab using the right mouse button (since 3.10).
function rightclick_cb(Ihandle ih, integer pos) ih: identifier of the element that activated the event. pos: the tab position |
|||||||||||||||||
also | MAP_CB, UNMAP_CB, DESTROY_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB: All common callbacks are supported. | |||||||||||||||||
Examples: |
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.
A simple and runnable demonstration of IupTabs can be found in demo\pGUI\tabs.exw. Note that the main Edix window uses a "zero height" IupTabs and a single canvas that is fully redrawn on tab change, and filedump.exw does a similar trick over a single listview, hence neither should be copied(/studied) for more traditional uses, by which I specifically mean where selecting a different tab automatically hides some controls and displays some others. |
|||||||||||||||||
See Also: | IupImage, IupButton |