REF POP_UI Julian Clinton, July 1991 Revised Robert Duncan, May 1995 COPYRIGHT University of Sussex 1995. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< POPLOG USER INTERFACE >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< PROCEDURES >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This file describes the procedures and variables associated with the Poplog X User Interface library, LIB * POPLOG_UI. CONTENTS - (Use g to access required sections) 1 User Interface Initialisation 2 Poplog Control Panel 3 Control Panel Compiler Buttons 4 Library and Help Tools 5 Options Dialogs 6 File Chooser Dialog 7 Other Popups 8 Associated Documentation -------------------------------- 1 User Interface Initialisation -------------------------------- When the POPLOG_UI library is loaded, it appends the procedure pop_ui_setup to the end of sysxsetup. This means that whenever sysxsetup is called (e.g. if Poplog is invoked with the "%x" option and assuming this has been included as part of the startup.psv saved image), the Poplog Control Panel will also be invoked. If you do not wish the Poplog Control Panel to be invoked, you can assign false to poplog_ui_enabled (e.g. in your init.p); this will prevent pop_ui_setup from doing anything. pop_ui_setup() [procedure] Called to startup the Poplog User Interface. If the variable poplog_ui_enabled is set to before this procedure is called, it does nothing. On the first call (with poplog_ui_enabled true), it calls pop_ui_popcontroltool to set up the interface tool, and then assigns true to the variable pop_ui_setup_done. Subsequent calls will do nothing unless is re-assigned to pop_ui_setup_done. pop_ui_setup_done [variable] This boolean variable indicates whether the Poplog user interface has been initialised by calling pop_ui_setup. The user can force another initialisation by assigning to this variable. poplog_ui_enabled [variable] Setting this variable (e.g. in your init.p, etc) prevents pop_ui_setup from ever doing anything. Its default value is . ----------------------- 2 Poplog Control Panel ----------------------- If pop_ui_setup_done is non- then pop_ui_setup calls this procedure to create the main control panel. pop_ui_popcontroltool(x, y) [procedure] Creates the Poplog control panel at the position given by the integers x,y. The widget is assigned to the variable pop_ui_control_panel. Note that if the panel has already been created then the existing panel is destroyed (using * XtDestroyWidget) and a new panel created. pop_ui_control_panel [variable] This holds the value of the Poplog control panel widget or if the panel has not been created. --------------------------------- 3 Control Panel Compiler Buttons --------------------------------- The top-level compiler section of the control panel allows the user to swap between any languages which have been loaded into the currently running Poplog. Mousing on one of the labels will change the top-level compiler to the selected language by calling switch_subsystem_to (see REF * SUBSYSTEM). Note that if the requested subsystem is not available then selecting a button will do nothing. These can be manipulated using the procedures and variable described below. subsystem_button_selectable(ss_name) -> bool [procedure] bool -> subsystem_button_selectable(ss_name) In access mode, returns whether the button associated with the subsystem name ss_name (a word) is sensitive to mouse events. In update mode, the procedure changes the sensitivity of the button according to the boolean value ( = sensitive, = insensitive). ss_name is a word describing one of the buttons (currently one of "pop11", "top", "prolog", "lisp" and "ml"). current_subsystem_button -> word [active variable] word -> current_subsystem_button In access mode, this returns the name of the button which is currently active (note that if the Prolog button is selected, the return value is "top"). In update mode, this will change the currently selected subsystem button to the button associated with word. ------------------------- 4 Library and Help Tools ------------------------- pop_ui_helptool(subject, subsystem_options, [procedure] searchfiletypes, search_index, ref_widget) -> widget Creates a help tool window and displays it. If subject is a string then this is displayed in the 'Subject:' text field. subsystem_options is either a list of names which specify which subsystems are to be searched for references (valid entries are "pop11", "prolog", "lisp" and "ml") or . The first time the window is displayed, a value of will set all the currently loaded subsystems active. searchfiletypes is can also be a list of words which give the types of file to be searched for (currently "help", "ref", "teach" or "doc"). search_index is a boolean flag which specifies whether the index files should be searched. When called the first time, a value of will cause the search_index to default to , and after that, the value will not be changed. ref_widget is a widget id of the help tool's parent widget or . Returns the help tool widget id. pop_ui_librarytool(name, subsystem, ref_widget) -> widget [procedure] Creates a library tool window and displays it. If name is a string then this is displayed in the 'Libraries:' text field. subsystem is a word specifying which libraries should be displayed for references or . The first time the window is displayed, a value of will display the library list for the current subsystem. ref_widget is a widget id of the help tool's parent widget or . Returns the library tool widget id. Sometimes a description will cause a number of library names to be displayed in the text field. Selecting the 'Show' option will only display the library whose name appears last in the text field. Selecting 'Compile' will compile all the libraries in the text field in the order in which the appear. Note that the 'Compile' button will not be set sensitive if the subsystem is not part of the currently running Poplog. ------------------ 5 Options Dialogs ------------------ An options dialog contains one or more options pages; only one of these pages can be displayed at a time, so those dialogs containing more than one page have an additional menu button for page selection. There may be several options dialogs in existence at any one time: the standard control panel offers various dialogs for controlling aspects of system behaviour, but new dialogs can be created, and additional pages added to the standard dialogs, using the procedure pop_ui_add_property. A particular options page is identified by its title, a 2-list of the form [dialog-name page-name] where both the dialog-name and the page-name must be strings. The dialog-name identifies a dialog box and the page-name denotes a particular page within that box. In the procedures described below, the title argument should be in this form, although for convenience only the dialog-name need be supplied (as a string) in which case the page-name defaults to the string 'General'. Options dialogs are created by LIB * PROPSHEET: an options dialog is a propsheet box containing one property sheet for each page and an additional sheet for the menu button which is hidden or exposed automatically depending on the number of pages. pop_ui_add_property(title, field_list, display) [procedure] pop_ui_add_property(title, field_list, display, save_p) Adds a new options page, or replaces an existing page, with the given title and propsheet field_list. The title is as above. If there is no existing options dialog with the name specified by title, a new one is created using *propsheet_new_box; if there is no existing page within that dialog with the name specified by title, or if the page exists but its current field list is not identical (==) to field_list, a new (replacement) page is created using *propsheet_new applied to field_list. If the display argument is non-false, the new or replacement page is made visible; this may involve popping up its containing dialog. save_p is an optional procedure used to save the page values such that they can be restored in a subsequent Poplog session. If present, save_p must have the form save_p(title, psheet) where title is as above and psheet is the property sheet created by the call to propsheet_new. The procedure will be called when the Save Options button is selected from the Options menu, but only if the sheet Apply button has been pressed since the last save. The mechanism by which values are saved and restored is application-dependent. pop_ui_remove_property(title, display) [procedure] Deletes the options page identified by title (as above); if the deleted page is the last one in its containing dialog, the dialog too is deleted. The display argument is ignored. pop_ui_show_property(title, parent) [procedure] Displays the options page identified by title (as above) popping up its containing dialog box if necessary. When a dialog is to be displayed for the first time, the parent argument can be a widget used as the dialog's parent widget, or to indicate a default parent; on subsequent calls, the parent argument is ignored. pop_ui_property_list -> list [active variable] A list of titles of the options pages currently available. ---------------------- 6 File Chooser Dialog ---------------------- pop_ui_choose_file(parent, title, label, directory, [procedure] pattern, file, flags) -> choice Prompts the user for a file name by popping up a file-selection dialog. The dialog is modal, so this call will effectively block until either a file is chosen, or the dialog is dismissed. The arguments are: parent The parent widget for the dialog. A new dialog is created for each distinct parent, but subsequent calls with the same parent will re-use the same dialog which will remember the selection from the previous time. Supplying for the parent pops up the standard dialog used by the UI control panel. title The dialog box title: a string, or for a default title. label The label to be displayed on the OK button: a string, or for a default label. Pressing the OK button dismisses the dialog and returns the currently-selected file. directory The initial directory for file-selection: a string, or for a default directory. The dialog displays the files in this directory. pattern The initial filter for file-selection: a string, or for a default pattern. The dialog only displays files which match this pattern. file The initial selection: a string, or for no default. If this is supplied, the user need only press the OK button to have file returned as the result. flags Miscellaneous flags controlling dialog behaviour. Currently this has only two documented values: Allows the user to select a non-existent file Forces the user to select an existing file The resulting choice will be a file name (a string) if the user pressed the OK button when the selection was valid, or if the dialog was otherwise dismissed without a selection being made. pop_ui_file_search_directory -> string [variable] string -> pop_ui_file_search_directory pop_ui_file_search_pattern -> string [variable] string -> pop_ui_file_search_pattern pop_ui_file_search_name -> string [variable] string -> pop_ui_file_search_name These provide the defaults for the directory, pattern and file arguments to pop_ui_choose_file for each new dialog created. If these are not set, or are set to the null string, the defaults are determined dynamically: for the directory, the default is the value of current_directory; for the pattern, the default is '*' <> pop_default_type i.e., a pattern matching program files of the current subsystem. There is no default for the initial file name. pop_ui_filetool(name, directory, pattern, label, [procedure] newfile, ref_widget) -> choice Obsolete file-selection dialog: use pop_ui_choose_file instead. This call is approximately equivalent to pop_ui_choose_file(ref_widget, 'Poplog: File Tool', label, directory, pattern, name, newfile) -> choice but all calls share the same dialog box. pop_ui_edittool(file, directory, pattern, ref_widget) [procedure] Implements the control panel Open File operation: calls pop_ui_choose_file to select a file name and calls Ved on the result. The arguments file, directory and pattern are as for pop_ui_choose_file; the argument ref_widget should always be . pop_ui_compiletool(file, directory, filter, ref_widget) [procedure] Implements the control panel Compile File operation: calls pop_ui_choose_file to select a file name and compiles the result using *subsystem_compile. The arguments file, directory and pattern are as for pop_ui_choose_file; the argument ref_widget should always be . --------------- 7 Other Popups --------------- pop_ui_information(info, center_text, [procedure] ref_widget) -> widget This pops up a window containing the string info and a 'Dismiss' button. If the boolean center_text is then text will be centrally aligned in the window, otherwise alignment will be to the left. The procedure returns the widget id of the window. ref_widget is a widget id of the information window's parent widget or . Returns the widget id. pop_ui_message(info, center_text, ref_widget) [procedure] This pops up a window containing the string info and an 'Okay' button. If the boolean center_text is then text will be centrally aligned in the window, otherwise alignment will be to the left. The procedure returns once the user has pressed the 'Okay' button and the window has been popped down. ref_widget is a widget id of the message window's emanate widget or . pop_ui_confirm(question, options, default, [procedure] center_text, ref_widget) -> selection Pops up a confirmation window displaying the prompt given by the string question. options is a list of strings or words to be used as labels for the buttons in the confirmation window. default is an integer giving the offset in the list of the button which is to be the default. center_text is a boolean flag which causes text to be justified centrally if set , otherwise the text is left aligned. ref_widget is or a widget id of the parent of the confirm widget. selection is an integer which represents the offset in the options list of the button which was pressed. --------------------------- 8 Associated Documentation --------------------------- HELP * POPLOG_UI The Poplog X User Interface library HELP * POP_UI_OVERVIEW Using the User Interface --- C.x/x/pop/ref/pop_ui --- Copyright University of Sussex 1996. All rights reserved.