Text Drawing

Text Drawing — Fonts and text primitives

Functions

Types and Values

Object Hierarchy

    GBoxed
    ├── GrxFont
    ╰── GrxTextOptions

Includes

#include <grx-3.0.h>

Description

The library supports loadable fonts. When in memory they are bitmapped (i.e. not scalable!) fonts.

Under the hood, it uses fontconfig and freetype2. This means than fontconfig must be configured to allow using bitmap fonts, otherwise grx_font_load() will not be able to find any fonts. You can also use the fontconfig command line tools to help find availble fonts. For example, fc-list ":scalable=False" will list all bitmap fonts.

To bypass fontconfig, use grx_font_load_from_file() instead.

Functions

grx_font_load_from_file ()

GrxFont *
grx_font_load_from_file (const gchar *filename,
                         GError **err);

Loads a font from a file. Only loads the first font face in the file.

Parameters

filename

the file path.

[type filename]

err

Pointer to hold an error

 

Returns

the font or NULL if there was an error such as the font was not found.

[transfer full][nullable]


grx_font_load_full ()

GrxFont *
grx_font_load_full (const gchar *family,
                    gint size,
                    gint dpi,
                    GrxFontWeight weight,
                    GrxFontSlant slant,
                    GrxFontWidth width,
                    gboolean monospace,
                    const gchar *lang,
                    const gchar *script,
                    GError **err);

Loads the font that best matches the parameters.

Uses fontconfig for font matching.

Parameters

family

the font family name or NULL.

[nullable]

size

the preferred size in points or -1 for any size

 

dpi

the screen resolution or -1 to ignore dpi

 

weight

the font weight (e.g. bold) or -1 for any weight

 

slant

the font slant (e.g. italic) or -1 for any slant

 

width

the font width (e.g. narrow) or -1 for any width

 

monospace

set to TRUE to prefer a monospace font

 

lang

a RFC-3066-style language code or NULL.

[nullable]

script

an ISO 15924 script code or NULL.

[nullable]

err

pointer to hold an error

 

Returns

the font or NULL if there was an error.

[transfer full][nullable]


grx_font_load ()

GrxFont *
grx_font_load (const gchar *family,
               gint size,
               GError **err);

Loads the font that best matches the parameters.

Uses fontconfig for font matching. This function is dpi aware, so the result depends on the currently selected video driver and possibly the video mode.

Parameters

family

the font family name or NULL.

[nullable]

size

the preferred size or -1 for any size

 

err

pointer to hold an error

 

Returns

the font or NULL if there was an error.

[transfer full][nullable]


grx_font_ref ()

GrxFont *
grx_font_ref (GrxFont *font);

Increases the reference count to font .

Parameters

font

the font

 

Returns

font .

[transfer full]


grx_font_unref ()

void
grx_font_unref (GrxFont *font);

Decreases the reference count on font .

When the reference count reaches 0, font is freed.

Parameters

font

the font.

[transfer full]

grx_font_get_family ()

const gchar *
grx_font_get_family (GrxFont *font);

Gets the name of the font family.

Parameters

font

the font

 

Returns

the name.

[transfer none][nullable]


grx_font_get_style ()

const gchar *
grx_font_get_style (GrxFont *font);

Gets the name of the font style.

Parameters

font

the font

 

Returns

the name.

[transfer none][nullable]


grx_font_get_height ()

gint
grx_font_get_height (GrxFont *font);

Gets the height of the font in pixels.

Parameters

font

the font

 

Returns

the height


grx_font_get_width ()

gint
grx_font_get_width (GrxFont *font);

Gets the width of the font in pixels.

Parameters

font

the font

 

Returns

the width


grx_font_dump ()

gint
grx_font_dump (GrxFont *font,
               GrxContext *context,
               gint start,
               GrxColor fg,
               GrxColor bg);

Draws as many glyphs as possible in the clip box of the specified context.

If all of the glyphs do no fit, an index will be returned. This index can be passed to start to draw the next "page" of glyphs.

Parameters

font

the font

 

context

the drawing context

 

start

the starting glyph index

 

fg

the forground color

 

bg

the background color

 

Returns

the index of the first glyph that was not drawn or -1 if all of the glyphs were drawn


grx_font_get_char_width ()

gint
grx_font_get_char_width (GrxFont *font,
                         gunichar c);

Gets the width of a character using the specified font.

Parameters

font

the font

 

c

the character

 

Returns

the width


grx_font_get_char_height ()

gint
grx_font_get_char_height (GrxFont *font,
                          gunichar c);

Gets the height of a character using the specified font.

Parameters

font

the font

 

c

the character

 

Returns

the height


grx_font_get_text_width ()

gint
grx_font_get_text_width (GrxFont *font,
                         const gchar *text);

Gets the width of a string using the specified font.

The string must contain valid UTF-8. Check using g_utf8_validate() first if text is from an unknown source.

Parameters

font

the font

 

text

the text.

[nullable]

Returns

the width


grx_font_get_text_height ()

gint
grx_font_get_text_height (GrxFont *font,
                          const gchar *text);

Gets the height of a string using the specified font.

The string must contain valid UTF-8. Check using g_utf8_validate() first if text is from an unknown source.

Parameters

font

the font

 

text

the text.

[nullable]

Returns

the height


grx_draw_text ()

void
grx_draw_text (const gchar *text,
               gint x,
               gint y,
               GrxTextOptions *options);

Draws the text at the specified coordinates using options .

The position of the text relative to the coordinates will depend on the alignment given in options .

Parameters

text

The text to draw

 

x

The x coordinate

 

y

The y coordinate

 

options

GrxTextOptions to control how the text is drawn

 

grx_text_options_new ()

GrxTextOptions *
grx_text_options_new (GrxFont *font,
                      GrxColor fg);

Allocate a text options structure with background color set to GRX_COLOR_NONE, horizontal alignment of GRX_TEXT_HALIGN_LEFT and vertival alignment of GRX_TEXT_VALIGN_TOP.

This structure is passed to text drawing functions to provide information on how to draw the text.

Parameters

font

the font

 

fg

the forground color

 

Returns

the new GrxTextOptions structure.

[transfer full]


grx_text_options_new_full ()

GrxTextOptions *
grx_text_options_new_full (GrxFont *font,
                           GrxColor fg,
                           GrxColor bg,
                           GrxTextHAlign h_align,
                           GrxTextVAlign v_align);

Allocate a text options structure.

This structure is passed to text drawing functions to provide information on how to draw the text.

Parameters

font

the font

 

fg

the forground color

 

bg

the background color

 

h_align

the horizontal alignment

 

v_align

the vertical alignment

 

Returns

the new GrxTextOptions structure.

[transfer full]


grx_text_options_ref ()

GrxTextOptions *
grx_text_options_ref (GrxTextOptions *options);

Increases the reference count to options .

Parameters

options

the options

 

Returns

options .

[transfer full]


grx_text_options_unref ()

void
grx_text_options_unref (GrxTextOptions *options);

Decreases the reference count on options .

When the reference count reaches 0, options is freed.

Parameters

options

the options.

[transfer full]

grx_text_options_get_font ()

GrxFont *
grx_text_options_get_font (GrxTextOptions *options);

Gets the font.

Parameters

options

the options

 

Returns

the font.

[transfer none]


grx_text_options_set_font ()

void
grx_text_options_set_font (GrxTextOptions *options,
                           GrxFont *font);

Sets the font.

Parameters

options

the options

 

font

the font

 

grx_text_options_get_fg_color ()

GrxColor
grx_text_options_get_fg_color (GrxTextOptions *options);

Gets the forground color.

Parameters

options

the options

 

Returns

the color


grx_text_options_set_fg_color ()

void
grx_text_options_set_fg_color (GrxTextOptions *options,
                               GrxColor fg);

Sets the forground color.

Parameters

options

the options

 

fg

the color

 

grx_text_options_get_bg_color ()

GrxColor
grx_text_options_get_bg_color (GrxTextOptions *options);

Gets the background color.

Parameters

options

the options

 

Returns

the color


grx_text_options_set_bg_color ()

void
grx_text_options_set_bg_color (GrxTextOptions *options,
                               GrxColor bg);

Sets the background color.

Parameters

options

the options

 

bg

the color

 

grx_text_options_get_h_align ()

GrxTextHAlign
grx_text_options_get_h_align (GrxTextOptions *options);

Gets the horizontal alignment.

Parameters

options

the options

 

Returns

the alignment


grx_text_options_set_h_align ()

void
grx_text_options_set_h_align (GrxTextOptions *options,
                              GrxTextHAlign h_align);

Sets the horizontal alignment.

Parameters

options

the options

 

h_align

the alignment

 

grx_text_options_get_v_align ()

GrxTextVAlign
grx_text_options_get_v_align (GrxTextOptions *options);

Gets the vertical alignment.

Parameters

options

the options

 

Returns

the alignment


grx_text_options_set_v_align ()

void
grx_text_options_set_v_align (GrxTextOptions *options,
                              GrxTextVAlign v_align);

Sets the vertical alignment.

Parameters

options

the options

 

v_align

the alignment

 

Types and Values

enum GrxFontWeight

Describes the weight of the font.

Members

GRX_FONT_WEIGHT_REGULAR

regular font

 

GRX_FONT_WEIGHT_BOLD

bold font

 

enum GrxFontSlant

Describes the slant of the font.

Members

GRX_FONT_SLANT_REGULAR

regular font

 

GRX_FONT_SLANT_ITALIC

italic font

 

enum GrxFontWidth

Describes the slant of the font.

Members

GRX_FONT_WIDTH_NARROW

narrow font

 

GRX_FONT_WIDTH_REGULAR

regular font

 

GRX_FONT_WIDTH_WIDE

wide font

 

enum GrxTextHAlign

Horizontal text alignment

Members

GRX_TEXT_HALIGN_LEFT

align text on the left

 

GRX_TEXT_HALIGN_CENTER

align text in the center

 

GRX_TEXT_HALIGN_RIGHT

align text on the right

 

enum GrxTextVAlign

Vertical text alignment

Members

GRX_TEXT_VALIGN_TOP

align text on the top

 

GRX_TEXT_VALIGN_MIDDLE

align text in the middle

 

GRX_TEXT_VALIGN_BOTTOM

align text on the bottom

 

GRX_TEXT_VALIGN_BASELINE

align text on the baseline

 

GrxFont

typedef struct _GrxFont GrxFont;

Data structure that represents a font.


GrxTextOptions

typedef struct _GrxTextOptions GrxTextOptions;

Data structure that contains text drawing options.