Gnome User Interface Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# 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

<<< Previous Page | Home | Up | Next Page >>>
gnome-ice | gnome-init