Recent Changes - Search:

WikiDoc

Categories

The [iconref] command

Commands.IconrefCommand History

Hide minor edits - Show changes to markup

March 03, 2007, at 09:49 AM by bd - Specifying an icon in Alpha
Changed lines 60-61 from:

In the case of an icon registered with the [iconref register] command, the creator is ALFA. In the case of a System defined option, the creator is

to:

For an icon registered with the [iconref register] command, the creator is ALFA. For a System defined option, the creator is

March 03, 2007, at 09:45 AM by bd - Specifying an icon in Alpha
Deleted line 2:
Changed lines 6-9 from:
to:
Changed line 24 from:

Under OS X, the Icon Services take care of registering and managing

to:

Under OS X, the Icon Services take care of registering and managing

Changed lines 34-36 from:

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

to:

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

Changed lines 43-50 from:

Synopsis

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:

to:

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:

Changed lines 56-57 from:
     iconref register ?-id resid? ?-file filepath? type
to:
     -icon {creator type}
     -icon type
Added lines 59-73:

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

Synopsis

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

Changed line 98 from:

The [unregister] subcommand

to:

The [unregister] subcommand

Changed line 110 from:

Examples

to:

Examples

Deleted line 147:
Changed lines 150-153 from:

to:

January 09, 2007, at 06:06 AM by bd - Introduced -file option
Added line 127:
January 09, 2007, at 06:04 AM by bd - Introduced -file option
Changed lines 3-4 from:
This file documents the [iconref] command introduced in version 8.1 of AlphaX.
to:
This file documents the [iconref] command introduced in version 8.1 of AlphaX.
Changed lines 6-10 from:
  • Introduction
  • Synopsis
    • The [register] subcommand
    • The [unregister] subcommand
  • Examples
to:
Changed line 13 from:

Introduction

to:

Introduction

Changed line 15 from:

Tcl commands in Alpha. This command also allows third party packages to add icons

to:

Tcl commands in Alpha. This will also allow third party packages to add icons

Changed line 20 from:

file. A natural location for these files would be in an /Images subfolder

to:

file. A natural location for these files would be in an /Images folder

Changed lines 24-35 from:

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). The system for instance provides many preregistered icons (see 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 large 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.

Synopsis

to:

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.

Synopsis

Changed line 48 from:

The [register] subcommand

to:

The [register] subcommand

Changed line 51 from:
     iconref register [-id resid] filename type
to:
     iconref register ?-id resid? ?-file filepath? type
Changed lines 54-62 from:

filename argument is expected to be an ".icns" image file.

If the -id option is specified, the file designated by the filename argument is expected to be a resource file (containing a resource map either in its data fork or in its resource fork). 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 (with types 'ics4', 'ics8', 'icl4', etc.).

to:

-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.

Changed lines 70-74 from:

letter to avoid conflicts. The ToolbarCommand page on this wiki gives a table of the main preregistered system types.

Internally, the [iconref] command uses Alpha's signature as a creator code to register the icon.

to:

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.

Changed line 77 from:

The [unregister] subcommand

to:

The [unregister] subcommand

Changed lines 89-92 from:

Note: Alpha's core should probably keep track of registered icons and release them itself when it quits.

Examples

Here is a basic example which can be executed from the Tcl shell in

to:

Examples

Here are some basic examples which can be executed from the Tcl shell in

Changed line 94 from:
     iconref register $fname "CALC"
to:
     iconref register -file $fname "CALC"
Changed lines 97-99 from:

associates it with the "CALC" type. Later, one could create a toolbar item using this icon like this:

to:

associates it with the four-character type CALC. Now one can for example create a toolbar item using the registered icon type like this:

Changed line 100 from:
     set tbi [toolbar create -iconref "CALC"]
to:
     set tbi [toolbar create -icon "CALC"]
Changed line 103 from:

This works because the -iconref option of the [toolbar create] command

to:

This works because the -icon option of the [toolbar create] command

Changed line 105 from:

command also has an -iconref option applicable for the creation of

to:

command also has an -icon option applicable for the creation of

Changed line 108 from:

Alternatively, the icon to register could have been stored in a resource file, say

to:

The icon to register could have been stored in a resource file, say

Changed line 113 from:
 	iconref register -id 128 $fname "CALC"
to:
 	iconref register -id 128 -file $fname "CALC"
Changed line 115 from:

It is not necessary to specify the resource type (here 'icns'). The command

to:

It is not necessary to specify the resource type. The command

Changed lines 119-124 from:
to:

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"

Changed lines 127-132 from:
to:

bd Alpha's core should probably keep track of registered icons and release them itself when it quits.

July 12, 2006, at 03:19 PM by bd - New [iconref] command doc
Added lines 1-2:

(:title The [iconref] command:)

July 12, 2006, at 11:54 AM by bd - New [iconref] command doc
Changed line 24 from:

icons (see the [Commands.ToolbarCommand] page on this wiki). Icon Services

to:

icons (see the ToolbarCommand page on this wiki). Icon Services

Changed line 56 from:

letter to avoid conflicts. The [Commands.ToolbarCommand] page on this wiki

to:

letter to avoid conflicts. The ToolbarCommand page on this wiki

July 12, 2006, at 11:52 AM by bd - New [iconref] command doc
Deleted line 0:
Changed lines 19-20 from:

located anuywhere on the system.

to:

located anywhere on the system.

Added lines 29-31:

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.

Changed line 97 from:

The icon to register could have been stored in a resource file, say

to:

Alternatively, the icon to register could have been stored in a resource file, say

Changed line 101 from:
 	set fname [file join $SUPPORT(user) Images calculator.icns]
to:
 	set fname [file join $SUPPORT(user) Images calculator.rsrc]
Changed lines 108-115 from:

The 'icns' resources (and .icns files) are preferred 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.

to:
July 12, 2006, at 11:44 AM by bd - New [iconref] command doc
Added lines 1-116:
This file documents the [iconref] command introduced in version 8.1 of AlphaX.

  • Introduction
  • Synopsis
    • The [register] subcommand
    • The [unregister] subcommand
  • Examples

Introduction

The [iconref] command lets you register icons to be used by some Tcl commands in Alpha. This command also allows 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 subfolder located in one of the Application Support folders. But they can be located anuywhere 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). The system for instance provides many preregistered icons (see the [Commands.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 large palette of colors: up to 24 bits per pixel and an eight-bit mask.

Synopsis

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] filename type

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

If the -id option is specified, the file designated by the filename argument is expected to be a resource file (containing a resource map either in its data fork or in its resource fork). 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 (with types 'ics4', 'ics8', 'icl4', etc.).

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 [Commands.ToolbarCommand] page on this wiki gives a table of the main preregistered system types.

Internally, the [iconref] command uses Alpha's signature as a creator code to register the icon. 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

Note: Alpha's core should probably keep track of registered icons and release them itself when it quits.

Examples

Here is a basic example 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 $fname "CALC"

This instruction registers the icon contained in $fname and associates it with the "CALC" type. Later, one could create a toolbar item using this icon like this:

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

This works because the -iconref option of the [toolbar create] command expects the type of a registered icon. Similarly the [hiview create] command also has an -iconref 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.icns]
 	iconref register -id 128 $fname "CALC"

It is not necessary to specify the resource type (here 'icns'). 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. The 'icns' resources (and .icns files) are preferred 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.


(add your comments here...)

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