## PgmText

PgmText — A text drawable.

## Synopsis

    #include <pgm/pgm.h>

    enum                PgmTextEllipsize;
    enum                PgmTextAlignment;
    enum                PgmTextWrap;
    enum                PgmTextGravity;
    enum                PgmTextStretch;
    enum                PgmTextStyle;
    enum                PgmTextVariant;
    enum                PgmTextWeight;
    enum                PgmTextShadowPosition;
                        PgmText;
    PgmDrawable *       pgm_text_new                        (const gchar *markup);
    PgmError            pgm_text_set_label                  (PgmText *text,
                                                             const gchar *label);
    PgmError            pgm_text_set_markup                 (PgmText *text,
                                                             const gchar *markup);
    PgmError            pgm_text_get_label                  (PgmText *text,
                                                             gchar **label);
    PgmError            pgm_text_set_font_family            (PgmText *text,
                                                             const gchar *font_family);
    PgmError            pgm_text_get_font_family            (PgmText *text,
                                                             gchar **font_family);
    PgmError            pgm_text_set_font_height            (PgmText *text,
                                                             gfloat font_height);
    PgmError            pgm_text_get_font_height            (PgmText *text,
                                                             gfloat *font_height);
    PgmError            pgm_text_set_ellipsize              (PgmText *text,
                                                             PgmTextEllipsize ellipsize);
    PgmError            pgm_text_get_ellipsize              (PgmText *text,
                                                             PgmTextEllipsize *ellipsize);
    PgmError            pgm_text_set_justify                (PgmText *text,
                                                             gboolean justify);
    PgmError            pgm_text_get_justify                (PgmText *text,
                                                             gboolean *justify);
    PgmError            pgm_text_set_alignment              (PgmText *text,
                                                             PgmTextAlignment alignment);
    PgmError            pgm_text_get_alignment              (PgmText *text,
                                                             PgmTextAlignment *alignment);
    PgmError            pgm_text_set_wrap                   (PgmText *text,
                                                             PgmTextWrap wrap);
    PgmError            pgm_text_get_wrap                   (PgmText *text,
                                                             PgmTextWrap *wrap);
    PgmError            pgm_text_set_gravity                (PgmText *text,
                                                             PgmTextGravity gravity);
    PgmError            pgm_text_get_gravity                (PgmText *text,
                                                             PgmTextGravity *gravity);
    PgmError            pgm_text_set_stretch                (PgmText *text,
                                                             PgmTextStretch stretch);
    PgmError            pgm_text_get_stretch                (PgmText *text,
                                                             PgmTextStretch *stretch);
    PgmError            pgm_text_set_style                  (PgmText *text,
                                                             PgmTextStyle style);
    PgmError            pgm_text_get_style                  (PgmText *text,
                                                             PgmTextStyle *style);
    PgmError            pgm_text_set_variant                (PgmText *text,
                                                             PgmTextVariant variant);
    PgmError            pgm_text_get_variant                (PgmText *text,
                                                             PgmTextVariant *variant);
    PgmError            pgm_text_set_weight                 (PgmText *text,
                                                             PgmTextWeight weight);
    PgmError            pgm_text_get_weight                 (PgmText *text,
                                                             PgmTextWeight *weight);
    PgmError            pgm_text_set_multiline              (PgmText *text,
                                                             gboolean multiline);
    PgmError            pgm_text_get_multiline              (PgmText *text,
                                                             gboolean *multiline);
    PgmError            pgm_text_set_line_spacing           (PgmText *text,
                                                             gfloat line_spacing);
    PgmError            pgm_text_get_line_spacing           (PgmText *text,
                                                             gfloat *line_spacing);
    PgmError            pgm_text_set_color                  (PgmText *text,
                                                             guchar red,
                                                             guchar green,
                                                             guchar blue,
                                                             guchar alpha);
    PgmError            pgm_text_get_color                  (PgmText *text,
                                                             guchar *red,
                                                             guchar *green,
                                                             guchar *blue,
                                                             guchar *alpha);
    PgmError            pgm_text_set_outline_color          (PgmText *text,
                                                             guchar red,
                                                             guchar green,
                                                             guchar blue,
                                                             guchar alpha);
    PgmError            pgm_text_get_outline_color          (PgmText *text,
                                                             guchar *red,
                                                             guchar *green,
                                                             guchar *blue,
                                                             guchar *alpha);
    PgmError            pgm_text_set_outline_width          (PgmText *text,
                                                             gfloat width);
    PgmError            pgm_text_get_outline_width          (PgmText *text,
                                                             gfloat *width);
    PgmError            pgm_text_set_cast_shadow            (PgmText *text,
                                                             gboolean cast_shadow);
    PgmError            pgm_text_get_cast_shadow            (PgmText *text,
                                                             gboolean *cast_shadow);
    PgmError            pgm_text_set_shadow_position        (PgmText *text,
                                                             PgmTextShadowPosition position);
    PgmError            pgm_text_get_shadow_position        (PgmText *text,
                                                             PgmTextShadowPosition *position);
    PgmError            pgm_text_set_shadow_color           (PgmText *text,
                                                             guchar red,
                                                             guchar green,
                                                             guchar blue,
                                                             guchar alpha);
    PgmError            pgm_text_get_shadow_color           (PgmText *text,
                                                             guchar *red,
                                                             guchar *green,
                                                             guchar *blue,
                                                             guchar *alpha);

## Object Hierarchy

      GObject
       +----GstObject
             +----PgmDrawable
                   +----PgmText

## Description

PgmText is a drawable displaying a text with support for multiple lines, markups and several properties. The specified text is then arranged to fit inside the drawable size. Fonts are specified through face name and attributes. The font height is given in canvas coordinates.

FIXME: • Describe the markup syntax. • Describe the different capabilities.

Last reviewed on 2007-05-18 (0.1.5)

## Details

### enum PgmTextEllipsize

    typedef enum {
      PGM_TEXT_ELLIPSIZE_NONE,
      PGM_TEXT_ELLIPSIZE_START,
      PGM_TEXT_ELLIPSIZE_MIDDLE,
      PGM_TEXT_ELLIPSIZE_END
    } PgmTextEllipsize;

The different text ellipsizings.

`PGM_TEXT_ELLIPSIZE_NONE` | No ellipsization.
`PGM_TEXT_ELLIPSIZE_START` | Omit characters at the start of the text.
`PGM_TEXT_ELLIPSIZE_MIDDLE` | Omit characters in the middle of the text.
`PGM_TEXT_ELLIPSIZE_END` | Omit characters at the end of the text.

### enum PgmTextAlignment

    typedef enum {
      PGM_TEXT_ALIGN_LEFT,
      PGM_TEXT_ALIGN_CENTER,
      PGM_TEXT_ALIGN_RIGHT
    } PgmTextAlignment;

The different text alignments.

`PGM_TEXT_ALIGN_LEFT` | Put all available space on the right.
`PGM_TEXT_ALIGN_CENTER` | Center the line within the available space.
`PGM_TEXT_ALIGN_RIGHT` | Put all available space on the left.

### enum PgmTextWrap

    typedef enum {
      PGM_TEXT_WRAP_WORD,
      PGM_TEXT_WRAP_CHAR,
      PGM_TEXT_WRAP_WORD_CHAR
    } PgmTextWrap;

The different text wrappings.

`PGM_TEXT_WRAP_WORD` | Wrap lines at word boundaries.
`PGM_TEXT_WRAP_CHAR` | Wrap lines at character boundaries.
`PGM_TEXT_WRAP_WORD_CHAR` | Wrap lines at word boundaries, but fall back to character boundaries if there is not enough space for a full word.

### enum PgmTextGravity

    typedef enum {
      PGM_TEXT_GRAVITY_SOUTH,
      PGM_TEXT_GRAVITY_EAST,
      PGM_TEXT_GRAVITY_NORTH,
      PGM_TEXT_GRAVITY_WEST,
      PGM_TEXT_GRAVITY_AUTO
    } PgmTextGravity;

The different text gravities.

`PGM_TEXT_GRAVITY_SOUTH` | Glyphs stand upright.
`PGM_TEXT_GRAVITY_EAST` | Glyphs are rotated 90 degrees clockwise.
`PGM_TEXT_GRAVITY_NORTH` | Glyphs are upside-down.
`PGM_TEXT_GRAVITY_WEST` | Glyphs are rotated 90 degrees counter-clockwise.
`PGM_TEXT_GRAVITY_AUTO` | Gravity is resolved automatically.

### enum PgmTextStretch

    typedef enum {
      PGM_TEXT_STRETCH_CONDENSED,
      PGM_TEXT_STRETCH_NORMAL,
      PGM_TEXT_STRETCH_EXPANDED
    } PgmTextStretch;

The different text stretchings.

`PGM_TEXT_STRETCH_CONDENSED` | Condensed width.
`PGM_TEXT_STRETCH_NORMAL` | Normal width.
`PGM_TEXT_STRETCH_EXPANDED` | Expanded width.

### enum PgmTextStyle

    typedef enum {
      PGM_TEXT_STYLE_NORMAL,
      PGM_TEXT_STYLE_OBLIQUE,
      PGM_TEXT_STYLE_ITALIC
    } PgmTextStyle;

The different text styles.

`PGM_TEXT_STYLE_NORMAL` | The font is upright.
`PGM_TEXT_STYLE_OBLIQUE` | The font is slanted, but in a roman style.
`PGM_TEXT_STYLE_ITALIC` | The font is slanted in an italic style.

### enum PgmTextVariant

    typedef enum {
      PGM_TEXT_VARIANT_NORMAL,
      PGM_TEXT_VARIANT_SMALL_CAPS
    } PgmTextVariant;

The different text variants.

`PGM_TEXT_VARIANT_NORMAL` | Normal font.
`PGM_TEXT_VARIANT_SMALL_CAPS` | Font with the lower case characters replaced by smaller variants of the capital characters.

### enum PgmTextWeight

    typedef enum {
      PGM_TEXT_WEIGHT_LIGHT,
      PGM_TEXT_WEIGHT_NORMAL,
      PGM_TEXT_WEIGHT_BOLD
    } PgmTextWeight;

The different text weights.

`PGM_TEXT_WEIGHT_LIGHT` | The light weight.
`PGM_TEXT_WEIGHT_NORMAL` | The normal weight.
`PGM_TEXT_WEIGHT_BOLD` | The bold weight.

### enum PgmTextShadowPosition

    typedef enum {
      PGM_TEXT_SHADOW_NORTH      = (1 << 0),
      PGM_TEXT_SHADOW_SOUTH      = (1 << 1),
      PGM_TEXT_SHADOW_WEST       = (1 << 2),
      PGM_TEXT_SHADOW_EAST       = (1 << 3),
      PGM_TEXT_SHADOW_NORTH_WEST = (PGM_TEXT_SHADOW_NORTH | PGM_TEXT_SHADOW_WEST),
      PGM_TEXT_SHADOW_NORTH_EAST = (PGM_TEXT_SHADOW_NORTH | PGM_TEXT_SHADOW_EAST),
      PGM_TEXT_SHADOW_SOUTH_WEST = (PGM_TEXT_SHADOW_SOUTH | PGM_TEXT_SHADOW_WEST),
      PGM_TEXT_SHADOW_SOUTH_EAST = (PGM_TEXT_SHADOW_SOUTH | PGM_TEXT_SHADOW_EAST)
    } PgmTextShadowPosition;

The text's shadow cast position.

`PGM_TEXT_SHADOW_NORTH` | Shadow casted to the North.
`PGM_TEXT_SHADOW_SOUTH` | Shadow casted to the South.
`PGM_TEXT_SHADOW_WEST` | Shadow casted to the West.
`PGM_TEXT_SHADOW_EAST` | Shadow casted to the East.
`PGM_TEXT_SHADOW_NORTH_WEST` | Shadow casted to the North/West.
`PGM_TEXT_SHADOW_NORTH_EAST` | Shadow casted to the North/East.
`PGM_TEXT_SHADOW_SOUTH_WEST` | Shadow casted to the South/West.
`PGM_TEXT_SHADOW_SOUTH_EAST` | Shadow casted to the South/East.

### PgmText

    typedef struct {
      /* Label */
      gchar *label;

      /* Font properties */
      gchar          *font_family;
      PgmTextGravity  gravity;
      PgmTextStretch  stretch;
      PgmTextStyle    style;
      PgmTextVariant  variant;
      PgmTextWeight   weight;
      gfloat          height;

      /* Text adjustment */
      PgmTextEllipsize ellipsize;
      PgmTextAlignment alignment;
      PgmTextWrap      wrap;
      gfloat           line_spacing;
      gboolean         justify;
      gboolean         multiline;

      gboolean cast_shadow;
      PgmTextShadowPosition shadow_position;
      gfloat outline_width;

      /* Colors */
      guchar r, g, b, a;
      guchar shadow_r, shadow_g, shadow_b, shadow_a;
      guchar outline_r, outline_g, outline_b, outline_a;
    } PgmText;

The PgmText structure.

gchar *`label`; | the text label.
gchar *`font_family`; | the text font family.
PgmTextGravity `gravity`; | the text gravity.
PgmTextStretch `stretch`; | the text stretching.
PgmTextStyle `style`; | the text style.
PgmTextVariant `variant`; | the text variant.
PgmTextWeight `weight`; | the text weight.
gfloat `height`; | the text height in proportion to the drawable height.
PgmTextEllipsize `ellipsize`; | the text ellipsizing.
PgmTextAlignment `alignment`; | the text alignment.
PgmTextWrap `wrap`; | the text wrapping.
gfloat `line_spacing`; | the space between to lines of text in canvas coordinates.
gboolean `justify`; | the text justification.
gboolean `multiline`; | the text multilining.
gboolean `cast_shadow`; | the text shadow casting state.
PgmTextShadowPosition `shadow_position`; | the text shadow position.
gfloat `outline_width`; | the text outline width in canvas coordinates.
guchar `r`; | the text red color component.
guchar `g`; | the text blue color component.
guchar `b`; | the text green color component.
guchar `a`; | the text alpha color component.
guchar `shadow_r`; | the text shadow red color component.
guchar `shadow_g`; | the text shadow blue color component.
guchar `shadow_b`; | the text shadow green color component.
guchar `shadow_a`; | the text shadow alpha color component.
guchar `outline_r`; | the text outline red color component.
guchar `outline_g`; | the text outline blue color component.
guchar `outline_b`; | the text outline green color component.
guchar `outline_a`; | the text outline alpha color component.

### pgm_text_new ()

    PgmDrawable *       pgm_text_new                        (const gchar *markup);

Creates a new PgmText instance.

MT safe.

`markup` : | the markup string.
Returns : | a new PgmText instance.

### pgm_text_set_label ()

    PgmError            pgm_text_set_label                  (PgmText *text,
                                                             const gchar *label);

Sets label of `text` to `label`. `label` has to be a NULL-terminated string. The default label is the empty one "".

MT safe.

`text` : | a PgmText object.
`label` : | the label string.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_markup ()

    PgmError            pgm_text_set_markup                 (PgmText *text,
                                                             const gchar *markup);

Sets markup of `text` to `markup`. `markup` has to be a NULL-terminated string. The default label is the empty one "".

MT safe.

`text` : | a PgmText object.
`markup` : | the markup string.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_label ()

    PgmError            pgm_text_get_label                  (PgmText *text,
                                                             gchar **label);

Retrieves the current label of `text` in `label`. If a markup is currently used, the full markup is retrieved.

MT safe.

`text` : | a PgmText object.
`label` : | a pointer to a pointer to a gchar where the label string will be stored. `g_free()` after use.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_font_family ()

    PgmError            pgm_text_set_font_family            (PgmText *text,
                                                             const gchar *font_family);

Sets the font family of `text` to `font_family`. The default font family name is "Sans".

MT safe.

`text` : | a PgmText object.
`font_family` : | the font-family string.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_font_family ()

    PgmError            pgm_text_get_font_family            (PgmText *text,
                                                             gchar **font_family);

Retrieves the current font-family of `text` in `label`.

MT safe.

`text` : | a PgmText object.
`font_family` : | a pointer to a pointer to a gchar where the font family string will be stored. `g_free()` after use.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_font_height ()

    PgmError            pgm_text_set_font_height            (PgmText *text,
                                                             gfloat font_height);

Sets the height of `text` to `font_height` in canvas coordinates. The default height is 1.0f.

MT safe.

`text` : | a PgmText object.
`font_height` : | the text height in canvas coordinates.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_font_height ()

    PgmError            pgm_text_get_font_height            (PgmText *text,
                                                             gfloat *font_height);

Retrieves the height of `text` in `height`.

MT safe.

`text` : | a PgmText object.
`font_height` : | a pointer to a gfloat where the text height is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_ellipsize ()

    PgmError            pgm_text_set_ellipsize              (PgmText *text,
                                                             PgmTextEllipsize ellipsize);

Sets ellipsizing of `text` to `ellipsize`. Only takes effect when `text` gets to large to fit the drawable size. The default value is PGM_TEXT_ELLIPSIZE_NONE.

MT safe.

`text` : | a PgmText object.
`ellipsize` : | the text ellipsizing.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_ellipsize ()

    PgmError            pgm_text_get_ellipsize              (PgmText *text,
                                                             PgmTextEllipsize *ellipsize);

Retrieves the ellipsizing of `text` in `ellipsize`.

MT safe.

`text` : | a PgmText object.
`ellipsize` : | a pointer to a PgmTextEllipsize where the text ellipsizing is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_justify ()

    PgmError            pgm_text_set_justify                (PgmText *text,
                                                             gboolean justify);

Enables or not justification of `text`. If `justify` is TRUE, text is expanded to fill the whole drawable width.

MT safe.

`text` : | a PgmText object.
`justify` : | the text justification state.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_justify ()

    PgmError            pgm_text_get_justify                (PgmText *text,
                                                             gboolean *justify);

Retrieves the justification state of `text` in `justify`.

MT safe.

`text` : | a PgmText object.
`justify` : | a pointer to a gboolean where the justification state is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_alignment ()

    PgmError            pgm_text_set_alignment              (PgmText *text,
                                                             PgmTextAlignment alignment);

Sets alignment of `text` to `alignment`. The default value is PGM_TEXT_ALIGN_LEFT.

MT safe.

`text` : | a PgmText object.
`alignment` : | the text alignment.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_alignment ()

    PgmError            pgm_text_get_alignment              (PgmText *text,
                                                             PgmTextAlignment *alignment);

Retrieves the alignment of `text` in `alignment`.

MT safe.

`text` : | a PgmText object.
`alignment` : | a pointer to a PgmTextAlignment where the text alignment is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_wrap ()

    PgmError            pgm_text_set_wrap                   (PgmText *text,
                                                             PgmTextWrap wrap);

Sets wrapping of `text` to `wrap`. The default value is PGM_TEXT_WRAP_WORD.

MT safe.

`text` : | a PgmText object.
`wrap` : | the text wrapping.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_wrap ()

    PgmError            pgm_text_get_wrap                   (PgmText *text,
                                                             PgmTextWrap *wrap);

Retrieves the wrapping of `text` in `wrap`.

MT safe.

`text` : | a PgmText object.
`wrap` : | a pointer to a PgmTextWrap where the text wrapping is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_gravity ()

    PgmError            pgm_text_set_gravity                (PgmText *text,
                                                             PgmTextGravity gravity);

Sets gravity of `text` to `gravity`. The default value is PGM_TEXT_GRAVITY_AUTO.

MT safe.

`text` : | a PgmText object.
`gravity` : | the text gravity.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_gravity ()

    PgmError            pgm_text_get_gravity                (PgmText *text,
                                                             PgmTextGravity *gravity);

Retrieves the gravity of `text` in `gravity`.

MT safe.

`text` : | a PgmText object.
`gravity` : | a pointer to a PgmTextGravity where the text gravity is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_stretch ()

    PgmError            pgm_text_set_stretch                (PgmText *text,
                                                             PgmTextStretch stretch);

Sets stretching of `text` to `stretch`. The default value is PGM_TEXT_STRETCH_NORMAL.

MT safe.

`text` : | a PgmText object.
`stretch` : | the text stretching.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_stretch ()

    PgmError            pgm_text_get_stretch                (PgmText *text,
                                                             PgmTextStretch *stretch);

Retrieves the stretching of `text` in `stretch`.

MT safe.

`text` : | a PgmText object.
`stretch` : | a pointer to a PgmTextStretch where the text stretching is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_style ()

    PgmError            pgm_text_set_style                  (PgmText *text,
                                                             PgmTextStyle style);

Sets style of `text` to `style`. The default value is PGM_TEXT_STYLE_NORMAL.

MT safe.

`text` : | a PgmText object.
`style` : | the text style.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_style ()

    PgmError            pgm_text_get_style                  (PgmText *text,
                                                             PgmTextStyle *style);

Retrieves the style of `text` in `style`.

MT safe.

`text` : | a PgmText object.
`style` : | a pointer to a PgmTextStyle where the text style is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_variant ()

    PgmError            pgm_text_set_variant                (PgmText *text,
                                                             PgmTextVariant variant);

Sets variant of `text` to `variant`. The default value is PGM_TEXT_VARIANT_NORMAL.

MT safe.

`text` : | a PgmText object.
`variant` : | the text variant.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_variant ()

    PgmError            pgm_text_get_variant                (PgmText *text,
                                                             PgmTextVariant *variant);

Retrieves the variant of `text` in `variant`.

MT safe.

`text` : | a PgmText object.
`variant` : | a pointer to a PgmTextVariant where the text variant is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_weight ()

    PgmError            pgm_text_set_weight                 (PgmText *text,
                                                             PgmTextWeight weight);

Sets weight of `text` to `weight`. The default value is PGM_TEXT_WEIGHT_NORMAL.

MT safe.

`text` : | a PgmText object.
`weight` : | the text weight.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_weight ()

    PgmError            pgm_text_get_weight                 (PgmText *text,
                                                             PgmTextWeight *weight);

Retrieves the weight of `text` in `weight`.

MT safe.

`text` : | a PgmText object.
`weight` : | a pointer to a PgmTextWeight where the text weight is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_multiline ()

    PgmError            pgm_text_set_multiline              (PgmText *text,
                                                             gboolean multiline);

Sets the multilining state of `text` to `multiline`. When multilining is disabled, the text is displayed on one line and vertically centered in the drawable. The default value is TRUE.

MT safe.

`text` : | a PgmText object.
`multiline` : | the multilining state.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_multiline ()

    PgmError            pgm_text_get_multiline              (PgmText *text,
                                                             gboolean *multiline);

Retrieves the multilining state of `text` in `multiline`.

MT safe.

`text` : | a PgmText object.
`multiline` : | a pointer to a gboolean where the multilining state is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_line_spacing ()

    PgmError            pgm_text_set_line_spacing           (PgmText *text,
                                                             gfloat line_spacing);

Sets the space between two lines of `text` to `line_spacing` in canvas coordinates. The default value is 0.0f.

MT safe.

`text` : | a PgmText object.
`line_spacing` : | the line spacing.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_line_spacing ()

    PgmError            pgm_text_get_line_spacing           (PgmText *text,
                                                             gfloat *line_spacing);

Retrieves the space between two lines of `text` in `line_spacing`.

MT safe.

`text` : | a PgmText object.
`line_spacing` : | a pointer to a gfloat where the line spacing is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_color ()

    PgmError            pgm_text_set_color                  (PgmText *text,
                                                             guchar red,
                                                             guchar green,
                                                             guchar blue,
                                                             guchar alpha);

Sets the color of `text` to (`red`, `green`, `blue`, `alpha`).

MT safe.

`text` : | a PgmText object.
`red` : | the text red color component.
`green` : | the text green color component.
`blue` : | the text blue color component.
`alpha` : | the text alpha color component.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_color ()

    PgmError            pgm_text_get_color                  (PgmText *text,
                                                             guchar *red,
                                                             guchar *green,
                                                             guchar *blue,
                                                             guchar *alpha);

Retrieves the color of `text` in (`red`, `green`, `blue`, `alpha`).

MT safe.

`text` : | a PgmText object.
`red` : | a pointer to a guchar where the red color component is going to be stored.
`green` : | a pointer to a guchar where the green color component is going to be stored.
`blue` : | a pointer to a guchar where the blue color component is going to be stored.
`alpha` : | a pointer to a guchar where the alpha color component is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_outline_color ()

    PgmError            pgm_text_set_outline_color          (PgmText *text,
                                                             guchar red,
                                                             guchar green,
                                                             guchar blue,
                                                             guchar alpha);

Sets the outline color of `text` to (`red`, `green`, `blue`, `alpha`).

MT safe.

`text` : | a PgmText object.
`red` : | the text outline red color component.
`green` : | the text outline green color component.
`blue` : | the text outline blue color component.
`alpha` : | the text outline alpha color component.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_outline_color ()

    PgmError            pgm_text_get_outline_color          (PgmText *text,
                                                             guchar *red,
                                                             guchar *green,
                                                             guchar *blue,
                                                             guchar *alpha);

Retrieves the outline color of `text` in (`red`, `green`, `blue`, `alpha`).

MT safe.

`text` : | a PgmText object.
`red` : | a pointer to a guchar where the outline red color component is going to be stored.
`green` : | a pointer to a guchar where the outline green color component is going to be stored.
`blue` : | a pointer to a guchar where the outline blue color component is going to be stored.
`alpha` : | a pointer to a guchar where the outline alpha color component is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_outline_width ()

    PgmError            pgm_text_set_outline_width          (PgmText *text,
                                                             gfloat width);

Sets the outline width (thickness) of `text` to `width` in canvas coordinates. The default value is 0.0f.

MT safe.

`text` : | a PgmText object.
`width` : | the text outline width.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_outline_width ()

    PgmError            pgm_text_get_outline_width          (PgmText *text,
                                                             gfloat *width);

Retrieves the outline width (thickness) of `text` in `width`.

MT safe.

`text` : | a PgmText object.
`width` : | a pointer to a gfloat where the text outline width is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_cast_shadow ()

    PgmError            pgm_text_set_cast_shadow            (PgmText *text,
                                                             gboolean cast_shadow);

Sets the shadow casting state of `text` to `cast_shadow`. When shadow casting is enabled, the text is displayed with a shadow behind it. The default value is FALSE.

MT safe.

`text` : | a PgmText object.
`cast_shadow` : | the shadow casting state.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_cast_shadow ()

    PgmError            pgm_text_get_cast_shadow            (PgmText *text,
                                                             gboolean *cast_shadow);

Retrieves the shadow casting state of `text` in `cast_shadow`.

MT safe.

`text` : | a PgmText object.
`cast_shadow` : | a pointer to a gboolean where the shadow casting state is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_shadow_position ()

    PgmError            pgm_text_set_shadow_position        (PgmText *text,
                                                             PgmTextShadowPosition position);

Sets the shadow position of `text` to `position`. The default value is PGM_TEXT_SHADOW_TOP.

MT safe.

`text` : | a PgmText object.
`position` : | the text shadow position.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_shadow_position ()

    PgmError            pgm_text_get_shadow_position        (PgmText *text,
                                                             PgmTextShadowPosition *position);

Retrieves the shadow position of `text` in `position`.

MT safe.

`text` : | a PgmText object.
`position` : | a pointer to a PgmTextShadowPosition where the text shadow position is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_text_set_shadow_color ()

    PgmError            pgm_text_set_shadow_color           (PgmText *text,
                                                             guchar red,
                                                             guchar green,
                                                             guchar blue,
                                                             guchar alpha);

Sets the shadow color of `text` to (`red`, `green`, `blue`, `alpha`).

MT safe.

`text` : | a PgmText object.
`red` : | the text shadow red color component.
`green` : | the text shadow green color component.
`blue` : | the text shadow blue color component.
`alpha` : | the text shadow alpha color component.
Returns : | A PgmError indicating success/failure.

### pgm_text_get_shadow_color ()

    PgmError            pgm_text_get_shadow_color           (PgmText *text,
                                                             guchar *red,
                                                             guchar *green,
                                                             guchar *blue,
                                                             guchar *alpha);

Retrieves the shadow color of `text` in (`red`, `green`, `blue`, `alpha`).

MT safe.

`text` : | a PgmText object.
`red` : | a pointer to a guchar where the shadow red color component is going to be stored.
`green` : | a pointer to a guchar where the shadow green color component is going to be stored.
`blue` : | a pointer to a guchar where the shadow blue color component is going to be stored.
`alpha` : | a pointer to a guchar where the shadow alpha color component is going to be stored.
Returns : | A PgmError indicating success/failure.

## See Also

#PgmDrawable, PgmImage.