/ 
IUP-0.305
River stage zero No dependents
/ IUP::Tabs

NAME

IUP::Tabs - [GUI element] allows a single dialog to have several screens, grouping options

DESCRIPTION

Creates a Tabs element. Allows a single dialog to have several screens, grouping options. The grouping is done in a single line of tabs arranged according to the tab type. Also known as Notebook in native systems.

Windows Classic Windows w/ Style

GTK

Motif

USAGE

CREATION - new() method

$tabs = IUP::Tabs->new( child=>[$elem1,$elem2], EXPAND=>'YES' );

child: (named parameter) List of the elements that will be placed in the box.

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

NOTE: You can pass to new() other ATTRIBUTE=>'value' or CALLBACKNAME=>\&func pairs relevant to this element - see IUP::Manual::02_Elements.

ATTRIBUTES

For more info about concept of attributes (setting/getting values etc.) see IUP::Manual::03_Attributes. Attributes specific to this element:

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.

COUNT

(read-only) (non inheritable)

Returns the number of tabs. Same value returned by GetChildCount. (since iup-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.

PADDING

(non inheritable)

Internal margin of the tab title. Works just like the MARGIN attribute of the IUP::Hbox and IUP::Vbox containers, but uses a different name to avoid inheritance problems. Default value: "0x0".

SIZE

(non inheritable)

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

TABIMAGE(n)(non inheritable)

<n> starts at 0.

Image name or IUP::Image reference to be used in the respective tab.

See - Using Images in Other Elements (via IMAGE Attribute)

In Motif, the image is shown only if TABTITLE(n) is undef. In Windows and Motif set the BGCOLOR attribute before setting the image.

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, VERTICAL is only supported when TABTYPE=LEFT or TABTYPE=RIGHT. (GTK 2.6)

TABTITLE(n) (non inheritable)

Contains the text to be shown in the respective tab title. n starts at 0. If this value is undef, 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 iup-3.3)

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 always. In Windows, when not TOP, then visual style is removed from tabs.

VALUE

(non inheritable)

Changes the active tab. The value passed must be the name (see SetName) of one of the elements contained in the tabs or a reference to such an element.

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.

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.

The following common attributes are also accepted:

CALLBACKS

For more info about concept of callbacks (setting callback handlers etc.) see IUP::Manual::04_Callbacks. Callbacks specific to this element:

TABCHANGE_CB

Callback called when the user shifts the active tab.

Callback handler prototype:

sub tabchange_cb_handler {
  my ($self, $new_tab, $old_tab) = @_;
  #...
}

    $self: reference to the element (IUP::Tabs) 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 iup-3.3)

Callback handler prototype:

sub tabchangepos_cb_handler {
  my ($self, $new_tab, $old_tab) = @_;
  #...
}

    $self: reference to the element (IUP::Tabs) that activated the event

    $new_pos: the new tab position selected by the user

    $old_pos: the previously selected tab position

The following common callbacks are also accepted:

NOTES

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

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

The Tabs children, differently from a IUP::Zbox, automatically receives a name if does not already have one when it is appended to the tabs in the native system. Also IUP::Tabs does NOT depends 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 SetFocus in the TABCHANGE_CB callback.

Utility Functions

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

$elem->SetAttributeId($name, $id, $value);
$elem->GetAttributeId($name, $id);

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

$elem->SetAttributeId("TABTITLE", 3, $value) ~~ $elem->SetAttribute("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

The element IUP::Tabs is used in the following sample scripts:

SEE ALSO

The original doc: iuptabs.html