XEROX INTERIM CLOS BROWSER 2 4 1 INTERIM CLOS BROWSER 1 4 By: Ramana Rao (Rao.pa@Xerox.com) and Kirk Kelley (Kelley.pa@Xerox.com) NOTE: This lispusers package contains many unimplemented features that cause harmless break windows. These features are the ones crossed out in the documentation below. Module Dependencies: PCL Grapher SEdit The CLOS-browser loads WEB-EDITOR and ED-PATCH. 1 Introduction CLOS, the Common Lisp Object System, provides a standard way to write object-oriented programs using extensions to Common Lisp. See the PCL documentation and Committee X3J13 Documents 87-006 and 87-007 available from the ANSI X3 Secretariat. One of the key components in CLOS is inheritance, in which structures have well-defined relationships to other structures. Class inheritance is a typical example of this relationship. Since inheritance can be described by a two-dimensional graph, it is natural to create a user interface for CLOS built on the Lisp Library module Grapher. This user interface is called a browser. Browsers are tools to assist in the development cycle of a product or vehicles for building user interfaces within a final product. Much development time is spent building, examining, and modifying the relationships between classes. These tasks include specifying the contents of various classes: class variables, instance variables, properties, and methods. The location of the class within the inheritance structure must also be determined. After a number of classes have been built, the relationships between the classes may need to be reviewed. Often, the initial design is flawed and requires the following changes: f Moving parts of one class to another class. f Adding, substracting, or changing data or functionality within classes. f Adding new classes, or merging different classes. The CLOS browser is the facility which support these types of operations. This document describes how to use the CLOS browser interactively with the mouse to browse classes. The design of the CLOS-browser is based on that of the LOOPS class browser, developed at the Knowledge Systems Area of the Xerox PARC Intelligent Systems Lab. For those familiar with the LOOPS class browser, see the Appendix for an overview of the differences in the CLOS browser. Browsers are most commonly used on the classes defined for an application. Some of the examples here browse objects which Xerox CLOS uses internally; the functionality is exactly the same. A CLOS browser shows the linkages between a CLOS class or classes and their subclasses. Super classes are shown on the left (or top) side of the browser window. Subclasses of these are connected by links moving to the right (or down). NOTE: Crossed through items represent features that are not implemented. 2 Opening Browsers A CLOS browser can be opened in the following ways: f Selecting a menu option from the Background Menu. f Using the xcl:browse-class function giving it the name of the class. For example, in the XCL exec, (browse-class 't) will, after a few seconds, ask you to position a browser of all the classes in your system. f Using the web:browse method on an instance of a clos-browser. 2.1 Background menu When the CLOS browser is loaded, the option CLOS browser is added to the background menu. Selecting it causes the following prompt to appear in a prompt window: Please tell me the name of the root class > Enter the name of a class. The system builds the appropriate type of browser and prompts you to indicate a position to place it. 2.2 Functions to open browsers When the CLOS-browser is loaded, it loads the web-editor. Symbols in both the CLOS-browser and the web-editor are interned in the web-editor package (nicknamed web). The xcl package is told to use the web-editor package. Thus making the following function available from the XCL exec window. (web:browse-class class-name-or-list &KEY :direction :window-or-title :good-classes :position) [Function] Purpose/Behavior: Opens a class-browser on a class showing its inheritance relationships to sub-classes. Arguments: class-name-or-list A symbol naming the class or a list of symbols for additional classes to appear as roots in the browser. :direction :subs or :supers. Default is :subs. :window-or-title A title to appear on the browser or a window to use (but which will be reshaped to fit the browser). Title defaults to "CLOS browser". :good-classes A list of clases other than class-name. (for future use, not implemented) :position Lower left corner of browser. If NIL, position the window with the mouse. Returns: A pointer to the browser. Examples: The following command opens a class browser on all the classes of numbers. (browse-class 'number) The following command opens a class browser with two root-nodes. One for the web-editor class and the other for the web-node class. (browse-class '(web::web-editor web::web-node)) (web:browse browser &optional browse-list window-or-title good-classes position) [Method on web-editor] Purpose/Behavior: Opens a browser, of a specific type that has already been created, showing inheritance relationships between an arbitrary set of classes. Arguments: browser An instance of clos-browser. &OPTIONAL browse-list A class name, a pointer to a class, or a list of those. window-or-title A title to appear on the browser or a window to use (but which will be reshaped to fit the browser). Title defaults to "CLOS browser". good-classes A list of classes other than class-name. (for future use, not implemented) position Lower left corner of browser. If NIL, position the window with the mouse. Returns: Pointer to the browser object. Example: The following command opens a class browser on all the classes of numbers. (browse (make-instance 'clos-browser) 'number) 3 Using Class Browsers This section shows examples of the various menus followed by descriptions of the actions performed after selecting particular options. Three areas of the browser are active. f The title bar menu manipulates the browser as a whole. f The Node left button menu manipulates the node and the Node MIddle button menu manipulates the class represented by the node. f The Browser background manipulates the browser as a whole. 3.1 Title Bar Menu Clicking in the title bar menu with the left or middle mouse button pops up a menu of three items: Recompute  @ P(T(P @ Browser looks  @ P(T(P @ Add root 3.1.1 Recompute and its Suboptions Pulling across to the right of Recompute produces the following suboptions: Recompute Recompute labels Recompute in place Recompute Recomputes the entire browser structure from the starting objects. It does not recompute the labels for each item if those labels have been cached, which is in an instance variable for this browser. Recompute labels Recomputes the entire browser structure from the starting objects and recomputes the labels for each item. Recompute in place Recomputes the browser without affecting the scrolled location of the lattice within the window. This may be necessary for a browser containing a large lattice structure. 3.1.1 Browser looks and its Suboptions Shape to hold Makes the window for the browser just large enough to hold all of the nodes in the browser, up to a maximum size. Browser windows may also be changed interactively or programmatically with SHAPEW. Change font size Causes a menu to appear containing 8, 10, 12, and 16. Selecting one changes the font size used to display the nodes to that value. Change format Causes the following menu to appear: 2C CD"# D$H PPHH P!PHHH !HH( AHD""!D$C!CO<HAB@A @A ~A @A @AHAB@AOA<C D"# !@H P!@H P !~HH !@H( @!@D""!!@C!!OߏHAHA HA OA A HAHHAOO Using the example of (browse-supers (class-named CLOS-browser) this browser is drawn for each of the formatting options. A tree does not show branches recombining; a lattice does. A boxed node in a tree indicates the node shows up in more than one location in a tree. When a browser is constructed by the system the default formatting style is HORIZONTAL/LATTICE. 3.1.2 Add root Add root A prompt appears in an attached window to enter the name of a class to be added to the browser. If the entered item is not an object, a message that nothing was added to the browser is printed. If the entered item is already in the browser, nothing occurs. If the entered name does not correspond to a class, a break occurs. Save value The browser instance is stored in the value of IL:IT and CL:* . Unhide node Objects within a browser can be put on the instance variable bad-list. This can be done by positioning the mouse on the node in a browser, pressing the left mouse button, and selecting an option from the menu that appears. Items on the bad-list are not displayed in the browser. If you select the option RemoveFromBadList, a menu appears showing any objects on the bad-list. Selecting one of those objects removes it from the bad-list and causes it to be redisplayed in the browser. 3.2 Node Left Button Using the left mouse button on a node in a browser manipulates the node representing that class. When the mouse is inside of a browser and you hold down the left mouse button, nodes within the browser become inverted when the cursor moves over them. When you release the mouse button over an inverted node, the node is selected to be the target of a copy or move. This is like placing the caret in text except a box is drawn around the node. You may use editing keys while making a selection. The editing keys are: f The COPY (or SHIFT) key: which causes the name of the class to be typed into the current type-in point. (See also: Browser background COPY selection) f The Control (CTRL) key: which hides the node. Pressing the CTRL key while selecting a node with the left button allows you to delete the node representing the class from the browser. It adds it to the browser's bad-list. If a class on the bad-list has subclasses, these are made into roots. To redisplay a class once it has been deleted, use RemoveFromBadList in the title bar AddRoot pull across menu. Using CTRL while holding down on the middle mouse button does the same but also adds all of the classes subclasses to the bad-list so the whole sub-tree is hidden. f The MOVE (or CTRL and SHIFT) key(s): which temporarily changes the layout of the nodes in the graph. Pressing the MOVE key while selecting a node with the left button causes the node to track movement by the cursor. This allows you to temporarily change the layout of the nodes in the graph. The next update of the browser recomputes new node positions. 3.3 Node Middle Button When the mouse is inside of a browser and you hold down the middle mouse button if you are pointing to a node the following menu appears: Edit  @ P(T(P @ Add method Browse  @ P(T(P @ Print  @ P(T(P @ Make instance Specialize -------------- slots methods  @ P(T(P @ The items shown in the menu operate on the class selected. The actions that occur as a result of selecting one of these items are described in the following subsections. Edit Selecting the Edit item brings up an editor on the definition of the class. Dragging to the right of the edit item produces the following menu: Inspect Inspect causes an Inspect window to open on the class object (instance of its meta-class). Add method Creates a defmethod template containing the class as a specializer and brings up an editor on the template. Browse Selecting the Browse item creates a browser of the sub-classes of the class. The submenu items for Browse are: sub classes super classes The sub classes item creates a browser of the sub-classes of the class. The super classes item creates a browser of the super classes of the class. Print Selecting the print item causes the definition of the class to be printed. Describe Prints the description of the class. Equivalent to calling the describe function on that class' name. Pulling across reveals the Print and Documentation options. Documentation Prints the documentation string of the class. Equivalent to calling the documentation function on that class' name. Make instance Creates a new instance of this class by calling make-instance. Calls put-saved-value with the new instance as an argument, and prints the instance. Specialize Defines a subclass of this class. This subclass is initialized with no locally defined slots. You are prompted to give a name for the new class. The new class is added to the browser. ------------ The items below the dash in the node middle menu, produce a second menu of the corresponding objects: local methods, inherited methods, or all methods, for that class. The "Add method" item at the top of the second menu will bring up an editor containing a template for adding a method to that class. At the bottom of the menu is the item "Fix menu" which, if selected, allows you to place the menu of the objects on the screen. Fixed menues are not maintained dynamically and may be out of date. slots Selecting the slots item brings up an editor on the definition of the class. The print level of the class definition is clipped so as to just show the lines containing the slot names. methods Selecting the methods item pops up a menu of the local methods defined on this class. Selecting one of these methods will bring up an editor on the definition of the method. Selecting the pull-across methods item pops up the following menu: local inherited all Selecting local produces the menu of local methods defined on the class. Selecting inherited produces a menu of just the methods that are inherited by this class. The method names appear in the font on (slot-value a-clos-browser-node 'web::method-menu-font), a value shared by all instances of clos-browser-node. left mouse button To edit the method, just select the name in the menu with the left mouse button. methods local middle mouse button Selecting a local method name with the middle mouse button pops up the following menu. Edit  @ P(T(P @Inspect Copy Print  @ P(T(P @Print Delete Describe Move Documentation Rename Break Trace Unbreak Edit Selecting Edit brings up an editor on the definition of the method. Copy Selecting Copy adds the method to the class represented by the boxed node. This is done by changing the method's definition to replace all occurances of the old class name in the specializer list by the name of the boxed class. Inspect Selecting Inspect brings up an inspector on the method object, an instance of the method class. Print Selecting Print pretty prints the definition of the method. Describe Selecting Describe prints a description of the method. Documentation Selecting Documentation prints the documentation string of the method. Delete Selecting Delete calls remove-method on the method and its generic function. Move Selecting Move first copies the method to the class represented by the boxed node, then delete is called on the old method. Rename Selecting Rename prompts you for the name of a new generic function for this method. It then changes the name of the generic function on which this method is defined to the one you named. This is done by editing the method's definition and replacing its name with the new name. Then delete is called on the old method. Break Selecting Break causes break-method to be called on the method. Trace Selecting Trace causes trace-method to be called on the method. Unbreak Selecting Unbreak causes unbreak-method to be called on the method. methods inherited middle mouse button Selecting an inherited method name with the middle mouse button pops up the following menu. Edit  @ P(T(P @Inspect Describe  @ P(T(P @Print Specialize Break Trace Unbreak Who owns These are the same as for local methods except Copy, Delete, Move, and Rename are not available. Instead, Specialize and Who owns are present. Specialize Selecting Specialize brings up an editor on the definition of a new method with the same name as the inherited method except this class replaces the owner of the method everywhere it occurs in the specializer list. Who owns Selecting Who owns displays the names of the classes on which this method is defined. 3.4 Browser background COPY selection If a node is not selected, but the cursor is in the background of the browser while holding down on the COPY or SHIFT button, the entire graph is copied. This can be used to insert browser images into TEdit documents, for example. See the Lisp Library documentation on Grapher for more details Appendix The CLOS browser differs from the LOOPS class browser mostly in minor details until it comes down to what functions are on the node left mouse button and node middle mouse button. Here essentially all the commands have been moved off of the node left button to the node middle button and they are available when the mouse button goes down. This makes remembering which button to push easier, but some actions (e.g. delete method) slightly harder. A general goal is to have 1. the left mouse button manipulate the node. 2. the middle mouse button operate on the class represented by the node. Thus in this design, the edit keys (DELETE/CTRL, COPY/SHIFT, & MOVE) used with the left mouse button operate on the node but not the class. Just clicking on a node with left mouse button, without the edit keys, boxes the node (same as BoxNode in LOOPS). The middle button pops up the following menu: Edit  @ P(T(P @ Add method Browse  @ P(T(P @ Print  @ P(T(P @ Make instance Specialize -------------- slots methods  @ P(T(P @ The items above the line operate directly on the entire class represented by the node and, where appropriate, all of the class' slots and methods as a group. The items below the line allow operating on specific slots or methods. The menu above with sub-menus expanded: Edit  @PP@ Edit Inspect Rename Delete Add method Browse  @PP@ sub classes super classes Print  @PP@ Print Describe Documentation Make instance Specialize -------------- slots methods  @PP@ local inherited all What the main menu items do: Edit brings up an editor on the defclass form plus a fixed menu of methods for that class (as described below) attached to the side of the editor window. Add method is here to provide a quick way to add a method (slot, etc.) that avoids bringing up the menu of existing ones. Just clicking on Add means Add method. Browse creates a new CLOS browser. Describe prints a description of the class and all of its methods. Specialize allows adding a new class as a sub-class of this one. -------------- Clicking on slots without using the sub-menu brings up an SEdit of the class definition. Thus it is like Edit except avoids generating the attached menu of methods. Clicking on one of slots' local/inherited/all submenu items, produces a menu of the indicated slot names. Clicking on methods or any of its sub-menus pops up a menu of methods defined on this class. slots and methods menus At the bottom of the list of slots or methods is the item *Fix menu* which, if selected, allows you to place the menu on the screen. Selecting an item in a slots or methods menu with the left button brings up an editor on that item. Selecting an item with the middle button pops up the menu of operators appropriate for the object it names (e.g. Edit, Break, Unbreak, Trace, Copy, Describe, Delete, Move, Rename, or Who owns). (LIST ((PAGE NIL (PAPERSIZE LETTER STARTINGPAGE# 173) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO NIL) (174 36 288 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 528 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))) (PAGE NIL (PAPERSIZE NIL . LETTER) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO NIL) (174 36 288 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 528 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))) (PAGE NIL (PAPERSIZE NIL . LETTER) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO NIL) (174 36 288 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 528 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL)))))($ (((((8(8D PAGEHEADING RUNNINGHEAD+ 1 + ($ 4 4 .( ( HELVETICA  HELVETICA  HELVETICA G9(DEFAULTFONT 1 (HELVETICA 8) (HELVETICA 8) (HELVETICA 8)) TERMINAL  HELVETICA   HELVETICAMODERN  MODERN  MODERN  HELVETICA HELVETICA  HELVETICA G9(DEFAULTFONT 1 (HELVETICA 8) (HELVETICA 8) (HELVETICA 8))MODERNLOGO HELVETICA  HELVETICA MODERN MODERN TERMINAL MODERN ?1(DEFAULTFONT 1 (GACHA 10) (GACHA 8) (TERMINAL 8)) MODERN  HELVETICA HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN J     0 L - I 5G 4#9G@ , j -   '4 m l    & J $T2  1      8   & J )S0 ' ;   =  c  BMOBJ.GETFN3 BMOBJ.GETFN3  " L .   l &      %  BMOBJ.GETFN3 1 2  H  /       >   =  +  6  0    bJ     a     j  BMOBJ.GETFN3  BMOBJ.GETFN3 BMOBJ.GETFN3   BMOBJ.GETFN3ND\ l   : "   L g<u     5 Lj E S#W  BMOBJ.GETFN3  BMOBJ.GETFN3 7 P ,   &  1P 1 0 0 2& \   BMOBJ.GETFN3  BMOBJ.GETFN3   /              F %&  .I. BMOBJ.GETFN3  BMOBJ.GETFN3 BMOBJ.GETFN3  BMOBJ.GETFN3( BMOBJ.GETFN3$##   BMOBJ.GETFN3* BMOBJ.GETFN3%*   BMOBJ.GETFN3'!#CA]dSnz