Configure (changes)

Showing changes from revision #7 to #8: Added | Removed | Changed

Programmer's Reference Manuals

» Configure

User interface for Configure plugins

Action buttons

Configure plugin windows should have “Set” and “Cancel” action buttons, and where appropriate, a “Default” one to restore sensible factory defaults.

Interactive Help

Interactive help messages should also be standardised across all plug-ins. Wherever possible, the interactive help messages shall take one of these forms, where *** should be replaced with whatever is appropriate under the circumstances, and |M is the usual sequence telling !Help to insert a line break:!Help to insert a line break:

Messages File

The plug-in’s Messages file should contain three tokens:

Displaying Icons

Each icon in the main window has three attributes which the central application has to determine, but which are best known to the plug-in:

1. the (brief) textual name
2. the sprite to use
3. the interactive help string

Method for displaying Icon Sprite for compliant PlugIn

Configure will *IconSprites a file called CoSprite (or CoSprite22 etc. according to the usual convention) within each plug-in to ensure the sprite is available. To avoid name clashes with other Wimp sprites, the sprite names will be prefixed with the three characters “co_”.

Each plugin should use specify the sprite name within the Messages file’s _ConfigSprite token. The appropriate !Sprites sprite for each plug-in will be different from the CoSprite sprite, because the latter is not constrained by the 68×68 OS units rule. If no better sprite is available, the “!configure” sprite may be re-used.

Method for displaying Icon Sprite for non-compliant PlugIn

In order to support protocol-ignorant applications as plug-ins, the following rules are followed:

• by default the text will be the name of the plug-in application (excluding the ! character)
• the sprite will be the name of the plug-in application (excluding the ! character)
• the help text will be a generalised string

Note: The above rules are a fallback position, and must not be relied upon by applications intended for use as plug-ins.

Information Transfer

In order to support as many existing configuration applications as possible, messaging supported by a plug-in can be limited to Message_Quit, although this will result in inconsistencies in window positioning.

Window positioning is handled via two routes: when the plug-in is started through Wimp_StartTask, the preferred co-ordinates of the top-left corner of the new window (in decimal OS units) are passed as arguments on the command line. A typical command line thus ends:

…!InetSetup -openat 120 844

(If the plug-in is started without this command line argument – eg if its application directory is double-clicked from a directory display – it must centre itself on screen instead.)

The other communication is necessary to bring the window to the top of the stack when the user clicks on an icon in the main window, and the plug-in window in question is already open. This is handled by Message_OpenConfigWindow.

The other main messaging is involved with allowing plug-ins to object to being quit, for example if complex selections have been made but not yet set. This is handled by the plug-in Quit protocol.

There has been another operation in the past where information was passed between parent and child configuration windows: Adjust-clicking on the close icon of a child would re-open the parent if it had been closed due to an icon in the main window having been clicked using Adjust. This would be difficult to implement across different tasks, and near impossible where the child task predates any release of the new specification of Configure. Instead, we will take advantage of the Style Guide convention that windows having a “Cancel” action button don’t have a close icon, and apply that convention to all plug-ins; the main window will no longer close when Adjust is used to click on an icon.

Locking

The central application is responsible for detecting whether the condition of the machine is unsuitable for configuration – a comparatively complex decision based upon whether the machine is remotely or locally booted, the <Choices$Write> access permission and the condition of FSLock.

Since the plug-in applications are located deep within !Boot, it is assumed that the average user will only ever access them through Configure, which only allows the plug-ins to be loaded when the machine is in a configurable state.

The alternative invocation method involves double-clicking on the plug-in application directly. Rather than requiring each plug-in to duplicate the lock detection code from Configure (which might conceivably be subject to change at a later date anyway), the plug-ins must not complain if a write operation to disc or CMOS fails. However, the settings must still be applied for the current session even if such a failure occurs; this will allow more knowledgeable users to adjust the operation of even locked machines where an alternative GUI is not available (eg mouse speed, Filer filename width, screen saver textual message).

Data Interchange

With the introduction of modularity into Configure, a limited amount of messaging will be introduced between the main application and the plug-ins. This is designed to provide the best possible results when third party configuration applications which are unaware of the protocol are used as plug-ins. There are three separate message protocols involved.

Quit Protocol

Applicability: all plug-ins where selections would be fiddly or time-consuming to repeat – the boot sequence editors, for example.

The established Message_PreQuit method cannot be used to warn plug-ins that they are about to be killed (which can happen either because of a click on the close icon of the main window, or because of the activation of FSLock). The problem is with the re-initialisation of the procedure if the user confirms that they do indeed want to quit anyway; Message_PreQuit allows only for the quitting of a single task or for the termination of the entire desktop.

When the central application receives a close window request, a Message_PlugInQuitContinue, or a Message_FSLockStateChangeRequest for a lock status of 2, it will broadcast Message_PlugInQuit with event type 18. If no plug-in responds, the Wimp will return the Message_PlugInQuit to the central application, which will then send a Message_Quit to each plug-in individually (except the Lock plug-in, in the case of lock activation).

This protocol is also used between top-level and second-level plug-ins in a similar fashion when necessary. The main difference is that the Message_Quit contains a flag word to indicate whether the quit was generated by a click on “Set” rather than “Cancel”, because in the former case the plug-in may assume that the user wants to set the selection (and need not therefore generate a Discard/Cancel/Set dialogue box).

Plug-ins must behave as follows (in addition to handling Message_PreQuit as normal) if they wish to be able to object to being quit:

Initialisation

• Set “complain” flag

Message_PlugInQuit received

• If “complain” and “modified” flags are set
  • acknowledge the message so that it isn’t returned to the central application;
  • query the user whether they want to “Discard”, “Cancel” or “Set” (this can span Wimp_Polls);
  • if “Discard” or “Set” is selected,
    • clear “complain” flag;
    • send Message_PlugInQuitContinue to the task that broadcast the Message_PlugInQuit
  • else (ie “Cancel” is selected),
    • broadcast Message_PlugInQuitAbort

Message_PlugInQuitAbort received

• Set “complain” flag, ready for the next time