iconset(1) BSD General Commands Manual iconset(1)
NAME
iconset -- icon resource fromat
SYNOPSIS
iconset
DESCRIPTION
iconset is a is an icon resource format for providing high resolution
application and document icons. The format consits of a folder named with
the iconset extension.
An iconset consists one or more variants, each variant is specified by
file resources that follow a nameing convention. There are 3 types of
resource supported:
o Image resources
o PDF resouces
o Composited resources
IMAGE RESOURCES
An image resource consists of pairs of images (standard and high resolu-
tion) images with sizes 16x16, 32x32, 128x128, 256x256, 512x512. The nam-
ing convention is:
<variantname>_[<subvariantname>]<sizeinpoints>x<sizein-
points>[@<scale>].png
where:
<variantname> is the name of the variant, the supported variants
<subvariantname>eisithe'name ifetheasub.variant. The only supported
subvariant is 'selected'. This is a expected to be a
minor variation of the variant that has been modified
to draw well in a control that is in the selected
<scale>pisn@2xsforttheshigh-resolution version.s
The images must be square and have the dimensions that match the name of
the file.
Ideally, you would supply a complete set of icons. However, it is not a
requirement to have a complete set; the system will choose the best rep-
resentation for sizes and resolutions that you donat supply. Each icon in
the set is a hint to the system as to the best representation to use. A
complete set consists of the following:
o icon_16x16.png
o icon_16x16@2x.png
o icon_32x32.png
o icon_32x32@2x.png
o icon_128x128.png
o icon_128x128@2x.png
o icon_256x256.png
o icon_256x256@2x.png
o icon_512x512.png
o icon_512x512@2x.png
PDF RESOURCES
A PDF resource consistes fo a single PDF the naming convention is:
<variantname>_[<subvariantname>].pdf
o <variantname> See image resource.
o <subvariantname> See image resource.
A PDF resource for any one variant can be combined with one or more image
resources. The images will be used in preferance to the PDF at draw time
and the PDF is only used at sizes larger than the largest image. Given
the following resources:
o icon_16x16.png
o icon_16x16@2x.png
o icon.pdf
the PNG images will be used to draw the icon are 16pt sizes and smaller
while the PDF will be used at sizes larger than 16pt. Given the following
resources:
o icon_16x16.png
o icon_16x16@2x.png
o icon_256x256.png
o icon_256x256@2x.png
o icon.pdf
the PDF will only be used at sizes larger than 256pt (not true there is a
bug).
COMPOSITED RESOURCES
A composited resouce consists of a JSON file and a resource folder with
the naming conventions:
<variantname>_[<subvariantname>].json
Resources/
o <variantname> See image resource.
o <subvariantname> See image resource.
The JSON conatains instructions for compositing an icon from the
resources provided in 'Resources' and by the System. The Resources folder
may contain image resources and PDF resouces as described above, it may
also contain other iconset folders however a composite my not referance
composite resources sources from another iconset.
The JSON supports 4 top level keys:
o info - Information on the iconset version.
o resource-folder-urls - An array of URL strings either relative or
absolute that may contain additional resources.
o recipe - The instructions used to composite the final icon, this may
be a string that referances a system provided recipe or custom recipe.
o resources - A dictionary of resource names, that can be used with the
recipes to composite the final icon images. A resouce may be:
Recipes:
The system provides 3 icon recipes:
o application - This recipe requires an entry in the resources dictio-
nary named 'image' and will construct an app icon using this image.
o badged-document - This recipe uses the 'badge' (graphic) and the
'extension' (text) entries from the resources dictionary. Both
resources are optional.
o movie-document - See badged-document recipe.
It is also possible to specifiy a custom recipe. This takes the form of
an array of layers, aach layer is represented as a dictionary the speci-
fies a resource and some options that control size and positioning and
the icon sizes the layer is active at. There are 2 types of layer,
Graphic and Text:
o Graphic - Draws the layer's resource image or PDF in the center of the
icon. For composition purposes the icon should be considered to be a
1024px square. Any sizes specified will be proportionaly adjused when
the icon is drawn at smaller sizes.
o resource - The name of an Image or PDF resource present the
Resources folder, provided by the system or when prefixed by a $
this value referances an entry from the resources dictionary.
o - An offset co-ordinate provided as '{<x>,<y>}'. The image is drawn
centered in the icon bounds and offset by <x> <y>.
o size - Specifies the size the image resouces should be drawn at.
o active - Specifies the icon size range that this layer will be
drawn at. If not present the layer will be drawn at all sizes.
'-32' will draw at all sizes <= 32pt, '32-128' will draw at all
sizes > 32pt and <= 128pt and '128-' will draw at all sizes >
128pt.
o Text - Draws text specified in the layer's resource. This is currently
optimized for drawing the file extension on document icons. By default
the text is drawn centered on the bottom edge of the icon.
o resource - The text to be drawn or when prefixed by a $ this
value referances an entry from the resources dictionary.
o offset - An offset co-ordinate provided as '{<x>,<y>}'.
o active - See Graphic layer.
Resources: There are 4 supported resource types:
o PDF - The value 'foo' would search the resource folders for a PDF named
'foo.pdf'
o Image - The value 'foo' would search the resource folders for a images
named foo_<sizeinpoints>x<sizeinpoints>[@<scale>].png
o Iconset - To use iconset resources you must also specify the variant to
use. The value 'foo.icon' would search the resource folders for an icon-
set named 'foo' and would use the 'icon' variant resources from that
iconset.
o Text - This provides test to a text layer. This is used exclusivly for
badging document icons with the file extension.
EXAMPLES
Darwin February 2, 2017 Darwin
Mac OS X 10.11.6 - Generated Thu Feb 2 07:55:32 CST 2017