Programming around Delirium
===========================

Several features have been added to Delirium to help application writers
integrate their applications more neatly into Delirium.

These features are provided in good faith, in the hope that they will be
useful. Kulture do not accept any responsibility for damage caused by
the use or misuse these features.

If anyone has any suggestions for new Delirium features, please let us
know at the address in the main Help file.


Everything in this file is "as of version 2.20". You are advised to
"RMEnsure Delirium 2.20" before using any of these features.


Controlling Delirium
--------------------

The following star commands are available, which allow a certain degree
of control over what Delirium is doing.

Delirium_Desktop

        This command is provided for the WIMP mainly, and shouldn't
        really be used unless you know what you are doing! ;)

Delirium_ShowIcon

        Asks Delirium politely to show its iconbar icon. If the icon is
        already visible, nothing happens.

Delirium_ToggleIcon

        This will toggle the visibility of the iconbar icon. It's the
        same as Delirium_ShowIcon, except that if the icon is currently
        visible, it'll be hidden.

Delirium_ReclaimVectors

        This forces Delirium to reclaim the keyboard/mouse vectors.

        Why? - Well, certain applications can claim these vectors, and
        prevent them getting through to Delirium. This was characterised
        by early versions of Delirium not detecting key presses when
        the PC card was running full-screen. Issuing this command
        ensures that Delirium is at the top of the list of vector
        claimees, so it always gets 'em.

        When the PC card software starts up, Delirium will automatically
        reclaim the vectors.

        You are /very/ unlikely to ever need to use this command.

Delirium_Disable

        Totally disables Delirium. Useful if, for whatever reason, you
        decide you don't want Del to dim/blank your screen. Potentially
        handy to prevent blankouts when running a demo...

Delirium_Enable

        Enables a disabled Delirium.

Delirium_StartSaver

        Asks Delirium to start the currently selected saver. This has
        exactly the same effect as clicking on the 'Test' button in the
        Delirium configure window.

        If there is a saver already running, nothing will happen.

Delirium_StopSaver

        Guess what? It stops a running saver. If there isn't a saver
        running, then it has no effect.

        Note: if the user has configured a password, then
        Delirium_StopSaver will not fully stop the saver, but rather
        show the password screen. If you want to stop a saver, and only
        carry out a certain action when the desktop has fully returned,
        see the section below on Monitoring Delirium...


Monitoring Delirium
-------------------

At the moment, there isn't much you can do to monitor Delirium's
activity. However, there is one very useful system variable that you
might want to be aware of:

Delirium$Saving

        This system variable can be read at any time to see if a screen
        saver is running or not. If a saver is running, it will be set
        to "1"; if not, it will be set to "0".

        If password protection is enabled, this variable will remain set
        at "1" until a user has successfully entered a correct password.
        This can be useful if an application wishes to wait until a
        saver has completely finished before carrying out a certain
        action.

        For example, if I wanted to show a message on the screen, I
        might do the following:

          Firstly, check if a saver is running with <Delirium$Saving>

          If there isn't a saver running, show my message and finish.

          If there is a saver running, issue the Delirium_StopSaver
          command. Then, periodically check the status of the
          <Delirium$Saving> variable. When this variable changes from
          "0" to "1", I know it is safe to show my message.


