Difference between revisions of "Documentation/BASIC Guide/Message and Input Boxes (Runtime Library)"

Latest revision as of 12:14, 30 January 2021

>]]

Apache OpenOffice Basic provides the MsgBox and InputBox functions for basic user communication.

Displaying Messages

MsgBox displays a basic information box, which can have one or more buttons. In its simplest variant the MsgBox only contains text and an OK button:

MsgBox "This is a piece of information!"

The appearance of the information box can be changed using a parameter. The parameter provides the option of adding additional buttons, defining the pre-assigned button, and adding an information symbol.

By convention, the symbolic names given below are written in UPPERCASE, to mark them as predefined, rather than user-defined. However, the names are not case-sensitive.

The values for selecting the buttons are:

• 0, MB_OK - OK button
• 1, MB_OKCANCEL - OK and Cancel button
• 2, MB_ABORTRETRYIGNORE - Abort, Retry, and Ignore buttons
• 3, MB_YESNOCANCEL - Yes, No, and Cancel buttons
• 4, MB_YESNO - Yes and No buttons
• 5, MB_RETRYCANCEL - Retry and Cancel buttons

To set a button as the default button, add one of the following values to the parameter value from the list of button selections. For example, to create Yes, No and Cancel buttons (value 3) where Cancel is the default (value 512), the parameter value is 3 + 512 = 515. The expression MB_YESNOCANCEL + MB_DEFBUTTON3 is harder to write, but easier to understand.

• 0, MB_DEFBUTTON1 - First button is default value
• 256, MB_DEFBUTTON2 - Second button is default value
• 512, MB_DEFBUTTON3 - Third button is default value

Finally, the following information symbols are available and can also be displayed by adding the relevant parameter values:

• 16, MB_ICONSTOP - Stop sign
• 32, MB_ICONQUESTION - Question mark
• 48, MB_ICONEXCLAMATION - Exclamation point
• 64, MB_ICONINFORMATION - Tip icon

The following call displays an information box with the Yes and No buttons (value 4), of which the second button (No) is set as the default value (value 256) and which also receives a question mark (value 32), 4+256+32=292.

MsgBox "Do you want to continue?",  292
' or,
MsgBox "Do you want to continue?", MB_YESNO + MB_DEFBUTTON2 + MB_ICONQUESTION

Display of the Message Box

If an information box contains several buttons, then a return value should be queried to determine which button has been pressed. The following return values are available in this instance:

• 1, IDOK - Ok
• 2, IDCANCEL - Cancel
• 3, IDABORT - Abort
• 4, IDRETRY - Retry
• 5 - Ignore
• 6, IDYES - Yes
• 7, IDNO - No

In the previous example, checking the return values could be as follows:

Dim iBox as Integer
iBox = MB_YESNO + MB_DEFBUTTON2 + MB_ICONQUESTION
If MsgBox ("Do you want to continue?", iBox) = IDYES Then
' or,
If MsgBox ("Do you want to continue?",  292) = 6 Then
  ' Yes button pressed
Else
  ' No button pressed
End IF

In addition to the information text and the parameter for arranging the information box, MsgBox also permits a third parameter, which defines the text for the box title:

MsgBox "Do you want to continue?",  292, "Box Title"

If no box title is specified, the default is “soffice”.

Input Box For Querying Simple Strings

The InputBox function queries simple strings from the user. It is therefore a simple alternative to configuring dialogs. InputBox receives three standard parameters:

• An information text.
• A box title.
• A default value which can be added within the input area.

InputVal = InputBox("Please enter value:", "Test", "default value")

Display of the Input Box

• The dimensions of the InputBox window cannot be changed.
• If the user clicks the OK button, the InputBox returns the string typed by the user (or the default string if it was not changed).
• If the user clicks the Cancel button or closes the window, the InputBox returns an empty string.