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 <ENTER> 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  <false> 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    <false>   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  <false> to  this
        variable.


poplog_ui_enabled                                             [variable]
        Setting  this  variable  <false>  (e.g.  in  your  init.p,  etc)
        prevents pop_ui_setup  from  ever doing  anything.  Its  default
        value is <true>.



-----------------------
2  Poplog Control Panel
-----------------------

If  pop_ui_setup_done  is  non-<false>  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
        <false> 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 (<true>  = sensitive,  <false> =
        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 <false>. The first  time
        the window is  displayed, a value  of <false> 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
        <undef> will cause  the search_index to  default to <true>,  and
        after that, the value will not be changed.

        ref_widget is a widget  id of the help  tool's parent widget  or
        <false>. 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 <false>.  The first time the  window
        is displayed, a value of  <false> will display the library  list
        for the current subsystem. ref_widget is a widget id of the help
        tool's parent widget or <false>. 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  <false>  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 <false> for  the
            parent pops up the  standard dialog used  by the UI  control
            panel.

        title
            The dialog box  title: a  string, or <false>  for a  default
            title.

        label
            The label to  be displayed on  the OK button:  a string,  or
            <false>  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
            <false> for  a default  directory. The  dialog displays  the
            files in this directory.

        pattern
            The initial filter for file-selection: a string, or  <false>
            for a default pattern. The dialog only displays files  which
            match this pattern.

        file
            The initial selection: a string, or <false> 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:

                <true>
                    Allows the user to select a non-existent file

                <false>
                    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  <false>
        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
        <false>.


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 <false>.



---------------
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 <true> 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 <false>. 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 <true> 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 <false>.


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  <true>,
        otherwise the text is left  aligned. ref_widget is <false>  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.
