REF GO_BASECLASSES Ben Rabau, Aug 93 COPYRIGHT Integral Solutions Ltd. 1993. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< GRAPHICAL OBJECT >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< BASE CLASSES >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< WARNING: This is the first version of a class library of graphical objects and is distributed with this release of Poplog for evaluation and comment. As a result of feedback and in the interests of better integration with Poplog, the facilities described may be modified. While all reasonable endeavours will be made to limit incompatible changes, programs which use these facilities may require modification to run on later versions. CONTENTS - (Use g to access required sections) -- go_screen_object -- go_shell -- go_screen_object --------------------------------------------------- go_screen_object; [class] isa go_colourable go_located; The class go_screen_object is one of the base classes in the Graphical Objects library and introduces visualisation. The screen objects will be visualised in one or more panes with a number of characteristics such as the line width and colours used. go_visible_in [slot] Default: == [] ; List of panes in which the object is visible (REF * GO_PANE). go_visible_now [slot] Default: == false ; True if drawn now, false if cleared, "forbidden" if in batch mode. go_fixed_image [slot] Default: == false ; Boolean for optimised dragging, true = use pixmap (REF * GO_XDRAG). stored_go_linewidth [slot] Default: == false ; Stored width of lines, if false use pane default. go_live_object [slot] Default: == false ; If false then take pane's mode, if true then always "live". go_editors [slot] Default: == [] ; This contains a list of the objects' editors if any. Global variable indicating whether an object is transparent to events, i.e. it gets the event but the event is also passed to underlying object(s). The default is not to be transparent, but this can be overruled upon return of the method go_accepts_events. Global variable indicating the objects to which an event is passed on. By default an object does not pass on events, so only one element is expected: that of the first object which accepts the event. If the object broadcasts the event to other objects then these objects can be added to this global variable (in the method go_accepts_events), or the global variable go_transparent_to_events can be set to true upon return of the method go_accepts_events in which case the search for objects which accept the event will continue as before. go_drag_outline [variable] Default: = false; Defines whether or not to drag just the box. If true, only the outline of the bounding box is drawn, the object itself is not shown. go_accepts_events( TYPE, RAW_EVENT_DATA, MOUSE_SENSITIVE ) -> BOOLEAN; [method] Returns whether or not this object accepts the event. By default this is FALSE. TYPE is one of "mouse" or "keyboard" RAW_EVENT_DATA is a vector (see REF * go_expand_event_data). SCREEN_OBJECT is a go_screen_object instance. go_redraw( SCREEN_OBJECT ); [method] Redraws the screen object and all the objects above it in the area occupied by the screen object. SCREEN_OBJECT is a go_screen_object instance. go_internal_redraw( SCREEN_OBJECT ); [method] Redraws the screen object and all the objects above it in the area occupied by the screen object. Since it does not redraw the objects below the screen object this is not safe to use unless the object was cleared just before (see REF * GO_SCREEN_OBJECT/go_clear). SCREEN_OBJECT is a go_screen_object instance. go_clear( SCREEN_OBJECT ); [method] Redraws all the objects below and above it in the area occupied by the screen object but not the screen object itself. This clears the object from the screen but does not physically remove if from any pane object. SCREEN_OBJECT is a go_screen_object instance. go_clear_bounding_box( SCREEN_OBJECT ); [method] Convenience function to clear a bounding box drawn with the method go_draw_bounding_box (see REF * GO_XDRAW). SCREEN_OBJECT is a go_screen_object instance. go_linewidth( SCREEN_OBJECT ) -> INTEGER_OR_FALSE; [method] Gets the line width in which the screen object is drawn on a pane. If false then the default from the pane itself is used (see also REF * GO_PANE). SCREEN_OBJECT is a go_screen_object instance. INTEGER_OR_FALSE -> go_linewidth( SCREEN_OBJECT ); [method updater] Sets the line width in which the screen object is drawn on a pane. If false then the default from the pane itself is used (see also REF * GO_PANE). SCREEN_OBJECT is a go_screen_object instance. go_applist( PROCEDURE, SCREEN_OBJECT ); [method] Apply the procedure to the screen object for each of the panes it is visible in (See also REF * APPLIST). The procedure needs to take the format: ( , ); PANE is an instance of the go_pane class. PROCEDURE is a Pop-11 procedure with two arguments (object and pane). SCREEN_OBJECT is a go_screen_object instance. go_update( SCREEN_OBJECT ); [method] Remove all cached screen coordinates. See also REF * GO_PANE/cached_go_coord_list SCREEN_OBJECT is a go_screen_object instance. go_update_and_draw( SCREEN_OBJECT ); [method] Remove all cached screen coordinates then redraw (which recalculates). SCREEN_OBJECT is a go_screen_object instance. LIST -> go_localcoords( SCREEN_OBJECT ); [method updater] LIST is the list of horizontal and vertical integer coordinates of points in the object's local coordinate system. SCREEN_OBJECT is a go_screen_object instance. INTEGER -> go_xorigin( SCREEN_OBJECT ); [method updater] The horizontal origin of the local coordinates of the object. SCREEN_OBJECT is a go_screen_object instance. INTEGER -> go_yorigin( SCREEN_OBJECT ); [method updater] The vertical origin of the local coordinates of the object. SCREEN_OBJECT is a go_screen_object instance. INTEGER -> go_xscale( SCREEN_OBJECT ); [method updater] Sets the horizontal scaling of the screen object which is reflected in the panes in which it is visible (see REF * GO_PANE, GO_LOCATED). SCREEN_OBJECT is a go_screen_object instance. INTEGER -> go_yscale( SCREEN_OBJECT ); [method updater] Sets the vertical scaling of the screen object which is reflected in the panes in which it is visible (see REF * GO_PANE, GO_LOCATED). SCREEN_OBJECT is a go_screen_object instance. go_origin_to( X, Y, SCREEN_OBJECT ); [method] Sets both horizontal and vertical origin of a located object. This is a convenience method using go_xorigin and go_yorigin. X and Y are world coordinates of the reference point. SCREEN_OBJECT is a go_screen_object instance. go_centre_to( X, Y, SCREEN_OBJECT ); [method] Move the centre point of the given screen object to the new location (in world coordinates). X and Y are world coordinates of the centre point. SCREEN_OBJECT is a go_screen_object instance. go_fgdraw( PANE, SCREEN_OBJECT ); [method] Draws the part of the screen object in the pane which is to be drawn in the foreground colour (see REF * GO_COLOURABLE/go_fgcolour). This typically represents the outline of an object. The default picture for a screen object is its bounding box although this will generate a warning at present (see also REF * GO_XDRAW/go_draw_bounding_box). PANE is an instance of the go_pane class. SCREEN_OBJECT is a go_screen_object instance. go_fgdraw( PANE, SCREEN_OBJECT ); [method] Draws the part of the screen object in the pane which is to be drawn in the background colour (see REF * GO_COLOURABLE/go_bgcolour). This typically represents the filling of an object (see REF * GO_FILLABLE). If no definition is given nothing is drawn although this will generate a warning at present. PANE is an instance of the go_pane class. SCREEN_OBJECT is a go_screen_object instance. go_find_occluded_list( BELOW, PANE, AREA, SCREEN_OBJECT ) [method] -> OBJECTS; This finds three lists of objects which are either below the screen object, on top of the screen object or editors on top of it. In some cases the objects below the screen object are not important which is indicated with the "BELOW" flag. If this is the case then the area searched will correspond to the screen object, otherwise the area is extended to its bounding box. BELOW is a boolean indicating if objects underneath are requested. PANE is an instance of the go_pane class. AREA is a go_area or a go_screen_object instance. SCREEN_OBJECT is a go_screen_object instance. OBJECTS is a tuple of three lists of located objects representing the objects below and those above and the editors above the screen object. go_safe_region( PANE, SCREEN_OBJECT ) -> (X, Y, W, H); [method] Returns a tuple with the screen region occupied by the screen object in the given pane. It includes a safety border which includes line width and space for editors if any (see REF * GO_EDITOR). PANE is an instance of the go_pane class. SCREEN_OBJECT is a go_screen_object instance. X and Y are screen coordinates of the bottom left corner of the region. W and H are the width and height in screen coordinates of the region. go_get_bounding_area( X, Y, W, H, PANE, SCREEN_OBJECT ) -> AREA;[method] Gets the area object which corresponds to the given size in screen coordinates. This is used to simplify calculations of complex objects by using the simplest object (an area) instead. The area returned is always the same and only its dimensions change. Care should be taken never to use this method recursively! PANE is an instance of the go_pane class. SCREEN_OBJECT is a go_screen_object instance. AREA is a unique instance of the go_area class. go_redraw_area( DRAW, BELOW, PANE, SCREEN_OBJECT ); [method] Redraws the area occupied by the screen object if requested by redrawing all the objects underneath the screen object, then if requested the screen object itself, then all the objects and editors on top of it. This is used by the go_redraw and go_clear methods. DRAW is a boolean indicating if the object itself needs to be drawn. BELOW is a boolean indicating if objects underneath are requested. PANE is an instance of the go_pane class. SCREEN_OBJECT is a go_screen_object instance. go_check_drag_limits( X, Y, SCREEN_OBJECT ) -> (X, Y); [method] Checks whether the new position of the centre point of the given screen object would keep it completely visible in the default pane. If the position would move the object (partially) outside the pane, then the nearest position inside the pane is returned. The default pane is the last created or activated pane (REF * GO_VARS/go_default_pane). This method can be redefined to increase or restrict the dragging movements allowed by a certain type of screen objects. SCREEN_OBJECT is a go_screen_object instance. go_draw_drag( CLIENT_DATA, SCREEN_OBJECT ); [method] Execute the drawing part when dragging a screen object. This will be executed whenever the object has changed. See also the slot go_fixed_image which optimised the drag operation by not calling this function when the object simply moves (see TEACH * GO_DRAG). The allowed positions of the object are controlled by the method: go_check_drag_limits (see REF * GO_SCREEN_OBJECT/go_check_drag_limits). The global variable go_drag_outline offers further optimisation: 1. If go_drag_filled is false then objects will be dragged over the screen without being filled and on top of every other object. 2. If go_drag_filled is true, a filled object will be filled and shown in its right screen depth even during dragging. When the drop occurs the "inDrag" flag in the client data will be set to false (see also REF * GO_XDRAG). This method is called from the go_drag method and should never be called directly. CLIENT_DATA is a structure containing information for dragging. SCREEN_OBJECT is a go_screen_object instance. go_draw_drag( CLIENT_DATA, SCREEN_OBJECT ); [method] Execute the cleaning part when dragging a screen object. This will be executed when the object is first picked up (see REF * GO_XDRAG). CLIENT_DATA is a structure containing information for dragging. SCREEN_OBJECT is a go_screen_object instance. go_drag_and_drop( SCREEN_OBJECT ); [method] Pick up a screen object and move it around the screen. The object can be picked up in any of the panes it is visible in. See also the the go_clear_drag and go_draw_drag methods. SCREEN_OBJECT is a go_screen_object instance. go_draw_drag_in_pane( CLIENT_DATA, SCREEN_OBJECT ); [method] Identical to the go_draw_drag method but always moving the reference point of the bounding box of the screen object. This is needed if the object hasn't been picked up with the mouse but has been "picked" up programmatically with the go_drag_in_pane method. CLIENT_DATA is a structure containing information for dragging. SCREEN_OBJECT is a go_screen_object instance. go_drag_in_pane( SCREEN_OBJECT ); [method] "picked" up the screen object programmatically and move it with the mouse motions until it is dropped . This is an alternative to the go_drag_and_drop method. SCREEN_OBJECT is a go_screen_object instance. go_copy_object( SCREEN_OBJECT ) -> NEW_SCREEN_OBJECT; [method] Creates a new screen object as an exact copy of the given one. This will result in an object which is visible in the same panes on the same place but on top of all other objects. This will always "hide" the original object which will be underneath the new one. SCREEN_OBJECT is a go_screen_object instance. go_destroy_object( SCREEN_OBJECT ); [method] Destroys the object by removing it from all panes it was in. It also removes any editors involved. Currently it does not make the structure of the instance completely free. SCREEN_OBJECT is a go_screen_object instance. -- go_shell ----------------------------------------------------------- go_shell; [class] isa go_located; The class go_shell represents a physical window in which a number of graphical panes can be placed. Multiple GO pane objects can be added to the shell which will manage their visibility and their relative location (see also go_add_to_shell). The global variable "go_shells" holds all currently active instances of the go_shell class in GO. the_go_panes [slot] Default: = [] ; Handles to all go_panes in this shell. the_go_shell [slot] Default: = false ; Handle to the shell's Widget. the_go_board [slot] Default: = false ; Handle to the shell's BulletinBoard Widget. stored_go_bounding_width [slot] Default: = 500 ; Stored value of horizontal size (screen coord = world coord) stored_go_bounding_height [slot] Default: = 500 ; Stored value of vertical size (screen coord = world coord) go_initialise_shell( SHELL ); [method] Create the physical window of a new shell object. This will call upon the Xt toolkit to create the shell (see also HELP * XtVaAppCreateShell) and a bulletin board inside it (see also HELP * BulletinBoardWidget). The latter will provide a composite widget in which the panes (see slot "the_go_panes" can be placed on specific locations like a board on which you can pin papers. It also provides a simple geometry management which handles locations when a pane is removed from the shell. The exact behaviour depends on the window manager which is used (currently OPENLOOK and MOTIF have been foreseen). SHELL is an instance of the go_shell class. go_add_to_shell( X, Y, W, H, PANE, SHELL ); [method] Add the given pane as a new pane with given dimensions to the shell. This creates a new XpwGraphic widget and attaches it to the pane which is then added to the shell (see also REF * GO_PANE). X/Y integer screen coord of pane relative to top-left corner of shell W/H integer width and height in screen coord of new pane. PANE is an instance of the go_pane class. SHELL is an instance of the go_shell class. go_add_to( PANE, SHELL ); [method] Make the given pane visible in the given shell. This can only be done if the pane is an element of the shell (see also go_add_to_shell). PANE is an instance of the go_pane class. SHELL is an instance of the go_shell class. go_add_to( PANE, SHELL ); [method] This is exactly the same as REF * GO_SHELL/go_add_to. PANE is an instance of the go_pane class. SHELL is an instance of the go_shell class. go_remove_from( PANE, SHELL ); [method] Removes the pane from the shell, and also detroys the object since the pane cannot exist outside its parent shell. PANE is an instance of the go_pane class. SHELL is an instance of the go_shell class. go_show( SHELL ); [method] Make the given shell visible on the screen. Note that the shell has no parent in which it is visualized. SHELL is an instance of the go_shell class. go_hide( SHELL ); [method] Make the given shell invisible on the screen. Note that the shell has no parent in which it is visualized. SHELL is an instance of the go_shell class. go_window_xloc( SHELL ) -> INT; [method] INT -> go_window_xloc( SHELL ); [method updater] Horizontal screen coordinate (on the display) from top-left hand corner of the screen. SHELL is an instance of the go_shell class. go_window_yloc( SHELL ) -> INT; [method] INT -> go_window_xloc( SHELL ); [method updater] Vertical screen coordinate (on the display) of the shell calculated from top-left hand corner. SHELL is an instance of the go_shell class. go_window_width( SHELL ) -> INT; [method] INT -> go_window_width( SHELL ); [method updater] The physical screen width (on the display) of the shell. SHELL is an instance of the go_shell class. go_window_height( SHELL ) -> INT; [method] INT -> go_window_height( SHELL ); [method updater] The physical screen height (on the display) of the shell. SHELL is an instance of the go_shell class. go_copy_object( SHELL ) -> SHELL; [method] Make a new shell object which is a complete copy of given shell. This copy will contain its own Graphics panes (go_window_pane) and the objects in the panes of the original shell are also copied They are not shared: they will move independently if dragged... The algorithm used will first create a copy in the original pane, then change its visibility from the old to the new pane. This is safer if the_go_components is method rather than a slot. go_destroy_object( SHELL ); [method] Makes the shell invisible, and destroys the shell and all its panes. First all panes are destroyed with go_destroy_object( PANE ), then the physical widget representing the shell (see slot "the_go_shell") is destroyed (see XtDestroyWidget). method_failure( VALUE, SHELL, METHOD ) [method] All methods not recognised by the go_shell class will be sent to its panes (see slot "the_go_panes"). This will only work for methods which expect one update value and no extra arguments except for the object of the go_pane class. WARNING: this catch-all method should not count on the fact that extra arguments can be left on the stack, since this will only work in the exceptional case of one pane per shell!. --- C.all/lib/proto/go/ref/go_baseclasses --- Copyright University of Sussex 1993. All rights reserved.