
                          Visual DCL

                         User's Guide



                       Widemann Systeme



Information  in  this  document  is  subject  to  change  without
notice  and  does  not  represent a commitment  on  the  part  of
Widemann  Systeme.  The software  described in this  document  is
furnished  under a license agreement  or nondisclosure agreement.
The  software  may be used or copied  only in accordance with the
terms  of  the  agrement.  It is  against the  law  to  copy  the
software  on  any medium  except as specifically allowed  in  the
license  or nondisclosure agreement.  No part uf this manual  may
be  produced  or  transmitted  in  any  form  or  by  any  means,
electronic or mechanical,  including  photocopying and recording,
for  any  purpose  without the   express  written  permission  of
Widemann Systeme.

Copyright  Widemann Systeme, 1993. All rights reserved.

Printed and bound in Germany.


                                                            - i -

                       Table of Contents

Introduction ...........................................  1
    What is Visual DCL ? ...............................  1
    Requirements .......................................  1
    Using this Manual ..................................  1
         Designing Layouts .............................  1
         Developing Dialogues for AutoLISP .............  2
         Developing Dialogues for C or C++ .............  2
         Customising Code Generation for a Development .
         Environment ...................................  2
    Notational Conventions .............................  2
         EBNF ..........................................  2
    Related Documents ..................................  3
Installing Visual DCL ..................................  4
    Hardware Requirements ..............................  4
    Software Requirements ..............................  4
    Installation .......................................  4
         Installing for DOS ............................  5
         Installing for Windows 3.1 ....................  5
         Installing for both DOS and Windows 3.1 .......  5
Configuration ..........................................  6
    Introduction .......................................  6
    General Information ................................  6
    Attribute Defaults .................................  6
    Control Properties .................................  7
    Layout Options .....................................  8
    Languages ..........................................  8
    Miscellaneous ......................................  9
    Switches ...........................................  9
    Controlling Code Generators ........................ 10
    Drive and Path Assignments ......................... 11
Getting Started ........................................ 12
    Invoking Visual DCL ................................ 12
    Editing ............................................ 13
    Saving ............................................. 13
    Generating a DCL file .............................. 14
    Leaving Visual DCL ................................. 14
The Prefix ............................................. 15
The Dialogue Control Data Base (DCB) ................... 16
Languages .............................................. 17
    Introduction ....................................... 17
    Changing the Current Language ...................... 17
    Translating to other languages ..................... 17
Using Dialogue Prototypes .............................. 19
    Introduction ....................................... 19
    Preparing a Dialogue Prototype ..................... 19
    Creating a New Dialogue from a Dialogue Prototype .. 20


                                                           - ii -

Editing a Dialogue ..................................... 21
    Selecting Controls ................................. 21
         Direct Selection .............................. 21
         The Layout Model .............................. 21
         Walking through a DCL Tree .................... 22
    Inserting Controls ................................. 23
         Inserting Single Controls ..................... 24
         Inserting a Group of Controls ................. 25
    Replacing Controls ................................. 25
    Deleting and Undoing a Deletion .................... 26
         Deleting Controls ............................. 26
         Undoing a Deletion ............................ 26
    Changing the Attributes of a Control................ 27
         boxed_column .................................. 28
         boxed_radio_column ............................ 28
         boxed_radio_row ............................... 29
         boxed_row ..................................... 29
         button ........................................ 29
         column ........................................ 30
         concatenation ................................. 30
         DCL ........................................... 30
         dialog ........................................ 30
         edit_box ...................................... 31
         image ......................................... 31
         image_button .................................. 32
         list_box ...................................... 32
         paragraph ..................................... 33
         popup_list .................................... 33
         radio_button .................................. 33
         radio_column .................................. 34
         radio_row ..................................... 34
         row ........................................... 34
         slider ........................................ 35
         spacer ........................................ 35
         spacer_0 ...................................... 35
         spacer_1 ...................................... 35
         text .......................................... 36
         text_part ..................................... 36
         toggle ........................................ 36
    Visual DCL Attributes .............................. 37
    Automatic Recovery ................................. 37
Displaying a Dialogue .................................. 38
Reorganising ........................................... 39
    Introduction ....................................... 39
    The Effect of Reorganising ......................... 39
    Running a Reorganisation ........................... 40


                                                          - iii -

Options                                                  41
    Changing the Audit Level ........................... 41
    Changing the Prefix ................................ 41
    Changing the Language .............................. 41
    Displaying a List of all Keys ...................... 42
    Controlling Layout and Behaviour of the Edit .......
    Dialogue ........................................... 42
         Selecting the Position of the Editor Control ..
         Area .......................................... 42
         Selecting the View of the Layout Model ........ 43
         Controlling Automatic Invocation of Attribute .
         Dialogues ..................................... 43
    Changing the Colours of the Layout Model ........... 43
Dialogue Control Programming (DCP) ..................... 45
    Introduction ....................................... 45
    Preparing a Dialogue for usage with DCP ............ 45
    Using a DCP file ................................... 46
Generating Code ........................................ 47
    Introduction ....................................... 47
    Invoking the Code Generator ........................ 48
    Enabling and Disabling particular Entries .......... 48
    Changing the Destination Path ...................... 49
    Changing Template Assignments ...................... 49
    Changing the Language .............................. 49
    Starting the Code Generator ........................ 50
Templates .............................................. 51
    Introduction ....................................... 51
    Directives and Instructions ........................ 51
         Syntax Rules .................................. 52
         Context Rules ................................. 54
         Format Definitions ............................ 56
         Debug Switch .................................. 56
         Loops ......................................... 57
         Conditional Formatting ........................ 57
         Comment ....................................... 59
         Inserting Items ............................... 60
         Upper and lower case .......................... 63
         Date and Time ................................. 63
         Tabulators .................................... 63
    Protecting Application Code against Overwriting .... 64
Run Time Considerations ................................ 65
    Introduction ....................................... 65
    Loading the DCB Driver ............................. 65
    Invoking the DCB Driver ............................ 65
         An Example using LISP ......................... 66
         An Example using C ............................ 67
    Dynamic Language Switching ......................... 68
    The Integrated DCB Driver .......................... 68


                                                           - iv -

Appendices ............................................. 69
    Templates supplied with Visual DCL ................. 69
         Templates for C ............................... 69
         Templates for C++ ............................. 70
         Templates for LISP ............................ 70
         Templates for Reports ......................... 70
    The Dialogue Tree of Visual DCL .................... 71


                                                            - 1 -

Introduction
============

What is Visual DCL ?
--------------------

Writing  and  testing DCL files is a time consuming task.  Visual
DCL   has   been  designed  to  supply  an  interactive   surface
generating  DCL  files  and displaying  the  result  immediately.
Consequently,  Visual  DCL  is run  as  an  AutoCAD  application.
Furthermore   Visual   DCL  provides   a   series   of   features
rationalising  the  development of AutoCAD  dialogues.  The  code
generators   of  Visual  DCL  produce  skeleton  code   for   the
programming  languages  supported  by  AutoCAD.  Using  templates
makes  code  generation  to  a highly  flexible  instrument.  The
multi  language  support  and  run time  support  round  off  the
capabilities of Visual DCL.


Requirements
------------

It   is   supposed   that  the  reader  is  familiar   with   the
terminology  of  Proteus  and  DCL.  This  manual  can  be   read
without    knowledge   of   the   ADS   interface   of   AutoCAD.
Nevertheless  the  developper  of applications  using  C  or  C++
will need this knowledge, either.


Using this Manual
-----------------

The  Visual  DCL  User's  Guide is  intended  to  be  used  as  a
reference  manual.  The following part of this section  describes
which  chapters are important for particular tasks  supported  by
Visual DCL.


Designing Layouts
-----------------

For this task the chapters
    'Getting Started'
    'Using Dialogue Prototypes',
    'Editing a Dialogue',
    'Displaying a Dialogue',
    'Reorganising', and
    'Options'
are recommended to be read.


                                                            - 2 -

Developing Dialogues for AutoLISP
---------------------------------

Additionally, the chapters
    'Generating Code' and
    'Run Time Considerations'
may be helpful.


Developing Dialogues for C or C++
---------------------------------

The chapter
    'Templates'
is recommended to be read additionally.


Customising Code Generation for a Development Environment
---------------------------------------------------------

For  this  task  the  whole of the Visual DCL  User's  Guide  may
turn out to be relevant.


Notational Conventions
----------------------

There  is  no  extensive  use  of  special  notations.  But   the
chapters  'Configuration' and 'Templates'  contain  syntax  rules
expressed in the meta language EBNF.


EBNF
----

The  abbreviation  EBNF denotes the N. Wirth's  extension  of the
Bacus Naur Form (BNF). As this meta language provides an easy way
to express syntax rules. A  short informal  description  of  EBNF
is given below.  Rules are used to describe how  new symbols  are
derived  from  symbols by combining or selecting  other  symbols.
This is written as an equation of the form

    symbol   =   expression.


                                                            - 3 -

There   are   several  ways  of  combining   symbols,   i.e.   of
constructing expressions:

   symbol1 symbol2    (multiplication, a sequence of two symbols),
   symbol1 | symbol2  (addition, two alternative symbols),
   [ symbol ]         (optional symbol),
   { symbol }         (optional iteration of symbol).

Parenthesis  are  used to break priority rules in  the  same  way
as in algebraic expressions.
Symbols  derived  from other symbols (non terminal  symbols)  are
printed  italic.  Symbols  not derived  from  other  symbols  are
printed  bold.  Any  printable character is  represented  by  the
symbol 'anyany', but, as in the example

    string       =   "{any}".

the  symbol  following  one  ore more  'any's  (here  the  ")  is
excluded  from the set represented by 'any'. Expressions  of  the
form   (  a  b ) c  or  a ( b c )  are shortened to  a  b  c.  In
the  same way, expressions of the form  ( a | b ) | c   or   a  |
( b | c )  are shortened to  a | b | c.


Related Documents
-----------------

AutoCAD   Customisation Manual

AutoCAD   Development System, Programmer's Reference Manual

AutoCAD   AutoLISP, Programmer's Reference Manual


                                                            - 4 -

Installing Visual DCL
=====================

Hardware Requirements
---------------------

The hardware requirements for running AutoCAD Release 12 or later
on a IBM PC AT or a compatible cover the requirements for running
Visual DCL.  The graphics screen must have a resolution of 1024 x
768, at least; i.e.

    high resolution screen, recommended: 19" monitor,
    Mouse or digitizer.
    besides, the same hardware as for AutoCAD.

Visual  DCL  is protected by a hardlock device. This  has  to  be
plugged  on  a  parallel  port. The Demo Version  of  Visual  DCL
runs without a hardlock device.


Software Requirements
---------------------

As  Visual  DCL  is run as an AutoCAD application,  the  software
requirements are  determined  by the  software  requirements  for
AutoCAD Version 12 or later or AutoCAD for Windows, respectively:


Installation
------------

Plug the  hardlock device  supplied with Visual DCL on a parallel
port.


                                                            - 5 -

Installing for DOS
------------------

Insert  the  Visual  DCL  diskette for the  DOS  Version  in  the
appropriate  drive. As an example it is assumed that  this  drive
is a:. Then, on the DOS command line type

    a:install

and  press   the  'RETURN'  key.  The  installation program  will
ask  for  the  drive  and  path, where  the  executables and  the
auxiliary files needed by Visual DCL  are to  be  copied to.  You
can  either confirm the suggestion by pressing 'RETURN'  or  type
a  different  drive and path.  The installation  can  be  stopped
at any time by pressing the 'Esc' key.


Installing for Windows 3.1
--------------------------

The  installation  for Windows 3.1 is done  in  nearly  the  same
way as the installation for DOS:
Insert  the  Visual DCL diskette for the Windows Version  in  the
appropriate  drive. As an example it is assumed that  this  drive
is a:. Then, on the DOS command line type

    a:install

and press the 'RETURN' key. The installation program will ask for
the drive and path, where the executables and the auxiliary files
needed by Visual DCL are to be copied to. You can  either confirm
the suggestion by pressing 'RETURN' or type a different drive and
path.
The  installation  can  be stopped at any time  by  pressing  the
'Esc' key.


Installing for both DOS and Windows 3.1
---------------------------------------

In  order  to  install Visual DCL for both DOS and  Windows  3.1,
the  two  installations described above  have  to  be  done.  The
installation  program  suggests  different  paths  for  DOS   and
Windows 3.1.

Typing  the  drive and paths explicitly, note that they  must  be
different for DOS and Windows 3.1.


                                                            - 6 -

Configuration
=============

Introduction
------------

When started, Visual DCL reads its configuration file
    'ACL_VDCL.INI'.
This file is expected to reside  in  the same  directory  as  the
executable. The configuration file is organised by grouping para-
meters belonging to the same topics. The  general  format  of the
configuration file is determined by the syntax rules

    configuration_file =   { topic } EOF.
    topic              =   [ topic_name ] EOL
                           { parameter }.
    parameter          =   parameter_name = [ value_list ] EOL.
    value_list         =   value{ value }.
    value              =   number | identifier | string.

The  symbol parameter_name represents a key word among a  set  of
key  words  assigned to each topic. The type of value depends  on
the  context  made  up  by  the topic,  the  parameter,  and  the
position within a value_list.

The  subsequent  sections describe the topics and their  specific
parameters.


General Information
-------------------

Currently,  the  parameters  of the  topic  [general_information]
are treated as comment.


Attribute Defaults
------------------

The topic [attribute_defaults] containes the three following para-
meters.

The default colour of images is specified by

    parameter = image_color = number EOL.


                                                            - 7 -

where  number  is  decimal number in the  range  0  through  255.
Correspondingly,   the  default  colour   of   image_buttons   is
specified by

    parameter = image_button_color = number EOL.

The   automatic   invocation  of  the  attribute  dialogues   are
controlled by the parameter

    parameter = immediately = ( ON | OFF ) EOL.

The  value  ON specifies automatic invocation; and the value  OFF
supresses automatic invocation.


Control Properties
------------------

For  the  topic [control_properties]  there  is
one  parameter for each control_type. Three values  are  assigned
to each control type,

    parameter    = control_type = even_colour odd_colour type_switch EOL.
    control_type =   DCL                 | boxed_column
                   | boxed_radio_column  | boxed_radio_row
                   | boxed_row           | button
                   | column              | concatenation
                   | dialog              | edit_box
                   | image               | image_button
                   | list_box            | paragraph
                   | popup_list          | radio_button
                   | radio_column        | radio_row
                   | row                 | slider
                   | spacer              | spacer_0
                   | spacer_1            | text
                   | text_part           | toggle
                   | selection.
    even_colour  = number.
    odd_colour   = number.
    type_switch  = ( ON | OFF ).

where  even_colour and odd_colour are numbers in the  range  from
0  through  255,  representing the colours of  the  layout  model
(see  chapter  'Options', section 'Changing the  Colours  of  the
Layout  Model').  Specifying the type_switch  of  a  control_type
by  the  value  OFF  will  exclude  this  control_type  from  the


                                                            - 8 -

list_box   in   the   dialogues  for  inserting   and   replacing
controls.
As an example, the line

    slider = 241 241 OFF

would cause Visual DCL to forbid sliders.

Note  that  in  the case of tiles the colour of the layout  model
is  specified  by too equal numbers. The colours  of  the  layout
model can be changed using the 'Colours' dialogue.

Layout Options
--------------

The view level of the layout model is specified by

    parameter = levels = ( 1 | 2 ) EOL.

The  position  of the editor control area is determined by the

    parameter = control_below = ( ON | OFF ) EOL.

If  the  value ON is specified, the editor control is  placed  at
the lower  part of the edit dialogue. Otherwise,  it is placed at
the right hand side.

These   parameters  also  can  be  changed  using  the   'Layout'
dialogue.


Languages
---------

The topic [languages] supports the following parameters:

The default names of the five languages supported  by  Visual DCL
are specified by

    parameter = language = name0 name1 name2 name3 name4 EOL.

name0  through  name4 are strings denoting the  desired  language
(each in any appropriate language).





                                                            - 9 -

The  default  language  used  when  creating  a  new  dialog   is
controlled by the

    parameter = default = ( 0 | 1 | 2 | 3 | 4 ) EOL.

The value (0 through 4) is the language  index. This  default can
also be changed using the 'Languages' dialogue.

The  language,  spoken by Visual DCL (not by the dialogue  to  be
edited) is specified by the

    parameter = editor = ( 0 | 1 | 2 | 3 | 4 ) EOL.

Note   that  currently  only  the  indices  0  (german)   and   1
(english) are supported.


Miscellaneous
-------------

The  topic  [miscellaneous] is used to preset the audit level and
the prefix:

    parameter = audit_level = ( 0 | 1 | 2 | 3 ) EOL.

    parameter = prefix = "letter (letter | digit)" EOL.

These  defaults  can  also  be changed using  the  'Change  Audit
Level'    dialogue    and   the   'Change    Prefix'    dialogue,
respectively.


Switches
--------

The topic [switches] is reserved for future use.


                                                           - 10 -

Controlling Code Generators
---------------------------

The topics
    [templates_c]        (C code),
    [templates_cpp],     (C ++ code),
    [templates_lsp],     (LISP code),
    [templates_user],    (user specified code generators), and
    [templates_report],  (reports)
each   contains   one  line  for  each  code  generator   to   be
specified,

    parameter     = title
                    type
                    template_dir
                    template_name
                    target_dir
                    target_name
                    enabled
                    EOL.
    title         = string.
    type          = ( DCL | DCP | TPL ).
    template_dir  = vdcl_dir | app1_dir | ... | app9_dir.
    template_name = string.
    target_dir    = app1_dir | ... | app9_dir.
    targen_name   = string.
    enabled       = ( ON | OFF )

The  value  title  is  a  string of up to 30  characters  and  is
displayed   as  a  generator  name  in  the  'Program  Generator'
dialogue.  The  value type controls the type  of  code  generator
to  be  used. The template_dir and the target_dir must be  chosen
from  the  fixed  sets as indicated above. The drives  and  paths
represented   by  them  are  specified  by  the  topic   [paths],
described below.
The  value  template_name is a string specifying  the  file  name
of  a  template  (without drive and path). The value  target_name
is  a  string representing either a file name (without drive  and
path)  or  a  pure file name extension preceded  by  a  dot.  The
value  enabled  controls if the corresponding code  generator  is
enabled by default.

Note  that  the  'Program Generator' dialogue processes  the  top
nine entries of each topic, only.




                                                           - 11 -

Drive and Path Assignments
--------------------------

The topic [paths] is used to assign real drive and  path names to
a fixed set of symbolic paths:

    parameter   = path_symbol = string EOL.
    path_symbol =   vdcl_dirvdcl_dir
                  | app1_dirapp1_dir
                  | app2_dir
                  ...
                  | app9_dir.

vdcl_dir  is  reserved  for specifying an installation  directory
for Visual DCL.



                                                           - 12 -

Getting Started
===============

This  chapter  describes a first short walk  through  some  basic
functions  of Visual DCL, in order to get familiar with  the  way
how  Visual  DCL  works. Therefore, this description  is  neither
systematic nor complete.


Invoking Visual DCL
-------------------

Visual  DCL  can  be  invoked in the  same  way  as  any  AutoCAD
application can be invoked.

A  first  method is loading the executable and starting  it.  The
following  example  assumes that Visual DCL  has  been  installed
using  the  default  drive  and  path  'C:\ACL_VDCL'.  Then   the
loading is done by the AutoLISP command

    (xload "C:\ACL_VDCL\ACL_VDCL.EXP")

The subsequent command

    ACL_VDCL

starts Visual DCL.

Loading  could  be automated inserting the xload  command  in  an
'ACAD.LSP' file residing in a directory known to AutoCAD.

However,  it  is  recommended  to use  the  file  'ACL_VDCL.LSP',
supplied by Visual DCL. Inserting the line

    (autoload  "ACL_VDCL.LSP"  '("vdcl") )

in  the  'ACADR12.LSP'  (or  an  equivalent  file,  respectively)
before starting AutoCAD will define the command

    vdclvdcl

for starting Visual DCL.

Visual  DCL  starts  displaying its logo.  The  Demo  Version  of
Visual  DCL  requires  pressing the 'OK' button.  Then  the  main
menu appears.


                                                           - 13 -

Editing
-------

Activate  the  'File:' popup_list from the main menu  and  select
the  entry  'new'. Then the edit dialogue is displayed.  There is
an editor control area surrounded by red lines.  Note  that, as a
first control,  a button  has already been inserted.  It  can  be
replaced  by  a control  of  any  other type.  This  is  done  by
pressing the 'Chg' button. Select the desired  control  type from
the  list box of the 'Replace Control' dialogue  and  press 'OK'.
Press  the  'Ins' button  in order to  add another  control.  The
'Insert Control' dialogue  is similar  to  the  'Replace Control'
dialogue. Use the 'Attributes' button  to activate an appropriate
attributes  dialogue. This displays  the names and pre-set values
of  the  attributes allowed  for  the  currently selected control
type. Change the attributes and press 'OK' when ready.

The coloured image button, the layout model, shows now a rectang-
le  containing two smaller rectangles  representing the two  con-
trols. One of the four arrows of the tree walk button is enabled.
Pressing it makes  the  other control the currently selected one.
An identifier, the  control  type,  and the  label  (if  any)  of
the currently selected  control  is displayed  as text within the
editor control area.

Pressing  the  'OK' button of the editor control  area  does  not
complete  the  editing;  it only interrupts  editing  and  passes
control  to  the  main menu of Visual DCL. Editing  is  continued
by selecting the entry  'edit'  of the  'Edit:'  popup list.


Saving
------

Activate the 'File:' popup list of the  main menu  and select the
entry 'save as'.  The standard file menu  titled 'Store DCB File'
is invoked. Visual DCL  stores all information about the dialogue
being edited in a so called 'Dialogue  Control  Data Base' (DCB).
The file name extension is '.DCB', either.  After the successfull
completion  of the saving, the file name  (without extension)  is
displayed at the lower part  of  the  main  menu, indicating that
now the generating of code is enabled.






                                                           - 14 -

Generating a DCL file
---------------------

Activate  the  'Generate:' popup list of the main menu and select
the  entry '-> ANSI C'.  Then the  'Visual DCL Program Generator'
dialogue is displayed. There is  one row titled  by  'DCL  file'.
Enable this row using the corresponding toggle, disable the other
rows,  and  press  'OK'.  After  the desired  DCL  file  has been
written, Visual DCL returns the control to the main menu.


Leaving Visual DCL
------------------

Activate the 'File:' popup list of the main menu  and  select the
entry 'quit'. If changes have been made since the last saving, or
since the last opening  or creating a new dialogue, respectively,
Visual DCL asks 'Save changes?'. Answer pressing the 'Yes' button
if changes have to be saved.  Press the  'No'  button  if changes
have to be discarded.

Now  the  'Quit Visual DCL' dialogue is displayed. The  state  of
a    toggle    indicates   changes   with    respect    to    the
configuration. Leaving Visual DCL while this toggle  is  switched
on, will update the configuration  file.
Switch  the  toggle off if changes of the configuration  have  to
be  discarded.  Then  press  the 'Yes'  button  for  leaving,  or
press the 'No' button for returning to the main menu.


                                                           - 15 -

The Prefix
==========

The prefix supported by Visual DCL is intended  to be used as the
name of the  parameter structure  to be defined in C or C++ code.
Apart from this, it is used as the prefix of control identifiers.

The  prefix  consists  of exactly two letters,  where  the  usual
identifier syntax of programming languages is required.


                                                           - 16 -

The Dialogue Control Data Base (DCB)
====================================

This  chapter  is purely informal. Because  the term  'DCB' plays
a central role  for  using  Visual DCL, the developer should know
what a DCB is.

Visual   DCL   stores  all  data  describing   a   dialogue   and
contributing to produce

  *  a DCL file,
  *  a DCP file  (see  chapter  'Dialogue Control via Programming
     (DCP)'),
  *  a set of C or C++ source files for a application skeleton,
  *  a LISP code skeleton, or
  *  corresponding reports

in an internal data base, called  a  dialogue control  data  base
(DCB). Saving creates  a binary file which is called a DCB,  too.
Therefore, the file name extension '.dcb' is used.

Thus  a  DCB  is  the central format of a data  collection,  from
which  Visual  DCL derives all it needs in order to  provide  its
features.

Multi  language  support  for up to 5 different  languages  needs
only one DCB per dialogue.
Furthermore,  there  is  a run time support  for  DCBs.  This  is
supplied by the DCB driver. It

  *  loads a DCB file,
  *  converts it to a  temporary DCL file  in the one of the five
     languages spoken by the DCB,
  *  loads this  temporary DCL  file using 'ads_load_dialog', and
  *  immediately deletes it.

In  this  way,  the  DCB  driver makes DCL  files  invisible  and
supports  dynamic  language  switching.  For details  see chapter
'Run Time Considerations'.

This  is  already all, what the developer should know  about  the
term DCB.


                                                           - 17 -

Languages
=========

Introduction
------------

In   the  data  base  storing  the  information  describing   the
dialogue   being   edited  (DCB),  Visual  DCL   maintains   five
languages  in  parallel.  Visual DCL  does  not  prescribe  which
languages   are   used,   but   provides   the   language indices
through 4. The  configuration  assigns a default language name to
each of the language indices.


Changing the Current Language
-----------------------------

See the section 'Languages' of the chapter 'Options'.

In  principle,  translation can be done by changing  the  current
language  and  changing  the  appropriate  attributes  using  the
attribute  dialogues (see the section 'Changing Attributes  of  a
Control'  of  the  chapter 'Editing'). A more convenient  way  to
perform   the  task  of  translation  is  using  the  translation
dialogue described below.


Translating to other languages
------------------------------

Activate   the   'Edit:'  popup  list  and   select   the   entry
'translate'.  The dialogue  titled 'Translate' is displayed.  The
list box  labelled  'text'  shows  all  string attributes,  being
subject of translation, i.e. the attribute types

    label,
    help_file,
    help_topic,
    info_name,
    list,
    mnemonic, and
    slide_name.

The  attribute type of the currently selected text  is  displayed
below  the  list  box. The language in which  the  texts  in  the
list  box  are shown can be switched using the radio  buttons  in


                                                           - 18 -

the  middle  of  the dialogue box. On the right hand  side  there
are  edit  boxes displaying the currently selected  text  in  the
five  languages. Here the translation can be done.  Pressing  the
'copy  text from the actual language' selects the text  from  the
actual  language  and  copies it to  the  other  four  languages.
Pressing   the  'OK'  button  stores  the  changes  done,   while
pressing  the  'Cancel' button discards. All changes  done  since
the invocation of the 'Translate' dialogue.


                                                           - 19 -

Using Dialogue Prototypes
=========================

Introduction
------------

Many  dialogue  layouts of an application appear  uniformly  with
respect  to  certain  parts.  Particularly,  the  buttons   'OK',
'Cancel',  'Help',  and 'Info' are preferably represented  in  an
uniform   way   with  respect  to  size,  shape,  ordering,   and
location.  Visual  DCL supports starting the layout  design  from
prototypes    realising   skeleton    dialogues stored  as  DCBs.
Therefore, such  prototypes  can be prepared  using Visual DCL in
exactly the same way  as  for  any other  dialogue  to be edited.
However, it  is  recommended  to store dialogue prototypes in   a
separate directory.
Subsequently,  this  will  be  assumed.  The  following   section
discusses  some  specific  aspects  of  using  Visual  DCL   when
preparing  dialogue  prototypes. A further section  shows  how  a
dialogue  prototype  is  used to create a complete  dialogue  (or
another dialogue prototype).


Preparing a Dialogue Prototype
------------------------------

While   there  is  nothing  special  about  editing  a   dialogue
containing  a set of controls planned to be reused, it  might  by
helpful to point out the following aspects:

  *  Keys  of  buttons  like  'OK',  'Cancel', etc.  can be given
     names, already now.
  *  More  generally, it may save time if as many  attributes  as
     possible are specified.
  *  Particularly,   check  if  the  attributes  'is_cancel'  and
     'is_default' are specified.
  *  It  might  even  be  useful to build an executable  skeleton
     application from a prototype, before using it as such.
  *  If  multi  language support is planed to be used,  translate
     all texts to the required   languages,  in  order  to  avoid
     repeating the same work when using the dialogue prototype.



                                                           - 20 -

Creating a New Dialogue from a Dialogue Prototype
-------------------------------------------------

Activate  the  'File:'  popup list of the Visual  DCL  main  menu
and  select  the entry labelled by 'new from'. Then the file menu
titled  'Open  Source File' appears. Change to the directory con-
taining  the desired dialogue  prototypes,  select the individual
prototype  you want  to start from, and  press  the 'OK'  button.
Another   file  menu  titled   'Open  Destination File'  appears.
Specify the file name of the new dialogue to be created by typing
it  or selecting it from  the  corresponding list box  and  press
the 'OK' button. Now Visual DCL  displays the  selected prototype
for editing. As usual the new file name is displayed  in the main
menu; i. e. after having been  edited, saving  will  be  achieved
by selecting 'save' from the 'File:' popup list.



                                                           - 21 -

Editing a Dialogue
==================

Selecting Controls
------------------

As  Visual  DCL  itself  works with  Proteus,  an  instrument  is
needed   for   making   selectable   each   individual   control.
Selection of controls is needed for the following reasons:

  *  Inserting  a control is done above, below, on the  left,  or
     on the right hand side of the    control currently  selected
     (where the directions are  restricted  by  the  type  of the
     containing cluster) .
  *  Changing a control replaces the selected control.
  *  Deleting a control eliminates the selected control.
  *  Undoing a deletion is similar to insertion.
  *  Specifying  Attributes  relates  to  the  control  currently
     selected.

Therefore,  a  first  section  of  this  chapter  describes   how
Visual DCL supports selection.


Direct Selection
----------------

The  most  natural  method  of selecting  a  control,  simply  by
moving  the  mouse  pointer to it and  click,  is  restricted  to
some of the active control types, listed below:

    button,
    image_button,
    list_box      (by selecting an entry if any),
    popup_list    (by selecting an entry if any),
    radio_button,
    slider, and
    toggle.


The Layout Model
----------------

Visual  DCL  provides  a square shaped image button  representing
a model of the dialogue layout currently being edited.



                                                           - 22 -

This    representation   is   designed   to   map   the    layout
structure, not the dimensions of the controls. Indeed, the layout
model maps  the   tree structure  of the corresponding  DCL.  All
controls appear as rectangles. A control  representing a cluster,
contains  one  or  more  rectangles representing  other controls,
which may correspond to tiles or clusters again  and so on.

The  orientation  is  improved  by using  different  colours  for
different  groups of control types.  A problem  would  arise,  if
nested  clusters of the same control type  had  the  same colour.
Therefore, the colours of clusters alternate  with  even and  odd
levels of nesting.  The colours used in the  layout model  can be
configured  (see the section 'Colours' of the chapter 'Options').

Clicking  at  a  particular rectangle  inside  the  layout  model
changes its colour  to a certain colour indicating  selection.  A
text  displayed near the layout model tells the id,  the  control
type, and the label (if any) of the selected control.

The  resolution of the layout model being limited  by  the  space
occupied,   Visual   DCL   performs  automatic   zooming. The way
this is done, may be influenced   by   a configuration  parameter
(see  the section  'Controlling  Layout and Behaviour of the Edit
Dialogue' of the chapter 'Options').


Walking through a DCL Tree
--------------------------

While  the  layout model supports a kind of random  selection  of
controls,  as  a  supplementary,  incremental  selection  method,
Visual DCL provides "selection by tree walk".

We   start   remarking  that  the  two  vertical  and   the   two
horizontal  directions, relevant for the layout  of  a  dialogue,
are  determined  by  the  enclosing clusters,  which  are  either
horizontal  or  vertical. The latter not  always  being  visible,
renders   the  optical  orientation  more  difficult.  For   this
reason,  the  tree  walk button of Visual DCL has  been  designed
to facilitate orientation.

The tree walk  button  represents six "arrows".  Four of them are
shown in the used manner.





                                                           - 23 -

The   left   arrow  is  highlighted  if  the  currently  selected
control  is  contained  in  a  horizontal  cluster,  i.e.  in   a
boxed_row,   a  row,  a  boxed_radio_row,  a  radio_row,   or   a
concatenation  and  if  additionally this  cluster  contains  any
control  at  its  left  hand side. Clicking  to  the  left  arrow
changes  the  current  selection to the left  neighbour  control.
The  right,  up,  and  down arrow behaves  correspondingly.  Note
that these movements do not change the level in the DCL tree.

The  small  rectangle in the centre of the figure is  highlighted
if  the  current  control has children. Clicking  at  it  selects
the first, i.e. the most left or top, child control, respectively.

The   surrounding  rectangle  is  highlighted  if   the   current
control  has  a parent control. Clicking  near  one of  its edges
selects this parent control. Note that for Visual DCL the control
'dialog' has a parent pseudo control denoted by 'DCL'.

Each  movement  can  change the situation.  Therefore  the  whole
figure is updated according to the new situation.


Inserting Controls
------------------

Pressing the 'Ins' button of the editor control area,  a dialogue
titled  'Insert Control'  is  displayed.  Decisions have   to  be
made  about  inserting "where", about inserting "what", and about
inserting "how many". The latter  is  treated in  a different way
for  clusters  and for tiles,  as  described below.  Furthermore,
inserting inside of radio clusters is restricted.

We  start  discussing  the decision about  the  location  of  the
insertion.
In  the  upper area or the 'Insert Control' dialogue,  there  are
four  radio  buttons  forming a cross. Their  labels  denote  the
two  pairs  of  possible directions, left or right and  above  or
below.  Only  one  pair  of directions is enabled  at  any  time,
depending on the enclosing cluster.

If the enclosing cluster belongs to one of the horizontal control
types, i.e.
    boxed_row,
    boxed radio row,
    concatenation,
    radio_row, or
    row,

                                                           - 24 -

insertion  on  the left hand side or on the right  hand  side  of
the  selected  control is possible. In this case the  default  is
set to 'right'.

If,  on  the contrary, the enclosing cluster belongs  to  one  of
the vertical control types, i.e.
    boxed_column,
    boxed_radio_column,
    column,
    dialog,
    paragraph, or
    radio_column,
insertion  above  or  below  the currently  selected  control  is
possible. In this case the default is set to 'left'.

In  the  middle  of the directions cross there is  a  popup  list
labelled   'times'.  The number (from one through ten) selectable
has a different meaning for
  *  tiles    (see the section 'inserting single controls' below)
     and for
  *  clusters (see  the  section  'inserting  groups of controls'
     below).
A  list  box  contains the names of the controls of  both  types,
listed  in  alphabetical order. This list represents the  control
types  supported  by  Visual DCL.  The  control  type 'dialog' is
skipped, because  this  is  already  inserted   by creating a new
dialogue.


Inserting Single Controls
-------------------------

The controls of the types
     button,                edit_box,            image,
     image_button,          list_box,            popup_list,
     radio_button,          slider,              spacer,
     spacer_0,              spacer_1,            text,
     text_part,             toggle
are  inserted  as  often as specified by the number  selected  in
the 'times' popup list.


                                                           - 25 -

Inserting a Group of Controls
-----------------------------

The controls of the types
     boxed_column,          boxed_radio_column,  boxed_radio_row,
     boxed_row,             column,              concatenation,
     paragraph,             radio_column,        radio_row,
     row
are  inserted  as  a  group,  where  the  selected  control  type
contains  as  many buttons or radio buttons as specified  by  the
number selected in the 'times' popup list.

Trying  to  insert another control type than a radio_button  into
a  radio  cluster,  displays  a warning  dialogue  prompting  for
confirmation.  In  this case insertion of spacers,  i.e.  spacer,
spacer_0  and  spacer_1,  is allowed,  while  for  other  control
types  Proteus  will display a warning. This may  depend  on  the
audit   level,  currently  set.  If  Proteus  detects  an  error,
Visual  DCL  invokes  its  automatic recovery  (see  the  section
'Automatic Recovery' below).


Replacing Controls
------------------

Pressing the 'Chg' button  of the editor control area  displays a
dialogue titled 'Replace Control'. Apart from another title, this
dialogue is the same as the 'Insert Control' dialogue.  Therefore
a detailed description  would  be  a repetition  of  the  section
'Inserting  Controls'.  Hence, we concentrate to the differences.

Replacing  a  control  or  a group of controls  (i.e.  a  cluster
containing   other  controls)  is  very  similar   to   inserting
controls  or  groups of controls. Indeed, the only difference  to
insertion  is  made  up by the fact, that replacing  deletes  the
control,  currently  selected, and inserts a  new  control  or  a
new  group  of  controls. In this case the location of  insertion
is  determined  already by the location of the  deleted  control.
Therefore, the direction radio buttons are disabled.


                                                           - 26 -

Deleting and Undoing a Deletion
-------------------------------

As  known  from text editors, deleting and undoing a deletion  of
something  is  not only useful in order to remove  something  for
ever  (and  undoing because made by mistake). But these  function
can also be used for rearranging controls.


Deleting Controls
-----------------

Pressing  the  'Del' button  of  the  editor  control  area,  the
currently  selected  control or group of controls,  respectively,
is deleted, and the editor dialogue is refreshed.

We complete this section adding some remarks.

Note   that  deleting  a  group  of  controls,  i.e.  a  cluster,
deletes all controls contained in this cluster.

If  the  dialogue  being  edited contains  only  one  control  or
group  of  controls,  this  cannot  be  deleted.  Therefore,  the
'Del'  button  is  disabled in this situation. The  only  way  to
get rid  of this, is replacing it by another control or (what  is
essentially the same) insert another control, then delete.

Deleting  the  last  control  inside  a  cluster  (excluding  the
control   type  'dialog')  does  not  automatically  delete   the
cluster,  but  leaves an empty cluster. Note that insertion  into
an  empty  cluster is not supported. Therefore  the  quicker  way
is   deleting  the  whole  cluster;  as  mentioned   above,   its
contents is deleted automatically.

Note   that   reorganising  destroys   the   possibility   of   a
subsequent undeletion.


Undoing a Deletion
------------------

A   previously  deleted   control   or  group  of  controls   can
be reinserted   pressing   the  'Undo'  button   of  the   editor
control  area.  In  order  to  specify  the  new  location   with
respect  to  the currently selected control, Visual DCL  displays
a  dialogue  titled  'Undelete Control'.  Like in  the  case   of


                                                           - 27 -

insertion  a  cross  of  radio  buttons  indicate  the   actually
possible  relative  location, where the deleted  control  can  be
reinserted.   The  default  relative  location  is   'right'   or
'below', respectively.

Furthermore,  the 'Undelete Control' dialogue displays  the  type
of the recently deleted control.

Note  that  a  deleted control can be undeleted only  once.  This
is made visible by disabling the 'Undo' button.

If  the  action  is confirmed, by pressing the 'OK'  button,  the
editor dialogue is refreshed.

Under    special   circumstances,   undeleting   can   cause    a
conflict.  A typical example of such  a  conflict  comes from the
following sequence of actions:
  *  insert a button and specify the attribute 'is_cancel=true;',
  *  delete this button,
  *  insert another button and  specify again  'is_cancel=true;',
     and
  *  undelete.
As  Proteus  requires that the attribute 'is_cancel' occurs  only
once  for  the  same  dialogue, Visual DCL displays  a  dialogue,
informing that  the conflicting attributes  are removed  from the
control to be reinserted.


Changing the Attributes of a Control
------------------------------------

As each control type allows another set of attributes, there is a
corresponding set of dialogues supporting  the  specifications of
the  appropriate  attributes.
Furthermore,  there  are  several  methods  for  invoking   these
'Change <control type> Attributes' dialogues:

  *  specify   attributes   when  creating  (i.e.  inserting   or
     replacing)  a  new  control  then
       *  press the 'OK' button and  let  the dialogue be invoked
          automatically, or
       *  press  the  'Attributes' button   instead  of  pressing
          the 'OK' button  of the  'Insert Control'  or  'Replace
          Control' dialogue, or
  *  specify  attributes  selecting the desired  control  in  the
     edit dialogue and
       *  press  the  'Attributes' button  of the  editor control
          area, or
       *  double  click  at  the  corresponding  rectangle of the
          layout model.


                                                           - 28 -

In  any  case  the  appropriate dialogue  is  activated.  If  the
attributes  dialogue  is  invoked  via  inserting  or  replacing,
pressing  the 'Cancel' button cancels the attribute  dialogue  as
well as the insertion or replacing, respectively.

The remainder of this section  summarises the attributes that can
be   specified   for  the  controls  supported  by   Visual  DCL.
Attributes defined by Proteus are printed bold.

boxed_column
------------

    alignment
    children_alignment
    children_fixed_height
    children_fixed_width
    fixed_height
    fixed_width
    height
    label
    width


boxed_radio_column
------------------

    alignment
    children_alignment
    children_fixed_height
    children_fixed_width
    fixed_height
    fixed_width
    has_key
    height
    [ key ]      (if 'has_key' set)
    label
    [ value ]    (if 'has_key' set)
    width


                                                           - 29 -

boxed_radio_row
---------------

    alignment
    children_alignment
    children_fixed_height
    children_fixed_width
    fixed_height
    fixed_width
    has_key
    height
    [ key ]      (if 'has_key' set)
    label
    [ value ]    (if 'has_key' set)
    width


boxed_row
---------

    alignment
    children_alignment
    children_fixed_height
    children_fixed_width
    fixed_height
    fixed_width
    height
    label
    width


button
------

    action
    alignment
    fixed_height
    fixed_width
    height
    help_file
    help_topic
    info_name
    is_cancel
    is_default
    is_enabled
    is_tabstop
    key
    label
    mnemonic
    pick_name
    width


                                                           - 30 -

column
------

    alignment
    children_alignment
    children_fixed_height
    children_fixed_width
    fixed_height
    fixed_width
    height
    width


concatenation
-------------

    alignment


DCL
---

    dialog_name


dialog
------

    aspect_ratio
    initial_focus
    is_positioned
    key
    label
    x_position    (if 'is_positioned' set)
    y_position    (if 'is_positioned' set)


                                                           - 31 -

edit_box
--------

    action
    alignment
    allow_accept
    data_type
    edit_limit
    edit_width
    fixed_height
    fixed_width
    height
    is_enabled
    is_tabstop
    key
    label
    mnemonic
    value
    width


image
-----

    alignment
    aspect_ratio
    color
    fixed_height
    fixed_width
    height
    key
    label
    slide_name
    width


                                                           - 32 -

image_button
------------

    action
    alignment
    allow_accept
    aspect_ratio
    color
    fixed_height
    fixed_width
    height
    help_file
    help_topic
    info_name
    is_cancel
    is_default
    is_tabstop
    key
    label
    mnemonic
    pick_name
    slide_name
    width


list_box
--------

    action
    alignment
    allow_accept
    fixed_height
    fixed_width
    height
    is_enabled
    is_tabstop
    key
    label
    list
    mnemonic
    multiple_select
    tabs
    value
    width


                                                           - 33 -

paragraph
---------

    alignment


popup_list
----------

    action
    alignment
    edit_width
    fixed_height
    fixed_width
    height
    is_enabled
    is_tabstop
    key
    label
    list
    mnemonic
    tabs
    value
    width


radio_button
------------

    action
    alignment
    fixed_height
    fixed_width
    height
    is_enabled
    is_tabstop
    key
    label
    mnemonic
    value
    width


                                                           - 34 -

radio_column
------------

    alignment
    children_alignment
    children_fixed_height
    children_fixed_width
    fixed_height
    fixed_width
    has_key
    height
    [ key ]      (if 'has_key' set)
    [ value ]    (if 'has_key' set)
    width


radio_row
---------

    alignment
    children_alignment
    children_fixed_height
    children_fixed_width
    fixed_height
    fixed_width
    has_key
    height
    [ key ]      (if 'has_key' set)
    [ value ]    (if 'has_key' set)
    width


row
---

    alignment
    children_alignment
    children_fixed_height
    children_fixed_width
    fixed_height
    fixed_width
    height
    width


                                                           - 35 -

slider
------

    action
    alignment
    big_increment
    fixed_height
    fixed_width
    height
    is_enabled
    is_tabstop
    key
    layout
    max_value
    min_value
    small_increment
    value
    width


spacer
------

    alignment
    fixed_height
    fixed_width
    height
    width


spacer_0
--------

    (no attributes allowed)


spacer_1
--------

    (no attributes allowed)


                                                           - 36 -

text
----

    alignment
    fixed_height
    fixed_width
    has_key
    height
    is_bold
    [ key ]      (if 'has_key' set)
    label
    width


text_part
---------

    alignment
    fixed_height
    fixed_width
    has_key
    height
    is_bold
    [ key ]      (if 'has_key' set)
    label
    width


toggle
------

    action
    alignment
    fixed_height
    fixed_width
    height
    is_enabled
    is_tabstop
    key
    label
    mnemonic
    value
    width


                                                           - 37 -

Visual DCL Attributes
---------------------

Visual  DCL  supplies  some  attributes,  not  contained  in  the
attributes  set of Proteus. These additional attributes  have  no
effect   with  respect  to  dialogue  layouts.  They  have   been
designed   to  be  used  in  connection  with  code  and   report
generation,  i.e.  to be retrieved by templates.  There  are  the
following Visual DCL attributes (applying to the controls):

  *  data_type      (edit_box),
  *  dialog_name    (dialog),
  *  has_key        (text, text_part, and radio clusters),
  *  help_file      (button and image_button),
  *  help_topic     (button and image_button),
  *  info_name      (button and image_button),
  *  is_positioned  (dialog),
  *  pick_name      (button and image_button),
  *  slide_name     (button, image and image_button),
  *  x_position     (dialog), and
  *  y_position     (dialog).

For the details see the chapter 'Templates'.


Automatic Recovery
------------------

As  Visual  DCL is involved neither in creating dialogue  layouts
from  DCL  files  nor  in  performing the display  of  dialogues,
Visual  DCL cannot detect if a dialogue will still fit  into  the
screen.  But  Proteus will detect it and will  display  an  error
message.

Visual  DCL  tries  to  recover errors detected  and reported  by
Proteus. This is done in the following way:

  *  The  changes  since the last refresh of the  dialogue  being
     edited  are  discarded  and   another  normally   successful
     refresh is performed. We call this a 'fall back'.

  *  If,  for  any  reason, recovery by fall back  fails,  Visual
     DCL  prompts  for decreasing the  audit level. In some cases
     this may be iterated until the audit level has reached zero.
     In this case there is no further recovery.


                                                           - 38 -

Displaying a Dialogue
=====================

The  view  of  the  dialogue being edited  may  be influenced  by
the  editor  controls. A more realistic view is provided  by  the
display  function  of  Visual  DCL.  In  order  to  activate  it,
select the entry 'display' of the 'File:' popup list.

Under  certain  circumstances,  Visual  DCL  adds  an  additional
button labelled  'Back' at the bottom of  the  dialogue  box  and
separated by a red line.  This  indicates,   that  an 'is_cancel'
attribute has not been specified, yet.

Displaying  without  any  'is_cancel'  attribute  would  cause  a
deadlock   because   the   dialogue   being   displayed   behaves
realistic  in  the  sense  that there is  no  special  call  back
processing    saying    'done_dialog'    or    'ads_done_dialog',
respectively.

Even  if  the  attribute 'is_cancel' has been  specified  for  an
appropriate  control,  this might have  been  disabled.  In  this
case a 'Back' button is added, too.

Note  that adding a 'Back' button, if necessary, applies  in  the
same  way  to  generating DCL files, generating  DCB  files,  but
not to generating DCP files.


                                                           - 39 -

Reorganising
============

Introduction
------------

Visual DCL  attaches a control identifier to each edited control.
This has the format

    pp_nnn

where   pp   is  a  the  prefix,  valid   at   the   moment   the
corresponding  control has been created, and  'nnn'  is  a  three
digit decimal number.

The  control  identifier  of the currently  selected  control  is
displayed in the editor control area.
Furthermore,   Visual  DCL  uses  the  control   identifiers   as
default texts for some types  of string attributes. Particularly,
this applies to labels.

Inserting,  replacing, and deleting controls perturbs  the  order
of numbering and causes gaps.  Subsequent  changes  of the prefix
leads to a set of identifiers with  different prefixes.


The Effect of Reorganising
--------------------------

For  the  above  reasons, Visual DCL provides  a  function,  that
reorganises all  control  identifiers.  The  effects are:

  *  The  prefix of each control identifier is set to the  actual
     value.

  *  The  number  parts are replaced corresponding to  the  order
     resulting from a walk through the DCL tree, where the "depth
     first strategy"   is   applied.  This  means,  each  cluster
     including its complete contents is numbered before any other
     cluster or tile is processed.

  *  String attributes  of the form  'pp_nnn', where 'pp' is  the
     a c t u a l  prefix,  and  'nnn'  is  a  three digit decimal
     number,  are  updated  using  the  new  identifiers  of  the
     controls, they belong to. Note that string attributes of the
     above form which have an  o l d  prefix, remain unchanged.


                                                           - 40 -

Note  that   reorganising  disables  undoing  the  last deletion.
Therefore, ensure that there is no deleted control intended to be
undeleted.


Running a Reorganisation
------------------------

Selecting  the  entry  'reorganise'  from the  'Edit:' popup list
activates a small dialogue. The  action  is  started by  pressing
the 'Yes' button. Alternatively a cancellation is possible.


                                                           - 41 -

Options
=======

Changing the Audit Level
------------------------

Visual DCL  supplies a default as well as  an actual value of the
attribute  'audit_level'  of the control  'default_dcl_settings'.
In order to change it,  select  the entry  'Audit  Level'  of the
'Options:' popup  list.  Then  the  dialogue titled 'Change Audit
Level' is displayed.

Pressing  the  'OK'  button  activates  the  changes  done.   The
default  audit level  is updated  in the  configuration  file  of
Visual  DCL if the 'Save Changes ?' prompt is confirmed  as  soon
as you leave Visual DCL.


Changing the Prefix
-------------------

Originally the prefix is specified  when creating a new dialogue.
For later changes  select the entry  'Prefix'  of the  'Options:'
popup list. Then the 'Change Prefix' dialogue is displayed.

Visual DCL  checks  the length  and  the identifier syntax of the
changed prefix when pressing the 'OK' button.


Changing the Language
---------------------

Most  of  the texts of the dialogue being edited are attached  to
the  actual  language index.  Changing  the actual language means
changing the actual language index  with the  effect that the set
of texts, attached to the new language index will subsequently be
used. For the details see the chapter 'Languages'.

Note  that  changing the actual language is not  intended  to  be
used   for   doing   translation,  because  there   is   a   more
appropriate  method  described  in  the  chapter  'Translating  a
Dialogue'.

Changing  the  actual  language for other  purposes  is  done  by
selecting  the  'Languages' entry of the 'Options:'  popup  list.
Then  the  'Change Language' dialogue is displayed.  The  default


                                                           - 42 -

language  as  well as the actual languages can  be  changed.  Use
the  corresponding toggles in order to determine what  is  to  be
changed.  Then  select  the desired new language  from  the  list
box and press the 'OK' button.

Note  that  the  new  default  language  will  be  updated in the
configuration file of Visual DCL as soon as you leave Visual DCL.


Displaying a List of all Keys
-----------------------------

A list of all keys specified for controls of the  dialogue  being
edited  is  shown   by   activating   the 'Options:'  popup  list
and selecting  the entry  'Key  List'.  Each control having a key
attribute specified displayes the following items in one row of a
list box:

  *  id, the control identifier,
  *  key,the string representing the key,
  *  cb,  an  indicator telling whether the control  allows  call
     back processing,
  *  type, the control type, and
  *  label, the label of the control if any, or blanks,  if there
     is no or an empty label.


Controlling Layout and Behaviour of the Edit Dialogue
-----------------------------------------------------

The   corresponding  dialogue  is  invoked  by   activating   the
'Options:'  popup  list  and selecting  the entry  'Layout'.  The
'Change  Layout'  dialogue,  activated  by  that,  provides three
topics described by the sections below.


Selecting the Position of the Editor Control Area
-------------------------------------------------

The  editor  control area  is  the  area  of  the  edit  dialogue
surrounded by  red lines and  containing   the controls  for  the
editing functions. Editing dialogues covering a large area on the
screen,  the  space  may  become  scarce  in  one  or  the  other
direction. By default the editor control  area  is placed  at the
bottom.  This  default  can  be changed  as  well  as the  actual
positioning of the editor control area. There is  a radio row for
each of both decisions.


                                                           - 43 -


Selecting the View of the Layout Model
--------------------------------------

The  automatic zooming  of the layout model  is controlled by the
number  of  levels  above the   level  containing  the  currently
selected control. This number can be chosen to be one or two.


Controlling Automatic Invocation of Attribute Dialogues
-------------------------------------------------------

The  'Attributes'  button of the 'Insert  Control'  dialogue  and
of  the  'Replace Control' dialogue can be chosen to  be  pressed
automatically  with each insertion and with each  replacement  of
a control. If automatic invocation is selected,  the 'Change  ...
Attributes' dialogues  are  iterated  as  many  times  as  single
controls have been specified.  In the case of  groups of controls
the  automatic invocation,  if specified,  is performed  one time
for specifying  the attributes  of the  containing cluster  to be
created.


Changing the Colours of the Layout Model
----------------------------------------

Activating  the  'Options:' popup list and  selecting  the  entry
'Colours'  displays the dialogue  titled  'Change Colours'.  This
dialogue is dedicated to the specification  of the  colours  used
for  the  particular  parts  of  the  layout model of  the editor
control area.

At  first,  select the control type, the colour or  the  pair  of
colours  which  has  to be changed. In the  sample  layout  model
the  selected  control type is highlighted.  Clicking  repeatedly
at  this  sample  will toggle the colour of a  part  representing
the  selected  control  type, by changing  its  colour  from  the
"highlighting colour" to the colour actually specified.

Note  that  at  the  end  of  the  control  types  list  box  the
highlighting colour  has an entry denoted by 's e l e c t i o n'.
Select it for changing the highlighting colour.
If  the  selected control type belongs to the clusters,  a  first
colour  for  even DCL tree levels  and a second  colour  for  odd
DCL tree levels  can  be  chosen.  Select  'even',  for instance,
specify  the colour to be applied  to  the  even DCL tree levels,


                                                           - 44 -

using the palette and press the 'Set' button. Then  select 'odd',
specify the colour to be applied  to  the odd DCL tree levels and
press the 'Set' button again.

If  the  selected  control type belongs to the  tiles,  only  one
colour  can  be specified. The odd or even pair is disabled,  and
the part labelled by 'all' is enabled.  Select the desired colour
from the palette and press 'Set'.

Select  the  next control type to be changed and proceed  in  the
same way.

Pressing the 'Update' button will store the changes done  for the
actual Visual DCL session only.

Pressing  the  'Save'  button  will  store  the  changes  in  the
configuration   file.   Note  that  in  this   case   the   'Save
Configuration'  toggle must be switched on  when  leaving  Visual
DCL. Otherwise the changes will be lost.


                                                           - 45 -

Dialogue Control Programming (DCP)
==================================

Introduction
------------

This   chapter  relates  to  dialogues  to  be  realised   in   a
programming language working with ADS, i.e. currently  C and C++.
Dialogues with variable layout  can be realised  by programming a
peace of code, writing  a  DCL  file,  so  that  the  application
program  controls  the  layout.  Visual DCL  provides  a  feature
supporting this technique by  generating  a so called DCP file. A
DCP file is similar to a DCL file. The differences are:

  *  The  corresponding  lines of a DCL  file  are  prepared  for
     being compiled by a C or C++ compiler, i.e. some characters,
     like  '"'  and  '\', are  preceded by   the  C string escape
     character '\'.
  *  Leading blanks for indentation are omitted  in order to save
     memory.
  *  Each  line  of the corresponding DCL file, is written  as  a
     parameter of a C macro call.


Preparing a Dialogue for usage with DCP
---------------------------------------

Obviously,  the  first step should be planning a dialogue  layout
containing  all  controls needed in order to derive  the  desired
variants.  After  having  edited a corresponding  dialogue,  save
it.  Then  generate  a  DCP file. For that purpose  activate  the
'Generate:' popup list  of the  main menu  and  select  the entry
'->  ANSI  C'.  In the  'Visual DCL  Program Generator'  dialogue
enable the row titled 'DCP  file', disable all other  rows  (i.e.
code generators), choose the desired target drive and path, using
the  'Target Path' button,  and finally  start  the generator  by
pressing the 'OK' button.


                                                           - 46 -

Using a DCP file
----------------

The  integration of a DCP file in the application  code  requires
the following steps:

  *  Define  the C macro referred in the DCP file for  performing
     the output to the DCL file.
  *  Open the DCL file.
  *  Insert  the DCP file and add the conditions controlling  the
     desired variants.
  *  Close the DCL file.

Subsequently  the DCL file may be used in the  same  way  as  any
other DCL file.


                                                           - 47 -

Generating Code
===============

Introduction
------------

There are three types of codes generated by Visual DCL:

  *  DCL files,
  *  DCP files, and
  *  files produced via templates.

All  three  types  use the information stored  in  the  currently
loaded  DCB.  The  fact that any DCB is loaded  is  reflected  in
the file name display of the main menu of Visual DCL.

Visual  DCL  organises  its  code  generators  by  the  following
grouping:

  *  C code,
  *  C++ code,
  *  LISP code,
  *  user defined code or report generators, and
  *  reports,

where  the   user  defined  code  generators are  intended  to be
modified   by   the   developer  in  order  to   meet  individual
requirements  with  respect  to  code generation   of  any  kind.
There are two instances, where modifications can be done:

  *  configuration  (modify  the .INI file  of  Visual  DCL,  see
     the section 'Configuration') and
  *  templates (modify or create new templates,  see  the chapter
     'Templates').

Indeed,  these  possibilities  apply  to  each of the  five  code
generation groups.

In  this  chapter, however, we concentrate on the  usage  of  the
code   generator   dialogues.  The   chapters   'Templates'   and
'Configuration'  provide  the  information,  needed   to   modify
existing  code  generators and to create and configure  new  code
generators.


                                                           - 48 -

Invoking the Code Generator
---------------------------

Select the popup list titled 'Generate:' and choose the currently
required entry from the  listed  groups  of  code generators. The
following groups are available:

  *  -> ANSI C,
  *  -> ANSI C++,
  *  -> LISP,
  *  -> User, and
  *  -> Report.

Each  of  these  selections displays a  dialogue  titled  'Visual
DCL Program Generator'.
Next  to  the  button labelled 'Source DCB' the drive,  path  and
file  name of the currently loaded DCB is displayed. If  this  is
empty,  no  DCB  is loaded. If, in this  case  you  have  already
edited  a  dialogue,  you should return  to  the  main  dialogue,
choose  the  entry 'save as ...' of the  'File:' popup  list  and
save the dialogue.

The path of  the files to be generated,  is displayed next to the
button labelled 'Target Path'.

The  available  code  generators are  displayed  in  eight  rows,
some  of  them  may  be  empty. Each row contains  the  following
elements informing about the corresponding code generator:

  *  toggle   telling if the code generator is currently enabled,
  *  text naming the code generator,
  *  edit box displaying the template used by the code generator,
  *  and a button invoking a file menu for selection  of an other
     template.

Note that generating DCLs and DCPs do not require templates.


Enabling and Disabling particular Entries
-----------------------------------------

Before  starting execution by pressing the 'OK'  button  you  can
enable   or   disable   particular  code  generators   using  the
corresponding toggle.  Such changes remain  valid for the time of
the  actual invocation   of  the  program  generator,  only.  For
permanent changes see the chapter 'Configuration' .


                                                           - 49 -

Changing the Destination Path
-----------------------------

If  you  want  to change the drive and the path of the  files  to
be  generated,  press  the  'Target  Path'  button.  The  'Select
Target Path' dialogue will be displayed.

In  a  list  box  the path symbols 'app1_dir' through  'app9_dir'
are displayed. The currently selected path symbol is highlighted;
and its currently  configured  contents is  displayed in the edit
box. You can choose either one  of  the  path  symbols or you can
type the desired drive and path in the edit box.  A change of the
target drive and path remains valid for  the  time  of the actual
invocation of the code  generator.  For permanent changes see the
chapter 'Configuration'.


Changing Template Assignments
-----------------------------

Code  generators  working  with templates,  i.e.  all  but  those
generating  DCL  files  or  DCP files, display  a  template  file
name  in  a  corresponding  edit  box.  You  can  select  another
template  by  pressing  the corresponding '>'  button.  Then  the
file  menu  'Select Template' is displayed. Note that  this  does
not  change  the name or extension of the file to  be  generated.
The  latter  can be changed editing the configuration  file  (see
the     chapter    'Configuration').    Changes    of    template
assignments remain valid  for  the time  of the actual invocation
of  the code  generator.  For  permanent changes  see the chapter
'Configuration'.


Changing the Language
---------------------

Pressing the 'Language Number' button  invokes the  same dialogue
as the 'Language' entry of the  'Options' popup_list  of the main
menu,  i.e.  you can  change  the  actual language as well as the
default language.

Note  that  the  effect of changing the actual  language  remains
valid  until  the  next  change, or until you  quit  Visual  DCL,
respectively.  Changing  the default  language  will  update  the
configuration  file,  if  the  toggle  'Save  Configuration'   is
switched on as soon as you leave Visual DCL.


                                                           - 50 -

How  does  the  selected  language  influence  the  code  to   be
generated ?
Because  Visual  DCL  does not use language dependent  templates,
the  difference  between  output files  generated  for  different
languages,  is  determined  by the differences  within  the  used
DCB with respect to languages.
If  the  application  to  be  realised  is  designed  to  support
different  dynamically switchable languages, and  if  you  decide
to  use  the  DCB  driver of Visual DCL  at  run  time, there  is
no  need  for  switching  the  language;  but,  if  the  assigned
templates   generate  language   dependent comments (labels,  for
instance), the decision of the language  selection should be made
up  by  the language  preferred  by  the developer(s) or required
coding standards, respectively.


Starting the Code Generator
---------------------------

After  having  set-up  all desired options, code  generating  can
be  started by pressing the 'OK' button. At first this  starts  a
check  for  existing files with respect to the  currently  loaded
DCB  and  the  currently enabled code generators.  If  there  are
files  to  be  overwritten, Visual DCL prompts  for  confirmation
If  confirmed,  if  necessary, generating  is  performed  in  the
order  of  the  enabled  rows, where the name  of  the  currently
generated  file  is  displayed  below  the  'OK'  button.   After
completion  the  'Visual  DCL  Program  Generator'  dialogue   is
terminated, and control is passed to the main dialogue.


                                                           - 51 -

Templates
=========

Introduction
------------

Using templates, Visual DCL provides a highly flexible method for
generating source codes, reports, and user defined formats.
Roughly  spoken,  a  Visual DCL template is an  ASCII  text  file
with place holders  beginning with the  key  '@('  and describing
which data item will be inserted at  code  generation time.  This
chapter is intended to enable the user  to modify the  Visual DCL
templates  in  order  to  meet  his individual requirements  with
respect to code generation.  Furthermore  the user  can  add  own
templates to  Visual DCL,  realising  various formats  using  the
information of DCBs. In this chapter the user is supposed  to  be
familiar with  the formatting strings  used  in  the  programming
language C.  Knowledge  of  the  Bacus Naur Form  (BNF)  would be
advantageous.
The  control  of  formatting  uses  a loop  construction stepping
through   all  controls   having  a  key.   Nestable  conditional
formatting is supported within loops.
Some   design  considerations  with  respect  to  templates   are
discussed in an additional section.


Directives and Instructions
---------------------------

We  start  this section with a formal description of  the  syntax
and  context  rules of "place holders", where we use  N.  Wirth's
extension of  the Bacus Naur form (EBNF)  as a meta language.  In
this notation curled brackets are used to represent  an  optional
iteration of a symbol.  Names of symbols constructed  from  other
symbols (non terminal symbols)  are italic.  Key  words  and  non
meta language  single characters (terminal symbols) are bold. The
key word 'any' represents any printable character.


                                                           - 52 -

Syntax Rules
------------

    place_holder        = directive | instruction.

    directive           =   format_definition
                          | get_time
                          | debug_switch.

    format_definition   = @(form,format_name,format_string).

    get_time            = @(time).

    debug_switch        = @(debug,(on | off)).

    instruction         =   control_instruction
                          | insert_instruction.

    control_instruction =   @((- | ;))
                          | @(loop)
                          | @(endloop)
                          | @((if | ifnot),condition)
                          | @(endif).

    condition           =   control_type
                          | control_property
                          | key_item = string.

    insert_instruction  =   @(format_name,(key_item | non_key_item))
                          | @(tab,number).

    format_name         = identifier.

    identifier          = letter {letter | digit}.

    letter              =   A | B | C | D | E | F | G | H | I | J
                          | K | L | M | N | O | P | Q | R | S | T
                          | U | V | W | X | Y | Z
                          | a | b | c | d | e | f | g | h | i | j
                          | k | l | m | n | o | p | q | r | s | t
                          | u | v | w | x | y | z
                          | _.

    digit               = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9.

    format_string       = string.


                                                           - 53 -

    string              = "{any}".

    number              = digit {digit}.

    control_type        =   button          | dialog
                          | edit_box        | image
                          | image_button    | list_box
                          | popup_list      | radio_button
                          | slider          | text
                          | text_part       | toggle.

    control_property    =   has_action      | has_edit_limit
                          | has_label       | has_slide
                          | has_value       | is_2D_point
                          | is_3D_point     | is_ads_real
                          | is_callback     | is_cancel
                          | is_default      | is_help
                          | is_info         | is_integer
                          | is_long         | is_pick
                          | is_positioned   | is_radio_group
                          | is_short        | is_string.

    non_key_item        =   day             | DLG
                          | Dlg             | dlg
                          | dlg_name        | hour
                          | minute          | month
                          | PREFIX          | Prefix
                          | prefix          | second
                          | year.

    key_item            =   action          | big_increment
                          | control_id      | control_name
                          | dimx            | dimy
                          | edit_limit      | file_name
                          | help_file       | help_topic
                          | info_name       | KEY
                          | Key             | key
                          | label           | max_value
                          | min_value       | pick_name
                          | slider_value    | slide_name
                          | small_increment | value.

Note  that  the place holder introducer sequence '@('  is  a  key
word  so  that  the  '@' and the '(' must  not  be  separated  by
blanks or tabs.


                                                           - 54 -

Each   directive  as  well  as  each  control_instruction  should
start   at   the   first  position  of  a  line.  All   preceding
characters  in  a  directive  or  control_instruction  line   are
otherwise  echoed  to  the  output  file.  Any  text   behind   a
directive  or  control_instruction is  treated  as  comment  (not
echoed  to  the  output file). But note that one  line  must  not
contain   more   than   one  directive  or   control_instruction.
Particularly,  the comment instructions @(-)  and  @(;)  can  not
be  used  for commenting out place holders of any type. One  line
may contain any number of insert_instructions.
If  a  syntax  error is detected at  code  generation time,   the
formatting is terminated, an error message  is displayed, and the
output file is closed.


Context Rules
-------------

The  essential  ability of the template based code  generator  of
Visual  DCL  is  made up by the possibility to loop  through  all
controls   of  the  current  DCB  having  a  key  and  performing
conditional formatting within such loops.
The  majority of data items retrievable from a DCB  are  made  up
by   the   key_items.  Therefore  insert_instructions   referring
key_items  must  not  be placed outside of  a  loop  ...  endloop
construction.
The  latter  requirement is an example  of  a  context  rule  for
template  place  holders. We now list a complete  description  of
the context rules.

  *  Each format_name must be declared  by  a  format_defininion,
     before it can be referred by an insert instruction.
  *  Each  loop instruction  must  have  a corresponding  endloop
     instruction.
  *  Loops must not be nested.
  *  Each if and each ifnot instruction must have a corresponding
     endif instruction.
  *  Each  if/ifnot...endif construction must be placed inside of
     a loop...endloop construction.
  *  A key_item  must  only  be referred within  a loop...endloop
     construction.


                                                           - 55 -

Using  the  symbols  of  the above syntax description,  then,  in
EBNF, the context rules look like that:

    template_file           = {  non_formatting_line
                               | directice_line
                               | loop_construction
                               | non_key_formatting_line
                              }
                              EOF.

    non_formatting_line     = {any} EOL.

    directive_line          = directive {any} EOL.

    loop_construction       = @(loop) {any} EOL
                              {  non_formatting_line
                               | directive_line
                               | formatting_line
                               | conditional_section
                              }
                              @(endloop) {any} EOL.

    conditional_section     = @((if | ifnot),condition) {any} EOL
                              {  non_formatting_line
                               | directive_line
                               | formatting_line
                               | conditional_section
                              }
                              @(endif) {any} EOL.

    non_key_formatting_line = {  any
                               | @(format_name,non_key_item)
                               | @(tab,number)
                              }
                              EOL.

    formatted_line          = {  any
                               | @(format_name,non_key_item)
                               | @(format_name,key_item)
                               | @(tab,number)
                              }
                              EOL.

Note  that  the  symbol 'any' represents any printable  character
(excluding  EOL and EOF). But a '@', immediately  followed  by  a
'('  terminates  a  sequence  of 'any'  characters.  However  the
sequence  '@('  can  occur in a string inside any  place  holder,
without   being   interpreted  as  a  place   holder   introducer
sequence.


                                                           - 56 -

If  a  context  error   is  detected  at  code  generation  time,
formatting is terminated, an error message  is  displayed and the
output file is closed.


Format Definitions
------------------

The  Visual  DCL  code  generator has  been  designed  to  use  C
formatting  strings  and to support symbolic format  definitions.
This allows central control of formatting details.
The format_definition

    @(form,fs,"%s")

is  used  for  string items like key or prefix. A  list,  telling
the  data  types  of all items, i.e. key_items and non_key_items,
is  contained in the section 'Inserting Items' below.  Note  that
each  format  string  must contain exactly  one  item,  i.e.  one
'%'  character.  Visual DCL  does not check this.  The  developer
of  templates  is therefore responsible for supplying  consistent
format_definitions.   The   following   format_definitions    are
inconsistent  and  may produce unpredictable  behaviour  as  well
for  Visual  DCL as for the application produced if such  formats
are referred by a subsequent insert_instruction:

    @(form,bad1,"hello")
    @(form,bad2,"(%f,%f)")


Debug Switch
------------

The  code  generator  can  produce output  files  containing  the
original  template  lines (including line  numbers)  as  well  as
the   formatted   output  lines  (without  line  numbers).   This
feature is useful if looking for errors. The directive

    @(debug,on)

results  in  the  effect  that the subsequent  template  text  is
echoed until the directive

    @(debug,off)

is read. By default, the debug switch is off.


                                                           - 57 -

Loops
-----

As mentioned above, the loop construction of Visual DCL  provides
an iteration  of all controls  belonging  to the currently loaded
DCB and having a key attribute.
A  simple application of this loop construction is shown  by  the
following  template. It creates a file containing a list  of  all
keys of the currently loaded DCB.

    @(form,fs,"%s")
                         key list
    @(loop)
                         @(fs,key)
    @(endloop)

Generally, the loop construction can be read as

    loop through all controls of the currently loaded DCB  having
    a key
          ...
    endloop


Conditional Formatting
----------------------

We  start  extending the above example of a loop construction  by
adding a condition selecting all keys which produce  a  call back
from Proteus if activated by the user of the dialogue.

    @(form,fs,"%s")
                       call back key list
    @(loop)
    @(  if,is_callback)
                       @(fs,key)
    @(  endif)
    @(endloop)

The  lines  between the if instruction and the endif  instruction
are  processed  with the effect of producing an  output  for  all
keys  having  the call back property. In this case  the  type  of
control,  to  which the current key belongs, is  responsible  for
the  matching  of  the condition. Replacing the  control_property
'is_callback'   in   the   above   if   instruction   with    the
control_property 'has_slide', the condition will  match  for  all
images  and  all  image buttons for which a slide_name  has  been
specified.


                                                           - 58 -

There are three types of conditions
  *  control_property,
  *  control_type, and
  *  string comparison of a key_item to a constant string.

In  a  second  example control_types are tested in  order  to  do
conditional formatting.

    @(loop)
    @(  if,button)
    /*    conditional text for control type button */
    @(  endif)
    /*  test for other control types */
    @(  if,toggle)
    /*    conditional text for control type toggle */
    @(  endif)
    @(endloop)

The  following example of a template illustrates  the  use  of  a
string  comparison  for  a key_item and  nesting  of  conditional
formatting.

    @(loop)
    @(  if,is_help)
    @(    if,help_file="my_help")
    /*      processing for my_help */
    @(    endif)
    @(    ifnot,help_file="my_help")
    /*      alternate processing else */
    @(    endif)
    @(  endif)
    @(endloop)

Note  that the outer condition '@(if,is_help)' ensures  that  the
control   currently  processed  by  the  loop  construction   has
indeed  a  'help_file'  attribute. The developer  is  responsible
for  ensuring  the  consistent addressability of  key_items  used
in   comparisons.   Inconsistencies  may  produce   unpredictable
behaviour of the code generator.

The table T1, below, describes the  control_properties  supported
by Visual DCL.


                                                           - 59 -

  control_property | DCL | associated control(s) | associated attribute(s)
  -----------------+-----+-----------------------+------------------------
  has_action       |     | all active controls   | action
  has_edit_limit   |     | edit_box              | edit_limit
  has_label        |     | all, but slider       | label
  has_slide        |     | image, image_button   | slide_name
  has_value        |     | all active controls   | value
  is_2D_point      |     | edit_box              | data_type
  is_3D_point      |     | edit_box              | data_type
  is_ads_real      |     | edit_box              | data_type
  is_callback      |     | all                   | (defined by Proteus)
  is_cancel        | yes | button, image_button  | is_cancel
  is_default       | yes | button, image_button  | is_default
  is_help          |     | button, image_button  | help_file
  is_info          |     | button, image_button  | info_name
  is_integer       |     | edit_box              | data_type
  is_long          |     | edit_box              | data_type
  is_pick          |     | button, image_button  | pick_name
  is_positioned    |     | dialog                | dimx, dimy
  is_radio_group   |     | boxed_radio_column,   | key
                   |     | boxed_radio_row,      |
                   |     | radio_column,         |
                   |     | radio_row             |
  is_short         |     | edit_box              | data_type
  is_string        |     | edit_box              | data_type
  -----------------+-----+-----------------------+------------------------

                      Table T1  control_properties


Comment
-------

Lines     beginning     with    one     of     the     equivalent
control_instructions  @(-)  or  @(;)  do not  contribute  to  the
output in any way.

    @(;)  comment may be used to improve readability
    @(;)  and  maintainability of templates.

Note  that  the control_instructions  @(;)  and  @(-)   must  not
be used for commenting out directives or instructions.

Other  control_instructions may be commented  in  the  same  way,
for example,

    ...
    @(    endif)      is help
    @(  endif)      is call back
    @(endloop)    end of call back function skeletons
    ...


                                                           - 60 -

Inserting Items
---------------

There are two different types of data items supported by the code
generator of Visual DCL,

  *  key_items,      usable inside of loop constructions, and
  *  non_key_items,  usable anywhere.

Both types contain items corresponding to DCL attributes  as well
as items added by Visual DCL. While the reader is supposed  to be
familiar with DCL, the  additional  items  need some explanation:

  *  control_id  is the numeric control identifier  used  in DCBs
     and  displayed in the edit dialogue  preceded by the  prefix
     and  an underscore, '_'.  With respect  to  code generation,
     this item is intended to be used merely within comments.
  *  control_name  retrieves the name of the current control type
     within a loop.  The use of this item  with  respect to  code
     generation will normally be restricted to comments.
  *  dimx, dimy  contain  the  position  data  specified  in  the
     'dialog attributes' dialogue,  if  the  toggle  indicating a
     positioned dialogue has been switched on.  The state of this
     toggle is stored in the control_property 'is_positioned'.
  *  dlg_name   reflects  the  string   specified   in  the  'DCL
     attributes' dialogue.  It is intended to contribute  to  the
     construction  of  identifiers  specific  to  an   individual
     dialogue.  For instance, the Visual DCL templates use it for
     the  construction  of a dialogue function name,  a type name
     for the dialogue data structure, and for similar purposes.
  *  file_name  contains  the  file name  of the currently loaded
     DCB without drive, path, and file name extension.  This item
     provides  an easy way for deriving  related file names,  for
     instance within include statements.
  *  help_file  is a key_item. In Visual DCL, some control types,
     i.e.  button  and  image_button, the  presence of  a  string
     attribute 'help_file' is indicated  by the  control_property
     'is_help'. The key_item 'help_file'  must  not  be  referred
     without testing the control_property 'is_help'.
  *  help_topic is treated analogous to the key_item 'help_file'.
     The associated control_property 'is_topic' indicates whether
     a help_topic attribute had been specified. References of the
     key_item 'help_topic'  must  be  done conditionally, testing
     the control_property 'is_topic'.


                                                           - 61 -

  *  pick_name    with the associated control_property  'is_pick'
     applies  to buttons  and image_buttons.  References  of this
     item  require conditional formatting,  using the  associated
     control_property.
  *  PREFIX, Prefix, prefix   are  non_key_items  reflecting  the
     prefix string as displayed by the  main menu  of Visual DCL.
     The  three  ways  of  spelling  correspond  to  upper  case,
     original spelling, and lower case, respectively.  The prefix
     is intended to be used as the name of  a parameter structure
     to  be  generated for each C or C++ dialogue  skeleton code.

In  order  to  format  an item, an appropriate  format_definition
must  be  referred.  The  example  shows  the  inserting  of  the
non_key_items 'Prefix', and 'dlg_name'.

     @(form,fstr,"%s")
     (defun:dlg_@(fstr,Prefix)_@(fstr,dlg_name) ()
     ...
     )

The  Table  T2  lists all items supported by the  code  generator
together  with  their item types, their data types  in  terms  of
C,  and  a  basic C format string. The latter may be extended  by
additional  specifications like the field width,  left  or  right
adjustment etc.


                                                           - 62 -

   item            | DCL       | key  | non key | data   | format
   name            | attribute | item | item    | type   | string
   ----------------+-----------+------+---------+--------+-------
   action          | yes       | yes  |         | char * | "%s"
   big_increment   | yes       | yes  |         | short  | "%d"
   control_id      |           | yes  |         | short  | "%d"
   control_name    |           | yes  |         | char * | "%s"
   day             |           |      | yes     | int    | "%d"
   dimx            |           | yes  |         | short  | "%d"
   dimy            |           | yes  |         | short  | "%d"
   DLG             | yes 1)    |      | yes     | char * | "%s"
   Dlg             | yes 1)    |      | yes     | char * | "%s"
   dlg             | yes 1)    |      | yes     | char * | "%s"
   dlg_name        |           |      | yes     | char * | "%s"
   edit_limit      | yes       | yes  |         | short  | "%d"
   file_name       |           |      | yes     | char * | "%s"
   help_file       |           | yes  |         | char * | "%s"
   help_topic      |           | yes  |         | char * | "%s"
   hour            |           |      | yes     | int    | "%d"
   info_name       |           | yes  |         | char * | "%s"
   KEY             | yes       | yes  |         | char * | "%s"
   Key             | yes       | yes  |         | char * | "%s"
   key             | yes       | yes  |         | char * | "%s"
   label           | yes       | yes  |         | char * | "%s"
   max_value       | yes       | yes  |         | short  | "%d"
   minute          |           |      | yes     | int    | "%d"
   min_value       | yes       | yes  |         | short  | "%d"
   month           |           |      | yes     | int    | "%d"
   pick_name       |           | yes  |         | char * | "%s"
   PREFIX          |           |      | yes     | char * | "%s"
   Prefix          |           |      | yes     | char * | "%s"
   prefix          |           |      | yes     | char * | "%s"
   second          | yes       |      |         | int    | "%d"
   slider_value    | yes       | yes  |         | short  | "%d"
   slide_name      | yes       |      |         | char * | "%s"
   small_increment | yes       | yes  |         | float  | "%f"
   value           | yes       | yes  |         | char * | "%s"
   year            |           |      | yes     | int    | "%d"
   ----------------+-----------+------+---------+--------+-------

              Table T2  key_items and non_key_items

 ----------
 1)   This  is  the key attribute of  the control  'dialog'.  The
      Visual DCL  templates  use  it  as  a  part  string  of the
      dialogue function name.


                                                           - 63 -

Upper and lower case
--------------------

Some string items are available in

  *  upper case
     (DLG, KEY, and PREFIX),
  *  the original case as typed in the attribute  dialogue
     (Dlg, Key, and Prefix),
  *  and lower case
     (dlg, key, and prefix).

This  feature  is  intended,  for instance,  for  deriving  macro
names when generating C or C++ code.


Date and Time
-------------

The current date and the time, i.e. the date and the time of code
generation,  is stored at the moment when the  directive  @(time)
is executed and may be formatted using the non_key_items  'year',
'month', 'day', 'hour', 'minute', and 'second'.
The  example   shows  some  appropriate  format_definitions,  the
get_time   directive,  and  insert_instructions  formatting   the
corresponding non_key_items.

    @(form,short_2,"%2d")
    @(form,short02,"%02d")
    @(form,short_4,"%4d")
    ...
    @(time)             store current time and date
    @(;)                insert month, day, and year:
    ...
    Date  @(short_2,month)/@(short02,day)/@(short_4,year)
    Time  @(short_2,hour):@(short02,minute):@(short02,second)


Tabulators
----------

The insert_instruction  @(tab,number)  appends blanks to the line
currently being formatted until the position specified  by number
is reached. This instruction is ignored,  if the current position
is greater than the value of number.
As  the  example  shows,  more than one tab  instruction  may  be
used in the same line.

    @(form,fstr,"%s")
    ...
    /*  @(tab,8)@(fstr,file_name).c@(tab,70)*/


                                                           - 64 -

Protecting Application Code against Overwriting
-----------------------------------------------

As  the  development of an application usually  is  an  iterative
process,  the  question  arises,  how  to  avoid  overwriting  of
application  code inserted into the skeleton code  generated,  if
code  generating  is iterated. This section describes  one  among
several  possible  methods  of  protecting  inserted  application
code.

A  first  approach to solve this "one way, only"  dilemma,  could
be  writing  a template with  #include  directives  at the places
where  application  code is to be inserted. The  disadvantage  of
this  method  is  obviously the distribution of  the  application
code to many include files.

Using  compile  switches, additionally, allows  to  include  only
one  file  containing all application code to  be  inserted.  The
included  file  can  be generated using an appropriate  template.
The principle of this technique is shown by the example below:

    /*  sample.c  */            |    /*  sample.usr  */
    # define SAMPLE_INCL        |    # ifdef SAMPLE_INCL
    # include "sample.usr"      |    /* additional includes */
    # undef  SAMPLE_INCL        |    # endif
    ...
    |
    # define SAMPLE_INIT        |    # ifdef SAMPLE_INIT
    # include "sample.usr"      |    /* initialisations */
    # undef  SAMPLE_INIT        |    # endif
    ...                         |
    ...                         |    ...
    ...                         |
    # define SAMPLE_SUBR        |    # ifdef SAMPLE_SUBR
    # include "sample.usr"      |    /* local functions */
    # undef  SAMPLE_SUBR        |    # endif


                                                           - 65 -

Run Time Considerations
=======================

Introduction
------------

This chapter discusses the usage of the run time support supplied
by  Visual DCL.  This  run time  support,  the  DCB driver, is  a
separate application that has been designed for loading DCB files
instead of DCL files.  The DCB driver reads a DCB file, generates
a   temporary   DCL   file,   loads   it   using   the   function
'ads_load_dialog'  and then  deletes the temporary DCL file.  The
advantages of this method are:

  *  The  language  of the produced DCL file  can be chosen  upon
     those supported  by  the  DCB  file  loaded  (see  also  the
     chapter 'Languages').

  *  For  applications,  designed  for more  than  one  language,
     the number of auxiliary files is reduced.

  *  The  DCL  file   becomes   invisible  to  the  user  of  the
     application.  The  possibility  of  changes  by  the user is
     avoided.


Loading the DCB Driver
----------------------

The  DCB  driver has to be loaded. If, for instance,  Visual  DCL
had  been  installed  in the directory  'C:\ACL_VDCL,   the  LISP
statement

    (xload "C:\ACL_VDCL\ACL_VDCB.EXP")

can be used.


Invoking the DCB Driver
-----------------------

Having  been  loaded, the DCB driver is availabe as the  external
function

    acl_vdcb_load_dcb

with the three mandatory parmeters

  *  path of the DCB file,
  *  name of the DCB file, and
  *  language index in the range of 0 through 4.


                                                           - 66 -

An Example using LISP
---------------------

If  the  DCB file 'C:\MY_DCBS\THIS.DCB' has to be loaded and  the
the  language  index 0 has to be used, the significant  piece  of
code looks like that:

     (defun C:my_dialog ()
       (setq dcl_id (acl_vdcb_load_dcb    ; DCB driver
                     "C:\\MY_DCBS"        ; path
                     " "THIS.DCB"         ; DCB file name
                     0                    ; language index
                    )
       )
       (if (< dcl_id 0) (exit))

       (if (not (new_dialog "my_dialog" dcl_id)) (exit))
       ...
       ...
       (start_dialog)
       (unload_dialog dcl_id)
       ...
     )

Note   that  the  template  'DCBA_LSP.TPL'  generates  LISP  code
loading and unloading the DCB driver.


                                                           - 67 -

An Example using C
------------------

The   following   example  for  C  shows,  how   the   DCB   file
'C:\MY_DCBS\THIS.DCB'  has to be loaded,  if  the  language  with
the index 0 has to be selected:

     int my_dialog (void)
       {
       int             rc;        /* return code    */
       int             dcl_id;    /* dcl identifier */
       struct resbuf * argl;
       struct resbuf * rslt;

       argl = ads_buildlist (RTSTR,   "acl_vdcb_load_dcb"
                            ,RTSTR,   "C:\\MY_DCBS"  /* DCB path */
                            ,RTSTR,   "THIS.DCB"     /* DCB file */
                            ,RTSHORT, 0              /* language */
                            ,0
                            );
       if  ( argl != NULL )
           {
           rc = ads_invoke (argl,& rslt);
           ads_relrb (argl);
           }
       if  ( rslt != NULL )
           {
           dcl_id = (rslt ->restype == RTSHORT)
                  ? rslt ->resval .rint
                  : -1;
           ads_relrb (rslt);
           }
       if  ( rc != RTNORM )
           {
           /* error: 'acl_vdcl_load_dcb' failed */
           return   (rc);
           }

       /* Subsequently, the function 'ads_new_dialog' can be */
       /* called, where the 'dcl_id' returned in the result  */
       /* buffer of the call to 'ads_invoke' has to be used. */

       /* ... */
       /* ... */
       /* ... */
       }

In  the  examples  above loading is done each time  the  dialogue
is  called.  Therefore,  this method  is called "load  on  call".
Correspondingly, the method of loading a dialogue at the time the
application is started is called "preload".


                                                           - 68 -

Dynamic Language Switching
--------------------------

The  previous  section implies that all what has to  be  done  in
order to switch the language of a dialogue dynamically, is

  *  Use a global variable  for the language index,  for invoking
     'acl_vdcb_load_dcb'.
  *  Preset this variable by a default value.
  *  Get user input changing the language index variable  to  the
     actually desired value.

Note that dynamic language switching requires the  "load on call"
method.


The Integrated DCB Driver
-------------------------

If  testing  dialogues  while  Visual  DCL  is  loaded,  the  DCB
driver  integrated  in  Visual DCL can be  used  instead  of  the
stand  alone  DCB  driver  described above.  The  integrated  DCB
driver  is  invoked in the same way as the stand  alone  version;
but the function name differs. Use

    acl_vdcl_load_dcb

instead of 'acl_vdcb_load_dcb'.


                                                           - 69 -

Appendices
==========

Templates supplied with Visual DCL
----------------------------------

This  sections  is  a  short  reference  of  the  template  files
supplied with Visual DCL.


Templates for C
---------------

DCLC_C__.TPL  uses the  corresponding DCL file  and  the  load on
              call method.

DCBC_C__.TPL  uses the  corresponding DCB file  and  the  load on
              call method,  and generates  definitions of compile
              switches and includes  a  .USR file for application
              specific code (see also DCBS_C__.TPL).

DCLH_C__.TPL  defines  an  application  parameter  structure  and
              function prototypes.

DCBS_C__.TPL  references the compile switches generated using the
              template DCBC_C__.TPL. The file generated  by  this
              template has the extension  '.S', which is intended
              to be renamed in '.USR' in order to protect against
              being overwritten by mistake.

MAIN_C__.TPL  contains the code needed for  calling  the dialogue
              function  generated  using the templates  mentioned
              above.

MAKE_C__.TPL  produces a makefile for compiling  and linking  the
              modules generated by the above templates.

LINK_C__.TPL  produces a  link response file  referenced  by  the
              makefile MAKE_C__.TPL.


                                                           - 70 -

Templates for C++
-----------------

DCLC_CPP.TPL
DCBC_CPP.TPL
DCLH_CPP.TPL
DCBS_CPP.TPL
MAIN_CPP.TPL
MAKE_CPP.TPL
LINK_CPP.TPL

Currently,  these  templates  have  the  same  contents  as   the
corresponding C templates.


Templates for LISP
------------------

DCLA_LSP.TPL  uses the  corresponding DCL file  and  the  load on
              call method.

DCBA_LSP.TPL  uses the  corresponding DCB file  and  the  load on
              call method.


Templates for Reports
---------------------

REPORT_1.TPL  produces a list of all non_key items and  a list of
              all controls, including  the items  and  properties
              as specified for the corresponding dialogue.

REPORT_2.TPL  same  as   REPORT_1.TPL,   but   uses   semigraphic
              characters of the IBM extended ASCII character set.


                                                           - 71 -

The Dialogue Tree of Visual DCL
-------------------------------

The synopsis below shows the dialogue tree  of Visual DCL,  where
the  help dialogues,  the warnings,  and  the error messages  are
omitted. The Symbol '*' indicates  selections  from a list box or
popup_list. Activation by a button is marked using the characters
'[' and ']'. Dialogue titles are marked using '"'s.

"Visual DCL, the Proteus Editor"
    File:
      *  new        "Create New Dialogue"
      *  new from   "Open DCB Source File"
                    "Open DCB Destination File"
      *  open       "Open DCB File"
      *  save       -
      *  save as    "Store DCB File"
      *  quit       "Quit Visual DCL"
    Edit:
      *  edit       "<actual label of dialogue being edited>"
                        [ Ins ]         "Insert Control"
                           [ Attributes ] "Change ... Attributes"
                        [ Chg ]         "Replace Control"
                           [ Attributes ] "Change ... Attributes"
                        [ Undo ]        "Undelete Control"
                        [ Attributes ]  "Change ... Attributes"
      * display     "<actual label of dialogue being edited>"
      * translate   "Translate"
      * reorganise  -
    Generate:
      * -> ANSI C   "Visual DCL Program Generator" \
      * -> ANSI C++ "Visual DCL Program Generator"  |
      * -> LISP     "Visual DCL Program Generator"  >
      * -> User     "Visual DCL Program Generator"  |
      * -> Report   "Visual DCL Program Generator" /
                        [ Target Path ]      "Select Target Path"
                        [ > ]                "Select Template"
                        [ Language Number ]  "Select Language"
    Options:
      * Audit Level "Change Audit Level"
      * Prefix      "Change Prefix"
      * Language    "Change Language"
      * Key List    "Key List"
      * Layout      "Layout"
      * Colours     "Change Colours"
    Help:
      * Handling    -
      * Terms       -
      * Visual DCL  "<Visual DCL Logo>"


