IupDialog

IUP - Portable User Interface

IupDialog

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.

Parameters/Return

Ihandle* IupDialog(Ihandle *element); [in C]
iupdialog{element: iuplua_tag} -> (elem: iuplua_tag) [in IupLua3]
iup.dialog{element: iuplua_tag} -> (elem: iuplua_tag) [in IupLua5]
dialog(element) [in LED]

element: Identifier of an interface element.

This function returns the identifier of the created dialog, or NULL if an error occurs.

Attributes

CURSOR: Defines a cursor for the dialog.

ICON: Dialog’s icon.

MAXBOX: Requires a maximize button from the window manager. Creation-only attribute.

MENU: Associates a menu to the dialog.

MENUBOX: Requires a menu box from the window manager. Creation-only attribute.

MINBOX: Requires a minimize button from the window manager. Creation-only attribute.

RESIZE: Allows interactively changing the dialog’s size. Creation-only attribute.

SIZE: Dialog’s size. Differently from other interface elements, the following values can be defined for width and height:

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

Default: the smallest size that allows viewing the dialog.

The dialog’s size has precedence over the smallest size required by its children (either if it was specified in its creation or in run-time). Attributing a NULL value to SIZE or RASTERSIZE (in C) in a dialog will recompute its size according to its children.

TITLE: Dialog’s title. On Motif, if it is not defined, the dialog will not be properly displayed.

STARTFOCUS: Name of the dialog element that must receive the focus right after the dialog is opened.

DEFAULTENTERName of the button activated when Enter is hit.

DEFAULTESC: Name of the button activated when Esc is hit.

X: Dialog’s horizontal position on the screen, in pixels.

Y: Dialog’s vertical position on the screen, in pixels.

SHRINK: Allows changing the elements’ distribution when the dialog is smaller than the minimum size.

PARENTDIALOG: Makes the dialog be treated as a child of the specified dialog.

FULLSCREEN

Makes the dialog occupy the whole screen. All dialog details, such as border, maximize button, etc, are removed. Possible values: YES, NO. Must be set before mapping to the native system. In Motif you may have to click in the dialog to set its focus. Use IupPopup for better results.

WIN_SAVEBITS (Windows Only)

This attribute is only consulted when the dialog is mapped. When this attribute is true (YES), the dialog stores the original image of the desktop region it occupies (if Windows 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.

TOPMOST (Windows Only)

This attribute puts the dialog always in front of all other dialogs in all applications. Default: NO.

TOOLBOX (Windows Only)

This attribute makes the dialog look like a toolbar. It is only valid if the PARENTDIALOG attribute is also defined. Default: NO.

CLIPCHILDREN (Windows Only)

Modifies the way the dialog and its children are redrawn.

When option YES is selected, the area occupied by the children in the dialog is not redrawn, thus preventing the matrix and the canvas from blinking when a resize is made. Usually this brings better performance, but in some cases it may bring a performance reduction, as every time the dialog needs to be redrawn all children are redrawn as well – including IupFrame. For the attribute to work efficiently, the canvas cannot be inside a IupFrame. Default: NO.

BRINGFRONT (Windows Only)

This attribute makes the dialog the foreground window. Use "YES" to activate it. Useful for multithreaded applications.

NATIVEPARENT (Windows Only)

Makes any window created in the system (even from outside IUP) able to be parent of a IUP dialog. The value provided should be a valid window handle (HWND.)

PLACEMENT (Windows Only)

Changes how the dialog will be show. Values: "MAXIMIZED", "MINIMIZED" and "NORMAL". After IupShow the attribute is set to "NORMAL" if it was different. "NORMAL" is equivalent of not defining the attribute.

HELPBUTTON (Windows 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.

TRAY(Windows Only): When set to "YES", displays an icon on the system tray.

TRAYICON(Windows Only): System tray icon

TRAYTIP(Windows Only): Tray icon's tooltip text

HIDETASKBAR (Windows Only)

When set to "YES", hides the dialog from the task bar. Must be used with TRAYICON attribute.

Callbacks

SHOW_CB: Called right after the dialog is opened, minimized or restored from a minimization.

MAP_CB: Called right after the element is mapped.

CLOSE_CB: Called right before the dialog is closed.

TRAYCLICK_CB: Called right after the mouse button is pressed or released over the tray icon.

int function(Ihandle *n, int but, int pressed, int dclick); [in C]
elem:trayclick(but, pressed, dclick: number) -> (ret: number) [in IupLua3]
elem:trayclick_cb(but, pressed, dclick: number) -> (ret: number) [in IupLua5]

but: identifies the activated mouse button.
pressed: indicates the state of the button.
dclick: indicates a double click.

Returning CLOSE closes the dialog.

Notes

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 when its VISIBLE attribute and that of the dialog are "YES".

A menu that is not associated to a dialog can interact with the user by means of the IupPopup function.

Values attributed to the SIZE attribute 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 NULL (in C) to SIZE. In the case of partial dimensions, a specified dimension is always used, while a non-defined dimension uses the smallest necessary size for the elements in the corresponding direction.

In Motif the decorations MENUBOX, MINBOX, MAXBOX, RESIZE and BORDER will work only if the running Window Manager supports the Motif WM hints.

Examples