script.doc

BORLAND公司C语言对话框开发程序

This file serves to document the script file as well as the conversion
programs supplied with Dialog Design.

CONVERSION PROGRAM CALLING SEQUENCE

For source generating conversion programs, Dialog Design uses the
following calling sequence:

  progname.exe  <scriptname>  <outfilename> <errorfilename>

Where <scriptname> is the script input filename, <outfilename> is the
name of the file the source code is to be written to, and <errorfilename>
is a file to which errors are written.  In operation, Dialog Design
first writes the script file and then calls the program as above.  If the
exitcode is non-zero, the error file is then read and the error displayed.
Both the script and error files are then deleted.

In the implementations supplied, <errorfilename> is made optional and if
omitted, error output comes to the console.  This allows the conversion
programs to be run from DOS as well as from within Dialog Design--an aid
in debugging.

The calling sequence for the resource conversion programs is slightly
different:

  progname.exe <scriptname> <resource filename> <resource ID> <errorfilename>

where an additional parameter for the resource ID string has been added.
Before calling a resource conversion program, Dialog Design checks to see
if the resource filename exists.  If it does, it then checks to see if it's
actually an EXE file or a resource file of the appropriate type (C++ or
Pascal).  Hence the conversion program does not have to make these checks.
However, the conversion program is responsible for making a backup of the
old file if that's desirable.


READSCPT.PAS

READSCPT.PAS compiles into a Pascal unit which reads the script files output
by Dialog Design.  It's used for all three Pascal conversion programs
supplied.  If you decide to write your own conversion programs, you can
probably use this unit without change.

In brief, READSCPT reads through the script file storing the information
for the dialog and its controls in variant records (type ScriptRec).  The
dialog itself has a record called Dialog and the control records are
inserted in a TCollection named, ScriptColl.  Thus, once the script file is
read, all the data is available for processing by the rest of the program.


READSCPT.CPP

READSCPT.CPP and READSCPT.H similarly form a module for reading the script
file.  It's used by all the supplied C++ conversion programs and can
probably be used without change for any modified conversion programs.

READSCPT defines an abstract struct (ViewObj) to serve as a base object
for later descendants.  In addition to defining fields common to all
controls, three abstract code writing methods are also defined.

Also defined are script reading descendants of ViewObj for the dialog itself
and each of the controls.  These descendants contain fields special to each
control and have a contructor which reads it's portion of the script file
and fills in the fields.

The final descendants of ViewObj are defined in the source code or resource
generator module where the codewriting methods are fleshed out to do
whatever is appropriate.

READSCPT requires that a function ( getKind() ) be defined in the codewriting
section.  This function takes a single enum parameter which defines the basic
type of control (button, inputline, etc.).  The return should be an instance
of the final descendant of that basic type.  See any of the C++ conversion
programs for an example of getKind().

As the script file is read, each ViewObj descendant is inserted in a
TNSCollection named ScriptColl and the dialog itself is stored in Dialog.



SPECIAL CONTROL EXAMPLE

The supplied conversion files can be easily modified to accommodate specially
derived controls.  PASSRC1 and CPPSRC1 already have an example of such a
modification.  If you take a look at the demo, OPBUTTON.DLG, you'll see that
it contains a special option button with a pointer name, POptionButton
(TOptionButton would have been a better name in C++).  The constructor call
for POptionButton is quite different from that of normal TButtons requiring
two word parameters (here named PBOptions and PBEventMask) in addition to
the normal TRect.  In addition, POptionButton also requires a special field
in the dialog's transfer data record (here called AOptions).  This extra
information has been entered in the control's 'Extra' dialog.

Both PASSRC1 and CPPSRC1 have a few extra lines of code added to be on the
lookout for POptionButton and generate the proper constructor call for it.


SCRIPT FILE

While looking over the documentation for the script file, it would be
helpful for you to print out a sample script file as well as the Interface
part of READSCPT.PAS (for Pascal users) or READSCPT.H (for C++ users).

The script file generated by Dialog Design is an ASCII file which consists
entirely (except for the first item) of only two types of tokens, decimal
numbers and double quoted strings.  Not much to be said about decimal
numbers, but here's a few facts about the strings:

   "This is a string\n"

   There's three different escape sequences a string may contain:
     '\n'    a newline
     '\"'    a double quote within the string
     '\\'    a backslash within the string

   A '+' immediately following the quote is used to indicate concatenation
   with the next string.  In this manner strings of up to 255 characters
   can be output with 80 or so characters per line.
     "This is considered"+
     "one string."

The layout for the script file consists of variable length records for the
dialog itself followed by similar records for each control in the dialog,
something like:

             |-----------------|
             |  Version        |
             |-----------------|
             |  Reserved       |
             |=================|
             |  Fixed Part     |   -|
             |-----------------|    |__ Dialog
             |  Variable Part  |   -|
             |=================|
             |  Fixed Part     |   -|
             |-----------------|    |__ Control
             |  Variable Part  |   -|
             |=================|
                     .
                     .
             |=================|
             |  Fixed Part     |   -|
             |-----------------|    |__ Control
             |  Variable Part  |   -|
             |=================|
             |  -1             |
             |-----------------|

The script file starts off with "SCRIPT1" (but without the quotes in this
case) followed by a newline.  This serves to verify the file IS a script
file and supplies the version number.  A reserved section comes next--
a single quoted string and a single number. Following this are the records
for the dialog, and for each of the controls in the dialog.  The controls
appear in Tab order (reverse Z order) except for TLabel's, THistory's,
and attached TScrollBar's.  Labels and Historys immediately follow the
control to which they're attached and attached ScrollBars immediately
precede the control they're attached to.

The last control is followed with -1 to indicate there are no more.

The record for each control ( and the dialog itself) consists of a fixed
part and a variable part.  The fixed part is identical for each type of
control (although sometimes fields are blank).  The variable part varies
with each type of control.

FIXED PART

Here's the order and contents of the fixed part:

   Name          Type              Example or comment

   Kind          RecType           Identifies the control type
   BaseObj       string            "TInputLine"  (the basic type)
   Obj           string            "PMyInputLine"/"TMyInputLine" (the
                                   Pointer Name/Class Name)
   X1,Y1,X2,Y2   Integer           The TRect
   DefOptns      word              Default options for the control
   Optns         word              The options as specified
   DefEvMsk      word              Default EventMask for the control
   EvMsk         word              The eventmask as specified
   HCtx          word              Numerical value of help context
   Grow          word              GrowMode for control (not used)
   Param         string[6]         The 6 'Extra' parameters
   HelpCtxSym    string            "hcNoContext"
   FieldName     string            "field102"   (field name for data record)
   VarName       string            "control"    (name given to this control)

See the BlockType definition (Pascal) or the ViewObj definition (C++).
For each control, 'Kind' appears first in the script file and serves to guide
the reading for the remainder of the variable record.  However, it isn't
stored first in the Pascal record and isn't stored at all in the C++
structure.

The default option and eventmask are included to enable a comparison to see
which bits (if any) are being changed.

The six extra parameters are those that would be entered on the dialog
accessed with the 'Extra' button.  You can use these for whatever you want.

For the dialog itself, FieldName is used to specify the name of the data
record.


Variable Parts


Listed below are the variable parts for each control which appear after the
fixed part.

Dialog

   Palette       word         Dialog Palette (not used in C++)
   WinFlags      word         The dialog's  wfXXXX flags
   DlgFuncName   string       "MakeDialog"/"makeDialog"
   KeyString     string       Default resource ID string
   Title         string       Dialog's Title

Button

   CommandName   string       "cmOK"
   ButtonText    string       "~C~ancel"
   CommandValue  word         The value of the command
   Flags         word         The bfXXXX flag bits

Static Text
Colored Text

   Attrib       word          Color Attribute (not used for TStaticText)
   Text         string

InputLine

This is a messy one as it contains a varient record for Validators.
Validators have no place in C++ yet.

   StringLeng   word          The number of characters that can be typed in.
                              =MaxLen in Pascal, maxLen-1 in C++.
   ValKind      ValType       Number indication type of validator, -1 for
                              none.  Always -1 in C++.
   ValPtrName   string        "PPXPictureValidator"

If ValKind is not -1, then the following fields are present.
  Picture (1)
   AutoFill     byte          non zero if AutoFill set.
   PictureString string       The picture string.

  Range(2)
   LowLim,
   UpLim        LongInt       Range limits
   Transfer     word          non zero if voTransfer bit set.

  StringLookup (3)
   List         string        The string collection name or "Nil" for none.

  Filter (4)
   CharSet      string        "['a'..'z', '_']"
   ActualCharSet  LongInt[8]  A set of 8 numbers repersenting the actual
                              character set.

TInputLong

  LongLabelText string        The text of the attached label.  Used as the
                              6th parameter in the C++ constructor.
  LongStrLeng   word          The number of characters that can be typed in.
                              =MaxLen in Pascal, maxLen-1 in C++.
  LLim, ULim    long int      Lower and upper range limits.
  ILOptions     word          Options

TLabel
  LabelText     string        The label's text.
  LinkName      string        The variable name (VarName) of the control
                              to which the label is linked.

THistory
  HistoryID     word          History list number
  HistoryLing   string        The variable name (VarName) of the control
                              to which the THistory is linked.

TCheckBoxes
TMultiCheckBoxes
TRadioButtons

TMultiCheckBoxes won't appear in C++ output.

  Items         word          Number of CheckBoxes/RadioButtons
  Mask          LongInt       Set bits represent enabled items. (-1 in C++)
  Labels        string[Items] A series of label strings.  If Items = N,
                              then there will be N strings.
  MCBFlags      word          For TMultiCheckBoxes, numerical value of one
                              of the cfXXXX constants.  Otherwise 0.
  SelRange      byte          For TMultiCheckBoxes, the actual number of
                              states a cluster can assume.
  States        string        The characters that represent the states.

TListBox

  Columns       word          Number of columns
  ScrollBar     string        Variable Name (VarName) of attached scrollbar
                              or  "" for none.

TMemo

  TextFieldName string        The data record fieldname for the Text field.
                              (The FieldName field in the fixed part is the
                               Text length fieldname.)
  BufSize       word          The text buffer size.
  VScroll,
  HScroll       string        Variable names (VarName) of attached scrollbars
                              or "" for none.