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