IupFlatTabs
| Definition: |
include pGUI.e
Ihandle ih = IupFlatTabs(Ihandles children={}, string attributes="", dword_seq args={}) |
| 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. Identical to the IupTabs control but the decorations and buttons are manually drawn. It inherits from IupCanvas. children: List of the elements that will be placed in the box. It can be empty. For more information on the attributes and args parameters see IupSetAttributes. Returns: the identifier of the created element. |
| pwa/p2js: | Not supported. (May end up just getting aliased to IupTabs.) |
| 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. When flattabs has the focus, the current tab can be changed using the left and right arrow keys. (since 3.25) Differences from IupTabs:Appearance can be controlled for global features and for individual tabs.Child focus can be controlled without native problems. Tabs can be individually disabled using TABACTIVEid attribute. Tab change can be controlled by the callbacks and ignored. MULTILINE is NOT supported. Mnemonics are NOT supported. All the usual Iup(Get|Set)(Attribute|Int|Float)[Id] functions can be used here. The C functions IupFlatTabsV and IupFlatTabsv are not wrapped: children must be a sequence, rather than varargs or a pointer to dword-null-terminated memory. |
| Attributes: |
(non inheritable) Inherits all attributes and callbacks of the IupCanvas, but redefines a few attributes. BORDER and SCROLLBAR are always NO. |
| BGCOLOR |
background color for the current Tab and the children. Default: "255 255 255". It is non inheritable, but when set will internally propagate to the children (since 3.25). |
| CANFOCUS | (creation only) (non inheritable): enables the focus traversal of the control. Default: YES. |
| FOCUSFEEDBACK | (non inheritable): draw the focus feedback. Can be Yes or No. Default: Yes. (since 3.27) |
| PROPAGATEFOCUS | (non inheritable): enables the focus callback forwarding to the next native parent with FOCUS_CB defined. Default: NO. (since 3.23) |
| CHILDSIZEALL | (non inheritable): compute the natural size using all children. If set to NO will compute using only the current tab. Default: Yes. (since 3.27) |
| 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". |
| FIXEDWIDTH |
forces all tabs to use the same width, given by the attribute. It does not include padding, nor the close button space if any, i.e. padding and close button space will be added to the fixed width. |
| HASFOCUS | (read-only): returns the tabs state if it has focus. Can be Yes or No. (since 3.25) |
| 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. |
| SHOWLINES | when enabled the current tab will be separated of the other tabs by a line. Can be Yes or No. Default: Yes. |
| 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, so a new tab is made current internally. (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. Alignment does not includes the padding area. Default value: "6x4" (default changed in 3.29). |
| 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. If not defined it will use the background color of the parent. |
| 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) |
| TABSTEXTWRAP |
(non inheritable): For single line texts if the text is larger than its box the line will be automatically broken in multiple lines. Notice that this is done internally by the system, the element natural size will still use only a single line. For the remaining lines to be visible the element should use EXPAND=VERTICAL or set a SIZE/RASTERSIZE with enough height for the wrapped lines. (since 3.25) |
| TABSTEXTELLIPSIS | (non inheritable): If the text is larger that its box, an ellipsis ("...") will be placed near the last visible part of the text and replace the invisible part. It will be ignored when TEXTWRAP=Yes. (since 3.25) |
| TABSTEXTORIENTATION | (non inheritable): text angle in degrees and counterclockwise. The text size will adapt to include the rotated space. (since 3.25) |
| TABTYPE |
(non inheritable): the type of tabs, which can be "TOP", "BOTTOM", "LEFT" or "RIGHT". Default is "TOP". It will not automatically change the TABORIENTATION. When changed with the dialog visible the application should call IupRefresh or IupRefresh children to updated the layout when ready. (since 3.27) |
| TABORIENTATION | (non inheritable) the orientation of tab text, which can be "HORIZONTAL" or "VERTICAL". Default is "HORIZONTAL". When set to vertical it will simply set TABSTEXTORIENTATION to 90. (since 3.25) |
| TABSLINECOLOR | color of the separator line. Default: "160 160 160" |
| 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". Alignment does not includes the padding area. Default: "ACENTER:ACENTER". Partial values are also accepted, like "ARIGHT" or ":ATOP", the other value will be obtained from the default value. |
| 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. |
| TABIMAGEHIGHTLIGHTn | same as TABIMAGEn when in highlight state. If not defined TABIMAGEn is used. (since 3.22) |
| TABIMAGEINACTIVEn |
same as TABIMAGEn when in inactive state. If not defined TABIMAGEn is used and its colors will be replaced by a modified version creating the disabled effect. (since 3.22) |
| TABVISIBLEn | controls the visibility of 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. |
| TABACTIVEn | active state of the tab. Can be Yes or No. Default: Yes. |
| TABFORECOLORn | text color of the tab title. When not defined TABSFORECOLOR is used. |
| TABBACKCOLORn | background color of the tab. When not defined TABSBACKCOLOR is used. |
| TABHIGHCOLORn | highlight color of the tab title. 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. |
| TABTIPn | TIP of the tab. (since 3.22) |
| Tab Close Button Attributes | |
| CLOSEIMAGE |
image name to be used in the close button. Default: "IMGFLATCLOSE". Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. n starts at 0. See also IupImage. |
| CLOSEIMAGEPRESS | image name to be used in the close button in pressed state. Default: "IMGFLATCLOSEPRESS". |
| CLOSEIMAGEHIGHLIGHT | image name to be used in the close button in highlight state. |
| CLOSEIMAGEINACTIVE |
image name to be used in the close button in inactive state. If it is not defined then the CLOSEIMAGE is used and its colors will be replaced by a modified version creating the disabled effect. (since 3.22) |
| CLOSEPRESSCOLOR | background color of the close button in pressed state. Default: "50 150 255". (since 3.22) |
| CLOSEHIGHCOLOR | background color of the close button in highlight state. Default: "200 225 245". |
| Extra Buttons Attributes (non inheritable) | |
| EXTRABUTTONS |
sets the number of extra image buttons at right in the free space area. There can be any number of buttons. See the EXTRABUTTON_CB callback. Default: 0.
Button id starts at 1, and are positioned from right to left. Just like the tabs they do not affect natural width. But they also don’t affect the tabs title height, if button title or image are larger than the tabs title height they will be cropped. |
| EXTRATITLEid | text of the respective button. |
| EXTRAACTIVEid | active state of the button. Can be Yes or No. When not defined works as "Yes". |
| EXTRABORDERWIDTHid | width of the button border. Set this attribute to at least 1 to enable the border. Default: 0 (since 3.27) |
| EXTRASHOWBORDERid | always show the button border. If not defined the border is shown when highlighted or pressed. Default: NO (since 3.27) |
| EXTRABORDERCOLORid | color of the border. Default: "50 150 255" (since 3.27) |
| EXTRAFORECOLORid | text color of the button title. When not defined TABSFORECOLOR is used. |
| EXTRAPRESSCOLORid | background color of the button in pressed state. Default: "150 200 235". |
| EXTRAHIGHCOLORid | background color of the button in highlight state. Default: "200 225 245". |
| EXTRAFONTid | text font of the button. When not defined TABSFONT is used. |
| EXTRAIMAGEid |
image name to be used in the respective button. Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. n starts at 0. See also IupImage. |
| EXTRAIMAGEPRESSid | same as EXTRAIMAGEid when in pressed state. If not defined EXTRAIMAGEid is used. |
| EXTRAIMAGEHIGHLIGHTid | same as EXTRAIMAGEid when in highlight state. If not defined EXTRAIMAGEid is used. |
| EXTRAIMAGEINACTIVEid | same as EXTRAIMAGEid when in inactive state. If not defined EXTRAIMAGEid is used and its colors will be replaced by a modified version creating the disabled effect. |
| EXTRATIPid | TIP of the button. |
| EXTRATOGGLEid | enabled the toggle behavior. Default: NO. (since 3.27) |
| EXTRAVALUEid | Toggle’s state. Values can be "ON" or "OFF". Default: "OFF". (since 3.27) |
| Expand Button Attributes (non inheritable) | |
| EXPANDBUTTON |
uses the next free extra button to configure an expand button. The button allows to dynamically expand and collapse the tabs contents. When collapsed a click on a tab causes that tab to be temporarily expanded until it looses the focus. |
| EXPANDBUTTONPOS | (read-only): position of the expand button in the extra buttons. |
| EXPANDBUTTONSTATE | The expand button is on expand state. Can be Yes or No. Default: Yes. |
| Current Tab (non inheritable) | |
| VALUE |
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. When the tabs is created, the first element inserted is set as the current tab. When the current tab is changed is also scrolled to be visible (since 3.23). |
| VALUE_HANDLE | Changes the current tab by its handle. The value passed must be the handle of a child contained in the tabs. |
| VALUEPOS | Changes the active tab by its position, starting at 0. |
| 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. It is not updated if TABTITLEn is changed. |
| 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. It is not updated if TABIMAGEn is changed. |
| also | ACTIVE, FONT, SCREENPOSITION, POSITION, CLIENTSIZE, CLIENTOFFSET, MINSIZE, MAXSIZE, WID, TIP, RASTERSIZE, THEME, ZORDER, VISIBLE: also accepted. |
| Callbacks: |
Inherits all callbacks of the IupCanvas, but redefines a few of them. Including BUTTON_CB, MOTION_CB, GETFOCUS_CB, KILLFOCUS_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. In FLATBUTTON_CB and FLAT_MOTION_CB use IupConvertXYToPos to convert (x,y) coordinates in tab position (same as VALUEPOS) (since 3.23). |
| TABCHANGE_CB |
Callback called when the user shifts the active tab.
function tabchange_cb(Ihandle ih, new_tab, 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 Returns: if IUP_IGNORE is returned the current tab is NOT changed. |
| TABCHANGEPOS_CB |
Callback called when the user shifts the active tab. Called only when TABCHANGE_CB is not defined.
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 Returns: if IUP_IGNORE is returned the current tab is NOT changed. |
| TABCLOSE_CB |
Callback called when the user clicks on the close button. 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.
function rightclick_cb(Ihandle ih, integer pos) ih: identifier of the element that activated the event. pos: the tab position |
| EXTRABUTTON_CB |
Action generated when any mouse button is pressed or released.
function extrabutton_cb(Ihandle ih, integer button, pressed) ih: identifier of the element that activated the event. button: identifies the extra button. Can be 1, 2, 3, 4, and so on. (this is not the same as BUTTON_CB) pressed: indicates the state of the button (1=pressed, 0=released) |
| also | MAP_CB, UNMAP_CB, DESTROY_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB: All common callbacks are supported. |
| Example: | See demo\pGUI\IupFlatTabs.exw |
| See Also: | IupTabs, IupImage, IupButton |