Paulb at 23:47, 26 June 2008

2008-06-26T23:47:46Z

New page

{{UnderConstruction}}
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 [[Eiffel Matrix Code Generator|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.
<code>
# My icon file

name=ES_MY_ICONS_16
pixel_width=16
pixel_height=16
width=10
height=4
</code>

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.

Matrix Pixmap Configuration Files - Revision history

Paulb at 23:47, 26 June 2008