CAPSLOCK() | Hackers Guide to Visual FoxPro 7.0

MessageBox(), FoxTool's MsgBox(), InputBox()

Haven't you wondered how all those cool Windows programs display the same type of dialogs—with the same icons, text faces, and screen positioning? Perhaps it's a conspiracy. Nah. Maybe they all agreed on a convention and are actually sticking with it? Get real. The only reason those boxes all look the same is because they are all produced from the same function, and FoxPro programmers have access to that function as well.

MessageBox() is a function introduced to the language in Visual FoxPro 3.0 that duplicates much of the functionality already available to FoxPro 2.x programmers in the FoxTools.FLL function MsgBox. (See FoxTools and SET LIBRARY TO for more information on FoxTools and libraries in general.) The big difference between using the two is that MessageBox() is built in and doesn't require the use of any external libraries. The little difference is that the order of parameters differs between the two. Both functions return the same values to indicate the user's choice.

InputBox() was introduced in VFP 7 to give developers access to the single input dialog used for collecting View Parameters.

Usage

nReturnValue = MESSAGEBOX( uMessage [, nIconButtons [, cTitle                             [, nTimeOut ] ] ] ) nReturnValue = MSGBOX( cMessage, cTitle,                         nIconButtons )    && FoxTools version

Parameter	Value	Meaning
uMessage	Any	The message to display in the body of the dialog box. In VFP 6 and earlier, this parameter must be character. Beginning in VFP 7, any type may be used and it's converted to character. If uMessage is character, you can use CHR(13) to separate lines of text, and the text is automatically word-wrapped. VFP cuts off the message after 1024 characters.
cMessage	Character	A character string or expression to display in the body of the dialog box. Use CHR(13) to separate lines of text. Automatically word-wrapped.
nIconButtons: Choose one icon:	0	No icon.
	16 (MB_ICONSTOP)	Stop icon.
	32 (MB_ICONQUESTION)	Question mark.
	48 (MB_ICONEXCLAMATION)	Exclamation point.
	64 (MB_ICONINFORMATION)	Information (i).
Add to that value which button set to display:	0 (MB_OK)	OK.
	1 (MB_OKCANCEL)	OK, Cancel.
	2 (MB_ABORTRETRYIGNORE)	Abort, Retry, Ignore.
	3 (MB_YESNOCANCEL)	Yes, No, Cancel.
	4 (MB_YESNO)	Yes, No.
	5 (MB_RETRYCANCEL)	Retry, Cancel.
and add to that the default button:	0 (MB_DEFBUTTON1)	First button has the focus.
	256 (MB_DEFBUTTON2)	Second button has the focus.
	512 (MB_DEFBUTTON3)	Third button has the focus.
And if desperate:	4096 (MB_SYSTEMMODAL)	System modality: forces the message box to always be on top.
cTitle	Character	A character string or expression to display in the title bar of the box.
nTimeOut (added in VFP 7)	Numeric	The number of milliseconds after which the dialog should be closed, even if the user hasn't made a choice.
nTimeOut (added in VFP 7)	Omitted	The dialog stays open until the user makes a choice.
nReturnValue	1 (IDOK)	OK
	2 (IDCANCEL)	Cancel
	3 (IDABORT)	Abort
	4 (IDRETRY)	Retry
	5 (IDIGNORE)	Ignore
	6 (IDYES)	Yes
	7 (IDNO)	No
	-1	The dialog timed out

The second numeric parameter is calculated by adding the three numeric values for the icon, types of buttons and default button, and passing that value as a single numeric parameter.

Example

* This example displays the dialog box shown in Figure 1 MessageBox("Your system appears to have been destroyed."+;         chr(13)+"Purging all traces of your work..."+ ;         "Press any key to continue...", 16,;         "Monologue Box, not Dialog Box")

Figure 1: Sample dialog box.

This is a pretty sample, but a terrible user interface example. Remember, dialog boxes should allow you to have a dialogue with your users, your clients, the people who sign your paycheck. These are not opportunities to show how much smarter you are than they (you never know what you may prove!). Give the people who pay your salary intelligent, understandable options, not one-way, no-way-out warnings that Armageddon is around the corner. While we're on a tear, Figure 2 shows our second-least-favorite dialog.

Figure 2: A really bad dialog box.

Don't ever leave a dialog as confusing as this for your end users to mess with. You risk invoking the 50-50-90 law: If there's a 50-50 chance of your end users choosing a particular option, 90 percent of the time they'll choose the one that causes the most destruction.

You might be wondering how you can keep track of, and decode in the future, the obscure settings of the message functions' numeric parameter. Fortunately, Microsoft has taken care of this by letting you #INCLUDE any of the MessageBox parameter settings stored within the FoxPro.H file, an ASCII text file. (The table above shows the defined constants for the various values.) By including this file, provided with FoxPro, code can be changed from this:

IF MessageBox("This is the message body", 21, ;              "This is the title") = 2

to this:

#INCLUDE "FOXPRO.H"   IF MessageBox("This is the message body", ;              MB_RETRYCANCEL + ;              MB_ICONSTOP + ;              MB_DEFBUTTON1, ;              "This is the title") = IDCANCEL

Add 4096 to the numeric parameter passed to the message function to invoke system modality. In Windows 3.1, this was a "last resort" style dialog, without all the features (nor did it consume all the resources) of its fancier siblings. The title was displayed as the first line of text within the box. Body text did not word-wrap. Icon settings were ignored and no icon was displayed. In VFP 5.0 and later, now that FoxPro runs on Win32 platforms only, the System Modal setting is not that severe. In Windows 95 and 98, there seems to be no difference from an ordinary message box. In NT, the message box always stays on top, even if you switch applications underneath it. But it is not the potential system-locking-up monster it was under Windows 3.1. Good riddance!

The folks at Hacker Labs went to town on this function in VFP 3, and we documented several weird behaviors in that product in the Hacker's Guide for Visual FoxPro 3.0. In VFP 5 and later, these loopholes seem to have been plugged.

Usage

cResult = INPUTBOX( cMessage [, cCaption [, cDefault                      [, nTimeOut [, cTimeoutValue ] ] ] ] )

Parameter	Value	Meaning
cMessage	Character	The prompt to appear in the dialog. Unlike MessageBox(), the prompt is limited to a single line. Any message too long for the dialog (94 characters with default settings) gets cut off.
cCaption	Character	The caption to appear on the title bar of the dialog. Like the message, captions that are too long get cut off.
cCaption	Omitted or empty	The dialog caption is the caption of the main Visual FoxPro window.
cDefault	Character	An initial string to offer the user. The string appears, highlighted, in the text box portion of the dialog.
cDefault	Omitted	Nothing appears initially in the text box portion of the dialog.
nTimeOut	Numeric	The number of milliseconds after which the dialog closes, even if the user hasn't pressed a button.
nTimeOut	Omitted	The dialog stays open until the user chooses either OK or Cancel, or uses the keyboard equivalents.
cTimeoutValue	Character	The string to return if the dialog times out.
cTimeoutValue	Omitted	The empty string is returned if the dialog times out.
cResult	Character	The user's input (or cDefault if the user didn't change it) if he chooses OK; the empty string if the user chooses Cancel or presses ESC; cTimeoutValue if the dialog times out.

Have you ever needed just one little input value from a user? Creating a form for that situation seems like so much work (though, of course, you could have a form class for collecting a single input). The InputBox() function is designed for just that situation. This is another case where the FoxPro team took functionality that was already in the product (this dialog is used to get the value of a parameter when a parameterized view is opened) and exposed it so that we could use it, too.

Note that the function returns a character string, even when the input looks like a number or date. Similarly, the default value and timeout value must be character strings.

Example

cUser = InputBox( "Who are you?", oApp.cAppName )   cMainCompany = "The most important one" cCompany = InputBox( "What company do you want to work on?", ;                      "Accounting App", cMainCompany )   cSignIn = InputBox( "You have 10 seconds to identify yourself",;                     "", "", 10000, "Intruder" )