                     P I L O T   E X P L O R E R
                     ===========================

Author: Scott Powell (scottpowell@kagi.com)
Version: 1.4
Date: 04/08/1997

Copyright Notice
================

   Copyright(c) 1997, Scott Powell.


Install Notes
=============

  Simply use 'instapp' to install the 'explorer.prc' & 'pimapps.prc' files
  onto your pilot. There should also be other .PRC files. These are standard
  'Plugins' (see below), which are optional add-ons which you can install if
  you like (using 'instapp').


Instructions
============

  Explorer gives you a 'tree view' of your data. If you have used any
  modern Graphical User Interface (GUI's) you will probably have seen
  a 'tree' view like this. Basically objects are represented in a hierarchy,
  shown by indentation, ie. objects owned by another are shown underneath
  their 'parent' and indented (to the right).

  Each object is displayed in the following format:

    [ICON]  [Tree text]  | [Size/other-info Text]

  The icon will show what type of object it is (ie. Memo, Address, etc.)
  and the 'Tree text' is some identify text of the object. The text to the
  right varies depending on the type of object. For group objects it is
  usually the number of child objects it owns.

  Objects that hold 'child' objects are termed as 'group' objects. These
  can have a '+' or '-' displayed inside their icon which indicates whether
  they can be 'expanded' or 'collapsed'.

  If you tap on the 'Tree text' part of the object, or on the 'size' text,
  then the default action is performed on that object. These are:

       for group objects     - 'toggles' branch, ie. expands or collapses
       for non-group objects - launches 'viewer' for object.

  If you tap on the icon of the object you get its 'context menu'. These
  have the full list of actions you can perform on the object.

  At the top right corner of the screen are three radio buttons, for
  controlling the current 'mode' of operation. These are explained below:

        Select      - Normal mode, where you can expand/collapse branches,
                      and select object's context menus.

        <->         - select this mode when you wish to move the vertical
                      bar left and right. Once in this mode, just drag the
                      pen on the screen to move the bar.

        Scroll      - when in this mode, the pen being held down will cause
                      the tree to scroll up (if the pen is in the upper half
                      of the screen), or down (if the pen is in the lower
                      half)

  Graffiti Key Strokes:

    * Backspace - If you type this the current (highlighted) object becomes
                  the PARENT of the current object. This is very handy for
                  collapsing the current branch you are on.

    * <Alpha>   - If you type an alphabetic character, the current object
                  becomes the FIRST CHILD object that starts with that
                  letter. Very handy quick search (esp. in the address book)

  Hardware Buttons:

    * Up & Down - These buttons scroll the tree up and down. (like in 'Scroll'
                  Mode)
                  NOTE: These buttons may do different things when a dialog box is
                        currently being displayed. Some of these are:

                       Find Dialog:   Scrolls the hit-list up and down.
                       Address View:  Flicks between the top & bottom page of the
                                      address details.
                       Memo View:     Scrolls the memo text up and down.

  At the bottom of the screen is the 'status line'. This is a multi-purpose
  area for helpful information, or short-cuts to your favourite commands.
  See below for more about the status bar.


Plugins & Status Bar!!
======================

  Explorer now supports 'Plugins'. These are add-on modules which provide
  access to 3rd party databases, and/or provide helpful status-bar displays (see
  below). Please contact the author of your favourate apps for them to provide
  a Plugin for their data. Plugins can optionally have support for Folders!
  If the Plugin provides this, then you can create/move/edit/delete objects of
  its types inside Folders!

  Three standard Plugins are provided (along with source code, for interested
  developers). These are 'Clock-Plugin', 'Battery-Plugin' and 'Trash-Can
  Plugin'. These are examples of what can be done with the status line. They
  aren't, however, examples of 3rd party database access. If there isn't enough
  room on the screen for all the 'applets' then scroll arrows come up, letting
  you scroll the status bar left & right.

  NOTE:   Access to the PIM objects (Memo, Address, Datebook & ToDo) is now
          provided through a Plugin called 'PIM-Apps' (pimapps.prc).

  The status bar is completely 'open ended', and there are many possibilities
  for 'applets' to put there. If you have something you would dearly love to
  have on the status bar contact me and I'll consider writing a Plugin, or
  have a go at writing one yourself by using the source code of one of the
  samples.


Folders!!
=========

  The last object under the 'root' object ('Pilot Desktop') is the root
  branch of the 'Folders' area. This is a new concept to Pilots. Here you
  can create your own Folders (or directories, if you like) using the 'New...'
  action in the context menu. Here, you can have any number of sub-folders,
  and folders in folders. You can also create, move or copy any PIM object
  (Memo, To Do, etc.) here.

  Have a play with them, I'm sure you'll find them very useful.

NOTE:  not all of the above features are completed yet, but will be very soon.

NOTE:  For standard PIM objects, they are still stored under the usual
       application's databases, but are put in an 'unused' category. See
       below for more on this topic.


Standard PIM Objects (Memo's, To Do's, etc.)
====================

  For the 'Memo', 'Address' & 'To Do' application entries in the tree, you
  can now select their 'view/edit' action. This pops up a dialog asking you
  for your preferred 'unused' category for that application. As the PIM objects
  can be moved to or created in a Folder they must be 'marked' as being in
  a Folder (NOT a category). So, you must nominate ONE of your categories (in
  each application) to be the 'unused' one.

  By default this category is the 'Unfiled' category (for all PIM apps). This
  is why you may have noticed some of your records don't show up.

  Just select a category (must be empty) and Explorer will automatically update
  all existing Folder objects of the application type you are modifying, to the
  new 'unused' category, and mark all new and moved objects from that
  application with this category.

  Select the Datebook's View/Edit action to pop-up it's configuration
  dialog. Here you can select whether you want the appointments to be
  displayed in ascending or descending order (ie. from oldest->newest,
  or newest->oldest).


Known Bugs
==========

  Various functions aren't implemented yet. You will see a dialog box when
  you select such a function. Below is a list of known problems:

     - To Do details dialog doesn't show or update due date.
     - Setting an appointment with an Alarm will not cause an alarm
       to be issued. This will be implemented soon!
     - Some users have noticed conflicts with the 'Hack Extensions'
     - Low memory conditions can cause problems in redrawing.
     - There is currently a limit of 512 elements on the size of the whole
       tree. If this is reached a fatal error is issued. This will be improved
       shortly, automatically collapsing branches that are not in use.

  If you discover new bugs please contact me by Email at:

      scottpowell@kagi.com


Future Directions
=================

* With the open-endedness of Plugins, there should be (hopefully) many
  interesting and usefull extensions available in the near future.

* Backup/Restore of Folder database.



Revision History
================

04/08/1997  1.4   - Minor touch-ups:
                     screen blank at startup in shareware version now fixed
                     vertical separator goes all the way to the left sometimes,
                          now puts it back to the right when this is detected.

07/07/1997  1.3   - Added expiry reminder at start of program.

23/06/1997  1.2   - Added 'History List', last 10 objects viewed,
                      accessable from Status Bar icon.
                    Moved PIM object access to a Plugin, pimapps.prc.
                    Can now create and update Address & Datebook objects.
                    Datebook now has configuration dialog (select it's
                      View/Edit action). Can now view appointments in
                      ascending or descending order.
                    Improved dynamic heap usage, less memory being used.
                    Wrote simple 'calculator' plugin.

15/06/1997  1.2pr - Added comprehensive Plugin sample (for developers)
                    Fixed Datebook date display error

13/06/1997  1.1   - Added 'Select Unused Category' functionality (launched
                        from PIM app's 'view/edit' action)
                    Can now create To Do's  (from 'New..')
                    Fixed problem when creating new PIM object, then updating
                         (need for synchronization could be missed)
                    Extra capabilities for status bar applets
                          - can now capture pen input if they want
                          - can handle 'drag & drop' events (TrashCan is
                              example of this)
                    Implemented scrolling of status bar.

10/06/1997  1.0   - Commercial release
                    Finished functionality of Folders (new/move/delete)
                    Created 'Plugin' interface.
                    Created status bar interface.
                    Created Folder soft-type interface.

03/06/1997  0.1b  - Initial version (beta)


Credits
=======

  thanks to:
     - John J. Lehett        for the GNU 'C' port.
     - Wes Cherry            for 'PILRC'


Standard Disclaimer Stuff
=========================

  This program is presented 'as is'. I take no responsibility in any loss of data
  or productivity in case of operating failures.

