View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
kmx > IUP-0.101 > IUP::Dialog



Annotate this POD


New  2
Open  1
View/Report Bugs
Source   Latest Release: IUP-0.305


IUP::Dialog - [GUI element] the main GUI element; the main application window


Creates a dialog element. It manages user interaction with the interface elements. For any interface element to be shown, it must be encapsulated in a dialog.


CREATION - new() method

 $dialog = IUP::Dialog->new( TITLE=>"Windows title", $child=>$frame_element );

$child: Identifier of an interface element. The dialog has only one child.

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.


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



(non inheritable)

Dialog background color or image. Can be a non inheritable alternative to BGCOLOR or can be the name of an image to be tiled on the background. See also the screenshots:


(non inheritable) (creation only)

Shows a resize border around the dialog. Default: "YES". BORDER=NO is useful only when RESIZE=NO, MAXBOX=NO, MINBOX=NO, MENUBOX=NO and TITLE=NULL, if any of these are defined there will be always some border.


(non inheritable)

Defines a cursor for the dialog.


[Windows and GTK Only] (non inheritable)

Enable or disable the drag&drop of files. Default: NO, but if DROPFILES_CB is defined when the element is mapped then it will be automatically enabled.


(non inheritable)

The default value is "YES".


(non inheritable)

Dialogs size. Additionally the following values can also be defined for width and/or height:

"FULL": Defines the dialogs width (or height) equal to the screen's width (or height)
"HALF": Defines the dialogs width (or height) equal to half the screen's width (or height)
"THIRD": Defines the dialogs width (or height) equal to 1/3 the screen's width (or height)
"QUARTER": Defines the dialogs width (or height) equal to 1/4 of the screen's width (or height)
"EIGHTH": Defines the dialogs width (or height) equal to 1/8 of the screen's width (or height)

The dialog Natural size is only considered when the User size is not defined or when it is bigger than the Current size. This behavior is different from a control that goes inside the dialog. Because of that, when SIZE or RASTERSIZE are set (changing the User size), the Current size is internally reset to 0x0, so the the =item Natural size can be considered when re-computing the Current size of the dialog.

Values set at SIZE or RASTERSIZE attributes of a dialog are always accepted, regardless of the minimum size required by its children. For a dialog to have the minimum necessary size to fit all elements contained in it, simply define SIZE or RASTERSIZE to NULL. Also if you set SIZE or RASTERSIZE to be used as the initial size of the dialog, its contents will be limited to this size as the minimum size, if you do not want that, then after showing the dialog reset this size to NULL so the dialog can be resized to smaller values. But notice that its contents will still be limited by the Natural size, to also remove that limitation set SHRINK=YES.

For more information see IUP::Manual::05_DialogLayout.


(non inheritable)

Dialogs title. Default: NULL. If you want to remove the title bar you must also set MENUBOX=NO, MAXBOX=NO and MINBOX=NO, before map. But in Motif and GTK it will hide it only if RESIZE=NO also.


Simply call Show or Hide for the dialog.

The following common attributes are also accepted:


Exclusive [Windows and GTK Only]

Exclusive [GTK Only]

Exclusive [Windows Only]

Exclusive MDI [Windows Only]


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


Called right before the dialog is closed.


[Windows Only]

Called at the first instance, when a second instance is running. Must set the global attribute SINGLEINSTANCE to be called. (since iup-3.2)

Callback handler prototype:

 sub copydata_cb_handler {
   my ($self, $cmdLine, $size) = @_;

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

$cmdLine: command line of the second instance.

$size: size of the command line string including the null character.


[Windows and GTK Only]

Action generated when one or more files are dropped in the dialog.


[Windows Only]

Called when a MDI child window is activated. Only the MDI child receive this message. It is not called when the child is shown for the first time.

Callback handler prototype:

 sub mdiactivate_cb_handler {
   my ($self) = @_;

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


[Windows and GTK Only]

Called after the dialog was moved on screen. The coordinates are the same as the SCREENPOSITION attribute. (since iup-3.0)

Callback handler prototype:

 sub mdiactivate_cb_handler {
   my ($self, $x, $y) = @_;

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

$x, y: coordinates of the new position.


Action generated when the dialog size is changed. If returns IUP_IGNORE the dialog layout is NOT recalculated.


Called right after the dialog is showed, hidden, maximized, minimized or restored from minimized/maximized.


[Windows and GTK Only]

Called right after the mouse button is pressed or released over the tray icon. (GTK 2.10)

Callback handler prototype:

 sub trayclick_cb_handler {
   my ($self, $but, $pressed, $dclick) = @_;

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

$but: identifies the activated mouse button. Can be: 1, 2 or 3. Note that this is different from the BUTTON_CB canvas callback definition. GTK does not get button=2 messages.

$pressed: indicates the state of the button. Always 1 in GTK.

$dclick: indicates a double click. In GTK double click is simulated.

Returns: IUP_CLOSE will be processed.

The following common callbacks are also accepted:


Do not associate an IUP::Dialog with the native "dialog" nomenclature in Windows, GTK or Motif. IUP::Dialog use native standard windows in all drivers.

Except for the menu, all other elements must be inside a dialog to interact with the user. Therefore, an interface element will only be visible if its dialog is also visible.

The order of callback calling is system dependent. For instance, the RESIZE_CB and the SHOW_CB are called in a different order in Win32 and in X-Windows when the dialog is shown for the first time.

Windows MDI

The MDI support is composed of 3 components: the MDI frame window (IUP::Dialog), the MDI client window (IUP::Canvas) and the MDI children (IUP::Dialog). Although the MDI client is a IUP::Canvas it is not used directly by the application, but it must be created and included in the dialog that will be the MDI frame, other controls can also be available in the same dialog, like buttons and other canvases composing toolbars and status area. The following picture illustrates the e components:


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


IUP::FileDlg, IUP::MessageDlg, Destroy, ShowXY, Show,, Popup

The original doc: iupdialog.html

syntax highlighting: