CapeSoft MessageBox Objects
Documentation
Latest Version 
| 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 dependent 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. For English, this would be: 'OK,Yes,No,Abort,Retry,Ignore,Cancel,Help' |
| 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. |
| 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 elements 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 miscellaneous 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 occurred 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 uniform 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 overridden 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. |
| Method | Parameters | Method Description |
| Init | (long
UseABCClass=0, long UseDefaultLog=0) | This method just initializes 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. |
| 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. |
| 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. |