





                                    The DialogPro
                                           
                *  * * * *  Users Guide and Reference Manual * * * * *
                                           
                                   by Kenneth Stott
                                     version 2.0
                                           
                                           
                                           
                                           
                                           
                                           
                                           
                                           
                                           
                                           
                                  Seabreeze Software
                                 397 Dal-Rich Village
                                      Suite 169
                               Richardson, Texas 75080
                                    (214) 437-2729
                                           
                                           
                                           
                                           
                                           
                                           
                       Copyright (c) 1987-1988 by Kenneth Stott
                                 All Rights Reserved
                                           
                                           
                                           
                                           
                                           
                                           
                                           
                                           
                                           
          The DialogPro shareware diskette, containing a copy of this
          manual, may be freely copied and shared.  But, printed copies of
          this document may not be copied by any method without the express
          written permission of Seabreeze Software.





















          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          I.    Introduction . . . . . . . . . . . . . . . . . . . . .    1
          II.   Overview . . . . . . . . . . . . . . . . . . . . . . .    3
          III.  Technical Notes  . . . . . . . . . . . . . . . . . . .    5
          IV.   Shareware  . . . . . . . . . . . . . . . . . . . . . .   12
          V.    Registration . . . . . . . . . . . . . . . . . . . . .   13
          VI.   Support Details  . . . . . . . . . . . . . . . . . . .   15
          VII.  Diskette . . . . . . . . . . . . . . . . . . . . . . .   16
          VIII. Installation . . . . . . . . . . . . . . . . . . . . .   18
          IX.   Compiling and linking the demo . . . . . . . . . . . .   19
          X.    Changes between version 1.0 and 2.0  . . . . . . . . .   20
          XI.   Future enhancements  . . . . . . . . . . . . . . . . .   22
          XII.  Reference  . . . . . . . . . . . . . . . . . . . . . .   23
             A. Introduction . . . . . . . . . . . . . . . . . . . . .   23
             B. Functions  . . . . . . . . . . . . . . . . . . . . . .   24
                1.  db_display . . . . . . . . . . . . . . . . . . . .   24
                2.  db_displayq  . . . . . . . . . . . . . . . . . . .   24
                3.  db_flushqueue  . . . . . . . . . . . . . . . . . .   25
                4.  db_freestorage . . . . . . . . . . . . . . . . . .   25
                5.  db_pop . . . . . . . . . . . . . . . . . . . . . .   26
                6.  db_priority  . . . . . . . . . . . . . . . . . . .   26
                7.  db_push  . . . . . . . . . . . . . . . . . . . . .   26
                8.  db_restoreanswers  . . . . . . . . . . . . . . . .   27
                9.  db_run . . . . . . . . . . . . . . . . . . . . . .   27
                10. db_selectq . . . . . . . . . . . . . . . . . . . .   29
                11. db_storeanswers  . . . . . . . . . . . . . . . . .   30
                12. db_switchqueue . . . . . . . . . . . . . . . . . .   31
                13. lst_display  . . . . . . . . . . . . . . . . . . .   32
                14. lst_displayitem  . . . . . . . . . . . . . . . . .   33
                15. lst_freestorage  . . . . . . . . . . . . . . . . .   34
                16. lst_restoreanswers . . . . . . . . . . . . . . . .   34
                17. lst_run  . . . . . . . . . . . . . . . . . . . . .   35
                18. lst_select . . . . . . . . . . . . . . . . . . . .   37
                19. lst_storeanswers . . . . . . . . . . . . . . . . .   37
                20. lst_toggle . . . . . . . . . . . . . . . . . . . .   38
             C. Standard Return Values . . . . . . . . . . . . . . . .   39
             D. Data structures  . . . . . . . . . . . . . . . . . . .   40
                1.  button . . . . . . . . . . . . . . . . . . . . . .   40
                2.  db_colors  . . . . . . . . . . . . . . . . . . . .   41
                3.  db_delimiters  . . . . . . . . . . . . . . . . . .   42
                4.  dialog_box . . . . . . . . . . . . . . . . . . . .   43
                5.  free_form  . . . . . . . . . . . . . . . . . . . .   45
                6.  list . . . . . . . . . . . . . . . . . . . . . . .   46
                7.  list_rec . . . . . . . . . . . . . . . . . . . . .   49
                8.  multi_choice . . . . . . . . . . . . . . . . . . .   52
                9.  rcbutton . . . . . . . . . . . . . . . . . . . . .   54
                10. reducer  . . . . . . . . . . . . . . . . . . . . .   55
                11. scroll_txt . . . . . . . . . . . . . . . . . . . .   58
                12. title  . . . . . . . . . . . . . . . . . . . . . .   59
             E. Global variables . . . . . . . . . . . . . . . . . . .   60
                1. db_head, db_tail, db_queue  . . . . . . . . . . . .   60
                2. default_db_cmds . . . . . . . . . . . . . . . . . .   60
                3. idle  . . . . . . . . . . . . . . . . . . . . . . .   60
                4. monitor_switch, _fg, _bg, _speed, _wdw, _tile . . .   60
                5. mouse_sensitivity . . . . . . . . . . . . . . . . .   61



                               - Table of Contents 1 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


             F. Messages . . . . . . . . . . . . . . . . . . . . . . .   62
                1. Dialog Box  . . . . . . . . . . . . . . . . . . . .   62
                2. Line Editor . . . . . . . . . . . . . . . . . . . .   65
                3. list question . . . . . . . . . . . . . . . . . . .   67
                4. Pull down list  . . . . . . . . . . . . . . . . . .   68




















































                               - Table of Contents 2 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          I.    Introduction
          
          The DialogPro will help you implement one of today's hottest user
          interface analogies, the dialog box.  The dialog box, popularized
          by Apple, is now a mainstay in almost all modern PC based
          software.  And it is here to stay.  Despite not being invented by
          IBM, it is included in their latest SAA user interface standards.
          
          If you don't already know, The dialog box is a pop-up window with
          a form inside of it.  The form consists principally of questions,
          these questions can be checklists, multiple choice questions
          (sometimes known as radio buttons,) scrolling lists, and
          buttons.  Buttons are special because they can indicate to
          perform some sort of action.  Typically the action will be
          something like, confirm the answers to the other questions, or
          abort the dialog box (restore the old answers and return to the
          previous process.)  The dialog box is a familiar sight to most
          personal computer users and is a tremendously simple way to get a
          solid, consistent, user interface into your applications.
          
          The bad news is that dialog boxes, while making life easier for
          the user, are difficult to implement.  This is particularly true
          in a mouse environment -- where a user can literally click (or
          point, or press, or drag, etc., etc.) on any thing he sees on the
          screen -- how do you deal with that in a traditional structured
          programming style?  
          
          The answer is you don't have to, at least not directly.  Most
          programmers work in a competitive, cost conscious environment and
          don't have the time to ponder messaging and object orientation. 
          The DialogPro lets you use the latest techniques, without
          sweating the details.  It lets you put the latest, most
          professional, Microsoftish/Borlandish/Macontish interface on your
          programs without the pain.  Your users will be able to hang onto
          to their mice and learn your programs faster (even if you don't
          get it -- A lot people have fallen in love with the mouse.)  And
          you'll be relieved of a big part of the programming, the
          training, and the support.
          
          The DialogPro is tremendously flexible.  Every dialog box
          understands over 60 commands -- you program these commands to any
          keystrokes you like.  Create additional commands, hot-keys, etc.
          by defining macro-commands and attaching them to keystrokes. 
          Automatically update target variables in your applications. 
          "Hook" in your own routines directly into dialog box questions. 
          Perform edit checking and field updating/formatting on the fly,
          anything you can imagine.
          
          There are just so many uses for the DialogPro that it is hard to
          list them all here.  But things like interreferenced help systems
          a la Lotus 1-2-3 are pretty straight forward.  Likewise, creating
          a user interface that conforms to SAA standards would be easy. 
          The DialogPro is perfect for desktop oriented applications
          because at the heart of the DialogPro are sophisticated,



                                        - 1 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          object-oriented, messaging algorithms.  But the DialogPro is just
          as comfortable sprucing up existing programs because the
          sophistication is literally "at the heart" of The DialogPro;
          ready to be put to use when you need it--but ingeniously "hidden"
          until you want it.  And that really is the key to The
          DialogPro--it gives you what YOU want, adapts to your style.



















































                                        - 2 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          II.   Overview
          
          The user sees a dialog box like this.  A form to fill in.  A
          dynamic form where lists can scroll, amounts fill in
          automatically, and buttons can be pushed to continue or perform
          other actions.
          
              +[  Personal Information  ]-----------------+
              |                                           |
              |  Name : _________________________________ |
              |  Street : _______________________________ |
              |  City : _________________________________ |
              |  State : __   Zip Code __________________ |
              |                                           |
              |  Occupation :    +----------------------+ |        
              |                  |[ ] Doctor           ^^ |
              |  +=========+     |[ ] Dentist          || |
              |  | Confirm |     |[ ] Lawyer           || |
              |  +=========+     |[ ] Accountant       oo |
              |  +---------+     |[ ] Mechanic         || |
              |  |  Abort  |     |[ ] Engineer         vv |
              |  +---------+     +----------------------- |
              +-------------------------------------------+
          
          The programmer sees this as a hierarchical data structure.  The
          dialog box is a structure with a series of subordinate data
          structures representing the various questions, buttons, and
          lists.  As the programmer your principal task is to create these
          data structures.  The db_run and db_display functions are then
          used to execute and/or display the dialog boxes.
          
          In the above example your would first define a dialog box
          structure.  You would then define free_form (or
          fill-in-the-blank) structures for the Name, Street, City, and Zip
          Code fields.  The State field could be represented as either a
          multiple choice question, a reduction question (where the user
          supplies part of the answer and the dialog box attempts to
          determine the correct answer or displays a list of possible
          answers to select from -- like all the states that begin with M,
          for example,) or it could be just another fill in the blank
          question.
          
          Confirm and Abort would be defined as button structures and
          Occupation would be list structure.
          
          To see an example of how to create a simple dialog box see the
          included source file, SIMPLEDB.C.
          
          Of course, if this were the end of the story The DialogPro
          wouldn't be all that useful.  There are several default data
          types to help you get started but ultimately the programmer has
          final control over virtually every aspect of how a dialog box
          looks and operates.  For example,
          



                                        - 3 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


            .  You can position questions anywhere in the pop-up window, or
               in separate tiles of a pop up window, even create paged
               dialog boxes by swapping tiles in and out.
            
            .  You can control how the questions are presented to the
               user.  Including delimiter characters, the position of the
               statement describing the question, where the response to the
               question should be located, the maximum length of the
               response, the color of the statement, the color of the
               response, and many more aspects.
            
            .  You may assign target variables to questions. Target
               variables are automatically updated with the responses to
               questions as they are answered.
            
            .  You can control the order that the user navigates to the
               questions.
            
            .  You can "hook" in pre and/or post routines to each
               question.  Using the pre/post routines you can do edit
               checking, field updating, even modify the user interface.
            
            .  You can indicate that questions are "unavailable" for
               modification.  In a graphics environment this is sometimes
               known as "greying" out a choice.
            
            .  You can extend both the mouse and keyboard interface by
               creating macros to define completely new commands and
               features, or combine or modify existing features.  Macros
               can call your own routines or simply expand into a series of
               alternative messages.  This feature alone makes the
               DialogPro almost infinitely extendable.
            
























                                        - 4 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          III.  Technical Notes
          
          This section describes what you'll need to use The DialogPro, any
          limitations you should be aware of, and describes (in further
          detail) the theory of operation.
          
          
          The WindowPro
          
          The DialogPro is based on The WindowPro.  You must have The
          WindowPro to use The DialogPro.  Just like The DialogPro, The
          WindowPro is also available from Seabreeze Software.
          
          If you have The WindowPro, and it works on your machine and
          compiler, then so will The DialogPro.  (Note: The DialogPro is
          currently only tested with Quick-C 1.X, MSC C 5.X, and Turbo C
          1.X compilers.)
          
          Size
          
          The DialogPro adds 30 to 40K of code to your application, in
          addition to requiring virtually the full WindowPro library (which
          adds about another 60K.)
          
          
          What is a dialog box?
          
          Dialog boxes and questions are hierarchical data structures. 
          Each dialog box routine operates on a given data structure. 
          Because they are data structures you can modify them, on the
          fly.  In fact your pre/post routines can "grey-out" options,
          update fields, and remove questions dynamically by doing just
          that.  The dialog box routines interpret the data structures to
          display the dialog box, select methods of dealing with user
          commands, etc.  As such, the application programmers main task is
          to "fill-in" these data structures properly.  
          
          
          Messages at first glance
          
          The major dialog box routine is db_run.  db_run handles the bulk
          of the work, interpreting all messages and parceling out the work
          to the lower level routines.  They each have their own keyboard
          and mouse handlers so that they operate as closed systems or
          black boxes.  You call the routines, they execute, put the
          results into the target variables, and return to the calling
          function.  The application programmer doesn't deal with message
          queues, keyboards, or mice--A BLACK BOX.  
          
          But inside the black box keyboard and mouse handlers interpret
          keyboard and mouse activity into messages.  The messages are then
          placed into a queue and processed.  Despite being somewhat





                                        - 5 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          "invisible" the capability to manipulate the message queues is
          there.  Manipulating messages directly can give you added
          flexibility.
          
          
          Using the KEYBOARD
          
          Each of the "standard" commands recognized by a dialog box (see
          DBOPS.H for a complete list) can be associated with a keyboard
          code (a scan code & ascii code two byte sequence.)  This keyboard
          interface is represented as an array of integers where its
          position in the array relates to the standard message value, i.e.
          a message with a value of 1 is created when the keyboard code in
          the first position (the 0th element) in the array is recognized,
          a message with a value of 2 for the second position, etc.
          
          
          Using the MOUSE
          
          First, in the same way that the keyboard generates dialog box
          messages, so do the mouse handler routines.  You can even modify
          the mouse interface (although not as directly as the keyboard
          interface) by defining macros which intercept the mouse generated
          messages and redefine those messages.
          
          However, practically speaking the difference between the mouse
          and the keyboard is that the mouse can click on "things" it sees
          on the screen that may not be related to the current process.  In
          general terms the way this is dealt with is -- when a mouse event
          is recognized we determine if it is "within" the screen space
          representing the "object" (like a dialog box's window for
          instance.)  Next, if it is within the "object's" boundaries we
          compare the mouse hit's location to the areas occupied by all of
          the sub-objects related to the current object.  If the hit was on
          a sub-object.  We call the sub-objects calling routine and pass
          it a message indicating that a mouse hit happened within its
          boundaries.  The sub-object then goes through the same process
          until eventually one of these subordinate objects deals with the
          mouse hit by modifying its data structure in some way -- for
          example by indicating that a certain item in a list is selected. 
          
          A mouse hit which happens outside of the boundaries of the
          current object is handled in a similar way by exiting the current
          routine with a value indicating to the superior object that it
          has a mouse hit outside of its boundaries.  The superior object
          then deals with the mouse hits in the same way as described
          above.
          
          To be more specific on how this is dealt with in The DialogPro, 
          consider the db_run routine.  Simply executing
          db_run(db_data_ptr, 0) would display the dialog box represented
          by db_data_ptr and begin gathering input from the keyboard and
          mouse, interpreting those into messages, and executing the
          messages.  The second parameter indicates the first message to be



                                        - 6 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          executed, normally this is 0 (indicating no message.)  Of course
          you can use this for anything you want -- but the major purpose
          is for letting the dialog box deal with a mouse hit inside of its
          window borders, i.e. if a mouse hit is detected inside of a
          dialog box, while the application is executing another routine,
          that routine would execute db_run(db_data_ptr, MOUSE_EVENT).  The
          MOUSE_EVENT indicates to take the last mouse activity returned by
          The WindowPro function kb_mouseclicks and interpret it into a new
          message, like select a question, edit a response, etc.
          
          To apply this to the real world, suppose you are writing "ZIPPY
          WORD PROCESSOR".  The entire screen is reserved for editing text,
          but you have a dialog box on the screen to let the user change
          formatting characterstics.  While editing text you poll both the
          keyboard and the mouse (using kb_mouseclicks.)  If the keyboard
          is hit you deal with it as you would in a traditional program.
          But if a mouse event takes place you could deal with it like
          this-- Via kb_mouseclicks you recognize that the user has clicked
          the mouse.  Using wn_whereon you determine that he has clicked in
          the formatting dialog box.  So, you call
          db_run(format_dialog_box, MOUSE_EVENT).  db_run picks it up from
          this point. 
          
          It determines that the last mouse event was indeed inside the
          format_dialog_box, on a question representing the value of the
          right hand margin.  db_run executes the line editor placing the
          cursor where the user clicked his mouse.  The user edits the
          right margin value.  Via the "post" question routines you
          attached to this question it checks to make sure that the value
          is greater than the left hand margin.  The user then "clicks"
          back inside of the text editor.  db_run now updates the target
          variables in your application hooked into the dialog box,
          updating your global variable RIGHT_MARGIN with the new value,
          and exits.  
          
          Now its your turn.  Based on db_run's exit value you know that
          the user has clicked outside of the formatting dialog box, you
          check to see if your formatting variables have changed.  They
          have so you reformat the document.  You then check to see if the
          use clicked inside of the text editor (using wn_whereon) he has
          so you position the cursor at the location of the last mouse
          click, and go back to editing text.
          
          
          Creating and Interpreting Messages
          
          To understand how messages are created and interpreted.
          
          Each data structure has a function to display it and execute it. 
          Each of these functions handles messages like this.
          
               1.   It takes the message passed as a parameter and puts it
                    at the head of the current circular queue.
          



                                        - 7 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


               2.   It looks for a message at the tail of the queue.
          
                    A.   If a message is found:
                    
                         a.   It first looks up the message in the macro
                              list.  If the message is a macro it expands
                              the macro by putting the new messages at the
                              tail of the queue, and then returns to step
                              2,
          
                         b.   Messages must have a value of less than 256. 
                              If the message has a value of greater than
                              256 we assume that it is an extended keyboard
                              code.  The extended kyeboard code is
                              intepreted into a "real" message".  The
                              "real" message is placed at the tail of the
                              queue,  and it then returns to step 2.
                         
                         c.   If we make it past steps 2.A.a and 2.A.b we
                              execute the message.  The CONFIRM, ABORT, 
                              SPECIAL messages terminate db_run and return
                              back to the calling function.  If the message
                              is not one of the above it returns to step 2
                              to get another message to execute.
          
                    C.   If no message is found, it polls the mouse and the
                         keyboard waiting for activity.  If activity is
                         found, the activity is interpreted into a message
                         and put at the tail of the queue -- it then
                         returns to step 2.
          
          
          You can modify the behavior of The DialogPro by manipulating the
          message queues.  Several functions are provided for putting
          messages at the head and the tail, and for reading the message
          queue. 
          
          
          The Questions
          
          FREE_FORM
          
          Free form questions are used to gather one line text responses. 
          The text can be up to a thousand characters long.  The response
          area can be any size.  While editing, the response text scrolls
          within the response area.  The line editor has home, end, word
          right/left, and character right/left, backspace and delete
          functions.  Clicking on any character places the cursor on the
          character.
          
          
          MULTI_CHOICE
          




                                        - 8 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          Multiple choice questions can be configured to operate as pull
          down menus or as more traditional multiple choice questions.  The
          principle difference is that the current response to a multiple
          choice question is displayed in the response area.  The pulldown
          menu type doesn't display the current response.
          
          The user cycles through the responses to a multiple choice
          question with PRESS_BUTTON, or selects the next response
          beginning with a specific character, or pulls down the list of
          available choices with the DESCEND or EXPAND commands -- and then
          selects his choice from the complete list.  With the mouse, the
          user cycles through the available responses by clicking on the
          response area.  He pulls down the list of available responses by
          double-clicking, or holding, on the response area.
          
          
          RADIO BUTTONS
          
          Radio buttons serve the same purpose as multiple choice
          questions, except that all of your available choices are
          displayed in the dialog box rather than just your currently
          selected choice.
          
          
          CHECKBOXES
          
          Checkboxes let you toggle an item on and off.
          
          
          REDUCER
          
          Reducer questions operate just like free_form except that after
          confirming DialogPro compares the response to a list of available
          responses.  If there is only one response which matches the
          current response -- nothing happens.  If more than one available
          response begin with the same letters as the given response, the
          response is considered ambiguous and a list of possible matches
          is displayed in a pulldown list.  The user then selects his
          response from the pulldown list.
          
          The user can skip the reduction stage and go straight to the list
          by pressing EXPAND.
          
          The user can view the entire list by double-clicking or holding
          on the response area with the mouse.
          
          
          LIST
          
          There are two types of lists, select list and checklist.  The
          checklist allows more than one item to be "checked-off."  he
          select list allows only one item at a time to be "checked-off."
          




                                        - 9 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          A list response area is rectangular.  If the list is bigger than
          the rectangular area the user can scroll the list.
          
          The user can modify the selections by placing the cursor inside
          the list.  The user can then check-off items using PRESS_BUTTON
          or navigate to another question.  
          
          With the mouse, clicking on an item in the list will toggle it
          between checked and un-checked.  Holding or clicking on the
          scroll bar hotpoints, or holding and dragging the scroll bar
          thumbwheels scroll the list.
          
          
          BUTTON
          
          The user executes a button by pressing the key it is "bound" to. 
          Pressing the "bound" key will place the button's command key in
          the message queue.  This lets buttons behave as another way of
          executing a CONFIRM, or ABORT, or any command -- or keystroke.  A
          kind of visual representation of commands.
          
          You can also execute a key by pressing its mnemonic key.  Its
          mnemonic key will first make the button the selected question and
          then put the command key in the message queue.  The basic
          difference is that the first method does not change the selected
          question, or highlighting.  This method changes the highlighted
          item to the button.
          
          You can also execute a button by navigating to it (or
          highlighting it) and then executing PRESS_BUTTON.
          
          With the mouse, clicking on a button is the same as pressing the
          "bound" key.  Holding on a button and then releasing it the same
          as pressing the mnemonic key.
          
          Buttons may or may not have a border.  Buttons without borders
          are useful for making words in a text behave like hot-points
          (useful in hypertext type applications, help screens, etc.) or in
          creating new hot-points that work like the scroll bars, for
          example, creating a sliding scale in a dialog box would be done
          with borderless buttons representing different parts of the scale
          (an up button, a down button, the scale itself, etc. -- this lets
          users literally reach out and grab a piece of your invention and
          move it around the screen, pull levers, push buttons, and move
          sliding scales.)
          
          SCROLLING TEXT
          
          Scrolling text questions is really a misnomer.  Scrolling text
          allows you to place a sub-window within the dialog box and then
          associate a controlling routine with that sub-window.  Some of
          the common uses for this would be, for example, a box of
          scrolling text, or a sub-dialog box.  Sample control routines for




                                       - 10 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          both of these types of SCROLLING TEXT questions are included. 
          But, you can create your own routines, infinitely extending the
          abilities of The DialogPro.
          





















































                                       - 11 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          IV.   Shareware
          
          Seabreeze Software distributes DialogPro under the shareware
          marketing concept.  Because DialogPro is shareware you can freely
          copy and share the DialogPro shareware diskette with its programs
          and manual.  You can also obtain it from Seabreeze Software for
          $15 (the cost of the diskette, postage, and handling.)  In fact,
          we hope you do help us by sharing unmodified copies of the
          DialogPro shareware diskette with other programmers.
          
          You may incorporate DialogPro into your programs and distribute
          those programs absolutely royalty free (see registration section
          for details.)  You may not however sell, or give away, the
          DialogPro source code -- even if you purchase the right to use it
          (see registration section.)










































                                       - 12 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          V.    Registration
          
          Shareware is software which can be freely copied and
          distributed.  It is copyrighted software which the author
          encourages people to copy and share with others.
          
          You can register with Seabreeze Software for three levels of
          support:
          
           .  For $50 you receive
          
               .  A serialized diskette containing all the latest libraries
                  for all supported compilers and memory models.
               
               .  Single user telephone support (BBS, Compuserve, and
                  voice.)  See next section for details.
               
               .  Notification of updates for one year.
          
           .  For $100 you receive 
           
               .  the above, and
               .  one hundred pages of liberally commented source code (on
                  diskette,) 
               
                  This support-level is usable for non-commercial
                  programs.  Non-commercial programs are those created for
                  limited user (less than 50 users) installations (as
                  typically might be found in a small consulting situation
                  or a small corporate software development setting,) or
                  for unlimited shareware or freeware distribution.
            
           .  For $200 you receive 
           
               .  the above, plus 
               .  the right to use DialogPro in commercial applications. 
           
           .  Call for details regarding site licensing, consulting
              services, and customizations.
             
          
          Seabreeze Software retains the following rights:
          
           .  If you purchase the source code you may not distribute it
              except as part of an application program.  In other words,
              you can't resell the source in its current or modified form
              in a way that competes with the original product.  
           
           .  If you provide the DialogPro source code to a purchaser of
              your applications software you must leave the remarks in the
              source code indicating that the original copyright is held by
              Seabreeze Software.  If you rewrite portions of DialogPro you





                                       - 13 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


              must point out the modifications made by yourself and you are
              legally obligated to leave the original copyright notice in
              the source code.
           
           .  Seabreeze Software may modify its pricing and distribution
              policies at any time without notification.  This does not
              imply that we will not honor our contractual obligations. But
              that we reserve the right to not contract for the above
              services at the above prices, i.e. we are not bound by 'old'
              advertising.
          
          The registration form is at the back of this manual.
          












































                                       - 14 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          VI.   Support Details
          
          Support is provided under three methods.
          
           .  E-mail.  Send mail to Seabreeze Software, Compuserve ID#
              72330, 705
           
           .  Voice.  You may call Seabreeze Software directly at
              214-437-2729, Monday through Friday, 9 a.m. to 5 p.m. 
              Central Time.
          
          Technical support is available to registered users only, you must
          leave your license agreement number, your name, and instructions
          for answering the question (like - "please answer via Compuserve
          E-mail ID# XXXXX, XXX." or  "Please call me at XXX-XXX-XXXX for
          verbal consultation.")  Give as many details as possible. 
          Answers will generally be received within 24 hours or less,
          Monday through Friday.
          
          Seabreeze Software will respond to general questions from
          unregistered users, like "I have version X.XX, what is the latest
          version?" or "What is the current price for support level X?"  We
          cannot respond to technical questions from unregistered users.


































                                       - 15 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          VII.  Diskette
          
          The shareware diskettes should contain the following files:
          
          READ.ME             Any last minute corrections, additions, etc.
          PKXARC.COM          Unarchives Pro.arc
          DBPRO1.ARC          This manual and demo exe files
          DBPRO2.ARC          Required include, batch, and source files
          DBPRO3.ARC          Microsoft MS C/Quick-C libraries
          DBPRO4.ARC          Turbo-C libraries
          DBPRO5.ARC          Quick-C quicklib
          
          dbpro1.arc, dbpro2.arc, dbpro3.arc, dbpro4.arc  & dbpro5.arc
          contain:
          
          DBPRO.TXT           Users guide and reference manual for The
                              DialogPro
          MSDBPROM.LIB        DialogPro MS C / Quick C medium model library
          MSDBPROL.LIB        DialogPro MS C / Quick C large model library
          QCDBPRO.QLB         DialogPro Quick C quicklib
          TCDBPROM.LIB        DialogPro Turbo C medium model library
          TCDBPROL.LIB        DialogPro Turbo C large model library
          DBERRORS.H          DialogPro include files
          DBOPS.H                  "
          DBPRO.H                  "
          MAKEMENU.C          Demo programs for creating pulldown menus
                              with the DialogPro
          MAKEMENU.H          "
          MENUDEMO.C          "
          MSMENU_L.BAT        Compiler/linker driver batch files for
                              compiling and linking the menu demo.
          MSMENU_M.BAT        "
          QCMENU_L.BAT        "
          QCMENU_M.BAT        "
          TCMENU_L.BAT        "
          TCMENU_M.BAT        "
          MENU_L.PRJ          Turbo-C project files for pulldown menu
                              example.
          MENU_M.PRJ          "
          SIMPLEDB.C          Easy example of a simple dialog box
          SIMPLDBL.PRJ        Turbo-C project files for above sample
                              program.
          SIMPLDBM.PRJ        "
          QCDBPROM.BAT        Generic Quick C medium model DialogPro
                              compile/link batch file
          QCDBPROL.BAT        Generic Quick C large model DialogPro
                              compile/link batch file
          MSDBPROM.BAT        Generic MS C medium model DialogPro
                              compile/link batch file
          MSDBPROL.BAT        Generic MS C large model DialogPro
                              compile/link batch file
          TCDBPROM.BAT        Generic Turbo C medium model DialogPro
                              compile/link batch file




                                       - 16 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          TCDBPROL.BAT        Generic Turbo C large model DialogPro
                              compile/link batch file
          
          Note: BBS operators may repackage The DialogPro files to optimize
          on-line time.  If you received your files via a BBS please make
          sure you have all of The DialogPro shareware files.



















































                                       - 17 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          VIII. Installation
          
            1. Backup your shareware diskette.
            
            2. Type "pkxarc dbpro1" at the dos prompt and press ENTER, and
               then "pkxarc dbpro2".  Pkxarc will unarc dbpro1.arc &
               dbpro2.arc into the current default directory.  You can run
               pkxarc.exe from another directory, and unarc dbpro1.arc
               located on another drive or directory by preceding each with
               a drive and directory specification, for example
            
            
               C:\Pro>a:pkxarc a:dbpro1
            
               will run pkxarc from the a: drive and unarc dbpro1.arc
               located on the a: drive into the c: drive and the "Pro"
               sub-directory.
            
               Repeat for dbpro3.arc and dbpro4.arc.
            
            3. Copy the library files for your compiler (extension of
               ".lib") to the diskette or sub-directory you usually use
               with your C compiler.  The lib files should be in the same
               sub-directory as your C runtime libraries.  

































                                       - 18 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          IX.   Compiling and linking the demo
          
          Confirm proper installation by compiling one of the demo
          programs.  Compile makemenu.c by typing one of the following at
          the dos prompt.
          
               msmenu_l
               msmenu_m
               qcmenu_l
               qcmenu_m
               tcmenu_l
               tcmenu_m
          
          Or compile or simpledb.c by typing
          
               msdbprol simpledb
               msdbprom simpledb
               qcdbprol simpledb
               qcdbprom simpledb
               tcdbprol simpledb
               tcdbprom simpledb
          
          If you were unable to compile and link check to make sure that:
          
          TURBO-C :
          
          Determine that you have all of the files listed on the previous
          page.  Turbo-C is installed as described in the Turbo-C manual,
          you are compiling from the TURBOC directory,  the source files
          are in the default sub-directory, and the TCDBPRO?.LIB files are
          installed in the LIB sub-directory.
          
          QUICK-C :
          
          Determine that the LIB, TMP, BIN, and INCLUDE environment
          variables have been properly initialized, the MSDBPRO?.LIB files
          are included in the subdirectory associated with LIB environment
          variable, and the source files are in your default directory.
          
          If the problem persists contact Seabreeze Software Customer
          Support.
















                                       - 19 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          X.    Changes between version 1.0 and 2.0
          
          Changes between 1.0 and 1.1
          
          Documentation
          
          We realize that The DialogPro represents somewhat of a departure
          from the programming style you may be used to.  To help the
          transition we have provided three, new, heavily commented
          examples.
          
          Upgrades
          
          All operations now pass through the queue before being executed.
          Previously, if there was no operation in the queue the
          keyboard/mouse interpreter would poll until it received an event
          which translated into a command.  The command was then
          immediately executed.  These commands are now passed into the
          queue and then only executed as they are removed from the queue. 
          This makes debugging about 100% easier.
          
          Added features
          
          New question type.  A new question type has been added,
          scroll_txt.  This question type can be used for creating custom
          question types but includes two functions for using scroll_txt. 
          The included functions help you use scroll_txt as a scrolling
          text box or as a sub dialog box.
          
          Monitoring.  The command queue can now be monitored.  To monitor
          the command queue simply turn on the monitor switch and assign
          the monitor to a window handle.  The command queue monitor will
          then continuously scroll in the monitor window.  You can slow
          down queue execution with a delay factor or step through the
          command queue by keystroke.  This is a tremendously effective way
          to debug dialog boxes.
          
          New list type.  Elements in a list can now be indicated to be
          marked, unmarked, and in version 1.1 as titles.  Titles cannot be
          selected or returned as a selected item.  Use them to divide
          lists into segments -- e.g. segmented pull down menus.
          
          New commands.  The EXECUTE command allows you to place the
          address of a function in the command queue.  After EXECUTE is
          received the next two parameters off of the queue are used to
          construct a far address to a function.  The dialog box then calls
          the function using a pointer to the dialog box as a parameter. 
          If required, You can pass additional parameters to this function
          through the command queue.  This feature allows you to construct
          macros which call other functions.  Tremendously useful.
          
          
          
          Changes between 1.1 and 2.0



                                       - 20 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          
          DialogPro now supports radio buttons, check boxes, and
          multi-column lists.
          
          DialogPro now allows delimiters to be placed completely around a
          response area (a box) rather than just to the left and right.
          
          DialogPro's default settings are now more similar to SAA user
          interface standards.
          
          DialogPro has improved speed, particularly with list type
          questions.
          
          DialogPro now has global macros.  You can now define macros which
          are global or local.  global macros are always processed before
          local macros.  This is very useful in creating application-wide
          hotkeys.
          
          You no longer specify an up,down,left,right for each question. 
          Instead you can only navigate to the next and previous questions
          which is determined by the questions position within the question
          array.
          
          We have added an idle function pointer, which will repeatedly
          call the function it points to as the keyboard and mouse are
          polled.
          
          Every structure which required a window handle has been added
          additional strucutre members to describe the window.  If the
          window handle is not valid it is automatically created based on
          these values.  You can therefore describe most dialog boxes
          entirely at compile time.
          
          Added some new #defines to simplify creating DialogPro macros.
          
          Dialog box colors and delimiters are now specified through a
          pointer to a color and delimiter structure rather than explicitly
          specified in each dialog box.  This makes it much simpler to
          implement design changes.
           

















                                       - 21 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          XI.   Future enhancements
          
          Action Bars -- Again this is real similar to the makemenu.c
          demonstration.  However we may streamline it down and make it
          more similar to the MS-WINDOW'S programmer's interface.
          
          OS/2 -- very soon.  We are currently testing the OS/2 version.


















































                                       - 22 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          XII.  Reference
          
          A. Introduction
          
          Generally speaking you only need to be familiar with the
          functions db_run, lst_run, db_switchqueue, and the data
          structures dialog_box and list_rec.  All of the other functions
          are documented solely to assist the application programmer in
          writing pre and post routines to attach to questions.  Using
          these functions can help you do things like modify the dialog_box
          structure based on an interim response.  Typically this technique
          is used to gray-out a questions in a dialog box based on another
          response or to perform other similar processes.
          
          The DialogPro is targeted for experienced applications
          developers.  The best way to learn how to use the DialogPro is by
          studying, running, and modifying the sample programs menudemo and
          simpledb.







































                                       - 23 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          B. Functions
          
          1.  db_display
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int db_display(db_ptr)
                         ______ 
          i                    )
                         ______ 
          
          dialog_box *db_ptr;
                      _______
          dialog_box *       
                      _______
          
          
          b. Description
          
          Displays the dialog box pointed to by dp_ptr. If the window
                                                ________             
          associated with db_ptr is not on the screen it will be opened via
                          ______                                           
          a call to wn_openw.  If the window associated with the dialog box
                    wn_openw                                               
          (db_ptr->handle) is open but is not the last_wdw (on top of the
           ______                                                        
                 ->handle                         last_wdw               
           ______                                                        
          stack of windows) and db_ptr->bg_operation is TRUE it will be
                                ______                                 
                                      ->bg_operation                   
                                ______                                 
          brought to the top of the stack by a call to wn_openw.
                                                       wn_openw 
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          
          2.  db_displayq
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int db_displayq(db_ptr, question_id)
                          ______  ___________ 
          int db_displayq(      ,            )
                          ______  ___________ 
          
          dialog_box *db_ptr;
                      _______
          dialog_box *       
                      _______
          unsigned char question_id;
                        ____________
          unsigned char             
                        ____________
          
          
          b. Description
          
          Displays the question pointed to by
          db_ptr->questions[question_id] in the window db_ptr->handle.
          ______            ___________                ______         
                ->questions[           ]                     ->handle 
          ______            ___________                ______         
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          






                                       - 24 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          3.  db_flushqueue
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          void db_flushqueue(void)
                             ____ 
          void db flushqueue      
                             ____ 
          
          
          b. Description
          
          Clears all messages in the queue, db_queue.  Indiscriminate use
                                            db queue                     
          of db_flushqueue() is not advised.  It may interfere with the
          processing of macros.  It is best to discard only those messages
          which you are sure you do not want.
          
          
          c. Return Value
          
          None.
          
          
          4.  db_freestorage
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int db_freestorage(db_ptr, insurance)
                             ______  _________ 
          int db_freestorage(      ,          )
                             ______  _________ 
          
          dialog_box *db_ptr;
                      _______
          dialog_box *       
                      _______
          storage **insurance;
                    __________
          storage **          
                    __________
          
          
          b. Description
          
          If *insurance does not equal NULL the data structure pointed to
             __________                                                  
                                       NULL                              
             __________                                                  
          by *insurance is freed and *insurance is set to NULL.
             __________              __________                
                                                          NULL 
             __________              __________                
          
          If *insurance is equal to NULL, nothing happens.
             __________                                   
                                    NULL                  
             __________                                   
          
          (Normally **insurance is the same as &(db_ptr->insurance). 
                    ___________                  ______              
                                               &(      ->insurance)  
                    ___________                  ______              
          db_ptr->insurance is used by db_run to point to the previous
          ______                                                      
                ->insurance            db_run                         
          ______                                                      
          answers to the dialog box.)
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          






                                       - 25 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          5.  db_pop
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          unsigned db_pop(void)
                          ____ 
          unsigned db pop      
                          ____ 
          
          
          b. Description
          
          Reads the next message from the tail of the queue, db_queue.
                                                             db queue 
          
          
          c. Return Value
          
          <> - 1    Function executed properly.
          
          -1        The queue is empty.
          
          
          6.  db_priority
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int db_priority(new_event)
                          ___ _____ 
          int db priority           
                          ___ _____ 
          
          unsigned new_event;
                   ___ _____ 
          unsigned           
                   ___ _____ 
          
          
          b. Description
          
          Puts new_message at the tail of the queue, db_queue.
               ___ _______                                    
                                                     db queue 
               ___ _______                                    
          
          
          c. Return Value
          
          TRUE      Function executed properly.
          TRUE                                 
          
          FALSE     The queue is full (a queue can only have 256 messages
          FALSE                                                          
                    in it.)
          
          
          7.  db_push
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int db_push(new_event)
                      ___ _____ 
          int db push           
                      ___ _____ 
          
          unsigned new_event;
                   ___ _____ 
          unsigned           
                   ___ _____ 



                                       - 26 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          b. Description
          
          Puts new_message at the head of the queue, db_queue.
               ___ _______                                    
                                                     db queue 
               ___ _______                                    
          
          
          c. Return Value
          
          TRUE      Function executed properly.
          TRUE                                 
          
          FALSE     The queue is full (a queue can only have 256 messages
          FALSE                                                          
                    in it.)
          
          
          8.  db_restoreanswers
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int db_restoreanswers(db_ptr, insurance)
                                ______  _________ 
          int db_restoreanswers(      ,          )
                                ______  _________ 
          
          dialog_box *db_ptr;
                      _______
          dialog_box *       
                      _______
          storage **insurance;
                    __________
          storage **          
                    __________
          
          
          b. Description
          
          If *insurance is not equal to NULL the answers to the dialog box,
             __________                                                    
                                        NULL                               
             __________                                                    
          db_ptr, are changed to the answers recorded in the data structure
          ______                                                           
          (which only contains the answers) of type storage pointed to by
                                                    storage              
          *insurance.  The storage data structure is freed and *insurance
          __________                                                     
                           storage                                       
          __________                                                     
          is set to NULL.
                    NULL 
          
          If insurance is equal to NULL, nothing happens.
             _________                                   
                                   NULL                  
             _________                                   
          
          (Normally **insurance is the same as &(db_ptr->insurance). 
                    ___________                  ______              
                                               &(      ->insurance)  
                    ___________                  ______              
          db_ptr->insurance is used by db_run to point to the previous
          ______                                                      
                ->insurance            db_run                         
          ______                                                      
          answers to the dialog box.)
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          
          9.  db_run
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int db_run(db_ptr, message)
                     ______  _______ 
          int db_run(      , message)
                     ______  _______ 
          
          dialog_box *db_ptr;
                      _______
          dialog_box *       
                      _______



                                       - 27 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          unsigned message;
                   ________
          unsigned         
                   ________
          
          
          b. Description
          
          The function db_run executes the messages in the message queue
                       db_run                                           
          pointed to by db_queue against the dialog box data structure
                        db_queue                                      
          db_ptr.  (It is very important that a message queue have been
          ______                                                       
          initialized via a call to db_switchqueue before calling db_run.)
                                    db switchqueue                db run  
          
          Before executing the message queue it first places the standard
          message STORAGE at the tail of the queue and then it places the
                  STORAGE                                                
          parameter message at the head of the queue.  All messages are
                    _______                                            
          retrieved from the tail of the queue.  Each retrieved message is
          checked against the macro list db_ptr->macros.  If the message is
                                         ______                            
                                               ->macros                    
                                         ______                            
          a macro it is expanded by placing the items pointed to by the
          macro at the tail of the queue in reverse order.
          
          If there are no messages in the message queue db_run polls the
                                                        db_run          
          kyeboard and mouse (if one is recognized when wn_init is
          called.)  When activity is noted the keyboard/mouse activity is
          translated into a message and placed at the tail of the queue.
          
          If it is a mouse event the message MOUSE_EVENT is placed at the
                                             MOUSE_EVENT                 
          tail of the queue.  The MOUSE_EVENT message takes the last mouse
                                  MOUSE_EVENT                             
          event, translates it into a message and places it at the tail of
          the queue.
          
          It it is a keyboard event, the keystroke is first compared
          against the the shortcut key of each of the questions, starting
          at the current question + 1 and ending at the current question. 
          The first question whose shortcut key matches the keystroke is
          selected.   If the question is a button and it matches
          BUTTONQUEST(question_id)->key the button is selected, the
          BUTTONQUEST(question_id)->key                            
          keystroke value is replaced with the value
          BUTTONQUEST(question_id)->cmd_key, and the global variable
          BUTTONQUEST(question_id)->cmd_key                         
          button_press is set the the value of
          button_press                        
          BUTTONQUEST(question_id)->exitval.  If the question is a button
          BUTTONQUEST(question_id)->exitval                              
          and it matches BUTTONQUEST(question_id)->keybind the current
                         BUTTONQUEST(question_id)->keybind            
          question remains selected, and the keystroke value is replaced
          with the value BUTTONQUEST(question_id)->cmd_key, and the global
                         BUTTONQUEST(question_id)->cmd_key                
          variable button_press is set the the value of
          BUTTONQUEST(question_id)->exitval.  
          BUTTONQUEST(question_id)->exitval   
          
          The new keystroke value is then compared against the
          keystroke-command table.  If the keystroke is in the table the
          keystroke is interpreted into a standard event.  If it is not, it
          is processed as a keystroke value.  Alphanumeric Keystrokes can
          be used to begin editing a free_form, a reducer, or select a
          multiple choice response.
          
          When one of several exit type messages is received db_run
          terminates.
          



                                       - 28 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          The actual message selection/interpretation code explains it a
          little more succinctly:
          
          do {
          
               /* get event from queue */
               if (!NO_EVENT) event = db_pop();                       
          
               /* or from keyboard/mouse */
               else event = get_dbevent(db_ptr);
          
          } while
               
               /* expand macros */
               (db_executemacros(event, db_ptr->macros));
          
          
          /* if event is a keystroke value ... */
          if (event > 256) {
          
               /* get ascii code */
               ascii = event % 256;
          
               /* check shortcut keys */
               button_press = db_touchbutton(db_ptr, &event);
          
               /* translate into a message */
               event = db_getopcode(db_ptr, event);
          }
          
          
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          Note that if this function returns with a value of CONFIRMED or
          ABORTED that it has also placed a CONFIRM or ABORT message in the
          queue.  Many programmers find that using the queue for sending
          and receiving arguments and return values is the cleanest way to
          use the DialogPro.  On the other hand, particularly if you are
          integrating the DialogPro into an existing application you may
          want to discard these messages.  Use db_pop() to discard the the
          unwanted message, or db_flushqueue() to discard all messages in
          the queue.
          
          
          10. db_selectq
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          



                                       - 29 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          int db_selectq(db_ptr, question_id)
                         ______  ___________ 
          int db_selectq(      ,            )
                         ______  ___________ 
          
          dialog_box *db_ptr;
                      _______
          dialog_box *       
                      _______
          unsigned char question_id;
                        ____________
          unsigned char             
                        ____________
          
          
          b. Description
          
          Makes db_ptr->id_select equal to question_id.  Then displays the
          question pointed to previously by
          db_ptr->questions[db_ptr->id_select] (dehighlighting the
          question) and then displays the question
          db_ptr->questions[question_id] (highlighting it--as it is now the
          ______            ___________                                    
                ->questions[           ]                                   
          ______            ___________                                    
          selected question.)
          
          Before dehighlighting the first question, the function pointed to
          by (*) FIRST_QUESTION->whenoff(db_ptr) is executed, if
          FIRST_QUESTION->whenoff(db_ptr) does not return TRUE db_selectq
          terminates without modifying db_ptr->id_select.
          
          After dehighlighting the second question, the function pointed to
          by (*) SECOND_QUESTION->whenon(db_ptr) is executed, if
          SECOND_QUESTION->whenon(db_ptr) does not return TRUE db_selectq
          terminates without modifying db_ptr->id_select.
          
          
          (*) FIRST_QUESTION and SECOND_QUESTION are generic pointers use
          for illustrative purposes representing what would be the specific
          pointer type for each question.  Each question type has its own
          pointer type.
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          
          11. db_storeanswers
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int db_storeanswers(db_ptr, insurance)
                              ______  _________ 
          int db_storeanswers(      ,          )
                              ______  _________ 
          
          dialog_box *db_ptr;
                      _______
          dialog_box *       
                      _______
          storage **insurance;
                    __________
          storage **          
                    __________
          
          








                                       - 30 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          b. Description
          
          If *insurance is equal to NULL the answers to the dialog box,
             __________                                                
                                    NULL                               
             __________                                                
          db_ptr, are stored in an interim data structure (which only
          ______                                                     
          contains the answers) of type storage and *insurance returns the
                                                    __________            
                                        storage                           
                                                    __________            
          pointer to the data structure.
          
          If insurance is not equal to NULL, nothing happens.
             _________                                       
                                       NULL                  
             _________                                       
          
          (Normally **insurance is the same as &(db_ptr->insurance). 
                    ___________                  ______              
                                               &(      ->insurance)  
                    ___________                  ______              
          db_ptr->insurance is used by db_run to point to the previous
          ______                                                      
                ->insurance            db_run                         
          ______                                                      
          answers to the dialog box.)
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          
          12. db_switchqueue
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int db_switchqueue(head, tail, queue)
                             ____  ____  _____ 
          int db switchqueue                   
                             ____  ____  _____ 
          
          unsigned char *head, *tail;
                         ____   ____ 
          unsigned char              
                         ____   ____ 
          unsigned *queue;
                    _____ 
          unsigned        
                    _____ 
          
          
          b. Description
          
          db_switchqueue associates variables representing the head, tail,
          db switchqueue                                                  
          and circular message queue used by db_run and lst_run.  This
                                             db run     lst run       
          function must be called once before using db_run or lst_run.  It
                                                    db run    lst run     
          only has to be called once and then db_run and lst_run can be
                                              db run     lst run       
          used as many times necessary.  You can however call this more
          than once if you want to use separate message queues for
          different dialog boxes.
          
          queue must be a pointer to a 512 byte memory block (256
          _____                                                  
          integers.) head and tail should be pointers to existing unsigned
                     ____     ____                                        
          chars.  head and tail should be initialized to their proper
                  ____     ____                                      
          values before calling db_switchqueue.  If you are just
                                db switchqueue                  
          initializing a brand new queue both would be 0.
          
          
          c. Return Value
          
          None.
          
          




                                       - 31 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          13. lst_display
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int lst_display(list_ptr, mode)
                          ________  ____ 
          int lst_display                
                          ________  ____ 
          
          list_rec *list_ptr;
                    ________ 
          list_rec *         
                    ________ 
          unsigned char mode;
                        ____ 
          unsigned char      
                        ____ 
          
          
          b. Description
          
          Refreshes the display of the list, list_ptr.
                                             ________ 
          
          
          If mode is equal to 
             ____             
          
          0         The window, lst_ptr->handle, is brought to the top of
                                ________ ______                          
                                lst_ptr                                  
                                ________ ______                          
                    the stack of windows via a call to wn_openw.
                                                       wn_openw 
          
          1         The window, lst_ptr->handle, is brought to the top of
                                         ______                          
                                lst ptr-                                 
                                         ______                          
                    the stack of windows via a call to q_open.  q_open is
                                                       q open   q open   
                    faster than wn_openw but no windowing functions which
                                wn openw                                 
                    disrupt the order of display (wn_closew, wn_openw, or
                                                  wn closew  wn openw    
                    wn_activew) should be called without first removing the
                    wn activew                                             
                    window by a call to q_close.  This mode is used in pull
                                        q close                            
                    down menus for example because it is designed in a way
                    that makes certain that the window is closed on exit.
          
          2         Only the virtual screen is refreshed.  The changes are
                    not updated on the physical screen.
          
          These data structures members may be effected by lst_display
          (Note: in the following listing TILE is defined as
                                          TILE              
          window[lst_ptr->handle]->tiles[lst_ptr->tile_handle] and WDW is
                 ___ ____                ___ ____                        
          window          handle   tiles          tile handle      WDW   
                 ___ ____                ___ ____                        
          defined as window[lst_ptr->handle]):
                            ___ ____          
                     window          handle   
                            ___ ____          
          
          lst_ptr->optlen               The length of the longest string in
          ___ ____                                                         
                   optlen                                                  
          ___ ____                                                         
                                        the list of options.
          
          lst_ptr->taglen               The length of the longest on/off
          ___ ____                                                      
                   taglen                                               
          ___ ____                                                      
                                        tag (displayed to the left of each
                                        option in the list.
          
          lst_ptr->numopts              The number of options in the list.
          ___ ____                                                        
                   numopts                                                
          ___ ____                                                        
          
          TILE->virtual_screen          If (TILE->vs_rows *
          TILE- virtual screen              TILE- vs rows  
                                        TILE->vs_columns) >
                                        TILE- vs columns   
                                        (lst_ptr->numopts *
                                         ___ ____          
                                                  numopts  
                                         ___ ____          
                                        (lst_ptr->taglen +
                                         ___ ____         
                                                  taglen  
                                         ___ ____         
                                        lst_ptr->optlen)) then
                                        ___ ____              
                                                 optlen       
                                        ___ ____              
                                        TILE->virtual_screen is deallocated
                                        TILE- virtual screen               



                                       - 32 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


                                        and a larger memory block is
                                        allocated.  TILE->virtual_screen
                                                    TILE- virtual screen
                                        then points to the new memory
                                        block.
          
          TILE->vs_rows, 
          TILE- vs rows  
          TILE->vs_columns              If TILE->vs_rows does not equal
          TILE- vs columns                 TILE- vs rows               
                                        lst_ptr->numopts or
                                        ___ ____           
                                                 numopts   
                                        ___ ____           
                                        TILE->vs_columns does not equal
                                        TILE- vs columns               
                                        (lst_ptr->optlen + lst_ptr->taglen)
                                         ___ ____          ___ ____        
                                                  optlen            taglen 
                                         ___ ____          ___ ____        
                                        then TILE->vs_columns is set equal
                                             TILE- vs columns             
                                        to lst_ptr->optlen +
                                           ___ ____         
                                                    optlen  
                                           ___ ____         
                                        lst_ptr->taglen and TILE->vs_rows
                                        ___ ____                         
                                                 taglen     TILE- vs rows
                                        ___ ____                         
                                        is calculated based on the size of
                                        the memory block pointed to by
                                        TILE->virtual_screen.
                                        TILE- virtual screen 
          
          WDW->port_columns             If lst_ptr->auto_horiz is TRUE and
                                           ___ ____                       
          WDW- port columns                         auto horiz    TRUE    
                                           ___ ____                       
                                        lst_ptr->optlen + lst_ptr->taglen
                                        ___ ____          ___ ____       
                                                 optlen            taglen
                                        ___ ____          ___ ____       
                                        does not equal WDW->port_columns,
                                                       WDW- port columns 
                                        WDW->port_columns is set equal to
                                        WDW- port columns                
                                        lst_ptr->optlen + lst_ptr->taglen.
                                        ___ ____          ___ ____        
                                                 optlen            taglen 
                                        ___ ____          ___ ____        
           
          WDW->port_rows                If lst_ptr->auto_vert is TRUE and
                                           ___ ____                      
          WDW- port rows                            auto vert    TRUE    
                                           ___ ____                      
                                        lst_ptr->numopts does not equal
                                        ___ ____                       
                                                 numopts               
                                        ___ ____                       
                                        WDW->port_rows, WDW->port_rows is
                                        WDW- port rows  WDW- port rows   
                                        set equal to lst_ptr->numopts.
                                                     ___ ____         
                                                              numopts 
                                                     ___ ____         
           
          
          If the list is not changed this function operates quickly.  If
          the list is larger than the previous list lst_display must free
                                                    lst display          
          the original virtual screen and allocate memory for the new
          virtual screen.  This can make for a small hiccup when opening a
          modified list.  You can get around this hiccup by calling
          lst_display with mode equal to 0 after modifying the list at a
          point where processing speed is less critical.  When lst_display
                                                               lst display
          is called (probably via lst_run) for actual display the user will
                                  lst run                                  
          not notice any delay.
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          
          14. lst_displayitem
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int lst_displayitem(list_ptr, offset)
                              ________  ______ 
          int lst_displayitem                  
                              ________  ______ 
          
          list_rec *list_ptr;
                    ________ 
          list_rec *         
                    ________ 



                                       - 33 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          int offset;
              ______ 
          int        
              ______ 
          
          
          b. Description
          
          Refreshes the display of the offset item (the first item is 0) in
                                       ______                              
          the list list_ptr.
                   ________ 
          
          If offset is greater than the number of items in the list
             ______                                                
          (list_ptr->numopts) then a blank line is output at that row in
           _________                                                    
                   ->numopts                                            
           _________                                                    
          the virtual screen.
          
          If offset is greater than the last row in the virtual screen
             ______                                                   
          an OUT_OF_RANGE error is returned.
             OUT_OF_RANGE                   
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          
          15. lst_freestorage
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int lst_freestorage(insurance)
                              _________ 
          int lst_freestorage(         )
                              _________ 
          
          lst_storage **insurance;
                        __________
          lst_storage **          
                        __________
          
          
          b. Description
          
          If *insurance does not equal NULL the data structure pointed to
             __________                                                  
                                       NULL                              
             __________                                                  
          by *insurance is freed and *insurance is set to NULL.
             __________              __________                
                                                          NULL 
             __________              __________                
          
          If *insurance is equal to NULL, nothing happens.
             __________                                   
                                    NULL                  
             __________                                   
          
          (Normally **insurance is the same as &(lst_ptr->insurance). 
                    ___________                  _______              
                                               &(       ->insurance)  
                    ___________                  _______              
          lst_ptr->insurance is used by lst_run to point to the previous
          _______                                                       
                 ->insurance            lst_run                         
          _______                                                       
          answers to the list.)
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          
          16. lst_restoreanswers
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"



                                       - 34 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          
          int lst_restoreanswers(lst_ptr, insurance)
                                 _______  _________ 
          int lst_restoreanswers(       ,          )
                                 _______  _________ 
          
          lst_rec *lst_ptr;
                   ________
          lst_rec *        
                   ________
          lst_storage **insurance;
                        __________
          lst_storage **          
                        __________
          
          
          b. Description
          
          If *insurance is not equal to NULL the state of the lst, lst_ptr,
             __________                                            _______ 
                                        NULL                               
             __________                                            _______ 
          is changed to the answers recorded in the data structure of
          type lst_storage pointed to by *insurance.  The lst_storage data
                                         __________                       
               lst_storage                                lst_storage     
                                         __________                       
          structure is freed and *insurance is set to NULL.
                                                      NULL 
          
          If insurance is equal to NULL, nothing happens.
             _________                                   
                                   NULL                  
             _________                                   
          
          (Normally **insurance is the same as &(lst_ptr->insurance). 
                    ___________                  _______              
                                               &(       ->insurance)  
                    ___________                  _______              
          lst_ptr->insurance is used by lst_run to point to the previous
          _______                                                       
                 ->insurance            lst_run                         
          _______                                                       
          answers to the list.)
          
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          
          17. lst_run
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int lst_run(lst_ptr, message)
                      _______  _______ 
          int lst_run(       , message)
                      _______  _______ 
          
          list_rec *lst_ptr;
                    ________
          list_rec *        
                    ________
          unsigned int message;
                       ________
          unsigned int         
                       ________
          
          
          b. Description
          
          The function lst_run executes the messages in the message queue
                       lst_run                                           
          pointed to by db_queue against the data structure lst_ptr.  (It
                                                            _______      
                        db_queue                                         
                                                            _______      
          is very important that a message queue have been initialized via
          a call to db_switchqueue before calling lst_run.)
                    db switchqueue                lst run  
          
          Before executing the message queue it first places the standard
          message STORAGE at the tail of the queue and then it places
                  STORAGE                                            
          message at the head of the queue.  All messages are retrieved
          from the tail of the queue.  Each retrieved message is checked
          first against the global macro list, global macros, and then
          against the local macro list lst_ptr->macros.  If the message is
                                       _______                            
                                              ->macros                    
                                       _______                            
          a macro it is expanded by placing the items pointed to by the
          macro at the tail of the queue in reverse order.



                                       - 35 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          
          If there are no messages in the message queue lst_run polls the
                                                        lst_run          
          keyboard and mouse (if one is recognized when wn_init is
                                                        wn init   
          called.)  When activity is noted the keyboard/mouse activity is
          translated into a message and placed at the tail of the queue.
          
          If it is a mouse event the message MOUSE_EVENT is placed at the
                                             MOUSE_EVENT                 
          tail of the queue.  The MOUSE_EVENT message takes the last mouse
                                  MOUSE_EVENT                             
          event, translates it into a keystroke and places it at the tail
          of the queue.
          
          If the message has a value greater than 256 it is compared
          against the keystroke-command table, lst_ptr->cmds. If the
          keystroke is in the table it is interpreted into a standard
          event.  
          
          If the message is less than 256 it is interpreted as a standard
          message.  Otherwise it is compared against the the shortcut key
          of each of the options, starting at the current item + 1 and
          ending at the current item.  The first item whose shortcut key
          matches the keystroke is selected.   If lst_ptr->alpha_confirm is
          TRUE and lst_ptr->list_type is CHECKLIST then the item is toggles
          on/off.  If lst_ptr->alpha_confirm is TRUE and lst_ptr->list_type
          is SELECT_ONE then the item is set to TRUE and lst_run exits with
          a value of CONFIRMED.
          
          When one of several exit type messages is received lst_run
          terminates.
          
          The actual message selection/interpretation code explains it a
          little more succinctly:
          
          do {
          
               /* get event from queue */
               if (!NO_EVENT) event = db_pop();                       
          
               /* or from keyboard/mouse */
               else event = get_lstevent(lst_ptr);
          
          } while
               
               /* expand macros */
               (db_executemacros(event, lst_ptr->macros));
          
          /* if event > 256 see if attached to a standard message */
          if (event > 256) {
               event = lst_opcode(list_ptr, event);
               ascii = event % 256;
          }
          
          EXECUTE MESSAGE where:
          
                              message < 256, standard message,



                                       - 36 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


                              message > 256, short cut selection.
          
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          
          18. lst_select
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int lst_select(list_ptr, offset)
                         ____ ___  ______ 
          int lst select                  
                         ____ ___  ______ 
          
          list_rec *list_ptr;
                    ____ ___ 
          list rec           
                    ____ ___ 
          int offset;
              ______ 
          int        
              ______ 
          
          
          b. Description
          
          Dehighlights the currently selected item and highlights the item
          offset items above (-) or below (+) relative to the current item.
          ______                                                           
          
          Accounts for rollover.
          
          Does nothing if offset is equal to 0.
                          ______               
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          
          19. lst_storeanswers
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int lst_storeanswers(lst_ptr, insurance)
                               _______  _________ 
          int lst_storeanswers(       ,          )
                               _______  _________ 
          
          list_rec *lst_ptr;
                    ________
          list_rec *        
                    ________
          lst_storage **insurance;
                        __________
          lst_storage **          
                        __________
          
          
          b. Description
          
          If *insurance is equal to NULL the state of the list, db_ptr, is
             __________                                         ______    
                                    NULL                                  
             __________                                         ______    
          stored in an interim data structure of type lst_storage and
                                                      lst_storage    
          *insurance returns the pointer to the data structure.
          __________                                           
          



                                       - 37 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          If insurance is not equal to NULL, nothing happens.
             _________                                       
                                       NULL                  
             _________                                       
          
          (Normally **insurance is the same as &(lst_ptr->insurance). 
                    ___________                  _______              
                                               &(       ->insurance)  
                    ___________                  _______              
          lst_ptr->insurance is used by lst_run to point to the previous
          _______                                                       
                 ->insurance            lst_run                         
          _______                                                       
          answers to the list.)
          
          
          c. Return Value
          
          See section Standard Return Values.
          
          
          20. lst_toggle
          
          a. Summary
          
          #include "dbpro.h"
          #include "dbpro.h"
          
          int lst_toggle(list_ptr, item)
                         ____ ___  ____ 
          int lst toggle                
                         ____ ___  ____ 
          
          list_rec *list_ptr;
                    ____ ___ 
          list rec           
                    ____ ___ 
          int item;
              ____ 
          int      
              ____ 
          
          
          b. Description
          
          If lst_ptr->lst_type is equal to CHECKLIST toggles the value of
             ___ ____                                                    
                      lst type             CHECKLIST                     
             ___ ____                                                    
          lst_ptr->selections[item] between TRUE and FALSE and refreshes
          ___ ____            ____                                      
                   selections               TRUE     FALSE              
          ___ ____            ____                                      
          the display of item by calling lst_displayitem.
                                         lst displayitem 
          
          If lst_ptr->lst_type is equal to SELECT_ONE all other items in
             ___ ____                                                   
                      lst type             SELECT ONE                   
             ___ ____                                                   
          the list are set to FALSE, lst_ptr->selections[item] is set to
                                     ___ ____            ____           
                              FALSE           selections                
                                     ___ ____            ____           
          TRUE, and the entire list is refreshed.
          TRUE                                   
          
          The value of lst_ptr->available[item] must be TRUE.
                       ___ ____           ____               
                                available               TRUE 
                       ___ ____           ____               
          
          
          c. Return Value
          
          FALSE     If lst_ptr->available[item] is FALSE the function
                       ___ ____           ____                       
          FALSE                 available          FALSE             
                       ___ ____           ____                       
                    terminates early and returns FALSE.
                                                 FALSE 
          
          TRUE      function executed properly.
          TRUE                                 














                                       - 38 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          C. Standard Return Values
          
          ABORTED                  User exited by abort
          
          CONFIRMED                User exited by confirm
          
          ASCENDED                 User exited by ascending
          
          DESCENDED                User exited by descending
          
          MOUSED                   User exited by clicking the mouse
                                   outside of the image of the window
                                   associated with the dialog box.
          
          MENUED                   User exited by confirming a pull down
                                   menu
          
          OK                       No errors detected
          
          INVALID_QUESTION_TYPE    Dialog box's question list has a
                                   question of a type not defined in
                                   dbpro.h
          
          BAD_PARAMS               Coordinates or variables were outside of
                                   a specified range
          
          NULL_POINTER             Passed a NULL pointer
          
          OUT_OF_MEMORY            Function could not allocate enough
                                   memory to create required data
                                   structures


























                                       - 39 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          D. Data structures
          
          1.  button
          
          char question_type            must be set to BUTTON.
               ________ ____                                  
          char                                         BUTTON 
               ________ ____                                  
          
          unsigned char tile_handle     The question is displayed in this
                        ____ ______                                      
          unsigned char                                                  
                        ____ ______                                      
                                        tile.  tile_handle must be a valid
                                               ____ ______                
                                        tile handle.
          
          int (*whenon)
                ______ 
          int          
                ______ 
              (dialog_box *)
               dialog box   
          int (*whenoff)
                _______ 
          int           
                _______ 
              (dialog_box *)
               dialog box   
          int (*action)(dialog_box *)   Pointers to edit checking
                ______                                           
          int           dialog box                               
                ______                                           
                                        routines.  db_run executes each
                                                   db run              
                                        routine under these conditions.  On
                                        selecting the question whenon is
                                                               ______   
                                        executed.  On selecting a question
                                        other than the current question or
                                        on exiting db_run whenoff is
                                                          _______   
                                                   db run           
                                                          _______   
                                        executed.  On pressing the
                                        button action is executed.  whenoff
                                               ______                      
                                        must return TRUE or the attempt to
                                                    TRUE                  
                                        navigate to another question will
                                        fail.  If any routine is set to
                                        NULL it is not executed.  db_run
                                        NULL                            
                                        always passes the current dialog
                                        box pointer to each edit checking
                                        function.
          
          char *statement               A string representing the statement
                _________                                                  
          char                                                             
                _________                                                  
                                        to appear inside the button.
          
          int statementx, statementy    Upper left coordinate of the
              __________  __________                                
          int                                                       
              __________  __________                                
                                        button.
          
          int key                       Identical to keybind (below), but
              ___                                                        
          int                                                            
              ___                                                        
                                        the button also becomes the
                                        selected question.
          
          char *boxchars                Box drawing characters to be used
                ________                                                 
          char                                                           
                ________                                                 
                                        in drawing the button border.  Use
                                        NULL to indicate no borders.  See
                                        NULL                             
                                        vs_box in The WindowPro reference
                                        vs box                           
                                        manual for further explanation.
          
          char shading                  Shading style to be used when
               _______                                               
          char                                                       
               _______                                               
                                        drawing the box surrounding the
                                        button.  See vs_box in The
                                                     vs box       
                                        WindowPro reference manual for
                                        further explanation.
          




                                       - 40 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          int cmdkey                    On pressing a button this value is
              ______                                                      
          int                                                             
              ______                                                      
                                        placed at the tail of the message
                                        queue.
          
          int keybind                   This value binds the keyboard code,
              _______                                                      
          int                                                              
              _______                                                      
                                        keybind, to the button.  Generating
                                        _______                            
                                        this keyboard code will 1-flash the
                                        button, 2-place cmdkey at the tail
                                                        ______            
                                        of the message queue, and 3-execute
                                        action.  Note that the selected
                                        ______                         
                                        question is not effected.
          
          char continuous               If TRUE, holding the mouse cursor
               __________                                                
          char                             TRUE                          
               __________                                                
                                        on the button repeatedly places
                                        PRESS_BUTTON at the tail of the
                                        PRESS BUTTON                   
                                        message queue.  If FALSE only a
                                                           FALSE       
                                        mouse release will place a single
                                        PRESS_BUTTON at the tail of the
                                        PRESS BUTTON                   
                                        message queue.
          
          int exitval                   If cmdkey results in exiting
              _______                      ______                   
          int                                                       
              _______                      ______                   
                                        db_run.  db_run will exit with the
                                        db run   db run                   
                                        value exitval.
                                              _______ 
          
          
          2.  db_colors
          
          db_colors represents the attributes to be used when updating a
          dialog box.  Typically you would set up one db_colors structure
          for use with all dialog boxes to establish a personality for your
          system.  You may also want to have various color schemes for
          different types of dialog boxes.
          
               
          unsigned char title_bg, 
                        __________
          unsigned char           
                        __________
          title_fg                      The background and foreground color
          ______________________________                                   
                                        to use when updating a title.
          
          unsigned char question_bg,
                        ____________
          unsigned char             
                        ____________
          question_fg                   The background and foreground color
          ______________________________                                   
                                        to use when updating the statement
                                        portions of questions.
          
          unsigned char response_bg, 
                        _____________
          unsigned char              
                        _____________
          response_fg                   The background and foreground color
          ______________________________                                   
                                        to use when updating an unselected,
                                        available response.
          
          unsigned char un_bg, un_fg    The background and foreground color
                        ________________                                   
          unsigned char                                                    
                        ________________                                   
                                        to use when updating an unselected,
                                        unavailable response.
          





                                       - 41 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          unsigned char sun_bg, sun_fg  The background and foreground color
                        ______________                                     
          unsigned char                                                    
                        ______________                                     
                                        to use when updating a selected,
                                        unavailable response.
          
          unsigned char select_bg,      
                       ____________     
          unsigned char                 
                       ____________     
          select_fg                     The background and foreground color
          ______________________________                                   
                                        to use when updating a selected,
                                        available response.
          
          unsigned char key_bg, key_fg  The background and foreground color
                       ________________                                    
          unsigned char                                                    
                       ________________                                    
                                        to use when updating a statement or
                                        list element.  Each character
                                        preceded by a ~ in a statement or
                                        list element is output in this
                                        color.  If there are no ~s in the
                                        string the first character is
                                        output with this color.  Used to
                                        indicate the shortcut keys for a
                                        question.
          
          unsigned char edit_bg, 
                       __________
          unsigned char          
                       __________
          edit_fg                       The background and foreground color
          _______                                                          
                                        to use when using the line editor
                                        in a free_form or reducer.
          
          
          3.  db_delimiters
          
          db_delimiters represents the characters to be placed around the
          response portion of questions within a dialog box.  Typically you
          would set up one db_delimiters structure for use with all dialog
          boxes to establish a personality for your system.  You may also
          want to have various delimiter schemes for different types of
          dialog boxes.
          
               
          
          unsigned char *ff_boxchars    The characters to place around the
                         ___________                                      
          unsigned char                                                   
                         ___________                                      
                                        response portion of a free_form
                                                              free_form
                                        question.  These character arrays
                                        are defined the same as the window
                                        border character arrays.  Note that
                                        any NULL characters are simply not
                                            NULL                          
                                        output.  This means that you do not
                                        have to triple space questions as
                                        you would by putting a complete box
                                        around each, but could just define
                                        delimiters on either side (as in
                                        DBPRO 1.1) or even none at all.
          
          unsigned char *mc_boxchars    Same as ff_boxchars, but for
                         ___________            ___________         
          unsigned char                                             
                         ___________            ___________         
                                        multi_choice questions.
          




                                       - 42 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          unsigned char *r_boxchars     Same as ff_boxchars, but for
                         __________             ___________         
          unsigned char                                             
                         __________             ___________         
                                        reducer questions.
          
          char *check_on, *check_off    The characters to be placed to the
                ________   _________                                      
          char                                                            
                ________   _________                                      
                                        left of a checkbox statement
                                        indicating that the item is checked
                                        or not checked, e.g. [ ] or [X].
          
          char *radio_on, *radio_off    Same as check_on, check_off but for
                ________   _________                                       
          char                                                             
                ________   _________                                       
                                        radio buttons.
          
          
          
          4.  dialog_box
          
          dialog_box is the basic data type used by almost all of the high
          ______ ___                                                      
          level functions.  The dialog box data structure consists of the
          following members.
          
          int handle                    Every dialog box must be related to
              ______                                                       
          int                                                              
              ______                                                       
                                        an existing window.  If handle is
                                                                ______   
                                        not a valid window handle a window
                                                                          
                                        handle is created using the window
                                        information at the end of this
                                        structure.
          
          (*post_size)(void *)          after db_run processes any sizing
            ____ ____                                                    
                       void                   db run                     
            ____ ____                                                    
                                        messages it executes post_size
                                                             ____ ____
                                        passing db_ptr as argument.
          
          int (*post_move)(void *)      after db_run processes any moving
                ____ ____                                                
          int              void               db run                     
                ____ ____                                                
                                        messages it executes post_move
                                                             ____ ____
                                        passing db_ptr as argument.
          
          char move_ok                  db_run will not process any moving
               ____ __                                                    
          char                          db run                            
               ____ __                                                    
                                        messages if move_ok is FALSE.
                                                    ____ __          
                                                               FALSE 
                                                    ____ __          
          
          char size_ok                  db_run will not process any sizing
               ____ __                                                    
          char                          db run                            
               ____ __                                                    
                                        messages if size_ok is FALSE.
                                                    ____ __          
                                                               FALSE 
                                                    ____ __          
          
          char **questions              pointer to an array representing
                 _________                                              
          char                                                          
                 _________                                              
                                        the list of questions which
                                        comprise the dialog box.  The last
                                        item in the array must be a NULL
                                        pointer.
          
          char *available               pointer to an array corresponding
                _________                                                
          char                                                           
                _________                                                
                                        to the above array, where a value
                                        of FALSE indicates that the
                                        response to the corresponding
                                        question cannot be modified.
          





                                       - 43 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          char id_select                The currently selected question as
               __ ______                                                  
          char                                                            
               __ ______                                                  
                                        an offset in the question array
                                        (questions, above.)
                                         _________         
          
          int *cmds                     An array of extended keyboard codes
               ____                                                        
          int                                                              
               ____                                                        
                                        corresponding to the standard
                                        messages, where standard message 1
                                        (PRESS_BUTTON) corresponds to
                                        keyboard code in position 0,
                                        message 2 (CONFIRM) corresponds to
                                        the keyboard code in position 1,
                                        etc.  This array is used to
                                        interpret keyboard codes into
                                        messages.  cmds is generally set to
                                                   ____                    
                                        the supplied default keyboard
                                        commands default_db_cmds.
                                                 default_db_cmds 
          
          char bg_operation             If FALSE, when db_run is executed
               __ _________                                              
          char                             FALSE       db run            
               __ _________                                              
                                        the dialog box window is brought to
                                        the top of the stack via a call to
                                        wn_openw.  If FALSE and the window
                                        wn openw      FALSE               
                                        is on the screen it remains in its
                                        position in the stack.  If FALSE
                                                                   FALSE
                                        and the window is not on the screen
                                        it is displayed via a call to
                                        wn_openw.  In a desktop type
                                        wn_openw                    
                                        application the desktop itself can
                                        be setup as a type of dialog box (a
                                        row of pull down menus along the
                                        top, with perhaps some buttons
                                        representing disk drives, etc.)  In
                                        this case we would not want the
                                        dialog box brought to the top of
                                        the stack since it would obscure
                                        all of the windows on the screen. 
                                        This type of dialog box would
                                        generally set bg_operation to TRUE.
                                                      __ _________         
                                                                      TRUE 
                                                      __ _________         
          
          storage *insurance            A pointer to a data structure
                   _________                                         
          storage                                                    
                   _________                                         
                                        representing the previous answers
                                        to the dialog box questions. 
                                        Always set this to NULL.
                                                           NULL 
          
          int **macros                  A list of macros associated with
                ______                                                  
          int                                                           
                ______                                                  
                                        this dialog box.  This array must
                                        be NULL terminated.  Each
                                           NULL                  
                                        individual macro must be
                                        constructed in this manner:
          
                                        [message to replace, number of
                                        replacement message, nth
                                        replacement message,...., first
                                        replacement message]
          



                                       - 44 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


                                        Note that the first item represents
                                        the message to be replaced, the
                                        second item represents the number
                                        of replacement items, and the
                                        succeeding items represent the
                                        messages to replace it with (note
                                        that these are in reverse order.
          
          db_colors *colors             Determines what attributes to use
                     ______                                              
          db_colors                                                      
                     ______                                              
                                        when displaying a dialog box.
          
          db_delimiters *delimiters     Determines what delimiters to place
                         __________                                        
          db_delimiters                                                    
                         __________                                        
                                        around various question types.
          
          
          5.  free_form
          
          char question_type            must be set to FREE_FORM
               ________ ____                                    
          char                                         FREE FORM
               ________ ____                                    
          
          unsigned char tile_handle     The question is displayed in this
                        ____ ______                                      
          unsigned char                                                  
                        ____ ______                                      
                                        tile.  tile_handle must be a valid
                                               ____ ______                
                                        tile handle.
          
          int (*whenon)
                ______ 
          int          
                ______ 
              (dialog_box *)
               dialog box   
          int (*whenoff)
                _______ 
          int           
                _______ 
              (dialog_box *)
               dialog box   
          int (*action)(dialog_box *)   Pointers to edit checking
                ______                                           
          int           dialog box                               
                ______                                           
                                        routines.  db_run executes each
                                                   db run              
                                        routine under these conditions.  On
                                        selecting the question whenon is
                                                               ______   
                                        executed.  On selecting a question
                                        other than the current question or
                                        on exiting db_run whenoff is
                                                          _______   
                                                   db run           
                                                          _______   
                                        executed.  On exiting the line
                                        editor action is executed.  action
                                               ______               ______
                                        must return TRUE or you will not be
                                                    TRUE                   
                                        able to exit the line editor.
                                        whenoff must return TRUE or the
                                        _______                        
                                                            TRUE       
                                        _______                        
                                        attempt to navigate to another
                                        question will fail.  If any routine
                                        is set to NULL it is not executed. 
                                                  NULL                     
                                        db_run always passes the current
                                        dialog box pointer to each edit
                                        checking function.
          
          char *statement               A string representing the statement
                _________                                                  
          char                                                             
                _________                                                  
                                        portion of the question.
          
          int statementx, statementy    The left coordinate of the
              __________  __________                              
          int                                                     
              __________  __________                              
                                        statement.
          
          int key                       Shortcut key.
              ___                                    
          int                                        
              ___                                    
          



                                       - 45 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          char *response                The current response to the
                ________                                           
          char                                                     
                ________                                           
                                        question.  This must be a
                                        dynamically allocated string.  On
                                        confirming a new response this
                                        response will be freed.
          
          char *default_response        If response is NULL when the line
                                        editor is invoked, or the response
                                        is displayed, response will be set
                                        equal to a dynamically allocated
                                        copy of this string.
          
          int responsex, responsey      The coordinate where the response
              _________  _________                                       
          int                                                            
              _________  _________                                       
                                        will be displayed.
          
          int responselen               The maximum displayed length of the
              ___________                                                  
          int                                                              
              ___________                                                  
                                        response.  The actual length of the
                                        response can be up to 1000
                                        characters.
          
          char *storage                 The previous response to the
                _______                                             
          char                                                      
                _______                                             
                                        question.  Should always be set
                                        to NULL.
                                           NULL 
          
          char **target                 The char * pointer pointed to by
                 ______                                                 
          char                                                          
                 ______                                                 
                                        target is updated with the value of
                                        ______                             
                                        response on exiting the db_run.
                                        ________                       
                                                                db run 
                                        ________                       
          
          int cursor_position           The position of the cursor on
              ______ ________                                        
          int                                                        
              ______ ________                                        
                                        confirming the current response to
                                        the question.
          
          int **macros                  See dialog_box for further
                ______                                            
          int                               dialog box            
                ______                                            
                                        explanation.
          
          char refresh                  If TRUE the statement and question
               _______                                                    
          char                                                            
               _______                                                    
                                        delimiters are output.  Set this to
                                        true on initialization.  Each time
                                        the statement and delimiters are
                                        displayed this value is reset to
                                        FALSE.
          
          
          6.  list
          
          unsigned char tile_handle     The question is displayed in this
                        ____ ______                                      
          unsigned char                                                  
                        ____ ______                                      
                                        tile.  tile_handle must be a valid
                                               ____ ______                
                                        tile handle.
          
          int (*whenon)
                ______ 
          int          
                ______ 
              (dialog_box *)
               dialog box   
          int (*whenoff)
                _______ 
          int           
                _______ 
              (dialog_box *)
               dialog box   




                                       - 46 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          int (*action)(dialog_box *)   Pointers to edit checking
                ______                                           
          int           dialog box                               
                ______                                           
                                        routines.  db_run executes each
                                                   db run              
                                        routine under these conditions.  On
                                        selecting the question whenon is
                                                               ______   
                                        executed.  On selecting a question
                                        other than the current question or
                                        on exiting db_run whenoff is
                                                          _______   
                                                   db run           
                                                          _______   
                                        executed.  On exiting the list
                                        action is executed.  Until action
                                        ______                     ______
                                        returns TRUE the user will be
                                                TRUE                 
                                        unable to exit the list.  whenoff
                                                                  _______
                                        must return TRUE or the attempt to
                                                    TRUE                  
                                        navigate to another question will
                                        fail.  If any routine is set to
                                        NULL it is not executed.  db_run
                                        NULL                            
                                        always passes the current dialog
                                        box pointer to each edit checking
                                        function.
          
          char *statement               A string representing the statement
                _________                                                  
          char                                                             
                _________                                                  
                                        portion of the question.
          
          int statementx, statementy    The left coordinate of the
              __________  __________                              
          int                                                     
              __________  __________                              
                                        statement.
          
          int key                       Shortcut key.
              ___                                    
          int                                        
              ___                                    
          
          unsigned int handle           A window handle.  The window should
                       ______                                              
          unsigned int                                                     
                       ______                                              
                                        have the number of rows and columns
                                        and appropriate border type and
                                        style as desired for the scrolling
                                        list box.  If this is not a valid
                                        window handle.  The window will be
                                        created using the window parameters
                                        below.
          
          if handle (above) is not a valid window handle we use this info
             ______                                                      
          to create a window ....
          
          unsigned virtual_rows         number of row & columns in the
                   ____________                                       
          unsigned                                                    
                   ____________                                       
          unsigned virtual_columns      virtual screen.
                   _______________                     
          unsigned                                     
                   _______________                     
          
          unsigned physical_x           location of the upper left hand
                   __________                                          
          unsigned                                                     
                   __________                                          
          unsigned physical_y           corner of the list within the
                   __________                                        
          unsigned                                                   
                   __________                                        
                                        dialog box window.
          
          unsigned virtual_x            upper left coordinate of the list's
                   _________                                               
          unsigned                                                         
                   _________                                               
          unsigned virtual_y            virtual screen which maps to the
                   _________                                            
          unsigned                                                      
                   _________                                            
                                        upper left hand corner of the lists
                                        frame.
          
          unsigned port_rows            number of rows & columns within the
                   _________                                               
          unsigned                                                         
                   _________                                               
          unsigned port_columns         list's frame
                   ____________                     
          unsigned                                  
                   ____________                     
          



                                       - 47 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          unsigned shading              style of shading to use for the
                   _______                                             
          unsigned                                                     
                   _______                                             
                                        list's frame.  See The WindowPro
                                        manual for further explanation.
          
          char *name1, *name2           a string to place in the top &
                _____   _____                                         
          char                                                        
                _____   _____                                         
                                        bottom part or the list's frame.
          
          unsigned char *boxchars       The characters to use when creating
                         ________                                          
          unsigned char                                                    
                         ________                                          
                                        the list's frame.  See The
                                        WindowPro manual for further
                                        explanation
          
          unsigned char scroll_bars     The scroll bar style to use when
                        ___________                                     
          unsigned char                                                 
                        ___________                                     
                                        creating the list's frame.  See The
                                        WindowPro manual for further
                                        explanation.
          
          Note : If handle is a valid window handle than you do not need to
                    ______                                                 
          set the above structure members to meaningful values.
          
          char list_type                Set this to SELECT_ONE for a radio
               ____ ____                                                  
          char                                      SELECT ONE            
               ____ ____                                                  
                                        buttons style list.  Set this to
                                        CHECKLIST to toggle more than one
                                        CHECKLIST                        
                                        item on and off.
          
          char **options                An array of strings representing
                 _______                                                
          char                                                          
                 _______                                                
                                        the items in the list.
          
          int offset                    An offset into the above array
              ______                                                  
          int                                                         
              ______                                                  
                                        representing the currently selected
                                        item.
          
          char *selections              An array of chars corresponding the
                __________                                                 
          char                                                             
                __________                                                 
                                        above array.  If selections[0] is
                                                         __________      
                                        TRUE indicates that the first item
                                        TRUE                              
                                        in the list is toggle on, If
                                        selections[1] is TRUE indicates
                                        __________                     
                                                         TRUE          
                                        __________                     
                                        that the second item in the list is
                                        toggled on.  selections[2] == 2
                                                  _____________        
                                        indicates that the third item
                                        represents a title within the list.
          
          char *available               pointer to an array corresponding
                _________                                                
          char                                                           
                _________                                                
                                        to the above array, where a value
                                        of FALSE indicates that the state
                                           FALSE                         
                                        of the corresponding item cannot be
                                        modified.
          
          char *on, *off                Strings which represent the on/off
                __   ___                                                  
          char                                                            
                __   ___                                                  
                                        states of each item in the list,
                                        e.g. "ON" and "OFF", or "XX" and
                                        "--", etc.
          
          list_rec *list_ptr            Used internally.  Set this to NULL.
                    ____ ___                                               
          list rec                                                    NULL 
                    ____ ___                                               



                                       - 48 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          
          char **target                 A pointer to an array of chars.  On
                 ______                                                    
          char                                                             
                 ______                                                    
                                        exiting db_run *target is set equal
                                                        ______             
                                                db run                     
                                                        ______             
                                        to selections.
                                           __________ 
          
          int **macros                  See explanation at dialog_box.
                ______                                                
          int                                              dialog box 
                ______                                                
          
          
          7.  list_rec
          
          list_rec is the basic data type used by almost all of the high
          ________                                                      
          level list-oriented functions.  The list_rec data structure
                                              ________               
          consists of the following members.
          
          int handle                    Every list must be related to an
              ______                                                    
          int                                                           
              ______                                                    
                                        existing window.  handle must be a
                                                          ______          
                                        valid window handle.
          
          int tile_handle               Every list must be related to an
              ___________                                               
          int                                                           
              ___________                                               
                                        existing tile.  tile_handle must be
                                                        ___________        
                                        a valid tile handle.
          
          char list_type                Set to CHECKLIST to allow more than
               _________________________                                   
          char                                 CHECKLIST                   
               _________________________                                   
                                        one item to be toggled on/off.  Set
                                        to SELECT_ONE so that as one item
                                           SELECT ONE                    
                                        is toggled on all other items are
                                        toggled off.
          
          char move_ok                  lst_run will not process any moving
               ____ __                                                     
          char                          lst run                            
               ____ __                                                     
                                        messages if move_ok is FALSE.
                                                    ____ __          
                                                               FALSE 
                                                    ____ __          
          
          char size_ok                  lst_run will not process any sizing
               ____ __                                                     
          char                          lst run                            
               ____ __                                                     
                                        messages if size_ok is FALSE.
                                                    ____ __          
                                                               FALSE 
                                                    ____ __          
          
          char auto_vert                If TRUE, on calling lst_run the
               ____ ____                                               
          char                             TRUE             lst run    
               ____ ____                                               
                                        window is automatically resized so
                                        that it has the same number of rows
                                        as there are items in the list.
          
          char auto_horiz               If TRUE, on calling lst_run the
               ____ _____                                              
          char                             TRUE             lst run    
               ____ _____                                              
                                        window is automatically resized so
                                        that it is as wide as the widest
                                        option.
          
          char alpha_confirm            If TRUE, list_type is SELECT_ONE,
               _____ _______                     ____ ____               
          char                             TRUE               SELECT ONE 
               _____ _______                     ____ ____               
                                        and executing lst_run,  pressing
                                                      lst run           
                                        any alpha selects the next item
                                        bound to the key, toggles it on,
                                        and exits lst_run with a value of
                                                  lst run                
                                        CONFIRMED.
                                        CONFIRMED 
          






                                       - 49 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


                                        If TRUE, list_type is CHECKLIST,
                                           TRUE               CHECKLIST 
                                        and executing lst_run, pressing any
                                                      lst run              
                                        alpha key selects the next item in
                                        the list bound to that key and
                                        toggles the item on.
          
          int *cmds                     An array of extended keyboard codes
               ____                                                        
          int                                                              
               ____                                                        
                                        corresponding to the standard
                                        messages, where standard message 1
                                        (PRESS_BUTTON) corresponds to
                                        keyboard code in position 0,
                                        message 2 (CONFIRM) corresponds to
                                        the keyboard code in position 1,
                                        etc.  This array is used to
                                        interpret keyboard codes into
                                        messages.  cmds is generally set to
                                                   ____                    
                                        the default keyboard commands
                                        default_db_cmds.
                                        default_db_cmds 
          
          char bg_operation             If FALSE, when db_run is executed
               __ _________                                              
          char                             FALSE       db run            
               __ _________                                              
                                        the dialog box window is brought to
                                        the top of the stack via a call to
                                        wn_openw.  If FALSE and the window
                                        wn openw      FALSE               
                                        is on the screen it remains in its
                                        position in the stack.  If FALSE
                                                                   FALSE
                                        and the window is not on the screen
                                        it is displayed via a call to
                                        wn_openw.  In a desktop type
                                        application the desktop itself can
                                        be setup as a type of dialog box (a
                                        row of pull down menus along the
                                        top, with perhaps some buttons
                                        representing disk drives, etc.)  In
                                        this case we would not want the
                                        dialog box brought to the top of
                                        the stack since it would obscure
                                        all of the windows on the screen. 
                                        This type of dialog box would
                                        generally set bg_operation to TRUE.
                                                      __ _________         
                                                                      TRUE 
                                                      __ _________         
          
          lst_storage *insurance        A pointer to a data structure
                       _________                                     
          lst_storage                                                
                       _________                                     
                                        representing the previous answers
                                        to the list.  Always set this to
                                        NULL.
                                        NULL 
          
          int **macros                  A list of macros associated with
                ______                                                  
          int                                                           
                ______                                                  
                                        this dialog box.  The list must be
                                        NULL terminated (i.e. the last item
                                        NULL                               
                                        in the array must be NULL.)  Each
                                                             NULL        
                                        individual macro must be
                                        constructed in this manner:
          
                                        [message to replace, nth
                                        message,...., first message, NULL]
                                                                     NULL 



                                       - 50 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          
                                        Note that the first item represents
                                        the message to be replaced, the
                                        succeeding items represent the
                                        messages to replace it with (note
                                        that these are in reverse order,)
                                        and the last item must be a NULL.
                                                                    NULL 
          
          char *on, *off                Strings which represent the on/off
                __   ___                                                  
          char                                                            
                __   ___                                                  
                                        states of each item in the list,
                                        e.g. "ON" and "OFF", or "XX" and
                                        "--", etc.
          
          char **options                An array of strings representing
                 _______                                                
          char                                                          
                 _______                                                
                                        the items in the list.  The last
                                        element in the array must be NULL.
                                                                     NULL 
          
          char *selections              An array of chars corresponding the
                __________                                                 
          char                                                             
                __________                                                 
                                        above array.  If selections[0] is
                                                         __________      
                                        TRUE indicates that the first item
                                        TRUE                              
                                        in the list is toggle on, If
                                        selections[1] is TRUE indicates
                                        __________                     
                                                         TRUE          
                                        __________                     
                                        that the second item in the list is
                                        toggled on, etc.
          
          char *available               pointer to an array corresponding
                _________                                                
          char                                                           
                _________                                                
                                        to the above array, where a value
                                        of FALSE indicates that the state
                                           FALSE                         
                                        of the corresponding item cannot be
                                        modified.
          
          unsigned *keybind             An array of ints corresponding to
                    _______                                              
          unsigned                                                       
                    _______                                              
                                        the above array where each element
                                        in the array represents an extended
                                        keyboard code or an ascii code. 
                                        These values bind the options to
                                        keystrokes (see alpha_confirm,
                                                        _____ _______ 
                                        above, for further explanation.) 
                                        If an ascii code is used selection
                                        in case insensitive.  If an
                                        extended keyboard code is used it
                                        must match exactly.
          
          int selected                  An offset into the above array
              ________                                                
          int                                                         
              ________                                                
                                        representing the item in the list
                                        which is currently selected.
          
          int                           These values are used internally
          int                                                           
                                        and should not be modified.  You
                                        may however read these variables
                                        although they are not always
                                        guaranteed to be up to date.
          
          



                                       - 51 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          optlen,                       The length of the longest option in
          ______                                                           
                                        the list.
          
          taglen,                       The length of the longest on/off
          ______                                                        
                                        indicator.
          
          numopts                       The number of items in the list.
          _______                                                       
          
          db_colors *colors             A pointer to a color scheme
                     ______                                        
          db_colors                                                
                     ______                                        
                                        structure.  Determines which
                                        attributes to use when displaying
                                        different parts of the list.
          
          unsigned maxcols              determines the number of columns in
                   _______                                                 
          unsigned                                                         
                   _______                                                 
                                        the list.  If this number is larger
                                        than the number of items in the
                                        list, creates a vertical list, like
                                        a lotus menu.
          
          unsigned                      If handle (above) is not a valid
                                           ______                       
          unsigned                                                      
                                           ______                       
                                        window handle these items are used
                                        to create a window for the list.
          
               physical_x, physical_y
          ___________________________
               virtual_x, virtual_y,
          __________________________
               virtual_rows,
          __________________
               virtual_columns
          ____________________
               port_rows, port_columns
          ____________________________
               shading
          ____________
          
          char *name1, *name2
                _____   _____
          char               
                _____   _____
          char unsigned *boxchars;
                         ________ 
          char unsigned           
                         ________ 
          
          
          8.  multi_choice
          
          char question_type            must be set to MULTI_CHOICE.
               ________ ____                                        
          char                                         MULTI CHOICE 
               ________ ____                                        
          
          unsigned char tile_handle     The question is displayed in this
                        ____ ______                                      
          unsigned char                                                  
                        ____ ______                                      
                                        tile.  tile_handle must be a valid
                                               ____ ______                
                                        tile handle.
          
          int (*whenon)
          int          
              (dialog_box *)
               dialog box   
          int (*whenoff)
          int           
              (dialog_box *)
               dialog box   
          int (*action)(dialog_box *)   Pointers to edit checking
                ______                                           
          int           dialog box                               
                ______                                           
                                        routines.  db_run executes each
                                                   db run              
                                        routine under these conditions.  On
                                        selecting the question whenon is
                                        executed.  On selecting a question
                                        other than the current question or
                                        on exiting the db_run whenoff is
                                                              _______   
                                                       db run           
                                                              _______   
                                        executed.  On confirming the



                                       - 52 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


                                        response to the current
                                        question action is executed. 
                                                 ______              
                                        whenoff must return TRUE or the
                                                            TRUE       
                                        attempt to navigate to another
                                        question will fail.  If any routine
                                        is set to NULL it is not executed. 
                                                  NULL                     
                                        db_run always passes the current
                                        dialog box pointer to each edit
                                        checking function.
          
          char *statement               A string representing the statement
                _________                                                  
          char                                                             
                _________                                                  
                                        portion of the question.
          
          int statementx, statementy    Displays the statement portion of
              __________  __________                                     
          int                                                            
              __________  __________                                     
                                        the question at these coordinates.
          
          char *response_mask           If not set to NULL, db_run
                ________ ____                                     
          char                                        NULL  db run
                ________ ____                                     
                                        suppresses the display of statement
                                        and puts this string in place of
                                        the response.  Makes multiple
                                        choice question behave like a pull
                                        down menu.
          
          char **response_list          An array of strings representing
                 ________ ____                                          
          char                                                          
                 ________ ____                                          
                                        the available choices in the
                                        multiple choice question.  The last
                                        element in the array must be set to
                                        NULL.
                                        NULL 
          
          char *available               An array of chars corresponding to
                _________                                                 
          char                                                            
                _________                                                 
                                        the above array. If available[0] is
                                                            _________      
                                        FALSE the first item cannot be
                                        FALSE                         
                                        chosen as the response, If
                                        available[1] is TRUE the second
                                        _________                      
                                                        TRUE           
                                        _________                      
                                        item in response_list can be chosen
                                                ________ ____              
                                        as the response. A 2 indicates that
                                        the list element is a title.
          
          int response_offset           The current response to the
              ________ ______                                      
          int                                                      
              ________ ______                                      
                                        question as an offset into
                                        response_list.
                                        ________ ____ 
          
          int responsex, responsey      The coordinates where the response
              _________  _________                                        
          int                                                             
              _________  _________                                        
                                        portion of the question is
                                        displayed.
          
          int responselen               The displayed length of the
              ___________                                          
          int                                                      
              ___________                                          
                                        response.  The actual response can
                                        be longer.
          







                                       - 53 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          int key                       The extended keyboard code for the
              ___                                                         
          int                                                             
              ___                                                         
                                        shortcut key (when executing
                                        db_run, if the user presses the
                                        db run                         
                                        shortcut key he navigates directly
                                        to associated question.)
          
          unsigned int aux_handle       A window handle.  Required for the
                       ___ ______                                         
          unsigned int                                                    
                       ___ ______                                         
                                        pull down list.  Note if this is
                                        not a valid window handle it will
                                        be automatically created.
          
          unsigned char aux_tile        A valid tile handle.  Required for
                        ___ ____                                          
          unsigned char                                                   
                        ___ ____                                          
                                        the pull down list.
          
          if aux_handle (above) is not a valid window handle this info to
             __________                                                  
          create a window ...
          
          unsigned char *boxchars       
                         ________       
          unsigned char                 
                         ________       
          char *major_head, *minor_head
                __________   __________
          char                         
                __________   __________
          char shading
               _______
          char        
               _______
          
          
          list_rec *list_ptr            Used internally.  Set this to NULL.
                    ____ ___                                               
          list rec                                                    NULL 
                    ____ ___                                               
          
          int *target                   A pointer to an int to set equal to
               ______                                                      
          int                                                              
               ______                                                      
                                        response_offset on exiting db_run.
                                        _______________                   
                                                                   db run 
                                        _______________                   
          
          int **macros                  See dialog_box for an explanation.
                ______                                                    
          int                               dialog box                    
                ______                                                    
          
          char refresh                  When this value is true and the
               _______                                                 
          char                                                         
               _______                                                 
                                        question is displayed the statement
                                        and delimiters are output to the
                                        dialog box's virtual screen. 
                                        Otherwise, just the response is
                                        sent.  Typically you initialize
                                        this to TRUE.  Every time the
                                                TRUE                 
                                        question is displayed this is reset
                                        to FALSE.
                                           FALSE 
          
          unsigned maxcols              Indicates how many columns to use
                   _______                                               
          unsigned                                                       
                   _______                                               
                                        when displaying the pull down list.
          
          
          9.  rcbutton
          
          This structure is used to represent either a radio button or a
          check box.
          
          char question_type            must be set to RCBUTTON.
               ________ ____                                    
          char                                         RCBUTTON 
               ________ ____                                    
          
          unsigned char tile_handle     The question is displayed in this
                        ____ ______                                      
          unsigned char                                                  
                        ____ ______                                      
                                        tile.  tile_handle must be a valid
                                               ____ ______                
                                        tile handle.
          



                                       - 54 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          int (*whenon)
                ______ 
          int          
                ______ 
              (dialog_box *)
               dialog box   
          int (*whenoff)
                _______ 
          int           
                _______ 
              (dialog_box *)
               dialog box   
          int (*action)(dialog_box *)   Pointers to edit checking
                ______                                           
          int           dialog box                               
                ______                                           
                                        routines.  db_run executes each
                                                   db run              
                                        routine under these conditions.  On
                                        selecting the question whenon is
                                                               ______   
                                        executed.  On selecting a question
                                        other than the current question or
                                        on exiting db_run whenoff is
                                                          _______   
                                                   db run           
                                                          _______   
                                        executed.  On pressing the
                                        rcbutton action is executed. 
                                                 ______              
                                        whenoff must return TRUE or the
                                                            TRUE       
                                        attempt to navigate to another
                                        question will fail.  If any routine
                                        is set to NULL it is not executed. 
                                                  NULL                     
                                        db_run always passes the current
                                        dialog box pointer to each edit
                                        checking function.
          
          char *statement               A string representing the statement
                _________                                                  
          char                                                             
                _________                                                  
                                        to appear to the right of the
                                        rcbutton's checkoff area.
          
          int statementx, statementy    left coordinate of the rcbutton.
              __________  __________                                    
          int                                                           
              __________  __________                                    
          
          int key                       Shortcut key.
              ___                                    
          int                                        
              ___                                    
          
          unsigned char btype           Set to CHECK if a checkbox, or
                        _____                                         
          unsigned char                                               
                        _____                                         
                                        RADIO(N) where N is a number
                                        between 0 and 254.  Only one
                                        rcbutton in the radio group number
                                        N can be "on" at any moment.
          
          char checked                  Set to TRUE if the rcbutton is
               _________________________                              
          char                                                        
               _________________________                              
                                        checked.
          
          char *target                  The variable pointed to by target
                ________________________                           ______
          char                                                           
                ________________________                           ______
                                        will be updated with the value of
                                        checked on exiting the dialog box.
                                        _______                           
          
          
          10. reducer
          
          char question_type            must be set to REDUCER.
               ________ ____                                   
          char                                         REDUCER 
               ________ ____                                   
          
          unsigned char tile_handle     The question is displayed in this
                        ____ ______                                      
          unsigned char                                                  
                        ____ ______                                      
                                        tile.  tile_handle must be a valid
                                               ____ ______                
                                        tile handle.
          
          int (*whenon)
          int          
              (dialog_box *)
               dialog box   
          int (*whenoff)
          int           



                                       - 55 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


              (dialog_box *)
               dialog box   
          int (*action)(dialog_box *)   Pointers to edit checking
                ______                                           
          int           dialog box                               
                ______                                           
                                        routines.  db_run executes each
                                                   db run              
                                        routine under these conditions.  On
                                        selecting the question whenon is
                                        executed.  On selecting a question
                                        other than the current question or
                                        on exiting the db_run whenoff is
                                                              _______   
                                                       db run           
                                                              _______   
                                        executed.  On confirming the
                                        response to the current
                                        question action is executed. 
                                                 ______              
                                        whenoff must return TRUE or the
                                                            TRUE       
                                        attempt to navigate to another
                                        question will fail.  If any routine
                                        is set to NULL it is not executed. 
                                                  NULL                     
                                        db_run always passes the current
                                        dialog box pointer to each edit
                                        checking function.
          
          char *statement               A string representing the statement
                _________                                                  
          char                                                             
                _________                                                  
                                        portion of the question.
          
          int statementx, statementy    Displays the statement portion of
              __________  __________                                     
          int                                                            
              __________  __________                                     
                                        the question at these coordinates.
          
          char **response_list          An array of strings representing
                 ________ ____                                          
          char                                                          
                 ________ ____                                          
                                        the available choices in the
                                        multiple choice question.  The last
                                        element in the array must be set to
                                        NULL.
                                        NULL 
          
          char *available               An array of chars corresponding to
                _________                                                 
          char                                                            
                _________                                                 
                                        the above array. If available[0] is
                                                            _________      
                                        FALSE the first item cannot be
                                        FALSE                         
                                        chosen as the response, If
                                        available[1] is TRUE the second
                                        _________                      
                                                        TRUE           
                                        _________                      
                                        item in response_list can be chosen
                                                ________ ____              
                                        as the response, etc.
          
          char *response                The current response to the
               _________                                           
          char                                                     
               _________                                           
                                        question.  Must be a dynamically
                                        allocated string as when a new
                                        response is confirmed the previous
                                        response is freed.
          
          int responsex, responsey      The coordinates where the response
              _________  _________                                        
          int                                                             
              _________  _________                                        
                                        portion of the question is
                                        displayed.
          
          int responselen               The displayed length of the
              ___________                                          
          int                                                      
              ___________                                          
                                        response.  The actual response can
                                        be longer.
          




                                       - 56 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          int key                       The extended keyboard code for the
              ___                                                         
          int                                                             
              ___                                                         
                                        shortcut key (when executing
                                        db_run, if the user presses the
                                        db run                         
                                        shortcut key he navigates directly
                                        to associated question.)
          
          int cursor_position           The position of the cursor when the
              ______ ________                                              
          int                                                              
              ______ ________                                              
                                        current response was confirmed.
          
          char **target                 A pointer to a variable to set
                _______                                               
          char                                                        
                _______                                               
                                        equal to response on exiting
                                                 ________           
                                        db_run.
                                        db run 
          
          int **list_macros             Macros used while in the pull down
                ___________                                               
          int                                                             
                ___________                                               
                                        list portion of a reducer
                                        question.  See dialog_box for an
                                                       dialog box       
                                        explanation.
          
          int **edlin_macros            Macros used while in the lide
                ____________                                         
          int                                                        
                ____________                                         
                                        editor portion of a reducer
                                        question.  See dialog_box for an
                                                       dialog box       
                                        explanation.
          
          unsigned int aux_handle       A window handle.  Required for the
                       ___ ______                                         
          unsigned int                                                    
                       ___ ______                                         
                                        pull down list.  Note if this is
                                        not a valid window handle it will
                                        be automatically created.
          
          unsigned char aux_tile        A valid tile handle.  Required for
                        ___ ____                                          
          unsigned char                                                   
                        ___ ____                                          
                                        the pull down list.
          
          if aux_handle (above) is not a valid window handle this info to
             __________                                                  
          create a window ...
          
          unsigned char *boxchars       
                         ________       
          unsigned char                 
                         ________       
          char *major_head, *minor_head
                __________   __________
          char                         
                __________   __________
          char shading
               _______
          char        
               _______
          
          
          list_rec *list_ptr            Used internally.  Set this to NULL.
                    ____ ___                                               
          list rec                                                    NULL 
                    ____ ___                                               
          
          char refresh                  When this value is true and the
               _______                                                 
          char                                                         
               _______                                                 
                                        question is displayed the statement
                                        and delimiters are output to the
                                        dialog box's virtual screen. 
                                        Otherwise, just the response is
                                        sent.  Typically you initialize
                                        this to TRUE.  Every time the
                                                TRUE                 
                                        question is displayed this is reset
                                        to FALSE.
                                           FALSE 
          
          unsigned maxcols              Indicates how many columns to use
                   _______                                               
          unsigned                                                       
                   _______                                               
                                        when displaying the pull down list.
          



                                       - 57 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          11. scroll_txt
          
          This data structure is used to define the scrolling text type
          questions.  This question type is different from the other
          question types because you must supply the address to the
          'controlling' function.  Two sample controlling functions are
          provided.
          
          char question_type            Must be set to SCROLL_TXT.
               _____________                                      
          char                                         SCROLL_TXT 
               _____________                                      
          
          unsigned char tile_handle     The question is displayed in this
                        ____ ______                                      
          unsigned char                                                  
                        ____ ______                                      
                                        tile.  tile_handle must be a valid
                                               ____ ______                
                                        tile handle.
          
          int (*whenon)
          int          
              (dialog_box *)
               dialog box   
          int (*whenoff)
          int           
              (dialog_box *)
               dialog box   
          int (*action)(dialog_box *)   Pointers to edit checking
                ______                                           
          int           dialog box                               
                ______                                           
                                        routines.  db_run executes each
                                                   db run              
                                        routine under these conditions.  On
                                        selecting the question whenon is
                                        executed.  On selecting a question
                                        other than the current question or
                                        on exiting the db_run whenoff is
                                                              _______   
                                                       db run           
                                                              _______   
                                        executed.  On confirming the
                                        response to the current
                                        question action is executed. 
                                                 ______              
                                        whenoff must return TRUE or the
                                                            TRUE       
                                        attempt to navigate to another
                                        question will fail.  If any routine
                                        is set to NULL it is not executed. 
                                                  NULL                     
                                        db_run always passes the current
                                        dialog box pointer to each edit
                                        checking function.
          
          int (far *control)
                    _______ 
          int  far          
                    _______ 
               (dialog_box *, int)      On executing the question control
                dialog_box    int                                        
                                        is passed to this routine.  In the
                                        event of a MOUSE_EVENT occuring
                                                   MOUSE_EVENT         
                                        within the question's region the
                                        second parameter will be set to
                                        MOUSE_EVENT. Otherwise the
                                        MOUSE_EVENT               
                                        parameter will be 0.
          
          void *misc_ptr                Because the use of SCROLL_TXT is
                ________                                                
          void                                             SCROLL_TXT   
                ________                                                
                                        open-ended it may be necessary to
                                        associate additional data with the
                                        question.  You can point to a
                                        structure containing this
                                        additional data using this pointer.
          





                                       - 58 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          int boxx, boxy                The upper left corner of the
              ____  ____                                            
          int                                                       
              ____  ____                                            
                                        question will begin at this
                                        coordinate within the dialog box
                                        window.
          
          unsigned int aux_handle       The question requires a window for
                       __________                                         
          unsigned int                                                    
                       __________                                         
                                        some interim processing.  Create a
                                        window and assign the handle to
                                        this data structure member.  The
                                        question region will be same size
                                        as this window.
          
          int **macros                  See dialog_box for further
                ______                                            
          int                               dialog box            
                ______                                            
                                        explanation.
          
          
          
          12. title
          
          Use this to display titles in dialog boxes.
          
          char question_type            Must be set to TITLE.
               _________________________                     
          char                                         TITLE 
               _________________________                     
          
          unsigned char tile_handle     Indicates which tile to display the
                        ________________                                   
          unsigned char                                                    
                        ________________                                   
                                        title in.
          
          char *statement               Indicates the title string.
                _________                                          
          char                                                     
                _________                                          
          
          int statementx, statementy    Where to locate the title.
              __________________________                          
          int                                                     
              __________________________                          
          
          char center_justify           If TRUE ignores statementx and
               _________________________                __________    
          char                             TRUE                       
               _________________________                __________    
                                        center justifies the title within
                                        the virtual screen.
























                                       - 59 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          E. Global variables
          
          1. db_head, db_tail, db_queue
          
          int *db_queue                 An array of ints representing the
               __ _____                                                  
          int                                                            
               __ _____                                                  
                                        circular message queue
          
          unsigned char *db_head        A pointer to a char containing the
                         __ ____                                          
          unsigned char                                                   
                         __ ____                                          
                                        offset into db_queue where the last
                                                    __ _____               
                                        message in the queue is located.
          
          unsigned char *db_tail        A pointer to a char containing the
                         __ ____                                          
          unsigned char                                                   
                         __ ____                                          
                                        offset into db_queue where the next
                                                    __ _____               
                                        message to be used is located.
          
          
          2. default_db_cmds
          
          A default keyboard-command table.
          
          
          3. idle
          
          void (* idle)(void *)
                  ____         
          void          void   
                  ____         
          
          the idle function is repeatedly called in the keyboard/mouse
          polling loop.  The function pointed to by idle is passed a
                                                    ____            
          pointer to the active dialog_box or list_rec on each call.  Use
                                dialog_box    list_rec                   
          this to place time limits on a response, update a time and date
          field, or do other real time updating.  Note that the timing of
          the polling loop can vary based on whether keyboard typematic is
          active, the mouse buttons are up or down, or whether or not a
          mouse is installed.
          
          
          4. monitor_switch, _fg, _bg, _speed, _wdw, _tile
          
          These values determine how the debug monitor operates.  The debug
          monitor will display the queue events in a window.  You can watch
          these queue events to determine if a dialog box is behaving
          properly.
          
          extern unsigned int 
          extern unsigned int 
            monitor_wdw                 The handle of the window where the
            ___________                                                   
                                        debug info will be displayed.  The 
          extern unsigned char          
          extern unsigned char          
            monitor_tile                The tile handle where the debug
          ______________                                               
                                        info will be displayed.  This
                                        tile's virtual screen needs to be
                                        about 70 characters wide.
          
          extern int monitor_speed      0 = no delay, > 0 = more delay, -1
                     _____________                                        
          extern int                                                      
                     _____________                                        
                                        = step through by keystroke.
          



                                       - 60 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          extern int monitor_switch     0 if monitor is OFF, 1 if it is ON.
                     ______________                                        
          extern int                                                       
                     ______________                                        
          
          extern unsigned char 
          extern unsigned char 
            monitor_fg, monitor_bg      The background and foreground color
            __________  __________                                         
                                        that the monitor info will display
                                        in.
          
          
          
          5. mouse_sensitivity
          
          The timeout value to be used when calling kb_mouseclicks.  15
                                                    kb mouseclicks     
          seems to work just about right.  But you may want to fine tune it
          for other systems or give the user access to this value--like the
          MAC or Microsoft Windows.










































                                       - 61 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          F. Messages
          
          1. Dialog Box
          
          Each message is translated as follows at the dialog box level by
                                                _______________________   
          db_run (several of the messages transfer porcessing to question
          level--to see how messages are interpreted at the question level
          review the following section):
          
          DO_NOTHING          Does nothing.
          DO_NOTHING                       
          
          PRESS_BUTTON        If the current question (indicated by
          PRESS_BUTTON                                             
                              db_ptr->id_select) is a button the value
                              ______                                  
                                    ->id_select                       
                              ______                                  
                              BUTTONQUEST(db_ptr->id_select)->cmd_key is
                                          ______                        
                              BUTTONQUEST(      ->id_select)->cmd_key   
                                          ______                        
                              placed at the tail of the queue and the
                              global variable button_press is set to
                              BUTTONQUEST(db_ptr->id_select)->exitval.
                                          ______                      
                              BUTTONQUEST(      ->id_select)->exitval 
                                          ______                      
          
                              If the current question is a multiple choice
                              question the current response + 1 (with wrap
                              around from the last response to the first)
                              becomes the new response.
          
                              On the other questions, nothing happens.
          
          CONFIRM             If the current question is a multiple choice
          CONFIRM                                                         
                              and CURRMC->response__mask does not equal
                                  CURRMC->response__mask               
                              NULL the message DESCEND is placed at the
                              NULL             DESCEND                 
                              tail of the queue.  
          
                              Otherwise, if at the dialog box level, it
                              executes db_freestorage.  Exits db_run with
                                       db_freestorage         db_run     
                              the value CONFIRMED and places CONFIRM at the
                                        CONFIRMED            CONFIRM       
                              tail of the queue if button_press is equal to
                                                   button_press            
                              0, otherwise it exits with the value of
                              button_press.
                              button_press 
          
          ABORT               Executes db_restoreanswers and exits db_run.
          ABORT                        db_restoreanswers           db_run 
                              Exits with the value ABORTED and places ABORT
                                                   ABORTED            ABORT
                              at the tail of the queue if button_press is
                                                          button_press   
                              equal to 0, otherwise it exits with the value
                              button_press.
                              button_press 
          
          UP, DOWN, LEFT, RIGHT, HOME, END, BIG_RIGHT, BIG_LEFT, BACKSPACE
          UP, DOWN, LEFT, RIGHT, HOME, END, BIG_RIGHT, BIG_LEFT, BACKSPACE
          
                              Passes the event onto the current question by
                              putting the respective event at the tail of
                              the queue and then placing a DESCEND at the
                              tail of the queue.  
          
                              In the case of a BUTTON the event is
                              ignored.  In the case of radio button selects
                              the next or previous radio button in the
                              radio button group.



                                       - 62 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          
          BIG_UP              Does nothing.
          BIG_UP                           
          BIG_DOWN                 "
          BIG_DOWN                  
          
          BIG_HOME            Selects the first question in the dialog box.
          BIG_HOME                                                         
          BIG_END             Selects the last question in the dialog box.
          BIG_END                                                         
          
          ASCEND              Executes db_freestorage.  Exits db_run with
          ASCEND                       db_freestorage         db_run     
                              the value ASCENDED if button_press is equal
                                        ASCENDED    button_press         
                              to 0, otherwise it exits with the value of
                              button_press.
                              button_press 
          
          DESCEND             If the current question is a multiple choice,
          DESCEND                                                          
                              "pulls down" the list of selection in a
                              vertical list, with the current response
                              highlighted.
          
                              If the current question is a free form or
                              reducer, enters the line editor.
          
                              If the current question is a list, the cursor
                              moves inside of the scrolling list and the
                              item which was highlighted when the user last
                              executed the list is highlighted.
          
                              If the current question is a button, does
                              nothing.
          
          EXPAND              If the current question is a multiple choice
          EXPAND                                                          
                              question it "pulls down" the available
                              responses to the question in a vertical list.
          
                              If the current question is a reducer is
                              "pulls down" ALL of the available responses
                              to the question in a vertical list.
          
          DELETE              does nothing.
          DELETE                           
          
          MOUSE_CONFIRM       Executes db_freestorage.  Exits db_run with
          MOUSE_CONFIRM                db_freestorage         db_run     
                              the value MOUSED and places MOUSE_EVENT at
                                        MOUSED            MOUSE_EVENT   
                              the tail of the queue.
           
          MOUSE_EVENT         Interprets the last mouse event (prev_x,
          MOUSE_EVENT                                          prev_x 
                              prev_y, and prev_click) into keystroke.  The
                              prev_y      prev_click                      
                              keystroke is then placed at the tail of the
                              queue.
          
          MOUSE_DESCEND       If the current question is a reducer or a
          MOUSE_DESCEND                                                
                              multiple choice question db_run calls the
                                                       db_run          
                              line editor and places the cursor at the
                              location clicked on in the text.
          





                                       - 63 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


                              If the current question is a list,
                              MOUSE_EVENT is placed at the tail of the
                              MOUSE_EVENT                             
                              queue and the list is executed.
          
          STORE               Executes db_storeanswers.
          STORE                        db_storeanswers.
          
          RESTORE             Executes db_restoreanswers.
          RESTORE                      db_restoreanswers 
          
          FREE_STORAGE        Executes db_freestorage.
          FREE_STORAGE                 db_freestorage 
          
          POSITION            Selects the question based on the value of
          POSITION                                                      
                              the next integer in the event queue.
          
          POSITION_TOGGLE     Does nothing.
          POSITION_TOGGLE                  
          
          POSITION_CONFIRM    Does nothing.
          POSITION_CONFIRM                 
          
          If db_ptr->size_ok is TRUE then:
             ______                       
                   ->size_ok              
             ______                       
          
          SIZE_LT             Pulls right border of window (db_ptr->handle)
                                                            ______         
          SIZE_LT                                                 ->handle 
                                                            ______         
                              in one character.
          
          SIZE_RT             Pulls right border of window (db_ptr->handle)
                                                            ______         
          SIZE_RT                                                 ->handle 
                                                            ______         
                              out one character.
          
          SIZE_UP             Pulls bottom border of tile (db_ptr->handle,
                                                           ______         
          SIZE_UP                                                ->handle 
                                                           ______         
                              QUESTION->tile_handle) up one character.
                              QUESTION->tile_handle                   
          
          SIZE_DN             Pulls bottom border of tile down one
          SIZE_DN                                                 
                              character.
          
          BIG_SIZE_LT         Same as above but by 8 characters.
          BIG_SIZE_LT                                           
          
          BIG_SIZE_RT                        "
          BIG_SIZE_RT                         
          
          BIG_SIZE_UP                        "
          BIG_SIZE_UP                         
          
          BIG_SIZE_DN                        "
          BIG_SIZE_DN                         
          
          SCROLL_LT           Scrolls virtual screen (db_ptr->handle,
                                                      ______         
          SCROLL_LT                                         ->handle 
                                                      ______         
                              QUESTION->tile_handle) left one column.
                              QUESTION->tile_handle                  
          
          SCROLL_RT                          "         right     ".
          SCROLL_RT                                                
          
          SCROLL_UP                          "         up one row.
          SCROLL_UP                                               
          
          SCROLL_DN                          "         down      ".
          SCROLL_DN                                                
          
          BIG_SCROLL_LT       Same as above but by 8.
          BIG_SCROLL_LT                              
          
          BIG_SCROLL_RT                      "
          BIG_SCROLL_RT                       
          
          BIG_SCROLL_UP                      "
          BIG_SCROLL_UP                       
          



                                       - 64 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          BIG_SCROLL_DN                      "
          BIG_SCROLL_DN                       
          
          MOVE_LT             Moves the window (db_ptr->handle) left one
                                                ______                  
          MOVE_LT                                     ->handle          
                                                ______                  
                              character.
          
          MOVE_RT                            "              right.
          MOVE_RT                                                 
          
          MOVE_UP                            "              up.
          MOVE_UP                                              
          
          MOVE_DN                            "              down.
          MOVE_DN                                                
          
          BIG_MOVE_LT         Same as above but by 8.
          BIG_MOVE_LT                                
          
          BIG_MOVE_RT                        "
          BIG_MOVE_RT                         
          
          BIG_MOVE_UP                        "
          BIG_MOVE_UP                         
          
          BIG_MOVE_DN                        "
          BIG_MOVE_DN                         
          
          EXECUTE             Executes a function by generating a function
          EXECUTE                                                         
                              pointer based on the next two instructions in
                              the event queue.  The function is passed
                              db_ptr as a parameter.  The function is
                              db_ptr                                 
                              continually execute until it returns an
                              integer value of TRUE.
                                               TRUE 
          
          alphanumeric        If on a free_form or reducer, erases the
                              current response, makes the character pressed
                              the first character in the new response and
                              enters the line editor.
          
                              If on a multiple choice, selects the next
                              item beginning with that character.
          
          NEXT, PREVIOUS      Selects the next/previous question.
          NEXT  PREVIOUS                                         
          
          
          2. Line Editor
          
          The line editor is invoked when editing a free_form or a reducer.
          Each message is translated as follows at the line editor level
                                                ________________________
          (several of the messages transfer porcessing to the dialog box
          level--to see how messages are interpreted at the dialog box
          level review the previous section):
          
          CONFIRM             Exits the line editor and makes
          CONFIRM                                            
                              CURRFF->response (or CURRR->response, for a
                              ______               _____                 
                                    ->response          ->response       
                              ______               _____                 
                              reducer) equal to the current edited
                              response.  Also, places a CONFIRM at the tail
                                                        CONFIRM            
                              of the queue.  If the question is a reducer
                              and the current response matches more than
                              one of the specified items, the possible
                              matches are displayed in a "pulldown" list.
          



                                       - 65 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


                              Executes CURRFF->action(db_ptr) (or
                                       ______                    
                                             ->action(db_ptr)    
                                       ______                    
                              CURRR->action(db_ptr).)
                              _____                  
                                   ->action(db_ptr)  
                              _____                  
          
          ABORT               Exits the line editor.  The current edited
          ABORT                                                         
                              response is replaced by the previous response
                              (CURRFF->response or CURRR->response.) Also
                               ______              _____                 
                                     ->response         ->response       
                               ______              _____                 
                              places an ABORT at the tail of the queue.
                                        ABORT                          
          
                              Executes CURRFF->action(db_ptr) (or
                                       ______                    
                                             ->action(db_ptr)    
                                       ______                    
                              CURRR->action(db_ptr).)
                              _____                  
                                   ->action(db_ptr)  
                              _____                  
          
          LEFT                Selects the character to the left.
          LEFT                                                  
          
          RIGHT                              "             right.
          RIGHT                                                  
          
          HOME                Selects the first character.
          HOME                                            
          
          END                 Selects the last character.
          END                                            
          
          BIG_LEFT            Selects the first character in the word to
          BIG_LEFT                                                      
                              the left.
          
          BIG_RIGHT           Selects the first character in the word to
          BIG_RIGHT                                                     
                              the right.
          
          ASCEND              Same as CONFIRM.
          ASCEND                      CONFIRM 
          
          DESCEND                  "
          DESCEND                   
          
          BACKSPACE           Deletes the character to the left of the
          BACKSPACE                                                   
                              cursor.
          
          DELETE              Deletes the character under the cursor.
          DELETE                                                     
          
          MOUSE_CONFIRM       Same as CONFIRM, but also puts a MOUSE_EVENT
          MOUSE_CONFIRM               CONFIRM                  MOUSE_EVENT
                              at the tail of the queue.
          
          MOUSE_EVENT         Converts the last mouse event into a message
          MOUSE_EVENT                                                     
                              of either POSITION or MOUSE_CONFIRM.
                                        POSITION    MOUSE_CONFIRM 
          
          STORE               if CURRFF->insurance is NULL makes it equal
                                 ______                                  
          STORE                        ->insurance    NULL               
                                 ______                                  
                              to CURRFF->response.
                                 ______           
                                       ->response 
                                 ______           
          
          RESTORE             If CURRFF->insurance does not equal NULL
                                 ______                               
          RESTORE                      ->insurance                NULL
                                 ______                               
                              makes CURRFF->response equal to
                                    ______                   
                                          ->response         
                                    ______                   
                              CURRFF->insurance and sets CURRFF->insurance
                              ______                     ______           
                                    ->insurance                ->insurance
                              ______                     ______           
                              to NULL.
                                 NULL 
          
          FREE_STORAGE        Set CURRFF->insurance to NULL.
                                  ______                    
          FREE_STORAGE                  ->insurance    NULL 
                                  ______                    
          
          POSITION            Selects the character based on the value of
          POSITION                                                       
                              the next integer in the event queue.
          
          



                                       - 66 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          3. list question
          
          Each message is translated as follows at the list level (several
                                                _________________         
          of the messages transfer porcessing to the dialog box level--to
          see how messages are interpreted at the dialog box level review
          the previous section):
          
          CONFIRM             Executes CURRLIST->action(db_ptr), places a
                                       _________                         
          CONFIRM                               >action(db_ptr)          
                                       _________                         
                              CONFIRM at the tail of the queue, and exits
                              CONFIRM                                    
                              back to db_run.
          
          PRESS_BUTTON        check the current item on/off.
          PRESS_BUTTON                                      
          
          ABORT               Executes lst_freestorage, executes
          ABORT                                                 
                              CURRLIST->action(db_ptr), places an ABORT at
                              _________                                   
                                       >action(db_ptr)                    
                              _________                                   
                              the tail of the queue, and exits back to
                              db_run.
          
          UP                  Highlights item above current item.
          UP                                                     
          
          DOWN                Highlights item below current item.
          DOWN                                                   
          
          LEFT                If in a multicolumn list selects the item to
          LEFT                                                            
                              the left of the current item.
          
          RIGHT               If in a multicolumn list selects the item to
          RIGHT                                                           
                              the right of the current item.
          
          HOME                Highlights the first item.
          HOME                                          
          
          END                 Highlights the last item.
          END                                          
          
          BIG_UP              Highlights the item a window's length above.
          BIG_UP                                                          
          
          BIG_DOWN            Highlights the item a window's length below.
          BIG_DOWN                                                        
          
          ASCEND              Exits the list, confirms the current
          ASCEND                                                  
                              responses, and executes
                              CURRLIST->action(CURRLIST->list_ptr). 
                              _________        _________            
                                       >action(         >list_ptr)  
                              _________        _________            
          
          DESCEND                  "
          DESCEND                   
          
          MOUSE_CONFIRM       Same as ASCEND, but also puts a MOUSE_EVENT
          MOUSE_CONFIRM               ASCEND                  MOUSE_EVENT
                              at the tail of the queue.
          
          MOUSE_EVENT         Converts the last mouse event into a message
          MOUSE_EVENT                                                     
                              of either POSITION, POSITION_TOGGLE or
                                        POSITION  POSITION_TOGGLE   
                              MOUSE_CONFIRM.
                              MOUSE_CONFIRM 
          
          STORE               Stores the current selected item in another
          STORE                                                          
                              data structure.
          
          RESTORE             Restores the list to its state when STORE was
          RESTORE                                                 STORE    
                              called.



                                       - 67 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          
          FREE_STORAGE        Free data structures created on STORE.
          FREE_STORAGE                                        STORE 
          
          POSITION            Highlights an item based on the value of the
          POSITION                                                        
                              next instruction in the event queue.
          
          POSITION_TOGGLE     Highlights item clicked on (based on the
          POSITION_TOGGLE                                             
                              value of the next instruction in the event
                              queue,) and toggles the item on/off.
          
          POSITION_CONFIRM         "
          POSITION_CONFIRM          
          
          
          
          
          4. Pull down list
          
          Pull down lists can originate from a multiple choice or a reducer
          question.  Regardless of how they came about they operate the
          same.  Each message is translated as follows at the pull down
                                                       ________________
          list level (several of the messages transfer porcessing to the
          __________                                                    
          dialog box level--to see how messages are interpreted at the
          dialog box level review the previous section):
          
          CONFIRM             Selects the current item as the answer, exits
          CONFIRM                                                          
                              the pull down list and places a RIGHT at the
                                                              RIGHT       
                              tail of the queue.
          
                              Executes CURRMC->action(db_ptr) (or
                                       ______                    
                                             ->action(db_ptr)    
                                       ______                    
                              CURRR->action(db_ptr).)
                              _____                  
                                   ->action(db_ptr)  
                              _____                  
          
          ABORT               Does not change the selected item, and exits
          ABORT                                                           
                              the pull down list.
          
                              Executes CURRMC->action(db_ptr) (or
                                       ______                    
                                             ->action(db_ptr)    
                                       ______                    
                              CURRR->action(db_ptr).)
                              _____                  
                                   ->action(db_ptr)  
                              _____                  
          
          UP                  Highlights item above current item.
          UP                                                     
          
          DOWN                Highlights item below current item.
          DOWN                                                   
          
          LEFT                If a multicolumn list selects the item to the
          LEFT                                                             
                              left of the current item.
          
          RIGHT               If a multicolumn list selects the item to the
          RIGHT                                                            
                              right of the current item.
          
          HOME                Highlights the first item.
          HOME                                          
          
          END                 Highlights the last item.
          END                                          
          
          BIG_UP              Highlights the item a window's length above.
          BIG_UP                                                          
          
          BIG_DOWN            Highlights the item a window's length below.
          BIG_DOWN                                                        



                                       - 68 -





          DialogPro v 2.0                                       Users Guide
                                                           Reference Manual


          
          ASCEND              Selects the current item as the answer, and
          ASCEND                                                         
                              exits the pull down list.
          
                              Executes CURRMC->action(db_ptr) (or
                                       ______                    
                                             ->action(db_ptr)    
                                       ______                    
                              CURRR->action(db_ptr).)
                              _____                  
                                   ->action(db_ptr)  
                              _____                  
          
          DESCEND                  "
          DESCEND                   
          
          MOUSE_CONFIRM       Same as ASCEND, but also puts a MOUSE_EVENT
          MOUSE_CONFIRM               ASCEND                  MOUSE_EVENT
                              at the tail of the queue.
          
          MOUSE_EVENT         Converts the last mouse event into a message
          MOUSE_EVENT                                                     
                              of either POSITION, POSITION_TOGGLE or
                                        POSITION  POSITION_TOGGLE   
                              MOUSE_CONFIRM.
                              MOUSE_CONFIRM 
          
          STORE               Stores the current selected item in another
          STORE                                                          
                              data structure.
          
          RESTORE             Restores the list to its state when STORE was
          RESTORE                                                 STORE    
                              called.
          
          FREE_STORAGE        Free data structures created on STORE.
          FREE_STORAGE                                        STORE 
          
          POSITION            Highlights an item based on the position of
          POSITION                                                       
                              the last mouse event.
          
          POSITION_TOGGLE     Highlights item clicked on, selects the item,
          POSITION_TOGGLE                                                  
                              and exits.
          
          POSITION_CONFIRM         "
          POSITION_CONFIRM          


























                                       - 69 -









          ----------------- The DialogPro registration form ---------------
          
          Mailing Address
          
          Name         :___________________________________________________
          Company Name :___________________________________________________
          Position     :___________________________________________________
          Street       :___________________________________________________
                        ___________________________________________________
          City         :_________________  State  :__  Zip Code :__________
          Country      :___________________________________________________
          Compuserve # :___________________________________________________
          
          
          Computer System
          
          Manufacturer :___________________________________________________
          Model        :___________________________________________________
          RAM          :___________________________________________________
          
          Disk Media   5 1/4" 360K __    5 1/4" 1.2mb __  
                       3 1/2" 720K __    3 1/2" 1.4mb __
          Hard Disk
            Capacity   :___________________________________________________
          Video Adapter:___________________________________________________
          Monitor      :___________________________________________________
          
          
          How did you hear about DialogPro? ______________________________
          _________________________________________________________________
          _________________________________________________________________
          _________________________________________________________________
          
          Desired Support Level (check one)
          
          __ $15,  The DialogPro shareware diskette
          __ $50,  registered DialogPro shareware library user
          __ $100, registered DialogPro source code user (non-commercial)
          __ $200, registered DialogPro source code user (commercial)
          
          Include a check for the amount corresponding to the desired level
          of service.  Make the check payable to, Seabreeze Software.



















