Matrix Pixmap Configuration Files

The Eiffel Matrix Code Generator (emcgen) is a tool that can be used to generate an Eiffel class that permits named access, through Eiffel code, to icons on a [[Icon Resources# Icons, Pixmaps, Pixel Buffers and Matrices |matrix pixmap]. The matrix pixmap is not required to generate the Eiffel code, only the configuration file as described here.

Configuration Files

Matrix pixmaps configuration files are INI file detailing information of an associated matrix pixmap file, including dimensions, icon names and output options for the emcgen tool.

Basic Properties

All configuration files must contain the following properties, in the default section (top of the document). Failure to exclude any of one of the following properties, or to incorrectly declare their values will result in an error:

• pixel_width: Matrix icon width in pixels. So for 16x16 icons this would be 16.
• pixel_height: Matrix icon height in pixels. So for 16x16 icons this would be 16.
• width: Matrix width in the number of icon slots, *not* pixels.
• height: Matrix height in the number of icon slots, *not* pixels.

Addition Properties

There are also additional properties to declare Optional 'name' and 'suffix' properties can be set to indicate the name of the generate class and its contained features. The 'name' property can be set or overridden via the '-class' command-line switch.

name  : Name of the class to generate

             Note: If an invalid Eiffel class name is specified the name will be formatted.

suffix  : Suffix to give generated feature names

             Note: If an invalid Eiffel feature name suffix is specified the suffix will be formatted.

Recommended: Alway specify the property name, and have the class name prefixed ES_ and suffixed ICONS_X where X is the squared dimension. Currently, EiffelStudio's icon accessor classes are ill-named and will likely change in the near future.

The following is the header of a configuration file for 16 by 16 pixel icons on a matrix that has a 4 icon rows and 10 icon columns.

# My icon file
 
name=ES_MY_ICONS_16
pixel_width=16
pixel_height=16
width=10
height=4

2.3 Sections

INI sections are used for two purposes. (1) To prefix generate pixmap access feature names and (2) to skip to the next line on the matrix.

As an example:

 [section name]
 icon1
 icon2

 [new section]
 icon3

Will generate features:

 section_name_icon1_icon: EV_PIXMAP... -- Icon at line 1 column 1
 section_name_icon2_icon: EV_PIXMAP... -- Icon at line 1 column 2
 new_section_icon3_icon: EV_PIXMAP...  -- Icon at line 2 column 1

Given that a section will skip to the next line, it's foreseeable that you might want to prefix feature names with a different prefix but continue on the current line. These come in the form of "continuation sections", which are section's whose labels a prefixed with an '@' symbol.

As an example:

 [section name]
 icon1
 icon2
 
 [@continued]
 icon3
 icon4

Will generate features:

 section_name_icon1_icon: EV_PIXMAP...   -- Icon at line 1 column 1
 section_name_icon2_icon: EV_PIXMAP...   -- Icon at line 1 column 2
 continued_name_icon3_icon: EV_PIXMAP... -- Icon at line 1 column 3
 continued_name_icon4_icon: EV_PIXMAP... -- Icon at line 1 column 5

2.3 Example

Pixmap code generation ini file.

class_name=TEST pixel_width=16 pixel_height=16 width=6 height=6

[icons] drop feature hand

[compiler state] error success

[@compilation] melt compile

Frame Files =

Next to the emcgen tool there should be a frames folder. This, be default, contains a single frame file. Frame files are the template files that will be used to generate the Eiffel class.

If you have a custom frame file you want to use the specify it's location using the -frame command-line switch.

3.1 Frame Variables

There are a number of frame file variables that are replaced with emcgen generated code. These variables should be used in your frame files to function correctly. The following list details:

 ${NAME}          : Class name.
 ${ACCESS}        : Generated pixmap access features.
 ${IMPLEMENTATION}: Generated implementation features.
 ${PIXEL_WIDTH}   : Width, in pixels, of a single matrix tile.
 ${PIXEL_HEIGHT}  : Height, in pixels, of a single matrix tile.
 ${WIDTH}         : Width, in tiles, of the matrix.
 ${HEIGHT}        : Height, in tiles, of the matrix.

3.2 Custom Frame Variables

It's possible to define custom frame variable that can change between INI configuration files. To do this, simply add a named property in the form of:

 name=value

after the require configuration property declaration (such as 'pixel_height', etc.)

Note: name, access, implementation, pixel_width, pixel_height, width and height have special meaning. If you try to set these your generated Eiffel class may not appear as it should.

To use the custom variables in your frame file use a ${NAME}, where NAME is the upper-cased version of your property name.

4.0 Matrix Pixmaps

Matrix pixmaps must be created in a desired fashion, in order to be read correctly (unless you have your own frame file implementation - See Section 5.0).

Using the default frame template file, matrix pixmaps must be bordered by one pixel and each tile padded with a single pixel. This is to allow the use of a matrix grid that does not interfere with any of the tiles. This is what tools, such as EiffelStudio, use.

5.0 Command-Line Options

There are number of command-line options, please use

 emcgen /?

for more information.