Class Documentation

Name:TabFocus
Version:1.0
ID:ID_TABFOCUS
Status:Stable
Category:GUI
Date:January 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2003-2004. All rights reserved.
Short:  Manages the 'user focus' via the tab key.



Description

The TabFocus class manages the use of the tab key and its relationship to the user-focus in the GUI of each application. To create a tab-list, you only need to pass a list of focus-able objects that are in the application window. As the user presses the tab-key, the focus will switch to each drawable in the list, following the order that you have specified.

Objects can be added to the tabfocus using the AddTabObject method for individual objects, or you can set the Objects field for a mass addition. Some GUI classes such as the Button support a TabFocus field that you can set and this will cause it to automatically add itself to the referenced tabfocus object.

Actions

The TabFocus class supports the following actions:

Activate  Moves the focus to the next object in the focus list.
Clear  Flushes the tab list.

Methods

The TabFocus class implements the following methods:

AddTabObject  Adds a new object to the tab list.
InsertTabObject  Inserts a new object in the tab list.
RemoveTabObject  Removes an object from the tab list.
SetTabObject  Changes the object for a specific index.

Structure

The TabFocus object consists of the following public fields:

Object  New objects may be set at specific indexes via this field.
Objects  A string sequence of objects to be added to the tab list may be set here.
Method:AddTabObject()
Synonym:AddObject
Short:Adds a new object to the tab list.
Arguments:
OBJECTID ObjectID  Reference to the object to be inserted.

New objects can be added to the tab list by calling this method. The object can be of any class type, but it must support the Focus action or it will not be able to respond when the tab list attempts to use it.

Once the object is added, the user will be able to focus on it by using the tab-key.


Method:InsertTabObject()
Synonym:InsertObject
Short:Inserts a new object in the tab list.
Arguments:
LONG Index  The index at which the object should be inserted.
OBJECTID ObjectID  The ID of the object that you want to insert.

New objects can be inserted into the tab list by calling this method. You need to provide the unique ID for a drawable object, or the routine may fail. Some intelligence is used when non-drawable objects are passed to this method, whereby the routine will check for Region and Drawable fields to discover valid drawable objects.

Once the object is inserted, the user will be able to focus on it by using the tab-key.

Result
ERR_Okay  The method succeeded.
ERR_Args  Invalid arguments were specified.
ERR_OutOfRange  The index is out of range.

Method:RemoveTabObject()
Synonym:RemoveObject
Short:Removes an object from the tab list.
Arguments:
OBJECTID ObjectID  A reference to the object that you want to remove.

Use the RemoveObject() method in instances where you need to remove an existing object from the tab list. You only need to provide this method with the ID of the object that you want to remove.

Result
ERR_Okay  The object was removed, or did not already exist in the tab list.
ERR_Args  Invalid arguments were specified.

Method:SetTabObject()
Synonym:SetObject
Short:Changes the object for a specific index.
Arguments:
LONG Index  The index in the tab list that you want to set.
OBJECTID ObjectID  The ID of the object that you want to set at the specified Index.

The tab list may be manipulated on a more direct basis by using the SetObject() method. It allows you to change the object ID for a specific index point.

Result
ERR_Okay  The method succeeded.
ERR_Args  Invalid arguments were specified.
ERR_OutOfRange  The specified Index was out of range.

Field:Object
Short:New objects may be set at specific indexes via this field.
Type:STRING
Status:Set

The Object field provides a field-based way of setting objects at specific indexes. An object can be set by specifying the index number, followed by the ID of the object that you want to set. The following is a valid example, "3:-9495". The index and object ID can be separated with any type of white-space or non-numeric character(s).


Field:Objects
Short:A string sequence of objects to be added to the tab list may be set here.
Type:STRING
Status:Set

A string sequence of objects may be added to the tab list via this field. Objects must be specified as ID's and be separated with white-space or non-numeric characters. The following example illustrates a valid string "7984, #9493, -4001".