Communicating with Users

There are many different ways to communicate and interact with the user. Virtually all applications communicate with the user by displaying information, prompting for information, or displaying a custom dialog window. These interactions control the flow of information into the software application as well as force the user to make decisions that affect the database information. For example, you can display a message"Document Saved"or confirm an action"Are you sure you want to delete these documents?"

This section will describe some of the more common commandsMessagebox, Dialogbox, Inputbox, and Print. You'll find that these statements are frequently used in the LotusScript programming language.

Messagebox Statement

The Messagebox statement is probably the most commonly used statement for communicating with users. This command offers many robust options that can be used to interface with the end-user community. The following describes the syntax for this command.

MessageBox message, options, title

message Any text string (including variables, constants, or reference objects).

options Used to configure the button, icon, display mode, and default "selected" button.

These parameters are optional.

title Used to set the popup window title. This parameter is optional.

In the simplest form, this statement is used to display a popup message to the user (see Figure 6.3). For example, the following displays a text string along with the current date and time.

Figure 6.3. Sample Messagebox

Messagebox "The current date and time is: " + Now

However, the statement also has many additional parameters that enable you to customize the display of the popup message window. Before we get to the display options, you can add a title to the popup message window. The window title is the third parameter and must be a text string value that does not exceed 128 characters. You'll notice that in Figure 6.4, the second parameter is omitted, which is the reason for the two commas in the sample code.

Figure 6.4. Sample Messagebox with optional parameters

Messagebox "The date and time is: " + Now , , "Today's Date"

Next, you can add graphics, modify the buttons, and set a default button for the message window. This is accomplished via the second parameter, which must equate to a valid value. Adding one or more values together determines the values for the Messagebox statement to display.

Value	Constant	Description of Button to Be Displayed
0	MB_OK	OK
1	MB_OKCANCEL	OK and Cancel
2	MB_ABORTRETRYIGNORE	Abort, Retry, and Ignore
3	MB_YESNOCANCEL	Yes, No, and Cancel
4	MB_YESNO	Yes and No
5	MB_RETRYCANCEL	Retry and Cancel

Value	Constant	Description of Icon to Be Displayed
16	MB_ICONSTOP	Stop sign icon
32	MB_ICONQUESTION	Question mark icon
48	MB_ICONEXCLAMATION	Exclamation point icon
64	MB_ICONINFORMATION	Information icon

Value	Constant	Description
0	MB_DEFBUTTON1	Set button 1 as the default button
256	MB_DEFBUTTON2	Set button 2 as the default button
512	MB_DEFBUTTON3	Set button 3 as the default button
0	MB_APPLMODAL	This options stops the current application until the end-user responds to the message.
4,096	MB_SYSTEMMODAL	This options stops all applications until the end-user responds to the message.

For example, the following illustrates four example Messagebox statements. The first illustrates a message with no parameters. The second prompts the user to select Yes or No and includes the question mark icon. This message also includes a window title"Caution". The third example includes the Abort, Retry, and Cancel buttons. Using the 256 value, the Retry button is set to the default button. Finally, the last example illustrates the use of the LotusScript constant library, which references MB_OKCANCEL, or a value of 1.

' Display an informational message
Messagebox "Document saved."

' Display YES/NO buttons and Question mark icon
Messagebox "Do you want to continue?", 4 + 32, "Caution"

' Display Abort/Retry/Cancel buttons, stop sign icon and
' make the second button (abort) the default
Messagebox "Unable to open file", 2 + 16 + 256, "Warning"

' Display the OK/Cancel Button. Must add %Include "LSCONST.LSS"
' in the (Options) section of the Globals values.
Messagebox "Unable to open file", MB_OKCANCEL, "Warning"

Note

To utilize constant strings (such as MB_OKCANCEL) to manage the messagebox display settings, you must add the following statement to the (Options) section:

%include "LSCONST.LSS"

This statement is used to reference a LotusScript file that contains default constants. Refer to the Domino Designer help for a complete listing of constant files and their uses.

Finally, messagebox can be called as a function that returns a value that corresponds to the selected button. The following shows the syntax for a messagebox function call.

MessageBox (message, options, title)

When called in this fashion, the function will return one of the following values.

Value	Constant	Description
1	IDOK	Return value when the OK button is clicked.
2	IDCANCEL	Return value when the Cancel button is clicked.
3	IDABORT	Return value when the Abort button is clicked.
4	IDRETRY	Return value when the Retry button is clicked.
5	IDIGNORE	Return value when the Ignore button is clicked.
6	IDYES	Return value when the Yes button is clicked.
7	IDNO	Return value when the No button is clicked.

For example, the following illustrates how to capture the result of the messagebox window.

answer% = Messagebox("Are you sure?", 36, "Continue?")
If answer% = 6 Then
 Messagebox ("Update complete.")
 Else
 Messagebox ("Transaction canceled.")
 Exit Sub
 End If

Tip

There are two ways to call this statementMessagebox or Msgbox. Both are valid and equivalent statements.

 

Print Statement

The Print statement is another way to communicate with the user. However, instead of displaying messages in a popup window, the text string is displayed in the Status Bar located at the bottom of the Lotus Notes client. The syntax for this command is

Print string

string Any text string, variable, date, time, or list of values separated by semicolons, colons, or spaces.

Print "The current date and time is: " + Now

The Print and Messagebox statements can help debug or track the execution of a LotusScript routine. You can periodically add Print statements to determine variable values or track conditional branches as the program executes. For example, the following illustrates how the value of the variable could be displayed. By periodically inserting a print or messagebox statement, you can view the object value as the program executes.

Print "The current value is: " + doc.Status(0)
Msgbox "The current value is: " + doc.Status(0)

A.6.2

In this second example, you can track the path that the user selects.

answer% = Messagebox("Are you sure?", 36, "Continue?")
If answer% = 6 Then
 Print "The user selected YES"
Else
 Print "The user selected NO"
End If

 

Inputbox Statement

The Inputbox is used to display a popup window where the end-user can specify a value. This value is subsequently returned to the LotusScript routine where it can be processed or stored. The syntax for this function is as follows.

Inputbox (prompt, title, default, position)

prompt A text string expression that describes the input box.

title Optional. Used to describe the title of the window.

default Optional. The default to be displayed in the input field.

position Optional. The x and y coordinates for the window separated by a comma.

For example, the following prompts the user to provide his or her name. When the input box window is displayed, the input field defaults to "John Doe" and the title displays at the top of the window (see Figure 6.5). The answer is subsequently displayed in the Status Bar at the bottom of the Lotus Notes client.

Figure 6.5. Sample Inputbox

Dim result As String
result = Inputbox("What is your name?", "Question", "John Doe")
Print "Your name is: " + result

 

Dialogbox Statement

The Dialogbox method is used to display the current document or a specified form in a popup dialog window. Using this method, you can pass field values between the popup and the underlying form. The following describes the syntax for this method.

flag = notesUIWorkspace.Dialogbox (form, options)
Call notesUIWorkspace.Dialogbox (form, options)

The following describes the various options associated with this method, which are listed in chronological order. To use the default value, simply insert a comma as a placeholder for the parameter. All of the following are optional parameters.

Option	Description
1. AutoHorzFit	Automatically size the dialog box horizontally to fit the first layout region or table on the form. This value must be a boolean value of either trUE or FALSE.
2. AutoVertFit	Automatically size the dialog box vertically to fit the first lay out region or table on the form. This value must be a boolean value of either TRUE or FALSE.
3. NoCancel	Do not display the Cancel button. This value must be a boolean value of either trUE or FALSE.
4. NoNewFields	By default, any field that contains a value on the dialog form but that does not exist in the underlying document is automatically created. This optional parameter enables or disables the creation of new fields on the underlying document. This value must be a boolean value of either trUE or FALSE.
5. NoFieldUpdate	Used to disable field updates between the dialog window and the underlying document. This value must be a boolean value of either trUE or FALSE.
6. ReadOnly	This value displays the dialog box in "readonly" mode when set to TRUE. Otherwise, by default, the window is displayed in read-write mode. This value must be a boolean value of either trUE or FALSE.
7. Title	The title for the dialog window.
8. NotesDocument	Used to display an alternate document instead of the currently selected document.
9. SizeToTable	Used to automatically size the dialog based on the first table in the form. This value must be a boolean value of either trUE or FALSE.
10. NoOkCancel	Removes the OK button from the dialog window. This value must be a boolean value of either trUE or FALSE.
11. OkCancelAtBottom	By default, the OK and Cancel buttons are displayed to the right of the window. When set to trUE, this option displays the button along the bottom of the window. This value must be a boolean value of either trUE or FALSE.

For example, let's say you have a conference room form that includes a button called Recurring Event. This button contains the following code that, when clicked, displays a form named (RepeatReservation) in a dialog window. Using this dialog, the user can enter the parameters of the recurring conference room reservation.

When the user clicks OK, the field values are passed from the dialog window back to the corresponding fields on the underlying document. In this scenario, the form in the dialog must contain the same field names as the main form in order for the values to be passed from the DialogBox to the document. If the fields do not exist on the underlying document, they are automatically created.

Dim w As New NotesUIWorkspace
Dim uidoc As NotesUIDocument
Dim doc As NotesDocument
Set uidoc = w.CurrentDocument
Set doc = uidoc.Document
Call w.DialogBox("(RepeatReservation)", True, True,,,,, "Repeat")