Icon Resources

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

The Icon hash key identifies the client element the icon is intended for, such as a Command System. 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>