/ 
IUP-0.302
River stage zero No dependents
/ IUP::Dialog

NAME

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

DESCRIPTION

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.

USAGE

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.

ATTRIBUTES

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

Common

BACKGROUND

(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:

normal background setting dialog BACKGROUND setting dialog BGCOLOR setting children BGCOLOR
Motif
GTK
Windows
Classic
Windows
w/ Styles
Windows
Vista

BORDER

(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=undef, if any of these are defined there will be always some border.

CURSOR

(non inheritable)

Defines a cursor for the dialog.

DRAGDROP

[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.

EXPAND

(non inheritable)

The default value is "YES".

SIZE

(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 undef. 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 undef 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.

TITLE

(non inheritable)

Dialogs title. Default: undef. 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.

VISIBLE

Simply call Show or Hide for the dialog.

The following common attributes are also accepted:

Exclusive

DEFAULTENTER

Name of the button activated when the user press Enter when focus is in another control of the dialog.

To associate a name to element use SetName or name=>'ElemName' named parameter of new() constructor.

DEFAULTESC

Name of the button activated when the user press Esc when focus is in another control of the dialog.

To associate a name to element use SetName or name=>'ElemName' named parameter of new() constructor.

DIALOGFRAME

Set the common decorations for modal dialogs. This means RESIZE=NO, MINBOX=NO and MAXBOX=NO. In Windows, if the PARENTDIALOG is defined then the MENUBOX is also removed, but the Close button remains.

ICON

Dialogs icon.

FULLSCREEN

Makes the dialog occupy the whole screen over any system bars in the main monitor. All dialog details, such as title bar, borders, maximize button, etc, are removed.

Possible values "YES", "NO". In Motif you may have to click in the dialog to set its focus.

In Motif if set to YES when the dialog is hidden, then it can not be changed after it is visible.

HWND

[Windows Only] (non inheritable, read-only) Returns the Windows Window handle. Available in the Windows driver or in the GTK driver in Windows.

MAXBOX

(creation only) Requires a maximize button from the window manager. If RESIZE=NO then MAXBOX will be set to NO. Default: YES. In Motif the decorations are controlled by the Window Manager and may not be possible to be changed from IUP. In Windows MAXBOX is hidden only if MINBOX is hidden as well, or else it will be just disabled.

MAXSIZE

Maximum size for the dialog in raster units (pixels). The windowing system will not be able to change the size beyond this limit. Default: 65535x65535.

Name of a menu or IUP::Menu reference. Associates a menu to the dialog as a menu bar. The previous menu, if any, is unmapped.

(creation only) Requires a system menu box from the window manager. If hidden will also remove the Close button. Default: YES. In Motif the decorations are controlled by the Window Manager and may not be possible to be changed from IUP. In Windows if hidden will hide also MAXBOX and MINBOX.

MINBOX

(creation only) Requires a minimize button from the window manager. Default: YES. In Motif the decorations are controlled by the Window Manager and may not be possible to be changed from IUP. In Windows MINBOX is hidden only if MAXBOX is hidden as well, or else it will be just disabled.

MINSIZE

Minimum size for the dialog in raster units (pixels). The windowing system will not be able to change the size beyond this limit. Default: 1x1. Some systems define a very minimum size greatter than this. Typically Windows has an horizontal minimum size that includes the window decoration buttons.

(read-only) Returns the popup state. It is "YES" if the dialog was shown using Popup. It is "NO" if Show was used or it is not visible.

NATIVEPARENT

(creation only) Native handle of a dialog to be used as parent. Used only if PARENTDIALOG is not defined.

PARENTDIALOG

(creation only) Name of a dialog to be used as parent.

PLACEMENT

Changes how the dialog will be shown. Values: "FULL", "MAXIMIZED", "MINIMIZED" and "NORMAL". Default: NORMAL. After Show/Popup the attribute is set back to "NORMAL". FULL is similar to FULLSCREEN but only the dialog client area covers the screen area, menu and decorations will be there but out of the screen. In UNIX there is a chance that the placement won't work correctly, that depends on the Window Manager.

RESIZE

(creation only) Allows interactively changing the dialogs size. Default: YES. If RESIZE=NO then MAXBOX will be set to NO. In Motif the decorations are controlled by the Window Manager and may not be possible to be changed from IUP.

SAVEUNDER

[Windows and Motif Only] (creation only) When this attribute is true (YES), the dialog stores the original image of the desktop region it occupies (if the system has enough memory to store the image). In this case, when the dialog is closed or moved, a redrawing event is not generated for the windows that were shadowed by it. Its default value is YES. To save memory disable it for your main dialog. Not available in GTK.

SHRINK

Allows changing the elements distribution when the dialog is smaller than the minimum size. Default: NO.

STARTFOCUS

Name of the element that must receive the focus right after the dialog is shown using Show or Popup. If not defined then the first control than can receive the focus is selected (same effect of calling NextField for the dialog). Updated after SHOW_CB is called and only if the focus was not changed during the callback.

XWINDOW

[UNIX Only] (non inheritable, read-only) Returns the X-Windows Window (Drawable). Available in the Motif driver or in the GTK driver in UNIX.

Exclusive [Windows and GTK Only]

ACTIVEWINDOW

[Windows and GTK Only] (read-only) informs if the dialog is the active window (the window with focus). Can be Yes or No. (since iup-3.4)

HIDETASKBAR

[Windows and GTK Only] (write-only) Action attribute that when set to "YES", hides the dialog, but does not decrement the visible dialog count, does not call SHOW_CB and does not mark the dialog as hidden inside IUP. It is usually used to hide the dialog and keep the tray icon working without closing the main loop. It has the same effect as setting LOCKLOOP=Yes and normally hiding the dialog. IMPORTANT: when you hide using HIDETASKBAR, you must show using HIDETASKBAR also. Possible values: YES, NO.

OPACITY

[Windows and GTK Only] sets the dialog transparency alpha value. Valid values range from 0 (completely transparent) to 255 (opaque). In Windows set to undef to remove the LAYERED style bit. (GTK 2.12)

TOPMOST

[Windows and GTK Only] puts the dialog always in front of all other dialogs in all applications. Default: NO.

TRAY

[Windows and GTK Only] When set to "YES", displays an icon on the system tray. (GTK 2.10)

TRAYIMAGE

[Windows and GTK Only] Name of a IUP image to be used as the tray icon. (GTK 2.10)

TRAYTIP

[Windows and GTK Only] Tray icon's tooltip text. (GTK 2.10)

Exclusive [GTK Only]

DIALOGHINT

(creation-only) if enabled sets the window type hint to a dialog hint.

Exclusive [Windows Only]

BRINGFRONT

[Windows Only] (write-only) makes the dialog the foreground window. Use "YES" to activate it. Useful for multithreaded applications.

COMPOSITED

[Windows Only] (creation only) controls if the window will have an automatic double buffer for all children. Default is "NO". In Windows Vista it is NOT working as expected.

CONTROL

[Windows Only] (creation only) Embeds the dialog inside another window.

HELPBUTTON

[Windows Only] (creation only) Inserts a help button in the same place of the maximize button. It can only be used for dialogs without the minimize and maximize buttons, and with the menu box. For the next interaction of the user with a control in the dialog, the callback HELP_CB will be called instead of the control defined ACTION callback. Possible values: YES, NO. Default: NO.

TOOLBOX

[Windows Only] (creation only) makes the dialog look like a toolbar. It is only valid if the PARENTDIALOG or NATIVEPARENT attribute is also defined. Default: NO.

Exclusive MDI [Windows Only]

MDIFRAME

(creation only, non inheritable) [Windows Only] Configure this dialog as a MDI frame. Can be YES or NO. Default: NO.

MDIACTIVE

[Windows Only] (read-only) Returns the name of the current active MDI child. Use IUP::GetAttributeHandle to directly retrieve the child handle.

MDIACTIVATE

[Windows Only] (write-only) Name of a MDI child window to be activated. If value is "NEXT" will activate the next window after the current active window. If value is "PREVIOUS" will activate the previous one.

MDIARRANGE

[Windows Only] (write-only) Action to arrange MDI child windows. Possible values: TILEHORIZONTAL, TILEVERTICAL, CASCADE and ICON (arrange the minimized icons).

MDICLOSEALL

[Windows Only] (write-only) Action to close and destroy all MDI child windows. The CLOSE_CB callback will be called for each child.

IMPORTANT: When a MDI child window is closed it is automatically destroyed. The application can override this returning IUP_IGNORE in CLOSE_CB.

MDINEXT

[Windows Only] (read-only) Returns the name of the next available MDI child. Use IUP::GetAttributeHandle to directly retrieve the child handle. Must use MDIACTIVE to retrieve the first child. If the application is going to destroy the child retrieve the next child before destroying the current.

MDICLIENT

[Windows Only] (non inheritable, creation only) Configure the canvas as a MDI client. Can be YES or NO. No callbacks will be called. This canvas will be used internally only by the MDI Frame and its MDI Children. The MDI frame must have one and only one MDI client. Default: NO.

MDIMENU

(creation only) [Windows Only] Name of a IUP::Menu to be used as the Window list of a MDI frame. The system will automatically add the list of MDI child windows there.

MDICHILD

(creation only) [Windows Only] Configure this dialog to be a MDI child. Can be YES or NO. The PARENTDIALOG attribute must also be defined. Each MDI child is automatically named if it does not have one. Default: NO.

CALLBACKS

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

CLOSE_CB

Called right before the dialog is closed.

COPYDATA_CB

[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.

DROPFILES_CB

[Windows and GTK Only]

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

MDIACTIVATE_CB

[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

MOVE_CB

[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.

RESIZE_CB

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

SHOW_CB

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

TRAYCLICK_CB

[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:

NOTES

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:

EXAMPLES

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

SEE ALSO

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

The original doc: iupdialog.html