DIALOG

version 11 (Modified)

DIALOG ({aTable; }form; *)

The DIALOG command presents the form form to the user. This command is often used to get information from the user through the use of variables, or to present information to the user, such as options for performing an operation.

It is common to display the form inside a modal window created with the Open window command.

Here is a typical example of a dialog:

Use DIALOG instead of ALERT, CONFIRM, or Request when the information that must be presented or gathered is more complex than those commands can manage.

Note: In converted databases, it is possible to prohibit data entry in fields of dialog boxes (and thus limit data entry to variables only) using an option in the Preferences of 4D (Compatibility page). This restriction corresponds to the operation of former versions of 4D.

Unlike ADD RECORD or MODIFY RECORD, DIALOG does not use the current input form. You must specify the form (project form or table form) to be used in the form parameter. Also, the default button panel is not used if buttons are omitted. In this case, only the Escape (Windows) or Esc (Mac OS) key lets you exit the form.

The dialog is accepted if the user clicks an Accept button or presses the Enter key (numeric key pad), or if the ACCEPT command is executed.

Keep in mind that validation does not cause saving: if the dialog includes fields, you must explicitly call the SAVE RECORD command to save any data that has been modified.

The dialog is canceled if the user clicks a Cancel button or presses the cancel key combination (Ctrl-Period on Windows, Command-Period on Macintosh), or if the CANCEL command is executed.

If you pass the optional * parameter, the form is loaded and displayed in the last open window of the current process and the command finishes it execution while leaving the active form on screen.

This form then reacts "normally" to user actions and is closed when 4D code related to the form (object method or form method) calls the CANCEL or ACCEPT command. If the current process terminates, the forms created in this way are automatically closed in the same way as if a CANCEL command had been called. This opening mode is particularly useful for displaying a floating palette with a document, without necessarily requiring another process.

Note: You must create a window before calling the statement DIALOG(form;*); it is not possible to use the current dialog window in the process nor the window created by default for each process. Otherwise, the error -9909 is generated.

After a call to DIALOG, if the dialog is accepted, OK is set to 1; if it is canceled, OK is set to 0.

1. The following example shows the use of DIALOG to specify search criteria. A custom form containing the variables vName and vState is displayed so the user can enter the search criteria.

   Open window (10;40;370;220)  ` Open a modal window 
   DIALOG("Search Dialog")  ` Display a custom search dialog 
   CLOSE WINDOW  ` No longer need the modal window 
   If (OK=1)  ` If the dialog is accepted 
      QUERY ([Company];[Company]Name=vName;*) 
      QUERY ([Company];&;[Company]State=vState) 
   End if

2. The following example can be used to create a tool palette:

      `Display tool palette
   $palette_window:=Open form window("tools";Palette form window)
   DIALOG("tools";*) `Give back the control immediately
      `Display main document windowl
   $document_window:=Open form window("doc";Standard form window)
   DIALOG("doc")

ACCEPT, ADD RECORD, CANCEL, Open window.

After a call to DIALOG, if the dialog is accepted, OK is set to 1; if it is canceled, OK is set to 0.