HELP RCLIB                                        Aaron Sloman June 1997
Last updated: 29 Mar 2006

Accessible as
    http://www.cs.bham.ac.uk/research/poplog/rclib/help/rclib

Note:
    replaced "rc_informant_contents" with "rc_informant_value"
    The former is left as a synonym for the latter, to enable
    old user code to continue work.
    Introduced rc_real_contents for radio and someof buttons.
    See LIB RC_BUTTONS

    The three categories of action button types POPNOW, POP11
    and INVED are all now collapsed into one: POP11 actions.
    Changes to the event handler have made the distinctions
    unnecessary. However DEFER actions remain a distinct category.


Major rewrites of this file in July 2000, March 2000, Aug-Sept 2002

See also
    HELP RCLIB_NEWS



TABLE OF CONTENTS

 -- What is RCLIB?
 -- Packages using RCLIB
 -- -- The RCMENU (recursive hypermenu) system
 -- -- The SIM_AGENT toolkit
 -- -- Student projects and various demos
 -- Historical note
 -- Availability
 -- Installation and making everything accessible
 -- Getting started and getting to know RCLIB
 -- This file: HELP RCLIB
 -- Information about updates: HELP RCLIB_NEWS
 -- The "low level" Poplog X facilities
 -- -- Note on Motif
 -- RC_GRAPHIC, the starting point for RCLIB
 -- Limitations of RC_GRAPHIC
 -- NOTE on mixing RC_GRAPHIC and RCLIB facilities
 -- RC_GRAPHIC facilities to avoid
 -- RC_GRAPHIC and its extensions: an overview
 -- Facilities provided in LIB RC_GRAPHIC, prior to RCLIB
 -- Additional parts of the RC_GRAPHIC library
 -- -- LIB rc_mouse (avoid)
 -- -- LIB rc_context (avoid)
 -- -- LIB rc_rotate_xy (avoid)
 -- -- LIB rc_graphplot
 -- -- LIB rc_set_coord_frame (avoid)
 -- -- LIB rc_set_scale (avoid)
 -- -- LIB popvision
 -- Extensions provided by RCLIB
 -- The class/mixin structure of RCLIB
 -- -- Window object classes and picture object classes
 -- -- Picture object mixins in LIB rc_linepic
 -- -- Mixins defined in LIB rc_opaque_mover
 -- -- Classes and mixins in LIB rc_window_object
 -- -- Other classes and mixins
 -- -- Picture objects that are mouse- or keyboard-sensitive
 -- rc_mousepic: Making a window sensitive to mouse or keyboard events
 -- How events are handled
 -- Event handling methods
 -- -- How to associate an object with event handlers
 -- -- Using indirection to facilitate development and testing
 -- -- Event handling contexts
 -- -- Three main types of event handling contexts in RCLIB
 -- AUTOLOADABLE FACILITIES IN RCLIB
 -- -- ARGS (Macro for optional arguments)
 -- -- async_apply
 -- -- async_interpret_action
 -- -- async_unix_obey
 -- -- async_vedinput
 -- -- create_modified_instance
 -- -- define_rc_defaults
 -- -- files_matching
 -- -- forevery
 -- -- is_pattern_string
 -- -- interpret_specs
 -- -- isrc_panel_field
 -- -- isrc_window_object
 -- -- loadrcdemo
 -- -- max_string_length
 -- -- menu_choosefile1
 -- -- menu_choosefile2
 -- -- pattern_instance
 -- -- print_to_strings
 -- -- rc_add_handler
 -- -- rc_add_kill_button
 -- -- -- Global variables for kill buttons
 -- -- rc_app_mouse
 -- -- rc_background
 -- -- rc_between
 -- -- rc_black_white_inverted
 -- -- rc_blob_demo
 -- -- rc_browse_files
 -- -- rc_browser_action
 -- -- rc_button_in_field_in_panel
 -- -- rc_change_picture
 -- -- rc_check_current_window
 -- -- rc_check_window_object
 -- -- rc_check_window
 -- -- rc_circle
 -- -- rc_coloured_circles
 -- -- rc_confirm
 -- -- rc_consolidate_all_input
 -- -- rc_constrained_pointer
 -- -- rc_constrained_rotater
 -- -- rc_control_panel
 -- -- rc_coloured_panel
 -- -- rc_panelcontents
 -- -- rc_panel_field_value
 -- -- rc_current_handlers
 -- -- rc_defaults (declaring defaults for global variables)
 -- -- rc_delete_handler
 -- -- rc_dial
 -- -- rc_display_file
 -- -- rc_display_strings
 -- -- . globals for rc_display_strings and rc_display_file, etc
 -- -- . rc_kill_browser_panels
 -- -- rc_default_window_object
 -- -- rc_destroy
 -- -- rc_distance
 -- -- rc_do_unix
 -- -- rc_drag_window
 -- -- rc_draw_arc_segment
 -- -- rc_draw_arc_segments
 -- -- rc_draw_bar
 -- -- rc_draw_blob
 -- -- rc_draw_blob_sector
 -- -- rc_draw_unscaled_blob
 -- -- rc_draw_centred_rect
 -- -- rc_draw_centred_square
 -- -- rc_draw_circle
 -- -- rc_draw_lines
 -- -- rc_draw_lines_closed
 -- -- rc_draw_lines_filled
 -- -- rc_draw_coloured_circle
 -- -- rc_draw_coloured_line
 -- -- rc_draw_pointer
 -- -- rc_draw_ob
 -- -- rc_draw_pointlist
 -- -- rc_draw_coloured_pointlist
 -- -- rc_draw_rect
 -- -- rc_draw_Rrect
 -- -- rc_draw_filled_rect
 -- -- rc_draw_filled_centred_rect
 -- -- rc_draw_scaled_blob
 -- -- rc_draw_semi_circle.p
 -- -- rc_draw_square
 -- -- rc_draw_Rsquare
 -- -- rc_draw_coloured_square
 -- -- rc_draw_triangle
 -- -- rc_draw_filled_triangle
 -- -- rc_drawline_absolute
 -- -- rc_drawline_relative
 -- -- rc_drawtree
 -- -- rc_flush_everything
 -- -- rc_font
 -- -- rc_font_dimensions
 -- -- rc_foreground
 -- -- rc_foreground_changeable
 -- -- rc_get_coords
 -- -- rc_get_coords_from
 -- -- rc_getfile
 -- -- rc_getinput
 -- -- rc_hide_menu
 -- -- rc_kill_menu
 -- -- rc_hide_panel
 -- -- rc_kill_panel
 -- -- rc_interpolate_coords
 -- -- fast_interpolate_coords
 -- -- rc_interpret_key
 -- -- rc_islive_window_object(win) -> boole
 -- -- rc_label_dial
 -- -- . rc_dial_label_xoffset = -8;
 -- -- . rc_dial_label_yoffset = 5;
 -- -- rc_kill_selected_windows
 -- -- rc_lengthen_window_by
 -- -- rc_line_function
 -- -- rc_line_style
 -- -- rc_line_width
 -- -- rc_lispbrowser
 -- -- rc_make_current_window
 -- -- rc_make_draggable
 -- -- rc_message
 -- -- rc_message_wait
 -- -- rc_mouse_coords
 -- -- rc_mousepic
 -- -- rc_add_pic_to_window
 -- -- rc_remove_pic_from_window
 -- -- rc_new_graphic_widget
 -- -- rc_popup_panel
 -- -- rc_popup_query
 -- -- rc_popup_readin
 -- -- rc_popup_readline
 -- -- rc_popup_strings
 -- -- rc_poster
 -- -- rc_print_strings
 -- -- . variable rc_print_strings_offset
 -- -- rc_procbrowser and rc_lispbrowser
 -- -- -- rc_procbrowser defaults
 -- -- -- rc_lispbrowser defaults
 -- -- rc_query_mouse
 -- -- rc_readline
 -- -- rc_rotate_vector
 -- -- rc_reset_panel
 -- -- rc_run_deferred_events
 -- -- rc_scratch_panel
 -- -- rc_scratch_window
 -- -- rc_screensize
 -- -- rc_set_planemask
 -- -- rc_set_window_scale and rc_pixels_per_inch
 -- -- rc_setup_linefunction
 -- -- rc_shift_window_frame_by
 -- -- rc_showtree
 -- -- rc_slider
 -- -- rc_opaque_slider
 -- -- rc_square_slider
 -- -- rc_sync_display and rc_window_sync
 -- -- rc_testbrowser
 -- -- rc_text_area
 -- -- rc_title
 -- -- rc_transfer_window_contents
 -- -- rc_transform_lines
 -- -- rc_transform_pictures
 -- -- rc_vedfileselect
 -- -- rc_warp_to
 -- -- rc_widen_window_by
 -- -- rc_window_coords
 -- -- rc_window_dimensions
 -- -- rc_xterm
 -- -- self_caller()
 -- -- SETWINDOW <expression>
 -- -- Interacting with VED files
 -- -- .  ved_open_file(name, x, y, cols, rows, saveable);
 -- -- .  ved_write_to_file(item, file);
 -- -- .  ved_read_from_file(string, file) -> list;
 -- -- ved_browser
 -- -- ved_killwin (ENTER killwin)
 -- -- ved_procbrowser (ENTER procbrowser)
 -- -- ved_rcdemo (ENTER rcdemo)
 -- -- veddiscin
 -- -- veddiscout
 -- -- vedreadlinefrom
 -- NON-AUTOLOADABLE LIBRARIES AND PROCEDURES
 -- -- rc_coords
 -- -- LIB getpointvec
 -- -- . getpointvec(points, n, closed) ->(nitems, vec);
 -- -- . freepointvec(vec)
 -- -- . Global variable: max_reusable_vector
 -- -- LIB rc_apply_util
 -- -- LIB rc_buttons
 -- -- . Asynchronous control buttons:
 -- -- . Synchronous control buttons (for popup menus):
 -- -- . Procedures for creating individual buttons or collections
 -- -- -- create_rc_button
 -- -- -- create_button_columns
 -- -- -- create_radio_button_columns
 -- -- -- create_someof_button_columns
 -- -- . Additional procedures in LIB rc_button_utils
 -- -- . Classes and mixins concerned with buttons
 -- -- LIB rc_compound
 -- -- LIB rc_constrained_mover
 -- -- LIB rc_exceed (defunct)
 -- -- LIB rc_extend_utils
 -- -- LIB rc_freezable
 -- -- LIB rc_informant
 -- -- . More detailed information on rc_informant facilities
 -- -- Synonyms for backward compatibility
 -- -- Note on use of mixin rc_informant
 -- -- . rc_informant_window
 -- -- . rc_informant_label
 -- -- . rc_informant_with_label
 -- -- LIB rc_linepic
 -- -- LIB rc_linked_pic
 -- -- LIB rc_mousepic (event handling primitives)
 -- -- . Creating events:
 -- -- -- . rc_do_button_actions
 -- -- -- . rc_do_move_actions
 -- -- -- . rc_do_mouse_actions
 -- -- -- . rc_do_keyboard_actions
 -- -- -- . rc_handle_event
 -- -- -- . rc_get_handler
 -- -- -- More specific event handlers
 -- -- -- . rc_system_button_down_callback
 -- -- -- . rc_system_button_up_callback
 -- -- -- . rc_system_move_callback
 -- -- -- . rc_system_drag_callback
 -- -- -- . rc_system_entry_callback
 -- -- -- . rc_system_exit_callback
 -- -- -- . rc_system_keypress_callback
 -- -- LIB rc_opaque_mover
 -- -- LIB rc_point
 -- -- LIB rc_poly
 -- -- LIB rc_polydemo
 -- -- LIB rc_polyline
 -- -- LIB rc_polypanel
 -- -- LIB rc_pythagoras
 -- -- LIB rc_scratchpad
 -- -- LIB rc_scrolltext
 -- -- LIB rc_swap_context (redundant)
 -- -- LIB rc_text_input
 -- -- . rc_handle_text_input
 -- -- . List of facilities in LIB * RC_TEXT_INPUT
 -- -- LIB rc_window_object
 -- -- . global variables in rc_window_object and rc_mousepic
 -- -- . :class rc_window_object
 -- -- . rc_new_window_object
 -- -- -- additional formats:
 -- -- -- The container argument
 -- -- -- The location arguments
 -- -- -- The creator procedure
 -- -- -- The "hidden" argument
 -- -- -- The string (window title) argument
 -- -- -- The setframe argument
 -- -- -- The result of rc_new_window_object
 -- -- . :mixin rc_selectable
 -- -- . :mixin rc_keysensitive
 -- -- . :method rc_mousexyin(win_obj:rc_window_object, x, y) -> (x, y) ;
 -- -- . :method rc_transxyin_in
 -- -- . Methods and procedures associated with rc_window_objects
 -- -- LIB rc_blocks and LIB rc_hand
 -- Global variables
 -- -- rc_active_picture_object
 -- -- rc_border_allowance rc_title_allowance
 -- -- rc_active_window_object
 -- -- rc_charout_buffer
 -- -- rc_clear_before_redraw
 -- -- rc_current_panel
 -- -- rc_current_panel_field;
 -- -- rc_current_picture_object
 -- -- rc_current_window_object
 -- -- rc_fast_drag
 -- -- rc_inside_callback
 -- -- rc_fast_move
 -- -- rc_in_event_handler
 -- -- rc_no_more_handlers
 -- -- rc_pause_draw
 -- -- rc_prev_active_window_object
 -- -- rc_prev_active_picture_object
 -- -- rc_redrawing_window
 -- -- rc_selected_window_objects
 -- -- rc_selected_picture_objects
 -- -- rc_moving_picture_object
 -- -- rc_sole_active_widget
 -- -- rc_transparent_objects
 -- -- rc_window_sync_time
 -- -- rc_window_x_offset, rc_window_y_offset
 -- -- rc_window_object_of (property)
 -- -- rc_select_distance
 -- -- rc_sync_delay_time
 -- -- use_rc_graphic_versions
 -- Additional files
 -- -- TEACH RC_DEMO, TEACH FACES
 -- -- TEACH RCLIB_DEMO.P
 -- -- TEACH RC_LINEPIC
 -- -- TEACH RC_OPAQUE_MOVER
 -- -- TEACH RC_MOUSEPIC
 -- -- TEACH RC_LINEPIC.DEMO.P
 -- -- TEACH RC_GRAPHPLOT
 -- -- TEACH RC_CONTROL_PANEL
 -- -- TEACH POPCONTROL
 -- -- TEACH RC_ASYNC_DEMO
 -- -- TEACH RC_BUTTONS
 -- -- TEACH RC_CONSTRAINED_PANEL
 -- -- TEACH RC_CONSTRAINED_POINTER
 -- -- TEACH RC_DIAL
 -- -- TEACH rc_intro
 -- -- TEACH rc_linepic.extra
 -- -- TEACH RCLIBTEACHINDEX
 -- Demonstration libraries
 -- -- rc_ant_demo
 -- -- painting_demo
 -- -- rcblocks demo
 -- -- rc_polypanel
 -- -- rc_neural
 -- -- Demonstrations based on sim_agent
 -- -- Other demo libraries
 -- Notes on recent developments

-- What is RCLIB? -----------------------------------------------------

RCLIB makes available a powerful collection of object oriented graphical
facilities based on the X window interface in Pop-11. It is designed to
be usable by both beginner programmers and experts. The 'RC' prefix
stands for 'Relative Coordinates'. The idea was the basis of the much
older RC_GRAPHIC library which allowed graphical commands (e.g. drawing
lines, printing strings) to be given coordinates relative to a
user-defined framework rather than relative to the pixel coordinate
system in the window.

RCLIB builds on the old RC_GRAPHIC library, using the Objectclass
object-oriented facilities, to provide facilities for constructing a
variety of types of graphical interfaces and displays involving static
or moving 2-D pictures, including a variety of types of control-panels.

As in RC_GRAPHIC, the low level X facilities, including event handling
mechanisms, are packaged in convenient methods that users can extend or
redefine for various subclasses, e.g. button events, motion events,
keyboard events, etc. To support this a collection of very simple, very
abstract 'mixins' are defined, with associated methods, and various
combinations of these are then used to define classes which combine many
features and capabilities, e.g. sliders, dials, various kinds of
buttons, and control panels containing all these things.

The mixin and class hierarchy is currently being documented, and will
later be described in a file posted here:

    http://www.cs.bham.ac.uk/research/poplog/rclib/ref/rclib

At present you can get a rough idea of the existing classes and mixins
by giving these commands and then looking more closely at the files
displayed:

    grep :mixin $poplocal/local/rclib/*/*.p | grep :define
    grep :class $poplocal/local/rclib/*/*.p | grep :define

Examples of the most basic mixins and classes are

     LIB * RC_LINEPIC
         Drawable and movable entities that can be used
         in conjunction with the RC_GRAPHIC libary, or the
         more sophisticated facilities of LIB RC_WINDOW_OBJECT

         define :mixin rc_linepic;
         define :mixin rc_linepic_movable; is rc_linepic;
         define :mixin rc_rotatable; is rc_linepic_movable;
         define :mixin rc_rotatable_picsonly; is rc_rotatable;
            See TEACH * RC_LINEPIC for examples.

     LIB * RC_WINDOW_OBJECT
     LIB * RC_MOUSEPIC
         Provides facilities for creating and managing window objects
         in which drawing can be done, and in which mouse and
         keyboard events can be handled.

         define :mixin rc_selectable;
         define :mixin rc_keysensitive;
         define :mixin rc_resizeable;
         define :class rc_window_object;


     LIB * rc_constrained_mover.p:
         define :mixin rc_constrained_mover; is rc_linepic_movable;
            used for sliders and dials, for instance.

     LIB * RC_INFORMANT
         define :mixin rc_informant;
            Used for objects that hold some possibly changable
            value, e.g. a string or number or other information.

Many methods are defined in those libraries, defining a class of
behaviours that can be combined and refined in various ways in
libraries implementing more specific facilities, e.g. buttons, sliders,
dials, text and number input, scrolling text, automatically formatted
control panels, etc. Some of the default methods do nothing at all, but
exist so that more specific versions can be implemented for sub-clases.

Because so much of RCLIB is implemented in Pop-11, it is very easy to
extend or modify (E.g. compared with the C-based utilities described in
REF Xpw and related files describing the X window facilities in Poplog.)

RCLIB builds on the RC_GRAPHIC library, using the Objectclass
object-oriented facilities, to provide facilities for constructing a
variety of types of graphical interfaces and displays involving static
or moving 2-D pictures, including a variety of types of control-panels.

As in RC_GRAPHIC, the low level X facilities, including event handling
mechanisms, are packaged in convenient methods that users can extend or
redefine for various subclasses, e.g. button events, motion events,
keyboard events, etc.

The most powerful RCLIB construct, rc_control_panel, accepts a
declarative specification of a control panel (i.e. an X graphical window
with associated event handlers) which can contain buttons, sliders, text
fields, dials, scrolling text panels, static or movable graphical
objects, etc. It uses the declarative specification (a list of lists) to
construct an automatically formatted panel. In some ways this duplicates
the previous Propsheet facility, but rc_control_panel is far easier to
modify and extend, as all the main code is in pop-11, and based on
objectclass methods. In some ways it is more general, e.g. allowing
sliders to have any orientation, instead of being only vertical or
horizontal.

Moreover, like everything else in RCLIB, rc_control_panel does not
depend on Motif, so it works on all Unix/Linux systems with the X
windows system. A control panel can contain other control panels.

-- Packages using RCLIB -----------------------------------------------

Since its introduction RCLIB has been used for a number of applications.

-- -- The RCMENU (recursive hypermenu) system

This package, implemented on top of RCLIB, provides a collection of
autoloadable, easily extended, mutually recursive menus and control
panels which can be used to drive Ved or Xved, interact with the Pop-11
compiler or other Poplog compilers, and can lauch unix utilities,
perhaps running programs and reading their output into Ved buffers.

LIB * RCMENU supports menu panels defined in a readable formalism with
the syntax

    define :menu <name>;
        <menu body>
    enddefine;

where recompiling the menu definition will automatically remove from the
screen a menu panel based on the previous definition and replace it with
the new one. Pre-existing menu panels that referred to the old one will
thereafter invoke the new version instead of the old ones. This makes
development and testing of interfaces very fast and also allows the
precise form of a particular menu to be varied dynamically.

If you have installed RCMENU more information is available here
    HELP * VED_MENU
    TEACH * VED_MENU
    TEACH * MENU_DEMO


The rcmenu package is not automatically included with RCLIB but can be
fetched from the Free Poplog distribution site:
    http://www.cs.bham.ac.uk/research/poplog/freepoplog.html

It is available as a gzipped tar file rcmenu.tar.gz and can be
browsed in
    http://www.cs.bham.ac.uk/research/poplog/rcmenu/

It is included in the linux-poplog package described here:
    http://www.cs.bham.ac.uk/research/poplog/linux-cd/


NOTE: the rcmenu package was originally implemented using * PROPSHEET
and was called LIB MENU. There may still be some procedures in
RCMENU that invoke the old mechanism and need to be replaced.


-- -- The SIM_AGENT toolkit

There is a graphical extension to the Sim_agent toolkit built on
RCLIB. Sim_agent is a powerful toolkit for exploring agent
architectures, described in

    http://www.cs.bham.ac.uk/~axs/cog_affect/sim_agent.html

and is also available via the Free Poplog distribution site:
    http://www.cs.bham.ac.uk/research/poplog/freepoplog.html

in the gzipped tar file newkit.tar.gz

Its graphical library is sim_picagent, described in

    http://www.cs.bham.ac.uk/research/poplog/newkit/sim/help/sim_picagent

-- -- Student projects and various demos

RCLIB (with or without sim_agent) has been used increasingly as a
mechanism for providing graphical interfaces for student projects.

Some of these will be made available either as part of the rclib
package (e.g. in the demo/ subdirectory) or in the sim_agent
package (e.g. the simulated sheepdog and other demonstrations
included with sim_agent use rclib).



-- Historical note ----------------------------------------------------

The idea of using the rc_graphic tools as the basis for a wide
range of user interface tools was independently proposed around 1993 by
Jonathan Cunningham while working on the UIDE project, involving
ISL, BMT Ltd, Sussex University and Birmingham University. He produced a
first draft partial implementation, called "sketch", based on the
Flavours library, which was one of the early implementations of object
oriented programming in Pop-11. (See REF FLAVOURS).

For the RCLIB package I started again, using the Objectclass extension
to Pop-11, which became available later and is more suitable than
Flavours, e.g. because it supports multi-methods (generic functions)
and is better integrated wtih the Pop-11 programming style.
(See REF OBJECTCLASS)


-- Availability -------------------------------------------------------

The RCLIB package is available from the Birmingham Free Poplog directory

    http://www.cs.bham.ac.uk/research/poplog/
also  available as
    ftp://ftp.cs.bham.ac.uk/pub/dist/poplog/

For general information about the contents of the directory see the
file
    http://www.cs.bham.ac.uk/research/poplog/freepoplog.html
or
    ftp://ftp.cs.bham.ac.uk/pub/dist/poplog/freepoplog.html

The rclib package can be browsed online in this directory

    http://www.cs.bham.ac.uk/research/poplog/rclib
    ftp://ftp.cs.bham.ac.uk/pub/dist/poplog/rclib

There is also a compressed tar file containing the package, including
code and documentation

    http://www.cs.bham.ac.uk/research/poplog/rclib.tar.gz
    ftp://ftp.cs.bham.ac.uk/pub/dist/poplog/rclib.tar.gz

RCLIB depends on Poplog, which can be fetched with full system sources,
free of charge from
    ftp://ftp.cs.bham.ac.uk/pub/dist/poplog/freepoplog.html
or
    http://www.cs.bham.ac.uk/research/poplog/freepoplog.html


-- Installation and making everything accessible ----------------------

Fetch rclib.tar.gz from the Free Poplog site, or one of the mirrors, and
untar the package in the directory
    $poplocal/local

This will create a directory $poplocal/local/rclib/ with the usual
collection of sub-directories, e.g. auto, lib, teach, help, ref,and a
demo directory with some demonstrations.

It should also provide a symbolic link from the file

    $poplocal/local/rclib/rclib.p
to
    $poplocal/local/lib/rclib.p

If the latter does not exist, do

    cd $poplocal/local/lib
    ln -s ../rclib/rclib.p .

After that everything in the library can be made accessible by means
of this command:

    uses rclib

which will extend the Pop-11 and VED search lists so as to make
available a collection of extensions to the Pop-11 RC_GRAPHIC library.
Some are autoloadable utilities. Others are substantial packages that
have to be explicitly compiled using "uses" or "lib".

-- Getting started and getting to know RCLIB --------------------------

To gain a first idea of the contents of RCLIB, work through the tutorial
introductory overview which gives many examples of the higher level
facilites in RCLIB

    TEACH RCLIB_DEMO.P

Working through that could take about 30 to 60 minutes or more depending
how much you experiment with the examples and how closely you read the
details.

It includes a demonstration of the mechanisms for creating an
automatically formatted control panel. Further, detailed, information
about this powerful mechanism can be found in
    HELP RC_CONTROL_PANEL
Several of the teach files listed below include examples. There
is a growing collection of library packages based on rc_control_panel.
A mechanism for creating automatically formatted dials, with or without
using rc_control_panel is illustrated in
    TEACH RC_DIAL

For tutorial information about the basic picture drawing and event
handling mechanisms provided by rclib see:

    TEACH RC_LINEPIC

The drawing, event handling, and mouse-activated mechanisms are
described in more detail in the file

    HELP RC_LINEPIC

and in the section on event handling below in this file. There is also a
file
    HELP RC_EVENTS

describing event handling (which is very complex because the
package has to work whether you are communicating simply with Pop-11
through a terminal, or with VED or with XVed, and the mechanisms may be
invoked asynchronously while arbitrary programs are running.)

The facilities for buttons and popup messages, menus, etc. are
described, with examples, in

    HELP RC_BUTTONS


See also the more complete "index" files
    TEACH RCLIBTEACHINDEX
    HELP RCLIBHELPINDEX
    REF RCLIBREFINDEX
    These give more complete lists of teach and help files

For experts, examination of the code in
    LIB RC_WINDOW_OBJECT
    LIB RC_MOUSEPIC
    LIB RC_LINEPIC

may provide useful understanding. This is still more messy than I would
like and may be revised.

The event handling for buttons is in LIB RC_BUTTONS


-- This file: HELP RCLIB ----------------------------------------------

This file is the main overview file. When trying to get information
about an rclib utility, first search this file. If that fails
it may be useful to look at the tables of contents of the
other help and teach files, or even to use grep with

    $poplocal/local/rclib/help/*
    $poplocal/local/rclib/teach/*
    $poplocal/local/rclib/ref/*

In particular see
    HELP RC_LINEPIC
    HELP RC_BUTTONS
    HELP RC_CONTROL_PANEL
    HELP RC_EVENTS



-- Information about updates: HELP RCLIB_NEWS -------------------------

The RCLIB package is extended from time to time with new facilities
suggested by users and (occasional!) bug fixes.

For "Change notes" see HELP RCLIB_NEWS, usually accessible online at

    ftp://ftp.cs.bham.ac.uk/pub/dist/poplog/rclib/help/rclib_news
or
    http://www.cs.bham.ac.uk/research/poplog/rclib/help/rclib_news

After changes the rclib.tar.gz file is usually updated within a few
days
    http://www.cs.bham.ac.uk/research/poplog/rclib.tar.gz
    ftp://ftp.cs.bham.ac.uk/pub/dist/poplog/rclib.tar.gz

-- The "low level" Poplog X facilities --------------------------------

This section can be skipped by beginners.

Poplog has a large and comprehensive collection of facilities for
interfacing to the X window system at different levels, including
support for externally provided toolkits, such as motif.

Most users of the RCLIB package will not need to learn about Poplog's
basic X facilities, but those who wish to do so may look at the
documentation in these files:

    HELP X, REF X,  HELP Xpw, TEACH Xpw,
    TEACH XTOOLKIT

For a more comprehensive overview of the more basic facilities on which
the tools are built see

    REF Xpw, REF XpwGraphic, REF XpwPixmap,


and other files in
    $usepop/pop/x/pop/ref/
    $usepop/pop/x/pop/help/
    $usepop/pop/x/pop/teach/

These facilities make it possible to create, modify, draw in, print
text in, and attach event handlers to X windows (widgets), and include
support for a scrolling text facility.

However, using these mechanisms is not always easy as they are defined
at a low level, and the programmer is required to learn a great deal
about the X window system and also about some of the low level features
of the Poplog external interface, as described in
    REF EXTERNAL
    REF EXTERNAL_DATA

and perhaps also some of the low level information about asynchronous
event handling described in
    REF ASYNC

One of the more high level tools based on these X facilities is
LIB PROPSHEET, described in
    TEACH PROPSHEET
    REF PROPSHEET

This provides mechanisms for creating menus, dialog boxes, sliders, etc.

However this is not well integrated into the graphical drawing packages.
E.g. it is not easy to add a set of radio buttons, or a menu, or
numerical incrementor button to a picture produced by graphical
commands or vice versa, though both can be done if you are an X expert.

Another problem is that the propsheet library depends on the
availability of the Motif widget set (or Sun's Openlook widget set),
neither of which can be assumed to be available on all platforms
supporting the X window system, e.g. under linux. The facilities
described here are designed to be independent of Motif and Openlook.

Moreover not all users find the interface from pop-11 programs to
Propsheet to be intuitive. E.g. we have found that students using it
often encounter problems, such as access violation errors because of a
failure to understand when to use external_defer_apply.

Fortunately the RCLIB package, like LIB RC_GRAPHIC, makes it relatively
easy to produce graphical events without having to read about all the
low level facilities. In particular, you should not need to read
a manual on the X window system.

In fact by using mainly high level packaged facilities such as
rc_control_panel, you may not need to learn much about the details of
event handling in RCLIB. However the information is available, if
required, in HELP RC_EVENTS.

-- -- Note on Motif

NOTE: the RCLIB package is designed to work without motif. This means
that all of its facilities should work on linux poplog, whether or not
motif (or lestif) has been installed.

There is a further extension to the Poplog X window interface which is
based on Propsheet and various Motif (or Openlook) widgets, which is
described in
    REF POP_UI
    HELP POPLOG_UI
    HELP POP_UI_OVERVIEW

Approximately equivalent, and more general, facilities are now provided
by RCLIB

-- RC_GRAPHIC, the starting point for RCLIB ---------------------------

Since about 1990, the RC_GRAPHIC extension to Poplog's X window
facilities has made it very easy within the X window framework to create
certain sorts of graphical displays generated by program commands.

The facilities provided are described in

    TEACH RC_GRAPHIC
    HELP RC_GRAPHIC

This package supports "relative coordinate" graphical commands: the
user can specify a coordinate frame, and then give graphical commands
which will then be carried out relative to that frame, with automatic
conversion to the low level X coordinate frame. Thus it is easy to put
the centre of the coordinate frame in the middle of a window, with Y
increasing upwards, instead of using the X default, with the origin in
the top left corner and Y increasing downwards.

David Young, at the University of Sussex, provided a useful collection
of extensions to the package, for drawing graphs of various kinds.

    TEACH RC_GRAPHPLOT
    HELP RC_GRAPHPLOT

He also provided some image manipulating facilities based on RC_GRAPHIC
in the "popvision" library, available from the Free Poplog Web site:
    http://www.cs.bham.ac.uk/research/poplog/freepoplog.html

If this is installed in your system try
    uses popvision
    HELP POPVISION

Newcomers to Pop-11 need not pay much attention to the relationships
between RC_GRAPHIC and RCLIB, since most of the former's functionality
is smoothly subsumed by the latter. However people who are already
familiar with rc_graphic may find some of the new facilities confusing,
especially if they have used LIB rc_context, now replaced and
generalised by rc_window_object or LIB rc_mouse, now subsumed by
utilities like rc_get_coords, rc_app_mouse, rc_mouse_draw, all described
below.

-- Limitations of RC_GRAPHIC ------------------------------------------

This package has many limitations, although it is very useful for
elementary 2-D graphics.

1. The graphical objects drawn using rc_graphic are not represented in
program-accessible structures: they are merely represented on the
screen. Thus a program cannot move or rotate them.

RCLIB provides a class of graphical objects which can be moved either by
program or by mouse.

2. The drawing procedures in Rc_graphic assume that there is a current
graphical window, and all drawing goes into that window. This makes it
difficult to draw in different windows, especially if those windows have
different properties, such as a different coordinage frame.

A partial solution to this was proved in LIB rc_context, described
briefly in
    HELP RC_GRAPHIC/RC_CONTEXT

This is messy and complicated and in the RCLIB package the idea is
replaced by treating windows as objectclass instances which have a lot
of information that can be used by drawing procedures.

3. The RC_GRAPHIC library does not make it easy to add mouse or keyboard
sensitive items such as buttons, sliders, scrolling text-panels, etc. to
the basic RC_GRAPHIC windows. RCLIB provides a wide range of such
facilities.

Since the RCLIB mechanisms are based on objectclass, and the source code
is available, they should be very easy to extend or modify, which is not
true of all other X based packages. The RCLIB utilities are also more
flexible than those found in standard widget sets, e.g. supporting
sliders that are not constrained to be vertical or horizontal.
(See HELP RC_SLIDER)

The RCLIB package provides an object-oriented extension to RC_GRAPHIC,
based on the Pop-11 Objectclass library. See HELP OBJECTCLASS

Objectclass allows classes and subclasses to be defined which make
use of powerful inheritance mechanisms, including multiple inheritance.
Methods can be associated with various classes which are invoked when
mouse or keyboard events occur, or when certain programmable events
occur. These methods can be re-defined for different subclasses, or
replaced at the level of individual instances. This makes it very easy
for a variety of applications to share a collection of general
utilities, and for special types of objects to be given their own
special event handling and other capabilities.

Using these ideas, RCLIB adds to RC_GRAPHIC a variety of interaction
devices (e.g. various kinds of buttons, menus, sliders, control
panels, etc.) which previously required the use of propsheet.

It also allows pictures to be drawn that can later be manipulated either
by programs or by the user via the mouse, for instance moving objects
around on a picture to change the locations in a simulation program.

The basic facilities for drawing static and moving pictures and handling
events are described in more detail in HELP RC_LINEPIC. The remainder
of this file gives a more general overview.

The programs are extended and improved from time to time. I shall
attempt to make sure that all changes are summarised in
    HELP RCLIB_NEWS

There may be some problems with colours if you use moving picture
objects. see HELP RCLIB_PROBLEMS.

That file also draws attention to some problems concerning compatibility
with older packages based only on RC_GRAPHIC, and with colour maps if
you are not using an 8 bit display.

-- NOTE on mixing RC_GRAPHIC and RCLIB facilities ---------------------

The RCLIB facilities include a new class rc_window_object. Wherever
possible instances of this (or its subclasses) are used as windows on
which drawing can be done and buttons, sliders and other interactive
mouse-sensitive devices can be placed.

If you use the facilities for mouse sensitive pictures you should
not create rc_graphic windows using rc_start or rc_new_window, and you
should not use rc_context (described in HELP RC_GRAPHIC) to switch
between windows.

Instead create windows using rc_new_window_object (or one of its
derivatives) and switch between windows by assigning an rc_window_object
instance to the active variable rc_current_window_object, as
demonstrated in the RCLIB teach and help files.

WARNING: If the old and the new facilities are mixed then it is likely
that the rc_graphic global variables used by both will become
inconsistent.

In particular, instances of the class rc_window_object, and methods and
procedures that apply to them should be used instead of using
the lgobal variable rc_window (defined in HELP RC_GRAPHIC) and
procedures that operate on it.

The value of rc_window and other rc_graphic globals will be set
automatically when an instance of rc_window_object is assigned
to rc_current_window_object.

When that happens the "old" rc_graphic utilities described in the
HELP and TEACH files for the RC_GRAPHIC library and also RC_GRAPHPLOT
can be used to draw lines, circles, etc., print strings, draw graphs,
etc. on the "current" window object.

See the following file for an explanation of how some widget procedures
can be extended so that they operate on rc_window_objects:

    HELP RC_EXTEND_UTILS

See also HELP rclib_compatibility

The remainder of this file gives an overview of the original Pop-11
RC_GRAPHIC facilities as well as the the RCLIB extensions.


-- RC_GRAPHIC facilities to avoid -------------------------------------

Use of the following items listed in HELP RC_GRAPHIC may cause trouble,
e.g. since they do not take account of RCLIB's automatic detection of
type of display and drawing functions required, or because they use
global variables not heeded by all RCLIB facilities.

Procedures to avoid:
   rc_mouse_draw(listpoints, stop_button)
        Use rc_mouse_coords

   rc_transxyin(x_window, y_window ) -> (x_user, y_user) ;
        Use rc_transxyin_in

   rc_mousexyin
        New version defined as a method in LIB rc_mousepic

   rc_mouse_setup(widget)

   rc_mouse_disable(widget)
        Various rc_window_object facilities replace this

   rc_mouse_do(first_input, other_input, test_exit)
        Compare rc_app_mouse

Global variables no longer relevant
   rc_button_procedures (list, default [])
   rc_mousing   (boolean, default false)
   rc_move_procedures (list, default [])
   rc_rubber_function (integer)

Avoid items related to LIB RC_CONTEXNT
   rc_context_vars
   rc_context
   rc_destroy_context

instead use methods for rc_window_object and the global (active)
variable rc_curren_window_object

Clipping facilities in RC_GRAPHIC

These occasionally useful variables and procedures

    rc_clipping rc_xmin rc_xmax rc_ymin rc_ymax
    rc_clip_region(region)
    rc_clip_region(xmin, xmax, ymin, ymax)

are respected by rc_drawline, but not by most other graphical facilities
which directly invoke X drawing utilities, e.g. these rc_graphic
facilities have never respected the clipping variables:
    rc_arc_around
    rc_draw_arc

Other things that may cause problems are as follows

    RC_GRAPHIC utility      RCLIB replacement (described below)
    =================       ================
    rc_shift_frame_by       rc_shift_window_frame_by
    rc_set_scale            rc_set_window_scale
    rc_new_window           rc_new_window_object

Frame rotation facilities:

    rc_frame_angle (active variable, current rotation angle)
    rc_rotate_frame(angle)
    rc_rotate_xy(user_x, user_y) -> window_y -> window_x

These facilities are probably subsumed by instances of the rc_rotatable
mixin. If not, a new sub-class of rc_window_object should be created
which supports a global "frame angle".

Active variables to use with care:

    RC_GRAPHIC utility      RCLIB replacement (described below)
    =================       ================
    rc_linewidth            rc_line_width(win)
    rc_linefunction         See HELP rclib_problems/Glinefunction
                                and rc_setup_linefunction, below

Starting a new window or clearing the current one

    rc_start()

The procedure rc_start() has been redefined to work with RCLIB, but
may occasionally give problems. It can create a new default window if
there is no current window object. Otherwise it simply clears the
current window object.
    See HELP rclib_compatibility


-- RC_GRAPHIC and its extensions: an overview -------------------------

The main purpose of the RCLIB directory tree is to provide a collection
of useful extensions to the RC_GRAPHIC library distributed with Poplog.

LIB RC_GRAPHIC is the Pop-11 "Relative-Coordinates" Graphic library
providing a convenient interface to the Pop-11 X Graphic utilities.
It is described in TEACH RC_GRAPHIC and HELP RC_GRAPHIC.

The RC_GRAPHIC library allows you to create procedures that employ a
user-defined coordinate frame for drawing in a graphic window, instead
of the standard pixel-based frame. E.g. instead of the origin being at
top left it can be anywhere in the window. Moreover the X and Y scales
can differ and be positive or negative.

Global variables used: rc_xorigin, rc_yorigin, rc_xscale, rc_yscale

The numbers may be integers, decimals, ratios, etc. and may be positive
or negative. The system starts with default values that put the origin
in the middle of the window, with rc_yscale set to -1, so that the
y-axis goes up the screen not down.

The library defines a collection of graphical procedures, including
"turtle" graphics (i.e. drawing procedures relative to a current state
represented as the location and heading of a "turtle" moving on the
screen).

Global variables used: rc_xposition, rc_yposition, rc_heading

There are several different parts of the old RC_GRAPHIC library, which
will now be described, after which the new RCLIB facilities are
described in more detail.

-- Facilities provided in LIB RC_GRAPHIC, prior to RCLIB --------------

All of the following are documented in HELP RC_GRAPHIC

 --- Startup and re-start procedure
 ---     rc_start()
    Redefined in LIB RC_WINDOW_OBJECT

 ---     rc_wm_input   (default -false-)
 --- Altering window size and location
 ---     rc_window_xsize   (default 500)
 ---     rc_window_ysize   (default 500)
 ---     rc_window_x   (default 520)
 ---     rc_window_y   (default 300)
 ---     rc_window
 ---     rc_new_window(width, height, xloc, yloc, setframe)
 ---     rc_setsize()
 ---     rc_clear_window()
    Defined in rc_graphic and also in LIB rc_window_object
 --- Setting or altering the coordinate frame relative to window
 ---     rc_xorigin, rc_yorigin, rc_xscale, rc_yscale
 ---     rc_set_coordinates(xorigin, yorigin, xscale, yscale)
 ---     rc_shift_frame_by(x, y)
 ---     rc_stretch_frame_by(scale)
 --- Drawing and jumping relative to current location and heading
 ---     rc_xposition, rc_yposition, rc_heading
 ---     rc_turn(angle)
 ---     rc_jump(amount)
 ---     rc_jumpby(dx, dy)
 ---     rc_drawto(pointcoords)
 ---     rc_drawby(dx, dy)
 ---     rc_draw(amount)
 ---     rc_point_here()
 ---     rc_newposition(amount) -> newy -> newx
 ---     rc_draw_rectangle(width, height)
 ---     rc_draw_oblong(width, height, radius)
 ---     rc_arc_around(radius, degrees)
 --- Absolute drawing and jumping
 ---     rc_jumpto(pointcoords)
 ---     rc_drawpoint(pointcoords)
 ---     rc_drawline(pointcoords1, pointcoords2)
 ---     rc_draw_arc(pointcoords, width, height, angle1, angleinc)
 --- Saving and restoring "turtle" state
 ---     rc_save_state() -> state
 ---     rc_restore_state(state)
 --- Transformations from and to user coordinates
 ---     rc_transxyout(x_user, y_user) -> y_win -> x_win
 ---     rc_transxyin(x_win, y_win) -> y_user -> x_user



-- Additional parts of the RC_GRAPHIC library -------------------------

The library as distributed with Poplog includes the following.

-- -- LIB rc_mouse (avoid)

This package enables line drawing etc to be controlled by button presses
using sensitivity to mouse movements to indicate, with a "rubber band"
where the next line will go. It is described in
    TEACH RC_GRAPHIC/rc_mouse and HELP RC_GRAPHIC/rc_mouse

Most of the facilities of this library are superseded by mechanisms
described below.

E.g. The following procedure takes over some of the functions of
rc_mouse_draw:

    rc_mouse_coords(stop_button) -> list;

    LIB rc_point defines the method:
        rc_get_mouse_points(win_obj:rc_window_object, radius, pdr, stop_button);

    Which is defined in terms of
        rc_app_mouse(pdr, stop_button);

    LIB rc_get_coords defines the method
        rc_get_coords(win:rc_window_object, pdr, button);

These procedures are described in more detail below.

-- -- LIB rc_context (avoid)

This extension to RC_GRAPHIC should not be used alongside RCLIB
facilities.

It allows several graphical windows to be managed at once, with only one
of them the current window at any time.

    HELP RC_GRAPHIC/rc_context

While useful, it does not have the benefits of a system based on a
object oriented approach. It is superseded by the use of
rc_new_window_object to create windows, and the assignment of such
windows to the active variable: rc_current_window_object

-- -- LIB rc_rotate_xy (avoid)

Defines additional global variables for use by the co-ordinate
transformation system, accessed via the "active" variable
rc_frame_angle, and the procedure rc_rotate_frame. Redefines the
coordinate transformation procedures for input and output in rotated
coordinate frames. For details see

    TEACH RC_GRAPHIC/Rotating, HELP RC_GRAPHIC/rc_rotate_xy

This is probably superseded by the rc_rotatable mixin and associated
methods described below.

-- -- LIB rc_graphplot

This extends the basic RC_GRAPHIC facilities with a wide range of
options for drawing graphs. This library is included with the standard
Poplog distribution. For details see

    TEACH RC_GRAPHPLOT, HELP RC_GRAPHPLOT

Libraries
    LIB RCG_UTILS, LIB RC_GRAPHPLOT, LIB RC_GRAPHPLOT2

These should work with RCLIB, though there may be occasional
inconsistencies in the way global variables are used to define a
current drawing context.

See HELP RCLIB_PROBLEMS

-- -- LIB rc_set_coord_frame (avoid)

A procedure for conveniently modifying the coordinate frame, e.g. to map
a 2-D array into a specified region of the graphical window.
    See HELP RC_GRAPHIC/rc_set_coord_frame

This is mostly superseded by facilities based on rc_window_object,
especially this method

    rc_shift_window_frame_by(x, y, win_obj:rc_window_object);

described below.

It is possible to assign a four element vector defining a coordinate
frame to the rc_window_origin slot of a window object instance.

-- -- LIB rc_set_scale (avoid)

This is replaced by rc_set_window_scale described below.

For details of rc_set_scale(type, xscale, yscale)
See LIB rc_set_scale

Assumes this default, which you may have to change:
    90 -> rc_pixels_per_inch ;

-- -- LIB popvision

This library, developed by David Young at Sussex University, provides a
range of facilities for manipulating bitmaps and other images in an
rc_graphic window, and also includes a variety of image processing
utilities useful for work in vision.

See TEACH POPVISION (at Birmingham)
    HELP POPVISION (if already installed)

The package is available by ftp from Sussex University in the directory

    ftp://ftp.cogs.sussex.ac.uk/pub/poplog/popvision

and (packaged slightly differently) in the Free Poplog directory

    http://www.cs.bham.ac.uk/research/poplog/popvision.tar.gz
    ftp://ftp.cs.bham.ac.uk/pub/dist/poplog/popvision.tar.gz


For information about the latest version of the popvision package email
davidy@cogs.sussex.ac.uk or post queries to comp.lang.pop


-- Extensions provided by RCLIB ---------------------------------------

RCLIB, developed at the University of Birmingham, extends the RC_GRAPHIC
library further by providing a directory usually installed at

    $poplocal/local/rclib/

containing additional graphical utilities making use of the rc_graphic
framework. Some of them are autoloadable after you have compiled

    uses rclib

or the file

    $poplocal/local/rclib/rclib.p


The RCLIB directory tree normally contains the following subdirectories:

    auto/
        Autoloadable utilities
    lib/
        Additional utilities (requiring "lib" or "uses").
    teach/
        Tutorial introductions
    help/
        More formal descriptions
    demo/
        The files in here can be viewed using this command
            ENTER rcdemo <filename>

    E.g. to look at the file
        $poplocal/local/rclib/demo/rc_ant_demo.p
    Give the command
            ENTER rcdemo rc_ant_demo

    To look at Riccardo Poli's neural net demo do
            ENTER rcdemo rc_neural.p

Further details follow.

-- The class/mixin structure of RCLIB --------------------------------

There are various types of classes and mixins defined by RCLIB, using
the Objectclass mechanisms.

-- -- Window object classes and picture object classes

The two main types of classes are

(a) Classes of complete "window objects", which are all subclasses of
the class rc_window_object, defined in LIB RC_WINDOW_OBJECT.
This file provides the basic methods and procedures for creating and
manipulating window objects.

(b) Classes of "picture objects" which can be drawn inside window
objects, and which may be static or movable, fixed or changing in their
appearance. These are generally based on the mixins defined in LIB
RC_LINEPIC, as follows.

-- -- Picture object mixins in LIB rc_linepic

The library LIB rc_linepic defines the basic mixins for picture objects,
and all the basic methods for drawing them, for undrawing them, and for
moving or rotating them.

    define :mixin rc_linepic;
        These can be drawn in a graphic window. They have their own
        internal coordinate frame. They are displayed using rc_graphic
        drawing procedures for drawing objects relative to a coordinate
        frame. A simple notation has been defined for specifying what
        instances of this mixin should look like, specified in the
        slot rc_pic_lines (for drawing the object) and the slot
        rc_pic_strings (for adding labels drawn in various fonts, with
        various colours, etc.) Two more important slots rc_picx and
        rc_picy define the location of the object. The main method
        available for this class is rc_draw_linepic.

    define :mixin rc_linepic_movable; is rc_linepic;
        Instances of this mixin can be moved, using methods like
        rc_move_to and rc_move_by. The moving is done by UNdrawing
        the object using (rc_undraw_linepic) and then drawing it
        in the new location. This works if the picture is first
        drawn using either XOR or EQUIV as drawing style. This causes
        some problems described in HELP RCLIB_PROBLEMS, but is extremely
        convenient for producing movable objects.
        Usually moving is done by means of one of the methods rc_move_to
        and rc_move_by.

    define :mixin rc_rotatable; is rc_linepic_movable;
        This mixin extends the above facilities by providing a current
        orientation, represented by the value of the slot rc_axis.
        The orientation can be changed using the methods rc_set_axis
        and rc_turn_by, or methods derived from these.
        rc_set_axis produces a new orientation for a rotatable object
        and rc_turn_by rotates the object by a specified angle, assumed
        to be in degrees.
        When the angle in the slot rc_axis is0, the internal coordinate
        frame of of the picture object is aligned with the coordinate
        frame of the window in which it is drawn.

    define :mixin rc_rotatable_picsonly; is rc_rotatable;
        Rotation methods for this mixin are defined so that strings are
        not rotated, only the pictures.

-- -- Mixins defined in LIB rc_opaque_mover

Derived mixins are in LIB rc_opaque_mover

    define :mixin rc_opaque_movable; is rc_linepic_movable;
    define :mixin rc_opaque_rotatable; is rc_opaque_movable rc_rotatable;

        These allow objects to move without using xor/equiv as drawing
        function. Thus they work properly only when constrained to
        move in a region with a uniform background colour.
        These are used in rc_opaque_slider rc_constrained_pointer
        and rc_dial

-- -- Classes and mixins in LIB rc_window_object

There are additional mixins and classes defined in LIB rc_window_object,
which can be combined with the above.

In particular, all the types of mouse sensitive or keyboard sensitive
window objects have to have their methods invoked via the window that
contains them. So the library LIB rc_window_object introduces the basic
class of window objects that can be manipulated and can be made
sensitive to various kinds of events. All other event-sensitive types of
objects created using rclib can do nothing unless the containing window
object knows about them (e.g. after use of rc_add_pic_to_window.
Some objects can exist in different window, where they may be shown at
different scales or orientations, as defined in LIB rc_linked_pic,
described below.

    define :mixin rc_selectable;
        For windows and picture objects which are sensitive to mouse
        events,

    define :mixin rc_keysensitive;
        For windows and picture objects within which keyboard events can
        occur and be handled.


    define :class rc_window_object;

        This class inherits slots and methods from the above two mixins
        rc_selectable  rc_keysensitive.

        However, for instances of rc_window_object to benefit from the
        event handlers for mouse or keyboard events, they need to be
        made "sensitive" to sunce events by using the procedure
            rc_mousepic(win_obj)

        described below. Some window creating procedures automatically
        invoke rc_mousepic, e.g. rc_control_panel and its derivatives.
        But you can create a window which is not mouse or keyboard
        sensitive, though it can be drawn on by programs.

-- -- Other classes and mixins
    See the information below about classes and mixins defined in these
    libraries
       LIB rc_informant
       LIB rc_buttons
       LIB rc_constrained_mover
       LIB rc_freezable
       LIB rc_linked_pic
       LIB rc_point
       LIB rc_polyline
       LIB rc_scrolltext
       LIB rc_text_input

-- -- Picture objects that are mouse- or keyboard-sensitive

NOTE: Picture objects can also inherit from the mixins rc_selectable and
rc_keysensitive. After creation they can be added to particular windows
by means of the following method described below, in HELP rc_linepic
and in HELP RC_EVENTS

    rc_add_pic_to_window(
        pic:rc_selectable, win_obj:rc_window_object, atfront);

Such picture objects may then be acted on by mouse and/or keyboard,if
the window to which they have been aded has been made sensitive by
means of the method rc_mousepic.

Merely drawing a picture object PO on a window W will not make the
window object corresponding to W aware of PO. So just because an
instance of rc_selectable has been drawn on W and W is mouse-sensitive,
it does not follow that PO will be movable by means of the mouse. For
that to happen, rc_add_pic_to_window must be used to make W aware of PO.

However program commands using methods like rc_move_to, rc_turn_by,
and rc_undraw_linepic can be used to move PO around the window, rotate
it, etc., even it cannot be accessed iva the mouse.

For some classes of picture objects it makes no sense to draw them
unless they are to be accessible via the mouse. So in that case the
invocation of rc_add_pic_to_window is done by the method that creates
instances for that class. Button picture objects are an example, as are
sliders.


-- rc_mousepic: Making a window sensitive to mouse or keyboard events

A more comprehensive account of event handling is given in
    HELP RC_EVENTS

This file gives a partial overview in this and the next few sections.

The procedure procedure rc_mousepic takes a window object and optionally
a possibly empty list of event types, or false:

        rc_mousepic(win_obj)
        rc_mousepic(win_obj, [...event types...])
        rc_mousepic(win_obj, false)

It is used to specify the types of events which can be handled within
the window object.

If the second argument is false, then all event handling is disabled.

The optional list argument specifies the types of sensitivity given to
the window. If no list is provided, or if the list is empty, then it
defaults to this:

        [button motion mouse keyboard]

The words in the list are interpreted as follows:

    "button"
        specifies that the window should be sensitive to a mouse button
        going up or down.

    "motion"
        specifies that the window should be sensitive to a mouse pointer
        moving within the window.

    "mouse"
        specifies that the window should be sensitive to the mouse
        pointer entering or leaving the window.

    "keyboard"
        specifies that the window should be sensitive to a keyboard
        key being depressed or released.

Instead of or inaddition to the event type "motion" it is possible to
specify "dragonly". This means that only drag events will be handled,
and other types of motion events ignored, in the window.

The first three types of events are relevant to instances of the mixin
rc_selectable. The last one is relevant to instances of rc_keysensitive.

Event handling is described in more detail in HELP RC_EVENTS

See REF XEvents for more on available event types supported by the
Poplog X interface. It may be possible later on to extend RCLIB to
provide convenient extensions to more event types, though the existing
Pop-11 X facilities can be used directly when necessary.
    (See REF Xpw, and files referenced therein.)


-- How events are handled ---------------------------------------------

When an event of any of the above types occurs in a window which has
been made sensitive by rc_mousepic, the rclib system event handler
decides whether it should be handled by the window or by an object which
is in that window and known to the window as a mouse or keyboard
sensitive object.

Depending on which it is, an appropriate method is invoked, and applied
to the window or picture object along with additional information. The
method is found by looking in an appropriate slot in the window object
or picture object, as described below. Instead of a single method the
slot may hold a list of methods, in which case they will all be run,
unless one of them aborts the rest. Since that list can be changed
dyamically that provides considerable flexibility.

The type of information provided for each method depends on the type of
event. Typically the event handling method is applied to these items:

    the selected picture object or the window object

    x and y values corresponding to the mouse pointer location in the
        rc_graphic coordinates relevant to that window, at the time of
        the event

    modifiers, a possibly empty string, specifying which of the keyboard
        modifier keys happens to be down at the time. The string may
        contain any combination of the following ASCII characters:
            `s` = shift key depressed
            `c` = control key depressed
            `m` = meta key depressed
                    (which key this is will depend on the keyboard)

In the case of keyboard events, the handler is given an additional
argument:

    key, an integer representing the ascii character code for the key or
        some other code for non ascii keys. If the integer is positive
        the key has been pressed. If negative it has been released.

Note: it might have been more consistent to have different methods for
handling keypress (down) events and keyrelease (up) events, as has been
done for mouse buttons. However it was felt that separating "mouse down"
and "mouse up" events was far more important, e.g. when the mouse goes
down prior to dragging and up after dragging.

If desired it is easy to define a sub-class of rc_keysensitive which has
two more slots, one holding a method to be invoked for presses and
another for releases. Then the default keypress handler method for that
class of objects could select one or other method, depending on whether
its key argument is positive or negative.

It is also possible to associate a type of event with a list of
handlers, as described below. So separate handlers for presses and
releases can simply be defined to check whether the key argument is
positive or negative, and held in a list in the rc_keypress_handler
slot. See entries below for these procedures, which make it possible to
add, delete, or interrogate a picture object's or a window objects'
event handlers at run time.

    rc_add_handler, rc_delete_handler, rc_current_handlers


-- Event handling methods ---------------------------------------------

Various types of event handling are available in RCLIB

The events are controlled by methods associated with instances of
rc_window_object and rc_linepic, and their various subclasses, which
include control_panels, buttons, sliders, text_input panels, etc.

The main types of events supported are those involving the mouse and
mouse buttons, associated with the rc_selectable mixin, and those
involving keyboard keys being pressed and released, associated with the
rc_keysensitive mixin.

(a) Mouse button events
    These are held by handlers in the following slots defined in the
    rc_selectable mixin, each of which holds a three element vector:

    slot rc_button_up_handlers =
        { rc_button_1_up rc_button_2_up rc_button_3_up };

    slot rc_button_down_handlers =
        { rc_button_1_down rc_button_2_down rc_button_3_down };


(b) Mouse dragging events (motion with a button down)

    slot rc_drag_handlers =
        { rc_button_1_drag rc_button_2_drag rc_button_3_drag };


(c) Mouse motion events (with no button down)

    slot rc_move_handler = "rc_move_mouse";


(c) Mouse entry/exit events
    slot rc_entry_handler ="rc_mouse_enter";
    slot rc_exit_handler ="rc_mouse_exit";


(d) Keyboard events (in instances of the rc_keysensitive mixin)

    slot rc_keypress_handler = "rc_handle_keypress";

    The default value of this slot for picture objects which are not key
    sensitive is a method:

         define :method rc_keypress_handler(pic:rc_linepic);

    which returns false as its value, so that they do nothing.

    For other classes new handlers may be defined.
    E.g. LIB RC_SCROLLTEXT provides a version which emulates some
    simple editor motion commands. (See the library file for details: the
    handler is user-definable, but the default could be improved.)

    In LIB RC_TEXT_INPUT the default method is
        rc_handle_text_input(pic:rc_text_input, x, y, modifier, key);
    this is also redefinable and extendable.

Further details are in:   HELP RC_EVENTS

Additional types of events and event handlers may be handled later.

-- -- How to associate an object with event handlers

The particular event handler which fills a slot, or is included in one
of the above vectors may be specified as a pop-11 procedure or an
objectclass method or a list of event handlers (or their names).

A handler slot (or the relevant part of a vector) may hold the boolean
value false, which is interpreted as an indication that the object has
no handler. I.e. the event is ignored.

Having a list of event handlers allows different tasks to be done by
different handlers, and also allows some aspects of the event handlers
to change dynamically. It is also possible to run a standard event
handler for the class preceded and/or followed by a specific event
handler for the instance. In some cases an earlier event handler
can act as a filter causing the others not to run, by making the
variable rc_no_more_handlers true.
    See
    LIB rc_mousepic/rc_no_more_handlers

See also information below concerning these methods:
    rc_add_handler
    rc_current_handlers
    rc_delete_handler


-- -- Using indirection to facilitate development and testing

In many cases it suffices if the occupant of a slot or the relevant
location in a vector is not an event handline method, but the NAME
of the method.

In that case it will be dereferenced when needed (using
recursive_valof). This has the advantage that during development and
testing a method can be edited and recompiled and then all objectclass
instances that use it will automatically get the new version rather than
the original. This can enormously speed up development and testing.

It also allows temporary (dynamic) changes to event handlers using the
Pop-11 dlocal mechanism (see HELP DLOCAL).


-- -- Event handling contexts

Pop-11 pogrammers often find that their event handlers cause obscure
errors, including "access violation" because they are run in an
inappropriate context, e.g. in which it is not safe to do anything that
might trigger a garbage collection. Use of the system procedure
external_defer_apply can avoid this danger but it may be difficult to
work out where it should or should not be used, and programmers often
forget to use it, thereafter encountering obscure bugs.

RCLIB reduces the risks by ensuring that in the "normal" case, described
below, event handling methods are invoked through external_defer_apply.

Another problem that can occur is attempting to invoke a Ved or Xved
mechanism from an event handler, e.g. if clicking on a button should
cause a file to be opened, or a marked range deleted. The problem is
that if XVed is running it has its own process thread, and these actions
will not be performed properly unless given to vedinput. However if it
is Ved, not XVed that is running the requirements are different. Writing
programs that work equally well in both contexts can be very tiresome.
RCLIB simplifies this by ensuring that the appropriate mechanism is
used, in at least the cases that cause most problems, namely action
buttons.

It used to be necessary to use the the "INVED" action type to ensure
that appropriate mechanisms are used for actions involving the editor.
Since September 2002 this is no longer necessary.

For more on this see HELP * RC_EVENTS

-- -- Three main types of event handling contexts in RCLIB

The context in which an event is handled may be one of two main types.
Until September 2002 there were three main types, immediate, normal and
deferred, but the first two have now been merged. The need for the
"immediate" type has been removed by generalising the "normal" type
to cope in circumstances where previously only the "immediate" type
would cope. So the two remaining types are

    1. Normal
        The event is handled immediately, but in the context where the
        activated window object is the value of rc_current_window_object.
        It is also the value of rc_active_window_object, a global
        variable that refers to the last window in which an event was
        handled.
        To minimise the risk of bugs due to the use of call-backs all
        user-defined event handlers are evoked using the procedure
        external_defer_apply, described in REF * EXTERNAL. This makes it
        safe for an event handler to trigger a garbage collection for
        instance, which could otherwise crash poplog.

        As explained in HELP * RC_CONTROL_PANEL and HELP * RC_BUTTONS
        action buttons requiring normal event handling can be specified
        using the keywords "POP11" (The keyword "POPNOW" previously
        indicated an "immediate" event. Instead this is now equivalent
        to the action button keyword "POP11".)

            [POP11 ....]

    2. Deferred
        As for type normal, these are handled by external_defer_apply,
        but in a context where rc_current_window_object and its
        associated variables have been re-set to what they were before
        the event occurred.
        Where ACTION buttons are used, these events are indicated by
        the keyword "DEFER", in an action specification.
            [DEFER .....]

        An event run in this context can assign a new window object to
            rc_current_window_object.

        The window in which the event occurs remains accessible as the
        value of rc_active_window_object.

The distinctions between these contexts are catered for most clearly in
connection with action buttons. However various kinds of event handlers
can trigger many methods indirectly and care is needed to ensure that
when propagating effects using reactor methods or checking constraints
in constraint methods the context is dealt with appropriately. In
particular, although the use of action buttons forces you to think about
the context, and defaults to the "normal" case, the system cannot check
whether a procedure you have chosen to run in the normal context is
unsuitable for the purpose!

Further information about event handling, along with examples, can be
found in:
    HELP RC_EVENTS
    HELP RC_LINEPIC
    HELP RC_BUTTONS
    HELP RC_CONTROL_PANEL
    HELP RC_SLIDER
    HELP RC_SCROLLTEXT
and the corresponding libraries.

There are also examples in

    TEACH RC_ASYNC_DEMO
    TEACH RC_LINEPIC
    TEACH RC_CONSTRAINED_PANEL

and other demonstration teach files.

Expert users who wish to allow certain callbacks that do not go through
external_defer_apply can either use the low level poplog X facilities,
or else redefine the procedure rc_handle_event in LIB * RC_MOUSEPIC
taking care not to disrupt any of the existing uses of that procedure.


-- AUTOLOADABLE FACILITIES IN RCLIB -----------------------------------

The following are automatically made available by the command

    uses rclib

Additional important procedures are defined in the non-autoloadable
libraries listed below.

-- -- ARGS (Macro for optional arguments)

The RCLIB package includes a Pop-11 macro ARGS, originally suggested by
Brian Logan, which makes it easy to define procedures with optional
extra arguments, as required for many of the instance creation
procedures, since they may specify additional optional information to
override defaults when the instance is created.

A procedure which has three compulsor arguments x, y, z and three
optional arguments A, B, C, could start as follows:

    define args_example(x, y, z);

        ;;; set up defaults for optional args
        lvars A = undef, B = 0, C = [];

        ARGS x, y, z, &OPTIONAL A:isword, B:isinteger, C:islist;
        .........
        etc.

Here the ARGS expression expands to something like:

    repeat
        if islist(z) then
            (x, y, z) -> (x, y, z, C)
        elseif isinteger(z) then
            (x, y, z) -> (x, y, z, B)
        elseif isword(z) then
            (x, y, z) -> (x, y, z, A)
        else
            quitloop()
        endif
    endrepeat;

;;; example

define silly(p, q, r) -> result;
    ;;; A procedure with up to two extra arguments, A, a boolean and
    ;;; B a number

    ;;; give them default values.
    lvars A = false, B = 0;

    ARGS p, q, r, &OPTIONAL A:isboolean, B:isnumber;

    [%p, q, r, A, B%] -> result
enddefine;

;;; test it

silly([1], [2], [3]) =>
** [[1] [2] [3] <false> 0]
silly([1], [2], [3], true) =>
** [[1] [2] [3] <true> 0]
silly([1], [2], [3], 99) =>
** [[1] [2] [3] <false> 99]
silly([1], [2], [3], true, 99) =>
** [[1] [2] [3] <true> 99]
silly([1], [2], [3], 99, true) =>
** [[1] [2] [3] <true> 99]


-- -- async_apply
async_apply(proc);
    ;;; apply the procedure, raise any new file, but don't
    ;;; warp context. Suitable for buttons rotating or swapping
    ;;; files, etc.
    (Previously used in callbacks, but not necessary now)

-- -- async_interpret_action
async_interpret_action(action);
    This procedure is run when the action in an action button is a list.
    It interprets the list according to rules described in
        HELP RC_BUTTONS

-- -- async_unix_obey
async_unix_obey(list);
    list is either of the form [<commandstring>] or
    [<commandstring> <shell pathname>]
    See REF SYSOBEY, REF VEDGENSHELL, HELP PIPEUTILS

-- -- async_vedinput
async_vedinput(P);
    ;;; This is needed for putting stuff on VED input stream in Xved
    ;;; Otherwise do the action immediately

-- -- create_modified_instance
create_modified_instance(vec, creator) -> object;
    [No longer needed]


-- -- define_rc_defaults

LIB define_rc_defaults

Autoloadable version of rc_defaults, described below.


-- -- files_matching

files_matching(path, filter, with_dirs, with_dotfiles, dirs_first) -> vec;

    Return a vector of strings corresponding to the path name, using the
    given filter pattern.
    if with_dirs is true, include the directory above the path and
    the directory of the path, as well as the matching files.
    If with_dotfiles is true, include all dotfiles. e.g. .login

Example

uses rclib
uses files_matching

files_matching('~', '*', false, true, false) ==>

files_matching('$usepop/pop', '*', false, true, false) ==>


-- -- forevery
This modified version of forevery is redefined to use pattern_instance
instead of instance, to avoid clashes with objectclass.
    See HELP FOREVERY

-- -- is_pattern_string

Recognise strings containing pattern elements

define is_pattern_string(string) -> boolean;
    strmember(`*`, string)
    or strmember(`?`, string)
    or strmember(`[`, string)
    or strmember(`{`, string)
    or issubstring('/.../', string) -> boolean;
enddefine;

See HELP SYS_FILE_MATCH for pattern formats

-- -- interpret_specs

interpret_specs(obj, specs);
    Obj is a newly created objectclass instance. Spec is a featurespec
    describing how it should be modified so as to differ from the
    default. See HELP FEATURESPEC, which describes how to create
    re-usable featurespec descriptors, for temporarily changing the
    defaults for one or more classes of buttons.

-- -- isrc_panel_field

Autoloadable recogniser procedure for panel field instances,
pre-defined in case the relevant mixin has not yet been compiled
(in LIB rc_control_panel).

-- -- isrc_window_object

Autoloadable recogniser procedure for rc_window_object instances,
pre-defined in case the relevant class has not yet been compiled.

-- -- loadrcdemo

loadrcdemo <file>
    This is a macro for compiling files in the rclib/demo/ directory.

-- -- max_string_length

max_string_length(vec) -> num;

    Autoloadable utility. Takes a vector of strings and returns the
    length of the longest string.

-- -- menu_choosefile1
-- -- menu_choosefile2
    These are two tools for selecting files, based on the ved_menu
    facility, which previously used propsheet, but now no longer does.

Both procedures use these global variables

global vars
    menu_choosefile_font = '9x15',
    menu_choosefile_rows = 30,
    ;;;  make this 0 to allow it to expand or contract as needed:
    menu_choosefile_cols = 40;


menu_choosefile1();
    This invokes rc_getfile to present the user with options. If a file
    is selected it is read into the editor.

menu_choosefile2();
    This uses rc_browse_files to present a file browser panel with
    several options available, including expanding directories, editing
    a file, running a program, or giving a file as input to another
    program.


-- -- pattern_instance

pattern_instance(pattern) -> list;
    This is designed to replace instance, which clashes with instance in
    objectclass. Pattern_instance takes a pattern with ? or ?? and
    instantiates ALL the variables in a copy of the pattern. Used in
    FOREVERY, etc.


-- -- print_to_strings

print_to_strings(procedure print_command);
    ;;; run the print command, but instead of sending
    ;;; characters to the terminal, make set of strings,
    ;;; one string per line of output.
    ;;; Leave them on the stack.

This is useful for re-directing print output to a display panel.

e.g.

uses rc_message;

global vars rc_message_instruct = '[CLICK TO DISMISS]';

define testit();
    lvars x, row;

    [%
        for row from 5 to 20 do
            [%for x from 30 to 30 + row do x endfor%]
        endfor %] ==>

enddefine;


rc_message(300,300,strings,1, true, '9x15', false, false)->;
rc_message(300,300,strings,2, false, '9x15', false, false)->;
rc_message(300,300,strings,2, "right", '8x13bold', 'black', 'gray90')->;
rc_message(300,300,strings,2, "right", '8x13', 'black', 'gray90')->;

uses rc_message_wait
rc_message_wait("right", "top", strings, 2, "right", '12x24', 'blue', 'yellow');
rc_message_wait("left",  "top", strings, 2, "left", '6x13', 'blue', 'red');

See also rc_popup_strings, rc_popup_panel and other things.

-- -- rc_add_handler

rc_add_handler(obj, handler, slot, /*num, atend*/);

    obj is the window object or picture object.

    handler is the procedure, or method, to be added, or a word
        which is its name.

    slot is the name of a slot holding event handlers, e.g.
        rc_move_handler rc_entry_handler rc_exit_handler
        rc_keypress_handler
        rc_button_up_handlers rc_button_down_handlers
        rc_drag_handlers
            The last three of these require a number argument.

    num is an optional integer, required for slots that typically hold
        a three element vector, for mouse button events.

    atend is an optional boolean, which defaults to false.
        If true it specifies that the new handler should be put at the
        end of the list of handlers

    handler can be a procedure(method) or word whose valof is a
    procedure(method), or false.
    If handler is FALSE, then the handlers are all cleared.

    See also rc_current_handlers, rc_delete_handler
    and the overview of event handling above.

-- -- rc_add_kill_button

rc_add_kill_button(win, x, y, buttonwidth, buttonheight);

win is a window object, produced by rc_new_window_object
add "KILL" button to win, at location x, y.

if x is false use right edge of window
if y is false us bottom edge of window
Otherwise treat x and y as rc_graphic coordinates for top left of
button.

-- -- -- Global variables for kill buttons

These are used by rc_add_kill_button

define :rc_defaults;
    rc_kill_button_text_col = 'black';
    rc_kill_button_bg_col = 'white';
    rc_kill_button_font = '6x13';
enddefine;

-- -- rc_app_mouse
rc_app_mouse(pdr, stop_button);

    Used to define rc_mouse_coords
    pdr is a procedure that can be applied to two numbers representing
    x and y coordinates in a graphical window and stop_button is an
    integer. It is invoked repeatedly every time you click with
    any mouse button other than stop_button, and pdr is applied to
    the current coordinates of the mouse, after transformation
    using the user definable procedure
        rc_app_mouse_xyin(x, y) -> (x, y)
    See HELP RC_APP_MOUSE

    rc_app_mouse is also used in rc_get_mouse_points, defined in
    LIB RC_POINT

-- -- rc_background
rc_background(window) -> colour;
colour -> rc_background(window);

    Can be used to access or update the background colour of the current
    rc_window. The first form will typically return an integer. In the
    second form colour is a string

    NB. When the colour is updated, the window is cleared.

    See HELP RC_BACKGROUND

-- -- rc_between

rc_between(x, v1, v2) -> boolean

    Return true if value of x lies between v1 and v2, false otherwise.

-- -- rc_black_white_inverted

This is a recogniser for displays in black and white bit values are
inverted.

rc_black_white_inverted() -> isinverted;
    True if white is 1 and black is 0, false otherwise.
    E.g. on Suns white (default background) is 0, and black (default
    foreground) is 1.

See HELP RCLIB_PROBLEMS

This is no longer needed as rc_setup_linefunction now performs the task
previously done by rc_black_white_inverted

-- -- rc_blob_demo

rc_blob_demo(x, y, width, height, maxrad, num, new);

Runs a demonstration showing lots of randomly generated coloured blobs
of different colours and sizes. Examples follow.

rc_blob_demo(10,10,800,800,500,3000,true);
rc_blob_demo(10,10,800,800,200,3000, false);
rc_blob_demo(10,10,800,800,100,4000, false);

The last argument specifies whether to re-use the current window.

The colours available are in a list held in the global variable:
    blobcolours

-- -- rc_browse_files

rc_browse_files (x, y, path, filter, instruct, rows, cols, font, wident) -> panel;
    and optional extra argument container

    x, y,
        Screen location, in numeric or symbolic format,
        e.g. "left", "middle" "right" or "top" "middle" "bottom"

    path, filter,
        Starting directory or file, and a pattern (both strings)

    instruct,
        List of strings to be displayed as text.

    rows, cols, font
        Size of panel used for scroll text, and the font used for the
        strings.
        Either of rows or cols can be 0, allowing the program to decide
        on size of panel.

    wident
        An identifier or word whose valof should always be the currently
        selected file or directory name.

    container (optional)
        If present is a window object (instance of rc_window_object),
        in which case x, y specify location in the container.

One of the panels shown is used to take an action on the currently
selected file. The action to be taken is determined by the
user-definable procedure rc_browser_action, described below.

Example:

uses rclib
uses rc_control_panel
uses rc_browse_files

vars selected_file;

vars instruct = ['Select your file'];

vars panel =
    rc_browse_files (300, 20, '~/', '*',
        instruct, 20, 50, '10x20', ident selected_file);

;;; That creates a panel. You can select a file from the set displayed.
;;; the following variable will hold the selected string.
    selected_file =>

;;; Try varying the directory (3rd argument)
;;; and the filter (4th argument)

vars panel2 =
    rc_browse_files (300, 20, '$usepop/pop/help/', 'ved*',
        instruct, 20, 50, '10x20', ident selected_file);


See also ved_browser, below, and rc_procbrowser

-- -- rc_browser_action

rc_browser_action(file);

This user-definable procedure can determine what to do with "accepted"
files in the rc_browse_files procedure. The default is something like
this (use showlib to check):

define vars rc_browser_action(file);
    if isendstring('.ps', file) then
        veddo('bg ghostview -a4 -magstep -1 ' <> file);
    elseif isendstring('.ps.gz', file) then
        veddo('bg gunzip -c ' <> file <> '| ghostview -a4 -magstep -1 -');
    elseif isendstring('.dvi', file) then
        veddo('bg /bham/pd/packages/tex/bin/xdvi -s 4 -paper a4 ' <> file);
    elseif isendstring('.pdf', file) then
        veddo('bg acroread ' <> file);
    elseif isendstring('.html', file)
    or isendstring('.pdf.gz', file)
    or isendstring('.html.gz', file)
    then
        veddo('bg netscape ' <> file);
    elseif sys_is_executable(file) then
        dlocal vedargument = file, show_output_on_status = false;
        vedgenshell(systranslate('SHELL'), false)
    else
        edit(file);
    endif;
enddefine;

-- -- rc_button_in_field_in_panel

    rc_button_in_field_in_panel(label, fieldlabel, panel) -> button;

This uses the rc_button_with_label procedure (See HELP rc_buttons)
and rc_fieldcontents_of (see HELP rc_control_panel), to find the
button which is in the field with the given label within the given
panel.


-- -- rc_change_picture

rc_change_picture(pic:rc_linepic_movable, newx, newy, newlines, newstrings);

    Re-draws the object pic, in the new location, with new slot values
    for either or both of rc_pic_lines and rc_pic_strings
    If either of newlines or newstrings is false, the corresponding
    old slot value is retained.

    For examples see LIB rc_change_picture

The definition is as follows

define :method rc_change_picture(pic:rc_linepic_movable,
        newx, newy, newlines, newstrings);

    rc_undraw_linepic(pic);

    ;;; move without displaying
    rc_move_to(pic, newx, newy, false);

    ;;; change picture if necessary
    if newlines then
        newlines -> rc_pic_lines(pic);
    endif;

    ;;; change strings if necessary
    if newstrings then
        newstrings -> rc_pic_strings(pic);
    endif;
    rc_draw_linepic(pic);

enddefine;

-- -- rc_check_current_window

Defined as follows:

define rc_check_current_window(explain);
    unless rc_current_window_object and XptIsLiveType(rc_window, "Widget") then
        mishap('Live current window object needed',[^explain])
    endunless;
enddefine;

-- -- rc_check_window_object

For procedures and methods that require the current window object to
have been set and to be live.

define rc_check_window_object();
    lvars win_obj = rc_current_window_object;

    unless rc_islive_window_object(win_obj) then
        mishap('LIVE rc_current_window_object needed', [^win_obj])
    endunless;

enddefine;

-- -- rc_check_window

For checking that a window or window object is live

Defined as follows:

define rc_check_window(win);
    lvars widget =
        if isrc_window_object(win) then rc_widget(win) else win endif;

    unless XptIsLiveType(widget, "Widget") then
        mishap('LIVE WINDOW OR WINDOW OBJECT NEEDED',[^win])
    endunless

enddefine;

-- -- rc_circle
Old name for rc_draw_circle

-- -- rc_coloured_circles

rc_coloured_circles(xcentre, ycentre, radius, thickness, inc, colours);

Draw circles at the location specified with the thickness specified,
starting with the radius specified, and increasing radius by
thickness plus inc each time. The list of strings, colours, is used
for the colours of the successive circles.

If rc_xscale and rc_yscale are different the circles may be elliptical
instead of circular.

Drawing a nested collection of coloured circles may sometimes be useful
when producing a movable picture that needs to be seen against a
non-white background, since individual colours may not be visible when
drawn using XOR. See HELP RCLIB_PROBLEMS

Example:

vars
    colours1 =
        ['red' 'blue' 'yellow' 'green'],
    colours2 =
        ['gray0' 'gray10'  'gray20'  'gray30'  'gray40'  'gray50'
      'gray60'  'gray70'],
    ;

rc_start();
rc_coloured_circles(-50,-50,5,3,1, colours1);
rc_start();
rc_coloured_circles(150,150,10,5,2, colours2);

-- -- rc_confirm

rc_confirm(x, y, strings, answers, font, title) -> answer;
    The list of strings should specify a question or comment. Possible
    words or strings or numbers are in the list answers.

    container (optional extra argument)
        If present, container is a window object (instance of
        rc_window_object), in which case x, y specify location in the
        container.

    The user will be presented with the question and buttons labelled
    with the possible answers. The program waits until an answer button
    is selected, then returns with the corresponding word, string or
    number as its result.

    (This procedure uses rc_popup_panel. Compare rc_popup_query, which
    was implemented before rc_popup_panel was available.)

Example:

uses rclib
uses rc_confirm

vars
    question =
        ['Now is the time' 'for all good men and women'
         'to stand up and be counted' 'Do you agree?'],

    answers1 = [Yes No],
    answers2 = ['Yes' 'No' 'Maybe'],
    answers3 = [1 2 3 4];

rc_confirm(400, 20, question, answers1, '10x20', 'Confirm')=>
rc_confirm(400, 20, question, answers2, '10x20', 'Confirm')=>
rc_confirm(400, 20, question, answers3, '9x15', 'Confirm') =>

-- -- rc_consolidate_all_input
    rc_consolidate_all_input(panel:rc_panel);

    The panel should have been created by rc_control_panel.
    This method goes through all text/number input fields and
    consolidates all the panels in all of those fields.
    It will not necessarily find text or number input panels
    which form parts of other fields, e.g. panels in slider fields.

    See also HELP * RC_TEXT_INPUT/consolidate_or_activate

-- -- rc_constrained_pointer

rc_constrained_pointer(
    x, y, orient, minang, maxang, len, width, colour, bg) -> pointer;

This library provides a mechanism for creating dials with moving
pointers, which have an internal state that can be linked to a Pop-11
variable. It can be used with additional RCLIB facilities to produce
dials with marked divisions on the dial, and numeric or other labels.

The pointer arrow on such a dial can be moved either under program
control or under mouse control. The latter provides a mechanism for the
mouse to control a program.

Dials are instances of the rc_informant mixin described below.

So all the facilities mentioned in connection with that mixin are
available, including rc_informant_reactor methods which can cause
changes in the dial to be propagated.

The RC_DIAL library makes use of LIB RC_CONSTRAINED_ROTATER, mentioned
below.

For further details see
    TEACH RC_CONSTRAINED_POINTER

The procedure rc_constrained_pointer is used in LIB RC_DIAL, described
in HELP RC_DIAL, TEACH RC_DIAL, and below.

The library LIB rc_constrained_pointer introduces the following
facilities.

 define -- The class rc_constrained_pointer
 define :class vars rc_constrained_pointer;

 define -- methods for the class
 define :method print_instance(pic:rc_constrained_pointer);

 define :method rc_pointer_mouse_limit(x, y, picx, picy,
        pic:rc_constrained_pointer) -> boole;

 define -- drawing procedures
 define rc_draw_pivot_blob(pic, bg);
 define lconstant decoration_parameters(pic) -> (x, y, len, startorient, endorient);
 define :method rc_draw_dial_marks(pic:rc_constrained_pointer, marks);
 define :method rc_draw_dial_labels(pic:rc_constrained_pointer, labels);
 define :method rc_print_dial_captions(pic:rc_constrained_pointer, captions);
 define :method rc_draw_dial_decorations(pointer:rc_constrained_pointer);
 define :method rc_undraw_dial_marks(pic:rc_constrained_pointer, marks);
 define :method rc_undraw_dial_labels(pic:rc_constrained_pointer, labels);
 define :method rc_undraw_dial_captions(pic:rc_constrained_pointer, captions);
 define :method rc_draw_pointer_frame(pic:rc_constrained_pointer);
 define :method rc_draw_constrained_pointer(pic:rc_constrained_pointer);
 define :method rc_draw_linepic(pic:rc_constrained_pointer);
 define :method rc_undraw_dial(pic:rc_constrained_pointer);
 define :method rc_redraw_linepic(pic:rc_constrained_pointer);
 define -- Mechanisms for handling, converting and changing pointer values
 define lconstant pointer_value_from_ang(vang, pic) -> val;
 define lconstant pointer_ang_from_value(val, pic) -> vang;
 define lconstant adjust_step_value(pic, val) -> val;
 define :method rc_set_axis(pic:rc_constrained_pointer, ang, mode);
 define :method rc_pointer_value(pic:rc_constrained_pointer) -> val;
 define :method updaterof rc_pointer_value(newval, pic:rc_constrained_pointer);
 define :method updaterof rc_informant_value(val, pic:rc_constrained_pointer);
 define :method rc_pointer_reactor(s:rc_constrained_pointer, val);
 define -- Dial and pointer spec abbreviations
 define expand_dial_spec_abbreviations(spec) -> spec;
 define -- Recognisers for optional arguments
 define iswident(w);
 define isspecvector(v);
 define isrctypespec(item);
 define lconstant Istypespec(list, word);
 define ismarkspec(item);
 define islabelspec(item);
 define iscaptionspec(item);
 define -- creation of dials
 define rc_install_dial_features(range, marks, labels, captions, pointer);

 define rc_constrained_pointer_init(x, y, orient, minang, maxang,
        len, width, colour, bg) -> pointer;

 define rc_install_pointer(pointer, win);

 define rc_constrained_pointer(x, y, orient, minang, maxang, len,
        width, colour, bg) -> pointer;

 define create_rc_pointer_dial(
        x, y, orient, minang, maxang, len, width, colour, bg,
            range, marks, labels, captions,
                wid, specs, typespec) -> pointer;


 define -- The most general dial creator
 define create_rc_pointer(x, y, startorient, angwidth,
        len, width, bg, colour) -> pointer;
    (Still under development)

-- -- rc_constrained_rotater

This library, used in LIB rc_constrained_pointer, makes the following
available:

 define :mixin rc_constrained_rotater;
    is rc_constrained_mover;

    ;;; location around which pointer pivots
    ;;; relative coords
    slot rc_pivot_x == 0;   ;;; default - rotates about its centre
    slot rc_pivot_y == 0;
    ;;; absolute coords, calculated from location, offset and orientation
    slot rc_real_pivot_x == false;
    slot rc_real_pivot_y == false;

    slot rc_pivot_length;

    ;;; coordinates of end of pointer relative to origin (rc_picx, rc_picy)
    slot rc_end_x ; ;;; movable end
    slot rc_end_y ; ;;; movable end

    ;;; stuff for constraints, including a method to constrain the rotater
    slot rc_min_ang == false;
    slot rc_max_ang == false;
    slot rc_constraint == "rc_constrain_rotater";

    ;;; The orientation of the whole dial (not pointer) in degrees.
    ;;; 0 = upright, 90 = rotated 90degrees clockwise
    ;;; if rc_scale is positive and rc_yscale negative.
    slot rc_rotater_orient = 0;

 enddefine;

with the following methods:

 define :method rc_setup_rotater(pic:rc_constrained_rotater);
 define :method rc_constrain_rotater(pic:rc_constrained_rotater, vang) -> newang;
 define :method rc_pivot_coords(pic:rc_constrained_rotater);
 define :method updaterof rc_pivot_coords(x, y, pic:rc_constrained_rotater);
 define :method rc_real_pivot_coords(pic:rc_constrained_rotater) -> (x,y);
 define :method updaterof rc_real_pivot_coords(x0, y0, pic:rc_constrained_rotater);
 define :method rc_end_coords(pic:rc_constrained_rotater);
 define :method updaterof rc_end_coords(/*x,y, */ pic:rc_constrained_rotater);
 define :method rc_real_end_coords(pic:rc_constrained_rotater) -> (x,y);
 define :method updaterof rc_real_end_coords(x0, y0, pic:rc_constrained_rotater);
 define :method rc_set_axis(pic:rc_constrained_rotater, ang, mode);
 define :method rc_turn_by(pic:rc_constrained_rotater, ang, draw);
 define :method rc_oriented_angle(pic:rc_constrained_rotater, ang) -> ang;
 define rc_actual_to_virtual_angle(pic, ang) -> vang;
 define :method rc_virtual_axis(pic:rc_constrained_rotater) -> vang;
 define :method updaterof rc_virtual_axis(vang, pic:rc_constrained_rotater);
 define :method rc_ang_to_point(pic:rc_constrained_rotater, x, y) -> ang;
 define :method rc_move_to(pic:rc_constrained_rotater, x, y, mode);
 define :method rc_move_by(pic:rc_constrained_rotater, dx, dy, draw);

See how these are used in LIB rc_constrained_pointer, illustrated in
TEACH RC_CONSTRAINED_POINTER


-- -- rc_control_panel

rc_control_panel(x, y, fields, title) -> panel;
rc_control_panel(x, y, fields, title, container) -> panel;

The main procedure creates control panels and displays which are
instances of rc_window_object (and its subclass rc_button_window). The
panels are automatically formatted, including text fields, sliders
various kinds of buttons, text input, number input, scrolling text
panels, and, if required, additional graphics.

When the container is given, it should be an instance of
rc_window_object. It may have been previously created by
rc_control_panel.

The other arguments are

x, y
    Either numbers or symbolic values indicating location in the
    container (for full details see the HELP RC_CONTROL_PANEL file)


fields
    This is a list of field specifications. See the help file for
    details.

Title is a string, used as the name of the panel when it is printed, and
also on the title bar for a non-contained panel.

For full details see:

    LIB RC_CONTROL_PANEL

The procedure rc_popup_panel uses rc_control_panel but waits until an
action is performed using mouse or keyboard, after which the panel is
removed.

More complete documentation on rc_control_panel is in:

    HELP  RC_CONTROL_PANEL

Tutorial examples are in

    TEACH RCLIB_DEMO.P/rc_control_panel
    TEACH RC_CONTROL_PANEL
    TEACH RC_ASYNC_DEMO
    TEACH RC_CONSTRAINED_PANEL
    TEACH POPCONTROL

An extended example showing how to build a tutorial panel for making
pictures controlled by values of sliders, and selections of colours
using buttons is in

    LIB   RC_POLYPANEL

    See also rc_reset_panel, rc_display_strings, rc_popup_panel

-- -- rc_coloured_panel

rc_coloured_panel(x, y, width, height, colour, contents, container) -> panel;

    Create a coloured panel inside the container. x and y can be
    numerical or symbolic, as for rc_control_panel.

-- -- rc_panelcontents

    rc_panelcontents(<panel> <panelpath>) -> result;

This is used to get information from a panel created by rc_control_panel

<panelpath> is a list of labels or special keywords.

It can be
    [<fieldlabel>]
        returns a panel field

    [all_fields]
        returns a list of all the fields in the panel

    [<fieldlabel> <itemlabel>]
        returns an item in a panel field

    [<fieldlabel> all_items]
        returns a list of items in a panel field

    [<fieldlabel> all_values]
        returns a list of informant_values of items in a panel field

    [<fieldlabel> all_labels]
        returns a list of informant_labels of items in a panel field

    [<fieldlabel> all_true]
        returns a list of items in a panel field whose rc_informant_value
        == true (not just non-false)
        Useful for SOMEOF or RADIO buttons in rc_control_panel

    [<fieldlabel> all_false]
        returns a list of items in a panel field whose rc_informant_value
        == false
        Useful for SOMEOF or RADIO buttons in rc_control_panel

    [<fieldlabel> labels_true]
        returns a list of labels of items in a panel field whose
        rc_informant_value is non-false
        Useful for SOMEOF or RADIO buttons in rc_control_panel

    [<fieldlabel> labels_false]
        returns a list of labels of items in a panel field whose
        rc_informant_value is false
        Useful for SOMEOF or RADIO buttons in rc_control_panel

See also
    rc_panel_field_value

-- -- rc_panel_field_value

    rc_panel_field_value(<panel> <panelpath>) -> val
    val -> rc_panel_field_value(<panel> <panelpath>)

    Returns or updates the value of an item in a panel field
    (where appropriate: may mishap in some cases, e.g. action
    buttons).

    <panelpath> is a list of labels
        It can be
            [<fieldlabel> <itemlabel>]

Setting a panel item: use the updater

    val  -> rc_panel_field_value(<panel> <panelpath>)

    <panelpath> is a list of labels or special keywords.

    It can be
        [<fieldlabel> <itemlabel>]
            Update informant value of the relevant item with val

        [<fieldlabel> all_items]
            Updates all items in the panel field with val. Can be used
            to make them all true, all false, or all 0, etc.

See also rc_panelcontents

-- -- rc_current_handlers

rc_current_handlers(obj, slot, /*num*/) -> handlers;
handlers -> updaterof rc_current_handlers(obj, slot, /*num*/);

    This procedure and its updater are used by rc_add_handler and
    rc_delete_handler.

    obj is a window object or picture object.

    slot is one of the slots holding event handlers, as for
        rc_add_handler

    If num is provided, as needed for button related handlers (press,
        release or drag handlers), it should be 1, 2 or 3, representing
        a button, e.g. for the rc_drag_handlers slot.

    handlers is one of the following:

        false, meaning there is no handler.

        A method or procedure, which will be used as the handler.

        A word which is the name of a method or procedure.

        A list containing words or procedures(methods).

Possible values for slot are:

    rc_button_up_handlers
    rc_button_down_handlers
    rc_drag_handlers

    rc_move_handler
    rc_entry_handler
    rc_exit_handler

    rc_keypress_handler

The first three of these require the integer "num" argument to be
provided, to specify which button is involved.

See also rc_add_handler rc_delete_handler, and the information on event
handling above.

-- -- rc_defaults (declaring defaults for global variables)

LIB rc_defaults

This library provides the "define :rc_defaults" syntax which is used to
give default values to global variables unless already given values.
E.g.  in LIB rc_buttons:

define :rc_defaults;
    ;;; total height of button
    rc_button_height_def = 24;

    ;;; total length of button
    rc_button_width_def = 120;

    rc_button_border_def = 3;

    ;;; standard font for label
    rc_button_font_def = '*lucida*-r-*sans-10*';

    ;;; colour of label
    rc_button_stringcolour_def = 'black';

    < .... etc. etc. ....>

enddefine;

Also used in LIB rc_control_panel and various other RCLIB libraries.


-- -- rc_delete_handler

rc_delete_handler(obj, handler, slot, /*num*/);

    The arguments are as for rc_add_handler.

    As for rc_add_handler the num argument is required for slots that
    typically hold a three element vector, i.e. each of these:
        rc_button_up_handlers rc_button_down_handlers
        rc_drag_handlers

    handler can be a procedure(method) or word whose valof is a
        procedure(method). The deletion procedure uses an equality
        test such that if a word is given and the list contains
        its valof, the item will be deleted, or if the word contains
        the name and the procedure is given the word will be deleted,
        etc.

    See also rc_current_handlers, rc_add_handler
    and the general information on event handling above.

-- -- rc_dial

LIB RC_DIAL
Provides a powerful facility for creating dials with movable pointers.
See
    HELP RC_DIAL (full details)
    TEACH RC_DIAL (examples)
    TEACH RC_CONSTRAINED_POINTER    (underlying mechanisms)

rc_dial(
    x, y, orient, angwidth, range, len, width, colour, bg) -> dial;

Additional optional arguments
        wid, specs, typespec, win,
        marks, labels, captions

See the TEACH ahd HELP files for details

-- -- rc_display_file

rc_display_file(
    x, y, file, panel_fields, acceptor, reactor,
        rows, cols, scrollspecs, title) -> panel;

OR

rc_display_file(
    x, y, file, panel_fields, acceptor, reactor,
        rows, cols, scrollspecs, title, container) -> panel;

This procedure is exactly like rc_display_strings described below,
except for the third argument, file, which should be a file name
represented as a single string, or else a readble device created by
sysopen in line mode, i.e. with "line" is the third argument.
(See REF sysopen).

E.g. this will display your .login file at the top right of the screen
in a scrollable 10 lines by 40 column panel.

vars login_line;    ;;; holds the selected line

vars login_panel =
    rc_display_file(
        "right", "top", '.login',
        [], false, false, 10, 40,
        [{font '6x13'} {textfg 'blue'} {fieldbg 'red'}
          ;;; {blobcol 'brown'}
          {ident login_line}],
        'LOGIN');

;;; check the selected line:
 login_line =>

Invisible scrollbars are provided at the left (if there are more lines
than the panel can display) and at the bottom (if the longest line is
too long to fit within the width).

You can make the scroll bars visible and also a pointer on the left for
the selected string, if you add the "blobcol" property with a string
giving the desired colour, e.g. {blobcol 'brown'}, commented out in
the example above.


-- -- rc_display_strings

rc_display_strings(
    x, y, strings, panel_fields, acceptor, reactor,
        rows, cols, scrollspecs, title) -> panel;

rc_display_strings(
    x, y, strings, panel_fields, acceptor, reactor,
        rows, cols, scrollspecs, title, container) -> panel;


Uses rc_control_panel and rc_scrolltext to create a panel displaying a
vector of strings in a scrolling text panel. See HELP RC_SCROLLTEXT

The arguments are as follows
    x, y,
        these specify location on screen or in container panel, either
        as integer coordinates or one of "left", "middle", "right" for x
        and "top", "middle", "bottom" for y

    strings,
        a vector or list of strings to be displayed in the scroll text
        panel

    panel_fields,
        This is a list which can contain specifications for additional
        fields of the type produced by rc_control_panel, to go above
        the scrolltext panel, e.g. text fields, text or number input
        fields, action buttons, radio buttons, sliders, dials, etc.

        For details of possible fields, see HELP rc_control_panel

    acceptor,
        Unless this is false, the scrolltext panel will be created
        with property {acceptor ^acceptor}. I.e. the value of acceptor
        will go into the rc_accept_action slot of the scrolltext object
        as defined in HELP RC_SCROLLTEXT

    reactor,
        Unless this is false, the scrolltext panel will be created
        with property {reactor ^reactor}. I.e. the value of reactor
        will go into the rc_informant_reactor slot.

    rows,
        The number of rows to be shown in the scrolltext panel. This
        will be reduced to the number of strings if there are fewer
        strings

    cols,
        The number of columns to be shown. If this is 0 then the length
        of the longest string is used.

    scrollspecs,
        This is a list of two element vectors defining a featurespec, as
        described in HELP FEATURESPEC, to override default field values
        in the scrolling text panel. The format is that allowed for
        scrolltext fields specified in rc_control_panel. An example
        might be this list of vectors:

        [{font '8x13'} {fieldbg 'black'} {textbg 'yellow'}
            {textfg 'blue'} {ident the_string}]

    title
        A string, to be used as the title of the panel. This is ignored
        if there is a container argument.

    container (optional extra argument)
        If present, container is a window object (i.e. an instance of
        rc_window_object), in which case x, y specify location in the
        container.

Additional global variables that control the behaviour are defined in
a later section.

If there are more strings than rows in the panel there will be a
scrollbar on the right of the panel. If the longest string has more
characters than the width of the panel, there will be a scrollbar at
the bottom of the panel, which can be used for scrolling left and right.
There will also be a pointer on the left of the panel showing the
current selected string, which defaults to the first string.

Example:


;;; make a vector of strings
vars strings;

{%
    lvars x;
    for x to 40 do
        x ><
        '. a useful number to display is the number ' >< x
    endfor;
%} -> strings;

vars selected_string;    ;;; holds the selected string

vars strings_panel =
    rc_display_strings(
        "right", "top", strings,
        [], false, false, 10, 40,
        [{font '6x13'} {textfg 'blue'} {fieldbg 'red'}
          ;;; {blobcol 'yellow'}  ;;; try uncommenting this
          {ident selected_string}],
        'LOGIN');

;;; check the selected string:
selected_string =>


One of the strings can be selected by clicking on it, or by moving the
pointer on the left of the panel.

The currently "selected" string is accessible via reactor procedures,
and the association of an identifier or variable with the panel. E.g. if
the feature {ident the_string} is in the scrollspecs list, then the
Pop-11 word "the_string" will be associated with the currently selected
string.

It is possible to associate  the identifier rather than the word with
the selected string, using the syntax

        {ident ^(ident selected_string)}

This can be useful with local lvars variables in procedures invoking
rc_display strings.

For an example of the use of rc_display_strings see LIB RC_BROWSE_FILES

Compare rc_popup_strings, which uses rc_popup_panel. rc_popup_strings
puts up the list of strings, and waits till you make a selection which
is then returned (or false if you select "Cancel");


-- -- . globals for rc_display_strings and rc_display_file, etc

The procedure rc_display_strings uses the following globals:

define :rc_defaults;
    rc_display_strings_fieldbg_def = 'white';
    rc_display_strings_textfg_def = 'grey10';
    rc_display_strings_textbg_def = 'grey90';
    rc_display_strings_surround_def = 'grey80';
    rc_display_strings_blobcol_def = 'grey20';
    rc_display_strings_buttonwidth_def = 90;
enddefine;


global vars
    ;;; List of current browsers produced by rc_display_strings,
    ;;; to prevent them being garbage collected.
    ;;; The "Dismiss All" button runs the procedure rc_kill_browser
    ;;; panels, defined below.
    ;;; Each newly created panel is put on this list
    browse_panels = [],

    ;;; Variable set when selecting files from a panel created by
    ;;; rc_display_strings, if the default reactor is used.
    the_selected_string = false;

-- -- . rc_kill_browser_panels

This procedure is associated with the "Dismiss All" action button
on panels created by rc_display_strings. Its default definition is this:


define vars rc_kill_browser_panels();
    applist(browse_panels, rc_kill_window_object);
    [] -> browse_panels;
enddefine;

I.e. it kills all the windows on the list browse_panels.

-- -- rc_default_window_object

This is an active variable which returns a default instance of
rc_window_object with an invisible window, which can be used to compute
text dimensions, as in rc_text_area

-- -- rc_destroy
rc_destroy();
    Gets rid of the current window, held in rc_window
    Contrast rc_kill_window_object(win_obj), for destroying a
    window associated with an instance of rc_window_object

-- -- rc_distance
A simple utility
    rc_distance(x1, y1, x2, y2) -> dist;

-- -- rc_do_unix

rc_do_unix(x, y);
    Using rc_getinput put a panel at location x, y, asking for a Unix
    shell command, then run the command and read the result back into a
    VED file.

The global variable rc_shell should hold a string specifying the shell
to be used, and for which a suitable VED enter command is defined. E.g.
the procedures ved_sh and ved_csh are provided by default.

The default value of rc_shell is 'csh'. So by default the call of
rc_do_unix is equivalent to a VED command

    ENTER csh <unix command>

Example:

uses rclib
uses rc_shell

'csh' -> rc_shell;
rc_do_unix(400,400);

Contrast rc_xterm, which starts up a new xterm window.

-- -- rc_drag_window

LIB rc_drag_window

define :method rc_drag_window(pic:rc_window_object, x, y, modifiers);

This can be used to make a window draggable (whether contained in
another window or not).

-- -- rc_draw_arc_segment

rc_draw_arc_segment(xcentre, ycentre, radius, startangle, incangle, width, col);

Draws part of a circular arc in a possibly squashed square of side
2*radius with top left corner located such that xcentre,ycentre is at
the centre of the square.

The startangle for the sector is measured counter clockwise from east
(3 o clock) when rc_yscale is negative and clockwise when it is
positive.

The incangle is measured in the same direction.

Used in rc_draw_arc_segments

Compare rc_draw_blob_sector

-- -- rc_draw_arc_segments

rc_draw_arc_segments(xcentre, ycentre, radius, start, gap, lim, inc, width, col);

Draw sequence of segments of angular width inc, and linewidth width,
at angular locations specified by start, gap, lim, centred on a circle
with given centre and radius, at angular location start and subsequent
locations at angular distance gap, up to angular limit lim. The colour
is col.

For the interpretation of the arguments see rc_draw_arc_segment

Example. Draw

vars win1 = rc_new_window_object( "right", 20, 450, 450, true, 'win1');

;;; Draw: radial "lines" of length 10 and angluar width 2, at 45 degre
;;; intervals on a semi-circle above the line centred at 0,0, of
;;; radius 50.
rc_draw_arc_segments(0, 0, 50, 179, -45, -1, 2, 10, 'blue');

;;; Green radial marks at 10 degree intervals round a whole circle.
rc_draw_arc_segments(0, 0, 80, -1, 10, 360, 2, 18, 'green');

;;; 30 degree intervals in the bottom right quadrant
rc_draw_arc_segments(0, 0, 100, 179, 30, 270, 2, 6, 'red');


-- -- rc_draw_bar

rc_draw_bar(x, y, height, len, col);

    Draw a horizontal bar of given height, length and colour starting at
    location x, y (middle of left end). All the numerical arguments are
    relative to current rc_window coordinates.
    Col should be a string (see HELP xcolours) or false. If it is false,
    the colour drawn is the current default foreground for the window.
    If it is the word "background", then the colour drawn is the
    background colour of the current window.

E.g.
    rc_start();
    rc_draw_bar(-100,50, 10, 30, 'red');
    rc_draw_bar(-100,50, 40, 30, 'red');

    rc_draw_bar(-100,-50, 80, 130, 'blue');
    rc_draw_bar(-90,-50, 60, 110, false);
    rc_draw_bar(-90,-50, 60, 110, "background");
    rc_draw_bar(-110,-50, 2, 150, 'green');
    rc_draw_bar(-110,-50, 100, 2, 'green');


-- -- rc_draw_blob

rc_draw_blob(xcentre, ycentre, radius, colour);

    Draws a circular blob at the location specified with the radius
    specified.
    If the colour is the boolean false (instead of a string) the colour
    drawn is the current foreground colour of the current window.
    If the colour is the word "background", the colour drawn is the
    current background colour of the current window.

-- -- rc_draw_blob_sector

rc_draw_blob_sector(xcentre, ycentre, radius, startangle, incangle, colour);

Draws part of a circular blob in a possibly squashed square of side
2*radius with top left corner located such that xcentre,ycentre is at
the centre of the square.

The startangle for the sector is measured counter clockwise from east
(3 o clock) when rc_yscale is negative and clockwise when it is
positive.

The incangle is measured in the same direction.

Should startangle be measured from the west if rc_xscale is negative??

    See REF XpwFillArc, XpwDrawArc
    MAN XFillArc, *XDrawArc

rc_draw_blob_sector is used in
    rc_draw_semi_circle
    rc_draw_pointer
The latter is used in
    rc_constrained_pointer

Compare rc_draw_arc_segment

-- -- rc_draw_unscaled_blob

rc_draw_unscaled_blob(xcentre, ycentre, radius, colour);

Draws a circular blob at the location specified with the radius
specified. Always draws blob with the specified radius, no matter what
rc_xscale and rc_yscale are. Colour can be a string or false, or the
word "background" as in rc_draw_blob.

-- -- rc_draw_centred_rect
-- -- rc_draw_centred_square

    rc_draw_centred_rect(x, y, side, side, colour, width)
    rc_draw_centred_square(x, y, side, colour, width);

These two procedures draw squares or rectangles centred around the
location (x, y). The lines are drawn using the specified colour (a
string, or the word "background", or false) and width (a number or
false).

If the colour or width argument is false, then the current default
colour or width for the window is used.

If the colour is the word "background" then the current background
colour is used. See rc_foreground.

-- -- rc_draw_circle

rc_draw_circle(xcentre, ycentre, radius)
    Draw a circle of the specified radius at the specified location.
    Warning if rc_xscale and rc_yscale are different the picture may be
    elliptical instead of circular.
    LIB RC_DRAW_CIRCLE

See next procedure.

-- -- rc_draw_lines
-- -- rc_draw_lines_closed
-- -- rc_draw_lines_filled

These three procedures are defined in LIB rc_draw_lines, which
is autoloadable. For the other two it is necessary to do
    uses rc_draw_lines

They make use of the following procedures defined in REF XpwPixmap:
        XpwDrawLines XpwFillPolygon

They allow open and closed or filled polygons to be drawn efficiently,
and in the case of the non-filled polygons produce neater corners than
is possible with repeated use of rc_drawline.

    rc_draw_lines(coords, colour, linewidth, mode);
        Draw a polygon joining the points given in coords, using the
        colour and linewidth specified

    rc_draw_lines_closed(coords, colour, linewidth, mode);
        Draw a closed polygon joining the points given in coords, using
        the colour and linewidth specified

    rc_draw_lines_filled(coords, colour, shape, mode);
        Draw a filled polygon joining the points given in coords, using
        the colour and shape specified

The "coords" argument can be a list, vector, or shortvec with 2*N
numbers representing N points. The coordinates (integer or decimal) will
be interpreted using the procedure rctransxyout, which normally makes
use of the current rc_graphic global variables , rc_xorigin, rc_yorigin,
rc_xscale, rc_yscale.

The "mode" argument is one of these two, as described in REF XpwPixmap
    CoordModeOrigin:
        coordinates are relative to the origin
    CoordModePrevious
        coordinates are relative to the previous point, apart from the
        first point which is taken to be relative to the origin.
        See MAN  XDrawLine.

        If these are for any reason undefined, put the following at the
        top of your file:
            loadinclude XpwPixmap.ph

The "linewidth" argument may be false (use the current default) or
an integer.

The "colour" argument may be false (use the current default) or a string
specifying a colour. (See HELP xcolours for available colours.)

The "shape" argument for the third procedure should be one of
the following
    Convex, Nonconvex Complex

REF XpwPixmap specifies "NonConvex", but that's a mistake.
See MAN XFillPolygon, which states:

     Depending on the specified shape, the following occurs:

     o    If shape is Complex, the path may self-intersect. Note
          that contiguous coincident points in the path are not
          treated as self-intersection.

     o    If shape is Convex, for every pair of points inside the
          polygon, the line segment connecting them does not
          intersect the path.  If known by the client, specifying
          Convex can improve performance. If you specify Convex
          for a path that is not convex, the graphics results are
          undefined.

     o    If shape is Nonconvex, the path does not self-
          intersect, but the shape is not wholly convex. If known
          by the client, specifying Nonconvex instead of Complex
          may improve performance. If you specify Nonconvex for a
          self-intersecting path, the graphics results are unde-
          fined.

     The fill-rule of the GC controls the filling behavior of
     self-intersecting polygons.

In principle it should be possible to produce similar relative
coordinate procedures for additional utilities described in
REF XpwPixmap

-- -- rc_draw_coloured_circle

rc_draw_coloured_circle(xcentre, ycentre, radius, colour, linewidth);
    Draw circle at the location specified with the thickness specified,
    with the colour specified.

    If either colour or linewidth is false then the current setting is
    used. If colour is "background" then the current background colour
    is used.

    If rc_xscale and rc_yscale are different the circles may be elliptical
    instead of circular.
    LIB rc_draw_coloured_circle

-- -- rc_draw_coloured_line

    rc_draw_coloured_line(x1, y1, x2, y2, colour, linewidth);

    Draw line at the location specified with the thickness specified,
    with the colour specified.

    If either colour or linewidth is false then the current setting is
    used. If colour is "background" then the current background colour
    is used.

-- -- rc_draw_pointer

This defines a utility for drawing pointers made of a sector of a
circle.

rc_draw_pointer(xcentre, ycentre, radius, angle, width, colour);

Draws a sector of a circle of the given radius. Centre of the circle is
not at xcentre,ycenter but at a distance radius away, in the direction
specified by angle (0 = to the right if rc_axis is positive otherwise
to the left). The angle is measured counter clockwise if rc_yaxis is
positive, otherwise clockwise. Angle specifies the amount of the circle.

E.g. if rc_xaxis = 1 and rc_yaxis = -1 then

    rc_draw_pointer(0, 0, 100, 90, 20, 'pink');

will draw a pink "pointer" pointing up from location 0,0 to location
0,100, using a 20 degree sector of a circle.

    rc_draw_pointer(0, -100, 100, -90, 10, 'blue');

will draw a narrower (10 degree wide) blue pointer from position 0 -100
pointing down, of length 100.

This is used to draw the pointer of a dial in LIB rc_constrained_pointer

See also
    LIB rc_draw_pointer.p
    LIB rc_draw_semi_circle.p

-- -- rc_draw_ob
rc_draw_ob(x, y, width, height, radius1, radius2);
    This is a generalisation of rc_draw_oblong defined in
    HELP RC_GRAPHIC/rc_draw_oblong, which has only one radius,
    and uses the current `turtle' location.

This procedure uses XpwDrawRoundedRectangle to draw a rectangle with
rounded corners, with the given width and height (in user coordinates)
with the top left corner at location (x, y) , and lines horizontal and
vertical. The third and fourth arguments, multiplied by rc_xscale and
rc_yscale, respectively, provide the two "radius" arguments required
for XpwDrawRoundedRectangle. For further information see
    HELP XpwDrawRoundedRectangle

-- -- rc_draw_pointlist

rc_draw_pointlist(pointlist, closed);
    Draw a polyline using the given list of points, if the final
    boolean argument is true the polyline is closed, whereas if it is
    false the polyline is open (i.e. the last line is not drawn)

Examples
;;; open square
rc_draw_pointlist([{0 0} {0 100} {100 100} {100 0}], false);
;;; closed square
rc_draw_pointlist([{0 0} {0 100} {100 100} {100 0}], true);

The elements of pointlist may be any two element structures suitable as
arguments for explode, e.g. a pair, a two element vector, a two element
record, a two element list, etc.
    LIB rc_draw_pointlist

See next procedure.


-- -- rc_draw_coloured_pointlist

rc_draw_coloured_pointlist(pointlist, colour, linewidth, closed);

    Draw an open or closed polyline linking the points in pointlist,
    whose elements are structures containing two numbers, as in
    rc_draw_pointlist, above.

    The lines drawn will have the specified colour (a string) and
    linewidth (an integer). If either is false the current
    default colour or linewidth for the window will be used.
    If the colour argument is the word "background" the current
    background colour will be used.

    If the final boolean argument is true the polyline is closed,
    whereas if it is false the polyline is open (i.e. the last line is
    not drawn). Compare rc_draw_pointlist

    LIB rc_draw_coloured_pointlist


Examples:
rc_start();

;;; open polyline
rc_draw_coloured_pointlist(
    [{0 0} {0 80} {80 80} {80 0}], 'green', 1, false);

;;; closed polyline
rc_draw_coloured_pointlist(
    [{-60 -60} {-60 100} {100 100} {100 -60}], 'blue', 20, true);

;;; closed polyline using background colour
rc_draw_coloured_pointlist(
    [{-60 -60} {-60 100} {100 100} {100 -60}], "background", 10, true);

;;; closed polyline using current default foreground
rc_draw_coloured_pointlist(
    [{-60 -60} {-60 100} {100 100} {100 -60}], false, 5, true);


-- -- rc_draw_rect
rc_draw_rect(x, y, width, height);
    Draw a rectangle of the specified width and height with its top left
    corner at location (x, y)

-- -- rc_draw_Rrect
rc_draw_Rrect(x, y, width, height);
    Draw a "rotatable" rectangle of the specified width and height
    with "top left" corner (in the current coordinate frame) located at
    (x, y). Because four separate line drawing commands are used, this
    sort of rectangle can be rotated by rotating the rc_graphic
    coordinate frame, unlike rectangles drawn using rc_draw_rect

-- -- rc_draw_filled_rect
    rc_draw_filled_rect(x, y, width, height, colour)
        Draw non-rotatable filled rectangle with top left corner
        at location x,y using relative coordinates for x and y,
        and width and height interpreted relative to absolute values
        of rc_xscale and rc_yscale, respectively

-- -- rc_draw_filled_centred_rect
    rc_draw_filled_centred_rect(x, y, width, height, colour);

    Like rc_draw_filled_rect, except that x,y is the location of the
    centre of the rectangle.

-- -- rc_draw_scaled_blob

rc_draw_scaled_blob(xcentre, ycentre, radius, colour);

Draws a blob at the location specified with the radius specified.

If rc_xscale and rc_yscale are different the blob may be elliptical
instead of circular.
See
    LIB rc_draw_scaled_blob.p

-- -- rc_draw_semi_circle.p
rc_draw_semi_circle(xcentre, ycentre, radius, orientation, colour);

Draws a semi-circle of the given radius and colour, with centre at
xcentre, ycentre. The orientation parameter defines the starting
direction of a semi-circular sweep and is measured counter clockwise if
rc_yscale is negative otherwise clockwise. If rc_xscale is positive,
the orientation is measured from 0 = pointing right, otherwise pointing
left.

E.g. if rc_xscale = 1 and rc_yscale = -1 then

    rc_draw_semi_circle(0, 100, 30, 90, 'blue');

will draw a blue semi-circle of radius 30 with centre at 0, 100, to the
left of the vertical through the centre.

    rc_draw_semi_circle(0, -100, 30, 180, 'red');

will draw a red semi-circle of radius 30 with centre at 0, -100, below
the horizontal through the centre.

This uses
    rc_draw_blob_sector

See
    LIB rc_draw_semi_circle.p

-- -- rc_draw_square
rc_draw_square(x, y, side);
    Draw a square with top left corner at (x, y)
    Equivalent to
        rc_draw_rect(x, y, side, side)

-- -- rc_draw_Rsquare
rc_draw_Rsquare(x, y, side);
    Draw a rotatable square with initial corner at (x, y)
        Equivalent to
            rc_draw_Rrect(x, y, side, side)

-- -- rc_draw_coloured_square

rc_draw_coloured_square(xcentre, ycentre, colour, width);
    Draw a filled square at the location specified with the
    colour and width specified

    If rc_xscale and rc_yscale are different a rectangle may appear
    instead of circular.

    Colour can be a string, or integer (colour code), or false
    or the word "background".
    If false then current default foreground colour is used. If it is
    the word "background" then current default background colour is
    used, as in rc_drawline_absolute
    (Compare the convention for rc_foreground)

    LIB rc_draw_coloured_square

-- -- rc_draw_triangle
    rc_draw_triangle(x1, y1, x2, y2, x3, y3, colour, linewidth );

    Draw the triangle defined by the coordinates of the three points,
    using specified colour and linewidth.

    Rotatable.

-- -- rc_draw_filled_triangle

    rc_draw_filled_triangle(x1, y1, x2, y2, x3, y3, colour);

    Draw a filled triangle defined by the coordinates of the three
    points, using specified colour.

    Rotatable.


-- -- rc_drawline_absolute
rc_drawline_absolute(x1, y1, x2, y2, colour, width);
    Draw a line of given width and colour using absolute coordinates

    NB this was changed, Feb 2000, to conform to rc_foreground.

    Colour can be a string, or integer (colour code), false, or the
    word "background".
    If false then current default foreground colour is used. If the
    word "background" then current default background colour is used.
    (Compare the convention for rc_foreground)

    See also rc_drawline_relative, rc_draw_bar

-- -- rc_drawline_relative
rc_drawline_relative(x1, y1, x2, y2, colour, width);
    Draw a line of given width and colour using relative coordinates
    (Like rc_drawline_absolute, otherwise)

-- -- rc_drawtree
Early name for rc_showtree

-- -- rc_flush_everything
rc_flush_everything();

    This is a user definable procedure, which can be used to flush all
    the standard output buffers. Its default definition is

    define vars rc_flush_everything();
        sysflush(popdeverr);
        sysflush(popdevout);
        if vedediting then
            vedcheck();
            vedsetcursor();
            vedscr_flush_output();
        endif;
        sysflush(poprawdevout);
    enddefine;

-- -- rc_font

rc_font(window) -> font
font -> rc_font(window)

    Used to access or update the font used for printing in the window,
    e.g. using rc_print_at or rc_print_pic_string. Does some simple
    cache-ing.
    See LIB RC_FONT

-- -- rc_font_dimensions

rc_font_dimensions(font, text)-> (width, height, ascend, descend);

Given a font (a string) and a text string returns the width of that
string using that font, along with the font height and the font
ascent and descent.
See REF XpwFontAscent XpwFontDescent XpwFontHeight XpwTextWidth

This procedures uses rc_default_window_object

Example

    rc_font_dimensions('12x24', 'Now is the time for all')=>
    ** 276 24 22 2

-- -- rc_foreground
-- -- rc_foreground_changeable

When the global variable rc_foreground_changeable has the value true,
then the foreground colour of a window can be changed. Otherwise
attempts to change it will do nothing. This is used in
    LIB rc_opaque_mover

rc_foreground(window) -> foreground
string       -> rc_foreground(window)
false        -> rc_foreground(window)
"background" -> rc_foreground(window)

    Used to access or update the foreground colour used for drawing in
    the window specified,
    See LIB RC_FOREGROUND

When using the updater of rc_foreground, the colour specified should
normally be a string.

If it is the word "background" then the current background colour is set
to be the foreground colour, e.g. for drawing a "hole" in part of a
picture.

If it is the boolean, false, then the foreground colour is unchanged.
I.e. use false to mean use the current default.

-- -- rc_get_coords
-- -- rc_get_coords_from

rc_get_coords(win_obj, pdr, button)
rc_get_coords_from(win_obj, pdr, button, boolean)
    [Second version added March 2006]

The second version allows warping to be prevented, if the boolean
is false.

The method rc_get_coords takes an instance of the class
rc_window_object, win_obj, a procedure pdr of two arguments
(coordinates), and an integer representing a mouse button.

When invoked, it warps the mouse pointer to the centre of the window and
then waits until a mouse button is clicked in that window.

The second method, rc_get_coords_from, is similar, except that the final
argument determines whether the mouse pointer is warped to the window.

When the specified button is clicked the procedure pdr, is applied to
the two integers X, and Y representing the location at which it is
clicked (in local rc_graphic coordinates), and the procedure returns. If
pdr is identfn, then the two integers are simply left on the stack. If
it is conspair, then a pair is created containing the two integers, and
so on.

The integers are coordinates relative the current coordinate frame of
the window, as defined by the procedure rc_app_mouse_xyin, which can be
found in LIB rc_app_mouse.

For more details, and examples, see HELP RC_GET_COORDS

Planned extension:
rc_get_coords(win_obj, pdr, vector) [Not Implemented]
[It was intended to allow the integer to be replaced by a a vector of
three numbers representing mouse button, X coordinate and Y coordinate.
However this has not yet been implemented. The X and Y coordinate
were to have been passed to rc_warp_to ]

-- -- rc_getfile

rc_getfile(x, y, path, filter, rows, cols, font) -> selection;
rc_getfile(x, y, path, filter, rows, cols, font, "recurse") -> selection;
rc_getfile(x, y, path, filter, rows, cols, font, container) -> selection;
rc_getfile(x, y, path, filter, rows, cols, font, "recurse", container) -> selection;

    Get a list of the files matching the filter pattern, and display
    them in a panel containing a scrolling text widget, using
    rc_popup_strings. Then wait till the user makes a selection or
    interrupts. If there's an interrupt return false, otherwise the
    string selected.

    If the extra argument "recurse" is given, then if you select
    directory it will invoke rc_getfile on that directory instead of
    path, using the same arguments otherwise.

    If present, the optional argument container is a window object
    (instance of rc_window_object), in which case x, y specify location
    in the container.

Controlled by these global variables

global vars
    rc_show_dot_files = false,
    rc_list_dirs_first = true;

Example:

uses rclib
uses rc_getfile

rc_getfile(500, 20, '~', false, 10, 50, '9x15') =>
rc_getfile(500, 20, '~', '*.p', 10, 50, '9x15') =>
rc_getfile(500, 20, '/usr/bin', false, 20, 50, '10x20', "recurse") =>

[THIS PROCEDURE WILL BE ENHANCED LATER]


-- -- rc_getinput

rc_getinput(x, y, strings, prompt, specs, title) -> result;
rc_getinput(x, y, strings, prompt, specs, title, container) -> result;

Puts up a window containing text strings and a text input panel. Asks a
question and returns a string input by user or false if the user selects
the "cancel" button. Accepts an optional "container" argument.

    x, y
        Location of panel. Can be words if container argument supplied.
    strings
        A list of strings to be displayed, giving instructions
        or asking a question
    prompt
        The default answer, or one to be edited. Could be an
        empty string.

    specs
        List (possibly empty) of qualifiers for properties of the
        text input field.

    title
        String, to go in the title bar of the new window.

Example

uses rclib
uses rc_getinput

vars instruct =
    ['Type your name in'
    'Press return or click'
    'Then press "OK"'];

rc_getinput(600, 300, instruct, '', [], 'Name?')=>
rc_getinput(600, 300, instruct, '', [{font '12x24'}], 'Name?')=>
rc_getinput(600, 300, instruct, '', [{font '12x24'}{width 500}], 'Name?')=>
rc_getinput(600, 300, ['type a number'], 0, [{font '10x20'}], 'A number')=>
rc_getinput(600, 300, instruct, 'hello', [{font '6x13'}], 'Name?')=>


-- -- rc_hide_menu
-- -- rc_kill_menu

See: rc_hide_panel rc_kill_panel, below.

-- -- rc_hide_panel
-- -- rc_kill_panel

    rc_hide_panel()
        This essentially does
            rc_hide_window(rc_active_window_object);
        and some tidying up.

    rc_kill_panel()
        This essentially does
            rc_kill_window_object(rc_active_window_object);
        and some tidying up.

These two autoloadable library procedures are convenient for action
buttons which are required to either temporarily hide, or permanently
destroy the current panel.

Names used previously for these functions were rc_hide_menu and
rc_kill_menu. These names will gradually be phased out.


-- -- rc_interpolate_coords

rc_interpolate_coords(coords1, coords2, S, stepnum, coords3) -> coords3;

coords1 is a list or vector of 2N numbers representing N points, as are
coords2 and coords3.

The values of the coordinates in coords1 and coords2 are used to produce
an interpolated value in coords3 on the assumption that there are S
interpolation steps and this is step stepnum. So if the values or the
kth components of coords1 and coords2 are x1 and x2, then the
corresponding value of coords3 will be
    x1 + (x2 - x1)*stepnum/S

This can be used repeatedly to interpolate coordinates when morphing
between two sets of lines, as in rc_transform_lines

Example:
vars list = [ 0 0];
vars x;
for x from 0 by 2 to 10 do
    rc_interpolate_coords([0 0], [1 1], 10, x, list)=>
endfor;

** [0.0 0.0]
** [0.2 0.2]
** [0.4 0.4]
** [0.6 0.6]
** [0.8 0.8]
** [1.0 1.0]

Used in rc_transform_lines


-- -- fast_interpolate_coords

fast_interpolate_coords(
    coords1, coords2, S, stepnum, coords3) -> coords3;

This is like rc_interpolate_coords except that each of coords1,
coords2 and coords3 must be a vector. Uses fast_subscrv.

This is used in rc_transform_pictures.

-- -- rc_interpret_key

rc_interpret_key(code) -> key;

    This user-extendable procedure can be used to decode the
    integers produced via event handler procedures when a keyboard
    key is pressed and the mouse pointer is in a keypress sensitive
    window. For an overview see HELP RC_KEYCODES

    Users can override some of the mappings by redefining this
    procedure, included in LIB RC_INTERPRET_KEY

        define vars user_rc_interpret_key(code) -> key;
            false -> key;
        enddefine;

    If a non false result is returned for any code, that value is
    used, otherwise the defaults are used. For details of the default
    mappings see LIB RC_INTERPRET_KEY

-- -- rc_islive_window_object(win) -> boole
    This procedure, defined in LIB RC_WINDOW_OBJECT recognises
    window objects which still have associated windows that have not
    been destroyed.

-- -- rc_label_dial

rc_label_dial(xcentre, ycentre, radius, start, inc, lim, num, incnum, colour, font);
    draw numbers starting at num, incremented by incnum at locations
    specified by the first six arguments as in rc_draw_arc_segments

There are two global variables defining offsets for printing numeric
labels, with these default values. They are used by rc_label_dial

-- -- . rc_dial_label_xoffset = -8;
-- -- . rc_dial_label_yoffset = 5;
    I.e. numeric labels are printed a bit to the left and down a bit.
    This may not suit all cases.

Examples:
vars win1 = rc_new_window_object( "right", 20, 450, 450, true, 'win1');

rc_draw_arc_segments(0, 0, 110, 179, -10, -1, 2, 20, 'green');

rc_label_dial(0, 0, 130, 180, -30, 0, 0, 3, 'red', '10x20');

rc_label_dial(0, 0, 50, 180, -45, 0, 0, 4.5, 'red', '6x13');

rc_draw_arc_segments(0, 0, 160, 179, -10, -1, 0.5, 10, 'blue');
rc_label_dial(0, 0, 180, 180, -10, 0, 0, 0.1, 'red', '6x13');

rc_start()
rc_draw_arc_segments(0, -50, 110, 89, 10, 270, 2, 5, 'blue');
rc_label_dial(0, -50, 130, 270, -20, 89, 0.0, 1.0, 'red', '6x13');


-- -- rc_kill_selected_windows
Kill windows selected using mouse button 3

define rc_kill_selected_windows();
    applist(rc_selected_window_objects, rc_kill_window_object);
    [] -> rc_selected_window_objects
enddefine;

-- -- rc_lengthen_window_by

rc_lengthen_window_by(win_obj, len, colour);

    NB this was changed, Feb 2000, to conform to the conventions of
    rc_foreground.

    win_obj is an instance of rc_window_object. Increases its height by
    len (at the bottom). If colour is false it uses the current
    foreground colour. If it is the word "background" it uses the
    current background colour. Otherwise colour is a string or integer.
    (Compare the convention for rc_foreground)

    See also rc_widen_window_by


-- -- rc_line_function

rc_line_function(window) -> int
int -> rc_line_function(window)
    Get or update value of for rc_linefunction for current window.
    HELP RC_GRAPHIC/rc_linefunction

The following possible values are supported

    GXclear             GXand           GXandReverse
    GXcopy (default)    GXandInverted   GXnoop
    GXxor               GXor            GXnor
    GXequiv             GXinvert        GXorReverse
    GXcopyInverted      GXorInverted    GXnand
    GXset


-- -- rc_line_style

rc_line_style(window) -> int
int -> rc_line_style(int,window)
    Get or update value of for rc_linestyle for current window.
    HELP RC_GRAPHIC/rc_linestyle

The following possible values are supported

        LineSolid       (default)
        LineOnOffDash
        LineDoubleDash

-- -- rc_line_width

rc_line_width(window) -> int
int -> rc_line_width(int,window)
    Get or update value of for rc_linewidth for current window.
    See HELP RC_GRAPHIC/rc_linewidth

    Default value is 0. Larger values draw thicker lines.

-- -- rc_lispbrowser

See rc_procbrowser, below

-- -- rc_make_current_window

rc_make_current_window(win_obj);
    This can be used in button objects to set win_obj to be the value of
    rc_current_window_object after the action has been finished.

    It does this by putting an action to make win_obj the current window
    onto the defer list.
    See LIB rc_mousepic and HELP rc_linepic for details of
    rc_defer_apply

An action button to make the window containing the button the current
one could use the command

    rc_make_current_window(rc_active_window_object);

E.g.

vars panel_spec =
    [{width 300}{height 300}{bg 'white'}
     [ACTIONS {width 90}:
        ['Set current'
            [POP11 rc_make_current_window(rc_active_window_object)]]
        ['Dismiss' rc_kill_panel]
     ]
    ];

vars win1 =
    rc_control_panel(400, 10, panel_spec, 'win1'),
    win2 =
    rc_control_panel(700, 10, panel_spec, 'win2');

;;; Now click on the set current button to select one of the windows
;;; and then do this

    repeat 10 times
        rc_draw_blob(
            random(400) - 100,
            random(250) +50,
            random(30),
            oneof(['red' 'blue' 'green' 'orange' 'black']))
    endrepeat;

;;; Repeat the above after selecting the other window

-- -- rc_make_draggable

rc_make_draggable(win_obj, button, xloc, yloc);

    Ued to make a window object draggable by the specified button, a its
    internal location xloc, yloc.

See HELP RC_CONTROL_PANEL/rc_make_draggable

-- -- rc_message

rc_message(
    x,y, strings, spacing, centre, font, bgcol, fgcol) -> win_obj;

    Put up a message consisting of a lot of strings, using a specified
    font, font colour and background colour. The "centre" argument
    can be false, true, or the word "right". Anything else counts
    as true.
    This uses rc_print_strings

    Displays the message, leaves it visible, and unlike rc_message_wait
    allows further processing continue.
    The message will be dismissed if mouse button 1 is clicked or a key
    is pressed while the mouse pointer is in the window.
        See HELP RC_BUTTONS/rc_message for examples

    The global variable rc_message_instruct holds a string to be
    displayed at the top of the panel, or false, in which case it is not
    used.

-- -- rc_message_wait
rc_message_wait(x,y, strings, spacing, centre, font, bgcol, fgcol);

    Like rc_message, but waits for the user to dismiss the window
    before it returns. Also warps the mouse pointer onto the window.
    The window will be dismissed if any key on the keyboard is pressed,
    or if mouse button 1 is pressed.

    It locally sets rc_sole_active_widget to hold the current widget so
    that all events in other widgets are disabled until this one is
    dismissed.

    The centre argument can be false, true, or the word "right".
    Anything else counts as true. This uses rc_print_strings

        See HELP RC_BUTTONS/rc_message_wait for examples

    The global variable rc_message_wait_instruct holds a string to be
    displayed at the top of the panel, or false, in which case it is not
    used.

    Compare rc_confirm

Example:

vars strings=
    ['Now is the time''for all good men and women''to stand up'
     'and be counted'];

rc_message_wait(300,300,strings,0, true, '9x15', false, false);
rc_message_wait(300,100,strings,0, true, '8x13bold', false, false);
rc_message_wait(100,20,strings,0, true, '10x20', 'darkslategrey', 'yellow');

-- -- rc_mouse_coords
rc_mouse_coords(stop_button) -> list;

Enables you to point at a set of locations in the current rc_graphic
window, and get a list of coordinates of those locations. Use any mouse
button except the stop_button until the last point. Each point is
represented in the list by the result of rc_conspoint(x, y) where
rc_conspoint is user definable and defaults to conspair.

See HELP RC_MOUSE_COORDS

-- -- rc_mousepic

rc_mousepic(win_obj, [ list ])

This procedure takes an instance of rc_window_object and an optional
list of words defining event types. It is used to make a window object
"live" i.e. sensitive to various kinds of events (mouse events, keyboard
events).

See HELP RC_LINEPIC/rc_mousepic

    rc_mousepic(win_obj)
    rc_mousepic(win_obj, list)

Where win_obj is a window_object instance, and list, if present,
contains some combination of the words "button", "motion", "mouse",
"keyboard", defining the types of events that can be handled.

If no list is provided, or if the list is empty, then it defaults to

    [button motion mouse keyboard]

i.e. the window is made sensitive to all these types of events.

Other event types may be added later.


-- -- rc_add_pic_to_window

After a window has been made sensitive, picture objects can be added to
the window using this method

    rc_add_pic_to_window(pic, win_obj)

described in HELP RC_LINEPIC/rc_add_pic_to_window

Examples in TEACH RC_LINEPIC/rc_add_pic_to_window

To see how to make the same picture object visible in several windows
see HELP RC_LINKED_PIC

See also the next item

-- -- rc_remove_pic_from_window

    rc_remove_pic_from_window(pic:rc_selectable, win_obj:rc_window_object);

Removes pic from the list rc_window_contents(win_obj)
Does more complex things if pic is a "linked" picture. See
    HELP RC_LINKED_PIC

-- -- rc_new_graphic_widget
Create a new graphic widget without necessarily displaying it.

rc_new_graphic_widget(title, width, height, xloc, yloc, setframe);

Assigns the window to rc_window

-- -- rc_popup_panel

rc_popup_panel(x, y, panel_info, title, control_ident);
rc_popup_panel(x, y, panel_info, title, control_ident, container);

    container (optional extra argument)
        If present, container is a window object (instance of
        rc_window_object), in which case x, y specify location in the
        container.

    Uses rc_control_panel to put up a panel which waits until either
    a selection is made, or a cancel button clicked, or interrupt is
    invoked. While it waits, the calling program is suspended.

    Used by things like rc_popup_strings, rc_getfile, rc_readline
    and many more.

Example

uses rclib
uses rc_popup_panel

;;; Control variable to be set true when action performed.
vars xxx = false;

;;; A procedure to make it true.
define doit;
    true -> xxx
enddefine;

;;; This produces a panel with an OK button, which waits till the
;;; button is clicked.

rc_popup_panel(400, 20, [[ACTIONS: ['OK' ^doit ]]], 'test_window', ident xxx);

It returns no result, but the value of xxx can be interrogated.

xxx =>

See rc_control_panel for more complex examples of actions, and other
kinds of contents in the panel which is displayed. See rc_confirm, and
rc_popup_strings for examples of the use of rc_popup_panel.

-- -- rc_popup_query

rc_popup_query(x,y, strings, answers, centre, columns, buttonW, buttonH,
                     font, bgcol, fgcol, specs, options) -> selection;

Can be used to pop up a menu, or a set of options from which a subset
can be chosen, including

o Select buttons. These can be used in a popup menu which waits for the
  user to select one of the buttons. At that point the button label (or
  some other value associated with it) is then returned by the menu
  procedure.

o Option buttons. These come in groups displayed in a panel in a popup
  menu which asks a question. Any subset or none can be selected to
  answer the question. Additional select buttons are provided to
  indicate when the selection has been made.

LIB rc_popup_query defines the followin class and various associated
methods:
    define :class rc_select_button; is rc_option_button;

See HELP RC_BUTTONS

For examples see TEACH RCLIB_DEMO.P

-- -- rc_popup_readin
    This can be used to get a string or a number via a Popup mechanism.
    For examples see HELP RC_TEXT_INPUT/rc_popup_readin

-- -- rc_popup_readline
    This pops up a panel inviting the user to type in a line of text.
    When the RETURN key is pressed the panel disappears and the text
    string is broken up into words and numbers.
    For examples see HELP RC_TEXT_INPUT/rc_popup_readline

-- -- rc_popup_strings

rc_popup_strings(x, y, list, strings, rows, cols, font) -> selection;
rc_popup_strings(x, y, list, strings, rows, cols, font, container) -> selection;

    Using rc_popup_panel, create a panel, including a scrolling text
    window, and wait for user to make a selection from that window
    (by clicking or dragging) and press the 'OK' button. Return the
    selected string as result.
    If interrupted (Ctrl-C), or if the 'Cancel' button is selected,
    return false.

    x, y
        Screen location of top left corner of panel, in numeric or
        symbolic form:
            "left", "middle" "right" or  "top" "middle" "bottom"

    list
        A list or vector of strings list, to be displaced in a scrolling
        text panel

    strings
        Text strings to be displayed at the top of the panel

    rows, cols
        number of rows and columns to be displayed. If either is
        0 then use number required to display all rows, or all columns,
        or both.

    font
        Use specified font.

    container (optional extra argument)
        If present, container is a window object (instance of
        rc_window_object), in which case x, y specify location in the
        container.

Compare rc_popup_strings, which uses rc_popup_panel with
rc_display_strings, which uses rc_control_panel to put up a "permanent"
display showing the strings, and allowing a different string to be the
currently "selected" string at different times.

rc_popup_strings uses rc_popup_panel to put up the list of strings, and
waits till you make a selection which is then returned.

Example:

vars
    strings =
    ['Select your string' 'after scrolling if necessary'],
    vec =
    {%
        lvars x;
        for x to 40 do
            x ><
                '. a very useful number to display today is the number '
                    >< x
        endfor;
    %};

rc_popup_strings(500, 20, vec, strings, 30, 50, '9x15') =>

The selected string can be returned by double-clicking, by pressing
RETURN on the keyboard or by clicking on the OK button. The Cancel
button causes false to be returned.


-- -- rc_poster
rc_poster(
    x,y, strings, spacing, centre, font, bgcol, fgcol) -> win_obj;

    Exactly like rc_message, except that clicking with the mouse
    has no effect, so the message remains until removed with
    rc_kill_window_object.
    The centre argument can be false, true, or the word "right".
    Anything else counts as true. This uses rc_print_strings
        See HELP RC_BUTTONS/rc_poster for examples


-- -- rc_print_strings

rc_print_strings(x, y, strings, spacing, centre, font, bgcol, fgcol)
                    -> (maxwidth, totalheight);

    Print a list of strings in a box starting at location x,y (top
    left corner). The other arguments are:

        strings -- a list of strings.
        spacing -- an integer indicating additional vertical spacing
            between strings (often 0).
        centre  -- a boolean or one of the words "left", "centre" or
            "right", indicating whether strings should be centred
            relative to the longest string. If it is true or "centre"
            the strings are centred. If "left" or false, they are
            left aligned. If "right" then right aligned.
        font    -- a string specifying the font to be used.
        bgcol   -- false or a string indicating background colour
        fgcol   -- false or a string indicating foreground colour

    The results maxwidth, totalheight, are positive or negative integers
    or ratios specifying the width and height of the rectangle used to
    print the strings. x, y, spacing, and maxwidth and totalheight are
    all relative to the current rc_window frame, i.e. to get pixel
    values multiply by rc_xscale or rc_yscale.
        (See also rc_text_area)

    If either of bgcol or fgcol is false the corresponding current
    default for the window is used. If bgcol is specified, a rectangle
    of that colour is drawn using rc_draw_bar before the strings are
    printed. If fgcol is specified that colour is used for printing the
    strings.

-- -- . variable rc_print_strings_offset

The global variable rc_print_strings_offset (default value 2) specifies
the minimal amount of the coloured background that should be visible to
left and right of the strings. The effect is felt by derivatives, e.g.
rc_poster, rc_message, rc_message_wait

-- -- rc_procbrowser and rc_lispbrowser

The procedures rc_procbrowser rc_lispbrowser, which can be invoked by
        ENTER procbrowser
are program development tools.

The ved command uses the file extension to decide whether to fetch the
Pop-11 version or the Lisp version. Additional versions may be added
later for the other languages.

The browser procedure produces a list of procedure headers in the
current Ved file and displays them in a scrolling text window in a panel
with buttons for doing various things that are useful during program
development, or while browsing a program file.

It uses rc_display strings, which is based in rc_control_panel, which
does automatic formatting of control panels. So end users can very
easily modify the browser tools to add additional control buttons, etc.
Just copy the source and edit. (A better way to modify without doing
that may be added later.)

Compare rc_browse_files

The following default global variables may be changed by users

-- -- -- rc_procbrowser defaults

    rc_procbrowser_button_font = '*lucida*-r-*sans-10*';
    rc_procbrowser_button_width = 105;
    rc_procbrowser_scroll_columns = 55;
    rc_procbrowser_scroll_rows = 15;
    rc_procbrowser_scroll_font = '7x13';
    rc_procbrowser_text_font = '*lucida*-r-*sans-12*';

-- -- -- rc_lispbrowser defaults

    rc_lispbrowser_button_font = '*lucida*-r-*sans-10*';
    rc_lispbrowser_button_width = 105;
    rc_lispbrowser_scroll_columns = 55;
    rc_lispbrowser_scroll_rows = 15;
    rc_lispbrowser_scroll_font = '7x13';
    rc_lispbrowser_text_font = '*lucida*-r-*sans-12*';

-- -- rc_query_mouse

rc_query_mouse() -> (x,y);

Returns current screen coordinates of mouse pointer (or possibly
undef,undef)

-- -- rc_readline

rc_readline(x, y, strings, prompt, specs, title) -> list;
rc_readline(x, y, strings, prompt, specs, title, container) -> list;

    Using rc_getinput present a window at screen location x, y, with the
    strings displayed (e.g. giving instructions or asking a question)
    and a tex input panel containing the string prompt. The panel has
    the string title as its title, and the possibly empty vector specs
    is a possibly empty list of two element vectors specifying features
    of the text input field (see HELP RC_CONTROL_PANEL for information
    about such specifications).

    Return a list consisting of the words and numbers typed in.
    Interprets input in the same way as readline.

    container (optional extra argument)
        If present, container is a window object (instance of
        rc_window_object), in which case x, y specify location in the
        container.

Example:

uses rclib
uses rc_readline

vars instruct =
    ['Type your name in'
    'Press return or click'
    'Then press "OK"'];

rc_readline(600, 300, instruct, '', [], 'Name?')=>
rc_readline(600, 300, instruct, '', [{font '12x24'}], 'Name?')=>


-- -- rc_rotate_vector

An autoloadable utility for rotating vectors.

define rc_rotate_vector(x, y, ang) -> (x, y);
    ;;; Takes two numbers (user co-ordinates) and returns two
    ;;; new numbers, corresponding to rotation by ang
    lvars
        x,y
        angcos = cos(ang),
        angsin = sin(ang);

    ;;; First rotate about user origin
    x * angcos - y * angsin, x * angsin + y * angcos -> (x, y)
enddefine;

-- -- rc_reset_panel

rc_reset_panel(panel)
    This can be used to reset the internal frame coordinates for a panel
    created by rc_control_panel whose buttons etc have stopped working
    e.g. because an action button changed something it shouldn't have.
    See also ved_killwin

-- -- rc_run_deferred_events

rc_run_deferred_events();

    After ensuring that all previous display events (e.g. drawing events
    have been completed), this will run events that were deferred
    because rc_in_event_handler was true when an attempt was made to
    invoke them or because they involved action buttons using DEFER
    (See HELP rc_buttons)

    It can be used with LIB SIM_AGENT. E.g. call it in sim_run_agent to
    ensure deferred events are handled after each agent runs, if the
    agents can draw on the display and suppress event handling when they
    do so. This is sometimes needed to ensure button and drag events are
    not kept waiting indefinitely because of program generated activity
    on the screen.
    See also HELP RC_EVENTS

-- -- rc_scratch_panel
(Based on suggestions from Brian Logan).

rc_scratch_panel(x, y);
    Creates a small window at location (x, y) on the screen. This
    has four buttons, One creates a new window object using
    rc_scratch_window and rc_tearoff, described below.

    Another removes previously "torn off" windows. A third deletes the
    current scratchpad window. The fourth deletes the panel.

    The New panel button makes the new scratchpad window the value of
    rc_current_window object, by using rc_make_current_window

-- -- rc_scratch_window


LIB RC_SCRATCH_WINDOW

Used with LIB RC_SCRATCHPAD

rc_scratch_window is an active variable which creates a "safe"
rc_graphic window when accessed. For examples see

    TEACH RCLIB_DEMO.P/rc_scratchpad
    LIB RC_SCRATCH_WINDOW

Accessing the active variable causes a "scratchpad" window to be created
if there is no current one. It can be used for drawing on.

Assigning false to it, removes the current scratchpad window. Assigning
undef to it makes it treat the scratchpad window as "torn off" and
inaccessible. I.e. the picture on it is saved. Then the next time
rc_scratch_window is accessed, a new scratchpad window is created.

(The mouse button 1 plus Control Key can be used used to make a
previously "torn off" scratchpad current again.)

The library uses a new class

 define :class rc_scratch_window; is rc_window_object;

 define active rc_scratch_window() -> win_obj;
 define updaterof active rc_scratch_window(item);
 define rc_tearoff();
 define rc_kill_tearoffs();
 define lconstant switch_scratchpad();
 define :method rc_button_1_down(pic:rc_scratch_window, x, y, modifiers);

-- -- rc_screensize

rc_screensize() ->(width, height);
    Returns width and height of current screen.

-- -- rc_set_planemask
rc_set_planemask(window, mask);
    Utility used for coping with differences between colour terminals.

-- -- rc_set_window_scale and rc_pixels_per_inch

rc_set_window_scale(win_obj:rc_window_object, type, xscale, yscale);
Changes the scale variables in the window object. This is based
on LIB rc_set_scale

Type can be
    "inches"
        Then xscale is the number of inches per user unit to right
        Then yscale is the number of inches per user unit up screen

    "cm"
        Then xscale is the number of centimetres per user unit to right
        Then yscale is the number of centimetres per user unit up screen
    "frame"
        Then xscale is the number of window widths per user unit to right
        Then yscale is the number of window heights per user unit up screen
    false
        Just use xscale and yscale as given (y positive upwards)

The global variable rc_pixels_per_inch is given the default value of 90.
Change it if necessary.

rc_set_window_scale uses rc_shift_window_frame_by


-- -- rc_setup_linefunction
rc_setup_linefunction();
    Utility used for determining whether to use xor or equiv for
    handling movable picture objects.
    In December 1999 this was extended to distinguish three cases

        Displays of depth > 8 bits
            rc_xor_drawpic -> Gdrawprocedure;
            GXequiv -> Glinefunction;

        8 Bit displays with white == 0
            rc_xor_drawpic -> Gdrawprocedure;
            GXxor -> Glinefunction;

        8 Bit displays with white == 1
            GXequiv -> Glinefunction;
            rc_equiv_drawpic -> Gdrawprocedure;

    Automatic invocation of rc_setup_linefunction before creating
    any moving pictures solves the main problem described in
    HELP rclib_problems


-- -- rc_shift_window_frame_by

method

rc_shift_window_frame_by(x, y, win_obj:rc_window_object);

    Alters the location of the origin of the window object by the
    amounts, x and y relative to the current scales.
    Uses rc_shift_frame_by, documented in
        HELP RC_GRAPHIC/rc_shift_frame_by

    It first undraws all objects known to the window (as a result of
    calls of rc_add_pic_to_window, then changes the origin then
    re-draws them

    This allows objects that have been moved out of the visible are to
    be made visible again.


-- -- rc_showtree
rc_showtree(tree, x, y, font);
rc_showtree(tree, x, y);
    Partly modelled on LIB SHOWTREE

    Draws a tree, at location x, y, using font (string) argument if
    provided to specify fonts for the node labels.
    controlled by the following global variables.

        showtree_ortho_links;
        showtree_oblong_nodes;
        showtree_sideways;

    See HELP RC_SHOWTREE

-- -- rc_slider

LIB RC_SLIDER defines a class, rc_slider and a procedure for creating
instances of the class. The slider is represented by a straight coloured
bar linking two specified points, and a movable blob, which can be of
various shapes. There may also be a number panel and assorted labels
alongside the slider. The slider can have any orientation.

The main procedure is:

rc_slider(x1, y1, x2, y2, range,
            radius, linecol, slidercol, strings) -> slider;

rc_slider(x1, y1, x2, y2, range,
            radius, linecol, slidercol, strings, specs) -> slider;

Optional arguments allowed are:
    o A featurespec vector or list (or false)
    o A word or identifier to be associated with the value
    o A type specifier, which can be word, key, or constructor
      procedure, e.g. newrc_square_opaque_slider, as illustrated
      above.

The range argument can take one of five forms, specifying min and max
values, a default initial value, and a step increment value.

    a number, in which case it is taken to be max, with
        min = 0, default = 0.

    a two element vector {min max}
        then default = min.

    a three element vector
        {min max default}

    a four element vector
        {min max default step}

For more information see

    HELP RC_SLIDER

For additional examples of the use of sliders see
    TEACH RCLIB_DEMO.P
    TEACH RC_CONTROL_PANEL
    HELP  RC_CONTROL_PANEL
    LIB   RC_POLYPANEL

-- -- rc_opaque_slider

 define rc_opaque_slider(x1, y1, x2, y2, range,
        radius, linecol, slidercol, strings) -> slider;

    with optional extra arguments similar to rc_slider.

This extends rc_slider using rc_opaque_movable, to overcome the problem
of a movable slider blob not looking the right colour, for reasons
explainedin TEACH RC_OPAQUE_MOVER

LIB RC_OPAQUE_SLIDER defines the following

 define :class rc_opaque_slider; is rc_slider rc_opaque_movable;
 define :method rc_setup_slider_barwidth(slider:rc_opaque_slider, radius);
 define :method rc_draw_slider_opaque(s:rc_opaque_slider);
 define :class rc_square_opaque_slider; is rc_opaque_slider;
 define :method rc_draw_opaque_slider_square(s:rc_opaque_slider);

 define rc_opaque_slider(x1, y1, x2, y2,
        range, radius, linecol, slidercol, strings) -> slider;

-- -- rc_square_slider

This extends rc_slider with the option of a square movable slider "blob"

rc_square_slider(x1, y1, x2, y2, range,
            radius, linecol, slidercol, strings) -> slider;
rc_square_slider(x1, y1, x2, y2, range,
            radius, linecol, slidercol, strings, specs) -> slider;

Note that LIB rc_opaque_slider  defines a class rc_square_opaque_slider

-- -- rc_sync_display and rc_window_sync

rc_sync_display();

    Use XptSyncDisplay to synchronise display (i.e. wait till it
    is quiescent.
    Then if rc_sync_delay_time is an integer (default false) call
    syssleep(rc_sync_delay_time) for additional delay.

Contrast rc_window_sync which uses the global variable
rc_window_sync_time defined thus:

define rc_window_sync();
    dlocal rc_sync_delay_time = rc_window_sync_time ;
    rc_sync_display()
enddefine;

It is not clear that both procedures rc_window_sync and rc_sync_display
are needed.

-- -- rc_testbrowser

rc_testbrowser(x, y, file, filter, rows, font);

    Simplified interface to rc_browse_files

Examples
    rc_testbrowser(400, 10, '~', '*', 30, '9x15');
    rc_testbrowser(400, 10, '~/', '*.p', 30, '9x15');

Check the variable which holds the selected string:
    the_selected_string =>

-- -- rc_text_area

rc_text_area(strings, font) ->(widths, maxwidth, height, ascent);

    Given a list of strings, and a font, return a list of text widths,
    one for each string, the maximum width required to print the
    strings, the text height for that font, and the ascent height. A
    graphic window must already exist as the value of rc_window.

    All the numbers produced are integers, in pixel values, not scaled
    values, so they may have to be divided by rc_xscale or rc_yscale to
    get suitable values for rc_graphic commands.
    [Changed 30th April.]

-- -- rc_title

rc_title(window) -> string;
string -> rc_title(window)

Get or set title of window

See also the method rc_window_title(win_object), defined in

LIB rc_window_object


-- -- rc_transfer_window_contents

rc_transfer_window_contents(win_obj1, win_obj2);
rc_transfer_window_contents(win_obj1, win_obj2, true);

Where win_obj1 and win_obj2 are instances of rc_window_object (typically
created by rc_new_window_object). this procedure transfers the drawable
and selectable picture objects from win_obj1 to win_obj2, but without
copying them, and without erasing them from the first window. This can
cause confusion if you are not careful.

If the optional third argument, true, is provided, then the objects
are copied, and the objects in the two windows can then be moved
independently of each other.

See HELP RC_TRANSFER_WINDOW_CONTENTS

-- -- rc_transform_lines

Used to gradually transform one polygon or other picture, defined
by a list or vector of numbers, to a new picture, also defined by
a list or vector, of the same length. (Compare rc_transform_pictures)

Usually the numbers will define coordinates of points, e.g. if the
pictures are polygons (open, closed or filled). But other options
are supported.

rc_transform_lines(
    coords1, coords2, N, colour,
        widthOrShape, mode, delay, trail, proc);

coords1 and coords2:
    are lists or vectors of K sets of coordinates representing points to
    be joined by lines, which are to be drawn as open or closed
    polygons, or as filled polygons, depending on the drawing
    procedure proc. They could have a different interpretation if
    proc is a user-defined procedure, as explained below. If they are
    2-D coordinates then each list or vector has length 2xK.

N:
    the number of intermediate steps

colour:
    The procedure rc_interpolate_coords defined above is used N times to
    find an intermediate set of coordinates to draw the figure, using the
    colour given (a string).

proc:
    Is one of these procedures, defined above:

    rc_draw_lines           -- for open polygons
    rc_draw_lines_closed    -- for closed polygons
    rc_draw_lines_filled    -- for filled polygons

    Or a user defined procedure, which must take four arguments,
        a list or vector,
        a colour,
        and two other arguments corresponding to
            widthOrShape and mode in the call to
            rc_transform_lines

widthOrShape:
    If proc is one of the three procedures listed above, then this is
    an integer specifying line width for open or closed polygons
    or else one of Convex, Nonconvex or Complex for filled polygons, as
    explained in connection with the above three procedures.
    If proc is a user-defined procedure this will be given as the
    third argument.

mode:
    If proc is one of the three procedures listed above, then this is
    one of CoordModeOrigin or CoordModePrevious, depending on whether
    the coordinates are to be interpreted relative to the fixed origin
    or relative to the previous point (except for the first point).
    If proc is a user-defined procedure this will be given as the
    fourth argument.

delay:
    an integer representing the delay in 100ths of a second between
    drawn stages. Make this smaller for faster morphing.

trail:
    This is a boolean. If it is true, then the intermediate steps are
    left drawn, otherwise they are drawn and deleted, using XOR or
    EQUIV, according to the value of Glinefunction, explained above.
    (Set by rc_setup_linefunction.)

An example of the use of this procedure is given in
    LIB rc_pythagoras

An example to draw a filled blue rotating triangle with changing shape
follows:

vars win1 =
        rc_new_window_object("right", "top", 500, 500, true, 'win1');

rc_start();
;;; three points defining an open polygon, linewidth 4
rc_transform_lines(
    {-220 200 0 150 -50 0},    ;;; initial triangle
    {-20 -150 100 200 220 130},   ;;; final triangle
    40, 'blue', 4, CoordModeOrigin, 4, false,
        rc_draw_lines);

rc_start();
;;; a closed polygon, linewidth 10
rc_transform_lines(
    {-220 200 0 150 -50 0},    ;;; initial triangle
    {-20 -150 100 200 220 130},   ;;; final triangle
    40, 'green', 10, CoordModeOrigin, 4, false,
        rc_draw_lines_closed);

rc_start();
;;; a filled polygon red
rc_transform_lines(
    {-220 200 0 150 -50 0},    ;;; initial triangle
    {-20 -150 100 200 220 130},   ;;; final triangle
    40, 'red', Convex, CoordModeOrigin, 4, false,
        rc_draw_lines_filled);

Further examples can be seen by looking at the tests in the file:
    LIB rc_transform_lines


-- -- rc_transform_pictures

rc_transform_pictures(pics, steps, delay, trail);

This is used to create a display with several moving pictures
defined by collections of lines, etc. It repeatedly draws/re-draws a
collection of pictures specified in the list or vector pics.
They are drawn steps times with a pause of delay 100ths of a second
between each "frame". If trail is true the intermediate versions remain
drawn, otherwise they are deleted before the next frame.
(Compare rc_transform_lines)

pics:
    A vector or list of picture specifications, where each element is
    a vector or list, containing six items:
        startcoords, endcoords, colour, widthOrShape, mode, proc
    as follows:

        startcoords:
            a lists or vector of K sets of coordinates representing
            points defining the initial state of a sub-picture, to be
            drawn by proc. If the numbers represent 2-D coordinates then
            startcoords has length 2xK.

        endcoords:
            Similar to startcoords, but defines the final state of a
            subpicture

        colour:
            A string

        widthOrShape:
            If the procedure proc is rc_draw_lines_filled (or the word
            "FILLED" then this should be one of
                Convex, Nonconvex or Complex (See REF XpwPixmap)
            Otherwise value should be an integer representing width
            of lines or something interpreted by a user-supplied
            procedure proc

        mode:
            One of
                CoordModeOrigin:
                    coordinates are relative to the origin
                CoordModePrevious:
                    coordinates are relative to the previous point,
                    apart from the first point which is taken to be
                    relative to the origin.
                    See MAN  XDrawLine.
        proc:
            This can be one of the words "OPEN", "CLOSED" or "FILLED"
            interpreted as referring to the corresponding one of these
            procedures
                rc_draw_lines           -- for open polygons
                rc_draw_lines_closed    -- for closed polygons
                rc_draw_lines_filled    -- for filled polygons
            or it can be a procedure or a name of a procedure, as long
            as the procedure takes four arguments:
                a vector (e.g. like startcoords, etc.)
                a colour,
                two other arguments corresponding to widthOrShape
                    and mode as explained above

steps:
    An integer specifying how many intermediate pictures should be
    drawn between initial and final state.

delay:
    An integer specifying 100ths of a second delay between frames.

trail:
    A boolean. If false, rc_transform_pictures does not leave a "trail"
    of intermediate states visible, otherwise it does.


Examples of use of rc_transform_pictures
vars win1 =
        rc_new_window_object("right", "top", 500, 500, true, 'win1');

rc_transform_pictures(
    [
        [[0 200 50 50 50 100] [180 10 100 190 200 200]
            'blue' 4 ^CoordModeOrigin OPEN]

        [[-100 100 50 0 50 100] [200 -50 100 50 220 80]
            'red' ^Convex ^CoordModeOrigin FILLED]

        [[-150 -200 -50 -10 50 -100] [180 -150 200 -50 240 -200]
            'green' 6 ^CoordModeOrigin CLOSED]

    ],
    20, 1, false);

;;; redo that with final argument set true to leave a trail

-- -- rc_vedfileselect

    rc_vedfileselect(x, y, font);
    rc_vedfileselect(x, y, font, container);

Starts up a selector for files currently in the editor. It may appear
on its own, or inside another container panel.

-- -- rc_warp_to

rc_warp_to(win, x, y);
    Win is an instance of rc_window_object or a widget. Warp the mouse
    pointer to the widget at location x y on the widget.
    If x is false use middle of width. If y is false use middle of
    height. So, to warp to middle of window: rc_warp_to(win, x, y)

-- -- rc_widen_window_by

rc_widen_window_by(win_obj, width, colour);

    NB this was changed, Feb 2000, to conform to the conventions of
    rc_foreground.

    win_obj is an instance of rc_window_object. Increases its width by
    width (on the right). If colour is false it uses the current
    foreground colour. If it is the word "background" it uses the
    current background colour. Otherwise colour is a string or integer.
    (Compare the convention for rc_foreground)

    See also rc_lengthen_window_by

-- -- rc_window_coords

rc_window_coords() ->(xloc, yloc)
xloc,yloc -> rc_window_coords();

This procedure and its updater can be used to access or update the X and
Y coordinates of the Xgraphic window on the screen.
    See HELP RC_WINDOW_COORDS

Compare rc_window_location which handles x, y, width, height for
rc_window_object instances.

-- -- rc_window_dimensions

rc_window_dimensions() ->(width, height)
width, height -> rc_window_dimensions();

This procedure and its updater can be used to access or update the width
and height of the Xgraphic window on the screen.
    See HELP RC_WINDOW_DIMENSIONS

Contrast rc_screen_frame in rc_window_object

-- -- rc_xterm

rc_xterm(x, y);

    This will open an xterm window (using defaults from your .Xdefaults
    file. Before doing that it uses rc_getinput to get a command to
    be obeyed in the xterm window. If no command is given, then an
    xterm window is started with no program running.

    x and y are the coordinates of the location for the rc_getinput
    panel asking for text.

Example:

uses rclib
uses rc_xterm

rc_xterm(300,300);

E.g. try typing in the text input window
        pop11 +eliza
or
        top

-- -- self_caller()

This autoloadable procedure is useful for procedures linking fields in a
control panel, to check for looping recursion. It is defined thus:

define self_caller() -> boolean;
    ;;; Is the caller of this procedure (caller(1)) in the calling
    ;;; chain above itself
    iscaller(caller(1), 2) -> boolean;
enddefine;

It can be used in a test of this form at the beginning of a constraint
procedure:

    returnif(self_caller()):

An example is in TEACH RC_CONSTRAINED_PANEL


-- -- SETWINDOW <expression>

    This is a syntax word which can be used as an abbreviation for

        <expression> -> rc_current_window_object

    See also rc_current_window_object, below.

-- -- Interacting with VED files

-- -- .  ved_open_file(name, x, y, cols, rows, saveable);
    Open the file if it does not already exist, at location x, y on
    screen, with specified number of columns and rows, with vedwriteable
    true or false depending on saveable.

    If XVed is not running the x, y, cols, rows arguments are ignored.

-- -- .  ved_write_to_file(item, file);
    Item should be a printable pop-11 item, e.g. list, string, number,
    etc.

-- -- .  ved_read_from_file(string, file) -> list;

    Analogous to readline, except that it uses a specified Ved/XVed
    file, and it prints the string as a prompt in the file.
    Then read a line of text, terminated by RETURN and return it, as
    readline does.

    Open the file with the following defaults if the file is not
    already in Ved.
        ;;; default location for file
        rc_ved_x_default = 300;
        rc_ved_y_default = 300;

        ;;; default number of rows and columns
        rc_ved_cols_default = 40;
        rc_ved_rows_default = 8;

    Users may change these defaults, or open the file using
    ved_open_file. if XVed is not running those defaults are ignored
    by Ved.


-- -- ved_browser

Ved ENTER command for invoking rc_browse_files

    ENTER browser -k
        Dismiss all panels produced by the browser

    ENTER browser path

    ENTER browser pattern

    ENTER browser path pattern

The pattern is a filter used to select files in the directory given by
path.

See also ved_procbrowser

-- -- ved_killwin (ENTER killwin)

ved_killwin();
Can be used as an ordinary procedure or as a VED command

    ENTER killwin

It does

    rc_kill_window_object(rc_current_window_object);

To select the window to be killed, make it the current window object, by
clicking on it with mouse button 1 (left) while CTRL/Control key is held
down. Then ENTER killwin

-- -- ved_procbrowser (ENTER procbrowser)

This ENTER command invokes rc_procbrowser or rc_lispbrowser, depending
on the extension of the current file. It may later cope also with
Prolog and ML.

define ved_procbrowser();
    lvars extension = sys_fname_extn(vedpathname);
    if member(extension, lispfiletypes) then
        veddo(':rc_lispbrowser()')
    else
        veddo(':rc_procbrowser()')
    endif;
enddefine;

For further details, including user-modifiable global variables see the
information above for

    rc_procbrowser
    rc_lispbrowser

See also ved_browser

-- -- ved_rcdemo (ENTER rcdemo)

LIB VED_RCDEMO defines a VED procedure for looking at files in
    $poplocal/local/rclib/demo/*.p

Do
    ENTER rcdemo <file>

The '.p' will be added.

-- -- veddiscin

veddiscin(filename) -> repeater
    Given a filename produce a character repeater which reads from the
    VED buffer with that name. Waits for user to press RETURN.

-- -- veddiscout
veddiscout(filename) -> consumer;

-- -- vedreadlinefrom
vedreadlinefrom(filename, defaults, save) -> list;
    Utility for getting a line of text from a Ved buffer.

    filename: a string
    defaults: false or vedhelpdefaults, or vedveddefaults ,etc.
    save:     if true, then save the buffer, otherwise quit


-- NON-AUTOLOADABLE LIBRARIES AND PROCEDURES --------------------------

These libraries need to be explicitly compiled (with uses or lib) as
they are not in the autoloadable directory, though they may use
procedures that are there. They are all made accessible via

    uses rclib

followed by a more specific "uses" command including the library name.

-- -- rc_coords

This method is defined in various places, e.g. in LIB RC_LINEPIC,
LIB RC_WINDOW_OBJECT, and elsewhere, for various classes. It returns the
x,y coordinates of a window object on the screen or inside another
window object, or the coordinates of a picture object in a window
containing it.

    define :method rc_coords(pic:rc_linepic) -> (x, y);
    define :method updaterof rc_coords(/*x, y,*/ pic:rc_linepic);


    define :method rc_coords(pic: rc_selectable) -> (x, y);
    define :method updaterof rc_coords(/*x, y,*/ pic:rc_selectable);

    define :method rc_coords(w:rc_window_object) -> (x, y);
    define :method updaterof rc_coords(/*x, y,*/ w:rc_window_object);


-- -- LIB getpointvec

-- -- . getpointvec(points, n, closed) ->(nitems, vec);

Given
    1. points:
        a list, vector or shortvec (See REF INTVEC) with
        coordinates for points in an n-dimensional space

    2. n:
        an integer

    3. closed:
        a boolean (trye if the points represent a closed
        polygon).

returns a vector vec and the number nitems of groups of n integers in
the vector (i.e. length(points)/n, plus 1 if closed)

If closed is true, then the new vector vec has n more items
than the original  (all 0). In that case the last n fields wll
be used by the calling procedure to store the the coordinates of the
final point in a closed polygon.

If closed is false, and vec is a vector, then vec is returned.

A vector of length less than or equal to max_reusable_vector
created by getpointvec can later be given to the procedure
freepointvec (described below) to be saved for re-use.

In that case if getpointvec later needs to use a vector of the same
length it will use one of the saved ones instead of creating a new one
everytime.

This is based on the non-exported procedure shortpointvec in
LIB XpwPixmap

-- -- . freepointvec(vec)

NOTE: this procedure is potentially dangerous, like sys_grbg_list,
sys_grbg_destpair, etc. and is made available in case there is a
need to reduce garbage collections for efficiency.
(See HELP EFFICIENCY).

Given a vector of length N adds it to the collection of re-usable
vectors of length N unless N exceeds the value of the global variable
max_reusable_vector. The re-usable vectors will be found by getpointvec
when needed.

-- -- . Global variable: max_reusable_vector

This has the default value 30 (which may change).

Users can give this a larger or smaller value. Use the maximum size of
polygon you are likely to need drawn frequently.

This is used in
    rc_draw_lines, rc_draw_lines_closed, rc_draw_lines_filled

-- -- LIB rc_apply_util

This is designed to enable certain types of rc_graphic commands to be
applied to a particular window.

It is not clear how useful this is. For details see LIB rc_apply_util
May be withdrawn, or redefined.

Used by rc_extend_utils

-- -- LIB rc_buttons

LIB rc_buttons
Described in far more detail in HELP RC_BUTTONS

This demonstrates how to make button objects which contain a descriptive
label and cause a procedure to be invoked if clicked on (e.g. a Ved
procedure). Details can be found in HELP RC_BUTTONS. The various types
of button fields in rc_control_panale, e.g. ACTIONS, SOMEOF, RADIO
buttons are all based on this library.

This package includes facilities for creating single buttons of various
sorts, rows of buttons, columns of buttons, etc. The following are
included, explained in more detail in the help file. Users can, of
course, define new classes of buttons using the inheritance mechanisms
of Objectclass.

-- -- . Asynchronous control buttons:

o Action buttons.

o Action buttons with blobs.

o Toggle buttons.

o Counter buttons.

o Radio buttons.

o Someof buttons.

-- -- . Synchronous control buttons (for popup menus):

o Select buttons.

o Option buttons.

-- -- . Procedures for creating individual buttons or collections

-- -- -- create_rc_button

create_rc_button(x, y, width, height, contents, type, specs) -> button;
create_rc_button(x, y, width, height, contents, type, specs, "nodraw") -> button;

    Create an individual button, of whatever type. The full explanation
    is given in HELP rc_buttons/create_rc_button


-- -- -- create_button_columns

create_button_columns(x, y, width, height, spacing, columns,
                                    list, type, specs) -> buttons;
    Display a list of buttons in a row, or in one or more columns.
    Defined in LIB rc_buttons


-- -- -- create_radio_button_columns
-- -- -- create_someof_button_columns

create_radio_button_columns(x, y, width, height, spacing, columns,
                                        string, list, specs) -> buttons;
    Display a set of radio buttons, with a message given by string
    Individual buttons may be toggled by clicking. Only at most
    one can be true. See HELP rc_buttons
    Defined in LIB rc_button_utils


create_someof_button_columns(x, y, width, height, spacing, columns,
                                        string, list, specs) -> buttons;
    Display a set of someof buttons, with a message given by string.
    Individual buttons may be toggled by clicking. Any subset can
    be true. See HELP rc_buttons
    Defined in LIB rc_button_utils

create_button_row(x, y, width, height, spacing,
                                        list, type, specs) -> buttons;

    Creates and displays just one row of radio or someof buttons.
    Defined in LIB rc_button_utils

create_button_column(x, y, width, height, spacing,
                                        list, type, specs) -> buttons;

    Creates and displays just one column of radio or someof buttons.
    Defined in LIB rc_button_utils

See also rc_add_kill_button

-- -- . Additional procedures in LIB rc_button_utils

define create_action_button(x, y, width, height,
        label, action, specs) -> button;

define create_blob_button(x, y, width, height,
        label, action, specs) -> button;

define create_option_button(x, y, width, height,
        label, specs) -> button;

define create_select_button(x, y, width, height,
        label, specs) -> button;


-- -- . Classes and mixins concerned with buttons

See HELP RC_BUTTONS
    (Much revised Feb 2004)

 define :class vars rc_button_window; is rc_window_object;
 define :mixin rc_button;
 define :mixin rc_display_button;
 define :class rc_action_button; is rc_button;
 define :class rc_invisible_action_button; is rc_action_button;
 define :class rc_blob_button; is rc_action_button;
 define :class rc_toggle_button; is rc_display_button rc_button;
 define :class rc_counter_button; is rc_display_button rc_button;
 define :class rc_option_button; is rc_display_button rc_button;
 define :class rc_radio_button; is rc_option_button;
 define :class rc_someof_button; is rc_radio_button;

The library supports many methods associated with these classes and
mixins, e.g. mouse button up or down methods and methods for altering
the appearance of buttons when selected or de-selected.

-- -- LIB rc_compound

Experimental library defining compound objects that can be moved.

 define :mixin rc_compound is rc_linepic;
 define :mixin rc_component is rc_linepic;
 define :method rc_draw_linepic(p: rc_compound);
 define :method rc_undraw_linepic(p: rc_compound);
 define :method rc_move_by(p:rc_compound, dx, dy, draw);
 define :method rc_move_to(p:rc_compound, x, y, draw);

This is probably not usable directly but could be a starting point for
a suit of utilities for handling compound objects whose instances
contain picture objects.

-- -- LIB rc_constrained_mover

A collection of utilities for defining movers that are constrained, e.g.
to move horizontally, or vertically, or along a line between two points,
or in some other fashion. See

    LIB rc_constrained_mover

The rc_slider facility, described below, is based on one of the
subclasses defined here. For tutorial examples see

    TEACH RC_LINEPIC/rc_constrained_mover

See also
    LIB RC_SLIDER
    HELP RC_SLIDER

Defined in LIB rc_constrained_mover
   define :mixin rc_constrained_mover; is rc_linepic_movable;
        slot rc_constraint;
        slot rc_keypress_handler;
   define :method rc_key_do_nothing(b:rc_constrained_mover, x, y, modifiers, key);
   define :mixin rc_horiz_constrained_mover; is rc_constrained_mover;
   define :method rc_move_to(pic:rc_horiz_constrained_mover, x, y, mode);
        ;;; ignore y, i.e. do not allow picy to change, only picx
   define :mixin rc_vert_constrained_mover; is rc_constrained_mover;
   define :method rc_move_to(pic:rc_vert_constrained_mover, x, y, mode);
        ;;; ignore x, i.e. do not allow picx to change, only picy
   define :mixin rc_point_constrained_mover; is rc_constrained_mover;
   define lconstant orientation_record(x1, y1, x2, y2) -> vec;
   define rc_project_point(x, y, x1, y1, linecos, linesin) -> (x,y);
        ;;; project point x, y, onto the line through x1, y1, with orientation
        ;;; defined by linecos, linesin. This algorithm gives an accurate projection
        ;;; ONLY where x, y is already on the line, and in some other special cases,
        ;;; e.g. where the line is horizontal or vertical. However, the closer x,y is
        ;;; to the line, the more accurate the result. This is probably good enough
        ;;; for constraining a point moved by the mouse to lie on the line, e.g.
        ;;; finding a slider location.
   define :method rc_initialise_mover(pic:rc_point_constrained_mover);
   define :method rc_move_to(pic:rc_point_constrained_mover, x, y, mode);
        ;;; force pic to move only between end1 and end2, by projecting
        ;;; x,y onto the line between them


-- -- LIB rc_exceed (defunct)

This is now redundant. See rc_setup_linefunction

LIB RC_EXCEED was originally provided for use when eXceed on a PC is
being used to access Pop-11 and use graphics remotely.

All it does is

    GXequiv -> Glinefunction;
    rc_xor_drawpic -> Gdrawprocedure;

This should now happen automatically
    See HELP RCLIB_PROBLEMS

-- -- LIB rc_extend_utils

LIB RC_EXTEND_UTILS
HELP RC_EXTEND_UTILS

This gives information on how to extend a number of rc_graphic utilities
that access or update resources, so that they can also be applied to
instances of rc_window_object.

It applies to things like
    rc_font, rc_line_style, rc_line_width, rc_line_function,
    rc_background, rc_foreground, rc_title,

[This list may be extended]

-- -- LIB rc_freezable

LIB rc_freezable
Defines a class of movable objects which can be "frozen" so that they
are no longer movable. Freezable objects start off unfrozen. They can be
moved ONCE until they are frozen. This happens if the button is lifted
after the object has heen dragged.

Frozen objects are drawn as if they were not movable. (I.e. they then
show their true colours. See HELP RCLIB_PROBLEMS.)

 define :mixin rc_freezable; is rc_selectable;
 define :method rc_move_to(pic:rc_freezable, x, y, mode);
 define :method rc_freeze(pic:rc_freezable);
 define :method rc_unfreeze(pic:rc_freezable);
 define :method rc_draw_linepic(pic:rc_freezable);
 define :method rc_button_1_up(pic:rc_freezable, x, y, modifiers);

-- -- LIB rc_informant

defines a mixin that can be used as the basis for picture objects that
contain some information that can change either as a result of a
procedure being invoked or a user action driven by mouse or keyboard.
Examples are sliders which control a numerical value, "radio" buttons
which implement a user's selection of one item among a set of options,
"someof" buttons which implement the user's selection of a subset among
a set of options, text input and number input buttons.

Facilities provided (explained in more detail below):

 define :mixin rc_informant;
 define :method rc_informant_value(obj:rc_informant) -> val;
 define :method updaterof rc_informant_value(val, obj:rc_informant);
 define vars procedure rc_update_fields(val, list);
 define :method rc_information_changed(obj:rc_informant);
 define :method rc_informant_reactor_def(obj:rc_informant, val);
 define :method rc_informant_init(obj:rc_informant);

Global variables
        rc_constrainer_depth = 0,
        rc_reactor_depth = 0,

The library is basically very simple, providing some slots and methods
that can be used uniformly among a variety of different sorts of
classes, for objects which display some contents which can change.

-- -- . More detailed information on rc_informant facilities

define :mixin vars rc_informant;
    ;;; slot holding the contents (could be any value associated with
    ;;; the button, slider, etc.)
    slot RC_informant_value == rc_undefined;

    ;;; Slot holding a reactor method, taking object and new value,
    ;;; to be run when contents change. Set by "reactor" in rc_control_panel
    slot rc_informant_reactor == "rc_informant_reactor_def";

    ;;; A possible associated word or identifier, whose value is to be set
    ;;; when contents change.
    slot rc_informant_ident == false;

    ;;; Slot holding a constrainer method, applied when values are
    ;;; updated. Set by "constrain" in rc_control_panel
    ;;; For examples see TEACH * RC_CONSTRAINED_PANEL/Constraining
    slot rc_constrain_contents == identfn;

    ;;; Slot holding a window object, to be made current when the
    ;;; informant instance is updated, if that can cause drawing to
    ;;; occur on its window.
    slot rc_informant_window == false;  ;;; possible window_object
enddefine;


define global procedure rc_informant_label = newproperty([], 32, false, "tmparg")
    ;;; Associates a label with an item. This could be a slot for rc_informant
    (See below)

Various methods are automatically invoked by the methods which change
the value of a slider, or of a button of type counter, toggle, option,
radio, someof, etc.

 define :method vars rc_informant_value(obj:rc_informant) -> val;
 define :method updaterof rc_informant_value(val, obj:rc_informant);
    Access or update the object's current contents. There may be
    internal contents (e.g. a string) and external contents (e.g. a
    number to be displayed). This accesses or updates the external
    contents.
    The updater first runs the value through the procedure held in
        rc_constrain_contents(obj)
    which may transform the result, e.g. rounding it, and also check
    that it is of a permitted type, e.g. a member of a set of permitted
    values. Otherwise a mishap or warning message may result.
    It also checks whether the informant has an associated word or
    identifier in its rc_informant_ident field, and if so assigns to
    the valof.

 define :method rc_information_changed(obj:rc_informant);
    This does the following, by default

    recursive_valof(rc_informant_reactor(obj))(obj, rc_informant_value(obj))

    I.e. the procedure or method in the object's rc_informant_reactor
    slot is applied to the current (external) contents.
    This may trigger changes in other display items, e.g. to keep two or
    more things consistent (e.g. slider and number input panel).
    To prevent loops use this near the beginning of such a method.
        returnif(self_caller())
    (See TEACH RC_CONSTRAINED_PANEL for examples.)


 define :method rc_informant_reactor_def(obj:rc_informant, val);
    This is the default method held in the rc_informant_reactor slot.
    It does nothing. However it can be overridden by methods which
    propagate effects of change, as shown in TEACH RC_CONSTRAINED_PANEL

NOTE: the value held in rc_informant_reactor and rc_constrain_contents
    slots may be words which are names of procedures instead of
    procedures, since recursive_valof is applied to the value before
    it is applied to the arguments. This makes it possible to redefine a
    procedure after constructing a display, the new procedure will then
    be invoked by display events. This vastly speeds up testing and
    debugging, and also allows dlocal to be used to temporarily change
    a constrainer or reactor.


define :method rc_informant_init(obj:rc_informant);
    ;;; initialise informant with value of the corresponding identifier


define rc_informant_with_label(label, list) -> item;
    See below


-- -- Synonyms for backward compatibility

    syssynonym("rc_informant_contents", "rc_informant_value");
    syssynonym("RC_informant_contents", "RC_informant_value");


-- -- Note on use of mixin rc_informant

Designers have a choice if the behaviour of a particular subset of
cases is to be changed. Either a new subclass can be created and the
method rc_information_changed redefined for that class, or else the
individual instances that need different behaviours can have special
procedures or methods stored in their rc_informant_reactor slot.
Often the latter is simpler.

It is possible that this mechanism provides more flexibility than anyone
will ever want to use!

See also

    TEACH RC_CONSTRAINED_PANEL
    HELP rc_control_panel
    HELP rc_buttons
        LIB  RC_BUTTONS
    HELP RC_SLIDER
        LIB  RC_SLIDER
    HELP RC_TEXT_INPUT
        LIB RC_TEXT_INPUT

-- -- . rc_informant_window

    This is a slot in rc_informant instances, holding the window
    object in which they are drawn. See rc_informant

-- -- . rc_informant_label

    The property rc_informant_label makes it possible to associate
    a 'label', e.g. a word, string, or number, with picture objects on
    a panel, e.g. a button, slider, dial etc. in a list of
    items. If they can have labels then it will no longer be necessary
    to identify them by their location in the list. Instead use
        rc_informant_with_label

-- -- . rc_informant_with_label

    define rc_informant_with_label(label, list) -> item;
        Check that label, usually a string or word, is one of the labels
        of the items in the list.
        Return the item with the label or false.

-- -- LIB rc_linepic

This is one of the core libraries, defining the basic mixins and methods
for creating and drawing static or moving or rotatable picture objects.
Normally used with rc_window_object

See TEACH RC_LINEPIC, HELP RC_LINEPIC
and other files referred to therein.

Two important extension added in July 2000 are:

    LIB rc_opaque_mover
        This makes it possible to overcome some of the problems of
        drawing movable objects when the background is not white,
        but is known to be uniform in colour.
        Described in more detail below.

    New mixin rc_rotatable_picsonly
        This makes it possible to define rotatable objects which do not
        alter the position of their string lables when they rotate.

-- -- LIB rc_linked_pic

This library provides two mixins, rc_linked_pic and rc_linked_static,
with facilities for drawing the same static or movable picture in
different windows. If the picture is movable its appearances are linked
so that if the picture moves (either dragged by mouse or under program
control) in one window it moves in all.

    See HELP RC_LINKED_PIC,  LIB RC_LINKED_PIC

The library includes:
 define :mixin rc_linked_static;
 define :mixin rc_linked_pic;

 define :method rc_add_containers(pic:rc_linked_static, windows);
 define :method rc_add_containers(pic:rc_linked_pic, windows);
    Make a list of window objects all containers of pic.

 define :method rc_remove_container(pic:rc_linked_pic, win_obj);
    Make win_obj no longer a container of pic

 define :method rc_add_container(pic:rc_linked_static, win_obj);
 define :method rc_add_container(pic:rc_linked_pic, win_obj);
    Make win_obj a container of pic

Modified versions of previous methods:
 define :method print_instance(pic:rc_linked_static);
 define :method print_instance(pic:rc_linked_pic);
 define :method rc_draw_linepic(pic:rc_linked_pic);
 define :method rc_draw_oldpic(pic:rc_linked_pic);
 define :method rc_undraw_linepic(pic:rc_linked_pic);

(If you have the SimAgent toolkit installed, compare this with
LIB sim_picagent)

-- -- LIB rc_mousepic (event handling primitives)

This core library is concerned with making pictures mouse and keyboard
sensitive. Defines all the default event handlers. See the section
above headed: How events are handled, and HELP RC_EVENTS

It presupposes LIB RC_WINDOW_OBJECT

See TEACH RC_LINEPIC,  HELP RC_LINEPIC/rc_mousepic

There is more information in the sections near the top of this file
on event handling. The procedure rc_mousepic described above is used to
make a window event sensitive.


-- -- . Creating events:

The following are user-definable procedures for handling specific
types of events by creating appropriate event records to go into
the events queue

-- -- -- . rc_do_button_actions

rc_do_button_actions(widget, item, data);
    Invoke the handler for mouse button up or down events

-- -- -- . rc_do_move_actions
rc_do_move_actions(widget, item, data);
    Invoke the handler for move or drag events.

-- -- -- . rc_do_mouse_actions
rc_do_mouse_actions(widget, item, data);
    This invokes handers for mouse entering or leaving window events.

-- -- -- . rc_do_keyboard_actions
rc_do_keyboard_actions(widget, item, data);
    Invoke handler for keypress events

-- -- -- . rc_handle_event

Used by the above to create event records

-- -- -- . rc_get_handler

rc_get_handler(obj, type, button) -> handler;
    Invoked by various sytem callback handlers.
    It gets the handler of the appropriate type from the
    object, usually, but not necessarily, inherited from the class.

    If it is a mouse button or drag event there will be a vector of
    handlers, one for each button, as defined in the rc_selectable
    mixin, where the vector can contain methods or method-names,
    or false.

    Otherwise the handler will be one handler, represented by a
    method or its name.

    If the handler is false then no action occurs.

-- -- -- More specific event handlers

The following user-definable procedures are packaged into event records,
along with event data. When the event is processed, the procedure
rc_get_handler will be used to get the final handler from the object in
question, a window object or a picture object.

-- -- -- . rc_system_button_down_callback
rc_system_button_down_callback(obj, x, y, modifiers, item, button);

-- -- -- . rc_system_button_up_callback
rc_system_button_up_callback(obj, x, y, modifiers, item, button);

-- -- -- . rc_system_move_callback
rc_system_move_callback(obj, x, y, modifiers, item, button);

-- -- -- . rc_system_drag_callback
rc_system_drag_callback(obj, x, y, modifiers, item, button);

-- -- -- . rc_system_entry_callback
rc_system_entry_callback(obj, x, y, modifiers, data, mode);

-- -- -- . rc_system_exit_callback
rc_system_exit_callback(obj, x, y, modifiers, data, mode);

-- -- -- . rc_system_keypress_callback
rc_system_keypress_callback(obj, x, y, modifiers, data, key);

-- -- LIB rc_opaque_mover

This file introduces two mixins and a collection of associated
utilities.

 define :mixin rc_opaque_movable; is rc_linepic_movable;
 define :mixin rc_opaque_rotatable; is rc_opaque_movable rc_rotatable;

 define :method rc_set_drawing_colour(pic:rc_opaque_movable, colour, window);
 define :method rc_draw_linepic(pic:rc_opaque_movable);
 define :method rc_draw_linepic(pic:rc_opaque_rotatable);
 define :method rc_draw_oldpic(pic:rc_opaque_movable);
 define :method rc_draw_oldpic(pic:rc_opaque_rotatable);
 define :method rc_undraw_linepic(pic:rc_opaque_movable);
 define :method rc_undraw_linepic(pic:rc_opaque_rotatable);

Instances of the mixins are movable or rotatable picture objects, which,
unlike direct instances of rc_linepic_movable and rc_linepic_rotatable,
can be told that they are on a uniformly coloured background. They can
then replace the backgroundw henever they move, overcoming some of the
problems described in HELP RCLIB_PROBLEMS

This is used in LIB rc_opaque_slider, and various other libraries
concerned with movable objects, e.g. the moving pointers in
LIB rc_constrained_pointer.

LIB rc_control_panel was changed in July 2000 to use opaque sliders by
default.

-- -- LIB rc_point

A library file defining a mouse-manipulable class of points, which
could be used to control other things. See HELP RC_POINT

Includes

 define :class rc_point;
 define rc_cons_point(x,y, radius) -> newpoint;
 define rc_new_live_point(x, y, radius, string) -> newpoint;
 define rc_new_live_point(x, y, radius, string, list) -> newpoint;
 define rc_new_live_point(x, y, colour, radius, string) -> newpoint;
 define rc_new_live_point(x, y, colour, radius, string, list) -> newpoint;
 define rc_kill_point(point);
 define :method rc_get_mouse_points(
        win_obj:rc_window_object, radius, pdr, stop_button);

See also rc_get_coords

-- -- LIB rc_poly
-- -- LIB rc_polydemo

Demonstration programs

The operation rc_poly, repeatedly draws a polyspiral, in response to
four numbers typed in by the user:

    Initial length
    Increment
    Angle to turn
    Number of sides

All but the last can be positive or negative, integers or decimals.

rc_polydemo is similar except that it provides more instruction and
comments. See details in LIB RC_POLYDEMO

These should later be moved to the rclib/demo library.

A related library is LIB RC_POLYPANEL, described below.

-- -- LIB rc_polyline

Defines a class of linked points joined by lines. The junctions can
be moved by means of the mouse and new points added with the mouse.
(Still under development 4 Apr 1997). For examples see the top of the
file
    LIB RC_POLYLINE

-- -- LIB rc_polypanel

Demonstration library:
This is a version of rc_polydemo with a graphical interface implemented
using LIB RC_CONTROL_PANEL and various other facilities including,
buttons sliders, message windows, and uses rc_scratchpad to allow a
picture to be saved before a new one is drawn.

-- -- LIB rc_pythagoras

This uses the procedure rc_transform_lines and other procedures
mentioned in connection with it, to demonstrate the purely graphical
Chinese proof of pythagoras' theorem dynamically, by moving squares and
triangles around.

To run it either do

    lib rc_pythagoras

or ENTER showlib rc_pythagoras followed by ENTER l1.

Either way instructions are printed out. An example command might be

    rc_pythagoras(90, 120, 60);

This will use a right angled triangle of base 90 and height 120 to
demonstrate the theorem with a delay of 60 100ths of a second between
steps. Use a smaller delay to speed up the process.

This demonstration was inspired in part by the Java-based demonstration
by Norman Foo at
    http://www.cse.unsw.edu.au/~norman/Pythag.html


-- -- LIB rc_scratchpad
(Based on suggestions from Brian Logan).

This defines facilities based on rc_scratch_window for doing old
rc_graphic things alongside new ones without clobbering window
objects. For examples see

    TEACH RCLIB_DEMO.P/rc_scratchpad
    LIB RC_SCRATCHPAD

See also the autoloadable rc_scratch_window

-- -- LIB rc_scrolltext

    Creates scrolling text panel displaying a vector of strings,
    with pointer on left, scroll bar on right and on bottom.
    Described in detail in HELP RC_SCROLLTEXT

    create_scroll_text(
        name, vec, container, xpos, ypos, rows, cols, fg, bg, font,
        swidth, scol, sblob, fcol, fwidth) -> obj;

This is Invoked by SCROLLTEXT fields in rc_control_panel
    Examples in
        TEACH POPCONTROL
        HELP  RC_SCROLLTEXT
        TEACH RCLIB_DEMO.P (including use of rc_display_strings)

Various methods are provided in the library.

Applications based on this are described in
        HELP  RC_SCROLLTEXT

including these (defined above):

    rc_getfile(x, y, filter, rows, cols, font) -> selection;

    rc_browse_files
        (x, y, path, filter, instruct, rows, cols, font, wident)
            -> panel;

    rc_testbrowser(x, y, file, filter, rows, font);

    rc_display_strings(
        x, y, strings, panel_fields, acceptor, reactor,
            rows, cols, scrollspecs, title) -> panel;

    rc_display_file(
        x, y, file, panel_fields, acceptor, reactor, rows, cols,
            scrollspecs, title) -> panel;

    rc_popup_strings(x, y, list, strings, rows, cols, font) -> selection;

    rc_vedfileselect(300, 300, '9x15');

    ENTER browser <directory> <filter>
        I.e. ved_browser, described above.

-- -- LIB rc_swap_context (redundant)

LIB RC_SWAP_CONTEXT, produced by David Young at Sussex, extends the
facilities provided by LIB RC_CONTEXT (see HELP RC_GRAPHIC/RC_CONTEXT),
by providing a simple mechanism to switch between contexts.

However, this is now redundant in the context of LIB RC_WINDOW_OBJECT

-- -- LIB rc_text_input

LIB * RC_TEXT_INPUT
    uses the mechanisms in LIB * RC_MOUSEPIC extended by
    LIB * RC_INTERPRET_KEY to create text input boxes, which
    can be used to return strings or numbers or other things.

    See HELP * RC_TEXT_INPUT,

    See also LIB * RC_INTERPRET_KEY

Supported by rc_control_panel.

-- -- . rc_handle_text_input

rc_handle_text_input(pic:rc_text_input, x, y, modifier, key);

This re-definable method determines the reactions of a text input
picture object or a number input picture object to various key
sequences.

-- -- . List of facilities in LIB * RC_TEXT_INPUT
As of 12 Sep 2002
 define vars rc_text_input_disabled(key, modifier);
 define :mixin vars rc_text_input;
 define :mixin vars rc_number_input; is rc_text_input;
 define constant transform_places(num, places)->num;
 define :method prepare_for_printing(num, pic:rc_number_input) -> num;
 define :method updaterof rc_informant_value(newval, pic:rc_text_input);
 define :method updaterof rc_informant_value(val, pic:rc_number_input);
 define :method rc_text_value(pic:rc_text_input) -> val;
 define :method updaterof rc_text_value(newval, pic:rc_text_input);
 define :method constant consolidate_or_activate(pic:rc_text_input);
 define :method rc_button_1_down(pic:rc_text_input, x, y, modifiers);
 define :method print_instance(pic:rc_text_input);
 define :method constant consolidate_or_activate(pic:rc_number_input);
 define :method print_instance(pic:rc_number_input);
 define rc_convert_number_in(number) -> string;
 define rc_convert_number_out(string) -> number;
 define rc_check_number_format(string) -> boole;
 define :method rc_text_altered(pic:rc_text_input, val);
 define :method rc_text_altered(pic:rc_number_input, val);
 define constant rc_increment_pointer(num, pic, string);
 define constant rc_places_ok(pic, string, p, key) -> boole;
 define :method rc_handle_text_input(pic:rc_text_input, x, y, modifier, key);
 define :method rc_text_font (pic:rc_text_input) -> font;
 define constant update_font_specs(pic);
 define :method updaterof rc_text_font(font, pic:rc_text_input);
 define :method prepare_for_printing(string, pic:rc_text_input) -> string;
 define :method rc_DRAW_TEXT_INPUT(pic:rc_text_input);
 define :method rc_SHOW_TEXT_LABEL(pic:rc_text_input);
 define -- Class definitions and creation procedures
 define :class vars rc_text_button; is rc_text_input;
 define :class vars rc_number_button; is rc_number_input;
 define vars rc_textin_field_abbreviations =
 define create_text_input_field(x, y, width, height, content, extendable, font, creator) -> field;
 define create_input_field(x, y, width, height, content, extendable, font, proc) -> field;

-- -- LIB rc_window_object

This core library provides facilities for creating objects associated
with graphical windows. They can be moved, hidden, exposed, etc.
The basic procedure for creating such window objects is

    rc_new_window_object

described in more detail below.

LIB RC_WINDOW_OBJECT redefines two of the rc_graphic procedures for
creating windows, rc_start and rc_new_window. These now use
rc_new_window_object to produce composite widgets which can contain
sub-windows (which was not possible in the basic RC_GRAPHIC library, nor
in early versions of the RCLIB package).

These two procedures (rc_start and rc_new_window) can be made to
produce their previous behaviour when called by a procedure if the name
of that procedure is in the list use_rc_graphic_versions, described
below, in the section on global variables.

Different windows may be current at different times. There are examples
in
    HELP  RC_BUTTONS
    HELP  RC_TRANSFER_WINDOW_CONTENTS
    TEACH RCLIB_DEMO.P
    TEACH RC_LINEPIC
    TEACH RC_ASYNC_DEMO

    LIB RC_BLOCKS
    LIB RC_POLYPANEL

and ALSO some of the demonstrations provided in the Sim_agent toolkit,
including the sim_picagent and sim_harness libraries included in that
toolkit.

The class rc_window_object, and the procedure rc_new_window_object, are
used by rc_control_panel and many other libraries, including the rcmenu
package (available separately from RCLIB).

-- -- . global variables in rc_window_object and rc_mousepic
There are many global variables connected with these libraries, and
defined below in the section on global variables, including:

    rc_current_picture_object
    rc_active_picture_object
    rc_active_window_object
    rc_current_window_object
    rc_window (as in LIB rc_graphic).

These are all concerned with determining which window object or picture
object is currently active, etc.


SETWINDOW, a syntax word that can be used to assign to
    rc_current_window_object

-- -- . :class rc_window_object

This class is provided for creating multiple instances of the rc_graphic
window type, some of which may be mouse or keyboard sensitive. For
details see LIB RC_WINDOW_OBJECT/':class rc_window_object'

The slot rc_widget holds the graphical widget which would correspond to
rc_window in the rc_graphic package.

Tutorial introductions to the use of instances of this class can be
found in
    TEACH RCLIB_DEMO
    TEACH RC_LINEPIC
    HELP RC_BUTTONS
    HELP RC_LINKED_PIC

-- -- . rc_new_window_object

Window objects are created using this procedure. It can be invoked in
several formats, including provision of a new class procedure so that it
creates an instance of a subclass of rc_window_object instead of an
instance of rc_window_object.

The basic format is:

    rc_new_window_object(xloc, yloc, width, height, setframe);

Either or both of the xloc and yloc arguments may be false, in which
case the previous value is used offset by the appropriate one of:

    rc_window_x_offset (default 20)
    rc_window_y_offset (default 20)

-- -- -- additional formats:

It also allows the following formats, with one, two, three, or four
optional extra arguments, in any order: the word "hidden", a string for
the title, a container which is another instance of rc_window-object,
and finally a creator procedure. newXXX, e.g. allowing formats like
these:

    rc_new_window_object(xloc, yloc, width, height, frame, "hidden");
    rc_new_window_object(xloc, yloc, width, height, frame, string);
    rc_new_window_object(xloc, yloc, width, height, frame, string, "hidden");
    rc_new_window_object(xloc, yloc, width, height, frame, "hidden", string);
    rc_new_window_object(xloc, yloc, width, height, frame, container);
    rc_new_window_object(xloc, yloc, width, height, frame, string, newXXX);
    etc.

-- -- -- The container argument
The container argument can be added to any of those forms. If present,
container is a window object (instance of rc_window_object), in which
case x, y specify location within the container. If the container is
given,

-- -- -- The location arguments
the xloc, yloc arguments instead of being numbers can be words, e.g.
    xloc can be one of "left" "middle" "right" "abut"
    yloc can be one of "top" "middle" "bottom" "abut"

-- -- -- The creator procedure
In addition a forth optional extra argument can be a newXXX procedure
(before or after the other optional arguments). If you use objectclass
to define a class XXX then it automatically creates a procedure newXXX
which returns an instance of the class with default values for its
slots. If you wish to create a window that is an instance of a subclass
of rc_window_object, use its associated 'new' procedure.
    (See REF objectclass/'class new' for further details)

The newXXX procedure, if provided, creates the desired type of
window_object. The default is the procedure newrc_window_object. See
HELP RC_BUTTONS for an example, using newrc_button_window.

-- -- -- The "hidden" argument

If the word "hidden" occurs the new window object is created without
being made visible, but can be shown later using rc_show_window. In
fact, the widget is not created until then.

-- -- -- The string (window title) argument

If the string argument is provided then that is used to give the window
and its icon a title. Otherwise it gets the default title 'Xgraphic'.

-- -- -- The setframe argument

The setframe argument can be false, true, or a vector of either 4 or 7
elements, used to set the coordinate frame for the window (4 numbers)
and optionally the turtle location and heading.

If the setframe argument is false, the coordinate frame of the new
window is determined by this user-definable procedure which must
produce 12 results

    rc_set_window_defaults(x, y, width, height) ->
        (rc_xorigin,  rc_yorigin,   rc_xscale, rc_yscale,
            rc_xposition, rc_yposition, rc_heading,
            rc_clipping, rc_xmin, rc_ymin, rc_xmax, rc_ymax);

If the setframe argument is true a "standard" default frame is used , as
described in
    HELP RC_GRAPHIC/rc_new_window

This default frame has its origin at the centre of the picture, with
X increasing to the right and Y upwards.

If the setframe argument is a vector it should have either 4 or 7 items.
If the number is 4, then the elements are assigned as follows

    ->(rc_xorigin, rc_yorigin, rc_xscale, rc_yscale)

If the number is 7, then the elements are assigned as follows, with
three extra arguments suitable for the "turtle" graphic commands
described in TEACH RC_GRAPHIC

    -> (rc_xorigin, rc_yorigin, rc_xscale, rc_yscale,
                rc_xposition, rc_yposition, rc_heading)

The following defaults are given to
    rc_clipping, rc_xmin, rc_ymin, rc_xmax, rc_ymax
        false,   0,       0,       width,   height

-- -- -- The result of rc_new_window_object

There is a new class of window objects in LIB RC_BUTTONS, illustrating
the above.

Window objects created by rc_new_window_object can be moved, can have
their width or height changed, can be hidden and redisplayed, and can be
destroyed using this method

    rc_kill_window_object(win_obj:rc_window_object);

See further details in HELP RC_CONTROL_PANEL

-- -- . :mixin rc_selectable
-- -- . :mixin rc_keysensitive

Instances of these mixins may be accessible via the mouse or keyboard in
an rc_window_object instance. The instances known to the window object
are held in the slot rc_window_contents.

See HELP RC_EVENTS for details of event handling.

-- -- . :method rc_mousexyin(win_obj:rc_window_object, x, y) -> (x, y) ;

define :method rc_mousexyin(win_obj:rc_window_object, x, y) (x, y);
This is defined in LIB rc_mousepic, and replaces the old rc_graphic
version.

-- -- . :method rc_transxyin_in

This replaces rc_transxyin in the context of rc_window_object

define :method rc_transxyin_in(w:rc_window_object, x, y) -> (x, y);
    dlocal rc_current_window_object = w;
        rc_mousexyin(w, x,y) -> (x,y)
enddefine;


-- -- . Methods and procedures associated with rc_window_objects

There are several types of event handling methods, along with
methods and procedures for accessing or altering the location or size of
a window object, or hiding it or exposing it, or accessing or changing
some of its contents.

Here are some of them, defined in
    LIB RC_WINDOW_OBJECT

WARNING: the contents of this help file can get out of date: check the
library file to get a complete list.

 define :method rc_window_frame(win_obj:rc_window_object) -> vec;
 define :method updaterof rc_window_frame(win_obj:rc_window_object);

    Returns (or updates) the 12 element vector containing the four
    numbers that are in rc_window_origin(win_obj) and several
    others.

    The four numbers in the rc_window_origin vector hold the main
    rc_graphic coordinate frame specification for the window object,
    i.e.
        rc_xorigin, rc_yorigin, rc_xscale, rc_yscale

    The additional elements in the rc_window_frame vector are

        ;;; turtle variables
        rc_xposition, rc_yposition, rc_heading,

        ;;; clipping variables
        rc_clipping, rc_xmin, rc_ymin, rc_xmax, rc_ymax

    The access procedure first updates the contents of the vector,
    obtained from rc_window_origin(win_obj).

    The vector in rc_window_origin can be thought of as a useful cache
    for the first for elements in the rc_window_frame vector.


 define :method rc_window_title(win_obj:rc_window_object) -> string;
 define :method updaterof rc_window_title(win_obj:rc_window_object);

    Access or update the title of the window obejct.


 define :method rc_screen_coords(win_obj:rc_window_object) /* -> (x, y, w, h) */;
 define :method updaterof rc_screen_coords(x, y, w, h, win_obj:rc_window_object);
    Returns or updates location width and height of win_obj. If any of
    x, y, w, h is false, the updater does not update the slots.

 define :method rc_window_xyorigin(win_obj:rc_window_object) -> (x, y);
    Returns the coordinates of the RC_GRAPHIC origin of the window
    object.

 define :method rc_window_location(win_obj:rc_window_object) -> (x, y, w, h);
 define :method updaterof rc_window_location(x, y, w, h, win_obj:rc_window_object);
 define rc_fix_window_location(win_obj);
 define :method print_instance(win_obj:rc_window_object);


 define rc_get_current_globals(window);
 define rc_islive_window_object(obj) -> boole;
    Defined above

 define rc_save_window_object(win_obj);
 define :method rc_set_window_globals(win_obj:rc_window_object);
 define rc_set_window_defaults(x, y, width, height) /* -> 12 results */;
    Defined above
 define XptNewPanel(name, size, args, class) -> (widget, composite, shell);
 define xt_new_panel(string, xsize, ysize, xloc, yloc) -> (widget,composite,shell);
 define xt_new_window(string, xsize, ysize, xloc, yloc) -> widget;

 define :method rc_realize_window_object(win_obj:rc_window_object);
 define rc_new_window_object(x, y, width, height, setframe) -> win_obj;
    Defined above

 define rc_new_window(width, height, xloc, yloc, setframe);
 define rc_clear_window();
    Defined above
 define rc_start();
    Redefined from RC_GRAPHIC version for use with rc_window_object

 define: method rc_map_window_object(win_obj:rc_window_object);
 define: method rc_unmap_window_object(win_obj:rc_window_object);
 define :method rc_kill_window_object(win_obj:rc_window_object);
 define rc_destroy();
    Defined above

 define -- Showing and hiding window objects
 define :method rc_show_window(win_obj:rc_window_object);
 define :method rc_hide_window(win_obj:rc_window_object);
 define :method rc_raise_window(win_obj:rc_window_object);

 define active rc_current_window_object /* -> win_obj */;
 define updaterof active rc_current_window_object(win_obj);

    Defined above

 define -- simulate some rc_linepic methods
    (make methods that work for picture objets work for window objects
    either on the main screen or inside other window objects).

 define :method rc_graphic_frame(w:rc_window_object) -> (x, y, xscale, yscale);
 define :method rc_transxyout_in(w:rc_window_object, x, y) -> (x, y);
 define :method rc_transxyin_in(w:rc_window_object, x, y) -> (x, y);
    Defined above

 define :method rc_container_xy(w:rc_window_object, x, y) -> (x, y);
 define :method rc_move_to(w:rc_window_object, x, y, visible);

 define :method rc_coords(w:rc_window_object) -> (x, y);
 define :method updaterof rc_coords(/*x, y,*/ w:rc_window_object);
    defined above

 define :method rc_move_by(w:rc_window_object, dx, dy, visible);

 define :method rc_picx(w:rc_window_object) -> x;
 define :method updaterof rc_picx(x, w:rc_window_object);
 define :method rc_picy(w:rc_window_object) -> y;
 define :method updaterof rc_picy(y, w:rc_window_object);

 define -- Re-drawing and clearing a window

 define :method rc_redraw_window_object(win_obj:rc_window_object);
    Redraws objects in the list rc_window_contents(win_obj) but in
    the reverse order, so that most recently active or added objects are
    drawn loast.
    This methodwas previously specified to take an optional extra
    boolean argument to determine whether the window should be cleared
    first. But optional arguments are not permitted for objectclass
    methods. So added global variable
            rc_clear_before_redraw  : default false

    This procedure sets the global variable rc_redrawing_window to
    win_obj when redrawing. Otherwise the variable is false. (It is
    used in LIB rc_linked_pic)

 define :method rc_clear_window_object(win_obj:rc_window_object);

There are additional methods used by system procedures in RCLIB

Event handlers for windows:
See also the event handling methods defined for picture objects in
LIB RC_MOUSEPIC

define :method rc_pictures_selected(win_obj:rc_window_object, x, y, findone) -> num;
define :method rc_button_1_down(pic:rc_window_object, x, y, modifiers);
define :method rc_button_1_drag(pic:rc_window_object, x, y, modifiers);
define :method rc_button_2_drag(pic:rc_window_object, x, y, modifiers);
define :method rc_button_3_drag(pic:rc_window_object, x, y, modifiers);

define :method rc_add_pic_to_window(pic:rc_selectable, win_obj:rc_window_object, atfront);
    Described above
define :method rc_remove_pic_from_window(pic:rc_selectable, win_obj:rc_window_object);
    Described above

-- -- LIB rc_blocks and LIB rc_hand

    $poplocal/local/rclib/lib/rc_blocks.p
    $poplocal/local/rclib/lib/rc_hand.p

These two files provide a simple simulated robot which moves coloured
blocks around in response to English commands and answers simple
questions about the blocks. (Compare TEACH MSBLOCKS, TEACH MSDEMO).
For instructions see TEACH RC_LINEPIC/rc_blocks

These should be moved to the rclib/demo/ directory. Perhaps they will
be one day.

To create a saved image in $poplocalbin, use the script

    $poplocal/local/rclib/mkgblocks

Edit if necessary to change the location. (This is pre-built at
Birmingham).

-- Global variables ---------------------------------------------------

Many of the the files define global variables that specify default
fillers for slots. Examples can be found in
    LIB rc_buttons
    LIB rc_control_panel
    LIB rc_slider

In some cases these are defined using the define :rc_defaults format.
(They all should be.)

These global variables are not listed here: there are too many of them.
If you wish to change some defaults of the appearances of buttons,
sliders, text_input panels, etc. look up the libraries and see whether
to modify slot values or global variables holding defaults.

There are additional global variables that are useful, including the
active variables

    rc_current_window_object,  rc_active_window_object

etc.

-- -- rc_active_picture_object

This global variable is set by the event handling procedures. Its value
is the last picture object (instance of rc_selectable) in which an event
was handled.

Compare rc_current_picture_object

-- -- rc_border_allowance rc_title_allowance

These two global variables hold an integer or false.

If rc_border_allowance holds an integer (e.g. 2) it is treated as an
estimate of the width of the border of windows.

If rc_title_allowance holds an integer (e.g. 23) it is treated as an
estimate of the height of the title bar of a window.

Both variables are set by the (inaccessible) procedure adjust_location
the first time it is called. Users may adjust them if required.


-- -- rc_active_window_object

This global variable is set by the event handling procedures. It refers
to the instance of rc_window_object in which the most recent event was
handled. The window is thus accessible when mouse, or keyboard events
occur, and immediately afterwards, e.g. in events handled via
rc_defer_apply

Compare rc_current_window_object

-- -- rc_charout_buffer
Default value 'output.p'

See LIB rc_mousepic/rc_charout_buffer

This defines where output should go if event handlers invoked from
inside Ved have to do some printing.

-- -- rc_clear_before_redraw
    Controls the behaviour of rc_redraw_window_object. The default is
    false. If true, the window is cleared before the contents of the
    window are redrawn.

-- -- rc_current_panel

The panel being constructed, or last panel constructed. Used in
LIB rc_control_panel

-- -- rc_current_panel_field;

the field currently being constructed

Used in LIB rc_control_panel


-- -- rc_current_picture_object

This global variable is set by the picture drawing procedures defined in
LIB rc_linepic

It can be checked to see whether a picture object is currently being
drawn or redrawn (e.g. if an event handler is about to draw or move it).

Compare rc_active_picture_object

-- -- rc_current_window_object

This is an active variable whose value should be false or an instance of
rc_window_object.

Assigning an instance of the class rc_window_object to the active
variable

    rc_current_window_object

automatically sets the rc_graphic global variables to correspond to that
object. Such an object can be made mouse and keyboard sensitive using
the procedure rc_mousepic.

By default if a window object has been made mouse sensitive the
mouse button 1 down method, when the CTRL key is depressed, makes the
current window the value of rc_current_window_object. However the value
is reset when the event has been handled. If an event handler is to
access the previous value it should be run via rc_defer_apply. This is
done by buttons using DEFER actions. (See HELP RC_BUTTONS/DEFER)

See also SETWINDOW, a syntax word that can be used to assign to
    rc_current_window_object

E.g.
    SETWINDOW win3


-- -- rc_fast_drag
Boolean with default value true

Controls whether dragging is done quickly by invoking the drag handler
less often.

See LIB rc_mousepic/rc_fast_drag

-- -- rc_inside_callback

Global variable: Normally false, but made true while a callback defined
in LIB * RC_MOUSEPIC is still running. Should be false when the pop-11
handler runs.

-- -- rc_fast_move
Boolean with default value true

Controls whether moving is done quickly by invoking the move handler
less often.

See LIB rc_mousepic/rc_fast_move

-- -- rc_in_event_handler

Boolean, default value false. When the main event handler is being
invoked this variable is set true. Thus it will not be re-invoked
while already active.

Used in LIB rc_mousepic in the procedure rc_process_event_queue which
runs items in the event queue set up by the RCLIB event handlers.


-- -- rc_no_more_handlers

This global variable is set false when the event handler starts to run a
list of methods or procedures found in an event handler slot. If one of
them sets the variable rc_no_more_handlers true, then no further
handlers are activated. For full details see
    LIB rc_mousepic/rc_no_more_handlers


-- -- rc_pause_draw
rc_pause_draw
    Value is a boolean or a string, default false.

Make this non-false to cause all drawing done by rc_move_to rc_move_by
or rotate methods, to pause until a key is pressed.

If it is a string, the string is printed out when pausing.

See LIB rc_linepic/rc_pause_draw


-- -- rc_prev_active_window_object
Holds a window object or false

Previous value of rc_active_window_object
See LIB rc_mousepic/rc_prev_active_window_object

-- -- rc_prev_active_picture_object
Holds a picture object or false
Previous value of rc_active_picture_object

See LIB rc_mousepic/rc_prev_active_picture_object

-- -- rc_redrawing_window

Default value false.

The value is set to the window being redrawn by the method

    rc_redraw_window_object(win_obj:rc_window_object);

So that no attempt will be made to redraw it or parts of it while the
window is being redrawn.


-- -- rc_selected_window_objects
This a list, default value []

It is used by the methods
    rc_make_selected(pic:rc_window_object, x, y, modifiers);
    rc_make_unselected(pic:rc_window_object, x, y, modifiers);

See LIB rc_mousepic/rc_selected_window_objects

The default action when pressing mouse button 3 in a window is to add
that window to the list or remove it if already in it. This is useful
for killing or hiding a collection of windows.

-- -- rc_selected_picture_objects

This a list, default value []

It is used by the methods
    rc_make_selected(pic:rc_selectable, x, y, modifiers);
    rc_make_unselected(pic:rc_selectable, x, y, modifiers);

See LIB rc_mousepic/rc_selected_picture_objects

The default action when pressing mouse button 3 in a picture object
is to add that window to the list or remove it if it was already there.
Selecting a collection of window objects.

-- -- rc_moving_picture_object
A picture object or false. Default value is false;
used by rc_move_to to indicate which object is currently being moved.
If invoked by an event handler to move the same object it will abort.

See LIB rc_mousepic/rc_moving_picture_object

-- -- rc_sole_active_widget
    (default value is false)

This can have a widget assigned to it. The result is that no events will
be handled in any other widget. This is done by rc_message_wait and
rc_popup_query. It can be used to disable all event processing until a
particular query or notice has been dealt with.

-- -- rc_transparent_objects

If this is set false, the default, then an event will be handled by the
first picture object whose sensitive region includes the mouse. If that
object is not of a type for which the relevant method is defined an
error will occur. If it is set true the object will be ignored and the
event will fall through to the next picture object, or the window
object.

For more on this see HELP RC_EVENTS/rc_transparent_objects

-- -- rc_window_sync_time

rc_window_sync_time
    Integer value, default 5

This integer represents hundredths of a second delay after calls of
XptSyncDisplay(XptDefaultDisplay) when invoked via the procedure
rc_window_sync, defined below.

For a slow display accessed over the network a larger delay may be
needed.

Compare rc_sync_delay_time

-- -- rc_window_x_offset, rc_window_y_offset

These variables hold integer values, both have the default 20.

If rc_new_window_object is given false arguments for x and y then it
uses previous values plus these offsets. This can be used to provide
"staggered" windows.


-- -- rc_window_object_of (property)

This variable holds a property, created by newproperty.

It associates an instance of rc_window_object with each graphic window
which is created by rc_new_window_object. When a window object is made
current, the graphic window is assigned to rc_window, for consistency
with the facilities in LIB rc_graphic. So to find out whether there is
an associated window object examine the value of
    rc_window_object_of(rc_window)

If it is false there is no associated window object. If non false it
should be an instance of rc_window_object.


-- -- rc_select_distance

This variable holds the vector {-10 -10 10 10} as its default value,
representing a 20x20 square as the region of sensitivity of a picture
object.

It provides the default value for the rc_mouse_limit slot in
instances of the mixin rc_selectable defined in LIB rc_window_object

The value can be a number representing a distance, a four element
vector as above, or a procedure or method taking five arguments
    piclim(x, y, picx, picy, pic);
the current mouse x and y locations, the location of the picture object
pic in the window, and the picture object itself.

-- -- rc_sync_delay_time

If an integer determines delay time for the procedure
rc_sync_display described above.

-- -- use_rc_graphic_versions

This is a list, default value []

If a word naming a procedure is added to that list, then whenever the
versions of rc_start and rc_new_window defined in LIB rc_window_object
are invoked, the original versions of those procedures (as defined in
LIB rc_graphic) will be invoked. E.g. to make it use its old behaviour
when invoked by a procedure called display_image then do

  [^display_image ^^use_rc_graphic_versions] -> use_rc_graphic_versions;



-- Additional files

-- -- TEACH RC_DEMO, TEACH FACES

TEACH RC_DEMO
Gives a short demonstration of some RC_GRAPHIC capabilities

TEACH FACES
Gives a more general introduction to the drawing facilities in
rc_graphic, some of which are extended in rclib. Does not use
picture objects or associated methods. Shows how to draw happy and
sad faces using coloured blobs.

-- -- TEACH RCLIB_DEMO.P

Gives a short demonstration of some of the RCLIB facilities extending
the RC_GRAPHIC facilities, including pop-up windows, menus, static and
moving picture objects, control_panels, and many more.

-- -- TEACH RC_LINEPIC

Gives a more detailed tutorial introduction to the basic facilities for
creating picture objects which may be static, movable, rotatable,
opaque movable, selectable, keyboard sensitive, etc.

HELP RC_LINEPIC, is more systematic and complete.

-- -- TEACH RC_OPAQUE_MOVER

Show how the mixin rc_opaque_movable and its derivatives can be used to
create and manipulate movable objects for which it is known that the
background will always be uniform, so that it is not necessary to
use the xor or equiv drawing methods used by default.
See HELP RCLIB_PROBLEMS


-- -- TEACH RC_MOUSEPIC

Extends TEACH RC_LINEPIC with more detailed information concerning
mouse and button event handlers and how to use or modify them.

-- -- TEACH RC_LINEPIC.DEMO.P

This possibly redundant, rather messy and provisional teach file
provides some details and code that were originally in
    TEACH RC_LINEPIC


-- -- TEACH RC_GRAPHPLOT

Introduces the package of facilities developed by David Young at Sussex
University for drawing graphs, histograms, etc. of various kinds.

-- -- TEACH RC_CONTROL_PANEL

A tutorial introduction to rc_control_panel, the very powerful facility
for creating control panels with buttons, sliders, text and number input
fields, and other sorts of contents, all automatically formatted on the
basis of a declarative description of the contents of the panel. One
panel can contain another.

See also HELP RC_CONTROL_PANEL, for more detailed information.

-- -- TEACH POPCONTROL

Shows how to use rc_control_panel to create a panel controlling various
global variables used by Pop-11 and Ved. It is easily generalised.

-- -- TEACH RC_ASYNC_DEMO

This teach file shows how to create a panel which can launch a program
which is then controlled asynchronously by buttons on the first panel
and by other panels.

-- -- TEACH RC_BUTTONS
Merely points to HELP RC_BUTTONS, which has extensive examples.

-- -- TEACH RC_CONSTRAINED_PANEL

This file presents a tutorial on using rc_control_panel with fields
constrained by "constrainer" procedures and linked by "reactor"
procedures.

It introduces the use of rc_control_panel with fields linked to Pop-11
variables, then to fields with constrainers which limit their possible
values, then to fields with reactors which can cause changes to be
propagated.

It presupposes that you already know about the basic functionality of
rc_control_panel.

-- -- TEACH RC_CONSTRAINED_POINTER

This shows how to create a type of dial with a movable pointer which can
move either under program control, or under mouse control.

-- -- TEACH RC_DIAL

A higher level interface to rc_constrained_pointer, for creating dials.

This shows how to create a type of dial with a movable pointer which can
move either under program control, or under mouse control.


-- -- TEACH rc_intro
A slightly out of date tutorial overview for rc_graphic and rclib

-- -- TEACH rc_linepic.extra
A redundant precursor to parts of TEACH RC_LINEPIC
Will probably be removed.


-- -- TEACH RCLIBTEACHINDEX

Should have a complete list of teach files, depending on when
    $popcom/makeindexes
was last run, or, at Birmingham
    $poplocal/local/com/mklocalindex


-- Demonstration libraries --------------------------------------------

In the directory $poplocal/local/rclib/demo/ new demonstration programs
will be added as they are developed. These are useful for testing the
main libraries as well as demonstrating their potential. A first draft
control panel demo with automatic formatting facilities is in the
control.panel.p file in the demo/directory. It will be improved later.

-- -- rc_ant_demo

    ENTER rcdemo rc_ant_demo.p
    ENTER l1
or
    load $poplocal/local/rclib/demo/rc_ant_demo.p

This file gives a demonstration of lots of moving "ants", with a control
panel that can increase or decrease the number of ants. When the ants
meet they move in a partly random way that suggests something like
conversational interaction, not to be taken seriously.

-- -- painting_demo

    Shows how to use these facilities to produce a "toy" interactive
painting kit, with a row of brushes of various kinds and a column of
paint pots. The location of this file is
    $poplocal/local/rclib/demo/painting_demo.p

Try
    ENTER rcdemo painting_demo
    ENTER l1
then to Pop-11
    painting_go();

-- -- rcblocks demo
Described in an earlier section.

-- -- rc_polypanel

The command
    uses rclib
    ENTER showlib rc_polypanel

reads in a library file which demonstrates the use of rc_control_panel
with sliders, action buttons, number input panels, radio buttons, etc.,
to build an interactive graphical tool for making pictures using the
"polyspiral" technique.

-- -- rc_neural

Riccardo Poli has produced a demonstration of neural net learning using
rc_control_panel. To explore it do

    uses rclib

then
    ENTER rcdemo rc_neural

Compile the file (ENTER l1), then look at the examples at the end of the
file. The procedure train_net is given a list of lists specifying a
truth-table of some kind. It builds a neural net and trains it, and sets
up a control panel which can be used to experiment with the net.

-- -- Demonstrations based on sim_agent

Other demonstrations will be available in the SIM_AGENT library. See

    http://www.cs.bham.ac.uk/~axs/cog_affect/sim_agent.html
and

    http://www.cs.bham.ac.uk/research/poplog/newkit/sim
    ftp://ftp.cs.bham.ac.uk/pub/dist/poplog/newkit/sim

-- -- Other demo libraries

See also rc_poly and rc_polydemo, rc_polypanel


-- Notes on recent developments ---------------------------------------

These notes will change from time to time. They summarise recent
changes reported in more detail in the HELP rclib_news file.

Often there are changes not yet recorded in detail in this file, but
briefly recorded in HELP RCLIB_NEWS.

****NOTE (Aug-Sep 2002)****

Major changes, to be recorded in HELP * RCLIB_NEWS

(Facilities for morphing sets of lines added, Nov 2000).
(Some important sections re-written, e.g. on event
    handling 3 Sept 2000. Also added HELP RC_EVENTS)
(Several new facilities added in August 2000,
    including VED interface utilities, and dials with
    moving pointers. See TEACH RC_DIAL)


****NOTE (10 Jul 2000)****

"Opaque" movable objects introduced: they do not use XOR or EQUIV
for drawing. However they work only on uniform backgrounds.

HELP RC_SLIDER now explains opaque sliders.

This file (HELP RCLIB) has had major revisions.

The new mixin rc_rotatable_picsonly makes it possible to define a
class of rotatable objects whose associated strings are not
rotated. This allows a rotating picture to keep its label(s) in the
same place.

See the following new or changed libraries:

    LIB rc_control_panel.p
        changed to use a new format for scrolltext panels, and to
        use opaque sliders by default

    LIB rc_scrolltext.p
        New format using opaque sliders rather than panel sliders

    LIB rc_foreground.p
        New global variable rc_foreground_changeable. If it is false
        then attempts to change foreground do nothing. Used by
        opaque movers.


****NOTE (February - March 2000)****
Event handlers can now be lists of methods (or procedures),
or their names.

The updater of rc_foreground has been extended to allow false as a
colour, meaning use the current default, or "background" meaning use the
current background to become the foreground (useful for drawing
"holes"). This feature is available for the colour argument of several
procedures that locally alter rc_foreground, e.g.

    rc_draw_bar, rc_draw_blob

Two procedures have been changed to conform to this convention:
    rc_drawline_absolute, rc_drawline_relative
    (previously they used false instead of "background" and true
    instead of false for current foreground).

rc_make_current_window has been added to allow an action button to set
a window to be rc_current_window_object, using rc_defer_apply
]

****NOTE (October 1999)***

Following the introduction of the RCMENU package in August/September
1999, the problem of compatibility between RCLIB mechanisms and the
original RC_GRAPHIC facilities described in TEACH RC_GRAPHIC and
HELP RC_GRAPHIC became acute.

A solution was devised and implemented, which is described in

    HELP RCLIB_COMPATIBILITY

Please read this if you are familiar with rc_graphic, and rc_graphplot,
and intend to use some of the examples in its teach and help files.

Additions August/Sept 1999

  Converted the old Pop-11 "menu" package (Recursive Hypermenus) which
  used to use Propsheet (see REF PROPSHEET), and no longer requires it.

  This means that the menu system is now completely independent of motif
  and can be used with linux poplog even if motif is not available. The
  new version is called "rcmenu" instead of "menu", and, is normally
  available via
      ftp://ftp.cs.bham.ac.uk/pub/dist/poplog/rcmenu.tar.gz
      http://www.cs.bham.ac.uk/research/poplog/rcmenu.tar.gz

  If installed properly it is made "active" by the command
      uses rcmenu

  This command makes both the menus and rclib available.

Additions in April and May 1999:

  Changed rc_new_window_object, rc_control_panel and procedures based on
  them so as to allow an extra optional "container" argument which is a
  window_object, in which case the new one is placed within it. Also
  allowed "symbolic" versions of "x" and "y" arguments, e.g. "left",
  "middle" "right" or "top" "middle" "bottom"



--- $usepop/pop/packages/rclib/help/rclib
--- Copyright University of Birmingham 2006. All rights reserved. ------
