Generic UI Controllers: 5 GenToolControlClass

| Up: GEOS SDK TechDocs | Up | Prev: 4 Creating Your Own Controllers | Next: 6 GenToolGroupClass

GenToolControlClass is a subclass of GenControlClass ; the tool control allows the user to manipulate and manage all the other controllers in an application and save the configuration he or she sets up.

Previous sections of this chapter explain how to include a GenToolControl object in your application; this section details the specific structures, messages, and internals of GenToolControlClass . Most application programmers will never need to know this information, though some library programmers will want to read the next section.

GenToolControlClass has two instance fields beyond those inherited from GenControlClass . One field is the chunk handle of the Tool Location Table, and the other is the chunk handle of the Tool Group List, both defined below:

@instance ChunkHandle				 GTCI_toolboxList;
@instance ChunkHandle				 GTCI_toolGroupList;
    @default GI_states = @default | GS_ENABLED;

The Tool Location Table must be set up for any application that uses a GenToolControl. The structure of this table is given in Using Tools . The total number of allowable entries in the Tool Location Table is MAX_NUM_TOOLBOXES, which is 25. Because the GenToolControl uses one of these entries, you can have at most 24 other locations for a controller's tools to appear.

The Tool Group List is a list of all the GenToolGroup objects associated with controllers in the application. Each controller may have exactly one GenToolGroup object for managing its tools, and all the ToolGroups must appear in this list if the GenToolControl is to manage them. The Tool Group List is described in Using Tools .

GenToolControlClass also uses a vardata field to store temporary information about a particular controller; the tool control uses this information when presenting the user with options of where the controller's features may be placed. This vardata field is shown below (both the definition of the field and the structure it uses):

@vardata TempGenToolControlInstance
			 TEMP_GEN_TOOL_CONTROL_INSTANCE;
  typedef struct {
    optr		TGTCI_curController;
    word		TGTCI_features;
    word		TGTCI_required;
    word		TGTCI_allowed;
}  TempGenToolControlInstance;

The individual fields of the temporary structure are described below.

TGTCI_curController
The optr of the current controller whose tool options are being presented to the user. The GenToolControl allows the user to select and edit the features and location of this controller. If the user selects a new controller for editing, this field will be changed to the new controller's optr.
TGTCI_features
The mask of the currently active features of the controller.
TGTCI_required
The mask of the features which the controller object has defined as required--these must always be active and can not be "hidden" by the user. This mask is set by the controller with ATTR_GEN_CONTROL_REQUIRE_TOOLBOX_UI .
TGTCI_allowed
The mask of features that are allowed by both the controller and the application. Features set in this mask but not in TGTCI_features will be implemented but will be "hidden" from the user. Features not in either list will not be implemented by the controller for the application.

The GenToolControl uses a number of internal messages that should not be intercepted. You can, however, use the data structures of GenToolControlClass in a subclass and add functionality to the tool controller.

| Up: GEOS SDK TechDocs | Up | Prev: 4 Creating Your Own Controllers | Next: 6 GenToolGroupClass