Contents
		Getting Started - some basics
		Introduction [Suggested Reading]
		Feature List
		Installation Instructions  [Suggested Reading]
		Jump Start  [Suggested Reading]
		Examples
		Some More Detail
		Capesoft's Messaging Features [Suggested Reading]
		Using the Capesoft MessageBox Templates
		General Info - for manual procedure adding
		International Language Support
		Relationship with other products [New in Version 1.53]
		Support
		Frequently Asked Questions
		Object Documentation
		How to get Technical Support
		General Information
		What the users are saying
		Source Code Policy [Important]
		Copyright and License
		Distribution
		Where can you get it
		Version History [NB for existing users]
		NB: Existing users upgrading from a previous version, should read all the Version History notes of the subsequent versions as well as the release notes for this version.

Introduction

Have you ever heard the saying: "I got an error message which said something like..."? or: "This program never works!" Getting the actual message out of the user can be a lengthy process. To try and make a logging system for every message that you make, gets a bit tedious. It either means making a window and calling that window every time, or else calling a function whenever you call the message. Sounds like the job for an object or a template!

Thus came forth Capesoft MessageBox, which has some useful features enhancing our other products. I found whilst using Special Agent, that there were many occasions where I had to work around that "Are you sure you want to delete this record?" message. Wouldn't it be great to integrate Makeover into your messages and stops to make them look like the rest of your program?

The advantage of using Capesoft MessageBox is you can use the Message(), Stop() and Halt() commands as usual, but they'll call the Capesoft MessageBox functions instead of the Topspeed ones, so you don't have to go changing all your existing code!!

Capesoft MessageBox comes in the form of a global object set and a template that makes it easy to use the objects. Because MessageBox is managed in a window that the programmer controls, there really isn?t anything you can?t do!

Note: Although Capesoft MessageBox is written using objects, you can use Capesoft MessageBox in legacy applications as well.

Note: It his highly recommended that you take a bit of time to read up about the Message (in particular), Stop and Halt functions in the Clarion manuals to be able to obtain the full functionality of Capesoft MessageBox.

Features

• Logging Messages to a file (you can determine the file structure and what gets written there)
• Message time-outs
• Message with the DontShowThisAgain check box
• Message with the PlaySound feature
• Skip x next Messages
• Static Features (switch one/more of the above features on for the whole program)
• Button Icons (left/right justified or no text)
• Larger buttons for longer text
• Interacts with HyperActive to: mail you the message from your user; or place a Hyperlink on your message box to a website, etc.
• Integrate your MESSAGE() with other 3rdparty products like Special Agent, Makeover, etc.
• Supports translation.
• Compatible with ClarioNet and WebBuilder.
• Change message/heading/button text in the Message window.

Note: The MessageBox text is limited to 1024 characters.

Installation Instructions

1.	Run the supplied installation program. (You may have already done this, to get this far).

Note: Please take note of the example applications section of this doc to demonstrate some of the features of Capesoft MessageBox.

Getting Started

Step 1 (optional - if you want to log messages to a file in your dictionary):

Open your dictionary (of your application that you want to add MessageBox to) and import the MessageBox.txd that is found in the clarionx\3rdparty\libsrc directory.

Step 2:

Open your application (that you want to add MessageBox to) in the Clarion IDE. If this is a Multi-DLL application, then the application to open is the Data-DLL.

Run the Template Utility 'ImportCSMessageBoxxxx' (In the 'Application' menu, select the 'Template Utility'). xxx meaning abc or leg (for legacy) depending on which template set you are using for this application (for multi-DLL projects - do this only on the data DLL).

Note the names of the 3 procedures added: ds_Stop, ds_Halt and ds_Message (these are the names of the 3 procedures that will be used for the stop(), halt() and message() functions).

Step 3:

Add Capesoft MessageBox's Global Extension Template (for more details on the various options, click here)  to your application.

On the Basic tab of the MessageBox Global Extension template select the corresponding procedure for each of the procedures required. So for the Message Box Procedure, select the ds_Message procedure.

For Multi-DLL applications:

• For Legacy applications you must complete Step 2 in both the Data DLL application and all EXE applications in the project.
• For ABC applications you need only complete Step 2 in the Data DLL application.
• You must set-up the multi-DLL relationship in the Global Extension template correctly.
• If you require any of the features in your other applications, then you need to add the Global extension template to those DLL applications (where the features are required).
• Note: In Clarion5 ABC Data DLLs you will receive a whole bunch of compile warnings (for a duplicate class generation). You can ignore these warnings (a glitch fixed in Clarion5.5).

Step 4 (optional - if you want to set features using templates):

Using the 'Capesoft MessageBox Set Features' code template (or you can do it manually), set the features properties that you require, if you're using the 'CapeSoft MessageBox with Features' objects.

Example Applications

Capesoft MessageBox ships with a number of examples to aid you in implementing some of the features, which you can find in the clarionx\3rdParty\examples\CapesoftMessageBoxl.

There is only one application in each directory, except the Multi-DLL application example, which has all the applications for the multi-DLL in the one directory

The Examples are as follows (all apps are 32bit, stand-alone unless specified):

Capesoft's Messaging Features

Logging Messages to a file
Message time-outs [Not available for Stop() commands and not recommended for Halt() commands]
Message with the DontShowThisAgain check box
Message with the PlaySound feature
Skip x next Messages [Not available for Halt() commands] 
Icons on the Buttons
Hyperlinks and Mailing the Message
The DontShowWindow Feature
Static Features
Property changing

1. Message Logging to a file

Using this feature enables you to track the messages that occur while the user is using your program. At present, the fields that can be tracked are: Message, Heading, Time and Date of occurrence, Duration (that the message was open), Button Pressed and User (if the message box times out, then the User = 'Timer'). The beauty of using objects for this messaging is you're not tied to the default file structure. You can add extra fields and prime them just before the record is added to the file.

You can set the TempLogOff property on if you would like to disable logging for a single message. This property is always cleared at the end of the MessageBox procedure. So the logging will be reactivated after the first Message is called after the TempLogOff property is set.

1.1. Steps to implement Message Logging

Step 1

You should add a logging file to your dictionary, or you may use the Capesoft MessageBox default ASCII file if you like, in which case you may skip this step. There are two ways of doing this, you can either:

1. Import the CapeSoft Message Logging file (recommended) (Details).
2. Add your own file to your dictionary. You don't need to use the Topspeed driver.

Step 2

You need to complete the steps for implementing the CapeSoft Messaging laid out in the Getting Started section

Step 3

You need to ensure that the Global Extension template has been set to allow Message Logging.

Step 4

You need to set the Logging feature property to activate the logging. You can either:

1. Use the Set Features Code Template to set the property or
2. Set the object's LogMessages property directly 

Example Code

ThisMessageBox.LogMessages = 1         !Activate Message Logging
ThisMessageBox.LoggedIn = UserName   !UserName is a string(100) of the user logged in

Step 5 (optional)

It's a good idea to add a browse and/or report for the logging file. You can use the Clarion (abc or legacy) templates to do this. Check the example applications for ideas.

For tips on logging and doing special and unique logging, see the FAQs.

2. Message time-outs

It's often useful to have a time out on a message. A message may be a non-essential, that you don't want a process to be halted if no-one's around, but if someone is around, then they have a chance to respond to the message. You can create a message with a default button and set the time-out length. When the time-out occurs, the default button will be "Pressed" and the message closed so that your program can continue. This feature will not be usable in stops, as the default button is the abort button. It is sometimes handy to inform your user on how much time the window will be open before the TimeOut occurs. There's an object property which you can set to display a counter that indicates the time remaining before the TimeOut occurs in hh:mm:ss.

2.1. Steps to implement the Timeout Feature

Step 1

If you have not done so already: complete the steps in the Getting Started section. You need to select the CapeSoft Message Box with features radio button in the Global Extension Template. If you would like to display the TimeOut counter in all the messages that use the TimeOut feature, you can set this up in the Global Extension Template.

Step 2

You need to set the Time-out object property. You can either:

1. Use the Set Features Code Template to set the property; or
2. Set the object's Timeout property directly

Example Code

ThisMessageBox.TimeOut = 3000            !30 second TimeOut
ThisMessageBox.ShowTimeOut = 1         !Show the TimeOut down-counter to indicate the time until TimeOut occurs

Step 3 (optional)

You can also set the ShowTimeOut property in order to display the time remaining until TimeOut if you don't want to set this in the global extension template.

3. Message with the DontShowThisAgain check box

3.1. Steps to implement the 'DontShowThisAgain' Feature

Step 1

If you have not done so already: complete the steps in the Getting Started section. You need to select the CapeSoft Message Box with features radio button in the Global Extension Template.

Step 2

You need to set the 'DontShowThisAgain' object property. You can either:

1. Use the Set Features Code Template to set the property; or
2. Set the object's NotAgain property directly

Example Code

ThisMessageBox.NotAgain = 1                !Activate the NotAgain feature, which will display the 'DontShowThisAgain' check box.

Step 3 (Optional)

You can set the text to appear next to the checkbox if you don't want the default 'Don't show this again' text to appear next to the check box.

Example Code

ThisMessageBox.NotAgainText = 'Save this option'

4. Message with the PlaySound feature

Sounds can be a way of alerting a user when a message occurs, especially when the message pops-up in the middle of a long process.

4.1. Steps to implement the PlaySound Feature

Step 1

If you have not done so already: complete the steps in the Getting Started section. You need to select the CapeSoft Message Box with features radio button in the Global Extension Template.

Step 2

You need to set the wavfile (an object property) that the PlaySound must perform when the message occurs. You can either:

1. Use the Set Features Code Template to set the property; or
2. Set the object's PlayWavFile property directly.

Example Code

ThisMessageBox.PlayWavFile = WavFileName !WavFileName is a cstring(255) of the sound file to play.

5. Skip x next Messages

If you're debugging a loop, it can be useful to use a stop or message to watch what's going on. The problem is that you often want to skip a lot of the messages until you're at the right one. It gets tedious pressing the ignore button so many times, and in many instances you go past the point where you're wanting to stop. So you use this feature to skip the correct amount of messages or stops until you're at the right one.

Note: The counter (for how many messages are to be skipped) is stored in a queue, which will be reset when the program is restarted. 

Note: If you set the SkipNext property to 10 then, the 1st, 11th, 21st, etc. messages will be displayed. The number (-1) indicates the amount of messages skipped between messages displayed.

5.1. Steps to implement the SkipXNext messages feature

Step 1

If you have not done so already: complete the steps in the Getting Started section. You need to select the CapeSoft Message Box with features radio button in the Global Extension Template.

Step 2

You need to set the Object property so that the object knows how many messages to skip before displaying the next one. The object tracks what messages to skip in a queue so that you can skip (for example) 20 of Message A and skip 27 of Message B and 12 of Message C. You will need to set the property of this message before you display it. You can either:

1. Use the Set Features Code Template to set the property; or
2. Set the object's SkipNext property directly

Example Code

loop 57 times                                        
  ThisMessageBox.SkipNext = 56         !Skip the following stop 55 times - so it will be shown on the 1st and 57th times
  stop('First/Last time')
  loop 12 times
    ThisMessageBox.SkipNext = 11       !Skip the following stop 10 times - so it will be shown on the 1st and 12th times
    stop('First/Last time Sub')
  end
end
ThisMessageBox.SkipNext = 0

6. Icons on the Buttons

NB: Before continuing, at present Clarion does not support Icons on XP-type buttons. So if you use an icon on a button you will loose the XP type look (if you have a manifest file attached to this EXE) of the buttons.

Sometimes it can be handy to display an icon on a button instead of or as well as text. There are 2 ways of doing this:

1. Including the icon in the button parameter:

The button parameter will need to be a string, so you will not be able to use the Clarion Button equates when using icons on the buttons as well - using this method (more about this in method 2). You can use the Clarion Icon equates in the string though for the relevant icons. The icon equate or icon file must be enclosed in square brackets. If the filename is placed before the button text, then it will be positioned to the left of the button text, otherwise it will be placed to the right of the button text.

Example Code

message('Message Text here','Heading Text',icon:question,'[' & icon:Open & ']Open|[' & icon:New & ']New|Copy[' & icon:Copy & ']|[' & icon:cut & ']|[' & icon:paste & ']',1)

will display the following MessageBox:




Note: If you want to use square brackets('[]') in the ButtonsString, then you must repeat the first one as follows.

message('Message Text here','Heading Text',icon:question,'Copy[[1]|Paste[[2]|Cut[[3]',3)


will display the following MessageBox:

7. Hyperlinks and Mailing the Message

Together with Capesoft's HyperActive, you can place a HyperActive string on the MessageBox. You can even (with a few easy steps) add email support so that your users can mail you the precise message, straight from the MessageBox. Using the email support they won't even have to fill in the MessageBox Text, heading and Date and time of occurrence. This will all be done for them.

7.1. Steps to implement a Hyperlink onto your MessageBox

Step 1

If you have not done so already: complete the steps in the Getting Started section. You need to select the CapeSoft Message Box with features radio button in the Global Extension Template.

Step 2

You need to add the HyperActive Global Extension to your application and add the HyperActive Local Extension Template to your MessageBox procedure (the message window - probably called ds_message). Note: You will need to add the HALink control to the HyperActive controls list on the HyperLinks tab. Check the HyperActive docs for more details on making controls HyperActive.

Step 3

You need to set the HyperLink that the URL must point to in the MessageBox. You can either:

1. Use the Set Features Code Template to set the property; or
2. Set the object's HyperLink property directly.

Example Code

ThisMessageBox.HyperLink = OurWebSite            !OurWebSite is a cstring(255) of the URL

Step 4 (For mailing)

If you would like the URL to create an email of the MessageBox, then you need to set up the following:

8. The DontShowWindow Feature

There are times when you cannot access a message that is being displayed, such as a Clarion message or a 3rdparty DLL of which you do not have the access to modify the source. If you set this property, then you can prevent this message from being displayed. If the logging is on, then it will still be logged. The message() function will return the default button when the window is not displayed (unless the DontShowThisAgain checkbox was previously checked.

8.1. Steps to implement the DontShowWindow Feature

Step 1

If you have not done so already: complete the steps in the Getting Started section. You need to select the CapeSoft Message Box with features radio button in the Global Extension Template.

Step 2

You need to set the DontShowWindow (an object property). You can either:

1. Use the Set Features Code Template to set the property; or
2. Set the object's DontShowWindow property directly.

Example Code

ThisMessageBox.DontShowWindow = 1

9. Static Features

It's often useful to be able to set a feature once and then not have to set the feature again, like in the case of Message Logging. 9 times out of 10 you'll want all the messages that occur to be logged, so it's useful to set this feature to be static. But with most of the other features you'll probably not want to make them static as you probably won't want all your messages to (for instance) have the DontShowThisAgain check-box or a Timeout. In the case of the SkipNext feature, this is a static feature, so the property should be cleared after the message (which the property is required for) has been displayed.

You will be able to set these features in the Set Features Code Template or you can set the object's property directly.

Features that can be made static are: the DontShowThisAgain check-box , Timeout , Message Logging , MessageBox HyperLinks , Playing Sounds and DontShowWindow.

Example Code to set the Static Features:

ThisMessageBox.StaticFeatures = bor(ThisMessageBox.StaticFeatures,Glo:Set_NotAgain)
ThisMessageBox.StaticFeatures = bor(ThisMessageBox.StaticFeatures,Glo:Set_MsgLogging)
ThisMessageBox.StaticFeatures = bor(ThisMessageBox.StaticFeatures,Glo:Set_TimeOut)
ThisMessageBox.StaticFeatures = bor(ThisMessageBox.StaticFeatures,Glo:Set_HALink)
ThisMessageBox.StaticFeatures = bor(ThisMessageBox.StaticFeatures,Glo:Set_DontShowWin)

Example Code to clear the Static Features:

ThisMessageBox.StaticFeatures = band(ThisMessageBox.StaticFeatures,65535 - Glo:Set_NotAgain)
ThisMessageBox.StaticFeatures = band(ThisMessageBox.StaticFeatures,65535 - Glo:Set_TimeOut)
ThisMessageBox.StaticFeatures = band(ThisMessageBox.StaticFeatures,65535 - Glo:Set_MsgLogging)
ThisMessageBox.StaticFeatures = band(ThisMessageBox.StaticFeatures,65535 - Glo:Set_HALink)
ThisMessageBox.StaticFeatures = band(ThisMessageBox.StaticFeatures,65535 - Glo:Set_DontShowWin)

10. Property changing

Sometimes you cannot get at the message() commands that are passed to your message window. The message() function could be called from 3rdparty DLLs, Clarion itself, or buried in a class somewhere. Often these messages contain text that is even difficult to interpret for the programmer, let alone the user.

MessageBox makes it easy for you to change the text that will be visible to the user. 

1. Go to the Embeds of your Message window (probably called ds_message) and highlight the following embed:

2. Insert source such as the following:

if clip(LMBD:MessageText) = 'Change this text'    !If this text is used
  if (LMBD:Buttons = button:yes+button:no) and (LMBD:HeadingText = 'Now')
      !If these buttons are on the window then exit without showing the window.
    ThisMessageBox.DontShowWindow = 1
  else
      !Otherwise just change the displayed window text.
    LMBD:MessageText = 'What should I change this text to?'


  end
 end




The following variables can be used:

LMBD:MessageText contains the text in the first parameter of the Message() call, which is the body text of the message window.
LMBD:HeadingText contains the text in the second parameter of the message() call, which is the text used for the heading of the message.
LMBD:UseIcon contains the equate or file for the icon to be displayed on the message() window.
LMBD:Buttons contains the value of the fourth parameter of the message() call, which is used to determine which buttons must be on the window and what the text on those buttons is.

Template Guide

Global Extension Template
Local Message Control Template
Local Stop Extension Template
Local Halt Extension Template
The Set Features Code Template
The ImportCSMessageBox Utility Template

1. Global Extension Template

The first step (once your application is open) is to add the Global Extension. To do this:

1.1	Click the 'Global' button on the Application tree window.
1.2	Click on the 'Extensions' button on the 'Global Properties' window.
1.3	Click on the 'Insert' button on the 'Extension and Control Templates' window.
1.4	Select the 'Activate_MessageBox' template from the list of extension templates and click on the 'Select' button.
1.5	Back at the 'Extension and Control Templates' window there should appear the template with its details on the right.
1.6	Debugging: Check the 'Disable All Capesoft MessageBox Code' checkbox if you don’t want to generate any Capesoft MessageBox code. This is useful if your app doesn't compile and you want to exclude all Capesoft MessageBox source when compiling.
1.7	Capesoft Functions to Use: If this is part of a Multi-DLL app, then jump to 1.26. Alternatively, select the Capesoft MessageBox functions that you require. For example, if you would like to use just the Messaging function, then uncheck the 'All' check box and check the 'Messages' check box in the 'CapeSoft Functions to Use:' group.
1.8	Once you've selected which functions you require, the object selection will be enabled.
1.9	Procedure Selection: Select a window procedure on which the message code will be populated. Use the 'Message Box Procedure' drop list to do this. You need to do this even if you do not require the 'Messages' function as the Stop and Halt functions require this procedure.
1.10	You will need to enter a Stop procedure name if you require the Stop function (and like-wise for the Halt function).
1.11	Select the object to use: You can either choose to use the 'Standard Clarion Message' objects, or you can use the 'CapeSoft Message Box with features' objects (see Capesoft's Messaging features).
1.12	ClarioNET support: If you have the ClarioNET global extension template added to this application, then the ClarioNET Support option will appear. Similarly for WebBuilder applications, you can enable the WebBuilder support in MessageBox.
1.13	Change to the 'Logging' tab to set up the logging options. Leave the 'Disable Logging' check box unchecked (if you require Message logging) and select a file from your dictionary for the Message Logging File. (see Importing the Message Logging File to use the file shipped with MessageBox) You can also leave this blank to use the default ASCII file ('c:\MessageBox.Log').
1.14	Selective Logging: If you only want to log Stops and Halts, then you can check the 'No Logging for Messages' check box. Similarly for only logging Messages, check the other two check boxes, etc.
1.15	If you want to turn message logging on at program startup, then check the 'Automatically Log Messages' check-box.
1.16	Fields: You can equate some fields in your file to the Capesoft MessageBox Fields if you require them in the entry fields supplied. These fields are optional, and are there because we find them useful. You can create extra fields if you would like to and populate them with your own info. You can use the object embed in the PrimeLog method. These fields are not available if you are using the default ASCII file.
1.17	Record Limits: You can limit the logging file if you want to. You can either limit it by Date or Count. Select either from the 'Limit By:' drop list box. If you are using the default ASCII file, then you will not be able to limit it.
1.18	If you selected to limit the file to Date, then you can select how far back you want to store records. The limiter is in days, so any messages logged more than this 'limit' ago will be deleted. If you selected to limit the file to Count, then you can select the maximum amount of messages to be stored in the log file. The messages will be logged until the limit is reached, when the oldest record will be removed every time a new message is logged to the file. You can use a variable if you like, although you must be sure to set the variable before the first message()/stop()/halt() is called.
1.19	Go to the 'Features' tab if you selected to use the 'CapeSoft Message Box with features' objects then you will be able to tweak the template to suite your needs on the 'Features' tab. If you don't require logging, then you can check the 'Disable Logging' check box. This will save you the time of having to create the Logging file in your dictionary (see Creating the Logging File). All the other features will be available as and when you require them, simply by setting the respective properties.
1.20	Remember Features: You can remember Some, All or None of the feature settings by checking/ unchecking the respective check boxes. If you check the 'Remember xxx' check box, then this property becomes static and you need to manually reset the activating property when you do not require it. Alternatively, the property gets cleared after the message box is displayed.
1.21	When the TimeOut feature is used, you can display a counter to indicate the time left before the TimeOut occurs. Check the 'Display TimeOut Counter' checkbox to set this property by default. You can set this feature on at any time using the ShowTimeOut property.
1.22	You may want to display a vertical bar in your Message windows. You can use || double vertical bars and check the 'Allow Double Vertical bars to be displayed as a bar' checkbox in order to display a vertical bar. Otherwise, || will mean two line breaks in your message text.
1.23	Dont Show This Again Settings: You can choose whether you would like to store the DontShowThisAgain setting in an INIFile or the windows registry. If you selected the Registry, then you can set the Registry sub-folder (inside the HKEY_LOCAL_MACHINE\SOFTWARE) which will contain the status of the DontShowThisAgain for your messages. There is also an option to select 'Other' and enter your own Registry sub-folder in the field provided (use quotes for constants or a variable name).
1.24	If you selected an INIFile then you can set the INI file which will contain the status of the DontShowThisAgain for your messages. It was previously set to 'CSMesBox.ini', so existing programs should retain this setting. Appame.ini will be the name of your application file, or you can use the existing default or the win.ini file. There is also an option to select 'Other' and enter your own ini file in the field provided (use quotes for constants or a variable name). You can set the INI Section which will contain the status of the DontShowThisAgain for your messages. It was previously set to 'CS_Messages', so existing programs should retain this setting. Application will be the name of your application file, or you can use the existing default or the command that was used to start the application (This is useful for DLLs used with different EXEs so that you can retain different settings for the different EXEs). There is also an option to select 'Other' and enter your own section name in the field provided (use quotes for constants or a variable name).
1.25	You can enter a HotKey to create a GPF if the Message window is open. This is particularly useful when you have a infinite loop with a stop in it, or you want to debug using GPF Reporter.
1.26	If this is a Multi-DLL application, then check the 'This is part of a Multi-DLL Application' check box. You'll still need to select one of the objects on the 'Message Details' tab if this is not the data DLL.
1.27	If this is a Multi-DLL application and you want to define the Capesoft MessageBox code in this DLL and export it to the other DLLs and EXEs (i.e. this is the data DLL), then check the 'Export Capesoft MessageBox data defined in this DLL'. If you've checked this, then you'll need to fill in all the relevant settings (1.7 - 1.26).
1.28	If you are going to require translation, then go to the 'Translation' tab and check the 'Use a Translation File' check box on.
1.29	If you would like the default language to be a language other than English, then you can enter an Initial Translation File. This should include the path() if the file is not in your windows directory.

2. Local Message Control Template

You need to add this template to the window which you will use for the message box. You will need to create a window procedure. (Details) Once you've created the window, you can add the local Control template.

2.1	In the application window, select your message box window procedure and click the 'Properties' button.
2.2	In the 'Procedure Properties' window, click the 'Window' button.
2.3	Click the 'Control Template' item in the 'Populate' menu.
2.4	Select the 'CSMesBox_MessageBoxControl - Capesoft MessageBox Controls' template, and click on the 'Select' button.
2.5	To edit the control properties, quit and save from the window editor and click the 'Extensions' button on the Procedure Properties window.
2.6	Select the 'Capesoft MessageBox Controls' template and change to the 'Appearance' tab to edit the following:
2.7	You can check the 'Make Buttons Flat' for flat buttons on the message window.
2.8	You can check the 'Transparent Strings' to make the message text (DontShowThisAgain checkbox, Timer notifier and the Hyperlink string - where used) transparent. This is useful if you are applying Wall paper to the window.
	You can check the 'Transparent Buttons' to make the message buttons transparent. This is useful if you are applying Wall paper to the window, although transparent buttons are not supported by manifest files in Windows XP.
2.9	You can check the 'Centralize the text on the window' check box in order to center the message text (other wise the text is left justified).
2.10	On the Icons Tab: Default Icon: You may enter a default icon for the messages that don't have icons. If you are using ClarioNET and you would like to make use of icons in your message windows, then you need to enter a default icon. This will ensure that message()s without icons have the default icon assigned to them. You cannot use an equate for a default icon when using ClarioNET and WebBuilder as the equates are not supported by ClarioNET and WebBuilder. You can enter Default icons for the buttons as well. Use the fields in the Default Button Icons group to stipulate the icons for each button equate.
2.11	On the 'Features Tab': If you would like to maintain the status of the GlobalRequest and GlobalResponse variables (on by default), then you can check the 'Preserve GlobalResponse and GlobalRequest' checkbox on the Advanced tab.   The diagram below shows the ABC ErrorClass name (in the global properties) on the left and the field where you should fill this in in the MessageBox control template on the right. The procedure name is only available in ABC applications.
2.12	Clarion 5.5 (and higher) users only. If you would like to maintain the Procedure name in your GlobalErrors class then you need to check the 'Maintain the Procedure name in the ErrorClass' checked. Checking this checkbox will ensure that the procedure name, from which the message/stop/halt was called, remains the procedure name in the ErrorClass. Alternatively, the name of your MessageBox window will be the name that appears in the procedure name of the ErrorClass. If you checked this checkbox then you need to enter the correct name in the 'Global Error Class name' field. The default is 'GlobalErrors', which is what is normally used. If you have a different name for your global ErrorClass (see on the 'Global Objects' tab in your 'Global Properties') then you need to match that name here. Note: Checking this will also mean that the FromProcedure property is set with the procedure that is currently active. This means that you will be able to log the procedure name from where the Message() command was called. If you would like to display the procedure and application name that called the Message() function, then you can check the relevant checkboxes. This will place the Procedure and/or application name in square brackets in the title bar.
2.13	If you would like to display the calling Application name, then check the 'Display the Application name calling the message' checkbox. This useful in a Multi-DLL application (or Multi-EXE), also so that the message is automatically identified with your application.
2.14	HyperActive users only. If you would like to be able to mail your message as a support facility, then you can set this up on the 'Features' tab. (more details)
2.15	Click 'OK' a couple of times to return to the Application window.

3. Local Stop Extension Template

You need to add this template to the procedure, which you will use for the stop function. You will need to create a source procedure. (Details) Once you've created the procedure, you can add the local extension template.

3.1	In the application window, select your Stop source procedure and click the 'Properties' button.
3.2	In the 'Procedure Properties' window, click the 'Extensions' button.
3.3	Click the 'Insert' button on the 'Extension and Control Templates' window.
3.4	Select the 'CSMesBox_ActivateStop - Capesoft Stop' template, and click on the 'Select' button.
3.5	Click 'OK' a couple of times to return to the Application window.

There's nothing to be done in Capesoft MessageBox's Local Stop Extension Template. Remember that the Stop command will use the Message window that you've defined above, so the same settings that will be applied to the stop as to the message window.

4. Local Halt Extension Template

You need to add this template to the procedure, which you will use for the halt function. You will need to create a source procedure. (Details) Once you've created the procedure, you can add the local extension template.

4.1	In the application window, select your Halt source procedure and click the 'Properties' button.
4.2	In the 'Procedure Properties' window, click the 'Extensions' button.
4.3	Click the 'Insert' button on the 'Extension and Control Templates' window.
4.4	Select the 'CSMesBox_ActivateHalt - Capesoft Halt' template, and click on the 'Select' button.
4.5	Click 'OK' a couple of times to return to the Application window.

There's nothing to be done in Capesoft MessageBox's Local Halt Extension Template. Remember that the Halt command will use the Message window that you've defined above, so the same settings that will be applied to the Halt as to the message window.

5. The Set Features Code Template

5.1.1.	The 'Active' check box will activate the 'DontShowThisAgain' check box feature.
5.1.2.	The 'Value' field sets the length of the Timeout for the message. The time out value is in One Hundredths of a second. So for an 8 second time-out, set the value to 800. You can also enter the name of a variable.
5.1.3.	The 'File:' field indicates the wavfile to be played when the next message is opened. You must use quotes for a string, alternatively you can use a variable.
5.1.4.	The 'Enable' check box will enable message logging. You must not have disabled this feature in the Global Extension Template.
5.1.5.	The 'x:' field entry is used to set the amount of messages that must be skipped.
5.2.	The 'Remember' check box is used to set the Static attribute for the feature. The SkipNext feature is by nature a static feature, so it has no Remember check box. If you set the Static Attribute on in the global extension
5.3.	'Clear checkbox' will place code to clear both the static and the active properties.

If you don't require a property to be changed then leave all the fields unaltered. Thus in this template you will be able to set all or some of the features.

6. The ImportCSMessageBox Utility Template

This template utility is used to import a standard set of Message, Stop and Halt functions to your application. These functions can then be modified (or used as is) to suite your needs.

 

General Info

Adding a Blank Window Procedure
Importing the CapeSoft Message Logging File
Adding a Blank Source Procedure
Adding derived code into your MessageBox object

1. Adding a Blank Window Procedure for the Message Function

You should first consider using the Utility Template to perform this function.

1.1	In the Application Tree window, select the 'New' item from the 'Procedure' menu.
1.2	In the window that appears enter a name for your window (like MyMessageBox) and click the OK button.
1.3	In the 'Select Procedure Type' window that appears, select the 'Window - Generic Window Handler' and click the Select button.
1.4	Click the 'Window' button in the Procedure MyMessageBox Properties screen that appears.
1.5	Select the 'Window' option in the list that appears (the object will do all the fancies - so the bare minimum is all we need) and then click OK.
1.6	You don't need to do anything in the window that appears, but it is advisable that you set the Font to the Font you require. You can also add a wallpaper to the background of the window. If you add wall paper, then it is advisable that you check the 'Transparent Strings' check box on in the MessageBox Local Control Template that you will add just now. You can quit the window editor, as the template and objects will do the rest.

 

1.6	In the Prototype field enter the following prototype (with parameters): (STRING MessageTxt,<STRING HeadingTxt>,<STRING IconSent>,<STRING ButtonsPar>,UNSIGNED Defaults=0,BOOL StylePar=FALSE),UNSIGNED,PROC It is essential that this prototype is correct.
1.7	In the Parameters field, enter the same string for the parameters (leave the return definition off). For example: (STRING MessageTxt,<STRING HeadingTxt>,<STRING IconSent>,<STRING ButtonsPar>,UNSIGNED Defaults=0,BOOL StylePar=FALSE)
1.8	Check the 'Declare Globally' checkbox.
1.9	Enter a variable in the 'Return Value' field. This should be a variable of type 'UNSIGNED'.
1.10	Click the OK Button to exit the window.

You'll need to add the Local Message Extension Template to this procedure.

2. Importing the CapeSoft Message Logging File into your Dictionary

1.1	If you're in the Application editor, then quit it and from the File menu, select the Open item. Select your dictionary in the file dialog box (you will probably need to change the 'Files of type' drop list to 'Dictionary (*.dct)') and click the 'Open' button.
1.2	In the dictionary editor, click the 'Import Text' from the File menu.
1.3	Select the MessageBox.txd file that is found in the clarionx\3rdparty\libsrc directory.

3. Adding a Blank Source Procedure for the Stop and Halt Functions

You should first consider using the Utility Template to perform this function.

1.1	In the Application Tree window, select the 'New' item from the 'Procedure' menu.
1.2	In the window that appears enter a name for your window (like MyStop or MyHalt) and click the OK button.
1.3	In the 'Select Procedure Type' window that appears, select the 'Source - Source Procedure' and click the Select button.

 

1.4.1	In the Prototype field enter the following prototype (for the Stop function): (<string StopText>) It is essential that this prototype is correct.
1.4.2	In the Prototype field enter the following prototype (for the Halt function): (UNSIGNED Level=0,<STRING HaltText>) It is essential that this prototype is correct.
1.5.1	In the Parameters field (for the Stop function), enter a parameter for each field in the prototype (i.e. there must be 1 parameter). For example: (<string StopText>)
1.5.2	In the Parameters field (for the Halt function), enter a parameter for each field in the prototype (i.e. there must be 2 parameters). For example: (UNSIGNED Level=0,<STRING HaltText>)
1.6	Check the 'Declare Globally' checkbox.
1.7	Click the OK Button to exit the window.

You'll need to add the Local Extension Template to this procedure. (StopDetails or HaltDetails)

4. Adding derived code into your MessageBox object

It is really useful to be able to add your own code to some of the MessageBox objects. You can derive these locally (i.e. for this application only), by going to the Global Embeds and selecting the Capesoft MessageBox | ThisMessageBox and the name of the method that you want to derive as follows (where the Init method has been derived):

The above embed point is really useful for setting variables and properties, before initialising MessageBox. In each method you will find 3 (or perhaps 4) embed points: a Data, Before the Parent Call and After the Parent call embed point. If the template generates code after or before the parent call, then there will be an extra embed point to enable you to place code on either side of the parent call as well as on either side of the template generated code.

International Language Support

In order to activate the Translation features, you need to check the 'Use a Translation File' check box on in the Global Extension Template (on the Translation tab).

1. Translating the MessageBox default text

1.1	You can start with a default translation file if you don't want to start your program with the default in English. You can do this in the global extension (in your EXE if this is a multi-DLL project).
1.2	If you are supporting multiple languages then you can change the language at run-time using the TranslationFile property. You should have one translation file for each language that your program will use. For example: case Selected_Language of 'English'   ThisMessageBox.TranslationFile = path() & '\English.trn' of 'Brazilian Portuguese'   ThisMessageBox.TranslationFile = path() & '\Brazil.trn' of 'Spanish'   ThisMessageBox.TranslationFile = path() & '\Spanish.trn' else   if FileDialog('Select Translation File',ThisMessageBox.|           TranslationFile,'Translation Files|*.trn|All Files|*.*',16) . end
1.3	When you run your program and call a message/stop/halt, the translation file will be created (if it is non-existent) as an ini-type file. There will be a section for the button text and one for miscellaneous other text as follows: [MessageBox_Buttons] Button:OK=OK Button:Yes=&Yes Button:No=&No Button:Abort=&Abort Button:Retry=&Retry Button:Ignore=&Ignore Button:Cancel=Cancel Button:Help=&Help [MessageBox_Text] StopHeader=Stop StopDefault=Exit? HaltHeader=Halt TimeOutPrompt=Time Out: DontShowThisAgain=Don't Show This Again LogTimer=Timer
1.4	Once the entries are placed in the ini file, you will need to edit these with a text editor. Example: Button:Cancel=Cancel would appear in the text file as the default text for the Cancel button. To change the text to Portuguese edit as follows: Button:Cancel=Cancelam

2. Setting and Changing the MessageBox language file to use

You can set the initial language file (if you require an initial language other than English) in the Global Extension Template.

If you would like to change the language at some stage during the program, you simply need to change the TranslationFile property (see 1.2 immediately above). Of course, you must be sure that the translation file is in the path that is specified by the TranslationFile property, or else the message box buttons and default text will appear in English.

There is an example application of the Translation File usage.

3. Translating your messagebox text at runtime

For this you will need your own method of translation (the one that you use for your application). To add translation support for Message Headings, text and text buttons - you'll need to add the following code in the ds_Message procedure. Here's the embed point:




Here's an example of the code you would use:

LMBD:HeadingText = TranslateFunction(LMBD:HeadingText)
LMBD:MessageText = TranslateFunction(LMBD:MessageText)
if not numeric(LMBD:Buttons)
  LMBD:Buttons = TranslateFunction(LMBD:Buttons)
end

Relationship with other products

ClarioNET support
HyperActive support
WebBuilder Support
UBeaut support
Other Products

ClarioNET support

MessageBox supports ClarioNET with the following limitations:

• TimeOuts for the window do not work, as these are based on EVENT:Timer which is not recognised by the ClarioNET client.
• Icons must be files and not icon equates (you cannot use ICON:Exclamation, ICON:Hand, etc). If you require the standard messaging icons you will need to make icon files for them (or make use of the ones provided with MessageBox in the clarion\3rdparty\image directory).
• The Image that is used on the window cannot be hidden at runtime, so you can either make the image have a default icon (if no icon is passed to it) or hide the image (set in the ClarioNET local extension template) so that no icons may be used with your message() functions.
• ClarioNET does not support prompt paragraphing. This means that all text will stream into one sentence, although the text will be wrapped automatically to fit the message window.
• ClarioNET cannot play a sound on the client, and so MessageBox's playsound feature will not be supported in ClarioNET applications.
• ClarioNET does not support more than 511 characters in a prompt control. This means that your MessageBox text is restricted to 511 characters.

Besides these limitations, the rest of the MessageBox functionality will be unaltered by the addition of ClarioNET.

Steps to implementing ClarioNET support:

• In the MessageBox Global Extension template, on the Basic tab, you need to check the 'Enable ClarioNET support'.
• In the MessageBox local Extension template on your Message() window, it would be advisable to set a default icon. This is incase you have messages that do not have an icon parameter, as the image cannot be hidden at runtime.
• For handcoders: You need to set the ThisMessageBox.WebSupportHere property in order for the built-in ClarioNET support to be activated.
  

HyperActive support

The best way to make your message()s HyperActive is to set the HyperLink property so that the HyperLink will appear on the MessageBox. If you add you own HyperActive control to the MessageBox window, you will need to position and size it upon receipt of an EVENT:OpenWindow in your own Message() procedure.

WebBuilder support

MessageBox supports WebBuilder with the following limitations:

• TimeOuts for the window do not work.
• Icons must be files and not icon equates (you cannot use ICON:Exclamation, ICON:Hand, etc). If you require the standard messaging icons you will need to make icon files for them.
• WebBuilder does not support prompt paragraphing. This means that all text will stream into one sentence, although the text will be wrapped automatically to fit the message window.
• WebBuilder cannot play a sound on the client, and so MessageBox's playsound feature will not be supported in ClarioNET applications.
• WebBuilder does not support the DontShowThisAgain checkbox and the DontShowWindow feature. These two features cause a program GPF when attempting to close the message() procedure before the window is opened.
• WebBuilder does not support icons on buttons.

Besides these limitations, the rest of the MessageBox functionality will be unaltered by the addition of WebBuilder. You need to check the 'Enable WebBuilder support' on the MessageBox global extension template.

Steps to implementing WebBuilder support:

• In the MessageBox Global Extension template, on the Basic tab, you need to check the 'Enable WebBuilder support'.
• In the MessageBox local Extension template on your Message() window, it would be advisable to set a default icon. This is incase you have messages that do not have an icon parameter, as the image cannot be hidden at runtime.
• For handcoders: You need to set the ThisMessageBox.WebSupportHere property in order for the built-in WebBuilder support to be activated.
  

UBeaut support

If you have a thread manager (e.g. UBeaut) installed, then by default only one copy of your message window can run. So if you happen to have a message window open and then call it from another thread, it will return immediately. This can have tragic results if the user's being asked to confirm some major action.

You will need to disable your thread manager on your MessageBox window. If you are unsure as to how to do this, you will need to contact your Thread manager supplier.

Other Products

Most other 3rdparty products will be completely supported by MessageBox. MessageBox has been tested with all of Capesoft's products and numerous other 3rdparty products. For queries on specific other 3rdparty products please contact our support division.

Frequently Asked Questions

My app seems to hang when a Message() appears. What's wrong?

I'm getting Compile Errors

	Logging Problems
1.1	If I get an error in my logfile, it GPFs without warning when I log a message. How do I inform my users of this?
1.2	I am having a problem with logging. Nothing is being logged to my logfile. What could I be doing wrong?
1.3	I'm trying to use the logging feature in my Message/stop/halt functions but it GPFs when the window closes.
1.4	If I set my MessageLog file to Current/DataDir(Messagebox.log) I can't find it.
	Logging How Tos...
2.1	How do I add information to the log about where the message box was invoked from(i.e. the procedure that called it)?
2.2	I want to just log all/some of the Clarion Messages without displaying them. How do I do this?
2.3	How do I log extra details to my log file?
2.4	I use Secwin (or another Security template) with this app. How do I get the user name into the MessageBox user name field?
2.5	I only want to log messages, without logging stops as well. Can I do this?
2.6	I only want to log system messages without logging other messages. How do I do this?
2.7	My users reboot the computer when a MessageBox appears. How can I log this?
	Compiling Issues
	Features Issues
4.1	I'm trying to use the Timeout, but it doesn't work.
4.2	I want other text on my message box buttons than the standard OK/Yes/No/Abort/Retry/Ignore/Cancel/Help text. Is this possible?
4.3	Can I put Icons on the buttons?
4.4	How do I use variables in my MessageBox when I want to use the 'DontShowThisAgain' feature?
4.5	I am trying to use the Hyperlinked email message, but it doesn't seem to work.
4.6	I want to change the text on a message that is generated by Clarion (or a 3rdparty DLL). Is this possible?
4.7.	I would like to alter the parameters that are passed to the Message window (Text, buttons and the like).
4.8.	I'm getting strangely formatted messages with vertical bars in them.
	General Issues
5.1	I'm trying to use the LOCALE command to set the default button text, but it does not affect my message() buttons.
5.2	When I issue a stop and/or message command the program closes immediately without warning. If I use the Clarion stop and/or message then it works.
5.3	I can't get rid of the Message, Stop and Halt TODO procedures in my application
5.4	I'm using messagebox in a couple of my programs which are running locally without problems, but not so over a Network.
5.5	I'm getting buttons with raised text on my MessageBox buttons occasionally. These are buttons with longer-than-average text length. How can I rectify this?
5.6	I have a legacy single-EXE application which GPFs if I use the Capesoft MessageBox with Features class.
5.7	Is there a way to default the button icons for the standard buttons instead of sending them in each call to the message procedure?
5.8	Is it possible to change the font, font size or the font type (bold, italic, etc) of the text on the message box?
5.9	My Message window displays the minimize, restore, and close buttons in the caption bar. How do I get rid of these?
5.10	I want to remove MessageBox from my application. How do I do this?
5.11	My app seems to hang when a Message() appears. What's wrong?
5.12	One specific Message() call GPFs my app when using MessageBox.
5.13	Is it possible to dynamically change the font information for any given message?
5.14	How do I change the size of the buttons on the MessageBox window?
5.15	I want more space on either side of the text on the MessageBox window - it looks too cramped.

1.1	If I get an error in my logfile, it GPFs without warning when I log a message. How do I inform my users of this?
Answer:	The problem is you can't use your message() function to report the error (as it is open already). One solution is to not use the MessageBoxHalt() function and call the halt if you encounter an error in this instance. This will ensure that the user is given some feedback when the program exits (after all - the program is about to GPF in any case).  Thus:       If errorcode() then halt(,'There is a problem with the MessageBox file...') .          !For Legacy     If access:<MessageBoxFile>.Errors.SaveErrorCode then halt(,'There is a problem with the MessageBox file.') . !For ABC - Clarion5 and C55 If you are using Clarion 6 then:     If access:<MessageBoxFile>.Errors.Status.V.SaveErrorCode then halt(,'There is a problem with the MessageBox file.') . !For ABC - Clarion6 You can put this code in the embed point - ThisMessageBox|InsertLog|(4) After the Parent Call and generated code. Alternatively, if you are using the LimitLogFile feature, you must put this check in the ThisMessageBox|LimitLog|(4) Before Generated Code, as the LimitLog method is called before the above embed point is reached.  Note for ABC users: Unfortunately the writers of the ABC classes have deemed it beneficial (for reasons best known to them) to make the Errors class a protected property. You need to remove the PROTECTED attribute of the Errors property and the SaveErrorCode property in the ErrorClass. You can do this in the abfile.inc and the aberror.inc header files.
1.2	I am having a problem with logging. Nothing is being logged to my logfile. What could I be doing wrong?
Answer:	You need to check that you: 1. are in fact using your own stop - check that the 'Functions To Use' options group on the Basic tab of your MessageBox Global Template has either the 'All' Checkbox checked or the 'Stop' checkbox. 2. have selected the 'Capesoft MessageBox with features' object on the Basic tab of your MessageBox Global Template. 3. have not disabled MessageLogging (on the Features tab of your Global MesageBox Template). 4. have either checked the 'Automatically log messages' on the Features tab of your MessageBox global Extension template your you have set the ThisMessageBox.LogMessages = 1 at the beginning of your program. 5. have checked the 'Remember logging' on the Features tab of your MessageBox global template. 6. have all the checkboxes cleared in the Selective logging group on the Features tab of your global template. 7. have specified your file as the logging file on the LogFile tab of your messageBox global template.   if you have checked all these and are still not logging:   8. Do a scan of your source routines for ThisMessageBox.LogMessages = 0 to make sure that the logging is not being turned off.   if you have checked this and are still not logging:   9. Place a trial stop in your code and set the ThisMessageBox.LogMessages = 1 immediately before this. If this is the last step and you can see the stop being logged, then your static property has not been set for logging, or has been cleared at some point.
1.3	I'm trying to use the logging feature in my Message/stop/halt functions but it GPFs when the window closes.
Answer:	You've probably checked the 'Disable Logging' check box in the Global Extension Template, but you're setting the logging feature flag. You need to uncheck this 'Disable Logging' check box in order to allow you to use and activate the Logging feature.
1.4.	If I set my MessageLog file to Current/DataDir(Messagebox.log) I can't find it.
Answer:	The ASCII message file name is set in the Init method of the MessageBox class. If you're only setting your path after the call to the ThisMessageBox.Init, then the logfile will be placed in whatever path your application started in. Example:   GlobalErrors.Init(GlobalErrorStatus)   INIMgr.Init('.\msgbox.INI', NVD_INI)                     ! Configure INIManager to use INI file   DctInit !You need to set your datapath here                  !CapeSoft MessageBox init code   ThisMessageBox.init(1,1)                  !End of CapeSoft MessageBox init code   SystemParametersInfo (38, 0, lCurrentFDSetting, 0)       ! Configure frame dragging
2.1	How do I add information to the log about where the message box was invoked from (i.e. the procedure that called it)?
Answer:	You can do this in C5.5 or later and is only available in ABC applications. 1. In the MessageBox procedure - extensions - Capesoft MessageBox Controls template, go to the 'Advanced' tab and check the 'Maintain the Procedure name in the Error Class'. 2. If you are using a table in your dictionary to log the messages, then make sure that you have a field in your MessageBox logfile to store the Procedure name in it (setup in the MessageBox Global Extension template - in the Logging tab)
2.2	I want to just log all/some of the Clarion Messages without displaying them. How do I do this?
Answer:	There's a DontShowWindow Property property in the 'CapeSoft Message Box with features' class, which (if set) will just log the message without displaying it.  This is easy in Clarion5.5 (and above) if you are using ABC methods: 1. Turn off Remember logging in the Messagebox Global Extension Template. 2. You need to insert the following code in the embed before the GlobalObjects | Abc Objects | Error Manager | Msg PROCEDURE | CODE | Parent Call. To get there click the Global button, and then the Embed button and find the embed point in the Embed tree. case ID                           of Msg:UpdateIllegal orof Msg:InsertIllegal orof Msg:DeleteIllegal !This will only disregard illegal file change messages (but will log them)   ThisMessageBox.DontShowWindow = 1 end