home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / v / vista / !Manual / manual / wins < prev   
Text File  |  1996-01-09  |  17KB  |  483 lines
  1. <html>
  2. <title>Derived Windows</title>
  3. <h1>Derived Windows</h1>
  4.  
  5. The Window class provides facilities for the manipulation of basic windows.  In 
  6. order to provide more functional windows, it is necessary to define new
  7. classes based on the Window class.  The Window class has a set of virtual
  8. member functions which may be replaced by a derived class in order to
  9. enhance the functionality.
  10. <p>
  11. Vista includes a set of useful functional windows which may be used
  12. by the program.  Again, if the functionality of the windows defined i
  13. not sufficient, it is a simple matter of deriving a new class from
  14. them.
  15. <p>
  16. The derived windows supplied with Vista are:
  17. <p>
  18. <ul>
  19. <li><a href="file:wins#dbox">DialogueBox:</a> - An input/output device
  20. <li><a href="file:wins#grid">IconGrid:</a> - A window like a Filer
  21. <li><a href="file:wins#save">SaveBox:</a> - The standard Save box
  22. <li><a href="file:wins#prog">ProgramInfo:</a> - The standard Program Info box
  23. </ul>
  24.  
  25. <p>
  26. <hr>
  27. <p>
  28. <a name="dbox"></a>
  29. <h2>DialogueBox</h2>
  30.  
  31. The DialogueBox class implements a generic data input/output mechanism.
  32. It consists of a window which contains a set of <a href="file:wins#attr">attributes.</a>
  33. An attribute
  34. is a piece of data that may be modified by the user.  It appears as
  35. an icon in the window.
  36. <p>
  37. The Dialogue Box class is defined as:
  38. <hr>
  39. <pre>
  40.  
  41.    class DialogueBox : public Window, public Thread
  42.       {
  43.       public:
  44.          DialogueBox (Task *t, char *tname, int cancel = -1, int ok = -1, char *menu = 0) ;
  45.          virtual ~DialogueBox() ;
  46.          void click (int mx, int my, int buttons, int icon) ;
  47.          void key(int icon, int x, int y, int height, int index, int code) ;
  48.          virtual void show() ;
  49.          virtual void hide() ;
  50.          void run() ;
  51.          void close() ;
  52.          Icon *find_icon (int icon) { return NULL ; }
  53.          virtual void cancel(int button) ;
  54.          virtual void ok(int button) ;
  55.          void add_attribute (Attribute *attr) ;
  56.          void create_attribute (int iconnum, char *str) ;
  57.          void create_attribute (int iconnum, int &num) ;
  58.          void create_attribute (int iconnum, bool &value) ;
  59.          void create_attribute (int num_values, bool *values, ...) ;
  60.          void create_attribute (Icon *icon, char *str) ;
  61.          void create_attribute (Icon *icon, int &num) ;
  62.          void create_attribute (Icon *icon, bool &num) ;
  63.          void next_attribute (int icon) ;
  64.          void prev_attribute (int icon) ;
  65.       protected:
  66.          Attribute *attributes ;
  67.          Attribute *last_attribute ;
  68.          Icon *cancel_icon ;
  69.          Icon *ok_icon ;
  70.          ThreadSemaphore *waiting ;
  71.          int from_menu ;
  72.       public:
  73.          int cancelled ;
  74.       } ;
  75.  
  76. </pre>
  77. <hr>
  78. <p>
  79. It is derived from both the Window and Thread classes.  This means that it
  80. behaves like both classes.  It appears as a window on the screen, but also
  81. runs as a thread.
  82. <p>
  83. The normal operation for a dialogue box is for the user to display it on the
  84. screen, fill in some of the fields and click on either the OK or Cancel button.
  85. If the OK button is clicked, the attributes are committed, otherwise the values
  86. entered by the user are discarded.  It is normally necessary for the program
  87. to wait for the user to enter the data before it can continue.
  88. <p>
  89. The DialogueBox is created by use of the constructor.  This is supplied with the
  90. following parameters:
  91. <p>
  92. <ol>
  93. <li>The task
  94. <li>The name of the window template
  95. <li>The icon number for the 'Cancel' icon (-1 = none)
  96. <li>The icon number for the 'OK' icon (-1 = none)
  97. <li>The name of a menu (0 = none)
  98. </ol>
  99. <p>
  100. The dialogue box does not appear on the screen.  To do this, the 'show()'
  101. function must be called.  This causes the window to appear on the screen
  102. and the thread started.  The thread terminates when the user has closed the
  103. dialogue box by clicking on OK or Cancel (or by otherwise causing the
  104. window to close).  Usually the function which opened the dialogue box will
  105. be waiting the the user to fill it in.
  106.  
  107. <p>
  108. <a name="attr"></a>
  109. <h3>Attributes</h3>
  110.  
  111. When defining a dialogue box, a new class should be derived from the 
  112. DialogueBox base class.  This new class should contain all the attributes
  113. to be filled in by the user.  An attribute consists of 2 parts:
  114. <p>
  115. <ol>
  116. <li>A piece of data which will contain the value of the attribute
  117. <li>A user interface allowing the user to modify the value.
  118. </ol>
  119. <p>
  120. In order to tie these 2 parts together, you need to tell the DialogueBox
  121. class what they are.  The functions 'create_attribute' allow the dialogue
  122. box to be told of all the attributes it contains.
  123. <p>
  124. For example, consider the following dialogue box:
  125. <pre>
  126.  
  127. class PersonDetails : public DialogueBox
  128.    {
  129.    public:
  130.       PersonDetails(Task *t) : DialogueBox (t, "details", 1, 2)
  131.           {
  132.           strcpy (name, "") ;
  133.           age = 21 ;
  134.           create_attribute (3, name) ;
  135.           create_attribute (4, age) ;
  136.           }
  137.       ~PersonDetails() {}
  138.  
  139. // attributes
  140.  
  141.       char name[32] ;
  142.       int age ;
  143.    } ;
  144.  
  145. </pre>
  146. This dialogue box is created from a template called "details" and
  147. has an OK and a Cancel button.  The OK button has icon number 2 and the
  148. Cancel button is icon 1.
  149. <p>
  150. There are 2 attributes:
  151. <p>
  152. <ol>
  153. <li><b>name</b> - a string (icon number 3)
  154. <li><b>age</b> - an integral number (icon number 4)
  155. </ol>
  156. <p>
  157. The constructor initialises the values for the attributes and tells the
  158. DialogueBox class the icon number and data address of each.  The icons
  159. representing the attributes should be writeable icons so that the user
  160. may fill them in.
  161. <p>
  162. When the user clicks on the OK button, the values he has types in to the
  163. icons are copied into the attributes value.  If he clicks on Cancel, the
  164. values types in are ignored.  Also, clicking on Cancel sets a variable
  165. called 'cancelled' inside the DialogueBox and this can be interrogated
  166. by the caller.
  167. <p>
  168. Attributes may also be created manually by creating an object of a type
  169. derived from the type 'Attribute'.  This is an abstract class which has
  170. a number of specific attribute types derived from it.  The attribute
  171. types are:
  172. <p>
  173. <ol>
  174. <li><b>StringAttribute</b>    - the value is a string
  175. <li><b>BoolAttribute</b>      - the value is a boolean
  176. <li><b>IntegerAttribute</b>   - the value is an integer
  177. <li><b>SetAttribute</b>       - the value is a set of boolean values (array of words)
  178. </ol>
  179. <p>
  180. Once the attribute has been created it is automatically added to the dialogue box
  181. and deleted when the dialogue box is deleted.
  182. <p>
  183. <h3>Displaying a Dialogue Box</h3>
  184.  
  185. In order to cause a dialogue box to appear on the screen, the function
  186. 'show()' is called.  This opens the window and starts the thread running.
  187. The function that called 'show()' may then wait for the user to fill in
  188. and close the dialogue box by use of the 'sleep()' function.
  189. <p>
  190.  
  191. For example, if we wanted to open the PersonDetails dialogue box and
  192. wait for the user to fill in the name and age, we would write the following
  193. code:
  194. <pre>
  195.  
  196. void fill_in_details(Task *task)
  197.    {
  198.    PersonDetails details (task) ;     // create the DialogueBox
  199.    details.show() ;                   // show it on the screen
  200.    task->sleep (&details) ;           // sleep until it is closed
  201.    if (!details.cancelled)            // check if input was cancelled
  202.       {
  203.       // use the attribute values from details.
  204.       }
  205.    }
  206.  
  207. </pre>
  208. The destructor for the PersonDetails dialogue box will be called
  209. at the end of the function when the variable 'details' goes out
  210. of scope.
  211. <p>
  212. If the dialogue box is attached to a menu selection it will behave
  213. differently.  When Vista informs the task or window that the
  214. appropriate menu selection has been made, the menu handler function
  215. simply opens the DialogueBox.  If the user then moves the mouse
  216. back over the menu, or clicks outside the dialogue box, it will
  217. be closed.
  218. <p>
  219. The code for opening a dialogue box off a menu selection would be:
  220. <pre>
  221.  
  222. void MyWin::menu (MenuItem items[])
  223.    {
  224.    switch (items[0])
  225.       {
  226.       case DETAILS:
  227.          {
  228.          PersonDetails details (task) ;
  229.          details.show() ;
  230.          task->sleep (&details) ;
  231.          if (!details.cancelled)
  232.             {
  233.             }
  234.