Recent Changes - Search:



The [iconref] command

This file documents the [iconref] command introduced in version 8.1 of AlphaX.


The [iconref] command lets you register icons to be used by some Tcl commands in Alpha. This will also allow third party packages to add icons for their own use and not to rely exclusively on the icons provided by Alpha in its resource fork.

The external icons can be stored in a ".icns" data file or in a resource file. A natural location for these files would be in an /Images folder located in one of the Application Support folders. But they can be located anywhere on the system.

Under OS X, the Icon Services take care of registering and managing icons for applications. The icons are identified by a creator and a type (four-character codes): internally, the [iconref] command uses Alpha's signature as a creator code to register the icon. The system, for instance, provides many preregistered icons (see the Icon codes section of the ToolbarCommand page on this wiki). Icon Services can provide icon data to multiple Mac OS clients, including the Finder, extensions and applications. The icons provided by Icon Services support a much larger palette of colors: up to 24 bits per pixel and an eight-bit mask.

The 'icns' resources (and .icns files) are preferred over other kinds of icon data because they provide a single source for icon data, as opposed to the variety of icon resources represented by ‘ICN#’, ‘icl8’ and other familiar resource types. Combining all icon data into a single resource type speeds up icon fetching and simplifies resource management. They also provide for 32-bit-deep icon data, deep masks (meaning an icon mask with upto 256 different levels of transparency) and huge icons (48x48 pixels), as well as the sizes contained in other icon resources.

Specifying an icon in Alpha

Several commands in Alpha have options which expect an icon reference. As explained above, icons are identified by a creator and a type. As a consequence, one just has to pass the creator and the type.

The creator is in fact optional: in the case of an icon registered via the [iconref register] command or an icon predefined by the System, one can omit the creator. If no creator is specified, Alpha first looks for an icon registered with the [iconref register] command and, if none is found, it looks for a System defined icon.

The syntax of an -icon option can thus take two forms:

     -icon {creator type}
     -icon type

where creator and type are four-character strings. For an icon registered with the [iconref register] command, the creator is ALFA. For a System defined option, the creator is macs.


The formal syntax of the [iconref] command is:

iconref subcommand ?options?

The possible subcommands are described below.

The [register] subcommand

This subcommand registers a new icon. The syntax is:

     iconref register ?-id resid? ?-file filepath? type

If the -id option is not specified, the file designated by the -file option is expected to be an ".icns" image file.

If the -id option is specified, the icon must be defined as a resource. In that case, the file specified by the -file option (if any) is expected to be a resource file (containing a resource map either in its data fork or in its resource fork), otherwise the command looks in the resource map of the application itself. The value of the -id option is the ID of the resource containing the icon data. This should preferably be an 'icns' resource; if not, it can be a classical icon family (ics4, ics8, icl4 etc.)

At least one of the -file or -id options must be specified.

The type argument is a four-character string (like an OS type) which will be used to refer to this icon. Normally all-lowercase codes are reserved by the System, so ensure that you use at least one uppercase letter to avoid conflicts. The Icon codes section of the ToolbarCommand page on this wiki gives a table of the main preregistered system types: these types can be used directly and do not need to be registered with the [iconref] command.

Note that there is no risk of duplicate registrations: if a type has already been registered, the previous icon reference is used.

The [unregister] subcommand

This subcommand lets you unregister a type from the Icon Services. Icon reference values are reference counted, so that the icon data represented by a particular icon reference can be shared by several clients simultaneously. Each client that uses a particular icon reference increments its count. When there are no more clients using a particular icon reference, the icon data associated with it is disposed of. The [iconref unregister] command just decrements the reference count. It thus claims that we are not a client anymore to this icon:

 	iconref unregister type


Here are some basic examples which can be executed from the Tcl shell in AlphaX. Suppose we have the image of a calculator in a file named calculator.icns and located in the /Images subfolder of the Application Support folder:

     set fname [file join $SUPPORT(user) Images calculator.icns]
     iconref register -file $fname "CALC"

This instruction registers the icon contained in $fname and associates it with the four-character type CALC. Now one can for example create a toolbar item using the registered icon type like this:

     set tbi [toolbar create -icon "CALC"]
     toolbar add $tbi

This works because the -icon option of the [toolbar create] command expects the type of a registered icon. Similarly the [hiview create] command also has an -icon option applicable for the creation of subviews containing an icon (bevel button, icon control, round button; etc.)

The icon to register could have been stored in a resource file, say calculator.rsrc. If it is defined in a resource of type 'icns' with ID 128, one would register it like this:

 	set fname [file join $SUPPORT(user) Images calculator.rsrc]
 	iconref register -id 128 -file $fname "CALC"

It is not necessary to specify the resource type. The command first looks for an 'icns' resource; if it does not find one, it automatically tries to find an appropriate icon among the other usual icon types. In order to designate a resource belonging to the application itself, just omit the -file option. For instance (272 is the ID of the CMacTeX icon):

     iconref register -id 272 "CMTX"

(add your comments here...) bd Alpha's core should probably keep track of registered icons and release them itself when it quits.

Page last modified on March 03, 2007, at 09:49 AM
Hosted on Logo