onCue comes with a configuration file config.txt (in the lib folder) that you can change to affect its behaviour. The main things that you can modify are:

• the window's size, position and decoration
• the fading behaviour of the icons
• the window's colours
• the web browser that you wish to use
• the clipboard adapter that you would like to use
• the Qbits (things that onCue can do) that are enabled

Configuration is only recommended for those users who feel confident fiddling with text files. For most users the defaults will be fine. In future releases we will provide easier ways of setting up onCue's options.

Remember, as when editing any configuration files, it is a good idea to keep a copy of the original so that you can go back to it if everything suddenly stops working!

config.txt is a standard Java properties file. You can use the # character to comment out unwanted lines.

Automatic Behaviour

com.aqtive.update.check and com.aqtive.registration.send

These parameters accept a 'yes' or a 'no' and control whether onCue automatically checks for new versions with our website, or sends registration information automatically respectively. The check for updates occur only when you are already connected to the Internet, and should not impact your on-line time or system performance. Registration information is only sent once - if you wish to inspect what is sent, see registration.txt in this folder.

Window Configuration

com.aqtive.window.xpos and com.aqtive.window.ypos

These parameters accept integer numbers and define where the window should open on the screen when the program is first run. The values are the distance in pixels from the top left hand corner of the screen. Negative values can be given to specify distances from the right hand side and bottom of the screen respectively. The default values are -94 and 20.

com.aqtive.window.cols and com.aqtive.window.rows

These parameters control the initial size and shape of the window. The numbers are integers stating the number of columns and rows of icons to allow space for. The default is 3 columns and 6 rows.

com.aqtive.window.iconcol and com.aqtive.window.iconrow

These parameters specify where the aQtive icon should appear in the window. The values should be integer numbers and give the column and row to use in the window. The top left hand corner is 1, 1. Negative values specify the distance from the bottom right. The defaults are -1, 2.

com.aqtive.window.frame

This parameter takes a 'yes' or a 'no' and tells the program whether or not to put the window into a frame. By default the window does not have a border provided by the operating system, but there are times when this is desirable. For example under windows, this allows you to access the window from the taskbar. Under certain X window managers, the window only responds to the mouse and keyboard if it is in a frame.

com.aqtive.window.ontop

This parameter also takes a 'yes' or 'no' and specifies whether the window should float in front of all other windows or not. By default, it will if the operating system supports it.

Fading Behaviour

com.aqtive.fading.delay

This parameter defines the time to wait (in milliseconds) between frames when fading in the icons in and out. A shorter time period will result in the icons fading in more quickly, but will be more processor intensive. The default delay is 50 milliseconds.

com.aqtive.fading.steps

This parameter defines the number of frames to use when moving between a totally faded out image and a totally faded in image. The default number of stages is 25. A lesser number will make the icon appear more quickly, but will appear more jerky. The minimum number of steps is 1. A larger number will take longer, but will appear more smooth, values larger than 255 will not make any visible impact on the smoothness.

com.aqtive.fading.threshold: 11

When a service is being suggested again, but with slightly different data, it will not fade all the way out. This parameter specifies how many frames from being faded out that it should stop at. This parameter should be given a value somewhere between 0 and whatever the fading.steps parameter above is. The default of 11 is just over halfway faded out. A value of zero will cause it to fade out completely before being resuggested.

Colours

Most of the colours used by onCue can be configured by setting values in the configuration file. Colours are specified in the same way as they are in HTML (i.e. #RRGGBB where RR is a 0-255 value specified in hex for red etc.).

The list of colour properties that can be changed is given below. For each of the base property names given below it is possible either to configure one colour (e.g.com.aqtive.color.tip.fore: #000000) to be used in all screen modes, or to configure a variety for use in modes with different numbers of colours.

To specify the colours to use in modes with different bit depths (numbers of colours) simply specify the property name for that mode followed by the number of bits per pixel of that mode. You can specify colours for all bit depths from 1-24 and onCue will pick the appropriate one for the mode when it starts. If it is started in a mode which hasn't got an explicit entry, onCue will choose the nearest one. If a particular mode doesn't have a particular colour in its palette, onCue will let Java approximate to the nearest available colour.

For example, you could specify three entries, one to be used in 256 colour modes, one in 32 thousand colours and one in a 24 bit (true colour) mode:

com.aqtive.color.tip.back.8: #FFFFFF
com.aqtive.color.tip.back.15: #EEEEEE
com.aqtive.color.tip.back.24: #D4D5D6

Note that under Windows, Java thinks that a 16 colour mode has 8bpp so values less than 8 are generally not used.

The parts of the interface that you can specify colours for are:

com.aqtive.color.tip.fore
com.aqtive.color.tip.back
com.aqtive.color.tip.border

com.aqtive.color.menu.fore
com.aqtive.color.menu.back
com.aqtive.color.menu.border
com.aqtive.color.menu.hifore
com.aqtive.color.menu.hiback
com.aqtive.color.menu.gray
com.aqtive.color.menu.divider

com.aqtive.color.window.back
com.aqtive.color.window.icon
com.aqtive.color.window.border
com.aqtive.color.window.hifore
com.aqtive.color.window.hipress

Web Browser Configuration

com.aqtive.browser.class

This parameter tells the software which class to use as to access the system's web browser. By default it uses the com.aqtive.desktop.Browser class which is fairly general and can be tailored to specific installations by using the following com.aqtive.browser.* parameters.

However, in certain circumstances this class will not be able to control the browser in the correct manner. By changing the value of this parameter you can use your own class instead - it simply has to implement the com.aqtive.qbit.pattern.Browser1Pattern interface (which has three methods).

This allows other programmers to write wrappers that perhaps make use of a native library of code to do the appropriate things. For example, to make the software work on a Macintosh you might want to take advantage of MRJ specific methods, or use a library like JConfig to launch the browser.

com.aqtive.browser.name

If the browser class is the default one, this parameter allows you to change the name of the browser shown in the help message in the tool tip. By default this is 'your Web Browser', but you could specify 'Netscape Navigator' for example.

com.aqtive.browser.icon

If the browser class is the default one, this parameter allows you to specify which icon to use to represent the browser. This icon needs to be stored in the lib/images/com/aqtive/desktop/images directory and should be a gif or jpeg file 32x32 pixels big. The default is generic.gif, but an explorer.gif and a netscape.gif is also provided.

com.aqtive.browser.path

If the browser class is the default one, this parameter allows you to specify the location in the filing system of the program to use to launch a web browser. If you wish to use Netscape Navigator as your default browser for example, you would need to enter the path to the netscape executable/binary program. When changing this parameter, remember to escape backslashes with a second backslash - so for \ enter \\. Spaces in paths can be entered, and appear to work without any problems - an alternative to try would be %20 if they don't appear to work for you. The default is rundll32 which in combination with the appropriate argument below will use your default web browser, but you could use something specific like C:\\Program Files\\Netscape\\Communicator\\Program or C:\\Program Files\\Internet Explorer\\iexplore for example.

com.aqtive.browser.args

If the browser class is the default one, this parameter allows you to specify the command line arguments to pass to the browser program to tell it to show a particular URL. The parameter should specify the command string to use, with <URL> where the URL should fall in the string. By default this is url.dll,FileProtocolHandler <URL> which starts the default web browser, but for specific browsers you could use something like -remote openURL(<URL>) when using netscape on a unix platform. See the netscape documentation on command line options for more details.

com.aqtive.browser.path2 and com.aqtive.browser.args2

These parameters use the same form of data as path and args, but are used if the first call to the browser fails (if the browser class is the default one). For example, under Unix, the first call could be one to remotely control the web browser to go to the page. However this will fail if no browser is currently running. In that case, path2 and args2 could be used to start an instance of the browser and send it directly to the desired page.

Clipboard Configuration

com.aqtive.clipboard.class

This command tells onCue which class to use to gain access to the system's clipboard. On most systems a native piece of code will be needed to access all of the capabilities of the system. The class has to implement the com.aqtive.qbit.pattern.Clipboard1Pattern interface.

By default the Windows' clipboard is accessed via the com.aqtive.desktop.GrabClipboard class. A pure Java version is also provided for use in different circumstances. To use this class instead specify com.aqtive.desktop.PollClipboard for this property.

com.aqtive.clipboard.poll

If the clipboard.class is PollClipboard (which isn't the default) this parameter tells Java how often to check the system clipboard for changes. The default is every 3000 milliseconds (3 seconds).

Qbit Configuration

com.aqtive.qbits.xmlpath

This parameter tells the system where to pick up its list of Qbits from. The default is the qbits.xml file in the lib folder (paths are taken relative to the top level aQtive directory rather than to the config.txt file). This value won't normally need to be changed.

The qbits.xml file defines which Qbits (components) that are to be used in your version of onCue. The Qbits fall into two categories: recognisers and services. Recognisers are the Qbits that guess at what the information the user selected really is. Services are the action or data providing Qbits that make use of the information guessed at by the recognisers.

The qbits.xml file uses a standard XML format to list the qbits that are to be loaded into the system. If you don't ever wish to use a particular Qbit, simply comment out its entry in this file.

To do that, load the file into a suitable editor (such as notepad) and locate the <Qbit> entry for the service that you don't wish to use. Open an XML comment on the line before by typing the text <!--. Locate the end of the entry by finding the following </Qbit> line and close the XML comment after it by inserting the following text -->.

If you write your own Qbits, this is where they can be added to the system. Most Qbits are written in Java, but native Qbits are possible. It will also be possible for non-programmers to use XML to add certain simple sorts of Qbit. If you are interested in developing your own onCue extensions please see the Java developer community area on our web site for more details. Alternatively register with us or email us to ask for more details.