Dialogue Boxes

Summary

This chapter details the construction, types, functions and uses of 3B2 dialogue boxes.

1 Introduction

A dialogue box appears on the screen to present information or request input. Typically, dialogue boxes are temporary; they disappear once the user has entered the requested information and clicked OK or Cancel. In addition to describing Arbortext APP's standard dialogue boxes, this chapter will demonstrate how users can create their own dialogue boxes to specific requirements.

Dialogue boxes in Arbortext APP are extremely extensive and the information provided to understand them ranges from basic to very complex. Consequently, this chapter is divided into three sections:

The Intermediate Section contains supplementary information to extend the range of dialogue box features.

The Advanced Section is for experienced Arbortext APP users who have more complex requirements for dialogue box creation.

2 Basic Section

2.1	Basic dialogue box components

All dialogue boxes are defined by numbered strings or within a documents stream. Dialogue box content items can be defined either in internal Arbortext APP streams or external strings files and are invoked using macros, which either call the internal stream or the string number assigned by the external string file.

More information on Arbortext APP string files, string numbers and scripts can be found in the 3B2 Scripting chapter.

The main macros used for creating dialogue boxes are:

wdb

twdb

The twdb macro simplifies dialogue box creation. It uses the contents of a stream to create a dialogue box without having to use defstr and addstr to define and add strings. For more information see twdb.

It is recommended that you read the basics of this chapter before commencing development of your first dialogue box.

The basic elements of a dialogue box are:

edit fields

buttons

the use of variables and exit buttons

The above elements will be described throughout this section.

2.2	Basic dialogue box script example

The internal script stream below includes all the basics required for a simple dialogue box:

^fname=	1
^columns=2#	2
^filepath=getvar 31086,"var"	3
defstr 350,"J Doe\|@Jane Doe\n"	4
addstr 350,"J Smith\|@John Smith\n"	5
defstr 351,"\|Welcome to dialogue boxes\n"	6
addstr 351,"\n"addstr 351,"\n"	7
addstr 351,"Do you require the date }^date %b\n"	8
addstr 351,"-\n"addstr 351,"Your name }^fname %1..30s!352!\n"	9
addstr 351,"Load file }^filepath %1..999;20s!?11*.txt!\n"	10
addstr 351,"Number of columns }^columns %1..4r[1] [2] [3] [4]\n"	11
addstr 351,"\n"	12
addstr 351,"This version of 3B2 is }^var %1.30t\n"	13
addstr 351,"-\n"addstr 351,"\|%2..1e[OK] [Cancel]\n"	14
wdb 351^wdb--	15
?=0,^wdb trun 0	16

1-3: At the start of the script, the variables, used in the main dialogue box, are cleared first so that any previous information that may have been passed to them is deleted. However, the columns variable will be set with a value of 2. The button number 2, where this variable is used in the dialogue box, will be pressed by default.

4: The getvar 31086 is being passed to the variable var. This variable is used later on in the script. The getvar 31086 obtains the current version of Arbortext APP. For more information on getvars see the System Variables chapter and getvar.

5-6: These two script lines that refer to string 350 are codes for the pull down menu and must appear prior to being called for. The text before the @ symbol is what will appear in the pull down menu. The @ symbols means @ insert to Arbortext APP and will insert the text that follows it. Menus need to be assigned to a different string number.

7: This line in the script always begins with defines the string hence 'defstr'. The text is the title of the dialogue box dialogue box. By default, the text is aligned to the left (other alignment methods are discussed later, for example || is the syntax to align text to the right). The \n syntax signifies the start of a new line.

8: Inserts a new line.

9: Inserts a new line.

10: The %b syntax is the coding used to build a tick box. If the box is ticked then a value of 1 is passed to the variable ^date, if not it will be 0. The variable will be tested later for its value. } is another alignment point. Arbortext APP looks for other } in the script and will align with them accordingly.

11: Inserts a new line with a rule (-) across the width of the dialogue box.

12: The coding in this line is used to build an entry field. The coding %1..30s means that the field requires a minimum of one character to be entered and up to thirty. The content is then passed to the variable ^fname to be used later. The !350! tells Arbortext APP that a menu is attached to this edit field and refers to the menu string previously defined which contains the information.

13: This is another entry field which obtains a filename. The semicolon then the number 20 tells Arbortext APP to just display twenty characters in the box. The !?11! is a built in special menu function that displays a file picker dialogue. The added parameter tells Arbortext APP to look for all .txt files.

14: The coding %1..4r tells Arbortext APP to make four push down buttons and gives each button a value from 1 to 4. If button 1 is pressed then number 1 is passed to the variable and so on.

15: Inserts a new line.

16: This is a non-editable field. The variable which was set earlier in the script using the getvar is used here. This field is for information only.

17: The code for an exit button is %2..1e. The number 2 represents OK or and 1 Cancel. The 'e' tells Arbortext APP that these are exit buttons. The values 1 or 2 are then automatically passed to a variable called ^wdb. If the dialogue box has been exited by enter or Ctrl + A , a 0 is returned.

18: Inserts a new line with a rule (-) across the width of the dialogue box.

19: Draws the dialogue box to the screen.

20: This subtracts 1 from the contents of the variable.

21: Tests if ^wdb is 0. If so stop all scripts with trun 0. It would be 0 if Cancel has been pressed.

The above script will output this dialogue box:

2.3	Dialogue Box Interaction

2.3.1 General edit fields and lists

As described in the previous section, there are many edit fields that can be incorporated into dialogue boxes including:

combo boxes

check boxes

button groups

Lists are one of the fundamental features of a dialogue box. There are many variations such as general picking lists, menu lists and combo box lists. They are all explained further in the Intermediate Section of this chapter but a quick overview is given here. The screenshot of the Paragraph Rules dialogue box below details the different components of a dialogue box:

7.67

Another example of lists is editable field lists. Editable field lists are effectively designed as a combo box but the user can also enter text in the edit field. One example of an editable field list is in the Stream Editor (from version 7.67). For more information see ttagedit:

Treeview lists list structured data hierarchically. If you use Windows, you will be familiar with this view as it is commonplace within the operating system. Users can create their own dialogue boxes in Arbortext APP with this view. Further information on treeview lists can be found in the Intermediate Section. The screenshot below shows a treeview list:

2.3.2 Enter and Tab keys

The Tab , Tab + Shift and Enter keys can be used to interact with a dialogue box as described below:

Key	Description
`Tab` key	Use to move forward through the different components of a dialogue box.
`Tab` + `Shift`	Use to move backwards through the different components of a dialogue box.
`Enter` key	Accepts the dialogue box. (Unless it is specified otherwise in the Interface Options dialogue box under the `Dialogue Boxes ▶` tab by ticking the `Don't exit on Return: □` tickbox. For more information see wdpref).

2.3.3 Selecting text in edit fields

Clicking in an edit field will select all the text that has been entered, unless the 'n' option (see Labelling editable field items section) has been used which does not clear the field when you type. Subsequent clicks enable you to place the cursor at a specific point in the line and dragging the cursor over the characters will select it accordingly. When double clicking in a field, the whole field will be selected.

2.3.4 Cut copy and paste

The cut, copy and paste functions work in edit fields by using the following keys:

Key	Function
`Ctrl X`	Cut
`Ctrl C`	Copy
`Ctrl V`	Paste

With Windows versions of Arbortext APP these functions interact with the Windows clipboard.

2.3.5 Keyboard mode

A keyboard mode has been added to the dialogue box interface options. By default, the cursor Home and End keys do not affect the mouse controls but instead always affect the cursor within the current edit field. The former mode, when the mouse controls can be turned on, is specified in Arbortext APP's Interface Options dialogue box under the Dialogue Boxes ▶ tab by ticking the Simulate Mouse with Keyboard: □ tickbox. For more information see wdpref.

Below is a list of keystrokes that can be used in dialogue boxes:

Key	Function
`Ctrl` + `Left Arrow`	Move cursor back one word (edit box).
`Ctrl` + `Right Arrow`	Move cursor forward one word (edit box).
`Ctrl` + `Shift` + `Left Arrow`	Move and select back one word (edit box).
`Ctrl` + `Shift` + `Right Arrow`	Move and select forward one word (edit box).
`Shift` + `Left Arrow`	Move and select one character back (edit box).
`Shift` + `Right Arrow`	Move and select one character forward (edit box).
`Shift` + `Home`	Move and select to start of line (edit box).
`Shift` + `End`	Move and select to end of line (edit box).
`Shift` + `Down Arrow`	Move and select one line down (list box).
`Shift` + `Up Arrow`	Move and select one line up (list box).
`Shift` + `Page Down`	Move and select one page down (list box).
`Shift` + `Page Up`	Move and select one page up (list box).
`Shift` + `End`	Move and select to end (list box).
`Shift` + `Home`	Move and select to start (list box).

2.3.6 Exiting a dialogue box

The most common way for the user to exit a dialogue box is to click on an exit button, such as OK or Cancel. Exit buttons are the one field type where it is not necessary to include a variable name, since Arbortext APP does this automatically, the following sequence represents exit buttons which will automatically return the values 2 and 1 to the ^wdb variable, which can then be processed like any other variable:

%2..1e OK Cancel

Arbortext APP's standard dialogue box shortcuts can be used to exit a user-defined dialogue box, therefore it is important to understand how the shortcuts return values to the ^wdb variable.

The user can exit a dialogue box by pressing Ctrl + A , pressing Enter in an exit field, a field with the x option appended to the field type or pressing any key if the dialogue box contains a ~ (tilde) character to indicate that any key can be used to exit (see Keyboard exit from a dialogue below). These three methods of accepting a dialogue box always give the ^wdb variable a value of 1.

7.60 Pressing Ctrl + Q or Esc (only after version 7.60) will always return a value of 1 to the ^wdb variable.

A user-defined dialogue box should be constructed so that the %1e field carries out some sort of Cancel or Quit function. There should also be a way of processing ^wdb variables with a value of -1 so that the user can carry on using Arbortext APP's keyboard shortcuts without anything unexpected happening.

2.3.6.1 Keyboard exit from a dialogue box

If there are no edit fields to receive typed characters in a dialogue box, you can allow the user to exit by pressing any key. A value of -1 will be returned to the ^wdb variable. This is done by including the ~ character anywhere in the string (usually at the front) for example:

defstr 390, "~|Dialogue box title\n"

2.3.6.2 Processing the wdb variable

The sample script below defines a simple dialogue box which contains three exit buttons, which will pass values of 3..1 to the ^wdb variable. Clicking on Cancel or pressing Ctrl + Q will return a value of 1. However, when the user presses Ctrl + A (^wdb=-1) the script behaves as if OK has been pressed. The dialogue box is set up to expect a value of ^wdb=3 when OK is pressed, therefore it is best to test specifically for a value of ^wdb=-1. If this is the value, reset ^wdb to have a value of 3.

defstr 390,"Ways of Quitting a Dialogue Box\n-\n"	1
addstr 390,"Tagname1:^string1%1S\n"	2
addstr 390,"Tagname2:^string2%1Sx\n-\n"	3
addstr 390,"%3..1e[OK] [Something else] [CANCEL]"	4
wdb 390	5
?=^wdb,-1	6
^wdb=3	7
^wdb--	8
?0^wdb trun -1	9
^wdb--	10
?0^wdb }Somethingelse	11
^wdb--	12
?0^wdb }OK	13

1-4: Defines dialogue, the first line in the script begins with defining the string using defstr.

5: Invokes dialogue

6-13: After the check for ^wdb=-1 the rest of the script successively decreases the value of ^wdb by 1 and tests it for a value of 0. When ^wdb finally has a value of 0 an action is carried out.

Suppose the user has pressed OK or Ctrl + A . Below is a description of what Arbortext APP would do:

Take 1 away from the value of ^wdb. Is the result 0? If it is, then do something. If it is not, try taking 1 away again:

3-1=2
2-1=1
1-1=0

This saves implimenting a multiple jump sequence.

2.3.7 Dialogue box titles

All dialogue boxes have a title by default, which is a blue bar with white text (colours 155 and 156 respectively as defined in the scol256c.3ad file). When a second dialogue box pops over the top of the current one, the title background will switch to 50% grey (colour 157), until it is reactivated.

The dialogue title is simply the first line of the dialogue box script, up until the first return character. If a separator line is required then it must be defined on a separate line.

The main title has certain criteria. It is not allowed any % item in it. If a percent item is present, then no title will be given to the dialogue box. Also if a '[' bracket is encountered in the title, the dialogue box will be without a title.

If no title is required, a thin blue bar across the top of the box can be obtained by entering two dashes as the characters in the title string.

Starting the dialogue box with a return is the default way to skip any title.

The title is the same width as the dialogue box. It will be formatted in the normal way, so use | and || to centre, or flush the title to the right respectively. Further information on alignment and horizontal rules is described in the Intermediate Section.

2.3.8 Adding macro text to a dialogue box

Arbortext APP dialogue boxes can display the name of the macro used to invoke them. The name of the macro is only shown when the user has opted to show macros inside dialogue boxes using the Interface Options dialogue box under the Show Macros ▶ tab by ticking the In dialogue boxes: □ tickbox. For more information see wdpref. At all other times the name of the macro is not displayed.

The name of a macro (or any other text) can be displayed in a dialogue box by including it between two @ characters. In presenting a consistent interface to the user, it is recommended putting the macro name in either the top left-hand corner or, in more complex dialogue boxes which gather together several macros, next to the edit box of each edit box.

Note that when a dialogue box is defined using defstr and addstr and you want to refer to a trun macro followed by the tag name parameter, you will need to use two sets of double quote marks around the name of the script as shown below:

defstr 999,"@trun ""script""@ |Alignment example\ntest\n"

2.3.9 Using variables in a dialogue box

Dialogue boxes are the interface the user has with your script and therefore the way in which variables are passed information. They are, effectively, an interface for the ^ (^) macro. The variable ^varname that precedes most editable items in a dialogue box as being the equivalent of ^var= in a script.

For more information on variables see the Variables chapter.

2.3.10 Adding editable items to a dialogue box

Editable items in a dialogue box take the form of edit fields, into which a user can choose to enter characters or edit buttons.

Syntax `(SVNNA)`

varname:v `%´ ( par1:n `;´ par2:n? field_type:b ) [ `!´ list_type:b `!´ ]? options:b? [ `?´ help:n `?´ ]?

varname:v

The name of the variable to be given a value. This parameter is not used for field_types d (dummy help) and e (automatically returns value to ^wdb variable).

Forgetting to include a variable name with any other field_type will usually cause 3B2 to crash.

par1:n

n...n	For `field_types` of `a`, `i`, `m`, `q`, `u` and `H`, the lowest and highest acceptable values respectively, separated by .. (two points).
n[...n]	For `field_type s`, `f` and `t` the values returned to the `varname` variable (or, in the case of `e`, to the `^wdb` variable) when the button, or range of buttons, is clicked on.
n...[n,]n	For `field_type s`, `f`, `X` and `t`, the minimum and maximum number of characters that may be entered in the field. A value of 0 as the minimum number of characters means that the field may be left empty by the user. The optional parameter is for scrollable fields, only displaying the last `n` value, but scrolling up to this number of characters.
;n	For `field_type s`, the following values are valid:

;0	Field may be left blank.
;1	Field must be completed with at least 1 character.

par2:n

;n	For `field_type a`, `i`, `m`, `s`, `f` and `t` the number of characters to display in the dialogue box or, for `field_type H`, the width of the horizontal slider in pixels. The following values are valid for `field_types q` and `u`:

;0	horizontal units.
;1	vertical units.
;2	font units.
;3	system units.

For field_type s the following values are used:

;1	allow full stop.
;2	allow ? and *.
;4	allow $
;8	do not allow hyphen.
;16	allow \| (vertical bar).

field_type:b

a	Angle.
i	Integer.
m	Micron. A fixed point number to four decimal places without the point, for example 10,000 X number.
u	Unit of measurement.
q	Unit of measurement, with relative values allowed, for example 1.5h.
l	Similar to i for the purposes of user-defined scripts.
w	Similar to i for the purposes of user-defined scripts.
b/B	Will by default produce a checkbox instead of a pair of buttons. A tick will appear if the value of the variable being used is 1 for b or 0 for B. Any of the following buttons, which are usually Yes/No or On/Off do not appear as buttons but as checkboxes, but need to be specified if `wdpref +3` is selected in 'interface options' and then are still used, (see wdpref. Alternatively, the buttons can be specified in the script line for example: `[Yes] [No]`. When a checkbox is used in a dialogue box the user can either click on the box itself, or on the immediately preceding text. If there are formatting items between the text and the checkbox (i.e. fills), then it may prevent the user from clicking on the text. The `b` & `B` also take an option `o`. When this option is specified enough space is left horizontally for the box, but not for the tick, so you must make sure manually that the tick is allowed for.
r	Radio button.
e	Exit button. A varname is not used with this `field_type`, the value being returned to the `^wdb` variable.
c	Colour box. The variable varname will contain the text definition of the colour.
h	Colour slider.
s	Alphanumeric text string.
f	Alphanumeric text string which does not perform conversion to and from the 3B2 character set on the Mac. On non-Mac systems, this behaves like `field_type s`.
t	This creates a field that will display a string as ordinary text which is not editable by the user, but which can be updated by external procedures or label actions etc. By default the `t` is displayed as ordinary text, without any border etc. and a `num` parameter will normally be needed to specify the width required. The `t` can also take both `o` and `O` options.
s	Valid tag name.
d	Dummy to which help can be attached. A varname is not used with this `field_type` and there are no parameters.
z	Skip field. This is useful for editing an existing strings file to remove unwanted fields. Changing a field_type to z means that the specified field will not be drawn in the dialogue box, but the dialogue box (and any script or program code which refers to it) will behave as if it is still there. Similarly, unwanted dialogue box buttons can be removed from the display by having their text replaced with a full stop.
g	This is used for boxes which have an external procedure to draw them and accept clicks etc.
P	This procedure automatically rescans all variables to see if they have changed and if so, redraws them. Its main use is to enable you to pass the same parameter to a dialogue box more than once and changing one will automatically affect the other. This also works with named variables and so can be used within a script.
Z	This is similar to `P`, but returns 0 automatically, to stop a redraw when the field is changed. This is only useful to override a default procedure attached to every field. Also works with named variables and so can be used in a script.
X	This makes the specified field 'password protected'. It can only be used with fields that the user types in and as the user types they will only see a series of * instead of the actual data they typed.

options:b

x	Exit dialogue box when `Enter` is pressed.
n	Do not clear field when user enters new text.
o	Will cause the `t` (for example) to have a sunken background and so will look more like an editable field, although the background will be in white.
O	Will cause the text to be centred within the width specified.
V	This option is used for verifying fields, see Verifying fields.

Note that O can be used in conjunction with o to produce a text item centred within a box. However, users can not edit it.

list_type:b

Many of 3B2's own dialogue boxes contain links to a menu, which the user enters by clicking a button next to an edit box. The user chooses an item from the menu and is then returned to the dialogue box itself.

Selectors can be added to all field_types except b, B, r, e.

num A menu defined in stuk.3ad, suser.3ad or by defstr or addstr, where nnn is the string number.

The selector types are as follows:

?[colour_opt]

Colour selector.

P	From the colour pallet.
n	Named colour

?0 File names. Gives a list of filenames which optionally match the given wildcard name. Picks up the path from the field if present, along with the name if wild. Fills in the remainder of the path and the wild name from the <parameter string> and then from the default path and/or *.3d. If the options contain ** as part of the wild name then files are shown with their sizes; *** and pages are shown and ***** gives both.

P	From the colour pallet.
n	Named colour
type	The file type extension, as listed under ttagmk for example: `^variable_name %1..50s !?1,*.3f!`

?1	Tag names. Gives a list of tag names matching an optional wildcard name. The value of the field itself is ignored and the <parameter string> is read as <types>:<wild>. The types let you pick which type of tags you are interested in and are the same as those used for `?1` as menu. If the '`u`' option was specified for the list box, then an element "None" is added at the start of the list.
?2	Unused.
?3	Font short name.
?30	Font long and short names. Uses field as optional wildcard. <parameter string>[0] = 's' for short\|short, '1' for long\|long, other for long\|short. <parameter string>[1] = type to match: defaults to all, 0=txt only, 1-4 maths fonts.
?31	Font long name.
?4	Save dialogue box. (if used on other platforms other than a Mac, reverts to option 5 below).
?5	Directory picker.
?6	Variable names. Gives a list of variable names matching an optional wild card which is taken from <parameter string> if exists and field otherwise.
?7	Unused.
?8	Area names. Gives a list of area names.
?9	Drive names. Gives a list of drives.
?10	Colour book description. Gives a list of colour books using the field as an optional wild card to match to.
?11	Unused.
?12	Icons, actions and toolbars. Gives a list of root tag names matching an optional wildcard name. The value of the field itself is ignored and the <parameter string> is read as <types>:<wild> The <types> let you pick which types of tags you are interested in:

a	Actions names.
i	Icons names.
r	Toolbars names.

If the 'u' option was specified for the list box, then an element "None" is added at the start of the list.

?13	Unused.
?14	Unused.
?15	Tag Information. The parameter string supplies the tag name to display informatin for. Information is returned as sequential lines of plain-text information on the given tag name.
?16	Unused.
?17[, options]	Tag Types. The parameter string supplies which tag types to list, the valid parameter format and tag types are detailed here: Tag types.

The tag class selections are described below:

a	Actions names.
i	Icons names.
r	Toolbars names.

p	Identical to Xx see below
Xx	Specifies tag types by class, where x is a valid class type in the range:

F	Frame-text tags
t	Text Tags
o	Object Tags
r	Raster Tags
p	Page Tags
c	Colour Tags
m	Bookmark Tags
f	Font Tags
n	Namespaces

The special options are described below:

-	Toggles between setting and unsetting tag types. At the start of the parameter string you are specifying types to include in the list, following a '-' you are then specifying types to exclude from the list.
E	Put type after name.
T	Put type after name.
h	Display linked AUTO's.
+	Show whole namespace name.
/	Add trailing : to namespace.
;	Show main namespace.

help:n

Many of 3B2's own dialogue boxes contain links to a help menu, which the user enters by clicking a ? button. ? buttons can either be attached to an editable item, or can appear on their own. Help for tab groups is discussed in the Help tabs enhancements section.

num A help screen defined in shuk.3ad, suser.3ad or by defstr or addstr, where nnn is the string number. 3B2's help index being string no.400.

It is often useful to provide more general help, for example to provide an overview of the function of a dialogue box. You can attach a ? button to a non-editable item by attaching it to the dummy field_type, 'd'. In this case the full code would be:

L%d?nnn?

You can restrict use of a 'dummy' help link to the help button to which it is first assigned by including its string number between ? and ??? marks. In this form the help link is only available when the ? button to which it is assigned is clicked, letting you offer the user very context sensitive help.

The example below illustrates the three forms of help you can offer the user:

defstr 390,"%d?464???\n"	1
addstr 390,"%d?465?\n"	2
addstr 390,"%d?464?\n"	3
addstr 390,"Edit box: ^var%1..20;10s!10!?464?\n"	4

2.3.10.1 Radio Buttons

In the basic dialogue box script example it has been demonstrated in that radio buttons are defined by %r with the number of buttons defined in between for example, %1..4r. The actual buttons appear in the script line after this as a series of [ ]. The text the user wants to appear on the button is inside the square brackets. The user can also specify the minimum width of the corresponding buttons. The width is specified in the same units as other [num] parameters and so it varies with the height being used, for example:

%2..1;6e[OK] [Cancel]

In the above example the width is specified by the number 6.

It is also possible to have text between a series of radio buttons; therefore radio buttons can span multiple lines and have sub-headings for each line. Fills and spaces can also separate a list of radio buttons.

Radio buttons can also have colours applied to them, for further information see the Colours in dialogue boxes section.

2.4	Colours in dialogue boxes

Buttons, tabs and backgrounds can be given a colour and some of these have a default colour applied (see list below).

These colours are defined in the scol256c.3ad file. They can be altered if necessary by creating a scoluser.3ad file. Certain colours can be turned off by setting them to the same colour as the dialogue box.

If you alter the colours in the scol256c.3ad it is good practice to keep a copy of the original file for reference.

Colours 130-157 are the default group colours for non mono dialogues, the colours are defined as the extract below in the scol256c.3ad file.

colour 130,80/25 red+50,0 :'130 DB Group 0	1
colour 131,80/50 red+50,0 :'131 DB Group 1	2
colour 132,100/30 green,0 :'132 DB Group 2	3
colour 133,100/66 green,0 :'133 DB Group 3	4
colour 134,100/20 magenta+50,0 :'134 DB Group 4	5
colour 135,100/50 magenta+50,0 :'135 DB Group 5	6
colour 136,100/28 cyan+35,0 :'136 DB Group 6	7
colour 137,100/61 cyan+47.5,0 :'137 DB Group 7	8
colour 138,100/25 yellow,0 :'138 DB Group 8	9
colour 139,100/50 yellow,0 :'139 DB Group 9	10
colour 140,90/33 green,0 :'140 DB 'OK' buttons	11
colour 141,90/33 red,0 :'141 DB 'Cancel' buttons	12
colour 142,90/33 cyan,0 :'142 DB Exit buttons	13
colour 143,90/33 magenta,0 :'143 DB Control buttons	14
colour 144,80%,0 :'144 DB menu buttons	15
colour 145,90/33 yellow,0 :'145 DB help buttons	16
	17
colour 146,red,0 :'146 DB check box ticks	18
colour 147,white,0 :'147 DB list box background	19
colour 148,80% cyan+60,0 :'148 DB list box text	20
colour 149,red,0 :'149 DB list box highlight	21
colour 150,red,0 :'150 DB text box highlight	22
colour 151,50% green,0 :'151 List Box Hypertext	23
colour 152,red,0 :'152 List Box Titles, Dirs & None	24
colour 153,blue,0 :'153 List Box/Release Note Tags	25
colour 154,50% blue,0 :'154 List Box References	26
colour 155,50% blue,0 :'155 Dialogue Box Title Background	27
colour 156,white,0 :'156 Dialogue Box Title Text	28
colour 157,50%,0 :'157 Dialogue Box Title Deselect	29

Individual buttons can also be coloured, or have their default colour overridden by specifying the colour with the button, for example:

%1..3r[(142)First][(143)Second][(132,136)Third]

Tabs can be coloured and it is also possible to override their default colour for example:

[[tab oc(130)]]

For more information see the Tabbed group examples

The main backgrounds in dialogue boxes can also have their colour changed. The default colour is grey. The syntax to change the background is demonstrated below and more further information on this syntax can be found in the Resizable dialogues section.

[[parms bgcol (146)]]

If no colours are required, then Arbortext APP can be started with a parameter to turn them all back to the original colours as follows:

\3b2 -D:MONO_DB This is placed in the sargs.3ad file.

3 Intermediate Section

3.1	Special characters

There are numerous special characters that are used in the creation of dialogue boxes, some of which have been demonstrated already in this chapter. The inclusion of special characters mean that more features and design effects are to be implemented in the dialogue box, for example alignment of text. The table below describes the function of each special character:

Special Character	Description of function
`@`	Used for displaying macro name in the dialogue box.
`%`	Inserts an editable field and takes character limiting/scroll to max parameters in the form (0..0;0 :: min_char..max_char;scroll_up_to) .
`[ ]`	Delimiters used for icon names (see below), buttons and tab names.
`[[ ]]`	The double square brackets are used to delimit group related commands of the dialogue box. They are also used to delimit modeless scripts and extended parameters.
`+`	Inserting this character at the beginning of a line will make that line at least as deep as a line containing buttons or edit fields etc. This is used to give a consistent leading between lines when needed.
`\|`	The basic `\|` character is used for centering items on a line and defining macros to menu options '`cut text\|tcut`' for example, but can be followed by various options to give completely different commands as described below.
`\|=`	Gives a vertical fill. In a normal dialogue box this will have no effect, as there is no extra space to take up, but where groups are used it works as a vertical leader. If there is more than one vertical fill, the space is divided equally between each one as far as the resolution of a pixel allows. `\|=` should be placed at either at the beginning or the end of a line, otherwise the results will be unpredictable.
`\| \|`	Gives a horizontal fill. Unlike the vertical fill, this has many uses in an ordinary dialogue box and works like a normal leader i.e. when `\|\|` appears in front of any items they will be flushed right and either side will centre be centred etc.
`\| -`	Works as `\|\|` but fills out with a grooved line.
`\| - -`	Works as `\|\|` but fills out with a ridged line.
`\| +`	Gives a 'Soft Return' and starts a new line at the same alignment.
`\| *`	Gives a negative kern: useful for flushing things further right.
`}`	Placing a `}` in front of an item to align will cause the dialogue box to look for other lines that also have this character then align on the furthest from the left. You can set up to seven alignment points within a dialogue box. Arbortext APP uses a proportionally spaced font for its dialogue boxes. In order to align items within a dialogue box you can use the `{` and `}` characters in much the same way as text tabs. The `}` character works like a tab that auto-detects its minimum position based on other lines that also have a tab. It aligns anything following it to the maximum position reached by the tab on this or any other line in the dialogue box. Multiple tab stops can be used by including more than one `}` on a line. The `{` character is used to skip a tab stop without affecting the position of the skipped tab. Alignment points work fully when some are skipped i.e. if words spanning two alignment points are wider than the two singles together, then the width of the second is increased accordingly. The usage of `}` and `{` otherwise remains the same. The fills work in combination with the alignment points, so if items are followed by a `}` then the fills will only work within the local alignment. This means that the alignment points can now be treated like tabs and things can be flushed right or centred within a tab (or two tabs etc. if `{` are used). The restriction to this is that there must be at least one item after the `}` even if it is just a space, otherwise the fill(s) will work up until the next alignment which does contain something (see example below). If no alignment points follow the fill(s), then space will be added to fill out to the full width of the dialogue box (or group: see later). The `\|\|` fills right out to alignment points, so if you want to flush right, but leaving a small gap, put a space just before the `}`. See the alignment example below:

defstr 390,"Hello \|Test dialogue box\n-\n"	1
addstr 390,"}}\|-Num:\|-} }}\|-Num:\|-\n"	2
addstr 390,"Numbers Used: {}%i\n"	3
addstr 390,"Option }\|-One }%m }\|-Option }\|-Four }%m\n"	4
addstr 390,"}\|-Two }%m }\|-}\|-Five }%m\n"	5
addstr 390,"}\|-Three }%m }\|-Six {}%m\n"	6
addstr 390,"}Alignment skipping two levels:{{}\|-Seven }%m\n-\n"	7
addstr 390,"%1..7r[One]\|-[Two]\|-[Three]\|-[Four]\n"	8
addstr 390,"[Five]\|-[Six]\|-[Seven]\n"	9
addstr 390,"\|-%2..1e[OK] [Cancel]	10
wdb 390	11
?=^wdb,^(1) trun 0	12

The above script creates the dialogue box shown below:

Both 'Num's are effectively centred over the edit fields beneath them, by putting |- on either side of them. But after the first 'Num', notice that there is also a space after the following }: if this space did not exist, then there is no item within the following alignment tab and the 'Num' would have been centred over the next three alignment tabs instead.

Note the use of fills between buttons, to spread them out to the measure. A line containing |- on its own will work just like a - , but will leave a space at either side.

3.1.1 Separator lines

A separator groove or ridge line can be drawn across the dialogue box. This is done by including a line that contains just a single hyphen character for a groove or two hyphens for a ridge. Arbortext APP's dialogue boxes have a separator groove line following the title and another before the exit buttons at the bottom and occasionally elsewhere where needed.

The example below defines a grooved line that can be used to separate sections in a dialogue box:

addstr 390,"-\n"	1
addstr 390,"\|%2..1e[OK] [Cancel]"	2

3.1.2 Icons in dialogue boxes

Icons can be included within dialogue boxes. The normal use of these will be within a radio button list, where you can mix and match with normal radio buttons i.e. %r. The basic syntax is that if the first text within the [ ] is in quotes, then it is an icon name to be used on the button. It is possible to have normal text on the button which by default will be positioned underneath the icon, by inserting a colon : following the icon name, the text will be placed to the right of the icon.

Colours can be used on the buttons as normal within the ( ) and these come before the icon name. The extension to this is that a colour of -1 for the background, will result in no background being drawn at all and just the icon being shown i.e:

["file_o"]

Gives a button with the "file_o" icon on it.

[(-1)"file_o"]

Just displays the icon.

To use an icon in the text proceeding a checkbox, so that the icon can also be clicked on to trigger the check, follow the example below:

^fred%1rP[(-1)"file_o"] Open: ^fred %1..0bP

The icon is a hidden radio button that is linked to the checkbox by virtue of using the same variable and the 'P's.

3.2	Dialogue box groups

Groups allow for items within a dialogue box to be grouped together and form an item of their own, similar to a mini dialogue box. All the abilities to centre, flush left or right etc. are valid within these groups and it is also possible to highlight them by colour and/or a border.

Some characteristics of dialogue box groups include:

Groups can contain more than one sub-group or tab, which are arranged next to each other horizontally, vertically or overlay each other with some means of controlling which tab is visible at any one time.

Group commands are contained within [[ ]] and consist of a keyword, followed by any options required.

3.2.1 Group Start commands

The three main group types are as follows:

`[[hgroup]]`	A horizontal group, where tabs are arranged from left to right and the height of the group is determined by the height of the biggest tab.
`[[vgroup]]`	A vertical group, where tabs are arranged top to bottom and the width of the group is determined by the width of the widest tab.
`[[tgroup]]`	A tabbed group where tabs are overlayed on top of each other and is as high and wide as the tallest and widest of its tabs.

3.2.2 Other group commands

Any one of the Group start commands starts a group. Subsequent text is then processed as per a normal dialogue box until one of the following occurs: [[hgroup]], [[vgroup]] or [[tgroup]] start a nested group, within the current one.

`[[tab]]` or `[[]]`	Terminates the existing tab and starts the next one. If this immediately follows a `[[hgroup]]`, `[[vgroup]]` or `[[tgroup]]` command then it actually starts the first tab, but enables you to specify options for that tab otherwise the first tab is the default.
`[[end]]`	Terminates the current group and returns you to either the main dialogue box or another group if you were already nested within a group.
`[[line]]`	Gives a vertical groove if in a `[[hgroup]]` or a horizontal groove if in a `[[vgroup]]` and will then start the next tab. Horizontal and vertical `[[line]]` from adjoining groups should meet correctly. Margins should be specified if you do not want them to. If you require a ridge instead then specify either `o`, `i`, `r` or `g` (see the following section).
`[[fill]]`	See, Boxed Group Options.
`[[--]]`	Gives a vertical ridge.

The main dialogue box is itself a [[vgroup]] with the f option specified (see below), so [[tab]] can be used to start a new tab if required.

3.2.3 Miscellaneous Group Options

After the main keyword and prior to the ]] it is possible to specify any number of the following options, most of which are accumulative, but some of which cancel out earlier options. Some of these options have different effects for the three types of group, which are detailed. Also note that it is case sensitive.

`m(t,b,l,r)`	Enables you to specify margins in pixels around the group or tab, so that you can fine tune its position in relation to other items. These are specified in the order 'top, bottom, left, right' and can be negative if desired. Can be combined along with `M(t,b,l,r)` or `R(t,b,l,r)` to give cumulative effect, see below.
`M(t,b,l,r)`	As above, but values are multiples of line height or width / 6
`R(t,b,l,r)`	As above, but values are multiplied by raised border thickness.
`c([col])`	Enables you to specify the background colour of a group and/or tab, as well as the colour of grooves and ridges within the group. Within a `[[hgroup]]` or `[[vgroup]]` it is only relevant if either `o`, `i`, `r` or `g` is specified for either the `[[hgroup]]` or `[[vgroup]]` itself or the `[[tab]]`.Within a `[[tgroup]]` it will also be relevant for a `[[tab]]` if o, i, r or g is specified for the outer `[[tgroup]]`.Has no effect in a `[[fill]]`, `[[line]]` or `[[end]]` command.
`C([col])`	As '`c`' above, but the colour will be applied to the group, whether or not the group is boxed by `o`, `i`, `r` or `g`
`T` or `t`	Specify titles for groups. See also Group titles.
`X`	Removes the normal gap around the edge of a group or a tab, so that any buttons etc. within the group, touch the edges. Should not be used with any border around the group, but is useful, particularly within `[[tgroup]]` to ensure that the group does not take up any more space than necessary.
`x[num]`	Used to ensure `[[tgroup]]` containing buttons take up exactly the space that the button itself would take up. This is context sensitive, so use `x1` if the `[[tgroup]]` is in a line with other buttons and use `x2` if in a line on its own. These simulate the margins and work for any raised border thicknesses. Both affect the internal `[[tab]]` for the tgroup as follows:

[[tab XR(-1,-1,-1,-1)m(0,0,0,-1)]]

The current [[tgroup]] margins are as follows:

for "x1":

[[tgroup R(-1,0,0,-1)m(0,1,6,0)]]

for "x2":

[[tgroup R(0,-1,0,-1)m(0,1,6,0)]]

3.2.4 Boxed Group Options

Below are examples of syntax and the resulting display of the Boxed Groups Options.

3.2.4.1 Example 1 - Indented by raised border thickness box group option - i

\|Test dialogue box\n	1
-\n	2
\|[[hgroup i]]&NL;\n\n\n\n[[end]]\n	3
-\n	4
\|%2..1;6e[OK] [Cancel]	5

The above example creates the following dialogue box:

3.2.4.2 Example 2 - Outdented raised border thickness box group option - o

\|Test dialogue box\n	1
-\n	2
\|[[hgroup oc(130)]]	3
\n\n\n\n[[end]]\n	4
-\n	5
\|%2..1;6e[OK] [Cancel]	6

The above example creates the following dialogue box:

3.2.4.3 Example 3 - Groove surround box group option - g

The groove around the dialogue box is specified by 'n' pixels down and then 'n' pixels up, where 'n' is one less than the raised border thickness.

\|Test dialogue box\n	1
-\n	2
\|[[hgroup	3
gc(132)]]	4
\n\n\n\n[[end]]\n	5
-\n	6
\|%2..1;6e[OK] [Cancel]	7

The above example creates the following dialogue box:

3.2.4.4 Example 4 - Ridge surround box group option - r

The ridge around the dialogue box is specified by 'n' pixels up and then 'n' pixels down, where 'n' is one less than the raised border thickness.

\|Test dialogue box\n	1
-\n	2
\|[[hgroup r(134)]]	3
\n\n\n\n[[end]]\n	4
-\n	5
\|%2..1;6e[OK] [Cancel]	6

The above example creates the following dialogue box:

3.2.5 Boxed Group Options

Fill options within groups are relatively complicated, but they enable extra control over the size of groups so that you can make several groups all the same size.

`f`	Within an `[[hgroup]]` or `[[vgroup]]`, the tabs do not by default fill out to the height or depth of the group. Specifying the '`f`' parameter means that all tabs will be the same height within a `[[hgroup]]`, or the same width within a `[[vgroup]]` and so any fills can be used to take up the slack and centring will now be within the wider width, within a `[[vgroup]]`. Within a `[[tgroup]]` all tabs are automatically filled out to the height and width of the overall group. Specifying the '`f`' option will instead cause the buttons at the top of the group to fill out to the width. This has no effect in a `[[tab]]`, `[[fill]]`, `[[line]]` or `[[end]]` command.
`\| \|` or `\|`	Either option can be specified multiple times. Each time making the `[[hgroup]]`, `[[vgroup]]`, or `[[tgroup]]` expand by the equivalent of '`\|\|`' or '`\|=`' being specified outside of the group, i.e. they can be used to make the specified group take up any slack horizontally or vertically within the outer group. They work in conjunction with any '`\|\|`' or '`\|=`' commands within the outer group and share the space evenly: hence the possible need to specify multiples. This will only expand the group itself though, causing any boxes or backgrounds on the group to increase in size. If you want to expand the tabs within the group by a similar amount then either use the '`f`' option detailed above, or use '`\|\|`' or '`\|=`' within the `[[tab]]` command itself. (so you may need to specify an initial `[[tab]]`). Can also be used within `[[tab]]`, `[[line]]` or `[[fill]]` to expand the size of the relevant sub-group; so you could have a row of `[[tabs]]` and spread any space evenly between them by specifying `[[tab \|\|]]`. Having expanded the sub-group, it could contain groups with fill options to take up the added slack within the group. For example, `[[vgroup \|\|fg]]`. If specified in the outer group of a dialogue box, it will make a group with a groove around it, which is the full width of the dialogue box and objects within the group, centred or filled to this new width, if specified. If the '`f`' option was not given, then the grooved box would still be the new size, but the items within, would be their original size and flushed left.
`[[fill]]`	A whole new group type that will give the equivalent of a blank `[[tab]]` with '`\|\|`' if inside an `[[hgroup]]` or '`\|=`' if inside a `[[vgroup]]`. If you want multiple fills then either use multiple `[[fill]]` group commands, or specify extra '`\|\|`' or '`\|=`' options within the `[[fill]]`.

The example below shows four dialogue boxes containing grooved [[vgroup]], with a space either side of the group. The first uses [[vgroup g]], the second [[vgroup||g]], the third [[vgroup ||fg]] and the fourth, [[vgroup ||g]][[tab ||]] to give the same effect as the third.

The fourth variant would be needed if [[hgroup]] was used instead, as the 'f' option only affects vertical size for [[hgroup]].

3.2.6 Group titles

Normal groups and tabs can also have titles, by specifying either 'T' or 't' within the group parameters. They are very similar to the main titles, but have some extra features:

The title includes all items up to the next return character, which must be present. These titles are allowed to contain % items, help buttons and [ etc. If they are present they will just make the title taller and can be used in the normal way. A particular use of this may be to have a checkbox on the title, which disables the group contents using an internal [[tgroup]] See also Tabbed groups

`-`	Lines are not skipped after the title.
`T`	Will give the same type of title, as the main dialogue box title i.e. a blue bar with the text in white. If the title is followed by a '`-`' line, then it modifies the title, so that it does not have any border around it, looking more like a raised bar.
`t`	Gives a title without any background and where the text automatically sits on top of any border round the group. Text sticking above the border is not taken into account with group margins.

The colours for the title can be overridden by specifying [bcol],[tcol]), immediately after the 'T' or 't'. [bcol] is the background colour for the title bar for a 'T' or the background colour for the text in a 't'. [tcol] is the colour of the text itself within the title.

Group titles can also be applied to [[tab]], the only restriction being that [[tab]] within a [[tgroup]] cannot have 't' titles.

The following example shows the main title and group titles 'T', 'T' with '-' and 't':

\|Main Title Centred<><>	1
[[hgroup]][[tab gT]]'T' left<>	2
\|Hello There[[tab gT]]\|''T' & ''-'<>	3
-<>	4
\|Hello There[[tab gt]]\|\|''t' right<>	5
Hello There<>	6
[[end]] <>	7
\|%2..1e[OK] [Cancel]	8

The above example creates the following dialogue box:

3.2.7 Tabbed groups

Tabbed groups are special and enable overlayed tabs where only one is displayed at any one time. These can be used to section data into manageable portions, to show different data for options or even to hide data when certain options are turned off.

After the [[tgroup]] command, Arbortext APP will read up until the next [[ and will take what it finds in between as the control and buttons that are to be placed at the top of the [[tgroup]]

This must include a %T command, which is passed a variable controlling which tab to display. It works almost identically to a %r and takes an optional list of buttons in the normal fashion, along with low and high range, options ('o' & 'O') and change procedure ('P' or 'p').

Other than the %T command, the only other things allowed, are the buttons themselves in [], spaces, carriage returns and possibly a named variable prior to the %T, if in a script, or not wanting to pass a parameter to control the displaying tab.

Tabbed groups do not need to have a row of tab buttons at the top, but the %T must still be present. When there are no buttons, the tab being displayed can be controlled by other editable fields (usually radio buttons). The same variable must be passed to both and a 'P' or equivalent specified on the other control so that when it changes, the tabbed group does too.

If tab buttons are used, then these can be specified in several rows if required and when a new tab is brought to the front, the rest of the tabs will rotate. Also in the case of multiple rows button, it is possible to click anywhere on tabs that are visible.

By default the tab buttons will overlap slightly. If you want space between them it is possible to use spaces. If you want to spread out the buttons to fill the width of the group, specify the 'f' option.

3.2.7.1 Error handling

Error handling within tabbed groups works in two different ways depending on whether the [[tgroup]] has buttons. If the default is not what you require then you can switch to the other method by specifying 'O' as an option to the %T.

Buttons	Buttonless
It is assumed that when buttons are present, the `[[tgroup]]` is being used to save space only and that all the tabs contain relevant information. So if there are any errors on hidden tabs when you try to 'accept' the dialogue box, it will not work and the relevant tab will be brought to the front.	It is assumed that tabs without buttons are used where the `[[tgroup]]` shows only the data is relevant, controlled by an external option. In this case, only the visible tab is checked for errors.

3.2.7.2 Greyed out tabs

By default, when the variable controlling the tab has a value outside of the range of tabs, no tab will be displayed at all. It is possible however, to specify a default tab to be displayed in this case, but it will be 'greyed out'. This means that all the colours within the tab will be washed out and it is not possible for the user to click in any item within the tab, or change any data.

To specify a 'grey tab', a parameter must be given to specify which tab to use and the 'o' option must be specified for the %T as follows:

%1..3;1To

Specifies a tabbed group with three tabs and if the tab variable is not 1,2 or 3 then tab 1 will be displayed greyed out.

Greyed out tabs will normally be used when there is no row of tabs at the top of the tabbed group, but when the tab is controlled by an external set of radio buttons or more likely, by a checkbox.

The following is an example with a checkbox is shown below, with the checkbox selected on the left and deselected on the right showing the 'greyed out' tab.

\|Example dialogue box<>	1
-<>	2
\|[[hgroup tfg]]Option\|\|^tick%1..0boP[Yes] [No]<>	3
[[tgroup R(-3,0,0,0)]]^tick%1;1To[[tab]]Parameter: ^string%;8sP<>	4
[[end]][[end]]<>	5
\|%2..1e[OK] [Cancel]<>	6

The above example creates the following dialogue box:

The [[tgroup]] is nested within an [[hgroup]] which contains the title.

This might also be a good time to use the 'X' option within the tab itself, so that the border around the 'Parameter' is removed.

All the colours are 'greyed out' when the checkbox is deselected and the 'Parameter' cannot be edited by the user.

3.2.7.3 Tabbed group examples

Standard tabbed group with one row of buttons

This section provides examples of syntax and the resulting display of 'tabbed groups', comprising the common elements used in dialogue boxes.

Notice that the colours are specified for each individual tab, they can also be specified on the [[tgroup]] buttons instead. Also the tab buttons do not stretch all the way across the group. To achieve this, [[tgroup f]] would be used instead. With this option, if any of the tab-buttons had been wider than any of the tabs, the overall width of the tabbed group would have expanded to accommodate them. Notice also the use of named variables, so this can be run as a script.

\|Test dialogue box\n-\n	1
\|[[tgroup]]	2
^taba%T[Brown][Salmon][Pink][Blue]	3
[[tab oc(130)]]	4
\|Centred\n	5
\|=Off }X }^xmin%mP Blah Blah\n\|=- \n	6
\|=}Y }^xmin%mP \|\|Right\n\|=Left\|\|Centre\|\|Right	7
[[tab oc(132)]]	8
\|Tabbed Buttons:\n	9
\|^tab%0..2rP[(140)One] [(141)Two] [(142)Three]\n	10
\|Normal Buttons:\n	11
\|^tab%0..2rP[(140)One] [(141)Two] [(142)Three]\n	12
[[tab oc(134)]]	13
\|Normal Buttons:\n	14
\|^tab%0..2r[(140)One] [(141)Two] [(142)Three]\n	15
[[tab oc(137)]]	16
\|Hello there.\n\|How\n\|Are\n\|You?\n	17
[[end]]\n	18
-\n\|%2..1;6e[OK] [Cancel]	19

The above example creates the following dialogue box:

Standard tabbed group with multiple rows of buttons

Note the range specified on the %T, that the tab--buttons now control the colours, rather than the tabs and that there are more tab-buttons than actual tabs (which give empty tabs which could be used when no extra data is needed).

Notice also the effect of the rows themselves being cycled round when tab-buttons are selected and that tab-buttons like the 'Blue' in the first example, can be clicked on anywhere where they are not covered up!

\|Test dialogue box\n-\n	1
\|[[tgroup]]	2
%1..10T[(130)Brown][(131)Chocolate][(132)Salmon][(133)Orange]\n	3
[(134)Pink][(135)Hot Pink][(136)Turquoise][(137)Blue]\n	4
[(138)Pale Yellow][(139)Sunshine]	5
[[tab]]	6
\|Centred\n	7
\|=Off }X }^xmin%mP Blah Blah\n\|=-\n	8
\|=}Y }^xmin%mP \|\|Right\n\|=Left\|\|Centre\|\|Right	9
[[tab]]\|Tabbed Buttons:\n	10
\|^tab%0..2rP[(140)One] [(141)Two] [(142)Three]\n	11
\|Normal Buttons:\n	12
\|^tab%0..2rP[(140)One] [(141)Two] [(142)Three]\n	13
[[tab]]	14
\|Normal Buttons:\n	15
\|^tab%0..2r[(140)One] [(141)Two] [(142)Three]\n	16
[[tab]]	17
\|Hello there.\n\|How\n\|Are\n\|You?\n	18
[[tab]][[tab]][[tab]]	19
[[end]]\n	20
-\n	21
\|%2..1;6e[OK] [Cancel]	22

The above example creates the following dialogue box:

or filled [[tgroupf]]

Tabbed group controlled by radio buttons

This section provides an example of a tabbed group controlled by radio buttons. Listed below are a few points to note in this example:

The differing ranges on the radio buttons and the tabbed group and that when the value of the radio button is outside the range of available tabs, then none is drawn.

The grooved border placed on the [[tgroup]] itself and how this makes the colour on its tabs relevant.

Each [[tab]] could have instead specified its own border and in which case when 'None' was selected then you would not even see an outline.

\|Test dialogue box\n-\n	1
Tabbed group and control buttons:\n	2
\| [[hgroup fgc(131)]]	3
^taba%0..4;7rP[None]\n[Salmon]\n[Hot Pink]\n[Blue]\n[Yellow]	4
[[tab]]	5
\|=\|[[tgroup g]]^taba%1..4T	6
[[tab c(132)]]	7
\|Centred\n	8
\|=Off }X }^xmin%mP Blah Blah\n\|=- \n	9
\|=}Y }^xmin%mP \|\|Right\n\|=Left\|\|Centre\|\|Right	10
[[tab c(135)]]\|Tabbed Buttons:\n	11
\|^tab%0..2rP[(140)One] [(141)Two] [(142)Three]\n	12
\|Normal Buttons:\n	13
\|^tab%0..2rP[(140)One] [(141)Two] [(142)Three]\n	14
[[tab c(137)]]\|Normal Buttons:\n	15
\|^tab%0..2r[(140)One] [(141)Two] [(142)Three]\n	16
[[tab c(139)]]\|Hello there.\n\|How\n\|Are\n\|You?\n	17
[[end]]\|=	18
[[end]] \n	19
\n\|%2..1;6e[OK] [Cancel]\n	20

The above example creates the following dialogue box:

3.3	Dialogue list treeview

From version 8 the list treeview is intended for listing structured data that is arranged in a tree-like hierarchy. Windows users will be familiar with this type of control already as it is used extensively in Windows Explorer and is provided in the Microsoft Common Controls library for Windows. Arbortext APP's treeview control attempts to conform to the Microsoft treeview standards (in terms of interface and interaction) as much as possible.

Syntax `(7.82a)`

( (:L branch:s leaf:s+ ):L )+ elemsep:s nodesep:s

branch:s Name of branch node*

leaf:s Name of leaf node*+

elemsep:s Character(s) separating node names. Default character: colon ":" (#58)

nodesep:s Character(s) separating nodes

3.3.1 Interface

The interface of listbox treeviews is designed to be intuitive, facilitating and as familiar as possible. The following screenshot shows a sample multi-select list tree, generated from the source data given below. Nodes that are selected are shown with a red tick, branches by default cannot be selected, unless the "Branches Return Result" flag is set.

Case:Motherboard:CPU	1
Case:Motherboard:RAM	2
Case:Motherboard:Video Card:RAM	3
Case:Motherboard:((disk_n))Network Card	4
Case:Motherboard:Sound Card	5
Case:Power Supply	6
Case:((disk_h))Hard Disk	7
Case:((disk_f))Floppy	8
Case:((disk_c))CD-ROM	9
((machine))Screen	10
Keyboard:Keys	11
MouseSpeakers	12

Note that certain icons have been overridden using the ((icon.name))syntax.

3.3.2 Interaction

3.3.2.1 Mouse

The user may use the mouse to open and close branches of the tree or select one or more items in a tree. The following table describes the supported interactivity:

Action	Location	Result
Double click	Branch name Leaf name	Open/close branch Select leaf (if double click select flagged)
Single click	Branch widget Node name	Open/close branch Select node+
`Shift` -click*	Name	Select all items between last selection and item clicked on
`Ctrl` -click*	Name	Toggle selection of item

*	only valid for multiple-select lists
+	by default branch nodes cannot be selected unless the '`b`' flag is supplied.

3.3.2.2 Keyboard

All standard listbox keystrokes work identically. The special treeview keys are listed below and can be remapped by supplying the listed keyname to the '***' macro. Within a treeview listbox, a key which is mapped to one of the "dbtree…" actions will take precedence over any generic dialogue mappings.

Refer to the following Key Table for a list of treeview specific keystroke names, default mappings and description. Key names with a value of -1 are unmapped.

Keyname	Default Keycode	Keystroke	Meaning
db_tree_open1 db_tree_open2	101063 43	Right arrow Plus	Open selected branch
db_tree_close1 db_tree_close2	101061 45	Left arrow Minus	Close selected branch
db_tree_expand1 db_tree_expand2	42 -1	Asterisk	Open the selected branch and all its children
db_tree_toggle1 db_tree_toggle2	200013 -1	Enter	Open/close selected branch
db_tree_scrollu1 db_tree_scrollu2	109254 -1	Ctrl-up	Scroll viewable area up
db_tree_scrolld1 db_tree_scrolld2	109256 -1	Ctrl-down	Scroll viewable area down
db_tree_scrolll1 db_tree_scrolll2	109253 -1	Ctrl-left	Scroll viewable area left
db_tree_scrollr1 db_tree_scrollr2	109255 -1	Ctrl-right	Scroll viewable area right
db_right1 db_right2	101063 -1	right arrow	Open selected branch (Added v7.96h)
db_left1 db_left2	101061 -1	left arrow	Jump to parent branch if a child node or closed branch is selected. Close current branch if an open branch is selected. (Added v7.96h).

3.3.2.3 Limits

When list elements are selected by either a linked variable/field or (in the case of multiple select lists) a linked stream the target nodes are matched against their result string. This means a match will be dependent upon the "Case Sensitive" flag, the "Full Result Strings" flag and the "Branches Return Result" flag.

Wildcard usage for matching elements in multiple select treeview lists is not supported.

3.4	Embedded Dialogues in Toolbars

7.76a

Toolbars have long been a useful fixture of the Arbortext APP user interface and from version 7.76a users can embed dialogue boxes into toolbar strips. Embedded dialogue boxes are treated as modeless dialogues by Arbortext APP. See Modeless Dialogue Boxes

The dialogue to be embedded must be contained within a numbered string. Dialogue boxes contained within text streams are not supported targets for embedding. Dialogues may be embedded using the Toolbar Editor macro tooledit. The screenshot below shows a Item Type ▶ tab of the Edit Toolbar dialogue box (invoked with the macro tooledit):

3.4.1 Embedded dialogue behaviour

Clicking within an embedded dialogue or any of its controls will cause the dialogue to become active just as if it were a modeless dialogue. (See Modeless Dialogue Boxes). All macros will pass through the modeless dialogue before being handled by the rest of Arbortext APP, for example, @ (insert) macros will insert text into embedded text fields. The dialogue only becomes inactive when another dialogue or the main document is clicked on.

An embedded dialogue can never be closed unless its parent toolbar is removed.

3.4.2 Guidelines for embedded dialogues

There is currently no method for creating one dialogue which will work equally well when embedded in either a vertical of horizontal toolbar. It is best to decide the orientation of the target toolbar in the early stages of using embedded dialogues.

When creating a dialogue for embedding, you will want to keep the physical dimensions to an absolute minimum; to this end, OK and Cancel buttons should never be used. These buttons would also give the wrong impression to the user because it is not possible to exit an embedded dialogue.

Avoid using groups or tabs, these add extra space which may not be desirable.

3.4.3 Scripting enhancements

Information on the current context of the dialogue can be accessed in two ways:

{{context}} insert in dialogue [[scripts]]

Both forms above return the value of 1 if the dialogue is embedded, 0 if not.

The wdbmi "getparms" syntax has been extended for embedded dialogues as shown below:

"maxsize" parameter returns "0,0"

Only a limited subset of the [[parms]] syntax is interpreted for an embedded dialogue, however the full set will be used when an unlocked embedded dialogue is dragged off the toolbar to create a modeless dialogue. The allowable subset for embedded dialogues is as follows: "class", "resize", "store", "parentwh" and "instances". This subset also applies to wdbmi "setparms" calls which target an embedded dialogue.

The behaviour of other wdbmi commands which target an embedded dialogue is also affected:

"c", "s", "h", "e" and "d" will not work.

3.4.4 Differences between embedded dialogues and standard dialogues

Below is a summary of the basic differences between embedded dialogues and standard dialogues:

Embedded dialogues must have a title line in their dialogue definition.

Embedded dialogues use a limited subset of the [[parms]] syntax

Embedded dialogues can never be closed, except by removing the parent toolbar.

3.5	Help links in dialogue boxes

3.5.1 Help tabs

The use of tabbed groups within help dialogue boxes enables related help items to be placed together within a single dialogue box and a single string. To give a consistent interface it is suggested that all tabbed groups are given colour 40, the use of [[tab oc(40)]] at the start of each tab.

To support tabbed groups some enhancements have been made to the help system as follows:

When specifying a help box within a normal dialogue box the syntax can now support an optional tab number. The following example will bring up help string 601 and will show tab number 5, when you click on the ? for example: ...?601,5?

An extraction action 't', has been added so that you can change the tab number for future help dialogue boxes without affecting the tab for the current help box. The following example will exit the current help box when you click on the NextBox button and will go to help box number 601, showing tab number 5 on the top: %[t5]601e[Next Box]

An example of Help-tabs in use can be seen in the help-box for vertical justification, string number 601. in the shuk.3ad file.

3.5.2 Help text

Help buttons now default to a character, but this can be overridden, by specifying the text for the button within the '?' as follows:

?601,5,Help?

The above syntax will produce the button: Help

The tab number is optional and may be missed out as long as the text for the button does not start with a digit.

4 Advanced section

4.1	Labelling edit fields

An editable field is any item in a dialogue box which enables interaction such as buttons, text fields, sliders Editable fields within dialogue boxes can now be given a label, which enable them to be referenced by other fields and certain actions taken, whenever a specified field is changed by the user.

Labels and actions are specified within [ ] immediately after % signs and preceding the range, type and options of an editable field.

Syntax `(SVNNA)`

`%´ [ `*´ `,´ label:n? `,´ action:n? `,´ action:n? `,´ action:n? `,´ action:n? `,´ action:n? ]?

`*:`	Can only be used for one field within a dialogue box. It specifies that the actions for this field are performed when the dialogue box is first created, as well as calling any procedure associated with the field.

@: This specifies that the supplied list of actions should be applied to all the following editable fields as default actions. The '@' symbol applies per action type. The default actions are overridden on any or all of the following editable fields if any actions are specified for the given action type.

label:n A number from 0 to 99 and enables this field to be referenced and therefore changed by other fields. See also action below.

action:n

Are always specified by a single character, normally followed by a label which specifies which field to affect. Actions can optionally be separated by commas. Quite a number of the actions depend on the value of the working field which is initially the field that you are on, but which can be exchanged by using the 'x' action.

The various actions available are as follows:

z[label]	Zero is the field specified by the following `[label]`. This means setting it to "0" if it is a number, "" if it is a string or "none" if it is a colour.
f[label]	Extracts the filename part of the working field and makes it the filename part of the field specified by the given `[label]`.
w[label]	Extracts the filename part of the working field and if it is wild, makes it the filename part of the field specified by the given `[label]`.
W[label]	Extracts the filename part of the working field and if it is not wild, makes it the filename part of the field specified by the given `[label]`.
p[label]	As '`f`' above, but with paths instead.
F[label]	Zero is the filename part of the specified field.
P[label]	Zero is the path of the specified field.
I[label]	Sets the specified field to the font longname equivalent of the working field's font shortname.
s[label]	Sets specified field to the font shortname equivalent of the working field's font longname.
t[label]	Sets the help-tab number to 'num' for the next help dialogue box.
b[label]	Sets the specified field to either '0' or '1' depending on the value of the working field. If the working field is a string then it will use '0' if it is empty and '1' if it is not. For Colours '0' is used for 'None' and '1' otherwise. For integers '0' is used if this field is 0 and 1 otherwise. Could then be used in conjunction with greyed out tabbed groups to make other options available or not. See Greyed out tabs.
c[label]	Copies the working field to the specified field.
a[label]	Appends the working field onto the end of the specified field.
u[label]	Forces the specified listbox field to update it is list.
e[ret]	Exits the dialogue box, with ret as the return value. Different from the normal 'x' option on a field, as exits whenever this field changes.
+[label]	Increments the value of the field specified by the given label. When the maximum value is reached, then it will wrap round and start again with the minimum value. This should only be used with fields of type `i`, `r`, `R` & `T`.
-[label]	As + but decrements value cyclically instead.
x[label]	Sets the working field to the field specified by the given label. This enables a field to have diverse effects in a dialogue box depending on the value of other fields. For example, a button that when clicked on decrements the value of a 2nd field (`[label]2`) and if that field hits zero, it zeros the 3rd field (`[label]3`), which controls a tabbed group (meaning that the tabbed group is available for all values except zero) i.e.: `^num%[-2x2b3]1r[Back]`
v[label]	Sets the field specified by the given `[label]`, to the given value.
L[label]	Sets the field specified by the given label to lowercase.
U[label]	Sets the field specified by the given label to uppercase.
I[label]	Sets the field specified by the given label to lowercase with an initial capital.
k[key]	See Assigning keys to fields using 'actions' section in the Dialogues chapter.
E[label]	Switches the current editable field to be the specified label.
d[label]	Drive
D[label]	Drive and Path

Tag related actions:

M[label]	Sets the field specified by the given label, to the name of the comment tag associated with the tag represented by the working field. If the working field does not contain an existing tag or it has no comment associated with it then the result name will be empty.
C[label]	Sets the field specified by the given label to the class of the tag represented by the working field.

The values assigned are as follows:
-1	Tag doesn’t exist.
0	A text tag.
1	A graphic tag.
2	A raster tag.
3	A page/overlay/underlay tag.
4	A colour tag.
5	A bookmark tag.
6	A font tag.
7	A namespace tag.

T [label] Similar to c but sets the field specified by the given label to the type of the tag represented by the working field.

The full list of 3B2 tag types can be found in the 3B2 Tag types chapter.

S [label]: Evaluates whether the current field contains a tag name that is a script. Sets the value of the field specified by label to 1 if true or 0 if false.

X[label]=<function>: Provides extended special functions. Valid functions are: 0 Changes labelled treeview the output mode of the listbox to the value of the current field .

4.2	Assigning keys to fields using actions

When specifying a list of actions for a field, it is also possible to assign a key to the particular field. An example of this would be to make the PageUp and PageDown keys move backwards and forwards through a tabgroup or to create a shortcut key to do any number of actions.

k[key]

Not strictly an action: this assigns a key to the current field. <key> is a letter 'a-z' (ignoring case) which corresponds to keys Ctrl + A to Ctrl + Z

When the corresponding key is pressed within the dialogue box, Arbortext APP will treat this field as though it has changed. In other words, any actions for the current field will be processed. In addition, if this field is editable, Arbortext APP will move the cursor to it (which will be the sole result if no actions exist).

As a result, you can program a Ctrl Key to do anything that can be done by a list of actions. If you have no existing fields that you want the key to emulate, then you can always attach a list of actions to a dummy field '%d'.

Examples of use, would be to program a key to exit a dialogue box with a result value, for example the following syntax will program Ctrl + B to exit the dialogue box with value '4':

%[kbe4]d

Note use of '%d' to give a dummy field on which to 'hang' the actions, that has no visible effect on the dialogue box.

Another useful example may be to assign Ctrl + T to cycle through a list of tabs, using the + action. See also Tabbed groups.

The following keys already have reserved meanings and cannot be reprogrammed:

Key	Description
`Ctrl` + `A`	Accept dialogue box, return value '-1'.
`Ctrl` + `C`	Copy in Windows version.
`Ctrl` + `H`	Backspace.
`Ctrl` + `I`	Tab - move on to next field.
`Ctrl` + `J`	Linefeed - actions current field.
`Ctrl` + `M`	Return.
`Ctrl` + `Q`	Quit, Cancel dialogue, with exit code '1'.
`Ctrl` + `U`	Clear contents of current field.
`Ctrl` + `V`	Paste in Windows version.
`Ctrl` + `X`	Cut in Windows version or as `Ctrl` + `U` .

All of the above keystokes are now configurable using the * macro in the swkdefuk.3ad.

It is also possible to assign fields to the PageUp and PageDown keys using 'k-' and 'k+' respectively.

These keys have set uses in a list box and will not work if a list box is the currently highlighted field, but otherwise they will work as the other programmable Ctrl keys. A good use of PageUp and PageDown would probably be to cycle round the tabs of a large tabbed group.

4.3	Verifying fields

The 'V' option enables the contents of fields to be verified according to varied criteria. This gives a high level of control over validation of input data i.e it is not possible to click OK in a dialogue box if any fields are invalid.

Syntax `(0.00)`

`(´ [ low:n `...´ high:n? ]? [ `;´ param:n `...´ param2:n? ]? test:s [ test:s [ test:s ]? ]? `)´

test:s

The [low], [high] etc. have varying use depending on the [test]. You can specify as many [test]s as you want, the field will be tried against each one in turn until one fails or until they have all succeeded. (see @ for the exception).

@	`[test]` succeeds if the field starts with a '`(`' or a '`[`'. This is mainly used for text attributes where '`(`' stands for default and '`[`' stands for paragraph default. If this particular `[test]` succeeds it will prevent any of the rest of the `[test]`s being tried and should normally be used as the first `[test]`.
*[@([wild])	`[test]` succeeds if the field matches the given `[wild]` string, which may contain `*`'s and `?`'s. The matching is case insensitive by default. Add the optional '`@`' for a case sensitive test.
/[@([reg-exp])	`[test]` succeeds if the field matches the given `[reg- exp]` string, which may contain all the usual regular expression syntax. The matching is case insensitive by default and you should add the optional '`@`' for a case sensitive test.
I	Tests field is an integer in the range `[low]`..`[high]`
u	Tests field is a unit in the range `[low]`..`[high]`, where 10000 represents 1mm. `[param]` is used to specify the default units to use if none are given 0=horizontal, 1=vertical and 2=text units.
m	Tests that the field is a fixed point number in the range `[low]`..`[high]`, where the ranges are multiplied by 10000. i.e. V(10000..20000m) will check for a number in the range 1.0000 to 2.0000.
S	Tests that the field contains a valid tag name.
s	Tests that the field contains a string whose number of characters is between `[low]`..`[high]` inclusive.
q	Tests that the field contains an optional unit plus a fraction of the width or height. `[low]`..`[high]` are the allowable ranges for the unit and [param] is used to specify the default units (see '`u`' above). For example, valid fields are '12pt', '1.2h', '2pt+0.5w'
N	Tests that the field contains a valid page number. This option also allows for the extended syntax of sub-page-numbers when pages have been frozen. If `[low]` is '1', then the separator between sub-page-numbers is '_' instead of '.'
c	Tests that the field is a valid colour description.

Further tests may be added in the future, so make sure that the above syntax is adhered to strictly, so that your dialogue box will still work if the syntax is extended.

4.4	Lists and Combo boxes

This section will provide the user with the information required to create lists in dialogue boxes. The difference between general lists and combo boxes is simply size. A combo will display just one element with a list being displayed from the down arrow for example a font list. A general list can be any size but will normally have a scroll facility for example a list of tags in the Browse Tags dialogue box.

4.4.1 List Box - basic syntax

Syntax `(SVNNA)`

`%´ [ across:n down:n? ]? `L´ `o´ ? `!´ list type:n options:n? `!´

across:n Is the width to make the list box specified in the same units as most, widths for %s etc. (default 5)

down:n Is the number of lines deep to make the list box. (default: 4 )

`o:`	An optional single letter '`o`', indicates the list elements are going to be inline and the !! section is not needed.

list type:n

Indicates how to generate the list box elements. The list type indicates the way in which the list box or combo box generates its list of elements. This is often modified by using the options and in particular the 'p' option, the parameter string. The type takes the following format:

[!string_num!]	The list is generated from the specified string in the `stuk.3ad` file. Each line of the string specifies one element and should be in the form: `[display_string\|result_string]` The only exception to this is if the '`o`' option is specified which lets the string be in the form of a old style menu string instead and 3B2 will convert the # or @ macro into the result string. In this case it will be essential to include the 'f' option as well. This option is detailed later.
?S	Similar to num, but picks up the string number from the parameter string, which lets it be variable, for example: `!?S,p(string_num)!`
?s	Uses the parameter string to indicate a stream_name within the current document. Each line within the given stream represents an element, for example: `?s,p(stream_name)!`
?c	This type indicates that the list should be generated from the given Multiple Clipboards number (currently 0..19) This type displays the given clipboard as a brief description of the clipboard contents, including type icon, followed by a blank line and then the translated buffer text (if applicable). There is also a "raw" switch which can be given in the parameter string as a trailing "r" after the clipboard number (for example, "`p(12r)`"). This flag will generate a list containing the raw clipboard data, for example: `!?c,p(0)!`
?f	This type indicates that the list should be generated using the contents of an external file. Each line within the source file represents a list element, for example: `!?c,p(/3d/demo.3d)!`
?v	This type indicates that the list should be generated using the contents of the specified variable. Each line within the variable represents a list element, for example: `!?v,p(my_var$10$)!`
?l	This list type generates a list of height, width or text measurements using the default units specified by the user. The given example will create a list of text measurements in a range of 6 points to 36 points in steps of 2 points, produced in the default text measurement units. This has been used mainly for generating menus for the LAPT types. The syntax is as follows: !?l<units>,<start>,<end>,<step>,<append>!

units	0 = horizontal units
1	vertical units
2	text units
start	measurement to start at
end	measurement to end at
step	desired stepping measurement
append	a string number containing a valid menu string which shall be appended to the menu. If no menu string is required this value should be 0, for exmaple see below:

!?l2,6pt,36pt,2pt,1375!

?r This is a rasc-type. It enables you to specify a range of values to use and then how to format those values for both the display_string and the result_string for exmaple: !?r,p(1,12,"%%209z }%%308z","%%d"),f! The basic syntax within the parameter string is: p([min],[max],"display str","result str") 3B2 will generate each element by ranging an integer from min to max and formatting the two strings with that number. The double '%' are necessary as a single '%' has a separate meaning within the parameter string. The basic formatting options available are as follows:

`%%d`	Shows the number in decimal format. This will probably be the most normal `result_string`.
`%%X`	Shows the number in hexadecimal format.
`%%[num]z`	Shows the number as a show string would display a `$item`. `num` indicates the way to format the number, so in our example the 208 means to display the number as English [one, two, three etc.] and capitalise the start of the first word. The 309 means to display the number as a month name, capitalising the start of each word.

Note that more than one '%%' item can be included in the two strings, up to four can be used. Also the 'f' option needed so that the '}' character within the display_string causes alignment. The two strings could also contain text if required.

options:n

The options follow on from the basic list box type and can occur in any order, optionally separated by commas or spaces. Unrecognised characters will be ignored, but should not be used as they may have meaning in the future. The options are as follows:

o	Old option. Enables old menu strings to be used for list boxes. (See `num` or `?S` types).
f	Format option. Without this option specified then '} { ! &' will be treated as normal characters. With the format option they mean the following:

`}`	Alignment point.
`{`	Skip alignment point (span alignments).
`!`	Horizontal fill, for flush right, centring etc.
`&`	Toggle drawing on/off for phantoms.

m	Do not add a menu button to the list box.
k	List is static, do not regenerate the list.
d	Double click. Needs a double click (or a return) to select an element, for example the directory picker. Has a secondary effect in that it automatically causes the list box to regenerate its list of elements whenever an item is double-clicked.
u	Option passed to the list box procedure, so has no use for types `num`, `?S`, `?s`, `?r` or `?b`. Effect is dependant on procedure, but for example, within the directory picker, it causes the default 3B2 path to be updated.
e	Makes the list box case sensitive.
a	Always regenerate. Only relevant to Combo boxes and causes the list to be regenerated whenever the combo box is selected.
\|	Live scroll. Whenever a new element from a list box is selected then any actions associated with the list box field are actioned and a procedure will be called if one has been attached. The '`l`' option causes these to be done as you drag over the list box, so that you can see other fields or previews etc. being updated.
^	Stores up a variable name in the normal way, ready for the next `%` item.
c	Colour `c(tcol,bcol)`. `tcol` is the pattern number to use for the list box text. `bcol` is the pattern number for the list box background.
M	Multiple selected, `M(name)`. Specifies that this list box is a multiple select list box. name is optional and specifies the description of the type of elements, so that when several are selected and a label is used to copy the multiple select list box to another field, it can say "5 Files" etc. (if `M(files)` is used). As the result from a multiple select list box is more than one element, the variable passed to the field should be the name of a stream to fill in with the results.
t	Specifies that this list box is a 'textbox'. This means that it is not used to select elements at all and is purely for display purposes unless the '`h`' option is also included. All the normal types can be used to generate the 'textbox', but it does not have individual elements in the normal way. Instead text flows and wraps within a 'textbox'.
r	Show Returns only useful in combination with '`t`' in a 'textbox'. Specifies that returns will be displayed within the 'textbox', so that you can see the difference between where the line has wrapped and real carriage returns.
h	Hypertext - only useful in combination with '`t`' in a 'textbox'. This specifies that within the textbox, it is possible to click on some bits of the text and when they are clicked on the variable attached to the textbox field will be updated. Each clickable element occurs buried in the rest of the text in the following format: `[result string:display string]` The result string will be written to the field when it is clicked on and the display string will be highlighted in dark green and is what the user can click on. An example of hypertext being used is the Thesaurus. Using labels and making a the contents of a textbox depend on itself, you can create a hypertext box whose contents changes whenever an item is clicked on.
p	Parameter string : format, `p(parameter string)` This is the option string used for generating the list of elements and will often simply contain text. Its power is shown though when variable elements occur within the string, signified by the following:

`%`	A percent item is substituted by the current value on the stack, formatted according to a following character of '`d`, `l`, `s`', or '`b`'. These are used for number, long number, string in quotes or just strings, but note that only the '`s`' & '`b`' can be used within scripts. In all these cases you should make sure that an item is already on the stack either from within the c-code or by preceding the '`%`' item with a '`^`' variable name. (see below) If you want a real '`%`' use two together.
`label`	Will be substituted with the current field of the given label.
`^var`	Will queue up the script variable for the next `%` item.

Note also that if you want to use ')' within the parameter string you will have to precede it with a '\' character.

R Raw Mode. Only useful within a textbox. Stops '&, !' and '\' being interpreted as special characters and displays them as other normal characters.

T Only useful within a textbox. '<', which signal the start of a tag, are used as word delimiters and lines will break before the '>', making text streams look neater.

7.67 Only useful within a textbox. Flags field as a "buffer direct" field. Enables you to view a large stream of up to 2147483647 lines (defeats the 8000 line limit of normal text boxes). This option can only be used with text boxes containing non-temporary streams (such as ?s and ?b). (From v7.67).

7.67 Only useful within a text box. Flags field as an "Editable" field. Enables you to edit the linked stream. This flag also implies the D and R flags if not specified, also if the f or h flags are specified, they are disabled. Enables cut/copy/paste and typing within the specified stream. Having more than one 'E' text box per dialogue may work but it is not yet supported. (From v7.67).

H Only useful within a text box. Flags field as having "syntax highlighting" enabled.

x Extended returns. This option is only useful within a text box. Treats page breaks, column breaks etc. as if they are carriage returns.

F Format only line which uses the first line of the given list source to setup formatting only the line is never displayed.

4.4.2 Combo Box - basic syntax

Syntax `(SVNNA)`

`%´ [ low:n `...´ high:n? ]? [ `;´across:n `...´ down:n? ]? `C´ `o´ ? `!´ list type:n options:n? `!´

low:n Not normally needed unless the details of the elements for the combo box are specified in-line which will be detailed later.

high:n Not normally needed unless the details of the elements for the combo box are specified in-line which will be detailed later.

across:n Is the width to make the list box specified in the same units as most, width's for %s etc. (Default 128 so must be specified).

down:n Is the number of lines deep to make the list box. (default : 5).

`o:`	An optional single letter '`o`', indicates the list elements are going to be inline and the `!!` section is not needed.

list type:n Indicates how to generate the combo list elements, see below.

options:n Are optional and will be explained later.

4.4.3 Editable Combos

Editable combos are very similar to normal combo boxes, but in addition to the ability to select the element from a list, the user can also type. The low..high are used to specify the minimum and maximum length of the string that the user can type.

4.4.3.1 Elements

Elements within list boxes consist of two halves; what is displayed to the user and what is written to the variable. They need bear no resemblance to each other, so provide a useful way of interacting with the user when a cryptic result is required.

4.4.4 Radio Combos

In addition to the normal Combo boxes, it is also possible to use radio combos. These differ from normal combo boxes in that the variable passed is a number rather than a string and by default they take their elements in-line.

4.4.4.1 Radio Combo Box basic syntax

Syntax `(SVNNA)`

`%´ [ low:n `...´ high:n? ]? [ `;´across:n `...´ down:n? ]? `R´ `o´ ? elem:n [ `;´elem:n `...´ elem:n? ]?

low:n Specifies the return value of the first element.

high:n Normally specifies the return value of the last element, but in actual fact it specifies whether the elements count up or down from low.

across:n Can be specified as for a List box or Combo box, but if missing, the Radio Combo will be just large enough for the widest element.

down:n Defaults to however many elements you have, but can be specified if you prefer.

elem:n Each element would normally just consist of the text to display to the user and the range specified by low..high dictates the return value to be used. The return value can be overridden if required then the syntax for an elem would be: [displaytext|integer_result]

o:

The optional letter 'o', has the reverse effect to that of list boxes and combo boxes. It indicates that the elements are not going to be inline, but use the following syntax instead: list type [options]

If this format is used, it is imperative that the elements all contain integer results. In addition, across will need to be specified in this case as it will not be measured.

4.4.5 In-Line elements

List boxes and normal combo boxes can also be given a list of in-line elements in the same way as a radio combo, but the 'o' option has to be specified with the L, C or R to indicate that the elements are going to be inline.

They are specified in the same way as for a radio-combo box, but as they both work with string variables, each element must have the following syntax:

[displaytext|result_string]

4.4.6 List box regenerating

A list box will regenerate its list of elements under certain circumstances:

A listbox can be updated under external control, using the 'u' action.

Whenever the parameter string for a list box changes, the list will be regenerated. This is where using labels within the parameter string comes into its own and for instance the parameter string for the file lister is dependant on the labels for the directory, the file types, sizes and pages and so will change whenever any of these change.

4.4.7 Escape codes and icons within list box elements

Within the display part of a list box element it is possible to include more than straight text. Within (( )) you can place special escape codes, or an icon name which will then be placed within the list box. This is how icons are placed within the directory list and also how colour changes are achieved.

4.4.7.1 Icons

((icon name)) will insert the named icon at that point in the text, allowing the correct space for its width and centring it within the line vertically. Best results will be used with 'Char Icons', as then Arbortext APP will pick the correct size of icon for the text.

For example, ((file_c)) will give you the closed file icon and ((file_o)) will give you the open one.

4.4.7.2 Escape sequences

These are numerous and all start with '31' and then a 'Sub-code' and optional data as follows:

Code

Sub-Code

Data

Description

none

Switches colour to dialogue box macro colour - red

none

Switches back to default colour

none

Switches colour to menu macro colour - red

none

Toggles drawing on and off (same as & - phantom)

5 - 18

none

Other colour switches are as follows:

5	yellow bar tag
6	yellow bar style
7	yellow bar reference
8	yellow bar hash
9	yellow bar pling!
10	listbox hypertext
11	listbox title, dirs + none
12	listbox tags
13	listbox references
14	menu keyboard shortcuts
15	yellow bar breaks
16	yellow bar exit
17	yellow bar goto
18	yellow bar label

20- 25

kern

Gives a horizontal kern of size kern+ (subcode-20)*256

col

Switches colour to pattern colour col

'icon'

Same as ((icon)) specified above.

4.5	Modeless Dialogue Boxes

During the history of Arbortext APP, dialogue boxes have always been "modal". This refers to the fact that once a dialogue box is created on the Arbortext APP system, the main interface and any other previously active dialogue is rendered inactive and will not interact with the user. "Modeless" dialogues, on the other hand, will not disable any other element of the system when they are made active, for example, a user can be working on their Arbortext APP document while a Font Properties dialogue floats over the Arbortext APP window. This feature brings with it some new macros and advanced levels of dialogue scripting (including inter-window communications), which is detailed in the remainder of this section.

4.5.1 Identifying a Modeless Dialogue

A modeless dialogue acts much differently to modal dialogues. Modal dialogues remain on the screen until the user clicks an exit button, which closes the dialogue and returns an exit code in the ^wdb variable. Modeless dialogues remain on the screen for an indefinite period and do not return an exit code. Interaction is performed through new scripting commands and special macros. The interaction macro is wdbmi.

Scripts can be attached to modeless dialogues using the [[scripts]] syntax: + "alias", "APPLY (n/a)", "UPDATE (n/a) + ON_CLOSE (n/a).

Modeless dialogues have a unique title bar colour to aid the user in recognition of a modeless dialogue. By default the colour of the title bar is a shade from 10% Magenta to 100% Magenta. Setting Arbortext APP to use Windows colour values does not affect the modeless dialogue colours. The colour index numbers which can be customised in the scol*.3ad files are 200 and 201.

4.5.2 Modeless Dialogue Invocation

Invocation of modeless dialogues is performed using an identical syntax to standard modal dialogues. Either of the following two examples of syntax may be used:

wdbm num

Creates a modeless dialogue from string number num.

twdbm "stream"

Creates a modeless dialogue from text stream stream.

For either of the above invocations, the ID of the new dialogue is returned in the user-space wdbm variable. Dialogue IDs are unique to each dialogue box instance and are important for advanced scripting.

4.6	Advanced Dialogue Scripting

4.7	Introduction

Dialogues of either type may now have scripts or macros attached to dialogue exit/apply codes. For example, the user clicks the OK button of a modeless dialogue, causing a trf macro to be triggered. Dialogues may also have "update" routines which are similar to automac ,run when given Arbortext APP expressions change.

4.7.1 Syntax

To open a scripting section, use the "[[scripts" directive on a line of its own at the end of the dialogue string you wish to attach scripts to. All lines of text are interpreted as scripting commands up to the final close scripting directive "]]".

The following scripting commands are defined:

autoexec

autoexit

ON_CLOSE (n/a)

7.68a Define a macro or script to run when the document/window identified by the specified "expression" is closed. A useful expression would be (h) which would be replaced with the dialogue's parent document window handle. Note that the expression is only evaluated when the dialogue is first opened (added 7.68a).

Note that scripts are not executed automically and can be interrupted by user input between lines of the script. A good idea would be to group macros that need to be atomic using the ":" macro concatenation character (as shown in the example). The example update command uses a script as an example action, but in the real world should be optimised by changing the action to a macro call:

update () wdb "my_th":th

Also note that multiple apply, alias, autoexec, autoexit, update and on_close commands can be defined. You can also define multiple scripts or macros to apply to the same exit/apply code. The scripts will be interpreted in order of definition.

4.7.2 Creating an Apply Button

A new dialogue element modifier has been implemented to enable dialogue elements to "emulate" an exit/apply code. In effect, when the value of an element changes, the apply command(s) for a certain exit code are processed. When this feature is used in combination with a radio button we can create an Apply button that emulates a click on the OK button without actually exiting the dialogue.

The new modifier is of the syntax:

p(x)

Where x is the exit/apply code to emulate.

It is important to note that this modifier is a variant of the standard "p" modifier, which has no brackets. The standard "p" modifier is used to attach a C callback function to a dialogue element and should never be used from Arbortext APP scripting.

Borrowing from the earlier example:

^dummy%[5z5]1rp(2)[(138)Apply]

Below the separate elements of the above syntax it will be easier to see exactly what the syntax is achieving:

1r defines the radio button to be number 1 by default (as dummy is 0), otherwise the radio button will appear to be depressed.

p(2) signifies that when the radio button is clicked, exit/apply code 2 is emulated.

[(138)Apply] sets the label of the radio button to "Apply" and forces the button colour to be yellow. The colour 138 is the recommended colour for Apply buttons, to help avoid confusion with other buttons.

Of course one may script their own exit/apply codes which are not even linked to an exit button, which opens a whole world of possibilities in terms of flexible dialogue scripting. The Apply button is simply one use for the "p()" element modifier.

4.7.3 Inter-Window Communication

Inter window communication is controlled with the wdbmi macro.

4.8	Resizable Dialogue boxes

7.82

In the past Arbortext APP's dialogues system has always been based on the concept of fixed size dialogue boxes. To allow greater flexibility in interface design, support for resizable dialogues has been added to Arbortext APP. Resizable dialogues are modal or modeless dialogue boxes which may be resized, while active, by the user or via Arbortext APP scripting.

Scripting is only available for modeless dialogues.

4.8.1 Identifying resizable dialogue boxes

It is simple to identify a resizable dialogue box. Arbortext APP follows the Windows convention of drawing a "widget" in the lower right-hand corner of the dialogue box as shown in the image below:

4.8.2 Using resizable dialogue boxes

Resizable dialogues work in identical fashion to current non-resizable dialogues, the main exception is when the user left-clicks and drags at a corner or edge of the dialogue window. This causes the window to grow or shrink as the user moves the mouse, until the user releases the mouse button.

There is currently no keyboard interface to resize a dialogue box. Also note that resizable dialogues cannot shrink smaller than the minimum size required to display all the dialogue elements.

4.8.3 Creating a resizable dialogue box

Constructing a dialogue which looks and feels correct when resized requires a bit more thought than traditional dialogues. The first thing to remember is that, by default, the dialogue groups and items will try to squeeze into the smallest possible space. To create a resizable dialogue where the elements actually grow and space out requires the use of horizontal and vertical fills.

There are three different types of fills available for use within a dialogue box as described below:

Type of fill	Description
1. Group fills	Group fills are the top level fills and are used to space out groups or make groups fill out horizontally or vertically within their container (for example `[[fill]]`, `[[hgroup \|\|]]`, `[[tab \|=]]`, etc.).
2. Inter-item fills	Inter-item fills are inserted between items to space out the items within their group (for example `\|\|`, `\|=`).
3. Item fills	Item fills are applied to specific items within the dialogue to make the items fill out any extra space within their group. From version 7.82a, item fills can be used on any GUI version of Arbortext APP.

The screenshots below show examples of different fills:

Example of no fills:

Example of horizontal inter-item fill before Done button:

Example of horizontal item fill applied to the Done button:

There are a few points to consider when planning a resizable dialogue. The primary concept behind building a resizable dialogue is that extra fill space due to a resize must be passed down hierarchically through the groups to their tabs and then within the tabs to inter-item and item fills. Vertical or horizontal fill space can be allocated independently of, or in conjunction with, each other.

The dialogue content (after the title line) is contained within a [[vgroup f]]. This means when the dialogue is resized, the content within the vgroup will not be resized vertically unless one or more tabs are explicitly defined with a vertical fill (for example [[tab |=]]). The second point to remember is that other groups within the dialogue will not fill out unless specified. For vgroups specified with the 'f' flag, internal tabs will fill out horizontally but not vertically – to fill vertically use a tab [[tab|=]]. For hgroups specified with the 'f' flag, internal tabs will fill out vertically but not horizontally – to fill horizontally use a [[tab | |]]. Tabs within a tgroup fill out uniformly, according to the fills specified in the main [[tgroup]] instruction. A final concept to remember is that within a tab the extra space is distributed evenly amongst both item fills and inter-item fills.

While developing a dialogue box it is often useful to set different background colours or borders for groups, as a visual aid.

4.8.3.1 Developing a resizable dialogue

The following describes each a step involved in creating a resizable dialogue.

4 Basic dialogue layout, coloured backgrounds help identify the [[hgroup]] and its [[tab]]. Notice how all the items within the outer vgroup are squashed left and how the items in the hgroup are squashed to the top.

8 The hgroup has now been supplied with a horizontal fill and an inter-tab fill has also been inserted between the first and second groups in the hgroup. Even though it is not explicitly specified after the [[hgroup]], there is a hidden [[tab]] which contains the listbox.

12 The hgroup has been supplied the 'f' option which makes all its tabs fill out vertically (notice how the 'Hi' tab now reaches the bottom of the hgroup). The inter-tab [[fill]] has also been removed, the explicitly specified horizontally filling [[tab]] now takes up the left over space. A horizontal item fill has been added to the listbox and it now fills out the tab. As a finishing touch, vertical fills have been added above and below the 'Hi' text to keep it vertically centred within its tab.

16 The dialogue now works properly as a resizable dialogue. The tab of the outer vgroup has now been explicitly specified as vertically filling (so vertical resizing works properly). Also the hgroup has been specified as vertically filling and the listbox now has a vertical item fill. The [[parms]] parameter flags this dialogue as resizable.

4.8.4 Dialogue Item Fills

7.82a

A new option has been added to allow horizontal and vertical fills to be applied to dialogue editable items. This option is supplied similarly to existing item options and takes the following format. As of version 7.82a, item fills can be used on any GUI version of Arbortext APP.

4.8.4.1 Example of a dialogue item definition containing an item fill

^var%30..15LPI(|||=)!?s,p(89),t!

Item fill syntax

I (fills)

The fills parameter can be any combination of valid fill sequences. The currently supported valid fill sequences are '||' for a horizontal fill and '|=' for a vertical fill. There are restrictions as to which fills are usable with which item types (see table).

4.8.5 Extended dialogue parameters

The dialogue box syntax allows for the specification of the dialogue box parameters within the dialogue string itself. The extended parameter syntax should be included at the end of a dialogue box string, before any [[scripts]] section and takes the following format.

4.8.5.1 Example of a dialogue string containing extended parameters

\| Test Dialogue	1
[[tab \| =]] This is a test ^str %1..10s	2
\| = \| \| %2..1e [OK] [Cancel]	3
[[parms class ("test1"), resize (1), pos ("tr")]]	4
<!--Extended parameter syntax-->	5
[[parms parm (value), parm (value),…]]	6

The valid parameter names, their allowable values and behaviour are outlined in the table below. Cells with an asterisk indicate parameters which are available across all Arbortext APP platforms. Value types of "string" are any string of characters surrounded by double quotes. Double quotes within the string data should be replaced with a two sets of double quotes. Value types of "expr" are any valid Arbortext APP expression. Any counters used in the expression are evaluated within the context of the current dialogue box, for example, 'd' for dialogue number, 'h' for parent window handle.

Parameter

Value

Behaviour

class

"string"

Sets the class of the dialogue to the specified string. Class names are used to uniquely identify the type of dialogue.

pos

expr, expr "string"

Sets the position of the dialogue box to the specified offset (x,y), relative to the upper left corner of the main window frame. If a string value is specified then a combination of the following characters can be used: 't' top, 'b' bottom, 'l' left and 'r' right.

abpos

expr, expr

Sets the position of the dialogue box to the specified offset (x,y), relative to the upper left corner of the screen.

size

expr, expr

Resizes the dialogue to the specified width and height. Only applicable to resizable dialogues.

resize

expr

Flags the dialogue as resizable.

store

expr

Flags whether the size and position of the dialogue box should be stored in the Windows registry. This setting will override any user preference.

bgcol*

expr

Sets the background colour for the dialogue box to the specified colour value. Uses the same colour values as dialogue groups.

parentwh*

expr

Sets the parent window handle of the dialogue to the specified value.

instances*

expr

Allows only the specified number of instances of this dialogue class to be created. The current dialogue will not open if it would exceed this limit. A value of -1 indicates unlimited, any other positive 32-bit signed integer value is valid.

maxsize

expr, expr

Sets the maximum dimensions (width, height) of the dialogue. A value of -1 indicates infinite size, a value of 0 indicates the minimum size for that axis of growth (for example, no growth along that axis), any other value is interpreted literally as a number of pixels. Only applicable to resizable dialogues.

controls

expr

Sets which dialogue controls are available. All dialogues now contain the "close" control button, you may specify 3 to this parameter, which will give you an additional "rollup" control button. The "rollup" button will shrink the dialogue to just the title bar height when clicked. It may then be rolled down again. The controls are rendered in system colours 202 and 203.

title*

"string"

7.82a (Added v7.82a). This parameter can be used to set or read the title of the given dialogue. The title that is returned is the currently displayed title (if the title was too long and letters have been truncated, then that is what is returned). When setting the title, note that alignment characters (|,||) are not available and the current alignment is kept from the originally specified title.

4.8.6 Dialogue size and position memory

As an adjunct to the resizable dialogues feature, support has been added to Arbortext APP for memory of dialogue sizes and positions. The data for this feature is stored in the Windows registry under a sub-key "Dialogues" within the main Arbortext APP key. The size and position memory is unique to each dialogue class, not a dialogue string/stream nor an individual instance of a dialogue.

This feature is labelled "Save dialogue sizes and positions" and can be located within the [File/3B2 Preferences/Interface...] dialogue, under the Dialogue Boxes ▶ tab. The wdpref macro has been updated with a new switch, "S", which takes a parameter of 0 or 1 to disable or enable the "Save dialogue sizes and positions" feature from scripts. This feature does not apply to untitled dialogues which are created without a class parameter.

There is also a "Clear all dialogue size and position data button present on the Interface Options dialogue, under the Dialogue Boxes ▶ tab. Clicking this button will cause all dialogue position and size data to be removed from the Windows registry.

When the "Save dialogue sizes and positions" feature is enabled, the following behaviour is exhibited by Arbortext APP:

4.8.6.1 When a dialogue opens

4.8.6.2 Positioning

6 If there is no stored registry data, or the user preference is disabled, the dialogue is positioned either: - centred (if the dialogue "Always display at centre" user preference is set) - at a specified position (if the dialogue is called with flag 16) - under the mouse cursor (if the dialogue is called with flag 1).

4.8.6.3 Sizing

6 If there is no stored registry data, or the user preference is disabled, the dialogue is opened at the default (minimum) size.

4.8.6.4 Sizing

If the "Save dialogue sizes and positions" preference is activated, or has been overridden for this particular dialogue using the store parameter, then the current size and position of the dialogue is saved to the Windows registry.

The table below describes dialogue item types and which item fills are valid for each type. An 'X' indicates the fill type is valid for that item, a '-' indicates the fill type is invalid.

Item	Horizontal Fill	Vertical Fill	Item Description
a	X	-	Angle
b B	X*	-	Checkbox
c	X	-	Colour
C	X	-	Combo
d	-	-	Dummy field
e	X	X	Exit buttons
E	X	-	Editable combo
f	X	-	Mac String
g	X	X	Xbox
h	X	-	Horizontal slider
i	X	-	Numeric (integer)
l	X	-	Numeric (long)
L	X	X	List box
m	X	-	Micron
N	X	-	Namespace
q	X	-	LAPT expression
r	X	X	Radio buttons
R	X	-	Radio combo
s	X	-	String
S	X	-	Stream
t	X	-	Text
T	-**	-	Tabgroup item
u	X	-	Unit of measurement
w	X	-	Numeric (word)
z	-	-	Null field

*	only valid when "Use Yes/No instead of checkboxes" preference is enabled.
**	this effect can be achieved by specifying '`f`' as a `[[tgroup]]` option.

5 Dialogue box examples

Below is a script example that includes comments to explain what each section of the script is doing.

<!-- Define Bill State Types -->	1
defstr 352,"Draft\|@Draft\n"	2
addstr 352,"Amendment\|@Amendment\n"	3
addstr 352,"Resolution\|@Resolution\n"	4
<!-- Define Line Numbering Options -->	5
defstr 353,"No Lines\|@NoLines\n"	6
addstr 353,"Lines Only\|@Lines\n"	7
addstr 353,"Lines and Page\|@PageLines\n"	8
<!--Menus are defined in strings 352 (Bill State) and 353 (Line Numbering).-->	9
<!-- Main Dialogue Box -->	10
^documentType=1	11
defstr 350,"\|Legislative Demo\n"	12
<!-- Main tabbed Group -->	13
addstr 350,"Document Type }^documentType%1..0rP[(114) Bill ] [(132)Journal]\n\n"	14
<!--This script line defines the two main buttons "Bill" and "Journal". As the variable ^documentType has already been set to 1, the first button "bill" is already pressed.-->	15
addstr 350,"[[tgroup R(-3,0,0,0)]]^documentType%1To"	16
addstr 350,"[[tab]]Select Page Size: }^pageSize%1..2R[Letter][Legal]\n"	17
addstr 350,"[[end]]\n"	18
addstr 350,"XML Instance }^inputFile%1..250;20s!?11!\n"	19
<!-- This script line is the file picker.-->	20
<!-- The !?11! coding provides &app; with this information and then invokes the open file dialogue box. -->	21
addstr 350,"\n"	22
addstr 350,"[[tgroup R(-3,0,0,0)]]^documentType%1To"	23
<!--This script line starts a tabbed group.-->	24
addstr 350,"[[tab]]State }^stateName%1..20s\n"	25
addstr 350,"\n"	26
addstr 350,"Bill State }^billState%0..20s!352!\n"	27
addstr 350,"\n"	28
addstr 350,"Line Numbering }^LineNumbering%0..20s!353!\n"	29
<!--This script line calls on the string 353. The user then makes a choice from this menu.-->	30
addstr 350,"\n"	31
addstr 350,"[[end]]\n"	32
<!--This ends the current group and returns you to the main dialogue.-->	33
addstr 350,"Output Formats: }PDF }^pdfOut%0..1b\n"	34
addstr 350,"[[tgroup R(-3,0,0,0)]]^documentType%1To"	35
addstr 350,"[[tab]] }XML }^xmlOut%0..1b\n"	36
addstr 350,"\n"	37
addstr 350," }HTML }^htmOut%0..1b\n"	38
addstr 350,"\n"	39
addstr 350,"[[end]]\n"	40
addstr 350,"\|%2..1e[OK] [Cancel]"	41
wdb 350	42
'?=^wdb,^(1) trun 0	43

The script above creates the dialogue box shown below:

This screenshot shows the dialogue box with the Bill button pressed down:

This screenshot shows the dialogue box with the Journal button pressed down:

6 Further information

Raw dialogues documentation from 3B2 programmers is available on the 3B2 installation CD.

6.1	Associated documentation

addstr

twdb

7 Subject Index

Subject index only applicable to the PDF version.

Document created on 17-Sep-2002, last reviewed on 06-Jan-2005 (revision 4)

Summary

Contents

1

2

2.1

2.2

2.3

2.3.1

2.3.2

2.3.3

2.3.4

2.3.5

2.3.6

2.3.6.1

2.3.6.2

2.3.7

2.3.8

2.3.9

2.3.10

Syntax (SVNNA)

2.3.10.1

2.4

3

3.1

3.1.1

3.1.2

3.2

3.2.1

3.2.2

3.2.3

3.2.4

3.2.4.1

3.2.4.2

3.2.4.3

3.2.4.4

3.2.5

3.2.6

3.2.7

3.2.7.1

3.2.7.2

Syntax `(SVNNA)`