HELP OVERVIEW Robert Duncan, July 1996 Using the Poplog X User Interface. CONTENTS - (Use g to access required sections) 1 The Poplog Control Panel 2 The Menu Bar 2.1 The File Menu ... The File Dialog ... The Library Tool 2.2 The Project Menu 2.3 The Options Menu ... File ... Store Management ... Ved ... Pop-11 2.4 The Help Menu ... The Help Tool 3 Notes for Experienced Users 3.1 X Resources 4 Related Information ----------------------------------------------------------------------- 1 The Poplog Control Panel ----------------------------------------------------------------------- The Poplog control panel provides your first entry point into Poplog. It should appear automatically whenever you run Poplog with the %x option to start up an X connection, or call sysxsetup from within a program. If you don't see the control panel, or would prefer never to see it again, refer to the section Notes for Experienced Users below. The title bar of the control panel window shows the Poplog version number: you should quote this if ever you have an enquiry about Poplog or need to report a problem. Choose the Customer Support option from the Help menu for details of how to do this. The top of the control panel window is spanned by a menu bar containing the buttons File Project Options Help These are described in detail below. Beneath the menu bar is a panel of buttons labelled with the standard subsystem names: Pop-11 Prolog Common Lisp Standard ML Use these buttons to choose the primary subsystem for your Poplog session: this determines the top-level compiler for the base window, the default search paths for documentation and library files, and the default file extension. Choose the Languages|Subsystems option from the Help menu for more details. You may find that some of the subsystem buttons are insensitive so that they don't respond to selection: this indicates that those subsystems have not yet been loaded into Poplog. Which subsystems are available initially depends on the command you used to enter Poplog, but you can load others interactively if you wish: the Subsystems help file explains how. Neither the menu bar nor the button panel has useful resizing behaviour, so you may find that your window manager will not allow you to resize the control panel, but you can position it on screen wherever it's most convenient for you. ----------------------------------------------------------------------- 2 The Menu Bar ----------------------------------------------------------------------- Many of the menu options call up functions from Poplog's XVed editor: choose the Editor|Overview option from the Help menu for an introduction to XVed or see TEACH * XVED. 2.1 The File Menu ------------------ Open... Opens an XVed window on a named file: this may be an existing file, or a new one that you want to create. Selecting this option pops up the Open File dialog box in which you can enter the file name: how to do this is described below. Once you have selected a file name, press the Open button to view that file or Cancel to cancel the operation and dismiss the dialog. Choosing this option is the same as running the XVed command openfile Compile... Compiles a named file which must already exist. Selecting this option pops up the Compile File dialog box in which you can enter the file name: the box is shared with the Open File operation, so details are remembered between the two. Press the dialog Compile button to compile the selected file: the appropriate language compiler will be determined from the file extension. Choosing this option is the same as running the XVed command compilefile Library... Displays the Library Tool described below. Choosing this option is the same as running the XVed command librarytool Interaction Opens an interactive (or ``immediate mode'') XVed window in which you can evaluate expressions directly: the language for the interaction is determined from the currently-selected subsystem button on the control panel. Choosing this option is the same as running the Ved command im Interactive buffers aren't normally marked as writeable by XVed: if you want to save a record of your interaction, you must first make the buffer writeable with the command set vedwriteable Save All Saves all XVed buffers marked as writeable which have been changed since the last save. If there are no such buffers, this option will be insensitive. Each named buffer will be written to its associated file: the previous version of the file will normally be saved as a backup. Each unnamed buffer will pop up a Save File dialog from which you can either choose a name under which to save the buffer, or cancel the save in which case that buffer will be left unwritten. Choosing this option is the same as running the Ved command w Exit Terminates your Poplog session. Selecting this option pops up a Confirm dialog box which allows you to choose whether or not you really want to exit: press the Exit button to leave Poplog or Cancel to carry on. If you have changed some XVed buffers and not saved their contents, a simple Exit will discard those changes; press the Save Files and Exit button to do a Save All before quitting. Closing the control panel from your window manager menu should provide an alternative means of leaving Poplog. ... The File Dialog -------------------- The file-chooser dialog is used by the Open File and Compile File options from the control panel File menu and by various options from the XVed buffer File menu (if present) to let you select a file name. While the dialog is up, you cannot otherwise interact with Poplog: if you don't want to choose a file immediately, press the Cancel button to dismiss the dialog and cancel the pending operation. To select a file, either type the file name directly into the text box provided, or use the mouse or keyboard to select a name from the list of files offered to you. The file list is initialised with files in the current directory. To change the display, select a directory name instead of a file name and press the Filter button: the list of files will change to show the files in that directory. The list of files is further constrained to those which match the specified Filter: this can be treated as a standard file pattern, using special characters such as '?' to match any character and '*' to match any sequence of characters. The filter is initialised to match program files of the primary subsystem, but you can change it to restrict or expand the list of files displayed: use the Filter button to redisplay the list if the filter is changed. Once you have selected a file, press the left-most button in the box -- labelled Open or Compile as appropriate -- to initiate the operation on that file. ... The Library Tool --------------------- The Library Tool provides easy access to a selection of Poplog source libraries and their associated documentation. Use the Language buttons to choose the subsystem you are interested in: this need not be the same as the primary subsystem selected on the control panel. Descriptions of some of the libraries supplied with that subsystem are displayed in the Descriptions list. Use the mouse or keyboard to browse this list and select a library: the name or names of the relevant library files will be displayed in the Libraries text field. If you already know the name of the library you want you can type it directly into here. Use the buttons at the bottom of the dialog to act on your chosen library: Help Displays documentation for the library Show Displays the library source code Compile Compiles the library: this option will only be available if the relevant subsystem is loaded Use the Dismiss button to close the Library Tool window: it can be reopened from the File menu and will remember your last selection. 2.2 The Project Menu --------------------- This provides a subset of options from the Project menu in the Project Tool window. To learn more about projects choose Project Tool from the Help menu or see HELP * POP_UI_PROJECTTOOL. New Starts a new project. Open... Opens an existing project. Save Saves the current project. This option will be insensitive if there is no current project. Close Closes the current project. This option will be insensitive if there is no current project. 2.3 The Options Menu --------------------- Use the dialogs on this menu to set your preferences for Poplog, including the editor and the language subsystems. Options dialogs are organised into sets of sheets or pages displaying the values of user-assignable Poplog variables. Changing the values on an options sheet does not automatically update the corresponding variables: you must press the Apply button on that same sheet to make those changes take effect. If you don't like the changes you have made, press the Reset button to restore things as they were before the Apply, or the Set Defaults button to go back to some default state (typically how things were on entry to Poplog). If you press Apply on any sheet, the Save Options button is enabled on the menu. Use this to save any applied changes to disk such that they will be restored each time you run Poplog in the future. Save Options Saves the values of any options sheets which have been modified and applied since the last save; if there are no such sheets, this option will be inactive. Different sheets save their values in different ways; most will update your init files ("init.p", "vedinit.p", etc.). Selecting any other menu item will display one of the Options dialogs. The choice of items will vary depending on which components of Poplog you have loaded, but those described below are typical for a standard system. ... File --------- Variables controlling the File dialog and the creation of new files. Initial search directory The initial directory used by the File dialog: an empty string means the current directory Initial search pattern The initial filter pattern used by the File dialog File creation mode (UNIX only) See REF * pop_file_mode File backups See REF * pop_file_versions ... Store Management --------------------- Variables controlling dynamic storage allocation. Maximum heap size See REF * popmemlim Minimum heap size See REF * popminmemlim Garbage collection algorithm See REF * pop_gc_copy Garbage collection ratio See REF * popgcratio Garbage collection trace See REF * popgctrace ... Ved -------- Editor preferences, controlling both Ved and XVed. Use the menu button at the top of the dialog to select from the following pages: General Ved global variables. Auto write See REF * vedautowrite Preserve in input Whether to preserve tabs and/or trailing spaces in files when they are read into Ved. See REF * vedreadintabs, * vedreadintrailspaces Tab style See REF * vedhardtabs Page up/down See REF * vedscrollscreen Status line display See REF * vedstatusshowcols Command history See REF * vedstatusbufferlimit XVed XVed application resources. Auto Window Placement See REF * AutoWindowPlacement Always Raise Window See REF * AlwaysRaiseWindow Set Input Focus See REF * SetInputFocus Warp Pointer See REF * WarpPointer Show File Name See REF * ShowFileName Set Line Break On Resize See REF * SetLineBreakOnResize Search Does Select See REF * SearchDoesSelect Auto Cut See REF * AutoCut MultiClick TimeOut See REF * MultiClickTimeOut Max Windows See REF * MaxWindows XVed Window XVed currentWindow and defaultWindow resources. Number of Rows Number of Columns The size of the window text area in characters See REF * numRows, * numColumns Foreground Background Status Foreground Status Background Colours for the text area of the window See REF * foreground, * background, * statusForeground, * statusBackground Font Bold Font Italic Font Bold Italic Font Fonts for the text area of the window See REF * font, * boldFont, * altFont, * boldAltFont Pointer Shape X cursor shape in the text area of the window See REF * pointerShape ... Pop-11 ----------- Pop-11 language preferences. Use the menu button at the top of the dialog to select from the following pages: Printing Standard printing options. Maximum depth See REF * pop_pr_level Output radix See REF * pop_pr_radix Fractional places See REF * pop_pr_places Exponential format See REF * pop_pr_exponent Ratio format See REF * pop_pr_ratios Quoted strings See REF * pop_pr_quotes Exceptions Controls printing of exception -- mishap and warning -- messages. Minimum detail level See REF * pop_message_min_detail Maximum backtrace length See REF * pop_mishap_doing_lim Show system procedures See REF * popsyscall Compile Mode Sets Pop-11 compile mode flags described in HELP * COMPILE_MODE 2.4 The Help Menu ------------------ Most of these options use XVed to display standard Poplog HELP and TEACH files and so provide short-cuts into the Poplog documentation system. Choose the Editor|Overview option for details of how to navigate through the help system. Overview Displays this file -- HELP * POP_UI_OVERVIEW Project Tool Displays HELP * POP_UI_PROJECTTOOL Search... Displays the Help Tool described below: use this to search for help available on particular topics. Choosing this option is the same as running the XVed command helptool Editor -> Overview Displays HELP * POP_UI_EDITOR_OVERVIEW XVed Reference Displays REF * XVED Command Reference Displays REF * VEDCOMMS Keyboard Displays the standard function key bindings for your keyboard. Choosing this option is the same as running the Ved command hkeys Languages -> Subsystems Displays HELP * SUBSYSTEMS Pop-11 Displays HELP * POP11 Prolog Displays HELP * PROLOG Common Lisp Displays HELP * CLISP Standard ML Displays HELP * PML About Poplog... Pops up the Poplog Information dialog which summarises Poplog copyright, version and supplier information. Click the mouse anywhere in the dialog to dismiss the window. News Displays HELP * NEWS Customer Support Displays HELP * POPLOG User Group Displays HELP * PLUG Licence Displays HELP * POPLOG_LICENCE ... The Help Tool ------------------ The Help Tool provides a simple mechanism for searching the on-line documentation of Poplog. Type into the Subject field the name of the topic you are interested in and press the Search button: a list of references matching the subject will be displayed in the Search Results box. To follow up a reference, select it from the list of results and press View Document. Only single-word subjects are allowed and searching is restricted to document titles and keywords: you can't, for example, search for all documents containing the words input and output. Partial matches on the subject are reported however, so to maximise the number of references found you should stick to significant roots of words (so try copy rather than copying). By default, searching is restricted to the documentation of the primary subsystem selected on the control panel. Use the Language toggle buttons to widen the search to other subsystems. The File Types buttons let you restrict the search to particular documentation types corresponding to the four principal documentation categories of Poplog: HELP, REF, TEACH and DOC. The Search Indexes button determines whether the search includes indexed keywords, or is restricted to document titles only. In this context, "keywords" are typically identifier names. ----------------------------------------------------------------------- 3 Notes for Experienced Users ----------------------------------------------------------------------- The Poplog User Interface is built from the library LIB * POPLOG_UI. It is normally supplied ready-built as part of the startup saved image loaded with all the standard Poplog commands so that calling the standard X setup procedure sysxsetup -- either directly, or indirectly via the %x command-line option -- will automatically run the UI startup procedure pop_ui_setup. Whether the control panel window appears or not is determined by the boolean variable poplog_ui_enabled: this is normally true, so the control panel is created by default. If you don't want the control panel to appear automatically, you should set the variable poplog_ui_enabled to false in your "init.p" file: in case you are running Poplog without the UI library loaded, it's wisest to guard this assignment in a conditional compilation, like this: #_IF DEF poplog_ui_enabled false -> poplog_ui_enabled; #_ENDIF If you want subsequently to create the control panel by hand, do: true -> poplog_ui_enabled; pop_ui_setup(); More information about the programming interface to the UI is available in REF * POP_UI. 3.1 X Resources ---------------- You can use the X defaults mechanism to customise standard UI resources such as fonts and colours, but there are no application-specific resources that can be sensibly changed. The UI uses *XptDefaultDisplay for its X connection and the default class name is Poplog, so the following line added to your .Xdefaults file or similar would change the background colour of all windows created from the default display, including the UI: Poplog*background: LightSalmon Individual components of the interface can be addressed as follows: Poplog*controlTool The main control panel Poplog*projectTool The Project Tool window Poplog*helpTool The Help Tool window Poplog*libraryTool The Library Tool window Poplog*fileTool The file-chooser dialog ----------------------------------------------------------------------- 4 Related Information ----------------------------------------------------------------------- TEACH * XVED Notes on using the XVed editor HELP * SUBSYSTEMS An introduction to the Poplog language subsystems REF * POP_UI Procedures and variables of the Poplog User Interface HELP * POPLOG_UI The Poplog User Interface library --- C.x/x/pop/help/pop_ui_overview --- Copyright University of Sussex 1996. All rights reserved.