Version

www.capesoft.com
     

Contents
  Standard Clarion Message Box Object  
  Introduction
  Methods
  Properties
  CapeSoft Message Box with Features Object
  Introduction
  Methods
  Properties
Complete Documentation
     

Standard Clarion Message Box Object

Introduction

The Standard Clarion Message box object is Capesoft MessageBox's base class for all Capesoft MessageBox's classes. It replicates the Standard Clarion Message box, and is useful if none of the CapeSoft Messaging Features are required, or if you want to derive your own message class. The class is a global object whose properties can be set from anywhere in the program. While this is not particularly required in this class, it will be useful in other classes derived from this one.

Note: You can make use of the MessageBox project define (set and cleared by the template, depending on whether MessageBox is disabled or not) to omit MessageBox code from being compiled if MessageBox is disabled as follows:

  omit('***',_NoCSMesBox_=1)
ThisMessageBox.DontShowWindow=1
  ***

Methods

Method Parameters Method Description
Init ( ) This method just initializes the queues that the object uses. The Global Template populates this method in the global module (before any windows are open/run) .
Open (string MessageTxt,
string HeadingTxt,
string IconSent,
string ButtonsPar,
long DefaultPar,
<long StylePar>)		 This method does all the hard work of setting up the window correctly. 
It initializes the properties that require initializing, sets up the IconControl (if required), sets the  message box's main text and positions it correctly. After that it unhides the buttons required and sets their  position properties, as well as the position properties of the icon and the window size.
Parameters:
MessageTxt - the text for the message box window
HeadingTxt - the text for the title bar of the message window
IconSent - the icon to be placed on the window
ButtonsPar - the text or equated text to place on the buttons.
DefaultPar - the button to use as the default
StylePar - reserved for later use
It calls the CreateStrings, the CreateButtons and the SetControlProperties methods.
CreateStrings ( ) This method uses the BreakStringToQueue and the ExtractStringToQueue methods to break the message string into a queue from which the prompt control's text is set. 
It breaks the string up based on the existence of the vertical bar '|' character, the length of the string and the existence of spaces in long strings.
CreateButtons ( ) This method unhides and sets the text/image properties of the buttons required for the message box. It checks whether a button string was passed to the message box and will unhide a default 'OK' button if not, or unhide the buttons passed in the buttons string. It uses the ExtractStringToQueue method if customized buttons are required.
ExtractStringToQueue (string TempStr, long NoOfTimes) This method splits a string (TempStr) up into a queue based on the existence of a vertical bar '|' character. It will be limited to the NoOfTimes parameter passed to it. It ignores the rest of the string if more than NoOfTimes vertical bars are present in the string.
BreakStringToQueue (string TempStr) This method splits a string (TempStr) up into a queue dependant on the length of the string and the existence of spaces over the MaxLen property. If there are none between the MaxLen and the Glo:OverMaxLen equate, then the string is chopped at the Glo:OverMaxLen character.
SetControlProperties ( ) This method sets the position and dimensions of the buttons on the window. It also adjusts the window if it is too small to fit the buttons on. It sets the default button.
TakeEvent ( ) This method looks for a button accept event. It sets the button number for return and then posts an event:closewindow.
Kill ( ) This method disposes the queues that were created in the Init method.
SendClose ( ) This method simply posts a close event to the message() window.
CheckIniEntries ( ) This method checks whether the translation file that is specified exists. If not, then it is created (with the English text).
CSLocale (STRING CSButton, <STRING ButtonText>) This method should be used in place of the Clarion LOCALE function to set the default text for the message() buttons. Parameters:
CSButton - should contain 'button' or 'CLAbutton' (as in the LOCALE function)
ButtonText - A comma delimited string containing the text for the 8 buttons. This string should contain 7 commas.
CloseNow (LONG pForce=0) This method allows you to close the Message/Stop or Halt windows externally. An accept event will be posted to the default button. If pForce is omitted (or 0) the window will only close if there is a default button, otherwise (if it is set) if there is no default button, an accept is posted to the first button.

Properties

Property Type Property Description
ButtonPressed long This property contains the ID of the button that is pressed in order to close the window. It is blank if the window is not shown (i.e. if the DontShowWindow property is set or the DontShowThisAgain feature was previously activated for this message).
ReturnValue long This property contains the value to return when the window is closed.
ButtonsSent byte This property is a flag that is set in the Open method to inform the other methods whether a button parameter was sent to the Message window.
ButtonYPos long(15) This is the Y co-ordinate of the buttons. The initial height is the distance between the buttons and the strings. The CreateStrings method changes this property so that when all the string controls for the message have been created, the buttons are created at the correct height.
IconWidth long(0) This is the width of the icon (if any) after the icon control is created. This will determine the X-position of the string controls created.
NoOfButtons long This is the number of buttons created in the CreateButtons method.
DefaultButton long(0) Initially 0 incase no default is passed. This is the ID of the default button.
WinWidth long(0) This is the window width. It is adjusted throughout the open method, and is then used to set the window width after all the controls are created, etc.
Defaults unsigned(0) This is the actual default parameter passed to your message window.
MaxLen long(75) This is the start of the Maximum-lengthed string. The first space after MaxLen characters is where the string is cut. The remainder of the string is then cut similarly until the remainder string's length is less than MaxLen characters.
FlatButtons byte(0) This is a flag to indicate that the buttons on the messagebox window should be flat.
TrnStrings byte(0) This is a flag to indicate that those controls that should be transparent (prompt, strings, check boxes, etc) are.
FirstButton long Contains the Control ID of the first button.
ButtonText cstring(100),dim(8) Contains the text that appears on each button. The elements of the array are blank if no button is populated in that position (i.e. if there are 4 buttons then only the first for elimants in the array will have text). This property will retain the last message box's button text until the next message box is called.
WebSupportHere byte(0) Set this when WebBuilder or ClarioNET is used in this application. This byte ensures that the paragraphing character (<13,10>) is omitted from the MessageBox text, which is not supported by both ClarioNET and WebBuilder.
SavedResponse long This property is used to save the GlobalResponse, until the MessageBox routine is exited (in which case GlobalResponse is equated with the saved value).
ShowRepeatBar  byte(0) If this property is set, then a double vertical bar will display a single vertical bar (instead of 2 CR/LFs).
TrnButtons  Byte(0) separate property for setting the buttons to transparent.
FromProcedure string(255) Use this property to determine which procedure called the message() window - ABC, C55 and up only
FromExe string(255) Use this property to determine which EXE called the message window.
OKIcon string(255) Allow a default icon for the standard OK button.
YesIcon string(255) Allow a default icon for the standard yes button.
NoIcon string(255) Allow a default icon for the standard No button.
AbortIcon string(255) Allow a default icon for the standard Abort button.
RetryIcon string(255) Allow a default icon for the standard Retry button.
IgnoreIcon string(255) Allow a default icon for the standard Ignore button.
CancelIcon string(255) Allow a default icon for the standard Cancel button.
HelpIcon string(255) Allow a default icon for the standard Help button.
DefaultIconsOnRight byte If clear icons on left, otherwise on right.
TextYPos long(5) Allow programmer to place stuff above the text (if required).
BT queue After the Open method it contains a list of the buttons and their corresponding control IDs.
SQ queue Used for breaking up the message string and the buttons string into a queue from which the controls are created (one for each entry in the queue).
Message1 string(4096) Contains the message text to be displayed in the message box.
Heading string(1024) Contains the heading text to be displayed in the title bar of the message box.
Icon1 String(255) Contains the icon (filestring or equate) to be displayed in the message box.
Buttons string(255) Contains the buttons (string or equates) to be used in the message box.
IconControl long Contains the ID of the IconControl.
PromptControl long Contains the ID of the prompt control for the message box text
PromptControlHeight  long(8) Contains the height of the Prompt control after the prompt text has been set.
PromptControlWidth long Contains the width of the prompt control after the prompt text has been set.
CenterPrompt byte(0) If set, the message text will be centered in the window, as well as being center justified.
TranslationFile  cstring(@s255) Contains the file name to be used for translating the default button text and other miscellanous text.
MessagesUsed long(0) This property is incremented when the window is opened. If > 1 then it returns immediately as there is already a MessageBox open.
FirstSelectEvent byte An internal flag to indicate the first (auto) select event has occured and that the default button must be selected.
ButtonTextMaxWidth long(0) This property contains the size of the largest text length so that all the buttons will be unfiform to the largest required size (if this is larger than the default).
ButtonHeight long This property is used to store the button height (for fontsizes > 10). Set in the CreateButtons method. 
DefaultButtonText cstring(50), dim(8) Set in the CSLocale method, this property contains overriden button text (mainly used for translation)
ShowRepeatBar byte Set this to display a || (double vertical bar) as a | single bar instead of 2 line breaks.
TrnButtons byte(0) Separate property for making the buttons transparent.
FromExe string(255) Contains the name of the EXE that called the message window. This is primarily for Multi-EXE setup - or where a number of EXEs use the same logfile, or you want the EXE name to be displayed in the titlebar of the messagebox. This is not for Multi-DLL (i.e. to capture the name of the calling app).
FromProcedure string(255) Contains the name of the procedure that called the message window (ABC, C55 and above only).
OKIcon string(255) Use this property to place an icon on the OK button of a message window. This can either be an Icon equate or a file.
YesIcon string(255) Use this property to place an icon on the Yes button of a message window. This can either be an Icon equate or a file.
NoIcon string(255) Use this property to place an icon on the No button of a message window. This can either be an Icon equate or a file.
AbortIcon string(255) Use this property to place an icon on the Abort button of a message window. This can either be an Icon equate or a file.
RetryIcon string(255) Use this property to place an icon on the Retry button of a message window. This can either be an Icon equate or a file.
CancelIcon string(255) Use this property to place an icon on the Cancel button of a message window. This can either be an Icon equate or a file.
IgnoreIcon string(255) Use this property to place an icon on the Ignore button of a message window. This can either be an Icon equate or a file.
HelpIcon string(255) Use this property to place an icon on the Help button of a message window. This can either be an Icon equate or a file.
DefaultIconsOnRight byte If set then the icons for the button equates on the right of the buttons are placed on the right, otherwise they appear on the left of the button text.
_CloseAllWindows byte This property is set in the CloseNow method. If it's set, then future windows opened will Close immediately. 

Capesoft's Featured Message Box Object

Introduction

This class makes use of the Standard Clarion Message box object as it's base object to build in some useful features. These features are described in more detail in the Capesoft MessageBox Documentation in the following sections:

Logging Messages to a file
Message time-outs
Message with the DontShowThisAgain check box
Message with the PlaySound feature
Skip x next Messages

Methods

Method Parameters Method Description
Init (long UseABCClass=0,
long UseDefaultLog=0)		 This method just initialises the queue that the object uses and calls the Parent.Init.
PreOpen (string Message1,
string Heading, <long DefaultButtons>)		 This method checks some of the features to ensure that this window should be displayed. The DontShowThisAgain and the SkipNext features may require that the message is not displayed. The ThisWindow.Init routine is aborted before the window is opened.
If the playsound feature is required, then the sound is played here.
Parameters:
Message1: The message text to be displayed in the message box.
Heading: The heading text to be displayed in the title bar of the message box.
DefaultButtons: The DefaultButton number as passed to the MessageBox window procedure (only needed for windows that are not displayed).
Open (string MessageTxt,
string HeadingTxt,
string IconSent,
string ButtonsPar,
long DefaultPar,
long StylePar)		 This method sets the timer if a window timeout is required and unhides the DontShowThisAgain check-box if this feature is required. It then calls the Parent.Open.
The Parameters are all passed to the parent.open method.
SetControlProperties ( ) This method sets the position of the DontShowThisAgain check-box and calls the Parent.SetControlProperties.
OpenLog (<string ExtraDetails>) This method simply opens the log file. This enables you to put code before/after the log file is opened. This method is used whenever the file is opened.
Parameters:
ExtraDetails: This is used when extra details will be logged to the ASCII file. This will be the additional header.
CloseLog ( ) This method simply closes the log file. This enables you to put code before/after the log file is closed. This method is used whenever the file is closed.
GetDontShow (String IniEntry), long This method is a function to return whether the DontShowThisAgain checkbox was checked on this message previously. It returns the Button that was pressed when the CheckBox was checked, or a 0 if no entry is found. By default, the IniEntry string is made up of: 'DontShow: ' and the Heading (upto a maximum of 42 characters) and the MessageText (upto a maximum of 42 characters) - the entire section which cannot be more than 42 characters (Clarion/Windows limitation).
PutDontShow (string IniEntry,
 long IniValue=1)		 This method adds an entry to the Registry when the DontShowThisAgain check-box is checked. The IniEntry string must be formatted in precisely the same manner as the IniEntry string used in the GetDontShow method.
TakeEvent ( ) This method looks for a timer event (if the TimeOut feature is active) and the accept event from the DontShowThisAgain (if this feature is required). It also calls the Parent.TakeEvent.
Close ( ) This method clears the features that are not static using the self.StaticSettings property to determine which features are static. It also handles the logging of messages.
Kill ( ) This method disposes the queue that was created in the Init method and calls the Parent.Kill.
SendClose ( ) This method handles the logging of the message before calling the parent.sendclose method.
PrimeLog (<string ExtraDetails>) This method primes the log file with the information from the window that it is logging. If the default ASCII file is not used, then the priming must be done in the application (the template will normally take care of this).
Parameters:
ExtraDetails: This is used when extra details are required to be logged to the ASCII file. The string is added on after a comma to the rest of the ASCII log string.
InsertLog ( ),long This method adds a log record to the log file. If the default ASCII file is not used, then the record adding must be done in the application (the template will normally take care of this). Returns the errorcode (if any) after the add to the default file.
LimitLog (long LogFileLimit) This method is used to limit the records in the file as specified in the Global Extension template (this does not apply to the default ASCII file). The code is all generated into the EXE if the limiting is required.
GetEmail (STRING EAddress, STRING ESubject, STRING EApplication), string This method returns a properly structured (UUencoded) email message to be used in connection with the HyperActive Template. Parameters:
EAddress - The email address of the recipient, can be in the format ('Firstname Lastname <emailaddress>').
ESubject - The subject of the email.
EApplication - the application name. 
Returns - a formatted mail with the message text containing the date & time of occurance, the heading and the text of the message box.
ActivateTimeOut ( ) Posts an accepted event to the default button.
GetReg (LONG pHKey,
STRING sSubKeyPath, STRING sValue),?		 Gets an item's registry value.
PutReg (LONG pHKey,
STRING sSubKeyPath, STRING sValueName, STRING sValue,
LONG lType=1),byte		 Sets the value of an item in the registry.

Properties

Property Type Property Description
DontShowThisAgain long(394) This property contains the ID of the DontShowThisAgain control.
WhoPressed string(100) This property indicates who closed the window. If a button is pressed, then this property will contain self.LoggedIn. If the window times out then this property will contain 'Timer'.
StartTime long This is the time when the message box is opened. It is used for determining how long the message box is open for.
StartDate long This is the date when the message box is opened. It is used for determining how long the message box is open for.
HeadingLen long Contains the length of the heading to be stored in the Registry up to a max of 255. 
MessageLen long Contains the length of the message string to be stored in the Registry up to a max of 255. 
NotAgainCheckBox  long This is the property used to store the state of the 'Don'tShowThisAgain' checkbox when the message box is open.
UseDefaultLogFile  long A property to indicate that the file required is the default logging file, so file operations must be handled in the parent methods.
LogFileOpen  long A property to indicate that the logging file has been opened. This prevents the file from being closed when it has not been opened.
StartTimeOut  long The time when the MessageBox window was opened. Used for the TimeOut feature to track the time left until the MessageBox window times out.
TimeOutTracker  long The counter to indicate how much time is left before the window times out
TimeOutPrompt  long(391) The control value of the String for the TimeOut tracking counter.
HyperLink cstring(255) This is the string to place in the HyperActive control string on the MessageBox window. If this string is clear, then the HyperActive control string is hidden. You must have added the necessary HyperActive control templates into your application in order to use this feature.
HAControl long This is the ID of the HyperActive control string.
INIFile cstring(255) This is the sub-Registry folder used for storing the status of the messages that use the DontShowThisAgain feature.
INISection cstring(255) This is the section in the Registry folder used for storing the status of the messages that use the DontShowThisAgain feature.
RegistryFolder cstring(255) This contains the sub-folder in the HKEY_LOCAL_MACHINE\SOFTWARE Registry folder where the values for the status of the DontShowThisAgain for each message are stored. Used in conjunction with the RegistryKey property.
RegistryKey long This contains the key to use where the DontShowThisAgain settings will be stored. Should contain one of the key equates (like HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER). If 0 then HKEY_LOCAL_MACHINE will be used.
SN queue This queue tracks the amount of times that the message function is called for the SkipNext feature. It has 3 fields: Heading, Message and Hits. The Heading and Message are used to identify the unique message, and the hits field tracks how many messages were called and resets itself when the message is displayed.
TimeOut long(0),static This is the value that the window timer must be set to in order to activate the Message TimeOut feature.
ShowTimeOut byte(0),static This is the property to indicate that the TimeOut counter must be displayed so that the user can see how much longer the MessageBox window will still be open for.
SkipNext long(0),static This is the amount of messages that should be skipped before the next one is displayed.
LogMessages long(0),static This is a flag to indicate that the messages must be logged.
PlayWavFile cstring(255),static This is the name of the WavFile that should be played when the message box is opened. No WavFile is played if this is blank.
NotAgain long(0),static This is the flag to display the DontShowThisAgain checkbox.
NotAgainID long(0) This is an option ID used to store the status of the NotAgain checkbox (rather than by message text and heading).
NotAgainText cstring(255),static This is an optional string which contains the text for the DontShowThisAgain checkbox. If the string is blank then the default 'Don't show this again' text will be used. This text must be cleared before the next message box is called to return to the default text.
LoggedIn string(100),static This is the name of the user. This field may be used for the message logging.
StaticFeatures long,static This is a bit mask to indicate which features are static. The features that are not static are cleared in the Close method.
DontShowWindow byte(0) If you set this byte before the PreOpen method, then the MessageBox will not be displayed. This is useful to be able to log the message without having to view it.
TempLogOff byte(0) This property is to temporary disable logging. This property will be cleared at the end of the message for which it is set.
LogFile &File This is a pointer to the file to be used for message logging.
LogFileName &String This is a pointer to the variable that contains the filename of the default ASCII file (as specified in the Global Extension Template).
GPFHotKey long If this property contains a value (key equate), then this key is alerted, and if activated causes a GPF to the program.
DateFormat string('@d17') This property is used for the DatePicture of the date stamp in the logfile entry.


[end of document]