IupDialog

IUP - Portable User Interface

previous page next page

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.

Creation

Ihandle* IupDialog(Ihandle *child); [in C]
iup.dialog{child: ihandle} -> (elem: ihandle) [in Lua]
dialog(child) [in LED]

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

Returns: the identifier of the created element, or NULL if an error occurs.

Attributes

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. (since 3.0)

BGCOLOR: Dialog background color.

BORDER (non inheritable) (creation only): Shows a resize border around the dialog. Default: "YES".

BORDER=NO is usefull 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.

CURSOR (non inheritable): Defines a cursor for the dialog.

SIZE (non inheritable): Dialog’s size.

Additionally the following values can also be defined for width and/or 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)

If SIZE or RASTERSIZE are set changing the user size, then the current size is internally reset to 0x0, so the user size or the natural size can be used when updating the actual current size of the dialog.

TITLE (non inheritable): Dialog’s title.

VISIBLE: Simply call IupShow or IupHide for the dialog.

ACTIVE, FONT, EXPAND, X, Y, WID, TIP, CLIENTSIZE, RASTERSIZE, ZORDER: also accepted. Note that ACTIVE, BGCOLOR, EXPAND and FONT will also affect all the controls inside the dialog.

Exclusive

DEFAULTENTER:  Name of the button activated when Enter is hit.

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

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: Dialog’s icon.

FULLSCREEN: Makes the dialog occupy the whole screen.

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.

MAXBOX (creation only): Requires a maximize button from the window manager. If RESIZE=NO then MAXBOX will be set to NO. Default: YES. See comments about Motif in Notes bellow. 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. (since 3.0)

MENU: Associates a menu to the dialog.

MENUBOX (creation only): Requires a menu box from the window manager. If hidden will also remove the Close button. Default: YES. See comments about Motif in Notes bellow. In Windows if hidden will hide also MAXBOX and MINBOX.

MINBOX (creation only): Requires a minimize button from the window manager. Default: YES. See comments about Motif in Notes bellow. 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. (since 3.0)

MODAL (read-only): Returns the popup state. It is "YES" if the dialog was shown using IupPopup. It is "NO" if IupShow was used or it is not visible. (since 3.0)

PARENTDIALOG (creation only): Name of a dialog to be used as parent. This dialog will be always in front of the parent dialog. The parent dialog must be mapped before mapping the child dialog. If PARENTDIALOG is not defined then the NATIVEPARENT attribute is consulted. This one must be a native handle of an existing dialog.

IMPORTANT: When the parent is destroyed the child dialog is also destroyed, then the CLOSE_CB callback of the child dialog is NOT called. The application must take care of destroying the children dialogs before destroying the parent. This is usually done when CLOSE_CB of the parent dialog is called.

PLACEMENT (IupShow only):

Changes how the dialog will be shown. Values: "FULL", "MAXIMIZED", "MINIMIZED" and "NORMAL". Default: NORMAL. After IupShow 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. Not used in IupPopup. 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 dialog’s size. Default: YES. See comments about Motif in Notes bellow.

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 (in fact all the controls in GTK are double buffered to speed up redraw).

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 IupShow or IupPopup. If not defined then the first control than can receive the focus is selected (same effect of calling IupNextField for the dialog).

Exclusive [Windows and GTK Only]

DRAGDROP [Windows and GTK Only]: 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.

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.

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

TRAYIMAGE [Windows and GTK Only]: Name of a IUP image to be used as the tray icon.

TRAYTIP [Windows and GTK Only] :Tray icon's tooltip text.

Exclusive [Windows Only]

BRINGFRONT [Windows Only] (write-only):

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

CLIPCHILDREN [Windows Only] (creation only):

When option YES is selected, the area occupied by the children in the dialog is not redrawn, thus preventing the children 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. Default: YES.

COMPOSITED [Windows XP Only] (creation only):

This attribute controls if the window will have an automatic double buffer for all controls. Default is "NO".

CONTROL [Windows Only]: Embeds the dialog inside another window. Creation-only attribute.

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.

LAYERED [Windows Only]:

This attribute sets and removes the layered style bit. Use "YES" to activate it. Default is "NO". The LAYERALPHA attribute must also be set, just after this one.

LAYERALPHA [Windows Only]:

This attribute sets the dialog transparency alpha value. The dialog must have LAYERED=YES. Valid values range from 0 (completely transparent) to 255 (opaque).

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

TOPMOST [Windows Only]: This attribute puts the dialog always in front of all other dialogs in all applications. Default: NO.

Exclusive MDI [Windows Only]

MDIACTIVE [Windows Only] (read-only): Returns the the name of the current active MDI child.

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

MDICHILD [Windows Only]: Configure this dialog to be a MDI child window. The MDICLIENT attribute must also be set. Each MDI child is automatically named (IupSetHandle) to "mdichild%d", where "%d" is a sequencial number.

MDICLIENT [Windows Only]: Name of the IupCanvas used as MDI client window. The MDI frame window must have one and only one MDI client window.

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.

MDIMENU [Windows Only]: Name of a IupSubmenu to be used as the Window list of a MDI frame window. The system will automatically add the list of MDI child windows there. Used in the IupDialog configured as a MDI frame. This dialog must contains one IupCanvas configured with MDICLIENT=YES.

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

Callbacks

CLOSE_CB: Called right before the dialog is closed.

DROPFILES_CB [Windows and GTK Only]: Action generated when one or more files are dropped from the Windows Explorer or from Nautilus 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.

int function(Ihandle *ih); [in C]
elem:mdiactivate_cb() -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.

RESIZE_CB: Action generated when the dialog size is changed. (since 3.0)

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

TRAYCLICK_CB [Windows and GTK Only]: Called right after the mouse button is pressed or released over the tray icon.

int function(Ihandle *ih, int but, int pressed, int dclick); [in C]
elem:trayclick_cb(but, pressed, dclick: number) -> (ret: number) [in Lua]

ih: identifier of the element 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 mesages.
pressed: indicates the state of the button. Always 1 in GTK.
dclick: indicates a double click. In GTK double click is simulated.

Return: IUP_CLOSE will be processed.

MAP_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB: All common callbacks are supported.

Notes

Do not associate an IupDialog with the native "dialog" nomenclature in Windows, GTK or Motif. IupDialog 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.

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. See the SIZE attribute for further details.

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

In Motif the decorations ICON, MENUBOX, MINBOX, MAXBOX, RESIZE and BORDER are controled by the Window Manager and may not be possible to be changed from IUP.

Windows MDI

The MDI support is composed of 3 components: the MDI frame window (IupDialog), the MDI client window (IupCanvas) and the MDI children (IupDialog). Altough the MDI client is a IupCanvas 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

Very simple dialog with a label and a button. The application is closed when the button is pressed.

#include <iup.h>

int quit_cb(void)
{
  return IUP_CLOSE;
}

int main(int argc, char* argv[])
{
  Ihandle *dialog, *quit_bt, *vbox;

  IupOpen(&argc, &argv);

  /* Creating the button */ 
  quit_bt = IupButton("Quit", 0);
  IupSetCallback(quit_bt, "ACTION", (Icallback)quit_cb);

  /* the container with a label and the button */
  vbox = IupVbox(
           IupSetAttributes(IupLabel("Very Long Text Label"), "EXPAND=YES, ALIGNMENT=ACENTER"), 
           quit_bt, 
           0);
  IupSetAttribute(vbox, "MARGIN", "10x10");
  IupSetAttribute(vbox, "GAP", "5");

  /* Creating the dialog */ 
  dialog = IupDialog(vbox);
  IupSetAttribute(dialog, "TITLE", "Dialog Title");
  IupSetAttributeHandle(dialog, "DEFAULTESC", quit_bt);

  IupShow(dialog);

  IupMainLoop();
  
  IupDestroy(dialog);
  IupClose();

  return 0;
}

Other: Browse Example Files

See Also

IupFileDlg, IupMessageDlg, IupDestroy, IupShowXY, IupShow, IupPopup

previous page start next page