Symbols (XForms (Forms Library) - Version 1.2 (Rev. 4) A Graphical User Interface Toolkit for X)

Previous: Changing Many Attributes, Up: Changing Attributes [Contents][Index]

#### 3.11.7 Symbols

Rather than using text as a label it is possible to place symbols like an arrows etc. on objects. This is done in the following way:

When the label starts with the character `@` instead of the text a particular symbol is drawn3. The rest of the label string indicates the symbol. A number of pre-defined symbols are available:

`->` | Normal arrow pointing to the right.
`<-` | Normal arrow pointing to the left.
`>` | Triangular arrow pointing to the right.
`<` | Triangular arrow pointing to the left.
`>>` | Double triangle pointing to the right.
`<<` | Double triangle pointing to the left.
`<->` | Arrow pointing left and right.
`->|` | A normal arrow with a bar at the end.
`>|` | A triangular arrow with a bar at the end.
`-->` | A thin arrow pointing to the right.
`=` | Three embossed lines.
`arrow` | Same as `-->`.
`returnarrow` | `<Return>` key symbol.
`square` | A square.
`circle` | A circle.
`line` | A horizontal line.
`plus` | A plus sign (can be rotated to get a cross).
`UpLine` | An embossed line.
`DnLine` | An engraved line.
`UpArrow` | An embossed arrow.
`DnArrow` | An engraved arrow.

See Fig. 3.6 for how some of them look.

It is possible to use the symbols in different orientations. When the symbol name is preceded by a digit `1`-`9` it is rotated like on the numerical keypad, i.e., `6` (and also `5`) result in no rotation, `9` a rotation of 45 degrees counter-clockwise, `8` a rotation of 90 degrees, etc. Hence the order is `6`, `9`, `8`, `7`, `4`, `1`, `2`, `3`. (Just think of the keypad as consisting of arrow keys with 6 pointing in the default orientation, i.e., to the right). So to get an arrow that is pointing to the left top use a label `@7->`. To put the symbol in other orientations, put a 0 after the `@`, followed by the angle (counter-clockwise). E.g., to draw an arrow at an angle of 30 degrees you can use `@030->`.

The symbol will be scaled to fit in the bounding box. When the bounding box is not square, scaling in the x- and y-directions will be different. If keeping the aspect ratio is desired, put a sharp (`#`) immediately after the . E.g., `@#9->`.

Two additional prefixes, `+` and `-`, followed by a single digit, can be used to make small symbol size adjustment. A `+` indicates an increase of the symbol size while a `-` a decrease. The single digit following the prefix is the amount of increment (or decrement) in pixels. For example, to draw a square that is 3 pixels smaller in size than the default size use `@-3square`. If a single sequence of `+` or `-` and a single digit does not suffice, it can repeated, the effect is cumulative. Of course, this can also be combined with a rotation etc., so i.e., `@-9-3030->` (the order in which the different sequences are used doesn’t matter) will result in an arrow drawn 12 pixels smaller than normal and rotated by 30 degrees counter-clockwise.

As already stated the "default" size of a symbol is (this at least holds for the built-in ones) one where it fits autoatically into the box it is to be drawn into, with a bit of room left around it. Thus the size of the symbol should in most cases be fine without any further fine-tuning. If you increase the size for whatever reasons please consider that the symbol automatically gets clipped to the area it is will be drawn into, i.e., increments that result in the symbol becoming larger than the box it is to be drawn into should be avoided.

In addition to using symbols as object labels, symbols can also be drawn directly using

    int fl_draw_symbol(const char *symbolname, FL_Coord x, FL_Coord y,
                       FL_Coord w, FL_Coord h, FL_Color col);

(the function returns `1` on success and `0` on failure when the symbol name isn’t valid) or indirectly via `fl_draw_text()`. Drawing is clipped automatically to the area given by the arguments.

The application program can also add symbols to the system which it can then use to display symbols on objects that are not provided by the Forms Library. To add a symbol, use the call

    int fl_add_symbol(const char *name, void (*drawit)(),int sc);

`name` is the name under which the symbol should be known, which may not have a `@`, a `#` or a digit at the start (or `+` or `-`, directly followed by a digit). `drawit()` is the routine to be called for drawing the symbol. `sc` is reserved and currently has no meaning. Best set it to `0`.

The routine `drawit()` should have the form

    void drawit(FL_Coord x, FL_Coord y, FL_Coord w, FL_Coord h,
                int angle, FL_COLOR col);

`col` is the color in which to draw the symbol. This is the label color that can be provided and changed by the application program. The routine should draw the symbol centered inside the box by `x`, `y`, `w`, `h` and rotated from its natural position by `angle` degrees. The draw function can call all types of drawing routines, including `fl_draw_symbol()`. Before it is called clipping is set to the area given by the first four arguments.

If the new symbol name is the same as that of a built-in or of one previously defined, the new definition overrides the built-in or previously defined one.

The function returns `1` on success and `0` on failure (due to invalid arguments).

The symbol handling routines really should be viewed as a means of associating an arbitrary piece of text (the label) with arbitrary graphics, application of which can be quite pleasant given the right tasks.

A symbol (built-in or previously defined) can also be deleted using

    int fl_delete_symbol(const char *name);

On success `1` is returned, otherwise `0`.

#### Footnotes

### (3)

If you want a literal `@` character as the first character of a label text, escape it with another `@` character.

Previous: Changing Many Attributes, Up: Changing Attributes [Contents][Index]