
















                            PICASSO _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l


                          (_V_e_r_s_i_o_n _1._0 _J_u_l_y _1_5, _1_9_9_0)
























                        Computer Science Division - EECS
                            University of California
                               Berkeley, CA 94720

























                           PICASSO _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l|-
                          (_V_e_r_s_i_o_n _1._0 _J_u_l_y _1_5, _1_9_9_0)

                    _P_a_t_r_i_c_i_a _S_c_h_a_n_k, _J_o_e _K_o_n_s_t_a_n, _C_h_u_n_g _L_i_u
                 _L_a_w_r_e_n_c_e _A. _R_o_w_e, _S_t_e_v_e _S_e_i_t_z, _a_n_d _B_r_i_a_n _S_m_i_t_h

                        Computer Science Division - EECS
                            University of California
                               Berkeley, CA 94720



                                    _A_b_s_t_r_a_c_t


          PICASSO  is  an  object-oriented  graphical  user  interface
          development  system.   The  system  includes  an application
          framework, an interface toolkit, a constraint system, and  a
          persistent object interface to a relational database system.

          The  application  framework  includes  high-level   abstract
          objects (i.e., frames, forms, dialog boxes, and panels) that
          simplify the construction of  graphical  applications  which
          use  multiple  windows,  pulldown  menus,  dialog boxes, and
          electronic forms.  The toolkit contains a library of  prede-
          fined  interface widgets (e.g., buttons, menus, text fields,
          table fields,  graphics  fields,  image  fields,  etc.)  and
          geometry   managers   with   which  sophisticated  interface
          abstractions can be built.  The constraint system is used to
          bind   variables  to  widgets  and  to  implement  triggered
          behaviors.  The persistent object  database  interface  pro-
          vides an easy-to-use database interface.

          PICASSO is written in Common Lisp and the Common Lisp Object
          System and runs on the X Window System.











          ____________________
             |- This research was supported  by  the  National  Science
          Foundation (Grants DCR-8507256 and MIP-8715557), 3M Corpora-
          tion, and Siemens Corporation.













                                                          INTRODUCTION


                                       1
                                  INTRODUCTION

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         PICASSO is a graphical user  interface  (GUI)
                         development  system  for application program-
                         mers.  The PICASSO application framework pro-
                         vides high-level abstractions including modal
                         dialog boxes and non-modal frames and  panels
                         that  can  be  used to define an application.
                         These abstractions are similar to  procedures
                         and co-routines in a conventional programming
                         language procedures and  co-routines.   Local
                         variables  can  be  defined,  and they can be
                         called with parameters.

                         The toolkit contains a library of  predefined
                         high-level    abstractions   (e.g.   buttons,
                         scrollbars,  menus,  forms,  etc.),  geometry
                         managers,  and a constraint system.  The con-
                         straint system is used to bind program  vari-
                         ables  to  widgets,  to  implement  triggered
                         behaviors, and to implement multiple views of
                         data.

                         The system  is  implemented  in  Common  Lisp
                         using  the  Common Lisp Object System [Kee88]
                         and the CLX interface [ScL89] to the X Window
                         System [ScG86].

                         This chapter is organized as follows:

                         o+    What is PICASSO?

                         o+    Why use PICASSO?

                         o+    About this manual
          ____________________________________________________________________________________________________________________________________________________________________________________

          What is
          PICASSO?



                         PICASSO is a graphical user  interface  (GUI)
                         development system that includes an interface
                         toolkit and an  application  framework.   The
                         application   framework  provides  high-level
                         abstractions and other infrastructure to sup-
                         port the development of GUI applications.

                         The PICASSO framework  includes  five  object
                         types:   tools   (or   applications),  forms,
                         frames,  dialog  boxes,   and   panels.    An



          PICASSO Reference Manual                                 1-2







                                                          INTRODUCTION


                         _a_p_p_l_i_c_a_t_i_o_n  is  composed  of a collection of
                         frames, dialog boxes,  and  panels.   A  _f_o_r_m
                         contains  fields  through  which  data can be
                         displayed, entered, or edited by the user.  A
                         _f_r_a_m_e   specifies   the  primary  application
                         interface.  It contains a form and a menu  of
                         operations the user can execute. A _d_i_a_l_o_g _b_o_x
                         is a modal interface that solicits additional
                         arguments  for an operation or user confirma-
                         tion before executing  a  possibly  dangerous
                         operation  (e.g.,  deleting a file).  A _p_a_n_e_l
                         is  a  nonmodal  dialog  box  that  typically
                         presents  an  alternative  view  of data in a
                         frame or another panel.

                         The PICASSO toolkit  contains  a  library  of
                         predefined interface abstractions (e.g., but-
                         tons,  scrollbars,   menus,   forms,   etc.),
                         geometry managers, and a constraint system.

                         PICASSO is an object-oriented  system  imple-
                         mented in Common Lisp using the X Window Sys-
                         tem [ScG86].   The  toolkit,  framework,  and
                         user  applications  are implemented as Common
                         Lisp Object System (CLOS) objects [Kee88].  A
                         CLOS class is defined for each type of frame-
                         work object (e.g., application, frame,  form,
                         dialog  box,  and panel).  Instances of these
                         classes are called  PICASSO  objects  (PO's).
                         Each  PO  type  has a different visualization
                         and control regime.  The toolkit widgets that
                         implement   the   visualization  and  control
                         (e.g., title bars,  buttons  and  menus)  are
                         automatically generated when a PO is created.
                         Examples of a number of library PO's, as well
                         as several complete PICASSO applications, are
                         given in Chapter 18.

                         PO's are stored in an external  database  and
                         loaded  into  the  application  when  needed.
                         They are  shared  by  different  applications
                         because  the  database  is  shared.  Commonly
                         used PO's (e.g., a file directory browser and
                         an  error message dialog box) are provided to
                         maintain interface consistency  between  dif-
                         ferent applications.

                         A direct manipulation interface  builder  for
                         defining  POs is currently being developed to
                         help  application  programmers   create   and
                         modify  applications.   Forms will be defined
                         by  selecting  widgets  from  a  palette  and



          PICASSO Reference Manual                                 1-3







                                                          INTRODUCTION


                         placing  them, with the mouse, at the desired
                         location in a window.  Field attributes (e.g.
                         border, default values, etc.) will be changed
                         interactively.  Similar  interfaces  will  be
                         provided  to  define other PO types and code.
                         The toolkit and  interface  builder  will  be
                         extensible  so  that  developers  can add new
                         interface abstractions to the system.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Why Use
          PICASSO



                         PICASSO provides capabilities that are  simi-
                         lar to other application frameworks including
                         Garnet [Mye89],  InterViews  [Lin89],  MacApp
                         [Sch86], and Smalltalk [Gol83].

                         PICASSO provides a rich library of predefined
                         interface  widgets  and  gadgets for creating
                         abstractions   such   as   buttons,    menus,
                         scrollbars,  forms,  tables, images, etc., as
                         described in Chapters 9 through  17  of  this
                         manual.  These predefined widgets and gadgets
                         simplify coding because they can  be  reused.
                         PICASSO  also provides a high-level framework
                         for constructing applications, which  simpli-
                         fies application building by providing appli-
                         cation templates that can  be  filled  in  by
                         developers.
          ____________________________________________________________________________________________________________________________________________________________________________________

          About this
          manual



                         This reference manual describes  the  PICASSO
                         toolkit,  framework,  and  programming model.
                         The  programming  constructs  described   are
                         shown as extensions to Lisp.  Most users will
                         not see these textual specifications  because
                         a  direct  manipulation  interface builder is
                         being developed to create and modify applica-
                         tions.    Additional  information  about  the
                         application framework  [RKS90]  and  creating
                         widgets [Sei90] is also available.

                         The remainder of  this  reference  manual  is
                         organized  in  3 sections.  The first section
                         describes lower level details of the  PICASSO
                         system.   This  section  discusses the window
                         system (Chapter 2), the PICASSO  abstractions
                         for  commonly  used  X resources (Chapter 3),
                         and the event handling  mechanism  as  imple-
                         mented in PICASSO (Chapter 4).





          PICASSO Reference Manual                                 1-4







                                                          INTRODUCTION


                         The second  section  describes  higher  level
                         abstractions  used  in  the  PICASSO  system.
                         This   section   describes   the   high-level
                         abstractions provided by the PICASSO Applica-
                         tion Framework (Chapter 5), the PICASSO  data
                         model (Chapter 6), the data management facil-
                         ities  (Chapter  7),  and  grouping   PICASSO
                         objects  into  collections,  using a geometry
                         manager to control their  display  attributes
                         (Chapter 8).

                         The  third  section  manual   describes   the
                         PICASSO  toolkit  and the widgets and gadgets
                         implemented in it. In particular, the section
                         discusses  widgets  and  gadgets (Chapter 9),
                         displaying and  editing  text  (Chapter  10),
                         button  types  (Chapter  11), controlling the
                         view of PO's (Chapter 12), displaying  images
                         (Chapter  13), menus (Chapter 14), displaying
                         tables  (Chapter   15),   advanced   graphics
                         (Chapter  16), miscellaneous widgets (Chapter
                         17) library PO's and  examples  of  completed
                         applications (Chapter 18).

                         _____________________________________________

          NOTATION


                         The following notation conventions  are  used
                         in this manual:

                     macro-name

                                                               [_M_a_c_r_o]
                         { _a_r_g_u_m_e_n_t }*
                         The macro  macro-name  _i_s  _c_a_l_l_e_d  _w_i_t_h  _e_a_c_h
                         _a_r_g_u_m_e_n_t _l_i_s_t_e_d.

                     function-name

                                                            [_F_u_n_c_t_i_o_n]
                         { _a_r_g_u_m_e_n_t }*
                         &key
                         { (_k_e_y_w_o_r_d _d_e_f_a_u_l_t ) }*
                         &allow-other-keys
                         The function  function-name  is  called  with
                         each  _a_r_g_u_m_e_n_t  listed. Keyword arguments may
                         also be specified (the default value  of  the
                         key  is default), _a_n_d &allow-other-keys _i_n_d_i_-
                         _c_a_t_e_s _t_h_a_t _a_d_d_i_t_i_o_n_a_l  _k_e_y_s  (_i._e.,  _u_n_l_i_s_t_e_d
                         _i_n_h_e_r_i_t_e_d _k_e_y_s) _w_i_l_l _b_e _a_c_c_e_p_t_e_d _b_y _t_h_e _f_u_n_c_-
                         _t_i_o_n.

                     method-name

                                                              [_M_e_t_h_o_d]
                         { _a_r_g_u_m_e_n_t | (_a_r_g_u_m_e_n_t _a_r_g_u_m_e_n_t-_t_y_p_e) }*
                         The method method-name _i_s  _c_a_l_l_e_d  _w_i_t_h  _e_a_c_h
                         _a_r_g_u_m_e_n_t  _l_i_s_t_e_d.   _T_h_e  _a_r_g_u_m_e_n_t-_t_y_p_e _s_h_o_u_l_d



          PICASSO Reference Manual                                 1-5







                                                          INTRODUCTION


                         _n_o_t _b_e _e_x_p_l_i_c_i_t_l_y _s_p_e_c_i_f_i_e_d _i_n _t_h_e _c_a_l_l.

                     attribute-name

                                              [_R_e_a_d_e_r|_W_r_i_t_e_r|_A_c_c_e_s_s_o_r]
                         { _a_r_g_u_m_e_n_t | (_a_r_g_u_m_e_n_t _a_r_g_u_m_e_n_t-_t_y_p_e) }*
                         A special case of the  method-name  _n_o_t_a_t_i_o_n.
                         _A_t_t_r_i_b_u_t_e_s _m_a_y _h_a_v_e _R_e_a_d_e_r, _W_r_i_t_e_r, _o_r _A_c_c_e_s_-
                         _s_o_r _m_e_t_h_o_d_s. _Y_o_u _c_a_n  _u_s_e  _a_t_t_r_i_b_u_t_e-_n_a_m_e  _t_o
                         _q_u_e_r_y  _a _R_e_a_d_e_r _a_t_t_r_i_b_u_t_e _f_o_r _t_h_e _v_a_l_u_e _a_s_s_o_-
                         _c_i_a_t_e_d _w_i_t_h _i_t, _b_u_t  _y_o_u  _c_a_n_n_o_t  _c_h_a_n_g_e  _t_h_e
                         _v_a_l_u_e  _o_f  _R_e_a_d_e_r  _a_t_t_r_i_b_u_t_e_s.  _W_r_i_t_e_r _a_t_t_r_i_-
                         _b_u_t_e_s _c_a_n _b_e _s_e_t_f'_d; _i._e., _u_s_e


                          (_s_e_t_f (_a_t_t_r_i_b_u_t_e-_n_a_m_e <_o_b_j_e_c_t>) <_v_a_l_u_e>)


                         _t_o _c_h_a_n_g_e _t_h_e _a_t_t_r_i_b_u_t_e _v_a_l_u_e.  _H_o_w_e_v_e_r,  _y_o_u
                         _c_a_n  _n_o_t  _q_u_e_r_y  _a  _W_r_i_t_e_r  _a_t_t_r_i_b_u_t_e _f_o_r _t_h_e
                         _v_a_l_u_e _a_s_s_o_c_i_a_t_e_d _w_i_t_h  _i_t.   _A_c_c_e_s_s_o_r  _a_t_t_r_i_-
                         _b_u_t_e_s _c_a_n _b_e _b_o_t_h _r_e_a_d _a_n_d _s_e_t.



































          PICASSO Reference Manual                                 1-6







                                                               WINDOWS


                                               2
                                            WINDOWS

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         Windows are CLOS objects  that  represent  an
                         area  of the screen.  In PICASSO, unlike some
                         other toolkits, there  is  _n_o_t  a  one-to-one
                         correspondence between windows in the toolkit
                         and X windows in  the  server.   The  various
                         window  manipulation  functions  provided  by
                         most windowing systems, such as changing  the
                         size of a window, the background and the win-
                         dow border, are implemented as _m_e_t_h_o_d_s in the
                         PICASSO  toolkit.   When  appropriate,  subc-
                         lasses forward the request to the X server.

                         Gadgets are a subclass of  windows  that,  by
                         definition,  have no X server representation.
                         They can still  be  manipulated  as  windows,
                         however,  and  the appropriate X server calls
                         are  automatically  generated.   Gadgets  are
                         typically  used as flexible, lightweight win-
                         dows for output only.

                         Synthetic    gadgets,    sometimes     called
                         ``synths'',  are even lighter weight abstrac-
                         tions for output  purposes.   Unlike  windows
                         and  gadgets,  synthetic  gadgets  are  not a
                         defined class.  As a  result,  they  are  not
                         quite as flexible as gadgets, but are consid-
                         erably faster and smaller.

                         Windows, gadgets, and synthetic gadgets  form
                         the  base  on  which  all PICASSO widgets are
                         created.  Widgets are  input/output  abstrac-
                         tions,  and  are defined as a direct subclass
                         of opaque windows.  The  class  hierarchy  at
                         this point looks like this:


                                       window
                                      /     (
                                  gadget     x-window
                                               (
                                               opaque-window
                                                  (
                                                  widget






          PICASSO Reference Manual                                 2-7







                                                               WINDOWS


                         All widgets and  gadgets  share  some  common
                         behavior.  See Chapter 9 on widgets and gadg-
                         ets for more detail about the creation, mani-
                         pulation, and common behaviors of widgets and
                         gadgets.  This chapter is organized  as  fol-
                         lows:

                         o+    Windows

                         o+    Window Management

                         o+    X-windows

                         o+    Opaque windows
          ____________________________________________________________________________________________________________________________________________________________________________________

          Windows


                         The window class is the  top-level  class  in
                         PICASSO,  and  therefore does not inherit any
                         of  its  keywords  from  any  other   PICASSO
                         classes.   The following function can be used
                         to create windows.

                     make-window

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_d_o_c "")
                         (name "A Window")
                         (_v_a_l_u_e _n_i_l)
                         (status :exposed)
                         (_m_f-_s_e_l_e_c_t_a_b_l_e-_w_i_d_g_e_t _t)
                         ;; Information to support the window hierarchy
                         (parent nil)
                         (display (current_display))
                         (screen (current_screen))
                         (lexical-parent nil)
                         ;; Information about window geometry
                         (x-offset 0)
                         (y-offset 0)
                         (width 1)
                         (height 1)
                         (location nil)
                         (size nil)
                         (region nil)
                         ;; Information about window resizing
                         (base-width 1)
                         (base-height 1)
                         (width-increment 1)
                         (height-increment 1)
                         (width-height-ratio nil)
                         (increment-size nil)
                         (base-size nil)
                         (resize-hint nil)



          PICASSO Reference Manual                                 2-8







                                                               WINDOWS


                         (geom-spec nil)
                         ;; Drawing information about a window
                         (font nil)
                         (background "white")
                         (inverted-background "black")
                         (dimmed-background "white")
                         (foreground "black")
                         (dimmed-foreground "gray50")
                         (inverted-foreground "white")
                         (dimmed nil)
                         (inverted nil)
                         (colormap (colormap (root-window screen)))
                         (repaint-flag t)
                         ;; Label information
                         (label nil)
                         (label-type :left)
                         (label-x 0)
                         (label-y 0)
                         (label-font nil)
                         (label-attributes nil)
                         ;; Border information
                         (border-width 0)
                         (border-type nil)
                         (border-attributes nil)

                         _____________________________________________

          ATTRIBUTES



                     doc

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         A documentation string  associated  with  the
                         window.

                     name

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         A name string  associated  with  the  window.
                         Used primarily for debugging.

                     value

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The value of the window, of type t.

                     status

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The current window state,  of  type  symbolP.
                         One  of  :concealed,  :exposed,  _o_r :_p_e_n_d_i_n_g,
                         default :exposed.

                     mf-selectable-widget

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         Whether not the window can be "selected" in a



          PICASSO Reference Manual                                 2-9







                                                               WINDOWS


                         table (t _o_r _n_i_l).  Of type atom, _d_e_f_a_u_l_t _t.

                         _____________________________________________

          HIERARCHY
          ATTRIBUTES



                         Every  attached  window  is  associated  with
                         exactly  one window in the server, called the
                         server-window.  Each server window is associ-
                         ated  with a particular screen, which in turn
                         is associated with a  particular  display  in
                         the server.

                     display

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The PICASSO display of the  window.  Of  type
                         display, default (current_display).

                     lexical-parent

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The lexical parent of the  window.   Of  type
                         window, _d_e_f_a_u_l_t _n_i_l.

                     parent

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The parent of the  window.  Of  type  window,
                         _d_e_f_a_u_l_t _n_i_l.

                     res

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The  CLX  resource  representing  the  server
                         representation  of  the  window  (nil  _i_f _n_o_t
                         _a_t_t_a_c_h_e_d). _O_f _t_y_p_e _v_e_c_t_o_r, _d_e_f_a_u_l_t _n_i_l.

                     screen

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The PICASSO screen of  the  window.  Of  type
                         screen, default (current_screen).

                         _____________________________________________

          GEOMETRY
          ATTRIBUTES




                     x-offset

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The x-coordinate (in pixels)  of  the  window
                         relative   to  the  top-left  corner  of  the
                         window's parent. Of type _i_n_t_e_g_e_r, default 0.

                     y-offset

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The y-coordinate (in pixels)  of  the  window
                         relative   to  the  top-left  corner  of  the



          PICASSO Reference Manual                                2-10







                                                               WINDOWS


                         window's parent.  Of type _i_n_t_e_g_e_r, default 0.

                     location

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         A list ( _x-_o_f_f_s_e_t _y-_o_f_f_s_e_t ) _o_f _t_h_e  _w_i_n_d_o_w'_s
                         _x-_o_f_f_s_e_t _a_n_d _y-_o_f_f_s_e_t.

                     width

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The width of the window in pixels.   Of  type
                         _i_n_t_e_g_e_r, default 1.

                     height

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The height of the window in pixels.  Of  type
                         _i_n_t_e_g_e_r, default 1.

                     size

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         A list ( _w_i_d_t_h _h_e_i_g_h_t ) _o_f _t_h_e _w_i_n_d_o_w'_s _w_i_d_t_h
                         _a_n_d _h_e_i_g_h_t.

                     region

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         A list ( _x-_o_f_f_s_e_t _y-_o_f_f_s_e_t _w_i_d_t_h _h_e_i_g_h_t )  _o_f
                         _t_h_e  _w_i_n_d_o_w'_s  _x-_o_f_f_s_e_t,  _y-_o_f_f_s_e_t, _w_i_d_t_h _a_n_d
                         _h_e_i_g_h_t.

                         _____________________________________________

          RESIZE
          ATTRIBUTES




                     geom-spec

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         Various instructions concerning the  geometry
                         of  the  window  that  the  window's geometry
                         manager should look  at  (geom-spec  _a_n_d  _t_h_e
                         _g_e_o_m_e_t_r_y _m_a_n_a_g_e_r _a_r_e _d_i_s_c_u_s_s_e_d _i_n _t_h_e Collec-
                         tions _c_h_a_p_t_e_r).  _A_n_y _t_y_p_e, _d_e_f_a_u_l_t _n_i_l.

                     base-width

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The smallest desirable width of  the  window.
                         Of type _i_n_t_e_g_e_r, default 1.

                     base-height

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The smallest desirable height of the  window.
                         Of type _i_n_t_e_g_e_r, default 1.

                     base-size

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)



          PICASSO Reference Manual                                2-11







                                                               WINDOWS


                         A list (  _b_a_s_e-_w_i_d_t_h  _b_a_s_e-_h_e_i_g_h_t  )  _o_f  _t_h_e
                         _s_m_a_l_l_e_s_t _d_e_s_i_r_a_b_l_e _s_i_z_e _o_f _t_h_e _w_i_n_d_o_w.

                     width-increment

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The best amount by  which  to  increment  the
                         width  of a window.  Of type _i_n_t_e_g_e_r, default
                         1.

                     height-increment

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The best amount by  which  to  increment  the
                         height of a window.  Of type _i_n_t_e_g_e_r, default
                         1.

                     increment-size

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         A list ( _w_i_d_t_h-_i_n_c_r_e_m_e_n_t  _h_e_i_g_h_t-_i_n_c_r_e_m_e_n_t  )
                         _o_f _s_i_z_e _i_n_c_r_e_m_e_n_t_s _f_o_r _t_h_e _w_i_n_d_o_w.

                     width-height-ratio

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The best ratio for the  width/height  of  the
                         window.  Of type _f_l_o_a_t, default nil.

                     resize-hint

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         A  list  of  the   base-width,   base-height,
                         width-increment,     height-increment,    and
                         width-height-ratio.  Default nil.

                         _____________________________________________

          DRAWING
          ATTRIBUTES




                     inverted

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         When a window is inverted, its background and
                         inverted-background   are  swapped,  and  its
                         foreground   and   inverted-foreground    are
                         swapped.  Of type (t _o_r _n_i_l), default nil.

                     dimmed

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         When a window is dimmed, its  background  and
                         dimmed-background  are swapped, and its fore-
                         ground and dimmed-foreground are swapped.  Of
                         type (t _o_r _n_i_l), default nil.

                     background

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The background paint of the window,  of  type



          PICASSO Reference Manual                                2-12







                                                               WINDOWS


                         (member  (string  paint tile :parent-relative
                         nil)).  _I_n _g_e_n_e_r_a_l _t_h_e  _s_e_r_v_e_r  _a_u_t_o_m_a_t_i_c_a_l_l_y
                         _f_i_l_l_s _i_n _e_x_p_o_s_e_d _a_r_e_a_s _o_f _t_h_e _w_i_n_d_o_w _w_i_t_h _t_h_e
                         _w_i_n_d_o_w'_s _b_a_c_k_g_r_o_u_n_d when they are made  visi-
                         ble  after  being  occluded or concealed.  If
                         background is nil, _t_h_e _s_e_r_v_e_r _w_i_l_l _n_o_t _m_o_d_i_f_y
                         _e_x_p_o_s_e_d  _a_r_e_a_s.   _I_f  _b_a_c_k_g_r_o_u_n_d  _i_s :_p_a_r_e_n_t-
                         _r_e_l_a_t_i_v_e, the exposed areas  are  filled  in,
                         but  with  the  color/pixmap  of the window's
                         parent.  The paint resource is  automatically
                         created  (if  a  string  _i_s _s_p_e_c_i_f_i_e_d) _a_n_d/_o_r
                         _a_t_t_a_c_h_e_d _a_s _n_e_c_e_s_s_a_r_y.

                     inverted-background

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The background to  use  when  the  window  is
                         inverted.  Of type (member (string paint tile
                         nil)).  _T_h_e _p_a_i_n_t _r_e_s_o_u_r_c_e  _i_s  _a_u_t_o_m_a_t_i_c_a_l_l_y
                         _c_r_e_a_t_e_d  (_i_f  _a  _s_t_r_i_n_g  is specified) and/or
                         attached as necessary.

                     dimmed-background

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The background to  use  when  the  window  is
                         dimmed.   Of  type (member (string paint tile
                         nil)).  _T_h_e _p_a_i_n_t _r_e_s_o_u_r_c_e  _i_s  _a_u_t_o_m_a_t_i_c_a_l_l_y
                         _c_r_e_a_t_e_d  (_i_f  _a  _s_t_r_i_n_g  is specified) and/or
                         attached as necessary.

                     foreground

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The foreground to use in  graphic  operations
                         when the window is inverted.  Of type (member
                         (paint string tile nil)).  _T_h_e _p_a_i_n_t _r_e_s_o_u_r_c_e
                         _i_s  _a_u_t_o_m_a_t_i_c_a_l_l_y  _c_r_e_a_t_e_d  (_i_f  _a  _s_t_r_i_n_g is
                         specified) and/or attached as necessary.

                     inverted-foreground

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The foreground to use in  graphic  operations
                         when the window is inverted.  Of type (member
                         (paint string tile nil)).  _T_h_e _p_a_i_n_t _r_e_s_o_u_r_c_e
                         _i_s  _a_u_t_o_m_a_t_i_c_a_l_l_y  _c_r_e_a_t_e_d  (_i_f  _a  _s_t_r_i_n_g is
                         specified) and/or attached as necessary.

                     dimmed-foreground

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The foreground to use in  graphic  operations
                         when  the  window is dimmed.  Of type (member
                         (paint string tile nil)).  _T_h_e _p_a_i_n_t _r_e_s_o_u_r_c_e
                         _i_s  _a_u_t_o_m_a_t_i_c_a_l_l_y  _c_r_e_a_t_e_d  (_i_f  _a  _s_t_r_i_n_g is




          PICASSO Reference Manual                                2-13







                                                               WINDOWS


                         specified) and/or attached as necessary.

                     font

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The font of the window.  Every window  has  a
                         font which may be used in graphic operations.
                         Of type (member  `(string  font  nil)).   _T_h_e
                         _r_e_s_o_u_r_c_e   _i_s  _a_u_t_o_m_a_t_i_c_a_l_l_y  _c_r_e_a_t_e_d  (_i_f  _a
                         _s_t_r_i_n_g  is  specified)  and/or  attached  (if
                         font) _a_s _n_e_c_e_s_s_a_r_y.

                     repaint-flag

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         If set to t, _t_h_e _w_i_n_d_o_w _w_i_l_l _n_o_t _b_e _a_u_t_o_m_a_t_i_-
                         _c_a_l_l_y  _d_r_a_w_n  _a_s  _a _r_e_s_u_l_t _o_f _e_i_t_h_e_r _i_n_t_e_r_n_a_l
                         _e_v_e_n_t_s _o_r _a _c_a_l_l _t_o _r_e_p_a_i_n_t.

                     colormap

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         All windows have  a  colormap  which  can  be
                         read,  of  type  colormap,  _d_e_f_a_u_l_t (_c_o_l_o_r_m_a_p
                         (_r_o_o_t-_w_i_n_d_o_w _s_c_r_e_e_n)).

                         _____________________________________________

          LABEL
          ATTRIBUTES




                     label

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The label to draw for the window.  Any  type,
                         default nil.

                     label-type

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The type of label to use for the window.  The
                         predefined  label-types  include  nil, :_l_e_f_t,
                         :bottom,  _a_n_d  :_f_r_a_m_e.   Of   type   keyword,
                         _d_e_f_a_u_l_t :_l_e_f_t.

                     label-x

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The x-coordinate of the label relative to  an
                         origin.   The  origin  is  dependent  on  the
                         label-type of the window.  Of  type  integer,
                         _d_e_f_a_u_l_t _0.

                     label-y

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The y-coordinate of the label relative to  an
                         origin.   The  origin  is  dependent  on  the
                         label-type of the window.  Of  type  integer,




          PICASSO Reference Manual                                2-14







                                                               WINDOWS


                         _d_e_f_a_u_l_t _0.

                     label-position

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The position of the window label, which is  a
                         list  of  (  _l_a_b_e_l-_x _l_a_b_e_l-_y ). _O_f _t_y_p_e _l_i_s_t,
                         _d_e_f_a_u_l_t _n_i_l.

                     label-attributes

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         A list of attributes  concerning  the  label,
                         for example


                          (:foreground "red" :font "8x13" :italicized t)


                         Which label-attributes to specify, if any, is
                         dependent  on  the  label-type of the window.
                         Of type list, _d_e_f_a_u_l_t _n_i_l.

                     label-font

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The font to use in drawing the label  of  the
                         window.

                         _____________________________________________

          BORDER
          ATTRIBUTES




                     border-type

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The type of border to  use  for  the  window.
                         The predefined border-types include (nil :box
                         :frame :black-frame  :inset  :standout  :sha-
                         dow).  _O_f _t_y_p_e _k_e_y_w_o_r_d, default nil.

                     border-attributes

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         A list of attributes  concerning  the  border
                         (e.g.  (:foreground  "red").   _W_h_i_c_h  _b_o_r_d_e_r-
                         _a_t_t_r_i_b_u_t_e_s _t_o _s_p_e_c_i_f_y, _i_f _a_n_y,  _i_s  _d_e_p_e_n_d_e_n_t
                         _o_n _t_h_e _b_o_r_d_e_r-_t_y_p_e _o_f _t_h_e _w_i_n_d_o_w.

                     border-width

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         The dimensions of the  border  to  be  drawn.
                         Some  border-types allow borders to have non-
                         uniform dimensions.  Therefore,  border-width
                         may be either a list with four elements or an
                         integer value (e.g., a shadow-border may have
                         border  width  (0 0 10 10)).  _O_f _t_y_p_e _i_n_t_e_g_e_r



          PICASSO Reference Manual                                2-15







                                                               WINDOWS


                         or 4 element list, default 0.

                     gray

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         If t, _s_e_t_s  _t_h_e  _b_o_r_d_e_r-_t_y_p_e  to  :frame  _a_n_d
                         _l_a_b_e_l-_t_y_p_e to :frame.

                         _____________________________________________

          WINDOW
          OPERATION




                     clear

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         &key
                         (_i_g_n_o_r_e _n_i_l)
                         &allow-other-keys
                         Repaint window with background of window.

                     clear-region

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         _x
                         _y
                         _w_i_d_t_h
                         _h_e_i_g_h_t
                         Clear the region of the window  specified  by
                         width and height and beginning at the x and y
                         offsets of window.

                     destroy

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         Destroy window.

                     dim

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         Toggle dim of window.

                     invert

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         Toggle inversion of window.

                     move

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         _x-_o_f_f_s_e_t
                         _y-_o_f_f_s_e_t
                         Set the x and y offsets of the window.

                     reshape

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         _x-_o_f_f_s_e_t
                         _y-_o_f_f_s_e_t
                         _w_i_d_t_h
                         _h_e_i_g_h_t



          PICASSO Reference Manual                                2-16







                                                               WINDOWS


                         Set the x and y offsets, and width and height
                         of the window.

                     resize

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         _w_i_d_t_h
                         _h_e_i_g_h_t
                         Set the width and height of the window.

                     repaint

                                                            [_F_u_n_c_t_i_o_n]
                         _w_i_n_d_o_w
                         &key
                         (_c_l_e_a_r _t)
                         Redraw contents of window.

                     do-repaint

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         Redraw contents of window.

                     repaint-region

                                                            [_F_u_n_c_t_i_o_n]
                         _w_i_n_d_o_w
                         _x
                         _y
                         _w
                         _h
                         &key
                         (_c_l_e_a_r _t)
                         Redraw the specified region of the window.

                         _____________________________________________

          DEBUGGING



                     pt

                                                            [_F_u_n_c_t_i_o_n]
                         _r_o_o_t
                         &optional
                         (_l_e_v_e_l _0)
                         Prints out the geometry information about the
                         window and its children.

                     locate-window

                                                            [_F_u_n_c_t_i_o_n]
                         &optional
                         (_d_i_s_p_l_a_y (_c_u_r_r_e_n_t-_d_i_s_p_l_a_y))
                         Waits for the user to  click  the  mouse  and
                         returns  the  PICASSO  x-window  in which the
                         mouse was clicked.

                         _____________________________________________

          WINDOW
          SUMMARY








          PICASSO Reference Manual                                2-17







                                                               WINDOWS



                   _____________________________________________________________
                    Reader Methods      Setf Methods        Misc
                   __________________________________________________________________________________________________________________________
                    background          background          clear
                    base-height         base-height         clear-region
                    base-size           base-size           destroy
                    base-width          base-width          dim
                    border-attributes   border-attributes   invert
                    border-type         border-font         move
                    border-width        border-width        pt
                    colormap            colormap            resize
                    dimmed              dimmed              repaint, do-repaint
                    dimmed-background   dimmed-background   repaint-region
                    dimmed-foreground   dimmed-foreground
                    display
                    doc                 doc
                    font                font
                    foreground          foreground
                    geom-spec           geom-spec
                                        _c_o_n_t_i_n_u_e_d
                   _____________________________________________________________

                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |


















                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |


















                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |


















                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |




















































          PICASSO Reference Manual                                2-18







                                                               WINDOWS



                       ____________________________________________________
                        Reader Methods         Setf Methods           Misc
                       ________________________________________________________________________________________________________
                        gray                   gray
                        height                 height
                        height-increment       height-increment
                        increment-size         increment-size
                        inverted               inverted
                        inverted-background    inverted-background
                        inverted-foreground    inverted-foreground
                        label                  label
                        label-attributes       label-attributes
                        label-font             label-font
                        label-position         label-position
                        label-type             label-type
                        label-x                label-x
                        label-y                label-y
                        lexical-parent         lexical-parent
                        location               location
                        mf-selectable-widget   mf-selectable-widget
                        name                   name
                        parent                 parent
                        region                 region
                        repaint-flag           repaint-flag
                        res
                        resize-hint            resize-hint
                        screen
                        size                   size
                        status                 status
                        width                  width
                        width-height-ratio     width-height-ratio
                        width-increment        width-increment
                        value                  value
                        x-offset               x-offset
                        y-offset               y-offset
                       ____________________________________________________

                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |

































                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |

































                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |

































                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |




































          ____________________________________________________________________________________________________________________________________________________________________________________

          Window
          Management



                         A window can  be  in  one  of  three  states:
                         exposed,  concealed,  or pending.  A window's
                         current state can be  discovered  by  calling
                         the status method, which returns one of :con-
                         cealed, :exposed, or :pending.  If  a  window
                         is  pending,  it can be for one of three rea-
                         sons:

                         (1)  It is not attached.




          PICASSO Reference Manual                                2-19







                                                               WINDOWS


                         (2)  It has been shrunk to  zero  size  by  a
                              geometry manager ("pending").

                         (3)  Its parent is not visible.

                         These three states  are  orthogonal  states--
                         they   can  be  caused  by  the  server,  the
                         geometry manager, or the application, respec-
                         tively.   The  macros exposed-p, concealed-p,
                         pending-p,    attached-p,    pended-p,    and
                         invisible-p  can  be  used  to  determine the
                         status of a window.

                         _____________________________________________

          ATTACHED
          WINDOWS




                     attach

                                                            [_F_u_n_c_t_i_o_n]
                         _w_i_n_d_o_w
                         Attach _w_i_n_d_o_w to the  server  if  it  is  not
                         attached.

                     do-attach

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         Attach _w_i_n_d_o_w to the server without  checking
                         if it is already attached.

                     attach-when-possible

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _w_i_n_d_o_w)
                         Specifies whether  or  not  to  automatically
                         attach  the  window  when  its status is con-
                         cealed and its parent becomes  attached.   (t
                         _o_r _n_i_l).

                     attached-of

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w-_l_i_s_t
                         A list of children windows that are attached.
                         Return  t  _i_f  _o_b_j_e_c_t  _i_s  _a_t_t_a_c_h_e_d (_h_a_s _a_n _X
                         _s_e_r_v_e_r _r_e_p_r_e_s_e_n_t_a_t_i_o_n)

                     attached-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Return t _i_f _o_b_j_e_c_t  _i_s  _a_t_t_a_c_h_e_d  (_h_a_s  _a_n  _X
                         _s_e_r_v_e_r _r_e_p_r_e_s_e_n_t_a_t_i_o_n).

                         _____________________________________________

          DETACHED
          WINDOWS




                     detach

                                                            [_F_u_n_c_t_i_o_n]
                         _w_i_n_d_o_w
                         Detach  _w_i_n_d_o_w  from  the  server  if  it  is



          PICASSO Reference Manual                                2-20







                                                               WINDOWS


                         attached.

                     do-detach

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         Detach _w_i_n_d_o_w from the server without  check-
                         ing if it is attached.

                     detached-of

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w-_l_i_s_t
                         A list  of  children  windows  that  are  not
                         attached.

                     detached-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Return t _i_f _o_b_j_e_c_t _i_s _n_o_t _a_t_t_a_c_h_e_d (_h_a_s _n_o  _X
                         _s_e_r_v_e_r _r_e_p_r_e_s_e_n_t_a_t_i_o_n)

                         _____________________________________________

          PENDED
          STATE




                     pend

                                                            [_F_u_n_c_t_i_o_n]
                         _w_i_n_d_o_w
                         Pend _w_i_n_d_o_w (if it is  not  already  pended),
                         update status, and set the window state to 2.

                     do-pend

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         Pend _w_i_n_d_o_w without checking if it is already
                         pended.

                     pended-p

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w
                         Returns whether the window  has  been  pended
                         (is the state of the window 2?).

                     pending-of

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w-_l_i_s_t
                         Returns a list of children windows  that  are
                         not on the screen, but exposed.

                     pending-p

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w
                         Returns t _i_f _w_i_n_d_o_w _w_a_n_t_s _t_o _b_e _v_i_s_i_b_l_e,  _b_u_t
                         _i_s  _n_o_t  _f_o_r _s_o_m_e _r_e_a_s_o_n (_i_s _t_h_e _w_i_n_d_o_w _p_e_n_d_-
                         _i_n_g?).

                     unpend

                                                            [_F_u_n_c_t_i_o_n]
                         _w_i_n_d_o_w






          PICASSO Reference Manual                                2-21







                                                               WINDOWS


                         Unpend _w_i_n_d_o_w if it is pended.

                         _____________________________________________

          INVISIBLE
          WINDOWS




                     invisible-of

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w-_l_i_s_t
                         A list of children windows that  are  invisi-
                         ble.

                     invisible-p

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w
                         Returns  whether  the  window  is   invisible
                         (exposed, but parent not).

                     make-invisible

                                                            [_F_u_n_c_t_i_o_n]
                         _w_i_n_d_o_w
                         &key
                         (_x-_u_n_m_a_p _t)
                         Pend the window, update status, and  set  the
                         window state to 1.

                     do-make-invisible

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         &key
                         (_x-_u_n_m_a_p _t)
                         Pend the window, update status, and  set  the
                         window state to 1.

                     make-uninvisible

                                                            [_F_u_n_c_t_i_o_n]
                         _w_i_n_d_o_w
                         if _w_i_n_d_o_w is invisible,  and  the  parent  of
                         _w_i_n_d_o_w is exposed, then make _w_i_n_d_o_w uninvisi-
                         ble.

                     do-make-uninvisible

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         Same as make-uninvisible, _b_u_t  _d_o_e_s_n'_t  _f_i_r_s_t
                         _c_h_e_c_k _i_f _w_i_n_d_o_w _i_s _i_n_v_i_s_i_b_l_e.

                         _____________________________________________

          CONCEALED
          STATE




                     conceal

                                                            [_F_u_n_c_t_i_o_n]
                         _w_i_n_d_o_w
                         &key
                         (_t_r_a_n_s_p_a_r_e_n_t _n_i_l)
                         (x-unmap t)
                         Conceal _w_i_n_d_o_w if  it  is  not  already  con-




          PICASSO Reference Manual                                2-22







                                                               WINDOWS


                         cealed, and update status.

                     do-conceal

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         &key
                         (_t_r_a_n_s_p_a_r_e_n_t _n_i_l)
                         &allow-other-keysA
                         Conceal _w_i_n_d_o_w  without  checking  if  it  is
                         already concealed.

                     concealed-p

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w
                         Returns whether the window is concealed  (not
                         visible on screen).

                     concealed-of

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w-_l_i_s_t
                         Returns a list of children windows  that  are
                         concealed.

                         _____________________________________________

          EXPOSED
          STATE




                     expose

                                                            [_F_u_n_c_t_i_o_n]
                         _w_i_n_d_o_w
                         &key
                         (_x_m_a_p _t)
                         Expose _w_i_n_d_o_w unless it  is  already  exposed
                         and viewable, and update status.

                     do-expose

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _w_i_n_d_o_w)
                         &key
                         (_i_g_n_o_r_e _n_i_l)
                         &allow-other-keys
                         Expose  _w_i_n_d_o_w  without  checking  if  it  is
                         already exposed and viewable.

                     exposed-of

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w-_l_i_s_t
                         Returns a list of exposed children windows.

                     exposed-p

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w
                         Returns whether the window is exposed  (visi-
                         ble on screen).

                     active-p

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w
                         Returns whether the window is active  (had  a




          PICASSO Reference Manual                                2-23







                                                               WINDOWS


                         parent).

                         _____________________________________________

          MISC
          METHODS




                     managed-p

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w
                         Returns  whether  the  window's  geometry  is
                         being managed.

                     managed-of

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w-_l_i_s_t
                         Returns a list of managed children windows.

                     gadgets-of

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w-_l_i_s_t
                         Returns a list of children windows  that  are
                         gadgets.

                     exposed-gadgets-of

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w-_l_i_s_t
                         Returns a list of children windows  that  are
                         gadgets and exposed.

                     viewable-p

                                                               [_M_a_c_r_o]
                         _w_i_n_d_o_w
                         Returns t _i_f _w_i_n_d_o_w _i_s _v_i_e_w_a_b_l_e _o_n _t_h_e _s_c_r_e_e_n
                         _a_n_d  _c_a_n  _b_e _o_c_c_l_u_d_e_d (_t_h_e _w_i_n_d_o_w _i_s _a_t_t_a_c_h_e_d
                         _a_n_d _t_h_e _m_a_p-_s_t_a_t_e _o_f _w_i_n_d_o_w _i_s :_v_i_e_w_a_b_l_e)
          ____________________________________________________________________________________________________________________________________________________________________________________

          X-windows


                         X-windows are a subclass of the window class,
                         and   therefore   inherit   window  keys  and
                         methods.

                         The following function can be used to  create
                         X windows.

                     make-x-window

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_c_u_r_s_o_r _n_i_l)
                         (event-mask '( :no-event ))
                         ;; defaults overridden from superclasses
                         (_n_a_m_e "_A_n _X-_w_i_n_d_o_w")
                         ;; Plus keys inherited from windows
                         &allow-other-keys







          PICASSO Reference Manual                                2-24







                                                               WINDOWS


                         _____________________________________________

          ATTRIBUTES


                         X windows inherit all of the attributes  dis-
                         cussed  under windows.  In addition, the fol-
                         lowing attributes are defined for x-windows.

                     cursor

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         The cursor for the x-window. Of type  cursor,
                         _d_e_f_a_u_l_t _n_i_l.

                     event-mask

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         Any window  can  choose  to  receive  various
                         types  of  events,  and  only events that are
                         "requested" by the window will be  "sent"  to
                         the window.  An event is requested by insert-
                         ing the request-name of the event  type  into
                         the event-mask _l_i_s_t.  _T_h_e _t_y_p_e _o_f _e_v_e_n_t_s _t_h_a_t
                         _t_h_e  _w_i_n_d_o_w  _c_a_n  _h_a_n_d_l_e  _i_n_c_l_u_d_e   _k_e_y_b_o_a_r_d,
                         _p_o_i_n_t_e_r,  _e_x_p_o_s_u_r_e,  _i_n_p_u_t  _f_o_c_u_s, _a_n_d _c_l_i_e_n_t
                         _e_v_e_n_t_s,  _a_n_d  _t_h_e  _d_e_f_a_u_l_t  _v_a_l_u_e  _i_s  '(:_n_o-
                         _e_v_e_n_t).  For more information on the types of
                         events and how they are handled,  see  Events
                         (Chapter  4)  or  the "Widget Writer's Guide"
                         [Sei90].

                         _____________________________________________

          X-WINDOW
          GEOMETRY



                         In addition to the inherited window  Geometry
                         methods,  the  following  are  defined  on x-
                         windows:

                     configure

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         &key
                         (_x-_o_f_f_s_e_t _0 _x-_o_f_f_s_e_t-_p)
                         (y-offset 0 y-offset-p)
                         &allow-other-keys
                         If _x-_w_i_n_d_o_w is attached,  set  its  x  and  y
                         offset.

                     fix-location

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         &key
                         _x
                         _y
                         Fix the location (x and y offsets) of  the  x





          PICASSO Reference Manual                                2-25







                                                               WINDOWS


                         window.

                     fix-region

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         &key
                         _x
                         _y
                         _w_i_d_t_h
                         _h_e_i_g_h_t
                         Fix the region (x, y, width, and  height)  of
                         the x window.

                     fix-size

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         &key
                         _w_i_d_t_h
                         _h_e_i_g_h_t
                         Fix the size (width and height) of the x win-
                         dow.

                     query-region

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         Query the server for the  actual  coordinates
                         of the window, and cache the results.

                     server-x-offset

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         Query the server for the actual x  coordinate
                         of the window, and cache the results.

                     server-y-offset

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         Query the server for the actual y  coordinate
                         of the window, and cache the results.

                         _____________________________________________

          METHODS


                         In addition to the inherited window  methods,
                         the following are defined on x-windows.

                     circle-down

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         Lower the highest child of _w_i_n_d_o_w  that  par-
                         tially  or  completely occludes another child
                         to the bottom of the window stack.

                     circle-up

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         Raises the lowest child of _w_i_n_d_o_w  that  par-
                         tially  or  completely occludes another child




          PICASSO Reference Manual                                2-26







                                                               WINDOWS


                         to the top of the window stack.

                     conceal-inferiors

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         Conceal children windows.

                     expose-inferiors

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         Expose children windows.

                     grab-mouse

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         &key
                         (_c_u_r_s_o_r _n_i_l _c_u_r_s_o_r-_p)
                         (event-mask nil)
                         Grab control of the  mouse  pointer.   Events
                         specified  in _e_v_e_n_t-_m_a_s_k are sent to _x-_w_i_n_d_o_w
                         rather than to the client to which the events
                         would normally have been sent.

                     ungrab-mouse

                                                            [_F_u_n_c_t_i_o_n]
                         &optional
                         (_d_i_s_p_l_a_y (_c_u_r_r_e_n_t-_d_i_s_p_l_a_y) _d_i_s_p_l_a_y_p)
                         Release control of the mouse pointer.

                     lower

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         Lower the specified window  instance  to  the
                         bottom of the window stack.

                     raise

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         Raise the specified window  instance  to  the
                         top of the window stack.

                     related-p

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         (_p_a_r_e_n_t _x-_w_i_n_d_o_w)
                         Determine if two window are children  of  the
                         same root-window.

                     warp-mouse

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         &key
                         (_x _0)
                         (y 0)
                         (_l_o_c_a_t_i_o_n _n_i_l)
                         If  _l_o_c_a_t_i_o_n  is  specified,  move  mouse  to
                         specified location (list of x and y offsets).






          PICASSO Reference Manual                                2-27







                                                               WINDOWS


                         Otherwise, move mouse to specified _x and _y.

                     warp-mouse-if

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _x-_w_i_n_d_o_w)
                         &key
                         (_x _0)
                         (y 0)
                         (_l_o_c_a_t_i_o_n _n_i_l)
                         (in-window nil)
                         (_i_n-_r_e_g_i_o_n _n_i_l)
                         If the _i_n-_r_e_g_i_o_n  isn't  specified,  get  the
                         _i_n-_w_i_n_d_o_w  region, and only warp the mouse if
                         _i_n-_w_i_n_d_o_w or _i_n-_r_e_g_i_o_n is non-nil.  _I_f  _l_o_c_a_-
                         _t_i_o_n  _i_s  _s_p_e_c_i_f_i_e_d,  _m_o_v_e _m_o_u_s_e _t_o _s_p_e_c_i_f_i_e_d
                         _l_o_c_a_t_i_o_n (_l_i_s_t _o_f _x _a_n_d _y  _o_f_f_s_e_t_s).   _O_t_h_e_r_-
                         _w_i_s_e, _m_o_v_e _m_o_u_s_e _t_o _s_p_e_c_i_f_i_e_d _x _a_n_d _y.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Opaque
          Windows



                         Opaque windows are a subclass of the x-window
                         class,  and  therefore  inherit window and x-
                         window keys and methods.  The following func-
                         tion can be used to create opaque windows.

                     make-opaque-window

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_i_c_o_n _n_i_l)
                         (icon-name nil)
                         ;; defaults overridden from superclasses
                         (_n_a_m_e "_A_n _O_p_a_q_u_e _W_i_n_d_o_w")
                         (event-mask '(:exposure))
                         (_b_o_r_d_e_r-_t_y_p_e :_b_o_x)
                         (border-width 2)
                         ;; Plus keys inherited from x-windows
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES


                         In addition to the inherited  window  and  x-
                         window  attributes and methods, the following
                         are defined on opaque-windows.

                     icon

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _o_p_a_q_u_e-_w_i_n_d_o_w)
                         The icon associated with the window.  Of type
                         icon, _d_e_f_a_u_l_t _n_i_l.

                     icon-name

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _o_p_a_q_u_e-_w_i_n_d_o_w)
                         A name string associated with  the  icon  for
                         the window.



          PICASSO Reference Manual                                2-28







                                                             RESOURCES


                                               3
                                           RESOURCES

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview



                         PICASSO provides CLOS abstractions  for  many
                         of the commonly used X resources.  The advan-
                         tage of this is three-fold:  first, it allows
                         for  sharing  of  the  resources;  second, it
                         makes  many  of  these  resources  easier  to
                         create   and  manipulate;  and  finally,  the
                         resources  can   be   ``attached''   to   and
                         ``detached''  from a given X server, allowing
                         resources to  be  implemented  as  persistent
                         objects.

                         PICASSO provides CLOS classes for the follow-
                         ing CLX abstractions:

                         o+    Colors and colormaps

                         o+    Images

                         o+    Cursors

                         o+    Tiles

                         o+    Icons

                         o+    Fonts

                         o+    Displays

                         o+    Screens

                         o+    Graphics Contexts

                         In addition to defining CLOS classes for  the
                         corresponding  CLX  structures,  PICASSO pro-
                         vides some degree  of  management  for  these
                         resources.   All  resources have _n_a_m_e and _r_e_s
                         attributes.

                         _____________________________________________

          RES SLOT



                         Since  all   PICASSO   resources   correspond
                         directly  to CLX resources, PICASSO resources
                         share a common interface  for  accessing  the



          PICASSO Reference Manual                                3-29







                                                             RESOURCES


                         CLX  resources.  All PICASSO resources can be
                         attached to  or  detached  from  the  server.
                         When  a  resource  is  attached, its _r_e_s slot
                         contains the CLX structure which  corresponds
                         to  its representation in the server.  When a
                         resource is not attached,  its  _r_e_s  slot  is
                         nil.   _S_i_n_c_e  _r_e_s_o_u_r_c_e_s  _a_r_e _t_y_p_i_c_a_l_l_y _s_h_a_r_e_d
                         _b_e_t_w_e_e_n _w_i_d_g_e_t_s _a_n_d  _a_p_p_l_i_c_a_t_i_o_n_s,  _t_h_e_y  _a_l_l
                         _h_a_v_e  _i_n_t_e_r_n_a_l _r_e_f_e_r_e_n_c_e-_c_o_u_n_t_e_r_s _s_o _t_h_a_t _t_h_e
                         _r_e_s_o_u_r_c_e _i_s _a_u_t_o_m_a_t_i_c_a_l_l_y _d_e_t_a_c_h_e_d  _f_r_o_m  _t_h_e
                         _s_e_r_v_e_r _w_h_e_n _i_t _i_s _n_o _l_o_n_g_e_r _b_e_i_n_g _u_s_e_d.

                         The following operations exist for  attaching
                         and  detaching  resources  to  and  from  the
                         server:

                     attached-p

                                                               [_M_a_c_r_o]
                         _r_e_s_o_u_r_c_e
                         t if the _r_e_s_o_u_r_c_e is attached to  the  window
                         server, else nil.

                     attach

                                                            [_F_u_n_c_t_i_o_n]
                         _r_e_s_o_u_r_c_e

                     do-attach

                                                              [_M_e_t_h_o_d]
                         _r_e_s_o_u_r_c_e

                     <_r_e_s_o_u_r_c_e-_t_y_p_e>-attach

                                                               [_M_a_c_r_o]
                         _r_e_s_o_u_r_c_e
                         increment the reference  count  for  _r_e_s_o_u_r_c_e
                         and  attach the _r_e_s_o_u_r_c_e to the server if the
                         reference count was 0  _b_e_f_o_r_e  _t_h_e  _o_p_e_r_a_t_i_o_n
                         _w_a_s _i_n_v_o_k_e_d.

                     detach

                                                            [_F_u_n_c_t_i_o_n]
                         _r_e_s_o_u_r_c_e

                     do-detach

                                                              [_M_e_t_h_o_d]
                         _r_e_s_o_u_r_c_e

                     <_r_e_s_o_u_r_c_e-_t_y_p_e>-detach

                                                               [_M_a_c_r_o]
                         _r_e_s_o_u_r_c_e
                         decrement the reference count  for  _r_e_s_o_u_r_c_e.
                         If  the  new reference count is not positive,
                         detach the _r_e_s_o_u_r_c_e from the server.

                         _____________________________________________

          NAME SLOT



                         Since resources are  shared,  they  all  have
                         names.   The resources are named so that they



          PICASSO Reference Manual                                3-30







                                                             RESOURCES


                         can be conveniently referred to without keep-
                         ing  track  of  the  actual CLOS object.  The
                         lexical extent of the name for  a  particular
                         resource  varies  depending  on  the  type of
                         resource.  Each resource  type  has  its  own
                         dictionary  and  its  own functions to create
                         and retrieve the resource.  For creation  the
                         make-<_r_e_s_o_u_r_c_e-_t_y_p_e>  function  is  provided.
                         The arguments make-<_r_e_s_o_u_r_c_e-_t_y_p_e> depend  on
                         the   type   of   the   resource.   The  get-
                         <_r_e_s_o_u_r_c_e-_t_y_p_e> function is used to  retrieve
                         a  named  resource from the resource diction-
                         ary.  The format of   get-<_r_e_s_o_u_r_c_e-_t_y_p_e>  is
                         as follows:

                     get-<_r_e_s_o_u_r_c_e-_t_y_p_e>

                                                            [_F_u_n_c_t_i_o_n]
                         &optional
                         _n_a_m_e
                         _s_o_u_r_c_e
                         _n_a_m_e is a string which  usually  defaults  to
                         (default-<_r_e_s_o_u_r_c_e-_t_y_p_e>).    _s_o_u_r_c_e   is  an
                         object which specifies the  location  of  the
                         dictionary  in  which  the  resource is to be
                         found.   _s_o_u_r_c_e  defaults  to  a   reasonable
                         object   (usually  (current-display)).   _N_o_t_e
                         _t_h_a_t   (_g_e_t-<_r_e_s_o_u_r_c_e-_t_y_p_e>)   returns    the
                         "default" instance of <_r_e_s_o_u_r_c_e-_t_y_p_e>.

          ____________________________________________________________________________________________________________________________________________________________________________________

          Colors and
          Colormaps




                         In PICASSO, a _c_o_l_o_r is defined by a name  and
                         a  set  of three numeric values, representing
                         intensities  of  red,  green,  and  blue.   A
                         _c_o_l_o_r_m_a_p  is  conceptually a table which maps
                         from colors to _p_i_x_e_l  values.   Each  PICASSO
                         window  has a corresponding colormap.  Raster
                         graphics displays store  _p_i_x_e_l  values  in  a
                         special   screen  hardware  memory.   As  the
                         screen hardware scans this memory,  it  reads
                         each  pixel  value, looks up the color in the
                         corresponding  colormap,  and  displays   the
                         _c_o_l_o_r  on the screen.  For more on colors and
                         colormaps, see the  relevant  CLX  documenta-
                         tion.   The lexical context of a color's _n_a_m_e
                         is the color's colormap.   Hence,  the  color
                         "red"  could be different in different color-
                         maps.

                         In widgets that use many colors profusely and
                         in  a  very  transient fashion, it is usually



          PICASSO Reference Manual                                3-31







                                                             RESOURCES


                         desirable to  avoid  the  overhead  of  using
                         PICASSO colors.  In this case, the programmer
                         would be advised to use the corresponding CLX
                         operations directly (eg. use clx:make-color).
                         The CLX structures can always be obtained  by
                         means  of the res accessor method for colors,
                         colormaps, and any other PICASSO resource.

                         _____________________________________________

          COLOR
          DEFINITION



                         All colors are defined in the  context  of  a
                         particular  colormap.   The  actual number of
                         colors that can be allocated in a  particular
                         colormap   is   limited  (the  actual  number
                         depends on the hardware and  the  version  of
                         CLX).   Defined  colors are only available to
                         windows which use the same colormap in  which
                         the color is defined.

                         A _c_o_l_o_r is represented by a CLOS _c_l_a_s_s,  with
                         the following accessors:

                     res

                                                              [_R_e_a_d_e_r]
                         CLX representation of the color.

                     name

                                                              [_R_e_a_d_e_r]
                         identifier  by  which  the   color   can   be
                         accessed.

                     colormap

                                                              [_R_e_a_d_e_r]
                         PICASSO _c_o_l_o_r_m_a_p associated with the color.

                     pixel

                                                              [_R_e_a_d_e_r]
                         _p_i_x_e_l value  of  the  color  in  the  color's
                         colormap.

                     red

                                                              [_R_e_a_d_e_r]
                         intensity  of  the  red  hue.   Must   be   a
                         floating-point  number  between  0.0 (minimum
                         intensity) and 1.0 (maximum-intensity).

                     green

                                                              [_R_e_a_d_e_r]
                         intensity  of  the  green  hue.   Must  be  a
                         floating-point  number  between  0.0 (minimum
                         intensity) and 1.0 (maximum-intensity).

                     blue

                                                              [_R_e_a_d_e_r]
                         intensity  of  the  blue  hue.   Must  be   a
                         floating-point  number  between  0.0 (minimum
                         intensity) and 1.0 (maximum-intensity).




          PICASSO Reference Manual                                3-32







                                                             RESOURCES


                         The make-color function can be used to create
                         a  new  color.   If  a  PICASSO color already
                         exists with the same name, the existing color
                         will  be  returned  and  no new color will be
                         made.

                     make-color

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_n_a_m_e _n_i_l)
                         (colormap (default-colormap))
                         (_r_e_d _0)
                         (green 0)
                         (_b_l_u_e _0)
                         (lookup-p t)
                         &allow-other-keys
                         _n_a_m_e, _c_o_l_o_r_m_a_p, _r_e_d, _g_r_e_e_n, and _b_l_u_e  are  as
                         described  above.   The X window-server main-
                         tains a dictionary of common predefined color
                         names  and  their  associated  color objects.
                         _l_o_o_k_u_p-_p indicates whether or not _n_a_m_e is  to
                         be  looked up in the server color dictionary.
                         If _l_o_o_k_u_p-_p is non-nil and the lookup is suc-
                         cessful,  the  corresponding PICASSO color is
                         returned.

                         _____________________________________________

          COLORMAP
          DEFINITION




                         All colormaps are defined in the context of a
                         particular  screen.  All windows have exactly
                         one colormap at a given time.  Usually,  win-
                         dows   all  share  the  same  colormap  which
                         defaults to (default-colormap).   A  colormap
                         can have a number of colors defined within it
                         (the actual number depends  on  the  hardware
                         and the version of CLX).  Colors defined on a
                         colormap are available only to  windows  that
                         use  that particular colormap.  A colormap is
                         only effective if it is installed on  a  par-
                         ticular screen.  Most current hardwares allow
                         only one installed colormap per screen.

                         A _c_o_l_o_r_m_a_p is represented by  a  CLOS  _c_l_a_s_s,
                         with the following accessors:

                     res

                                                              [_R_e_a_d_e_r]
                         CLX representation of the colormap.

                     name

                                                              [_R_e_a_d_e_r]
                         identifier  by  which  the  colormap  can  be




          PICASSO Reference Manual                                3-33







                                                             RESOURCES


                         accessed.

                     visual

                                                              [_R_e_a_d_e_r]
                         type of visual supported by colormap  (member
                         (:direct-color    :gray-scale   :pseudo-color
                         :static-color :static-gray :true-color)).

                     screen

                                                              [_R_e_a_d_e_r]
                         _s_c_r_e_e_n _o_n  _w_h_i_c_h  _t_h_e  _c_o_l_o_r_m_a_p  _i_s  _d_e_f_i_n_e_d.
                         _D_e_f_a_u_l_t _i_s (_c_u_r_r_e_n_t-_s_c_r_e_e_n).

                         The make-colormap function  can  be  used  to
                         create a new colormap.

                     make-colormap

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_n_a_m_e _n_i_l)
                         (visual nil)
                         (_s_c_r_e_e_n (_c_u_r_r_e_n_t-_s_c_r_e_e_n))
                         (window nil)
                         &allow-other-keys
                         _n_a_m_e, _v_i_s_u_a_l, and _s_c_r_e_e_n,  are  as  described
                         above.   _w_i_n_d_o_w  is an alternative specifica-
                         tion to _s_c_r_e_e_n that specifies a  window  that
                         is to be on the screen of the colormap.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Images



                         An _i_m_a_g_e is a two-dimensional array of pixels
                         that is used to specify a picture that can be
                         displayed in windows.  Images are independent
                         of  display,  screen, and window.  Hence, all
                         images are defined at a global level.

                         An _i_m_a_g_e is represented by a CLOS _c_l_a_s_s, with
                         the following accessors:

                     res

                                                              [_R_e_a_d_e_r]
                         CLX representation of the image.

                     name

                                                              [_R_e_a_d_e_r]
                         identifier  by  which  the   image   can   be
                         accessed.

                     bitmap-p

                                                              [_R_e_a_d_e_r]
                         whether or not the image is a bitmap.

                     width

                                                              [_R_e_a_d_e_r]






          PICASSO Reference Manual                                3-34







                                                             RESOURCES


                         the width of the image in pixels.

                     height

                                                              [_R_e_a_d_e_r]
                         the height of the image in pixels.

                     height

                                                              [_R_e_a_d_e_r]
                         the depth of the image in pixels.

                         There are three ways of  creating  an  image:
                         from a file, a gif-file,  or from a region of
                         a window.

                         The make-image function can be used to create
                         a new image.

                     make-image

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_n_a_m_e _n_i_l)
                         (file nil)
                         (_g_i_f-_f_i_l_e _n_i_l)
                         (source nil)
                         (_s_r_c-_x _0)
                         (src-y 0)
                         (_w_i_d_t_h _n_i_l)
                         (height nil)
                         (_a_t_t_a_c_h-_p _t)
                         &allow-other-keys
                         _n_a_m_e, is as described above.  If the image is
                         to  be extracted from a bitmap file, the _f_i_l_e
                         specification should be used to indicate  the
                         name  of the source file.  If the image is to
                         be extracted from a GIF  file,  the  _g_i_f-_f_i_l_e
                         specification  should be used to indicate the
                         name of the source file.  The format of  bit-
                         map files used in PICASSO is the standard X11
                         bitmap format.  The format of GIF image files
                         used  in  PICASSO is the standard GIF format.
                         If the image is to be extracted from  a  por-
                         tion of a PICASSO window, the _s_o_u_r_c_e argument
                         is used, and the  _s_r_c-_x,  _s_r_c-_y,  _w_i_d_t_h,  and
                         _h_e_i_g_h_t arguments are relevant.  _s_r_c-_x, _s_r_c-_y,
                         _w_i_d_t_h, and _h_e_i_g_h_t  specify the region of  the
                         window  _s_o_u_r_c_e  to  make  into  an image.  If
                         _a_t_t_a_c_h-_p  is  non-nil,  the  image  will   be
                         automatically   attached   before  make-image
                         _r_e_t_u_r_n_s.  _T_h_e _d_e_f_a_u_l_t _d_i_r_e_c_t_o_r_y  _p_a_t_h_n_a_m_e  _i_s









          PICASSO Reference Manual                                3-35







                                                             RESOURCES


                         *_l_i_b_r_a_r_y-_p_a_t_h_n_a_m_e*.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Cursors



                         A _c_u_r_s_o_r is a visible shape that  appears  at
                         the  current  position  of the pointer device
                         (eg. mouse).  The cursor shape moves with the
                         pointer to provide continuous feedback to the
                         user  about  the  current  location  of   the
                         pointer.   Each window can have a cursor that
                         defines the appearance of the pointer  cursor
                         when  the  pointer  position  lies within the
                         window.  All cursors are defined relative  to
                         a particular display.

                         A _c_u_r_s_o_r is represented by a CLOS _c_l_a_s_s, with
                         the following accessors:

                     res

                                                              [_R_e_a_d_e_r]
                         CLX representation of the cursor.

                     name

                                                              [_R_e_a_d_e_r]
                         identifier  by  which  the  cursor   can   be
                         accessed.

                     display

                                                              [_R_e_a_d_e_r]
                         display  in  which  the  cursor  is  defined.
                         Default is (current-display).

                         There are three ways of creating  an  cursor:
                         from  a  font,  from a file, or from an image
                         window.  Currently, all cursor created from a
                         file  or  a font are bitmaps, which means the
                         pixel values (colors) are 1 or  0  (black  or
                         white).

                         The  make-cursor  function  can  be  used  to
                         create a new cursor.

                     make-cursor

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_n_a_m_e *_d_e_f_a_u_l_t-_c_u_r_s_o_r-_n_a_m_e*)
                         (file "arrow.cursor")
                         (_m_a_s_k-_f_i_l_e "_a_r_r_o_w__m_a_s_k._c_u_r_s_o_r")
                         (image nil)
                         (_f_o_n_t "_c_u_r_s_o_r")
                         (source-font "cursor")
                         (_m_a_s_k-_f_o_n_t "_c_u_r_s_o_r")
                         (index nil)
                         (_s_o_u_r_c_e-_i_n_d_e_x _n_i_l)
                         (mask-index nil)



          PICASSO Reference Manual                                3-36







                                                             RESOURCES


                         (_f_o_r_e_g_r_o_u_n_d "_b_l_a_c_k")
                         (background "white")
                         (_x-_h_o_t _n_i_l)
                         (y-hot nil)
                         (_d_i_s_p_l_a_y (_c_u_r_r_e_n_t-_d_i_s_p_l_a_y))
                         &allow-other-keys
                         _n_a_m_e and _d_i_s_p_l_a_y are as describe  above.   If
                         the  cursor  is  to be extracted from a font,
                         the  _f_o_n_t,  _s_o_u_r_c_e-_f_o_n_t,  _m_a_s_k-_f_o_n_t,   _i_n_d_e_x,
                         _s_o_u_r_c_e-_i_n_d_e_x,  and  _m_a_s_k-_i_n_d_e_x  arguments are
                         relevant. Specifying _f_o_n_t  is  equivalent  to
                         specifying  _s_o_u_r_c_e-_f_o_n_t  and specifying _i_n_d_e_x
                         is equivalent to specifying _s_o_u_r_c_e-_i_n_d_e_x. The
                         _s_o_u_r_c_e-_f_o_n_t  and  _m_a_s_k-_f_o_n_t specify the fonts
                         (or names of fonts)  from  which  the  cursor
                         glyph  and  mask  are  to extracted.  _s_o_u_r_c_e-
                         _i_n_d_e_x and _m_a_s_k-_i_n_d_e_x specify the indices into
                         the  source and mask fonts that determine the
                         particular source and mask glyph to  be  used
                         for  the  cursor.  If _m_a_s_k-_f_o_n_t is not speci-
                         fied, _s_o_u_r_c_e-_f_o_n_t is used  for  the  mask  as
                         well.    If   _m_a_s_k-_i_n_d_e_x  is  not  specified,
                         _s_o_u_r_c_e-_i_n_d_e_x + 1 _i_s _u_s_e_d _a_s _t_h_e _v_a_l_u_e _o_f  _t_h_e
                         _m_a_s_k  _i_n_d_e_x.   _T_h_e _m_i_n_i_m_a_l _s_p_e_c_i_f_i_c_a_t_i_o_n _t_h_a_t
                         _c_a_n _b_e _u_s_e_d _t_o _s_u_c_c_e_s_s_f_u_l_l_y _c_r_e_a_t_e  _a  _c_u_r_s_o_r
                         _f_r_o_m _a _f_o_n_t _g_l_y_p_h _i_s _j_u_s_t _i_n_d_e_x.

                         If the cursor is to be extracted from a file,
                         the  _f_i_l_e  specification  should  be  used to
                         indicate the name of the source file.  If the
                         image  is  to be extracted from an image, the
                         _s_o_u_r_c_e argument is  used  and  should  be  an
                         image.   _f_o_r_e_g_r_o_u_n_d  and  _b_a_c_k_g_r_o_u_n_d  are the
                         colors that are to be used for the colors  of
                         the  cursors.   _x-_h_o_t  and  _y-_h_o_t are used to
                         specify the  hot-spot  of  the  cursor.   The
                         default  directory  pathname  for  cursors is
                         *library-pathname*.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Tiles


                         A _t_i_l_e consists of a  CLX  _p_i_x_m_a_p  associated
                         with a PICASSO window.  A tile is customarily
                         used for _t_i_l_i_n_g the background of  a  window.
                         X  allows  window  backgrounds  to  be either
                         colors or  tiled  images.   Since  tiles  are
                         associated  with  a  particular  window, they
                         cannot be shared  in  the  sense  that  other
                         resources  are  shared.  Hence, a tile's name
                         has little significance (two tiles  can  have
                         the same name) and there is no get-tile func-
                         tion defined.



          PICASSO Reference Manual                                3-37







                                                             RESOURCES


                         A _t_i_l_e is represented by a CLOS  _c_l_a_s_s,  with
                         the following accessors:

                     res

                                                              [_R_e_a_d_e_r]
                         CLX representation  of  the  (a  CLX  _p_i_x_m_a_p)
                         tile.

                     name

                                                              [_R_e_a_d_e_r]
                         identifier by which the tile can be accessed.

                     width

                                                              [_R_e_a_d_e_r]
                         width in pixels of the tile.

                     height

                                                              [_R_e_a_d_e_r]
                         height in pixels of the tile.

                     depth

                                                              [_R_e_a_d_e_r]
                         depth of the tile.

                     image

                                                              [_R_e_a_d_e_r]
                         image used to create the tile.

                     foreground

                                                            [_A_c_c_e_s_s_o_r]
                         foreground  color  with  which  to  tile  the
                         image.   foreground  _c_a_n _o_n_l_y _b_e _s_e_t _w_h_e_n _t_h_e
                         _t_i_l_e _i_s _n_o_t _a_t_t_a_c_h_e_d.

                     background

                                                            [_A_c_c_e_s_s_o_r]
                         _b_a_c_k_g_r_o_u_n_d  _c_o_l_o_r  _w_i_t_h  _w_h_i_c_h  _t_o  _t_i_l_e  _t_h_e
                         _i_m_a_g_e.   _b_a_c_k_g_r_o_u_n_d  _c_a_n _o_n_l_y _b_e _s_e_t _w_h_e_n _t_h_e
                         _t_i_l_e _i_s _n_o_t _a_t_t_a_c_h_e_d.

                         There are four ways to create a tile; from  a
                         file,  image,  color, or window.  If the tile
                         is  made  from  an  image,  the  tile  simply
                         creates  a  CLX  pixmap from the image, fore-
                         ground _a_n_d _b_a_c_k_g_r_o_u_n_d.  If the tile  is  made
                         from  a  file,  window  or color, an image is
                         created first (see section on  "Images")  and
                         the tile is made from the resulting image.

                         The make-tile function can be used to  create
                         a new tile.

                     make-tile

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_n_a_m_e _n_i_l)
                         (window nil)
                         (_f_i_l_e _n_i_l)
                         (image nil)
                         (_c_o_l_o_r _n_i_l)
                         (source nil)



          PICASSO Reference Manual                                3-38







                                                             RESOURCES


                         (_x-_o_f_f_s_e_t _0)
                         (y-offset 0)
                         (_w_i_d_t_h _n_i_l)
                         (height nil)
                         (_d_e_p_t_h _n_i_l)
                         (foreground "black")
                         (_b_a_c_k_g_r_o_u_n_d "_w_h_i_t_e")
                         &allow-other-keys
                         _n_a_m_e, _w_i_n_d_o_w,  _w_i_d_t_h,  _h_e_i_g_h_t,  _d_e_p_t_h,  _f_o_r_e_-
                         _g_r_o_u_n_d,   and  _b_a_c_k_g_r_o_u_n_d  are  as  described
                         above.  _f_i_l_e should be used if the tile is to
                         be  made  from  a file, _i_m_a_g_e if it should be
                         made from an image, _c_o_l_o_r  if  it  should  be
                         made  from  a color, or _s_o_u_r_c_e if it is to be
                         made from a region of  a  window.   _x-_o_f_f_s_e_t,
                         _y-_o_f_f_s_e_t, _w_i_d_t_h, and _h_e_i_g_h_t are only relevant
                         if _s_o_u_r_c_e is specified.  The tile is automat-
                         ically  attached  unless _w_i_n_d_o_w is not speci-
                         fied.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Icons



                         An icon is a sort of window that pops up when
                         a  top-level window (a window whose parent is
                         the root-window) is concealed  or  _i_c_o_n_i_f_i_e_d.
                         Icons  are  a  feature  of window-managers so
                         PICASSO icons will not work with all  window-
                         managers.    PICASSO   icons  work  with  the
                         window-manager twm which is what we  all  use
                         here  at  PICASSO Inc.  If the window-manager
                         under which PICASSO is running does not  have
                         the  right type of icon-support, PICASSO will
                         still run but whether or not the windows have
                         icons is dependent on the window-manager.

                         PICASSO _i_c_o_n_s are  implemented  as  a  simple
                         subclass of _t_i_l_e.  Hence, all _i_c_o_n attributes
                         are the same as those for _t_i_l_e:

                     res

                                                              [_R_e_a_d_e_r]
                         CLX representation  of  the  (a  CLX  _p_i_x_m_a_p)
                         icon.

                     name

                                                              [_R_e_a_d_e_r]
                         identifier by which the icon can be accessed.

                     width

                                                              [_R_e_a_d_e_r]
                         width in pixels of the icon.

                     height

                                                              [_R_e_a_d_e_r]




          PICASSO Reference Manual                                3-39







                                                             RESOURCES


                         height in pixels of the icon.

                     depth

                                                              [_R_e_a_d_e_r]
                         depth of the icon.

                     image

                                                              [_R_e_a_d_e_r]
                         image used to create the icon.

                     foreground

                                                            [_A_c_c_e_s_s_o_r]
                         foreground  color  with  which  to  icon  the
                         image.   foreground  _c_a_n _o_n_l_y _b_e _s_e_t _w_h_e_n _t_h_e
                         _i_c_o_n _i_s _n_o_t _a_t_t_a_c_h_e_d.

                     background

                                                            [_A_c_c_e_s_s_o_r]
                         _b_a_c_k_g_r_o_u_n_d  _c_o_l_o_r  _w_i_t_h  _w_h_i_c_h  _t_o  _i_c_o_n  _t_h_e
                         _i_m_a_g_e.   _b_a_c_k_g_r_o_u_n_d  _c_a_n _o_n_l_y _b_e _s_e_t _w_h_e_n _t_h_e
                         _i_c_o_n _i_s _n_o_t _a_t_t_a_c_h_e_d.

                         The make-icon function can be used to  create
                         a new icon.

                     make-icon

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_n_a_m_e _n_i_l)
                         (window nil)
                         (_f_i_l_e _n_i_l)
                         (image nil)
                         (_c_o_l_o_r _n_i_l)
                         (source nil)
                         (_x-_o_f_f_s_e_t _0)
                         (y-offset 0)
                         (_w_i_d_t_h _n_i_l)
                         (height nil)
                         (_d_e_p_t_h _n_i_l)
                         (foreground "black")
                         (_b_a_c_k_g_r_o_u_n_d "_w_h_i_t_e")
                         &allow-other-keys
                         The arguments to make-icon are  the  same  as
                         those for make-tile.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Fonts



                         A font is  collection  of  character  glyphs.
                         There  are  several  different types of fonts
                         that  can  be  used  in   X   programs   (eg.
                         linear/matrix  encoded,  fixed/variable-size,
                         etc).  The X server maintains a set of prede-
                         fined  fonts  that can be used in text opera-
                         tions.  Any of these fonts  can  be  used  in
                         PICASSO   applications,   but  currently  the
                         PICASSO widgets work  best  with  fixed-width



          PICASSO Reference Manual                                3-40







                                                             RESOURCES


                         fonts.   Fonts are defined relative to a par-
                         ticular display.

                         A _f_o_n_t is represented by a CLOS  _c_l_a_s_s,  with
                         the following accessors:

                     res

                                                              [_R_e_a_d_e_r]
                         CLX representation of the font.

                     name

                                                              [_R_e_a_d_e_r]
                         identifier by  which  the  the  font  can  be
                         accessed.

                     display

                                                              [_R_e_a_d_e_r]
                         display in which  the  colormap  is  defined.
                         Default is (current-display).

                     width

                                                              [_R_e_a_d_e_r]

                     font-width

                                                              [_R_e_a_d_e_r]
                         _t_h_e _m_a_x_i_m_u_m _w_i_d_t_h _o_f _a _c_h_a_r_a_c_t_e_r _i_n _t_h_e _f_o_n_t.

                     height

                                                              [_R_e_a_d_e_r]

                     font-height

                                                              [_R_e_a_d_e_r]
                         _t_h_e _t_o_t_a_l _o_f _f_o_n_t-_a_s_c_e_n_t  +  _f_o_n_t-_d_e_s_c_e_n_t  _o_f
                         _t_h_e _f_o_n_t.

                     font-ascent

                                                              [_R_e_a_d_e_r]
                         _t_h_e _m_a_x_i_m_u_m _a_s_c_e_n_t  _o_f  _a  _c_h_a_r_a_c_t_e_r  _i_n  _t_h_e
                         _f_o_n_t.

                     font-descent

                                                              [_R_e_a_d_e_r]
                         _t_h_e _m_a_x_i_m_u_m _d_e_s_c_e_n_t _o_f  _a  _c_h_a_r_a_c_t_e_r  _i_n  _t_h_e
                         _f_o_n_t.

                         The make-font function can be used to  create
                         a new font.

                     make-font

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_n_a_m_e *_d_e_f_a_u_l_t-_f_o_n_t-_n_a_m_e*)
                         (display (current-display))
                         (_a_t_t_a_c_h-_p _n_i_l)
                         &allow-other-keys
                         _n_a_m_e and _d_i_s_p_l_a_y are as described above.   if
                         _a_t_t_a_c_h-_p   is   non-nil,  the  font  will  be
                         automatically   attached   before   make-font
                         _r_e_t_u_r_n_s.

                         There is a  default  font-path  that  X  (and
                         PICASSO)  looks for all requested fonts.  The



          PICASSO Reference Manual                                3-41







                                                             RESOURCES


                         _f_o_n_t-_p_a_t_h can be accessed  by  the  following
                         function and setf.

                     font-path

                                                       [_F_u_n_c_t_i_o_n|_S_e_t_f]
                         &optional
                         (_d_i_s_p_l_a_y (_c_u_r_r_e_n_t-_d_i_s_p_l_a_y))
                         Returns  a  list  of  names  containing   the
                         current  search  path  for fonts.  With setf,
                         this function sets the search path  for  font
                         lookup.   There  is  only one search path per
                         server, not one per client.  The  interpreta-
                         tion  of  the  names is server-dependent, but
                         they are intended to specify  directories  to
                         be searched in the order listed.  Setting the
                         path to nil restores the default path defined
                         for  the server.  Note that as a sided-effect
                         of executing  this  request,  the  server  is
                         guaranteed  to  flush  all cached information
                         about fonts for which there are currently  no
                         explicit resource IDs allocated.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Displays



                         A particular  X  server,  together  with  its
                         screens   and  input  devices,  is  called  a
                         _d_i_s_p_l_a_y.  In PICASSO the  _d_i_s_p_l_a_y  object  is
                         used  as  a  context  or a reference point to
                         keep track of information concerning  a  par-
                         ticular  connection to the X server.  In oth-
                         erwords,  all  windows,   screens,   cursors,
                         colors,  and  most  other  resources  must be
                         associated with a display  and  all  graphics
                         operations  must  be performed in the context
                         of a particular display.  If a display is not
                         explicitly  specified,  the context is impli-
                         citly  (current-display)  which   returns   a
                         display  object.  Naturally, (current-display
                         is equivalent to (get-display).  When you run
                         PICASSO, it implicitly creates a display.

                         A _d_i_s_p_l_a_y is represented  by  a  CLOS  _c_l_a_s_s,
                         with the following accessors:

                     res

                                                              [_R_e_a_d_e_r]
                         CLX representation of the display.

                     name

                                                              [_R_e_a_d_e_r]
                         name of the X display  server.   Typically  a
                         machine-name  or just "unix".  If _n_a_m_e is not
                         specified, the name  is  extracted  from  the
                         user's  DISPLAY  shell  environment  variable



          PICASSO Reference Manual                                3-42







                                                             RESOURCES


                         using the function default-display-name.

                     primary-screen

                                                              [_R_e_a_d_e_r]
                         default screen for this display.

                         The make-display  function  can  be  used  to
                         create a new display.

                     make-display

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_n_a_m_e (_d_e_f_a_u_l_t-_d_i_s_p_l_a_y-_n_a_m_e))
                         &allow-other-keys
                         Attempt to connect  to  the  X  server  named
                         _n_a_m_e.    If  successful,  creates  a  display
                         object.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Screen



                         An X display supports graphical output to one
                         or  more  _s_c_r_e_e_n_s.   each  screen has its own
                         root window and window hierarchy.  Each  win-
                         dow  belongs to exactly one screen and cannot
                         simultaneously appear on another screen.  The
                         kinds  of graphics hardware used by X screens
                         can vary greatly in their support  for  color
                         and  in  their  methods  for accessing raster
                         memory.  X uses the concept of a  _v_i_s_u_a_l-_t_y_p_e
                         (usually  referred  to  simply  as  a _v_i_s_u_a_l)
                         which identifies the hardware capabilities of
                         a  screen.  See the documentation on X _o_r _C_L_X
                         _f_o_r _m_o_r_e _i_n_f_o_r_m_a_t_i_o_n _o_n _s_c_r_e_e_n_s _a_n_d _v_i_s_u_a_l_s.

                         A _s_c_r_e_e_n is represented by a CLOS _c_l_a_s_s, with
                         the following accessors:

                     res

                                                              [_R_e_a_d_e_r]
                         CLX representation of the screen.

                     number

                                                              [_R_e_a_d_e_r]
                         the number of the screen, in relation to  the
                         display.

                     display

                                                              [_R_e_a_d_e_r]
                         the display of the screen.

                     root

                                                              [_R_e_a_d_e_r]
                         the root-window of screen.

                         The  make-screen  function  can  be  used  to





          PICASSO Reference Manual                                3-43







                                                             RESOURCES


                         create a new screen.

                     make-screen

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_d_i_s_p_l_a_y (_c_u_r_r_e_n_t-_d_i_s_p_l_a_y))
                         &allow-other-keys
                         Creates a screen and a  root-window  for  the
                         specified  _d_i_s_p_l_a_y.  The number _o_f _t_h_e _s_c_r_e_e_n
                         _i_s _d_e_t_e_r_m_i_n_e_d _b_y _t_h_e X _s_e_r_v_e_r _a_n_d _s_e_t  _i_n_t_e_r_-
                         _n_a_l_l_y.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Graphics
          Contexts




                         See Widget Writer's Guide.








































          PICASSO Reference Manual                                3-44







                                                 APPLICATION FRAMEWORK


                                               4
                                     APPLICATION FRAMEWORK

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         The PICASSO Application Framework provides  a
                         set  of  high-level abstractions that make it
                         easier to define applications.  Each of these
                         abstractions  is implemented as a subclass of
                         PICASSO Object (PO).  The  PICASSO  framework
                         includes  five  object subclass types: tools,
                         forms, frames, dialogs, and panels.

                         Tools are PO's that implement entire applica-
                         tions.  They  are,  in turn, composed of PO's
                         called  frames,  dialog  boxes,  and  panels.
                         Frames  implement  major  tool modes.  Dialog
                         boxes  are  modal  interactors.   Panels  are
                         non-modal interactors.  Each of these PO's in
                         turn contains a form and control  buttons  or
                         menus.   Forms implement an extended model of
                         a paper form.  They contain widgets  to  view
                         and edit data.

                         PO's are similar to subroutines and functions
                         in  conventional programming languages.  They
                         have a name, local  variables,  formal  argu-
                         ments,  and  a  lexical  parent.  A PO can be
                         called and arguments passed to  it  (as  dis-
                         cussed  below in "Argument Passing"), causing
                         the PO to allocate space for its local  vari-
                         ables  and  to  create X resources to display
                         the values of selected variables.

                         In particular, frames are similar to  subrou-
                         tines  in  that  they  are  called  and  they
                         return.  Only one frame can be  active  at  a
                         time;  calling  a  frame conceals the current
                         frame and displays the new frame, and return-
                         ing from the called frame redisplays the cal-
                         ling frame.

                         Dialog  boxes   return   values,   and   thus
                         correspond  to  functions.   Calling a dialog
                         box  displays  it  and  forces  the  user  to
                         respond.  A dialog box returns a value to the
                         caller when it returns (e.g., ``ok'').

                         Panels are similar to co-routines.  Calling a
                         panel  displays  it  in a separate window and
                         the user can interact with it  or  any  other



          PICASSO Reference Manual                                4-45







                                                 APPLICATION FRAMEWORK


                         frame  or  panel.   The location of the mouse
                         cursor  determines  which  frame   or   panel
                         receives the user input.

                         This chapter is organized as follows:

                         o+    PO Persistence and Naming

                         o+    Argument Passing

                         o+    Tools

                         o+    Forms

                         o+    Callable PO's

                         o+    Frames

                         o+    Dialog Boxes

                         o+    Panels

                         The following notation convention

                     def<po-type>

                                                               [_M_a_c_r_o]
                         ;; optional clauses
                         { (optional-clause _s_p_e_c) }*

                         is used to define the high-level objects dis-
                         cussed  in  this  chapter, where <po-type> is
                         one of tool, frame, form, panel, or dialog.
          ____________________________________________________________________________________________________________________________________________________________________________________

          PO Per-
          sistence
          and Naming




                         The design of PICASSO encourages the develop-
                         ment of reusable interface abstractions. _P_e_r_-
                         _s_i_s_t_e_n_t  objects  are  objects  that  can  be
                         shared   by   more   than   one  application.
                         General-purpose  panels  and   dialog   boxes
                         (e.g.,  table  browsers  and  prompters) have
                         been developed for reuse in multiple applica-
                         tions.   Forms  can  be  reused  in different
                         panels, dialog boxes, and frames.  For  exam-
                         ple,  a standard name and address block for a
                         person  can  be  reused  in  any  form   that
                         displays information about a person.

                         To encourage reuse, a PO can be declared per-
                         sistent  by  registering  it  with  a  unique
                         external name. An external name  is  composed
                         of  three  parts,  each  of  which  is a Lisp
                         string:



          PICASSO Reference Manual                                4-46







                                                 APPLICATION FRAMEWORK


                               (_p_a_c_k_a_g_e _n_a_m_e . _s_u_f_f_i_x)

                         Each PO has a _p_a_c_k_a_g_e name.  A package  is  a
                         set  of related PO's.  _N_a_m_e identifies the PO
                         and the optional _s_u_f_f_i_x specifies the type of
                         the  PO.   A  default  package is used if the
                         package is not specified.  An object with  an
                         empty  suffix  is distinct from other objects
                         with the same package and  name  and  a  non-
                         empty suffix.  Examples of valid names are:


                          ("vip" "main" . "frame");; fully-qualified name
                          ("emp" . "form")        ;; default package name
                          "help"                  ;; default package and
                                                  ;; no suffix
                          ("help" . "frame")      ;; distinct from "help"


                         External names can be used to  specify  a  PO
                         stored in the database or already loaded into
                         main memory.  Most  PO's  are  referenced  by
                         name  in  the  definition  of  their  lexical
                         parent, and the  parent  automatically  loads
                         the PO when it is called.  A shorter internal
                         name can be specified for the PO (as  a  con-
                         stant)  to  simplify  the code.  In addition,
                         internal names facilitate changing to a  dif-
                         ferent PO between runs, since only the inter-
                         nal name binding has to be changed.  A  func-
                         tion  is  provided that allows an application
                         to load a PO at run-time.

                         A PICASSO tool has a package search list that
                         specifies  packages  in  which  to  look  for
                         objects that do not have an explicit  package
                         name.   For  example,  if a tool references a
                         frame named help, the  system  will  look  in
                         each  package  in  the package search list to
                         find it.

                         _____________________________________________

          MANAGING
          PACKAGES



                         A tool maintains a list of packages that  are
                         searched when looking for partially-specified
                         PO's. Most tools  will  place  objects  in  a
                         package with the same name as the tool (e.g.,
                         VIP tool  objects  will  be  defined  in  the
                         ``vip''  package).  Commonly used objects can
                         be  placed  in  a   library   package.    The
                         ``picasso''   package   contains   predefined



          PICASSO Reference Manual                                4-47







                                                 APPLICATION FRAMEWORK


                         objects that are automatically  provided  for
                         all tools.

                         The default package search list contains  the
                         user's  name  and  the  ``picasso''  package.
                         Most tools  will  prepend  the  tool-specific
                         package  to  the package search list when the
                         tool is run.  For example, suppose that Brian
                         was  running  PICASSO.   The  initial package
                         search list is


                          ("brian" "picasso")


                         While executing a  tool  named  ``vip''  that
                         specified the package-search-list clause as


                          ("demo-tool")


                         the list would be


                          ("vip" "demo-tool" "brian" "picasso")


                         The search list is restored to  the  original
                         list when the tool exits.  See the section on
                         Tools for more information  on  the  package-
                         search-list clause.

                         _____________________________________________

          MANAGING
          PACKAGES



                         Several  functions  are  provided  to  manage
                         packages and the package search list.

                     current-package

                                                            [_F_u_n_c_t_i_o_n]
                         This function returns  the  current  package.
                         The  current  package is the first package on
                         the package search list.

                     exclude-package

                                                            [_F_u_n_c_t_i_o_n]
                         _p_a_c_k_a_g_e(_s)
                         This function removes the named package  from
                         the package search list. It removes the pack-
                         age regardless of where  it  appears  in  the
                         list.   The package argument can be a package
                         name or a list of package names.   For  exam-
                         ple, if the package search list is:



          PICASSO Reference Manual                                4-48







                                                 APPLICATION FRAMEWORK



                          ("demo" "joe" "edit-library" "picasso")


                         and the function


                          (exclude-package "edit-library")


                         is executed, the search list will become


                          ("demo" "joe" "picasso")



                     find-po-named

                                                            [_F_u_n_c_t_i_o_n]
                         _p_i_c_a_s_s_o-_n_a_m_e
                         Given a _p_i_c_a_s_s_o-_n_a_m_e in the format (pkg  name
                         .  suffix),  _t_h_i_s  _f_u_n_c_t_i_o_n _r_e_t_u_r_n_s _t_h_e _n_a_m_e_d
                         PICASSO _o_b_j_e_c_t, _i_f _i_t _e_x_i_s_t_s,  _a_n_d  _l_o_a_d_s  _i_t
                         _i_n_t_o  _m_e_m_o_r_y  _i_f  _n_e_e_d_e_d.   _O_t_h_e_r_w_i_s_e, _i_f _t_h_e
                         _n_a_m_e_d PICASSO _o_b_j_e_c_t  _d_o_e_s  _n_o_t  _e_x_i_s_t,  _t_h_i_s
                         _f_u_n_c_t_i_o_n _r_e_t_u_r_n_s _n_i_l.

                     include-package

                                                            [_F_u_n_c_t_i_o_n]
                         _p_a_c_k_a_g_e(_s)
                         This function prepends  the  package  to  the
                         package  search  list.   If the named package
                         already exists in the package search list, it
                         is  removed from its old position.  The argu-
                         ment to the function can be a package name or
                         a list of package names.  For example, if the
                         package search list is:


                          ("demo" "picasso")


                         and the function


                          (include-package "joe")


                         is executed, the search list will become


                          ("joe" "demo" "picasso")





          PICASSO Reference Manual                                4-49







                                                 APPLICATION FRAMEWORK


                     package-search-list

                                                            [_F_u_n_c_t_i_o_n]
                         This  function  returns  the  package  search
                         list.   Packages  are  represented  by s CLOS
                         strings.

                     reload-picasso-object-named

                                                            [_F_u_n_c_t_i_o_n]
                         _n_a_m_e-_f_o_r_m
                         &optional
                         (_d_e_s_t_r_o_y-_o_l_d _t)
                         Reload picasso object named _n_a_m_e-_f_o_r_m.

                         _____________________________________________

          PACKAGE
          SUMMARY







                                   _____________________________
                                    Package Functions
                                   __________________________________________________________
                                    current-package
                                    exclude-package
                                    include-package
                                    find-po-named
                                    package-search-list
                                    reload-picasso-object-named
                                   _____________________________

                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |







                                                               |
                                                               |
                                                               |
                                                               |
                                                               |
                                                               |
                                                               |
                                                               |
                                                               |










          ____________________________________________________________________________________________________________________________________________________________________________________

          Argument
          Passing



                         Five argument passing mechanisms are provided
                         to  pass  values  to  to  callable  PO's. The
                         parameter   passing    mechanisms    provided
                         include:   value   value/update  value-result
                         value-result/update  and  reference.   Value,
                         value-result, and reference are the parameter
                         passing mechanisms found in traditional  pro-
                         gramming languages.

                         Arguments passed by

                         o+    _v_a_l_u_e are copied into a local  variable.
                              The  value  is  discarded  when  the  PO
                              returns.

                         o+    _v_a_l_u_e-_r_e_s_u_l_t are  copied  into  a  local
                              variable  when  the  PO  is  called  and
                              copied back to the actual argument  when
                              the  PO returns.  The actual argument is



          PICASSO Reference Manual                                4-50







                                                 APPLICATION FRAMEWORK


                              evaluated  only  once  when  the  PO  is
                              called.  The address of the actual argu-
                              ment is saved in the called PO and  used
                              as  the  location  in which to store the
                              result.

                         o+    _r_e_f_e_r_e_n_c_e are bound to the actual  argu-
                              ment  so  that  a  change  to either the
                              actual or formal argument is  propagated
                              to the other.

                         o+    _v_a_l_u_e/_u_p_d_a_t_e are  similar  to  arguments
                              passed  by  value except that changes to
                              the actual argument  are  propagated  to
                              the local variable.

                         o+    _v_a_l_u_e-_r_e_s_u_l_t/_u_p_d_a_t_e   are   similar   to
                              value/update parameters except the value
                              is copied back to the  calling  environ-
                              ment when the PO returns.

                         Reference and value/update  argument  passing
                         are  typically used when arguments are passed
                         to a panel so that changes made to an  object
                         either through the panel or through the frame
                         are propagated to the other interface.

                         The default argument passing mechanism is  by
                         value.  The other argument passing mechanisms
                         are specified in  the  formal  argument  list
                         after  a  lambda-list keyword (&value-result,
                         &ref or  &value-update)  that  specifies  the
                         argument  passing  mechanism  for  the formal
                         arguments that follow it.  For  example,  the
                         argument list in the frame definition


                          (defframe "foo" (x
                                            (y "hi")
                                            &ref
                                            z
                                            &value-update
                                            (w "picasso"))
                            ...)


                         has four formal arguments: x and y are passed
                         by  value, z is passed by reference, and w is
                         passed by value-update.  All frame  arguments
                         are optional so a default value can be speci-
                         fied.  In this example, only  y  and  w  have
                         default  values.   The other arguments have a



          PICASSO Reference Manual                                4-51







                                                 APPLICATION FRAMEWORK


                         default value of nil.

                         Keywords  are  used  in  the  frame  call  to
                         specify  the  formal  argument  to  which the
                         actual argument should be bound.  The follow-
                         ing  call  on  the frame ``foo'' passes argu-
                         ments to x, z, and  w  (see  "Callable  PO's"
                         below for more information on calling PICASSO
                         objects):


                          (call-frame #!foo
                            :x '(a list)
                            :z (title (current-tool))
                            :w (current-package))


                         The argument y is  given  the  default  value
                         ``hi'' since it is not passed explicitly.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Tools


                         A tool is the outermost object in an applica-
                         tion.   The  window through which the tool is
                         displayed is managed  by  a  window  manager.
                         Iconifying this window causes all children to
                         be concealed.

                         A tool maintains a list of packages that  are
                         searched when looking for partially-specified
                         PO's.  It contains built-in PO's such as dia-
                         log  boxes  to  prompt  for a file name or to
                         confirm a destructive operation used  by  all
                         PICASSO applications.

                         _____________________________________________

          CREATION


                         A macro named deftool is provided to define a
                         tool.  The syntax of a call to this macro is:

                     (deftool _t_o_o_l-_n_a_m_e (_a_r_g_u_m_e_n_t_s)

                                                               [_M_a_c_r_o]
                         ;; optional clauses
                         "<_d_o_c_u_m_e_n_t_a_t_i_o_n _s_t_r_i_n_g>"
                         (_t_i_t_l_e _s_t_r_i_n_g)
                         (_f_r_a_m_e_s _p_o-_s_p_e_c_s)
                         (_d_i_a_l_o_g_s _p_o-_s_p_e_c_s)
                         (_p_a_n_e_l_s _p_o-_s_p_e_c_s)
                         (_p_a_c_k_a_g_e-_s_e_a_r_c_h-_l_i_s_t _s_t_r_i_n_g-_l_i_s_t)
                         (_s_t_a_t_i_c-_v_a_r_i_a_b_l_e_s _v_a_r-_s_p_e_c)
                         (_d_y_n_a_m_i_c-_v_a_r_i_a_b_l_e_s _v_a_r-_s_p_e_c)
                         (_c_o_n_s_t_a_n_t_s _v_a_r-_s_p_e_c)



          PICASSO Reference Manual                                4-52







                                                 APPLICATION FRAMEWORK


                         (_s_t_a_r_t-_f_r_a_m_e _p_o-_r_e_f_e_r_e_n_c_e)
                         (_s_t_a_r_t-_f_r_a_m_e-_a_r_g_s _v_a_r-_s_p_e_c)
                         (_i_n_i_t-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_e_x_i_t-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_s_e_t_u_p-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_r_e_g_i_o_n _s_i_z_e-_s_p_e_c)
                         (_x _x-_o_f_f_s_e_t)
                         (_y _y-_o_f_f_s_e_t)
                         (_w _w_i_d_t_h)
                         (_h _h_e_i_g_h_t)
                         (_s_i_z_e _a_r_e_a)
                         (_l_o_c_a_t_i_o_n _l_o_c)
                         (_a_u_t_o_r_a_i_s_e _t)
                         (_a_u_t_o_w_a_r_p _t)
                         (_i_c_o_n _i_c_o_n-_s_p_e_c)
                         (_i_c_o_n-_n_a_m_e _s_t_r_i_n_g))
                         The _t_o_o_l-_n_a_m_e is a PO name  as  discussed  in
                         the  section  on  PO  naming.   The _a_r_g_u_m_e_n_t_s
                         specify the  name  and  an  optional  default
                         value  for  each argument to the tool.  Argu-
                         ment names are symbols and the default  value
                         can  be an arbitrary LISP form.  The documen-
                         tation string and the other  tool  definition
                         clauses  specified in the body of the deftool
                         _m_a_c_r_o _a_r_e _o_p_t_i_o_n_a_l, _a_n_d _c_a_n _b_e  _s_p_e_c_i_f_i_e_d  _i_n
                         _a_n_y   _o_r_d_e_r.   _E_a_c_h   _o_f  _t_h_e_s_e  _c_l_a_u_s_e_s  _a_r_e
                         _d_e_s_c_r_i_b_e_d _b_e_l_o_w _a_f_t_e_r _t_h_e  _f_o_l_l_o_w_i_n_g  _e_x_a_m_p_l_e
                         _t_o_o_l _d_e_f_i_n_i_t_i_o_n.

                         _____________________________________________

          EXAMPLE


                         For example, the following is a definition of
                         a tool that calls a dialog to prompt the user
                         for her name when  she  runs  the  tool,  and
                         calls a panel to bring a goodbye message when
                         she  exits  the  tool.  The  #!  format   for
                         referencing  variables is described in detail
                         in Chapter 6: PICASSO Data Model.
















          PICASSO Reference Manual                                4-53







                                                 APPLICATION FRAMEWORK



                       (deftool ("demo-tool" "demo" . "tool") ((user nil))
                          "This is a simple demonstration tool"
                          (title "Demonstration tool")
                          (constants ((ask-string "What do you think")
                                      (bye-string "Its been fun. See you later"))))
                          (static-variables (talk-string "")
                                            (picture (make-graphic ....)))
                          (frames (f1 ("demo" . "frame"))
                                  (f2 ("vip" "demo" . "frame)))
                          (start-frame f2)
                          (dialogs (str-prompter ("str-prompter" . "dialog)))
                          (panels (msg-panel ("msg-panel" . "panel")))
                          (package-search-list ("demo-tool" "vip"))
                          (region '(300 500 100 200))
                          (init-code
                           (progn
                            (when (null #!user)
                                  (setf #!user (call #!str-prompter :prompt "Name?:"))
                                  (if (null #!user) (setf #!user "mysterious")))))
                          (exit-code
                            (call #!msg-panel :message #!talk-string))
                          (setup-code
                           (progn
                            (bind-var #!talk-string `(concatenate 'string
                                                                  #!bye-string
                                                                  ", "
                                                                  (var #!user))))))


                         This tool  uses  two  constants,  two  static
                         variables, two frames (the second of which is
                         called as initial startup frame), one  dialog
                         box and one panel. It also prepends two pack-
                         ages to the package  search  list,  specifies
                         the  tool  window region, and specifies LISP-
                         forms that should be  run  before  the  first
                         frame  is called (init-code), before the tool
                         exits (exit-code), and when the  tool  PO  is
                         created (setup-code).

                         _____________________________________________

          OPTIONAL
          CLAUSES



                         The title clause specifies a string  that  is
                         displayed  in the title bar of the tool.  The
                         default title is ``A Picasso Tool''.

                         The  frames,  dialogs,  and  panels   clauses
                         specify  the  PO's  that are used by the tool
                         and binds them to PICASSO constant names.   A
                         _p_o-_s_p_e_c  is  a  list  of  bindings of PO's to



          PICASSO Reference Manual                                4-54







                                                 APPLICATION FRAMEWORK


                         constant names.  Each binding is a list  with
                         the name of the constant and either a PO name
                         or a LISP form that evaluates to a  PO.   For
                         example, the clause


                          (frames (f1 ("demo" . "frame"))
                                  (f2 ("vip" "demo" . "frame)))


                         in the preceding example binds two frames  to
                         the  variables  f1 _a_n_d _f_2, specified by name.
                         The bindings  established  in  these  clauses
                         cannot be changed at runtime.

                         The frames, dialogs, and  panels  clauses  do
                         not  have  to  list all objects referenced in
                         the tool, only those lexically bound  to  the
                         tool environment.  For example, an error mes-
                         sage dialog that is used  in  several  frames
                         should  be  bound  to the tool environment by
                         listing it in the _d_i_a_l_o_g_s clause so  that  it
                         can be shared.  Operationally, objects listed
                         in these clauses are loaded into the  PICASSO
                         runtime  environment  when  the  tool is run.
                         Tools that want to control when  objects  are
                         loaded  or  that want to vary objects dynami-
                         cally can do so by assigning them  to  static
                         or   dynamic  variables.   The  find-po-named
                         function can be used  to  fetch  the  desired
                         object.

                         The  package-search-list  clause  lists   the
                         packages  that  should  be  prepended  to the
                         current package search list when the tool  is
                         run.   After  these packages are prepended to
                         the list, the tool package  is  prepended  to
                         it.

                         The static-variables, dynamic-variables,  and
                         constants  clauses declare PICASSO variables,
                         as discussed in Chapter  6.   _V_a_r-_s_p_e_c  is  a
                         list  of  variable  declarations that specify
                         the name and default value for each variable.
                         The clause


                          (static-variables (talk-string "")
                                            (picture (make-graphic <_s_p_e_c>)))


                         in the example definition defines two  static



          PICASSO Reference Manual                                4-55







                                                 APPLICATION FRAMEWORK


                         variables   talk-string  _a_n_d  _p_i_c_t_u_r_e,  whose
                         default values  are  ""  _a_n_d  _t_h_e  _r_e_s_u_l_t  _o_f
                         _e_v_a_l_u_a_t_i_n_g  _t_h_e  _L_I_S_P  (_m_a_k_e-_g_r_a_p_h_i_c <_s_p_e_c>),
                         _r_e_s_p_e_c_t_i_v_e_l_y.  _V_a_r_i_a_b_l_e_s _c_a_n _a_l_s_o _b_e _d_e_c_l_a_r_e_d
                         _w_i_t_h_o_u_t  _s_p_e_c_i_f_y_i_n_g  _a  _d_e_f_a_u_l_t  _v_a_r_i_a_b_l_e  _a_s
                         _s_h_o_w_n _f_o_r _u and w _i_n


                          (_d_y_n_a_m_i_c-_v_a_r_i_a_b_l_e_s     _u
                                                 (_v '(_x _y _z))
                                                 _w)



                         The start-frame _c_l_a_u_s_e _s_p_e_c_i_f_i_e_s _t_h_e _f_r_a_m_e _t_o
                         _c_a_l_l  _w_h_e_n  _t_h_e _t_o_o_l _i_s _r_u_n. _s_t_a_r_t-_f_r_a_m_e-_a_r_g_s
                         specifies the arguments to be passed  to  the
                         start-frame  _w_h_e_n _i_t _i_s _c_a_l_l_e_d.  _T_h_e _f_r_a_m_e _f_2
                         is specified as the start-frame _i_n _t_h_e  _g_i_v_e_n
                         _e_x_a_m_p_l_e.  _T_h_e _a_r_g_u_m_e_n_t _t_o _t_h_i_s _c_l_a_u_s_e _m_u_s_t _b_e
                         _a _p_o-_r_e_f_e_r_e_n_c_e,_w_h_i_c_h _i_s _e_i_t_h_e_r _a _v_a_r_i_a_b_l_e  _t_o
                         _w_h_i_c_h  _a  _f_r_a_m_e  _i_s _b_o_u_n_d _o_r _a _L_I_S_P _f_o_r_m _t_h_a_t
                         _e_v_a_l_u_a_t_e_s _t_o _a _f_r_a_m_e.  _I_f _a  _s_t_a_r_t  _f_r_a_m_e  _i_s
                         _n_o_t  _s_p_e_c_i_f_i_e_d _i_n _t_h_e _d_e_f_t_o_o_l _d_e_f_i_n_i_t_i_o_n, _t_h_e
                         _f_i_r_s_t _f_r_a_m_e _l_i_s_t_e_d _i_n _t_h_e  _f_r_a_m_e_s  _c_l_a_u_s_e  _i_s
                         _c_a_l_l_e_d _w_h_e_n _t_h_e _t_o_o_l _i_s _r_u_n.  _T_h_e _s_t_a_r_t _f_r_a_m_e
                         _a_n_d _s_t_a_r_t _f_r_a_m_e _a_r_g_u_m_e_n_t_s _c_a_n _a_l_s_o _b_e _s_e_t  _o_r
                         _c_h_a_n_g_e_d  _w_h_e_n _a _t_o_o_l _i_s _r_u_n (_s_e_e _t_h_e run-tool
                         _f_u_n_c_t_i_o_n _b_e_l_o_w)

                         The init-code _a_n_d _e_x_i_t-_c_o_d_e  clauses  specify
                         LISP  forms  that  should  be  run before the
                         first frame is called  and  before  the  tool
                         exits.   init-code  _c_a_n _b_e _u_s_e_d _t_o _i_n_i_t_i_a_l_i_z_e
                         _v_a_r_i_a_b_l_e_s _t_h_a_t _a_r_e _g_l_o_b_a_l  _t_o  _t_h_e  _t_o_o_l,  _t_o
                         _o_p_e_n  _s_y_s_t_e_m  _r_e_s_o_u_r_c_e_s (_e._g., _f_i_l_e_s), _a_n_d _t_o
                         _c_h_a_n_g_e _t_h_e _s_t_a_r_t _f_r_a_m_e. _I_n _t_h_e _e_x_a_m_p_l_e _a_b_o_v_e,
                         _t_h_e  _i_n_i_t-_c_o_d_e is used to initialize the user
                         _v_a_r_i_a_b_l_e _t_o _t_h_e  _u_s_e_r'_s  _n_a_m_e.  _e_x_i_t-_c_o_d_e  is
                         often  used  to  clean  up before the tool is
                         exited. In the example above,  the  exit-code
                         _i_s  _u_s_e_d  _t_o  _c_a_l_l  _a  _p_a_n_e_l _w_h_i_c_h _d_i_s_p_l_a_y_s _a
                         _g_o_o_d_b_y_e _m_e_s_s_a_g_e _t_o _t_h_e _u_s_e_r.  _T_h_e  _s_e_t_u_p-_c_o_d_e
                         clause specifies

                         LISP forms that should be run  upon  entering
                         the  tool.   In the example above, the setup-
                         code _i_s _u_s_e_d _t_o  _i_n_i_t_i_a_l_i_z_e  _t_h_e  _t_a_l_k-_s_t_r_i_n_g
                         variable to a personalized goodbye message.

                         A  region  defines  the  origin,  width,  and
                         height of the tool window.  The origin is the



          PICASSO Reference Manual                                4-56







                                                 APPLICATION FRAMEWORK


                         upper left corner of the window in the screen
                         coordinate  system.  The screen origin is the
                         upper left corner of the screen.  The  x-axis
                         runs  across  the  screen, left to right, and
                         the y-axis runs down the screen, top to  bot-
                         tom.  The region specification is a list with
                         4   elements:   x-coordinate,   y-coordinate,
                         width,  and  height.  For example, the region
                         clause in the given example  defines  a  tool
                         that  is  100 pixels wide and 200 pixels high
                         positioned at location (300, 500):


                          (region '(300 500 100 200))


                         The x-coordinate,  y-coordinate,  width,  and
                         height  can  all be be specified individually
                         using  the  x-offset,  y-offset,  width,  and
                         height  clauses,  respectively.  For example,
                         the   previous   region   specification    is
                         equivalent to


                          (x-offset 300)
                          (y-offset 500)
                          (width 100)
                          (height 200)


                         The  location  and  size   clauses   indicate
                         'pieces'    of    regions,   where   location
                         corresponds to x  and  y  offsets,  and  size
                         corresponds  to  width and height.  For exam-
                         ple, the  previous  region  specification  is
                         also equivalent to


                          (location '(300 500))
                          (size '(100 200)


                         The tool is centered on  the  screen  with  a
                         reasonable  window  size  by default if these
                         clauses are not supplied.

                         The icon clause specifies the bitmap or  pix-
                         map  that  will be displayed when the tool is
                         hidden.  The _i_c_o_n-_s_p_e_c is either the name  of
                         a  file that contains the bitmap or pixmap or
                         a LISP form that returns an icon object  when
                         executed.  The icon-name _s_p_e_c_i_f_i_e_s _t_h_e _s_t_r_i_n_g



          PICASSO Reference Manual                                4-57







                                                 APPLICATION FRAMEWORK


                         _t_o _b_e _d_i_s_p_l_a_y_e_d _w_i_t_h _t_h_e _i_c_o_n.

                         autoraise _s_p_e_c_i_f_i_e_s _w_h_e_t_h_e_r _t_h_e  _t_o_o_l  _w_i_n_d_o_w
                         _i_s _a_u_t_o_m_a_t_i_c_a_l_l_y _r_a_i_s_e_d _b_y _t_h_e _w_i_n_d_o_w _m_a_n_a_g_e_r
                         _w_h_e_n _t_h_e _m_o_u_s_e _e_n_t_e_r_s _i_t _a_n_d _a_u_t_o_w_a_r_p  speci-
                         fies  whether  the  mouse cursor is automati-
                         cally  moved  into  the  tool  window  (i.e.,
                         warped)  when  the  tool  is deiconified. The
                         default setting for both slots is true.

                         _____________________________________________

          MANAGING
          TOOLS



                         Tools are a subclass of  collection  widgets,
                         thus they inherit the methods defined on col-
                         lection widgets. In addition,  the  following
                         are also defined on tools.

                     current-tool

                                                               [_M_a_c_r_o]
                         Return the current tool object.

                     ret-tool

                                                               [_M_a_c_r_o]
                         &optional
                         (_r_e_t_u_r_n-_v_a_l_u_e _n_i_l)
                         Exit the currently running tool.

                     run-tool

                                                               [_M_a_c_r_o]
                         _t_o_o_l
                         &key
                         _s_t_a_r_t-_f_r_a_m_e
                         (_s_t_a_r_t-_f_r_a_m_e-_a_r_g_s _n_i_l)
                         Load the named tool, if it  has  not  already
                         been  loaded,  and  run it.  Change the start
                         frame of the  tool  to  _s_t_a_r_t-_f_r_a_m_e  and  the
                         start  frame arguments to _s_t_a_r_t-_f_r_a_m_e-_a_r_g_s if
                         specified when the tool is run.

                     run-tool-named

                                                               [_M_a_c_r_o]
                         _n_a_m_e
                         &key
                         _s_t_a_r_t-_f_r_a_m_e
                         (_s_t_a_r_t-_f_r_a_m_e-_a_r_g_s _n_i_l)
                         Given a _n_a_m_e in the format (pkg name  .  suf-
                         fix),  _t_h_i_s  _m_a_c_r_o  _i_s  _s_i_m_i_l_a_r  _t_o run-tool,
                         _e_x_c_e_p_t _t_h_a_t _i_t _f_i_n_d_s _t_h_e _P_O _n_a_m_e_d _n_a_m_e _f_i_r_s_t,
                         _t_h_e_n _l_o_a_d_s _a_n_d _r_u_n_s _i_t.

                     tool-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Return t _i_f _o_b_j_e_c_t _i_s _a _t_o_o_l _o_b_j_e_c_t, _n_i_l _o_t_h_-





          PICASSO Reference Manual                                4-58







                                                 APPLICATION FRAMEWORK


                         _e_r_w_i_s_e.

                         _____________________________________________

          TOOL SUM-
          MARY







                                         ________________
                                          Tool Macros
                                         ________________________________
                                          current-tool
                                          deftool
                                          ret-tool
                                          run-tool
                                          run-tool-named
                                          tool-p
                                         ________________

                                        |
                                        |
                                        |
                                        |
                                        |
                                        |
                                        |
                                        |
                                        |







                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |










          ____________________________________________________________________________________________________________________________________________________________________________________

          Forms


                         Forms are used in frames, panels,  or  dialog
                         boxes.   A  form  that  can be reused in more
                         than one PO, called an explicit or  _p_l_u_g_g_a_b_l_e
                         _f_o_r_m, is defined using the defform _c_o_n_s_t_r_u_c_t.
                         _P_l_u_g_g_a_b_l_e _f_o_r_m_s _t_y_p_i_c_a_l_l_y  _h_a_v_e  _l_o_c_a_l  _v_a_r_i_-
                         _a_b_l_e_s  _a_n_d  _p_a_r_a_m_e_t_e_r_s _a_n_d, _l_i_k_e _a_n_y _P_O, _t_h_e_y
                         _m_a_y  _h_a_v_e  _i_n_i_t_i_a_l_i_z_a_t_i_o_n   _a_n_d   _t_e_r_m_i_n_a_t_i_o_n
                         _c_l_a_u_s_e_s _t_h_a_t _s_p_e_c_i_f_y _c_o_d_e _t_o _b_e _e_x_e_c_u_t_e_d _w_h_e_n
                         _t_h_e _P_O _t_h_a_t _h_o_l_d_s  _t_h_e  _f_o_r_m  _i_s  _c_a_l_l_e_d  _a_n_d
                         _e_x_i_t_e_d, _r_e_s_p_e_c_t_i_v_e_l_y.

                         Sometimes forms are only  used  in  a  single
                         frame,  panel, or dialog box.  It complicates
                         the   application   specification   if    the
                         developer  has  to  create a separately named
                         form, so the developer can specify the  chil-
                         dren  and  other form clauses directly in the
                         frame, panel  or  dialog  box  specification.
                         These  forms  are  called  _i_m_p_l_i_c_i_t _f_o_r_m_s and
                         they cannot have local variables  or  parame-
                         ters.   They  can,  however, access variables
                         and  parameters  in  their  lexical   parent.
                         Implicit  forms  are  specified  in the forms
                         _c_l_a_u_s_e _b_y _d_e_f_i_n_i_n_g _t_h_e  _w_i_d_g_e_t_s  _a_n_d  _g_a_d_g_e_t_s
                         _t_h_a_t  _a_r_e _c_o_n_t_a_i_n_e_d _i_n _t_h_e _f_o_r_m.  _T_h_e _p_o-_s_p_e_c
                         _t_h_a_t _s_p_e_c_i_f_i_e_s _t_h_e _f_o_r_m_s _i_s _a _l_i_s_t _w_h_i_c_h _c_o_n_-
                         _t_a_i_n_s  _a  _v_a_r_i_a_b_l_e _n_a_m_e _a_n_d _a _f_o_r_m _s_p_e_c_i_f_i_c_a_-
                         _t_i_o_n.  _P_l_u_g_g_a_b_l_e _f_o_r_m_s _a_r_e _s_p_e_c_i_f_i_e_d _b_y _t_h_e_i_r



          PICASSO Reference Manual                                4-59







                                                 APPLICATION FRAMEWORK


                         _e_x_t_e_r_n_a_l  _n_a_m_e.  _F_o_r_m_s _i_n _f_r_a_m_e_s, _p_a_n_e_l_s, _a_n_d
                         _d_i_a_l_o_g _b_o_x _P_O'_s _a_r_e  _d_e_c_l_a_r_e_d  _e_i_t_h_e_r  _e_x_p_l_i_-
                         _c_i_t_l_y  _o_r  _i_m_p_l_i_c_i_t_l_y  (_n_o_t _b_o_t_h) _s_i_n_c_e _t_h_e_s_e
                         _P_O'_s _e_a_c_h _m_a_y _c_o_n_t_a_i_n _a_t _m_o_s_t _o_n_e _f_o_r_m.

                         An example of a forms specification is


                          (form (f1 "emp"))


                         The variable  f1  _i_s  _b_o_u_n_d  _t_o  _a_n  _e_x_t_e_r_n_a_l
                         _p_l_u_g_g_a_b_l_e _f_o_r_m _n_a_m_e_d ``_e_m_p'' .  Frame, panel,
                         and dialog box PO's have only one form.

                         _____________________________________________

          CREATION


                         The  macro  defform  is  provided  to  define
                         forms.   The  syntax  of a call to this macro
                         is:

                     (defform _n_a_m_e (_a_r_g_u_m_e_n_t_s)

                                                               [_M_a_c_r_o]
                         ;; optional clauses
                         (_c_h_i_l_d_r_e_n _c_o_m_p_o_n_e_n_t-_s_p_e_c_s)
                         (_g_m _g_e_o_m_e_t_r_y-_m_a_n_a_g_e_r-_s_p_e_c))
                         (_v_i_s_i_t-_o_r_d_e_r _p_o-_s_p_e_c)
                         (_s_e_l_e_c_t_a_b_l_e _p_o-_s_p_e_c)
                         ;; clauses common with tools
                         "<_d_o_c_u_m_e_n_t_a_t_i_o_n _s_t_r_i_n_g>"
                         (_s_t_a_t_i_c-_v_a_r_i_a_b_l_e_s _v_a_r-_s_p_e_c)
                         (_d_y_n_a_m_i_c-_v_a_r_i_a_b_l_e_s _v_a_r-_s_p_e_c)
                         (_c_o_n_s_t_a_n_t_s _v_a_r-_s_p_e_c)
                         (_i_n_i_t-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_e_x_i_t-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_s_e_t_u_p-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_d_i_a_l_o_g_s _p_o-_s_p_e_c)
                         (_p_a_n_e_l_s _p_o-_s_p_e_c))
                         The form _n_a_m_e is a PO name  as  discussed  in
                         the  section on PO naming.  _a_r_g_u_m_e_n_t_s specify
                         the name and an optional  default  value  for
                         each  argument  to  the form.  Argument names
                         are symbols and the default value can  be  an
                         arbitrary   LISP   form.   The  documentation
                         string and the other form definition  clauses
                         specified  in  the  body of the defform _m_a_c_r_o
                         _a_r_e _o_p_t_i_o_n_a_l, _a_n_d _c_a_n  _b_e  _s_p_e_c_i_f_i_e_d  _i_n  _a_n_y
                         _o_r_d_e_r.   _E_a_c_h  _o_f  _t_h_e_s_e _c_l_a_u_s_e_s _i_s _d_e_s_c_r_i_b_e_d
                         _b_e_l_o_w _a_f_t_e_r _t_h_e _f_o_l_l_o_w_i_n_g _e_x_a_m_p_l_e _f_o_r_m _d_e_f_i_n_-






          PICASSO Reference Manual                                4-60







                                                 APPLICATION FRAMEWORK


                         _i_t_i_o_n.

                         _____________________________________________

          EXAMPLE
          FORM



                         The following code  creates  a  form  with  a
                         label  ("Department  Information"), two entry
                         fields (one for a department name, one for  a
                         manager  name), and a table field (to display
                         the employees and  their  job  titles).   The
                         form has three arguments dname, mgr, and emps
                         that are bound to the three components in the
                         form.


                          (defform ("dept" . "form") (dname mgr emps)
                           (children
                           '((make-label
                                          :x-offset 50
                                          :y-offset 50
                                          :label "Department Information"))
                             (dep (make-entry-field
                                          :x-offset 5
                                          :y-offset 75
                                          :nchars 20
                                          :label "Dept Name:"))
                             (man (make-entry-field
                                          :x-offset 5
                                          :y-offset 100
                                          :nchars 20
                                          :label "Manager:"))
                             (emp (make-table-field
                                          :x-offset 5
                                          :y-offset 125
                                          :col-elements
                                          '((make-entry-field
                                                  :x-offset 0
                                                  :y-offset 0
                                                  :nchars 20)
                                            (make-entry-field
                                                  :x-offset 0
                                                  :y-offset 0
                                                  :nchars 30))
                                          :col-titles '("Name" "Job Title")
                                          :label "Employees")))
                            (setup-code
                              (progn
                                 (bind-slot 'value #!dep #!dname)
                                 (bind-slot 'value #!man #!mgr)
                                 (bind-slot 'value #!emp #!emps))))





          PICASSO Reference Manual                                4-61







                                                 APPLICATION FRAMEWORK


                         _____________________________________________

          OPTIONAL
          CLAUSES



                         The static-variables, dynamic-variables, con-
                         stants,  init-code,  exit-code,  dialogs  and
                         panels clauses are  the  same  as  in  tools.
                         Components  of  forms can either be specified
                         explicitly (with the dialog or panel clauses)
                         or  implicitly  (with  the  children  and  gm
                         clauses).  Each children component is  either
                         a  gadget  or  a  widget,  and  the gadget or
                         widget can be bound to a PICASSO variable  so
                         that  the  init-code  or a menu operation can
                         access the component.   Gadgets  and  widgets
                         are described in later chapters.

                         Components in a form are specified using  the
                         children  clause.  These  components  can  be
                         assigned to PICASSO variables by specifying a
                         symbol  before the component definition.  For
                         example, the _c_o_m_p_o_n_e_n_t _s_p_e_c


                          (dep (make-entry-field
                                       :x-offset 5
                                       :y-offset 75
                                       :nchars 20
                                       :label "Dept Name:"))


                         in the example binds the entry field  in  the
                         department  form  to  the  variable dep.  _T_h_e
                         _e_n_t_r_y _f_i_e_l_d _o_b_j_e_c_t _c_a_n  _b_e  _a_c_c_e_s_s_e_d  _b_y  _t_h_e
                         _e_x_p_r_e_s_s_i_o_n !#_d_e_p, as discussed in Chapter 6.

                         The position of a component within an enclos-
                         ing form, dialog, or panel is specified as an
                         _x-_o_f_f_s_e_t and  _y-_o_f_f_s_e_t  from  the  upper-left
                         corner   of   the  enclosing  object.   These
                         offsets specify the distance from the  upper-
                         left  corner  of  the component to the upper-
                         left corner of the enclosing object.

                         The gm clause specifies the geometry  manager
                         which  lays  out the widgets in the form. The
                         PICASSO interface toolkit provides a  variety
                         of   geometry  managers  including  one  that
                         repacks the components to fill the  available
                         area  (_p_a_c_k_e_d-_g_m)  and  one  that resizes the
                         components in proportion to the change in the
                         tool  window  (_r_u_b_b_e_r-_g_m).   Rubber-gm is the
                         default geometry manager for forms.  Geometry



          PICASSO Reference Manual                                4-62







                                                 APPLICATION FRAMEWORK


                         managers are discussed in detail in Chapter 8
                         on Collections.

                         The visit-order clause can be used to specify
                         the  order  in which the widgets in the order
                         are visited in the form.  the  tab  (^N)  and
                         shift-tab  (^P) keys can then be used to more
                         forwards and backwards, respectively, to  the
                         specified  widgets.  The _p_o-_s_p_e_c is a list of
                         bindings of  PO's  to  constant  names  (e.g.
                         '(#!wid1  #!wid2  #!wid3)),  _t_h_e  _f_i_r_s_t _b_e_i_n_g
                         _w_h_e_r_e _t_h_e _f_o_c_u_s _s_t_a_r_t_s _w_h_e_n _t_h_e _f_o_r_m _i_s _f_i_r_s_t
                         _c_a_l_l_e_d.

                         The selectable _c_l_a_u_s_e _s_p_e_c_i_f_i_e_s  _t_h_e  _w_i_d_g_e_t_s
                         (_s_p_e_c_i_f_i_e_d _a_s _a _l_i_s_t _o_f _b_i_n_d_i_n_g_s _o_f _P_O _n_a_m_e_s)
                         _t_h_a_t _c_a_n _b_e _s_e_l_e_c_t_e_d _w_i_t_h  _t_h_e  _l_e_f_t  _b_u_t_t_o_n.
                         _B_u_t_t_o_n_i_n_g  _a  _s_e_l_e_c_t_a_b_l_e  _w_i_d_g_e_t  _t_h_a_t _i_s _n_o_t
                         _a_l_r_e_a_d_y _s_e_l_e_c_t_e_d  _s_e_l_e_c_t_s  _i_t;  _b_u_t_t_o_n_i_n_g  _a_n
                         _a_l_r_e_a_d_y _s_e_l_e_c_t_e_d _s_e_l_e_c_t_a_b_l_e _w_i_d_g_e_t _c_a_u_s_e_s _t_h_e
                         _e_x_i_s_t_i_n_g _s_e_l_e_c_t_i_o_n _h_a_n_d_l_e_r _t_o _b_e _c_a_l_l_e_d.

                         _____________________________________________

          MANAGING
          FORMS



                         Forms are a subclass of  collection  widgets,
                         thus they inherit the methods defined on col-
                         lection widgets. In addition,  the  following
                         are also defined on forms.

                     current-field

                                                            [_A_c_c_e_s_s_o_r]
                         &optional
                         _f_o_r_m
                         The current selected field or nil _i_f _n_o _f_i_e_l_d
                         _i_s _s_e_l_e_c_t_e_d.  _T_h_i_s _v_a_l_u_e _m_a_y _b_e _s_e_t_f'd.

                     form-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Return t _i_f _o_b_j_e_c_t _i_s _a _f_o_r_m _o_b_j_e_c_t, _n_i_l _o_t_h_-
                         _e_r_w_i_s_e.

                     ret-form

                                                               [_M_a_c_r_o]
                         &optional
                         (_r_e_t_u_r_n-_v_a_l_u_e _n_i_l)
                         Exit the current form

                         _____________________________________________

          FORM SUM-
          MARY









          PICASSO Reference Manual                                4-63







                                                 APPLICATION FRAMEWORK



                                      ______________________
                                       Form macros/methods
                                      ____________________________________________
                                       defform
                                       current-field
                                       (setf current-field)
                                       form-p
                                       ret-form
                                      ______________________

                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |
                                     |






                                                           |
                                                           |
                                                           |
                                                           |
                                                           |
                                                           |
                                                           |
                                                           |









          ____________________________________________________________________________________________________________________________________________________________________________________

          Callable
          PO's



                         Frames, dialog boxes, and panels are callable
                         PO's.   Callable  PO's have forms that can be
                         implicit or explicit, as well as buttons  and
                         menus.  They are typically called in response
                         to a user action (e.g., a menu  selection  or
                         button  press).   The  syntax of a call is as
                         follows:


                          (call <_p_o> :arg-1 _v_a_l_u_e :arg-2 _v_a_l_u_e
                           ...)


                         The _P_O is specified  by  an  expression  that
                         evaluates  to  reference  to  the appropriate
                         PICASSO object.  The  expression  is  usually
                         the  internal PO name.  Parameters are passed
                         using Lisp keyword/value pairs.  For conveni-
                         ence,  there are also specific call-<_p_o> mac-
                         ros for each callable PO  type  (e.g.   call-
                         frame).

                         The semantics of calling a PO are:

                         (1)  Fetch the PO from the database, if it is
                              not already in memory.

                         (2)  Bind the actual arguments to the  formal
                              arguments.

                         (3)  Allocate and initialize local variables.

                         (4)  Fetch the lexical  children  of  the  PO
                              (e.g., forms, frames, etc.), if they are
                              not already in memory.





          PICASSO Reference Manual                                4-64







                                                 APPLICATION FRAMEWORK


                         (5)  Execute the init-code for the PO.

                         (6)  Display the object on the screen.

                         (7)  Enter an event loop.

                         PO's are cached in main memory to  avoid  the
                         delays  inherent  in  accessing the database.
                         Lexical children are fetched when the  PO  is
                         called  to  improve the performance of subse-
                         quent calls.  Dynamic variables are allocated
                         on  each  call and static variables are allo-
                         cated when the PO is created.  The event loop
                         dispatches all events (e.g., mouse, keyboard,
                         redraw,  etc.)  to  the   appropriate   event
                         handlers.

                         The following code is executed to return from
                         a PO:


                          (ret <_p_o> _o_p_t_i_o_n_a_l-_r_e_t_u_r_n-_v_a_l_u_e)


                         For  convenience,  there  are  also  specific
                         ret-<_p_o>  macros  for  each  callable PO type
                         (e.g.  ret-frame).  _T_h_i_s _c_o_d_e _i_s _e_x_e_c_u_t_e_d  _i_n
                         _r_e_s_p_o_n_s_e  _t_o  _a  _u_s_e_r  _a_c_t_i_o_n  (_e._g.,  _a _m_e_n_u
                         _s_e_l_e_c_t_i_o_n _o_r _b_u_t_t_o_n _p_r_e_s_s) _o_r _b_e_c_a_u_s_e _a _l_e_x_i_-
                         _c_a_l _p_a_r_e_n_t _i_s _c_l_e_a_n_i_n_g _u_p _i_t_s _c_h_i_l_d_r_e_n _b_e_f_o_r_e
                         _e_x_i_t_i_n_g.  _T_h_e _s_e_m_a_n_t_i_c_s _o_f _r_e_t_u_r_n_i_n_g  _f_r_o_m  _a
                         _P_O _a_r_e:

                         (1)  Force active lexical children to execute
                              a return.

                         (2)  Execute the exit-code.

                         (3)  Conceal the  PO,  erasing  it  from  the
                              screen.

                         (4)  Copy any result arguments  back  to  the
                              actual arguments.

                         (5)  Re-enter the event loop of  the  calling
                              PO.

                         The remainder of this section  describes  how







          PICASSO Reference Manual                                4-65







                                                 APPLICATION FRAMEWORK


                         callable PO's are defined.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Frames


                         A frame can specify a named form or a set  of
                         children  widgets  through which data will be
                         displayed to the user.  Variables defined  in
                         the  frame, called _f_r_a_m_e _v_a_r_i_a_b_l_e_s, store the
                         data on which the  frame  operates.  A  frame
                         treats  the  variables  in its forms, panels,
                         and dialogs as if they were at the same lexi-
                         cal level. Forms, panels, and dialog boxes in
                         the frame can access this data by referencing
                         the  frame  variables; alternately, the frame
                         can pass data to them as arguments. This sec-
                         tion  describes the functions and macros pro-
                         vided to create and manage frames.

                         _____________________________________________

          CREATION


                         The macro  defframe  is  provided  to  define
                         frames.   The  syntax of a call to this macro
                         is:

                     (defframe _n_a_m_e (_a_r_g_u_m_e_n_t_s)

                                                               [_M_a_c_r_o]
                         ;; optional clauses
                         (_f_o_r_m _p_o-_s_p_e_c)
                         (_f_o_r_m-_a_r_g_s _v_a_r-_s_p_e_c)
                         (_m_e_n_u _m_e_n_u-_b_a_r-_s_p_e_c)
                         ;; clauses common with tools and/or forms
                         "<_d_o_c_u_m_e_n_t_a_t_i_o_n _s_t_r_i_n_g>"
                         (_s_t_a_t_i_c-_v_a_r_i_a_b_l_e_s _v_a_r-_s_p_e_c)
                         (_d_y_n_a_m_i_c-_v_a_r_i_a_b_l_e_s _v_a_r-_s_p_e_c)
                         (_c_o_n_s_t_a_n_t_s _v_a_r-_s_p_e_c)
                         (_i_n_i_t-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_e_x_i_t-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_s_e_t_u_p-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_d_i_a_l_o_g_s _p_o-_s_p_e_c)
                         (_p_a_n_e_l_s _p_o-_s_p_e_c)
                         (_c_h_i_l_d_r_e_n _c_o_m_p_o_n_e_n_t-_s_p_e_c_s)
                         (_g_m _g_e_o_m_e_t_r_y-_m_a_n_a_g_e_r-_s_p_e_c))
                         (_v_i_s_i_t-_o_r_d_e_r _p_o-_s_p_e_c)
                         (_s_e_l_e_c_t_a_b_l_e _p_o-_s_p_e_c)
                         The frame _n_a_m_e is a PO name as  discussed  in
                         the  section on PO naming.  _a_r_g_u_m_e_n_t_s specify
                         the name and an optional  default  value  for
                         each  argument  to the frame.  Argument names
                         are symbols and the default value can  be  an
                         arbitrary   LISP   form.   The  documentation
                         string and the other frame definition clauses
                         specified  in  the body of the defframe _m_a_c_r_o



          PICASSO Reference Manual                                4-66







                                                 APPLICATION FRAMEWORK


                         _a_r_e _o_p_t_i_o_n_a_l, _a_n_d _c_a_n  _b_e  _s_p_e_c_i_f_i_e_d  _i_n  _a_n_y
                         _o_r_d_e_r.

                         _____________________________________________

          OPTIONAL
          CLAUSES



                         The static-variables, dynamic-variables, con-
                         stants,   init-code,  exit-code,  setup-code,
                         dialogs, panels,  children,  gm,  visit-order
                         and  selectable clauses are the same as those
                         defined in the deftool  and  defform  macros.
                         The  frames  clause is not included because a
                         frame cannot be lexically  bound  to  another
                         frame.

                         The form clause lists the form that  is  used
                         by  this  frame,  and the form-args specifies
                         the arguments passed to the form when  it  is
                         called.

                         The menu clause specifies the menus and  menu
                         entries.   The  menu  bar  of  the  frame  is
                         defined by a _m_e_n_u-_b_a_r-_s_p_e_c which is a list of
                         menu pane specifications.  Each menu pane has
                         a name and a list of menu entries (i.e., menu
                         operations)  that  the  user  can execute.  A
                         menu entry specifies the entry name  and  the
                         code to be executed when the user selects the
                         entry.

                         For example, a menu bar specification  for  a
                         simple text editor might be


                          (("Edit" ("Cut" <_L_I_S_P-_f_o_r_m>)
                                   ("Paste"  <_L_I_S_P-_f_o_r_m>)
                                   ("Copy" <_L_I_S_P-_f_o_r_m>)
                                   ("Search" <_L_I_S_P-_f_o_r_m>))
                           ("File" ("Load" <_L_I_S_P-_f_o_r_m>)
                                   ("Save" <_L_I_S_P-_f_o_r_m>)
                                   ("File List" <_L_I_S_P-_f_o_r_m>)))


                         Optional arguments can  be  given  after  the
                         menu entry code to specify: 1) the entry font
                         (:font); 2) whether  the  entry  is  inactive
                         (:dimmed);  and  3)  values  of  the left and
                         right components (:left and :right).  See the
                         Menus  chapter  for  more information on menu






          PICASSO Reference Manual                                4-67







                                                 APPLICATION FRAMEWORK


                         specifications.

                         _____________________________________________

          MANAGING
          FRAMES



                         Frames are a subclass of collection  widgets,
                         thus they inherit the methods defined on col-
                         lection widgets. In addition,  the  following
                         methods   and  macros  are  also  defined  on
                         frames.

                     call-frame

                                                               [_M_a_c_r_o]
                         _f_r_a_m_e
                         &rest
                         _a_r_g_u_m_e_n_t_s
                         This function calls  the  named  frame.   The
                         name is either a variable or PO name.  Return
                         to the waiting caller when the  called  frame
                         closes.

                     current-frame

                                                               [_M_a_c_r_o]
                         Returns the current frame.

                     frame-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Return t _i_f _o_b_j_e_c_t _i_s  _a  _f_r_a_m_e  _o_b_j_e_c_t,  _n_i_l
                         _o_t_h_e_r_w_i_s_e.

                     goto-frame

                                                               [_M_a_c_r_o]
                         _f_r_a_m_e
                         &optional
                         _a_r_g_u_m_e_n_t_s
                         Closes the current  frame  and  goes  to  the
                         frame _f_r_a_m_e.

                     ret-frame

                                                               [_M_a_c_r_o]
                         &optional
                         (_r_e_t_u_r_n-_v_a_l_u_e _n_i_l)
                         Closes the current frame, and if there  is  a
                         waiting caller it is reactivated.

                     run-frame

                                                               [_M_a_c_r_o]
                         _f_r_a_m_e
                         &rest
                         _a_r_g_u_m_e_n_t_s
                         Same as call-frame

                         _____________________________________________

          FRAME SUM-
          MARY








          PICASSO Reference Manual                                4-68







                                                 APPLICATION FRAMEWORK



                                          _______________
                                           Frame Macros
                                          ______________________________
                                           call-frame
                                           current-frame
                                           defframe
                                           frame-p
                                           goto-frame
                                           ret-frame
                                           run-frame
                                          _______________

                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |








                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |











          ____________________________________________________________________________________________________________________________________________________________________________________

          Dialog
          Boxes



                         A dialog box is a modal interface object that
                         solicits  additional  arguments for an opera-
                         tion or user confirmation before executing  a
                         possibly   dangerous  action.   This  section
                         describes the functions  provided  to  create
                         and manage dialogs.

                         _____________________________________________

          CREATION


                         The macro  defdialog  defines  dialogs.   The
                         syntax of a call to this macro is:

                     (defdialog _n_a_m_e (_a_r_g_u_m_e_n_t_s)

                                                               [_M_a_c_r_o]
                         ;; optional clauses
                         (_b_u_t_t_o_n_s _b_u_t_t_o_n-_s_p_e_c)
                         (_a_t_t_a_c_h-_w_h_e_n-_p_o_s_s_i_b_l_e _t)
                         ;; clauses common with tools, forms, and/or frames
                         "<_d_o_c_u_m_e_n_t_a_t_i_o_n _s_t_r_i_n_g>"
                         (_s_t_a_t_i_c-_v_a_r_i_a_b_l_e_s _v_a_r-_s_p_e_c)
                         (_d_y_n_a_m_i_c-_v_a_r_i_a_b_l_e_s _v_a_r-_s_p_e_c)
                         (_c_o_n_s_t_a_n_t_s _v_a_r-_s_p_e_c)
                         (_i_n_i_t-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_e_x_i_t-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_s_e_t_u_p-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_d_i_a_l_o_g_s _p_o-_s_p_e_c)
                         (_p_a_n_e_l_s _p_o-_s_p_e_c)
                         (_f_o_r_m _p_o-_s_p_e_c)
                         (_f_o_r_m-_a_r_g_s _v_a_r-_s_p_e_c)
                         (_r_e_g_i_o_n _s_i_z_e-_s_p_e_c)
                         (_x _x-_o_f_f_s_e_t)
                         (_y _y-_o_f_f_s_e_t)
                         (_w _w_i_d_t_h)
                         (_h _h_e_i_g_h_t)
                         (_s_i_z_e _a_r_e_a)



          PICASSO Reference Manual                                4-69







                                                 APPLICATION FRAMEWORK


                         (_l_o_c_a_t_i_o_n _l_o_c)
                         (_a_u_t_o_r_a_i_s_e _t)
                         (_c_h_i_l_d_r_e_n _c_o_m_p_o_n_e_n_t-_s_p_e_c_s)
                         (_g_m _g_e_o_m_e_t_r_y-_m_a_n_a_g_e_r-_s_p_e_c))
                         (_v_i_s_i_t-_o_r_d_e_r _p_o-_s_p_e_c)
                         (_s_e_l_e_c_t_a_b_l_e _p_o-_s_p_e_c)
                         The dialog _n_a_m_e is a PO name as discussed  in
                         the  section on PO naming.  _a_r_g_u_m_e_n_t_s specify
                         the name and an optional  default  value  for
                         each  argument to the dialog.  Argument names
                         are symbols and the default value can  be  an
                         arbitrary   LISP   form.   The  documentation
                         string and the other  dialog  box  definition
                         clauses  specified in the body of the defdia-
                         log _m_a_c_r_o _a_r_e _o_p_t_i_o_n_a_l, _a_n_d _c_a_n _b_e  _s_p_e_c_i_f_i_e_d
                         _i_n _a_n_y _o_r_d_e_r.

                         _____________________________________________

          EXAMPLE
          DIALOG



                         The following example defines a  dialog  that
                         confirms that you want to delete a file.


                          (defdialog "delete file?" (filename)
                            "Confirm that the user wants to delete the file."
                            (dynamic-variables
                               (msg (format t "Are you sure you want to delete the file ~s~%"
                                           #!filename)))
                            (buttons (("OK" (ret-dialog t) :default)
                                      ("CANCEL" (ret-dialog :cancelled))))
                            (children (make-label
                                            :x-offset 20
                                            :y-offset 20
                                             :label #!msg)))


                         The variable msg contains the  string  to  be
                         displayed.  Two buttons are defined that con-
                         firm or cancel the  operation.   Notice  that
                         the  code  executed for either button returns
                         from the dialog to the caller and passes back
                         a  value  (t  or :cancelled) that either con-
                         firms or cancels the operation.

                         _____________________________________________

          OPTIONAL
          CLAUSES



                         The static-variables, dynamic-variables, con-
                         stants,   init-code,  exit-code,  setup-code,
                         dialogs, panels,  buttons,  form,  form-args,
                         region,   x,   y,   w,   h,  size,  location,



          PICASSO Reference Manual                                4-70







                                                 APPLICATION FRAMEWORK


                         autoraise,  children,  gm,  visit-order   and
                         selectable  clauses  are  the  same  as those
                         defined in the deftool and  deform  and  def-
                         frame macros.

                         The buttons clause specifies a list  of  but-
                         tons  that  will  be  arranged down the right
                         edge of the dialog.  A button is defined by a
                         list  that  specifies  the  button label, the
                         code to execute when the button is  selected,
                         and  optional button attributes.  The attach-
                         when-possible  clause  specifies  whether  to
                         attach  X  resources whenever possible (i.e.,
                         when the parent is called) rather  than  when
                         necessary  (i.e.,  when  the object itself is
                         called). By default, X resources are attached
                         when possible.

                         _____________________________________________

          MANAGING
          DIALOGS



                         Dialogs are a subclass of collection widgets,
                         thus they inherit the methods defined on col-
                         lection widgets. In addition,  the  following
                         are also defined on dialogs.

                     call-dialog

                                                               [_M_a_c_r_o]
                         _d_i_a_l_o_g
                         &rest
                         _a_r_g_u_m_e_n_t_s
                         This function calls the specified dialog.

                     current-dialog

                                                               [_M_a_c_r_o]
                         Returns the current dialog.

                     dialog-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Return t _i_f _o_b_j_e_c_t _i_s _a  _d_i_a_l_o_g  _o_b_j_e_c_t,  _n_i_l
                         _o_t_h_e_r_w_i_s_e.

                     ret-dialog

                                                               [_M_a_c_r_o]
                         &optional
                         (_r_e_t_u_r_n-_v_a_l_u_e _n_i_l)
                         This function returns from the dialog to  the
                         caller.   The  caller could be a frame opera-
                         tion, init- or exit-code, or code in  a  but-
                         ton.   The  optional  return  value is passed
                         back to the caller if specified.

                     run-dialog

                                                               [_M_a_c_r_o]
                         _d_i_a_l_o_g
                         &rest



          PICASSO Reference Manual                                4-71







                                                 APPLICATION FRAMEWORK


                         _a_r_g_u_m_e_n_t_s
                         Same as call-dialog

                         _____________________________________________

          DIALOG
          SUMMARY







                                         ________________
                                          Dialog Macros
                                         ________________________________
                                          call-dialog
                                          current-dialog
                                          defdialog
                                          dialog-p
                                          ret-dialog
                                          run-dialog
                                         ________________

                                        |
                                        |
                                        |
                                        |
                                        |
                                        |
                                        |
                                        |
                                        |







                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |










          ____________________________________________________________________________________________________________________________________________________________________________________

          Panels


                         Panels are typically used  to  present  addi-
                         tional  information or an alternative view of
                         the same information to the user.   They  are
                         non-modal  so  that the user can shift his or
                         her  attention  between  the  current   frame
                         displayed in the tool window and the panel(s)
                         currently visible.   This  section  describes
                         the  functions provided to define and operate
                         on panels.

                         _____________________________________________

          CREATION


                         The macro defpanel defines a panel.  The syn-
                         tax of a call to this macro is:

                     (defpanel _n_a_m_e (_a_r_g_u_m_e_n_t_s)

                                                               [_M_a_c_r_o]
                         ;; optional clauses
                         (_i_c_o_n_i_f_y-_f_u_n_c _n_i_l)
                         (deiconify-func nil)
                         ;; clauses common with tools, forms, frames, and/or dialog boxes
                         "<_d_o_c_u_m_e_n_t_a_t_i_o_n _s_t_r_i_n_g>"
                         (_t_i_t_l_e _s_t_r_i_n_g)
                         (_s_t_a_t_i_c-_v_a_r_i_a_b_l_e_s _v_a_r-_s_p_e_c)
                         (_d_y_n_a_m_i_c-_v_a_r_i_a_b_l_e_s _v_a_r-_s_p_e_c)
                         (_c_o_n_s_t_a_n_t_s _v_a_r-_s_p_e_c)
                         (_i_n_i_t-_c_o_d_e _L_I_S_P-_f_o_r_m)



          PICASSO Reference Manual                                4-72







                                                 APPLICATION FRAMEWORK


                         (_e_x_i_t-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_s_e_t_u_p-_c_o_d_e _L_I_S_P-_f_o_r_m)
                         (_a_t_t_a_c_h-_w_h_e_n-_p_o_s_s_i_b_l_e _t)
                         (_d_i_a_l_o_g_s _p_o-_s_p_e_c)
                         (_p_a_n_e_l_s _p_o-_s_p_e_c)
                         (_b_u_t_t_o_n_s _b_u_t_t_o_n-_s_p_e_c)
                         (_m_e_n_u_s _m_e_n_u-_b_a_r-_s_p_e_c)
                         (_f_o_r_m _p_o-_s_p_e_c)
                         (_f_o_r_m-_a_r_g_s _v_a_r-_s_p_e_c)
                         (_r_e_g_i_o_n _s_i_z_e-_s_p_e_c)
                         (_x _x-_o_f_f_s_e_t)
                         (_y _y-_o_f_f_s_e_t)
                         (_w _w_i_d_t_h)
                         (_h _h_e_i_g_h_t)
                         (_s_i_z_e _a_r_e_a)
                         (_l_o_c_a_t_i_o_n _l_o_c)
                         (_a_u_t_o_r_a_i_s_e _t)
                         (_a_u_t_o_w_a_r_p _t)
                         (_c_h_i_l_d_r_e_n _c_o_m_p_o_n_e_n_t-_s_p_e_c_s)
                         (_g_m _g_e_o_m_e_t_r_y-_m_a_n_a_g_e_r-_s_p_e_c))
                         (_v_i_s_i_t-_o_r_d_e_r _p_o-_s_p_e_c)
                         (_s_e_l_e_c_t_a_b_l_e _p_o-_s_p_e_c)
                         The panel _n_a_m_e is a PO name as  discussed  in
                         the  section on PO naming.  _a_r_g_u_m_e_n_t_s specify
                         the name and an optional  default  value  for
                         each  argument  to the panel.  Argument names
                         are symbols and the default value can  be  an
                         arbitrary   LISP   form.   The  documentation
                         string and the other panel definition clauses
                         specified  in  the body of the defpanel _m_a_c_r_o
                         _a_r_e _o_p_t_i_o_n_a_l, _a_n_d _c_a_n  _b_e  _s_p_e_c_i_f_i_e_d  _i_n  _a_n_y
                         _o_r_d_e_r.

                         _____________________________________________

          OPTIONAL
          CLAUSES



                         A panel definition similar clauses as a  dia-
                         log  because  panels  are similar to dialogs.
                         Panels have a different visual appearance  to
                         the   user   and  they  are  non-modal.   The
                         static-variables,   dynamic-variables,   con-
                         stants,   init-code,  exit-code,  setup-code,
                         attach-when-possible, dialogs,  panels,  but-
                         tons,  menus,  form, form-args, region, x, y,
                         w, h, size,  location,  autoraise,  autowarp,
                         children,   gm,  visit-order  and  selectable
                         clauses are the same as those defined in  the
                         deftool, deform, defframe, and defdialog mac-
                         ros. iconify-func and deiconify-func  specify
                         functions  to  be  executed when the panel is
                         iconified or deiconified.




          PICASSO Reference Manual                                4-73







                                                 APPLICATION FRAMEWORK


                         _____________________________________________

          MANAGING
          PANELS



                         Panels are a subclass of collection  widgets,
                         thus they inherit the methods defined on col-
                         lection widgets. In addition,  the  following
                         are also defined on panels.

                     close-panel

                                                               [_M_a_c_r_o]
                         _p_a_n_e_l
                         This function  closes  a  panel.   The  _p_a_n_e_l
                         argument specifies which panel to close.

                     current-panel

                                                               [_M_a_c_r_o]
                         Returns the currently active panel.

                     open-panel

                                                               [_M_a_c_r_o]
                         _p_a_n_e_l
                         &rest
                         _a_c_t_u_a_l-_a_r_g_u_m_e_n_t_s
                         This function  opens  a  panel.   The  actual
                         arguments  are  bound to the formal arguments
                         specified in the panel definition.

                     panel-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Return t _i_f _o_b_j_e_c_t _i_s  _a  _p_a_n_e_l  _o_b_j_e_c_t,  _n_i_l
                         _o_t_h_e_r_w_i_s_e.

                     run-panel

                                                               [_M_a_c_r_o]
                         _p_a_n_e_l
                         &rest
                         _a_c_t_u_a_l-_a_r_g_u_m_e_n_t_s
                         Same as open-panel

                         _____________________________________________

          PANEL SUM-
          MARY




















          PICASSO Reference Manual                                4-74







                                                 APPLICATION FRAMEWORK



                                          _______________
                                           Panel Macros
                                          ______________________________
                                           close-panel
                                           current-panel
                                           defpanel
                                           open-panel
                                           panel-p
                                           run-panel
                                          _______________

                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |







                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |




















































          PICASSO Reference Manual                                4-75







                                                    PICASSO DATA MODEL


                                               5
                                      PICASSO DATA MODEL

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         The PICASSO data  model  provides  variables,
                         constants, and portal objects for communicat-
                         ing with a database.  Variables are generally
                         defined  in  PICASSO  Objects  as part of the
                         framework.  These can then be associated with
                         widgets   using   the  propagation  mechanism
                         described in Chapter 7.  Portal  objects  are
                         created by the database interface and contain
                         database records.  This chapter discusses the
                         use  and  definition of variables, constants,
                         and portals.  It also presents  the  database
                         interface.

                         This chapter is organized as follows:

                         o+    Variables

                         o+    Constants

                         o+    Referencing Variables and Constants

                         o+    Portals
          ____________________________________________________________________________________________________________________________________________________________________________________

          Variables


                         Variables are created  automatically  when  a
                         PICASSO  object is created or called.  All PO
                         definitions can have clauses to define static
                         or  dynamic  variables.  Static-variables are
                         created when the PO  is  created.   Different
                         invocations  of  the  PO  reference  the same
                         variables.   Dynamic-variables  are   created
                         when  the  PO is called, so different invoca-
                         tions reference different variables.

                         Static-variables can also be created  by  the
                         application  at  run-time  using  the add-var
                         function.  For example,


                          (addvar _v_a_r_i_a_b_l_e-_n_a_m_e _p_l_a_c_e)


                         creates a static-variable named _v_a_r_i_a_b_l_e-_n_a_m_e
                         in  the  PO specified by _p_l_a_c_e.  The variable
                         is immediately visible to lexical children of



          PICASSO Reference Manual                                5-76







                                                    PICASSO DATA MODEL


                         the PO.



                         A PICASSO variable can  be  referenced  using
                         the  setf accessor function lookup that takes
                         the name of the variable as an  argument,  or
                         by the reader macros described below.  Recall
                         that environments are  lexically  scoped.   A
                         variable  declared in a frame can be accessed
                         by code in the frame's  form  if  a  variable
                         with  the  same  name  is not declared in the
                         form.  Variables can also be referenced  from
                         outside  the  lexical scope in which they are
                         defined.  For example, code in a menu  opera-
                         tion  can  reference variables declared local
                         to a form in  the  frame  that  contains  the
                         menu.

                         _____________________________________________

          ACCESSING
          VARIABLES



                         The following functions are defined to access
                         variables and lexical environments.

                     clear-env

                                                            [_F_u_n_c_t_i_o_n]
                         Clears the current lexical environment.

                     lexical-environment

                                                               [_M_a_c_r_o]
                         This function  returns  the  current  lexical
                         environment.   The PICASSO variable _p_o always
                         points at the current lexical environment.

                     lookup

                                                            [_F_u_n_c_t_i_o_n]
                         _v_a_r_i_a_b_l_e-_n_a_m_e
                         &optional
                         (_p_l_a_c_e (_l_e_x_i_c_a_l-_e_n_v_i_r_o_n_m_e_n_t))
                         This function returns the named  variable  in
                         the specified lexical environment.

                     value

                                                            [_A_c_c_e_s_s_o_r]
                         _v_a_r_i_a_b_l_e
                         The value of the variable if it is used in an
                         l-value  context  or the address of the vari-
                         able if it is used in an r-value context.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Constants


                         Constants behave just like variables,  except
                         the  value  of  a constant cannot be changed.
                         Constants can be specified either  implicitly
                         or   explicitly.    Named  constants  can  be



          PICASSO Reference Manual                                5-77







                                                    PICASSO DATA MODEL


                         specified  explicitly  with   the   constants
                         clause of a def<po>, for example


                          (deftool ("demo-tool" "demo" . "tool")
                             (title "Demonstration Tool")
                             (constants ((bye-string "See you later")))
                             .
                             .
                             .


                         creates a constant named bye-string.

                         Named constants can also  be  created  impli-
                         citly  in  other  clauses of a PO definition.
                         For example, all lexical  children  of  a  PO
                         (i.e.,  PO's  specified in the frames, forms,
                         panels, or dialogs clauses) are  given  names
                         that are constants in the parent PO.  Widgets
                         specified in the children clause of a PO  can
                         also be bound to named constants by replacing
                         the widget definition


                          (make-<_w_i_d_g_e_t-_n_a_m_e> _a_r_g_s)


                         with a pair


                          (_c_o_n_s_t_a_n_t-_n_a_m_e (make-<_w_i_d_g_e_t-_n_a_m_e> _a_r_g_s))


                         This construct creates a name that references
                         the  widget when the PO is instantiated.  The
                         same  technique  can  be  used  with  buttons
                         specified in panels and dialog boxes and with
                         menus specified in frames or panels.

                         The following macros can be used  to  control
                         the setting of constants.

                     enforce-constants

                                                               [_M_a_c_r_o]
                         Doe not allow the value of  constants  to  be
                         changed.

                     relax-constants

                                                               [_M_a_c_r_o]
                         Allow the value of constants to  be  changed.
                         This  macro is used mainly for debugging pur-





          PICASSO Reference Manual                                5-78







                                                    PICASSO DATA MODEL


                         poses.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Referenc-
          ing Vari-
          ables and
          Constants





                         Variables and  constants  are  referenced  by
                         using  the  Common Lisp "#!" and "#?" macros,
                         The reader macro #?x is equivalent to


                          (lookup 'x)


                         and the reader macro #!x is equivalent to


                          (value (lookup 'x))


                         In either case, the variable is looked up  in
                         the  current  lexical  environment,  and  the
                         current environment depends on  which  PO  is
                         active  and the location of the mouse cursor.
                         The setup,  initialization,  and  termination
                         code is always executed in the context of the
                         defining PO.

                         Once the current environment is  established,
                         variable   lookup   proceeds   in  a  lexical
                         fashion.  The variable self always refers  to
                         the  current  lexical environment.  The vari-
                         ables  in  the  PO  referenced  by  self  are
                         searched  first,  followed  by the PO that is
                         the parent of self.  Parent  links  are  fol-
                         lowed  up to the tool.  For ease of use, #!po
                         always refers to the closest PO.   For  exam-
                         ple, it is the PO itself if the current lexi-
                         cal environment (i.e., self) points to a  PO.
                         Otherwise,  it  is  the closest enclosing PO.
                         The variable #!po can be used  in  button  or
                         menu  code  to  locate the enclosing PO since
                         self points to the button or menu entry.

                         An example of code  that  references  PICASSO
                         variables and calls s CLOS functions is


                          (setf #!x (+ #!x (f #!y)))


                         which adds x to the result  of  applying  the
                         function  f  to the variable y.  The expanded
                         code for this example is



          PICASSO Reference Manual                                5-79







                                                    PICASSO DATA MODEL



                          (setf (value (lookup 'x))
                                (+ (value (lookup 'x))
                                   (f (value (lookup 'y)))))



                         Sometimes it is necessary to specify where to
                         look  for a variable.  For example, a frame's
                         initialization  code  might  define  bindings
                         between  frame  variables  and widgets in the
                         enclosing       form.        The       syntax
                         "#!variable@place"  evaluates _p_l_a_c_e to find a
                         starting point for the search  for  _v_a_r_i_a_b_l_e.
                         For example, #?x@y _i_s _e_q_u_i_v_a_l_e_n_t _t_o


                          (_l_o_o_k_u_p '_x _y)


                         _a_n_d _t_h_e _e_x_p_r_e_s_s_i_o_n #!_x@_y is equivalent to


                          (value (lookup 'x y))



                         More complicated search  paths  can  also  be
                         used  to  reference  variables  in  different
                         environments.  The reader macro can reference
                         a  variable in another scope by specifying an
                         explicit path name of a place  that  contains
                         the  variable.  For example, a dialog that is
                         defined to be global to a tool can  reference
                         a  variable  defined  in a frame bound to the
                         variable  foo  by  the  expression   #!foo/x.
                         Names  in  the  path are separated by a slash
                         (`/').  This expression is equivalent to


                          (value (lookup 'x (value (lookup 'foo))))


                         Similarly,  the  expression  #!foo@x/y/z   is
                         equivalent to


                          (value (lookup 'z
                                         (value (lookup 'y
                                                        (value (lookup 'foo
                                                                       x))))))




          PICASSO Reference Manual                                5-80







                                                    PICASSO DATA MODEL


                         and the expression


                          #!start-frame@(current-tool)/x


                         references  x  in  the  start-frame  in   the
                         current tool.

                         Any number of "/"-separated names may  occur.
                         The  "@" clause can only be used on the first
                         variable, since the other names  are  located
                         based  on  the value of the preceding expres-
                         sion.  Notice that the location specifier  in
                         the  "@"  clause  can be any Lisp expression,
                         including a call, in this case, to the  func-
                         tion (current-tool).
          ____________________________________________________________________________________________________________________________________________________________________________________

          Databases


                         PICASSO tools can operate on any valid s CLOS
                         data   type,   and   a   reasonable  external
                         representation is used when these values  are
                         stored  in  a  database.  Two additional data
                         types, portals and persistent  CLOS  objects,
                         are  provided  in  PICASSO  for communicating
                         with a  database.   The  current  release  of
                         Picasso  works  with POSTGRES [Wen89] or com-
                         mercial INGRES.  The  portal  abstraction  is
                         defined  only for POSTGRES and the persistent
                         CLOS  abstraction  is  supported  either  for
                         POSTGRES  or  INGRES.  An embedded SQL inter-
                         face is also available to access INGRES data-
                         bases [ChR89].

                         A portal is an array  of  CLOS  objects  that
                         buffers  a subset of tuples in the return set
                         of a database query.   The  elements  in  the
                         array  can  be  accessed  using  the standard
                         array accessor  functions  (e.g.,  aref)  and
                         CLOS  slot  accessing  functions (e.g., slot-
                         value).  Additional functions are provided to
                         create  a portal and to fetch tuples from the
                         return set into the buffer.

                         The portal buffer is indexed by the  integers
                         0 to _n-_1 where _n is the number of elements in
                         the buffer.  The portal varies in  size  with







          PICASSO Reference Manual                                5-81







                                                    PICASSO DATA MODEL


                         each fetch command.

                         _____________________________________________

          CREATING
          PORTALS



                         The following function can be used to  create
                         a portal.

                     make-portal

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_d_a_t_a_b_a_s_e (_c_u_r_r_e_n_t-_d_a_t_a_b_a_s_e))
                         (name "")
                         (_t_a_r_g_e_t _n_i_l _t_a_r_g_e_t_p)
                         (where nil)
                         &allow-other-keys
                         The _d_a_t_a_b_a_s_e argument specifies the database.
                         The  _n_a_m_e  argument specifies the name of the
                         portal.  The _t_a_r_g_e_t  argument  specifies  the
                         target list for the query and the _w_h_e_r_e argu-
                         ment  specifies  the  where-clause  for   the
                         query.

                         _____________________________________________

          MANAGING
          PORTALS




                     close-portal

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _p_o_r_t_a_l)
                         Close the portal and deallocate space associ-
                         ated with it.

                     cl-to-db-type

                                                            [_F_u_n_c_t_i_o_n]
                         _c_l_t_y_p_e
                         This function controls the mapping of  inter-
                         nal s CLOS types to external database types.

                     current-database

                                                            [_F_u_n_c_t_i_o_n]
                         Return the name of the current  database,  or
                         nil if no current database.

                     current-tuple

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _p_o_r_t_a_l)
                         A portal has a current  tuple.   This  method
                         returns  the  CLOS  object  for  the  current
                         tuple.

                     db-to-cl-type

                                                            [_F_u_n_c_t_i_o_n]
                         _d_b_t_y_p_e
                         This function controls the mapping of  exter-






          PICASSO Reference Manual                                5-82







                                                    PICASSO DATA MODEL


                         nal database types to internal s CLOS types.

                     fetch-tuples

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _p_o_r_t_a_l)
                         &key
                         (_d_i_r_e_c_t_i_o_n :_f_o_r_w_a_r_d)
                         (count :all)
                         &allow-other-keys
                         This function fetches tuples from  the  data-
                         base  into  the  portal array.  The direction
                         may be either :forward _o_r  :_b_a_c_k_w_a_r_d.   :for-
                         ward _i_s _t_h_e _d_e_f_a_u_l_t.  _T_h_e _c_o_u_n_t _i_s _a _p_o_s_i_t_i_v_e
                         _i_n_t_e_g_e_r _t_h_a_t _s_p_e_c_i_f_i_e_s _t_h_e _m_a_x_i_m_u_m _n_u_m_b_e_r  _o_f
                         _t_u_p_l_e_s  _t_o  _f_e_t_c_h.   _I_f  _t_h_e  _k_e_y_w_o_r_d :_a_l_l is
                         passed to _c_o_u_n_t, all tuples are fetched.

                     next-tuple

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _p_o_r_t_a_l)
                         Make the next tuple in the portal the current
                         tuple and return it.

                     previous-tuple

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _p_o_r_t_a_l)
                         Make the previous tuple  in  the  portal  the
                         current tuple and return it.

                     rewind-portal

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _p_o_r_t_a_l)
                         Rewind the portal  to  the  first  tuple  and
                         return it.

                     setf-current-database

                                                            [_F_u_n_c_t_i_o_n]
                         _n_a_m_e
                         Set the current database to name.   An  error
                         is signaled if it is already defined.

                     (setf portal-tuple-index)

                                                              [_M_e_t_h_o_d]
                         (_v_a_l_u_e _i_n_t_e_g_e_r)
                         (_s_e_l_f _p_o_r_t_a_l)
                         This setf method changes  the  index  of  the
                         current tuple.

                         _____________________________________________

          PERSISTENT
          CLASSES



                         Persistent CLOS objects can be  defined  that
                         behave  similar  to local CLOS classes except
                         that they are stored in the  database.   Per-
                         sistent  objects  are  created  by defining a
                         persistent class,  creating  an  instance  of
                         that  class,  and storing the instance in the
                         database.  Both the class definition and  the



          PICASSO Reference Manual                                5-83







                                                    PICASSO DATA MODEL


                         persistent object are stored in the database.
                         Persistent classes are mapped into  the  CLOS
                         class hierarchy as shown:


                          T
                                  OBJECT
                                        _l_o_c_a_l _c_l_a_s_s_e_s
                                  DBOBJECT
                                        _p_e_r_s_i_s_t_e_n_t _c_l_a_s_s_e_s



                         The following defdbclass  macros  defined  to
                         create  persistent classes.  Defdbclass takes
                         the  same  arguments  as  the  CLOS  defclass
                         macro.

                     defdbclass

                                                               [_M_a_c_r_o]
                         _n_a_m_e
                         (_s_u_p_e_r_c_l_a_s_s_e_s)
                         (_s_l_o_t-_d_e_f_i_n_i_t_i_o_n_s)
                         (_c_l_a_s_s-_o_p_t_i_o_n_s)
                         This macro defines the class and issues  com-
                         mands  to  the  database  to create the class
                         definition and the relation  that  will  hold
                         the  instances  of  the  class.  _s_u_p_e_r_c_l_a_s_s_e_s
                         specifies a list  of  superclasses  for  this
                         class.   The  superclasses  must  all be per-
                         sistent  classes.   _S_l_o_t-_d_e_f_i_n_i_t_i_o_n_s  defines
                         the  object slots and _c_l_a_s_s-_o_p_t_i_o_n_s specifies
                         options of the class (e.g., :documentation _o_r
                         :_d_e_f_a_u_l_t-_i_n_i_t_a_r_g_s).

                         _____________________________________________

          EXAMPLE


                         The following definition creates a persistent
                         box class:


                          (defdbclass box (dbobject)
                              ((origin :type point :accessor origin)
                              (width :type integer :accessor width)
                              (height :type integer :accessor height)))


                         This code defines a class named box which  is
                         a  subclass  of  the  dbobject  class.  Three
                         object slots  are  defined  for  this  object
                         (origin, width, and height).  No options have




          PICASSO Reference Manual                                5-84







                                                    PICASSO DATA MODEL


                         been specified for this class.

                         _____________________________________________

          PERSISTENT
          OBJECTS



                         Instances of persistent classes  are  created
                         by  calling the CLOS make-instance method and
                         passing it  a  persistent  class.   The  per-
                         sistent  object  is stored in the database by
                         calling the method store-dbobject.  Slots are
                         accessed  by  calling slot-value or using the
                         accessor functions  specified  in  the  class
                         definition.   A  persistent  object is loaded
                         from  the  database  by  calling  the  method
                         fetch-dbobject.  This method creates the CLOS
                         class object for the persistent class  if  it
                         is  not  defined  and retrieves the specified
                         object from the database into an object cache
                         in the tool.

                         Persistent  objects  are  assigned  a  unique
                         identifier,   called   an  _o_b_j_e_c_t  _i_d_e_n_t_i_f_i_e_r
                         (OBJID) when it is created.  Objects  can  be
                         fetched from the database by OBJID or by giv-
                         ing a predicate that uniquely  specifies  the
                         desired  object.  Slots in persistent objects
                         can contain any valid PICASSO type  including
                         a  pointer  to  a local or persistent object.
                         Pointers to local objects  are  converted  to
                         _L_I_S_P-_f_o_r_ms   that  will  recreate  the  local
                         object  when   the   persistent   object   is
                         reloaded.  Pointers to persistent objects are
                         represented by OBJID's in the database.  They
                         are  represented  by  physical  pointers when
                         both objects are in the object cache.

                         _____________________________________________

          MANIPULAT-
          ING PER-
          SISTENT
          OBJECTS





                         The following functions are provided to mani-
                         pulate persistent objects.

                     fetch-dbobject

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _d_b_o_b_j_e_c_t)
                         &optional
                         _n_o-_e_r_r_o_r-_p
                         This function fetches  a  dbobject  given  an
                         OBJID.  The argument can be a single OBJID or
                         a list of OBJID's.

                     fetch-dbobject

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _d_b_c_l_a_s_s)



          PICASSO Reference Manual                                5-85







                                                    PICASSO DATA MODEL


                         _s_l_o_t-_n_a_m_e
                         _s_l_o_t-_v_a_l_u_e
                         &optional
                         _n_o-_e_r_r_o_r-_p
                         This function  fetches  a  dbobject  by  slot
                         value.

                     make-dbobject-from-database

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _d_b_c_l_a_s_s)
                         _q_u_e_r_y
                         &optional
                         _n_o-_e_r_r_o_r-_p
                         This function takes an  arbitrary  query  and
                         fetches the specified objects into the cache.

                     make-instance

                                                            [_F_u_n_c_t_i_o_n]
                         _c_l_a_s_s
                         &rest
                         _i_n_i_t-_p_l_i_s_t
                         Make an  instance  of  a  persistent  object.
                         This  function  calls the CLOS function _m_a_k_e-
                         _i_n_s_t_a_n_c_e to create  the  local  instance  and
                         assigns an OBJID.

                     ppi

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _o_b_j_i_d)
                         &key
                         (_s_t_r_e_a_m *_s_t_a_n_d_a_r_d-_o_u_t_p_u_t*)
                         (level nil)
                         Pretty-print  the  specified  object  on  the
                         specified output stream.

                     slot-type

                                                              [_M_e_t_h_o_d]
                         (_c_l_a_s_s _d_b_c_l_a_s_s)
                         _s_l_o_t-_n_a_m_e
                         This function returns the type of the  speci-
                         fied slot.

                     slot-value

                                                            [_F_u_n_c_t_i_o_n]
                         (_s_e_l_f _d_b_o_b_j_e_c_t)
                         _s_l_o_t
                         This accessor function can be used  to  fetch
                         or  store a value into a slot of a persistent
                         object.

                     store-dbobject

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _d_b_o_b_j_e_c_t)
                         This generic function stores  the  object  in
                         the  database.   The  argument _s_e_l_f can be an
                         instance of  a  _d_b_o_b_j_e_c_t  (i.e.,  a  physical
                         pointer  to a persistent object) or the OBJID
                         of a persistent object in the cache.



          PICASSO Reference Manual                                5-86







                                              PROPAGATION AND TRIGGERS


                                               6
                                   PROPAGATION AND TRIGGERS

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         PICASSO provides facilities to  automatically
                         enforce  constraints  among data values, exe-
                         cute code when data values change, and  cache
                         the   results   of  constraint  computations.
                         These data management  facilities  allow  the
                         programmer  to  state declaratively the rela-
                         tionships between data values  in  a  PICASSO
                         application.   Code  can be attached declara-
                         tively to data changes , and  the  programmer
                         can   choose  between  immediate  update  and
                         update-when-referenced for any data slot.

                         The types  of  data  constraint  and  trigger
                         facilities provided by PICASSO are:

                         o+    Bindings

                         o+    Triggers

                         o+    Lazy Evaluation
          ____________________________________________________________________________________________________________________________________________________________________________________

          Bindings


                         Data constraints and propagation are  managed
                         in  PICASSO  with  a  binding mechanism.  Any
                         PICASSO variable or any object  slot  can  be
                         given  a list of functions that determine its
                         value.  For example, a  widget  displaying  a
                         last  name could have its value slot bound to
                         a variable which holds the last name  of  the
                         current employee in a database.  Similarly, a
                         display-only gadget could display the current
                         pension  value  of an employee by computing a
                         function from the employee's salary and years
                         of service.

                         Bindings are  declarations  of  one-way  con-
                         straints on data values. When one of the con-
                         straining  values  changes,  the  constrained
                         value  is changed to reflect the new value of
                         the function.  Multiple  constraints  may  be
                         asserted,  in  which case two-way constraints
                         can be declared as a pair of bindings.

                         Bindings may be declared among three types of
                         data value:



          PICASSO Reference Manual                                6-87







                                              PROPAGATION AND TRIGGERS


                         o+    PICASSO variables

                         o+    Object slots

                         o+    Virtual slots

                         Virtual slots are combinations of methods and
                         setf methods that emulate real slots.  A com-
                         puted value can be implemented as  a  virtual
                         slot  by  having its accessor method refer to
                         the underlying data slots and by  defining  a
                         setf method that updates the underlying data.
                         For most purposes,  virtual  slots  and  real
                         object slots can be treated identically.

                         _____________________________________________

          DECLARING
          BINDINGS



                         Bindings can be most easily created using the
                         following macros:

                     blet

                                                               [_M_a_c_r_o]
                         _p_i_c_a_s_s_o-_v_a_r_i_a_b_l_e | (_s_l_o_t _o_b_j_e_c_t)
                         :_v_a_r ( { (_v_a_r _p_r_o_p-_v_a_l_u_e) }* )
                         :_w_i_t_h ( { (_v_a_r _c_o_n_s_t-_v_a_l_u_e) }* )
                         _f_o_r_m
                         The blet _m_a_c_r_o _i_s _u_s_e_d _t_o _e_s_t_a_b_l_i_s_h  _b_i_n_d_i_n_g_s
                         _t_o _a _s_l_o_t _o_f _a_n _o_b_j_e_c_t _o_r _a _p_i_c_a_s_s_o _v_a_r_i_a_b_l_e.
                         _M_o_r_e _p_r_e_c_i_s_e_l_y, _t_h_e _f_o_r_m


                          (_b_l_e_t _p_v_a_r
                                :_v_a_r ((_v_a_r_1 _p_r_o_p-_v_a_l_u_e_1)
                                      (_v_a_r_2 _p_r_o_p-_v_a_l_u_e_2)
                                       ...
                                      (_v_a_r_n _p_r_o_p-_v_a_l_u_e_n))
                                :_w_i_t_h ((_w_v_a_r_1 _c_o_n_s_t-_v_a_l_u_e_1)
                                       (_w_v_a_r_2 _c_o_n_s_t-_v_a_l_u_e_2)
                                       ...
                                       (_w_v_a_r_m _c_o_n_s_t-_v_a_l_u_e_m))
                                (_f_o_r_m))


                         _e_s_t_a_b_l_i_s_h_e_s _a _b_i_n_d_i_n_g _t_o  _p_v_a_r  _f_r_o_m  _t_h_e  _s-
                         _e_x_p_r_e_s_s_i_o_n _f_o_r_m.  _F_o_r_m _i_s _e_v_a_l_u_a_t_e_d _i_n _a _l_e_x_-
                         _i_c_a_l _e_n_v_i_r_o_n_m_e_n_t  _w_h_e_r_e  _v_a_r_i  _i_s  _t_h_e  _v_a_l_u_e
                         _r_e_t_u_r_n_e_d  _b_y  _t_h_e _e_x_p_r_e_s_s_i_o_n _p_r_o_p-_v_a_l_u_e_i, _a_n_d
                         _w_v_a_r_j _i_s _t_h_e _v_a_l_u_e _r_e_t_u_r_n_e_d _b_y _t_h_e _e_x_p_r_e_s_s_i_o_n
                         _c_o_n_s_t-_v_a_l_u_e_j, _s_i_m_i_l_a_r _t_o _t_h_e _L_i_s_p _l_e_t _s_p_e_c_i_a_l
                         _f_o_r_m.  _I_f, _a_f_t_e_r _t_h_e _e_v_a_l_u_a_t_i_o_n _o_f _t_h_i_s _f_o_r_m,
                         _a_n_y _o_f _t_h_e _v_a_l_u_e_s _p_r_o_p-_v_a_l_u_e_i _a_r_e _s_e_t _v_i_a _t_h_e
                         _s_e_t_f _m_a_c_r_o, _p_v_a_r _w_i_l_l _b_e  _r_e-_e_v_a_l_u_a_t_e_d;  _t_h_a_t



          PICASSO Reference Manual                                6-88







                                              PROPAGATION AND TRIGGERS


                         _i_s, _t_h_e _v_a_l_u_e_s _p_r_o_p-_v_a_l_u_e_i _a_r_e _t_h_e _s_o_u_r_c_e_s _o_f
                         _t_h_e _p_r_o_p_a_g_a_t_i_o_n.  _T_h_e _p_u_r_p_o_s_e  _o_f  _t_h_e  _v_a_r_i_-
                         _a_b_l_e_s  _c_o_n_s_t-_v_a_l_u_e_j  _i_s  _p_u_r_e_l_y  _c_o_n_v_e_n_i_e_n_c_e,
                         _s_i_m_i_l_a_r _t_o _t_h_e _t_r_a_d_i_t_i_o_n_a_l _L_i_s_p _l_e_t.

                         _____________________________________________

          EXAMPLE


                         Suppose that we have a  table  sel-list  that
                         has  a  slot  named  selection,  and a button
                         called add-button. To declare that  the  add-
                         button  should  be dimmed whenever the selec-
                         tion slot of the table sel-list  is  nil,  or
                         when  the picasso variable no-add is non-nil,
                         the following binding would be used:


                          (blet (dimmed #!add-button)
                                :var ((selected (selection #!sel-list))
                                      (not-ok-to-add #!no-add))
                                (or not-ok-to-add (null selected)))



                         A special case of bindings is  a  propagation
                         from a picasso-variable (or slot object) to a
                         picasso-variable (or slot object).   This  is
                         commonly  used,  for  example, to synchronize
                         two widgets or to bind the value of a  widget
                         to  a  picasso  variable.  The latter example
                         would allow the widget to display  the  value
                         of  the  variable.   These  bindings are most
                         conveniently established with the bind macro:

                     bind

                                                               [_M_a_c_r_o]
                         _d_e_s_t_i_n_a_t_i_o_n-_v_a_r_i_a_b_l_e | (_d_e_s_t_i_n_a_t_i_o_n-_s_l_o_t _d_e_s_t_i_n_a_t_i_o_n-_o_b_j_e_c_t)
                         _s_o_u_r_c_e-_v_a_r_i_a_b_l_e | (_s_o_u_r_c_e-_s_l_o_t _s_o_u_r_c_e-_o_b_j_e_c_t)

                         This macro establishes the binding  from  the
                         _s_o_u_r_c_e  to  the _d_e_s_t_i_n_a_t_i_o_n.  More precisely,
                         the following forms are equivalent:


                          (bind #!a #!b)
                                =  (blet #!a :var ((b #!b)) b)
                          (bind (s #!a) #!b)
                                =  (blet (s #!a) :var ((b #!b)) b)
                          (bind #!a (s #!b)
                                =  (blet #!a :var ((b (s #!b))) b)
                          (bind (s #!a) (s #!b)
                                =  (blet (s #!a) :var ((b (s #!b))) b)




          PICASSO Reference Manual                                6-89







                                              PROPAGATION AND TRIGGERS


                         Bindings are  declared  using  the  following
                         functions.   These functions are more general
                         purpose than blet  and  bind,  in  that  they
                         allow  certain obscure type of bindings to be
                         performed that blet and bind can't,  but  are
                         more cryptic in their notation.

                     bind-slot

                                                            [_F_u_n_c_t_i_o_n]
                         _s_l_o_t-_n_a_m_e
                         _o_b_j_e_c_t
                         _f_u_n_c_t_i_o_n
                         &optional
                         (_r_e_c_e_i_p_t _n_i_l)

                     bind-var

                                                               [_M_a_c_r_o]
                         _p_i_c_a_s_s_o-_v_a_r_i_a_b_l_e
                         _f_u_n_c_t_i_o_n
                         &optional
                         (_r_e_c_e_i_p_t _n_i_l)

                         These functions bind the specified slot, vir-
                         tual slot, or variable to the specified func-
                         tion.  When  _r_e_c_e_i_p_t  is  specified,  and  is
                         non-nil,  _t_h_e _b_i_n_d_i_n_g _f_u_n_c_t_i_o_n _r_e_t_u_r_n_s _a _h_a_n_-
                         _d_l_e _t_h_a_t _c_a_n _b_e  _u_s_e_d  _l_a_t_e_r  _t_o  _r_e_m_o_v_e  _t_h_e
                         _b_i_n_d_i_n_g  _e_f_f_i_c_i_e_n_t_l_y.  _T_h_e _f_u_n_c_t_i_o_n _s_p_e_c_i_f_i_e_d
                         _s_h_o_u_l_d  _b_e  _a_n  _e_v_a_l_u_a_b_l_e  _L_i_s_p  _s-_e_x_p_r_e_s_s_i_o_n
                         _w_h_i_c_h  _w_i_l_l  _e_x_e_c_u_t_e  _o_u_t_s_i_d_e _o_f _t_h_e _d_e_f_i_n_i_n_g
                         _e_n_v_i_r_o_n_m_e_n_t (_n_o _L_i_s_p _v_a_r_i_a_b_l_e_s _s_h_o_u_l_d _b_e _u_s_e_d
                         _i_n  _t_h_i_s _s-_e_x_p_r_e_s_s_i_o_n, _u_n_l_e_s_s _t_h_e_y _a_r_e _e_x_p_l_i_-
                         _c_i_t_l_y _b_o_u_n_d _i_n _t_h_e _s-_e_x_p_r_e_s_s_i_o_n _t_h_r_o_u_g_h  _l_e_t,
                         prog,  _o_r  _a  _s_i_m_i_l_a_r _c_o_n_s_t_r_u_c_t).  _W_i_t_h_i_n _t_h_e
                         _f_u_n_c_t_i_o_n, _c_a_l_l_s _t_o _t_h_e _m_a_c_r_o _v_a_r are used  to
                         mark  the  data values which should trigger a
                         propagation when they are changed.  There are
                         three forms for this macro:


                          (var _s_l_o_t-_n_a_m_e _o_b_j_e_c_t-_r_e_f_e_r_e_n_c_e)
                          (var _v_a_r_i_a_b_l_e-_r_e_f_e_r_e_n_c_e)
                          (var _v_a_r_i_a_b_l_e-_r_e_f_e_r_e_n_c_e :ref _l_o_c_a_t_i_o_n)


                         The slot name does not  need  to  be  quoted.
                         The object reference should not be quoted and
                         should evaluate to an object in the  defining
                         context.   The  variable reference should not
                         be quoted and will be resolved in the lexical
                         environment of the object (or variable) being
                         constrained.   The  location  should  not  be
                         quoted  and  should  evaluate  to  a  PICASSO
                         object in the  defining  context.   When  the



          PICASSO Reference Manual                                6-90







                                              PROPAGATION AND TRIGGERS


                         location is specified, the variable reference
                         is resolved in the  lexical  context  of  the
                         location.   Examples  of each type of binding
                         are presented in the next section.

                         The rest of the function must  be  completely
                         resolved before calling the binding function.
                         To include references to objects or variables
                         not placed in var macros, the function should
                         be expressed as a  backquoted  expression  in
                         Common  Lisp.   The  backquote  macro permits
                         individual clauses  to  be  pre-evaluated  by
                         prefixing them with a comma.  Examples of the
                         use of backquote and comma are  presented  in
                         the next section.

                         _____________________________________________

          EXAMPLES
          OF BIND-
          INGS




                         This section presents a set of  sample  bind-
                         ings.  Assume the following definitions:


                          (defframe "frame-1" ()
                            "This is the only frame"
                            (static-variables
                                 name age salary
                                 years-of-service form-creator)
                            (dynamic-variables employee)
                            (form              (emp-form "employee")))

                          (defform "employee" ()
                            "This is the only form"
                            (static-variables (creator "Picasso"))
                            (children
                              (name-field
                                (make-text-gadget :label "Name:"))
                              (salary-field
                                (make-text-gadget :label "Salary:"))
                              (pens-field
                                (make-text-gadget :label "Pension:"))
                              (author-field
                                (make-text-widget :label "Form Author:"))))



                         Also   assume   that   the   frame   variable
                         #!employee  has  as  its value an object with
                         fields for name, age, salary,  and  years  of
                         service.  For simplicity, we will assume that
                         the employee object is  read-only,  and  that
                         the  only  changes  that  will  occur are the



          PICASSO Reference Manual                                6-91







                                              PROPAGATION AND TRIGGERS


                         replacement of the entire object with  a  new
                         object   (and   a   therefore   a  change  to
                         #!employee as a whole. We will first  set  up
                         bindings  between  the frame static variables
                         and the fields of the employee object.  Since
                         this  code  will  be  executed as part of the
                         frame's setup code, it is written in the lex-
                         ical context of the frame.


                          (blet #!name
                            :var ((emp #!employee))
                            (name emp))
                          (blet #!age
                            :var ((emp #!employee))
                            (age employee))
                          (blet #!salary
                            :var ((emp #!employee))
                            (salary employee))
                          (blet #!years-of-service
                            :var ((emp #!employee))
                            (years-of-service employee))



                         These bindings assume  that  the  appropriate
                         accessors  for  the  employee  structure  are
                         defined.  Notice that the var clause is  used
                         for  the  dynamic  variable #!employee.  This
                         indicates that whenever #!employee is set  to
                         a different value (different object), each of
                         the static variables  will  be  updated.   If
                         instead  of  having  several employee objects
                         there were only one and that object  had  its
                         slots  set whenever the data was changed, the
                         following bindings would be more appropriate.


                          (blet #!name
                            :var ((empname (name  #!employee)))
                            empname)
                          (blet #!age
                            :var ((empage (age #!employee)))
                            empage)
                          (blet #!salary
                            :var ((empsal (salary #!employee)))
                            empsal)
                          (blet #!years-of-service
                            :var ((empyears (years-of-service #!employee)))
                            empyears)





          PICASSO Reference Manual                                6-92







                                              PROPAGATION AND TRIGGERS


                         These bindings would be  triggered  when  the
                         slots inside the object changed but would not
                         be triggered by a change to #!employee  which
                         would  leave the object untouched.  For cases
                         where both changes are possible  (not  common
                         in   PICASSO  since  the  portal  abstraction
                         creates  new  objects)   a   combination   of
                         triggers and bindings must be used (this case
                         is shown in the examples  of  triggers  later
                         this  chapter).  Assume for this example that
                         the interface supports browsing without edit-
                         ing  and  thus the object slots are not bound
                         to the variables.

                         Next, the form widgets should be bound to the
                         appropriate  variable  values  in  the frame.
                         This code will be executed  as  part  of  the
                         setup  code  for the form and thus is written
                         in the lexical scope of the form.


                          (blet (value #!name-field)
                            :var ((newname #!name))
                            newname)
                          (blet (value #!salary-field)
                            :var ((sal #!salary))
                            (print-to-string sal))
                          (blet (value #!pens-field)
                            :var ((salary #!salary)
                                  (years #!years-of-service))
                            :with ((age #!age))
                            (print-to-string
                               (* sal (/ years age))))



                         The first binding binds the value slot of the
                         text  gadget #!name-field to the string value
                         in the  frame  variable  #!name.   Since  the
                         frame  is  the lexical parent of the form, no
                         further qualification  is  necessary.   Since
                         the  text gadget cannot be edited, no binding
                         in the other direction is  necessary  either.
                         The  second  binding  binds  the  text gadget
                         which  displays  the  salary  to   a   string
                         representation   of  the  #!salary  variable.
                         This could be done by using  a  gadget  which
                         displays  a number directly, but this example
                         shows that Lisp functions can be included  in
                         the function.





          PICASSO Reference Manual                                6-93







                                              PROPAGATION AND TRIGGERS


                         The third binding is more  complicated.   The
                         pension  value  at this particular company is
                         calculated  by  multiplying  the   employee's
                         final  salary  by  the percentage of his life
                         that he was employed at the  company.   More-
                         over,  this  recalculation  is only made when
                         the salary changes or on the  anniversary  of
                         employment  (when the years of service in the
                         company  is  updated).   Pensions   are   not
                         adjusted  on  the employee's birthday (except
                         when this coincides with other changes) since
                         this would encourage employees to retire just
                         before their birthday.  The provided function
                         computes  the employee's pension but does not
                         result in an update of the pension when #!age
                         changes,  only  when  #!salary or #!years-of-
                         service change.  The evaluation of #!age will
                         occur   each  time  the  propagation  occurs.
                         Since the function is executed in the context
                         of the pension field, which lexically resides
                         at the level of the form, #!age  is  resolved
                         into the age variable in the frame.  If there
                         were concern about the possibility of  a  new
                         age  variable  being  introduced  at the form
                         level (by add-var) then the  variable  refer-
                         ence  could  be  resolved  completely at bind
                         time by recalling that variables  are  indeed
                         objects with a ``value'' slot.


                          (blet (value #!pens-field)
                            :var ((salary #!salary)
                                  (years #!years-of-service))
                            :with ((age (value ',#?age)))
                            (print-to-string
                               (* sal (/ years age))))


                         This second  version  uses  the  comma  macro
                         inside  the backquote macro to evaluate #?age
                         before passing the function to bind-slot.  In
                         this  case,  ,#?age gives us a pointer to the
                         age variable object.  The quote  before  this
                         prevents  it  from  being  re-evaluated later
                         (since it is now the object  pointer,  not  a
                         Lisp  expression which evaluates to an object
                         pointer).  This can be passed  to  the  value
                         accessor  which  extracts  the variable value
                         from  the  variable  object.   This  type  of
                         reference  is  only  available  with  PICASSO
                         variables,  since  Lisp  variables  are   not
                         represented  as  objects.   This  quote-comma



          PICASSO Reference Manual                                6-94







                                              PROPAGATION AND TRIGGERS


                         pattern  is  commonly  used  when   resolving
                         expressions at bind-time inside backquotes.

                         All that remains to bind  are  the  variables
                         and  object slots corresponding to the form's
                         author.  In the  form,  these  bind  commands
                         will  set  up  a  two-way binding between the
                         entry widget and the creator variable.


                          (blet (value #!author-field)
                            :var ((creator #!creator))
                            creator)
                          (blet #!creator
                            :var ((author (value #!author-field)))
                            author)


                         In the frame, a non-local  reference  to  the
                         creator  variable  must be made.  This can be
                         done in either of two ways.


                          (blet #!form-creator
                            :var ((creator #!emp-form/creator))
                            creator)
                          (blet #!form-creator
                            :var ((creator #!creator :ref #!emp-form))
                            creator)


                         The first form takes advantage  of  the  path
                         notation  for  PICASSO variables.  The second
                         form uses the :ref version of the var  macro.
                         The  second  form  is preferred because it it
                         generally easier to read.

                         To illustrate the use of bind-slot and  bind-
                         var,  here  are  some  of the above examples,
                         using these functions instead of blet.


                          (bind-slot 'value #!pens-field
                            `(print-to-string
                               (* (var #!salary) (/ (var #!years-of-service)
                                                    (value ',#?age)))))
                          (bind-var #!form-creator
                            '((var #!creator :ref #!emp-form)))


                         The above examples show all  combinations  of
                         binding  slots  and  variables.   Recall that



          PICASSO Reference Manual                                6-95







                                              PROPAGATION AND TRIGGERS


                         virtual slots are identical to real slots for
                         these  purposes  (i.e.,  it  does  not matter
                         whether ``value'' is really a slot or  is  an
                         accessor  and setf method for the gadgets and
                         widgets used).

                         _____________________________________________

          MULTIPLE
          CON-
          STRAINTS




                         More than one binding may be declared  for  a
                         data  item.   When  more  than one binding is
                         active, a change in data  which  triggers  an
                         update  will  use  the most recently declared
                         binding which is appropriate  for  the  datum
                         that  changed.  For instance, assume the fol-
                         lowing bindings are asserted in order.


                          (blet #!x
                            :var ((a #!a)
                                  (b #!b))
                            (+ a b))
                          (blet #!x
                            :var ((b #!b)
                                  (c #!c))
                            (* b c))
                          (blet #!x
                            :var ((a #!a)
                                  (b #!b)
                                  (d #!d))
                            (* a b d))
                          (blet #!x
                            :var ((b #!b))
                            b)


                         After the  first  binding  is  declared,  any
                         change  to #!a or #!b will cause the variable
                         #!x to be set to their sum.  After the second
                         binding  is  declared,  changes to #!b or #!c
                         will set #!x to the product of  #!b  and  #!c
                         but  changes to #!a will still set #!x to the
                         sum of #!a and #!b.  After the third  binding
                         is  declared,  any change to #!a, #!b, or #!d
                         uses the third function.  Only changes to #!c
                         would  use  the  second  function.  The first
                         binding is no longer active, and is automati-
                         cally  removed  by  PICASSO.  This first con-
                         straint is referred to  as  _s_u_p_e_r_c_e_d_e_d  since
                         each  of  the  data  values  which  propagate
                         changes to #!x _a_r_e _n_o_w _t_a_k_e_n _c_a_r_e _o_f _b_y  _m_o_r_e
                         _r_e_c_e_n_t _b_i_n_d_i_n_g_s.



          PICASSO Reference Manual                                6-96







                                              PROPAGATION AND TRIGGERS


                         The fourth binding supercedes all of the ear-
                         lier  ones.   This  illustrates the _s_u_p_e_r_s_e_t-
                         _o_r-_s_u_b_s_e_t rule used to determine when a bind-
                         ing  is  automatically  nullified  (removed).
                         This rule states that when the set of  depen-
                         dees in a newly declared binding are a super-
                         set of, or a subset of  the  dependees  of  a
                         previous binding then the previous binding is
                         nullified.   The  rationale  behind  this  is
                         clear  in  the  case above.  If the user says
                         that #!x _s_h_o_u_l_d _b_e _b_o_u_n_d _t_o #!_b  then  it  is
                         clear  that #!x _s_h_o_u_l_d _n_o_t _b_e _a_l_s_o _b_o_u_n_d _t_o _a
                         _s_u_m _o_r _p_r_o_d_u_c_t _i_n_v_o_l_v_i_n_g #!_b since that would
                         either  impose  unreasonable  restrictions on
                         the other dependees or result  in  a  set  of
                         asserted  constraints which do not make sense
                         declaratively.

                         This use of the superset-or-subset rule  also
                         avoids  most  cycles of constraints which are
                         not  mutually  satisfyable.   This  issue  is
                         dealt  with  in  more detail in the Technical
                         Notes section below.

                         _____________________________________________

          REMOVING
          CON-
          STRAINTS




                         In addition to nullifying bindings  automati-
                         cally,  PICASSO  allows  the  user  to remove
                         bindings explicitly.  If the user has a  han-
                         dle  for  the  binding,  generated  with  the
                         _r_e_c_e_i_p_t option  in  bind-slot  _a_n_d  _b_i_n_d-_v_a_r,
                         then he may remove the binding with the func-
                         tion

                     unbind-fast

                                                            [_F_u_n_c_t_i_o_n]
                         _r_e_c_e_i_p_t
                         This function takes the  handle  and  removes
                         the binding.  If no handle is available, then
                         alternative forms are available to remove the
                         binding.

                     unbind-slot

                                                            [_F_u_n_c_t_i_o_n]
                         _s_l_o_t-_n_a_m_e
                         _o_b_j_e_c_t
                         _e_x_p_r_e_s_s_i_o_n
                         &key
                         (_u_n_b_i_n_d-_s_u_p_e_r_s_e_t_s _t)
                         (unbind-subsets t)






          PICASSO Reference Manual                                6-97







                                              PROPAGATION AND TRIGGERS


                     unbind-var

                                                            [_F_u_n_c_t_i_o_n]
                         _v_a_r-_n_a_m_e
                         _r_e_f_e_r_e_n_c_e
                         _e_x_p_r_e_s_s_i_o_n
                         &key
                         (_u_n_b_i_n_d-_s_u_p_e_r_s_e_t_s _t)
                         (unbind-subsets t)

                         Unbind-slot should be called  with  the  same
                         slot-name  and  object  used  for the call to
                         bind-slot.  The expression can be the same as
                         the   function  given  to  bind-slot  or  any
                         expression which has  the  same  set  of  var
                         clauses.   It  is preferable to avoid expres-
                         sions evaluated using the comma  macro  since
                         they take execution time without contributing
                         to the dependee  list.   unbind-slot  removes
                         any bindings with exactly the same dependees.
                         In addition, if _u_n_b_i_n_d-_s_u_p_e_r_s_e_t_s is true (the
                         default) then any bindings with a superset of
                         the dependees are removed.  If _u_n_b_i_n_d-_s_u_b_s_e_t_s
                         is  true (the default) then any bindings with
                         a subset of the dependees are removed.

                         Unbind-var is called with a variable name and
                         a  reference  to  the location to resolve the
                         name from.  The rest of the arguments are the
                         same as for unbind-slot.

                         These two functions are very powerful.   They
                         can  be used to remove large numbers of bind-
                         ings at once.  At the  same  time,  they  are
                         very dangerous and should be avoided by inex-
                         perienced users.  The combination of receipts
                         and   automatic   nullification  will  handle
                         almost all cases.

                         _____________________________________________

          TECHNICAL
          NOTES



                         There are a few details about the implementa-
                         tion  of  bindings  of  which users should be
                         aware because they  have  an  impact  on  the
                         functionality in extreme cases.  This section
                         presents several of these details.   Many  of
                         these  are  limitations  which  we anticipate
                         removing in a later release of PICASSO or are
                         considering changing in future releases.  Any
                         such changes will be  noted  in  the  Release
                         Notes of such future releases.





          PICASSO Reference Manual                                6-98







                                              PROPAGATION AND TRIGGERS


                         Propagation is  implemented  by  Common  Lisp
                         setf  methods.  The dependees in any propaga-
                         tion have their setf method altered to  check
                         for a change and to propagate to their depen-
                         dents.  The data value being  constrained  is
                         updated  by using its own setf method to give
                         it a new value. This  allows  propagation  to
                         continue   through  multiple  bindings  until
                         values stop changing.  This implementation of
                         propagation  leads to several restrictions on
                         the use of bindings.

                         The first restriction  involves  the  use  of
                         virtual  slots.   Since virtual slots have no
                         storage, and therefore no  memory,  they  are
                         unable  to  determine  whether they are being
                         set to the  same  value  they  already  have.
                         Since  PICASSO  relies  on  this technique to
                         detect propagation loops, no loop may be  set
                         up with only virtual slots.  A loop must con-
                         tain at least one real slot or variable.

                         An additional consequence of the use of  setf
                         methods  for  propagation is that some values
                         may not wish to propagate all  changes,  only
                         changes  that are ``major'' in some way.  For
                         instance,  a  text  widget  only   propagates
                         changes to its data when the user is finished
                         editing.  To allow this, the user can  estab-
                         lish  a binding for the slot (or other value)
                         but not use the setf method  when  performing
                         incremental  updates.  A function is provided
                         for triggering a propagation by hand.

                     do-propagate

                                                            [_F_u_n_c_t_i_o_n]
                         _v_a_r_i_a_b_l_e

                     do-propagate

                                                            [_F_u_n_c_t_i_o_n]
                         _s_l_o_t-_n_a_m_e
                         _o_b_j_e_c_t
                         Either form triggers a  propagation  just  as
                         though  the  variable,  slot, or virtual slot
                         had been changed by use of a setf _m_e_t_h_o_d.

                         A final consequence of this implementation is
                         seen  when  dealing  with  objects which have
                         components.  As shown  in  the  example,  the
                         binding  mechanism can be used to detect when
                         a variable points to a new object, or when  a
                         slot  in  an existing object changes, but not
                         both.  This is the result of an  optimization
                         which   resolves  all  references  into  hard



          PICASSO Reference Manual                                6-99







                                              PROPAGATION AND TRIGGERS


                         pointers.  A technique for handling the prob-
                         lem case is shown in the section on triggers.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Triggers


                         Triggers are code attachments which are  exe-
                         cuted   whenever  the  data  value  they  are
                         attached to changes.   They  are  similar  to
                         bindings  but  do not necessarily propagate a
                         new value to a data  object.   Instead,  they
                         may  take  actions including, if needed, cal-
                         ling a dialog box or  performing  a  database
                         query.

                         _____________________________________________

          SETTING
          TRIGGERS



                         A trigger can be set  on  any  slot,  PICASSO
                         variable,  or  virtual  slot.  The  following
                         forms can be used to set triggers.

                     set-trigger

                                                               [_M_a_c_r_o]
                         _s_l_o_t-_n_a_m_e
                         _o_b_j_e_c_t
                         _c_o_d_e

                     set-trigger

                                                               [_M_a_c_r_o]
                         _p_i_c_a_s_s_o-_v_a_r_i_a_b_l_e
                         _c_o_d_e
                         Both forms accept code in  a  form  ready  to
                         evaluate  without  any  specific lexical con-
                         text.  Any  resolution  of  Lisp  or  PICASSO
                         variables should be done in advance using the
                         backquote macro and, if necessary, the  comma
                         macro  as  well.   When a trigger is set, the
                         code attached is automatically executed once.
                         This corresponds to the fact that the trigger
                         cannot know  whether  the  variable  or  slot
                         value is new or original.

                         Once a trigger is  set,  any  change  to  the
                         value of the slot or variable causes the code
                         to  be  executed.   The  changes  must  occur
                         through  the  use  of  the  Lisp  setf  form.
                         Changes made in other ways do not trigger the
                         code.   The  code  does  not execute when the
                         value set is not different from the  previous
                         value  except  in  the  case of virtual slots







          PICASSO Reference Manual                               6-100







                                              PROPAGATION AND TRIGGERS


                         which trigger the code with every setf.

                         _____________________________________________

          EXAMPLE


                         The typical trigger is set to handle a condi-
                         tion  which  can  only  occur  when a certain
                         value changes.  The following  trigger  would
                         call  a  Lisp  function  whenever the PICASSO
                         variable age exceeds 65.


                          (set-trigger #!age
                             '(if (> (value ',#?age) 65)
                                  (force-retirement)))


                         Note that the use of backquote and comma  are
                         necessary  here  because  the trigger code is
                         executed in an empty lexical environment.   A
                         similar  example  will  alert the user when a
                         text field contains inappropriate language:


                          (set-trigger 'value #!text-area
                             `(if (bad-words-in (value ',#!text-area))
                                  (call ',#!alert-dialog)))


                         In this case, the quote and comma are used to
                         evaluate  #!text-area to get a pointer to the
                         specific text widget.  When quoted, this  can
                         be  used later by the value method to get the
                         actual text.  Similarly, the variable  alert-
                         dialog is resolved at the time the trigger is
                         set.

                         We have seen that bindings alone  are  unable
                         to  handle  the case where both an object and
                         its slots may be changed externally.  By com-
                         bining  bindings with triggers we can develop
                         a solution to this problem.  Assume we have a
                         PICASSO  variable _e_m_p_l_o_y_e_e which points to an
                         object.  The object has  a  slot  _n_a_m_e  which
                         holds  the employee's name.  We have a second
                         PICASSO variable _e_m_p-_n_a_m_e which would like to
                         be bound to the employee's name regardless of
                         whether the object  changes  (and  #!_e_m_p_l_o_y_e_e
                         points  to  a  new  object) or the slot value
                         changes within the same object.  This follow-
                         ing  code  sets  up  precisely  that binding.
                         Assume, for  simplicity,  that  both  PICASSO



          PICASSO Reference Manual                               6-101







                                              PROPAGATION AND TRIGGERS


                         variables  are defined in the current lexical
                         environment.


                       (let ((trigger-code
                                 `(let ((emp-object (value ',#?employee))
                                        (name-loc   ',#?emp-name))
                                       (eval `(bind-slot 'value  `,name-loc
                                                  (list 'var
                                                        'name
                                                        ',emp-object))))))
                            (eval `(set-trigger #!employee ',trigger-code)))


                         This is a rather complex example.  The  outer
                         let   statement  creates  the  code  for  the
                         trigger and then evaluates a set-trigger call
                         with  that  code  on  the  employee variable.
                         Thus, whenever #!employee  points  to  a  new
                         object, this code will be executed.  The code
                         itself is a let which takes advantage to  the
                         backquote   macro   twice  to  plug  in  both
                         trigger-set-time  and  bind-time   constants.
                         This let sets up two local variables with the
                         location of the  employee  name  and  with  a
                         pointer  to  the  employee  record (both gen-
                         erated from trigger-set-time  values,  though
                         the  pointer itself is resolved at bind time)
                         and then binds the employee name variable  to
                         the name slot in the employee object.  A more
                         efficient implementation  could  also  remove
                         old  bindings  by  generating receipts (or by
                         using unbind functions).

                         This last example is about as complicated  as
                         triggers  and  binding  can  get.   The  code
                         illustrates that triggers are implemented  on
                         top  of bindings.  As such, the var structure
                         is synthesized at bind time so as not  to  be
                         misinterpreted by the trigger handler.

                         _____________________________________________

          REMOVING
          TRIGGERS



                         There is no explicit  function  for  removing
                         triggers.  Instead, set a trigger with nil as
                         the function.  Each trigger on a  data  loca-
                         tion  replaces the previous one and therefore
                         setting the code to nil  effectively  removes






          PICASSO Reference Manual                               6-102







                                              PROPAGATION AND TRIGGERS


                         the trigger.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Lazy
          Evaluation



                         PICASSO supports slots which serve as  caches
                         for  computed  values.  A slot is referred to
                         as  _l_a_z_y when it recomputes  its  value  only
                         when the value is read.  Lazy slots only mark
                         the cache as invalid when a setf _o_p_e_r_a_t_i_o_n _i_s
                         _p_e_r_f_o_r_m_e_d  _o_n _t_h_e_m.  _L_a_z_y _s_l_o_t_s _a_r_e _m_o_s_t _u_s_e_-
                         _f_u_l _w_h_e_n _t_h_e _c_o_m_p_u_t_a_t_i_o_n _n_e_e_d_e_d _t_o _u_p_d_a_t_e _t_h_e
                         _s_l_o_t  _i_s _e_x_p_e_n_s_i_v_e _a_n_d _t_h_e _s_l_o_t _i_s _w_r_i_t_t_e_n _t_o
                         _m_a_n_y _m_o_r_e _t_i_m_e_s _t_h_a_n _i_t _i_s _r_e_a_d _f_r_o_m.

                         _____________________________________________

          MAKING
          SLOTS LAZY



                         Two functions exist for  making  slots  lazy.
                         To  make a slot lazy for every instance in an
                         entire class, use:

                     make-slot-lazy-for-class

                                                            [_F_u_n_c_t_i_o_n]
                         _s_l_o_t-_n_a_m_e
                         _c_l_a_s_s-_n_a_m_e
                         _c_o_m_p_u_t_a_t_i_o_n
                         _S_l_o_t-_n_a_m_e and _c_l_a_s_s-_n_a_m_e are the names of the
                         respective slot and class.  They should typi-
                         cally be quoted, although they can be expres-
                         sions  that evaluate to slot and class names.
                         The computation should be an expression which
                         can  be  evaluated  to  yield the appropriate
                         value for the slot.  It is evaluated whenever
                         the cache needs to be updated.

                         The function  make-slot-lazy-for-instance  is
                         used  to  make  a slot lazy only for a single
                         instance of the class.

                     make-slot-lazy-for-instance

                                                            [_F_u_n_c_t_i_o_n]
                         _s_l_o_t-_n_a_m_e
                         _o_b_j_e_c_t
                         _c_o_m_p_u_t_a_t_i_o_n
                         The only difference between this function and
                         make-slot-lazy-for-class  _i_s  _t_h_a_t _t_h_i_s _f_u_n_c_-
                         _t_i_o_n _t_a_k_e_s _a_n _o_b_j_e_c_t _i_n_s_t_e_a_d _o_f _a _c_l_a_s_s _n_a_m_e.

                         Once a slot is lazy, setf _o_f _a_n_y  _v_a_l_u_e  _i_n_t_o
                         _t_h_a_t _s_l_o_t _m_e_r_e_l_y _m_a_r_k_s _i_t _i_n_v_a_l_i_d.  _T_h_e _m_a_c_r_o
                         _i_n_v_a_l_i_d-_p can be used to check whether a slot






          PICASSO Reference Manual                               6-103







                                              PROPAGATION AND TRIGGERS


                         value is invalid.

                     invalid-p

                                                               [_M_a_c_r_o]
                         _v_a_l_u_e
                         This macro can be used to check  whether  the
                         slot value _v_a_l_u_e is invalid. For example,


                          (invalid-p (value entry-widget))


                         is used to check whether the  value  slot  of
                         the  specified  entry  widget is invalid.  In
                         addition, the function lazy-p _c_a_n _b_e _u_s_e_d  _t_o
                         _t_e_l_l _w_h_e_t_h_e_r _a _s_l_o_t _i_n _a _p_a_r_t_i_c_u_l_a_r _o_b_j_e_c_t _i_s
                         _l_a_z_y _o_r _n_o_t.

                     lazy-p

                                                            [_F_u_n_c_t_i_o_n]
                         _s_l_o_t-_n_a_m_e
                         _o_b_j_e_c_t

                         This Function can be used to tell whether the
                         slot  _s_l_o_t-_n_a_m_e  in the object _o_b_j_e_c_t is lazy
                         or not.

                         _____________________________________________

          EXCLUDING
          SUBCLASSES
          FROM LAZI-
          NESS





                         When a class has  be  made  lazy  with  make-
                         slot-lazy-for-class,   all   subclasses  also
                         inherit the laziness.  To specify that a sub-
                         class  should not treat the slot as lazy, use
                         the function make-slot-unlazy-for-subclass.

                     make-slot-unlazy-for-subclass

                                                            [_F_u_n_c_t_i_o_n]
                         _s_l_o_t-_n_a_m_e
                         _c_l_a_s_s-_n_a_m_e
                         This function will make a subclass,  and  all
                         of its subclasses, unlazy for that slot.

                         _____________________________________________

          TECHNICAL
          NOTES



                         For most purposes,  the  programmer  can  set
                         lazy  slots  and  ignore them.  When they are
                         written to, they  become  invalid,  but  when
                         they  are  read  from  they automatically re-
                         cache the computed value.  Of course, it does
                         not  make sense to propagate from a lazy slot
                         (since that would  automatically  generate  a
                         read  for  every  write) and it does not make
                         sense to  make  slots  lazy  when  they  have



          PICASSO Reference Manual                               6-104







                                              PROPAGATION AND TRIGGERS


                         visible side effects (such as displaying data
                         on the screen).

                         Lazy evaluation slots should  be   used  very
                         carefully.    They  can  improve  performance
                         dramatically, but only when  the  computation
                         or  side  effect  being  avoided is expensive
                         enough to support the caching overhead.   The
                         implementation  of setf for lazy slots merely
                         shoves a marker into  the  slot  to  mark  it
                         invalid.   The accessor method will check the
                         cache and read it, if it  is  up-to-date,  or
                         refresh  it from the computation.  Lazy slots
                         can be  bound  to  other  slots,  since  this
                         merely  serves  to  cut  off  the propagation
                         chain early.  They cannot be bound to,  since
                         this would completely defeat lazy evaluation.






































          PICASSO Reference Manual                               6-105







                                                           COLLECTIONS


                                               7
                                          COLLECTIONS

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         Widgets in PICASSO are grouped  into  collec-
                         tions  which  arrange  them on the screen and
                         control their display attributes.  Forms  are
                         a  type  of collection used in the framework.
                         Each collection uses a  _g_e_o_m_e_t_r_y  _m_a_n_a_g_e_r  to
                         specify  the  layout  of  the widgets it con-
                         tains.   PICASSO   has   several   predefined
                         geometry  managers  as well as the facilities
                         for defining new ones.

                         This chapter documents the following:

                         o+    Collections

                         o+    Anchor-GM

                         o+    Packed-GM

                         o+    Stacked-GM

                         o+    Matrix-GM

                         o+    Root-GM

                         o+    Null-GM
          ____________________________________________________________________________________________________________________________________________________________________________________

          Collec-
          tions



                         PICASSO windows are organized in a hierarchy,
                         with  ancestors  enclosing their descendents.
                         However, many windows do not  have  children.
                         For  example, most widgets that appear on the
                         screen (i.e., buttons) do not have  children.
                         Collections,   which  are  comprised  of  the
                         _c_o_l_l_e_c_t_i_o_n-_g_a_d_g_e_t class and  its  subclasses,
                         most   notably   _c_o_l_l_e_c_t_i_o_n-_w_i_d_g_e_t,  are  the
                         PICASSO abstractions for  windows  that  have
                         children.

                         A question all collections  must  answer  is,
                         what happens when the collection changes size
                         (is ``resized'')?  Do the children just  stay
                         the  same  size,  or  are they, too, resized?
                         Consider, for example, a  collection  with  a
                         title bar, a scroll-bar, and a text-editor as
                         children.  When this collection  is  resized,



          PICASSO Reference Manual                               7-106







                                                           COLLECTIONS


                         we'd like the title-bar to span left to right
                         along the top of the collection, the  scroll-
                         bar to remain on the right side, spanning top
                         to bottom in the  remaining  space,  and  the
                         text-editor  to  fill  in  whatever  space is
                         left.  Other tools  will  behave  differently
                         when  the are resized.  The problem of resiz-
                         ing the children of  a  collection  when  the
                         collection  is  resized  is  called  _g_e_o_m_e_t_r_y
                         _m_a_n_a_g_e_m_e_n_t, and the action  of  resizing  and
                         moving  the  children of a collection is call
                         _r_e_p_a_c_k_i_n_g.

                         A collection in PICASSO  is  responsible  for
                         managing  the  layout  of  its children.  The
                         child's geometry is stored in _x, _y, _w_i_d_t_h and
                         _h_e_i_g_h_t  slots, combinations of which form the
                         child's _l_o_c_a_t_i_o_n (x, y), _s_i_z_e (width, height)
                         and _r_e_g_i_o_n (x, y, width, height).

                         _____________________________________________

          CREATING
          COLLECTION-
          GADGETS




                         Collection gadgets are a subclass of gadgets.
                         As  a subclass, they inherit keys and methods
                         from gadgets.

                     make-collection-gadget

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_n_a_m_e "_A _C_o_l_l_e_c_t_i_o_n")
                         (value "Collection")
                         (_g_m '_n_u_l_l-_g_m)
                         (children nil)
                         (_r_e_p_a_c_k-_f_l_a_g _n_i_l)
                         (repack-needed nil)
                         (_c_o_n_f_o_r_m :_g_r_o_w-_s_h_r_i_n_k)
                         (repack-count 0)
                         (_m_i_n-_s_i_z_e _n_i_l)
                         (gm-data nil)
                         ;; Defaults inherited from gadgets:
                         (_s_t_a_t_u_s :_e_x_p_o_s_e_d)
                         (font *default-font-name*)
                         (_b_a_c_k_g_r_o_u_n_d _n_i_l)
                         (dimmed-background nil)
                         (_i_n_v_e_r_t_e_d-_b_a_c_k_g_r_o_u_n_d _n_i_l)
                         ;; Plus keys inherited from window
                         &allow-other-keys








          PICASSO Reference Manual                               7-107







                                                           COLLECTIONS


                         _____________________________________________

          CREATING
          COLLECTION-
          WIDGETS




                         Collection widgets are  a  subclass  of  both
                         widgets  and  collection  gadgets.  As a sub-
                         class, collection widgets  inherit  the  keys
                         and methods specified for widgets and collec-
                         tion gadgets.

                     make-collection-widget

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_e_v_e_n_t-_m_a_s_k '( :_e_x_p_o_s_u_r_e))
                         (background "white")
                         (_i_n_v_e_r_t_e_d-_b_a_c_k_g_r_o_u_n_d "_b_l_a_c_k")
                         (dimmed-background "white")
                         (_f_o_r_e_g_r_o_u_n_d "_b_l_a_c_k")
                         (dimmed-foreground "black")
                         (_i_n_v_e_r_t_e_d-_f_o_r_e_g_r_o_u_n_d "_w_h_i_t_e")
                         ;; Defaults inherited from widgets:
                         (name "A Widget")
                         (status :exposed)
                         ;; Defaults inherited from collection gadgets:
                         (value "Collection")
                         (gm 'null-gm)
                         (children nil)
                         (repack-flag nil)
                         (repack-needed nil)
                         (conform :grow-shrink)
                         (repack-count 0)
                         (min-size nil)
                         (gm-data nil)
                         ;; Defaults inherited from gadget:
                         (font *default-font-name*)
                         ;; Plus keys inherited from window, opaque window and x-window
                         &allow-other-keys

                         _____________________________________________

          COLLECTION
          ATTRIBUTES




                         Most of the interesting attributes of collec-
                         tions   are   used  in  geometry  management.
                         Attributes fall into two major classes.   One
                         is  used  to  determine  the base-size of the
                         collection, and the other specifies  how  the
                         collections  children  are  resized  when the
                         collection is resized.

                         Since collection widgets are  a  subclass  of
                         collection   gadgets,  these  attributes  are





          PICASSO Reference Manual                               7-108







                                                           COLLECTIONS


                         inherited by collection widgets.

                     children

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _c_o_l_l_e_c_t_i_o_n-_g_a_d_g_e_t)
                         This method returns a list of the child  win-
                         dows  of  the  collection-gadget  _s_e_l_f.  This
                         value should not be setf'd by an  application
                         program;  use  the  add-child  macro to add a
                         subwindow instead.

                     conform

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _c_o_l_l_e_c_t_i_o_n-_g_a_d_g_e_t)

                         This method returns the conformity specifica-
                         tion  of the collection-gadget _s_e_l_f.  It will
                         be one of the values :grow-only, :_g_r_o_w-_s_h_r_i_n_k
                         or  :dont-conform,  _e_a_c_h  _o_f  _w_h_i_c_h  _w_i_l_l  _b_e
                         _d_e_s_c_r_i_b_e_d _b_e_l_o_w. _T_h_i_s _v_a_l_u_e _m_a_y _b_e _s_e_t_f'd.

                         Recall that the base-size of a window is  the
                         minimum width and height the window should be
                         sized to in order to reasonably  display  its
                         data.   For  example,  a window that displays
                         the string ``Hello'' would set it's base-size
                         to  the  size needed to display those charac-
                         ters in its current font.

                         The base-size for a collection  is,  in  gen-
                         eral,  a  function  of  the base-sizes of the
                         children.   This   conformity   specification
                         defines how to map from the base-sizes of the
                         children to the base-size of the  collection-
                         gadget  in the following way.  If the confor-
                         mity specification is :dont-conform, then the
                         base-size  of the collection-gadget is simply
                         composed from the value stored in  the  base-
                         width  and base-height slots.  If the confor-
                         mity specification is :grow-shrink, then  the
                         base-width  of  the  collection-gadget is the
                         minimum of the value stored in the base-width
                         slot and the smallest width needed to fit all
                         the children on the screen such that none  of
                         the children has a width smaller than its own
                         base-width.   The  base-height  is   computed
                         similarly.    Finally,   if   the  conformity
                         specification is :grow-only, then  the  base-
                         width  of  the  collection-gadget is computed
                         the same as in the :grow-shrink case,  except
                         that the value is never decremented.

                     gm

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _c_o_l_l_e_c_t_i_o_n-_g_a_d_g_e_t)



          PICASSO Reference Manual                               7-109







                                                           COLLECTIONS


                         This method returns a symbol that  identifies
                         the  type  of geometry-manager used to repack
                         the children of the  collection-gadget  _s_e_l_f.
                         Currently,  PICASSO  supports  the  following
                         geometry-managers:   anchor-gm,    matrix-gm,
                         packed-gm,  root-gm,  stacked-gm and nil, the
                         ``null-gm''.  Specifics about  each  type  of
                         geometry-manager  are  given in the following
                         sections.  This value may be setf'd.

                     gm-data

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _c_o_l_l_e_c_t_i_o_n-_g_a_d_g_e_t)
                         This method returns the _g_m-_d_a_t_a used  by  the
                         geometry-manager   of  the  collection-gadget
                         _s_e_l_f.  The gm-data  is  extra  data  used  by
                         specific geometry-managers in repacking their
                         children.   Currently,   the   only   PICASSO
                         geometry-managers  that  use  gm-data are the
                         matrix-gm  and  the  stacked-gm.    Specifics
                         about  what  goes into this slot are given in
                         the  following  sections  on  each  geometry-
                         manager.  This value may be setf'd.

                     min-size

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _c_o_l_l_e_c_t_i_o_n-_g_a_d_g_e_t)

                     repack-flag

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _c_o_l_l_e_c_t_i_o_n-_g_a_d_g_e_t)
                         This method returns the  _r_e_p_a_c_k-_f_l_a_g  of  the
                         collection-gadget  _s_e_l_f.   This flag, if nil,
                         _p_r_e_v_e_n_t_s _a _c_o_l_l_e_c_t_i_o_n  _f_r_o_m  _b_e_i_n_g  _r_e_p_a_c_k_e_d.
                         _T_h_i_s _i_s _u_s_e_f_u_l _w_h_e_n _m_a_n_y _c_h_a_n_g_e_s _w_i_l_l _b_e _m_a_d_e
                         _o_n _a _c_o_l_l_e_c_t_i_o_n, _a_n_d _i_t _w_o_u_l_d _b_e _w_a_s_t_e_f_u_l  _t_o
                         _r_e_p_a_c_k  _b_e_f_o_r_e  _a_l_l _t_h_e _c_h_a_n_g_e_s _a_r_e _f_i_n_i_s_h_e_d.
                         _F_o_r  _e_x_a_m_p_l_e,  _w_h_e_n  _i_n_i_t_i_a_l_l_y  _c_r_e_a_t_i_n_g  _t_h_e
                         _c_o_l_l_e_c_t_i_o_n-_g_a_d_g_e_t,  _c_h_i_l_d_r_e_n  _a_r_e _b_e_i_n_g _a_d_d_e_d
                         _a_n_d _i_f _a _r_e_p_a_c_k _w_e_r_e _p_e_r_f_o_r_m_e_d  _e_a_c_h  _t_i_m_e  _a
                         _c_h_i_l_d _w_a_s _a_d_d_e_d, _t_h_e _r_u_n_n_i_n_g _t_i_m_e _o_f _c_r_e_a_t_i_n_g
                         _t_h_e _c_o_l_l_e_c_t_i_o_n-_g_a_d_g_e_t _w_o_u_l_d  _b_e  _p_r_o_p_o_r_t_i_o_n_a_l
                         _t_o  _t_h_e _s_q_u_a_r_e _o_f _t_h_e _n_u_m_b_e_r _o_f _c_h_i_l_d_r_e_n.  _I_f
                         _t_h_e _r_e_p_a_c_k-_f_l_a_g _i_s _s_e_t _t_o _n_i_l while the chil-
                         dren  are being created, then only one repack
                         need be done after all the  children  are  in
                         place,  resulting  in a run time proportional
                         to the number of  children.   This  value  is
                         normally   changed  via  the  repack-off  _a_n_d
                         _r_e_p_a_c_k-_o_n  macros,  though  it  may  also  be








          PICASSO Reference Manual                               7-110







                                                           COLLECTIONS


                         setf'_d.

                         _____________________________________________

          COLLECTION
          MACROS




                     add-child

                                                               [_M_a_c_r_o]
                         _c_o_l_l_e_c_t_i_o_n
                         _c_h_i_l_d
                         This macro adds _c_h_i_l_d to the list of children
                         of  _c_o_l_l_e_c_t_i_o_n,  and  informs  the  geometry-
                         manager of _c_o_l_l_e_c_t_i_o_n of the change  by  cal-
                         ling  the  gm-add-child _m_e_t_h_o_d.  _T_h_i_s _h_a_s _t_h_e
                         _s_i_d_e-_e_f_f_e_c_t _o_f _r_e_p_a_c_k_i_n_g _a_n_d _r_e_p_a_i_n_t_i_n_g  _c_o_l_-
                         _l_e_c_t_i_o_n _a_s _n_e_c_e_s_s_a_r_y.

                     delete-child

                                                               [_M_a_c_r_o]
                         _c_o_l_l_e_c_t_i_o_n
                         _c_h_i_l_d
                         This macro removes _c_h_i_l_d  from  the  list  of
                         children   of  _c_o_l_l_e_c_t_i_o_n,  and  informs  the
                         geometry-manager of _c_o_l_l_e_c_t_i_o_n of the  change
                         by  calling the gm-delete-child _m_e_t_h_o_d.  _T_h_i_s
                         _h_a_s _t_h_e _s_i_d_e-_e_f_f_e_c_t _o_f _r_e_p_a_c_k_i_n_g _a_n_d _r_e_p_a_i_n_t_-
                         _i_n_g _c_o_l_l_e_c_t_i_o_n _a_s _n_e_c_e_s_s_a_r_y.

                     force-repack

                                                               [_M_a_c_r_o]
                         _c_o_l_l_e_c_t_i_o_n
                         This macro forces a repack of  a  collection-
                         gadget,   regardless  of  the  value  of  the
                         repack-flag or whether the window is exposed,
                         concealed  or  pending.   The min-size of the
                         collection is also recalculated.  This  macro
                         is  rarely  used by the user, except interac-
                         tively in debugging or designing.

                     just-repack

                                                               [_M_a_c_r_o]
                         _c_o_l_l_e_c_t_i_o_n
                         This macro forces a repack of  a  collection-
                         gadget,   regardless  of  the  value  of  the
                         repack-flag or whether the window is exposed,
                         concealed  or  pending.   Its function is the
                         same as the force-repack _m_a_c_r_o,  _e_x_c_e_p_t  _t_h_a_t
                         _t_h_e  _m_i_n-_s_i_z_e _o_f _t_h_e _c_o_l_l_e_c_t_i_o_n _i_s _n_o_t _r_e_c_a_l_-
                         _c_u_l_a_t_e_d.  _T_h_i_s _m_a_c_r_o _i_s _r_a_r_e_l_y  _u_s_e_d  _b_y  _t_h_e
                         _u_s_e_r, _e_x_c_e_p_t _i_n_t_e_r_a_c_t_i_v_e_l_y.

                     repack

                                                               [_M_a_c_r_o]
                         _c_o_l_l_e_c_t_i_o_n
                         This macro repacks a collection-gadget if the
                         collection is exposed, the repack-flag is on,
                         and a repack is needed.  If no recent changes



          PICASSO Reference Manual                               7-111







                                                           COLLECTIONS


                         have  been  made  that  may have effected the
                         children, then this macro has no effect.   It
                         is  rarely  used by the user, except interac-
                         tively.

                     repack-off

                                                               [_M_a_c_r_o]
                         _c_o_l_l_e_c_t_i_o_n
                         This  macro  sets  the  repack-flag  of   the
                         collection-gadget  to  nil,  _i._e.,  _i_t  _t_u_r_n_s
                         _r_e_p_a_c_k_i_n_g _o_f_f  _f_o_r  _a  _c_o_l_l_e_c_t_i_o_n.   _S_e_e  _t_h_e
                         _d_o_c_u_m_e_n_t_a_t_i_o_n _f_o_r _t_h_e _r_e_p_a_c_k-_f_l_a_g  method for
                         further details.

                     repack-on

                                                               [_M_a_c_r_o]
                         _c_o_l_l_e_c_t_i_o_n
                         This  macro  sets  the  repack-flag  of   the
                         collection-gadget   to   t,  _i._e.,  _i_t  _t_u_r_n_s
                         _r_e_p_a_c_k_i_n_g _o_n _f_o_r _a _c_o_l_l_e_c_t_i_o_n _a_n_d _r_e_p_a_c_k_s _t_h_e
                         _c_o_l_l_e_c_t_i_o_n  _i_f _n_e_c_e_s_s_a_r_y.  _S_e_e _t_h_e _d_o_c_u_m_e_n_t_a_-
                         _t_i_o_n _f_o_r _t_h_e _r_e_p_a_c_k-_f_l_a_g method  for  further
                         details.

                         _____________________________________________

          COLLECTION
          SUMMARY





                          ______________________________________________
                           Reader Methods   Setf Methods   Macros
                          ____________________________________________________________________________________________
                           children                        add-child
                           conform          conform        delete-child
                           gm               gm             force-repack
                           gm-data          gm-data        just-repack
                           repack-flag      repack-flag    repack
                                                           repack-off
                                                           repack-on
                          ______________________________________________

                         |
                         |
                         |
                         |
                         |
                         |
                         |
                         |
                         |
                         |








                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |








                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |








                                                                       |
                                                                       |
                                                                       |
                                                                       |
                                                                       |
                                                                       |
                                                                       |
                                                                       |
                                                                       |
                                                                       |











          ____________________________________________________________________________________________________________________________________________________________________________________

          Anchor-GM


                         Anchor-gm  handles  reshaping   of   children
                         according  to  the  placement  of  figurative
                         ``anchors'' and ``arrows''.  Arrows are  used
                         to  specify  that  a window can be stretched.
                         Anchors can be thought of  as  thumbtacks  on
                         the side of a window -- they specify that the
                         given side should be pinned down at a  speci-
                         fied distance from the side of the parent




          PICASSO Reference Manual                               7-112







                                                           COLLECTIONS


                         The geom-spec of the child of an anchor-gm is
                         a  list  of  (%x  %y %width %height <_a_n_c_h_o_r_s>
                         <_a_r_r_o_w_s> (:borders nil) (:label  nil))  _w_h_e_r_e
                         _a_r_r_o_w_s,  _a_n_c_h_o_r_s,  (:_b_o_r_d_e_r  _n_i_l) _a_n_d (:_l_a_b_e_l
                         _n_i_l)  _a_r_e  _o_p_t_i_o_n_a_l.   %_x,  %_y,  %_w_i_d_t_h   _a_n_d
                         %_h_e_i_g_h_t  _a_r_e  _n_u_m_b_e_r_s  _b_e_t_w_e_e_n  _0._0  _a_n_d _1._0,
                         _i_n_c_l_u_s_i_v_e, _a_n_d _s_p_e_c_i_f_y _t_h_e _l_o_c_a_t_i_o_n _a_n_d  _p_e_r_-
                         _c_e_n_t  _o_f  _t_h_e  _r_e_g_i_o_n  _t_h_e  _c_h_i_l_d _w_i_l_l _o_c_c_u_p_y
                         _w_i_t_h_i_n _t_h_e _p_a_r_e_n_t, _w_i_t_h  _t_h_e  _o_r_i_g_i_n  _i_n  _t_h_e
                         _u_p_p_e_r _l_e_f_t _c_o_r_n_e_r _o_f _t_h_e _p_a_r_e_n_t. _F_o_r _e_x_a_m_p_l_e,
                         _s_p_e_c_i_f_y_i_n_g _a %_w_i_d_t_h _o_f _0._7_5 _w_o_u_l_d _i_m_p_l_y  _t_h_a_t
                         _t_h_e  _c_h_i_l_d  _s_h_o_u_l_d _a_l_w_a_y_s _b_e _7_5% _o_f _t_h_e _w_i_d_t_h
                         _o_f _t_h_e _p_a_r_e_n_t. _I_f %_x _i_s _0._1 _a_n_d _t_h_e _p_a_r_e_n_t _i_s
                         _1_0_0  _p_i_x_e_l_s  _w_i_d_e,  _t_h_e_n  _t_h_e  _c_h_i_l_d  _w_i_l_l _b_e
                         _p_l_a_c_e_d _a_t _a_n _x-_o_f_f_s_e_t _o_f _1_0 _p_i_x_e_l_s.  _S_p_e_c_i_f_y_-
                         _i_n_g _p_e_r_c_e_n_t_a_g_e_s _i_m_p_l_i_e_s _t_h_a_t _a_r_r_o_w_s _s_h_o_u_l_d _b_e
                         _s_p_e_c_i_f_i_e_d _a_s _w_e_l_l, _s_i_n_c_e  _s_p_e_c_i_f_y_i_n_g  _p_e_r_c_e_n_-
                         _t_a_g_e_s _o_n_l_y _m_a_k_e_s _s_e_n_s_e _i_f _t_h_i_n_g_s _c_a_n _g_r_o_w _a_n_d
                         _s_h_r_i_n_k.

                         There are two types  of  arrows,  vertical  &
                         horizontal,  which  specify the directions in
                         which  a  given  child  should  be   resized.
                         Arrows  always  imply proportional reshaping,
                         as though  the  child  were  on  a  sheet  of
                         rubber; for example, if the parent doubles in
                         size, so will the child.  If arrows are omit-
                         ted,  the  child  is  not resized, but rather
                         moved to the center of  the  area  which  the
                         child would occupy if it were resized.

                         In the geom-spec, arrows are specified by the
                         keyword  :arrow  followed by an unquoted list
                         of arrow types, which can be either :horiz or
                         :vert.

                         Four types of anchors, left,  right,  top,  &
                         bottom, specify the side of the collection to
                         which the child should be anchored.   Anchors
                         imply  absolute  reshaping.   Associated with
                         each anchor is an integer which specifies the
                         gap (in pixels) between the given side of the
                         child and the given side of  the  collection.
                         For instance, a child can have its upper left
                         corner anchored at  coordinates  (20  35)  by
                         putting  a left anchor at 20 and a top anchor
                         35.  Anchor-gm  takes  into  account  border-
                         width  in  repacking  so  that  a window with
                         border-width 5 will be positioned 5 pixels in
                         from  its  specified  position  (x and y) and
                         will be 10 pixels shorter  and  thinner  than
                         specified,  overriding  base-width  and base-



          PICASSO Reference Manual                               7-113







                                                           COLLECTIONS


                         height if necessary.  Border-width is ignored
                         if  (:border  nil)  occurs  in the geom-spec.
                         Similarly, labels are ignored in repacking if
                         (:label nil) occurs in the geom-spec.

                         In the geom-spec, anchors  are  specified  by
                         the  keyword  :anchor  followed by a property
                         list of _s_i_d_e _o_f_f_s_e_t pairs, where _s_i_d_e is  one
                         of  the keywords :left, :_r_i_g_h_t, :top _o_r :_b_o_t_-
                         _t_o_m and _o_f_f_s_e_t is an integer  specifying  the
                         gap, in pixels.

                         _____________________________________________

          EXAMPLE


                         The following geom-spec  specifies  a  window
                         which sticks to the bottom, grows upward, but
                         remains  centered  horizontally  within   its
                         parent  and  always takes up 1/2 of the width
                         and 3/4 of the height of the parent:


                          (1/4 1/4 1/2 3/4 :anchor (:bottom 0) :arrow (:vert))



                         _____________________________________________

          EXAMPLE


                         The following  specifies  a  scrolling  text-
                         widget  of initial dimensions 100 x 100, with
                         a vertical scroll bar along the left edge and
                         a  horizontal  scroll  bar  along the bottom.
                         The first make-scroll-bar specifies the  left
                         vertical  scroll bar; the second make-scroll-
                         bar specifies the  bottom  horizontal  scroll
                         bar;   and  the  the  third  make-text-widget
                         specifies a text  widget  for  the  remaining
                         (majority) upper right region.
















          PICASSO Reference Manual                               7-114







                                                           COLLECTIONS



                          (make-collection-widget
                            :gm 'anchor-gm
                            :size '(100 100)
                            :parent (root-window)
                            :children '((make-scroll-bar
                                         :orientation :vertical
                                         :base-width 20
                                         :geom-spec '(:anchor
                                                       (:left 0
                                                        :top 0
                                                        :bottom 0)))
                                        (make-scroll-bar
                                         :orientation :horizontal
                                         :base-height 20
                                         :geom-spec '(:anchor
                                                       (:left 20
                                                        :bottom 0
                                                        :right 0))
                                         :height 20)
                                        (make-text-widget
                                         :region '(20 0 80 80)
                                         :geom-spec '(:anchor
                                                       (:left 20
                                                        :bottom 20
                                                        :right 0
                                                        :top 0)
                                                      :arrow (:vert :horiz)))))



          ____________________________________________________________________________________________________________________________________________________________________________________

          Packed-GM


                         Packed-gm is a geometry manager  that  allows
                         for  perpendicular packing of subwindows in a
                         style much like that of the SX toolkit.  Con-
                         sider a simple text editor, with a title-bar,
                         scroll-bar and window for editing.   You  can
                         use  packed-gm to specify, for instance, that
                         the title-bar should be along the top of  the
                         window,  span the window left to right and be
                         tall enough to display the text  in  whatever
                         font  it's  using, that the scroll-bar should
                         be on the left side  of  the  window  with  a
                         width  of 20 pixels, and that the text window
                         should fill in the remaining space.

                         To calculate the region occupied by  a  child
                         window  within  a  parent, packed-gm uses the
                         following algorithm:  Start  with  the  first
                         child  in  the list of children, and place it



          PICASSO Reference Manual                               7-115







                                                           COLLECTIONS


                         along the side of the collection specified in
                         the  geom-spec  of  that  child spanning that
                         side.  The region remaining unoccupied  is  a
                         (smaller)  rectangular  region.  Go on to the
                         next child and place it  within  this  region
                         along  the  side  specified by its geom-spec,
                         spanning that side in the  remaining  region,
                         leaving   yet   another  smaller  rectangular
                         region.  Go on with the rest of the  children
                         until  you  either a) run out of children, or
                         b) the leftover region is so  small  that  no
                         more  children  can  be placed within it.  In
                         the latter case, pend all the remaining chil-
                         dren since there is nowhere to put them; this
                         effectively makes them invisible.

                         The geom-spec  of  a  child  under  packed-gm
                         determines  the  side on which the child will
                         reside, and its size in the direction perpen-
                         dicular  to  that side.  It can be one of the
                         keywords  :left,  :right,  :top,  :bottom  or
                         :fill,  it  can  be  nil, or it can be a list
                         consisting of  one  of  the  keywords  :left,
                         :right,   :top  or  :bottom  followed  by  an
                         integer that specifies the size of the child,
                         in  pixels, in the direction perpendicular to
                         the specified side.  Examples  of  the  geom-
                         spec are:


                      ______________________________________________________
                                   Place the child on the left side
                                   of the parent, with the width determined

                       :left
                                   by the base-size of the child.
                      ______________________________________________________
                                   Place the child along the top of the
                       (:top 20)   parent, with a height of 20 pixels.
                      ______________________________________________________
                                   Place the child in the remaining
                       :fill       unoccupied region of the parent.
                      ______________________________________________________
                                   Treat as :top for tall windows,
                                   :left for wide windows.

                       nil
                                   (wide windows have width > 3*height)
                      ______________________________________________________

                     |
                     |
                     |
                     |
                     |
                     |
                     |
                     |
                     |
                     |
                     |
                     |
                     |
                     |












                                |
                                |
                                |
                                |
                                |
                                |
                                |
                                |
                                |
                                |
                                |
                                |
                                |
                                |












                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
















                         In addition, the geom-spec  of  a  child  can
                         contain the keyword/value pairs (:before _w_i_n_-
                         _d_o_w) and (:after _w_i_n_d_o_w), _w_h_i_c_h _s_p_e_c_i_f_y _w_h_e_r_e
                         _t_o  _p_l_a_c_e _t_h_i_s _c_h_i_l_d _i_n _t_h_e _l_i_s_t _o_f _c_h_i_l_d_r_e_n.



          PICASSO Reference Manual                               7-116







                                                           COLLECTIONS


                         _T_h_e _c_h_i_l_d _i_s _p_l_a_c_e_d _b_e_f_o_r_e (_o_r _a_f_t_e_r)  _w_i_n_d_o_w
                         _i_n  _t_h_e _l_i_s_t _o_f _c_h_i_l_d_r_e_n.  _I_f _w_i_n_d_o_w _i_s _o_m_i_t_-
                         _t_e_d, _t_h_e _w_i_n_d_o_w _i_s _p_l_a_c_e_d _a_t _t_h_e _b_e_g_i_n_n_i_n_g _o_r
                         _e_n_d   _o_r  _t_h_e  _l_i_s_t,  _a_s  _a_p_p_r_o_p_r_i_a_t_e.   _T_h_i_s
                         _f_e_a_t_u_r_e _i_s _p_a_r_t_i_c_u_l_a_r_l_y  _u_s_e_f_u_l  _w_h_e_n  _a_d_d_i_n_g
                         _c_h_i_l_d_r_e_n  _t_o  _a  _w_i_n_d_o_w  _a_f_t_e_r _t_h_e _w_i_n_d_o_w _h_a_s
                         _b_e_e_n _c_r_e_a_t_e_d.

                         Finally, the geom-spec of a child can contain
                         keyword/value  pairs  that specify padding on
                         the left, right, top or bottom sides  of  the
                         child.   This  padding  serves  as  a  visual
                         "gully" to separate two children.   The  key-
                         words recognized are:


               ____________________________________________________________________
                (:left-pad _s_i_z_e)     Pad the left side with _s_i_z_e pixels
                (:right-pad _s_i_z_e)    _P_a_d _t_h_e _r_i_g_h_t _s_i_d_e _w_i_t_h _s_i_z_e _p_i_x_e_l_s
                (:_t_o_p-_p_a_d _s_i_z_e)      _P_a_d _t_h_e _t_o_p _s_i_d_e _w_i_t_h _s_i_z_e _p_i_x_e_l_s
                (:_b_o_t_t_o_m-_p_a_d _s_i_z_e)   _P_a_d _t_h_e _b_o_t_t_o_m _s_i_d_e _w_i_t_h _s_i_z_e _p_i_x_e_l_s
                (:_h_o_r_i_z-_p_a_d _s_i_z_e)    _P_a_d _t_h_e _l_e_f_t _a_n_d _r_i_g_h_t _s_i_d_e_s _w_i_t_h _s_i_z_e _p_i_x_e_l_s
                (:_v_e_r_t-_p_a_d _s_i_z_e)     _P_a_d _t_h_e _t_o_p _a_n_d _b_o_t_t_o_m _s_i_d_e _w_i_t_h _s_i_z_e _p_i_x_e_l_s
                (:_p_a_d _s_i_z_e)          _P_a_d _a_l_l _s_i_d_e_s _w_i_t_h _s_i_z_e _p_i_x_e_l_s
               ____________________________________________________________________

              |
              |
              |
              |
              |
              |
              |
              |






                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |






                                                                                  |
                                                                                  |
                                                                                  |
                                                                                  |
                                                                                  |
                                                                                  |
                                                                                  |
                                                                                  |










                         _____________________________________________

          EXAMPLE


                         Another version  of  the  example  given  for
                         anchor-gm:  the  following specifies a scrol-
                         ling text-widget of initial dimensions 100  x
                         100,  with  a  vertical  scroll bar along the
                         left edge and a horizontal scroll  bar  along
                         the bottom.  The text-widget is surrounded by
                         a gully of 4 pixels.  The first  make-scroll-
                         bar  specifies  the left vertical scroll bar;
                         the second make-scroll-bar specifies the bot-
                         tom  horizontal scroll bar; and the the third
                         make-text-widget specifies a text widget  for
                         the remaining region.












          PICASSO Reference Manual                               7-117







                                                           COLLECTIONS



                          (make-collection-widget
                            :gm 'packed-gm
                            :size '(100 100)
                            :parent (root-window)
                            :children '((make-scroll-bar
                                         :orientation :vertical
                                         :geom-spec :left)
                                        (make-scroll-bar
                                         :orientation :horizontal
                                         :geom-spec :bottom)
                                        (make-text-widget
                                         :geom-spec '(:fill :pad 4))))


          ____________________________________________________________________________________________________________________________________________________________________________________

          Stacked-GM


                         Stacked-gm is a very simple geometry  manager
                         that places as many children as will fit left
                         to right across the  collection,  then  over-
                         flows  into  the  next  row.  This process is
                         continued until either there is no more space
                         for  another  row  or  all children have been
                         packed in.

                         The geom-specs of the children  are  ignored.
                         The  children are given a size equal to their
                         base size.  The gm-data  of  the  collection,
                         however, is used to determine the gap between
                         the children.  Gm-data is a list  of  (inter-
                         row-gap  inter-column-gap),  where inter-row-
                         gap  specifies  how  many  pixels  to   place
                         between  each  child  in  a  row,  and inter-
                         column-gap specifies how many pixels to place
                         between the rows of children,

                         _____________________________________________

          EXAMPLE


                         A stack of 5 buttons, with a gap of 4  pixels
                         between each:













          PICASSO Reference Manual                               7-118







                                                           COLLECTIONS



                          (make-collection-widget
                            :gm 'stacked-gm
                            :gm-data '(4 4)
                            :parent (root-window)
                            :children '((make-gray-button :value "Add")
                                        (make-gray-button :value "Delete")
                                        (make-gray-button :value "Cancel")
                                        (make-gray-button :value "Reset")
                                        (make-gray-button :value "Close")))


          ____________________________________________________________________________________________________________________________________________________________________________________

          Matrix-GM


                         Matrix-gm is  the  geometry-manager  used  by
                         table-fields,  matrix-fields, and list-boxes.
                         It manages  an  array-style  organization  of
                         windows.  The geom-specs of the children con-
                         tains a list  which  specifies  the  row  and
                         column  of  the child, and the gm-data of the
                         collection contains a structure  which  holds
                         data private to the matrix.

                         Most of the parameters of the  matrix-gm  are
                         set  at initialization, which is performed by
                         calling  the  gm-matrix-init  function   (see
                         below).   This  function  sets  the number of
                         rows and columns in the matrix,  the  maximum
                         number of rows and columns visible at any one
                         time, the row and column defining  the  upper
                         left corner, and the minimum and maximum size
                         a row/column  can  shrink  or  grow  to.   By
                         default,   the  maximum  number  of  rows  an
                         columns visible are the number  of  rows  and
                         columns  in the matrix, the upper left corner
                         is (0 0), and the minimum size  of  rows  and
                         columns are set such that each row will be at
                         least as tall as required by the tallest win-
                         dow  in  that  row and each column will be at
                         least as wide as needed to display the widest
                         window.

                     gm-matrix-init

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         &key
                         (_r_o_w_s (_r_o_w_s _s_e_l_f))
                         (_c_o_l_s (_c_o_l_s _s_e_l_f))
                         (_m_a_x-_v_i_s_i_b_l_e-_r_o_w_s _r_o_w_s)
                         (_m_a_x-_v_i_s_i_b_l_e-_c_o_l_s _c_o_l_s)
                         (_r_o_w-_m_i_n_s _n_i_l)
                         (col-mins nil)



          PICASSO Reference Manual                               7-119







                                                           COLLECTIONS


                         (_r_o_w-_m_a_x_s _n_i_l)
                         (col-maxs nil)
                         (_r_o_w-_i_n_d_e_x _0)
                         (col-index 0)
                         (_i_n_t_e_r-_r_o_w-_p_a_d _0)
                         (inter-col-pad 0)
                         (_c_o_n_f_o_r_m _n_i_l)
                         This function initializes the matrix-gm asso-
                         ciated  with  the  collection  _s_e_l_f. _R_o_w_s and
                         _c_o_l_s specifies the number of rows and columns
                         in  the  matrix.  _M_a_x-_v_i_s_i_b_l_e-_r_o_w_s  and  _m_a_x-
                         _v_i_s_i_b_l_e-_c_o_l_s specify the  maximum  number  of
                         rows  and  columns visible at one time.  _R_o_w-
                         _m_i_n_s, _c_o_l-_m_i_n_s,  _r_o_w-_m_a_x_s  and  _c_o_l-_m_a_x_s  are
                         sequences of length _r_o_w_s or _c_o_l_s that specify
                         the minimum and maximum size  for  a  row  or
                         column.   By  default these are set such that
                         each row will be at least as tall as required
                         by  the  tallest  window in that row and each
                         column will be at least as wide as needed  to
                         display  the  widest  window.   _R_o_w-_i_n_d_e_x and
                         _c_o_l-_i_n_d_e_x specify the element to be displayed
                         in  the  upper  left  corner  of  the matrix.
                         _I_n_t_e_r-_r_o_w-_p_a_d and _i_n_t_e_r-_c_o_l-_p_a_d  specify  the
                         number  of pixels to appear between two items
                         in  a  given  row  or  column,  respectively.
                         Finally,  if  _c_o_n_f_o_r_m  is t, _t_h_e _b_a_s_e-_s_i_z_e _o_f
                         _t_h_e _m_a_t_r_i_x _i_s _s_e_t _t_o _d_i_s_p_l_a_y _m_a_x-_v_i_s_i_b_l_e-_r_o_w_s
                         _a_n_d _m_a_x-_v_i_s_i_b_l_e-_c_o_l_s _o_f _w_i_n_d_o_w_s.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Null-GM
          and Root-
          GM




                         PICASSO  has  two  other  built-in  geometry-
                         managers,  which  are  used  internally.  The
                         functionality contained  in  these  geometry-
                         managers  is  occasionally  useful for widget
                         writers and writers of new geometry-managers.
                         This  section briefly documents the following
                         geometry-managers:

                         o+    root-gm,  the   geometry-manager   which
                              manages all children of the root-window.

                         o+    null-gm,  the   geometry-manager   which
                              defines    the   default   behavior   of
                              geometry-managers.

                         Root-gm is the geometry-manager used  by  the
                         root-window, the collection-widget that is at
                         the top of the x-window  instance  hierarchy.
                         Root-gm  sets  a  widget's  size based on the
                         following logic, ignoring  the  geom-spec  of



          PICASSO Reference Manual                               7-120







                                                           COLLECTIONS


                         the child: if the width-increment of the win-
                         dow is zero, implying that the window's width
                         cannot be changed, then the window's width is
                         set to its base-width; otherwise, the  width-
                         increment is non-zero, and the window's width
                         is chosen such that a)  it  fits  within  the
                         confines of the root-window, b) that it is no
                         smaller than the base-width and c)  that  the
                         window's   width   isn't  decreased  if  it's
                         currently greater than the  base-width.   The
                         last  rule prevents the root-gm from resizing
                         a window to its  base  size  after  the  user
                         enlarges the window.  A similar logic is used
                         to determine the window's height.

                         Null-gm defines the default behavior  of  all
                         geometry-managers. It honors all requests for
                         a widget's placement, and it sets a  widget's
                         size based on the same logic as root-gm;  see
                         the above description of root-gm for details.
                         The minimum size for a collection with a null
                         geometry-manager is the size  the  collection
                         must be in order for all of its subwindows to
                         be visible.

                         _____________________________________________

          GEOMETRY
          MANAGER
          SUMMARY




                         The following table summarizes the use of the
                         geom-spec  and  gm-data slots for the various
                         geometry   managers.    For   anchor-gm   and
                         packed-gm,  _p_o_s is one of the keywords :left,
                         :_r_i_g_h_t, :top _o_r :_b_o_t_t_o_m.  For  anchor-gm,  x,
                         _y, w _a_n_d _h are all in the range 0.0 .. 1.0.





















          PICASSO Reference Manual                               7-121







                                                           COLLECTIONS



          _________________________________________________________________________________________
           Geometry Manager   gm-data                geom-spec
          __________________________________________________________________________________________________________________________________________________________________________________
                                                     (%x %y %w %h :anchor ({_p_o_s _p_i_x_e_l_s}*)
                                                              :arrow (_d_i_r)

           anchor-gm          unused
                                                              where _d_i_r is :horiz or :vert or both
          _________________________________________________________________________________________
           packed-gm          unused                 _p_o_s|:fill|(_p_o_s _p_i_x_e_l_s)
          _________________________________________________________________________________________
           stacked-gm         (row-gap column-gap)   unused
          _________________________________________________________________________________________
           matrix-gm          used internally        (_r_o_w-_n_u_m _c_o_l_u_m_n-_n_u_m)
          _________________________________________________________________________________________
           null-gm            unused                 unused
          _________________________________________________________________________________________
           root-gm            unused                 unused
          _________________________________________________________________________________________

         |
         |
         |
         |
         |
         |
         |
         |
         |
         |
         |
         |
         |
         |
         |
         |














                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |














                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |














                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |
                                                                                                  |




















































          PICASSO Reference Manual                               7-122







                                                   WIDGETS AND GADGETS


                                               8
                                      WIDGETS AND GADGETS

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         Almost  all  input  and  output  behavior  of
                         PICASSO  is implemented through two interface
                         abstractions: gadgets and  widgets.   Gadgets
                         are  abstractions  for  output  behavior, and
                         widgets  are  abstractions  for  input/output
                         behavior.   The rest of this manual describes
                         the PICASSO toolkit  and  the  more  than  30
                         predefined widgets and gadgets implemented in
                         it.  All widgets and gadgets share some  com-
                         mon  behavior.  For instance, all widgets and
                         gadgets can have borders and  labels  defined
                         for them.  In addition, many of the slots and
                         methods are common to all widgets  and  gadg-
                         ets.  This chapter presents all of the common
                         behaviors of widgets and gadgets.

                         This chapter is organized as follows:

                         o+    Gadgets

                         o+    Widgets

                         o+    Synthetic Gadgets

                         o+    Borders

                         o+    Labels
          ____________________________________________________________________________________________________________________________________________________________________________________

          Gadgets


                         The gadgets class is a subclass  of  windows,
                         and  therefore  inherits keys and methods via
                         the window class.  Although  most  developers
                         are  unlikely  to  need  to  use  make-gadget
                         directly, the following function is available
                         to define gadgets.

                     make-gadget

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         ;; defaults overridden from superclasses
                         (_n_a_m_e "_A _G_a_d_g_e_t")
                         (status :exposed)
                         (_f_o_n_t *_d_e_f_a_u_l_t-_f_o_n_t-_n_a_m_e*)
                         (background nil)
                         (_d_i_m_m_e_d-_b_a_c_k_g_r_o_u_n_d _n_i_l)
                         (inverted-background nil)



          PICASSO Reference Manual                               8-123







                                                   WIDGETS AND GADGETS


                         ;; Plus keys inherited from windows
                         &allow-other-keys

                         Each of the attributes listed for make-gadget
                         is  described  in  Chapter  2  under windows.
                         Since gadgets are a subclass of windows,  the
                         additional  attributes,  methods  and  macros
                         given for windows also apply to gadgets.   In
                         addition,  the  following are also defined on
                         gadgets:

                     determine-class

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _g_a_d_g_e_t)
                         _v_a_l_u_e
                         Returns what class _g_a_d_g_e_t  is  a  member  of.
                         Possible  values  include  (null-gadget text-
                         gadget  bitmap-gadget   image-gadget   paint-
                         gadget  arrow-gadget).  _I_f  _g_a_d_g_e_t  _i_s  _n_o_t _a
                         _m_e_m_b_e_r _o_f _a_n_y _o_f _t_h_e_s_e _c_l_a_s_s_e_s, _a _w_a_r_n_i_n_g  _i_s
                         _i_s_s_u_e_d _a_n_d '_n_u_l_l-_g_a_d_g_e_t _i_s _r_e_t_u_r_n_e_d.

                     repaint-x

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _g_a_d_g_e_t)
                         Returns the x offset of the gadget  from  the
                         enclosing  window.  If the gadget itself is a
                         window, the x offset is 0.

                     repaint-y

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _g_a_d_g_e_t)
                         Returns the y offset of the gadget  from  the
                         enclosing  window.  If the gadget itself is a
                         window, the y offset is 0.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Widgets


                         The widgets class is defined as a subclass of
                         opaque  windows,  and therefore inherits keys
                         and methods  via  the  opaque  window  class.
                         Although   developers  are  unlikely  to  use
                         make-widget directly, the following  function
                         is provided to define widgets.

                     make-widget

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         ;; defaults overridden from superclasses
                         (_n_a_m_e "_A _W_i_d_g_e_t")
                         (status :exposed)
                         ;; Plus keys inherited from opaque windows
                         &allow-other-keys

                         As a  subclass  of  opaque  windows,  widgets
                         inherit  all of the methods defined on opaque



          PICASSO Reference Manual                               8-124







                                                   WIDGETS AND GADGETS


                         windows, described in Chapter 2.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Synthetic
          Gadgets




                         Creating  complex  widgets  and  gadgets  can
                         become  expensive,  and  some of this expense
                         can be avoided by  using  _s_y_n_t_h_e_t_i_c  _g_a_d_g_e_t_s.
                         Synthetic  gadgets,  sometimes called _s_y_n_t_h_s,
                         are very light-weight abstractions for output
                         purposes  only.   Unlike widgets and gadgets,
                         synthetic gadgets are not a defined class. As
                         a  result,  they are not quite as flexible as
                         gadgets,  but  are  considerably  faster  and
                         smaller.   Many  of  the  widgets/gadgets  in
                         PICASSO  that  were  originally   implemented
                         using  collections  have since been rewritten
                         using synths instead.  In complicated widgets
                         like tables or menus, using synths results in
                         a dramatic speed increase.

                         A synth is simply a LISP list consisting  the
                         arguments  to  a  put method, as described in
                         [Sei90]. Applying the put method to  a  synth
                         will  draw the synth on the screen. The synth
                         list format is:


                          (<_s_t_r_i_n_g>   { (_k_e_y _v_a_l_u_e) }* )


                         The following keys  are  standardly  used  in
                         creating synths:


                                   ____________________________
                                     Key         Default
                                   ________________________________________________________
                                    window       nil
                                    gc           (gc-res self)
                                    font         nil
                                    x            0
                                    y            0
                                    height       (height self)
                                    width        (width self)
                                    mask         nil
                                    dimmed       nil
                                    inverted     nil
                                    horiz-just   :center
                                    vert-just    :center
                                   ____________________________

                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |
                                  |













                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |













                                                              |
                                                              |
                                                              |
                                                              |
                                                              |
                                                              |
                                                              |
                                                              |
                                                              |
                                                              |
                                                              |
                                                              |
                                                              |
                                                              |
                                                              |


















          PICASSO Reference Manual                               8-125







                                                   WIDGETS AND GADGETS


                         Synthetic  gadget  keyword  values   can   be
                         queried  by  using  getf,  and  can be set by
                         using setf.  For example, if we have the syn-
                         thetic gadget my-synth specified as


                          ("hello" :window <_w_i_n> :gc <_m_y-_g_c>)


                         then


                          (getf (cdr my-synth) :window)


                         will return <_w_i_n>, and


                          (setf (getf (cdr my-synth) :window) <_m_y-_w_i_n_d_o_w>)


                         will set  the  window  of  my-synth  _t_o  <_m_y-
                         _w_i_n_d_o_w>, _a_n_d


                          (_a_p_p_l_y #'_p_u_t _m_y-_s_y_n_t_h)


                         _w_i_l_l _d_r_a_w _t_h_e _s_y_n_t_h _m_y-_s_y_n_t_h _o_n _t_h_e _s_c_r_e_e_n.

                         The following macro is also defined  on  syn-
                         thetic gadgets:

                     synth-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Return t _i_f _o_b_j_e_c_t _i_s _a _s_y_n_t_h_e_t_i_c-_g_a_d_g_e_t, _n_i_l
                         _o_t_h_e_r_w_i_s_e.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Borders


                         The border of a window can be set to  any  of
                         six  predefined PICASSO border types, and can
                         have  various  widths.   The  three  keys  of
                         interest  for specifying the border of a win-
                         dow  are  :border-type,  :border-width,   and
                         border-attributes.

                         Six types of predefined border types exist in
                         PICASSO.   These  border types are _b_o_x, _s_t_a_n_d
                         _o_u_t, _i_n_s_e_t, _d_r_o_p _s_h_a_d_o_w,  _f_r_a_m_e,,  and  _n_u_l_l.
                         The  desired  border type for a window can be
                         specified with the :border-type _k_e_y, _a_n_d  _t_h_e



          PICASSO Reference Manual                               8-126







                                                   WIDGETS AND GADGETS


                         _d_e_f_a_u_l_t _b_o_r_d_e_r _i_s _t_h_e _n_u_l_l _b_o_r_d_e_r.

                         A box border  is  simply  a  black  rectangle
                         around a window, and can be created by speci-
                         fying :border-type :box _w_h_e_n _c_r_e_a_t_i_n_g _a  _w_i_n_-
                         _d_o_w.  _T_h_e _d_e_f_a_u_l_t _b_o_r_d_e_r-_w_i_d_t_h _o_f _b_o_x _b_o_r_d_e_r_s
                         _i_s _1.

                         Stand out borders look like the  border  used
                         for gray buttons (see gray buttons in Chapter
                         11) in that the upper and left-most edges are
                         filled  with "white" _p_a_i_n_t, _a_n_d _t_h_e _l_o_w_e_r _a_n_d
                         _r_i_g_h_t-_m_o_s_t  _e_d_g_e_s  _a_r_e  _f_i_l_l_e_d  _w_i_t_h  "_b_l_a_c_k"
                         paint as the following diagram illustrates:


                             --------------------
                            |white             **|
                            |   -------------- **|
                            |  |              |**|
                            |  |              |**|
                            |  |              |**|
                            |  |              |**|
                            |   -------------- **|
                            |***************black|
                             --------------------


                         Standout borders are  created  by  specifying
                         :border-type  :standout  _w_h_e_n _c_r_e_a_t_i_n_g _a _w_i_n_-
                         _d_o_w, _a_n_d _t_h_e _d_e_f_a_u_l_t _b_o_r_d_e_r _w_i_d_t_h  _f_o_r  _s_t_a_n_-
                         _d_o_u_t _b_o_r_d_e_r_s _i_s _2.

                         Inset borders are inverted standout  borders,
                         i.e.,  the  upper  and  left-  most edges are
                         filled with "black _p_a_i_n_t, _a_n_d _t_h_e  _l_o_w_e_r  _a_n_d
                         _r_i_g_h_t-_m_o_s_t   _e_d_g_e_s  _a_r_e  _f_i_l_l_e_d  _w_i_t_h  "_b_l_a_c_k
                         paint. Inset borders are created by  specify-
                         ing  :border-type  :inset,  _a_n_d  _t_h_e  _d_e_f_a_u_l_t
                         _b_o_r_d_e_r _w_i_d_t_h _f_o_r _i_n_s_e_t _b_o_r_d_e_r_s _i_s _a_l_s_o _2.

                         A frame border is a combination of  an  inset
                         border drawn inside of a standout border, and
                         looks somewhat  like  a  picture  frame.   In
                         addition,  the  area  between  the  inset and
                         standout border can be filled with  a  desig-
                         nated  color  by using the :border-attributes
                         _k_e_y, _a_s _t_h_e _f_o_l_l_o_w_i_n_g _d_i_a_g_r_a_m _i_l_l_u_s_t_r_a_t_e_s:







          PICASSO Reference Manual                               8-127







                                                   WIDGETS AND GADGETS



                           -----------------------------------
                          |_w_h_i_t_e                             *|
                          |   ----------------------------- **|
                          |  |/////// _f_i_l_l ////////////////|**|
                          |  |// ----------------------- //|**|
                          |  |//|_b_l_a_c_k******************|//|**|
                          |  |//|** -----------------   |//|**|
                          |  |//|**|                 |  |//|**|
                          |  |//|**|                 |  |//|**|
                          |  |//|**|                 |  |//|**|
                          |  |//|**|                 |  |//|**|
                          |  |//|**|                 |  |//|**|
                          |  |//|**|                 |  |//|**|
                          |  |//|** -----------------   |//|**|
                          |  |//|*                 _w_h_i_t_e|//|**|
                          |  |// ----------------------- //|**|
                          |  |/////// _f_i_l_l ////////////////|**|
                          |   ----------------------------- **|
                          |******************************_b_l_a_c_k|
                           -----------------------------------


                         _F_r_a_m_e _b_o_r_d_e_r_s _h_a_v_e _a _d_e_f_a_u_l_t _b_o_r_d_e_r-_w_i_d_t_h  of
                         7,  and  can  be  created using the following
                         specification:


                          :border-type :frame
                          :border-width <_w_i_d_t_h>
                          :border-attribute '(:background <_p_a_i_n_t>)



                         Shadow borders have a drop-shadow filled with
                         the  paint  "gray25".   Shadow borders can be
                         created by specifying  :border-type  :shadow,
                         and  have  default border-width of '(0 0 7 7)
                         (where each list element corresponds to: left
                         top right bottom).

                         Null borders are  _n_o  border  (i.e.,  border-
                         width  _i_s  _0).   Null borders are the default
                         border type, and can be explicitly created by
                         specifying  a border-type of t, _o_r _a_n_y _b_o_r_d_e_r
                         _t_y_p_e _t_h_a_t _d_o_e_s_n'_t _e_x_i_s_t.









          PICASSO Reference Manual                               8-128







                                                   WIDGETS AND GADGETS


                         _____________________________________________

          MANAGING
          BORDERS



                         The following methods are defined on borders:

                     border-clear

                                                              [_M_e_t_h_o_d]
                         _b_o_r_d_e_r
                         _s_e_l_f
                         Clears the border of _s_e_l_f.

                     border-init

                                                              [_M_e_t_h_o_d]
                         _b_o_r_d_e_r
                         (_s_e_l_f)
                         Initializes the _b_o_r_d_e_r of _s_e_l_f, with  default
                         border width.

                     border-repaint

                                                              [_M_e_t_h_o_d]
                         _b_o_r_d_e_r
                         _s_e_l_f
                         Redraws the _b_o_r_d_e_r of _s_e_l_f.

                         _____________________________________________

          BORDER
          SUMMARY





                     ________________________________________________________
                                    default
                      border-type   border-width   comments
                     ________________________________________________________________________________________________________________
                      :box          1              black rectangle
                      :stand-out    2              look like gray buttons
                      :inset        2              inverted standout buttons
                      :frame        7              inset inside standout
                      :shadow       '(0 0 7 7)     drop filled shadow1
                      null          0              no border (default)
                     ________________________________________________________

                    |
                    |
                    |
                    |
                    |
                    |
                    |
                    |
                    |
                    |








                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |








                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |








                                                                            |
                                                                            |
                                                                            |
                                                                            |
                                                                            |
                                                                            |
                                                                            |
                                                                            |
                                                                            |
                                                                            |











          ____________________________________________________________________________________________________________________________________________________________________________________

          Labels


                         The label of a window can be set  to  any  of
                         four  predefined PICASSO label types, and can
                         have various widths.  Keys  of  interest  for
                         specifying  the label of a window are :label,
                         :label-font, :label-type, :label-x, :label-y,
                         and  label-attributes.  :label-attributes can
                         be used to specify various attributes of  the
                         label, such as the color of the label.





          PICASSO Reference Manual                               8-129







                                                   WIDGETS AND GADGETS


                         The four of predefined label types are  _l_e_f_t,
                         _b_o_t_t_o_m,  _f_r_a_m_e,  and _n_u_l_l.  The desired label
                         type for a window can be specified  with  the
                         :label-type _k_e_y, _a_n_d _t_h_e _d_e_f_a_u_l_t _l_a_b_e_l _i_s _t_h_e
                         _n_u_l_l _l_a_b_e_l.

                         Left  labels  are   created   by   specifying
                         :label-type :left, _a_n_d _g_o _j_u_s_t _a_b_o_v_e _t_h_e _w_i_n_-
                         _d_o_w.  _T_h_e _x _a_n_d _y  _o_f_f_s_e_t  _o_f  _a  _l_e_f_t  _l_a_b_e_l
                         (:_l_a_b_e_l-_x  and  label-y)  _a_r_e _r_e_l_a_t_i_v_e _t_o _t_h_e
                         _u_p_p_e_r _l_e_f_t _c_o_r_n_e_r _o_f _t_h_e _w_i_n_d_o_w.

                         Bottom  labels  are  created  by   specifying
                         :label-type  :bottom,  _a_n_d  _g_o _j_u_s_t _b_e_l_o_w _t_h_e
                         _w_i_n_d_o_w.  _T_h_e _x _a_n_d _y _o_f_f_s_e_t _o_f _a _b_o_t_t_o_m _l_a_b_e_l
                         (:_l_a_b_e_l-_x  and  label-y)  _a_r_e _r_e_l_a_t_i_v_e _t_o _t_h_e
                         _l_o_w_e_r _l_e_f_t _c_o_r_n_e_r _o_f _t_h_e _w_i_n_d_o_w.

                         Frame labels are designed  to  fit  inside  a
                         frame border.  They are created by specifying
                         :label-type :frame, _a_n_d _a_r_e _d_i_s_p_l_a_y_e_d _i_n  _t_h_e
                         _f_i_l_l _p_o_r_t_i_o_n _b_e_t_w_e_e_n _t_h_e _f_r_a_m_e_d _b_o_r_d_e_r _o_f _t_h_e
                         _w_i_n_d_o_w (_s_e_e  _t_h_e  _s_e_c_t_i_o_n  _o_n  _f_r_a_m_e  _b_o_r_d_e_r_s
                         _a_b_o_v_e).   _T_h_e _x _a_n_d _y _o_f_f_s_e_t _o_f _a _f_r_a_m_e _l_a_b_e_l
                         (:_l_a_b_e_l-_x _a_n_d _l_a_b_e_l-_y) _a_r_e  _r_e_l_a_t_i_v_e  _t_o  _t_h_e
                         _i_n_n_e_r _l_e_f_t _c_o_r_n_e_r _o_f _t_h_e _f_r_a_m_e _o_f _t_h_e _w_i_n_d_o_w,
                         _a_n_d _d_e_f_a_u_l_t _t_o _1_0 _a_n_d _0, _r_e_s_p_e_c_t_i_v_e_l_y.

                         Null labels are basically _n_o label,  and  are
                         the default.

                         For  example,  the  following   specification
                         creates  a  red  left  label,  in the default
                         "8x13" font:


                          :label-type :left
                          :label-font "8x13"
                          :label-attributes '(:paint "red")



                         _____________________________________________

          MANAGING
          LABELS



                         The  following  function  and   methods   are
                         defined on labels.

                     make-label

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         _x-_o_f_f_s_e_t
                         _y-_o_f_f_s_e_t



          PICASSO Reference Manual                               8-130







                                                   WIDGETS AND GADGETS


                         _l_a_b_e_l
                         &optional
                         (_f_o_n_t (_m_a_k_e-_f_o_n_t))
                         This function creates  a  label.   The  label
                         string is displayed at the specified _x-_o_f_f_s_e_t
                         and _y-_o_f_f_s_e_t in the specified _f_o_n_t.

                     label-clear

                                                              [_M_e_t_h_o_d]
                         _l_a_b_e_l
                         _s_e_l_f
                         Clears the _l_a_b_e_l of _s_e_l_f.

                     label-init

                                                              [_M_e_t_h_o_d]
                         _l_a_b_e_l
                         _s_e_l_f
                         Initializes the _l_a_b_e_l of _s_e_l_f.

                     label-repaint

                                                              [_M_e_t_h_o_d]
                         _l_a_b_e_l
                         _s_e_l_f
                         Redraws the _l_a_b_e_l of _s_e_l_f.

                         _____________________________________________

          LABEL SUM-
          MARY





                           ____________________________________________
                            label-type   comments
                           ________________________________________________________________________________________
                            :left        just above and left of window
                            :bottom      just below window
                            :frame       fit inside frame border
                            null         no label (default)
                           ____________________________________________

                          |
                          |
                          |
                          |
                          |
                          |
                          |





                                      |
                                      |
                                      |
                                      |
                                      |
                                      |
                                      |





                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |


























          PICASSO Reference Manual                               8-131







                                                                  TEXT


                                               9
                                             TEXT




          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         The many types of text  gadgets  and  widgets
                         provide  the  user  with a variety of options
                         for displaying,  entering  and  editing  text
                         data.  The  main  classes of text gadgets and
                         widgets are:

                         o+    text-gadget - used for displaying  small
                              amounts of text

                         o+    text-buffer-gadget - used for viewing  a
                              potentially large buffer of text

                         o+    text-widget - used for editing  a  text-
                              buffer-gadget

                         o+    scrolling-text-widget  -  a  text-widget
                              with a scroll-bar

                         o+    entry-widget - a one-line text-widget

                         o+    num-entry - a numeric entry-field

                         Also, instances of the _b_u_f_f_e_r class are  used
                         by  text-buffer-gadgets  to  store their text
                         information.   In  practice,   instances   of
                         buffer   and  text-buffer-gadget  are  almost
                         never used without a text-widget.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Text
          Gadget



                         A text-gadget  allows  the  user  to  display
                         uneditable  text  information.   The text can
                         have one or many lines, and is displayed  all
                         at  once.  Only one font is allowed per text-
                         gadget, but there are no restrictions on  the
                         type  of  font  chosen.  The text may be hor-
                         izontally and vertically justified,  repaints
                         may  be  masked  or non-masked, and the base-
                         size of a text-gadget can be  self-adjusting.
                         These attributes are explained in more detail






          PICASSO Reference Manual                               9-132







                                                                  TEXT


                         below.

                         _____________________________________________

          CREATION



                     make-text-gadget

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_v_a_l_u_e "")
                         (font  (make-font))
                         (_h_o_r_i_z-_j_u_s_t :_c_e_n_t_e_r)
                         (vert-just :center)
                         (_m_a_s_k _t)
                         (self-adjusting nil)
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES



                     dimmed

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_g_a_d_g_e_t)
                         Returns if _s_e_l_f is dimmed.  A setf _m_e_t_h_o_d  _i_s
                         _a_l_s_o _d_e_f_i_n_e_d.

                     font

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_g_a_d_g_e_t)
                         Returns the font of _s_e_l_f.   Each  text-gadget
                         has  only  one  font.   A setf _m_e_t_h_o_d _i_s _a_l_s_o
                         _d_e_f_i_n_e_d.

                     horiz-just

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_g_a_d_g_e_t)
                         Returns the horizontal justification of _s_e_l_f,
                         which  will  be  one  of  :left,  :_c_e_n_t_e_r  or
                         :right.  _A _s_e_t_f method is also defined.

                     mask

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_g_a_d_g_e_t)
                         Returns t  _o_r  _n_i_l,  indicating  if  _s_e_l_f  is
                         repainted  with a mask. If mask is t, _s_e_l_f _i_s
                         _r_e_p_a_i_n_t_e_d _d_i_r_e_c_t_l_y _o_n_t_o _i_t_s  _r_e_p_a_i_n_t  _r_e_g_i_o_n.
                         _I_f _m_a_s_k _i_s _n_i_l, _s_e_l_f _i_s _r_e_p_a_i_n_t_e_d _o_n _t_o_p _o_f _a
                         _r_e_c_t_a_n_g_u_l_a_r _a_r_e_a _o_f _t_h_e  _c_o_l_o_r  _i_n_d_i_c_a_t_e_d  _b_y
                         (_i_n_v_e_r_t_e_d-_f_o_r_e_g_r_o_u_n_d  _s_e_l_f). _T_h_e _d_e_f_a_u_l_t _m_a_s_k
                         _i_s _n_i_l _f_o_r _m_o_n_o_c_h_r_o_m_e  _d_i_s_p_l_a_y_s,  _a_n_d  _t  _f_o_r
                         _c_o_l_o_r   _d_i_s_p_l_a_y_s.   _A  _s_e_t_f  _m_e_t_h_o_d  _i_s  _a_l_s_o
                         _d_e_f_i_n_e_d.

                     self-adjusting

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_g_a_d_g_e_t)
                         Returns  t  _o_r  _n_i_l,   indicating   if   _s_e_l_f



          PICASSO Reference Manual                               9-133







                                                                  TEXT


                         automatically   readjusts  its  base-size  on
                         calls to (setf font) _o_r (_s_e_t_f _v_a_l_u_e).  A setf
                         _m_e_t_h_o_d _i_s _a_l_s_o _d_e_f_i_n_e_d.

                     (setf value)

                                                              [_W_r_i_t_e_r]
                         (_s_e_l_f _t_e_x_t-_g_a_d_g_e_t)
                         (_v_a_l_u_e _s_t_r_i_n_g)
                         Sets the text displayed  by  _s_e_l_f  to  _v_a_l_u_e.
                         Automatically   repaints  _s_e_l_f  in  order  to
                         update the text displayed.

                     (setf value)

                                                              [_W_r_i_t_e_r]
                         (_s_e_l_f _t_e_x_t-_g_a_d_g_e_t)
                         (_v_a_l_u_e _l_i_s_t)
                         Sets the text displayed  by  _s_e_l_f  to  _v_a_l_u_e,
                         which must be a list of strings.  Each string
                         in _v_a_l_u_e corresponds to a  line  of  text  in
                         _s_e_l_f.   Automatically  repaints _s_e_l_f in order
                         to update the text displayed.

                     value

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _t_e_x_t-_g_a_d_g_e_t)
                         Returns a list of strings, with  each  string
                         corresponding to a line of text in _s_e_l_f.

                     vert-just

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_g_a_d_g_e_t)
                         Returns the vertical justification  of  _s_e_l_f,
                         which  will  be one of :top, :_c_e_n_t_e_r or :bot-
                         tom.  _A _s_e_t_f method is also defined.

                         _____________________________________________

          TEXT
          GADGET
          SUMMARY






                                 _________________________________
                                  Reader Methods   Setf Methods
                                 __________________________________________________________________
                                  dimmed           dimmed
                                  font             font
                                  horiz-just       horiz-just
                                  mask             mask
                                  self-adjusting   self-adjusting
                                  value            value
                                  vert-just        vert-just
                                 _________________________________

                                |
                                |
                                |
                                |
                                |
                                |
                                |
                                |
                                |
                                |








                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |








                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |

















          PICASSO Reference Manual                               9-134







                                                                  TEXT


          ____________________________________________________________________________________________________________________________________________________________________________________

          Buffer


                         A _b_u_f_f_e_r stores text in an array of  strings.
                         The  maximum number of lines of text that can
                         be stored in a  buffer  is  system-dependent,
                         and  determined  by the constant array-total-
                         size-limit.  _T_h_e _m_a_i_n _r_o_l_e _o_f _b_u_f_f_e_r_s  _i_s  _t_o
                         _s_t_o_r_e _t_e_x_t _f_o_r _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t_s.

                         _____________________________________________

          ATTRIBUTES



                     columns

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _b_u_f_f_e_r)
                         _r_o_w
                         Returns the number of columns in row  _r_o_w  of
                         _s_e_l_f.  The default value of _r_o_w is 0.

                     new

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _b_u_f_f_e_r)
                         Clears all the contents of _s_e_l_f.  Instead  of
                         actually  erasing  the  old array of strings,
                         this method just creates a new array and lets
                         the old one be garbage-collected.

                     rows

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _b_u_f_f_e_r)
                         Returns the number of rows in _s_e_l_f.

                     (setf value)

                                                              [_W_r_i_t_e_r]
                         (_s_e_l_f _b_u_f_f_e_r)
                         _v_a_l
                         Sets the contents of  _b_u_f_f_e_r  to  _v_a_l,  which
                         must be an adjustable vector of strings.

                     value

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _b_u_f_f_e_r)
                         &key
                         (_r_o_w _0)
                         (column 0)
                         Returns a string with the contents of row _r_o_w
                         of _s_e_l_f, starting at column _c_o_l_u_m_n.  Rows and
                         columns are numbered starting with zero.   If
                         _r_o_w  and  _c_o_l_u_m_n  are not specified, then the









          PICASSO Reference Manual                               9-135







                                                                  TEXT


                         entire array of strings is returned.

                         _____________________________________________

          LINKING
          WITH
          SCROLL
          BARS





                         These methods are provided to facilitate  the
                         interaction of buffers with controllers, such
                         as scroll-bars.

                     data

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_f_f_e_r)
                         This slot may be used in any way.   There  is
                         also a corresponding setf _m_e_t_h_o_d.

                     rows-changed-function

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_f_f_e_r)
                         Returns the rows-changed-function, _w_h_i_c_h _i_s _a
                         _h_o_o_k  _f_o_r  _o_t_h_e_r  _w_i_d_g_e_t_s _a_n_d _g_a_d_g_e_t_s _t_o _k_n_o_w
                         _w_h_e_n  _t_h_e  _n_u_m_b_e_r  _o_f  _r_o_w_s  _i_n  _t_h_e   _b_u_f_f_e_r
                         _c_h_a_n_g_e_s.  _A _s_e_t_f method is also defined.  The
                         _f_u_n_c used must be either a function  or  nil.
                         _I_f _f_u_n_c _i_s _n_o_t _n_i_l, _t_h_e_n, _w_h_e_n_e_v_e_r _t_h_e _n_u_m_b_e_r
                         _o_f _r_o_w_s _i_n _s_e_l_f _c_h_a_n_g_e_s, _f_u_n_c _i_s _c_a_l_l_e_d _w_i_t_h


                          (_f_u_n_c_a_l_l _f_u_n_c (_d_a_t_a _s_e_l_f) _n_i_l)



                         _____________________________________________

          BUFFER
          SUMMARY





                          _______________________________________________
                           Reader Methods          Setf Methods
                          ______________________________________________________________________________________________
                           data                    data
                           columns
                           new
                           rows
                           rows-changed-function   rows-changed-function
                           value                   value
                          _______________________________________________

                         |
                         |
                         |
                         |
                         |
                         |
                         |
                         |
                         |







                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |







                                                                        |
                                                                        |
                                                                        |
                                                                        |
                                                                        |
                                                                        |
                                                                        |
                                                                        |
                                                                        |



















          PICASSO Reference Manual                               9-136







                                                                  TEXT


          ____________________________________________________________________________________________________________________________________________________________________________________

          Text
          Buffer
          Gadget




                         A text-buffer-gadget displays a variable sub-
                         set  of  the  text  stored  in its buffer (of
                         class  _b_u_f_f_e_r).   This  contrasts  with   the
                         text-gadget  class,  in which all the text is
                         displayed at once.   Only  fixed-width  fonts
                         are supported.

                         _____________________________________________

          ACCESSING
          THE TEXT




                     buffer

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Returns the buffer containing the  text  data
                         of _s_e_l_f.

                     value

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Returns an array of strings corresponding  to
                         the  lines  of  _s_e_l_f.   This  is  the same as
                         (value (buffer self)).

                         _____________________________________________

          MODIFYING
          THE TEXT




                     new

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Deletes all text in _s_e_l_f, and places the cur-
                         sor at the home position.

                     put

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         _s_t_r
                         &key
                         (_o_v_e_r_w_r_i_t_e _n_i_l)
                         (repaint t)
                         Insert  string  _s_t_r  into  _s_e_l_f  at  row  _a_n_d
                         _c_o_l_u_m_n.   Update row _a_n_d _c_o_l_u_m_n. If _o_v_e_r_w_r_i_t_e
                         is nil, _i_n_s_e_r_t _i_n _i_n_s_e_r_t _m_o_d_e.  _I_f  _o_v_e_r_w_r_i_t_e
                         _i_s  _t,  _i_n_s_e_r_t _i_n _o_v_e_r_w_r_i_t_e _m_o_d_e.  _I_f _r_e_p_a_i_n_t
                         _i_s _t, _r_e_p_a_i_n_t _n_e_w _t_e_x_t.

                     (setf value)

                                                              [_W_r_i_t_e_r]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         _v_a_l_u_e
                         Set the text data of _s_e_l_f to _v_a_l_u_e, which can
                         be  a  string, a vector of strings, a list of




          PICASSO Reference Manual                               9-137







                                                                  TEXT


                         strings or a number.

                         _____________________________________________

          THE TEXT
          WINDOW



                         Often a text-widget  is  not  big  enough  to
                         display  all  the text in it.  When this hap-
                         pens,  only  a  portion  of  the  text   gets
                         displayed.   The  following  methods indicate
                         and  determine  what  part  of  the  text  is
                         displayed.

                     columns

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Returns the number of visible columns of text
                         of  _s_e_l_f.   This is calculated from the font-
                         size and the height _o_f  _s_e_l_f.   _T_h_e_r_e  _i_s  _n_o
                         _c_o_r_r_e_s_p_o_n_d_i_n_g _s_e_t_f _m_e_t_h_o_d.

                     left-of-screen

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Returns the number of the leftmost column  of
                         text   displayed   in   the  text  window.  A
                         corresponding setf _m_e_t_h_o_d _i_s _a_l_s_o _d_e_f_i_n_e_d.

                     rows

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Returns the number of visible rows of text of
                         _s_e_l_f.   This is calculated from the font-size
                         and  the  width  _o_f  _s_e_l_f.    _T_h_e_r_e   _i_s   _n_o
                         _c_o_r_r_e_s_p_o_n_d_i_n_g _s_e_t_f _m_e_t_h_o_d.

                     top-of-screen

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Returns the number of the row  of  text  that
                         appears  on  the  top  of the text window.  A
                         corresponding setf _m_e_t_h_o_d _i_s _a_l_s_o _d_e_f_i_n_e_d.

                         _____________________________________________

          THE CURSOR



                     column

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Returns the current column of the  cursor  of
                         _s_e_l_f.   This  value  is offset from the first
                         column of text in the buffer of _s_e_l_f, not the
                         left-of-screen.   _A _c_o_r_r_e_s_p_o_n_d_i_n_g _s_e_t_f method
                         is also defined.

                     cursor-mode

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)



          PICASSO Reference Manual                               9-138







                                                                  TEXT


                         Returns   :overwrite,   :_i_n_s_e_r_t,   or    nil,
                         _c_o_r_r_e_s_p_o_n_d_i_n_g  _t_o  _t_h_e  _c_u_r_s_o_r  _b_e_i_n_g _a _s_o_l_i_d
                         _b_l_o_c_k, _a _v_e_r_t_i_c_a_l _b_a_r, _o_r _i_n_v_i_s_i_b_l_e.

                     row

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Returns the current  row  of  the  cursor  of
                         _s_e_l_f.   This  value  is offset from the first
                         row of text in the buffer of  _s_e_l_f,  not  the
                         top-of-screen.   _A  _c_o_r_r_e_s_p_o_n_d_i_n_g _s_e_t_f method
                         is also defined.

                         _____________________________________________

          MARKING
          TEXT



                         Marking means highlighting a portion of  text
                         for  a  special  purpose, such as deleting or
                         copying.  All text between the  cursor  posi-
                         tion and the mark position is marked.

                     copy-mark

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Copy marked text  into  cut-buffer  number  0
                         (cut-buffer  is  a  temporary  holding buffer
                         [ScL89], and is compatible with xterm).

                     delete-mark

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Zap marked text into non-existence.

                     mark

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         &key
                         (_m_a_r_k-_r_o_w  (_m_a_r_k-_r_o_w _s_e_l_f))
                         (mark-column  (mark-column self))
                         Mark all text between the cursor position and
                         _m_a_r_k-_r_o_w and _m_a_r_k-_c_o_l_u_m_n.

                     unmark

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Unmark any marked text, and set mark-row  _a_n_d
                         _m_a_r_k-_c_o_l_u_m_n of _s_e_l_f to nil.

                         _____________________________________________

          FILE I/O



                     append-to-file

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         _f_i_l_e_n_a_m_e
                         Append the contents of _s_e_l_f  to  the  end  of




          PICASSO Reference Manual                               9-139







                                                                  TEXT


                         _f_i_l_e_n_a_m_e.

                     load-file

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         _f_i_l_e_n_a_m_e
                         &key
                         (_c_o_u_n_t -_1)
                         Replace the contents of _s_e_l_f with  the  first
                         _c_o_u_n_t  lines  of  _f_i_l_e_n_a_m_e.   If _c_o_u_n_t is -1,
                         _t_h_e_n _u_s_e _a_l_l _o_f _t_h_e _l_i_n_e_s _o_f _f_i_l_e_n_a_m_e.

                     put-file

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         _f_i_l_e_n_a_m_e
                         &key
                         (_c_o_u_n_t -_1)
                         Insert file the first _c_o_u_n_t lines of _f_i_l_e_n_a_m_e
                         into _s_e_l_f at the current cursor position.  If
                         _c_o_u_n_t is -1, _t_h_e_n _i_n_s_e_r_t _a_l_l _o_f _t_h_e _l_i_n_e_s  _o_f
                         _f_i_l_e_n_a_m_e.

                     save-file

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         _f_i_l_e_n_a_m_e
                         Save the contents of _s_e_l_f into _f_i_l_e_n_a_m_e.

                         _____________________________________________

          SEARCHING
          TEXT




                     search-backward

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         _p_a_t_t_e_r_n
                         Search for first backward occurrence of  _p_a_t_-
                         _t_e_r_n.  If found, return t _a_n_d _p_o_s_i_t_i_o_n _c_u_r_s_o_r
                         _a_t _t_h_e _f_i_r_s_t _l_e_t_t_e_r _o_f  _t_h_e  _o_c_c_u_r_r_e_n_c_e.   _I_f
                         _t_h_e _p_a_t_t_e_r_n _c_a_n_n_o_t _b_e _m_a_t_c_h_e_d, _o_r _i_f _t_h_e _p_a_t_-
                         _t_e_r_n _i_s _t_h_e _e_m_p_t_y _s_t_r_i_n_g, _r_e_t_u_r_n _n_i_l.

                     search-forward

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         _p_a_t_t_e_r_n
                         Search for first forward occurrence  of  _p_a_t_-
                         _t_e_r_n.  If found, return t _a_n_d _p_o_s_i_t_i_o_n _c_u_r_s_o_r
                         _o_n_e _p_o_s_i_t_i_o_n _p_a_s_t  _t_h_e  _l_a_s_t  _l_e_t_t_e_r  _o_f  _t_h_e
                         _o_c_c_u_r_r_e_n_c_e.    _I_f   _t_h_e   _p_a_t_t_e_r_n  _c_a_n_n_o_t  _b_e
                         _m_a_t_c_h_e_d, _o_r  _i_f  _t_h_e  _p_a_t_t_e_r_n  _i_s  _t_h_e  _e_m_p_t_y








          PICASSO Reference Manual                               9-140







                                                                  TEXT


                         _s_t_r_i_n_g, _r_e_t_u_r_n _n_i_l.

                         _____________________________________________

          OTHER
          ATTRIBUTES




                     font

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Returns the current font of _s_e_l_f.  There is a
                         corresponding  setf  _m_e_t_h_o_d,  _b_u_t _o_n_l_y _f_i_x_e_d-
                         _w_i_d_t_h _f_o_n_t_s _a_r_e _s_u_p_p_o_r_t_e_d.

                     invert

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_b_u_f_f_e_r-_g_a_d_g_e_t)
                         Returns t _o_r _n_i_l, indicating if  _s_e_l_f  is  in
                         invert  mode (where background and foreground
                         are swapped.) A setf _m_e_t_h_o_d  _i_s  _d_e_f_i_n_e_d  _f_o_r
                         _t_h_i_s _a_t_t_r_i_b_u_t_e.

                         _____________________________________________

          TEXT
          BUFFER
          GADGET
          SUMMARY







                        ___________________________________________________
                         Reader Methods   Setf Methods     Misc
                        ______________________________________________________________________________________________________
                         buffer           buffer           append-to-file
                         column           column           copy-mark
                         columns                           cursor-mode
                         font             font             delete-mark
                         invert           invert           load-file
                         left-of-screen   left-of-screen   mark
                         row              row              new
                         rows                              put
                         top-of-screen    top-of-screen    put-file
                         value            value            save-file
                                                           search-backward
                                                           search-forward
                                                           unmark
                        ___________________________________________________

                       |
                       |
                       |
                       |
                       |
                       |
                       |
                       |
                       |
                       |
                       |
                       |
                       |
                       |
                       |
                       |














                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |














                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |














                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |
                                                                          |

















          ____________________________________________________________________________________________________________________________________________________________________________________

          Text
          Widget



                         A text-widget allows the  user  to  edit  the
                         contents  of a text-buffer-gadget.  Actually,
                         text-widget is a combined subclass  of  text-
                         buffer-gadget  and  widgets.   This  means in
                         effect that  text-widget  is  a  text-buffer-
                         gadget  with  an  X window and event handling



          PICASSO Reference Manual                               9-141







                                                                  TEXT


                         capabilities.

                         _____________________________________________

          CREATION


                         Since text-widget  is  a  subclass  of  text-
                         buffer-gadget,  it accepts all of the keyword
                         arguments of text-buffer-gadget.

                     make-text-widget

                                                            [_F_u_n_c_t_i_o_n]
                         (_e_d_i_t_a_b_l_e _n_i_l)
                         (insert-mode nil)
                         (_t_a_b-_s_t_e_p _8)
                         (scroll-right-at nil)
                         (_h_o_r_i_z_o_n_t_a_l-_s_c_r_o_l_l-_u_p _n_i_l)
                         (vertical-scroll-up nil)
                         ;; Plus keys inherited from text-buffer-gadget
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES



                     editable

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_w_i_d_g_e_t)
                         Returns t _o_r _n_i_l, indicating if the text con-
                         tents  of  _s_e_l_f  can  be modified through the
                         keyboard. A setf _m_e_t_h_o_d _i_s _a_l_s_o _d_e_f_i_n_e_d.

                     horizontal-scroll-step

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_w_i_d_g_e_t)
                         Returns the number of columns to scroll at  a
                         time  when  scrolling  to the right or to the
                         left.   If  nil,  _a  _w_h_o_l_e  _s_c_r_e_e_n  _w_i_d_t_h  _i_s
                         _s_c_r_o_l_l_e_d _a_t _a _t_i_m_e.  _A _s_e_t_f method is defined
                         for this attribute.

                     insert-mode

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_w_i_d_g_e_t)
                         Returns t _o_r _n_i_l, indicating whether _s_e_l_f  is
                         in  insert  or  overwrite mode, respectively.
                         In insert mode, when text is typed  into  the
                         text-widget,  the  characters to the right of
                         the cursor are pushed over and preserved.  In
                         overwrite mode, they are overwritten.  A setf
                         _m_e_t_h_o_d _i_s _a_l_s_o _d_e_f_i_n_e_d.

                     scroll-right-at

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_w_i_d_g_e_t)
                         Returns the number of columns to the right of
                         left-of-screen  _a_t  _w_h_i_c_h _s_e_l_f _w_i_l_l _a_u_t_o_m_a_t_i_-
                         _c_a_l_l_y _s_c_r_o_l_l _r_i_g_h_t _b_y _t_h_e _n_u_m_b_e_r  _o_f  _c_o_l_u_m_n_s



          PICASSO Reference Manual                               9-142







                                                                  TEXT


                         _s_p_e_c_i_f_i_e_d  _b_y _h_o_r_i_z_o_n_t_a_l-_s_c_r_o_l_l-_s_t_e_p.  _A _s_e_t_f
                         _m_e_t_h_o_d _i_s _d_e_f_i_n_e_d _f_o_r _t_h_i_s _a_t_t_r_i_b_u_t_e.

                     tab-step

                                                            [_A_c_c_e_s_s_o_r]
                         _R_e_t_u_r_n_s _t_h_e _n_u_m_b_e_r  _o_f  _c_o_l_u_m_n_s  _b_e_t_w_e_e_n  _t_a_b
                         _s_t_o_p_s.  _I_n  _t_e_x_t-_w_i_d_g_e_t_s,  _t_a_b_s  _a_r_e _a_c_t_u_a_l_l_y
                         _s_i_m_u_l_a_t_e_d _w_i_t_h _s_p_a_c_e_s.  _A _c_o_r_r_e_s_p_o_n_d_i_n_g  _s_e_t_f
                         _m_e_t_h_o_d _i_s _a_l_s_o _d_e_f_i_n_e_d.

                     vertical-scroll-step

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _t_e_x_t-_w_i_d_g_e_t)
                         Returns the number of rows  to  scroll  at  a
                         time  when  scrolling  up  or down. if nil, _a
                         _w_h_o_l_e _s_c_r_e_e_n _h_e_i_g_h_t _i_s _s_c_r_o_l_l_e_d _a_t _a _t_i_m_e.  _A
                         _s_e_t_f method is defined for this attribute.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Scrolling
          Text
          Widget




                         A scrolling-text-widget is a collection  con-
                         taining  a text-widget and a scroll-bar which
                         are linked together.

                         _____________________________________________

          CREATION


                         Scrolling text widget is a subclass  of  col-
                         lection   gadget,   so  scrolling-text-widget
                         accepts  all  of  the  keyword  arguments  of
                         collection-gadgets.

                     make-scrolling-text-widget

                                                            [_F_u_n_c_t_i_o_n]
                         (_s_c_r_o_l_l-_b_a_r _n_i_l)
                         (text-widget nil)
                         (_g_m '_p_a_c_k_e_d-_g_m)
                         (conform :grow-only)
                         ;; Plus keys inherited from collection-gadget
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES



                     scroll-bar

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l_i_n_g-_t_e_x_t-_w_i_d_g_e_t)
                         Returns the scroll-bar of self. There is also
                         a setf _m_e_t_h_o_d _d_e_f_i_n_e_d.

                     text-widget

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l_i_n_g-_t_e_x_t-_w_i_d_g_e_t)
                         Returns the text-widget of  self.   There  is





          PICASSO Reference Manual                               9-143







                                                                  TEXT


                         also a setf _m_e_t_h_o_d _d_e_f_i_n_e_d.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Entry
          Widget



                         An entry-widget  is  a  one-line  text-widget
                         with  a slot to store a function to be called
                         whenever the return key is pressed.

                         _____________________________________________

          CREATION


                         Entry widgets are a subclass of text widgets,
                         so  they  accept all of the keyword arguments
                         of text widgets.

                     make-entry-widget

                                                            [_F_u_n_c_t_i_o_n]
                         (_r_e_t_u_r_n-_f_u_n_c_t_i_o_n _n_i_l)
                         ;; Plus keys inherited from text-widget
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES



                     return-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _e_n_t_r_y-_w_i_d_g_e_t)
                         The (return) function to  be  executed  after
                         the user presses return.

                     setf return-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _e_n_t_r_y-_w_i_d_g_e_t)
                         _f_u_n_c
                         Sets the function to be  executed  after  the
                         user presses return to _f_u_n_c.  If _f_u_n_c is nil,
                         _n_o _f_u_n_c_t_i_o_n _i_s _e_x_e_c_u_t_e_d.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Num Entry


                         A num-entry  is  an  entry-widget  that  only
                         accepts  numeric  input  from the keyboard. A
                         scrollable option is available which  creates
                         a  num-entry  with two scrolling buttons that
                         increment and decrement the numeric value  of
                         the num-entry.

                         _____________________________________________

          CREATION


                         Num entries are a subclass of entry  widgets,
                         so  they  accept all of the keyword arguments





          PICASSO Reference Manual                               9-144







                                                                  TEXT


                         of entry widgets.

                     make-num-entry

                                                            [_F_u_n_c_t_i_o_n]
                         (_s_c_r_o_l_l_a_b_l_e _n_i_l)
                         ;; Plus keys inherited from entry-widget
                         &allow-other-keys
                         Returns a num-entry. If scrollable is t,  the
                         num-entry  is  associated  with  two  buttons
                         which increment or decrement the value of the
                         num-entry.













































          PICASSO Reference Manual                               9-145







                                                               BUTTONS


                                              10
                                            BUTTONS

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         Buttons are used to allow  the  user  a  con-
                         venient  way  to  specify an action.  Buttons
                         can contain any text  or  image  and  execute
                         code   either   when   pressed  or  released.
                         PICASSO provides  several  predefined  button
                         types:

                         o+    Button

                         o+    Gray Button

                         o+    Pop Button

                         o+    Gray Pop Button

                         o+    Click Button

                         o+    Button Groups

                         o+    Radio Buttons Groups

                         o+    Check Buttons Groups

                         o+    Implicit Buttons in Panels and Dialogs
          ____________________________________________________________________________________________________________________________________________________________________________________

          Buttons


                         The button class is a subclass of the  widget
                         class.   As  a  subclass  of  widget, buttons
                         inherit keys  and  methods  from  the  widget
                         class.  The following function can be used to
                         create buttons.

                     make-button

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_d_e_f_a_u_l_t _n_i_l)
                         (pause-seconds nil)
                         (_p_r_e_s_s-_f_u_n_c _n_i_l)
                         (release-func nil)
                         (_p_u_s_h_e_d _t)
                         (flag t)
                         (_d_a_t_a _n_i_l)
                         (mask color-display-p)
                         ;; defaults overridden from superclasses
                         (_n_a_m_e "_A _B_u_t_t_o_n")
                         (geom-spec :center)



          PICASSO Reference Manual                              10-146







                                                               BUTTONS


                         (_b_o_r_d_e_r-_w_i_d_t_h _1)
                         (event-mask '(:exposure :button-press
                                          :button-release :leave-window
                                          :enter-window))
                         (_b_a_s_e-_w_i_d_t_h _0)
                         (base-height 0)
                         (_f_o_n_t "-_b&_h*_b_o_l_d-_r*_1_4*")
                         ;; Defaults inherited from widgets:
                         (status :exposed)
                         ;; Plus keys inherited from opaque window, x-window and window
                         &allow-other-keys
                         This function creates a button at the  speci-
                         fied location.

                         _____________________________________________

          ATTRIBUTES



                     default

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n)
                         Indicates whether the button is  the  default
                         button.   The  LISP-form bound to the default
                         button is evaluated  if  the  user  enters  a
                         return  character  and there is no input com-
                         ponent in the interface object.  Default but-
                         tons  are  commonly  used  in  dialogs.  They
                         allow the user to  exit  the  dialog  without
                         having to move his or her hands from the key-
                         board.

                     pause-seconds

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n)
                         The time to leave the  button  pushed,  after
                         being  selected  and before calling the func-
                         tion (can be fractional).

                     press-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n)
                         A LISP-form that will be evaluated  when  the
                         user  selects  the  button.  The LISP-form is
                         evaluated in a lexical environment that binds
                         the  COMMON  LISP  symbol  _s_e_l_f to the button
                         object and the _e_v_e_n_t  to  the  X  event  that
                         triggered the call.

                     pushed

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n)
                         Indicates whether button is currently  pushed
                         or not.

                     release-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n)



          PICASSO Reference Manual                              10-147







                                                               BUTTONS


                         A LISP-form that will be evaluated  when  the
                         user  releases  the button.  The LISP-form is
                         evaluated in a lexical environment that binds
                         the  COMMON  LISP  symbol  _s_e_l_f to the button
                         object and the _e_v_e_n_t  to  the  X  event  that
                         triggered the call.

                     value

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n)
                         Specifies the label on the button, and should
                         be a string.

                     flag

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n)
                         If flag is t, _c_a_l_l _t_h_e  _p_r_e_s_s-_f_u_n_c  when  the
                         button is selected.

                     data

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n)

                     mask

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n)

                         _____________________________________________

          MANAGEMENT



                     button-p

                                                               [_M_a_c_r_o]
                         _s_e_l_f
                         Returns t _i_f _s_e_l_f _i_s _a _b_u_t_t_o_n, _n_i_l _o_t_h_e_r_w_i_s_e.

                     func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n)
                         The release function on the button.

                         _____________________________________________

          BUTTON
          SUMMARY




















          PICASSO Reference Manual                              10-148







                                                               BUTTONS



                            ___________________________________________
                             Reader Methods   Setf Methods    Misc
                            ______________________________________________________________________________________
                             data             data            button-p
                             default          default
                             flag             flag
                             func             func
                             mask             mask
                             pause-seconds    pause-seconds
                             press-func       press-func
                             pushed           pushed
                             release-func     release-func
                             value            value
                            ___________________________________________

                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |











                                           |
                                           |
                                           |
                                           |
                                           |
                                           |
                                           |
                                           |
                                           |
                                           |
                                           |
                                           |
                                           |











                                                           |
                                                           |
                                                           |
                                                           |
                                                           |
                                                           |
                                                           |
                                                           |
                                                           |
                                                           |
                                                           |
                                                           |
                                                           |











                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |














          ____________________________________________________________________________________________________________________________________________________________________________________

          Gray But-
          tons



                         Gray buttons are a  subclass  of  the  button
                         class  and thus inherits keys and methods via
                         buttons. The following function can  be  used
                         to create gray buttons.

                     make-gray-button

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_d_e_p_r_e_s_s _t)
                         (drawn-border-width 2)
                         (_i_n_v_e_r_t-_w_i_d_t_h _4)
                         (gray t)
                         (_o_l_d-_a_t_t_r_i_b_u_t_e_s _n_i_l)
                         ;; defaults overridden from superclasses
                         (name "A Gray Button")
                         (border-width 0)
                         ;; Plus keys inherited from button
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES



                     depress

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _g_r_a_y-_b_u_t_t_o_n)
                         When set, the gray-button  looks  "depressed"
                         when selected.

                     drawn-border-width

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _g_r_a_y-_b_u_t_t_o_n)
                         Gray buttons are drawn with a standout border
                         (see   Borders  in  Chapter  8),  and  drawn-
                         border-width  refers  to  the  width  of  the



          PICASSO Reference Manual                              10-149







                                                               BUTTONS


                         standout border.

                     gray

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n)
                         Returns whether or not the _b_u_t_t_o_n is  a  gray
                         button.   This value may be setf'_d; _s_e_t_t_i_n_g _a
                         _b_u_t_t_o_n _g_r_a_y _c_h_a_n_g_e_s _i_t_s _c_l_a_s_s _f_r_o_m _b_u_t_t_o_n  _t_o
                         _g_r_a_y-_b_u_t_t_o_n.   _S_e_t_t_i_n_g _a _g_r_a_y _b_u_t_t_o_n _t_o _g_r_a_y-
                         _n_i_l (_i._e.


                          (_s_e_t_f (_g_r_a_y <_g_r_a_y-_b_u_t_t_o_n>) _n_i_l)


                         _c_h_a_n_g_e_s _i_t_s _c_l_a_s_s _f_r_o_m _g_r_a_y-_b_u_t_t_o_n _t_o _b_u_t_t_o_n.

                     invert-width

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _g_r_a_y-_b_u_t_t_o_n)
                         Inverted gray buttons are drawn with a  frame
                         border   (see   Borders  in  Chapter  8)  and
                         inverted-width refers to  the  width  of  the
                         enclosed inset border.

                     old-attributes

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _g_r_a_y-_b_u_t_t_o_n)
                         Keeps track of prior backgrounds (:background
                         and  :border-width) before button was changed
                         from button class to gray button  class.   If
                         the  button  is  made ungray, the prior back-
                         grounds are restored.

                         _____________________________________________

          MANAGEMENT



                     gray-button-p

                                                               [_M_a_c_r_o]
                         _s_e_l_f
                         Returns t _i_f _s_e_l_f _i_s _a _g_r_a_y _b_u_t_t_o_n, _n_i_l  _o_t_h_-
                         _e_r_w_i_s_e.

                     inverted

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _g_r_a_y-_b_u_t_t_o_n)
                         Whether  or  not  _g_r_a_y-_b_u_t_t_o_n  is   currently
                         inverted.

                     make-gray

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _b_u_t_t_o_n)
                         &key
                         (_b_o_r_d_e_r-_w_i_d_t_h _2)
                         (background "gray75")
                         (_i_n_v_e_r_t-_w_i_d_t_h (_i_n_v_e_r_t-_w_i_d_t_h _s_e_l_f))
                         Make a button a gray button (creates  a  gray



          PICASSO Reference Manual                              10-150







                                                               BUTTONS


                         border).

                     make-ungray

                                                              [_M_e_t_h_o_d]
                         (_o_l_d _g_r_a_y-_b_u_t_t_o_n)
                         _s_e_l_f
                         Make a gray button a regular button (gets rid
                         of a gray border).
          ____________________________________________________________________________________________________________________________________________________________________________________

          Pop But-
          tons



                         A pop-button is a button  except  that,  when
                         selected,  pops  up  a  menu pane which has a
                         user-specified  behavior.   By  default,  the
                         selection  of a menu-item just sets the value
                         of the button to the selected value.

                         Pop buttons are a subclass of  buttons,  thus
                         they inherit keys and methods from the button
                         class.  The following function can be used to
                         create pop buttons.

                     make-pop-button

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_m_e_n_u _n_i_l)
                         (items nil)
                         (_i_t_e_m_s-_f_o_n_t _n_i_l)
                         ;; defaults overridden from superclasses
                         (event-mask '(:exposure :button-press
                                          :button-release))
                         ;; Plus keys inherited from button
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES



                     items

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_o_p-_b_u_t_t_o_n)
                         Pop buttons take a list of menu entries,  for
                         example


                          :items '("red" "blue" ...)


                         and a font along with all  the  other  button
                         arguments.   Optionally,  the :items _m_a_y _b_e _a
                         _l_i_s_t _o_f _l_i_s_t_s _w_h_e_r_e _e_a_c_h _l_i_s_t _h_a_s  _a_n  _o_b_j_e_c_t
                         _a_n_d  _a_n  _e_x_p_r_e_s_s_i_o_n _t_o _e_v_a_l (the code for the
                         menu-entry).  For example:





          PICASSO Reference Manual                              10-151







                                                               BUTTONS



                          :items '(("hello" '(print "This is Great"))
                                   ("good-bye" `(print ',val))
                                   "welcome"
                                   ("cancel" nil))


                         Alternately, the :menu _k_e_y  _c_a_n  _b_e  _u_s_e_d  _t_o
                         _s_p_e_c_i_f_y _m_e_n_u _p_a_n_e _e_n_t_r_i_e_s.

                     items-font

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_o_p-_b_u_t_t_o_n)
                         The font of the menu entry items.

                     menu

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_o_p-_b_u_t_t_o_n)
                         The :menu _k_e_y _c_a_n _b_e  _u_s_e_d  _t_o  _s_p_e_c_i_f_y  _m_e_n_u
                         _p_a_n_e  _e_n_t_r_i_e_s.  _T_h_e _d_i_f_f_e_r_e_n_c_e _b_e_t_w_e_e_n :_i_t_e_m_s
                         and :menu _i_s _t_h_a_t :_m_e_n_u takes  an  object  of
                         type _m_e_n_u-_p_a_n_e.

                         _____________________________________________

          ~MANAGE-
          MENT"




                     pop-button-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Returns t _i_f _o_b_j_e_c_t _i_s _a _p_o_p _b_u_t_t_o_n, _n_i_l _o_t_h_-
                         _e_r_w_i_s_e.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Gray Pop
          Buttons



                         A gray-pop-button is a gray button that, when
                         selected,  pops  up  a menu which has a user-
                         specified behavior.  By default,  the  selec-
                         tion  of  a  menu item just sets the value of
                         the button to the selected value.  the  menu-
                         items  just  set  the  value of the button to
                         their value.

                         Gray pop buttons are a subclass of gray  but-
                         tons,  thus they inherit keys and methods via
                         gray buttons. The following function  can  be
                         used to create gray pop pop buttons.

                     make-gray-pop-button

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_m_e_n_u _n_i_l)
                         (items-font nil)
                         (_e_v_e_n_t-_m_a_s_k '(:_e_x_p_o_s_u_r_e :_b_u_t_t_o_n-_p_r_e_s_s
                                          :_b_u_t_t_o_n-_r_e_l_e_a_s_e))
                         ;; Plus keys inherited from gray-buttons



          PICASSO Reference Manual                              10-152







                                                               BUTTONS


                         &allow-other-keys
                         Gray  button  attributes  and   methods   are
                         described  under pop buttons and gray buttons
                         (see above).  The following macro can be used
                         to  determine whether an object is a gray pop
                         button.

                     gray-pop-button-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Returns t _i_f _o_b_j_e_c_t _i_s _a _g_r_a_y _p_o_p _b_u_t_t_o_n, _n_i_l
                         _o_t_h_e_r_w_i_s_e.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Click But-
          tons



                         A click button is a button that has one func-
                         tion for each mouse button (left, middle, and
                         right).

                         Click buttons are a subclass of buttons, thus
                         they  inherit  keywords  and  methods via the
                         button class.

                     make-click-button

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_n_a_m_e "_A _C_l_i_c_k _B_u_t_t_o_n")
                         (left-func nil)
                         (_m_i_d_d_l_e-_f_u_n_c _n_i_l)
                         (right-func nil)
                         ;; Plus keys inherited from buttons
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES



                     left-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _c_l_i_c_k-_b_u_t_t_o_n)
                         The function to be  executed  when  the  user
                         presses the left mouse button.

                     middle-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _c_l_i_c_k-_b_u_t_t_o_n)
                         The function to be  executed  when  the  user
                         presses the middle mouse button.

                     right-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _c_l_i_c_k-_b_u_t_t_o_n)
                         The function to be  executed  when  the  user







          PICASSO Reference Manual                              10-153







                                                               BUTTONS


                         presses the right mouse button.

                         _____________________________________________

          MANAGEMENT



                     click-button-p

                                                               [_M_a_c_r_o]
                         _s_e_l_f
                         Returns t _i_f _s_e_l_f _i_s _a _c_l_i_c_k _b_u_t_t_o_n, _n_i_l _o_t_h_-
                         _e_r_w_i_s_e.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Button
          Groups



                         A button group is a group of indicator  "but-
                         tons",  where  each  indicator  has  a  label
                         image, and clicking the indicator toggles the
                         label image.  Button groups are a subclass of
                         widgets, thus they inherit keys  and  methods
                         from widgets.

                     make-button-group

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_a_c_t_i_v_e-_i_m_a_g_e _n_i_l)
                         (inactive-image nil)
                         (_i_t_e_m_s '(""))
                         (orientation :vertical)
                         ;; defaults overridden from superclasses
                         (_n_a_m_e "_A _B_u_t_t_o_n _G_r_o_u_p")
                         (event-mask '(:exposure :button-press))
                         (_f_o_n_t "_8_x_1_3")
                         ;; Defaults inherited from widgets:
                         (status :exposed)
                         ;; Plus keys inherited from opaque windows
                         &allow-other-keys
                         For example, the  following  code  creates  a
                         button-group  with 3 items, oriented horizon-
                         tally, with the  label  displayed  below  the
                         button images.


                          (make-button-group
                             :items '("Equipment" "Utilities" "Lots")
                             :orientation :horizontal
                             :label-just :bottom)











          PICASSO Reference Manual                              10-154







                                                               BUTTONS


                         _____________________________________________

          ATTRIBUTES



                     active-image

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n-_g_r_o_u_p)
                         The image to display when a button  indicator
                         is toggled on.

                     inactive-image

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n-_g_r_o_u_p)
                         The image to display when a button  indicator
                         is toggled off.

                     items

                                                              [_W_r_i_t_e_r]
                         A list of specs, one per button, that can  be
                         passed  to  make-button-group,  _b_u_t _c_a_n_n_o_t _b_e
                         _s_e_t_f'd or read after  creation.   A  spec  is
                         either  a label or a property list, for exam-
                         ple

                     orientation

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_u_t_t_o_n-_g_r_o_u_p)
                         The orientation  of  the  group  of  buttons,
                         either  :vertical  _o_r  :_h_o_r_i_z_o_n_t_a_l.  Vertical
                         groups display their images to  the  left  of
                         each  label,  and  horizontal  groups display
                         their images above each label.

                         _____________________________________________

          MANAGEMENT



                     dim-item

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _b_u_t_t_o_n-_g_r_o_u_p)
                         _i_t_e_m
                         Dim item _i_t_e_m of _b_u_t_t_o_n-_g_r_o_u_p.

                     update-value

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _b_u_t_t_o_n-_g_r_o_u_p)
                         Force an update of the value of  the  button-
                         group.

                     vertical

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _b_u_t_t_o_n_g_r_o_u_p)
                         Returns true if _s_e_l_f's orientation is :verti-









          PICASSO Reference Manual                              10-155







                                                               BUTTONS


                         cal.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Radio But-
          ton Groups



                         Radio buttons display a small box that  looks
                         like a (pressed or depressed) radio dial, and
                         buttoning them toggles their state.

                         Radio-groups are a subclass of button-groups,
                         thus  they  inherit  keys  and  methods  from
                         button-groups.

                     make-radio-group

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_n_a_m_e "_A _R_a_d_i_o-_B_u_t_t_o_n _G_r_o_u_p")
                         (value 0)
                         (_a_c_t_i_v_e-_i_m_a_g_e (_m_a_k_e-_i_m_a_g_e
                           :_n_a_m_e "_r_a_d_i_o-_s_e_l_e_c_t"
                           :_f_i_l_e "_r_a_d_i_o-_s_e_l_e_c_t_e_d._b_i_t_m_a_p")
                         (inactive-image (make-image
                            :name "radio-deselect"
                            :file "radio-normal.bitmap")
                         ;; Plus keys inherited from button-groups
                         &allow-other-keys

                         _____________________________________________

          SINGLE
          RADIO BUT-
          TONS




                         Single radio buttons are a special case,  and
                         are  a  subclass  of  widgets. As a subclass,
                         they inherit keys and methods from widgets.

                     make-radio-button

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_s_e_l_e_c_t-_i_m_a_g_e _n_i_l)
                         (deselect-image nil)
                         ;; defaults overridden from superclasses
                         (_v_a_l_u_e _n_i_l)
                         (border-width 0)
                         (_b_a_s_e-_w_i_d_t_h _2_5)
                         (base-height 20)
                         (_e_v_e_n_t-_m_a_s_k `(:_e_x_p_o_s_u_r_e :_b_u_t_t_o_n-_p_r_e_s_s))
                         ;; Plus keys inherited from widgets
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES



                     deselect-image

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _r_a_d_i_o-_b_u_t_t_o_n)
                         The image to display when the radio button is



          PICASSO Reference Manual                              10-156







                                                               BUTTONS


                         toggled off.

                     select-image

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _r_a_d_i_o-_b_u_t_t_o_n)
                         The image to display when the radio button is
                         toggled on.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Check But-
          ton Groups



                         Check buttons display a  small  box  that  is
                         either  checked or not, and buttoning on them
                         toggles their state.

                         Check  button  groups  are  a   subclass   of
                         button-groups,  thus  they  inherit  keys and
                         methods via button-groups.

                     make-check-group

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_a_c_t_i_v_e-_i_m_a_g_e (_m_a_k_e-_i_m_a_g_e
                            :_n_a_m_e "_c_h_e_c_k-_s_e_l_e_c_t"
                            :_f_i_l_e "_c_h_e_c_k-_t_r_u_e._b_i_t_m_a_p"))
                         (inactive-image (make-image
                             :name "check-deselect"
                             :file "check-false.bitmap"))
                         ;; defaults overridden from superclasses
                         (_n_a_m_e "_C_h_e_c_k-_B_o_x _G_r_o_u_p")
                         ;; Plus keys inherited from button-group"
                         &allow-other-keys

                         _____________________________________________

          SINGLE
          CHECK BUT-
          TONS




                         Single check buttons are a special case,  and
                         are  a  subclass  of  widgets. As a subclass,
                         they inherit keys and methods from widgets.

                     make-check-button

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_s_e_l_e_c_t-_i_m_a_g_e _n_i_l)
                         (deselect-image nil)
                         ;; defaults overridden from superclasses
                         (_v_a_l_u_e _n_i_l)
                         (border-width 0)
                         (_b_a_s_e-_w_i_d_t_h _2_5)
                         (base-height 20)
                         (_e_v_e_n_t-_m_a_s_k '(:_e_x_p_o_s_u_r_e :_b_u_t_t_o_n-_p_r_e_s_s))
                         ;; Plus keys inherited from widgets
                         &allow-other-keys
                         The check buttons  attributes  deselect-image
                         and select-image are the same as those listed




          PICASSO Reference Manual                              10-157







                                                               BUTTONS


                         under radio buttons.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Implicit
          Buttons



                         Implicit buttons can be  defined  in  dialogs
                         and  panels  by  using  the  optional  button
                         clause.  The button of the dialog or panel is
                         defined  by a _b_u_t_t_o_n-_s_p_e_c, which is a list of
                         button specifications.  Each button  specifi-
                         cation  has a name, an optional documentation
                         string, an optional documentation string, and
                         optional  list  of  control arguments (any of
                         those you would pass to make-button),  and  a
                         function  to  be  executed when the button is
                         selected.

                         Optional control arguments  (discussed  under
                         buttons) can be specified to control the look
                         and behavior of  implicit  buttons.   If  the
                         button  is declared inactive, the name of the
                         button is dimmed to provide feedback  to  the
                         user  that  the button is inactive; moreover,
                         the button will  not  respond  when  selected
                         with the mouse.

                         _____________________________________________

          IMPLICIT


                         The following specification might be used for
                         a save-cancel-ok dialog that prompts users as
                         to whether they want to quit a  tool  without
                         saving  their  files.   This  dialog contains
                         three buttons, "Save",  "Cancel",  and  "Ok".
                         Clicking  on  "Save" returns t to the caller;
                         clicking  "Cancel"  returns  :cancelled,  and
                         clicking "OK" returns nil.


                          (defdialog ("picasso" "save-cancel-ok" . "dialog")
                            "example of implicit button specification"
                            (buttons ("Save"
                                      (ret-dialog) t)
                                     ("Cancel"
                                      (ret-dialog :cancelled))
                                     ("OK"
                                      (ret-dialog nil)))
                            .
                            .
                            .
                          )





          PICASSO Reference Manual                              10-158







                                                               BUTTONS


                                              11
                                           CONTROLS

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         Controls  are  interface  abstractions   that
                         allow a user to modify her view of an object.
                         Scroll-bars are a good example of a  control.
                         Controls  are  typically  used in conjunction
                         with other widgets rather than as stand-alone
                         widgets,  and use the PICASSO binding mechan-
                         ism to communicate with the widgets they con-
                         trol.

                         The types of controls implemented in  PICASSO
                         are:

                         o+    Scroll-bars

                         o+    Sliders

                         o+    Rover-widgets  -  allow  two-dimensional
                              scrolling
          ____________________________________________________________________________________________________________________________________________________________________________________

          Scroll
          Bars



                         PICASSO applications use scroll-bars to allow
                         the user to adjust her view of another object
                         that is too big to fit on the screen.  A good
                         example of such an application is a text edi-
                         tor, where the document's  length  is  unlim-
                         ited.   In this application, vertical scroll-
                         bars are placed alongside the editor to allow
                         the user to easily change the editor position
                         within the document.   The  widget  that  the
                         scroll-bar   is  controlling  is  called  the
                         _c_l_i_e_n_t of the scroll-bar.

                         A scroll-bar is a  widget  conceptually  con-
                         taining  two buttons and a slider.  It may be
                         either horizontal or vertical.   The  buttons
                         may  be placed at either the top or bottom of
                         the scroll-bar (left or right for  horizontal
                         scroll-bars).   The  slider  has an indicator
                         that typically reflects  the  current  offset
                         within the viewed object, and what portion of
                         the object they are viewing.  For efficiency,
                         scroll-bars  are implemented as a single win-
                         dow rather than a collection.





          PICASSO Reference Manual                              10-159







                                                              CONTROLS


                         It is typically desirable for the clients  of
                         a  scroll-bar to use a coordinate system con-
                         venient for them in positioning  the  scroll-
                         bar.   For  example,  for a text widget it is
                         desirable that the coordinate of the  top  of
                         the  scroll-bar  be  "1", and the position at
                         the bottom of the scroll-bar be the number of
                         lines in the text editor.

                         Using the normal PICASSO binding mechanism to
                         propagate  updates from the scroll-bar to the
                         client (e.g., a text-widget)  would  lead  to
                         unacceptably  poor performance in the dynamic
                         drag mode. Therefore, a  hand-tuned  propaga-
                         tion mechanism is used to achieve higher per-
                         formance   synchronization   with    clients.
                         Scroll-bars  communicate  with  their clients
                         (eg, a text-editor widget)  by  executing  s-
                         expressions  held in slots of the scroll-bar.
                         See the description of the  execute  function
                         for  details  of  this mechanism.  Typically,
                         the expression causes the  client  to  adjust
                         its data structures and then update the posi-
                         tion of the indicator in the scroll-bar.

                         The interaction of a scroll-bar  is  as  fol-
                         lows.   Buttoning within the prev-line button
                         causes the s-expression  held  in  the  _p_r_e_v-
                         _l_i_n_e-_f_u_n_c  slot  of the scroll-bar to be exe-
                         cuted.  By pressing and holding  the  button,
                         this  s-expression  is executed repetitively.
                         Since this can  cause  some  applications  to
                         scroll  too  fast,  repetitive executions are
                         delayed by  an  amount  held  in  the  _p_a_u_s_e-
                         _s_e_c_o_n_d_s  slot  of  the scroll-bar.  Buttoning
                         within the next-line button acts in a similar
                         fashion.

                         Buttoning in the area above the slider  indi-
                         cator  causes  the  s-expression  held in the
                         _p_r_e_v-_p_a_g_e-_f_u_n_c slot of the scroll-bar  to  be
                         executed;  similarly,  buttoning  in the area
                         below the indicator causes  the  s-expression
                         held   in  the  _n_e_x_t-_p_a_g_e-_f_u_n_c  slot  of  the
                         scroll-bar to be executed.  Finally,  if  the
                         user  buttons  within the area of the indica-
                         tor, the s-expression held in the  _m_o_v_e_d-_f_u_n_c
                         slot  of the scroll-bar is executed.  This is
                         typically used for dynamic drag.

                         The programming of the dynamic drag  function
                         is   a   bit   tricky,   and   deserves  some



          PICASSO Reference Manual                              11-160







                                                              CONTROLS


                         discussion.  When the _m_o_v_e_d-_f_u_n_c is executed,
                         it usually sets up any internal structures in
                         the client needed  for  fast  scrolling,  and
                         calls  the  _d_r_a_g-_s_c_r_o_l_l-_b_a_r function, passing
                         it the scroll-bar instance (_s_b),  a  function
                         (_f_u_n_c),  and  the arguments of the event that
                         triggered  this  sequence.   When  the  mouse
                         moves,  _f_u_n_c  is  called with two parameters:
                         the scroll-bar instance (_s_b) and the value of
                         the  _d_a_t_a slot in that instance.  At the time
                         of  the  call,  the  slider-location  of  the
                         scroll-bar instance contains the new position
                         of the slider.

                         A picture of a typical  scroll-bar  is  shown
                         below:




















                         _____________________________________________

          CREATING A
          SCROLL BAR







                     make-scroll-bar

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_b_u_t_t_o_n_s  :_b_o_t_t_o_m-_r_i_g_h_t)
                         (data  nil)
                         (_l_o_w_e_r-_l_i_m_i_t  _0._0)
                         (moved-func  see below)
                         (next-line-func  see below)
                         (next-page-func  see below)
                         (orientation  :vertical)



          PICASSO Reference Manual                              11-161







                                                              CONTROLS


                         (prev-line-func  see below)
                         (prev-page-func  see below)
                         (slider-location  0.0)
                         (slider-size  25.0)
                         (upper-limit  100.0)
                         &allow-other-keys

                         Creates and returns  a  scroll-bar.   _B_u_t_t_o_n_s
                         specifies  the position of the buttons and is
                         one of (:left :right  :top  :bottom  :bottom-
                         right   :bottom-left  :top-right  :top-left).
                         _T_h_i_s _a_r_g_u_m_e_n_t _h_a_s _t_h_e  _f_o_l_l_o_w_i_n_g  _i_n_t_e_r_p_r_e_t_a_-
                         _t_i_o_n _i_n _v_e_r_t_i_c_a_l _a_n_d _h_o_r_i_z_o_n_t_a_l _s_c_r_o_l_l-_b_a_r_s:


                              _______________________________________
                               Argument        Vertical   Horizontal
                              ______________________________________________________________________________
                               :_l_e_f_t           bottom     left
                               :right          _b_o_t_t_o_m     _r_i_g_h_t
                               :_t_o_p            top        left
                               :bottom         _t_o_p        _r_i_g_h_t
                               :_b_o_t_t_o_m-_r_i_g_h_t   bottom     right
                               :bottom-left    _b_o_t_t_o_m     _l_e_f_t
                               :_t_o_p-_r_i_g_h_t      top        right
                               :top-left       _t_o_p        _l_e_f_t
                              _______________________________________

                             |
                             |
                             |
                             |
                             |
                             |
                             |
                             |
                             |
                             |
                             |









                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |









                                                       |
                                                       |
                                                       |
                                                       |
                                                       |
                                                       |
                                                       |
                                                       |
                                                       |
                                                       |
                                                       |









                                                                    |
                                                                    |
                                                                    |
                                                                    |
                                                                    |
                                                                    |
                                                                    |
                                                                    |
                                                                    |
                                                                    |
                                                                    |













                         _D_a_t_a is stored in the scroll-bar's data slot,
                         and  is  typically  filled  in  by scroll-bar
                         clients to hold their  own  data  structures.
                         _L_o_w_e_r-_l_i_m_i_t and _u_p_p_e_r-_l_i_m_i_t gives the coordi-
                         nates of the top and bottom (left and  right)
                         of    the   the   scroll-bar,   respectively.
                         _S_l_i_d_e_r-_l_o_c_a_t_i_o_n specifies the position of the
                         indicator,   and  _s_l_i_d_e_r-_s_i_z_e  specifies  the
                         length of the indicator, relative  to  _l_o_w_e_r-
                         _l_i_m_i_t  and _u_p_p_e_r-_l_i_m_i_t.  Finally, _m_o_v_e_d-_f_u_n_c,
                         _n_e_x_t-_l_i_n_e-_f_u_n_c,  _n_e_x_t-_p_a_g_e-_f_u_n_c,   _p_r_e_v-_l_i_n_e-
                         _f_u_n_c  and  _p_r_e_v-_p_a_g_e-_f_u_n_c  are  s-expressions
                         which are executed (using the  execute  _f_u_n_c_-
                         _t_i_o_n) _a_n_d _d_e_f_a_u_l_t _t_o _e_x_p_r_e_s_s_i_o_n_s _w_h_i_c_h _a_d_j_u_s_t
                         _t_h_e _p_o_s_i_t_i_o_n _o_f _t_h_e _i_n_d_i_c_a_t_o_r.

                         _____________________________________________

          SCROLL BAR
          ATTRIBUTES



                         Scroll-bars are implemented in a very  flexi-
                         ble  way  in PICASSO, which allows the client
                         to  communicate  with   the   scroll-bar   in



          PICASSO Reference Manual                              11-162







                                                              CONTROLS


                         coordinates  convenient  for the client.  The
                         scroll-bar does almost no error  checking  on
                         these   coordinates.    It  is  the  client's
                         responsibility to ensure that all values  are
                         in  range;  otherwise  strange effects on the
                         screen may occur.

                     button-pos

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         Returns the position of  the  buttons  within
                         the  scroll-bar _s_e_l_f.  This value will be one
                         of :bottom-right, :bottom-left, :top-right _o_r
                         :_t_o_p-_l_e_f_t.   _T_h_e  _s_e_t_f _b_u_t_t_o_n_s _s_h_o_u_l_d _b_e _u_s_e_d
                         _t_o _c_h_a_n_g_e _t_h_i_s _v_a_l_u_e.

                     (setf buttons)

                                                              [_W_r_i_t_e_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)
                         _v_a_l_u_e

                         This function sets the position of  the  but-
                         tons   within  the  scroll-bar  _s_e_l_f.   _V_a_l_u_e
                         should be one of the keywords :left,  :right,
                         :top,  :bottom,  :bottom-right, :bottom-left,
                         :top-right _o_r  :_t_o_p-_l_e_f_t.  If :left,  :right,
                         :top  _o_r  :_b_o_t_t_o_m  are given, they are mapped
                         into :bottom-right, :bottom-left,  :top-right
                         _o_r   :_t_o_p-_l_e_f_t and stored into the button-pos
                         slot of the scroll-bar as shown:


                                    __________________________
                                     Argument   Stored value
                                    ____________________________________________________
                                     :top       :top-left
                                     :left      :top-left
                                     :right     :bottom-right
                                     :bottom    :bottom-right
                                    __________________________

                                   |
                                   |
                                   |
                                   |
                                   |
                                   |
                                   |





                                             |
                                             |
                                             |
                                             |
                                             |
                                             |
                                             |





                                                             |
                                                             |
                                                             |
                                                             |
                                                             |
                                                             |
                                                             |









                         The scroll-bar is repainted as a side-effect.
                         The value stored is returned.

                     lower-limit

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         This function returns the lower-limit of  the
                         scroll-bar,   i.e.,   the  client  coordinate
                         corresponding to  the  top  or  left  of  the




          PICASSO Reference Manual                              11-163







                                                              CONTROLS


                         scroll-bar.  This value may be setf'd.

                     orientation

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         This function returns the orientation of  the
                         scroll-bar,  either :horizontal or :vertical.
                         This value may be setf'd.

                     slider-location

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         This function returns  the  position  of  the
                         indicator  in client coordinates.  This value
                         may be setf'd.

                     slider-size

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         This function returns the length of the indi-
                         cator  in client coordinates.  This value may
                         be setf'd.

                     upper-limit

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         This function returns the upper-limit of  the
                         scroll-bar,   i.e.,   the  client  coordinate
                         corresponding to the bottom or right  of  the
                         scroll-bar.  This value may be setf'd.

                         _____________________________________________

          SCROLL BAR
          SYNCHRONI-
          ZATION





                     data

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         This slot is used by  scroll-bar  clients  to
                         store  client  information.  Typical applica-
                         tions will store  a  pointer  to  the  client
                         instance  in this slot, but the actual stored
                         value is completely up to the client.

                     moved-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         This slot holds a form that is executed  when
                         a  mouse button is pressed within the slider.
                         The form will be eval'd in a lexical environ-
                         ment  where  _s_e_l_f evaluates to the scroll-bar
                         instance.  Typical applications will use  the



          PICASSO Reference Manual                              11-164







                                                              CONTROLS


                         drag-scroll-bar function to aid in implement-
                         ing dynamic drag.   See  the  description  of
                         dynamic scrolling earlier in this section for
                         details.  The default value for this slot is:


                          (drag-scroll-bar self nil event)



                     next-line-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         This slot holds a form that is executed  when
                         a  mouse  button  is  pressed  in the down or
                         right button in a scroll-bar.  The form  will
                         be eval'd in a lexical environment where _s_e_l_f
                         evaluates to the scroll-bar instance.  If the
                         button  is  held  down, the form will be exe-
                         cuted  repetitively  until  the   button   is
                         released.  See the text near the beginning of
                         this section for details.  The default  value
                         for this slot is the following form:


                          (if (<= (+ (slider-location self) 1 (slider-size self))
                                  (upper-limit self))
                            (incf (slider-location self)))



                     next-page-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         This slot holds a form that is executed  when
                         a  mouse  button is pressed in the area below
                         or  to  the  right  of  the  indicator  in  a
                         scroll-bar.   The  form  will  be eval'd in a
                         lexical environment where _s_e_l_f  evaluates  to
                         the  scroll-bar  instance.  See the text near
                         the beginning of this  section  for  details.
                         The  default  value for this slot is the fol-
                         lowing form:


                          (if (<= (+ (slider-location self) (slider-size self)
                                     (slider-size self))
                                  (upper-limit self))
                            (incf (slider-location self) (slider-size self))
                            (setf (slider-location self) (- (upper-limit self)
                                                            (slider-size self))))




          PICASSO Reference Manual                              11-165







                                                              CONTROLS


                     pause-seconds

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         When users  press  and  hold  the  prev-line-
                         button and next-line-buttons in a scroll-bar,
                         the forms associated with those  actions  are
                         executed  repetitively.  In very high perfor-
                         mance applications, this can lead to a scrol-
                         ling  rate  that  is  too  fast.   The  value
                         returned by this function sets the delay,  in
                         seconds, between successive executions of the
                         form.  This value  may  be  setf'd.   A  good
                         value  seems  to  be about 0.1 for high-speed
                         applications.

                     prev-line-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         This slot holds a form that is executed  when
                         a  mouse  button is pressed in the up or left
                         button in a scroll-bar.   The  form  will  be
                         eval'd  in  a  lexical environment where _s_e_l_f
                         evaluates to the scroll-bar instance.  If the
                         button  is  held  down, the form will be exe-
                         cuted  repetitively  until  the   button   is
                         released.  See the text near the beginning of
                         this section for details.  The default  value
                         for this slot is the following form:


                          (if (>= (1- (slider-location self)) (lower-limit self))
                              (decf (slider-location self)))



                     prev-page-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         This slot holds a form that is executed  when
                         a  mouse  button is pressed in the area above
                         or to the left of the indicator in a  scroll-
                         bar.   The  form  will be eval'd in a lexical
                         environment  where  _s_e_l_f  evaluates  to   the
                         scroll-bar  instance.   See the text near the
                         beginning of this section for  details.   The
                         default  value for this slot is the following
                         form:








          PICASSO Reference Manual                              11-166







                                                              CONTROLS



                          (if (>= (- (slider-location self) (slider-size self))
                                  (lower-limit self))
                            (decf (slider-location self) (slider-size self))
                            (setf (slider-location self) (lower-limit self)))



                         _____________________________________________

          SCROLL BAR
          MISC




                     drag-scroll-bar

                                                            [_F_u_n_c_t_i_o_n]
                         (_s_c_r_o_l_l-_b_a_r _f_u_n_c _a_r_g_s)

                         This function is typically called by the code
                         stored  in the moved-func slot of the scroll-
                         bar for use with dynamic drag.  _S_c_r_o_l_l-_b_a_r is
                         a  scroll-bar instance, _f_u_n_c is a function to
                         be called  whenever  the  scroll-bar  changes
                         position,  and _a_r_g_s are the args of the event
                         that triggered the function.  When the  mouse
                         moves,  the  display of _s_c_r_o_l_l-_b_a_r is updated
                         and _f_u_n_c is called with two  parameters:  the
                         _s_c_r_o_l_l-_b_a_r  and  the value stored in the data
                         slot of _s_c_r_o_l_l-_b_a_r.  At the time of the call,
                         the  slider-location  of  _s_c_r_o_l_l-_b_a_r contains
                         the new position of the slider.   This  func-
                         tion returns nil.

                     vertical-p

                                                               [_M_a_c_r_o]
                         (_s_c_r_o_l_l-_b_a_r)

                         This macro returns t if  the  orientation  of
                         _s_c_r_o_l_l-_b_a_r is :vertical, _o_t_h_e_r_w_i_s_e _i_t _r_e_t_u_r_n_s




















          PICASSO Reference Manual                              11-167







                                                              CONTROLS


                         _n_i_l.

                         _____________________________________________

          SCROLL BAR
          SUMMARY







                       _____________________________________________________
                        Reader Methods    Setf Methods      Misc Methods
                       __________________________________________________________________________________________________________
                        button-pos        buttons           drag-scroll-bar
                        data              data              vertical-p
                        lower-limit       lower-limit
                        moved-func        moved-func
                        next-line-func    next-line-func
                        next-page-func    next-page-func
                        orientation       orientation
                        pause-seconds     pause-seconds
                        prev-line-func    prev-line-func
                        prev-page-func    prev-page-func
                        slider-location   slider-location
                        slider-size       slider-size
                        upper-limit       upper-limit
                       _____________________________________________________

                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |
                      |














                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |














                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |
                                                         |














                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |
                                                                           |












































          PICASSO Reference Manual                              11-168







                                                                IMAGES


                                              12
                                            IMAGES

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         Images are color or black-and-white rectangu-
                         lar  representations  of  pictures.   PICASSO
                         Displays  images  through  the  image-gadget.
                         Chapter   3   describes  image  resources  in
                         detail.

                         PICASSO displays images using  the  following
                         widgets:

                         o+    Image Gadget
          ____________________________________________________________________________________________________________________________________________________________________________________

          Image
          Gadget



                         An image gadget allows the  user  to  display
                         bitmap  images.  Image gadgets are a subclass
                         of gadgets, and thus inherit gadgets keys and
                         methods.  The  following function can be used
                         to create and return an image gadget:

                     make-image-gadget

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_s_r_c-_x _0)
                         (src-y 0)
                         (_s_r_c-_w_i_d_t_h _n_i_l)
                         (src-height nil)
                         (_b_i_t_m_a_p-_p _n_i_l)
                         (horiz-just :center)
                         (_v_e_r_t-_j_u_s_t :_c_e_n_t_e_r)
                         ;; defaults overridden from superclasses
                         (name "A Gadget")
                         (status :exposed)
                         ;; Plus keys inherited from windows
                         &allow-other-keys
                         Image gadgets inherit several other  keys  of
                         interest from the windows class, all of which
                         are described in Chapter 2 on Windows.   Some
                         of  the  more  notable keys include _v_a_l_u_e, _x-
                         _o_f_f_s_e_t, _y-_o_f_f_s_e_t, _w_i_d_t_h,  _h_e_i_g_h_t,  and  _g_e_o_m-
                         _s_p_e_c.   The  image  displayed  by  the image-
                         gadget can specified by the  _v_a_l_u_e  key.   _x-
                         _o_f_f_s_e_t  and  _y-_o_f_f_s_e_t  specify  the  x  and y
                         offsets, respectively,  of  the  image-gadget
                         from  the  upper  left  corner of its parent.
                         _w_i_d_t_h and _h_e_i_g_h_t specify the width and height
                         of  the image gadget.  _g_e_o_m-_s_p_e_c is discussed




          PICASSO Reference Manual                              12-169







                                                                IMAGES


                         in more detail in the Collections chapter.

                         _____________________________________________

          ATTRIBUTES



                     src-x

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _i_m_a_g_e-_g_a_d_g_e_t)
                         Specifies the x coordinate of the  origin  of
                         the  image.  Of type integer, _d_e_f_a_u_l_t _0 (left
                         edge of image).

                     src-y

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _i_m_a_g_e-_g_a_d_g_e_t)
                         Specifies the y coordinate of the  origin  of
                         the image.  Of type integer, _d_e_f_a_u_l_t _0 (upper
                         edge of image).  and _s_r_c-_y is used to specify
                         the origin of the image,

                     src-width

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _i_m_a_g_e-_g_a_d_g_e_t)
                         The width of the image in  pixels.   Of  type
                         integer,  _d_e_f_a_u_l_t  _n_i_l.   If  src-height  _a_n_d
                         _s_r_c-_w_i_d_t_h are not set, then the entire  image
                         below and to the right of the origin is used;
                         otherwise the portion  _s_r_c-_h_e_i_g_h_t  below  and
                         _s_r_c-_w_i_d_t_h across the image is used.

                     src-height

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _i_m_a_g_e-_g_a_d_g_e_t)
                         The height of the image in pixels.   Of  type
                         integer,  _d_e_f_a_u_l_t  _n_i_l.   If  src-height  _a_n_d
                         _s_r_c-_w_i_d_t_h are not set, then the entire  image
                         below and to the right of the origin is used;
                         otherwise the portion  _s_r_c-_h_e_i_g_h_t  below  and
                         _s_r_c-_w_i_d_t_h across the image is used.

                     bitmap-p

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _i_m_a_g_e-_g_a_d_g_e_t)
                         Specifies if the image is a bitmap (vs.  pix-
                         map) image, default nil.

                     horiz-just

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _i_m_a_g_e-_g_a_d_g_e_t)
                         The horizontal justification  of  the  image,
                         and  is one of :center, :_l_e_f_t, or :right.  _O_f
                         _t_y_p_e _k_e_y_w_o_r_d, default :center.

                     vert-just

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _i_m_a_g_e-_g_a_d_g_e_t)
                         The vertical justification of the image,  and
                         is one of :center, :_t_o_p, or :bottom.  _O_f _t_y_p_e



          PICASSO Reference Manual                              12-170







                                                                IMAGES


                         _k_e_y_w_o_r_d, default :center.

                     value

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _i_m_a_g_e-_g_a_d_g_e_t)
                         Sets the image displayed by  _s_e_l_f  to  _v_a_l_u_e.
                         Automatically   repaints  _s_e_l_f  in  order  to
                         update the image displayed.

                         _____________________________________________

          EXAMPLE


                         The following specifies the  display  of  the
                         upper-right  quarter  of  a  100 pixel-square
                         image next  to  the  lower-right  quarter  of
                         another 100 pixel-square image.


                       (children
                         '((picture
                             (make-collection-gadget
                               :size '(100 100)
                               :gm 'rubber-gm
                               :children
                                '((shown-on-the-left
                                    ; upper-right quarter of image
                                    (make-image-gadget
                                      :value (make-image :file "image.bitmap")
                                      :src-x 50
                                      :src-height 50
                                      :geom-spec '(.05 0 .40 .75 :center)))
                                  (shown-on-the-right
                                    ; lower-right quarter of image
                                    (make-image-gadget
                                      :value (make-image :file "image.bitmap")
                                      :src-x 50
                                      :src-y 50
                                      :geom-spec '(.55 0 .4 .75 :center))))))))


                         In this example, the image displayed is taken
                         from  the  file image.bitmap.  The portion of
                         the image displayed on the left  is  centered
                         at  an x-offset of 5 pixels and a y-offset of
                         0 pixels from the upper left  corner  of  its
                         100  pixel-wide  parent,  and occupies 40% of
                         the width  and  75%  of  the  height  of  the
                         parent.   The  portion of the image displayed
                         on the right is centered at an x-offset of 55
                         pixels  and  a  y-offset of 0 pixels from the
                         upper left corner of its parent, and occupies
                         40% of the width and 75% of the height of the




          PICASSO Reference Manual                              12-171







                                                                IMAGES


                         parent.

                         _____________________________________________

          IMAGE
          GADGET
          SUMMARY






                                  _______________________________
                                   Reader Methods   Setf Methods
                                  ______________________________________________________________
                                   bitmap-p
                                   src-x            src-x
                                   src-y            src-y
                                   src-width        src-width
                                   src-height       src-height
                                   horiz-just       horiz-just
                                   vert-just        vert-just
                                   x-offset         x-offset
                                   y-offset         y-offset
                                   width            width
                                   height           height
                                   geom-spec        geom-spec
                                   value            value
                                  _______________________________

                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |














                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |














                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |














































          PICASSO Reference Manual                              12-172







                                                                 MENUS


                                              13
                                             MENUS

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         PICASSO supports pull-down and  pop-up  menus
                         as well as tear-off menu panes.  This chapter
                         describes the use of the PICASSO menu system.

                         The chapter is organized as follows:

                         o+    Menu bars

                         o+    Menu entries

                         o+    Menu panes

                         o+    Menu buttons

                         o+    Menu interaction techniques:  pull-down,
                              pop-up, and tear-off menus.

                         o+    Implicit menus: defining menus in frame,
                              panels, and pop-buttons
          ____________________________________________________________________________________________________________________________________________________________________________________

          Menu Bars


                         Menu bars are a subclass of collection  gadg-
                         ets,  thus they inherit keys and methods from
                         collection gadgets.  The  following  function
                         can be used to create and return a menu bar.

                     make-menu-bar

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         ;; defaults overridden from superclasses
                         (_b_a_s_e-_h_e_i_g_h_t _4_0)
                         (geom-spec :top)
                         (_g_m '_j_u_s_t-_p_a_c_k-_g_m)
                         ;; Defaults inherited from collection-gadgets:
                         (name "A Collection")
                         (value "Collection")
                         (children nil)
                         (repack-flag nil)
                         (repack-needed nil)
                         (conform :grow-shrink)
                         ;; Plus keys inherited from gadgets
                         &allow-other-keys
                         Menu bars inherit their attributes from  col-
                         lection  gadgets  (see  Chapter  7 on Collec-
                         tions). No new  attributes  are  defined  for
                         menu bars.



          PICASSO Reference Manual                              13-173







                                                                 MENUS


                         The following macro can be used to  determine
                         if an object is a menu-bar object.

                     menu-bar-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Returns true if _o_b_j_e_c_t is a menu-bar  object,
                         nil _o_t_h_e_r_w_i_s_e.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Menu
          Entries



                         Menu entries  are  implemented  as  synthetic
                         gadgets.  The following can be used to create
                         a and return a menu entry:

                     make-menu-entry

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_l_e_f_t _n_i_l)
                         (center nil)
                         (_r_i_g_h_t _n_i_l)
                         (left-font nil)
                         (_c_e_n_t_e_r-_f_o_n_t _n_i_l)
                         (right-font nil)
                         (_f_o_n_t (_g_e_t-_f_o_n_t))
                         (code nil)
                         (_d_i_m_m_e_d _n_i_l)
                         (status nil)
                         (_l_e_f_t-_s_t_a_t_u_s _n_i_l)
                         (center-status nil)
                         (_r_i_g_h_t-_s_t_a_t_u_s _n_i_l)
                         (parent nil)
                         &allow-other-keys
                         A menu entry has a left,  center,  and  right
                         component.   The  entry  name is displayed in
                         the center component.   The  left  and  right
                         components  can be used to display additional
                         information about the entry.  For example,  a
                         menu  entry might represent an option that is
                         selected or not selected, and  a  check  mark
                         can be displayed in the left component of the
                         menu entry to indicate that it  is  selected.
                         Another  example  might  be  a  walking menu,
                         which could be indicated by an arrow  in  the
                         right component of the menu entry.

                         Optional arguments can  be  given  after  the
                         menu entry code to specify: 1) the entry font
                         (:font); 2) whether  the  entry  is  inactive
                         (:dimmed);  and  3)  values  for the left and
                         right components  (:left  and  :right).   The
                         font for the left and right components can be
                         different than the font for the  center  com-
                         ponent  by overriding the :font argument with



          PICASSO Reference Manual                              13-174







                                                                 MENUS


                         :left-font   and    :right-font    arguments.
                         :status is one of :concealed or :exposed.

                         _____________________________________________

          MENU ENTRY
          EXAMPLE



                         For  example,  the  following   specification
                         describes  a font menu for a simple text edi-
                         tor that displays font names, font sizes, and
                         type faces:


                          ("Font"
                             ("Times" (set-font #!times10)
                                      :font #!times12
                                      :right "10"
                                      :right-font #!helv12)
                             ("Helvetica" (set-font #!helv12)
                                      :font #!helv12
                                      :right "10")
                             ("Normal" (set-typeface 'normal)
                                      :left #!check-mark
                                      :font #!helv12)
                             ("Bold" (set-typeface 'bold)
                                      :font #!helv12))


                         Assuming   that   the    PICASSO    variables
                         #!times10,  #!times12, #!helv12, and #!check-
                         mark exist and are bound correctly, this menu
                         entry  specification defines four menu items:
                         two font names and  their  sizes  (Times  and
                         Helvetica),  and  two  type faces (Normal and
                         Bold).  The font names are displayed  in  the
                         font  itself,  and the font size is displayed
                         in the right component  in  a  standard  font
                         (helvetica 12).  The type faces are displayed
                         as entries with a check mark for the selected
                         type face (initially Normal).

                         The  functions  set-font   and   set-typeface
                         change  the  font and typeface, respectively.
                         set-typeface turns off the check mark in  the
                         current  menu  entry  and  turns on the check
                         mark in the selected menu entry.

                         Notice that the :right-font did not  have  to
                         be  set  to  helvetica 12 for the "Helvetica"
                         entry because the :font argument  is  already






          PICASSO Reference Manual                              13-175







                                                                 MENUS


                         set to helvetica 12.

                         _____________________________________________

          MANAGING
          MENU
          ENTRIES




                         Menu entries  are  implemented  as  synthetic
                         gadgets.    The  following  are  provided  to
                         manage menu entries:

                     menu-entry-p

                                                               [_M_a_c_r_o]
                         _s_e_l_f
                         Returns t _i_f _s_e_l_f _i_s _a _m_e_n_u _e_n_t_r_y.

                     set-me-parent

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         _p_a_n_e

                     (setf me-parent)

                                                            [_F_u_n_c_t_i_o_n]
                         _p_a_n_e
                         (_s_e_l_f _l_i_s_t)
                         Adds _s_e_l_f to menu pane _p_a_n_e.

                     me-left

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         The :left _c_o_m_p_o_n_e_n_t _o_f _s_e_l_f. _T_h_i_s  _v_a_l_u_e  _c_a_n
                         _b_e _s_e_t_f'_d, _o_r _u_s_e (_s_e_t-_m_e-_l_e_f_t _s_e_l_f _p_a_n_e ).

                     me-center

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         The :center _c_o_m_p_o_n_e_n_t _o_f  _s_e_l_f.   _T_h_i_s  _v_a_l_u_e
                         _c_a_n  _b_e  _s_e_t_f'_d,  _o_r  _u_s_e (_s_e_t-_m_e-_c_e_n_t_e_r _s_e_l_f
                         _p_a_n_e ).

                     me-right

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         The :right _c_o_m_p_o_n_e_n_t _o_f _s_e_l_f.  _T_h_i_s _v_a_l_u_e _c_a_n
                         _b_e _s_e_t_f'_d, _o_r _u_s_e (_s_e_t-_m_e-_r_i_g_h_t _s_e_l_f _p_a_n_e ).

                     me-font

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         The :font _o_f _s_e_l_f.  _T_h_i_s _v_a_l_u_e _c_a_n _b_e _s_e_t_f'_d,
                         _o_r _u_s_e (_s_e_t-_m_e-_f_o_n_t _s_e_l_f _p_a_n_e ).

                     me-dimmed

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         The :dimmed  _o_f  _s_e_l_f.   _T_h_i_s  _v_a_l_u_e  _c_a_n  _b_e
                         _s_e_t_f'_d, _o_r _u_s_e (_s_e_t-_m_e-_d_i_m_m_e_d _s_e_l_f _p_a_n_e ).

                     show-menu-item

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f





          PICASSO Reference Manual                              13-176







                                                                 MENUS


                         Sets the :exposed _o_f _s_e_l_f _t_o _t.

                     hide-menu-item

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         Sets the :exposed _o_f _s_e_l_f _t_o _n_i_l.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Menu Panes


                         Menu panes are made up of menu entries.  Menu
                         panes  are  a subclass of collection widgets,
                         thus they inherit keys and methods  from  the
                         collection widget class.

                         _____________________________________________

          MENU PANE
          CREATION




                     make-menu-pane

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_t_e_a_r_a_b_l_e _t)
                         (center-left-justified nil)
                         (_p_t_a_b _n_i_l)
                         (menu nil)
                         (_s_y_n_t_h_s _n_i_l)
                         ;; defaults overridden from superclasses
                         (name "A Menu Pane")
                         (parent (root-window))
                         (status :concealed)
                         (gm 'menu-gm)
                         (width-increment 0)
                         (height-increment 0)
                         (conform :grow-shrink)
                         (event-mask
                           '(:enter-window :leave-window
                              :button-press :button-release
                              :pointer-motion :visibility-change))
                         (attach-when-possible t)
                         (background nil)
                         (border-width 0)
                         ;; Plus keys inherited from collection-widgets
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES



                     ptab

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_e_n_u-_p_a_n_e)
                         Used to specify a pixel  table  that  maps  a
                         screen  position  to  a  menu entry.  Of type





          PICASSO Reference Manual                              13-177







                                                                 MENUS


                         vectorP, default nil.

                     center-left-justified

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_e_n_u-_p_a_n_e)
                         Specifies whether the menu center  column  is
                         left justified. Of type atom, _d_e_f_a_u_l_t _n_i_l.

                     menu

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_e_n_u-_p_a_n_e)
                         The pointer from _m_e_n_u-_p_a_n_e back to its parent
                         _m_e_n_u-_b_u_t_t_o_n. Of type menu, _d_e_f_a_u_l_t _n_i_l.

                     synths

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _m_e_n_u-_p_a_n_e
                         Menu pane entries, which are  implemented  as
                         synthetic gadgets.

                     tearable

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_e_n_u-_p_a_n_e)
                         _W_h_e_t_h_e_r _o_r _n_o_t _t_h_e _m_e_n_u-_p_a_n_e _i_s _a _t_e_a_r_a_b_l_e _m_e_n_u.  _T_e_a_r_a_b_l_e
                         _m_e_n_u_s _a_r_e _d_e_s_c_r_i_b_e_d _b_e_l_o_w _u_n_d_e_r "_M_e_n_u _I_n_t_e_r_a_c_t_i_o_n _T_e_c_h_n_i_q_u_e_s". _O_f
                         _t_y_p_e _a_t_o_m, _d_e_f_a_u_l_t _t.

                         _____________________________________________

          MANAGEMENT



                     menu-pane-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Returns true if _o_b_j_e_c_t is a menu-pane object,
                         nil _o_t_h_e_r_w_i_s_e.

                     num-cells

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _m_e_n_u-_p_a_n_e)
                         The number of menu entries in _m_e_n_u-_p_a_n_e.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Menu But-
          tons



                         Menu  buttons  implement  pull   down   menus
                         automatically.   Menu  buttons are a subclass
                         of gray buttons, thus they inherit  keys  and
                         methods  from  gray  buttons.   The following
                         function creates and returns a menu button.

                     make-menu-button

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_m_e_n_u _n_i_l)
                         (bring-back nil)
                         ;; defaults overridden from superclasses
                         (_f_o_n_t "_8_x_1_3")
                         (border-width 1)
                         (_i_n_v_e_r_t-_w_i_d_t_h _3)



          PICASSO Reference Manual                              13-178







                                                                 MENUS


                         ;; Plus keys inherited from gray-buttons
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES



                     menu

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_e_n_u-_b_u_t_t_o_n)
                         The pointer from  _m_e_n_u-_b_u_t_t_o_n  to  its  child
                         _m_e_n_u-_p_a_n_e. Of type menu-pane, _d_e_f_a_u_l_t _n_i_l.

                     bring-back

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_e_n_u-_b_u_t_t_o_n)
                         Whether _m_e_n_u-_b_u_t_t_o_n is invisible or not.   Of
                         type atom, _d_e_f_a_u_l_t _n_i_l.

                         _____________________________________________

          MANAGEMENT



                     menu-button-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Returns  true  if  _o_b_j_e_c_t  is  a  menu-button
                         object, nil _o_t_h_e_r_w_i_s_e.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Menu
          Interac-
          tion




                         Three menu interaction  techniques  are  pro-
                         vided  in  PICASSO, including tear-off, pull-
                         down menus, and pop-up menus.

                         A menu pane can be specified as  tearable  by
                         setting  :tearable  to  t when it is created.
                         Right buttoning on a tearable menu causes  it
                         to tear off.

                         A menu pane can be activate  as  a  pull-down
                         menu by using the following function:

                     activate-pull-down-menu

                                                            [_F_u_n_c_t_i_o_n]
                         _p_a_n_e
                         _m_e_n_u-_b_u_t_t_o_n
                         _e_v_e_n_t
                         Activate pull down menu _p_a_n_e when _m_e_n_u-_b_u_t_t_o_n
                         receives event _e_v_e_n_t.

                         A menu pane can be activated as a pop-up menu
                         by using the following function:

                     activate-pop-up-menu

                                                            [_F_u_n_c_t_i_o_n]
                         _p_a_n_e



          PICASSO Reference Manual                              13-179







                                                                 MENUS


                         _e_v_e_n_t
                         Activate pop up menu  _p_a_n_e  when  _m_e_n_u-_b_u_t_t_o_n
                         receives event _e_v_e_n_t.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Implicit
          Menus



                         Implicit menus can be defined in  frames  and
                         panels by using the optional menu clause, and
                         in pop-buttons by using the  :menu  key.  The
                         menu  bar  of the frame, panel, or pop-button
                         is defined by a _m_e_n_u-_b_a_r-_s_p_e_c which is a list
                         of  menu pane specifications.  Each menu pane
                         has a name, an optional documentation string,
                         an  optional list of control arguments, and a
                         list of menu entries (i.e., menu  operations)
                         that  the  user  can  execute.   A menu entry
                         specifies the entry name and the code  to  be
                         executed when the user selects the entry.

                         Optional arguments can be specified  to  con-
                         trol  the look and behavior of menu panes and
                         entries.  Arguments to the pane are specified
                         before  the  list of menu entries. Pane argu-
                         ments can specify options such as the font to
                         use  for the name, whether the pane is active
                         (i.e., responsive  to  user  selection),  and
                         whether the pane can be torn off.

                         If a pane is declared inactive, the  name  of
                         the  inactive pane is dimmed to provide feed-
                         back to the user that the pane  is  inactive;
                         moreover,  the  pane  will  not  pop-up  when
                         selected with the mouse. Tear off  menus  can
                         be retained on the screen by right buttoning,
                         and menu panes behave like any other window.

                         _____________________________________________

          MENU EXAM-
          PLE



                         For example, a menu pane specification for  a
                         simple text editor in an edit frame might be:














          PICASSO Reference Manual                              13-180







                                                                 MENUS



                          (defframe ("editor" "demo" . "frame")
                            "example of implicit menu pane specification"
                            (menu (("Edit" "Edit Selection"
                                     :tear-off
                                     ("Cut" _L_I_S_P-_f_o_r_m )
                                     ("Paste" _L_I_S_P-_f_o_r_m )
                                     ("Copy" _L_I_S_P-_f_o_r_m )
                                     ("Search" _L_I_S_P-_f_o_r_m ))
                                  (("File" "File operations"
                                     :dimmed
                                     ("Load" _L_I_S_P-_f_o_r_m )
                                     ("Save" _L_I_S_P-_f_o_r_m )
                                     ("File List" _L_I_S_P-_f_o_r_m ))))
                             .
                             .
                             .
                          )


                         and a similar specification in  a  pop-button
                         might be:


                          (make-pop-button
                            :items '(("Edit" "Edit Selection"
                                     :tear-off
                                     ("Cut" _L_I_S_P-_f_o_r_m )
                                     ("Paste" _L_I_S_P-_f_o_r_m )
                                     ("Copy" _L_I_S_P-_f_o_r_m )
                                     ("Search" _L_I_S_P-_f_o_r_m ))
                                  (("File" "File operations"
                                     :dimmed
                                     ("Load" _L_I_S_P-_f_o_r_m )
                                     ("Save" _L_I_S_P-_f_o_r_m )
                                     ("File List" _L_I_S_P-_f_o_r_m )))


                         These menu pane  specifications  both  define
                         two  menu  panes.  The  Edit  menu  pane is a
                         tear-off menu that contains menu  entries  to
                         cut,  paste,  copy,  or  search for text. The
                         File menu pane is currently dimmed, and  con-
                         tains entries to load, save, or list files.











          PICASSO Reference Manual                              13-181







                                                                TABLES


                                              14
                                            TABLES

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview



                         It is often desirable to display  data  in  a
                         tabular format.  For example, a developer who
                         creates a tool that uses a  relational  data-
                         base  might  want  to  provide  an  interface
                         abstraction for a relation as  a  table.   At
                         other  times,  users  want  to browse through
                         large amount of data that  is  hierarchically
                         organized.   The  widgets  described  in this
                         chapter are used to display data  in  tabular
                         format.   They  vary in power and ease of use
                         -- table-fields have the greatest flexibilty,
                         but they also require the user to specify the
                         most options.  In  contrast,  list-boxes  are
                         less flexible, but are very easy to use.

                         The types of controls implemented in  PICASSO
                         are:

                         o+    Browse-Widgets  -  used   for   browsing
                              hierarchical data.

                         o+    Matrix-Fields - used for displaying  and
                              editing  an array of data with arbitrary
                              elements

                         o+    Table-Fields  -  a  matrix  field   with
                              optional labels and scroll-bars.

                         o+    List-Boxes - used for displaying a  sin-
                              gle row or column of data.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Browse
          Widgets




                         Browse-widgets  allow  the  user  to   browse
                         through  a  list of objects in a hierarchical
                         manner.  For  example,  consider  browsing  a
                         list  of objects that have _d_e_p_a_r_t_m_e_n_t, _c_o_u_r_s_e
                         and _s_e_c_t_i_o_n slots. A browse widget  for  this
                         list  would  contain  three  tables, arranged
                         left to right.  Initially,  the  first  table
                         would  contain  a  sorted  list  of  all  the
                         departments,  the  second  and  third  tables
                         would  be  blank.   When  the  user selects a
                         department by buttoning with the  left  mouse



          PICASSO Reference Manual                              14-182







                                                                TABLES


                         button,  the  second  table  fills in  with a
                         list of all  the  course  names  within  that
                         department.   If  the  user selects a course,
                         the third table lists  all  the  sections  of
                         that  course.  In this way, a user may browse
                         a hierarchal data structure.

                         The user may also view the contents  of  more
                         than  one subtree of the hierarchy at a time.
                         In the example above, the user can  view  all
                         the   courses   in   both  the  ``math''  and
                         ``english''  departments  at  one  time.   To
                         extend  the  selected  courses, the user uses
                         the right mouse button.  For example, if  the
                         user  were already looking at all the courses
                         in the ``math'' department, by selecting  the
                         ``english''  department  with the right mouse
                         button, the courses  table  would  contain  a
                         list  of all the courses in both the ``math''
                         and ``english'' departments.

                         Browse widgets communicate with other widgets
                         by  using  the  _s_e_l_e_c_t_i_o_n  slot in the browse
                         widget.  At any time,  this  slot  (which  is
                         initially nil) _c_o_n_t_a_i_n_s _t_h_e _s_u_b_s_e_t _o_f _o_b_j_e_c_t_s
                         _t_h_a_t _t_h_e _u_s_e_r _i_s  _v_i_e_w_i_n_g.   _I_n  _t_h_e  _e_x_a_m_p_l_e
                         _a_b_o_v_e,  _t_h_i_s _s_l_o_t _w_o_u_l_d _c_o_n_t_a_i_n _a _l_i_s_t _o_f _a_l_l
                         _c_o_u_r_s_e_s _i_n _t_h_e _m_a_t_h _a_n_d _e_n_g_l_i_s_h _d_e_p_a_r_t_m_e_n_t_s.

                         Browse-widgets also  have  a  notion  of  the
                         current-selection,  which  is a list of items
                         that have been fully specified by  the  user.
                         The  user  selects  these when they button in
                         the rightmost table of the browse-widget.

                         Below is a picture of a browse-widget:



















          PICASSO Reference Manual                              14-183







                                                                TABLES











                             Picture of a browse-widget.











                         _____________________________________________

          CREATION


                         Browse widgets are a subclass  of  collection
                         widgets,  thus  they inherit keys and methods
                         from collection widgets.  The following func-
                         tion creates and returns a browse widget:

                     make-browse-widget

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_t_i_t_l_e-_f_o_n_t (_m_a_k_e-_f_o_n_t))
                         (col-widths nil)
                         (_f_o_n_t (_m_a_k_e-_f_o_n_t))
                         (sort-keys nil)
                         (_d_a_t_a _n_i_l)
                         ;; defaults overridden from superclasses
                         (event-mask '(:exposure :button-press))
                         (gm 'rubber-gm)
                         (name "A Browser")
                         ;; Plus keys inherited from collection-widgets
                         &allow-other-keys
                         Creates and returns a browse widget.

                         _____________________________________________

          ATTRIBUTES



                     data

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_r_o_w_s_e-_w_i_d_g_e_t)
                         The list of objects currently viewable within




          PICASSO Reference Manual                              14-184







                                                                TABLES


                         the browse-widget.

                     sort-keys

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_r_o_w_s_e-_w_i_d_g_e_t)
                         A list of  cons  _c_e_l_l_s,  _o_n_e  _c_o_n_s  cell  per
                         column  in the browse-widget. The car _o_f _e_a_c_h
                         _c_o_n_s cell is a string label for  its  column,
                         and  the  cdr  _i_s  _a  _r_e_a_d_e_r _f_u_n_c_t_i_o_n _f_o_r _t_h_e
                         _o_b_j_e_c_t _w_h_i_c_h _s_h_o_u_l_d _r_e_t_u_r_n _a _s_t_r_i_n_g.  _I_n  _t_h_e
                         _e_x_a_m_p_l_e  _g_i_v_e_n  _a_t _t_h_e _b_e_g_i_n_n_i_n_g _o_f _t_h_i_s _s_e_c_-
                         _t_i_o_n, _t_h_e _v_a_l_u_e  _o_f  _t_h_e  _s_o_r_t-_k_e_y_s  _a_r_g_u_m_e_n_t
                         _s_h_o_u_l_d _b_e:


                          (_l_i_s_t (_c_o_n_s "_D_e_p_a_r_t_m_e_n_t" #'_d_e_p_t)
                                (_c_o_n_s "_C_o_u_r_s_e" #'_c_o_u_r_s_e)
                                (_c_o_n_s "_S_e_c_t_i_o_n" #'_s_e_c_t_i_o_n))




                     column-widths

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_r_o_w_s_e-_w_i_d_g_e_t)
                         A list of numbers giving the relative  widths
                         of  the  columns.  If not supplied, the rela-
                         tive widths of the columns will be determined
                         the  same  as  the  relative  lengths  of the
                         labels of each column.

                     font

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_r_o_w_s_e-_w_i_d_g_e_t)
                         The font to use in displaying  the  items  in
                         the table

                     title-font

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_r_o_w_s_e-_w_i_d_g_e_t)
                         The font to be used for displaying the column
                         labels.  These should be fixed-width fonts.

                         _____________________________________________

          BROWSE
          WIDGET
          SYNCHRONI-
          ZATION






                     selection

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _b_r_o_w_s_e-_w_i_d_g_e_t)

                         This  method  returns  the  list  of  objects
                         currently  selected  by  the user.  This list
                         contains all objects  that  match  the  users
                         specification, including partial matches.  In
                         the department-course-section example, if the
                         user  has  selected  the ``math'' department,



          PICASSO Reference Manual                              14-185







                                                                TABLES


                         this slot would contain a list of all courses
                         in  the  _d_a_t_a  slot that were in the ``math''
                         department.

                     current-selection

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _b_r_o_w_s_e-_w_i_d_g_e_t)

                         This  method  returns  the  list  of  objects
                         currently  fully specified by the user.  Only
                         those objects for which the user  has  speci-
                         fied  a value in the last column will be part
                         of this list.

                         _____________________________________________

          BROWSE
          WIDGET
          SUMMARY






                                 ________________________________
                                  Attributes   Methods
                                 ________________________________________________________________
                                  data         current-selection
                                  col-width    selection
                                  sort-keys
                                  font
                                  title-font
                                 ________________________________

                                |
                                |
                                |
                                |
                                |
                                |
                                |
                                |






                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |
                                            |






                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |









          ____________________________________________________________________________________________________________________________________________________________________________________

          Matrix-
          Field




                         Table-fields (or  just  tables)  and  matrix-
                         fields  (or  just  matrices)  are designed to
                         display data which is  intrinsically  tabular
                         (ie.  can be organized into rows and columns)
                         in   structure.    Matrix-fields   (or   just
                         matrices) are the "bare-bones" of the PICASSO
                         table-field.  A table in PICASSO is merely  a
                         container  for  a matrix, so most of learning
                         how to use tables is figuring  out  matrices.
                         Matrix-fields  are  very  powerful and versa-
                         tile, but they  can  be  rather  complex  and
                         creating/managing  them  can  be difficult at
                         first.  The key realization is  that,  though
                         there   are  so  many  options,  sufficiently
                         powerful  matrices  can  be   created/managed







          PICASSO Reference Manual                              14-186







                                                                TABLES


                         employing only a small subset of the options.

                         _____________________________________________

          DISPLAY
          FORMAT




                         The  matrix-field  displays  a  2-dimensional
                         array  of  data  in  a 2-dimensional array of
                         fields.  The mapping between data and  fields
                         need  not be one-to-one, as there may be more
                         data objects than fields.

                         Note: Matrix-fields do  not  support  dynami-
                         cally  changing the number of rows or columns
                         displayed.  However, the  data  displayed  in
                         the  matrix  field can easily be changed (see
                         section on data management).

                         _____________________________________________

          CREATION



                         On instantiation, a _m_a_t_r_i_x-_f_i_e_l_d creates

                         (1)  an array of data (if  the  data  is  not
                              already in an array format)

                         (2)  an array of fields

                         (3)  a   matrix-field   for   column   titles
                              (optional)

                         (4)  a matrix-field for row titles (optional)

                         (5)  a  cache  of  scrolling  functions  (for
                              optimization)

                         (6)  other stuff (to be discussed later)

                         The first two of these have already been dis-
                         cussed.   Items  (3)  & (4) may or may not be
                         used (even if they are created).  The columns
                         titles  are  of  dimension  (1  rows) and the
                         row-titles  are  of  dimension  (1  columns),
                         where  the  whole matrix (without titles) has
                         dimension (rows columns).  The column and row
                         title  matrices  can  be accessed through the
                         methods row-title-matrix and col-title-matrix
                         described above.  Item (5) is just a cache of
                         functions to  use  for  scrolling  up,  down,
                         left,  and  right.   Depending on whether the
                         rows/columns     of     fields     are     of



          PICASSO Reference Manual                              14-187







                                                                TABLES


                         uniform height/width   (respectively),   dif-
                         ferent scrolling functions are more efficient
                         than  others.  The decision and cache is made
                         at instantiation  and  both  are  updated  if
                         necessary  whenever  the base-size of a field
                         in the matrix changes.

                         The  creation  options  to  matrix-field  are
                         somewhat  intricate,  but  they  allow  for a
                         range of different types of  matrices  to  be
                         created (many quite easily).  The tricky part
                         is specifying what types of fields are to  be
                         displayed  in the matrix.  The default field-
                         type is the synthetic gadget which is just an
                         un-editable  displayer  of  an arbitrary data
                         item  (eg.  string,  image,  etc.).   In  the
                         default  case, the col-widths and row-heights
                         may be used to tailor the sizes of the fields
                         in  the  matrix.   Synthetic gadgets are used
                         unless unless either :row-elements  or  :col-
                         elements  is specified.  Following is a brief
                         description  of  the  non-standard   creation
                         options.

                     make-matrix-field

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_i_n_t_e_r-_r_o_w-_p_a_d _3)
                         (inter-col-pad 3)
                         (_r_o_w-_i_n_d_e_x _0)
                         (col-index 0)
                         (_d_a_t_a _n_i_l)
                         (data-rows 0)
                         (_d_a_t_a-_c_o_l_s _0)
                         (rows nil)
                         (_c_o_l_s _n_i_l)
                         (data-rows _r_o_w_s)
                         (data-cols _c_o_l_s)
                         (data-array-size (list (num-rows _d_a_t_a) (_n_u_m-_c_o_l_s _d_a_t_a)))
                         (_o_v_e_r_f_l_o_w-_i_n_c_r_e_m_e_n_t _5)
                         (_g_r_i_d-_l_i_n_e_s _t)
                         (_r_o_w-_e_l_e_m_e_n_t_s _n_i_l)
                         (_c_o_l-_e_l_e_m_e_n_t_s _n_i_l)
                         (_r_o_w-_h_e_i_g_h_t_s _4_0)
                         (_c_o_l-_w_i_d_t_h_s _1_0_0)
                         (_i_n_i_t_i_a_l-_r_o_w_s _n_i_l)
                         (_i_n_i_t_i_a_l-_c_o_l_s _n_i_l)
                         (_f_o_n_t (_d_e_f_a_u_l_t-_f_o_n_t))
                         (_t_i_t_l_e_s _n_i_l)
                         (_c_o_l-_t_i_t_l_e_s _n_i_l)
                         (_r_o_w-_t_i_t_l_e_s _n_i_l)
                         (_d_e_f_a_u_l_t-_t_i_t_l_e_s _t)
                         (_r_o_w-_t_i_t_l_e-_w_i_d_t_h _1_0_0)



          PICASSO Reference Manual                              14-188







                                                                TABLES


                         (_c_o_l-_t_i_t_l_e-_h_e_i_g_h_t _4_0)
                         (_r_o_w-_t_i_t_l_e-_e_l_e_m_e_n_t_s _n_i_l)
                         (_c_o_l-_t_i_t_l_e-_e_l_e_m_e_n_t_s _n_i_l)
                         (_r_o_w-_t_i_t_l_e-_f_o_n_t (_d_e_f_a_u_l_t-_f_o_n_t))
                         (_c_o_l-_t_i_t_l_e-_f_o_n_t (_d_e_f_a_u_l_t-_f_o_n_t))
                         (_s_e_l_f-_a_d_j_u_s_t_a_b_l_e _n_i_l)
                         (_s_e_l_e_c_t_i_o_n :_e_n_t_r_y)
                         (_c_u_r_r_e_n_t-_i_n_d_i_c_e_s _n_i_l)
                         (_s_e_l_e_c_t-_f_u_n_c _n_i_l)
                         (_u_n_s_e_l_e_c_t-_f_u_n_c _n_i_l)
                         (_u_n_i_q_u_e-_s_e_l_e_c_t_i_o_n _n_i_l)
                         (_r_o_w-_t_i_t_l_e-_s_e_l_e_c_t_a_b_l_e _n_i_l)
                         (_c_o_l-_t_i_t_l_e-_s_e_l_e_c_t_a_b_l_e _n_i_l)
                         (_e_d_i_t_a_b_l_e _n_i_l)
                         (_e_d_i_t_a_b_l_e-_r_o_w-_t_i_t_l_e_s _n_i_l)
                         (_e_d_i_t_a_b_l_e-_c_o_l-_t_i_t_l_e_s _n_i_l)
                         (_r_e_t_u_r_n-_f_u_n_c _n_i_l)
                         (_j_u_s_t :_c_e_n_t_e_r)
                         (_h_o_r_i_z-_j_u_s_t :_c_e_n_t_e_r)
                         (_v_e_r_t-_j_u_s_t :_c_e_n_t_e_r)
                         (_f_i_e_l_d-_t_a_b_l_e _n_i_l)
                         (_f_r_e_e-_n_o_m_a_d _n_i_l)
                         ;; Plus keys inherited from collection-widgets
                         &allow-other-keys
                         Creates and returns a  matrix  field.  Matrix
                         fields  are a subclass of collection widgets,
                         and thus inherit keys and methods  from  col-
                         lection gadgets.

                         _____________________________________________

          ATTRIBUTES



                     inter-row-pad

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The  space  (in  pixels)  between  each  row.
                         Default 3.

                     inter-col-pad

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The space (in pixels)  between  each  column.
                         Default 3.

                     row-index

                                                            [_A_r_g_u_m_e_n_t]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The  index  into  the  data  that  should  be
                         displayed  in  the  top  visible  row  of the
                         matrix.  See above note on display format  of
                         a matrix.  Default 0.

                     col-index

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)



          PICASSO Reference Manual                              14-189







                                                                TABLES


                         The  index  into  the  data  that  should  be
                         displayed  in  the  top visible column of the
                         matrix.  See above note on display format  of
                         a matrix.  Default 0.

                     data

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The data to be displayed in the fields of the
                         matrix.   Data may be specified in either one
                         of two ways:


                          (<row1> <row2> <row3> . . .)


                         where each _r_o_w is a list of data items.  This
                         can also be seen as


                                              (<row1>
                                               <row2>
                                               <row3>
                                               . . .)


                         (2) A two dimensional  array,  in  which  the
                         first  dimension  is  the rows, the second is
                         the columns.
                         (3) A pgclos portal.

                         The default is an array (rows cols) of nil.

                     data-rows

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The number of rows of  data  from  the  data-
                         table to be used in the matrix.

                     data-cols

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The number of columns of data from the  data-
                         table to be used in the matrix.

                     rows

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The total number of rows of fields  (not  all
                         are  necessarily displayed at the same time).
                         The default is determined  dynamically  based
                         on others args.

                     cols

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The total number of columns  of  fields  (not



          PICASSO Reference Manual                              14-190







                                                                TABLES


                         all  are  necessarily  displayed  at the same
                         time).  The default is determined dynamically
                         based on others args.

                     data-rows

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The number of rows  of  data  from  the  data
                         table  to be used in the matrix.  The default
                         is all rows.

                     data-cols

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The number of columns of data from  the  data
                         table  to be used in the matrix.  The default
                         is all columns.

                     data-array-size

                                                            [_A_r_g_u_m_e_n_t]
                         An initial argument  only.  If  specified,  a
                         list  (rows columns) specifying how large the
                         initial data-array  should  be.  :data-array-
                         size  is useful if an initial :data is speci-
                         fied and the data is expected to  grow.   The
                         default is the size of data.

                     overflow-increment

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The increment by which to  "grow"  the  data-
                         table  if  it  should  over-flow (by means of
                         insert-row/col  operations).  If  nil,  _t_a_b_l_e
                         _c_a_n'_t _g_r_o_w.  _T_h_e _d_e_f_a_u_l_t _i_s _5.

                     grid-lines

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         Draw dotted lines between rows &  columns  if
                         non-nil.

                     row-elements, col-elements

                                                            [_A_r_g_u_m_e_n_t]
                         _I_n_i_t_i_a_l _a_r_g_u_m_e_n_t_s _o_n_l_y.  _A  _l_i_s_t  _o_f  _e_x_p_r_e_s_-
                         _s_i_o_n_s  _w_h_i_c_h _m_a_y _b_e _e_v_a_l_u_a_t_e_d _i_n_d_i_v_i_d_u_a_l_l_y _t_o
                         _a_c_t_u_a_l_l_y _c_r_e_a_t_e _t_h_e _f_i_e_l_d_s _t_h_a_t  _s_h_o_u_l_d  _c_o_n_-
                         _s_t_i_t_u_t_e  _t_h_e  _e_l_e_m_e_n_t_s  _o_f _e_a_c_h _r_o_w/_c_o_l_u_m_n _o_f
                         _t_h_e _m_a_t_r_i_x.

                         Only  one  of  row-elements  _o_r  _c_o_l-_e_l_e_m_e_n_t_s
                         should be specified, or one will be ignored.

                         For example:,








          PICASSO Reference Manual                              14-191







                                                                TABLES



                          :row-elements
                            (:base-height 20 :font "8x13" :editable t)
                            (make-check-widget :background "green")
                            (:base-height 50 :unselectable t)
                            (make-gray-button :base-height 20))


                         creates a matrix in which the  first  row  is
                         all  meter-  widgets, the second row consists
                         of  synthetic  widgets,  the  third  row   of
                         check-widgets,  the fourth of synthetic gadg-
                         ets, and the fifth of gray-buttons. The first
                         and  fourth  rows of the matrix are unselect-
                         able.  An unselectable field cannot become  a
                         current-field  of  the  matrix.   The  :value
                         should generally not be specified by  any  of
                         these  expressions  as the value will only be
                         overrided  in  the  matrix.   A  non-editable
                         matrix row/column is typically made by speci-
                         fying one of the  row/col-elements  to  be  a
                         gadget  of  some  sort  (either  real or syn-
                         thetic). All fields in a matrix  are  select-
                         able   by  default,  unless  either  the  mf-
                         selectable slot of the widget is nil, or  the
                         keyword :unselectable is specified with value
                         t in  any  of  the  fields  of  the  row/col-
                         elements (see above example).

                         If used in association with  :rows  or  :row-
                         heights, the matrix will create how ever many
                         rows are specified and reuse  the  last  row-
                         element  for any remaining rows not specified
                         by a :row-elements.  This allows creation  of
                         a  table of unselectable synthetic gadgets by
                         means of:


                          (make-matrix-field
                            :row-elements '((:unselectable t))
                            :row-heights '(30 60 10 20 30 40 50 29)
                            :font "8x13")


                         Creation, scrolling, and resizing time become
                         major bottlenecks with large matrices. Hence,
                         we  have  invented  things  called  _s_y_n_t_h_e_t_i_c
                         fields  which  mimic real fields (widgets and
                         gadgets) but with real time  behavior.   Tim-
                         ings  indicate that a table can be speeded up
                         by between 1000 and  2000  percent  by  using
                         synthetic  fields  instead of "real" ones.  A



          PICASSO Reference Manual                              14-192







                                                                TABLES


                         synthetic widget can  be  created  using  the
                         :editable keyword in either the :col-elements
                         or  :row-elements.   Basically,  a  synthetic
                         field is a synthetic widget if it's editable,
                         a synthetic gadget if  it's  not.   Synthetic
                         widgets  have  the property that whenever you
                         select one, a real widget jumps to replace it
                         on  the  screen (and disappears when it is no
                         longer current).  Thus, instead  of  creating
                         widget  for  every  place  in the matrix (225
                         entries for a 15x15 table) we are now  creat-
                         ing  only  one (called a _n_o_m_a_d-_w_i_d_g_e_t).  This
                         explains the enhanced performance of matrices
                         with synthetic fields.  Synthetic widgets and
                         gadgets can display (and edit)  simple  data-
                         items   considerably  faster  than  any  real
                         widget/gadget.  Users are strongly  urged  to
                         use synthetic fields in place of text widgets
                         and gadgets.  The default is synthetic  gadg-
                         ets.

                     row-heights, col-widths

                                                            [_A_r_g_u_m_e_n_t]
                         Initial arguments only, an  integer  or  list
                         specifying   the   heights/widths   of   each
                         row/column in the matrix.  The  defaults  are
                         100 for rows, 40 for columns.

                     initial-rows, initial-cols

                                                            [_A_r_g_u_m_e_n_t]
                         Initial  arguments  only,   the   number   of
                         rows/columns  of  fields to be displayed ini-
                         tially in the matrix.  The defaults  are  the
                         total number of rows/columns that fit.

                     font

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The font of all synthetic widgets/gadgets  in
                         the matrix.

                     titles

                                                            [_A_r_g_u_m_e_n_t]
                         Initial argument only, used to specify a list
                         of data to display in the column-titles.

                     col-titles

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         A list of data  to  display  in  the  column-
                         titles,   default  nil.   _C_o_l_u_m_n  _t_i_t_l_e_s  _a_r_e
                         _d_i_s_p_l_a_y_e_d  _a_d_j_a_c_e_n_t  _t_o  _e_v_e_r_y   _c_o_l_u_m_n,   _i_n
                         _s_e_p_a_r_a_t_e  _m_a_t_r_i_x  _f_i_e_l_d_s _t_h_a_t _s_c_r_o_l_l _s_y_n_c_h_r_o_-
                         _n_o_u_s_l_y _w_i_t_h _t_h_e _m_a_t_r_i_x.  _T_h_i_s  _v_a_l_u_e  _c_a_n  _b_e
                         _s_e_t_f'd  only  if  the matrix-field is created





          PICASSO Reference Manual                              14-193







                                                                TABLES


                         with a col-title.

                     row-titles

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         A list of data to display in the  row-titles,
                         default  nil.  _R_o_w _t_i_t_l_e_s _a_r_e _d_i_s_p_l_a_y_e_d _a_d_j_a_-
                         _c_e_n_t _t_o _e_v_e_r_y _r_o_w, _i_n _s_e_p_a_r_a_t_e _m_a_t_r_i_x  _f_i_e_l_d_s
                         _t_h_a_t  _s_c_r_o_l_l  _s_y_n_c_h_r_o_n_o_u_s_l_y  _w_i_t_h _t_h_e _m_a_t_r_i_x.
                         _T_h_i_s _v_a_l_u_e _c_a_n _b_e _s_e_t_f'd only if the  matrix-
                         field is created with a row-title.

                     default-titles

                                                            [_A_r_g_u_m_e_n_t]
                         Initial argument only, If t, :_c_o_l-_t_i_t_l_e_s  are
                         not  specified,  and  :data is a portal, then
                         default column titles will  be  created  con-
                         sisting of the names of all the fields of the
                         relation (designated  by  the  portal).   The
                         default is t.

                     row-title-width, col-title-height

                                                            [_A_r_g_u_m_e_n_t]
                         Initial arguments only.   The  widths/heights
                         of all fields in the row/col-titles.

                     row-title-elements, col-title-elements

                                                            [_A_r_g_u_m_e_n_t]
                         Initial  arguments  only.   Can  be  used  to
                         specify the types of fields to be used in the
                         row/column titles.  Format is the same as for
                         :row/col-elements.   The default is synthetic
                         gadgets.

                     row-title-font, col-title-font

                                                            [_A_r_g_u_m_e_n_t]
                         Initial arguments only, may be  used  to  set
                         the  font of the row/col-titles.  The default
                         is "8x13bold".

                     self-adjustable

                                                            [_A_r_g_u_m_e_n_t]
                         _I_n_i_t_i_a_l _a_r_g_u_m_e_n_t _o_n_l_y.  _I_f _t, _t_h_e _f_i_e_l_d_s _w_i_l_l
                         _a_u_t_o_m_a_t_i_c_a_l_l_y  _a_d_j_u_s_t  _t_o  _m_e_e_t  _t_h_e_i_r  _b_a_s_e-
                         _s_i_z_e_s.  _T_h_i_s _c_a_n _b_e _n_i_c_e, _b_u_t _i_t _s_l_o_w_s _t_h_i_n_g_s
                         _d_o_w_n  _s_o_m_e_w_h_a_t  _a_n_d _i_t _m_a_k_e_s _t_h_e _t_a_b_l_e _c_h_a_n_g_e
                         _c_o_n_s_i_d_e_r_a_b_l_y _w_h_e_n_e_v_e_r  _t_h_e  _v_a_l_u_e_s  _d_i_s_p_l_a_y_e_d
                         _c_h_a_n_g_e _c_o_n_s_i_d_e_r_a_b_l_y (_i_e.  _i_f _a _l_o_n_g _s_t_r_i_n_g _i_s
                         _s_u_d_d_e_n_l_y _s_c_r_o_l_l_e_d _i_n_t_o _v_i_e_w).  _T_h_e _d_e_f_a_u_l_t _i_s
                         _n_i_l.

                     selection

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         Determines what type of selection protocol to
                         use.   Possible values include :entry (_s_e_l_e_c_t
                         _a_n_y _d_a_t_a-_i_t_e_m), :_r_o_w (select any  row),  :col
                         _o_r  :_c_o_l_u_m_n  (select  any  column),  and  nil
                         (_s_e_l_e_c_t_i_o_n _i_s _d_i_s_a_b_l_e_d).



          PICASSO Reference Manual                              14-194







                                                                TABLES


                         The default is :entry.

                     unique-selection

                                                            [_A_r_g_u_m_e_n_t]
                         _I_n_i_t_i_a_l _a_r_g_u_m_e_n_t  _o_n_l_y.   _I_f  _p_a_s_s_e_d  _w_i_t_h  _a
                         _v_a_l_u_e _o_f _t, _a_l_l _b_u_t_t_o_n _c_l_i_c_k_s _w_i_l_l _i_n_v_o_k_e _t_h_e
                         _h_a_n_d_l_e_r  _s_e_l_e_c_t-_u_n_i_q_u_e  and  multiple   field
                         selections  will be disabled.  The default is
                         nil.

                     row-title-selectable, col-title-selectable

                                                            [_A_r_g_u_m_e_n_t]
                         _I_n_i_t_i_a_l   _a_r_g_u_m_e_n_t_s   _o_n_l_y.    _I_f    _n_o_n-_n_i_l,
                         _r_o_w/_c_o_l_u_m_n  _t_i_t_l_e_s  _c_a_n  _b_e  _s_e_l_e_c_t_e_d (_m_a_r_k_e_d
                         _c_u_r_r_e_n_t).  _T_h_e _d_e_f_a_u_l_t _i_s _n_i_l.

                     editable

                                                            [_A_r_g_u_m_e_n_t]
                         _I_n_i_t_i_a_l _a_r_g_u_m_e_n_t _o_n_l_y.  _T_h_e _d_e_f_a_u_l_t  _e_d_i_t_a_b_l_e
                         _a_t_t_r_i_b_u_t_e  _f_o_r  _s_y_n_t_h_e_t_i_c _f_i_e_l_d_s _s_p_e_c_i_f_i_e_d _i_n
                         :_r_o_w/_c_o_l-_e_l_e_m_e_n_t_s. For example,


                          (make-matrix-field
                            :rows 5
                            :cols 2
                            :editable t)


                         creates a matrix consisting entirely of  syn-
                         thetic  widgets  (each  field can be indepen-
                         dently edited).  The default is nil.

                     editable-row-titles, editable-col-titles

                                                            [_A_r_g_u_m_e_n_t]
                         _I_n_i_t_i_a_l _a_r_g_u_m_e_n_t_s _o_n_l_y; _s_a_m_e _a_s :_e_d_i_t_a_b_l_e but
                         for row/column titles.  The default is nil.

                     current-indices

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         A list of all the indices of  the  data-items
                         that  are currently selected.  When selection
                         is :entry, the format of current-indices  is:
                         ([_r_o_w  _c_o_l_u_m_n]*),  where  each _r_o_w and _c_o_l_u_m_n
                         are the row and column offsets of  the  data-
                         item into the data-array, for example:


                          (setf (current-indices _m_f)
                                '((3 0) (52 37)))


                         The data-item itself can be obtained by pass-
                         ing _r_o_w and _c_o_l_u_m_n to mref.





          PICASSO Reference Manual                              14-195







                                                                TABLES


                         In  the  case  of  row-selection  or  column-
                         selection,   current-indices  has  the  form:
                         ([_i_n_d_e_x]*) where each  _i_n_d_e_x  corresponds  to
                         one row or column of data, for example:


                          (setf (current-indices _m_f)
                                '(0 7 3 87 24))
                          (setf (current-indices _m_f)
                                '(2))



                         The current-indices accessor should  be  used
                         whenever  the  list of current items needs to
                         be changed.

                     return-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         An expression to  be  executed  whenever  the
                         return  key is pressed in a synthetic widget;
                         actually the return-func of the _n_o_m_a_d-_w_i_d_g_e_t.
                         The default is nil.

                     select-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The expression to execute  whenever  current-
                         indices  has  been  changed  and the current-
                         fields have been updated.  The expression  is
                         executed  with the following lexical environ-
                         ment: _s_e_l_f is the matrix-field, and _e_v_e_n_t  is
                         the new current-indices.

                     unselect-func

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The expression to execute  whenever  current-
                         indices  has  been  changed  but  before  the
                         current-fields  have   been   updated.    The
                         expression  is  executed  with  the following
                         lexical  environment:  _s_e_l_f  is  the  matrix-
                         field, and _e_v_e_n_t is the new current-indices.

                     just

                                                            [_A_r_g_u_m_e_n_t]
                         Initial argument only.  Specifies the default
                         justification  (horizontal  and  vertical) of
                         every synthetic gadget in  the  matrix.   The
                         default is :center.

                     horiz-just, vert-just

                                                            [_A_r_g_u_m_e_n_t]
                         _I_n_i_t_i_a_l  _a_r_g_u_m_e_n_t_s   _o_n_l_y.    _S_p_e_c_i_f_i_e_s   _t_h_e
                         _d_e_f_a_u_l_t  _h_o_r_i_z_o_n_t_a_l/_v_e_r_t_i_c_a_l _j_u_s_t_i_f_i_c_a_t_i_o_n _o_f
                         _e_v_e_r_y _s_y_n_t_h_e_t_i_c _g_a_d_g_e_t _i_n  _t_h_e  _m_a_t_r_i_x.   _T_h_e



          PICASSO Reference Manual                              14-196







                                                                TABLES


                         _d_e_f_a_u_l_t_s _a_r_e :_c_e_n_t_e_r.

                     field-table

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The table of fields to display in the matrix.
                         Usually  not specified (do not specify unless
                         you know exactly what you're doing) Any  type
                         of PICASSO gadget or widget can be a field in
                         a matrix.  In addition, synthetic gadgets  or
                         _s_y_n_t_h_s can be used as fields in a matrix.  It
                         is usually a good idea to use _s_y_n_t_h_s  instead
                         of  real widgets/gadgets because matrices are
                         highly optimized in the use of  _s_y_n_t_h_s.   See
                         the  section on creation for more information
                         on fields.  The  default  is  constructed  at
                         run-time.

                     free-nomad

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         If non-nil, the nomad-widget is set to  be  a
                         child  of  the root-window.  The nomad-widget
                         is the editable widget that pops up  whenever
                         an  editable  synthetic  gadget  (a synthetic
                         widget) is edited.

                         _____________________________________________

          DISPLAY
          MANAGEMENT




                     visible-rows

                                                            [_A_c_c_e_s_s_o_r]
                         (self matrix-field)
                         The  number  of  rows  of  fields  that   are
                         currently  visible.   Unless  explicitly set,
                         visible-rows will be  the  maximum  that  fit
                         into  the  area  occupied  by the matrix (see
                         matrix-gm for more information).

                     visible-cols

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The number of  columns  of  fields  that  are
                         currently  visible.   Unless  explicitly set,
                         visible-cols will be  the  maximum  that  fit
                         into  the  area  occupied  by the matrix (see
                         matrix-gm for more information).

                     row-title-matrix

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         A matrix-field through which  row-titles  are
                         displayed.

                     col-title-matrix

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)



          PICASSO Reference Manual                              14-197







                                                                TABLES


                         matrix-field  through  which  col-titles  are
                         displayed.

                         _____________________________________________

          DATA
          MANAGEMENT




                         As previously mentioned, matrices  coordinate
                         two  tables:   the  field-table and the data-
                         table.  The  following  additional  accessors
                         can  be  used  to set and retrieve attributes
                         concerning the data-table.

                     mref

                                                            [_F_u_n_c_t_i_o_n]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         _r_o_w
                         _c_o_l_u_m_n
                         Used in a manner similar to  aref  to  access
                         data elements from the matrix _a-_m_a_t_r_i_x-_f_i_e_l_d,
                         and is settable.  The expression:


                          (mref _m_a_t_r_i_x-_f_i_e_l_d _r_o_w _c_o_l)


                         is equivalent to the expression:


                          (aref (data _m_a_t_r_i_x-_f_i_e_l_d) _r_o_w _c_o_l)


                         However, the expression:


                          (setf (mref _m_a_t_r_i_x-_f_i_e_l_d _r_o_w _c_o_l) new-val)


                         Does the corresponding aref  in  addition  to
                         updating  the output of the matrix to reflect
                         the new data value.  This function  and  setf
                         should   be  used  whenever  individual  data
                         objects need to  be  altered.   Updating  the
                         output of the matrix can be disabled by turn-
                         ing off the repaint-flag _o_f _t_h_e  _m_a_t_r_i_x  (_b_u_t
                         _m_a_k_e  _s_u_r_e  _y_o_u  _t_u_r_n _i_t _o_n _a_g_a_i_n _w_h_e_n _y_o_u'_r_e
                         _t_h_r_o_u_g_h).  _F_o_r _e_x_a_m_p_l_e,


                          (_m_r_e_f _m_f (_r_o_w-_i_n_d_e_x _m_f) (_c_o_l-_i_n_d_e_x _m_f))


                         _r_e_t_u_r_n_s _t_h_e  _d_a_t_a  _o_b_j_e_c_t  _d_i_s_p_l_a_y_e_d  _i_n  _t_h_e



          PICASSO Reference Manual                              14-198







                                                                TABLES


                         _u_p_p_e_r _l_e_f_t _c_o_r_n_e_r _o_f _t_h_e _m_a_t_r_i_x.

                         There are two methods which indicate how much
                         data from the table should be used.

                         There are a few  other  utilities  to  handle
                         keeping the data consistent with the fields:

                     mf-sync-data

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         _r_o_w
                         _c_o_l_u_m_n
                         Update the field (if  any)  corresponding  to
                         the  specified  _r_o_w  and  _c_o_l_u_m_n of the data.
                         This function is not needed if mref is used.

                     mf-sync-row

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         _r_o_w
                         Update the fields (if any)  corresponding  to
                         the  specified _r_o_w of data.  This function is
                         not needed if mref is used.

                     mf-sync-col

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         _c_o_l_u_m_n
                         Update the fields (if any)  corresponding  to
                         the  specified _c_o_l_u_m_n of data.  This function
                         is not needed if mref is used.

                     mf-sync-field

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         _f_i_e_l_d
                         Update the field with the data-item (if  any)
                         at the corresponding index into the data.

                     mf-propagate-field

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         _f_i_e_l_d
                         Update the  data-item  corresponding  to  the
                         field  with the current value of the field.

                     mf-propagate

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         Update all fields in the  matrix  with  their
                         corresponding data-items.

                         _____________________________________________

          CURRENT
          INDICES



                         Any number of data-items in a matrix  can  be
                         selected  or made _c_u_r_r_e_n_t. If a _c_u_r_r_e_n_t data-



          PICASSO Reference Manual                              14-199







                                                                TABLES


                         item is currently viewable through a field in
                         the  matrix, that field will be marked with a
                         dark border to indicate that it is displaying
                         a  _c_u_r_r_e_n_t  data-item.  Notice that it is not
                         the field that is marked, but the  data  item
                         (a  particular  data-item  may be displayable
                         through any one  of  several  fields  in  the
                         matrix).   Matrix-fields are set up such that
                         only  one  field  can  receive   input-events
                         (except  exposures) at a time.  The field, if
                         any, that is currently receiving input events
                         may  be  accessed by the current-field method
                         in the matrix.

                         Matrices can be configured to select based on
                         entry,  row, or column.  By default, a matrix
                         selects by entry.  With entry-selection,  any
                         individual  data-item  can be selected.  With
                         row-selection or  column-selection,  a  whole
                         row  or column is selected at a time.  Fields
                         can only be edited in entry-selection mode.

                         A matrix will not allow the  selection  of  a
                         field  which  does  not  have a corresponding
                         data-item.  For  instance,  if  a  matrix  is
                         created  without any data, the matrix will be
                         unselectable.  It is  possible  to  make  the
                         matrix  believe  that  it has data by setting
                         the data-rows and _d_a_t_a-_c_o_l_s of the matrix  to
                         positive values (eg. the number of rows & and
                         columns of the matrix).

                         The following are relevant methods:

                     current-value

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The  data-object  corresponding  to  _c_u_r_r_e_n_t-
                         _i_n_d_i_c_e_s.    Only   applicable  when  current-
                         indices has only one entry and  selection  is
                         :entry.

                     current-values

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         The data-objects  corresponding  to  _c_u_r_r_e_n_t-
                         _i_n_d_i_c_e_s.   Only  applicable when selection is
                         :entry.

                     current-fields

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         Lists of fields  currently  displaying  data-





          PICASSO Reference Manual                              14-200







                                                                TABLES


                         items (may include synths).

                     current-field

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         Field  currently  active.   If  a  field   is
                         receiving input, it is current-field.

                     add-current

                                                            [_F_u_n_c_t_i_o_n]
                         _i_n_d_e_x-_s_p_e_c
                         _m_a_t_r_i_x-_f_i_e_l_d
                         Adds  _i_n_d_e_x-_s_p_e_c   to   current-indices   and
                         selects  the  corresponding  field  (if any).
                         _i_n_d_e_x-_s_p_e_c should be list  of  (row  col)  if
                         selection is :entry, else a number indicating
                         the row or column to be made current.

                     delete-current

                                                            [_F_u_n_c_t_i_o_n]
                         _i_n_d_e_x-_s_p_e_c
                         _m_a_t_r_i_x-_f_i_e_l_d
                         Removes _i_n_d_e_x-_s_p_e_c from  current-indices  and
                         deselects  the  corresponding field (if any).
                         _i_n_d_e_x-_s_p_e_c should be list  of  (row  col)  if
                         selection is :entry, else a number indicating
                         the row or column to be made not current.

                     changed-indices

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _m_a_t_r_i_x-_f_i_e_l_d)
                         A list  of  indices  corresponding  to  data-
                         objects that have been changed via user edit-
                         ing operations.

                         It is often useful for the application to  be
                         notified when the current-indices of a matrix
                         have  been  changed.   Hence,  the  following
                         accessor is useful:

                         In addition  to  being  accessible  from  the
                         level  of programmer, the current-indices are
                         accessible to  the  user  via  the  following
                         handlers:


                 ________________________________________________________________
                  Handler           Default Mapping
                 ________________________________________________________________________________________________________________________________
                  select-unique     (:button-press :detail :left)
                  select-multiple   (:button-press :detail :right)
                  swap-rows         (:button-press :detail :right :state :shift)
                  swap-cols         (:button-press :detail :left :state :shift)
                 ________________________________________________________________

                |
                |
                |
                |
                |
                |
                |





                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |





                                                                                |
                                                                                |
                                                                                |
                                                                                |
                                                                                |
                                                                                |
                                                                                |











          PICASSO Reference Manual                              14-201







                                                                TABLES


                         The two swap handlers allow user  to  dynami-
                         cally rearrange the order in which fields are
                         displayed.  For example, to swap the position
                         of  columns  A and B, simply press the button
                         inside column A or B while holding the  shift
                         button.   A dashed box around the column will
                         be drawn.  Then drag the box over  the  other
                         column  and  release  the  button.   The  two
                         columns will then be switched.

                         _____________________________________________

          SCROLLING



                         Matrices support scrolling through both  rows
                         and columns of data. Functionally,  Scrolling
                         entails nothing more than changing  the  row-
                         index  or  col-index  of  the  matrix and the
                         title  matrices  (if  they  exist).    If   a
                         matrix-field  has  titles,  the  titles  will
                         scroll synchronously with  the  matrix.   For
                         each  direction  (left, right, up, and down),
                         there  are  two  different  types  of  matrix
                         scrolling  functions.   When  the  matrix has
                         uniform   row-types   (:row-elements,   :row-
                         heights  not  specified)  or  uniform column-
                         types (:_c_o_l-_e_l_e_m_e_n_t_s, :_c_o_l-_w_i_d_t_h_s not  speci-
                         fied)  scrolling  can be optimized.  In these
                         cases,  the   scrolling   functions   mf-uni-
                         scroll-up,     mf-uni-scroll-down,    mf-uni-
                         scroll-left,  and   mf-uni-scroll-right   are
                         optimal.  Otherwise, the somewhat slower ver-
                         sions for variable row/column-types  must  be
                         used;  mf-var-scroll-up,  mf-var-scroll-down,
                         mf-var-scroll-left,  and  mf-var-scroll-right
                         must  be  used  (or  the  programmer  can use
                         his/her own scrolling algorithm if he/she  is
                         really   ambitious).   The  "best"  scrolling
                         algorithm is  determined  automatically  when
                         the  matrix-field  is created and cached away
                         in the slots up-func, down-func,  right-func,
                         and  left-func.   The following utilities are
                         useful:

                     mf-scroll-up

                                                               [_M_a_c_r_o]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         _n
                         scroll _m_a_t_r_i_x-_f_i_e_l_d up _n rows. If  there  are
                         less than n rows left to scroll, mf-scroll-up
                         scrolls the maximum number of rows  possible.





          PICASSO Reference Manual                              14-202







                                                                TABLES


                         Uses cached optimal scrolling function.

                     mf-scroll-down

                                                               [_M_a_c_r_o]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         _n
                         scroll _m_a_t_r_i_x-_f_i_e_l_d down _n rows. If there are
                         less than n rows left to scroll, mf-scroll-up
                         scrolls the maximum number of rows  possible.
                         Uses cached optimal scrolling function.

                     mf-scroll-left

                                                               [_M_a_c_r_o]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         _n
                         scroll _m_a_t_r_i_x-_f_i_e_l_d left _n columns. If  there
                         are  less  than n columns left to scroll, mf-
                         scroll-up  scrolls  the  maximum  number   of
                         columns possible.  Uses cached optimal scrol-
                         ling function.

                     mf-scroll-right

                                                               [_M_a_c_r_o]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         _n
                         scroll _m_a_t_r_i_x-_f_i_e_l_d right _n columns. If there
                         are  less  than n columns left to scroll, mf-
                         scroll-up  scrolls  the  maximum  number   of
                         columns possible.  Uses cached optimal scrol-
                         ling function.

                     uniform-rows

                                                            [_A_c_c_e_s_s_o_r]
                         if t, matrix treats all rows  of  fields  the
                         same  way  and optimal scrolling algorithm is
                         cached.

                     uniform-rows

                                                            [_A_c_c_e_s_s_o_r]
                         if t, matrix treats all columns of fields the
                         same  way  and optimal scrolling algorithm is
                         cached.

                     up-func

                                                            [_A_c_c_e_s_s_o_r]
                         the cached  scrolling  function  to  use  for
                         scrolling  upwards.   Default  is  determined
                         once when the matrix is created.

                     down-func

                                                            [_A_c_c_e_s_s_o_r]
                         the cached  scrolling  function  to  use  for
                         scrolling  downwards.   Default is determined
                         once when the matrix is created.

                     left-func

                                                            [_A_c_c_e_s_s_o_r]
                         the cached  scrolling  function  to  use  for
                         scrolling  left.   Default is determined once




          PICASSO Reference Manual                              14-203







                                                                TABLES


                         when the matrix is created.

                     right-func

                                                            [_A_c_c_e_s_s_o_r]
                         the cached  scrolling  function  to  use  for
                         scrolling  right.  Default is determined once
                         when the matrix is created.

                         _____________________________________________

          UTILITIES


                         There are several utilities for matrix-fields
                         that may be of use for some types of applica-
                         tions.  These are as follows:

                     current-fields-by-row

                                                            [_F_u_n_c_t_i_o_n]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         a list of  the  current-indices  (increasing)
                         sorted by row.

                     current-fields-by-col

                                                            [_F_u_n_c_t_i_o_n]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         a list of  the  current-indices  (increasing)
                         sorted by column.

                     uncurrent-fields-by-row

                                                               [_M_a_c_r_o]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         a list of  all  data  indices  that  are  not
                         current (increasing) sorted by row.

                     uncurrent-fields-by-col

                                                               [_M_a_c_r_o]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         a list of  the  data  indices  that  are  not
                         current (increasing) sorted by column.

                     all-fields-by-row

                                                            [_F_u_n_c_t_i_o_n]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         a  list  of  all  data  indices  (increasing)
                         sorted by row.

                     all-fields-by-col

                                                            [_F_u_n_c_t_i_o_n]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         a  list  of  all  data  indices  (increasing)
                         sorted by column.

                     enumerate-row

                                                            [_F_u_n_c_t_i_o_n]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         _r_o_w
                         a list of the data indices for all  items  in
                         the row numbered row.

                     enumerate-col

                                                            [_F_u_n_c_t_i_o_n]
                         _m_a_t_r_i_x-_f_i_e_l_d



          PICASSO Reference Manual                              14-204







                                                                TABLES


                         _c_o_l_u_m_n
                         a list of the data indices for all  items  in
                         the column numbered col.

                     make-row-current

                                                              [_M_e_t_h_o_d]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         _r_o_w
                         make all  data-items  in  the  specified  row
                         current (use only if selection is :entry).

                     make-col-current

                                                              [_M_e_t_h_o_d]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         _r_o_w
                         make all data-items in the  specified  column
                         current (use only if selection is :entry).

                     make-row-uncurrent

                                                              [_M_e_t_h_o_d]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         _r_o_w
                         make all data-items in the specified row  not
                         current (use only if selection is :entry).

                     make-col-uncurrent

                                                              [_M_e_t_h_o_d]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         _r_o_w
                         make all data-items in the  specified  column
                         not   current   (use  only  if  selection  is
                         :entry).

                     insert-row

                                                              [_M_e_t_h_o_d]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         _r_o_w
                         make all data-items in the specified row  not
                         current (use only if selection is :entry).

                     insert-col

                                                              [_M_e_t_h_o_d]
                         _m_a_t_r_i_x-_f_i_e_l_d
                         _r_o_w
                         make all data-items in the  specified  column
                         not   current   (use  only  if  Selection  is
                         :entry).

                         _____________________________________________

          MATRIX-
          FIELD SUM-
          MARY














          PICASSO Reference Manual                              14-205







                                                                TABLES



                             _________________________________________
                              Reader Methods       Setf Methods
                             __________________________________________________________________________________
                              rows
                              cols
                              visible-rows         visible-rows
                              visible-cols         visible-cols
                              inter-row-pad        inter-row-pad
                              inter-col-pad        inter-col-pad
                              grid-lines           grid-lines
                              field-table          field-table
                              row-titles           row-titles
                              col-titles           col-titles
                              row-title-matrix     row-title-matrix
                              col-title-matrix     col-title-matrix
                              vert-scroll-bar-p    vert-scroll-bar-p
                              horiz-scroll-bar-p   horiz-scroll-bar-p
                              data                 data
                              row-index            row-index
                              col-index            col-index
                              data-rows            data-rows
                              data-cols            data-cols
                              selection            selection
                              current-indices      current-indices
                              current-value
                              current-values
                              current-field
                              current-fields
                              changed-indices
                              select-func          select-func
                              unselect-func        unselect-func
                             _________________________________________

                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |
                            |





























                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |





























                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
                                                                     |
































          ____________________________________________________________________________________________________________________________________________________________________________________

          Table-
          Field




                         While matrix-fields are powerful  and  versa-
                         tile,  they  are somewhat lacking in the area
                         of user-interface.  A matrix by  itself  pro-
                         vides  no interface for scrolling, displaying
                         row or column titles, or  performing  any  of
                         the operations discussed in the last section.
                         Therefore, it is rare that a matrix-field  is
                         used alone, without a table-field.

                         The primary purpose  of  the  table-field  is
                         just   to   piece  together  a  matrix-field,
                         scroll-bars,  titles,  and  controls  into  a
                         coherent  user  interface.   The  table-field



          PICASSO Reference Manual                              14-206







                                                                TABLES


                         consists of  a  primary  matrix-field,  zero,
                         one,  or  two titles, one or two scroll-bars,
                         and a "tf-button".  The tf-button is  a  pop-
                         button  which  can  be  used to make standard
                         matrix-operations available to the user  (eg.
                         deselect-matrix and add/delete rows/columns).
                         The operations of the tf-button are customiz-
                         able.


                              ______________________________________
                              |             col-titles           /   <-- tf-button
                              |   __________________________________/
                              | r |                              |  |
                              | o |                              | s|
                              | w |                              | c|
                              | - |                              | r|
                              | t |                              | o|
                              | i |       Primary Matrix         | l|
                              | t |                              | l|
                              | l |                              | -|
                              | e |                              | b|
                              | s |                              | a|
                              |   |                              | r|
                              |___|______________________________|  |
                              |   |                                 |
                              | __|______scroll-bar_________________|



                         _____________________________________________

          CREATION



                     make-table-field

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_t_f-_b_u_t_t_o_n _n_i_l)
                         (tf-items nil)
                         (_t_f-_i_m_a_g_e "_s_w_a_p._b_i_t_m_a_p")
                         (horizontal-scroll-bar-p nil)
                         (_v_e_r_t_i_c_a_l-_s_c_r_o_l_l-_b_a_r-_p _n_i_l)
                         ;; Defaults inherited from matrix-field:
                         (inter-row-pad 3)
                         (inter-col-pad 3)
                         (row-index 0)
                         (col-index 0)
                         (data nil)
                         (rows nil)
                         (cols nil)
                         (data-rows _r_o_w_s)
                         (data-cols _c_o_l_s)
                         (data-array-size (list (num-rows _d_a_t_a) (_n_u_m-_c_o_l_s _d_a_t_a)))



          PICASSO Reference Manual                              14-207







                                                                TABLES


                         (_o_v_e_r_f_l_o_w-_i_n_c_r_e_m_e_n_t _5)
                         (_r_o_w-_e_l_e_m_e_n_t_s _n_i_l)
                         (_c_o_l-_e_l_e_m_e_n_t_s _n_i_l)
                         (_r_o_w-_h_e_i_g_h_t_s _4_0)
                         (_c_o_l-_w_i_d_t_h_s _1_0_0)
                         (_i_n_i_t_i_a_l-_r_o_w_s _n_i_l)
                         (_i_n_i_t_i_a_l-_c_o_l_s _n_i_l)
                         (_f_o_n_t (_d_e_f_a_u_l_t-_f_o_n_t))
                         (_t_i_t_l_e_s _n_i_l)
                         (_c_o_l-_t_i_t_l_e_s _n_i_l)
                         (_r_o_w-_t_i_t_l_e_s _n_i_l)
                         (_d_e_f_a_u_l_t-_t_i_t_l_e_s _t)
                         (_r_o_w-_t_i_t_l_e-_w_i_d_t_h _1_0_0)
                         (_c_o_l-_t_i_t_l_e-_h_e_i_g_h_t _4_0)
                         (_r_o_w-_t_i_t_l_e-_e_l_e_m_e_n_t_s _n_i_l)
                         (_c_o_l-_t_i_t_l_e-_e_l_e_m_e_n_t_s _n_i_l)
                         (_r_o_w-_t_i_t_l_e-_f_o_n_t (_d_e_f_a_u_l_t-_f_o_n_t))
                         (_c_o_l-_t_i_t_l_e-_f_o_n_t (_d_e_f_a_u_l_t-_f_o_n_t))
                         (_s_e_l_f-_a_d_j_u_s_t_a_b_l_e _n_i_l)
                         (_s_e_l_e_c_t_i_o_n :_e_n_t_r_y)
                         (_u_n_i_q_u_e-_s_e_l_e_c_t_i_o_n _n_i_l)
                         (_r_o_w-_t_i_t_l_e-_s_e_l_e_c_t_a_b_l_e _n_i_l)
                         (_c_o_l-_t_i_t_l_e-_s_e_l_e_c_t_a_b_l_e _n_i_l)
                         (_e_d_i_t_a_b_l_e _n_i_l)
                         (_e_d_i_t_a_b_l_e-_r_o_w-_t_i_t_l_e_s _n_i_l)
                         (_e_d_i_t_a_b_l_e-_c_o_l-_t_i_t_l_e_s _n_i_l)
                         (_r_e_t_u_r_n-_f_u_n_c _n_i_l)
                         (_j_u_s_t :_c_e_n_t_e_r)
                         (_h_o_r_i_z-_j_u_s_t :_c_e_n_t_e_r)
                         (_v_e_r_t-_j_u_s_t :_c_e_n_t_e_r)
                         (_f_i_e_l_d-_t_a_b_l_e _n_i_l)
                         ;; Plus keys inherited from collection-widgets
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES



                     tf-button

                                                            [_A_r_g_u_m_e_n_t]
                         Initial  argument  only.   If  non-nil,   the
                         table-field will contain a tf-button if there
                         is room (if there are  column  titles  and  a
                         vertical-scroll-bar)

                     tf-items

                                                            [_A_r_g_u_m_e_n_t]
                         Initial argument only.   The  menu-items  for
                         the  tf-button (see pop-button).  The default
                         items are:

                         deselect
                              set current-indices of primary-matrix to
                              nil.



          PICASSO Reference Manual                              14-208







                                                                TABLES


                         add  insert a row at the selected  row  posi-
                              tion of the primary-matrix.

                         delete
                              delete the current row of  the  primary-
                              matrix.

                         free-nomad
                              free the nomad widget  of  the  primary-
                              matrix.

                     tf-image

                                                            [_A_r_g_u_m_e_n_t]
                         the image to display in the tf-button.

                         _____________________________________________

          ADDITIONAL
          ACCESSORS



                         Most information about the table concerns the
                         primary  matrix  of  the table.  Hence, it is
                         often necessary to extract the primary matrix
                         and  use  the  matrix-field accessors defined
                         above.  However, a few  accessors  are  rede-
                         fined  at  the table-field level for conveni-
                         ence.

                     matrix-field

                                                            [_A_c_c_e_s_s_o_r]
                         the primary-matrix for the table

                     horiz-scroll-bar-p

                                                            [_A_c_c_e_s_s_o_r]
                         if non-nil and  the  primary-matrix  is  more
                         than  one row, the table-field will contain a
                         horizontal scroll-bar.

                     vert-scroll-bar-p

                                                            [_A_c_c_e_s_s_o_r]
                         if non-nil and  the  primary-matrix  is  more
                         than one column, the table-field will contain
                         a vertical scroll-bar.

                     horiz-scroll-bar

                                                            [_A_c_c_e_s_s_o_r]
                         the horizontal scroll-bar for the table.

                     vert-scroll-bar

                                                            [_A_c_c_e_s_s_o_r]
                         the vertical scroll-bar for the table.

                     current-indices

                                                            [_A_c_c_e_s_s_o_r]
                         current-indices of the primary-matrix.

                     current-value

                                                              [_R_e_a_d_e_r]
                         current-value of the primary-matrix

                     select-func

                                                            [_A_c_c_e_s_s_o_r]




          PICASSO Reference Manual                              14-209







                                                                TABLES


                         select-func of the primary matrix.

                     data

                                                            [_A_c_c_e_s_s_o_r]
                         data of the primary matrix.

                     value

                                                            [_A_c_c_e_s_s_o_r]
                         data of the primary matrix.

                     rows

                                                              [_R_e_a_d_e_r]
                         rows of the primary matrix.

                     cols

                                                              [_R_e_a_d_e_r]
                         cols of the primary matrix.

                     visible-rows.

                                                            [_A_c_c_e_s_s_o_r]
                         visible-rows of the primary matrix.

                     visible-cols.

                                                            [_A_c_c_e_s_s_o_r]
                         visible-cols of the primary matrix.

                     row-titles

                                                            [_A_c_c_e_s_s_o_r]
                         row-titles of the primary matrix.

                     col-titles

                                                            [_A_c_c_e_s_s_o_r]
                         col-titles of the primary matrix.

                     row-title-matrix

                                                            [_A_c_c_e_s_s_o_r]
                         row-title-matrix of the primary matrix.

                     col-title-matrix

                                                            [_A_c_c_e_s_s_o_r]
                         col-title-matrix of the primary matrix.

                         Since  a  table-field  creates  its   primary
                         matrix-field  (unless  explicitly passed in),
                         all the matrix-field  instantiation  keywords
                         should  be  passed  to  the table-field.  The
                         table-field passes all of  its  instantiation
                         arguments to the matrix-field.

                         _____________________________________________

          TABLE-
          FIELD SUM-
          MARY

















          PICASSO Reference Manual                              14-210







                                                                TABLES



                               _____________________________________
                                Reader Methods     Setf Methods
                               __________________________________________________________________________
                                matrix-field       matrix-field
                                horiz-scroll-bar   horiz-scroll-bar
                                vert-scroll-bar    vert-scroll-bar
                                current-indices    current-indices
                                current-value      current-value
                                select-func        select-func
                                data               data
                                value              value
                                rows
                                cols
                                visible-rows       visible-rows
                                visible-cols       visible-cols
                                row-titles         row-titles
                                col-titles         col-titles
                                row-title-matrix   row-title-matrix
                                col-title-matrix   col-title-matrix
                               _____________________________________

                              |
                              |
                              |
                              |
                              |
                              |
                              |
                              |
                              |
                              |
                              |
                              |
                              |
                              |
                              |
                              |
                              |
                              |
                              |

















                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |
                                                |

















                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |
                                                                   |




















          ____________________________________________________________________________________________________________________________________________________________________________________

          List-Box



                         A list-box is subclass  of  table-field  with
                         only  one row or one column.  A list-box con-
                         tains only synthetic widgets or gadgets  (see
                         table-field)   and   therefore  creation  and
                         scrolling are pretty quick.  Other than these
                         restrictions,  the  only  differences between
                         list-boxes and table-fields are the  creation
                         options and extra accessor methods.

                         _____________________________________________

          CREATION



                     make-list-box

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_v_a_l_u_e _n_i_l)
                         (items nil)
                         (_p_a_d _0)
                         (orientation :vertical)
                         (_c_o_l-_w_i_d_t_h _n_i_l)
                         (col-height nil)
                         (_m_a_x-_e_l_e_m_e_n_t_s _n_i_l)
                         (max-height nil)
                         (_m_a_x-_w_i_d_t_h _n_i_l)
                         (title nil)



          PICASSO Reference Manual                              14-211







                                                                TABLES


                         ;; Plus keys inherited from table-fields
                         &allow-other-keys

                         _____________________________________________

          ATTRIBUTES


                         Many  of  the  instantiation  arguments   for
                         list-boxes  are  different  than  for  table-
                         fields:

                     value

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _l_i_s_t-_b_o_x)
                         A list of data-objects (string, image, dtext,
                         etc)  that  are to be the values of the list-
                         box.

                     orientation

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _l_i_s_t-_b_o_x)
                         The  orientation  of  the  list-box.   Either
                         :vertical  or  :horizontal,  the  default  is
                         :vertical.

                     items

                                                            [_A_r_g_u_m_e_n_t]
                         A list of data-objects (string, image, dtext,
                         etc)  that  are to be the values of the list-
                         box (same as value).

                     row-height, col-width

                                                            [_A_r_g_u_m_e_n_t]
                         height/width of rows/columns of the  list-box
                         (use  :row-height  if :_o_r_i_e_n_t_a_t_i_o_n is :verti-
                         cal, otherwise use :col-width).

                     pad

                                                              [_R_e_a_d_e_r]
                         (_s_e_l_f _l_i_s_t-_b_o_x)
                         Padding in  pixels  (in  addition  to  inter-
                         row/column  gap)  between  rows  or  columns.
                         Depends on orientation, _d_e_f_a_u_l_t _0.

                     max-elements

                                                            [_A_r_g_u_m_e_n_t]
                         The maximum amount of rows  (if  :_o_r_i_e_n_t_a_t_i_o_n
                         is  :vertical) or columns (if :_o_r_i_e_n_t_a_t_i_o_n is
                         :horizontal) which can  be  viewed  at  once.
                         This  is  necessary  since  the  table cannot
                         "gain" rows or columns dynamically.

                     max-height

                                                            [_A_r_g_u_m_e_n_t]
                         May be specified instead of :_m_a_x-_e_l_e_m_e_n_t_s  to
                         mean  the minimum height necessary to be able
                         to view all rows of the table  at  once.   If
                         the table can conceivable grow to be the full
                         height of the screen,  this  value  could  be
                         specified    as    (height    (root-window)).



          PICASSO Reference Manual                              14-212







                                                                TABLES


                         Incidentally, large values for  :_m_a_x-_e_l_e_m_e_n_t_s
                         or  :_m_a_x-_h_e_i_g_h_t have little noticeable effect
                         on overall performance of the list-box.

                     max-width

                                                            [_A_r_g_u_m_e_n_t]
                         Used instead of :_m_a_x-_h_e_i_g_h_t  if  :_o_r_i_e_n_t_a_t_i_o_n
                         is :horizontal.

                     title

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _l_i_s_t-_b_o_x)
                         Title of the list-box.

                     title-font

                                                            [_A_r_g_u_m_e_n_t]
                         Font of title of list-box.

                         _____________________________________________

          ADDITIONAL
          ACCESSORS




                     font

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _l_i_s_t-_b_o_x)
                         Font of the list-box.

                     row-height

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _l_i_s_t-_b_o_x)
                         Height of the rows of the list-box (use  only
                         if :_o_r_i_e_n_t_a_t_i_o_n is :vertical).

                     col-width

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _l_i_s_t-_b_o_x)
                         Width of the columns  of  the  list-box  (use
                         only if :_o_r_i_e_n_t_a_t_i_o_n is :horizontal).

                         _____________________________________________

          LIST-BOX
          SUMMARY





                                  _______________________________
                                   Reader Methods   Setf Methods
                                  ______________________________________________________________
                                   title            title
                                   value            value
                                   font             font
                                   row-height       row-height
                                   col-width        col-width
                                   pad              pad
                                  _______________________________

                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |
                                 |







                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |
                                                 |







                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |















          PICASSO Reference Manual                              14-213







                                                              GRAPHICS


                                              15
                                           GRAPHICS

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         PICASSO has built-in support for plotting x-y
                         graphs and displaying two dimensional graphic
                         objects.   By  building  in  these   advanced
                         graphics capabilities into PICASSO, a variety
                         of interesting and complex  applications  can
                         be easily written.

                         The types of graphic widgets  implemented  in
                         PICASSO are:

                         o+    Graphic-gadgets  -  display  two  dimen-
                              sional graphic objects.

                         o+    Graphic-browsers - display and allow the
                              user  to  select two dimensional graphic
                              objects.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Graphic
          Gadgets



                         PICASSO graphic-gadgets  are  an  output-only
                         interface abstraction (a gadget) which allows
                         for the display  of  graphic  objects  called
                         _s_h_a_p_e_s.   Currently,  all  structures are two
                         dimensional.   Functionality   includes   the
                         ability  to  set  color,  line-widths,  line-
                         styles, fonts and mapping  functions  of  the
                         displayed graphics, programmer controlled pan
                         and zoom, fast refresh, and basic shape mani-
                         pulating   functions.    First,  the  objects
                         displayed and shaped by graphic gadgets  will
                         be  described;  then  the  functionality  and
                         usage of graphic gadgets will be discussed.

                         In PICASSO, the objects displayed by  graphic
                         gadgets  are  subclasses  of the _s_h_a_p_e class.
                         The next several  sub-sections  describe  the
                         predefined shapes in PICASSO, including:

                             o+  Annotations to display text.
                             o+  Polygons.
                             o+  Boxes.

                         Shapes are designed to be easy to  create  in
                         PICASSO,  and  new  subclasses  can easily be
                         created to specify new object types.




          PICASSO Reference Manual                              15-214







                                                              GRAPHICS


                         After describing shapes, some of the concepts
                         associated with two-dimensional graphics will
                         be reviewed.  In PICASSO, these concepts  are
                         embodied in the _2_d-_m_a_p_p_e_r-_m_i_x_i_n class.  Next,
                         utility functions for creating and manipulat-
                         ing  2d-points,  the fundamental structure on
                         which   2d-graphics   is   based,   will   be
                         presented.  Finally,  the creation and use of
                         graphic gadgets will be discussed.

                         _____________________________________________

          SHAPES



                         The basis for display of graphic objects is a
                         _s_h_a_p_e. Shapes are maintained in a tree struc-
                         ture, the branches of which are subparts of a
                         shape,  and the leaves of which are geometric
                         primitives. This allows one  to  conveniently
                         create,   assemble  and  reuse  instances  of
                         shapes.  For example, a robot could be speci-
                         fied  by  creating an object to represent the
                         arms, legs and body, and then assembled in  a
                         tree as show below:


                                        Robot
                                       /  |  \
                                   arms  body legs
                                   /   \      /   \
                                arm-1 arm-2 leg-1 leg-2



                         It is beyond the scope of  this  document  to
                         describe  the  implementation  of  new  shape
                         types;  this will (eventually) be provided in
                         the form of a _S_h_a_p_e _W_r_i_t_e_r_s _G_u_i_d_e.

                         _____________________________________________

          CREATING A
          SHAPE







                     make-shape

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_n_a_m_e "")
                         (sub-objs nil)
                         (_v_i_e_w_e_r_s _n_i_l)




          PICASSO Reference Manual                              15-215







                                                              GRAPHICS


                         Creates and  returns  a  shape.   _N_a_m_e  is  a
                         string  specifying  the  name  of  the shape,
                         which can be used later  to  search  for  the
                         shape  in  a  hierarchy  in much the same way
                         that files are searched for in  a  directory.
                         _S_u_b-_o_b_j_s  is  a list of shapes that are parts
                         of this shape.  In the robot  example  above,
                         the  _s_u_b-_o_b_j_s  of the arms _s_h_a_p_e _w_o_u_l_d _b_e _t_h_e
                         _l_i_s_t (_a_r_m-_1 _a_r_m-_2).  This value can also be a
                         list  of  s-expressions that, when evaluated,
                         return a shape;  the mechanism is similar  to
                         the  :children _c_l_a_u_s_e _i_n _c_o_l_l_e_c_t_i_o_n _c_r_e_a_t_i_o_n.
                         _S_e_e _t_h_e _e_x_a_m_p_l_e _a_t _t_h_e _e_n_d  _o_f  _t_h_i_s  _s_e_c_t_i_o_n
                         _f_o_r _d_e_t_a_i_l_s.  _V_i_e_w_e_r_s _s_p_e_c_i_f_i_e_s _a _l_i_s_t _o_f _t_h_e
                         _g_r_a_p_h_i_c-_g_a_d_g_e_t_s, _g_r_a_p_h_i_c-_b_r_o_w_s_e_r_s  _a_n_d  _o_t_h_e_r
                         _o_b_j_e_c_t_s _t_h_a_t _w_i_l_l _b_e _d_i_s_p_l_a_y_i_n_g _t_h_i_s _s_h_a_p_e.

                         _____________________________________________

          SHAPE
          ATTRIBUTES






                     name

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         Returns the name of the shape _s_e_l_f,  of  type
                         string.   This value may be setf'_d.  _T_h_e _n_a_m_e
                         _i_s _p_r_o_v_i_d_e_d _t_o  _m_a_k_e  _i_d_e_n_t_i_f_i_c_a_t_i_o_n  _o_f  _t_h_e
                         _s_h_a_p_e _w_i_t_h _a _h_i_e_r_a_r_c_h_y _e_a_s_y, _i_n _m_u_c_h _t_h_e _s_a_m_e
                         _w_a_y _t_h_a_t _f_i_l_e_s _a_r_e _g_i_v_e_n _n_a_m_e_s _i_n _a _f_i_l_e _s_y_s_-
                         _t_e_m.

                     sub-objs

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         Returns a list of shapes that  are  the  sub-
                         parts  of  the  shape _s_e_l_f.  If this value is
                         setf'_d, _a_l_l _t_h_e  _v_i_e_w_e_r_s  _o_f  _t_h_e  _s_h_a_p_e  _a_r_e
                         _n_o_t_i_f_i_e_d  _o_f  _t_h_e  _c_h_a_n_g_e  _a_s  _a _s_i_d_e _e_f_f_e_c_t.
                         _M_o_s_t _v_i_e_w_e_r_s _d_i_s_p_l_a_y _a_l_l _t_h_e  _s_u_b-_o_b_j_s  _o_f  _a
                         _s_h_a_p_e _w_h_e_n _t_h_e_y _d_i_s_p_l_a_y _t_h_e _s_h_a_p_e _i_t_s_e_l_f, _a_n_d
                         _t_r_a_n_s_f_o_r_m _a_l_l _t_h_e _s_u_b-_o_b_j_s _o_f  _a  _s_h_a_p_e  _w_h_e_n
                         _t_h_e _s_h_a_p_e _i_t_s_e_l_f _i_s _t_r_a_n_s_f_o_r_m_e_d.

                     viewers

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_c_r_o_l_l-_b_a_r)

                         Returns a list of viewers of the shape  _s_e_l_f.
                         This  value  may be setf'_d.  _V_i_e_w_e_r_s _a_r_e _u_s_u_-
                         _a_l_l_y  _g_r_a_p_h_i_c-_g_a_d_g_e_t_s  _a_n_d  _g_r_a_p_h_i_c-_b_r_o_w_s_e_r_s,
                         _b_u_t  _c_a_n  _b_e _a_n_y _o_b_j_e_c_t _t_h_a_t _i_s _i_n_t_e_r_e_s_t_e_d _i_n



          PICASSO Reference Manual                              15-216







                                                              GRAPHICS


                         _b_e_i_n_g _n_o_t_i_f_i_e_d _w_h_e_n  _t_h_e  _s_h_a_p_e  _c_h_a_n_g_e_s  _i_t_s
                         _g_e_o_m_e_t_r_y  _o_r  _d_e_f_a_u_l_t  _g_r_a_p_h_i_c _d_i_s_p_l_a_y _a_t_t_r_i_-
                         _b_u_t_e_s.

                         _____________________________________________

          SHAPES
          FUNCTIONS
          AND
          METHODS










                     add-object

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _s_h_a_p_e)
                         (_o_b_j _s_h_a_p_e)

                         Adds the object _o_b_j to the sub-objs  list  of
                         the  shape  _s_e_l_f, and notifies the viewers of
                         the shape of the changes.  This  function  is
                         equivalent to (pushnew obj (sub-objs self)).

                     add-viewer

                                                              [_M_e_t_h_o_d]

                     add-viewer-recursively

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _s_h_a_p_e)
                         _v_i_e_w_e_r

                         _A_d_d-_v_i_e_w_e_r registers _v_i_e_w_e_r  as a  viewer  of
                         the  shape _s_e_l_f.  After this function, _v_i_e_w_e_r
                         will be notified of changes to  the  geometry
                         and  default display attributes of the shape.
                         Add-viewer-recursively registers _v_i_e_w_e_r  with
                         all the ancestors of _s_e_l_f as well.

                     copy

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _s_h_a_p_e)

                         Creates and returns a deep copy of the  shape
                         tree  whose  root is _s_e_l_f.  All the ancestors
                         of _s_e_l_f are copied  by  calling  copy  _r_e_c_u_r_-
                         _s_i_v_e_l_y.

                     delete-object

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _s_h_a_p_e)
                         (_o_b_j _s_h_a_p_e)

                         Deletes the object _o_b_j from the sub-objs list
                         of  the  shape _s_e_l_f, and notifies the viewers
                         of the shape of the changes.   This  function
                         is equivalent to





          PICASSO Reference Manual                              15-217







                                                              GRAPHICS



                          (setf (sub-objs self)
                                (delete objects (sub-objs self)))



                     delete-viewer

                                                              [_M_e_t_h_o_d]

                     delete-viewer-recursively

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _s_h_a_p_e)
                         _v_i_e_w_e_r

                         _D_e_l_e_t_e-_v_i_e_w_e_r unregisters _v_i_e_w_e_r  as a viewer
                         of  the  shape  _s_e_l_f.   After  this function,
                         _v_i_e_w_e_r will no longer be notified of  changes
                         to  the  geometry  and default display attri-
                         butes   of   the    shape.     Delete-viewer-
                         recursively  unregisters  _v_i_e_w_e_r with all the
                         ancestors of _s_e_l_f as well.

                     flatten

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _s_h_a_p_e)

                         Returns a list of  shapes  that  consists  of
                         _s_e_l_f  and all the ancestors of _s_e_l_f.  This is
                         a ``flattened'' version  of  the  shape  tree
                         whose root is _s_e_l_f.

                     find-shape

                                                            [_F_u_n_c_t_i_o_n]
                         _r_o_o_t
                         _p_a_t_h_n_a_m_e

                         Searches a shape tree whose root is _r_o_o_t  for
                         the shape instance whose name is specified by
                         this  list  of  strings  _p_a_t_h_n_a_m_e.   This  is
                         analogous to traversing a directory tree in a
                         file system.  Using the robot example at  the
                         beginning of this section, the expression


                          (find-shape robot '("Robot" "arms" "arm-1"))


                         will return  the  shape  arm-1.   _T_h_e  _s_t_r_i_n_g
                         ``*''  _c_a_n  _b_e _u_s_e_d _a_s _a _w_i_l_d-_c_a_r_d _p_a_t_t_e_r_n _t_o
                         _m_a_t_c_h _a_l_l _s_t_r_i_n_g_s.

                         _____________________________________________

          SHAPES
          SUMMARY








          PICASSO Reference Manual                              15-218







                                                              GRAPHICS



                    ___________________________________________________________
                     Reader Methods   Setf Methods   Misc Methods
                    ______________________________________________________________________________________________________________________
                     name             name           add-object
                     sub-objs         sub-objs       add-viewer
                     viewers          viewers        add-viewer-recursively
                                                     copy
                                                     delete-object
                                                     delete-viewer
                                                     delete-viewer-recursively
                                                     flatten
                                                     find-shape
                    ___________________________________________________________

                   |
                   |
                   |
                   |
                   |
                   |
                   |
                   |
                   |
                   |
                   |
                   |










                                   |
                                   |
                                   |
                                   |
                                   |
                                   |
                                   |
                                   |
                                   |
                                   |
                                   |
                                   |










                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |
                                                  |










                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |














                         _____________________________________________

          2D-SHAPES



                         2d-shapes  are  a  subclass  of  shapes  that
                         implement   two  dimensional  graphics.   2d-
                         shapes are described in a device  independent
                         coordinate  system  called _w_o_r_l_d _c_o_o_r_d_i_n_a_t_e_s.
                         This coordinate system is a  standard  carte-
                         sian  system, with the _x axis running left to
                         right, and the _y axis running bottom to  top.
                         Unlike  the  coordinate systems found in most
                         windowing systems, world coordinates  can  be
                         fractional.

                         _____________________________________________

          CREATING A
          2D-SHAPE







                     make-2d-shape

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_c_t_r_l-_p_t_s _n_i_l)
                         ;; Defaults inherited from shape:
                         (name "")
                         (sub-objs nil)
                         (viewers nil)
                         Creates and returns a 2d-shape.  _C_t_r_l-_p_t_s  is
                         a  list of 2d-points which are used for edit-
                         ing.  For convenience, a list (x  y)  _c_a_n  _b_e
                         _p_a_s_s_e_d _i_n_s_t_e_a_d _o_f _a _2_d-_p_o_i_n_t, _d_i_s_c_u_s_s_e_d _l_a_t_e_r
                         _i_n _t_h_i_s _c_h_a_p_t_e_r.  _E_a_c_h _s_u_b_c_l_a_s_s _a_s_s_o_c_i_a_t_e_s _a_n
                         _a_p_p_r_o_p_r_i_a_t_e _m_e_a_n_i_n_g _t_o _t_h_i_s _s_l_o_t, _b_u_t _e_d_i_t_o_r_s



          PICASSO Reference Manual                              15-219







                                                              GRAPHICS


                         _c_a_n _d_e_p_e_n_d _o_n _i_t_s _e_x_i_s_t_e_n_c_e.

                         _____________________________________________

          2D-SHAPE
          METHODS




                     2d-rotate

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _s_h_a_p_e)
                         _t_h_e_t_a
                         _o_x
                         _o_y

                         Rotates the 2d-shape _s_e_l_f by an  angle  _t_h_e_t_a
                         about an origin whose coordinates are _o_x, _o_y.
                         All sub-objects of _s_e_l_f are rotated as well.

                     2d-scale

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _s_h_a_p_e)
                         _s_f
                         _o_x
                         _o_y

                         Scales the 2d-shape _s_e_l_f by a factor _s_f about
                         an  origin whose coordinates are _o_x, _o_y.  All
                         sub-objects of _s_e_l_f are scaled as well.

                     2d-translate

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _s_h_a_p_e)
                         _t_x
                         _t_y

                         Translates the 2d-shape _s_e_l_f by an amount  _t_x
                         in  the  direction of the positive x axis and
                         by an amount _t_y in the direction of the posi-
                         tive  y  axis.   All  sub-objects of _s_e_l_f are
                         translated as well.

                         _____________________________________________

          SEGMENTS
          AND ANNO-
          TATIONS





                         Segments are  a  subclass  of  2d-shape  that
                         implement   line-segment-oriented   graphics.
                         Annotations are a subclass of  2d-shape  that
                         implement  character oriented graphics.  Both
                         classes provide  default  graphic  properties
                         appropriate  for  the  type  of graphics they
                         implement.   For  example,  both  provide   a
                         default  for the color to display the graphic
                         in, and segments provide a default line-width
                         and  default line-style to use in drawing the
                         graphic, whereas annotations provide  a  list



          PICASSO Reference Manual                              15-220







                                                              GRAPHICS


                         of fonts to use.

                         Annotations are guaranteed to fit in a box on
                         the  screen  that is specified in the defini-
                         tion of the annotation, and the viewer of the
                         annotation  will pick the largest font from a
                         font list that fits with that box.

                         _____________________________________________

          CREATING
          SEGMENTS
          AND ANNO-
          TATIONS









                     make-segment

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_c_o_l_o_r "_w_h_i_t_e")
                         (line-width 0)
                         (_l_i_n_e-_s_t_y_l_e :_s_o_l_i_d)
                         ;; Defaults inherited from 2d-shape:
                         (ctrl-pts nil)
                         ;; Defaults inherited from shape:
                         (name "")
                         (sub-objs nil)
                         (viewers nil)
                         Creates and returns a segment.  _C_o_l_o_r  speci-
                         fies  the  default color of the line segment,
                         and can be either a string giving the name of
                         a  color  or  an instance of the _c_o_l_o_r class.
                         _L_i_n_e-_w_i_d_t_h is the default line-width  of  the
                         line segment.  The special value 0 is used to
                         indicate the line is ``thin'', i.e., 1  pixel
                         wide.   _L_i_n_e-_s_t_y_l_e  is the default line-style
                         of the line segment, and should be one of the
                         keywords :solid, :dash _o_r :_d_o_u_b_l_e-_d_a_s_h.

                     make-annotation

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_c_o_l_o_r "_w_h_i_t_e")
                         (fonts <_s_e_e _b_e_l_o_w>)
                         (text "")
                         (_l_o_w_e_r-_l_e_f_t (_m_a_k_e-_2_d-_p_o_i_n_t :_x _0._0 :_y _0._0))
                         (width 1.0)
                         (_h_e_i_g_h_t _1._0)
                         (just :LC)
                         ;; Defaults inherited from 2d-shape:
                         (_c_t_r_l-_p_t_s _n_i_l)
                         ;; Defaults inherited from shape:
                         (name "")
                         (sub-objs nil)
                         (viewers nil)



          PICASSO Reference Manual                              15-221







                                                              GRAPHICS


                         Creates and  returns  an  annotation.   _C_o_l_o_r
                         specifies  the  default  color of the annota-
                         tion, and can be either a string  giving  the
                         name  of  a color or an instance of the _c_o_l_o_r
                         class.  _F_o_n_t_s specifies a list of fonts to be
                         used  to display the annotation, which should
                         be a list of instances of the _f_o_n_t class.  In
                         displaying  the  annotation, the largest font
                         that will fit into the box specified by _w_i_d_t_h
                         and  _h_e_i_g_h_t  will be used.  The default value
                         for this is a list of  helvetica  fonts  with
                         point  sizes  34,20,14,10,8  and the ``nil2''
                         font.  The fonts should be  sorted  the  most
                         preferable  font (usually the largest) first.
                         _T_e_x_t  specifies  the   string   to   display.
                         _L_o_w_e_r-_l_e_f_t  is  a 2d-point that specifies the
                         position of  the  lower-left  corner  of  the
                         annotation.  _J_u_s_t specifies the justification
                         of the annotation within the box specified by
                         _l_o_w_e_r-_l_e_f_t,  _w_i_d_t_h  and _h_e_i_g_h_t.  It should be
                         one of the keywords :LC, :LB, :LT, :CC,  :CB,
                         :CT,  :RC,  :RB _o_r :_R_T, which are interpreted
                         as follows:


                  ______________________________________________________________
                   Keywords   Horizontal Justification   Vertical Justification
                  ____________________________________________________________________________________________________________________________
                   :LB        Left                       Bottom
                   :LC        Left                       Centered
                   :LT        Left                       Top
                   :CB        Centered                   Bottom
                   :CC        Centered                   Centered
                   :CT        Centered                   Top
                   :RB        Right                      Bottom
                   :RC        Right                      Centered
                   :RT        Right                      Top
                  ______________________________________________________________

                 |
                 |
                 |
                 |
                 |
                 |
                 |
                 |
                 |
                 |
                 |
                 |










                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |
                           |










                                                      |
                                                      |
                                                      |
                                                      |
                                                      |
                                                      |
                                                      |
                                                      |
                                                      |
                                                      |
                                                      |
                                                      |










                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |
                                                                               |














                         _____________________________________________

          ANNOTATION
          ATTRIBUTES




                     color

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _a_n_n_o_t_a_t_i_o_n)
                         Returns the default color of  the  annotation
                         _s_e_l_f, which may be either a string giving the
                         name of a color or an instance of  the  _c_o_l_o_r
                         class.    This  value  may  be  setf'_d.   _A_l_l
                         _v_i_e_w_e_r_s _o_f  _s_e_l_f  _w_i_l_l  _b_e  _n_o_t_i_f_i_e_d  _o_f  _t_h_e



          PICASSO Reference Manual                              15-222







                                                              GRAPHICS


                         _c_h_a_n_g_e  _a_n_d  _c_a_n _u_p_d_a_t_e _t_h_e_i_r _d_i_s_p_l_a_y _a_c_c_o_r_d_-
                         _i_n_g_l_y.

                     fonts

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _a_n_n_o_t_a_t_i_o_n)
                         Returns the default font list of the  annota-
                         tion  _s_e_l_f,  which  is a list of instances of
                         the _f_o_n_t class.  This value  may  be  setf'_d,
                         _b_u_t  _t_h_e  _n_e_w  _l_i_s_t _o_f _f_o_n_t_s _s_h_o_u_l_d _b_e _s_o_r_t_e_d
                         _w_i_t_h _t_h_e _m_o_s_t _p_r_e_f_e_r_a_b_l_e  _f_o_n_t  (_u_s_u_a_l_l_y  _t_h_e
                         _l_a_r_g_e_s_t)  _f_i_r_s_t.  _A_l_l _v_i_e_w_e_r_s _o_f _s_e_l_f _w_i_l_l _b_e
                         _n_o_t_i_f_i_e_d _o_f _t_h_e _c_h_a_n_g_e _a_n_d _c_a_n  _u_p_d_a_t_e  _t_h_e_i_r
                         _d_i_s_p_l_a_y _a_c_c_o_r_d_i_n_g_l_y.

                     text

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _a_n_n_o_t_a_t_i_o_n)
                         Returns the string displayed by  the  annota-
                         tion  _s_e_l_f.   This  value may be setf'_d.  _A_l_l
                         _v_i_e_w_e_r_s _o_f  _s_e_l_f  _w_i_l_l  _b_e  _n_o_t_i_f_i_e_d  _o_f  _t_h_e
                         _c_h_a_n_g_e  _a_n_d  _c_a_n _u_p_d_a_t_e _t_h_e_i_r _d_i_s_p_l_a_y _a_c_c_o_r_d_-
                         _i_n_g_l_y.

                     lower-left

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _a_n_n_o_t_a_t_i_o_n)
                         Returns the 2d-point that specifies the posi-
                         tion  of the lower-left corner of the annota-
                         tion.  This value may be setf'_d.   _t_h_e  _v_a_l_u_e
                         _i_t  _i_s  _c_h_a_n_g_e_d  _t_o  _s_h_o_u_l_d  _b_e _c_r_e_a_t_e_d _u_s_i_n_g
                         _m_a_k_e-_2_d-_p_o_i_n_t :_x _x :_y  _y).   All  viewers  of
                         _s_e_l_f  will  be notified of the change and can
                         update their display accordingly.

                     width

                                                            [_A_c_c_e_s_s_o_r]

                     height

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _a_n_n_o_t_a_t_i_o_n)
                         Returns the width and height of  the  annota-
                         tion  in world coordinates.  This defines the
                         size of  the  box  the  annotation  must  fit
                         within  when displayed on the screen.  Either
                         of these values may be setf'_d.   _A_l_l  _v_i_e_w_e_r_s
                         _o_f  _s_e_l_f  _w_i_l_l  _b_e _n_o_t_i_f_i_e_d _o_f _t_h_e _c_h_a_n_g_e _a_n_d
                         _c_a_n _u_p_d_a_t_e _t_h_e_i_r _d_i_s_p_l_a_y _a_c_c_o_r_d_i_n_g_l_y.

                     just

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _a_n_n_o_t_a_t_i_o_n)
                         Returns the type of justification used by the
                         annotation  _s_e_l_f.   This value may be setf'_d.
                         _T_h_e _n_e_w _v_a_l_u_e _s_h_o_u_l_d _b_e _o_n_e _o_f  _t_h_e  _k_e_y_w_o_r_d_s
                         :_L_C,  :_L_B,  :_L_T,  :_C_C,  :_C_B, :_C_T, :_R_C, :_R_B or
                         :RT.  _A_l_l _v_i_e_w_e_r_s _o_f _s_e_l_f _w_i_l_l _b_e _n_o_t_i_f_i_e_d _o_f
                         _t_h_e  _c_h_a_n_g_e  _a_n_d  _c_a_n  _u_p_d_a_t_e  _t_h_e_i_r  _d_i_s_p_l_a_y



          PICASSO Reference Manual                              15-223







                                                              GRAPHICS


                         _a_c_c_o_r_d_i_n_g_l_y.

                         _____________________________________________

          SEGMENT
          ATTRIBUTES




                     color

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_e_g_m_e_n_t)
                         Returns the  default  color  of  the  segment
                         _s_e_l_f, which may be either a string giving the
                         name of a color or an instance of  the  _c_o_l_o_r
                         class.    This  value  may  be  setf'_d.   _A_l_l
                         _v_i_e_w_e_r_s _o_f  _s_e_l_f  _w_i_l_l  _b_e  _n_o_t_i_f_i_e_d  _o_f  _t_h_e
                         _c_h_a_n_g_e  _a_n_d  _c_a_n _u_p_d_a_t_e _t_h_e_i_r _d_i_s_p_l_a_y _a_c_c_o_r_d_-
                         _i_n_g_l_y.

                     line-width

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_e_g_m_e_n_t)
                         Returns the default line-width of the segment
                         _s_e_l_f.  This value may be setf'_d.  _A_l_l _v_i_e_w_e_r_s
                         _o_f _s_e_l_f _w_i_l_l _b_e _n_o_t_i_f_i_e_d _o_f  _t_h_e  _c_h_a_n_g_e  _a_n_d
                         _c_a_n _u_p_d_a_t_e _t_h_e_i_r _d_i_s_p_l_a_y _a_c_c_o_r_d_i_n_g_l_y.

                     line-style

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _s_e_g_m_e_n_t)
                         Returns the default line-style of the segment
                         _s_e_l_f,  This  value  may  be  setf'_d.  _T_h_e _n_e_w
                         _v_a_l_u_e _s_h_o_u_l_d _b_e _o_n_e _o_f _t_h_e  _k_e_y_w_o_r_d_s  :_s_o_l_i_d,
                         :_d_a_s_h  or  :double-dash.  _A_l_l _v_i_e_w_e_r_s _o_f _s_e_l_f
                         _w_i_l_l _b_e _n_o_t_i_f_i_e_d _o_f _t_h_e _c_h_a_n_g_e _a_n_d _c_a_n _u_p_d_a_t_e
                         _t_h_e_i_r _d_i_s_p_l_a_y _a_c_c_o_r_d_i_n_g_l_y.

                         _____________________________________________

          POLYGONS



                         Polygons are a subclass of segments that have
                         a  list of points that are the control points
                         of the polygon.   They  can  be  ``open''  or
                         ``closed''  - closed polygons implicitly con-
                         tain the last vertex as the start vertex.

                         Polygons also have a ``hook  point'',  a  2d-
                         point  stored  in  the  hook-pt  slot,  which
                         defaults to a point whose  world  coordinates
                         are  0.0,  0.0.   The hook point is used as a
                         default anchor point for various graphic edi-
                         tors,  e.g.,  for the origin for rotation and
                         scaling  operations.   The  ctrl-pts   of   a
                         polygon  is a list of 2d-points (created with
                         make-2d-point) that are the vertices  of  the




          PICASSO Reference Manual                              15-224







                                                              GRAPHICS


                         polygon.

                         _____________________________________________

          CREATING
          POLYGONS







                     make-polygon

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_c_l_o_s_e_d _n_i_l)
                         (hook-pt (make-2d-point :x 0 :y 0))
                         ;; Defaults inherited from segment:
                         (_c_o_l_o_r "_w_h_i_t_e")
                         (line-width 0)
                         (_l_i_n_e-_s_t_y_l_e :_s_o_l_i_d)
                         ;; Defaults inherited from 2d-shape:
                         (ctrl-pts nil)
                         ;; Defaults inherited from shape:
                         (name "")
                         (sub-objs nil)
                         (viewers nil)

                         _____________________________________________

          POLYGON
          ATTRIBUTES




                     closed

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_o_l_y_g_o_n)
                         Returns t _i_f _t_h_e _p_o_l_y_g_o_n _i_s _i_m_p_l_i_c_i_t_l_y _c_l_o_s_e_d
                         (_i._e.,  _t_h_e  _l_a_s_t  _p_o_i_n_t  _i_s  _t_h_e _s_a_m_e _a_s _t_h_e
                         _f_i_r_s_t), _n_i_l otherwise.   This  value  may  be
                         setf'_d, _c_a_u_s_i_n_g _t_h_e _v_i_e_w_e_r_s _o_f _t_h_e _p_o_l_y_g_o_n _t_o
                         _u_p_d_a_t_e _t_h_e_i_r _d_i_s_p_l_a_y, _i_f _n_e_c_e_s_s_a_r_y.

                     hook-pt

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_o_l_y_g_o_n)
                         Returns the hook-pt of  the  polygon,  a  2d-
                         point indicate the user-defined origin of the
                         polygon.  This value may be  setf'_d,  _c_a_u_s_i_n_g
                         _t_h_e  _v_i_e_w_e_r_s  _o_f  _t_h_e _p_o_l_y_g_o_n _t_o _u_p_d_a_t_e _t_h_e_i_r
                         _d_i_s_p_l_a_y, _i_f _n_e_c_e_s_s_a_r_y.

                         _____________________________________________

          BOXES



                         Boxes are a subclass of polygons that have  a
                         width  and a height and are constrained to be
                         orthogonal.  The hook-pt of the box is inter-




          PICASSO Reference Manual                              15-225







                                                              GRAPHICS


                         preted as the lower-left corner of the box.

                         _____________________________________________

          CREATING
          BOXES







                     make-box

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_w_i_d_t_h _1._0)
                         (height 1.0)
                         ;; Defaults inherited from polygon:
                         (_c_l_o_s_e_d _t)
                         (hook-pt (make-2d-point :x 0 :y 0))
                         ;; Defaults inherited from segment:
                         (_c_o_l_o_r "_w_h_i_t_e")
                         (line-width 0)
                         (_l_i_n_e-_s_t_y_l_e :_s_o_l_i_d)
                         ;; Defaults inherited from 2d-shape:
                         (ctrl-pts nil)
                         ;; Defaults inherited from shape:
                         (name "")
                         (sub-objs nil)
                         (viewers nil)

                         _____________________________________________

          BOX ATTRI-
          BUTES




                     width

                                                            [_A_c_c_e_s_s_o_r]

                     height

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _b_o_x)
                         Returns width and height  of  the  box  _s_e_l_f.
                         These  values  may  be  setf'_d,  _c_a_u_s_i_n_g  _t_h_e
                         _v_i_e_w_e_r_s _o_f _t_h_e _b_o_x _t_o _u_p_d_a_t_e  _t_h_e_i_r  _d_i_s_p_l_a_y,
                         _i_f _n_e_c_e_s_s_a_r_y.

                         _____________________________________________

          2D MAPPER
          MIXINS




                         The 2d-mapper-mixin class is defined to  han-
                         dle the mapping and clipping of world coordi-
                         nates into X window device  coordinates.   It
                         is  an  abstract  class  - it is not intended
                         that any 2d-mapper-mixins instances  will  be
                         created.   Routines  are provided to map from
                         world coordinates to device coordinates, from
                         device  coordinates to world coordinates, and



          PICASSO Reference Manual                              15-226







                                                              GRAPHICS


                         to clip polygons and  line  segments  against
                         the window of the mapper.

                         The mapping from world coordinates to  device
                         coordinates is accomplished by specifying the
                         width and height of the  mapper,  and  giving
                         the  world  coordinates of the lower left and
                         upper right corners of the device.  One other
                         parameter  that  must be specified is whether
                         the  mapping  is  isotropic  or  anisotropic.
                         Isotropic  mappings  preserve the geometry of
                         the displayed objects, so a square comes  out
                         square,  whereas  anisotropic  mappings don't
                         preserve the proportions.  In other words, in
                         isotropic  mappings,  the size of one unit on
                         the x axis is the same as  the  size  of  one
                         unit  of the y axis, regardless of the aspect
                         ratio of the display device.

                         _____________________________________________

          2D-MAPPER
          ATTRIBUTES




                     mapping

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _2_d-_m_a_p_p_e_r-_m_i_x_i_n)
                         Type of mapping, either :isotropic _o_r :_a_n_i_s_o_-
                         _t_r_o_p_i_c, default :isotropic.

                     height

                                                            [_A_c_c_e_s_s_o_r]

                     width

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _2_d-_m_a_p_p_e_r-_m_i_x_i_n)
                         Returns the  width  and  height  of  the  2d-
                         mapper-mixin _s_e_l_f. These represent the dimen-
                         sions of the output  device  that  mapper  is
                         mixed  into.   For  example,  graphic-gadgets
                         inherit from the gadget  class  and  the  2d-
                         mapper-mixin  class,  so  width and height in
                         this case are interpreted as the size of  the
                         window.  Classes that use the 2d-mapper-mixin
                         class  should  call  the  recache-map  _m_e_t_h_o_d
                         _w_h_e_n_e_v_e_r _t_h_e_s_e _v_a_l_u_e _c_h_a_n_g_e.

                     xmin

                                                            [_A_c_c_e_s_s_o_r]

                     xmax

                                                            [_A_c_c_e_s_s_o_r]

                     ymin

                                                            [_A_c_c_e_s_s_o_r]

                     ymax

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _2_d-_m_a_p_p_e_r-_m_i_x_i_n)
                         Returns the world coordinates of  the  lower-



          PICASSO Reference Manual                              15-227







                                                              GRAPHICS


                         left  and  upper-right  corners of the mapper
                         _s_e_l_f.  In other words, the point (_x_m_i_n, _y_m_i_n)
                         will map to the lower-left corner of the dev-
                         ice, and the point (_x_m_a_x, _y_m_a_x) will  map  to
                         the  upper-right corner of the device.  These
                         values may be setf'_d _i_n_d_i_v_i_d_u_a_l_l_y,  _o_r  _a_s  _a
                         _g_r_o_u_p _v_i_a _t_h_e _s_e_t-_l_o_w_e_r-_l_e_f_t, set-upper-right
                         _a_n_d _s_e_t-_w_o_r_l_d methods, to implement zoom  in,
                         zoom out, pan, etc.

                         _____________________________________________

          MAPPER
          METHODS




                     map-dc-to-wc

                                                               [_M_a_c_r_o]
                         _s_e_l_f
                         _d_x
                         _d_y
                         _w_x
                         _w_y
                         This macro destructively sets _w_x, _w_y  to  the
                         world  coordinates  that represent the device
                         coordinates _d_x, _d_y in the mapper _s_e_l_f.   This
                         macro is used, for example, to find the world
                         coordinates of a mouse hit on the mapper.

                     map-wc-to-dc

                                                               [_M_a_c_r_o]
                         _s_e_l_f
                         _w_x
                         _w_y
                         _d_x
                         _d_y
                         This macro destructively sets _d_x, _d_y  to  the
                         device  coordinates  that represent the world
                         coordinates _w_x, _w_y in the mapper _s_e_l_f.   This
                         macro  is used, for example, to find the dev-
                         ice coordinates of a point in  world  coordi-
                         nates.

                     pan

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _2_d-_m_a_p_p_e_r-_m_i_x_i_n)
                         _x-_f_a_c_t_o_r
                         _y-_f_a_c_t_o_r
                         This method modifies the world coordinates of
                         the  mapper _s_e_l_f such that the view presented
                         on the screen  is  ``panned''  by  an  amount
                         determined  by  _x-_f_a_c_t_o_r  and  _y-_f_a_c_t_o_r.  The
                         values are interpreted  as  follows.   An  _x-
                         _f_a_c_t_o_r  of  1.0 pans to the right by one-half
                         the current size of the screen, i.e., a point
                         that  was  on  the  right  edge of the screen
                         would now appear in the middle of the screen.



          PICASSO Reference Manual                              15-228







                                                              GRAPHICS


                         Similarly,  a  _y-_f_a_c_t_o_r of 1.0 pans down one-
                         half screen.  Negative values can be used  to
                         pan up or left.

                     ppu

                                                            [_F_u_n_c_t_i_o_n]
                         _m_a_p_p_e_r
                         The function returns  the  number  of  pixels
                         used  to  represent one unit of world coordi-
                         nate  space  (the  number  of  ``pixels   per
                         unit'').

                     recache-map

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _2_d-_m_a_p_p_e_r-_m_i_x_i_n)
                         This method recalculates the internal parame-
                         ters  used  in mapping from world coordinates
                         to device coordinates in the mapper _s_e_l_f.  It
                         is  called  automatically  whenever the world
                         coordinates of _s_e_l_f change.  Subclasses  that
                         inherit  from the 2d-mapper class should call
                         this method whenever either of the  following
                         occur:

                             o+ The size of the mapper object _s_e_l_f changes.
                             o+ The world coordinates slots of _s_e_l_f are setf'_d _v_i_a _s_l_o_t-_v_a_l_u_e.

                         Note that slots referred  to  in  the  latter
                         case  include  the  _m_a_p_p_i_n_g, _x_m_i_n, _x_m_a_x, _y_m_i_n
                         and _y_m_a_x slots of _s_e_l_f.

                         Subclasses  will  also  typically  add  func-
                         tionality  to  this  method  to  redraw their
                         screen and update any  internal  data  struc-
                         tures that depend on the world coordinates to
                         device coordinates mapping.  Since  the  side
                         effects  of  this  method  are used to do the
                         actual world coordinate to device  coordinate
                         mapping,  new  methods should first execute a
                         call-next-method before attempting  any  such
                         mappings.

                     set-lower-left

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _2_d-_m_a_p_p_e_r-_m_i_x_i_n)
                         _x_m_i_n
                         _y_m_i_n
                         Set the lower left corner of the mapper.

                     set-upper-right

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _2_d-_m_a_p_p_e_r-_m_i_x_i_n)
                         _x_m_a_x
                         _y_m_a_x
                         _S_e_t _t_h_e _u_p_p_e_r _r_i_g_h_t _c_o_r_n_e_r _o_f _t_h_e _m_a_p_p_e_r.




          PICASSO Reference Manual                              15-229







                                                              GRAPHICS


                     set-world

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _2_d-_m_a_p_p_e_r-_m_i_x_i_n)
                         _x_m_i_n
                         _y_m_i_n
                         _x_m_a_x
                         _y_m_a_x
                         These methods  change  the  world  coordinate
                         system of _s_e_l_f as specified.

                     zoom-factor

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _2_d-_m_a_p_p_e_r-_m_i_x_i_n)
                         _f_a_c_t_o_r
                         This method modifies the world coordinates of
                         the  mapper _s_e_l_f such that the view presented
                         on the screen is ``zoomed'' in or out  by  an
                         amount  determined  by  _f_a_c_t_o_r.  The value of
                         _f_a_c_t_o_r is interpreted as follows.   A  _f_a_c_t_o_r
                         of  2.0 ``zooms in'' around the middle of the
                         screen, ie, objects  in  the  middle  of  the
                         screen  will  be drawn twice as big after the
                         call.  _F_a_c_t_o_rs less than 1.0 cause the screen
                         to ``zoom out''.  It is an error to specify a
                         _f_a_c_t_o_r less than 0.

                         _____________________________________________

          2D-POINT
          FUNCTIONS



                         _2_d-_p_o_i_n_t_s are the fundamental structure  used
                         by  the  PICASSO graphic functions.  They are
                         defined  using  the  Common  Lisp   defstruct
                         facility,  and  have two attributes: x and y.
                         2d-points are often used as  vectors.   Since
                         their  use is so widespread, explicit alloca-
                         tion and freeing functions have been created.

                         _____________________________________________

          ALLOCAT-
          ING, FREE-
          ING AND
          COPYING
          2D-POINTS






                         2d-points can be created using the  following
                         function:

                     make-2d-point

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_x _0)
                         (y 0)
                         This function creates  and  returns  a  fresh
                         2d-point  with coordinates _x and _y.  Although
                         this function exists, the following  function
                         is usually used instead:

                     alloc-2d

                                                            [_F_u_n_c_t_i_o_n]
                         _x



          PICASSO Reference Manual                              15-230







                                                              GRAPHICS


                         _y
                         This function also returns a  fresh  2d-point
                         with  coordinates  _x  and _y, but the returned
                         2d-point is obtained from a free list of  2d-
                         points.   A  new  2d-point  is  created using
                         make-2d-point _i_f _t_h_e _f_r_e_e-_l_i_s_t _i_s _e_m_p_t_y.  _T_h_e
                         _r_e_t_u_r_n  _v_a_l_u_e  _m_a_y _b_e _p_l_a_c_e_d _o_n _t_h_e _f_r_e_e _l_i_s_t
                         _u_s_i_n_g _t_h_e _m_a_c_r_o:

                     free-2d

                                                               [_M_a_c_r_o]
                         _2_d-_p_o_i_n_t
                         This function adds _2_d-_p_o_i_n_t to the free  list
                         of 2d-points for recycling.

                     2dv-copy

                                                               [_M_a_c_r_o]
                         _d_s_t
                         _s_r_c
                         This macro destructively sets  the  x  and  y
                         values  of  the  2d-point  _d_s_t to the x and y
                         values of the 2d-point _s_r_c.

                     copy-2d

                                                               [_M_a_c_r_o]
                         _v
                         _x
                         _y
                         This macro destructively sets  the  x  and  y
                         values  of the 2d-point _v to _x and _y, respec-
                         tively.

                     duplicate-2d

                                                            [_F_u_n_c_t_i_o_n]
                         _v
                         This function  returns  a  freshly  allocated
                         2d-point whose x and y values are the same as
                         those of the 2d-point _v.

                         _____________________________________________

          2D-VECTOR
          UTILITY
          FUNCTIONS




                         2d-points are often used  as  vectors.   This
                         section describes the basic mathematical vec-
                         tor functions available on all 2d-points.

                     2dv+!

                                                            [_F_u_n_c_t_i_o_n]
                         _v_1
                         _v_2
                         This function destructively sets the x and  y
                         components  of the 2d-vector _v_1 to the sum of
                         the x and y components of the  2d-vectors  _v_1
                         and _v_2.

                     2dv+

                                                            [_F_u_n_c_t_i_o_n]
                         _v_1



          PICASSO Reference Manual                              15-231







                                                              GRAPHICS


                         _v_2
                         This is the non-destructive version of 2dv+!.
                         _I_t  _r_e_t_u_r_n_s  _a  _2_d-_p_o_i_n_t  _w_h_o_s_e  _x _a_n_d _y _c_o_m_-
                         _p_o_n_e_n_t_s _a_r_e _t_h_e _s_u_m _o_f _t_h_e _x _a_n_d _y _c_o_m_p_o_n_e_n_t_s
                         _o_f _t_h_e _2_d-_v_e_c_t_o_r_s _v_1 _a_n_d _v_2.

                     2dv-!

                                                            [_F_u_n_c_t_i_o_n]
                         _v_1
                         _v_2
                         This function destructively sets the x and  y
                         components of the 2d-vector _v_1 to the differ-
                         ence of the x and y  components  of  the  2d-
                         vectors _v_1 and _v_2.

                     2dv-

                                                            [_F_u_n_c_t_i_o_n]
                         _v_1
                         _v_2
                         This is the non-destructive version of 2dv-!.
                         _I_t  _r_e_t_u_r_n_s  _a  _2_d-_p_o_i_n_t  _w_h_o_s_e  _x _a_n_d _y _c_o_m_-
                         _p_o_n_e_n_t_s _a_r_e _t_h_e _d_i_f_f_e_r_e_n_c_e _o_f  _t_h_e  _x  _a_n_d  _y
                         _c_o_m_p_o_n_e_n_t_s _o_f _t_h_e _2_d-_v_e_c_t_o_r_s _v_1 _a_n_d _v_2.

                     2dv-dot-product

                                                            [_F_u_n_c_t_i_o_n]
                         _v_1
                         _v_2
                         This function returns the dot-product of  the
                         2d-vectors _v_1 and _v_2.

                     2dv-length

                                                            [_F_u_n_c_t_i_o_n]
                         _v_1
                         This function returns a floating point  value
                         that is the length of the 2d-vector _v_1.

                     2dv-negate!

                                                            [_F_u_n_c_t_i_o_n]
                         _v_1
                         This function destructively negates  the  2d-
                         vector  _v_1.   That is, the x and y components
                         of this vector are set  to  the  negative  of
                         their current values.

                     2dv-negate

                                                            [_F_u_n_c_t_i_o_n]
                         _v_1
                         This is the non-destructive version  of  2dv-
                         negate!.  _A _n_e_w _v_e_c_t_o_r _i_s _c_r_e_a_t_e_d _t_h_a_t _i_s _t_h_e
                         _v_e_c_t_o_r _r_e_s_u_l_t_i_n_g _f_r_o_m _n_e_g_a_t_i_n_g _t_h_e  _2_d-_v_e_c_t_o_r
                         _v_1.  _V_1 _i_s _l_e_f_t _u_n_c_h_a_n_g_e_d.

                     2dv-normalize!

                                                            [_F_u_n_c_t_i_o_n]
                         _v_1
                         This function destructively  scales  the  2d-





          PICASSO Reference Manual                              15-232







                                                              GRAPHICS


                         vector _v_1 so that it is normalized.

                     2dv-normalize

                                                            [_F_u_n_c_t_i_o_n]
                         _v_1
                         This is the non-destructive version  of  2dv-
                         normalize!.   _A _n_e_w _v_e_c_t_o_r _i_s _c_r_e_a_t_e_d _t_h_a_t _i_s
                         _t_h_e _v_e_c_t_o_r  _r_e_s_u_l_t_i_n_g  _f_r_o_m  _n_o_r_m_a_l_i_z_i_n_g  _t_h_e
                         _2_d-_v_e_c_t_o_r _v_1.  _V_1 _i_s _l_e_f_t _u_n_c_h_a_n_g_e_d.

                     2dv-scale!

                                                            [_F_u_n_c_t_i_o_n]
                         _v_1 _s_f
                         This function destructively  scales  the  2d-
                         vector _v_1 by the scale factor _s_f.

                     2dv-scale

                                                            [_F_u_n_c_t_i_o_n]
                         _v_1
                         _s_f
                         This is the non-destructive version  of  2dv-
                         scale!.   _A _n_e_w _v_e_c_t_o_r _i_s _c_r_e_a_t_e_d _t_h_a_t _i_s _t_h_e
                         _v_e_c_t_o_r _r_e_s_u_l_t_i_n_g _f_r_o_m _s_c_a_l_i_n_g  _t_h_e  _2_d-_v_e_c_t_o_r
                         _v_1  _b_y  _t_h_e  _s_c_a_l_e  _f_a_c_t_o_r  _s_f.  _V_1  _i_s  _l_e_f_t
                         _u_n_c_h_a_n_g_e_d.

                     2dv-zerop

                                                               [_M_a_c_r_o]
                         _v_1
                         This function returns t _i_f _t_h_e  _2_d-_v_e_c_t_o_r  _v_1
                         _i_s _t_h_e _z_e_r_o _v_e_c_t_o_r, _n_i_l _o_t_h_e_r_w_i_s_e.

                         _____________________________________________

          2D-VECTOR
          SUMMARY





               ____________________________________________________________________
                Allocation      Destructive      Non-Destructive   Misc
               ________________________________________________________________________________________________________________________________________
                alloc-2d        2dv-!            2dv-              2dv-dot-product
                duplicate-2d    2dv+!            2dv+              2dv-length
                free-2d         2dv-negate!      2dv-negate        2dv-zerop
                make-2d-point   2dv-normalize!   2dv-normalize
                                2dv-scale!       2dv-scale
                                copy-2d
                                2dv-copy
               ____________________________________________________________________

              |
              |
              |
              |
              |
              |
              |
              |
              |
              |








                             |
                             |
                             |
                             |
                             |
                             |
                             |
                             |
                             |
                             |








                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |
                                              |








                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |
                                                                |








                                                                                  |
                                                                                  |
                                                                                  |
                                                                                  |
                                                                                  |
                                                                                  |
                                                                                  |
                                                                                  |
                                                                                  |
                                                                                  |




















          PICASSO Reference Manual                              15-233







                                                              GRAPHICS


                         _____________________________________________

          LINESTRING
          UTILITY
          FUNCTIONS




                         Lists of 2d-points are used to  create  _l_i_n_e_-
                         _s_t_r_i_n_g_s.   Conceptually, a linestring is like
                         a polygon, but can be either open or  closed.
                         A  ``closed''  linestring  implicitly has its
                         last point connected to its first.

                     dopoints

                                                               [_M_a_c_r_o]
                         (_p_1 _p_2 _l_i_n_e_s_t_r _c_l_o_s_e_d)
                         &rest
                         _b_o_d_y
                         This macro iterates through all the points of
                         a line string.  If _c_l_o_s_e_d is non-nil, _l_i_n_e_s_t_r
                         _i_s _t_r_e_a_t_e_d _a_s _a _c_l_o_s_e_d _l_i_n_e_s_t_r_i_n_g.

                         First,  dopoints  _e_v_a_l_u_a_t_e_s  _l_i_n_e_s_t_r   (_w_h_i_c_h
                         _s_h_o_u_l_d  _b_e  _a _l_i_s_t _o_f _2_d-_p_o_i_n_t_s), _a_n_d _c_l_o_s_e_d.
                         _D_u_r_i_n_g _t_h_e _f_i_r_s_t _i_t_e_r_a_t_i_o_n,  _p_1  _i_s  _a_s_s_i_g_n_e_d
                         _t_h_e _f_i_r_s_t _p_o_i_n_t _i_n _t_h_e _l_i_n_e-_s_t_r_i_n_g, _a_n_d _p_2 _i_s
                         _a_s_s_i_g_n_e_d  _t_h_e  _s_e_c_o_n_d.    _D_u_r_i_n_g   _s_u_b_s_e_q_u_e_n_t
                         _i_t_e_r_a_t_i_o_n_s, _p_1 _a_n_d _p_2 _a_r_e _a_s_s_i_g_n_e_d _s_u_c_c_e_s_s_i_v_e
                         _p_o_i_n_t_s.  _A_f_t_e_r _a_l_l _s_u_c_c_e_s_s_i_v_e _p_a_i_r_s _o_f _p_o_i_n_t_s
                         _h_a_v_e  _b_e_e_n _e_x_h_a_u_s_t_e_d, _p_1 _i_s _a_s_s_i_g_n_e_d _t_h_e _l_a_s_t
                         _p_o_i_n_t _i_n _t_h_e _l_i_n_e-_s_t_r_i_n_g, _a_n_d _p_2 _i_s  _a_s_s_i_g_n_e_d
                         _t_h_e  _f_i_r_s_t _p_o_i_n_t _i_n _t_h_e _l_i_n_e-_s_t_r_i_n_g _i_f _c_l_o_s_e_d
                         _i_s _n_o_n-_n_i_l.

                     linestr-gravity-pt

                                                            [_F_u_n_c_t_i_o_n]
                         _l_i_n_e_s_t_r
                         _c_l_o_s_e_d
                         _d_o-_m_i_d_p_t
                         Linestr-gravity-pt _f_i_n_d_s _t_h_e  _g_r_a_v_i_t_y  _p_o_i_n_t_s
                         _f_o_r  _t_h_e  _l_i_n_e  _s_t_r_i_n_g  _p_a_s_s_e_d.  _I_t _r_e_t_u_r_n_s _a
                         _l_i_s_t _o_f _p_a_r_a_m_e_t_r_i_c _v_a_l_u_e_s _t_h_a_t  _d_e_s_c_r_i_b_e  _t_h_e
                         _g_r_a_v_i_t_y _p_o_i_n_t_s _o_f _t_h_e _l_i_n_e _s_t_r_i_n_g _t_h_a_t _m_a_y _b_e
                         _u_s_e_d _i_n _t_h_e _l_i_n_e_s_t_r-_n_o_r_m_a_l, linestr-point _a_n_d
                         _l_i_n_e_s_t_r-_p_t-_n_o_r_m_a_l  functions.  If _d_o-_m_i_d_p_t is
                         t, _t_h_e  _m_i_d_p_o_i_n_t_s  _a_r_e  _i_n_c_l_u_d_e_d  _a_s  _g_r_a_v_i_t_y
                         _p_o_i_n_t_s.   _I_f  _c_l_o_s_e_d  _i_s  _n_o_n-_n_i_l, _l_i_n_e_s_t_r _i_s
                         _t_r_e_a_t_e_d _a_s _a _c_l_o_s_e_d _l_i_n_e_s_t_r_i_n_g.

                     linestr-normal

                                                            [_F_u_n_c_t_i_o_n]
                         _l_i_n_e_s_t_r
                         _c_l_o_s_e_d
                         _v_a_l_u_e
                         Returns the 2d-vector (of type 2d-point) that
                         is   the  vector  normal  to  the  linestring
                         _l_i_n_e_s_t_r at the parametric  value  _v_a_l_u_e.   If
                         _c_l_o_s_e_d  is  non-nil,  _l_i_n_e_s_t_r _i_s _t_r_e_a_t_e_d _a_s _a
                         _c_l_o_s_e_d  _l_i_n_e_s_t_r_i_n_g.   _T_h_i_s  _p_o_i_n_t  _s_h_o_u_l_d  _b_e



          PICASSO Reference Manual                              15-234







                                                              GRAPHICS


                         _f_r_e_e_d  _w_i_t_h  _f_r_e_e-_2_d  _w_h_e_n  _i_t  _i_s  _n_o _l_o_n_g_e_r
                         _n_e_e_d_e_d.

                     linestr-point

                                                            [_F_u_n_c_t_i_o_n]
                         _l_i_n_e_s_t_r
                         _c_l_o_s_e_d
                         _v_a_l_u_e
                         Returns the 2d-vector (of type 2d-point) that
                         is the point on the linestring _l_i_n_e_s_t_r at the
                         parametric value _v_a_l_u_e. If _c_l_o_s_e_d is non-nil,
                         _l_i_n_e_s_t_r  _i_s  _t_r_e_a_t_e_d  _a_s _a _c_l_o_s_e_d _l_i_n_e_s_t_r_i_n_g.
                         _T_h_i_s _p_o_i_n_t _s_h_o_u_l_d _b_e _f_r_e_e_d _w_i_t_h _f_r_e_e-_2_d  _w_h_e_n
                         _i_t _i_s _n_o _l_o_n_g_e_r _n_e_e_d_e_d.

                     linestr-pt-normal

                                                            [_F_u_n_c_t_i_o_n]
                         _l_i_n_e_s_t_r
                         _c_l_o_s_e_d
                         _v_a_l_u_e
                         This function returns a  list  of  2d-vectors
                         (of  type 2d-point) that are the point on the
                         linestring _l_i_n_e_s_t_r at  the  parametric  value
                         _v_a_l_u_e and the normal vector to the linestring
                         _l_i_n_e_s_t_r at that point.  If _c_l_o_s_e_d is non-nil,
                         _l_i_n_e_s_t_r  _i_s  _t_r_e_a_t_e_d  _a_s _a _c_l_o_s_e_d _l_i_n_e_s_t_r_i_n_g.
                         _B_o_t_h  _t_h_e_s_e  _p_o_i_n_t_s  _s_h_o_u_l_d  _b_e  _f_r_e_e'_d  _w_i_t_h
                         _f_r_e_e-_2_d _w_h_e_n _t_h_e_y _a_r_e _n_o _l_o_n_g_e_r _n_e_e_d_e_d.

                     nearest-pt-to-linestr

                                                            [_F_u_n_c_t_i_o_n]
                         _l_i_n_e_s_t_r
                         _c_l_o_s_e_d
                         _p_t
                         This function finds the nearest point on  the
                         linestring  _l_i_n_e_s_t_r  to  the 2d-point _p_t.  It
                         returns a list whose  first  element  is  the
                         parametric   value   corresponding   to  this
                         nearest point, and whose second value is  the
                         distance from that point to the 2d-point _p_t.

                         _____________________________________________

          LINESTRING
          SUMMARY

















          PICASSO Reference Manual                              15-235







                                                              GRAPHICS



                                __________________________________
                                 Macros     Functions
                                ____________________________________________________________________
                                 dopoints   linestr-gravity-pt
                                            linestr-normal
                                            linestr-point
                                            linestr-pt-normal
                                            nearest-pt-to-linestr
                                __________________________________

                               |
                               |
                               |
                               |
                               |
                               |
                               |
                               |






                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |
                                         |






                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |










                         _____________________________________________

          CREATING A
          GRAPHIC
          GADGET





                         Graphic-gadgets  are  used  for   output-only
                         display  of  two  dimensional  graphic  data,
                         i.e.,  2d-shapes.   They  inherit  attributes
                         from the 2d-mapper-mixin class as well as the
                         gadget class.

                     make-graphic-gadget

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_v_a_l_u_e _n_i_l)
                         (zoom-extent t)
                         ;; Defaults inherited from 2d-mapper-mixin:
                         (_x_m_i_n _0._0)
                         (ymin 0.0)
                         (_x_m_a_x _1._0)
                         (ymax 1.0)
                         (_m_a_p_p_i_n_g :_i_s_o_t_r_o_p_i_c)
                         Creates and  returns  a  graphic-gadget.   If
                         _z_o_o_m-_e_x_t_e_n_t  is  non-nil,  _t_h_e  _i_n_i_t_i_a_l _w_o_r_l_d
                         _c_o_o_r_d_i_n_a_t_e _t_o _d_e_v_i_c_e  _c_o_o_r_d_i_n_a_t_e  _m_a_p_p_i_n_g  _i_s
                         _s_e_t  _s_o  _a_l_l _o_f _v_a_l_u_e _i_s _v_i_s_i_b_l_e.  _O_t_h_e_r_w_i_s_e,
                         _t_h_e _i_n_i_t_i_a_l _w_o_r_l_d _c_o_o_r_d_i_n_a_t_e _t_o _d_e_v_i_c_e  _c_o_o_r_-
                         _d_i_n_a_t_e  _m_a_p_p_i_n_g  _i_s _d_e_t_e_r_m_i_n_e_d _b_y _t_h_e _p_a_r_a_m_e_-
                         _t_e_r_s _m_a_p_p_i_n_g, _x_m_i_n, _x_m_a_x, _y_m_i_n _a_n_d _y_m_a_x.  _T_h_e
                         _v_a_l_u_e  _s_u_p_p_l_i_e_d  _s_h_o_u_l_d  _b_e _a _t_r_e_e _o_f _s_h_a_p_e_s.
                         _T_h_e  _g_r_a_p_h_i_c-_g_a_d_g_e_t  _a_u_t_o_m_a_t_i_c_a_l_l_y  _r_e_g_i_s_t_e_r_s
                         _i_t_s_e_l_f  _a_s  _a  _v_i_e_w_e_r _o_f _t_h_e _s_h_a_p_e _v_a_l_u_e, _a_n_d
                         _a_n_y  _c_h_a_n_g_e_s  _m_a_d_e  _t_o  _v_a_l_u_e  _a_r_e  _t_h_e_r_e_f_o_r_e
                         _a_u_t_o_m_a_t_i_c_a_l_l_y  _s_y_n_c_h_r_o_n_i_z_e_d _w_i_t_h _t_h_e _g_r_a_p_h_i_c-
                         _g_a_d_g_e_t _r_e_t_u_r_n_e_d.

                         _____________________________________________

          GRAPHIC
          GADGETS
          METHODS



          PICASSO Reference Manual15-236







            GRAPHICS


                     set-color-recursively

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         _s_h_a_p_e
                         _c_o_l_o_r
                         This function sets is used to set  the  color
                         of   the  graphic  object  _s_h_a_p_e  within  the
                         graphic-gadget  _s_e_l_f.   All  sub-objects   of
                         _s_h_a_p_e  will  also  have  their color changed.
                         The screen is updated dynamically.

                     set-visibility-recursively

                                                            [_F_u_n_c_t_i_o_n]
                         _s_e_l_f
                         _s_h_a_p_e
                         _v_i_s_i_b_l_e
                         This function sets is used to set  the  visi-
                         bility of the graphic object _s_h_a_p_e within the
                         graphic-gadget  _s_e_l_f.   _S_h_a_p_e  will  not   be
                         displayed  if  _v_i_s_i_b_l_e  in  nil, _o_t_h_e_r_w_i_s_e _i_t
                         _w_i_l_l _b_e _d_r_a_w_n.  _A_l_l _s_u_b-_o_b_j_e_c_t_s _o_f _s_h_a_p_e _w_i_l_l
                         _a_l_s_o  _h_a_v_e  _t_h_e_i_r  _v_i_s_i_b_i_l_i_t_y  _c_h_a_n_g_e_d.   _T_h_e
                         _s_c_r_e_e_n _i_s _u_p_d_a_t_e_d _d_y_n_a_m_i_c_a_l_l_y.

                     zoom-extent

                                                              [_M_e_t_h_o_d]
                         (_s_e_l_f _g_r_a_p_h_i_c-_g_a_d_g_e_t)
                         This method resets the world coordinate  sys-
                         tem  of  _s_e_l_f to a size sufficient to display
                         the entire object represented  in  the  value
                         slot of _s_e_l_f.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Graphic
          Browsers



                         The PICASSO graphic-browser is an interactive
                         form  of  the  graphic-gadget that allows for
                         the display and selection of  shapes.   Func-
                         tionality includes basic browsing facilities,
                         such as pan and zoom, and selection  features
                         which  allow  the user to select an object by
                         mousing near it or dragging a  box  around  a
                         group  of  objects.  Graphic-browsers inherit
                         attributes from the graphic-gadget  class  as
                         well as the widget class.

                     make-graphic-browser

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_s_e_l_e_c_t_i_o_n _n_i_l)
                         (selectables nil)
                         (_s_e_a_r_c_h-_r_a_d _5_0)
                         (highlight-font-list see below)
                         ;; Defaults inherited from graphic-gadget:
                         (value nil)
                         ;; Defaults inherited from 2d-mapper-mixin:
                         (xmin 0.0)



          PICASSO Reference Manual                              15-237







                                                              GRAPHICS


                         (ymin 0.0)
                         (xmax 1.0)
                         (ymax 1.0)
                         (mapping :isotropic)
                         Creates  and   returns   a   graphic-browser.
                         _S_e_l_e_c_t_i_o_n is a list of the _s_e_l_e_c_t_a_b_l_e objects
                         currently  selected.    _S_e_a_r_c_h-_r_a_d   is   the
                         radius,  in  pixels,  which  will be searched
                         around a mouse button event to find  objects.
                         Finally,  _h_i_g_h_l_i_g_h_t-_f_o_n_t-_l_i_s_t  is  a  list of
                         fonts that are used to display selected anno-
                         tations.   This  value  defaults to a list of
                         bold, oblique helvetica fonts ranging in size
                         from  34  to  10  points.  A typical graphic-
                         browser would have _s_e_l_e_c_t_a_b_l_e_s eq _t_o (_f_l_a_t_t_e_n
                         _v_a_l_u_e).

                         _____________________________________________

          GRAPHIC
          BROWSER
          METHODS








                     (setf selection)

                                                              [_M_e_t_h_o_d]
                         _n_e_w-_s_e_l_e_c_t_i_o_n
                         (_s_e_l_f _g_r_a_p_h_i_c-_b_r_o_w_s_e_r)
                         This method  changes  the  selection  of  the
                         graphic-browser    _s_e_l_f   to   _n_e_w-_s_e_l_e_c_t_i_o_n.
                         Objects are highlighted or unhighlighted from
                         the screen as necessary.

                         _____________________________________________

          GRAPHIC
          BROWSER
          INTERAC-
          TION






                         The graphic-browser allows selection of indi-
                         vidual  objects  and  groups of objects.  The
                         current list of selected objects is stored in
                         the  _s_e_l_e_c_t_i_o_n  slot  of the graphic-browser.
                         To make a single object the (unique)  element
                         of  the  selected  list,  left  button within
                         _s_e_a_r_c_h-_r_a_d pixels  of  the  intended  object.
                         The  graphic-browser  will  find  the closest
                         object that is in the selectables list within
                         _s_e_a_r_c_h-_r_a_d  pixels  of  the mouse (called the
                         _h_i_t _o_b_j_e_c_t), and that object will become  the
                         selection  and  be highlighted on the screen.
                         All other objects previously selected will be
                         unhighlighted.





          PICASSO Reference Manual                              15-238







                                                              GRAPHICS


                         To add or remove a  single  object  from  the
                         selected list, right button within _s_e_a_r_c_h-_r_a_d
                         pixels of the intended object.   If  the  hit
                         object  is  currently  selected,  it  will be
                         removed  from  the   selection   and   become
                         unhighlighted  on  the  screen,  otherwise it
                         will be added to  the  selection  and  become
                         highlighted on the screen.

                         To make a group of objects the selection, use
                         the  middle mouse button to drag a box around
                         the group of  objects.   All  objects  _w_h_o_l_l_y
                         contained  within  that  box  will become the
                         next selection.  To add or remove a group  of
                         objects  to  or  from  the selection, use the
                         middle mouse button in combination  with  the
                         shift  key  to drag a box around the group of
                         objects.  For any object wholly  within  that
                         box, its status in the selection will be tog-
                         gled: if it was a  member  of  the  selection
                         before, it will be removed, otherwise it will
                         be added.  The  graphics  screen  is  updated
                         dynamically at all times.

                         Dynamic zoom and pan are  also  supported  by
                         the PICASSO graphic-browser.  To zoom in on a
                         region of the screen,  click-and-drag  a  box
                         around  the  desired region by using the left
                         mouse button while holding down  the  control
                         key.   If  the  box  drawn is too small (less
                         than 5 pixels on a side), then the bell is is
                         sounded  and  no  effect  takes  place.  This
                         prevents ``getting lost'' if the mouse button
                         is  accidentally  released too early.  To pan
                         the    screen    dynamically,     use     the
                         control/middle-button combination to ``drag''
                         the image to the desired position.

                         _____________________________________________

          EXAMPLE



                         In this section we present a  simple  browser
                         of  a  graphic data structure that consists a
                         container object to hold two parts: a box and
                         a  triangle.   The  box  has  a  label.   All
                         objects are named.  Below  is  a  picture  of
                         this data structure:







          PICASSO Reference Manual                              15-239







                                                              GRAPHICS



                                      parts-list
                                      /       \
                                  triangle    box
                                               \
                                            box-label



                         The box is in red, the label in blue, and the
                         triangle   in  green  if  we're  on  a  color
                         display, otherwise everything  is  in  white.
                         The  box and the triangle are selectable, but
                         the label is not.


                       ;;; Make colors
                       (if (black-and-white-display-p)
                         (setq red "white"
                               green "white"
                               blue "white")
                         (setq red (make-color :name "red" :attach-p t)
                               green (make-color :name "green" :attach-p t)
                               blue (make-color :name "blue" :attach-p t)))































          PICASSO Reference Manual                              15-240







                                                              GRAPHICS



                       ;;; Make parts-list
                       (setq parts-list
                         (make-2d-shape
                          :name "parts-list"
                          :sub-objs '((make-box
                                       :name "box"
                                       :color red
                                       :hook-pt (alloc-2d 0 0)
                                       :width 30
                                       :height 30
                                       :sub-objs '((make-annotation
                                                    :name "box-label"
                                                    :color blue
                                                    :lower-left (alloc-2d 0 0)
                                                    :just :CC
                                                    :text "a-box"
                                                    :width 30
                                                    :height 30)))
                                      (make-polygon
                                       :name "triangle"
                                       :hook-pt (alloc-2d 10 10)
                                       :color green
                                       :ctrl-pts '((10 10) (20 10) (15 25))
                                       :closed t))))





                       ;;; Make a browser, attach it, and zoom all the way out
                       (setq selectables
                         (list (find-shape parts-list '("parts-list" "box"))
                               (find-shape parts-list '("parts-list" "triangle"))))

                       (setq gb (make-graphic-browser :value parts-list
                                                      :selectables selectables
                                                      :width 200
                                                      :height 200
                                                      :parent (root-window)))
                       (attach gb)














          PICASSO Reference Manual                              15-241







                                          APPLICATION-SPECIFIC WIDGETS


                                              16
                                 APPLICATION-SPECIFIC WIDGETS

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         In developing applications  for  PICASSO,  we
                         have  defined  several  widgets  which do not
                         easily  fit  into  the   categories   already
                         covered.  In this chapter we present the rest
                         of  the  widgets  defined  in   the   PICASSO
                         toolkit.

                         The following additional widgets are  defined
                         in PICASSO:

                         o+    Meter Widget

                         o+    Qual Widget

                         o+    Plot Widget
          ____________________________________________________________________________________________________________________________________________________________________________________

          Meter
          Widget



                         A meter widget consists of a meter-slider and
                         three  numeric fields. Meter widgets are used
                         as one-dimensional indicators, similar to the
                         indicator  (slider-bar) of a scroll-bar.  The
                         indicator is the meter-slider, which consists
                         of  a diamond-shaped locator and a horizontal
                         grid.  The three numeric-fields  specify  the
                         lower  and upper bounds and the current posi-
                         tion of the locator.

                         The lower and upper bounds may be  edited  by
                         clicking  on  them,  typing in the new value,
                         and pressing return.  The  current-value  can
                         only be set by the programmer.

                         _____________________________________________

          CREATION



                     make-meter-slider

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_l_o_w _0)
                         (high 0)
                         (_i_n_c_r_e_m_e_n_t _5)
                         (value 0)
                         (_u_p_d_a_t_e-_f_l_a_g _t)
                         ;; Plus keys inherited from widget
                         &allow-other-keys



          PICASSO Reference Manual                              16-242







                                          APPLICATION-SPECIFIC WIDGETS


                         Creates and returns a  meter  slider.   Meter
                         sliders  are  a subclass of widgets, and thus
                         inherit  additional  keys  and  methods  from
                         widgets.

                         _____________________________________________

          ATTRIBUTES



                     low

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_e_t_e_r-_s_l_i_d_e_r)
                         The lower bound of the  indicator.   Of  type
                         number, default 0

                     high

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_e_t_e_r-_s_l_i_d_e_r)
                         The upper bound of the  indicator.   Of  type
                         number, default 0

                     increment

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_e_t_e_r-_s_l_i_d_e_r)
                         The grid increment.  Of type number,  default
                         5.

                     value

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_e_t_e_r-_s_l_i_d_e_r)
                         The current position of the locator  relative
                         to low and high.  Of type number, default 0.

                     update-flag

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _m_e_t_e_r-_s_l_i_d_e_r)
                         Used when more than one of low, high,  value,
                         or  increment  _i_s  _s_e_t _a_t _o_n_c_e (_f_o_r _o_p_t_i_m_i_z_a_-
                         _t_i_o_n).  _F_o_r _e_x_a_m_p_l_e,


                          (_s_e_t_f _u_p_d_a_t_e-_f_l_a_g _m_w) _n_i_l)
                          (_s_e_t_f (_l_o_w _m_w) _0
                                (_h_i_g_h _m_w) _1_0_0
                                (_v_a_l_u_e _m_w) _2_5)
                          (_s_e_t_f (_u_p_d_a_t_e-_f_l_a_g _m_w) _t)



                         _____________________________________________

          MANAGEMENT



                     meter-slider-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t





          PICASSO Reference Manual                              16-243







                                          APPLICATION-SPECIFIC WIDGETS


                         Whether or not _o_b_j_e_c_t is a meter slider.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Qual
          Widget



                         A qual-widget is effectively two labels,  one
                         of  which  pops  up a menu when buttoned upon
                         (see pop-button for details).  It looks some-
                         thing like the following:


                                ______________________________
                                |                              |
                                |  Goal:  75%   Result:  50%   |
                                |______________________________|


                         All fields are customizable at instantiation,
                         and  the  data fields ("75%" and "50%" in the
                         above example) can be accessed dynamically as
                         well,  by means of the goal and result acces-
                         sor methods.

                         When the user clicks on "75%" above, the _g_o_a_l
                         field  is inverted and a list of menu options
                         pops up.  If a menu  item  is  selected,  the
                         menu goes away and the _g_o_a_l field is replaced
                         by the chosen item.  The process  is  aborted
                         if  the  mouse  is  released  outside  of the
                         menu-pane.  The menu items can be set dynami-
                         cally and/or at instantiation by means of the
                         items _a_c_c_e_s_s_o_r.

                         NOTE: the _r_e_s_u_l_t field ("50%" in above  exam-
                         ple)  can  be bound dynamically to some func-
                         tion on goal by using a bind-slot;  _f_o_r _e_x_a_m_-
                         _p_l_e:


                          (_b_i_n_d-_s_l_o_t
                            '_r_e_s_u_l_t
                            <_q_u_a_l _w_i_d_g_e_t>
                            `(_l_e_t ((_g_o_a_l (_v_a_r _g_o_a_l ,_q_w)))
                                  (_c_o_n_d ((_s_t_r_i_n_g= _g_o_a_l "_7_5%") "_5_0%")
                                        ((_s_t_r_i_n_g= _g_o_a_l "_5_0%") "_2_5%")
                                        (_t "_0%"))))


                         _S_e_e _t_h_e _d_o_c_u_m_e_n_t_a_t_i_o_n _o_n _b_i_n_d_i_n_g_s (_C_h_a_p_t_e_r _6)







          PICASSO Reference Manual                              16-244







                                          APPLICATION-SPECIFIC WIDGETS


                         _f_o_r _m_o_r_e _i_n_f_o_r_m_a_t_i_o_n.

                         _____________________________________________

          CREATION



                     make-qual-widget

                                                            [_F_u_n_c_t_i_o_n]
                         (_g_o_a_l _n_i_l)
                         (result nil)
                         (_f_i_r_s_t-_t_i_t_l_e "_G_o_a_l:")
                         (second-title "Result:")
                         (_f_i_r_s_t-_v_a_l_u_e "")
                         (second-value "")
                         (_f_i_r_s_t-_f_o_n_t (_m_a_k_e-_f_o_n_t))
                         (second-font (make-font))
                         (_i_t_e_m_s _n_i_l)
                         (orientation :left)
                         ;; defaults overridden from superclasses
                         (_g_m '_r_u_b_b_e_r-_g_m)
                         ;; Plus keys inherited from collection-widget
                         &allow-other-keys
                         Creates and  returns  a  qual  widget.   Qual
                         widgets are a subclass of collection widgets,
                         and thus inherit additional keys and  methods
                         from collection widgets.

                         _____________________________________________

          ATTRIBUTES



                     goal

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _q_u_a_l-_w_i_d_g_e_t)

                     result

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _q_u_a_l-_w_i_d_g_e_t)

                     first-title

                                                            [_A_r_g_u_m_e_n_t]
                         Initial argument only. The title of the first
                         field, default "Goal".

                     second-title

                                                            [_A_r_g_u_m_e_n_t]
                         _I_n_i_t_i_a_l  _a_r_g_u_m_e_n_t  _o_n_l_y.  _T_h_e  _t_i_t_l_e  _o_f  _t_h_e
                         _s_e_c_o_n_d _f_i_e_l_d, _d_e_f_a_u_l_t "_R_e_s_u_l_t".

                     first-value

                                                            [_A_r_g_u_m_e_n_t]
                         _I_n_i_t_i_a_l _a_r_g_u_m_e_n_t _o_n_l_y. _T_h_e _v_a_l_u_e _o_f _t_h_e _f_i_r_s_t
                         _f_i_e_l_d, _d_e_f_a_u_l_t "".

                     second-value

                                                            [_A_r_g_u_m_e_n_t]
                         _I_n_i_t_i_a_l  _a_r_g_u_m_e_n_t  _o_n_l_y.  _T_h_e  _v_a_l_u_e  _o_f  _t_h_e





          PICASSO Reference Manual                              16-245







                                          APPLICATION-SPECIFIC WIDGETS


                         _s_e_c_o_n_d _f_i_e_l_d, _d_e_f_a_u_l_t "".

                     first-font

                                                            [_A_r_g_u_m_e_n_t]
                         _I_n_i_t_i_a_l _a_r_g_u_m_e_n_t _o_n_l_y. _T_h_e _f_o_n_t _o_f _t_h_e  _f_i_r_s_t
                         _f_i_e_l_d.

                     second-font

                                                            [_A_r_g_u_m_e_n_t]
                         _I_n_i_t_i_a_l _a_r_g_u_m_e_n_t _o_n_l_y. _T_h_e _f_o_n_t _o_f _t_h_e _s_e_c_o_n_d
                         _f_i_e_l_d.

                     items

                                                            [_A_r_g_u_m_e_n_t]
                         _T_h_e _p_o_p _b_u_t_t_o_n _l_i_s_t _o_f _m_e_n_u _e_n_t_r_i_e_s (_s_e_e  _p_o_p
                         _b_u_t_t_o_n_s _f_o_r _m_o_r_e _i_n_f_o_r_m_a_t_i_o_n).

                     orientation

                                                            [_A_r_g_u_m_e_n_t]
                         _T_h_e _o_r_i_e_n_t_a_t_i_o_n _o_f _t_h_e _p_o_p _b_u_t_t_o_n _l_a_b_e_l,  _o_n_e
                         _o_f  :_l_e_f_t,  :_b_o_t_t_o_m,  :_f_r_a_m_e,  _o_r  _n_i_l.   _T_h_e
                         _d_e_f_a_u_l_t _i_s :_l_e_f_t.

                         _____________________________________________

          MANAGEMENT



                     qual-widget-p

                                                               [_M_a_c_r_o]
                         _o_b_j_e_c_t
                         Whether or not _o_b_j_e_c_t is a qual widget.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Plot
          Widget



                         A plot-widget displays XY plots  of  multiple
                         curves,  and  optionally  attaches a label to
                         each curve.  Each curve consists of an  array
                         of points. A plot-widget automatically scales
                         its X and Y axis in order to make visible all
                         the  specified  points.   However, each plot-
                         widget also has optional interactive pan  and
                         zoom controls which allow the user to examine
                         any part of the plot in detail.

                         _____________________________________________

          CREATION



                     make-plot-widget

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_v_a_l_u_e _n_i_l)
                         (x-label "")
                         (_y-_l_a_b_e_l "")
                         (x-pad 5)
                         (_y-_p_a_d _5)
                         (font (get-font))
                         (_m_a_r_k-_f_o_n_t (_g_e_t-_f_o_n_t))



          PICASSO Reference Manual                              16-246







                                          APPLICATION-SPECIFIC WIDGETS


                         (paints nil)
                         (_r_a_n_g_e _n_i_l)
                         (domain nil)
                         (_x-_i_n_c_r_e_m_e_n_t _5)
                         (y-increment 5)
                         (_m_a_r_k-_p_o_i_n_t_s _t)
                         (curve-labels nil)
                         (_x-_a_x_i_s _t)
                         (y-axis t)
                         ;; Plus keys inherited from collection-widget
                         &allow-other-keys
                         Creates and returns a plot-widget. Here is an
                         example:


                          (setq pts
                                (list (make-array 5 :initial-contents
                                                  '((10 . 10) (20 . 30) (50 . 15)
                                                    (60 . 70) (90 . 40)))
                                      (make-array 8 :initial-contents
                                                  '((5 . 60) (15 . 30) (30 . 15)
                                                    (35 . 12) (38 . 10) (45 . 8)
                                                    (65 . 40) (90 . 80)))))
                          (make-plot-widget :base-size '(200 200)
                                            :x-label "Hello"
                                            :y-label "There"
                                            :value pts
                                            :paints (list "green" "red"))


                         See below for more information.

                         _____________________________________________

          ATTRIBUTES



                     update-flag

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         Either t _o_r _n_i_l, indicating whether update is
                         on  or off. This slot works like repaint-flag
                         _o_r _r_e_p_a_c_k-_f_l_a_g.  Use when changing more  than
                         one  attribute  at once to avoid wasting time
                         with multiple updates.

                     value

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         The curve or curves to be plotted. Each curve
                         is an array of dotted pairs, with each dotted
                         pair representing a point on the curve.  This
                         slot  can contain either one array (when only
                         one curve is to be displayed) or  a  list  of




          PICASSO Reference Manual                              16-247







                                          APPLICATION-SPECIFIC WIDGETS


                         arrays.

                     x-label

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         The label of the x-axis of  the  plot-widget.
                         This  slot can contain a string, an image, or
                         anything with a put _m_e_t_h_o_d.

                     y-label

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         The label of the y-axis of  the  plot-widget.
                         This  slot can contain a string, an image, or
                         anything with a put _m_e_t_h_o_d.

                     x-pad

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         The empty space to  leave  on  the  left  and
                         right, in pixels.

                     y-pad

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         The empty space to leave on the top and  bot-
                         tom, in pixels.

                     font

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         The font used for x-label, y-label and  curve
                         labels.

                     mark-font

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         The font used for the numbers associated with
                         the tick marks.

                     paints

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         A list of colors or paints  corresponding  to
                         the  desired  color  of each of the curves in
                         value. _I_f _t_h_i_s _s_l_o_t _i_s _n_i_l,  the  curves  are
                         drawn  in  black.   If  this slot is not nil,
                         _t_h_e_r_e _s_h_o_u_l_d _b_e _a_s _m_a_n_y _p_a_i_n_t_s _a_s _c_u_r_v_e_s.  _I_f
                         _t_h_e_r_e  _a_r_e _n_o_t _e_n_o_u_g_h _p_a_i_n_t_s, _t_h_e _p_l_o_t-_w_i_d_g_e_t
                         _w_i_l_l _p_a_d _t_h_e _l_i_s_t _w_i_t_h _t_h_e _l_a_s_t _p_a_i_n_t _o_n  _t_h_e
                         _l_i_s_t.

                     range

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         A dotted pair  indicating  the  range  to  be
                         displayed.    This  attribute  overrides  the






          PICASSO Reference Manual                              16-248







                                          APPLICATION-SPECIFIC WIDGETS


                         automatic scaling which normally occurs.

                     domain

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         A dotted pair indicating  the  domain  to  be
                         displayed.    This  attribute  overrides  the
                         automatic scaling which normally occurs.

                     x-increment

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         The increment between tick marks  on  the  x-
                         axis.

                     y-increment

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         The increment between tick marks  on  the  y-
                         axis.

                     mark-points

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         Either t _o_r _n_i_l, specifies if each  point  on
                         the  plot  should  be  marked  with  a little
                         square.  If not, only  lines  between  points
                         are drawn.

                     curve-labels

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         A list of string labels,  each  corresponding
                         to a curve in value.  _T_h_e _l_a_b_e_l_s _a_r_e _d_r_a_w_n _b_y
                         _t_h_e _c_u_r_v_e_s.  _I_f _t_h_i_s _s_l_o_t _i_s _n_o_t  _n_i_l,  there
                         should be as many labels as curves.

                     x-axis

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         Either t _o_r  _n_i_l,  specifies  if  the  x-axis
                         should be drawn.

                     y-axis

                                                            [_A_c_c_e_s_s_o_r]
                         (_s_e_l_f _p_l_o_t-_w_i_d_g_e_t)
                         Either t _o_r  _n_i_l,  specifies  if  the  y-axis
                         should be drawn.














          PICASSO Reference Manual                              16-249







                                               LIBRARY PICASSO OBJECTS


                                              17
                                    LIBRARY PICASSO OBJECTS

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview


                         A number of library PO's  are  provided  with
                         PICASSO.   The PICASSO package contains a set
                         of general-purpose dialogs and  panels  which
                         can be called from any application.  In addi-
                         tion, several complete applications are  pro-
                         vided as examples of toolkit use.

                         This chapter describes the  following  groups
                         of provided objects:

                         o+    Library Panels and Dialogs

                         o+    Facility Manager Tool

                         o+    Tool Editor

                         o+    Robbie the Robot Tool

                         o+    Widgets at an Exhibition Tool

                         o+    Employee/Department Browser

                         o+    Recipe Generator Tool
          ____________________________________________________________________________________________________________________________________________________________________________________

          Library
          Panels and
          Dialogs




                         The PICASSO  package  contains  a  number  of
                         predefined  general-purpose dialogs which can
                         be called from any  application.   There  are
                         predefined dialogs for

                         o+    confirming or cancelling actions

                         o+    exiting tools

                         o+    displaying messages (notifying)

                         o+    opening files

                         o+    quitting without saving files

                         o+    saving files

                         o+    prompting for input strings





          PICASSO Reference Manual                              17-250







                                               LIBRARY PICASSO OBJECTS


                         These   PICASSO   objects    are    in    the
                         ~picasso/lib/po/picasso  directory,  and  are
                         described in the following sections.

                         The confirmer dialog (confirmer.dialog) takes
                         one  argument,  msg, and displays the message
                         bound to the msg variable.  The  dialog  also
                         displays two response buttons, "OK" and "Can-
                         cel"; buttoning the "OK" button will return t
                         to  the  calling  PO,  and buttoning "Cancel"
                         will return nil.

                         The exit dialog  (exit.dialog)  displays  the
                         message  "Are you sure you want to quit?", as
                         well as two response buttons, "OK" and  "CAN-
                         CEL".   Selecting  the  "OK" button will exit
                         the currently  running  tool  with  a  return
                         value  of  t.   Selecting the "CANCEL" button
                         will return :cancelled  to  the  calling  PO.
                         This  dialog  is automatically in the PICASSO
                         menu.

                         The notifier dialog  (notifier.dialog)  takes
                         one  argument,  msg, and displays the message
                         bound to the msg variable.  The  dialog  also
                         displays  an "OK" button, and clicking on the
                         "OK" button will return t to the caller.

                         The open file dialog (open-file.dialog) takes
                         an  initial directory path dir, prompts for a
                         file name,  and returns the full pathname (in
                         string  form)  of  the  file to be opened. It
                         displays three buttons, "Open", "Cancel", and
                         "Change-Dir",  as  well  as a list of current
                         directory files.

                         The   save-cancel-ok   dialog   (save-cancel-
                         ok.dialog)  prompts  users as to whether they
                         want to quit  a  tool  without  saving  their
                         files.  Specifically, it displays the message
                         "Do you want to do  so  without  saving  your
                         files(s)".   It  also displays three buttons,
                         "Save",  "Cancel",  and  "OK".  Clicking   on
                         "Save"  returns  t  to  the  caller, clicking
                         "Cancel"  returns  :cancelled,  and  clicking
                         "OK" returns nil.

                         The  file  saving  dialog  (save-file.dialog)
                         takes  an initial directory path dir, prompts
                         for a file name, and returns the  full  path-
                         name  of a file to be saved to.  It has three
                         buttons, "Save", "Cancel"  and  "Change-Dir",



          PICASSO Reference Manual                              17-251







                                               LIBRARY PICASSO OBJECTS


                         as well as a list of current directory files.

                         The    string    prompter    dialog     (str-
                         prompter.dialog)  takes  and displays a vari-
                         able prompt, prompts the user for  a  string,
                         and returns the string if the user clicks the
                         "OK" button.  If the user clicks the "CANCEL"
                         button, the dialog returns nil to the caller.



                         The following table summarizes the predefined
                         picasso  PICASSO  panels  and  dialogs in the
                         ~picasso/lib/po/picasso directory:


                 _________________________________________________________________
                  File                    PICASSO Name
                 __________________________________________________________________________________________________________________________________
                  confirmer.dialog        ("picasso" "confirmer" . "dialog")
                  exit.dialog             ("picasso" "exit" . "dialog")
                  notifier.dialog         ("picasso" "notifier" . "dialog")
                  open-file.dialog        ("picasso" "open-file" . "dialog")
                  save-cancel-ok.dialog   ("picasso" "save-cancel-ok" . "dialog")
                  save-file.dialog        ("picasso" "save-file" . "dialog")
                  str-prompter.dialog     ("picasso" "str-prompter" . "dialog")
                 _________________________________________________________________

                |
                |
                |
                |
                |
                |
                |
                |
                |
                |








                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |
                                       |








                                                                                 |
                                                                                 |
                                                                                 |
                                                                                 |
                                                                                 |
                                                                                 |
                                                                                 |
                                                                                 |
                                                                                 |
                                                                                 |











          ____________________________________________________________________________________________________________________________________________________________________________________

          Facility
          Manager
          Tool




                         The Facility Manager Tool (FM Tool) is a sam-
                         ple  application  of the PICASSO GUI develop-
                         ment system.  In particular,  FM  Tool  is  a
                         browsing  tool for spatial and production-lot
                         manufacturing data.  A novel end user  inter-
                         face  to  a  geometric  database, FM Tool was
                         developed to help facility managers in an  IC
                         fabrication facility.

                         To run FM Tool:


                          % picasso
                          % <picasso> (run-tool-named '("fmtool" "tool"))


                         The key binding for pan and zoom, as well  as
                         selection,  on  the graphic screen is as fol-
                         lows:




          PICASSO Reference Manual                              17-252







                                               LIBRARY PICASSO OBJECTS



                   ____________________________________________________________
                    Action                                 Key Binding
                   ________________________________________________________________________________________________________________________
                    Select single object:                  Left Button
                    Extend selection by a single object:   Right Button
                    Select within region:                  Middle Button
                    Extend selection within region:        Shift/Middle Button
                    Zoom by click-and-drag:                Ctrl/Left Button
                    Pan by click-and-drag:                 Ctrl/Middle Button
                   ____________________________________________________________

                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |
                  |







                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |
                                                        |







                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |
                                                                              |










          ____________________________________________________________________________________________________________________________________________________________________________________

          Tool Edi-
          tor



                         The PICASSO Tool Editor, a tool for  building
                         PICASSO   applications,  is  currently  under
                         development and  is  being  written  entirely
                         using  PICASSO.   The  Tool  Editor  is being
                         designed for ease of use  and  extensibility,
                         so  that  1) users do not need to use textual
                         information, 2) custom widgets can be manipu-
                         lated by the editor, and 3) widget writers do
                         not need to change the editor.   In  particu-
                         lar, the Tool Editor will allow users to:

                         o+    specify the contents of frames,  panels,
                              and dialog boxes

                         o+    specify           variables           by
                              pointing/clicking/typing a name

                         o+    utilize  separate  panels  for  building
                              menus and setting geometry

                         o+    specify any attributes for each widget

                         o+    take advantage  of  direct  manipulation
                              editing _a_n_d textual representations.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Robbie the
          Robot Tool



                         Robbie the Robot is a PICASSO tool  developed
                         for  teaching  LISP  programming to beginning
                         programmers, giving a gradual introduction to
                         LISP  control and data structures.  This tool
                         presents a graphic display of a robot  world,
                         and  using this tool, students learn to write
                         and call their own functions to  control  the
                         robot.  Robbie  the  Robot  is comprised of a
                         Tool window  and  three  panels;  the  Editor



          PICASSO Reference Manual                              17-253







                                               LIBRARY PICASSO OBJECTS


                         panel,    the    Lesson    panel,   and   the
                         Stepper/Debugger panel.

                         The Tool window presents a graphic display of
                         the   robot  world,  as  well  as  a  textual
                         representation of the world information.   It
                         also  displays the controls and menus for the
                         tool.

                         The Editor panel displays  a  formatted  test
                         window that highlights executing code, a LISP
                         customized  type-in  window,  a  browser  for
                         functions  and command names, as well as con-
                         trols for file input/output.

                         The  Lesson  panel   handles   administrative
                         details,  such as giving the student a lesson
                         text and displaying a list of data files. The
                         lesson manager facilitates teacher control of
                         lesson  content  and  sample  solutions,  and
                         allows  the  student  to  control the pace of
                         learning.

                         The Stepper/Debugger panel allows the student
                         to  set  breakpoints  and  to continue opera-
                         tions.   Stepper  functions  and  a   dynamic
                         tracer  with  zoom  facilities  are also pro-
                         vided.

                         To run Robbie:


                          % picasso
                          % <picasso> (run-tool-named '("robbie" "tool"))


          ____________________________________________________________________________________________________________________________________________________________________________________

          Widgets at
          an Exhibi-
          tion Tool




                         The  Widgets  at  an  Exhibition  Tool  is  a
                         demonstration of the PICASSO toolkit widgets,
                         including  buttons,  button  groups,  tables,
                         graphics,  and  text  widgets.  The following
                         table summarizes the toolkit  widgets  demon-
                         strated in this tool:










          PICASSO Reference Manual                              17-254







                                               LIBRARY PICASSO OBJECTS



             ________________________________________________________________________
                                                                Button
              Text                    Tables          Buttons   Groups   Graphics
             ________________________________________________________________________________________________________________________________________________
              text-gadget             list-box        button    check    plot-widget
              entry-widget            table-field     gray      radio
              num-entry               browse-widget   pop
              scrollable-num-entry
              text-widget
              scrolling-text-widget
             ________________________________________________________________________

            |
            |
            |
            |
            |
            |
            |
            |
            |
            |








                                   |
                                   |
                                   |
                                   |
                                   |
                                   |
                                   |
                                   |
                                   |
                                   |








                                                   |
                                                   |
                                                   |
                                                   |
                                                   |
                                                   |
                                                   |
                                                   |
                                                   |
                                                   |








                                                             |
                                                             |
                                                             |
                                                             |
                                                             |
                                                             |
                                                             |
                                                             |
                                                             |
                                                             |








                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |








                                                                                    |
                                                                                    |
                                                                                    |
                                                                                    |
                                                                                    |
                                                                                    |
                                                                                    |
                                                                                    |
                                                                                    |
                                                                                    |











                         These   PICASSO   objects    are    in    the
                         ~picasso/lib/po/gallery directory.

                         To run the Widgets at an Exhibition Tool:


                          % picasso
                          % <picasso> (run-tool-named '("gallery" "tool"))


          ____________________________________________________________________________________________________________________________________________________________________________________

          Employee/
          Department
          Browser




                         The Employee/Department Browser is a  PICASSO
                         application  that  displays information about
                         employees and departments, and consists of  a
                         tool window, a department panel, and a search
                         dialog.  The tool window displays information
                         about  an  employee.   It consists of a frame
                         containing  a  form   which   describes   the
                         employee  (e.g., name, age, etc.), and a menu
                         bar with pull-down menus that contain  opera-
                         tions  the  user can execute.  Buttons at the
                         bottom of the frame allow the  user  to  step
                         through the employees in the database.

                         The  department  panel  displays  information
                         about  the  department  to which the employee
                         belongs.  At  the  top  of  the  panel  is  a
                         hierarchy  browser that lists departments and
                         the  employees  in  a  selected   department.
                         Information  about  the  department  that the
                         current employee belongs to  is  shown  below
                         the   browser.   The  department  information
                         includes the manager  and  a  graphics  field
                         that  shows  a  floor  plan with the selected
                         employee and  his  or  her  manager's  office
                         highlighted.  If the user selects a button at



          PICASSO Reference Manual                              17-255







                                               LIBRARY PICASSO OBJECTS


                         the bottom of the frame to display the previ-
                         ous  or next employee and that employee is in
                         a different department, the department infor-
                         mation in the panel is automatically updated.

                         The user can search for an  employee  on  any
                         attribute  (e.g.,  age  or  department).  For
                         example, selecting the By Age... menu  opera-
                         tion  from  the  tool window calls the search
                         dialog box.  The  user  can  then  enter  the
                         desired  age  in  the type-in field and press
                         the Ok button, which returns from the  search
                         dialog  box  and  changes  the display to the
                         employee closest in age to the value entered.

                         To run the Employee/Department Browser:


                          % picasso
                          % <picasso> (run-tool-named '("paper" "demo" . "tool"))



































          PICASSO Reference Manual                              17-256







                                                              DEFAULTS


                                              18
                                           DEFAULTS

          ____________________________________________________________________________________________________________________________________________________________________________________

          Overview



                         In any toolkit, it is essential to have  some
                         sort  of  method  for  _d_e_f_a_u_l_t_i_n_g unspecified
                         attributes of the various objects  that  make
                         up  the toolkit.  For instance, complex widg-
                         ets like table-fields _a_n_d _t_e_x_t-_w_i_d_g_e_t_s have a
                         huge  number  of options, any number of which
                         can be specified when the widget is  created.
                         However,  it  is  not  expected that the user
                         specify very  many  of  these  options.   All
                         unspecified options will default to some rea-
                         sonable  value,  determined  by  the   widget
                         either    statically   (applicable   to   all
                         instances) or dynamically (deduced from  some
                         combination  of  other  attributes  on a per-
                         instance basis).

                         In PICASSO, there is a  three-level  defaults
                         hierarchy:

                         o+    user-level

                         o+    system-level

                         o+    widget-level

                         User-level defaults apply  only  to  applica-
                         tions run by a particular user.  System-level
                         defaults are global to a particular installa-
                         tion  of  PICASSO; they apply to all applica-
                         tions run using that particular  installation
                         of  PICASSO. Widget-level defaults are custom
                         coded in the actual widget-code;  they  apply
                         to  every  PICASSO  application  (on  earth).
                         User-level  defaults  override   system-level
                         defaults  which,  in  turn,  override widget-
                         level defaults.  Any  default  which  is  not
                         found  at the user-level is looked for in the
                         system level and then the widget-level so  it
                         is  possible  to combine defaults between the









          PICASSO Reference Manual                              18-257







                                                              DEFAULTS


                         levels.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Selecting
          Defaults




                         User-level  and  system-level  defaults   are
                         specified  in  two files having the same for-
                         mat.  The user-level defaults should be in  a
                         file named
                         ".picasso-defaults"
                         in the user's home  directory.   The  system-
                         level  defaults  (if  present)  are in a file
                         with the path
                         "~picasso/lib/picasso-defaults"

                         _____________________________________________

          FORMAT OF
          USER/SYSTEM
          DEFAULTS





                         A default is specified by a  _c_l_a_s_s,  optional
                         _f_i_e_l_d_s,  an _a_t_t_r_i_b_u_t_e, and a _v_a_l_u_e.  The col-
                         lection of (_c_l_a_s_s _f_i_e_l_d_s _a_t_t_r_i_b_u_t_e) is called
                         the   _d_e_f_a_u_l_t-_s_p_e_c.    Any   member   of  the
                         _d_e_f_a_u_l_t-_s_p_e_c can be a wildcard (specified  as
                         *).   _T_h_e  _a_l_g_o_r_i_t_h_m  _f_o_r _l_o_o_k_i_n_g-_u_p _d_e_f_a_u_l_t_s
                         _r_e_t_u_r_n_s  _t_h_e  _v_a_l_u_e  _f_o_r  _t_h_e  _d_e_f_a_u_l_t  _w_h_o_s_e
                         _d_e_f_a_u_l_t-_s_p_e_c _i_s _t_h_e _c_l_o_s_e_s_t _m_a_t_c_h _t_o _a _s_p_e_c_i_-
                         _f_i_e_d  _d_e_f_a_u_l_t-_r_e_q_u_e_s_t.  _T_h_e   _d_e_f_i_n_i_t_i_o_n   _o_f
                         _d_e_f_a_u_l_t-_r_e_q_u_e_s_t  _i_s _d_e_s_c_r_i_b_e_d _i_n _a _s_u_b_s_e_q_u_e_n_t
                         _s_e_c_t_i_o_n.  _T_h_e  _d_e_f_i_n_i_t_i_o_n  _o_f  _c_l_o_s_e_s_t  _m_a_t_c_h
                         _t_a_k_e_s _i_n_t_o _a_c_c_o_u_n_t _t_h_e _t_o_p-_d_o_w_n, _p_a_r_e_n_t-_c_h_i_l_d
                         _h_i_e_r_a_r_c_h_y _o_f _t_h_e  _d_e_f_a_u_l_t-_s_p_e_c.   _A  _w_i_l_d_c_a_r_d
                         _m_a_t_c_h_e_s _a_n_y_t_h_i_n_g.

                         _c_l_a_s_s is used  to  specify  the  global  name
                         which  identifies  the  object  to  which the
                         default applies.  Typically, _c_l_a_s_s  the  name
                         of  a  widget  or  a  PO  (a particular tool,
                         frame, form, panel, or dialog).  If  a  wild-
                         card, _c_l_a_s_s matches any object.

                         _f_i_e_l_d_s is a _f_i_e_l_d or list of _f_i_e_l_d_s that par-
                         tially  qualifies the default in a hierarchi-
                         cal manner.  Each _f_i_e_l_d is an attribute  that
                         is  more  specific  than  the last and can be
                         viewed as a hierarchical child  of  the  last
                         _f_i_e_l_d  and  parent  of  the  next field.  All
                         _f_i_e_l_d_s are hierarchical parents of the _a_t_t_r_i_-
                         _b_u_t_e specification.

                         _a_t_t_r_i_b_u_t_e is the specific  attribute  of  the
                         default that is to be set.



          PICASSO Reference Manual                              18-258







                                                              DEFAULTS


                         Perhaps an example would best illustrate  how
                         defaults are specified.

                         Here is a sample set of defaults:


               _____________________________________________________________________
                Class         Fields                   Attribute    Value
               __________________________________________________________________________________________________________________________________________
                *                                      font         8x13
                text-gadget                            font         6x10
                demo-tool     frame1, panel2, entry3   background   PukeGreen
                demo-tool     frame2, *, *             font         -b&h*bold-r*14*
               _____________________________________________________________________

              |
              |
              |
              |
              |
              |
              |





                           |
                           |
                           |
                           |
                           |
                           |
                           |





                                                    |
                                                    |
                                                    |
                                                    |
                                                    |
                                                    |
                                                    |





                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |
                                                                 |





                                                                                   |
                                                                                   |
                                                                                   |
                                                                                   |
                                                                                   |
                                                                                   |
                                                                                   |









                         This is  the  corresponding  picasso-defaults
                         file for the preceding set of defaults:


                          *.font:             8x13
                          text-gadget.font:   6x10

                          # defaults for demo-tool
                          demo-tool.frame1.panel2.entry3: BrightGreen
                          demo-tool.frame2.*.font:        -b&h*bold-r*14*



                         _____________________________________________

          BLACK &
          WHITE VS.
          COLOR





                         Because PICASSO supports  both  monochrome  &
                         color  displays,  PICASSO  applications often
                         need to  be  customized  in  different  ways,
                         depending  on  whether the current-display is
                         color or monochrome.  Hence,  PICASSO  allows
                         specifications  of  defaults  that are inter-
                         preted automatically as specifically applica-
                         ble to a certain type of display.

                         Any _d_e_f_a_u_l_t-_s_p_e_c that is  postpended  by  the
                         string   "b&w"   _i_s   _t_r_e_a_t_e_d  _a_s  _a  _d_e_f_a_u_l_t
                         _e_x_c_l_u_s_i_v_e_l_y _f_o_r _b_l_a_c_k-_a_n_d-_w_h_i_t_e  (_m_o_n_o_c_h_r_o_m_e)
                         _d_i_s_p_l_a_y_s.

                         For example:






          PICASSO Reference Manual                              18-259







                                                              DEFAULTS



                          *.background:         blue

                          # a global default for monochrome
                          *.background.b&w:     gray75

                          demo-tool.frame2.*.background:          BrightGreen
                          demo-tool.frame2.*.background.b&w:      White

                          button.background:                      black



                         In the above example, for a

                         monochrome-display:
                              default   background   is   gray75   (an
                              image/tile).    default  background  for
                              widgets in frame2 of demo-tool is White.
                              default background for buttons is black.

                         color-display:
                              default  background  is  blue.   default
                              background  for  widgets  in  frame2  of
                              demo-tool is BrightGreen.  default back-
                              ground for buttons is black.

                         _____________________________________________

          EVENT
          DEFAULTS



                         In addition so specifying defaults for attri-
                         butes  of  objects, PICASSO also allows a way
                         of  specifying   defaults   for   class-level
                         event-mappings.   The user should consult the
                         chapter on  Events  in  the  Widget  Writer's
                         Guide  to  get  an  understanding  of  event-
                         mappings, but a brief overview will be  given
                         in this section.

                         When an event is sent to a widget, what actu-
                         ally  happens  is  that PICASSO looks for and
                         invokes a _h_a_n_d_l_e_r  for  the  event.   PICASSO
                         consults  a  table  of _e_v_e_n_t-_m_a_p_p_i_n_g_s to find
                         this _h_a_n_d_l_e_r.  _e_v_e_n_t-_m_a_p_p_i_n_g_s can  be  either
                         fully   qualified   or  partially  qualified.
                         PICASSO  always  invokes  the  handler  most-
                         specific to the widget and the event.

                         An _e_v_e_n_t-_m_a_p_p_i_n_g is specified by five fields:
                         _c_l_a_s_s,   _e_v_e_n_t-_t_y_p_e,   _s_t_a_t_e,   _d_e_t_a_i_l,   and
                         _h_a_n_d_l_e_r.  These fields can be specified in  a
                         picasso-defaults _f_i_l_e _l_i_k_e _a_n_y _o_t_h_e_r _d_e_f_a_u_l_t.



          PICASSO Reference Manual                              18-260







                                                              DEFAULTS


                         Here is a sample set of event-defaults:


            ___________________________________________________________________________
             Class          Event-Type     State          Detail         Handler
            ______________________________________________________________________________________________________________________________________________________
             text-widget    key-press      control        k              kill-line
             text-widget    key-press      control K      kill-line
             matrix-field   button-press   *              *              select-unique
             matrix-field   button-press   *              right-button   select-unique
             *              button-press   (meta shift)   middle         help
            ___________________________________________________________________________

           |
           |
           |
           |
           |
           |
           |
           |






                         |
                         |
                         |
                         |
                         |
                         |
                         |
                         |






                                        |
                                        |
                                        |
                                        |
                                        |
                                        |
                                        |
                                        |






                                                       |
                                                       |
                                                       |
                                                       |
                                                       |
                                                       |
                                                       |
                                                       |






                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |
                                                                      |






                                                                                      |
                                                                                      |
                                                                                      |
                                                                                      |
                                                                                      |
                                                                                      |
                                                                                      |
                                                                                      |










                         This is  the  corresponding  picasso-defaults
                         file for the preceding set of event-defaults:


                          text-widget.key-press.control.k:        kill-line
                          text-widget.key-press.control.K:        kill-line
                          matrix-field.button-press.*:            select-unique
                          matrix-field.button-press.*.right-button:   select-multiple

                          # global help facility (same for all widgets)
                          *.button-press.(meta shift):middle-button:  help



                         Notice that the _h_a_n_d_l_e_r kill-line _m_a_p_s _t_o _t_w_o
                         _d_i_f_f_e_r_e_n_t _t_y_p_e_s _o_f _e_v_e_n_t_s.  _S_p_e_c_i_f_y_i_n_g _m_u_l_t_i_-
                         _p_l_e _m_a_p_p_i_n_g_s _w_i_t_h _t_h_e _s_a_m_e _h_a_n_d_l_e_r  _i_s  _f_i_n_e.
                         _H_o_w_e_v_e_r,  _s_p_e_c_i_f_y_i_n_g  _t_h_e  _s_a_m_e _m_a_p_p_i_n_g _t_w_i_c_e
                         (_w_i_t_h _a _d_i_f_f_e_r_e_n_t _h_a_n_d_l_e_r) _h_a_s  _u_n_p_r_e_d_i_c_t_a_b_l_e
                         _r_e_s_u_l_t_s.   _F_o_r  _t_h_e  _t_w_o  _m_a_p_p_i_n_g_s _o_n _m_a_t_r_i_x-
                         _f_i_e_l_d, _t_h_e _m_o_r_e  _s_p_e_c_i_f_i_c  _m_a_p_p_i_n_g  _h_a_s  _p_r_e_-
                         _c_e_d_e_n_c_e.    _H_e_n_c_e,  _i_f  _t_h_e  _r_i_g_h_t-_b_u_t_t_o_n  _i_s
                         _c_l_i_c_k_e_d  _o_n  _a  _m_a_t_r_i_x-_f_i_e_l_d,   _t_h_e   _s_e_l_e_c_t-
                         _m_u_l_t_i_p_l_e  _h_a_n_d_l_e_r  _w_i_l_l  _b_e  _c_a_l_l_e_d.   _I_f _a_n_y
                         _o_t_h_e_r  _b_u_t_t_o_n  _i_s  _c_l_i_c_k_e_d  _i_n  _t_h_e   _m_a_t_r_i_x,
                         _s_e_l_e_c_t-_u_n_i_q_u_e _w_i_l_l _b_e _c_a_l_l_e_d.
          ____________________________________________________________________________________________________________________________________________________________________________________

          Requesting
          Defaults




                         While both the user  and  system  can  select
                         defaults,   the requests will only by honored
                         if the widget itself  requests  the  default.
                         Currently,  defaults  that are requested from
                         the widget  code  include  background,  fore-
                         ground,  and font for all windows.  Also, all
                         event defaults are automatically requested.



          PICASSO Reference Manual                              18-261







                                                              DEFAULTS


                         To request a default, the following  function
                         is used.

                     get-default

                                                            [_F_u_n_c_t_i_o_n]
                         _o_b_j_e_c_t
                         _a_t_t_r_i_b_u_t_e
                         &key
                         _b_w-_p
                         gets the default from  the  _r_e_s_o_u_r_c_e-_d_a_t_a_b_a_s_e
                         that  most  closely matches _o_b_j_e_c_t and _a_t_t_r_i_-
                         _b_u_t_e.  Defaults are retrieved in a hierarchi-
                         cal  fashion,  as  described in the last sec-
                         tion.  _o_b_j_e_c_t is of type (member (pcl::object
                         pcl::class stringable nil)).  _I_f _o_b_j_e_c_t _i_s _a_n
                         _o_b_j_e_c_t, _i_t _i_s _c_o_n_v_e_r_t_e_d _i_n_t_o  _t_h_e  _c_l_a_s_s-_n_a_m_e
                         _o_f  _t_h_e  _o_b_j_e_c_t.  _I_f _o_b_j_e_c_t _i_s _a _c_l_a_s_s, _i_t _i_s
                         _c_o_n_v_e_r_t_e_d _i_n_t_o _t_h_e _n_a_m_e  _o_f  _t_h_e  _c_l_a_s_s.   _I_f
                         _n_i_l,  _o_b_j_e_c_t  _m_a_t_c_h_e_s  _a_n_y _c_l_a_s_s _i_n _t_h_e _d_a_t_a_-
                         _b_a_s_e. _a_t_t_r_i_b_u_t_e  _i_s  _e_i_t_h_e_r  _a  _s_i_n_g_l_e  _f_i_e_l_d
                         (_s_t_r_i_n_g_a_b_l_e)  _o_r  _a  _l_i_s_t  _o_f  _f_i_e_l_d_s.   _T_h_e,
                         _o_b_j_e_c_t _a_n_d _a_t_t_r_i_b_u_t_e _a_r_e _a_p_p_e_n_d_e_d _t_o _f_o_r_m _t_h_e
                         _d_e_f_a_u_l_t-_r_e_q_u_e_s_t.   _F_i_n_a_l_l_y, _g_e_t-_d_e_f_a_u_l_t _l_o_o_k_s
                         _u_p _t_h_e _d_e_f_a_u_l_t-_r_e_q_u_e_s_t _a_n_d _r_e_t_u_r_n_s _t_h_e  _v_a_l_u_e
                         _c_o_r_r_e_s_p_o_n_d_i_n_g   _t_o   _t_h_e   _c_l_o_s_e_s_t   _m_a_t_c_h_i_n_g
                         _d_e_f_a_u_l_t-_s_p_e_c.  _g_e_t-_d_e_f_a_u_l_t _t_a_k_e_s _i_n_t_o _a_c_c_o_u_n_t
                         _i_f  _i_t  _i_s _a _c_o_l_o_r _o_r _m_o_n_o_c_h_r_o_m_e _d_i_s_p_l_a_y.  _I_f
                         _i_t _i_s _a _m_o_n_o_c_h_r_o_m_e _d_i_s_p_l_a_y, _g_e_t-_d_e_f_a_u_l_t _l_o_o_k_s
                         _f_o_r _t_h_e _s_p_e_c_i_f_i_e_d _d_e_f_a_u_l_t _w_i_t_h _t_h_e "_b&_w" _s_u_f_-
                         _f_i_x _i_n _t_h_e _d_e_f_a_u_l_t_s _d_a_t_a_b_a_s_e.  _I_f _t_h_e_r_e _i_s _n_o
                         _c_o_r_r_e_s_p_o_n_d_i_n_g  _d_e_f_a_u_l_t,  _t_h_e  _r_e_g_u_l_a_r _d_e_f_a_u_l_t
                         (_w_i_t_h_o_u_t  _t_h_e  _s_u_f_f_i_x)   _i_s   _l_o_o_k_e_d-_u_p   _a_n_d
                         _r_e_t_u_r_n_e_d.   _I_f  _b_w-_p  _i_s _n_o_n-_n_i_l, _g_e_t-_d_e_f_a_u_l_t
                         _f_o_r_c_e_s _a _m_o_n_o_c_h_r_o_m_e _d_i_s_p_l_a_y _l_o_o_k_u_p.  _I_n  _t_h_i_s
                         _c_a_s_e,  _i_f  _n_o  _d_e_f_a_u_l_t _w_a_s _f_o_u_n_d, _g_e_t-_d_e_f_a_u_l_t
                         _r_e_t_u_r_n_s _n_i_l (_i_t _d_o_e_s  _n_o_t  _l_o_o_k_u_p  _t_h_e  _c_o_l_o_r
                         _d_e_f_a_u_l_t).

                         Following is an example of the  way  defaults
                         are requested.

                         picasso-defaults file:














          PICASSO Reference Manual                              18-262







                                                              DEFAULTS



                          *.font:                8x13
                          text-gadget.font:      6x10
                          *.background.b&w:      White
                          *.background:          Orange

                          # defaults for demo-tool
                          demo-tool.frame1.panel2.entry3.background.b&w: Black
                          demo-tool.frame1.panel2.entry3.background: BrightGreen
                          demo-tool.frame1.*.background: Purple



                         sample requests:


                          --> (get-default _a-_b_u_t_t_o_n "font")
                          "8x13"
                          --> (get-default "button" "font")
                          "8x13"
                          --> (get-default _a-_t_e_x_t-_w_i_d_g_e_t "font")
                          "6x10"


                          --> (color-display-p)
                          T
                          --> (get-default "demo-tool"
                                  '("frame1" "panel2" "entry3" "background"))
                          "BrightGreen"
                          --> (get-default "demo-tool"
                                  '("frame1" "panel2" "entry4" "background"))
                          "Purple"
                          --> (get-default "demo-tool"
                                  '("frame2" "panel2" "entry4" "background"))
                          "Orange"


                          --> (color-display-p)
                          NIL
                          --> (get-default "demo-tool"
                                  '("frame1" "panel2" "entry3" "background"))
                          "Black"
                          --> (get-default "demo-tool"
                                  '("frame1" "panel2" "entry4" "background"))
                          "Purple"
                          --> (get-default "demo-tool"
                                  '("frame2" "panel2" "entry4" "background"))
                          "White"







          PICASSO Reference Manual                              18-263







                                                              DEFAULTS


          ____________________________________________________________________________________________________________________________________________________________________________________

          Utilities


                         Here are a couple useful utilities for manag-
                         ing defaults:

                     load-defaults

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_e_r_a_s_e-_o_l_d _t)
                         reload all  system  and  user-level  defaults
                         from the appropriate files.  The system-level
                         default-file is  specified  by  the  variable
                         *picasso-defaults-path      (defaults      to
                         ~picasso/lib/picasso-defaults).   The   user-
                         level defaults file is specified by the vari-
                         able   *user-defaults-path*   (defaults    to
                         ~/.picasso-defaults).    When   _e_r_a_s_e-_o_l_d  is
                         non-nil, the current defaults that were  pre-
                         viously  loaded in are discarded.  Otherwise,
                         the new defaults are added  to  the  previous
                         ones.

                     clean-event-mapping

                                                            [_F_u_n_c_t_i_o_n]
                         &key
                         (_w_i_d_g_e_t_s _n_i_l)
                         clear default  event-mappings  for  specified
                         _w_i_d_g_e_t_s.  This function should only be called
                         if there is a default  event-mapping  (previ-
                         ously  loaded  in)  that needs to be removed.
                         Usually, load-defaults _i_s _c_a_l_l_e_d _f_o_l_l_o_w_i_n_g  _a
                         _c_a_l_l   _t_o  _c_l_e_a_n-_e_v_e_n_t-_m_a_p_p_i_n_g.   _w_i_d_g_e_t_s  is
                         either nil, _a _s_y_m_b_o_l, _o_r _a _l_i_s_t  _o_f  _s_y_m_b_o_l_s.
                         _W_h_e_n  _w_i_d_g_e_t_s  _i_s  _n_i_l,  _t_h_e  _e_n_t_i_r_e  _s_e_t  _o_f
                         _d_e_f_a_u_l_t _e_v_e_n_t-_m_a_p_p_i_n_g_s _f_o_r  _t_h_e  _t_o_o_l_k_i_t  _a_r_e
                         _c_l_e_a_r_e_d.   _W_h_e_n  _w_i_d_g_e_t_s  _i_s  _a  _s_y_m_b_o_l  (_e_g.
                         '_t_e_x_t-_w_i_d_g_e_t), _t_h_e _d_e_f_a_u_l_t _e_v_e_n_t-_m_a_p_p_i_n_g_s _f_o_r
                         _t_h_e  _w_i_d_g_e_t  _c_o_r_r_e_s_p_o_n_d_i_n_g _t_o _t_h_a_t _s_y_m_b_o_l _a_r_e
                         _c_l_e_a_r_e_d.  _W_h_e_n _w_i_d_g_e_t_s _i_s _a _l_i_s_t _o_f  _s_y_m_b_o_l_s,
                         _t_h_e  _d_e_f_a_u_l_t  _e_v_e_n_t-_m_a_p_p_i_n_g_s  _f_o_r _t_h_e _w_i_d_g_e_t_s
                         _c_o_r_r_e_s_p_o_n_d_i_n_g _t_o _e_a_c_h _o_f _t_h_e _s_y_m_b_o_l_s  _i_n  _t_h_e
                         _l_i_s_t  _a_r_e  _c_l_e_a_r_e_d.   _C_l_e_a_r_i_n_g _d_e_f_a_u_l_t _e_v_e_n_t-
                         _m_a_p_p_i_n_g_s _h_a_s _n_o _e_f_f_e_c_t _o_n _t_h_e _c_u_r_r_e_n_t  _e_v_e_n_t-
                         _m_a_p_p_i_n_g_s.    _T_o  _c_h_a_n_g_e  _t_h_e  _c_u_r_r_e_n_t  _e_v_e_n_t-
                         _m_a_p_p_i_n_g_s, _u_s_e _m_a_k_e-_c_l_a_s_s-_e_v_e_n_t-_m_a_p.

                     make-class-event-map

                                                            [_F_u_n_c_t_i_o_n]
                         _w_i_n_d_o_w
                         recreate the class level  event-mappings  for
                         the  specified _w_i_n_d_o_w from the default event-
                         mappings.  _w_i_n_d_o_w should be an instance of an
                         _x-_w_i_n_d_o_w (or subclass).




          PICASSO Reference Manual                              18-264







                                                            REFERENCES


                                              19
                                          REFERENCES


                              D. Charness and  L.  Rowe,  _C_L_I_N_G/_S_Q_L  -
                              _C_o_m_m_o_n  _L_I_S_P  _t_o  _I_N_G_R_E_S/_S_Q_L  _I_n_t_e_r_f_a_c_e,
                              Computer Science Division -  EECS,  U.C.
                              Berkeley, Dec. 1989.

                              A.    Goldberg,    _S_m_a_l_l_t_a_l_k-_8_0:     _T_h_e
                              _I_n_t_e_r_a_c_t_i_v_e   _P_r_o_g_r_a_m_m_i_n_g   _E_n_v_i_r_o_n_m_e_n_t,
                              Addison Wesley, Reading, MA, May 1983.

                              S. Keene, _O_b_j_e_c_t-_O_r_i_e_n_t_e_d _P_r_o_g_r_a_m_m_i_n_g _i_n
                              _C_o_m_m_o_n _L_i_s_p, Addison-Wesley, 1988.

                              M. A. Linton, "Composing User Interfaces
                              with  InterViews",  _I_E_E_E  _C_o_m_p_u_t_e_r, Feb.
                              1989.

                              B. Myers and et. al., _T_h_e _G_a_r_n_e_t _T_o_o_l_k_i_t
                              _R_e_f_e_r_e_n_c_e  _M_a_n_u_a_l_s:  _S_u_p_p_o_r_t  _f_o_r _H_i_g_h_l_y
                              _I_n_t_e_r_a_c_t_i_v_e, _G_r_a_p_h_i_c_a_l  _U_s_e_r  _I_n_t_e_r_f_a_c_e_s
                              _i_n    _L_i_s_p,    Technical   Report   CMU,
                              Pittsburgh,   PA-CS-89-196,    Carnegie-
                              Mellon University, Nov. 1989.

                              L. A. Rowe, J.  Konstan,  B.  Smith,  S.
                              Seitz    and   C.   Liu,   _T_h_e   PICASSO
                              _A_p_p_l_i_c_a_t_i_o_n _F_r_a_m_e_w_o_r_k, Computer  Science
                              Division  -  EECS,  U.C.  Berkeley,  May
                              1990.

                              R. W. Scheifler and J.  Gettys,  "The  X
                              Window  System",  _A_C_M _T_r_a_n_s. _o_n _G_r_a_p_h_i_c_s
                              _5, 2 (Apr. 1986).

                              R.  W.  Scheifler  and  O.  LaMott,  _C_L_X
                              _P_r_o_g_r_a_m_m_e_r'_s       _R_e_f_e_r_e_n_c_e,      Texas
                              Instruments, 1989.

                              K. J. Schmucker, "MacApp: An Application
                              Framework", _B_y_t_e, Aug. 1986.

                              S. Seitz, _W_i_d_g_e_t _W_r_i_t_e_r_s _G_u_i_d_e, Computer
                              Science  Division - EECS, U.C. Berkeley,
                              June 1990.

                              S. Wensel, "POSTGRES Reference  Manual",
                              _E_l_e_c_t_r_o_n_i_c_s   _R_e_s_e_a_r_c_h   _L_a_b.  _T_e_c_h_n_i_c_a_l
                              _R_e_p_o_r_t _M_8_8/_2_0 (_R_e_v_i_s_e_d), Apr. 1989.




          PICASSO Reference Manual                              19-265










                               Table of Contents


          Chapter 1:  INTRODUCTION
             Overview ...........................................  1-2
             What is PICASSO?  ..................................  1-2
             Why Use PICASSO ....................................  1-4
             About this manual ..................................  1-4
          Chapter 2:  WINDOWS
             Overview ...........................................  2-7
             Windows ............................................  2-8
             Window Management .................................. 2-19
             X-windows .......................................... 2-24
             Opaque Windows ..................................... 2-28
          Chapter 3:  RESOURCES
             Overview ........................................... 3-29
             Colors and Colormaps ............................... 3-31
             Images ............................................. 3-34
             Cursors ............................................ 3-36
             Tiles .............................................. 3-37
             Icons .............................................. 3-39
             Fonts .............................................. 3-40
             Displays ........................................... 3-42
             Screen ............................................. 3-43
             Graphics Contexts .................................. 3-44
          Chapter 4:  APPLICATION FRAMEWORK
             Overview ........................................... 4-45
             PO Persistence and Naming .......................... 4-46
             Argument Passing ................................... 4-50
             Tools .............................................. 4-52
             Forms .............................................. 4-59
             Callable PO's ...................................... 4-64
             Frames ............................................. 4-66
             Dialog Boxes ....................................... 4-69
             Panels ............................................. 4-72
          Chapter 5:  PICASSO DATA MODEL
             Overview ........................................... 5-76
             Variables .......................................... 5-76
             Constants .......................................... 5-77
             Referencing Variables and Constants ................ 5-79
             Databases .......................................... 5-81
          Chapter 6:  PROPAGATION AND TRIGGERS
             Overview ........................................... 6-87
             Bindings ........................................... 6-87
             Triggers ...........................................6-100
             Lazy Evaluation ....................................6-103
          Chapter 7:  COLLECTIONS
             Overview ...........................................7-106
             Collections ........................................7-106
             Anchor-GM ..........................................7-112
             Packed-GM ..........................................7-115
             Stacked-GM .........................................7-118



          PICASSO Reference Manual                                   i







                                                     TABLE OF CONTENTS


             Matrix-GM ..........................................7-119
             Null-GM and Root-GM ................................7-120
          Chapter 8:  WIDGETS AND GADGETS
             Overview ...........................................8-123
             Gadgets ............................................8-123
             Widgets ............................................8-124
             Synthetic    Gadgets ...............................8-125
             Borders ............................................8-126
             Labels .............................................8-129
          Chapter 9:  TEXT
             Overview ...........................................9-132
             Text Gadget ........................................9-132
             Buffer .............................................9-135
             Text Buffer Gadget .................................9-137
             Text Widget ........................................9-141
             Scrolling Text Widget ..............................9-143
             Entry Widget .......................................9-144
             Num Entry ..........................................9-144
          Chapter 10:  BUTTONS
             Overview ...........................................10-146
             Buttons ............................................10-146
             Gray Buttons .......................................10-149
             Pop Buttons ........................................10-151
             Gray Pop Buttons ...................................10-152
             Click Buttons ......................................10-153
             Button Groups ......................................10-154
             Radio Button Groups ................................10-156
             Check Button Groups ................................10-157
             Implicit Buttons ...................................10-158
          Chapter 11:  CONTROLS
             Overview ...........................................11-159
             Scroll Bars ........................................11-159
          Chapter 12:  IMAGES
             Overview ...........................................12-169
             Image Gadget .......................................12-169
          Chapter 13:  MENUS
             Overview ...........................................13-173
             Menu Bars ..........................................13-173
             Menu Entries .......................................13-174
             Menu Panes .........................................13-177
             Menu Buttons .......................................13-178
             Menu Interaction ...................................13-179
             Implicit Menus .....................................13-180
          Chapter 14:  TABLES
             Overview ...........................................14-182
             Browse Widgets .....................................14-182
             Matrix-Field .......................................14-186
             Table-Field ........................................14-206
             List-Box ...........................................14-211
          Chapter 15:  GRAPHICS
             Overview ...........................................15-214
             Graphic Gadgets ....................................15-214



          PICASSO Reference Manual                                  ii







                                                     TABLE OF CONTENTS


             Graphic Browsers ...................................15-237
          Chapter 16:  APPLICATION-SPECIFIC WIDGETS
             Overview ...........................................16-242
             Meter Widget .......................................16-242
             Qual Widget ........................................16-244
             Plot Widget ........................................16-246
          Chapter 17:  LIBRARY PICASSO OBJECTS
             Overview ...........................................17-250
             Library Panels and Dialogs .........................17-250
             Facility Manager Tool ..............................17-252
             Tool Editor ........................................17-253
             Robbie the Robot Tool ..............................17-253
             Widgets at an Exhibition Tool ......................17-254
             Employee/ Department Browser .......................17-255
          Chapter 18:  DEFAULTS
             Overview ...........................................18-257
             Selecting Defaults .................................18-258
             Requesting Defaults ................................18-261
             Utilities ..........................................18-264
          Chapter 19:  REFERENCES
          Function Index:  ......................................index-1


































          PICASSO Reference Manual                                 iii



