/* TEACH GO_POLYGON                              Ben Rabau, 27th Aug 1993

This file refers to polygon objects in Poplog/GO. This screen object class
forms the bases of a series of general shapes: regular polygons, irregular
closes polygons, rounded polygons. See also
    TEACH * GO_SQUARE           for squared regular closed polygons
    TEACH * GO_RECTANGLE        for rectangular regular closed polygons
    TEACH * GO_OBLONG           for oblongs (rounded rectangles)
    TEACH * GO_POLYLINE         for open polygons
    TEACH * GO_POLYARROW        for polylines with arrow heads

A go_polygon is a go_fillable (TEACH * GO_FILLABLE), go_rotatable
For more general detailed information see

HELP * GO
REF * GO

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

 -- Requirements
 -- Example
 -- Appearance
 -- go_colourable
 -- go_rotatable
 -- go_rounding

 */

/*
-- Requirements -------------------------------------------------------
 */
;;; This requires the following files to be loaded:
uses go;
uses go_polygon;

;;; It also requires an active go_pane (see TEACH * GO_PANE and
;;; TEACH * GO_RC_WINDOW):
go_init_rc();

/*
-- Example ------------------------------------------------------------
 */
;;; Create a polygon (see TEACH * GO_POLYGON) and visualise it on the
;;; newly created go_pane (see TEACH * GO_PANE/go_add_to):

vars poly1 = newgo_polygon();
go_add_to( poly1 , go_default_pane );

/*
-- Appearance ---------------------------------------------------------
 */
;;; The shape of the polygon can be changed by its go_npoints (number of sides):
;;; Note that this attribute is specific to polygons and their derivatives.
5 -> go_npoints( poly1 );          ;;; make a pentagon

;;; Or by changing its go_radius:
70 -> go_radius( poly1 );
55 -> go_radius( poly1 );

/*
-- go_colourable ------------------------------------------------------
 */
;;; A go_polygon inherits methods from go_screen_object which includes
;;; the ones from the go_colourable mixin.

;;; The apearance can be changed through it's colour and filling attributes:
;;; To change the color of the outline:
'blue' -> go_fgcolour( poly1 );

;;; To change the color of the inside you need to make the object go_filled
;;; and assign a color to go_bgcolour():
'aquamarine' -> go_bgcolour( poly1 );
true -> go_filled( poly1 );

/*
-- go_rotatable -------------------------------------------------------
 */
;;; A go_polygon also inherits methods from the go_rotatable mixin.

;;; You can rotate the go_polygon by changing the go_angle:
45 -> go_angle( poly1 );
 5 -> go_angle( poly1 );

;;; You can rotate in smaller steps by using the go_rotate method:
;;; The first argument is the final angle, the next argument the
;;; step.
0 -> go_angle( poly1 );
go_rotate( 45, 5, poly1 );

;;; Note that the rotation sometimes seems to stop for a fraction of a
;;; second.

;;; Rotation can be made continuous and smooth by using timers:
define do_rotation();
lvars rot_angle = go_angle( poly1 );
    go_batch_mode_on( go_default_pane );      ;;; See go_screen_object
    (rot_angle + 5 ) mod 360 -> rot_angle;
    rot_angle -> go_angle( poly1 );
    1e5 -> sys_timer( do_rotation );
    go_batch_mode_off( go_default_pane );     ;;; See go_screen_object
enddefine;

;;; To start the rotation do:
1e5 -> sys_timer( do_rotation );

;;; To end the rotation do:
false -> sys_timer( do_rotation );


/*
-- go_rounding -------------------------------------------------------
 */
;;; You can round the edges of a go_polygon with go_rounding.
;;; (see also HELP * GO_OBLONG and HELP * RC_ROUNDING for the original
;;; package in rc_window) :
10 -> go_rounding( poly1 );
25 -> go_rounding( poly1 );

;;; Note that go_rounding on go_filled objects only works correctly for
;;; convex shapes. It is an expensive procedure and dragging a go_filled
;;; rounded shape will necessitate at least motion hints (see TEACH *
;;; GO_DRAG and HELP * RC_DRAG):
true -> go_motionhint( go_default_pane );

;;; Other improvements can come from go_drag_filled and go_drag_outline
;;; described in TEACH * GO_DRAG. For instance:
false -> go_drag_filled;

;;; The defaults are:
true -> go_motionhint( go_default_pane );
true  -> go_drag_filled;
false -> go_drag_outline;

;;; To turn go_rounding off simple enter a go_value < 3:
 0 -> go_rounding( poly1 );

;;; The higher level functions go_smooth and go_roughen influence the
;;; go_rounding slots. Execute the following a few times:
go_smooth( poly1 );

;;; or:
go_roughen( poly1 );


/*
-- go_regular --------------------------------------------------------
 */
;;; Up to now only regular polygons have been used. We can make irregular
;;; shapes either by Direct Manipulation (see TEACH * GO_MAKE_EDITABLE)
;;; or by entering new data for the world coordinates with the slot
;;; go_regular set to the boolean false:

vars shape = instance go_polygon;
                 go_bgcolour  = 'slateblue';
                 go_filled    = true;
                 go_regular   = false;
                 go_world_coords
                 = [80 40  70 70  40 25  10 70  0 40  30 55  40 0  50 55];
             endinstance;

go_add_to( shape, go_default_pane );

;;; All the methods explained above also work on these irregular shapes:
go_rotate( 360, 15, shape );


;;; All the other methods are in line with TEACH * GO_SCREEN_OBJECT
;;; and TEACH * GO_MAKE_EDITABLE.

;;; eof;

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