Examine/edit a manual card
The Card Viewer allows you to read the textual contents of a card. It is normally started by double-clicking on a card in one of the summary lists (for example from the ClassBrowser).
Notation. The card editor may display multiple cards simultaneously Each card is started using by a bold-printed header-line. If multiple cards with the same description are displayed by the card viewer this tool will put a header for each displayed card above the actual description. The type-indicator of the header of the card the description originates from is underlined.
User interface:
Jumping around:
button in the
running-text jumps to the related card.
history entry of the manual's menu bar.
Jump As double-click (follow link) Previous Jump back (META-p) Source View related sourcecode Consult Consult code fragment Describe Describe *this* card (edit) Show Key Bindings All keyboard accelerators
The options Source and Describe are also active on the header lines and allow the user to specify a specific object if multiple cards with the same description are displayed.
Tool name: card_viewer
Overview PCE's class hierarchy
The Class Hierarchy browser provides a hierarchical overview of PCE's class inheritance hierarchy. Initially, it displays the root and first level of sub-classes.
Classes are represented by a small box-icon, followed by their name. The fron-side of the box-icon indicated whether the class is built-in (a house) or user-defined (a face).
The Classes Hierarchy browser automatically displays user-defined classes when they are created.
User interface:
The text-entry-field CLASS may be used to locate classes in the
hierarchy. The argument is a pattern (see regex->file_pattern).
All matching classes will be added to the hierarchy and selected.
LEFT-CLICKING a node will try to make that class the selection (i.e.
it will show a description of the class in the Card Viewer. If
the‘Card Viewer’is not yet opened, DOUBLE-LEFT-CLICK opens
it.
RIGHT-DOWN on a node presents a POPUP-MENU, providing access to the ClassBrowser and source-code (if the class is user-defined).
Tool name: class_hierarchy
Examine/find class attributes
The ClassBrowser finds cards that are related in some way to
the current class. It can be started from the PCE Manual
window, or from any card that represents a PCE class by selecting the ClassBrowser
option. Some of the runtime environment tools (Visual Hierarchy and
Inspector) also allow you to jump to the ClassBrowser. Finally, the
ClassBrowser may be started directly using the predicate manpce/1.
User interface:
This tool consists of three windows. The dialog at the left is used to specify a query for the types of cards you are interested in. The window at the top indicates the current class, the initialisation arguments and the inheritance- and delegation relations of the class. The browser shows all cards that match the query.
The primary goal of the dialog window is to specify a query for finding class related cards. As almost anything is an object, most cards can be found this way. Below is a specifiation of the entry fields,
-name
is completed by hitting the space-bar.
class(es) of cards you are
interrested in. Basic refers to the principal and most commonly
used items, Advanced to less frequently used material,
SELF The current class itself SUB-CLASS All immediate sub-classes VARIABLE Associated instance variables RESOURCE Associated X-resources SEND-METHOD Associated send behaviour GET-METHOD Associated get behaviour
# ... IN This specifies the textual attributes that are searched if a search-string is specified in the SEARCH entry-field.
Typing RETURN is equivalent to clicking APPLY; it starts the actual search.
The first line indicates the class name
and initialisation arguments (see object->initialise).
Double-clicking this field shows the card belonging to the ->initialise
method.
The second graphical object is a tree object that indicates the location in inheritance tree of the current class, as well as delegation performed by this class. All classes in the primary inheritance path are displayed in bold font. Classes to which delegation takes place are added in the default font. Dotted (on colour displays: green) lines indicate delegation relations.
Notes in this tree may be selected to indicate the scope of the search. All classes below selected nodes are considered when searching for methods to display. Double clicking selects the class clicked upon and activates the Apply button.
This is a standard list of cards. LEFT-CLICK shows the card, the menu associated with the right-button gives the usual further options.
Tool name: class_browser
Examine errors/warnings
The Errors Browser visualises all defined error
objects. It may be used to examine defined errors, get an extensive
description of an error or change the kind of an error. The variable error<-kind
describes how the system reacts when such an error is encountered:
->report.
If there is no place to display the message without attracting attention
it is ignored.
->catch_error_signals, pce->print_c_stack).
PCE attempts to abort back to the host-language
toplevel
It is not advised to change fatal messages into another
kind.
User interface:
The user interface of this tool is similar to the other overview tools.
If a search string is specified only cards that match the regular expression entered will be shown.
If an error is selected, the kind menu is activated. It
may be used to change the kind of the error. For example
the error no_behaviour is generated if a message is send to
an object and the object has no method implementing this message.
Setting kind to ignored will make the message
silently fail; message will print it, but continue
execution and warning will trap the tracer. The latter
allows you to inspect PCE's goal-stack.
Tool name: errors
Overview of examples
This tools displays an overview of all examples. Currently the examples themselves are displayed using the Card Viewer. A more dedicated visualisation that allows the user to run the code is planned.
User interface:
Standard card summary browser. After opening a card which is viewed
by the normal card viewer tool a section called code is
available. This code may be consulted in the Prolog process using the
option Consult from the popup menu in the code section of the
card.
After consulting, you may normally run the example by typing a relevant query in the Prolog window.
Copy and Paste may be used to copy (fragments) of the examples into your application.
Tool name: examples
Overview of Functional Groups
The Group Overview tool allows the user to browse through the defined functional groups. A functional group is a collection of methods and variables that perform a similar or related action.
The window to the left displays the defined functional groups in the
same order as they appear in the card summary overviews. This order is
based on the notion of common use. Typing in this window
starts incremental search. Hitting RETURN or double-clicking will
display all related methods and variables in the summary window at the
right-side of the tool.
The window to the right is a standard card summary window and may be used to start the card viewer on a specific card or all cards by selecting the (top) group-header-line.
Tool name: group_overview
Analyse the structure of objects
The Inspector allows the user to inspect runtime-objects by showing their attributes. This tool is first of all a debugging tool.
There are three common ways to get a starting object. If you know the reference it may be typed in the Inspect entry-field, you can select an object from the screen after pressing the pointing-hand icon and finally various other tools provide Inspect Object or similar that activate this tool, in particular the Visual Hierarchy tool.
Selecting a card will FLASH the associated graphical if this is visible.
Each object is displayed on its own card, which consists of a
two-column table. At the top-left is the displayed object and its class.
At the top-right are the memory-management flags (see object <-_flags)
and the reference count (see object
<-references).
Below that follows an alphabetically ordered list of attribute-names and their current value.
User interface:
->flash message to it.
Put the reference (e.g. @pce)
on the clipboard.
This tool sometimes appears to miss changes.
Tool name: inspector
Overview of defined manual tools
The Manual Tools browser provides cards (i.e.
the manual) for each of the manual tools. When the help-button of some
tool is pressed, the corresponding card from this list is shown in the
card-viewer.
Tool name: manual_tools
Overview of predefined global objects
The Object Browser displays a list of documented global objects provided by PCE. Examples are @pce to control the environment and @prolog to interface to Prolog.
User interface: Standard
Tool name: global_objects
Overview of changes to PCE
The PCE Changes tool allows for browsing changes that have been made to the PCE system itself. Normally, the description of the change will be related to the affected classes/behaviours of the PCE system.
User interface: The user interface is standard.
Tool name: changes_browser
Bugs:
A specialised visualisation is necessary that allows you to sort by name and find changes by searching for strings.
It should also be possible to get all changes made after a certain date.
Overall manual/environment control
You are probably viewing the first card of the PCE online documentation system. This card is exceptionally long as we expect you to read it all and in the order presented. Once you understand the principles of this manual we hope you find it a handy tool to find your way in the mysterious world called PCE.
The manual is organised in Cards. This example contains an overview of the manual itself. It describes the main window and the overall organisation of tools. Read it carefully before you go on. The scrollbar allows you to scroll through the entire card.
The window labeled PCE Manual is the graphical gateway to the PCE environment and and the PCE manual. It contains four pulldown menus and a field for (short) general feedback messages.
You managed to find the HELP option, so probably you'll know how to operate the menu bar.
The FILE menu provides overall operations; the BROWSERS menu provides access to various entry-points of the reference manual material, the TOOLS menu provides access to some tools to monitor runtime environment of PCE. Finally, the HISTORY menu provides access to places where you have been in this manual. At the bottom of this card is an overview of the options in these menu's.
Below follows a description of the general principles and style used by the online manual. To get a detailed overview of the existing tools, open the MANUAL BROWSERS window from the BROWSERS pulldown.
The manual is divided into cards, each describing some
specific issue of PCE. The cards are typed; each specific kind of topic
is described on a card of a specific kind. Each card has the following
general attributes:
Type A single capital indicating the type Name Short meaningful name Last Modified Time-stamp for last modification Summary About 40 characters summary Description Arbitrary length contents of the card See also Related cards.
The available types and their identifiers are:
B Browser (manual) tool C PCE Class E Example K Keyword entry M Method of a class O Global PCE object (@prolog, @pce, ...) P (Prolog) predicate T Topic V Variable
Currently, you are reading the DESCRIPTION of a card. In the window at the bottom-right are some cards that are related to this card. Note the first letter that serves as a type indicator.
The entire online help system consists of three different type of
tools. First of all the main window (called PCE manual), which
allows the user to start a browser.
Each BROWSER provides access to a GROUP of CARDS, starting from a specific ORGANISATION. The manual is organised around a class-oriented hierarchy (ClassHierarchy and ClassBrowser), a keyword-based index (Keyword Browser) and some special browsers listing cards of one specific type (predicates, global XPCE objects, examples and manual tools).
Most Browsers present a list of CARDS, displaying only the name and possibly the summary of the card. From there, the user may select a card to view the contents in the CARD VIEWER. When the card viewer is opened, a SINGLE-LEFT-CLICK on the object will open the card. Otherwise DOUBLE-LEFT-CLICK will start the card-viewer.
The CARD VIEWER displays the textual attributes of the card and allows you to jump to RELATED cards.
The online manual tools use two mechanisms to communicate. First of all, a CARD may be SELECTED. All other manual tools will highlight the currently selected card. The CARD VIEWER will show the textual contents and relations of the selected card. Selecting a card is done by LEFT-CLICKING on the card, or by selecting the SELECT option from the POPUP MENU associated with most representations of a card.
The manual can be requested to FOCUS on a specific card. The general
intention is that each tool is given the opportunity to focus
on that card. In practice, the current implementation makes this feature
only handy for cards representing a CLASS: requesting it to become the
focus makes the Class browser
jump to the associated class.
From the POPUP MENU associated with a visualisation of a card, a number of other options are available. These are:
SELECT Select the card and view its contents FOCUS Make card the focus (see above) SOURCE Start an editor on the source code RELATE Relate the card to the selection UNRELATE Unrelate the card from the selection
Menu BROWSERS MANUAL BROWSERS Overview of available manual tools ======================================== CLASS HIERARCHY Overview of the PCE class hierarchy CLASS BROWSER Examine definition of a class GlOBAL OBJECTS Overview of predefined objects ERRORS Define errors (may be catched) PROLOG PREDICATES Overview of PCE/Prolog predicates ======================================== KEYWORD BROWSER Keyword-based access GROUP OVERVIEW Overview of related methods EXAMPLES Overview of examples
Tool name: manual
Bugs:
Various things are still incomplete or buggy to these manual tools. A short list:
Overview of PCE related Prolog predicates
The Predicate Browser provides an overview of the Prolog predicates related to the PCE/Prolog interface and the PCE/Prolog libraries.
User interface: Standard
Tool name: predicate_browser
Search for combination of words in manual
The Search Tool is located in the Browsers/Search menu of the online manual tools.
This tool consists of a browser containing all words extracted from the manual, a summary window with the same user-interface as all other summary windows and a dialog containing a‘Search For’button and associated text entry field. A search specification can by typed in this field and all cards matching this specification will be shown on the upper summary browser.
If the user pauses typing for one second, the tool will evaluate the current expression and indicate the number of matches if the expression is syntactically correct.
The expression syntax contains the following keywords and special symbols:
and.
# ( Expr ) Brackets may be used to specify association. There is no
ordering in the operators. not matches the smallest
expression. A and B or C is read as
A and ( B or C).
Below are some valid expressions:
frame and displayed (file or directory) and absolute graphical and move and user
The database is maintained in the file
pce('man/reference/index.obj')
This file is a chain_table object, mapping words in the cards on their card identifier. The system will prompt to create a new index if the index cannot be found.
Tool name: search
Resource usage by PCE/Prolog
The Statistics Tool provides an overview of the memory usage by PCE. The values are updated every 5 seconds.
The values have the following meaning:
<-core_usage)
The total amount of core PCE has requested itself explicitly via the
system's malloc() function. Note that core requested by
libraries is not included.
<-core_wasted)
PCE defines it's own memory allocation schema. This value indicates the
total amount of memory allocated and later freed, but not (yet) reused.
<-objects_allocated
- pce<-objects_freed)
Total amount of living objects (i.e.
objects created and not yet freed).
Tool name: statistics
Bugs:
It appears this tools uses for misterious reasons a little bit of memory each time it is updated.
List of card summaries
Most of the manual tools provide means to find cards, giving some starting point. For example, the Class browser allows you to find cards from a PCE class; the Keyword Browser; allows you to find cards from some keyword.
These tools display a list of card-summaries in a browser window, normally positioned somewhere at the right side of the tool. This browser window displays the cards line-by-line. The first character indicates the type of the card:
B Browser (manual) tool C PCE Class E Example K Keyword entry M Method of a class O Global PCE object (@prolog, @pce, ...) P (Prolog) predicate T Topic ! Error object ~ Description of a change to PCE
The next field provides the name of the card. When there is enough space, a third field is added that provides a 40 character summary string of the contents of the card.
When the summary field is tagged with _(+)_, the description field is not empty. A double click will show the description field in the card viewer.
User interface:
A summary browser indicates the selected card by inverting it. It has the follwing user interface behaviour:
A LEFT-CLICK on a line sets the global selection of the manual to this card. This implies the Card Viewer will display the contents of the card. If the Card Viewer is not open, DOUBLE-LEFT-CLICK will open it.
A RIGTH-DOWN on a card invokes a popup menu with the following options:
SELECT Equivalent to LEFT-CLICK
FOCUS Set global focus. Currently only useful on
_Class cards_ to set the current class of the
_Class Browser_.
=====================================================
SOURCE Display the source-code related to the
card (Classes, methods, variables and
resources).
SPY If the object is a method, put a Prolog
spy-point on the implementing predicate.
=====================================================
TRACE When the object is a method, put a PCE
trace point on it. See also Method->trace
=====================================================
RELATE Relate this card to the selection
UNRELATE Destroy relation to the selection
Hierarchical overview of the manual
The Topic Browser displays a hierarchical overview of the manual. Unlike the class hierarchy, which shape has a technical motivation, the topic hierarchy is not constrained by any technical issues and contains subjects that are not directly related to a class.
Representing a tree, the interface is similar to that of the‘Class Hierarchy’browser. Some more options are available to allow for editing the topic hierarchy.
The contents of a topic are shown by the Card Viewer, which is automatically started when a topic is selected by a LEFT-CLICK or by the SELECT option from the POPUP-MENU associated with each topic (under the right mouse-button).
User interface:
A LEFT-CLICK on a node displayed the contents in the Card Viewer. If the Card Viewer is not yet opened, DOUBLE-CLICK will do so.
Each node (topic) in the tree has a popup-menu associated with the follwing options:
SELECT Make topic the selection (view contents) ===================================================== EXPAND Expand 1 level of sub-topics EXPAND TREE Expand all the way down COLLAPSE NODE Destroy all subnodes ===================================================== RELATE Relate topic to selection RENAME Change the name to the NAME field ===================================================== MOVE BELOW Reorder: move just below selection or to be first MAKE DAUGHTER Make this node a daughther of the selection REMOVE DAUGHTER Remove link to selected parent ===================================================== DELETE CARD Destroy the entire topic card
A new topic card is CREATED (when the manual is in edit-mode) by:
topic_browser
Overview consists hierarchy of visuals
The Visual Hierarchy tool can be used to overview the consists_of hierarchy of visual objects. It is commonly used to find the PCE reference for visual objects from the screen or to examine the structure of a tool (in terms of the visual objects it is built from).
The tool consists of a graphical window for displaying the hierarchy and a dialog. The graphical window displays the hierarchy. The root of the hierarchy is the PCE predefined object @display_manager and is always present.
User interface:
Any XPCE graphical object from the screen may be added to the tree by positioning the pointer (mouse) on the object and pressing META-SHIFT-CONTROL-V. Mnemonic: V for Visual and all modifiers to avoid conflict with applications.
Each node of the hierarchy has a menu associated with the right button. This menu has the following entries:
FLASH Send ->flash to the represented graphical ============================================= EXPAND Expand the next level of the hierarchy EXPAND TREE Expand as many levels as possible COLLAPSE Remove all subtrees DELETE Remove this node and anything below ============================================= SOURCE View source of class of object INSPECT Start _Inspector_ on object TILE HIERARCHY Frames: analyse the tile structure CLASS BROWSER Start _ClassBrowser_ on class of object.. ============================================= FREE Send ->free to the object POSTSCRIPT Genererate a PostScript description
The following button bindings are defined:
->Flash the object and print the output of
portray_object/1 in the dialog. The
reference of the object is put on the X-display clipboard for pasting in
another application (typically the Prolog window for further analysis of
the object).
Tool name: visual_hierarchy
Bugs:
The functionality of this tool is still experimental.
The tool does not automatically update for changes in the PCE world. Only destroyed visuals that are displayed by this tool will be removed from it.