Drawing Commands of the Icon Engine

Save/restore current context

<ctxt>save/restore</>

   Save and restore the current paint context.

The icon engine holds internal data defining the current colors, fonts, angle of rotation etc. Some paint commands alter this information in a global way. To preserve a set state the <ctxt> command can be used. It stores all the data on a stack and any changes will be reverted when issuing a <ctx>restore</>.
It is save to have several of these commands in a set of commands. Make sure every save has an associated restore.

See the Icon Tutorial for an example.

Setting colors

<color>r g b</>

   Set the color to be used by the next command.

The values r, g and b are in the range 0.0 to 1.0. They form a final RGB value for the color.

Examples:

   0.2 0.2 0.2 : a light grey
   1.0 0.0 0.0 : pure red
    1   0   0  : same as before
   0.0 0.0 0.0 : black

---

<colora>r g b a</>

   Set the color and alpha to be used by the next command.

Same as the <color></> but you may specify the alpha. A value of a can be chosen between 0.0 to 1.

  a=1   : completely opaque
  a=0.0 : completely transparent (this means invisible)
  a=0.5 : 50% transparent

Move the drawing position

<move>Xpos Ypos</>

   Move to the position ''xpos/yPos'' on the current surface.

This command specifies the position where the next drawing command will take place. The command may be drawing of an rectangle, a line, text or something else.

Drawing a line

For drawing a line one has to perform a sequence of commands:

• Move to the start position using <move>Xpos Ypos</>
• Set the line width using <lwidth>width</>
• Optionally specify how to paint line endpoints using <linecap></>
• Set the end point using '<line>toX toY</>
• Finally drawing the line using <stroke></>

For example:

   <color>0.5 0.5 0.9</><lwidth>0.05</><move>0.1 0.3</><line>0.8 0.9</><stroke></>

The commands will be described in detail in the following paragraphs.

Set line width

<lwidth>width</>

   Set the width for subsequently drawn lines.

The value may range from 0.0 to 1.0.

Set the shape of the lines end point

<linecap>style</>

   Draw the end point of a line using ''style''.

The parameter style may be one of:

   round:   the line start/end point is rounded with the center of the circle specified
            by the given x/y position
   square:  the line start or end point is a square with the center specified by the
            given x/y point
   butt:    the line starts and ends exactly at the specified positions

Set next line point

<line>toX toY</>

   Draw a line from the current position to toX/toY.

Perform the line drawing

There are two commands doing the actual drawing of the line.

<stroke></>

   Do the actual drawing.

Using <stroke></> all information about the painted path (start position, line segments, width etc.) is cleared from the curent context. This means for example one has to issue a new move command prior to any more line drawing.

<stroke>preserve</>

   Do the actual drawing but keep all line information in the context.

<stroke>preserve</> will keep all the path information in the drawing context. Subsequent drawing will take place at the last position specified by one of the drawing commands.

It is possible to do several move and line commands on a surface. The actual drawing only takes place when performing the stroke command.

Drawing rectangles

The engine supports the drawing of rectangles with or without borders.

Defining the rectangle

<rect>Xpos yPos width height</>

   Draw a rectangle at position 'Xpos/Ypos' with given 'height' and 'width'.

Note that nothing is actually painted yet. You need to issue a <fill></> or <stroke></> command.

Fill rectangle

<fill></>

   Fill the rectangle with the set color.

The color used is the one previously set using the <color> or <colora> commands like in this example:

<colora> 0 0.3 0.65 0.8</><rect>0.13 0.345 0.7 0.3</><fill></>

Draw outline rectangle

Similar to line drawing one has to issue the stroke command to actually draw the outline:

<stroke></>

   Do the actual drawing.

or

<stroke>preserve</>

   Do the actual drawing but keep all line information in the context.

Note that you have to define the line features prior to this command. You must at least specify the line width:

<colora> 0 0.3 0.65 0.8</><rect>0.13 0.345 0.7 0.3</><lwidth>0.05</><stroke></>

Draw a filled rectangle with border

Combining the previous commands it is possible to draw rectangles with borders using any combination of color and line with.

The following sequence of commands draws a rectangle with a blue semitransparent border filled with a solid grey color:

<colora>0 0.3 0.65 0.8</><rect>0.13 0.345 0.7 0.3</><lwidth>0.05</><stroke>preserve</><color>0.5 0.5 0.5</><fill></>

Note the use of <stroke>preserve</> here. This way the information about the rectangle's shape is kept in the current drawing context after drawing the border and the fill command is applied to the same shape.

When using <stroke></> here only the border is drawn because there is no definition for any shape when the <fill></>' command is encountered.

Using Images

Painting of images is done with some special commands described here.

Moving paint position for images

<transl>x y</>

   Specify the position for the next image command.

X and y specify the position on the surface where subsequent painting will take place. 0.0 0.0 is the upper left corner. The values may run from 0.0 to 1.0.

See the Icon Tutorial for an example.

Note that for other drawing commands the position is set using <move></>.

Sizing the image

<scale>xsize ysize</>

   Apply scaling to the next set of commands.

The values xsize and ysize are factors between 0.0 and 1.0. They specify the size of the items which will be painted afterwards. Note that this scaling is a global setting and will be applied to all paint commands which follow. Use <ctxt>save</> to save current scaling settings. Note that the factors usually have to be rather small. A value of 1.0 does not mean current icon size but is way bigger.

See the Icon Tutorial for an example.

Painting the image

<imgkey>imgname # alpha</>

   Paint an image specified by the key 'imgname' on the current surface with an alpha level of 'alpha'.

This command will paint an image at the current position with the current scaling. The value of alpha may run from 0.0 to 1.0 where 1.0 means completely opaque while 0.0 means completely translucent. imgname is the name of a key in the ini file specifiying the image file to be used. The path is a relative one as known from the 'Image' key. Note that the spelling of the key is important and references to keys belonging to other icons are not possible.

See the Icon Tutorial for an example.