Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: More Macintosh Toolbox /: Chapter 8 - Control Panels / Creating an Extension for the Monitors Control Panel

Supplying Optional Resources for a Monitors Extension
Your monitors extension file can also include any of the optional resources described in this section. To create these resources, either you can specify the resource description in an input file and then use a resource compiler, such as Rez, to compile the resource, or you can use a tool such as ResEdit to create your resources in a resource file.
The optional resources and their resource IDs are

The icon family resources ('ICN#', 'ics#', 'icl8', 'icl4', 'ics8', and 'ics4'), which specify an icon for display in the upper-left corner of the Options dialog box: resource ID -4096.
The version ('vers') resources: resource ID 1 and 2.
The string list ('STR#') resource: resource ID -4096.
The gamma table ('gama') resource: resource ID from -4080 through -4065.
The file reference ('FREF') resource. The resource ID follows the normal conventions (typically, you assign a resource ID of 128).
The bundle ('BNDL') resource. The resource ID follows the normal conventions (typically, you assign a resource ID of 128).
The icon family resources ('ICN#', 'ics#', 'icl8', 'icl4', 'ics8', and 'ics4'), which define the monitors extension file icon. The resource ID follows the normal conventions (typically, you assign a resource ID of 128).
The system extension ('INIT') resource.
The signature resource: resource ID 0.

In addition to the optional resources that these sections describe, you can include
private optional resources whose resource ID numbers must fall within the
range -4080 through -4065.

Specifying an Icon for the Options Dialog Box
To specify an icon that the Monitors control panel displays in the upper-left corner of the Options dialog box, you can define one or more members of an icon family. For each of these resources, you must assign a resource ID of -4064. If you provide an icon family, the Monitors control panel displays the appropriate icon according to the bit depth of the monitor. (Note that in System 6 you provide 'ICON' or 'cicn' icons instead of an icon family.) For more information on these icons, see the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials.
If you do not supply either of these icon resources, the Monitors control panel displays the icon defined in the sRsrcIcon entry of the sResource data structure of your video card's ROM. If your do not supply either of these resources and your video card does not include an icon, the Monitors control panel displays a generic icon that represents a monitor.
Listing 8-20 shows a partial listing of the icon family resources that define the SurfBoard video card icon shown in Figure 8-13 on page 8-51.
Listing 8-20 Rez input for icon family resources for a monitors extension
data 'ICN#' (-4064, purgeable) {
   /*icon data goes here*/
};
data 'icl8' (-4064, purgeable) {
   /*icon data goes here*/
};
data 'icl4' (-4064, purgeable) {
   /*icon data goes here*/
};
Specifying Version Information
You can include two kinds of version resources of type 'vers' to provide version information for your monitors extension file. The version resource with a resource ID
of 1 specifies the version of your monitors extension file. The version resource with a resource ID of 2 specifies the version of the group to which your file belongs--for example, the version number of the video card that your extension file supports.
The Finder displays version information about your monitors extension for the user. For complete information on how to specify the version resources and how the Finder displays the information from these resources in its information window, see the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials.
Listing 8-21 shows a version resource with a resource ID of 1 that specifies the version number of the SurfBoard's monitor extension file. This version resource includes the copyright of the River Change Systems company, which manufactures the card.
Listing 8-21 Rez input for a version ('vers') resource
resource 'vers' (1) {
   0x01, 0x00, release, 0x00,
   0, /*verUS*/
   "1.00",
   "1.00, Copyright © 1993 River Change Systems."
};
Providing an Alternative Name for a Video Card
The Monitors control panel displays the name of your video card in the upper-left corner of the Options dialog box. By default, it displays the name defined in the declaration ROM of the video card. To display a name for your video card that is different from the name in the declaration ROM of the video card, you can include a string list ('STR#') resource with resource ID -4096. This resource must contain pairs of Pascal strings. The first string in each pair must be identical to the name of your video card as specified in the sResource data structure in the ROM of the card. (For more information on the sResource data structure, see Designing Cards and Drivers for the Macintosh Family, third edition.) The second string in each pair is the name that you want to display in the Options dialog box. You can have as many pairs of names in one string list resource as you wish; the Monitors control panel uses the first match it finds.
It is unlikely that you will need to override the name specified in the declaration ROM. However, if you have misspelled the card name on the board, or if you want to display a name that is more descriptive, you can include a string list resource. Listing 8-22 shows the string list resource for the SurfBoard video card monitors extension. This monitors extension includes two card resources (see Listing 8-17 on page 8-52), but the string list resource includes only one entry to override the name SurfBoard Super Display Card. In this example, when the Monitors control panel displays the Options dialog box for the SurfBoard Super Display Card, it displays the name SurfBoard Super Fast Display Card instead of the name in the card's declaration ROM.
Listing 8-22 Rez input for the SurfBoard string list resource
resource 'STR#' (-4096, purgeable)
{
   {  "SurfBoard Super Display Card";
      "SurfBoard Super Fast Display Card"};
};
Supplying Gamma Table Resources
To indicate status as a superuser, the user presses the Option key while clicking the Options button in the Monitors control panel. In response, the Monitors control panel displays a list of gamma tables (see Figure 8-12 on page 8-50).
The software driver for a video card uses a gamma table to correct for the fact that the intensity of each color on a video display is not linearly proportional to the intensity of the electron beam; in other words, the gamma table helps the video driver to provide the most accurate colors possible for a video display. Because the user might prefer a nonstandard color correction, many developers of video cards provide more than one gamma table for a given card.
To supply one or more gamma tables for a video card, include in the monitors extension file a named resource of type 'gama' for each gamma table. To change the default gamma table for a monitor, the user clicks the Use Special Gamma checkbox and then selects a table by clicking its name in the list. The default gamma table for a monitor is the one listed in the screen resource of type 'scrn'. For a complete discussion of gamma tables, see Designing Cards and Drivers for the Macintosh Family, third edition. For information on the screen ('scrn') resource, see Inside Macintosh: Devices.

Creating File Reference, Bundle, and Signature Resources
The file reference ('FREF'), bundle ('BNDL'), and signature resources work together to give your file a distinctive appearance on the desktop. The Finder uses these resources to display the icon for your monitors extension.
The file reference resource specifies the file type for a monitors extension ('cdev'), the local ID of your icon list resource, and an empty string. The local ID maps the monitors extension file type to the icon list resource that is assigned the same local ID in the bundle resource. Listing 8-23 shows the file reference resource for the SurfBoard monitors extension.
Listing 8-23 Rez input for a file reference resource of a monitors extension
resource 'FREF' (128, purgeable) {
   'cdev', 0, ""
};
Note
If you provide the complete icon family, the Finder displays the appropriate member of the icon family according to the bit depth of the monitor.
The Finder uses the signature resource with the bundle resource to establish the identity of your monitors extension. You define a signature resource as a string resource (that is, a resource of type 'STR ') and specify as its resource type a unique four-character sequence that has the same value as your monitors extension's creator type. The signature resource contains a string that identifies your monitors extension; typically the string specifies the name, version number, and release date of the monitors extension.
A bundle ('BNDL') resource associates all of the resources that the Finder uses for your monitors extension. It associates your monitors extension and its signature with its icon. The Finder requires the information in the bundle resource to display icons for your monitors extension. In the bundle resource, you must specify a local ID for your icon
list resource that matches the local ID you assigned inside the corresponding file reference resource. In the bundle resource shown in Listing 8-24, local ID 0 is assigned to the icon list resource with resource ID 128, mapping the icon defined for the SurfBoard monitors extension to the monitors extension file.
Listing 8-24 Rez input for a bundle resource of a monitors extension
resource 'BNDL' (128, purgeable) {
   'kcah',
   0,
   {
   'ICN#', {0, 128},
   'FREF', {0, 128}
   }
};
(See the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials for complete information on how to create file reference, signature, and bundle resources.)

Including a System Extension Resource
A file that contains an extension to the Monitors control panel can contain a system extension resource of type 'INIT'. If your monitors extension file is in the Control Panels folder, the Extensions folder, or the base level of the System Folder, then the system software executes the system extension resource when the user starts or restarts the computer.
Although the system extension resource acts independently of other resources in the file, it should be related to the monitors extension.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.