# 
# * See the file "PlanWorks/disclaimers-and-notices.txt" for 
# * information on usage and redistribution of this file, 
# * and for a DISCLAIMER OF ALL WARRANTIES. 
# 

# $Id: GETTING_STARTED,v 1.60 2004/09/21 01:07:02 taylor Exp $
#

Projects and Plan Sequences
===========================
"Project->Create ..." brings up the "Create Project" dialog requesting
a project name.  

Clicking "OK" on the "Create Project" dialog brings up the "Select Planning
Sequence Directory(ies)" chooser.  The sequence directory chooser (also
invoked by "Project->Add Sequence") supports multiple selection of sequence 
directories, by using Ctrl-Mouse-Left for the second and subsequent selections.  
Mouse-left is used for the first selection and Mouse-Left-Double is used to 
open directories.  A single selection can be made on a directory, whose children 
are all sequence directories.  When selection is complete, click on "OK".  The 
selected sequence(s) are then loaded into the MySQL data base.  Pull-down menu 
"Planning Sequence" will be created, which is a cascading menu of loaded 
"sequence names".

"Project->Open ..." will bring up pre-loaded plan sequences for a pre-
defined project, and allow them the be viewed using the "Planning
Sequence" cascading menu.

"Project-Delete ..." will remove a pre-loaded project and its sequences
from view (if being currently displayed), and from the MySQL data base.

"Project->Add Sequence" prompts the user, via the sequence chooser dialog,
to add one or more sequences to the current project, and the MySQL data
base.

"Project->Delete Sequence" prompts the user, via a list dialog, to remove
the selected sequence from the current project, and the MySQL data base.


Overviews of Plan Sequence and Partial Plan Views
=================================================
The Sequence Steps view, and the partial plan views, except for DB Transaction 
and Decision, have a Mouse-Right popup named "Overview Window" which opens a 1/8th 
scaled view of the entire "observed" view.  There is a rectangle in the 
overview which can be dragged to cause the "observed" view to be scrolled 
to new locations.  Mouse-Left clicking in the overview outside of the 
rectangle will cause the "observed" view to "jump" to that location.


Zooming of Plan Sequence and Partial Plan Views
===============================================
Mouse-Right "Zoom View" is available for the Constraint Network, Navigator, 
Temporal Extent, Timeline, and Token Network partial plan views.  It also 
is available in the Sequence Steps view.  The zoom out factors are x2, x4, 
x6, and x8 (the same scaling as the Overview windows).  Whereas Mouse-Right 
"Overview Window" creates a new window and allows the coordinated viewing of 
the paired windows, "Zoom View" does not create a new window, rather it 
changes scaling in the existing window.  Thus the existing Mouse-Right 
functionality on the view background and the view nodes is maintained.


Plan Sequence Views
===================
The "Planning Sequence" menu expands into the available sequence names.  
Selecting a sequence name brings up two windows.  The first,
"SequenceQuery ...", allows the user to make data base queries over the 
sequence (see "Querying Sequences" below).  The second, "SequenceStepsView", 
is a histogram of the partial plan data base size for each step of the 
sequence, with every tenth step number displayed at the bottom of the 
appropriate element.  The "SequenceStepsView" background has these Mouse-
Right selections: "Close/Hide/Show <sequence-name>/step Views", which 
effect the views on all sequence steps.

Individual or all partial plan views for each step are available by
clicking Mouse-Right on the desired step in the histogram ("SequenceStepsView"). 
This step then becomes the currently selected step.  The histogram steps 
have a "mouse over" pop-up showing the step number, and the data base size 
for tokens, variables, and constraints -- which are color coded.  
The "SequenceStepsView" background also has "Step Backward step<nn> Active 
Views" and "Step Forward step<nn> Active Views", where <nn> is the currently 
selected step. Active views are those views which exist for the currently 
selected step.  Note that stepping an individual view will change the
currently selected step.

Above each histogram step in the SequenceStepsView is a colored dot: green - 
partial plan loaded into data base; yellow - partial plan on disk; and red - 
partial plan not on disk.


Partial Plan Views
==================
The partial plan views are Constraint Network, DB Transaction, Decision,
Resource Profile, Resource Transaction, Temporal Extent, Timeline, and
Token Network.  The key values for interval tokens, resource transactions,
constraints, variables, timelines, resources, objects, rule instances,
and slots appear in the appropriate node labels of the partial plan views. 

The rendered node shapes are: interval tokens and resource transactions (rectangles); 
resources (pinched/peaked rectangles); timelines (forward trapezoids); objects
(backward trapezoids); rule instances (ellipses); variables("pinched" rectangles);
constraints (left/right pointed rectangles); and slots (peaked rectangles).
 
All partial plan views' Mouse-Right pop-ups offer the user selections
 ("Open <view-name> View") for the other partial plan views, which will 
create them as needed.  All views, except for DB Transaction View, the
Decision View, the Resource Profile View, and Resource Transaction View,
also offer "Raise Content Filter", which will set focus on the appropriate
partial plan Content Filter window.  In addition, all partial plan view's  
Mouse-Right pop-ups offer the user "Close All Views", "Hide All Views", 
"Open All Views", "Show All Views", "Step Backward All Views", and
"Step Forward All Views".

Applying a Content Filter specification will cause the views to be redrawn 
with only the filtered predicates, timelines, time intervals, and their
dependencies.

Every view has two buttons in the lower left corner which, when clicked,
will cause the view to display either the next or previous step.  The
highlighted step in the SequenceStepsView will track the current step
number.

There are eight active views:

Constraint Network View
-----------------------
An incrementally built directed graph of objects, resources, timelines, 
interval tokens, resource transactions, rule instances, their variables and 
their constraints.  Because of its complexity, initially only the variable 
container nodes (objects, resources, timelines, interval tokens, resource 
transactions, and rule instances) are displayed.  They are "opened" by mouse 
clicks which lay out the variable container's variable nodes.  Clicking on 
variable nodes "opens" them to show or link to their nearest neighbors 
(constraints or variable containers).  Similarly, clicking on constraint nodes 
"opens" their nearest neighbors.  Clicking on an "open" node (bold border), 
"closes" that nodes nearest neighbor nodes/links, provided the link counts are 1.  
Then the node becomes "closed" and has an unbold border.  The active node 
("opened" or "closed" by Mouse-Left click) is positioned in the center of the 
view after layout, and highlighted by a bright green rectangle.

The view background Mouse-Right pop-up offers, in addition to the "standard" selections,
"Find Entity Path" and "Highlight Current Path".  "Find Entity Path" requests 
two entity keys, class node types to search, and an optional maximum 
path length.  "Find Path" finds a path through the classes specified, rendering
the selected nodes and highlighting them.  This dialog also offers "Does Path Exist"
which determines whether a path exists, without finding the nodes.  Selected nodes 
are dragged as a group, which may be inconvenient.  To deal with this, click
Mouse-Left in the background to discard the selections, drag the nodes to new 
locations, and then on the background select Mouse-Right: "Highlight Current Path".

Mouse cursor over all variable container nodes, except for interval tokens and
resource transactions, displays the node name, and Mouse-L: open" on the second 
line.  Mouse cursor over interval token nodes displays "predicateName( 
parameterValues)" on the first line, its slot key value on the second line, and 
"Mouse-L: open" on the third line.  Mouse cursor over resource transaction nodes 
displays the resource name and its change amount on the first line, and "Mouse-L: 
open" on the third line.  Mouse cursor over variable nodes displays "variableType" 
on the first line, and "Mouse-L: open" on the second line.  Mouse cursor over 
constraint nodes displays "constraintType" on the first line, and "Mouse-L: open" 
on the second line.  Clicking Mouse-Left on a node link will make visible two 
small hollow squares, one at the "root" of the link, and the other at the tip 
of the arrow.

DB Transaction View
----------------
Lists the transactions for this partial plan step.  Each entry includes the
transaction key (TX_KEY), the TRANSACTION_NAME, the transaction source
(SOURCE), the entity key (ENTITY_KEY), the step number (STEP), and the entity name
(ENTITY_NAME).  Entries with TRANSACTION_NAMEs of VARIABLE_* have values for 
PARENT_NAME.  Entries with TRANSACTION_NAMEs of VARIABLE_* and 
ENTITY_NAME = PARAMETER_VAR have values for PARAMETER_NAME.

Mouse-Right click on the background, between the window title and the table
column headers, offers "Find Transaction By Obj_Key".  Entering an ENTITY_KEY 
value will cause the lower portion of the Transaction view to scroll up to show 
the transaction entry with the selected ENTITY_KEY value.  The ENTITY_KEY value 
will be highlighted.  Mouse-Left clicks on the column header nodes offer sorting 
based on that columns's values: Mouse-Left clicks cycle through sortAscending, 
sortDescending, & noSort - while clearing other column sorts; Control-Mouse-Left 
clicks cycle through sortAscending, sortDescending, & noSort - while not clearing 
other column sorts.  The table column widths can be resized by dragging the column 
header boundaries.

Decision View
-------------
Lists the current plan decision and pending decisions in a "tree" format.  Decisions
with choices are "openable".  Objects, resources, timelines, interval tokens,
resource transactions, and variables can be viewed in other appropriate views by
choosing from Mouse-Right clicks on decsion and choice entity key values.  A Mouse-
Right click on the background offers the user "Find Decision by Key" and opening other
views, as choices.

Resource Profile View
---------------------
Lays out each resource's min/max profiles and min/max limits with the x-axis 
being time and the y-axes being the resource quantity.

The Mouse-Right selection "Snap to Active Resource" will find and scroll into
view the appropriate Resource, providing the "active" resource has been set
by the Resource Transaction View. The Mouse-Right selection "Snap to Active 
Resource by Transaction" will find and scroll into view the appropriate Resource, 
providing the "active" token is a Resource Transaction, rather than an Interval
Token.

Resource Transaction View
-------------------------
Lays each resource's transactions stacked vertically by their time intervals
when they overlap.  Mouse over the transaction rectangle pops up the time
interval and the min/max change values, along with the transaction's key value.
The x-axis is time and the y-axes are dynamic, depending on how many stacked 
transactions are rendered.

The Mouse-Right selection "Snap to Active Resource" will find and scroll into
view the appropriate Resource, providing the "active" resource has been set
by the Resource Profile View.  Mouse-Right on the resource transaction nodes 
offers the selections "Open Navigator View", and "Set Active Token".  The 
Mouse-Right selection "Snap to Active Resource Transaction" will find and
scroll into view the appropriate Resource Transaction, providing the "active"
token is a Resource Transaction, rather than an Interval Token.

Resource Views Mouse Operations
--------------------------------
Mouse over the resource names pops up a tool tip with the resource's key value.
Mouse-Right on the resource names offers the selections "Open Navigator View", 
and "Set Active Resource".

Mouse-Right on their "extent" backgrounds allows the setting of a vertical 
time mark ("Set Time Scale Line").  If both views are active for the same 
partial plan, the time mark is also rendered on the companion view, which is 
scrolled so the time mark is in the view port ("Set Time Scale Line/Snap to 
"Resoruce {Profile | Transactions}").


Temporal Extent View
--------------------
Lays out all predicates on a time scale, with triangles denoting the start 
and end variable values.  The range of extent is shown by a horizontal line.
The extent line and associated triangles are displayed immediately below 
each predicate node.  Downward triangles are start times, upward triangles 
are end times, leftward triangles are -Infinity, and rightward triangles are 
+Infinity.  Mouse cursor over start/end interval "triangles" displays their 
time scale value.  Mouse cursor over a token's duration  line displays the 
duration interval.  Mouse cursor over the token node displays 
"predicateName( parameterValues)" on the first line, and its slot key value 
on the second line.

Clicking Mouse-Right on the view background will pop-up a menu, one of whose 
selections is "Set Time Scale Line".  Selecting it will cause a red vertical 
time scale line to be drawn.  A Mouse-Right "Set Time Scale Line" selection 
at another location will move the time scale line.  "Hide/Show Node Labels"
is another available selection, where the large label rectangles vanish and
the token duration line expands to a thick bar. Mouse-Right also offers
"Show Earliest" and "Show Latest", as options to "Show Intervals".

Timeline View
-------------
Lays out the plan's objects, timelines, and slots.  Start/end time intervals
are displayed at slot boundaries.  Applying a Content Filter specification 
will cause the view to be redrawn with only the filtered timelines and slots.
Adjacent slots whose end and start intervals are equal will be drawn abutting 
each other.  Those that are not, will be drawn with a fixed space between them,
and the later slot will have its time interval labels drawn "lower" than
the previous slot, to prevent overlap.  Mouse cursor over timeline slots displays 
the slot's "predicateName( parameterValues)", and the second line displays the
token keys(s).

Providing the Temporal Extent View is open for a partial plan step which
has a Timeline View, Mouse-Right on the Timeline View background offers 
"Enable/Disable Auto Snap", which when enabled will cause the Temporal Extent 
View's focus to follow the mouse cursor's movement over Timeline View slots 
and free tokens.

Token Network View
------------------
Lays out the plan's token relations and rule instances in directed graphs whose
root nodes are the "supreme" master tokens.  The Token Network View is freshly 
layed out after a  Content Filter specification is applied.  The token nodes,
are rendered as rectangles with a label containing the token's predicate name
and its key value.  The rule instance nodes, are rendered as ovals, with the 
instance key and the rule key values in the label.  The initial rendering is
of only the "root" token nodes and their immediate rule instance nodes. The
view can be imncrementally increased or decreased by clicking on the appropriate
nodes (see below).

The view background Mouse-Right pop-up offers, in addition to the "standard"
selections, "Find Entity Path", and "Highlight Current Path".  "Find Entity Path" 
requests two entity keys, class node types to search, and an optional maximum 
path length.  "Find Path" finds a path through the classes specified, rendering
the selected nodes and highlighting them.  This dialog also offers "Does Path Exist"
which determines whether a path exists, without finding the nodes.  Selected nodes 
are dragged as a group, which may be inconvenient.  To deal with this, click
Mouse-Left in the background to discard the selections, drag the nodes to new 
locations, and then on the background select Mouse-Right: "Highlight Current Path".

Mouse cursor over token nodes displays "predicateName( parameterValues)", and 
the second line, if appropriate, shows "Mouse-L: {open | close}".  "Open" will
display the tokens neasrest neighbors, and "close" will make them invisible.
Mouse-Right on the token nodes offers the selections "Open Navigator View", and 
"Set Active Token".

Mouse cursor over rule instance nodes displays "Mouse-L: {open | close}, which 
open/close its nearest neighbors.  Mouse-Right on the rule instance nodes offers 
the selections "Open Navigator View", and "Open Rule Instance View".  "Open Rule 
Instance View" creates an internal frame titled "RuleInstanceView of 
<plan-name>/stepnn - n", which displays the "from" token, and "to" token key values 
and predicates, followed by the text of the rule.  A "RuleInstanceView ..." internal 
frame may be created for every rule instance node in the Token Network View.  Mouse-
Right: "Close Rule Instance Views" on the view background can be used to remove all 
"Rule Instance Views".

Clicking Mouse-Left on a node link will make visible two small hollow squares, one 
at the "root" of the link, and the other at the tip of the arrow.  


Node Focus in Views
==================================================
Nodes which can have focus set:
o Interval token nodes in the Constraint Network, Temporal Extent, Timeline
  (slot nodes), and Token Network views;
o Resource transactions in the Resource Transaction, Temporal Extent, and 
  Token Network views;
o Resource nodes in the Resource Profile, and Resource Transaction views.

These nodes have a Mouse-Right pop-up menu with the possible selection of
"Set Active Token".  When the "active token" has been set, the other views 
have a "background" Mouse-Right pop-up menu with the possible selection of
"Snap to Active Token".  Making this selection will cause the view
to scroll to a position where the "active token" will be shown,
highlighted, in the approximate center of the view.  A Mouse-Left click
in any view will erase node selection highlighting.  In the Timeline View,
clicking Mouse-Right "Set Active Token" on a slot, will set the overloaded
tokens as "secondary tokens", such that when Mouse-Right "Snap to Active
Token" is invoked in the background of the Constraint Network View, the
Temporal Extent View, or the Token Network View, these secondary tokens will 
be given secondary highlighting (turquoise).  The base token will have the 
primary highlighting color (light green).

In all the partial plan views (except the Transaction View), Mouse-Right on 
the background offers "Find by Key" which allows the user to enter a key
and have the view scroll to that node's location.  For Temporal Extent and 
Token Network views, entered keys will find interval token and resource
transaction nodes; for the Timeline view, entered keys will find timeline,
interval token, and slot nodes; for the Resource Profile view, entered keys 
will find resource profiles; for the Resource Transaction view, entered keys 
will find resources and resource transactions, and for the Constraint Network 
view, entered keys will find find object, timeline, resource, token, variable,
and constraint nodes -- opening appropriate connecting nodes, if needed.


Entity Relationships
================================================================
For all nodes, except empty slots, in the Constraint Network, the 
Resource Profile, the Resource Transaction, the Temporal Extent, the 
Timeline, and the Token Network views, there is a Mouse-Right selection 
"Open Navigator View" which allows navigation through all relationships 
in the partial plan data base, beginning with the selected entity.

In addition to the "standard" selections, the Navigator View has three
background Mouse-Right selection options: "Find by Key", "Find Entity Path",
and "Highlight Current Path".  "Find by Key" requests a single entity key and 
finds that node, opening it and its neighbors, if necessary.  "Find Entity Path" 
requests two entity keys, class node types to search, and an optional maximum 
path length.  "Find Path" finds a path through the classes specified, rendering
the selected nodes and highlighting them.  This dialog also offers "Does Path Exist"
which determines whether a path exists, without finding the nodes.  Selected nodes 
are dragged as a group, which may be inconvenient.  To deal with this, click
Mouse-Left in the background to discard the selections, drag the nodes to new 
locations, and then on the background select Mouse-Right: "Highlight Current Path".


Content Filtering
=====================
The tokens displayed in the partial plan views may be filtered by
predicate, by timeline, by time interval, and/or by token keys using the
partial plan's Content Filter dialog.  It is also possible to 
limit the set of valid tokens to only free tokens ("View free tokens"), to only
slotted tokens ("View slotted tokens"), to only base tokens ("Merge tokens" and
"View slotted tokens"), or to free and base tokens ("Merge tokens").

Applying single predicate, timeline, and time interval filters results
in only the tokens which match that filter being displayed.  To filter
"in" more than one of the types, use the "OR" combo box selection; to
filter "out" more than one of the types, use the "NOT" check box for
each entity type, and the "AND" combo box selection

The token keys filter works thusly: click on either the "require" or 
"exclude" radio button, and then enter the key value in the input slot.  
To include more keys, click on "Add"; to remove keys from a previous 
"Apply Filer" set, click on "Remove".  The "require" or "exclude" 
selections override the "Predicate", "Timeline", and "Time Interval" 
selections, with applied together.

Selections applied from this dialog result, internally, in a set of 
valid tokens, which are used by the views to filter their displays.

The Content Filter window's background areas offer Mouse-Right
selections for opening individual or all partial plan views, and for
"stepping" all active views.


Querying Sequences
==================
The "SequenceQuery for <sequence-name>" dialog, provides the user with 
queries which are in five groups, based on the primary kind of information 
returned:
"Steps": "Where Constraint/Token/Variable Transacted ..." which 
asks for a key value (if the key value is left blank, then all key values 
are returned) and the transaction type; "With Non-unit Variable 
Decisions", "With Restrictions", and "With Unit Variable Decisions". 
 
"Transactions": "For Constraint/Token/Variable ..." which asks for a key 
value; and "In Range ...", which asks for "StartStep" and "EndStep" values.

"Free Tokens":  "At Step ..." which asks for a sequence step.

"Unbound Variables": "At Step ..." which asks for a sequence step.

"All Decisions": "At Step ..." which asks for a sequence step,
and brings up two results windows, one for free tokens and one for 
unbound variables.

"Apply Query" will cause the query to be performed and a window "Query 
Results for ..." to be created to display the query results.  
The query results windows can be removing by clicking Mouse-Right on 
the background of the "SequenceQuery for ..." dialog, and selecting
"Discard Query Results Windows".

Each entry of the "Query Results for ..." windows for "Transactions" queries 
includes the transaction key (TX_KEY), the TRANSACTION_NAME, the transaction 
source (SOURCE), the step number (STEP), and the entity name (ENTITY_NAME).  
Entries with TRANSACTION_NAMEs of VARIABLE_* have values for PARENT_NAME.  
Entries with TRANSACTION_NAMEs of VARIABLE_* and ENTITY_NAME = PARAMETER_VAR 
have values for PARAMETER_NAME.  The "In Range ..." queries, 
also include the entity key (ENTITY_KEY).

Each entry of the "Query Results for ..." windows for "Steps" queries 
includes the step number (STEP), the transaction key (TX_KEY), the 
TRANSACTION_NAME, and the entity name (ENTITY_NAME).  Entries with 
TRANSACTION_NAMEs of VARIABLE_* have values for PARENT_NAME.  
Entries with TRANSACTION_NAMEs of VARIABLE_* and ENTITY_NAME = PARAMETER_VAR 
have values for PARAMETER_NAME.  The "With ..." queries, and the "Where ..."
queries with blank "Key" fields, also include the entity key (ENTITY_KEY).

The "Query Results for ..." windows which have a (---_KEY) column offer the 
user a pop-up dialog entitled "Find {Transaction|ConstraintToken|Variable} by 
{Entity_Key|CSTR_KEY|TOK_KEY|VAR_KEY}".  Mouse-Right on the background of the 
panel between the window title and the table column headers of the window, 
brings up this dialog.

The column header nodes of the "Query Results for ..." windows, offer sorting 
based on that columns's values: Mouse-Left clicks cycle through sortAscending, 
sortDescending, & noSort - while clearing other column sorts; Control-Mouse-Left 
clicks cycle through sortAscending, sortDescending, & noSort - while not clearing 
other column sorts.  The table column widths can be resized by dragging the column 
header boundaries.

The "Step" column values of Query Results windows offer a Mouse-Right popup 
with actions on the partial plan views for that step.


Screen Management
=================
The "Window" pull-down menu offers the user the ability to rearrange all
active windows by "tiling", or "cascading".  This menu also provides for the 
indivual selection of any active window ordered thusly:
  - menu separators divide different plan sequence window groups;
  - within each plan sequence group, the ordering is SequenceQueryView, 
    SequenceStepsView, and any QueryResults windows;
  - then a cascading sort by step number, and by view name of all partial plan 
    views, including the NavigatorView.


Function Management
===================
"Progress monitors" are created for functions which can be cpu intensive, such
as creating partial plans and rendering views.  The user has the option to "Cancel" 
these operations, if desired.

