Category : Miscellaneous Language Source Code
Archive   : DLGDS411.ZIP
Filename : SCRIPT.DOC

 
Output of file : SCRIPT.DOC contained in archive : DLGDS411.ZIP

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

Where is the script input filename, is the
name of the file the source code is to be written to, and
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, 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

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.


  3 Responses to “Category : Miscellaneous Language Source Code
Archive   : DLGDS411.ZIP
Filename : SCRIPT.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/