User Input and Output

OOo Basic provides a very simple mechanism for presenting information to the user and obtaining information from the user at run time (see Table 7 ). These routines aren't used to access files; they're used strictly for user input from the keyboard and output to the screen.

Table 7: User input and output functions.
Function	Description
InputBox(Msg, Title, Default, x_pos, y_pos)	Request user input as a String.
MsgBox (Message, Type, Title)	Display a message in a nice dialog.
Print expression1; expression2, expression3;...	Print expressions.

Simple Output

Use the Print statement for simple, single-line output. A list of expressions follows the Print statement. If two expressions are separated by a semicolon, the expressions are printed adjacent to each other. If two expressions are separated by a comma, the expressions are printed with a tab between them; you cannot change the size of the tabs.

 Print expression1, expression2, ...   ' Print with tabs between expressions Print expression1; expression2; ...   ' Print with nothing between expressions Print 1,Now;"hello","again";34.3      ' Mixing semicolons and commas is fine

Arguments are converted to a locale-specific string representation before they are printed. In other words, dates and numbers appear as you expect based on the locale set in your configuration (Tools Options Language Settings Languages). Boolean values, however, always print the text True or False.

The help included with OOo lists two special expressions that work with the Print statement: Spc and Tab. In OOo Basic, the Spc function works the same as the Space function. It accepts one numeric argument and returns a string composed completely of spaces. The purpose of the Tab function is to advance the printing to the specified column. For example, the command "Print Tab(5);"Hello"" should print "Hello" starting at column five. I say "should" because as of version 1.1, the Tab function does not exist and causes a run-time error. See Listing 11 for a Print example.

Listing 11: ExamplePrint is found in the Misc module in this chapter's source code files as SC08.sxw.

 Sub ExamplePrint   Print "It is now";Spc(12);Now() End Sub

Bug	As of version 1.1, the Tab function does not exist and causes a run-time error.

The Print statement is usually used for simple, single-line output while debugging, because it allows you to stop a macro from running by clicking the Cancel button (see Figure 2 ). This is a great tool for debugging. Place a Print statement before or after lines that may cause a problem. If the values don't appear to be correct, you can click the Cancel button to stop the macro.

Figure 2: The Spc function returns a string with spaces.

When using many Print statements for debugging purposes, print explanatory information with the data to remind yourself what it is.

 Print "Before the loop, x= ";x For i=0 To 10   Print "In the loop, i = ";i;" and x = ";x

When you print a string that contains a new-line character (ASCII 10 or 13), a new dialog is displayed for each new line. The code in Listing 12 displays three consecutive dialogs with text that reads "one", "two", and "three". The Print dialog is able to print using more than one line. If a single line of text becomes too long, the line wraps and appears on more than one line. In other words, although Print will wrap by itself, the user has no way to force a new line in the dialog.

Listing 12: New lines print in their own dialog.

 Print "one" & CHR$(10) & "two" & CHR$(13) & "three" ' Displays three dialogs

The Print statement uses a simple, defined protocol for numeric formatting. Positive numeric expressions contain a leading space. Negative numeric expressions contain a leading minus sign. Numbers with a decimal are printed in exponential notation if they become too large.

The Print statement displays a print dialog each time, unless the statement ends with either a semicolon or a comma. In this case it stores the text from each Print statement and adds to it until it encounters a Print statement that doesn't end with a semicolon or a comma.

 Print "one",  'Do not print yet, ends with a comma Print "two"   'Print "one    two" Print "one",  'Do not print yet, ends with a comma Print "two";  'Do not print yet, ends with a semicolon Print         'Print "one    two"

Multi-Line Output

The MsgBox statement provides more control over the dialog that is displayed than does the Print statement, but can print only one string expression at a time. String expressions that contain a new-line character (ASCII 10 or 13) are printed in the same dialog. Each new-line character starts a new line in the dialog.

Visual Basic .NET uses the Print statement to print to files. Use MsgBox for increased compatibility. See Listing 13 for an example; the output appears in Figure 3 .

Figure 3: This simple MsgBox dialog contains only an OK button.

Listing 13: ExampleMsgBoxWithReturn is found in the Misc module in this chapter's source code files as SC08.sxw.

Campatibility

 Sub ExampleMsgBoxWithReturn   MsgBox "one" & CHR$(10) & "two" End Sub

The dialog in Figure 3 is very simple. The MsgBox function accepts two new arguments, as shown in Listing 14 . The DialogTitle is displayed as the title line of the dialog. Valid values for DialogType are shown in Table 8 . The DialogType determines which buttons are displayed in the dialog, which button is the default button, and which icon is displayed on the dialog.

Table 8: Valid values for DialogType.
Value	Description
	Display OK button only.
1	Display OK and Cancel buttons.
2	Display Retry and Cancel buttons (same as 5).
3	Display Yes, No, and Cancel buttons.
4	Display Yes and No buttons.
5	Display Retry and Cancel buttons (same as 2).
16	Add the Stop icon to the dialog.
32	Add the Question icon to the dialog.
48	Add the Exclamation Point icon to the dialog.
64	Add the Information icon to the dialog.
128	First button in the dialog is the default button. This is the default behavior.
256	Second button in the dialog is the default button.
512	Third button in the dialog is the default button.

Listing 14: The MsgBox function can accept a type and a dialog title.

 MsgBox(Message) MsgBox(Message, DialogType) MsgBox(Message, DialogType, DialogTitle)

Campatibility

Visual Basic documents the value 0 as causing the first button to be the default button; this means that it is the default behavior. OOo Basic documents the value 128 as causing the first button to be the default button. Although this value works, it's only because the default behavior is to make the first button the default button. The source code never actually checks for the value 128; it checks for 256 or 512 and then uses the default behavior if neither is specified. Therefore, VB and OOo Basic are compatible. Whether or not this can be relied on in future revisions of VB and OOo Basic is, of course, anyone 's guess.

You can use more than one DialogType at the same time to achieve your desired buttons, icon, and default behavior. The display choices are encoded in the first four bits (values 0-15 are binary 0000-1111); the icons and default behavior are encoded in higher bits (for example, 64 is 01000000 in binary). To combine attributes, simply use OR or add the values together. (This is similar to the behavior described for file attributes.)

Although you can display a dialog with a Cancel button, this won't cause the macro to stop running, as happens with the Print statement. Instead, the MsgBox function returns an integer that identifies the selected button (see Table 9 ). Clicking the Cancel button returns the value 2, which can then be tested by your code; then you (in your code) can decide whether or not you really want to cancel the macro.

Table 9: Return values from MsgBox.
Value	Description
1	OK
2	Cancel
4	Retry
5	Ignore
6	Yes
7	No

In other words, if you want the macro to stop when a user clicks the Cancel button, you must check the return value, as demonstrated in Listing 15 . The message contains a new-line character so the message contains two lines of text. The dialog type requests three buttons and an icon, and sets the second button to be default (see Figure 4 ). The macro does different things based on the selected button.

Figure 4: Fancy MsgBox with an icon and multiple buttons.

Listing 15: ExampleMsgBox is found in the Misc module in this chapter's source code files as SC08.sxw.

 Sub ExampleMsgBox   Dim nReturnCode As Integer   Dim nDialogType As Integer   Dim sMessage As String   sMessage = "An error occurred!" & CHR$(10) & "Do the important work anyway?"   REM   3 means Yes, No, Cancel   REM  48 displays an Exclamation Point icon   REM 256 second button is default.   nDialogType = 3 OR 48 OR 256   nReturnCode = MsgBox(sMessage, nDialogType, "My Title")   If nReturnCode = 2 Then     Print "Stopping the macro now!"     Stop   ElseIf nReturnCode = 6 Then     Print "You chose Yes"   ElseIf nReturnCode = 7 Then     Print "You chose No"   Else     Print "I will never get here!",nReturnCode   End If   Print "Ready to exit the subroutine" End Sub

Prompting for Input

Use the InputBox function to prompt users for input. You can specify the dialog title. If a Default value is provided, it's displayed in the input box. The displayed dialog contains a text-input box, an OK button, and a Cancel button. The InputBox function returns a string to the calling statement. Clicking Cancel returns a zero-length string.

 InputBox(Message) InputBox(Message, Title) InputBox(Message, Title, Default) InputBox(Message, Title, Default, x_pos, y_pos)

The position arguments are in twips and are relative to the upper-left corner of the current window; one inch is 1440 twips. If the position is not specified, the dialog is centered both horizontally and vertically over the current window. The example in Listing 16 displays the input box two inches from the left edge of the window and four inches from the top. The size of the InputBox is defined automatically from the Message and buttons; OOo configures the layout of this box, as it does for the other basic input and output dialogs.

Listing 16: ExampleInputBox is found in the Misc module in this chapter's source code files as SC08.sxw.

 Sub ExampleInputBox   Dim sReturn As String     'Return value   Dim sMsg As String        'Holds the prompt   Dim sTitle As String      'Window title   Dim sDefault As String    'Default value   Dim nXPos As Integer      'Twips from left edge   Dim nYPos As Integer      'Twips from right edge   nXPos = 1440 * 2          'Two inches from left edge of the window   nYPos = 1440 * 4          'Four inches from top of the window   sMsg = "Please enter some meaningful text"   sTitle = "Meaningful Title"   sDefault = "Hello"   sReturn = InputBox(sMsg, sTitle, sDefault, nXPos, nYPos)   If sReturn <> "" Then     REM Print the entered string surrounded by double quotes     Print "You entered """;sReturn;""""   Else     Print "You either entered an empty string or chose Cancel"   End If End Sub

Figure 5 shows the dialog when it is first displayed. Pressing any key replaces the default text, because this text is highlighted when the dialog first opens. The macro in Listing 16 inspects the return value and checks for a zero-length string. A zero-length string could mean that the Cancel button was used to close the dialog, or it could mean that the user entered a zero-length string and then used the OK button to close the dialog. These two cases are not distinguishable from each other.

Figure 5: InputBox with default text selected.