User Interface: Messages
This section describes the functions used to communicate with the user through the text message area, including keyboard entry.
Writing a Message Using a Popup Dialog
The function ProUIMessageDialogDisplay() displays the UI message dialog. The input arguments to the function are:
•  The type of message to be displayed.
•  The text to display as the title of the dialog. If you want to support displaying localized text, use the message files and the function ProMessageToBuffer() to generate this string. Message files are described later in this chapter.
•  The message text to be displayed in the dialog. If you want to support displaying localized text, use the message files and function ProMessageToBuffer() to generate this string. Message files are described later in this chapter.
•  ProArray of possible button identifiers for the dialog.
•  The identifier of the default button for the dialog.
The function outputs the button that the user selected.
Example 1: Displaying the UI Message Dialog
The sample code in UgUIMessageDisplay located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_message shows how to display a hard coded confirmation message.
Writing a Message to the Message Window
This section describes the following topics:
•  Displaying and clearing messages
•  The text message file
Functions Introduced:
  • ProMessageDisplay()
    		•
  • ProMessageClear()
    		•
  • ProUIMessageDialogDisplay()
    		•
  • ProUIMessagedialogCreate()
    		•
  • ProUIMessagedialogShow()
    		•
  • ProUIMessagedialogTitleSet()
    		•
  • ProUIMessagedialogMessageSet()
    		•
  • ProUIMessagedialogTransientSet()
    		•
  • ProUIMessagedialogDurationSet()
    		•
  • ProUIMessagedialogBalloonSet()
    		•
    The function ProMessageDisplay() is similar to the C function printf(), but with some important differences:
    •  The first argument is the name (as a wide string) of the message file. The name must include the file extension, but not the path. See the section Text Message File Format and Restrictions.
    •  The second argument, instead of being a format string, is a keyword used to look up the format string in the message file.
    •  The subsequent arguments for the values inserted into the format string are pointers, not values. These values can be data inserted into the message or default values for the data to be read from user input. See the section Getting Keyboard Input for more information.
    •  Although the list of arguments for the values is variable in number, there is a maximum of 9. See Contents of the Message File for more information on using these arguments with a message format.
    The function ProMessageClear() scrolls the text in the message area up one line. This could be used to indicate that Creo Parametric has received the user’s response to a message.
    The function ProUIMessagedialogCreate() is used to create transitory and balloon message windows. The ProUIMessageDialogDisplay is used for the regular message window. The input argument type specifies the message type.
    The function ProUIMessagedialogShow() displays a message window.
    The function ProUIMessagedialogTitleSet() sets the title for a message window. The input argument titile specifies the title of the text.
    The function ProUIMessagedialogMessageSet() sets the message for the window. The input argument message is the text in the message.
    The function ProUIMessagedialogTransientSet() makes a message window transient.
    The function ProUIMessagedialogDurationSet() sets the duration of a transient window. The default duration is 5 seconds. The input argument duration specifies the duration of the window in milliseconds.
    The function ProUIMessagedialogBalloonSet() generates a message for a window balloon. The input arguments to the function are:
    •  target_dialog—The window on which the balloon is displayed
    •  target_component—The component that is pointed by the balloon
    Text Message File Format and Restrictions
    The text message file enables you to provide your own translation of the text message, just as the menu files enable you to provide your own translation of the button name and the one-line command help.
    Restrictions on the Text Message File
    You must observe the following restrictions when you name your message file:
    •  The name of the file must be 30 characters or less, including the extension.
    •  The name of the file must contain lowercase characters only.
    •  The file extension must be three characters.
    •  The version number must be in the range 1 to 9999.
    •  All message file names must be unique, and all message key strings must be unique across all applications that run with Creo Parametric. Duplicate message file names or message key strings can cause Creo Parametric to exhibit unexpected behavior. To avoid conflicts with the names of Creo Parametric or Creo TOOLKIT application message files or message key strings, PTC recommends that you choose a prefix unique to your application, and prepend that prefix to each message file name and each message key string corresponding to that application.
    Creo Parametric looks for the message file using the following search path:
    •  The current Creo Parametric directory
    •  The directory text under the directory named in the text_dir statement in the registry file (protk.dat).
    Note that message files are loaded into Creo Parametric only once during a session, during the first call to ProMessageDisplay(). Consequently, if you make a change to the message file while Creo Parametric is running, you must exit and restart Creo Parametric to have the changes take effect.
    Contents of the Message File
    The message file consists of groups of four lines—one group for each message you want to write. The four lines are as follows:
    1. A string that acts as the keyword to identify the message when you call ProMessageDisplay() This keyword must be unique for all Creo Parametric messages.
    2. A string that will be substituted for the first string when you call ProMessageDisplay(). This string acts like the format string in a printf() statement. By modifying this line in the message file, you can modify the text of the message without modifying your C code.
    3. The translation of the message into another language (can be blank).
    4. An intentionally blank line reserved for future extensions.
    The format string (line 2 in the message file) differs from the format string of a printf() in the following respects:
    •  The conversion specifications (%d, %s, and so on) must include an argument number corresponding to the position of that argument in the subsequent list (starting at 0). For example, instead of %d, %s, you must have %0d,%1s, and so on. If you want to specify a field width, put it in parentheses between the position number and the type specifier; for example, %0(5.3)f.
    •  The separator ||| between message text and a conversion specification signifies that the conversion specification is for a default value for user input. This default value will appear in the text box created using the keyboard input functions, such as ProMessageIntegerRead(). Refer to Using Default Values for more on default values.
    •  The conversion character w is available for wide strings.
    •  You do not need the character constant (\n) at the end of the format. Creo Parametric automatically inserts a new line when necessary.
    Note
    The length of any line in the message file must not exceed 4096 wide characters.
    The following table lists the conversion characters and their corresponding data types.
    Conversion Character
    Data Type
    f
    Float (or double)
    d
    Decimal integer
    s
    Ordinary string (or type char[])
    w
    Wide character strings
    e
    Exponential
    g
    Either float or exponential, as appropriate
    Ensure that the keyword string is similar to the format string to make your C code easy to interpret. Add a prefix that is unique to your application to the keyword string. The examples in this manual use the unique prefix “USER.”
    Message Classification
    Messages displayed in Creo Parametric include a symbol which identifies the message type. Each message type is identified by a classification which begins with the characters %C. A message classification requires that the message key (line 1 in the message file) be preceeded by the classification code. Note that the message key string used in the code should NOT contain the classification.
    Creo TOOLKIT applications can now display any or all of these message symbols:
    •  Prompt—the Creo Parametric message displayed is preceded by a green arrow. The user must respond to this message type (to either input information, accept the default value offered, or cancel the application). Without such action, no progress can be made. The response may be either textual or in the form of a selection. The classification code for prompt messages is %CP.
    •  Info—the Creo Parametric message displayed is preceded by a blue dot. This message type contains information such as user requests or feedback from either Creo Parametric or the Creo TOOLKIT application. The classification code for prompt messages is %CI.
    Note
    Do not classify as Info any message which informs users of a problem with an operation or process. These messages should be classified as Warnings.
    •  Warning—the Creo Parametric message displayed is preceded by a triangle containing an exclamation point. Warnings alert the user to situations which may lead to potentially erroneous situations at a later stage, for example, possible process restrictions imposed or a suspected data problem. However, warnings do not prevent or interrupt task completion, nor should they be used to indicate a failed operation. Warnings only caution the user that the operation has been completed, but may not have been performed in a completely desirable way. The classification code for prompt messages is %CW.
    •  Error—the Creo Parametric message is preceded by a broken square. This message type informs the user when a required task was not successfully completed. It may or may not require intervention or correction before work can continue, depending on the application. Whenever possible, provide a path to redress this situation. The classification code for prompt messages is %CE.
    •  Critical—the Creo Parametric message displayed is preceded by a red X. This message type informs the user of extremely serious situations, especially those which could cause the loss of user data. Options for redressing the situation (if available) should be provided with the message. The classification code for prompt messages is %CC.
    Writing a Message to an Internal Buffer
    Function Introduced:
  • ProMessageToBuffer()
    		•
  • ProMessageWstringbufferAlloc()
    		•
    The functions ProMessageToBuffer() and ProMessageWstringbufferAlloc() have the same relationship to ProMessageDisplay() that the C library function sprintf() has to printf(): it enables you to write a message to an internal, wide-string buffer instead of to the Creo Parametric message area. These functions perform exactly the same argument substitution and translation as ProMessageDisplay(). You provide a wide-string buffer as the first argument, and the subsequent arguments are the same as those for ProMessageDisplay().
    The function ProMessageToBuffer() allows you to write a message with a maximum length of 80 characters to a wide-string buffer.
    For a message of any length use the function ProMessageWstringbufferAlloc(). You must free the output string translated_msg using the function ProWstringFree().
    Note
    To avoid conflicts with the names of Creo Parametric or Creo TOOLKIT application message files or message key strings, PTC recommends that you choose a prefix unique to your application and prepend that prefix to each message file name and each message key string corresponding to that application.
    For example, you can rename the message file used by the following functions as <Application_Name>_msg.txt:
    •  ProMessageToBuffer()
    •  ProMessageWstringbufferAlloc()
    •  ProMessageDisplay()
    •  ProCmdDesignate()
    Getting Keyboard Input
    Functions Introduced:
  • ProMessageIntegerRead()
    		•
  • ProMessageDoubleRead()
    		•
  • ProMessageStringRead()
    		•
  • ProMessagePasswordRead()
    		•
    These four functions obtain keyboard input from a text box at the bottom of the Creo Parametric window. The functions check the syntax of the user’s entry and indicate when the entry is simply a carriage return. Each of the functions enable you to restrict numeric input to a specified range, or string input to a specified string length. The functions continue to prompt the user until a valid response is entered.
    The function ProMessageStringRead() supports string lengths up to 127 characters.
    Using Default Values
    Prior to Release 20, Pro/TOOLKIT applications implemented default values by checking for a user-entered carriage return. Beginning with Release 20, you can specify default values within the call to ProMessageDisplay(), provided that the separator ||| appears in the format string in the message file. (See the section Contents of the Message File for the specific placement of the ||| separator.)
    Note
    You must call the function ProMessageDisplay() before calling the ProMessage*Read functions to specify the default values.
    Default values are displayed in the text box as input. Note that this value will not be passed to the Creo TOOLKIT function if the user hits a carriage return; instead, the function will return PRO_TK_GENERAL_ERROR and the application must interpret that the user intends to use the default.
    To specify a constant default value, the format string would appear as follows:
             Enter a double: |||3.0
    Specifying constant defaults is not recommended as changing the default requires revising the Creo TOOLKIT application. Specifying defaults that are variables is more flexible.
    To specify a default integer that is a variable, for example, the format string in the message file would appear as follows:
             Enter any integer: |||%0d
    Example 2: Displaying Messages and Retrieving Keyboard Input
    The sample code in UgMessageWindowUse.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_message shows how to print messages and accept keyboard input with default values. The example also shows how to write a message to an internal, wide-string buffer. The name of the message file is msg_ugmessage.txt.