## ChafaSymbolMap ChafaSymbolMap — Describes a selection of textual symbols |

## Functions

ChafaSymbolMap * | chafa_symbol_map_new ()
ChafaSymbolMap * | chafa_symbol_map_copy ()
void | chafa_symbol_map_ref ()
void | chafa_symbol_map_unref ()
void | chafa_symbol_map_add_by_tags ()
void | chafa_symbol_map_remove_by_tags ()
gboolean | chafa_symbol_map_apply_selectors ()

## Types and Values

#define | CHAFA_SYMBOL_WIDTH_PIXELS
#define | CHAFA_SYMBOL_HEIGHT_PIXELS
enum | ChafaSymbolTags
typedef | ChafaSymbolMap

## Description

A ChafaSymbolMap describes a selection of the supported textual symbols that can be used in building a printable output string from a ChafaCanvas.

To create a new ChafaSymbolMap, use `chafa_symbol_map_new()`. You can then add symbols to it using `chafa_symbol_map_add_by_tags()` before copying it into a ChafaCanvasConfig using `chafa_canvas_config_set_symbol_map()`.

Note that some symbols match multiple tags, so it makes sense to e.g. add symbols matching CHAFA_SYMBOL_TAG_BORDER and then removing symbols matching CHAFA_SYMBOL_TAG_DIAGONAL.

The number of available symbols is a significant factor in the speed of ChafaCanvas. For the fastest possible operation you could use a single symbol -- CHAFA_SYMBOL_TAG_VHALF works well by itself.

## Functions

### chafa_symbol_map_new ()

    ChafaSymbolMap *
    chafa_symbol_map_new (void);

Creates a new ChafaSymbolMap representing a set of Unicode symbols. The symbol map starts out empty.

#### Returns

The new symbol map

### chafa_symbol_map_copy ()

    ChafaSymbolMap *
    chafa_symbol_map_copy (const ChafaSymbolMap *symbol_map);

Creates a new ChafaSymbolMap that's a copy of `symbol_map` .

#### Parameters

symbol_map | A ChafaSymbolMap to copy. |

#### Returns

The new ChafaSymbolMap

### chafa_symbol_map_ref ()

    void
    chafa_symbol_map_ref (ChafaSymbolMap *symbol_map);

Adds a reference to `symbol_map` .

#### Parameters

symbol_map | Symbol map to add a reference to |

### chafa_symbol_map_unref ()

    void
    chafa_symbol_map_unref (ChafaSymbolMap *symbol_map);

Removes a reference from `symbol_map` . When remaining references drops to zero, the symbol map is freed and can no longer be used.

#### Parameters

symbol_map | Symbol map to remove a reference from |

### chafa_symbol_map_add_by_tags ()

    void
    chafa_symbol_map_add_by_tags (ChafaSymbolMap *symbol_map,
                                  ChafaSymbolTags tags);

Adds symbols matching the set of `tags` to `symbol_map` .

#### Parameters

symbol_map | Symbol map to add symbols to |
tags | Selector tags for symbols to add |

### chafa_symbol_map_remove_by_tags ()

    void
    chafa_symbol_map_remove_by_tags (ChafaSymbolMap *symbol_map,
                                     ChafaSymbolTags tags);

Removes symbols matching the set of `tags` from `symbol_map` .

#### Parameters

symbol_map | Symbol map to remove symbols from |
tags | Selector tags for symbols to remove |

### chafa_symbol_map_apply_selectors ()

    gboolean
    chafa_symbol_map_apply_selectors (ChafaSymbolMap *symbol_map,
                                      const gchar *selectors,
                                      GError **error);

Parses a string consisting of symbol tags separated by [+-,] and applies the pattern to `symbol_map` . If the string begins with + or -, it's understood to be relative to the current set in `symbol_map` , otherwise the map is cleared first.

The symbol tags are string versions of ChafaSymbolTags, i.e. [all, none, space, solid, stipple, block, border, diagonal, dot, quad, half, hhalf, vhalf, braille, technical, geometric, ascii, extra].

Examples: "block,border" sets map to contain symbols matching either of those tags. "+block,border-dot,stipple" adds block and border symbols then removes dot and stipple symbols.

If there is a parse error, none of the changes are applied.

#### Parameters

symbol_map | Symbol map to apply selection to |
selectors | A string specifying selections |
error | Return location for an error, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` if there was a parse error

## Types and Values

### CHAFA_SYMBOL_WIDTH_PIXELS

    #define CHAFA_SYMBOL_WIDTH_PIXELS 8

The width of an internal symbol pixel matrix. If you are prescaling input graphics, you will get the best results when scaling to a multiple of this value.

### CHAFA_SYMBOL_HEIGHT_PIXELS

    #define CHAFA_SYMBOL_HEIGHT_PIXELS 8

The height of an internal symbol pixel matrix. If you are prescaling input graphics, you will get the best results when scaling to a multiple of this value.

### enum ChafaSymbolTags

#### Members

CHAFA_SYMBOL_TAG_NONE | Special value meaning no symbols. |
CHAFA_SYMBOL_TAG_SPACE | Space. |
CHAFA_SYMBOL_TAG_SOLID | Solid (inverse of space). |
CHAFA_SYMBOL_TAG_STIPPLE | Stipple symbols. |
CHAFA_SYMBOL_TAG_BLOCK | Block symbols. |
CHAFA_SYMBOL_TAG_BORDER | Border symbols. |
CHAFA_SYMBOL_TAG_DIAGONAL | Diagonal border symbols. |
CHAFA_SYMBOL_TAG_DOT | Symbols that look like isolated dots (excluding Braille). |
CHAFA_SYMBOL_TAG_QUAD | Quadrant block symbols. |
CHAFA_SYMBOL_TAG_HHALF | Horizontal half block symbols. |
CHAFA_SYMBOL_TAG_VHALF | Vertical half block symbols. |
CHAFA_SYMBOL_TAG_HALF | Joint set of horizontal and vertical halves. |
CHAFA_SYMBOL_TAG_INVERTED | Symbols that are the inverse of simpler symbols. When two symbols complement each other, only one will have this tag. |
CHAFA_SYMBOL_TAG_BRAILLE | Braille symbols. |
CHAFA_SYMBOL_TAG_TECHNICAL | Miscellaneous technical symbols. |
CHAFA_SYMBOL_TAG_GEOMETRIC | Geometric shapes. |
CHAFA_SYMBOL_TAG_ASCII | Printable ASCII characters. |
CHAFA_SYMBOL_TAG_EXTRA | Symbols not in any other category. |
CHAFA_SYMBOL_TAG_ALL | Special value meaning all supported symbols. |

### ChafaSymbolMap

    typedef struct ChafaSymbolMap ChafaSymbolMap;