FrontEnd Module Modifications And Extensions (changes)

Showing changes from revision #1 to #2: Added | Removed | Changed

FRONTEND MODULE MODIFICATIONS AND EXTENSIONS                     15-Jun-2001
RELEASED                                                         2503,128/AN
(C) PACE MICRO TECHNOLOGY PLC 2001                                   Issue C


OVERVIEW
========

This document principally describes additions and modifications to the
FrontEnd module formally documented in the "Desktop Tools" manual that
shipped with the Acorn C/C++ product. Internal version numbers of this
module have increased beyond that of the last shipped version due to build
changes, but there were no behavioural changes until FrontEnd 1.22, which
introduced a few extensions and fixes, and FrontEnd 1.23, which introduced
a larger number of changes including a selection of new rule types. In
FrontEnd 1.24 the module refuses to die if in use (avoiding the often fatal
crashes associated with accidentally soft-loading a new FrontEnd module on
top of a copy already supporting application instantiations). In FrontEnd
1.25, side-effect running of some rule types takes place; by FrontEnd 1.27
this work was basically complete. It is the difference between previously
released FrontEnd modules and 1.27 which is described in this document.


NEW ON/OFF USES
===============

The keywords "on" and "off" may now be used for icon and menu entry
declarations. Where "on" is absent, "on" is taken as implicit. For example:

  icn 23 maps_to "-outputme";
  "Menu entry" maps_to "-menuselected";

...do the same as:

  icn 23 on maps_to "-outputme";
  "Menu entry" on maps_to "-menuselected";

...whereas:

  icn 23 off maps_to "-outputme";
  "Menu entry" off maps_to "-menuselected";

...would only contribute the relevant strings to the command line when icon
23 or the named menu entry were *not* selected/ticked. When used for icons
that do not logically have an 'on' or 'off' state the "off" rule is
generally ignored, but modifiers on it may have side-effects. For example,
"prefix_by" is only relevant for writable fields, so if icon 15 was a
writable field, the following would give different results depending on the
order of appearance in the Desc file:

   icn 15 on  maps_to "-don "  string prefix_by "-D";
   icn 15 off maps_to "-doff " string prefix_by "-U";

If ordered as shown, the prefix would be "-D". If reversed, the prefix would
be "-U". Either way, "-don ..." would appear in the command line whenever
the writable field was not empty.

In FrontEnd 1.27, it is still not possible to both follow with an icon and
prefix at the same time. For example, if icon 20 is an option button, 21 is
a label and 22 a writable, the following is *not* possible:

   icn 20 on maps_to "-e " followed_by icn 22 prefix_by "-INCL";
   icn 22 maps_to "";

However the desired effect can be achieved as follows:

   icn 20 maps_to "";
   icn 22 maps_to "-e " string prefix_by "-INCL";


NEW DISPLAY BEHAVIOUR
=====================

Prior to version 1.22 FrontEnd would output control codes as they arrived.
This could be fatal for some binary files which might output VDU sequences
to do things like redirect output to a printer which wasn't connected.

By default, FrontEnd now shows any control character (i.e. codes &00-&08,
&0A-&1F inclusive and &7F) as a question mark, '?'. Tab (code &09) is
handled properly, though by default the tab width is 1, so it is shown as
a single space, as before. This behaviour can be modified by placing a new
item in the "metaoptions" section, "ctrl_chars". It must be placed after all
previously defined options (i.e. not before the place the default display
type, "display_dft_is <type>", would be written - see the "PARSER ISSUES"
section for more information).

There are three types of output:

   ctrl_chars text        - behaviour as described above, similar to older
                            versions of FrontEnd.
   ctrl_chars escape      - replace control characters in !Edit-style, i.e.
                            lower case two-digit hexadecimal in square
                            brackets - e.g. "[1f]".
   ctrl_chars hide        - do not show control characters at all.

In addition, tab width may be specified after the control characters option:

   tab_width <n>

The number <n> may be 0 (to hide tabs), 1 (for old-style behaviour of
showing a single space), or another integer up to 32, which defines true
tab points of the given width.

This extra display behaviour means that lines of output must be printed
character by character as opposed to whole lines at a time. There is a small
speed penalty as a result, but redraw is still acceptably fast on an issue 1
A5000 class machine. If a process is outputting large volumes of text, it
always was and continues to be recommended that the display is changed to
the summary (e.g. by adjust-clicking on the window's Close icon) or the
scroll bar moved upwards to stop the window scrolling with new output.

Note that when the output of the display window is saved, the file will
contain the actual data FrontEnd received, rather than (say) a text snapshot
of the display window contents.

Finally, FrontEnd 1.22 and later draw lines as they are output. In earlier
versions lines were only output when complete, so any sort of linear
progress indicator wasn't feasible. Now lines are drawn as they are output,
so outputs such as a series of dots or ASCII art progress bar will work. The
side-effect is that there is no need to flush the last line of output on
task exit, so when saving the text of the display window, the spurious blank
line that used to appear will no longer be present.

NB - a full compliment of line ending types (CR, LF, CR + LF, LF + CR) is
     supported by FrontEnd 1.17 and later.


NEW QUOTED STRING OUTPUT TYPE
=============================

In addition to "string" and "number", a new type of output may be specified.
This is "quoted_string". It is very useful when a field may contain spaces,
which may disturb command line parsing if left unhandled. If "quoted_string"
appears, the value of the icon is enclosed in double quotes. Any double
quote character inside the value itself is escaped with '\'. If you have
specified a prefix string with "prefix_by", then all prefixed entries will
be inside the double quotes.

For example, given a writable field at icon 20 holding text 'hello "world"':

   icn 20 maps_to "-display " quoted_string;
   icn 20 maps_to "-display " quoted_string prefix_by "-I";

...would, respectively, result in:

   -display "hello \"world\""
   -display "-Ihello -I\"world\""

Since icons are numbered, it is possible to have an icon output text when
either on or off; for menus, only either on or off. For more details, please
see the "PARSER ISSUES" section.

This feature is available in FrontEnd 1.22 and later.


NEW SELECTION, INCLUSION, AND ON/OFF RULES
==========================================

Prior to version 1.23, FrontEnd allowed "deselects" and "excludes" sections
after the dialogue box and menu regions of the Desc file. Here, icons and
menu entries could be made to deselect or exclude (grey out) other icons or
menu entries. There have been significant extensions in this area.

You may specify "on" or "off" after the "icn" or "menu" keyword at the start
of a line. If both are omitted, "on" is taken as the implicit meaning. For
example, it is possible to say:

   icn 8 deselects 12;
   icn 8 on deselects 12;
   icn 8 off deselects 12;

...where the first two lines mean the same thing and in the second case,
when icon 8 was switched off, icon 12 would be switched off too.

In addition to "deselects" and "excludes", you can now provide "selects" and
"includes" rules. For example:

   selections_start
     icn 3 selects icn 12, icn 14, menu 2;
   selections_end

   inclusions_start
      icn 20 includes icn 21, icn 22;
   inclusions_end

Take note of the "PARSER ISSUES" section regarding the ordering of these new
sections in the Desc file.

Selections can be useful where, for example, turning on a debug option
forces a parser into "strict" mode so that the "strict" switch can be
activated for better user feedback. Inclusions can be useful where, for
example, turning on an option box makes a writable field valid (e.g. an
output filename for some logging text). The availability of inclusions and
exclusions effectively works as syntactic sugar given you can also use
'on' and 'off', bar a small caveat mentioned later (see "NEW GREYING
BEHAVIOUR").

Rules are run recursively. For example, if the user were to switch on icon
4 given the following:

   icn 4 selects icn 5;
   icn 5 selects icn 6;
   icn 6 selects icn 7, icn 8;
   icn 8 deselects icn 5;

then icons 5, 6, 7 and 8 would be selected, but the selection of icon 8
would deselect icon 5, so that would be deselected again. The calculation
of rules is done internally and the front-end updated only with the final
outcome, so for most valid rules minimal flicker would be observed for these
kind of complex rules. Of course, it is clearly possible to define circular
references with this scheme.

Rules are only run recursively when the item in question is not already in
the state it is being changed to. For example, if an icon is selected, a
recursive rule to deselect it would be run. If that deselection led, via.
a circular reference, to an attempt to reselect the icon, rule running would
stop (for that thread of rules) there, since the icon was already selected
to start with. Thus circular references may be written but infinite
recursion is inherently impossible. For example:

   icn 8 on selects icn 8;

   icn 8 off selects icn 8;
   icn 8 on deselects icn 8;

   icn 8 on selects icn 9;
   icn 9 off selects icn 9;
   icn 9 on deselects icn 9;

...would all be spotted and not cause a problem. If bugs in FrontEnd manage
to lead to a locking problem, however, Alt + Break will get out of the loop
cleanly and allow you to debug the Desc file (assuming the task half doesn't
just run out of stack space and exit anyway).

Since it can be confusing to have to split rules across four sections, and
confusing behavioural bugs can result if those sections have accidentally
been put in the wrong order leading to one or more being ignored, a combined
rules section can be given. If this is used in addition to the individual
rules sections, it must appear after them, though it is expected that either
the individual sections or combined section would be used, rather than a
mixture of both.

The general syntax is as follows (indenting is optional):

   rules_start
     <list including> <selects> <list>;
   rules_end

For example:

   rules_start
     icn 3 off selects icn 10;
     menu 3 on deselects icn 4;
     menu 3 on excludes icn 5, icn 6, menu 4;
   rules_end

You can put rules inside the rules_start...rules_end markers in any order
you like. It's only the overall rule sections themselves that must appear
in the Desc file in the order covered in the "PARSER ISSUES" section below.

In FrontEnd 1.23 and later, you may specify a list of items before the rule
keyword, and the rule keyword itself may be singular or plural to suit your
grammatical preferences as shown in the table below.

   ====================   E.g.:
   Keyword     Synonym
   ====================      icn 2, icn 4 off, menu 3 exclude icn 4, menu 5;
   deselects   deselect      menu 1 off, menu 2 on include icn 10;
   selects     select
   excludes    exclude    This is the same as the second example above:
   includes    include
   ====================      menu 1 off, menu 2 includes icn 10;

You *cannot* specify multiple rule types on one line. For example, you might
want something like this:

  icn 10, icn 11 selects icn 4, icn 12, excludes icn 14;

There is ambiguity over whether the 'excludes' refers to icon 12 or the
list of icon 10 and 11, so to avoid any possible understanding, FrontEnd
insists you write this as two separate rules:

  icn 10, icn 11 selects icn 4, icn 12;
  icn 10, icn 11 excludes icn 14;


NEW GREYING BEHAVIOUR
=====================

When an exclusion rule is run (so items get greyed out) or an inclusion rule
is unwound (so again items are greyed out), FrontEnd 1.23 and later do *not*
empty the contents of writable icons or deselect currently selected items.
This was done in earlier versions because the command line construction was
done for all declared items in the SetUp window, regardless of whether they
were greyed out or not. FrontEnd 1.23 and later check that the item is
ungreyed before dealing with command line rules for that item. This makes
for much more user-friendly greying out behaviour.

Internally, FrontEnd keeps a count of the number of times selections or
deselections have led to an icon being greyed or ungreyed, and will only
reflect the change at the front end when the internal counters roll over
the zero point. This means that you can have different parts of a window
greying or ungreying the same things, and the behaviour should all work out
as consistent.

The only thing FrontEnd 1.27 presently does not do is run 'off' rules for
icons which are in a selection group, unless an item in the group that was
previously selected is explicitly deselected (e.g. by the user, or through a
!Choices file setting something in a selection group that is different from
the defaults listed in the Desc file).

For all intents and purposes, a selection group will mean a set of radio
buttons. FrontEnd will check the list of icons deselected when a given item
is selected, and if it finds this leads back to the starting icon, it knows
that a selection group is in use. In this case, running 'off' rules (or
unwinding 'on' rules) would be catastrophic - imagine six radio buttons;
the first is switched on, the next five have their own 'on' rules unwound.
This would slew the internal counters heavily. FrontEnd 1.27 is *not*
clever enough to only ignore the inclusion or exclusion rules of the
deselected items that the selected item will be touching; thus, you cannot
have 'off' rules on any item which is part of a selection group if defaults
are to work. Suppose icon 12 is a radio button:

  icn 12 on includes icn 2, icn 3;

If icon 12 was off, we might expect icons 2 and 3 to be excluded (faded out);
this would not be the case when the dialogue box was initially set up, and
would only take effect when user interaction with the radio group led to the
selection and subsequent deselection of icon 12.


PARSER ISSUES
=============

The parser in FrontEnd is quite strict, but not given to generating warnings
when things aren't recognised (as opposed to recognised, but of invalid
syntax, when FrontEnd becomes quite verbose). Be careful to put the rules
sections in order if you use them:

   1) Selections
   2) Deselections
   3) Inclusions
   4) Exclusions
   5) Combined rules

If you do use a combined rules section, items within it can be listed in any
order. If you use both specific rules sections and a combined rules section,
the combined rules must come last, as shown above.

As a reminder, the full file order must be as follows.

   * Mandatory tool details section:
      - Application name
      - Optional command name
      - Version string
      - Optional filetype of input file
      - Optional minimum Wimp slot size
      - Optional extended command line cue

   * Optional meta-options section, all entries optional:
      - Auto-run
      - Auto-save
      - Has text window
      - Has summary window
      - Default display type
      - Escape or hide control characters
      - Tab width

   * Optional file output section, all entries optional:
      - Output option
      - Default output filename
      - Does it produce output by default?

   * Optional dialogue box section:
      - Icon declarations
      - Optional defaults list
      - Optional imports list

   * Optional menu section:
      - Menu entry declarations and one list of defaults, in any order

   * Optional selections rules section
   * Optional deselections rules section
   * Optional inclusions rules section
   * Optional exclusions rules section
   * Optional combined rules section
   * Optional make exclusions rules list
   * Optional command line ordering list
   * Optional make command line ordering list.

Desc file parsing and syntax errors are now reported through calling SWI
Wimp_ReportError. This will either produce a Wimp error box or print to the
console according to that SWI's documented behaviour. This may have
implications for FrontEnd applications being invoked as part of a wider
action, particularly through Make. Generally speaking it makes developing
Desc files a rather more programmer-friendly process!

If you attempt to include an icon twice with different types (i.e. "string",
"number", "quoted_string") FrontEnd will complain; for example:

   icn 3 maps_to "-ss " string;
   icn 3 maps_to "-sn " number;

...is not valid. This means if you want an icon to contribute to the command
line both in an "off" and "on" state, the type of the thing it contributes
must be the same. For example, simply adding "off" to one of the lines in
the above example would not be acceptable, but:

   icn 3 on  maps_to "-on " string;
   icn 3 off maps_to "-off " string;

...is fine. If you include an icon many times for the same on or off state,
but don't change the type from string or number, FrontEnd will not complain
but will only use the most recently defined entry in the Desc file. Menu
entries do not suffer from this as you can inherently only include an entry
once - if you provide several entries with the same name, each will appear
as an individual entry in the menu itself.


RULE EXECUTION CHANGES
======================

There are changes to the way the deselections and exclusions are handled
when FrontEnd starts up an application and sets the default values in the
SetUp window, then sets the values listed in the !Choices file if present:

 * Icon "On" rules are run when the front end sets up the initial
   defaults listed in the "defaults" section and the item is listed as "On".
   Since the only way to have an item switched on in the window initially is
   to list it in the "defaults" section, this rule will always be run.

 * Icon "Off" rules were not available prior to FrontEnd 1.23. They are only
   run if the "defaults" section specifies explicitly that the item should
   be "Off". Bear in mind how selection group item "off" rules are never run
   and "on" rules are never unwound unless a previously selected item in the
   group is explicitly user-deselected (see "NEW GREYING BEHAVIOUR" for more
   information).

 * The saved front-end !Choices file is executed after setting the default
   values of the SetUp window. Rules for items at this point are only run if
   the state of an item is changed (important since the value of every
   single known item is stored there, and this could play havoc with
   carefully planned rules designed to be activated one at a time when the
   user interacts with your SetUp window). FrontEnd 1.22 and earlier ran all
   rules; this could lead to odd effects including items being greyed out
   (excluded) when not expected, and vice versa.


MISCELLANEOUS CHANGES, HINTS AND TIPS
=====================================

The module assumes that all icons in the SetUp window template are
deselected ("off") to start with. If this is not the case, behaviour will
be undefined.

Note that the button type of any non-writable item must be "Click", so if
you're trying to build a radio group, do *not* use the "Radio" button type
or worry about setting the ESG. You must explicitly specify the deselection
of icons in radio groups with in the deselection rules section of the Desc
file.

You may only select/deselect/include/exclude items that FrontEnd has been
told about. You do this in the "dbox" section for icons. If you, say, wish
to grey out items that are purely decorative and do not map to any specific
command line component, give a null mapping. For icons, this will look
something like the following:

   icn <n> maps_to "";

FrontEnd v1.22 and earlier would tend to abort if rules referenced
undeclared items; later versions tend to bail out of running all rules
related to the errant declaration, failing silently.

When a front-end icon holding the caret is faded, the caret is now hidden
inside the window, rather than left in the faded icon.

ADH, 2001-06-15