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 -- -- 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 ; 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 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] 0] silly([1], [2], [3], true) => ** [[1] [2] [3] 0] silly([1], [2], [3], 99) => ** [[1] [2] [3] 99] silly([1], [2], [3], true, 99) => ** [[1] [2] [3] 99] silly([1], [2], [3], 99, true) => ** [[1] [2] [3] 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 [] or [ ] 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 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( ) -> result; This is used to get information from a panel created by rc_control_panel is a list of labels or special keywords. It can be [] returns a panel field [all_fields] returns a list of all the fields in the panel [ ] returns an item in a panel field [ all_items] returns a list of items in a panel field [ all_values] returns a list of informant_values of items in a panel field [ all_labels] returns a list of informant_labels of items in a panel field [ 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 [ 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 [ 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 [ 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( ) -> val val -> rc_panel_field_value( ) Returns or updates the value of an item in a panel field (where appropriate: may mishap in some cases, e.g. action buttons). is a list of labels It can be [ ] Setting a panel item: use the updater val -> rc_panel_field_value( ) is a list of labels or special keywords. It can be [ ] Update informant value of the relevant item with val [ 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 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 This is a syntax word which can be used as an abbreviation for -> 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 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 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. ------