home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource5 / 301_01 / dcuwcu.doc < prev    next >
Encoding:
Text File  |  1989-12-30  |  13.2 KB  |  348 lines
  1.  
  2.  
  3.  
  4.               DCUWCU - A Simple Application Environment 
  5.  
  6.                            Mark A. Johnson
  7.  
  8.  
  9.  
  10.  
  11.      1.  Introduction
  12.  
  13.      I have used a mouse in computer user interfaces since 1981 
  14.      and feel it is the best and most convenient way to inform a 
  15.      computer program what you would like it to do.  I wanted to 
  16.      use a mouse in a number of programs for the PC and looked 
  17.      into a few application environments, such as Microsoft 
  18.      Windows and Digital Research GEM, but was disappointed to 
  19.      see how much complexity had to be mastered.  Most of the 
  20.      programs I had in mind needed only a mouse controlled 
  21.      cursor, a simple menu structure, and editable forms.  The 
  22.      resource construction sets, complex window management, and 
  23.      other overheads needed to write a simple application led me 
  24.      to write my own simple application environment based on 
  25.      Turbo C graphics routines and a public domain mouse 
  26.      interface.  My goal was to build a easy-to-use environment 
  27.      that provides a mouse-driven cursor, stacked pop-up menus, 
  28.      and forms that contain editable fields and a variety of 
  29.      selectable buttons.  The environment would keep track of 
  30.      what the user was doing, inform the application as needed, 
  31.      and clean up after itself.  An additional goal was to make 
  32.      it easy to port the environment to other machines that have 
  33.      a mouse, bitmap graphics, console I/O, and a simple timer.  
  34.      I have the same DCUWCU environment on my PC compatible and 
  35.      Atari ST, allowing me to easily move applications between 
  36.      systems.  
  37.  
  38.      2.  Operation
  39.  
  40.      A typical application begins with a blank screen, or 
  41.      suitable greeting, showing an arrow shaped cursor controlled
  42.      by the mouse.  Pressing the right mouse button displays a 
  43.      set of stacked pop-up menus.  While holding the right mouse 
  44.      button down, the user selects an item from the front-most 
  45.      menu or selects another menu and releases the right mouse 
  46.      button.  If a menu item was selected, then the application 
  47.      acts on the selection.  If another menu was selected, it is 
  48.      brought to the front of the menu stack ready for another 
  49.      round of menu item selection.  Pressing the left mouse 
  50.      button or the keyboard usually causes an application 
  51.      specific action.  Often such actions result in a form 
  52.      appearing on the screen to be filled out by the user.  When 
  53.      processing a form, all mouse and keyboard events are handled
  54.      by the environment.  Keyboard input is directed to the 
  55.      current editable field, denoted by the special input cursor.
  56.      A TAB moves the input cursor to the next editable field.  An
  57.      ESC (cancel) or ENTER (accept) ends form processing, 
  58.      returning data and control back to the application.  Some 
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.                                 - 2 -
  71.  
  72.  
  73.  
  74.      forms may contain small text labels, called form buttons, 
  75.      that are selected (or de-selected) by moving the cursor over
  76.      them and pressing the left mouse button.  There are three 
  77.      types of buttons: plain, radio, and exit.  A plain button is
  78.      a simple on/off switch.  A radio button is a one-of-many 
  79.      switch, much like the buttons on a car radio.  An exit 
  80.      button is like the plain button, but selecting it will cause
  81.      form processing to end.  
  82.  
  83.      The application environment also works equally well when no 
  84.      mouse is present by using the cursor keys to simulate mouse 
  85.      motion and the function keys F1 and F2 to simulate the left 
  86.      and right mouse buttons.  It takes one press of F2 to 
  87.      simulate depressing the right mouse button and another press
  88.      of F2 to release it.  A single press of the F1 button 
  89.      simulates the left mouse button.  
  90.  
  91.      3.  Application Interface
  92.  
  93.      An effort was made to keep the interface between application
  94.      and environment as simple as possible: strings are used to 
  95.      define forms and menus, pointers to variables are used to 
  96.      store values collected by forms, and calls to functions 
  97.      inform the application of user events such as menu selection
  98.      or mouse button clicks.  
  99.  
  100.      The application environment follows (and is named after) 
  101.      what is called "The Hollywood Principle," or "don't call us,
  102.      we'll call you." An application developer supplies four 
  103.      critical routines that are called when the application 
  104.      environment detects various user interface events.  
  105.  
  106.           start(argc, argv, envp) int argc; char **argv, **envp;
  107.      This is the initialization routine called immediately after 
  108.      the graphics interface is initialized but before the 
  109.      environment is completely started.  It is passed the same 
  110.      arguments that are normally passed to a C main() routine.  
  111.      The start() routine usually initializes the application and 
  112.      creates the menu stack using repeated calls to add_menu().  
  113.  
  114.           menu(m, i)
  115.      The menu() routine is called whenever a menu selection is 
  116.      made.  The application environment supports a stack of 
  117.      pop-up menus.  Any number of menus can be supported, 
  118.      although usually only two or three are active at any one 
  119.      time to minimize interface complexity (see menu_state() 
  120.      below).  The m argument identifies which menu was selected.
  121.      When the menu was first declareed (see add_menu()), the 
  122.      application provides a value that identifies the menu.  This
  123.      same identifer value is passed back to the application when 
  124.      a menu is selected.  The i argument specifies which menu 
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.                                 - 3 -
  137.  
  138.  
  139.  
  140.      item was selected with a value of 1 meaning the first item, 
  141.      etc.  
  142.  
  143.           button(b, x, y)
  144.      The button() routine is called when a user mouse button is 
  145.      pressed.  The right mouse button is reserved for menu 
  146.      manipulation, all others are passed to the application.  The
  147.      b argument is the button number (usually 1) and the x and y 
  148.      arguments are the mouse coordinates when the button was 
  149.      pressed.  
  150.  
  151.           keyboard(key)
  152.      The keyboard() routine is called whenever a console key is 
  153.      struck.  The character typed by the user is contained in the
  154.      single argument.  
  155.  
  156.           timer(t)
  157.      The (optional) timer() routine is called whenever a 
  158.      application requested timer expires.  When the timer is 
  159.      requested, a value identifying the timer is passed to the 
  160.      application environment.  The same identifer value is passed
  161.      back to the application in the t argument when the timer 
  162.      expires.  
  163.  
  164.      4.  Environment Interface
  165.  
  166.      There are some basic routines provided by the application 
  167.      environment that an application can call for control and 
  168.      service.  
  169.  
  170.           finish()
  171.      The finish() routine is called whenever the application is 
  172.      done and the program must exit.  
  173.  
  174.           add_menu(m, mdef) char *mdef;
  175.      The add_menu() routine adds a menu to the current set of 
  176.      pop-up menus maintained by the environment.  An application 
  177.      typically initializes all its menus from the start() 
  178.      routine.  The m argument is remembered by the environment 
  179.      and passed back to the application when a menu selection is 
  180.      made.  The mdef argument is a string that defines the menu.
  181.      For example, add_menu(1, "Main:About|Help|Quit") defines a 
  182.      menu identified as menu 1, titled Main, and with three 
  183.      items: About, Help, and Quit.  
  184.  
  185.           menu_state(m, on)
  186.      The menu_state() routine allows the application to activate 
  187.      or de-activate a particular menu.  The m argument refers to 
  188.      the menu defined with a previous add_menu() call.  The on 
  189.      argument should be set to 1 to activate or 0 to deactivate 
  190.      the menu.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.                                 - 4 -
  203.  
  204.  
  205.  
  206.  
  207.           menu_item(m, i, str) char *str;
  208.      The menu_item() routine is used to change the name of a 
  209.      particular menu item.  For example, suppose a drawing 
  210.      program can turn a grid on and off.  The application might 
  211.      have a menu item called "Grid" when no grid is shown and 
  212.      change it to "No Grid" using menu_item() when the grid is 
  213.      shown.  
  214.  
  215.           mouse_state(on)
  216.      The mouse_state() routine will activate or deactivate the 
  217.      mouse driven cursor.  The on variable should be set to 1 to 
  218.      show the mouse and 0 to hide it.  
  219.  
  220.           mouse_shape(type, bits, hotx, hoty) char *bits;
  221.      The application can control the shape of the cursor with the
  222.      mouse_shape() routine.  There are two built in forms: arrow 
  223.      and cross.  A type value of 0 and 1 specify arrow and cross,
  224.      respectively.  A type value of 3 allows the user to specify 
  225.      a custom designed mouse cursor.  The bits argument is a 
  226.      pointer to an eight byte character array containing the 
  227.      mouse bitmap (8 x 8 bits).  The hotx and hoty arguments 
  228.      specify which bit in the bitmap is considered the hotspot of
  229.      the cursor.  For example, the cross form has a hotspot of 
  230.      hotx=hoty=3, which is the center of the 8 x 8 bitmap.  
  231.  
  232.           add_timer(t, wait) long wait;
  233.      Many applications, especially games, require some sense of 
  234.      the passage of time.  Using the add_timer() routine, the 
  235.      application can arrange for the timer() routine to be called
  236.      after some time has elapsed.  The application's timer() 
  237.      routine can do such things as blank the screen if no 
  238.      activity has taken place for many minutes or move sprite's 
  239.      around the screen after a few tenths of a second.  The t 
  240.      argument identifies a particular timer and is passed back to
  241.      the application when the timer expires.  The wait argument 
  242.      specifies the needed delay in milliseconds (e.g.  wait=1000L
  243.      is a delay of one second).  
  244.  
  245.           form(def, argptr1, ...) char *def;
  246.      The form() routine displays a form on the screen, collects 
  247.      data from the user, and deposits it in the variables pointed
  248.      to by the argptr parameters.  this routine is somewhat 
  249.      similar to scanf().  The form definition string defines a 
  250.      number of fields.  Let's look at an example form definition.
  251.  
  252.      "  Name: %15s |Number: %5d |%[male|female] %[over 55]|   %{ok}"
  253.  
  254.      This form definition would result in the following being 
  255.      displayed in the middle of the screen surrounded by a 
  256.      rectangle.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.                                 - 5 -
  269.  
  270.  
  271.  
  272.  
  273.                          Name: _______________
  274.                        Number: _____
  275.                        [male|female] [over 55]
  276.                           {ok}
  277.  
  278.      Most of the text in the definition string is used as titles.
  279.      A "|" signifies the beginning of a new line in the form.  A 
  280.      data field begins with a "%" and is associated with a 
  281.      particular variable.  There are five types of data fields.  
  282.      (For the examples that follow, assume the following 
  283.      declarations occur before the call to form(): char c, 
  284.      buf[11]; int x;).  
  285.  
  286.            Field     Example     Argument  Values        
  287.           ------------------------------------------
  288.            text   %10s           &buf[0]  string    
  289.            number %5d            &x       integer   
  290.            button %[abc]         &c       0 or 1    
  291.            radio  %[abc:def:ghi] &c       0, 1, ... 
  292.            exit   %{ok}          &c       0 or 1    
  293.  
  294.      If a character pointer fdef points at the string described 
  295.      above, the following code fragment is a correct use of the 
  296.      form() routine.  
  297.  
  298.           char name[16], m_or_f = 0, over_55 = 1, ok = 0;
  299.           int number;
  300.           if (form(fdef, name, &number, &m_or_f, &over_55, &ok)) {
  301.               /* do stuff with name, number, etc. */
  302.           }
  303.  
  304.      After filling out the form, if the user selects the {ok} 
  305.      button or hits ENTER, the form() routine returns a non-zero 
  306.      value and the data data values collected by the form and 
  307.      stored in the variables name, number, m_or_f, and over_55 
  308.      are processed further by the body of the if statement.  If 
  309.      the user struck the ESC key while filling out the form, then
  310.      form() would return zero and the processing would not take 
  311.      place.  
  312.  
  313.      5.  Conclusion
  314.  
  315.      I have used the "Hollywood Principle" design model for a 
  316.      number of projects and have found it to shorten development 
  317.      time and result in a robust application.  The mouse is a 
  318.      unique and powerful user interface device, and when coupled 
  319.      with pop-up windows and forms, provides the user a clean, 
  320.      uncluttered operation.  I would like to acknowledge the 
  321.      designers of the many mouse-based user interfaces I have 
  322.      used in the past, such as the Apple Macintosh, Microsoft 
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.                                 - 6 -
  335.  
  336.  
  337.  
  338.      Windows, DR/Atari GEM, but most significantly the Xerox Mesa
  339.      Development System, for the inspiration in building this 
  340.      simple application environment.  
  341.  
  342.  
  343.  
  344.                                    Mark A. Johnson
  345.                                    5315 Holmes Place
  346.                                    Boulder, CO 80303
  347.                                    303-442-1812
  348.