=pod =head1 NAME IUP::Manual::02_Elements - GUI elements guide, methods common for all IUP elements =head1 IUP MANUAL =over =item * L =item * IUP::Manual::02_Elements EEEEE BEE this document> =item * L =item * L =item * L =item * L =item * L =back =head1 INTRODUCTION B This document is intended as a reference list for common methods used by all IUP elements. For more information about using elemets see L in L. xxxTODO GUI vs. non-GUI Currently available interface elements can be categorized as follows: =over =item * B (effective user interaction): B. =item * B (ways to show the elements): B B. =item * B (definition of a common functionality for a group of elements): B. =item * B (related both to menu bars and to pop-up menus): B. =item * Additional (elements built outside the main library): B. =item * B (useful predefined dialogs): B. =back =head1 CREATING ELEMENTS xxxTODO new() and its params (ATTRIB=>'val', param=>'val') =head1 CONSTRUCTORS new new_no_ihandle new_from_ihandle =head1 ACCESSORS ihandle name =head1 COMMON METHODS =head2 Element constructors =head3 new() xxxtodo =head3 new_from_ihandle() xxxtodo =head3 new_no_ihandle() xxxtodo =head2 Methods available in all IUP elements =head3 Append() =over Inserts an interface element at the end of the container, B 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); B<$ih:> Identifier of a container like hbox, vbox, zbox and menu. B<$new_child>: Identifier of the element to be inserted. B the actual B if the interface element was successfully inserted. Otherwise returns C. 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. B 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 L, for the appended child. If the actual parent is a layout box (L, L or L) 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 L for the container (or any other element in the dialog) to update the dialog layout. B L, L, L, L, L, L, L, L, L. =back =head3 ConvertXYToPos() =over Converts a (x,y) coordinate in an item position. my $position = $element->ConvertXYToPos($x, $y); B<$ih:> Identifier of the element. B<$x:> X coordinate of the left corner of the interface element. B<$y:> Y coordinate of the upper part of the interface element. B the position starting at 0 (except for L that starts at 1). If fails returns -1. B It can be used for L (returns a position in the string), L (returns an item) or L (returns a node identifier). B L, L, L. =back =head3 Destroy() =over Destroys an interface element and all its children. Only dialogs, timers, popup menus and images should be normally destroyed, but B controls can also be destroyed. $element->Destroy(); B<$ih:> Identifier of the interface element to be destroyed. B It will automatically B and B the element if necessary, and then B 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. B bars associated with dialogs are automatically destroyed when the dialog is destroyed. B 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 L. B L, L, L, L, L. =back =head3 Detach() =over B an interface element from its parent. $element->Detach(); B<$child:> Identifier of the interface element to be detached. B It will automatically call L to B the element if necessary, and then B the element. If left B it is still necessary to call L to B the IUP element. The elements are NOT immediately repositioned. Call L 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 B those attributes are lost. Use the function L when you want to B the element and keep its attributes. B L, L, L, L, L, L. =back =head3 GetAllAttributes() =over 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); B<$ih:> identifier of the interface element. names: table receiving the names. Only the list of names need to be allocated. Each name will point to an internal string.xxxTODOxxx B<$max_n:> maximum number of names the table can receive. Can be omitted. xxxtodo reuse txt B the actual number of names loaded to the table. If $names is C or $max_n is 0 then returns the maximum number of names. B L, L. =back =head3 GetAttribute() =over Returns the name of an interface element attribute. See also the L section. my $val = $element->GetAttribute($name); #or my @values = $element->GetAttribute(@names); B<$ih:> Identifier of the interface element. If C will retrieve from the global environment. xxxcheckthis is it the same as getglobal? B<$name:> name of the attribute. B<$id:> used when the attribute has an additional id. B the attribute value or C if the attribute is not defined or does not exist. B See the L for more details. B L B L. =back =head3 GetAttributeId() =over xxxTODOxxx my $val = $element->GetAttributeId($name, $id); =back =head3 GetAttributeId2() =over xxxTODOxxx my $val = $element->GetAttributeId2($name, $lin, $col); =back =head3 GetAttributes() =over 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 L instead. my $attr = $element->GetAttributes(); #later on print "Title=", $attr->{TITLE}, "\n"; print "Color=", $attr->{FGCOLOR}, "\n"; B<$ih:> Identifier of the interface element. B a hash of C<< ATTRIBUTE => VALUE >> pairs for all attributes of given element. B L, L, L. =back =head3 GetBrother() =over Returns the brother of a control or C if there is none. my $brother_elem = $element->GetBrother(); B<$ih:> identifier of the interface element. B xxxtodo B L, L, L. =back =head3 GetChild() =over Returns the a child of the given control given its position. my $child_elem = $element->GetChild($position); B<$ih:> identifier of the interface element. B<$position:> position of the desire child. B This function will return the children of the control in the exact same order in which they were assigned. B L, L, L, L. =back =head3 GetChildCount() =over Returns the number of children of the given control. my $count = $element->GetChildCount(); B<$ih:> identifier of the interface element. B L, L, L, L, L. =back =head3 GetChildPos() =over Returns the position of a child of the given control. my $position = $elmenet->GetChildPos($child_element); B<$ih:> identifier of the interface element. B<$child_element:> xxxTODOxxx B position of the desire child or -1 if child not found. B This function will return the children of the control in the exact same order in which they were assigned. B L, L, L, L, L. =back =head3 GetClassName() =over Returns the name of the class of an interface element. my $name = $element->GetClassName(); B<$ih:> Identifier of the interface element. B 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" B L, L. =back =head3 GetClassType() =over Returns the name of the native type of an interface element. my $type = $element->GetClassType(); B<$ih:> Identifier of the interface element. B 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" B L, L. =back =head3 GetDialog() =over 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(); B<$ih:> Identifier of an interface element. B the handle of the dialog or C if not found. =back =head3 GetDialogChild() =over 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); B<$ih:> Identifier of an interface element that belongs to the hierarchy. B<$name:> name of the control to be found B xxxtodo C if not found. B 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). B L. =back =head3 GetName() =over Returns the name of an interface element, if the element has an associated name using L or by C<< name=>'ElemName' >> named parameter of L constructor or using LED. my $name = $element->GetName(); B<$ih:> Identifier of the interface element. B the name. B L (element method), L (global function), L (global function). =back =head3 GetNextChild() =over Returns the a child of the given control given its brother. my $child_elem = $element->GetNextChild($child); B<$ih:> identifier of the interface element. Can be C if child not C. xxxcheckthis B<$child:> Identifier of the child brother to be used as reference. To get the first child use C. B the handle of the child or C. B This function will return the children of the control in the exact same order in which they were assigned. If child in not C then it returns exactly the same result as L. B 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( 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; B L, L, L. =back =head3 GetParamParam() =over xxxcheckthisxxx To retrieve a parameter of IUP->GetParam dialog you must use the following function: my $element = $dialog->GetParamParam($param_index); =over =item * B<$dialog:> Reference to IUP::Dialog object. =item * B<$param_index:> Parameter to be retrieved. =back =back =head3 GetParamValue() =over xxx hack related to GetParamParam, nicer way for getting item values than calling GetParamParam() xxx GetParamValue is also a setter - $self->GetParamValue($index, $value) =back =head3 GetParent() =over Returns the parent of a control. my $parent_elem = $element->GetParent(); B<$ih:> identifier of the interface element. B the handle of the parent or C if does not have a parent. B L, L, L. =back =head3 HasValidClassName() =over xxxspecial perl specific hack xxxmaybe make it an internal method =back =head3 Insert() =over Inserts an interface element B 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); B<$ih:> Identifier of a container like hbox, vbox, zbox and menu. B<$ref_child:> Identifier of the element to be used as reference. Can be C to insert as the first element. B<$new_child:> Identifier of the element to be inserted before the reference. B the actual B if the interface element was successfully inserted. Otherwise returns C. 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. B This function can be used when elements that will compose a container are not known I 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 L for the appended child. If the actual parent is a layout box (L, L or L) 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 L for the container* to update the dialog layout (* or any other element in the dialog). B L, L, L, L, L, L, L, L, L. =back =head3 IsValidCallbackName() =over xxxhack - perl specific =back =head3 Map() =over Creates (B) 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 B to a container if not a dialog. my $retval = $element->Map(); B<$ih:> Identifier of an interface element. B IUP_NOERROR if successful. If the element was already mapped returns IUP_NOERROR. If the native creation failed returns IUP_ERROR. B 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 L for an already mapped dialog is the same as only calling L for the dialog. If you add new elements to an already mapped dialog you must call L for that elements. And then call L to update the dialog layout. If the WID attribute is C, 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 L, L or L. It is usefull for the application to call L 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. B L, L, L, L, L, L, L, L, L. =back =head3 NextField() =over 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(); B<$ih:> identifier of the interface element. B the element that received the focus or C if not found. B L. =back =head3 PreviousField() =over 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(); B<$ih:> identifier of the interface element. B the element that received the focus or C if not found. B L. =back =head3 Redraw() =over Force the element and its children to be redraw immediately. $element->Redraw($children); B<$ih:> identifier of the interface element. B<$children:> flag to update its children. xxxcheckthis vales 0 or 1 =back =head3 Refresh() =over 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(); B<$ih:> identifier of the interface element. B 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 B size, if the new size is C the dialog will be resized to the B 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). L also updates the dialog layout even if the control is already mapped, so using it or using L, L or L (they all call L) will also update the dialog layout. B L, L, L. =back =head3 RefreshChildren() =over 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(); B<$ih:> identifier of the interface element. B 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 L. 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 L. B L. =back =head3 Reparent() =over Moves an interface element from one position in the hierarchy tree to another. my $retval = $element->Reparent($new_parent, $ref_child); B<$element:> Reference to the element to be moved. B Identifier of the new parent. B Identifier of the element to be used as reference, where the child will be inserted before it. Can be C. B IUP_NOERROR if successfully, IUP_ERROR if failed. Both B<$new_parent> and B<$element> must be mapped or unmapped at the same time. If B<$ref_child> is C, then it will B the B<$child> to the B<$new_parent>. If B<$ref_child> is NOT C then it will B B<$element> before B<$ref_child> inside the B<$new_parent>. B This function is faster and easier than doing the sequence B, B, B and B. The elements are NOT immediately repositioned. Call L 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 B/B sequence. But some attributes may be lost during the operation, mostly attributes that are id dependent. B L, L, L, L, L, L =back =head3 ResetAttribute() =over 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); B<$ih:> Identifier of the interface element. If C will set in the global environment. xxxcheckthis B<$name:> name of the attribute. B L, L. =back =head3 SaveClassAttributes() =over Saves all registered attributes on the internal hash table. $element->SaveClassAttributes(); B<$ih:> identifier of the interface element. B When the element is mapped some attributes are stored only in the native system. If the element is B those attributes are lost. So this function is useful when you want to B 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 L, L or L. B L, L, L, L, L. =back =head3 SetAttribute() =over Defines an attribute for an interface element. See also the L 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 ); B<$ih:> Identifier of the interface element. If C will set in the global environment. xxxcheckthis B<$name:> name of the attribute. B<$id:> used when the attribute has an additional id. B<$value:> value of the attribute. If C, the default value will be used. B See the L for more details. xxxcheckthisxxx The value stored in the attribute is not duplicated. Therefore, you can store your private attributes, such as a structure with data to be used in a callback. When you want IUP to store an attribute by duplicating a string passed as a value, use function L. struct myData* mydata = malloc(sizeof(struct myData));IUP::SetAttribute(dlg, "MYDATA", (char*)mydata) // correct (unknown attributes will be stored as pointers) B L, L. =back =head3 SetAttributeId() =over xxxTODO $element->SetAttributeId($name, $id, $value); =back =head3 SetAttributeId2() =over xxxTODO $element->SetAttributeId2($name, $lin, $col, $value); =back =head3 SetCallback() =over Associates a callback to an event. B 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 ); B<$ih:> identifier of the interface element. B<$cb_name:> attribute name of the callback. xxxsee B<$cb_handler:> xxxTODO func refxxx. If C removes the association. B the address of the previous function associated to the action xxxTODO ???. B L. =back =head3 SetFocus() =over 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(); B<$ih:> 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. B the identifier of the interface element that previously had the keyboard focus. B The value returned by L will be updated only after the main loop regain the control and the control actually receive the focus. So if you call L right after L the return value will be different. You could call L between the two functions to obtain the same value. B L. =back =head3 SetName() =over Associates a name with an interface element. This name can be later used for element lookup via global function L. $element->SetName($name); B<$ih:> identifier of the interface element. Use NULL to remove the association. xxxcheckthis B<$name:> name of the interface element. B the identifier of the interface element previously associated to the parameter B<$name>. B Also L 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 L will return the first name found. B L (element method), L (global function). =back =head3 Unmap() =over B the element from the native system. It will also unmap all its children. It will NOT B the element from its parent, , and it will NOT B the IUP element. $element->Unmap(); B<$ih:> Identifier of an interface element. B When the element is mapped some attributes are stored only in the native system. If the element is B those attributes are lost. Use the function L when you want to B the element and keep its attributes. B L, L, L, L, L. =back =head3 Update() =head3 UpdateChildren() =over Mark the element to be redraw when the control returns to the system. $element->Update; B<$element:> identifier of the interface element. =back =head3 UpdateChildren() =over Mark the element or its children to be redraw when the control returns to the system. $element->UpdateChildren; B<$element:> identifier of the interface element. =back =head1 Methods common for all Dialog-like elements xxx IUP::Dialog, IUP::ColorDlg etc =head3 Hide() =over Hides an interface element. This function has the same effect as attributing value "NO" to the interface element's VISIBLE attribute. $element->Hide(); #xxxcheckthis ?is it dialog only? - $dialog->Hide(); B<$ih:> Identifier of the interface element. B IUP_NOERROR always. B Once a dialog is hidden, either by means of L 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 L method must be called. B L, L, L, L. =back =head3 Popup() =over 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 L using L, then its interaction will not be inhibited. Every L 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, L is called, or when the popup dialog is hidden, for exemple using L. 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(); B<$ih:> Identifier of a dialog or a menu. B<$x>: horizontal position of the dialog or menu relative to the origin of the main screen. The following constants (see L) are valid: =over =item * IUP_LEFT: Positions the element on the left corner of the screen =item * IUP_CENTER: Centers the element on the screen =item * IUP_RIGHT: Positions the element on the right corner of the screen =item * IUP_MOUSEPOS: Positions the element on the mouse cursor =item * IUP_CENTERPARENT: Horizontally centralizes the dialog relative to its parent. Not valid for menus. =item * IUP_CURRENT: use the current position of the dialog. This is the B if the parameter is not defined. Not valid for menus. =back B<$y:> vertical position of the dialog or menu relative to the origin of the main screen. The following constants (see L) are valid: =over =item * IUP_TOP: Positions the element on the top of the screen =item * IUP_CENTER: Vertically centers the element on the screen =item * IUP_BOTTOM: Positions the element on the base of the screen =item * IUP_MOUSEPOS: Positions the element on the mouse cursor =item * IUP_CENTERPARENT: Vertically centralizes the dialog relative to its parent. Not valid for menus. =item * IUP_CURRENT: use the current position of the dialog. This is the B if the parameter is not defined. Not valid for menus. =back B IUP_NOERROR if sucessful. Returns IUP_INVALID if not a dialog or menu. If there was an error returns IUP_ERROR. B Will call L for the element. See the L 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. L works just like L and L, 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, L must be called. IMPORTANT: Calling L 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. B L, L, L, L. =back =head3 Show() =over 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 L. For other controls, to call IUP::Show is the same as setting VISIBLE=YES. $dialog->Show(); B<$ih:> identifier of the interface element. B IUP_NOERROR if sucessful. If there was an error returns IUP_ERROR. B For dialogs it is equivalent to L using IUP_CURRENT (or IUP_CENTER if not mapped). Will call L for the element. See the L 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 L for a visible dialog shown with L does nothing. B L, L, L, L. =back =head3 ShowXY() =over Displays a dialog in a given position on the screen. $dialog->ShowXY($x, $y); #or $dialog->ShowXY(); B<$ih:> identifier of the dialog. B<$x:> horizontal position of the dialog relative to the origin of the main screen. The following constants (see L) are valid: =over =item * IUP_LEFT: Positions the dialog on the left corner of the screen =item * IUP_CENTER: Horizontally centralizes the dialog on the screen =item * IUP_RIGHT: Positions the dialog on the right corner of the screen =item * IUP_MOUSEPOS: Positions the dialog on the mouse position =item * IUP_CENTERPARENT: Horizontally centralizes the dialog relative to its parent =item * IUP_CURRENT: use the current position of the dialog. This is the B if the parameter is not defined. =back B<$y:> vertical position of the dialog relative to the origin of the main screen. The following constants (see L) are valid: =over =item * IUP_TOP: Positions the dialog on the top of the screen =item * IUP_CENTER: Vertically centralizes the dialog on the screen =item * IUP_BOTTOM: Positions the dialog on the base of the screen =item * IUP_MOUSEPOS: Positions the dialog on the mouse position =item * IUP_CENTERPARENT: Vertically centralizes the dialog relative to its parent =item * IUP_CURRENT: use the current position of the dialog. This is the B if the parameter is not defined. =back B IUP_NOERROR if sucessful. Returns IUP_INVALID if not a dialog. If there was an error returns IUP_ERROR. B Will call L for the element. See the L 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 L for a visible dialog shown with L does nothing. B L, L, L, L. =back =head1 Methods common for all elements L, L, L, L, L, L, L, L