Note: The information contained in this document applies to OpenInsight for Workgroups v3.11 Pre-release Build 6 and above.
Messages are a key component of Windows applications; they are used to report errors, offer simple choices like Yes or No, OK or Cancel, and Abort, Retry or Ignore. In OpenInsight, messages can also prompt for user input, including passwords and data that must pass validation tests. The Msg() function, which implements OpenInsight messages, has been enhanced significantly for the OpenInsight 3.11 release to include:
1. Replaceable parameters
2. Context help directly from a message
3. Custom message icons and sounds
4. A response can be required for response-type messages
5. Default values can be generated by a user-defined function for response-type messages
6. Support for all Windows-relevant features from Advanced Revelation s messages
7. Processing messages
8. Asynchronous timed messages (ie. logon banners)
9. Improved backwards-compatability support for OpenInsight applications
Each of the new features is also defined in the Msg_Equates insert record. To edit an insert record, choose the File - Open Insert menu item in the System Editor.
Replaceable Parameters
Replaceable parameters allow a generic message to have specific details filled in when the message is displayed. This is the message equivalent of a form letter, like one in which the date, address, and name is filled in before printing. One of the biggest advantages of replaceable parameters is that it eases multi-lingual development: The message itself can be internationalized but the calling procedures do not have to be modified. Another advantage is the amount of customization that is available to each customer of the application. The most common use of replaceable is in error messages; for example:
Msg(@window, The "%1%" table has not been created or attached. , , , ACCOUNT )
will display:
The "ACCOUNT" table has not been created or attached.
One other note of interest: The replaceable parameters can be in any part of the message definition, including the message text, title, and button text.
Context Help
Some Yes/No messages may have dire consequences if the wrong choice is selected. Consider a message that asks, Are you sure you want to format the diskette in drive A? . Although the results in this case are clear, there are messages which need more of an explanation, at least for the first time they are encountered. To assist the user, you can add a Help button to the message. There are four options for the help button processing:
1. Display QuickHelp
2. Display help using a Windows help file (.hlp)
3. Display an explanatory message
4. Call a user-defined function
The first three options are obvious; the fourth allows you to implement a solution in Basic+, allowing for almost-unlimited flexibility.
The new message help feature is available from a new tab in the Message Designer, which is located in the User Interface Workspace. The default help is no help button.
Custom Icons and Sounds
If you are in the Message Designer, choose Help - About from the menu. The About dialog that displays is actually a message created using the Message Designer. The name of the message is MSG_ABOUT; it is stored in the SYSPROG application. On the Appearance tab, there is a area to specify the icon, with a new choice: Other. The Other choice allows you to select a bitmap entity to use as the icon for the message, either clipping or scaling the image. (The reason that a bitmap entity is used instead of an icon entity is that Windows 95 draws icons in a different manner than Windows 3.1. To use a .ico file, create a bitmap entity and specify the name of the .ico file as the bitmap file name. Starting in OpenInsight 3.1, bitmap entities support the following file types: .bmp, .ico, .wmf, .gif, .pcx, .tga, and .tif.)
The following example shows how to specify a bitmap entity and system sound for the message when calling Msg() programmatically:
$insert Msg_Equates
$insert Message_Box_Equates
$insert Logical
Def =
Def<MTEXT$ > = Check out the picture and sound
Def<MICON$ > = B
Def<MBITMAP$ > = MSG
Def<MCLIPBMP$> = TRUE$
Def<MBEEP$ > = MSG_ICON_STOP$ ;* the sound that Windows plays with a stop-sign message
Required Response
The response-type is one of the most useful features of the Msg() function. With a line or two of code, you can effectively produce the equivalent of a custom dialog and possibly hundreds of lines of code. A new feature has been added to response-type messages: the ability to require a non-null response. When this feature is used, the OK button is greyed until the user enters a value, thus requiring a response.
Default is Function
This is one of the most advanced options for the Msg() function. With response-type messages, the default response may require complex calculations or other custom coding. If the MLITERAL$ field of the message definition is true, the Msg() function assumes that the default value for the message is actually the name of a function which returns the default value for the message. For example, if you wrote a function called CURRENTUSER which returned the user name of the current user, you could specify CURRENTUSER as the default value (MDEFINPUT$) and set MLITERAL$ to true, so that the current user name would be the default value for the message. Up to two parameters are passed to the specified function depending on the number of parameters that the function takes, according to the following table:
# Params/Values Passed
0 None
1 MsgKey
2 MsgKey, MsgDef
Advanced Revelation Equivalencies
Several features were added to support Arev-style messages. Many of the message types in Arev were character-mode specific, like the types allowing the input.char() processing to be replaced, so those types are not supported in OpenInsight. The following is a list of Arev message types and their equivalents in OpenInsight:
A - the default message type in Arev; the equivalent message type in OpenInsight is BO (OK button)
D, DB - the down type message used to take down a message displayed using the U or UB types are supported in OpenInsight, but in a slightly simpler manner; see the Processing Messages section for an example.
N - prepend N to the message type to suppress display of the message; this is useful for toggling processes between batch mode and user-interaction mode, since in batch mode, the messages should return their defaults so that the batch can continue and in user-interaction mode the user should be able to review error messages and respond to Yes/No or other option-type messages
R, RC, RE, RCE/REC - These response type messages are all supported in OpenInsight
Tn - timed messages are supported in an identical manner in OpenInsight
U, UB - the up type message is supported in OpenInsight; see the Processing Messages section below for an example.
The unsupported Arev messages types are: AI, AX, AIX, C, H, L, RI, and S. The functionality of the C type can be approximated using the NR type and the Default is Function option. The other unsupported types either are character-mode specific or are solutions to issues with Arev s input.char() function.
Processing Messages
Processing messages are displayed and return immediately and then taken down when processing is complete. The calling program calls Msg() once with the U type to display the message and once more with the D type to take it down. No buttons are placed on the message, since it is for display only. The return value from the U type call is a structure which can be passed to the second call to Msg() which takes down the message:
Rec = "Processing…"
Rec<MTYPE$> = "U"
MsgUp = Msg(@window, Rec)
* processing goes here
Msg(@window, MsgUp) ;* take the message down
Asynchronous Timed Messages
Asynchronous timed messages are timed messages that return immediately, (instead of returning after the specified number of seconds). This style of message was made possible by the new TIMER event in OpenInsight 3.1. The most common use of asynchronous messages is splash screens, where a message is displayed for a certain number of seconds yet processing continues. Note that because the TIMER event is used, the message will not disappear until queued events can be executed. Queued events can not be executed while Basic+ procedures or other events are executing unless the Yield() function is called.
Improved Backwards-Compatability
In the OpenInsight 3.1 release, Msg() itself was a totally new function. It did not support all of the features that were in the original Msg() function. The main difference was that it could not be called from a program run from the System Editor or when there was no suitable parent window. In the 3.11 release, the new Msg() function senses these conditions and relegates to the older implementation automatically, providing better support for existing utilities and applications.
________
See Also: Msg(), Message_Box(), insert record Msg_Equates