Difference between revisions of "Icon Resources"

Latest revision as of 14:50, 26 June 2008

Note: The information here is for use in the EiffelStudio 6.3 development branch or later.

A typical EiffelStudio extender will need to either access either the pool of general stock icons (also know as pixmaps), add new stock icons or include a new collection for a tool or dialog development. The information here describes the built-n access methods as well as information for creating new icon pixmaps in the form of an icon "matrix".

Icons, Pixmaps, Pixel Buffers and Matrices

Icon resources come labeled in all sorts of manners, typically because of the evolving and maturing of the EiffelStudio code base. To help you get a grip on what means what and what to use where, here's run-down of the terms used.

Pixmaps are EiffelVision2 image representations. EiffelVision2 pixmaps support transparency but do not support alpha channels. As EiffelStudio matures pixmaps are being phased out in place of pixel buffers.

Pixel Buffers are also EiffelVision2 image representations, like pixmaps, but supporting alpha channels. Pixel buffers are become the image representation of choice because of their flexibility and their ability to be converted to pixmaps.

Icons are a single image representing a button, menu or other such glyph. In the EiffelStudio code base an icon is a notion rather than an actual physical entity. An icon is a slice of a pixmap/pixel buffer matrix.

Matrices are the way EiffelStudio logical groups a collection of icons. A matrix is typically a PNG file installed in the EiffelStudio delivery. A matrix is also referred to as a pixmap, which is a term derived from using EiffelVision2. In actualality a matrix is loaded as a pixel buffer and not a pixmap to support alpha channels. In the development branch, matrix pixmap resources are accompanied by a matrix configuration file, used with the Eiffel Matrix Code Generator tool to generate icon accessor classes, which is used in this document.

Accessing Icons

If all you need to do is to access existing icon resources from EiffelStudio, or the operating system's default icons there is very little you need to do. Depending on what you are developing and if you are using ESF.

Accessing "Stock" Icons

Access to all of the stock icons can be achieved through inheriting a shared accessor class ES_SHARED_PIXMAPS from your custom classes. ES_SHARED_PIXMAPS provides shared access to the OS stock icons through stock_pixmaps, EiffelStudio 16x16 through icon_pixmaps, EiffelStudio 12x12 through small_pixmaps and EiffelStudio 10x10 through mini_pixmaps.

Note: The names of the accessor functions are likely to change in the future for consistency and better naming.

Accessing icons in this way is specific to auxiliary development that is not based on ESF as ESF provides default accessor routines to all tools, dialogs and widgets through a stock_pixmaps and mini_stock_pixmaps function for 16x16 and 10x10 pixel sized icons respectively.

Warning: It is not recommended you create the icon accessor objects yourself using the accessor classes. EiffelStudio resource handling is smart enough to load matrix files twice, but at any point the matrix files may be renamed or the creation of the accessor objects may change and break your code.

All general stock icon matrix files are located under /Src/Delivery/studio/bitmap/png/ or installed under $ISE_EIFFEL/studio/bitmaps/png/.

Accessing Tool-Specific Icons

Tools and dialogs based on ESF can optionally inherit ES_TOOL_PIXMAPS_PROVIDER for accessing tool-specific icons located in the tool's folder. When inherited, ES_TOOL_PIXMAPS_PROVIDER, provides access to the icons through tool_pixmaps.

Adding New Icons

The Tools of the Trade

Icon classes, such as ES_PIXMAPS_16X16, ES_PIXMAPS_12X12 and ES_PIXMAPS_10X10 are automatically generated for EiffelStudio from a matrix configuration file. The configuration file holds information on a corresponding matrix and details the icon names associated with each matrix pixmap icon. One advantage of the configuration file is there is no need to manually code any information related to a respective icon's coordinates in the matrix pixmap, all that is really needed is logical group name(s) and icon name(s).

A separate tool, called emcgen is then used to generated an Eiffel class from the configuration file.

To regenerate the icon accessor class for the stock 16x16 icons, you could perform the following using your terminal of choice:

$>cd $EIFFEL_SRC/Eiffel/interface/new_graphical/shared
$>emcgen "$EIFFEL_SRC/Delivery/studio/bitmaps/png/16x16.ini"
    --frame "$EIFFEL_SRC/tools/eiffel_matrix_code_generator/frames/estudio.e.frame"

This does require emcgen to have been compiled and be accessible from $PATH.

Adding Stock Icons

To add new icons to the stock set of EiffelStudio icons you must first edit the corresponding matrix pixmap.

Adding Icons to Tools

Just like accessing tool icons, adding new icons to a tool differs slightly.

Tool Development

EiffelStudio has a special way of handling tool-specific icon resources, using the similar techniques as those already described. Tools should used the new [Modular Tool Development|modular] development concepts outline.