/* TEACH GO_SHELL                                Ben Rabau, 27th Aug 1993

This file shows an examples of the go_shell class. This uses the underlying
go_window_pane class (see also TEACH * GO_PANE) which allows connection
of GO to a XpwGraphic widget. See HELP * XpwGraphic for more details on
this graphical X-windows widget.

Graphical Objects can be created, visualised and manipulated in these
panes.

For more general detailed information see

TEACH * GO
HELP * GO
REF * GO

         CONTENTS - (Use <ENTER> g to access required sections)

 -- a top-level go_shell
 -- a go_shell with multiple XpwGraphics panes
 -- making a shell or its panes invisibility
 -- removing a pane from a shell
 -- copying a go_shell
 -- destroying a go_shell

 */

;;; Requires the following files to be loaded:
uses go;
uses go_shell;

;;; A shell is the part of the window which contains the borders
;;; and title bar.
;;; A pane is the part of the window in which the graphics will
;;; appear. It is the window without the header and any other
;;; attributes which are go_attached to it (resize objects, scroll
;;; bars, etc.).

;;; A shell can contain several panes but also a number of other
;;; window types such as command panes (see HELP * X)

;;; In GO the go_shell objects contain the handle tho the physical shell
;;; and the go_window_pane objects contains the handler to that physical
;;; window (an XpwGraphic widget).


/*  -------------------------------------------------------------------  *
-- a top-level go_shell -----------------------------------------------
 *  -------------------------------------------------------------------  */

;;; GO allows the creation of a completely new shell window. By default
;;; this shell window will also contain a graphics window which has the
;;; same size (a go_window_pane).

;;; The following creates a shell structure (does not appear on screen):
vars shell = newgo_shell();

;;; This shell will have created an object containing the dimensions of
;;; the shell and an instance of the go_window_pane class with the same
;;; dimensions. It is in the latter that the user can create Graphical
;;; Objects (see TEACH * GO_PANE).
;;; Fonts and colours can be specified both in the go_shell class or
;;; in the defaults file (see REF * GO_XDEFAULTS).

;;; To make the new shell visible on the screen, the user can issue the
;;; same command as for Graphical Objects in this library, namely:
go_show( shell );

/*  -------------------------------------------------------------------  *
-- a go_shell with multiple XpwGraphics panes -------------------------
 *  -------------------------------------------------------------------  */

;;; The go_shell has an easy mechanism for adding and removing XpwGraphics
;;; panes. This allows the addition of new go_window_pane objects with
;;; different window location or dimensions. The default dimensions are
;;; 500x500 from the top-left hand corner (0,0) position.
;;; The following adds a small go_window_pane at the bottom of the go_shell:
;;; The parameters represent the top-left hand corner (0,501) and the width
;;; and height (500,25) of the new pane:
vars new_pane = newgo_window_pane();
go_add_to_shell( 0, 501, 500, 25, new_pane, shell );

;;; Note that the window manager will be responsible to enlarge or shrink
;;; the shell window if panes are added or removed.

;;; The panes can of course be resized by the commands (see TEACH GO_PANE):
200 -> go_window_width( new_pane );
100 -> go_window_xloc( new_pane );

;;; All panes are stored in the slot: the_go_panes.
;;; The already existing default pane can be retrieved with:
vars default_pane = the_go_panes(shell)(1);
300 -> go_window_height( default_pane );

;;; Note that the window manager is unlikely to move new_pane closer
;;; to the reduced default_pane, but it is not excluded!

;;; The extra panes are added to the end of the list in the_go_panes:
new_pane == the_go_panes(shell)(2) =>

/*  -------------------------------------------------------------------  *
-- making a shell or its panes invisibility ---------------------------
 *  -------------------------------------------------------------------  */

;;; A shell or one of its panes can be made invisible with the go_hide()
;;; method. This is the opposite of go_show().
go_hide( new_pane );

;;; And:
go_show( new_pane );

;;; The whole shell can be made invisible with:
go_hide( shell );

;;; And:
go_show( shell );

;;; Sometimes the window manager will not pop the shell up in its previous
;;; location. This is due to default locations being used by the window
;;; manager. This can be avoided by explicitely setting the location:
200 -> go_window_xloc(shell);

;;; The shell can also be resized. This can influence the position of the
;;; panes, but this depends on the implementation of the window manager.
700 -> go_window_width(shell) ;
go_window_height( shell ) =>


/*  -------------------------------------------------------------------  *
-- removing a pane from a shell ---------------------------------------
 *  -------------------------------------------------------------------  */
;;; Panes can be removed with go_remove_from() just like they can be
;;; added with go_add_to_shell(). Let us first add another pane then destroy
;;; the middle one. The pane has to be of the go_window_pane class or a
;;; more specialised one; here we use: go_rc_window_pane

vars extra_pane = newgo_rc_window_pane();
go_add_to_shell( 0, 301, 100, 75, extra_pane, shell );
go_remove_from( new_pane, shell );

;;; Note that some window managers will reshuffle the rest of the panes
;;; in the shell. This is not controlled by GO! but normally happens when
;;; the destroyed pane is on the border of the shell.
;;; Compare the go_destroy_object() with the go_make_invisible() method:
go_hide( default_pane );
go_remove_from( default_pane, shell );

;;; Note that executing a go_destroy_object( default_pane ); will get
;;; the shell slot "go_panes" out of sync!!


/*  -------------------------------------------------------------------  *
-- copying a go_shell -------------------------------------------------
 *  -------------------------------------------------------------------  */

;;; As with all other GO objects the go_shell instances can also be copied.
;;; This operation is not very fast as it makes new instances of each of
;;; the panes and each of the objects in the panes. Note that any window
;;; added to this shell without the go_add_to_shell() will not be copied.

;;; Let us add a circle object to the extra_pane (see TEACH * GO_CIRCLE )
uses go_circle;
vars circ = newgo_circle() ;
go_add_to( circ, extra_pane );
vars new_shell = go_copy_object( shell );

;;; Then do:
go_show( new_shell );

/*  -------------------------------------------------------------------  *
-- destroying a go_shell ----------------------------------------------
 *  -------------------------------------------------------------------  */

;;; The same method applies as for all other GO objects: go_destroy_object()
;;; The following destroys the just created shell:
go_destroy_object( new_shell );


;;; There also is a top-level method which destroy all shells but also all
;;; panes which are created separately (see TEACH * GO_PANE ).
;;; This is based on the list of all current shells and panes in GO
;;; (see also REF * GO_VARS/go_shells and REF *GO_VARS/go_panes):

go_shells =>
go_panes =>

go_destroy();

;;; eof

--- C.all/lib/proto/go/teach/go_shell
--- Copyright University of Sussex 1993. All rights reserved.
