gnome-icon-text

Name

gnome-icon-text -- Text wrapping functions for icon captions.

Synopsis


#include <gnome.h>


struct      GnomeIconTextInfoRow;
struct      GnomeIconTextInfo;
GnomeIconTextInfo* gnome_icon_layout_text   (GdkFont *font,
                                             char *text,
                                             char *separators,
                                             int max_width,
                                             int confine);
void        gnome_icon_paint_text           (GnomeIconTextInfo *ti,
                                             GdkDrawable *drawable,
                                             GdkGC *gc,
                                             int x,
                                             int y,
                                             GtkJustification just);
void        gnome_icon_text_info_free       (GnomeIconTextInfo *ti);

Description

This module implements a generic and simple interface for wrapping text and painting it to a drawable. It is used by the GnomeIconTextItem object to perform word wrapping for icon text captions.

Details

struct GnomeIconTextInfoRow

typedef struct {
	char *text;
	int width;
	GdkWChar *text_wc;	/* text in wide characters */
	int text_length;	/* number of characters */
} GnomeIconTextInfoRow;

This structure defines a row of text in the list of wrapped text rows of the GnomeIconTextInfo structure. The text field contains the text that fits in that row, and width contains the width in pixels of that text, calculated with respect to the font that was used to format the text.


struct GnomeIconTextInfo

typedef struct {
	GList *rows;
	GdkFont *font;
	int width;
	int height;
	int baseline_skip;
} GnomeIconTextInfo;

This structure contains the information about a wrapped text string. The rows field is a list of GnomeIconTextInfoRow structures with the final rows of text. The width, height, and baseline_skip fields contain the total width, total height, and baseline height of the text in pixels, respectively.


gnome_icon_layout_text ()

GnomeIconTextInfo* gnome_icon_layout_text   (GdkFont *font,
                                             char *text,
                                             char *separators,
                                             int max_width,
                                             int confine);

Creates a new &GnomeIconTextInfo structure by wrapping the specified text. If non-NULL, the separators argument defines a set of characters to be used as word delimiters for performing word wrapping. If it is NULL, then only spaces will be used as word delimiters.

The max_width argument is used to specify the width at which word wrapping will be performed. If there is a very long word that does not fit in a single line, the confine argument can be used to specify whether the word should be unconditionally split to fit or whether the maximum width should be increased as necessary.

font : Name of the font that will be used to render the text.
text : Text to be formatted.
separators : Separators used for word wrapping, can be NULL.
max_width : Width in pixels to be used for word wrapping.
confine : Whether it is mandatory to wrap at max_width.
Returns : A newly-created &GnomeIconTextInfo structure.


gnome_icon_paint_text ()

void        gnome_icon_paint_text           (GnomeIconTextInfo *ti,
                                             GdkDrawable *drawable,
                                             GdkGC *gc,
                                             int x,
                                             int y,
                                             GtkJustification just);

Paints the formatted text in the icon text info structure onto a drawable. This is just a sample implementation; applications can choose to use other rendering functions.

ti : An icon text info structure.
drawable : Target drawable.
gc : GC used to render the string.
x : Left coordinate for text.
y : Upper coordinate for text.
just : Justification for text.


gnome_icon_text_info_free ()

void        gnome_icon_text_info_free       (GnomeIconTextInfo *ti);

Frees a &GnomeIconTextInfo structure. You should call this instead of freeing the structure yourself.

ti : An icon text info structure.

See Also

GnomeIconTextItem