@DialogBox (Formula Language)

Brings up a dialog box that displays the current document (either open or selected in a view). The dialog box shares fields with the underlying document. The user interacts with the dialog box as usual, clicking OK or Cancel when finished.

This function can be used with any form, but it's particularly useful with forms that contain a single table or layout region, because the user can interact with the table or layout region as if it were a dialog box.

Syntax

@DialogBox( form ; [AUTOHORZFIT] : [AUTOVERTFIT] : [NOCANCEL] : [NONEWFIELDS] : [NOFIELDUPDATE] : [READONLY] : [SIZETOTABLE] : [NOOKCANCEL] : [OKCANCELATBOTTOM] : [NONOTE] ; title )

Parameters

form

Text. The name of the form.

[AUTOHORZFIT]

Keyword. Optional. Scales the dialog box horizontally to fit the first layout region or table on the form. Otherwise, the dialog box is not scaled horizontally.

[AUTOVERTFIT]

Keyword. Optional. Scales the dialog box vertically to fit the first layout region or table on the form. Otherwise, the dialog box is not scaled vertically.

[NOCANCEL]

Keyword. Optional. Does not display the Cancel button. Otherwise, the dialog box contains the Cancel button.

[NONEWFIELDS]

Keyword. Optional. Does not add fields to the underlying document that are in the dialog box form but not the underlying form. Otherwise, all dialog box fields are passed to the underlying document.

[NOFIELDUPDATE]

Keyword. Optional. Does not pass edits from the fields in the dialog box to the underlying document (for example, if you're passing the edits somewhere else in a QueryClose script for the dialog box form). Otherwise, the edits are passed to the underlying form.

[READONLY]

Keyword. Optional. Prohibits writing to the dialog box (for example, if you are using the dialog box to display a Help screen). Otherwise, the dialog box is read-write. Use of this keyword implies [NoCancel].

[SIZETOTABLE]

Note: This parameter is new with Release 5.

Keyword. Optional. Applies [AUTOHORZFIT] and [AUTOVERTFIT] to the first table on the form. Otherwise, they are applied to the first layout region on the form.

[NOOKCANCEL]

Note: This parameter is new with Release 5.

Keyword. Optional. Does not display the OK button. Otherwise, the dialog box contains the OK button. Using this keyword prevents any changes made in the dialog box from being reflected in the current document. If you want the current document to be updated, but don't want an OK button to display, include a hotspot button that executes the RefreshParentNote @command.

[OKCANCELATBOTTOM]

Note: This parameter is new with Release 6.

Keyword. Optional. Displays the OK and/or Cancel buttons side-by-side at the end of the dialog box. Otherwise, the buttons appear stacked near the beginning.

[NONOTE]

Note: This parameter is new with Release 7.

Keyword. Optional. Allows the @Dialogbox function to be used without requiring a current document. If a current document exists, it will be ignored. Using this keyword implies [NOFIELDUPDATE] and [NONEWFIELDS] even if they are not explicitly specified. Using this keyword means that values are not passed from an underlying document to the dialog box; the only values displayed are default formula values. If the [NONOTE] parameter is not specified, a current document is required.

title

Text. The title of the dialog box. Defaults to "Notes®."

Return value

number

@True (1) if the user clicks OK, @False (0) otherwise. If the user clicks OK, corresponding fields are updated (see Sharing of field values) unless [NOFIELDUPDATE] or [NONOTE] is in effect.

Usage

This function is useful in buttons for actions. It does not work in column or selection formulas, or in agents that run on a server (mail and scheduled agents). It is not intended for use in window title or form formulas. It can be used with any form, but it's particularly useful with forms that contain a single table or layout region, because the user can interact with the table or layout region as if it were a dialog box.

@DialogBox cannot return data from a rich text field.

You cannot use this function in Web applications.

If the form contains actions on the action bar, they are not displayed in the dialog box.

[AUTOHORZFIT] and [AUTOVERTFIT] allow you to display an entire layout region (no [SIZETOTABLE]) or table ([SIZETOTABLE]) in a dialog box without displaying the rest of the form. If the form has more than one layout region or table, the first is used. For best results:

  • Use both [AUTOHORZFIT] and [AUTOVERTFIT].
  • In the Layout properties box, deselect "Show border" and select "3D style."

If [AUTOHORZFIT] and [AUTOVERTFIT] are both omitted, the entire form is used and no sizing takes place. If the form contains no layout region (no [SIZETOTABLE]) or table ([SIZETOTABLE]), the entire form is used and no sizing takes place.

Sharing of field values

@DialogBox displays the current document using a different form. This means:

  • If the form has field names in common with the current document, the field values of the current document are displayed in the dialog box. Rich text fields will not be displayed in the form, even if field names are the same as in the current document.
  • If the user changes the value of any fields in the dialog box and selects OK, the changes are reflected in the same fields on the current document.
  • If the user enters a value for a field in the dialog box, and the current document does not contain a field by that name, the value is added to the document, even if it is not displayed in the form.
  • If you do not want to include OK or Cancel buttons on the dialog box, but do want any changes made in it to be reflected in the current document, use @Command([RefreshParentNote]). If you add this command to a hotspot button on the dialog box form, for example, when a user clicks the button the field values in the current document are updated to reflect any changes made to fields having the same names in the dialog box.

Examples

  1. A form called "Profile" contains a button whose formula is 
    @DialogBox("Profile Options"; [AUTOHORZFIT] : [AUTOVERTFIT] )

    Both Profile and Profile Options have a field named "Comments." When the user clicks the button, the document is displayed in a dialog box, using the Profile Options form. The dialog box is scaled to fit the layout region on Profile Options.

    The user can interact with the dialog box, for example, by editing the Comments field.

    The user clicks OK. The changes made to the Comments field are reflected in the document, if it is in Edit mode.

  2. This formula displays a form named "Help screen" for reading only.
    @DialogBox("Help screen"; [AUTOHORZFIT] : [AUTOVERTFIT] : [NOCANCEL] : [NONEWFIELDS] : [READONLY]; "Help")
  3. This formula sizes the table in the form to the dialog box and does not display the OK button.
    @DialogBox( "Table Test" ; [AUTOHORZFIT] : [AUTOVERTFIT] : [SIZETOTABLE] : [NOOKCANCEL])

  4. This formula displays the "info" form in a dialog box entitled, "Provide information," that has no dialog box buttons. The only way the user can close this form to return to the current document is to click the Close icon on the dialog box.
    @DialogBox("info";[NOCANCEL]:[NOOKCANCEL];"Provide information")