Interface Controller Package  
  -v0.5A-  

[What it does] [How it works] [CTRL_REG.SRC] [Control gump] [Interface script] [Requirements] [Examples] [Credits]

What it does

The "Interface Controller Package" [ICP] is a package that allows GM's to keep a structured overview of all their installed packages, assuming they register with, and conform to the requirements of, this package.


How it works

ICP is installed, just like any other package, by being placed into the '/pkg' directory. Unlike most optional packages, however, it is not installed into the '/pkg/opt' directory! It's a control-package and, as such, defaults to the root '/pkg' folder. If you extract this archive, as-is, into your '/pkg' directory, it should have created the /pkg/control folder, automatically.

As can be seen in the requirements section of this help-file, this package requires the Gumps package (at least revision v2.1) and Sigismund's 'string.inc' file (at least revision v1.2). These should both be found on the ONElist, in the files section, under the '/OptionalPackages' and '/Includes' folders, respectively.

* NOTE: This is not a set of control scripts and should not be extracted into the /scripts/control directory! *

Once installed, ICP initialises, automatically, when the server first starts up, recurses through the entire list of loaded packages and calls a predefined script (ctrl_reg.src) which is, optionally, defined by each package. This script should then return a structure, containing specific information, which is used by ICP to append it to the end of the list of registered packages. This list is then stored, globally, and used, at a later time, by the Control Gump which is called up using the .control dot-command.

Once the server is running, the list of registered packages can be refreshed by issuing one of two commands:

    .control -r
    .control -refresh
Please refer to the "Control Gump" section for what the .control command does with no parameters.


CTRL_REG.SRC

The information within the structure, returned by the ctrl_reg.src script, is quite specific. The definition is as follows:

  • User-friendly name   (string)
    This is the name shown on the ICP control gump. It's a "friendly name" so as to be easily identifiable to the user.
  • Version number   (string)
    This is a string form of the version number of the package (which should, really, be the same as the version number given in the package's pkg.cfg file)
  • Whether it has a "user interface" or not   (integer)
    Any package that has a "user interface" [UI] (whether it be an informational gump, a gump for altering the package's settings or a system-message spam of commands) would pass an integer value of 1 (one) for this parameter. The lack of a UI would define the package as "listed only for the convenience of the user" and would require an integer value of 0 (zero) to be passed as the parameter.
  • If it has an interface, which script do we call?   (string)
    If a UI exists for a package then this parameter holds the name of the script (excluding the .src extension) to be initiated when a package is selected from the control gump. Please note that the ICP script will auto-prepend the script name with the package name (eg. with :control: in the case of the ICP) and, as such, expects only the unqualified script name, itself. It can, however, specify a path to follow from the package's root folder; thus, making it possible to specify a dot-command script as the interface script! (See the 'textcmd.src' file in the '/examples' directory within this package for a pre-written example of how this is implimented)

The structure should have the following member variables (examples are given based on the structure returned by ICP's own ctrl_reg.src script):

    Member Variable Example Value
    .sName "Interface Controller"
    .sVer "0.5a"
    .bCtrl 0
    .sScript ""

The Control Gump

The Control Gump is ICP's main display, accessed by the .control command (without any parameters), which shows the list of installed packages that have registered with ICP via the ctrl_reg.src script-mechanism.

In the list, each package is shown by its "friendly name" and its version number. If the package has been registered as having an interface, then there is a small blue button to the left of the name; press this button to close the Control Gump and bring up that package's interface (what this interface looks like, is entirely dependant on the package in question... although, a document detailing a "standard look" will be available, soon)

You can close the Control Gump, without choosing a package, by either right-clicking it or clicking the <Cancel> button at the bottom right.


Interface Script

There are at least two things an interface script MUST cater for when it is called:

  • An ICP test-call
    When a package is registered as having an interface script, ICP tests to see whether the specified script is valid before it adds it to it's internal list... if your script can't pass back the correct value (a simple non-zero integer), then it will be assumed to be invalid. (See the 'textcmd.src' and 'normal.src' scripts in the '/examples' directory within this package to see how interface scripts should interpret their parameters)
  • An ICP start-call
    This call is made when a user presses the blue interface button to the left of a package-name on the Control Gump. Since the script must recognise when it's the ICP is calling it and when it's not, you can do initialisation, here, that you may not do normally (I'm not sure if, or where, this would be useful, but the functionality is there for you to use as you will :-) )

NOTE: An interface script cannot do anything other than return the non-zero value during the test-call, as this is done during the server's initial start-up phase! There is no user attached to the call so creating gumps, or calling user-interactive functions, will cause your script to fail the ICP's test-call and may even print erroneous error messages to the console! You have been warned!


Overview of Package Requirements

Firstly, to use ICP you must be running version 088 of the POL core. This is not an option; you must be running that core version, at least!

You must also have, at least, v2.1 of the 'gumps' package installed, and enabled, and Sigismund's 'string.inc' file, of at least v1.2 (if you need to recompile the ICP package, for some reason, then the 'gumps' package must be in the root '/pkg' directory alongside ICP, otherwise you'll need to amend the "include" path in the 'check_packages.src' script!)

Then, to become properly registered, a package must adhere to, and fulfil, the following requirements:


Example scripts

Within this package you'll find a .ZIP file called examples.zip. If you extract this archive into ICP's directory it should automatically create an '/examples' folder with three sub-directories. These sub-directories contain the example package configurations as detailed in the following table:

Package Directory
(and description)
Filename Description
/examples/normal mainscript.src A dummy file that represents the "main script" for this package. :-)
Type: Normal
Interface: No
ctrl_reg.src The registration script for this example package.
pkg.cfg The package-config file for this example package.
/examples/interface interface.src The script that holds the "interface code" for this package. This is the script that needs to deal with the "test-call" mechanism.
Type: Normal
Interface: Yes
ctrl_reg.src The registration script for this example package.
pkg.cfg The package-config file for this example package.
/examples/textcommand /textcmd/gm/textcmd.src An example script that shows how to double a GM's text-command script as an interface script.
Type: Advanced
Interface: TextCmd
ctrl_reg.src The registration script for this example package.
pkg.cfg The package-config file for this example package.

Please note, if you compile up these examples, they will show up in ICP's Control Gump, when you restart the server, as the POL core sees them as nested packages. This cannot be helped, nor altered, by ICP. Sorry.


Credits :-)

Credits, thanks and kudos to the following people (in no particular order other than an alphabetical one :) for all the moral support and bug-testing and, in particular, Syzygy for tweaking the POL-core to allow the core of this package to work! :-)

AlleyCat Cassandra Louds Madman Mieow
Moravi Seilar Syzygy ToriOtoko Ynara


[What it does] [How it works] [CTRL_REG.SRC] [Control gump] [Interface script] [Requirements] [Examples] [Credits]

Core scripts, example scripts and help files created by Myrathi, 11-Apr-2000.
These scripts may be used and modified freely. All the author asks is that he's given appropriate credit for the original script. :-)