/ 
IUP-0.304_1
River stage zero No dependents
/ IUP::Manual::02_Elements

NAME

IUP::Manual::02_Elements - GUI elements guide, methods common for all IUP elements

IUP MANUAL

INTRODUCTION

This document is intended as a reference list for common methods used by all IUP elements.

For more information about using elemets see Elements Concept in IUP::Manual::01_Introduction.

Currently available interface elements can be categorized as follows:

  • Primitives (effective user interaction): dialog, label, button, text, multi-line, list, toggle, canvas, frame, image.

  • Composition (ways to show the elements): hbox, vbox, zbox, fill.

  • Grouping (definition of a common functionality for a group of elements): radio.

  • Menu (related both to menu bars and to pop-up menus): menu, submenu, item, separator.

  • Additional (elements built outside the main library): dial, gauge, matrix, tabs, valuator, OpenGL canvas, color chooser, color browser.

  • Dialogs (useful predefined dialogs): file selection, message, alarm, data input, list selection.

CREATING ELEMENTS

new()

Basic method for creating new element (constructor):

$elem = IUP::Button->new();

#or you can specify also some attribute values:
$elem = IUP::Button->new( TITLE=>"b1", SIZE=>"30x30");

#or you can specify also some callback handlers:
$elem = IUP::Button->new( TITLE=>"b1", SIZE=>"30x30",
                          ACTION=>\&func1, BUTTON_CB=>\&func2 );

#some elements accept 'child' (lowercase!!) parameter
$elem = IUP::Vbox->new( MARGIN=>10, child=>[$elem1, $elem2] );

#you can also assign a name (alias) to created element via 'name' parameter
$elem = IUP::Button->new( TITLE=>"b1", name=>"mybutton");
#...later in your code
$button = IUP->GetByName("mybutton");

new_no_ihandle()

$elem = IUP::Button->new_no_ihandle();

BEWARE: just for experts, you very likely do not need this at all!

new_from_ihandle()

$elem = IUP::Button->new_from_ihandle($ihandle);

BEWARE: just for experts, you very likely do not need this at all!

COMMON METHODS

Append()

    Inserts an interface element at the end of the container, after the last element of the container. Valid for any element that contains other elements like dialog, frame, hbox, vbox, zbox or menu.

    $element->Append($new_child);

    $ih: Identifier of a container like hbox, vbox, zbox and menu.

    $new_child: Identifier of the element to be inserted.

    Returns: the actual parent if the interface element was successfully inserted. Otherwise returns undef. Notice that the desired parent can contains a set of elements and containers where the child will be actually attached so the function returns the actual parent of the element.

    Notes:

    This function can be used when elements that will compose a container are not known a priori and should be dynamically constructed.

    The new child can NOT be mapped. It will NOT map the new child into the native system. If the parent is already mapped you must explicitly call Map, for the appended child.

    If the actual parent is a layout box (IUP::Vbox, IUP::Hbox or IUP::Zbox) and you try to append a child that it is already at the parent child list, then the child is moved to the last child position.

    The elements are NOT immediately repositioned. Call Refresh for the container (or any other element in the dialog) to update the dialog layout.

    See Also: Detach, Insert, Map, Unmap, Refresh, IUP::Hbox, IUP::Vbox, IUP::Zbox, IUP::Menu.

ConvertXYToPos()

    Converts a (x,y) coordinate in an item position.

    my $position = $element->ConvertXYToPos($x, $y);

    $ih: Identifier of the element.

    $x: X coordinate of the left corner of the interface element.

    $y: Y coordinate of the upper part of the interface element.

    Returns: the position starting at 0 (except for IUP::List that starts at 1). If fails returns -1.

    Notes:

    It can be used for IUP::Text (returns a position in the string), IUP::List (returns an item) or IUP::Tree (returns a node identifier).

    See Also: IUP::Text, IUP::List, IUP::Tree.

Destroy()

    Destroys an interface element and all its children. Only dialogs, timers, popup menus and images should be normally destroyed, but detached controls can also be destroyed.

    $element->Destroy();

    Notes:

    It will automatically unmap and detach the element if necessary, and then destroy the element.

    This function also deletes the main names associated to the interface element being destroyed, but if it has more than one name then some names may be left behind.

    Menu bars associated with dialogs are automatically destroyed when the dialog is destroyed.

    Images associated with controls are NOT automatically destroyed, because images can be reused in several controls the application must destroy them when they are not used anymore.

    All dialogs and all elements that have names are automatically destroyed in Close.

    See Also: Append, Detach, Map, Unmap, Create.

Detach()

    Detaches an interface element from its parent.

    $element->Detach();

    Notes:

    It will automatically call Unmap to unmap the element if necessary, and then detach the element.

    If left detached it is still necessary to call Destroy to destroy the IUP element.

    The elements are NOT immediately repositioned. Call Refresh for the container (or any other element in the dialog) to update the dialog layout.

    When the element is mapped some attributes are stored only in the native system. If the element is unmaped those attributes are lost. Use the function SaveClassAttributes when you want to unmap the element and keep its attributes.

    See Also: Append, Insert, Refresh, Unmap, Create, Destroy.

GetAllAttributes()

    Returns the names of all attributes of an element that are defined in its internal hash table only.

    my @attr_names1 = $element->GetAllAttributes();
#or
my @attr_names2 = $element->GetAllAttributes($max_n);

    $max_n: maximum number of names the table can receive. Can be omitted.

    Returns: reference to array with names. If $max_n is undef or $max_n is 0 then returns all names.

    See Also: GetAttribute, SetAttribute.

GetAttribute()

    Returns the value of an interface element attribute.

    my $val = $element->GetAttribute($name);
#or
my @values = $element->GetAttribute(@names);

    $name: name of the attribute.

    $id: used when the attribute has an additional id.

    Returns: the attribute value or undef if the attribute is not defined or does not exist.

    Notes:

    Examples:

    Browse for Example Files

    See Also:

    SetAttribute.

GetAttributeAsElement()

    Returns the reference to IUP element stored into an attribute of given name.

    my $elem = $element->GetAttribute($name);
#or
my @elems = $element->GetAttribute(@names);

    $name: name of the attribute.

    Returns: reference to iup element

GetAttributeId()

    my $val = $element->GetAttributeId($name, $id);

    Equivalent (just little bit faster) to:

    my $val = $element->GetAttribute("$name$id");

GetAttributeId2()

    my $val = $element->GetAttributeId2($name, $lin, $col);

    Equivalent (just little bit faster) to:

    my $val = $element->GetAttribute("$name$lin$col");

GetAttributes()

    Returns all attributes of a given element that are in the internal hash table. The known attributes that are pointers (not strings) are returned as integers.

    The internal attributes are not returned (attributes prefixed with "_IUP").

    Before calling this function the application must ensure that there is no pointer attributes set for that element, although some known pointers are handled.

    This function should be avoided. Use GetAllAttributes instead.

    my $attr = $element->GetAttributes();
#later on
print "Title=", $attr->{TITLE}, "\n";
print "Color=", $attr->{FGCOLOR}, "\n";

    Returns: a hash of ATTRIBUTE => VALUE pairs for all attributes of given element.

    See Also: GetAttribute, GetAllAttributes, SetAttribute.

GetBrother()

    Returns the brother of a control or undef if there is none.

    my $brother_elem = $element->GetBrother();

    Returns: reference to iup element

    See Also: GetChild, GetNextChild, GetParent.

GetChild()

    Returns the a child of the given control given its position.

    my $child_elem = $element->GetChild($position);

    $position: position of the desire child.

    Notes:

    This function will return the children of the control in the exact same order in which they were assigned.

    See Also: GetChildPos, GetNextChild, GetBrother, GetParent.

GetChildCount()

GetChildPos()

    Returns the position of a child of the given control.

    my $position = $elmenet->GetChildPos($child_element);

    $child_element: reference to child element

    Returns: position of the desire child or -1 if child not found.

    Notes:

    This function will return the children of the control in the exact same order in which they were assigned.

    See Also: GetChild, GetChildCount, GetNextChild, GetBrother, GetParent.

GetClassName()

    Returns the name of the class of an interface element.

    my $name = $element->GetClassName();

    Notes:

    The following names are known:

    "image"
"button"
"canvas"
"dialog"
"fill"
"frame" 
"hbox"
"item"
"separator"
"submenu"
"label"
"list"
"menu"
"radio"
"text" 
"toggle"
"vbox"
"zbox"
"multiline"
"user"
"matrix"
"tree"
"dial"
"gauge"
"val"
"glcanvas"
"tabs"
"cells"
"colorbrowser"
"colorbar"
"spin"
"sbox"
"cbox"
"progressbar"
"olecontrol"

    See Also: GetClassType, GetClassAttributes.

GetClassType()

    Returns the name of the native type of an interface element.

    my $type = $element->GetClassType();

    Notes:

    There are only a few pre-defined class types:

    "void" - No native representation - HBOX, VBOX, ZBOX, FILL, RADIO
"control" - Native controls - BUTTON, LABEL, TOGGLE, LIST, TEXT, MULTILINE, ITEM, SEPARATOR, SUBMENU, FRAME, others
"canvas" - Drawing canvas, also used as a base control for custom controls.
"dialog"
"image"
"menu"

    See Also: GetClassName, GetClassAttributes.

GetDialog()

    Returns the handle of the dialog that contains that interface element. Works also for children of a menu that is associated with a dialog.

    my $dialog = $element->GetDialog();

    $ih: Identifier of an interface element.

    Returns: the handle of the dialog or undef if not found.

GetDialogChild()

    Returns the identifier of the child element that has the NAME attribute equals to the given value on the same dialog hierarchy. Works also for children of a menu that is associated with a dialog.

    my $child_elem = $element->GetDialogChild($name);

    $ih: Identifier of an interface element that belongs to the hierarchy.

    $name: name of the control to be found

    Returns: reference to iup element, undef if not found

    Notes:

    This function will only found the child if the NAME attribute is set at the control.

    Before the dialog is mapped the function searches the hierarchy, even if the hierarchy does not belongs to a dialog yet, but after the child is mapped the result is immediate (the hierarchy is not searched).

    See Also: NAME.

GetName()

    Returns the name of an interface element, if the element has an associated name using SetName or by name=>'ElemName' named parameter of new() constructor or using LED.

    my $name = $element->GetName();

    Returns: the name.

    See Also: SetName (element method), GetByName (global function), GetAllNames (global function).

GetNextChild()

    Returns the a child of the given control given its brother.

    my $child_elem = $element->GetNextChild($child);

    $child: Identifier of the child brother to be used as reference. To get the first child use undef.

    Returns: the handle of the child or undef.

    Notes:

    This function will return the children of the control in the exact same order in which they were assigned. If child in not undef then it returns exactly the same result as GetBrother.

    Examples:

    my $bt = IUP::Button->new( TITLE=>"Button" );
my $lb = IUP::Label->new( TITLE=>"Label" );
my $vbox = IUP::Vbox->new( child=>[$bt, $lb] );
my $dialog = IUP::Dialog->new( child=>$vbox );

$dialog->Show();

my $child = undef; #passing undef to GetNextChild gives the first child

while($child = $vbox->GetNextChild($child)) {
  print "vbox has a child of type ", ref($child), "\n";
}

IUP->MainLoop;
return 0;

    See Also: GetBrother, GetParent, GetChild.

GetParamParam()

    To retrieve a parameter of IUP->GetParam dialog you must use the following function:

    my $element = $dialog->GetParamParam($param_index);

    $dialog: Reference to IUP::Dialog object.

    $param_index: Parameter to be retrieved.

GetParamValue()

    Helper method related to GetParamParam, nicer way for getting item values than calling GetParamParam()

    $value = $self->GetParamValue($index)

    GetParamValue can be also used as a setter:

    $self->GetParamValue($index, $value)

GetParent()

    Returns the parent of a control.

    my $parent_elem = $element->GetParent();

    Returns: the handle of the parent or undef if does not have a parent.

    See Also: GetChild, GetNextChild, GetBrother.

HasValidClassName()

    $element->HasValidClassName()

    Checks whether internal iup classname of given element is consistent with perl class name - e.g. button vs. IUP::Button

    Returns: 1 (if element internal iup classname corresponds to perl class), 0 otherwise

Insert()

    Inserts an interface element before another child of the container. Valid for any element that contains other elements like dialog, frame, hbox, vbox, zbox, menu, etc.

    my $parent = $element->Insert($ref_child, $new_child);

    $ih: Identifier of a container like hbox, vbox, zbox and menu.

    $ref_child: Identifier of the element to be used as reference. Can be undef to insert as the first element.

    $new_child: Identifier of the element to be inserted before the reference.

    Returns: the actual parent if the interface element was successfully inserted. Otherwise returns undef. Notice that the desired parent can contains a set of elements and containers where the child will be actually attached so the function returns the actual parent of the element.

    Notes:

    This function can be used when elements that will compose a container are not known a priori and should be dynamically constructed.

    The new child can NOT be mapped. It will NOT map the new child into the native system. If the parent is already mapped you must explicitly call Map for the appended child.

    If the actual parent is a layout box (IUP::Vbox, IUP::Hbox or IUP::Zbox) and you try to insert a child that it is already at the parent child list, then the child is moved to the insert position.

    The elements are NOT immediately repositioned. Call Refresh for the container* to update the dialog layout (* or any other element in the dialog).

    See Also: Append, Detach, IUP::Hbox, IUP::Vbox, IUP::Zbox, IUP::Menu, Map, Unmap, Refresh.

IsValidCallbackName()

    Checks whether callback_name is valid for given element.

    $element->IsValidCallbackName($callback_name);

    $callback_name: call back name - e.g. "ACTION"

    Returns: 1 (valid) or 0 (invalid)

Map()

    Creates (maps) the native interface objects corresponding to the given IUP interface elements.

    It will also create the native element of all the children in the element's tree.

    The element must be already attached to a container if not a dialog.

    my $retval = $element->Map();

    Returns: IUP_NOERROR if successful. If the element was already mapped returns IUP_NOERROR. If the native creation failed returns IUP_ERROR.

    Notes:

    If the element is a dialog then the abstract layout will be updated even if the element is already mapped. If the dialog is visible the elements will be immediately repositioned. Calling Map for an already mapped dialog is the same as only calling Refresh for the dialog.

    If you add new elements to an already mapped dialog you must call Map for that elements. And then call Refresh to update the dialog layout.

    If the WID attribute is undef, it means the element was not already mapped. Some containers do not have a native element associated, like VBOX and HBOX. In this case their WID is a fake (-1) value.

    A child is only mapped if its parent is already mapped.

    This function is automatically called before the dialog is shown in Show, ShowXY or Popup.

    It is usefull for the application to call Map when the value of the WID attribute must be known, or the native element must exist, before a dialog is made visible.

    The MAP_CB callback is called just after the native element is created and the dialog layout updated, so it can also be used to create other things that depend on the WID attribute.

    See Also: Append, Detach, Unmap, Create, Destroy, ShowXY, Show, Popup, MAP_CB.

NextField()

    Shifts the focus to the next element that can have the focus. It is relative to the given element and does not depend on the element currently with the focus.

    It will search for the next element first in the children, then in the brothers, then in the uncles and their children, and so on.

    This sequence is not the same sequence used by the Tab key, which is dependent on the native system.

    my $next_elem = $element->NextField();

    Returns: the element that received the focus or undef if not found.

    See Also: PreviousField.

PreviousField()

    Shifts the focus to the previous element that can have the focus. It is relative to the given element and does not depend on the element currently with the focus.

    my $prev_elem = $element->PreviousField();

    Returns: the element that received the focus or undef if not found.

    See Also:

    NextField.

Redraw()

    Force the element and its children to be redraw immediately.

    $element->Redraw($children);

    $children: flag to update its children (0 or 1)

Refresh()

    Updates the size and layout of controls after changing size attributes. Can be used for any element inside a dialog, the layout of the dialog will be updated. It can change the layout of all the controls inside the dialog because of the dynamic layout positioning.

    $element->Refresh();

    Notes:

    Can be used for any control, but it will always affect the whole dialog. Can be called even if the dialog is not mapped.

    The elements are immediately repositioned, if the dialog is visible then the change will be immediately reflected on the display.

    This function will NOT change the size of the dialog, except when the SIZE or RASTERSIZE attributes of the dialog where changed before the call.

    If you also want to change the size of the dialog use:

    $dialog->SetAttribute("SIZE", $newsize);
$dialog->Refresh();

    So the dialog will be resized for the new User size, if the new size is undef the dialog will be resized to the Natural size that include all the elements.

    Changing the size of elements without changing the dialog size may position some controls outside the dialog area at the left or bottom borders (the elements will be cropped at the dialog borders by the native system).

    Map also updates the dialog layout even if the control is already mapped, so using it or using Show, ShowXY or Popup (they all call Map) will also update the dialog layout.

    See Also: SIZE, Map, RefreshChildren.

RefreshChildren()

    Updates the size and layout of controls after changing size attributes. Can be used for any element inside a dialog, only its children will be updated. It can change the layout of all the controls inside the given element because of the dynamic layout positioning.

    $element->RefreshChildren();

    Notes:

    The given element must be a container. It must be inside a dialog hierarchy and must be mapped. It can not be a dialog. For dialogs use Refresh.

    The children are immediately repositioned, if the dialog is visible then the change will be immediately reflected on the display.

    This function will NOT change the size of the given element, even if the natural size of its children would increase its natural size.

    If your dialog has too many controls and you want to hide or destroy some, then add some other in the same place, so you actually know that the dialog layout would not change, this is a much faster function than Refresh.

    See Also: Refresh.

Reparent()

    Moves an interface element from one position in the hierarchy tree to another.

    my $retval = $element->Reparent($new_parent, $ref_child);

    $element: Reference to the element to be moved.

    new_parent: Identifier of the new parent.

    ref_child: Identifier of the element to be used as reference, where the child will be inserted before it. Can be undef.

    Returns: IUP_NOERROR if successfully, IUP_ERROR if failed.

    Both $new_parent and $element must be mapped or unmapped at the same time.

    If $ref_child is undef, then it will append the $child to the $new_parent. If $ref_child is NOT undef then it will insert $element before $ref_child inside the $new_parent.

    Notes:

    This function is faster and easier than doing the sequence unmap, detach, append/insert and map.

    The elements are NOT immediately repositioned. Call Refresh for the container (or any other element in the dialog) to update the dialog layout.

    Motif does not support the re-parent function, but we simulate a re-parent doing a unmap/map sequence. But some attributes may be lost during the operation, mostly attributes that are id dependent.

    See Also: Append, Insert, Detach, Map, Unmap, Refresh

ResetAttribute()

    Removes an attribute from the hash table of the element, and its children if the attribute is inheritable. It is useful to reset the state of inheritable attributes in a tree of elements.

    $element->ResetAttribute($name);

    $name: name of the attribute.

    See Also: GetAttribute, SetAttribute.

SaveClassAttributes()

    Saves all registered attributes on the internal hash table.

    $element->SaveClassAttributes();

    Notes:

    When the element is mapped some attributes are stored only in the native system. If the element is unmaped those attributes are lost. So this function is useful when you want to unmap the element and keep its attributes.

    It will not save id dependent attributes, like those which has a complementary number. For example: items in a IUP::List, IUP::Tree or IUP::Matrix.

    See Also: GetClassAttributes, GetClassName, GetClassType, GetAllAttributes, CopyClassAttributes.

SetAttribute()

    Defines an attribute for an interface element. See also the Attributes Guide section.

    $element->SetAttribute($name, $value);
#or
$element->SetAttribute( $name1=>$value1, $name2=>$value2, $name3=>$value3 );
#or
my %attr_values = ( $name1=>$value1, $name2=>$value2, $name3=>$value3 );
$element->SetAttribute( %attr_values );

    $name: name of the attribute.

    $value: value of the attribute. If undef, the default value will be used.

SetAttributeId()

    $element->SetAttributeId($name, $id, $value);

    Equivalent (just little bit faster) to:

    $element->GetAttribute("$name$id", $value);

SetAttributeId2()

    $element->SetAttributeId2($name, $lin, $col, $value);

    Equivalent (just little bit faster) to:

    $element->GetAttribute("$name$lin$col", $value);

SetCallback()

    Associates a callback to an event.

    Callback handler prototype:

    sub cb_handler {
  #...
}

$element->SetCallback($cb_name, \&cb_handler);
#or
$element->SetCallback( $cb_name1=>\&cb_handler, $cb_name2=>\&cb_handler, $cb_name3=>\&cb_handler );
#or
my %callbacks = ( $cb_name1=>\&cb_handler, $cb_name2=>\&cb_handler, $cb_name3=>\&cb_handler );
$element->SetCallback( %callbacks );

    $cb_name: attribute name of the callback.

    $cb_handler: reference to perl function. If undef removes the association.

SetFocus()

    Defines the interface element that will receive the keyboard focus, i.e., the element that will receive keyboard events. But this will be processed only after the con

    my $focused_elem = $element->SetFocus();

    $element: identifier of the interface element that will receive the keyboard focus. Only elements that can have the keyboard focus, are mapped, active and visible can be used, other elements are ignored.

    Returns: reference to iup element that previously had the keyboard focus.

    Notes:

    The value returned by GetFocus will be updated only after the main loop regain the control and the control actually receive the focus. So if you call GetFocus right after SetFocus the return value will be different. You could call Flush between the two functions to obtain the same value.

    See Also: GetFocus.

SetName()

    Associates a name with an interface element. This name can be later used for element lookup via global function GetByName.

    $element->SetName($name);

    $name: name of the interface element.

    Returns: reference to iup element previously associated to the parameter $name.

    Notes:

    Also SetName can be called several times with the same element and different names. There is no restriction for the number of names a element can have, but GetName will return the first name found.

    See Also: GetName (element method), GetByName (global function).

Unmap()

    Unmap the element from the native system. It will also unmap all its children.

    It will NOT detach the element from its parent, , and it will NOT destroy the IUP element.

    $element->Unmap();

    $ih: Identifier of an interface element.

    Notes:

    When the element is mapped some attributes are stored only in the native system. If the element is unmaped those attributes are lost. Use the function SaveClassAttributes when you want to unmap the element and keep its attributes.

    See Also: Append, Detach, Map, Create, Destroy.

Update()

UpdateChildren()

    Mark the element to be redraw when the control returns to the system.

    $element->Update;

UpdateChildren()

    Mark the element or its children to be redraw when the control returns to the system.

    $element->UpdateChildren;

Hide()

    Hides an interface element. This function has the same effect as attributing value "NO" to the interface element's VISIBLE attribute.

    $element->Hide();

    Returns: IUP_NOERROR always.

    Notes:

    Once a dialog is hidden, either by means of Hide method or by changing the VISIBLE attribute or by means of a click in the window close button, the elements inside this dialog are not destroyed, so that you can show them again. To destroy dialogs, the Destroy method must be called.

    See Also: ShowXY, Show, Popup, Destroy.

Popup()

    Shows a dialog or menu and restricts user interaction only to the specified element. It is equivalent of creating a Modal dialog is some tooklits.

    If another dialog is shown after Popup using Show, then its interaction will not be inhibited. Every Popup call creates a new popup level that inhibits all previous dialogs interactions, but does not disable new ones. IMPORTANT: The popup levels must be closed in the reverse order they were created or unpredictable results will occur.

    For a dialog this function will only return the control to the application after a callback returns IUP_CLOSE, ExitLoop is called, or when the popup dialog is hidden, for exemple using Hide. For a menu it returns automatically after a menu item is selected. IMPORTANT: If a menu item callback returns IUP_CLOSE, it will ends the current popup level dialog.

    $dialog->Popup($x, $y);
#or
$dialog->Popup();

    $ih: Identifier of a dialog or a menu.

    $x: horizontal position of the dialog or menu relative to the origin of the main screen. The following constants (see IUP::Constants) are valid:

    • IUP_LEFT: Positions the element on the left corner of the screen

    • IUP_CENTER: Centers the element on the screen

    • IUP_RIGHT: Positions the element on the right corner of the screen

    • IUP_MOUSEPOS: Positions the element on the mouse cursor

    • IUP_CENTERPARENT: Horizontally centralizes the dialog relative to its parent. Not valid for menus.

    • IUP_CURRENT: use the current position of the dialog. This is the default value if the parameter is not defined. Not valid for menus.

    $y: vertical position of the dialog or menu relative to the origin of the main screen. The following constants (see IUP::Constants) are valid:

    • IUP_TOP: Positions the element on the top of the screen

    • IUP_CENTER: Vertically centers the element on the screen

    • IUP_BOTTOM: Positions the element on the base of the screen

    • IUP_MOUSEPOS: Positions the element on the mouse cursor

    • IUP_CENTERPARENT: Vertically centralizes the dialog relative to its parent. Not valid for menus.

    • IUP_CURRENT: use the current position of the dialog. This is the default value if the parameter is not defined. Not valid for menus.

    Returns: IUP_NOERROR if sucessful. Returns IUP_INVALID if not a dialog or menu. If there was an error returns IUP_ERROR.

    Notes:

    Will call Map for the element.

    See the PLACEMENT attribute for other position and show options.

    When IUP_CENTERPARENT is used but PARENTDIALOG is not defined then it is replaced by IUP_CENTER.

    When IUP_CURRENT is used at the first time the dialog is shown then it will be replaced by IUP_CENTERPARENT.

    The main screen size does not include additional monitors.

    Popup works just like Show and ShowXY, but it inhibits interaction with other dialogs and interrupts the processing until IUP_CLOSE is returned in a callback or the dialog is hidden. Althougth it interrupts the processing, it does not destroy the dialog when it ends. To destroy the dialog, Destroy must be called.

    IMPORTANT: Calling Popup for an already visible dialog will only update its position and/or size on screen, will NOT change its modal state and will NOT interrupt processing.

    In GTK and Motif the inactive dialogs will still be able to move, resize and change their Z-order. Although their contents will be inactive, keyboard will be disabled, and they can not be closed from the close box.

    See Also: ShowXY, Show, Hide, Map.

Show()

    Displays a dialog in the current position, or changes a control VISIBLE attribute. If the dialog needs to be mapped and the current position is not known then the dialog is centered.

    For a dialog to set the attribute VISIBLE=YES is the same as calling Show. For other controls, to call IUP::Show is the same as setting VISIBLE=YES.

    $dialog->Show();

    Returns: IUP_NOERROR if sucessful. If there was an error returns IUP_ERROR.

    Notes:

    For dialogs it is equivalent to ShowXY using IUP_CURRENT (or IUP_CENTER if not mapped).

    Will call Map for the element.

    See the PLACEMENT attribute for other position and show options.

    This function can be executed more than once for the same dialog. This will make the dialog be placed above all other dialogs in the application, changing its Z-order, and update its position and/or size on screen.

    IMPORTANT: Calling Show for a visible dialog shown with Popup does nothing.

    See Also: ShowXY, Hide, Popup, Map.

ShowXY()

    Displays a dialog in a given position on the screen.

    $dialog->ShowXY($x, $y);
#or
$dialog->ShowXY();

    $ih: identifier of the dialog.

    $x: horizontal position of the dialog relative to the origin of the main screen. The following constants (see IUP::Constants) are valid:

    • IUP_LEFT: Positions the dialog on the left corner of the screen

    • IUP_CENTER: Horizontally centralizes the dialog on the screen

    • IUP_RIGHT: Positions the dialog on the right corner of the screen

    • IUP_MOUSEPOS: Positions the dialog on the mouse position

    • IUP_CENTERPARENT: Horizontally centralizes the dialog relative to its parent

    • IUP_CURRENT: use the current position of the dialog. This is the default value if the parameter is not defined.

    $y: vertical position of the dialog relative to the origin of the main screen. The following constants (see IUP::Constants) are valid:

    • IUP_TOP: Positions the dialog on the top of the screen

    • IUP_CENTER: Vertically centralizes the dialog on the screen

    • IUP_BOTTOM: Positions the dialog on the base of the screen

    • IUP_MOUSEPOS: Positions the dialog on the mouse position

    • IUP_CENTERPARENT: Vertically centralizes the dialog relative to its parent

    • IUP_CURRENT: use the current position of the dialog. This is the default value if the parameter is not defined.

    Returns: IUP_NOERROR if sucessful. Returns IUP_INVALID if not a dialog. If there was an error returns IUP_ERROR.

    Notes:

    Will call Map for the element.

    See the PLACEMENT attribute for other position and show options.

    When IUP_CENTERPARENT is used but PARENTDIALOG is not defined then it is replaced by IUP_CENTER.

    When IUP_CURRENT is used at the first time the dialog is shown then it will be replaced by IUP_CENTERPARENT.

    The main screen size does not include additional monitors.

    This function can be executed more than once for the same dialog. This will make the dialog be placed above all other dialogs in the application, changing its Z-order, and update its position and/or size on screen.

    IMPORTANT: Calling ShowXY for a visible dialog shown with Popup does nothing.

    See Also: Show, Hide, Popup, Map.