/ ============================================================================
/
/ User-configurable eMail text dialog
/ ===================================
/ 
/ These notes describe the Report Manager's customisable eMail text dialog.
/ If you want to print these notes, it is best to use the Courier font
/ at 9 point size.
/ 
/ Introduction
/ ------------
/ When the Report Manager is used to send a report via eMail, an accompanying
/ eMail message is sent to the recipient. The textual contents of this eMail
/ message are automatically generated by the Report Manager, and cannot be
/ changed by the user. However, it is possible to configure the Report Manager
/ to allow the user to choose from a number of optional text messages that will
/ be appended to the mail message.
/ 
/ This works by presenting an extra dialog to the user when they choose to send
/ a report via eMail. From this dialog, the user can select the various
/ additional text messages to be appended to the mail message.
/ 
/ The contents of the dialog are user-configurable, and are controlled by a text
/ file called "EMAILCFG.TXT", of which more later.
/ 
/ The dialog box will contain a number of buttons, which should be arranged into
/ groups of conceptually related buttons. There are two kinds of buttons:
/ 
/ Check Boxes
/ -----------
/ Check boxes are simple yes/no options. They can be individually selected;
/ the selection of one check box has no effect on any other check box. Use check
/ boxes to choose from a list of text messages where any number of the messages
/ may be selected.
/
/ For example, if you wanted to include a request in the mail message for the
/ types of analysis to be performed, you might use check boxes with options of
/ "Arrhythmia", "ST", "HRV" and "QT".
/ 
/ Radio Buttons
/ -------------
/ Radio buttons should be arranged in groups of two or more. Only one radio
/ button in a group can be selected at once. When a different radio button in a
/ group is clicked, the previously selected one in the same group is deselected.
/ 
/ Radio buttons are used to choose exactly one option from a list of
/ mutually-exclusive options.
/
/ For example, if you wanted the user to enter a priority for analyses requested
/ the mail message, you could use radio buttons with options of "Urgent", "Normal"
/ and "Low priority".
/ 
/ Groups
/ ------
/ A collection of related buttons is called a "group". The buttons are drawn
/ physically adjacent to one another in a column.
/ 
/ Each group of buttons has it's own title. When a group appears in the
/ dialog, it will have a rectangle drawn around it to indicate that it is a
/ group, and its title will be drawn along the top of that bounding rectangle.
/ 
/ All the buttons in a group must be the same kind (radio buttons or check
/ boxes). You cannot mix radio buttons with check boxes in a group.
/ 
/ The configuration file, "EMAILCFG.TXT"
/ --------------------------------------
/ The dialog box is configured according to the specification in the file called
/ "EMAILCFG.TXT". This file must be in the same folder as the Report Manager
/ executable (REPVIEW.EXE), otherwise it won't be used.
/ 
/ This file is an ASCII text file, and should only be edited with a text editor
/ such as Windows Notepad - do not use a wordprocessor, unless you explicitly
/ save the file as a "Text Only" file. Otherwise, extra data will be added to
/ the file by the wordprocessor, which will render the file unusable.
/ 
/ File format
/ -----------
/
/ The "EMAILCFG.TXT" file format looks like this:
/
/ <dialog title>
/ --------------------------------------\
/ @CHECKBOXES or @RADIOBUTTONS           \
/ <group title>                           \
/ <selected message>                       \
/ <unselected message>                      \  Repeat
/ <column number>                            \ for each
/ ---------------------------\               / group
/ <default selection status>  \  Repeat     /
/ <screen prompt text>         > for each  /
/ <mail message text>         /  button   /
/ ---------------------------/           /
/ @END                                  /
/ -------------------------------------/
/ 
/ This is properly defined by the following grammar:
/
/ complete-configuration-file:
/       dialog-title group-list
/
/ group-list:
/       group-block
/       group-list group-block
/ 
/ group-block:
/       '@CHECKBOXES'   group-body '@END'
/       '@RADIOBUTTONS' group-body '@END'
/
/ group-body:
/       group-title selected-message unselected-message column-number button-list
/
/ button-list:
/       button-block
/       button-list button-block
/
/ button-block:
/       default-selection-status screen-prompt-text mail-message-text
/
/ More details about the file format
/ ----------------------------------
/ 
/ <dialog title>
/ --------------
/ The first line is used as the title for the dialog box. The title appears in
/ the title-bar along the top of the dialog.
/ 
/ [group]
/ -------
/ The remainder of the file contains specifications for the groups of buttons to
/ be displayed in the dialog. The first line for each group specifies whether it
/ is a group of radio buttons or check boxes.
/ 
/ For radio buttons, the line should be "@RADIOBUTTONS" (without quotes).
/ For check boxes,   the line should be "@CHECKBOXES"   (without quotes).
/ 
/ <group title>
/ -------------
/ This line of text will be used as the title for the group.
/ 
/ <selected message>
/ ------------------
/ This is a line of text that will be added to the mail message if any of the
/ buttons in this group are selected by the user when the "OK" button is pressed
/ in the dialog, and at least one of those buttons produces text for the mail
/ message. If no button is selected (possible only for check box groups), or
/ none of the selected buttons produce text in the mail message, the <unselected
/ message> will be added to the mail message instead.
/ 
/ Note that any button that is selected will produce text in the mail message,
/ unless the <mail message text> (described below) is set to "<NONE>", so
/ normally having a button selected will result in the <selected message> being
/ added to the mail message.
/ 
/ You can embed carriage-return/line-feeds in the message by using "\n" (without
/ the quotes). For example, "One\nTwo\nThree" would come out on three lines.
/
/ NOTE: By default, no newline will be automatically output after the <selected
/ message>, so you would normally want to put a "\n" at the end of the
/ message. However, you may sometimes want to have several items on the same
/ row, in which case you would put a space at the end instead.
/ 
/ You can specify that you don't want this group to produce a <selected message>
/ in the mail message by specifying "<NONE>" (without the quotes).
/ 
/ <unselected message>
/ --------------------
/ This is a line of text that will be added to the mail message if none of the
/ buttons in this group are selected by the user when the "OK" button is pressed
/ in the dialog, or none of the selected buttons produce text for the mail
/ message. Otherwise, the <selected message> will be added to the mail message
/ instead.
/ 
/ The only way a selected button won't produce text for the mail message is if
/ its <mail message text> is set to "<NONE"> (see below).
/ 
/ You can embed carriage-return/line-feeds in the message by using "\n" (without
/ the quotes). For example, "One\nTwo\nThree" would come out on three lines.
/ 
/ NOTE: By default, no newline will be automatically output after the <unselected
/ message>, so you would normally want to put a "\n" at the end of the
/ message. However, you may sometimes want to have several items on the same
/ row, in which case you would put a space at the end instead.
/ 
/ You can specify that you don't want this group to produce an <unselected
/ message> in the mail message by specifying "<NONE>" (without the quotes).
/ 
/ <column number>
/ ---------------
/ This is a number, greater than or equal to one, that defines the column in
/ which the group should be displayed. '1' is the first column.
/ 
/ If you specify '1' for all the groups, they will all appear in the same
/ column. This is fine for most uses, but if you are using a number of groups,
/ the dialog box will tend to become tall and thin, and eventually it won't fit
/ on the screen. To circumvent this problem, you can specify column numbers of
/ '2' or higher to move the group into a different column. You may have to try
/ various combinations to achieve the best dialog layout.
/ 
/ Note that you do not specify a row number. Row numbers are assigned
/ automatically, in the order that the groups are defined in the configuration
/ file. If you want to move a group to a higher row, you simply move its group
/ block up in the configuration file.
/ 
/ If you miss out any columns (for example, you specify groups with columns of 1
/ and 3, but not 2), a small additional horizontal gap will appear between the
/ groups that surround the missing column.
/ 
/ <default selection status>
/ --------------------------
/ This is a number, "0" or "1" (without quotes) that defines whether the button
/ will be selected or unselected each time the dialog is displayed. Specify "0"
/ to have the button unselected, or "1" to have it selected.
/ 
/ Note that radio button groups should, according to Windows convention, have
/ exactly one button selected. It is possible to select zero, or more than one
/ by default, but as soon as the user clicks on a radio button in the group,
/ only that button will be selected.
/ 
/ <screen prompt text>
/ --------------------
/ This is the text that will appear next to the button in the dialog box. You
/ *cannot* embed "\n" characters or tabs, or specify "<NONE>" for this text.
/ 
/ <mail message text>
/ -------------------
/ This is the text that will be added to the mail message if the button is
/ selected at the time that the "OK" button is pressed in the dialog.
/ 
/ You can embed carriage-return/line-feeds in the message by using "\n" (without
/ the quotes. For example, "One\nTwo\nThree" would come out on three lines.
/ 
/ NOTE: By default, no newline will be automatically output after the <mail
/ message text>, so you would normally want to put a "\n" at the end of the
/ message. However, you may sometimes want to have several items on the same
/ row, in which case you would put a space at the end instead.
/
/ You can specify that no text should be added to the mail message when this
/ button is selected by specifying "<NONE>" (without the quotes).
/ 
/ You can put tabs into the <mail message text> to align things.
/ 
/ Comments and blank lines
/ ------------------------
/ You can use comment lines and blank lines in the configuration file:
/ 
/ * Any blank line is ignored.
/ * Any line beginning with '/' is a comment, and is ignored.
/ 
/ You can freely put blank lines and comments anywhere in the file, but you
/ cannot put a comment partway along a line.
/ 
/ Tab order
/ ---------
/ The "tab order" is the order in which the groups are visited in the dialog,
/ when the user presses the tab key. The tab order is the same as the order in
/ which the groups are defined in the configuration file.
/ 
/ Dialog box too big
/ ------------------
/ It is possible to make the dialog box too big to fit on the screen, by using
/ very long screen prompts for the buttons, or lots of buttons and groups. If
/ this happens, the "OK" and "Cancel" buttons may not be accessible. In this
/ event, remember that pressing the "Esc" key has the same effect as clicking on
/ "Cancel". So you can at least cancel the dialog box, but once it is too big,
/ you will need to fix it by changing the configuration file.
/
/ =============================================================================
/
/ Example configuration file
/ --------------------------
/ An example configuration file follows. This configuration file is intended to
/ be used on a satellite PC running the Report Manager rather than on the
/ analyser itself. A more complex example can be found in the file "EMAILCFG.SAM".
/
/ Firstly, here is the example in the form of comments:

/ Dialog title:         Analysis Request Options

/ First group:          @RADIOBUTTONS
/ Group title:          Analysis Priority
/ Selected message:     Priority:
/ Unselected message:   <NONE>
/ Column number:        1
/ Button 1...
/ Selection status:     0
/ Screen prompt:        Urgent
/ Mail message text:      Urgent
/ Button 2...
/ Selection status:     1
/ Screen prompt:        Normal
/ Mail message text:      Normal
/ Button 3...
/ Selection status:     0
/ Screen prompt:        Low
/ Mail message text:      Low
/ End of group:         @END

/ Next group:           @CHECKBOXES
/ Group title:          Required Analysis
/ Selected message:     Required Analysis:
/ Unselected message:   No analysis is required!\n
/ Column number:        2
/ Button 1...
/ Selection status:     1
/ Screen prompt:        Arrhythmia
/ Mail nessage text:      Arrhythmia
/ Button 2...
/ Selection status:     0
/ Screen prompt:        ST
/ Mail nessage text:      ST
/ Button 3...
/ Selection status:     0
/ Screen prompt:        HRV
/ Mail nessage text:      HRV
/ Button 4...
/ Selection status:     0
/ Screen prompt:        QT
/ Mail nessage text:      QT
/ End of group:         @END

/ Now here is the real example without the comments:

/ Dialog title:

Analysis Request Options

/ First group is a set of radio buttons for selecting analysis priority.

@RADIOBUTTONS
Analysis Priority
Priority:
<NONE>
1

0
Urgent
  Urgent

1
Normal
  Normal

0
Low
  Low

@END

/ Next group is a set of checkboxes for requesting types of analysis:

@CHECKBOXES
Required Analysis
Required Analysis:
No analysis is required!\n
2

1
Arrhythmia
  Arrhythmia

0
ST
  ST

0
HRV
  HRV

0
QT
  QT

@END

/ End of file.
