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.

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.

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.

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

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.

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.

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

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.

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.

Note This parameter is new with Release 6.

Keyword. Optional. Displays the OK and/or Cancel buttons side-by-side at the bottom right of the dialog box. Otherwise, the buttons appear stacked at the top right.

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. If the [NONOTE] parameter is not specified, a current document is required.

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

none

Only updates changes made to like-named fields on the current form if the dialog box is saved and closed. See "Sharing of field values" below.

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

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.

DialogBox method of LotusScript NotesUIWorkspace class

Example
See Also

DialogBox method
Filling out a form with @DialogBox
@PickList
@Prompt
RefreshParentNote @Command
"Taking your Domino applications to the Web" on the Lotus Developer Domain
"Creating context-sensitive help for applications" on the Lotus Developer Domain

Glossary