The Dialog Object

Synopsis

Description

A dialog shell for displaying and retrieving information. The default layout of the dialog is determined by the dialog types, which are shown in the figure below.

• The actual dialog appearance will vary slightly between Motif and Windows systems.
• Dialogs are not part of the main window, but instead are separate windows. Dialogs must be explicitly popped up and down using the functions GuiPopupDialog and GuiPopdownDialog.
• Any buttons that are created as children of a dialog, will appear in the dialog's button area.
• Dialogs are limited to one child object other than buttons. This object will appear in the dialog work area. To add multiple objects create a Bulletin as a child of the dialog and then add the objects to the bulletin.
• The only exception to the above is the bulletinBoard dialog type which is essentially a template dialog with a bulletin in its work area. The only draw back to this is that any buttons you add to it appear in the button area at the bottom not in the working area of the dialog. See the Bulletin object for more information.
• For dialogs with an input area you can use GuiGetString and GuiSetString to retrieve and set the selection.
• If you want to prompt the user for a single piece of information then it is a lot easier to use one of the following functions than program a new dialog: input_float, input_string, input_dataset, input_selection and input_file. Not only are these one-liners, but you avoid having to worry about callbacks. The only reason to use a selection dialog is if you wanted to add objects to its work area or if you needed it modal.

Depending on the dialog type, different components can be included in the dialog. The following table identifies these various components

• All objects: XuNdestroyable, XuNimmutable, XuNname and XuNuserData
• GUI objects: XuNguiCreateFunction, XuNguiDestroyFunction, XuNguiHeight, XuNguiPosition, XuNguiSensitive and XuNguiWidth.

New Resources

The following resources are used by all dialog types:

• XuNguiDialogType specifies the type of the dialog. The dialogType can be changed after the dialog has been created.
• A modeless dialog does block other window interaction. Application modal means the dialog must be popped down (OK or Cancel button) before the application can continue. System modal requires the dialog to be popped down before the user can interact with any other window.

• By default a dialog shell can be resized. Setting XuNguiAllowResize to false locks the size to the size set by the XuNguiWidth and XuNguiHeight resources.
• By default the Close button in the caption is not available. Setting XuNguiAllowDestroy to true enables the button in the caption.
• XuNguiTitle contains the text for the title bar of the dialog

• XuNguiCallback specifies the name of the function to call when any of the dialog's buttons are pressed or when [Return] is pressed in an input dialog. The function is also called when the dialog is resized or closed with the close button in the caption. The callback reason will be one of XuCR_OK, XuCR_APPLY, XuCR_CANCEL, XuCR_RESIZE or XuCR_KILL_DIALOG.
• If XuNguiCallbackData is specified then the value is passed to the callback function in the second argument.
• For more details - see Callback Functions

The following resource is used only by dialogs with an input (selection, fileSelection and prompt)

• This resource can be used to get or set the current selection. You can also use GuiGetString and GuiSetString.

The following resource is used only by dialogs with a label (error, information. warning, working, question message and prompt)

• The label which is displayed in the dialog label area.

The following resources are used only by the selection dialog:

• By default, any string can be entered in the dialog input area. If XuNguiMustMatch is set to true, then the input must match an item from the selection list.
  
  
• XuNguiListItems is a string array containing the items which make up the selection list. It must be a dataset or a fixed array of strings e.g. "'Higher'//'Lower'//'No change'"
• The list of strings is only updated when XuNguiListItems is changed. It is not enough to set it to a dataset and then modify the dataset. In fact once the XuNguiListItems has been set you can destroy the dataset without affecting the selection dialog.
• The list will not be updated if you set XuNguiListItems to the same dataset - it assumes the dataset has not changed. You must either use a different name for the dataset or set XuNguiListItems to undef and then back to the dataset.

The following resources are used only by the fileSelection dialog (but remember you are probably better off using input_file() ):

• The access mode of the selected file is stored in XuNguiFileAccess.
  
  
• XuNguiFileFilter is used to initialize the file filter. e.g. "*.dat", "*.*"

The following resource is used only by template dialogs:

• This resource can be used to control the border around the template dialog.

Callback Information

function DestroyDialogCB(string OBJ, string d, float r)
  OBJ = tokenize(OBJ, ".");
  OBJ  = OBJ[1]+"."+OBJ[2];
  destroy $OBJ;
endfunction

create Dialog gsharp_1.templatedialog
 ( XuNguiDialogType = "template",
   XuNguiWidth = 300,
   XuNguiHeight = 200
 );
create Bulletin gsharp_1.templatedialog.Bull;
create Label gsharp_1.templatedialog.Bull.label
 ( XuNguiLabel = "This is a template dialog",
   XuNguiPosition = (0,0)
 );
create Button gsharp_1.templatedialog.OK
 (    XuNguiCallback = "DestroyDialogCB"
 );
GuiPopupDialog("gsharp_1.templatedialog");

dialogtypes = "message"//"error"//"question"//"information"//
  "warning"//"working"//"prompt";
for type in dialogtypes
  PTR = "gsharp_1."+type+"dialog";
  create Dialog $PTR
   ( XuNguiDialogType = type,
     XuNguiWidth = 300,
     XuNguiHeight = 200,
     XuNguiPosition  = (rnd(1),rnd(1))*500,
     XuNguiTitle = "Demo Dialog",
     XuNguiLabel = "This is a "+type+" dialog",
     XuNguiCallback = "DestroyDialogCB"
   );
  create Button $(PTR).Test;
  GuiPopupDialog(PTR);
endfor

  create Dialog gsharp_1.selectiondialog
   ( XuNguiDialogType = "selection",
     XuNguiWidth = 300,
     XuNguiHeight = 200,
     XuNguiPosition  = (rnd(1),rnd(1))*500,
     XuNguiTitle = "Demo Dialog",
     XuNguiLabel = "This is a selection dialog",
     XuNguiCallback = "DestroyDialogCB",
     XuNguiListItems  = "dialogtypes",
     XuNguiMustMatch = true
   );
  GuiPopupDialog("gsharp_1.selectiondialog");

  create Dialog gsharp_1.fileselectiondialog
   ( XuNguiDialogType = "fileSelection",
     XuNguiPosition  = (rnd(1),rnd(1))*500,
     XuNguiCallback = "DestroyDialogCB",
     XuNguiTitle = "This is a fileSelection dialog",
     XuNguiMustMatch = true
   );
  GuiPopupDialog("gsharp_1.fileselectiondialog");