home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / pascal / dlgdsn41.zip / SCRIPT.DOC < prev    next >
Encoding:
Text File  |  1993-08-07  |  12.9 KB  |  311 lines
  1.  
  2. This file serves to document the script file as well as the conversion
  3. programs supplied with Dialog Design.
  4.  
  5. CONVERSION PROGRAM CALLING SEQUENCE
  6.  
  7. For source generating conversion programs, Dialog Design uses the
  8. following calling sequence:
  9.  
  10.   progname.exe  <scriptname>  <outfilename> <errorfilename>
  11.  
  12. Where <scriptname> is the script input filename, <outfilename> is the
  13. name of the file the source code is to be written to, and <errorfilename>
  14. is a file to which errors are written.  In operation, Dialog Design
  15. first writes the script file and then calls the program as above.  If the
  16. exitcode is non-zero, the error file is then read and the error displayed.
  17. Both the script and error files are then deleted.
  18.  
  19. In the implementations supplied, <errorfilename> is made optional and if
  20. omitted, error output comes to the console.  This allows the conversion
  21. programs to be run from DOS as well as from within Dialog Design--an aid
  22. in debugging.
  23.  
  24. The calling sequence for the resource conversion programs is slightly
  25. different:
  26.  
  27.   progname.exe <scriptname> <resource filename> <resource ID> <errorfilename>
  28.  
  29. where an additional parameter for the resource ID string has been added.
  30. Before calling a resource conversion program, Dialog Design checks to see
  31. if the resource filename exists.  If it does, it then checks to see if it's
  32. actually an EXE file or a resource file of the appropriate type (C++ or
  33. Pascal).  Hence the conversion program does not have to make these checks.
  34. However, the conversion program is responsible for making a backup of the
  35. old file if that's desirable.
  36.  
  37.  
  38. READSCPT.PAS
  39.  
  40. READSCPT.PAS compiles into a Pascal unit which reads the script files output
  41. by Dialog Design.  It's used for all three Pascal conversion programs
  42. supplied.  If you decide to write your own conversion programs, you can
  43. probably use this unit without change.
  44.  
  45. In brief, READSCPT reads through the script file storing the information
  46. for the dialog and its controls in variant records (type ScriptRec).  The
  47. dialog itself has a record called Dialog and the control records are
  48. inserted in a TCollection named, ScriptColl.  Thus, once the script file is
  49. read, all the data is available for processing by the rest of the program.
  50.  
  51.  
  52. READSCPT.CPP
  53.  
  54. READSCPT.CPP and READSCPT.H similarly form a module for reading the script
  55. file.  It's used by all the supplied C++ conversion programs and can
  56. probably be used without change for any modified conversion programs.
  57.  
  58. READSCPT defines an abstract struct (ViewObj) to serve as a base object
  59. for later descendants.  In addition to defining fields common to all
  60. controls, three abstract code writing methods are also defined.
  61.  
  62. Also defined are script reading descendants of ViewObj for the dialog itself
  63. and each of the controls.  These descendants contain fields special to each
  64. control and have a contructor which reads it's portion of the script file
  65. and fills in the fields.
  66.  
  67. The final descendants of ViewObj are defined in the source code or resource
  68. generator module where the codewriting methods are fleshed out to do
  69. whatever is appropriate.
  70.  
  71. READSCPT requires that a function ( getKind() ) be defined in the codewriting
  72. section.  This function takes a single enum parameter which defines the basic
  73. type of control (button, inputline, etc.).  The return should be an instance
  74. of the final descendant of that basic type.  See any of the C++ conversion
  75. programs for an example of getKind().
  76.  
  77. As the script file is read, each ViewObj descendant is inserted in a
  78. TNSCollection named ScriptColl and the dialog itself is stored in Dialog.
  79.  
  80.  
  81.  
  82. SPECIAL CONTROL EXAMPLE
  83.  
  84. The supplied conversion files can be easily modified to accommodate specially
  85. derived controls.  PASSRC1 and CPPSRC1 already have an example of such a
  86. modification.  If you take a look at the demo, OPBUTTON.DLG, you'll see that
  87. it contains a special option button with a pointer name, POptionButton
  88. (TOptionButton would have been a better name in C++).  The constructor call
  89. for POptionButton is quite different from that of normal TButtons requiring
  90. two word parameters (here named PBOptions and PBEventMask) in addition to
  91. the normal TRect.  In addition, POptionButton also requires a special field
  92. in the dialog's transfer data record (here called AOptions).  This extra
  93. information has been entered in the control's 'Extra' dialog.
  94.  
  95. Both PASSRC1 and CPPSRC1 have a few extra lines of code added to be on the
  96. lookout for POptionButton and generate the proper constructor call for it.
  97.  
  98.  
  99. SCRIPT FILE
  100.  
  101. While looking over the documentation for the script file, it would be
  102. helpful for you to print out a sample script file as well as the Interface
  103. part of READSCPT.PAS (for Pascal users) or READSCPT.H (for C++ users).
  104.  
  105. The script file generated by Dialog Design is an ASCII file which consists
  106. entirely (except for the first item) of only two types of tokens, decimal
  107. numbers and double quoted strings.  Not much to be said about decimal
  108. numbers, but here's a few facts about the strings:
  109.  
  110.    "This is a string\n"
  111.  
  112.    There's three different escape sequences a string may contain:
  113.      '\n'    a newline
  114.      '\"'    a double quote within the string
  115.      '\\'    a backslash within the string
  116.  
  117.    A '+' immediately following the quote is used to indicate concatenation
  118.    with the next string.  In this manner strings of up to 255 characters
  119.    can be output with 80 or so characters per line.
  120.      "This is considered"+
  121.      "one string."
  122.  
  123. The layout for the script file consists of variable length records for the
  124. dialog itself followed by similar records for each control in the dialog,
  125. something like:
  126.  
  127.              |-----------------|
  128.              |  Version        |
  129.              |-----------------|
  130.              |  Reserved       |
  131.              |=================|
  132.              |  Fixed Part     |   -|
  133.              |-----------------|    |__ Dialog
  134.              |  Variable Part  |   -|
  135.              |=================|
  136.              |  Fixed Part     |   -|
  137.              |-----------------|    |__ Control
  138.              |  Variable Part  |   -|
  139.              |=================|
  140.                      .
  141.                      .
  142.              |=================|
  143.              |  Fixed Part     |   -|
  144.              |-----------------|    |__ Control
  145.              |  Variable Part  |   -|
  146.              |=================|
  147.              |  -1             |
  148.              |-----------------|
  149.  
  150. The script file starts off with "SCRIPT1" (but without the quotes in this
  151. case) followed by a newline.  This serves to verify the file IS a script
  152. file and supplies the version number.  A reserved section comes next--
  153. a single quoted string and a single number. Following this are the records
  154. for the dialog, and for each of the controls in the dialog.  The controls
  155. appear in Tab order (reverse Z order) except for TLabel's, THistory's,
  156. and attached TScrollBar's.  Labels and Historys immediately follow the
  157. control to which they're attached and attached ScrollBars immediately
  158. precede the control they're attached to.
  159.  
  160. The last control is followed with -1 to indicate there are no more.
  161.  
  162. The record for each control ( and the dialog itself) consists of a fixed
  163. part and a variable part.  The fixed part is identical for each type of
  164. control (although sometimes fields are blank).  The variable part varies
  165. with each type of control.
  166.  
  167. FIXED PART
  168.  
  169. Here's the order and contents of the fixed part:
  170.  
  171.    Name          Type              Example or comment
  172.  
  173.    Kind          RecType           Identifies the control type
  174.    BaseObj       string            "TInputLine"  (the basic type)
  175.    Obj           string            "PMyInputLine"/"TMyInputLine" (the
  176.                                    Pointer Name/Class Name)
  177.    X1,Y1,X2,Y2   Integer           The TRect
  178.    DefOptns      word              Default options for the control
  179.    Optns         word              The options as specified
  180.    DefEvMsk      word              Default EventMask for the control
  181.    EvMsk         word              The eventmask as specified
  182.    HCtx          word              Numerical value of help context
  183.    Grow          word              GrowMode for control (not used)
  184.    Param         string[6]         The 6 'Extra' parameters
  185.    HelpCtxSym    string            "hcNoContext"
  186.    FieldName     string            "field102"   (field name for data record)
  187.    VarName       string            "control"    (name given to this control)
  188.  
  189. See the BlockType definition (Pascal) or the ViewObj definition (C++).
  190. For each control, 'Kind' appears first in the script file and serves to guide
  191. the reading for the remainder of the variable record.  However, it isn't
  192. stored first in the Pascal record and isn't stored at all in the C++
  193. structure.
  194.  
  195. The default option and eventmask are included to enable a comparison to see
  196. which bits (if any) are being changed.
  197.  
  198. The six extra parameters are those that would be entered on the dialog
  199. accessed with the 'Extra' button.  You can use these for whatever you want.
  200.  
  201. For the dialog itself, FieldName is used to specify the name of the data
  202. record.
  203.  
  204.  
  205. Variable Parts
  206.  
  207.  
  208. Listed below are the variable parts for each control which appear after the
  209. fixed part.
  210.  
  211. Dialog
  212.  
  213.    Palette       word         Dialog Palette (not used in C++)
  214.    WinFlags      word         The dialog's  wfXXXX flags
  215.    DlgFuncName   string       "MakeDialog"/"makeDialog"
  216.    KeyString     string       Default resource ID string
  217.    Title         string       Dialog's Title
  218.  
  219. Button
  220.  
  221.    CommandName   string       "cmOK"
  222.    ButtonText    string       "~C~ancel"
  223.    CommandValue  word         The value of the command
  224.    Flags         word         The bfXXXX flag bits
  225.  
  226. Static Text
  227. Colored Text
  228.  
  229.    Attrib       word          Color Attribute (not used for TStaticText)
  230.    Text         string
  231.  
  232. InputLine
  233.  
  234. This is a messy one as it contains a varient record for Validators.
  235. Validators have no place in C++ yet.
  236.  
  237.    StringLeng   word          The number of characters that can be typed in.
  238.                               =MaxLen in Pascal, maxLen-1 in C++.
  239.    ValKind      ValType       Number indication type of validator, -1 for
  240.                               none.  Always -1 in C++.
  241.    ValPtrName   string        "PPXPictureValidator"
  242.  
  243. If ValKind is not -1, then the following fields are present.
  244.   Picture (1)
  245.    AutoFill     byte          non zero if AutoFill set.
  246.    PictureString string       The picture string.
  247.  
  248.   Range(2)
  249.    LowLim,
  250.    UpLim        LongInt       Range limits
  251.    Transfer     word          non zero if voTransfer bit set.
  252.  
  253.   StringLookup (3)
  254.    List         string        The string collection name or "Nil" for none.
  255.  
  256.   Filter (4)
  257.    CharSet      string        "['a'..'z', '_']"
  258.    ActualCharSet  LongInt[8]  A set of 8 numbers repersenting the actual
  259.                               character set.
  260.  
  261. TInputLong
  262.  
  263.   LongLabelText string        The text of the attached label.  Used as the
  264.                               6th parameter in the C++ constructor.
  265.   LongStrLeng   word          The number of characters that can be typed in.
  266.                               =MaxLen in Pascal, maxLen-1 in C++.
  267.   LLim, ULim    long int      Lower and upper range limits.
  268.   ILOptions     word          Options
  269.  
  270. TLabel
  271.   LabelText     string        The label's text.
  272.   LinkName      string        The variable name (VarName) of the control
  273.                               to which the label is linked.
  274.  
  275. THistory
  276.   HistoryID     word          History list number
  277.   HistoryLing   string        The variable name (VarName) of the control
  278.                               to which the THistory is linked.
  279.  
  280. TCheckBoxes
  281. TMultiCheckBoxes
  282. TRadioButtons
  283.  
  284. TMultiCheckBoxes won't appear in C++ output.
  285.  
  286.   Items         word          Number of CheckBoxes/RadioButtons
  287.   Mask          LongInt       Set bits represent enabled items. (-1 in C++)
  288.   Labels        string[Items] A series of label strings.  If Items = N,
  289.                               then there will be N strings.
  290.   MCBFlags      word          For TMultiCheckBoxes, numerical value of one
  291.                               of the cfXXXX constants.  Otherwise 0.
  292.   SelRange      byte          For TMultiCheckBoxes, the actual number of
  293.                               states a cluster can assume.
  294.   States        string        The characters that represent the states.
  295.  
  296. TListBox
  297.  
  298.   Columns       word          Number of columns
  299.   ScrollBar     string        Variable Name (VarName) of attached scrollbar
  300.                               or  "" for none.
  301.  
  302. TMemo
  303.  
  304.   TextFieldName string        The data record fieldname for the Text field.
  305.                               (The FieldName field in the fixed part is the
  306.                                Text length fieldname.)
  307.   BufSize       word          The text buffer size.
  308.   VScroll,
  309.   HScroll       string        Variable names (VarName) of attached scrollbars
  310.                               or "" for none.
  311.