## GtkTextTag

GtkTextTag — A tag that can be applied to text in a GtkTextBuffer

## Synopsis

    #include <gtk/gtk.h>

                GtkTextTag;
    enum        GtkWrapMode;
                GtkTextAttributes;
    GtkTextTag* gtk_text_tag_new                (const gchar *name);
    gint        gtk_text_tag_get_priority       (GtkTextTag *tag);
    void        gtk_text_tag_set_priority       (GtkTextTag *tag,
                                                 gint priority);
    gboolean    gtk_text_tag_event              (GtkTextTag *tag,
                                                 GObject *event_object,
                                                 GdkEvent *event,
                                                 const GtkTextIter *iter);
                GtkTextAppearance;
    GtkTextAttributes* gtk_text_attributes_new  (void);
    GtkTextAttributes* gtk_text_attributes_copy (GtkTextAttributes *src);
    void        gtk_text_attributes_copy_values (GtkTextAttributes *src,
                                                 GtkTextAttributes *dest);
    void        gtk_text_attributes_unref       (GtkTextAttributes *values);
    void        gtk_text_attributes_ref         (GtkTextAttributes *values);

## Object Hierarchy

      GObject
       +----GtkTextTag

## Properties

      "background"           gchararray            : Write
      "background-full-height" gboolean              : Read / Write
      "background-full-height-set" gboolean              : Read / Write
      "background-gdk"       GdkColor              : Read / Write
      "background-set"       gboolean              : Read / Write
      "background-stipple"   GdkPixmap             : Read / Write
      "background-stipple-set" gboolean              : Read / Write
      "direction"            GtkTextDirection      : Read / Write
      "editable"             gboolean              : Read / Write
      "editable-set"         gboolean              : Read / Write
      "family"               gchararray            : Read / Write
      "family-set"           gboolean              : Read / Write
      "font"                 gchararray            : Read / Write
      "font-desc"            PangoFontDescription  : Read / Write
      "foreground"           gchararray            : Write
      "foreground-gdk"       GdkColor              : Read / Write
      "foreground-set"       gboolean              : Read / Write
      "foreground-stipple"   GdkPixmap             : Read / Write
      "foreground-stipple-set" gboolean              : Read / Write
      "indent"               gint                  : Read / Write
      "indent-set"           gboolean              : Read / Write
      "invisible"            gboolean              : Read / Write
      "invisible-set"        gboolean              : Read / Write
      "justification"        GtkJustification      : Read / Write
      "justification-set"    gboolean              : Read / Write
      "language"             gchararray            : Read / Write
      "language-set"         gboolean              : Read / Write
      "left-margin"          gint                  : Read / Write
      "left-margin-set"      gboolean              : Read / Write
      "name"                 gchararray            : Read / Write / Construct Only
      "pixels-above-lines"   gint                  : Read / Write
      "pixels-above-lines-set" gboolean              : Read / Write
      "pixels-below-lines"   gint                  : Read / Write
      "pixels-below-lines-set" gboolean              : Read / Write
      "pixels-inside-wrap"   gint                  : Read / Write
      "pixels-inside-wrap-set" gboolean              : Read / Write
      "right-margin"         gint                  : Read / Write
      "right-margin-set"     gboolean              : Read / Write
      "rise"                 gint                  : Read / Write
      "rise-set"             gboolean              : Read / Write
      "scale"                gdouble               : Read / Write
      "scale-set"            gboolean              : Read / Write
      "size"                 gint                  : Read / Write
      "size-points"          gdouble               : Read / Write
      "size-set"             gboolean              : Read / Write
      "stretch"              PangoStretch          : Read / Write
      "stretch-set"          gboolean              : Read / Write
      "strikethrough"        gboolean              : Read / Write
      "strikethrough-set"    gboolean              : Read / Write
      "style"                PangoStyle            : Read / Write
      "style-set"            gboolean              : Read / Write
      "tabs"                 PangoTabArray         : Read / Write
      "tabs-set"             gboolean              : Read / Write
      "underline"            PangoUnderline        : Read / Write
      "underline-set"        gboolean              : Read / Write
      "variant"              PangoVariant          : Read / Write
      "variant-set"          gboolean              : Read / Write
      "weight"               gint                  : Read / Write
      "weight-set"           gboolean              : Read / Write
      "wrap-mode"            GtkWrapMode           : Read / Write
      "wrap-mode-set"        gboolean              : Read / Write

## Signal Prototypes

    "event"     gboolean    user_function      (GtkTextTag *texttag,
                                                GObject *arg1,
                                                GdkEvent *event,
                                                GtkTextIter *arg2,
                                                gpointer user_data);

## Description

You may wish to begin by reading the text widget conceptual overview which gives an overview of all the objects and data types related to the text widget and how they work together.

Tags should be in the GtkTextTagTable for a given GtkTextBuffer before using them with that buffer.

`gtk_text_buffer_create_tag()` is the best way to create tags. See gtk-demo for numerous examples.

The "invisible" property was not implemented for GTK+ 2.0; it's planned to be implemented in future releases.

## Details

### GtkTextTag

    typedef struct _GtkTextTag GtkTextTag;

### enum GtkWrapMode

    typedef enum
    {
      GTK_WRAP_NONE,
      GTK_WRAP_CHAR,
      GTK_WRAP_WORD,
      GTK_WRAP_WORD_CHAR
    } GtkWrapMode;

Describes a type of line wrapping.

`GTK_WRAP_NONE` | do not wrap lines; just make the text area wider
`GTK_WRAP_CHAR` | wrap text, breaking lines anywhere the cursor can appear (between characters, usually - if you want to be technical, between graphemes, see `pango_get_log_attrs()`)
`GTK_WRAP_WORD` | wrap text, breaking lines in between words
`GTK_WRAP_WORD_CHAR` | wrap text, breaking lines in between words, or if that is not enough, also between graphemes.

### GtkTextAttributes

    typedef struct {
      GtkTextAppearance appearance;

      GtkJustification justification;
      GtkTextDirection direction;

      /* Individual chunks of this can be set/unset as a group */
      PangoFontDescription *font;

      gdouble font_scale;

      gint left_margin;

      gint indent;

      gint right_margin;

      gint pixels_above_lines;

      gint pixels_below_lines;

      gint pixels_inside_wrap;

      PangoTabArray *tabs;

      GtkWrapMode wrap_mode;        /* How to handle wrap-around for this tag.
                                     * Must be GTK_WRAPMODE_CHAR,
                                     * GTK_WRAPMODE_NONE, GTK_WRAPMODE_WORD
                                     */

      PangoLanguage *language;

      /* hide the text  */
      guint invisible : 1;

      /* Background is fit to full line height rather than
       * baseline +/- ascent/descent (font height)
       */
      guint bg_full_height : 1;

      /* can edit this text */
      guint editable : 1;

      /* colors are allocated etc. */
      guint realized : 1;
    } GtkTextAttributes;

Using GtkTextAttributes directly should rarely be necessary. It's primarily useful with `gtk_text_iter_get_attributes()`. As with most GTK+ structs, the fields in this struct should only be read, never modified directly.

GtkTextAppearance `appearance`; | pointer to sub-struct containing certain attributes
GtkJustification `justification`; |
GtkTextDirection `direction`; |
PangoFontDescription *`font`; |
gdouble `font_scale`; |
gint `left_margin`; |
gint `indent`; |
gint `right_margin`; |
gint `pixels_above_lines`; |
gint `pixels_below_lines`; |
gint `pixels_inside_wrap`; |
PangoTabArray *`tabs`; |
GtkWrapMode `wrap_mode`; |
PangoLanguage *`language`; |
guint `invisible` : 1; |
guint `bg_full_height` : 1; |
guint `editable` : 1; |
guint `realized` : 1; |

### gtk_text_tag_new ()

    GtkTextTag* gtk_text_tag_new                (const gchar *name);

Creates a GtkTextTag. Configure the tag using object arguments, i.e. using `g_object_set()`.

`name` : | tag name, or `NULL`
Returns : | a new GtkTextTag

### gtk_text_tag_get_priority ()

    gint        gtk_text_tag_get_priority       (GtkTextTag *tag);

Get the tag priority.

`tag` : | a GtkTextTag
Returns : | The tag's priority.

### gtk_text_tag_set_priority ()

    void        gtk_text_tag_set_priority       (GtkTextTag *tag,
                                                 gint priority);

Sets the priority of a GtkTextTag. Valid priorities are start at 0 and go to one less than `gtk_text_tag_table_get_size()`. Each tag in a table has a unique priority; setting the priority of one tag shifts the priorities of all the other tags in the table to maintain a unique priority for each tag. Higher priority tags "win" if two tags both set the same text attribute. When adding a tag to a tag table, it will be assigned the highest priority in the table by default; so normally the precedence of a set of tags is the order in which they were added to the table, or created with `gtk_text_buffer_create_tag()`, which adds the tag to the buffer's table automatically.

`tag` : | a GtkTextTag
`priority` : | the new priority

### gtk_text_tag_event ()

    gboolean    gtk_text_tag_event              (GtkTextTag *tag,
                                                 GObject *event_object,
                                                 GdkEvent *event,
                                                 const GtkTextIter *iter);

Emits the "event" signal on the GtkTextTag.

`tag` : | a GtkTextTag
`event_object` : | object that received the event, such as a widget
`event` : | the event
`iter` : | location where the event was received
Returns : | result of signal emission (whether the event was handled)

### GtkTextAppearance

    typedef struct {
      GdkColor bg_color;
      GdkColor fg_color;
      GdkBitmap *bg_stipple;
      GdkBitmap *fg_stipple;

      /* super/subscript rise, can be negative */
      gint rise;

      guint underline : 4;          /* PangoUnderline */
      guint strikethrough : 1;

      /* Whether to use background-related values; this is irrelevant for
       * the values struct when in a tag, but is used for the composite
       * values struct; it's true if any of the tags being composited
       * had background stuff set.
       */
      guint draw_bg : 1;

      /* These are only used when we are actually laying out and rendering
       * a paragraph; not when a GtkTextAppearance is part of a
       * GtkTextAttributes.
       */
      guint inside_selection : 1;
      guint is_text : 1;
    } GtkTextAppearance;

### gtk_text_attributes_new ()

    GtkTextAttributes* gtk_text_attributes_new  (void);

Creates a GtkTextAttributes, which describes a set of properties on some text.

Returns : | a new GtkTextAttributes

### gtk_text_attributes_copy ()

    GtkTextAttributes* gtk_text_attributes_copy (GtkTextAttributes *src);

Copies `src` and returns a new GtkTextAttributes.

`src` : | a GtkTextAttributes to be copied
Returns : | a copy of `src`

### gtk_text_attributes_copy_values ()

    void        gtk_text_attributes_copy_values (GtkTextAttributes *src,
                                                 GtkTextAttributes *dest);

Copies the values from `src` to `dest` so that `dest` has the same values as `src`. Frees existing values in `dest`.

`src` : | a GtkTextAttributes
`dest` : | another GtkTextAttributes

### gtk_text_attributes_unref ()

    void        gtk_text_attributes_unref       (GtkTextAttributes *values);

Decrements the reference count on `values`, freeing the structure if the reference count reaches 0.

`values` : | a GtkTextAttributes

### gtk_text_attributes_ref ()

    void        gtk_text_attributes_ref         (GtkTextAttributes *values);

Increments the reference count on `values`.

`values` : | a GtkTextAttributes

## Properties

### The "`background`" property

      "background"           gchararray            : Write

Background color as a string.

### The "`background-full-height`" property

      "background-full-height" gboolean              : Read / Write

Whether the background color fills the entire line height or only the height of the tagged characters.

### The "`background-full-height-set`" property

      "background-full-height-set" gboolean              : Read / Write

Whether this tag affects background height.

### The "`background-gdk`" property

      "background-gdk"       GdkColor              : Read / Write

Background color as a (possibly unallocated) GdkColor.

### The "`background-set`" property

      "background-set"       gboolean              : Read / Write

Whether this tag affects the background color.

### The "`background-stipple`" property

      "background-stipple"   GdkPixmap             : Read / Write

Bitmap to use as a mask when drawing the text background.

### The "`background-stipple-set`" property

      "background-stipple-set" gboolean              : Read / Write

Whether this tag affects the background stipple.

### The "`direction`" property

      "direction"            GtkTextDirection      : Read / Write

Text direction, e.g. right-to-left or left-to-right.

### The "`editable`" property

      "editable"             gboolean              : Read / Write

Whether the text can be modified by the user.

### The "`editable-set`" property

      "editable-set"         gboolean              : Read / Write

Whether this tag affects text editability.

### The "`family`" property

      "family"               gchararray            : Read / Write

Name of the font family, e.g. Sans, Helvetica, Times, Monospace.

### The "`family-set`" property

      "family-set"           gboolean              : Read / Write

Whether this tag affects the font family.

### The "`font`" property

      "font"                 gchararray            : Read / Write

Font description as a string, e.g. "Sans Italic 12".

### The "`font-desc`" property

      "font-desc"            PangoFontDescription  : Read / Write

Font description as a PangoFontDescription struct.

### The "`foreground`" property

      "foreground"           gchararray            : Write

Foreground color as a string.

### The "`foreground-gdk`" property

      "foreground-gdk"       GdkColor              : Read / Write

Foreground color as a (possibly unallocated) GdkColor.

### The "`foreground-set`" property

      "foreground-set"       gboolean              : Read / Write

Whether this tag affects the foreground color.

### The "`foreground-stipple`" property

      "foreground-stipple"   GdkPixmap             : Read / Write

Bitmap to use as a mask when drawing the text foreground.

### The "`foreground-stipple-set`" property

      "foreground-stipple-set" gboolean              : Read / Write

Whether this tag affects the foreground stipple.

### The "`indent`" property

      "indent"               gint                  : Read / Write

Amount to indent the paragraph, in pixels.

### The "`indent-set`" property

      "indent-set"           gboolean              : Read / Write

Whether this tag affects indentation.

### The "`invisible`" property

      "invisible"            gboolean              : Read / Write

Whether this text is hidden. Not implemented in GTK 2.0.

### The "`invisible-set`" property

      "invisible-set"        gboolean              : Read / Write

Whether this tag affects text visibility.

### The "`justification`" property

      "justification"        GtkJustification      : Read / Write

Left, right, or center justification.

### The "`justification-set`" property

      "justification-set"    gboolean              : Read / Write

Whether this tag affects paragraph justification.

### The "`language`" property

      "language"             gchararray            : Read / Write

The language this text is in, as an ISO code. Pango can use this as a hint when rendering the text. If not set, an appropriate default will be used.

### The "`language-set`" property

      "language-set"         gboolean              : Read / Write

Whether this tag affects the language the text is rendered as.

### The "`left-margin`" property

      "left-margin"          gint                  : Read / Write

Width of the left margin in pixels.

### The "`left-margin-set`" property

      "left-margin-set"      gboolean              : Read / Write

Whether this tag affects the left margin.

### The "`name`" property

      "name"                 gchararray            : Read / Write / Construct Only

Name used to refer to the text tag. NULL for anonymous tags.

### The "`pixels-above-lines`" property

      "pixels-above-lines"   gint                  : Read / Write

Pixels of blank space above paragraphs.

### The "`pixels-above-lines-set`" property

      "pixels-above-lines-set" gboolean              : Read / Write

Whether this tag affects the number of pixels above lines.

### The "`pixels-below-lines`" property

      "pixels-below-lines"   gint                  : Read / Write

Pixels of blank space below paragraphs.

### The "`pixels-below-lines-set`" property

      "pixels-below-lines-set" gboolean              : Read / Write

Whether this tag affects the number of pixels above lines.

### The "`pixels-inside-wrap`" property

      "pixels-inside-wrap"   gint                  : Read / Write

Pixels of blank space between wrapped lines in a paragraph.

### The "`pixels-inside-wrap-set`" property

      "pixels-inside-wrap-set" gboolean              : Read / Write

Whether this tag affects the number of pixels between wrapped lines.

### The "`right-margin`" property

      "right-margin"         gint                  : Read / Write

Width of the right margin in pixels.

### The "`right-margin-set`" property

      "right-margin-set"     gboolean              : Read / Write

Whether this tag affects the right margin.

### The "`rise`" property

      "rise"                 gint                  : Read / Write

Offset of text above the baseline (below the baseline if rise is negative) in pixels.

### The "`rise-set`" property

      "rise-set"             gboolean              : Read / Write

Whether this tag affects the rise.

### The "`scale`" property

      "scale"                gdouble               : Read / Write

Font size as a scale factor relative to the default font size. This properly adapts to theme changes etc. so is recommended. Pango predefines some scales such as PANGO_SCALE_X_LARGE.

### The "`scale-set`" property

      "scale-set"            gboolean              : Read / Write

Whether this tag scales the font size by a factor.

### The "`size`" property

      "size"                 gint                  : Read / Write

Font size in Pango units.

### The "`size-points`" property

      "size-points"          gdouble               : Read / Write

Font size in points.

### The "`size-set`" property

      "size-set"             gboolean              : Read / Write

Whether this tag affects the font size.

### The "`stretch`" property

      "stretch"              PangoStretch          : Read / Write

Font stretch as a PangoStretch, e.g. PANGO_STRETCH_CONDENSED.

### The "`stretch-set`" property

      "stretch-set"          gboolean              : Read / Write

Whether this tag affects the font stretch.

### The "`strikethrough`" property

      "strikethrough"        gboolean              : Read / Write

Whether to strike through the text.

### The "`strikethrough-set`" property

      "strikethrough-set"    gboolean              : Read / Write

Whether this tag affects strikethrough.

### The "`style`" property

      "style"                PangoStyle            : Read / Write

Font style as a PangoStyle, e.g. PANGO_STYLE_ITALIC.

### The "`style-set`" property

      "style-set"            gboolean              : Read / Write

Whether this tag affects the font style.

### The "`tabs`" property

      "tabs"                 PangoTabArray         : Read / Write

Custom tabs for this text.

### The "`tabs-set`" property

      "tabs-set"             gboolean              : Read / Write

Whether this tag affects tabs.

### The "`underline`" property

      "underline"            PangoUnderline        : Read / Write

Style of underline for this text.

### The "`underline-set`" property

      "underline-set"        gboolean              : Read / Write

Whether this tag affects underlining.

### The "`variant`" property

      "variant"              PangoVariant          : Read / Write

Font variant as a PangoVariant, e.g. PANGO_VARIANT_SMALL_CAPS.

### The "`variant-set`" property

      "variant-set"          gboolean              : Read / Write

Whether this tag affects the font variant.

### The "`weight`" property

      "weight"               gint                  : Read / Write

Font weight as an integer, see predefined values in PangoWeight; for example, PANGO_WEIGHT_BOLD.

### The "`weight-set`" property

      "weight-set"           gboolean              : Read / Write

Whether this tag affects the font weight.

### The "`wrap-mode`" property

      "wrap-mode"            GtkWrapMode           : Read / Write

Whether to wrap lines never, at word boundaries, or at character boundaries.

### The "`wrap-mode-set`" property

      "wrap-mode-set"        gboolean              : Read / Write

Whether this tag affects line wrap mode.

## Signals

### The "event" signal

    gboolean    user_function                  (GtkTextTag *texttag,
                                                GObject *arg1,
                                                GdkEvent *event,
                                                GtkTextIter *arg2,
                                                gpointer user_data);

`texttag` : | the object which received the signal.
`arg1` : |
`event` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.
Returns : |