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;
            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_line_spacing       (PgmText *text,
                                             gfloat line_spacing);
PgmError    pgm_text_get_line_spacing       (PgmText *text,
                                             gfloat *line_spacing);
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);


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.

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;

  /* Outline parameters */
  guchar outline_r, outline_g, outline_b, outline_a;
  gfloat outline_width;
} 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.
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.
gfloat outline_width; the text outline width in canvas coordinates.

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 proportion to the height of the drawable. The default height is 1.0f, which fills the drawable in height. font_height will be the maximum height of a line of text (i.e. the height of something like "Čq", measured from the bottom of the 'q' to the top of the accent on the 'Č').

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_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_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.

See Also

PgmDrawable, PgmImage.