Icon Resources

From The Foundry MODO SDK wiki
Jump to: navigation, search

Icons are defined as a combination of an image file and a Configs config file. These are commonly used to present icons for commands used as buttons in the user interface.

Icon Image Files

Icons are defined as regions within an image file. The image's file format can be any of those supported by modo, although Targa and PNG are most common. You can define any number of icons from a single image. These images are usually 32 bit (RGBA), thus allowing for irregular shapes through use of the alpha channel.

Defining Icons in Configs

Icons are part of the UIElements atom in a config file. It is composed of two parts, an Image defining a source for the icons, and a series of Icons define specific icons from regions of the source image.

The Image hash key can be anything you want, and will be used as the Source field in the Icon hash. The Image's content is the path to the image. file, usually referenced relative to the kit that it is used by (meaning that it is simply the name of the image, with no path prefix, as described in the kit images article.

The Icon hash key identifies the client element the icon is intended for, such as a command or a tool. The Source atom points to a previously defined Image hash key. The Location atom is four integers identifying the top-left corner of the icon, and it's width and height within the image.

Icon Example

This basic example defines an a single Image from which the Icon hash pulls a region identifying the icon itself. The hash of Icon determines which client element the icon will be used for.

 <?xml version="1.0"?>
 <configuration>
    <atom type="UIElements">
      <hash type="Image" key="imagekey">image.tga</hash>
      <hash type="Icon" key="client.element">
       <atom type="Source">imagekey</atom>
       <atom type="Location">0 0 13 13</atom>
     </hash>
    </atom>
 </configuration>

Often icons are laid out in grid patterns in image resources. Rather than having to compute offsets as multiples of 13, the Grid location isolates an icon given its position in the grid. For example, to get the icon in the third column and the second row, the zero-based offsets would be 2,1.

  <hash type="Icon" key="client.element">
    <atom type="Source">imagekey</atom>
    <atom type="Grid">2 1 13 13</atom>
  </hash>

Fields Table

Type Class Required Description/Use
Image hash The hash key is an arbitrary identifier that is referenced by the Source field of an Icon. The contents is the path to the image file, usually residing in resource:.
Icon hash The hash key is that of the client element that the icon is meant for.
  • Source
atom The hash key of a previously defined Image, as described above.
  • Location
atom or Grid Four integers representing the top-left corner and the width and height of the icon in pixels within the Source image.
  • Grid
atom or Location Four integers representing the x, y grid coordinates of the grid cell, and the width and height of each cell within the Source image.

Standard Icon Sizes and Names

Various icon sizes are hard-coded into the system, mostly for use in forms and in trees. You don't need to abide by them, but you'll have weird looking icons if you don't.

Icon names are more strict. The command system, for example, requires a combination of the command's internal name, an underscore and a pixel size, which is used choose which icon is displayed in a form given the size of the form's buttons.

Client Prefix Suffix Element Example Dimensions
Item Type
(Item List, etc)
item. (n/a) Internal name of the item or package type item.locator 13 by 13 pixels
(Tree icon)
Item Package
(Item List's Package column)
(uiicon) (n/a) Internal name of the item or package type (uiicon) locator 13 by 13 pixels
(Tree icon)
Item Type
(Form View)
item.create_ _20
_32
Internal name of the item or package type item.create_camera_32 20 by 20 pixels (Small button)
32 by 32 pixels (Large button)
Preset preseticon. (n/a) Internal name of the item type that the preset is meant for presetitem.camera Usually 128 by 128 pixels
Tools (n/a) _20
_32
Internal name of the tool or tool preset actr.element_32 20 by 20 pixels (Small button)
32 by 32 pixels (Large button)
Command (n/a) _20
_32
Internal name of the command item.name_20 20 by 20 pixels (Small button)
32 by 32 pixels (Large button)
UI Icon
(arbitrary usage)
{uiicon} (n/a) Arbitrary name depending on the specific use in the UI. {uiicon} paint.item 13 by 13 pixels (Tree icon); exact size depends on application
Script
(by service)
Internal name of the script service followed by a colon _20
_32
Hash of the script macro.scriptservice:12345:macro_20 20 by 20 pixels (Small button)
32 by 32 pixels (Large button)
Script
(automatic)
(n/a) _20
_32
Internal name (or filename) of the script myPythonScript.py_20 20 by 20 pixels (Small button)
32 by 32 pixels (Large button)

Template

You can copy and paste this into configs to get you started. Copy the Image and Icons sections as many times as you need, placing them inside a UIElements atom.

  <atom type="UIElements">
 
    <hash type="Image" key=""></hash>
 
    <hash type="Icon" key="">
      <atom type="Source"></atom>
      <atom type="Location"></atom>
    </hash>
 
  </atom>