!CPIShell 0.26 (12 Oct 2002)
=========

CPIShell (Configure Plug-In Shell) is a mechanism for launching
collections of related plug-ins. The shell will present the
user with filer-like window of plug-ins which can be launched
individually in a similar manner to the root plug-in window.

Syntax:
  Run <ConfigPluginShell$Dir>.!Run -dir <directory>
                                   -msgdir <messages directory>
                                   -openat <x> <y>
                                   -control <control class>
                                   -class <our class>

  -dir <directory> : Directory to search for plug-ins to
                     display.

  -msgdir <messages directory>
                   : Directory in which the messages live for
                     this application.

  -openat <x> <y>  : Configure plug-in protocol start-up

  -control <control class>
                   : Configure application class that we are
                     controlling (see configure protocol
                     specification for more details)

  -class <our class>
                   : Configure application class which we are a
                     member of (see configure protocol
                     specification for more details)

Messages file
-------------

The messages file of the CPIShell client (in the directory
given by -msgs) may contain a number of tokens which are used
by CPIShell:

   _ConfigWindowTitle:<title>
       Title of the window for the configuration window.

   _ConfigSetMessage:<message>
       Message to display when the Set button is pressed.
       This might be used for a warning about the details that
       have been configured.


Plug-ins as children of the CPIShell may contain a number of
tokens in addition to those defined by the configuration
plug-in protocol:

   _FadeIfVariable:[-+]<variable>...
       The plug-in will be faded, dependent on whether the
       variable specified is set (if + is specified) or unset
       (if - is specified).

   _FadeIfModule:[-+]<module>...
       The plug-in will be faded, dependent on whether the
       module specified is present (if + is specified) or
       absent (if - is specified).

   _FadeIfPodule:[-+]<product-type>...
       The plug-in will be faded, dependent on whether the
       podule specified is present (if + is specified) or
       absent (if - is specified).

   _ConfigHelpFaded:<message>
       Help message to display if the plug-in is faded.

   _ConfigHidden:<anything>
       If _ConfigHidden is specified, the plug-in will not
       be included in the list. This is different from faded
       plug-ins in that the user is not even presented with a
       faded plug-in. This is only useful to hide configuration
       which would otherwise cause conflicts with a later
       OS version.

   _ConfigMaxOSVersion:<three-digit-version>
       If _ConfigMaxOSVersion is specified, the plug-in will
       not appear if the OS version exceeds that supplied;
       that is it will be treated as if the 'hidden' flag
       above had been set. The OS version actually being
       checked is that provided by the variable Boot$OSVersion.
       This means that the final digit will always be a zero.
       For example, for a component which applies to RISC OS
       4.00 only, one would use 400.

_FadeIfVariable and _FadeIfModule can be extended by the use of
conjunction operators. These are provided for simple evaluation
of the context; they are not nestable. Conjunction operators
must be space separated. Only & and | are accepted as
conjunctions for logical AND and OR operations. For example:

   _FadeIfModule:-SCSI & -SCSIFS

would fade the plug-in if neither SCSI nor SCSIFS modules were
present.


Installing new plugins
----------------------

Installing a new plugin within a CPIShell application is
achieved by dragging the plug-in to the CPIShell window. The
application will be identified as a plugin by the existance of
the _ConfigSprite token in the messages file of the plug-in.
Applications without this token may not be installed.

Plug-ins to be installed should contain the following token in
their messages file :
   
   _ConfigOSVersion:<three-digit-version>
       This token determines what OS version the plugin applies
       to, and to where it will be installed. If this is not
       present, the plugin will be installed into the RO400Hook
       directory, for compatibility with earlier OS versions.
       Most commonly, this will be set to 420 or 400.
