manpagez: man pages & more
man iconset(1)
Home | html | info | man

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
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.