![]() |
![]() |
![]() |
Pigment 0.3 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
#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);
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)
typedef enum { PGM_TEXT_ELLIPSIZE_NONE, PGM_TEXT_ELLIPSIZE_START, PGM_TEXT_ELLIPSIZE_MIDDLE, PGM_TEXT_ELLIPSIZE_END } PgmTextEllipsize;
The different text ellipsizings.
typedef enum { PGM_TEXT_ALIGN_LEFT, PGM_TEXT_ALIGN_CENTER, PGM_TEXT_ALIGN_RIGHT } PgmTextAlignment;
The different text alignments.
typedef enum { PGM_TEXT_WRAP_WORD, PGM_TEXT_WRAP_CHAR, PGM_TEXT_WRAP_WORD_CHAR } PgmTextWrap;
The different text wrappings.
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.
typedef enum { PGM_TEXT_STRETCH_CONDENSED, PGM_TEXT_STRETCH_NORMAL, PGM_TEXT_STRETCH_EXPANDED } PgmTextStretch;
The different text stretchings.
typedef enum { PGM_TEXT_STYLE_NORMAL, PGM_TEXT_STYLE_OBLIQUE, PGM_TEXT_STYLE_ITALIC } PgmTextStyle;
The different text styles.
typedef enum { PGM_TEXT_VARIANT_NORMAL, PGM_TEXT_VARIANT_SMALL_CAPS } PgmTextVariant;
The different text variants.
typedef enum { PGM_TEXT_WEIGHT_LIGHT, PGM_TEXT_WEIGHT_NORMAL, PGM_TEXT_WEIGHT_BOLD } PgmTextWeight;
The different text weights.
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.
Shadow casted to the North. | |
Shadow casted to the South. | |
Shadow casted to the West. | |
Shadow casted to the East. | |
Shadow casted to the North/West. | |
Shadow casted to the North/East. | |
Shadow casted to the South/West. | |
Shadow casted to the South/East. |
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 * |
the text label. |
gchar * |
the text font family. |
PgmTextGravity |
the text gravity. |
PgmTextStretch |
the text stretching. |
PgmTextStyle |
the text style. |
PgmTextVariant |
the text variant. |
PgmTextWeight |
the text weight. |
gfloat |
the text height in proportion to the drawable height. |
PgmTextEllipsize |
the text ellipsizing. |
PgmTextAlignment |
the text alignment. |
PgmTextWrap |
the text wrapping. |
gfloat |
the space between to lines of text in canvas coordinates. |
gboolean |
the text justification. |
gboolean |
the text multilining. |
gboolean |
the text shadow casting state. |
PgmTextShadowPosition |
the text shadow position. |
gfloat |
the text outline width in canvas coordinates. |
guchar |
the text red color component. |
guchar |
the text blue color component. |
guchar |
the text green color component. |
guchar |
the text alpha color component. |
guchar |
the text shadow red color component. |
guchar |
the text shadow blue color component. |
guchar |
the text shadow green color component. |
guchar |
the text shadow alpha color component. |
guchar |
the text outline red color component. |
guchar |
the text outline blue color component. |
guchar |
the text outline green color component. |
guchar |
the text outline alpha color component. |
PgmDrawable * pgm_text_new (const gchar *markup);
Creates a new PgmText instance.
MT safe.
|
the markup string. |
Returns : |
a new PgmText instance. |
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.
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.
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.
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.
PgmError pgm_text_get_font_family (PgmText *text, gchar **font_family);
Retrieves the current font-family of text
in label
.
MT safe.
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.
PgmError pgm_text_get_font_height (PgmText *text, gfloat *font_height);
Retrieves the height of text
in height
.
MT safe.
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.
PgmError pgm_text_get_ellipsize (PgmText *text, PgmTextEllipsize *ellipsize);
Retrieves the ellipsizing of text
in ellipsize
.
MT safe.
|
a PgmText object. |
|
a pointer to a PgmTextEllipsize where the text ellipsizing is going to be stored. |
Returns : |
A PgmError indicating success/failure. |
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.
PgmError pgm_text_get_justify (PgmText *text, gboolean *justify);
Retrieves the justification state of text
in justify
.
MT safe.
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.
PgmError pgm_text_get_alignment (PgmText *text, PgmTextAlignment *alignment);
Retrieves the alignment of text
in alignment
.
MT safe.
|
a PgmText object. |
|
a pointer to a PgmTextAlignment where the text alignment is going to be stored. |
Returns : |
A PgmError indicating success/failure. |
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.
PgmError pgm_text_get_wrap (PgmText *text, PgmTextWrap *wrap);
Retrieves the wrapping of text
in wrap
.
MT safe.
|
a PgmText object. |
|
a pointer to a PgmTextWrap where the text wrapping is going to be stored. |
Returns : |
A PgmError indicating success/failure. |
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.
PgmError pgm_text_get_gravity (PgmText *text, PgmTextGravity *gravity);
Retrieves the gravity of text
in gravity
.
MT safe.
|
a PgmText object. |
|
a pointer to a PgmTextGravity where the text gravity is going to be stored. |
Returns : |
A PgmError indicating success/failure. |
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.
PgmError pgm_text_get_stretch (PgmText *text, PgmTextStretch *stretch);
Retrieves the stretching of text
in stretch
.
MT safe.
|
a PgmText object. |
|
a pointer to a PgmTextStretch where the text stretching is going to be stored. |
Returns : |
A PgmError indicating success/failure. |
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.
PgmError pgm_text_get_style (PgmText *text, PgmTextStyle *style);
Retrieves the style of text
in style
.
MT safe.
|
a PgmText object. |
|
a pointer to a PgmTextStyle where the text style is going to be stored. |
Returns : |
A PgmError indicating success/failure. |
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.
PgmError pgm_text_get_variant (PgmText *text, PgmTextVariant *variant);
Retrieves the variant of text
in variant
.
MT safe.
|
a PgmText object. |
|
a pointer to a PgmTextVariant where the text variant is going to be stored. |
Returns : |
A PgmError indicating success/failure. |
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.
PgmError pgm_text_get_weight (PgmText *text, PgmTextWeight *weight);
Retrieves the weight of text
in weight
.
MT safe.
|
a PgmText object. |
|
a pointer to a PgmTextWeight where the text weight is going to be stored. |
Returns : |
A PgmError indicating success/failure. |
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.
PgmError pgm_text_get_multiline (PgmText *text, gboolean *multiline);
Retrieves the multilining state of text
in multiline
.
MT safe.
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.
PgmError pgm_text_get_line_spacing (PgmText *text, gfloat *line_spacing);
Retrieves the space between two lines of text
in line_spacing
.
MT safe.
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.
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.
|
a PgmText object. |
|
a pointer to a guchar where the red color component is going to be stored. |
|
a pointer to a guchar where the green color component is going to be stored. |
|
a pointer to a guchar where the blue color component is going to be stored. |
|
a pointer to a guchar where the alpha color component is going to be stored. |
Returns : |
A PgmError indicating success/failure. |
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.
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.
|
a PgmText object. |
|
a pointer to a guchar where the outline red color component is going to be stored. |
|
a pointer to a guchar where the outline green color component is going to be stored. |
|
a pointer to a guchar where the outline blue color component is going to be stored. |
|
a pointer to a guchar where the outline alpha color component is going to be stored. |
Returns : |
A PgmError indicating success/failure. |
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.
PgmError pgm_text_get_outline_width (PgmText *text, gfloat *width);
Retrieves the outline width (thickness) of text
in width
.
MT safe.
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.
PgmError pgm_text_get_cast_shadow (PgmText *text, gboolean *cast_shadow);
Retrieves the shadow casting state of text
in cast_shadow
.
MT safe.
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.
PgmError pgm_text_get_shadow_position (PgmText *text, PgmTextShadowPosition *position);
Retrieves the shadow position of text
in position
.
MT safe.
|
a PgmText object. |
|
a pointer to a PgmTextShadowPosition where the text shadow position is going to be stored. |
Returns : |
A PgmError indicating success/failure. |
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.
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.
|
a PgmText object. |
|
a pointer to a guchar where the shadow red color component is going to be stored. |
|
a pointer to a guchar where the shadow green color component is going to be stored. |
|
a pointer to a guchar where the shadow blue color component is going to be stored. |
|
a pointer to a guchar where the shadow alpha color component is going to be stored. |
Returns : |
A PgmError indicating success/failure. |