## 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);
    GtkTextAttributes*  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
      paragraph-background     gchararray            : Write
      paragraph-background-gdk GdkColor              : Read / Write
      paragraph-background-set gboolean              : Read / Write
      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

## Signals

      event                                          : Run Last

## 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 ()

    GtkTextAttributes*  gtk_text_attributes_ref             (GtkTextAttributes *values);

Increments the reference count on `values`.

`values` : | a GtkTextAttributes
Returns : | the GtkTextAttributes that were passed in

## Property Details

### The :`background` property

      background               gchararray            : Write

Background color as a string.

Default value: NULL

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

Default value: FALSE

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

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

Whether this tag affects background height.

Default value: FALSE

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

Default value: FALSE

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

Default value: FALSE

### The :`direction` property

      direction                GtkTextDirection      : Read / Write

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

Default value: GTK_TEXT_DIR_NONE

### The :`editable` property

      editable                 gboolean              : Read / Write

Whether the text can be modified by the user.

Default value: TRUE

### The :`editable-set` property

      editable-set             gboolean              : Read / Write

Whether this tag affects text editability.

Default value: FALSE

### The :`family` property

      family                   gchararray            : Read / Write

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

Default value: NULL

### The :`family-set` property

      family-set               gboolean              : Read / Write

Whether this tag affects the font family.

Default value: FALSE

### The :`font` property

      font                     gchararray            : Read / Write

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

Note that the initial value of this property depends on the internals of PangoFontDescription.

Default value: NULL

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

Default value: NULL

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

Default value: FALSE

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

Default value: FALSE

### The :`indent` property

      indent                   gint                  : Read / Write

Amount to indent the paragraph, in pixels.

Default value: 0

### The :`indent-set` property

      indent-set               gboolean              : Read / Write

Whether this tag affects indentation.

Default value: FALSE

### The :`invisible` property

      invisible                gboolean              : Read / Write

Whether this text is hidden.

Note that there may still be problems with the support for invisible text, in particular when navigating programmatically inside a buffer containing invisible segments.

Default value: FALSE

Since 2.8

### The :`invisible-set` property

      invisible-set            gboolean              : Read / Write

Whether this tag affects text visibility.

Default value: FALSE

### The :`justification` property

      justification            GtkJustification      : Read / Write

Left, right, or center justification.

Default value: GTK_JUSTIFY_LEFT

### The :`justification-set` property

      justification-set        gboolean              : Read / Write

Whether this tag affects paragraph justification.

Default value: FALSE

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

Note that the initial value of this property depends on the current locale, see also `gtk_get_default_language()`.

Default value: NULL

### The :`language-set` property

      language-set             gboolean              : Read / Write

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

Default value: FALSE

### The :`left-margin` property

      left-margin              gint                  : Read / Write

Width of the left margin in pixels.

Allowed values: >= 0

Default value: 0

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

      left-margin-set          gboolean              : Read / Write

Whether this tag affects the left margin.

Default value: FALSE

### The :`name` property

      name                     gchararray            : Read / Write / Construct Only

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

Default value: NULL

### The :`paragraph-background` property

      paragraph-background     gchararray            : Write

The paragraph background color as a string.

Default value: NULL

Since 2.8

### The :`paragraph-background-gdk` property

      paragraph-background-gdk GdkColor              : Read / Write

The paragraph background color as a as a (possibly unallocated) GdkColor.

Since 2.8

### The :`paragraph-background-set` property

      paragraph-background-set gboolean              : Read / Write

Whether this tag affects the paragraph background color.

Default value: FALSE

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

      pixels-above-lines       gint                  : Read / Write

Pixels of blank space above paragraphs.

Allowed values: >= 0

Default value: 0

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

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

Whether this tag affects the number of pixels above lines.

Default value: FALSE

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

      pixels-below-lines       gint                  : Read / Write

Pixels of blank space below paragraphs.

Allowed values: >= 0

Default value: 0

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

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

Whether this tag affects the number of pixels above lines.

Default value: FALSE

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

      pixels-inside-wrap       gint                  : Read / Write

Pixels of blank space between wrapped lines in a paragraph.

Allowed values: >= 0

Default value: 0

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

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

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

Default value: FALSE

### The :`right-margin` property

      right-margin             gint                  : Read / Write

Width of the right margin in pixels.

Allowed values: >= 0

Default value: 0

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

      right-margin-set         gboolean              : Read / Write

Whether this tag affects the right margin.

Default value: FALSE

### The :`rise` property

      rise                     gint                  : Read / Write

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

Default value: 0

### The :`rise-set` property

      rise-set                 gboolean              : Read / Write

Whether this tag affects the rise.

Default value: FALSE

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

Allowed values: >= 0

Default value: 1

### The :`scale-set` property

      scale-set                gboolean              : Read / Write

Whether this tag scales the font size by a factor.

Default value: FALSE

### The :`size` property

      size                     gint                  : Read / Write

Font size in Pango units.

Allowed values: >= 0

Default value: 0

### The :`size-points` property

      size-points              gdouble               : Read / Write

Font size in points.

Allowed values: >= 0

Default value: 0

### The :`size-set` property

      size-set                 gboolean              : Read / Write

Whether this tag affects the font size.

Default value: FALSE

### The :`stretch` property

      stretch                  PangoStretch          : Read / Write

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

Default value: PANGO_STRETCH_NORMAL

### The :`stretch-set` property

      stretch-set              gboolean              : Read / Write

Whether this tag affects the font stretch.

Default value: FALSE

### The :`strikethrough` property

      strikethrough            gboolean              : Read / Write

Whether to strike through the text.

Default value: FALSE

### The :`strikethrough-set` property

      strikethrough-set        gboolean              : Read / Write

Whether this tag affects strikethrough.

Default value: FALSE

### The :`style` property

      style                    PangoStyle            : Read / Write

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

Default value: PANGO_STYLE_NORMAL

### The :`style-set` property

      style-set                gboolean              : Read / Write

Whether this tag affects the font style.

Default value: FALSE

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

Default value: FALSE

### The :`underline` property

      underline                PangoUnderline        : Read / Write

Style of underline for this text.

Default value: PANGO_UNDERLINE_NONE

### The :`underline-set` property

      underline-set            gboolean              : Read / Write

Whether this tag affects underlining.

Default value: FALSE

### The :`variant` property

      variant                  PangoVariant          : Read / Write

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

Default value: PANGO_VARIANT_NORMAL

### The :`variant-set` property

      variant-set              gboolean              : Read / Write

Whether this tag affects the font variant.

Default value: FALSE

### The :`weight` property

      weight                   gint                  : Read / Write

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

Allowed values: >= 0

Default value: 400

### The :`weight-set` property

      weight-set               gboolean              : Read / Write

Whether this tag affects the font weight.

Default value: FALSE

### The :`wrap-mode` property

      wrap-mode                GtkWrapMode           : Read / Write

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

Default value: GTK_WRAP_NONE

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

      wrap-mode-set            gboolean              : Read / Write

Whether this tag affects line wrap mode.

Default value: FALSE

## Signal Details

### The `::event` signal

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

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