home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 12 / CD_ASCQ_12_0294.iso / maj / 535 / dlgdsn.doc < prev    next >
Text File  |  1994-01-10  |  22KB  |  621 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                                           January 9, 1994
  9.  
  10.                                  Dialog Design
  11.  
  12.                   A Dialogbox Design Program for Turbo Vision
  13.  
  14.                                   Version 4.1
  15.  
  16.                    (C) Copyright 1990-4 by L. David Baldwin.  
  17.                              All Rights Reserved.
  18.  
  19.   Further copyright information given below.
  20.  
  21.  
  22.   OVERVIEW
  23.  
  24.   Dialog Design takes some of the pain out of designing dialog boxes for 
  25.   Borland's Turbo Vision package.  With Dialog Design, dialog controls can be 
  26.   easily added, edited, rearranged, and the dialog itself sized, moved, etc.  
  27.   Once the design is satisfactory, Dialog Design can produce source code to 
  28.   be included in your program or a resource file for use by your program.  
  29.   Both the Pascal and C++ languages are supported.
  30.  
  31.  
  32.   REQUIREMENTS
  33.  
  34.     Borland (R) Pascal version 7.0 (Turbo Vision 2.0)
  35.       and/or
  36.     Borland C++ version 3.1  (Turbo Vision 1.0)
  37.        (Dialog Design version 2.x supports Turbo Pascal 6.0)
  38.     Some familiarity with the Turbo Vision package
  39.     VGA Monitor
  40.     A mouse is desirable
  41.  
  42.  
  43.  
  44.   GETTING STARTED
  45.  
  46.   Dialog Design uses a number of external conversion programs to generate 
  47.   source code and resources for the two languages supported.  If you have 
  48.   downloaded this package, the executables of the conversion programs may not 
  49.   have been included to save download time.  If not, you will first have to 
  50.   compile and link the source before you can do anything meaningful.  See the 
  51.   accompanying READ.ME file for information on how to do this.
  52.  
  53.   When first starting Dialog Design, a Configuration Information dialog will 
  54.   come up.  Enter your preliminary configuration here, in particular the 
  55.   language you will be using.  The default names for the conversion files 
  56.   will already be listed but you should probably add the complete path to 
  57.   these names unless they will always be in the default directory.
  58.  
  59.  
  60.  
  61.  
  62.                                       1
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.   On leaving the this dialog, you will be given the opportunity to save the 
  71.   configuration.  Once saved, you won't have to fill it out each time you 
  72.   start the program.  However, you can change the configuration at any time 
  73.   using the Options/Configuration menu selection.
  74.  
  75.  
  76.   A NOTE TO C++ USERS
  77.  
  78.   C++ currently only supports Turbo Vision 1.0.  Many of the entry dialogs in 
  79.   Dialog Design show Turbo Vision 2.0 options.  However, in C++ mode, these 
  80.   options will be grayed or otherwise made inaccessible.
  81.  
  82.  
  83.   DESIGNING A DIALOG BOX
  84.  
  85.   Dialog Design has three modes of operation:
  86.  
  87.     Design Mode
  88.  
  89.     Dialog Design begins in design mode and this is the mode that you use for 
  90.     all layout work and editing.  In design mode, the dialog doesn't look or 
  91.     act quite like it will in the final design.  Here's some of the 
  92.     differences:
  93.  
  94.        A 'canvas' background is used to better delineate the actual space 
  95.        occupied by each control.
  96.  
  97.        Controls are colored red when selected.
  98.  
  99.        Multiple controls may be selected.
  100.  
  101.        All controls may be selected even those not normally selectable.
  102.  
  103.     Try Mode
  104.  
  105.     Try mode is entered using the F9 key.  In try mode, the dialog behaves as 
  106.     it's supposed to.  You can check the Tab order, make temporary entries, 
  107.     and push buttons to actually check how things will work.  Exit try mode 
  108.     with the escape key or click on the close box.
  109.  
  110.     Ordering Mode
  111.  
  112.     Ordering mode allows you to change the Tab order of your dialog controls.  
  113.     The method for doing this is discussed further below.  The F8 key toggles 
  114.     you into and out of ordering mode.
  115.  
  116.   While there is no fixed way to design a dialog, here's one suggested 
  117.   sequence:
  118.  
  119.   1.In design mode, work with the dialogbox large enough so that you won't be 
  120.     crowded. 
  121.  
  122.  
  123.  
  124.                                       2
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.   2.From the Add menu, select a control to add.  This will bring up a dialog
  133.     where you can enter the necessary information.  Use the online help (F1 
  134.     key) if you have a question as to what goes in a particular field.  When 
  135.     the OK button is pushed, the control will appear in the lower right corner 
  136.     of the design box.  The control is then positioned by dragging it with the 
  137.     mouse, or by using the arrow keys (Shift+arrow moves a little faster).  
  138.     Work in the upper left corner of the box.
  139.  
  140.     A faster way to add controls is to use the Toolbox.  See Toolbox below 
  141.     for more details.
  142.  
  143.   3.Continue adding controls as desired.  At any time, controls can be 
  144.     repositioned or sized with the mouse (further details below).  If 
  145.     something other than position or size needs changing, select the control 
  146.     and from the Edit menu choose Edit Selected (or use F7).  This will bring 
  147.     up its dialogbox for changes.
  148.  
  149.   4.When all the controls have been added and positioned, size the box to fit 
  150.     and move it to the desired location on the desktop.  Be sure and add a 
  151.     title (Edit Dialog from the Edit menu).
  152.  
  153.   5.Enter Try Mode with the F9 key and test the dialog.  Be sure to check how 
  154.     the controls sequence using the Tab key.  Exit Try mode with Esc or click 
  155.     on the close box.
  156.  
  157.   6.If the Tab sequence needs changing, use F8 to enter ordering mode.  With 
  158.     the mouse, click on each control to establish the desired order.   Exit 
  159.     back to design mode with F8.
  160.  
  161.     Changing the sequence without a mouse is a little more complicated.  Use 
  162.     the Tab key to select (highlight) the next control to be sequenced.  Then 
  163.     press the Enter key to enter the selected control into the sequence.  
  164.     After all controls have been entered, exit back to design mode with F8.
  165.  
  166.     Some controls (such as Static Text, and Labels) don't enter into the 
  167.     tab sequence of a dialogbox.  You can order these if it's convenient, but 
  168.     the order won't effect the final results.  
  169.  
  170.     Be sure to recheck the tab order in Try mode.
  171.  
  172.   7.This is a good time to save your work.  Choose Save or Save As from the 
  173.     File menu to create or update a .DLG file.  Any file with the same name 
  174.     will be renamed with a .BKP extension.
  175.  
  176.   8.You can preview the source code to be generated by choosing one of the 
  177.     Write Source selections from the Operations menu, and then choosing the 
  178.     Screen button.  The code will appear in a viewer window.
  179.  
  180.   9.To create source code for your dialogbox, choose one of the Write Source 
  181.     selections from the Operations menu and then choose the File button.  See 
  182.     the section below on Conversion Programs for a discussion of the source 
  183.     code generated.
  184.  
  185.  
  186.                                       3
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.   10.To generate a resource file or add the new dialogbox to an existing 
  196.     resource or EXE file, choose Write Resource from the Operation menu.  
  197.     Both a filename and a resource ID name will be requested.  If the file 
  198.     already exists, it will be renamed with a .BKP extension.  If the 
  199.     existing file is a resource or EXE file, it will be copied, and the new 
  200.     resource added to the copy.  Any existing resource with the same ID will 
  201.     be deleted.  Note that the resource ID name is case sensitive.
  202.  
  203.  
  204.   SELECTING, CLICKING, DRAGGING, SIZING, ETC.
  205.  
  206.   To select a control, click and release on it with the left button or use the 
  207.   Tab key.
  208.  
  209.   To select multiple controls, select the first, then hold down the shift key 
  210.   while clicking on the others.  Note that, in this mode, clicking toggles 
  211.   selection on and off so it's possible to deselect as well as select.
  212.  
  213.   You can also select a block of controls by using the mouse to define an 
  214.   enclosing rectangle.  Position the mouse to one corner of the desired 
  215.   rectangle (the start position must not be on a control).  Hold the left 
  216.   button down and drag to the opposite corner of the rectangle before 
  217.   releasing the button.  During the drag operation, a shaded area will show 
  218.   the rectangle.  Those controls completely enclosed by the rectangle 
  219.   will be selected.  If the shift key is held down during this operation, any 
  220.   previously selected controls will remain selected.
  221.  
  222.   To select all controls, use the F4 key.
  223.  
  224.   To move controls, select the controls to be moved, then click on any one of 
  225.   them and, without releasing the button, drag the group to the desired 
  226.   position.  The group may also be moved using the arrow keys.
  227.  
  228.   To resize a control, first select it then click and drag on its lower right 
  229.   corner.  Note that some controls only size in one dimension and all have a 
  230.   minimum size.
  231.  
  232.   To edit a control, click it with the right button.  Or select it with the 
  233.   Tab key and press F7.  Either way brings up the control's Add/Edit dialog.
  234.  
  235.   To edit the dialog itself, click on the caption line with the right button.  
  236.   Or use the the Edit/Dialog menu selection.
  237.  
  238.  
  239.   TOOLBOX
  240.  
  241.   The toolbox provides a quick method for adding controls to the dialogbox.  
  242.   If the toolbox isn't visible, toggle it on with Ctrl-F6.  The toolbox may 
  243.   be repositioned by dragging its caption bar.
  244.  
  245.   To add a control using the toolbox, click and release on the appropriate 
  246.  
  247.  
  248.                                       4
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.   icon with the left button.  The control will pop off the toolbox and follow 
  257.   the mouse.  When you reach the desired location, click once more to drop 
  258.   the control.  At this point, the mouse will be properly positioned to size 
  259.   the control.
  260.  
  261.   If you pick up a control from the toolbox and then decide not to use it, 
  262.   drop it outside of the dialog or move the mouse off screen.
  263.  
  264.   From top to bottom, left to right, the control icons are:
  265.  
  266.     TInputLine         TStaticText
  267.     TInputLong         TButton
  268.     TCheckbox          TListBox
  269.     TRadioButton       TScrollbar (Vertical)
  270.     TMemo              TScrollbar (Horizontal)                                  
  271.                                                                                 
  272.   TLabel and TMultiCheckBox have no representation in the toolbox.                       
  273.                                                                                 
  274.   Once you've added controls from the toolbox, you'll need to edit them to 
  275.   supply further information.                                           
  276.                                                                                 
  277.   SOME DETAILS
  278.  
  279.   Command Line
  280.  
  281.   The command line used to load Dialog Design is:
  282.  
  283.     DLGDSN [<dialog filename>]
  284.  
  285.   The optional dialog filename specifies the name of a design file to be 
  286.   loaded.  If no extension is given, '.DLG' is assumed.
  287.  
  288.  
  289.   Duplicating Controls
  290.  
  291.   Sometimes it is desirable to make a series of similar controls as might be 
  292.   found in a column of TInputLines, for instance.
  293.  
  294.   Controls may be duplicated by holding down the control key and left 
  295.   clicking with the mouse.  A copy of the control will appear directly below 
  296.   the copied control.
  297.  
  298.   You can also duplicate a control by selecting it and using the Edit|Copy 
  299.   Control menu command.
  300.  
  301.  
  302.   @ Operator for Text Entry
  303.  
  304.   The '@' operator may be used almost anywhere text input is required to 
  305.   indicate a variable reference is desired rather than a quoted string.  To 
  306.   indicate a variable reference, just enter '@' as the first character 
  307.   following it with the variable name.
  308.  
  309.  
  310.                                       5
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.   As an example, suppose (for a TStaticText entry) you enter 'This is a line 
  320.   of text.'  Dialog Design will generate code which looks like:
  321.  
  322.    Control := New(PStaticText,
  323.        Init(R, 'This is a line of text.'));      {for Pascal}
  324.    control = new TStaticText(TRect(8, 3, 25, 4),
  325.        "This is a line of text.");               //for C++
  326.  
  327.   But if you enter '@theText', you'll get code which looks like:
  328.  
  329.    Control := New(PStaticText,
  330.        Init(R, theText));                 {for Pascal}
  331.    control = new TStaticText(
  332.        TRect(8, 5, 23, 6), theText);      //for C++
  333.  
  334.   where 'theText' presumably refers to a string defined elsewhere.
  335.  
  336.  
  337.   Options Button
  338.  
  339.   Most of the Add/Edit dialogs have an Options button.  This button brings up  
  340.   another dialog which will let you change the default ofXXXX and evXXXX flag 
  341.   and mask bits.  In most cases, you'll want to stick with the defaults but 
  342.   some bits do have interesting uses.  In particular, the ofFramed bit can be 
  343.   used for framing controls.  Also, with a little effort, you can frame 
  344.   groups of controls or divide the dialog into panes.  The context sensitive 
  345.   help (F1) for the options dialog has some hints on this.
  346.  
  347.   Extras Button
  348.  
  349.   Many of the Add/Edit dialogs also have an Extras button.  This button 
  350.   brings up a dialog where you can add parameters or other information about 
  351.   non-standard controls (controls that you have derived).  This information 
  352.   is only of use if you are customizing your own conversion programs.
  353.  
  354.   Help Context
  355.  
  356.   Many of the Add/Edit dialogs have fields labeled Help Context and Value.  
  357.   By default, these contain hcNoContext and 0.  Dialog Design uses the help 
  358.   context symbol when generating source code and the value when producing a 
  359.   resource.
  360.  
  361.   For small projects, it may be convenient just to enter this information by 
  362.   hand.  However, if you're using Borland's demo help compiler, TVHC, Dialog 
  363.   Design can work with the help definition file it produces.  To do this, 
  364.   choose Load Help Ctx file from the Options menu and supply the filename of 
  365.   the help definition file.  Then clicking on the '*' box next to the help 
  366.   context field (or typing '*' in the field) will bring up a pick list of the 
  367.   definitions from which to choose.
  368.  
  369.   You can also automatically load your help definition file at startup by 
  370.  
  371.  
  372.                                       6
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.   entering the information in the Configuration dialog (Options/Configuration 
  381.   on the menu).
  382.  
  383.   During the various iterations of writing a help file, the numerical values 
  384.   associated with the help symbols are often changed.  However, once a help 
  385.   context symbol has been entered for a control, Dialog Design will keep its 
  386.   associated help value current.  Updating occurs whenever:
  387.  
  388.        A .DLG file is already loaded and a help context file is loaded
  389.     or
  390.        A help context file has been loaded and a new .DLG file is loaded.
  391.  
  392.  
  393.   Reading Pascal TDialog Resources  (Operations/Load Pascal Resource File)
  394.  
  395.   You can read Pascal (not C++, unfortunately) TDialog resources from 
  396.   compatible resource files generated by Dialog Design or other design 
  397.   programs such as Blaise' Turbo Vision Development Toolkit(tm).  You'll be 
  398.   asked for the resource filename and then given a list of resource ID's from 
  399.   which to choose.
  400.  
  401.   Dialog Design will read only TDialog resources with controls that it 
  402.   supports.  In the read process, the following conversions are made:
  403.  
  404.      TListViewer to TListBox
  405.      TParamText  to TStaticText
  406.      TView       to TStaticText (with no text)
  407.  
  408.   Note:  You should always save your design in .DLG files.  Storing them as 
  409.   resources and reading them as resources will result in loss of information.
  410.  
  411.  
  412.   CONVERSION PROGRAMS AND SOURCE CODE
  413.  
  414.   In this version of Dialog Design, all source code and resource generation 
  415.   is done by external conversion programs.  When you select one of the source 
  416.   code options from the menu, the following process occurs:
  417.  
  418.     1. A temporary ASCII script file is written to disk.
  419.     2. The appropriate conversion program is called with parameters telling 
  420.        it the script filename, the output filename, and an error filename.
  421.     3. The conversion program produces the desired conversion from script 
  422.        file to source code (or resource), or possibly returns error messages.
  423.     4. Dialog Design displays any error messages and deletes the temporary 
  424.        files.
  425.  
  426.   The above process is largely transparent to the user but because it uses 
  427.   external programs, it allows for user customization of these programs.  
  428.   (Customization is covered in separate documentation.)
  429.  
  430.   Here's a summary of the conversion programs supplied with Dialog Design:
  431.  
  432.  
  433.  
  434.                                       7
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.     PasSrc1, CppSrc1
  443.  
  444.     The source output for these two programs is similar (except for the 
  445.     language, of course) and closely resembles the source generated by 
  446.     previous versions of Dialog Design.  Source is in the form of a function 
  447.     (MakeDialog/makeDialog) which defines the dialog and returns a pointer to 
  448.     it.  A data record/structure is also defined to assist in transferring 
  449.     data into and out of the dialog.  The generated source code may be 
  450.     included in the files TestCase.Pas/TestCase.Cpp (at the line of 
  451.     asterisks) to form a test program for the dialog.
  452.  
  453.     PasSrc2
  454.  
  455.     Output from PasSrc2 is in the form of a Pascal unit with the dialog 
  456.     object being defined in the Interface section and the actual dialog 
  457.     construction done in the dialog's constructor.  This form is probably 
  458.     more suitable for dialogs which require overridden methods such as 
  459.     HandleEvent.  PasSrc2 uses an auxiliary (ASCII) file, Skel.Dat, to layout 
  460.     the unit structure.  When using PasSrc2, you should change the default 
  461.     PDialog pointer name as you're really defining a TDialog descendent.
  462.  
  463.     CppSrc2
  464.  
  465.     CppSrc2 produces a module and header file for a TDialog descendent with 
  466.     the dialog construction done in the constructor.  This form is probably 
  467.     more suitable for dialogs which require overridden methods such as 
  468.     handleEvent.  CppSrc2 uses an auxiliary (ASCII) file, CppSkel.Dat, to 
  469.     layout the file structure.  Be sure and change the dialog's class name 
  470.     from TDialog to something appropriate for your new class.
  471.  
  472.     The file generated by CppSrc2 contains a line "cut here" where it can be 
  473.     divided to form a .h and a .cpp file.
  474.  
  475.     PasRsrc, CppRsrc
  476.  
  477.     These files generate Pascal and C++ TDialog resources.  Resources can be 
  478.     added to an existing resource or EXE file, or a new resource file 
  479.     started.  You will be asked to enter a resource ID string (case sensitive 
  480.     and must not contain spaces).  Any existing resource or EXE file will be 
  481.     renamed with a .BKP extension, copied, and the resource added to the 
  482.     copy.  If the ID corresponds to an existing resource, that resource will 
  483.     be deleted.
  484.  
  485.     User
  486.  
  487.     A Space where you may include your own program.
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.                                       8
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.   COPYRIGHT AND REGISTRATION
  505.  
  506.   Documentation and Program (C) Copyright 1990-4 by L. David Baldwin.  
  507.   All Rights Reserved.
  508.  
  509.   Dialog Design may be copied and distributed freely (including uploading it 
  510.   to bulletin boards), providing:
  511.  
  512.     1. No fee is charged and it is not part of a package for which a charge 
  513.        is made.
  514.     2. The package is not modified in any way.
  515.  
  516.   If you do upload this package to a bulletin board,  I'd appreciate it if 
  517.   you would make an attempt to keep the upload current.
  518.  
  519.   If you use Dialog Design professionally (to assist in program creation for 
  520.   your employer or for sale) please send $30 along with your registration to 
  521.   the appropriate address listed below.  Registration entitles you to a free 
  522.   update to the most recent version or an update to the next release.  No 
  523.   usage fee is required for hobbyists, students, beginners, occasional users, 
  524.   etc.
  525.  
  526.   Please report any problems, suggestions, etc.  Contact me on Compuserve or 
  527.   Internet (the best way) or at one of the addresses below.
  528.  
  529.   Dave Baldwin
  530.   CompuServe ID #76327,53.
  531.   Internet address: 76327.53@compuserve.com
  532.  
  533.  
  534.   ACKNOWLEDGEMENTS
  535.  
  536.   Help file modifications from Peter Brandstrom's TVTOYS.ZIP.
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.                                       9
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.                                  REGISTRATION
  567.  
  568.  
  569.         Name: __________________________________________________________
  570.  
  571.         Telephone: ________________________CompuServe ID:_______________
  572.  
  573.         Address: _______________________________________________________
  574.  
  575.         Address: _______________________________________________________
  576.  
  577.         City: __________________________________________________________
  578.  
  579.         State/Country:______________________ Postal Code: ______________
  580.  
  581.  
  582.         Present Dialog Design Version:___________Pascal/C++:____________
  583.  
  584.  
  585.   Bugs, Problems, Comments: ____________________________________________
  586.  
  587.      ___________________________________________________________________
  588.  
  589.      ___________________________________________________________________
  590.  
  591.      ___________________________________________________________________
  592.  
  593.      ___________________________________________________________________
  594.  
  595.      ___________________________________________________________________
  596.  
  597.      ___________________________________________________________________
  598.  
  599.      ___________________________________________________________________
  600.  
  601.  
  602.   Professional users:  Please send along with $30 to:
  603.  
  604.   David Baldwin,
  605.   22 Fox Den Rd.,
  606.   Hollis, NH 03049        (Approx May 15 to Oct 15)
  607.   (603) 465-7857
  608.  
  609.   David Baldwin,
  610.   144 13th St. East,
  611.   Tierra Verde, FL 33715  (Approx Oct 15 to May 15)
  612.   (813) 867-3030
  613.  
  614.   Since mail is forwarded, either address may be used.
  615.  
  616.  
  617.  
  618.  
  619.  
  620.                                      10
  621.