GtkTextTag

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

Properties

gboolean accumulative-margin Read / Write
gchar * background Write
gboolean background-full-height Read / Write
gboolean background-full-height-set Read / Write
GdkColor * background-gdk Read / Write
GdkRGBA * background-rgba Read / Write
gboolean background-set Read / Write
GtkTextDirection direction Read / Write
gboolean editable Read / Write
gboolean editable-set Read / Write
gboolean fallback Read / Write
gboolean fallback-set Read / Write
gchar * family Read / Write
gboolean family-set Read / Write
gchar * font Read / Write
PangoFontDescription * font-desc Read / Write
gchar * font-features Read / Write
gboolean font-features-set Read / Write
gchar * foreground Write
GdkColor * foreground-gdk Read / Write
GdkRGBA * foreground-rgba Read / Write
gboolean foreground-set Read / Write
gint indent Read / Write
gboolean indent-set Read / Write
gboolean invisible Read / Write
gboolean invisible-set Read / Write
GtkJustification justification Read / Write
gboolean justification-set Read / Write
gchar * language Read / Write
gboolean language-set Read / Write
gint left-margin Read / Write
gboolean left-margin-set Read / Write
gint letter-spacing Read / Write
gboolean letter-spacing-set Read / Write
gchar * name Read / Write / Construct Only
gchar * paragraph-background Write
GdkColor * paragraph-background-gdk Read / Write
GdkRGBA * paragraph-background-rgba Read / Write
gboolean paragraph-background-set Read / Write
gint pixels-above-lines Read / Write
gboolean pixels-above-lines-set Read / Write
gint pixels-below-lines Read / Write
gboolean pixels-below-lines-set Read / Write
gint pixels-inside-wrap Read / Write
gboolean pixels-inside-wrap-set Read / Write
gint right-margin Read / Write
gboolean right-margin-set Read / Write
gint rise Read / Write
gboolean rise-set Read / Write
gdouble scale Read / Write
gboolean scale-set Read / Write
gint size Read / Write
gdouble size-points Read / Write
gboolean size-set Read / Write
PangoStretch stretch Read / Write
gboolean stretch-set Read / Write
gboolean strikethrough Read / Write
GdkRGBA * strikethrough-rgba Read / Write
gboolean strikethrough-rgba-set Read / Write
gboolean strikethrough-set Read / Write
PangoStyle style Read / Write
gboolean style-set Read / Write
PangoTabArray * tabs Read / Write
gboolean tabs-set Read / Write
PangoUnderline underline Read / Write
GdkRGBA * underline-rgba Read / Write
gboolean underline-rgba-set Read / Write
gboolean underline-set Read / Write
PangoVariant variant Read / Write
gboolean variant-set Read / Write
gint weight Read / Write
gboolean weight-set Read / Write
GtkWrapMode wrap-mode Read / Write
gboolean wrap-mode-set Read / Write

Types and Values

Object Hierarchy

    GObject
    ╰── GtkTextTag

Includes

#include <gtk/gtk.h>

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 “gtk3-demo” for numerous examples.

For each property of GtkTextTag, there is a “set” property, e.g. “font-set” corresponds to “font”. These “set” properties reflect whether a property has been set or not. They are maintained by GTK+ and you should not set them independently.

Functions

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

Parameters

name

tag name, or NULL.

[allow-none]

Returns

a new GtkTextTag


gtk_text_tag_get_priority ()

gint
gtk_text_tag_get_priority (GtkTextTag *tag);

Get the tag priority.

Parameters

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

Parameters

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.

Parameters

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)


gtk_text_tag_changed ()

void
gtk_text_tag_changed (GtkTextTag *tag,
                      gboolean size_changed);

Emits the “tag-changed” signal on the GtkTextTagTable where the tag is included.

The signal is already emitted when setting a GtkTextTag property. This function is useful for a GtkTextTag subclass.

Parameters

tag

a GtkTextTag.

 

size_changed

whether the change affects the GtkTextView layout.

 

Since: 3.20


gtk_text_attributes_new ()

GtkTextAttributes *
gtk_text_attributes_new (void);

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


gtk_text_attributes_copy ()

GtkTextAttributes *
gtk_text_attributes_copy (GtkTextAttributes *src);

Copies src and returns a new GtkTextAttributes.

Parameters

src

a GtkTextAttributes to be copied

 

Returns

a copy of src , free with gtk_text_attributes_unref()


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 .

Parameters

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.

Parameters

values

a GtkTextAttributes

 

gtk_text_attributes_ref ()

GtkTextAttributes *
gtk_text_attributes_ref (GtkTextAttributes *values);

Increments the reference count on values .

Parameters

values

a GtkTextAttributes

 

Returns

the GtkTextAttributes that were passed in

Types and Values

struct GtkTextTag

struct GtkTextTag;

struct GtkTextAttributes

struct GtkTextAttributes {
  GtkTextAppearance appearance;

  GtkJustification justification;
  GtkTextDirection direction;

  PangoFontDescription *font;

  gdouble font_scale;

  gint left_margin;
  gint right_margin;
  gint indent;

  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 no_fallback: 1;

  gint letter_spacing;

#ifdef __GI_SCANNER__
  /* The scanner should only see the transparent union, so that its
   * content does not vary across architectures.
   */
  union {
    gchar *font_features;
};

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.

Members

GtkTextAppearance appearance;

GtkTextAppearance for text.

 

GtkJustification justification;

GtkJustification for text.

 

GtkTextDirection direction;

GtkTextDirection for text.

 

PangoFontDescription *font;

PangoFontDescription for text.

 

gdouble font_scale;

Font scale factor.

 

gint left_margin;

Width of the left margin in pixels.

 

gint right_margin;

Width of the right margin in pixels.

 

gint indent;

Amount to indent the paragraph, in pixels.

 

gint pixels_above_lines;

Pixels of blank space above paragraphs.

 

gint pixels_below_lines;

Pixels of blank space below paragraphs.

 

gint pixels_inside_wrap;

Pixels of blank space between wrapped lines in a paragraph.

 

PangoTabArray *tabs;

Custom PangoTabArray for this text.

 

GtkWrapMode wrap_mode;

GtkWrapMode for text.

 

PangoLanguage *language;

PangoLanguage for text.

 

guint invisible : 1;

Hide the text.

 

guint bg_full_height : 1;

Background is fit to full line height rather than baseline +/- ascent/descent (font height).

 

guint editable : 1;

Can edit this text.

 

guint no_fallback : 1;

Whether to disable font fallback.

 

gint letter_spacing;

Extra space to insert between graphemes, in Pango units

 

gchar *font_features;

   

struct GtkTextAppearance

struct GtkTextAppearance {
  GdkColor bg_color; /* pixel is taken for underline color */
  GdkColor fg_color; /* pixel is taken for strikethrough color */

  /* 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;

  /* For the sad story of this bit of code, see
   * https://bugzilla.gnome.org/show_bug.cgi?id=711158
   */
#ifdef __GI_SCANNER__
  /* The scanner should only see the transparent union, so that its
   * content does not vary across architectures.
   */
  union {
    GdkRGBA *rgba[2];
};

Members

GdkColor bg_color;

Background GdkColor.

 

GdkColor fg_color;

Foreground GdkColor.

 

gint rise;

Super/subscript rise, can be negative.

 

guint underline : 4;

PangoUnderline

 

guint strikethrough : 1;

Strikethrough style

 

guint draw_bg : 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 inside_selection : 1;

This are only used when we are actually laying out and rendering a paragraph; not when a GtkTextAppearance is part of a GtkTextAttributes.

 

guint is_text : 1;

This are only used when we are actually laying out and rendering a paragraph; not when a GtkTextAppearance is part of a GtkTextAttributes.

 

GdkRGBA *rgba[2];

GdkRGBA

 

Property Details

The “accumulative-margin” property

  “accumulative-margin”      gboolean

Whether the margins accumulate or override each other.

When set to TRUE the margins of this tag are added to the margins of any other non-accumulative margins present. When set to FALSE the margins override one another (the default).

Flags: Read / Write

Default value: FALSE

Since: 2.12


The “background” property

  “background”               gchar *

Background color as a string.

Flags: Write

Default value: NULL


The “background-full-height” property

  “background-full-height”   gboolean

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

Flags: Read / Write

Default value: FALSE


The “background-full-height-set” property

  “background-full-height-set” gboolean

Whether this tag affects background height.

Flags: Read / Write

Default value: FALSE


The “background-gdk” property

  “background-gdk”           GdkColor *

Background color as a GdkColor.

GtkTextTag:background-gdk has been deprecated since version 3.4 and should not be used in newly-written code.

Use “background-rgba” instead.

Flags: Read / Write


The “background-rgba” property

  “background-rgba”          GdkRGBA *

Background color as a GdkRGBA.

Flags: Read / Write

Since: 3.2


The “background-set” property

  “background-set”           gboolean

Whether this tag affects the background color.

Flags: Read / Write

Default value: FALSE


The “direction” property

  “direction”                GtkTextDirection

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

Flags: Read / Write

Default value: GTK_TEXT_DIR_NONE


The “editable” property

  “editable”                 gboolean

Whether the text can be modified by the user.

Flags: Read / Write

Default value: TRUE


The “editable-set” property

  “editable-set”             gboolean

Whether this tag affects text editability.

Flags: Read / Write

Default value: FALSE


The “fallback” property

  “fallback”                 gboolean

Whether font fallback is enabled.

When set to TRUE, other fonts will be substituted where the current font is missing glyphs.

Flags: Read / Write

Default value: TRUE

Since: 3.16


The “fallback-set” property

  “fallback-set”             gboolean

Whether this tag affects font fallback.

Flags: Read / Write

Default value: FALSE


The “family” property

  “family”                   gchar *

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

Flags: Read / Write

Default value: NULL


The “family-set” property

  “family-set”               gboolean

Whether this tag affects the font family.

Flags: Read / Write

Default value: FALSE


The “font” property

  “font”                     gchar *

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

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

Flags: Read / Write

Default value: NULL


The “font-desc” property

  “font-desc”                PangoFontDescription *

Font description as a PangoFontDescription struct.

Flags: Read / Write


The “font-features” property

  “font-features”            gchar *

OpenType font features, as a string.

Flags: Read / Write

Default value: NULL

Since: 3.18


The “font-features-set” property

  “font-features-set”        gboolean

Whether this tag affects font features.

Flags: Read / Write

Default value: FALSE


The “foreground” property

  “foreground”               gchar *

Foreground color as a string.

Flags: Write

Default value: NULL


The “foreground-gdk” property

  “foreground-gdk”           GdkColor *

Foreground color as a GdkColor.

GtkTextTag:foreground-gdk has been deprecated since version 3.4 and should not be used in newly-written code.

Use “foreground-rgba” instead.

Flags: Read / Write


The “foreground-rgba” property

  “foreground-rgba”          GdkRGBA *

Foreground color as a GdkRGBA.

Flags: Read / Write

Since: 3.2


The “foreground-set” property

  “foreground-set”           gboolean

Whether this tag affects the foreground color.

Flags: Read / Write

Default value: FALSE


The “indent” property

  “indent”                   gint

Amount to indent the paragraph, in pixels.

Flags: Read / Write

Default value: 0


The “indent-set” property

  “indent-set”               gboolean

Whether this tag affects indentation.

Flags: Read / Write

Default value: FALSE


The “invisible” property

  “invisible”                gboolean

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.

Flags: Read / Write

Default value: FALSE

Since: 2.8


The “invisible-set” property

  “invisible-set”            gboolean

Whether this tag affects text visibility.

Flags: Read / Write

Default value: FALSE


The “justification” property

  “justification”            GtkJustification

Left, right, or center justification.

Flags: Read / Write

Default value: GTK_JUSTIFY_LEFT


The “justification-set” property

  “justification-set”        gboolean

Whether this tag affects paragraph justification.

Flags: Read / Write

Default value: FALSE


The “language” property

  “language”                 gchar *

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

Flags: Read / Write

Default value: NULL


The “language-set” property

  “language-set”             gboolean

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

Flags: Read / Write

Default value: FALSE


The “left-margin” property

  “left-margin”              gint

Width of the left margin in pixels.

Flags: Read / Write

Allowed values: >= 0

Default value: 0


The “left-margin-set” property

  “left-margin-set”          gboolean

Whether this tag affects the left margin.

Flags: Read / Write

Default value: FALSE


The “letter-spacing” property

  “letter-spacing”           gint

Extra spacing between graphemes, in Pango units.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 3.16


The “letter-spacing-set” property

  “letter-spacing-set”       gboolean

Whether this tag affects letter spacing.

Flags: Read / Write

Default value: FALSE


The “name” property

  “name”                     gchar *

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

Flags: Read / Write / Construct Only

Default value: NULL


The “paragraph-background” property

  “paragraph-background”     gchar *

The paragraph background color as a string.

Flags: Write

Default value: NULL

Since: 2.8


The “paragraph-background-gdk” property

  “paragraph-background-gdk” GdkColor *

The paragraph background color as a GdkColor.

GtkTextTag:paragraph-background-gdk has been deprecated since version 3.4 and should not be used in newly-written code.

Use “paragraph-background-rgba” instead.

Flags: Read / Write

Since: 2.8


The “paragraph-background-rgba” property

  “paragraph-background-rgba” GdkRGBA *

The paragraph background color as a GdkRGBA.

Flags: Read / Write

Since: 3.2


The “paragraph-background-set” property

  “paragraph-background-set” gboolean

Whether this tag affects the paragraph background color.

Flags: Read / Write

Default value: FALSE


The “pixels-above-lines” property

  “pixels-above-lines”       gint

Pixels of blank space above paragraphs.

Flags: Read / Write

Allowed values: >= 0

Default value: 0


The “pixels-above-lines-set” property

  “pixels-above-lines-set”   gboolean

Whether this tag affects the number of pixels above lines.

Flags: Read / Write

Default value: FALSE


The “pixels-below-lines” property

  “pixels-below-lines”       gint

Pixels of blank space below paragraphs.

Flags: Read / Write

Allowed values: >= 0

Default value: 0


The “pixels-below-lines-set” property

  “pixels-below-lines-set”   gboolean

Whether this tag affects the number of pixels above lines.

Flags: Read / Write

Default value: FALSE


The “pixels-inside-wrap” property

  “pixels-inside-wrap”       gint

Pixels of blank space between wrapped lines in a paragraph.

Flags: Read / Write

Allowed values: >= 0

Default value: 0


The “pixels-inside-wrap-set” property

  “pixels-inside-wrap-set”   gboolean

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

Flags: Read / Write

Default value: FALSE


The “right-margin” property

  “right-margin”             gint

Width of the right margin in pixels.

Flags: Read / Write

Allowed values: >= 0

Default value: 0


The “right-margin-set” property

  “right-margin-set”         gboolean

Whether this tag affects the right margin.

Flags: Read / Write

Default value: FALSE


The “rise” property

  “rise”                     gint

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

Flags: Read / Write

Default value: 0


The “rise-set” property

  “rise-set”                 gboolean

Whether this tag affects the rise.

Flags: Read / Write

Default value: FALSE


The “scale” property

  “scale”                    gdouble

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.

Flags: Read / Write

Allowed values: >= 0

Default value: 1


The “scale-set” property

  “scale-set”                gboolean

Whether this tag scales the font size by a factor.

Flags: Read / Write

Default value: FALSE


The “size” property

  “size”                     gint

Font size in Pango units.

Flags: Read / Write

Allowed values: >= 0

Default value: 0


The “size-points” property

  “size-points”              gdouble

Font size in points.

Flags: Read / Write

Allowed values: >= 0

Default value: 0


The “size-set” property

  “size-set”                 gboolean

Whether this tag affects the font size.

Flags: Read / Write

Default value: FALSE


The “stretch” property

  “stretch”                  PangoStretch

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

Flags: Read / Write

Default value: PANGO_STRETCH_NORMAL


The “stretch-set” property

  “stretch-set”              gboolean

Whether this tag affects the font stretch.

Flags: Read / Write

Default value: FALSE


The “strikethrough” property

  “strikethrough”            gboolean

Whether to strike through the text.

Flags: Read / Write

Default value: FALSE


The “strikethrough-rgba” property

  “strikethrough-rgba”       GdkRGBA *

This property modifies the color of strikeouts. If not set, strikeouts will use the forground color.

Flags: Read / Write

Since: 3.16


The “strikethrough-rgba-set” property

  “strikethrough-rgba-set”   gboolean

If the “strikethrough-rgba” property has been set.

Flags: Read / Write

Default value: FALSE

Since: 3.16


The “strikethrough-set” property

  “strikethrough-set”        gboolean

Whether this tag affects strikethrough.

Flags: Read / Write

Default value: FALSE


The “style” property

  “style”                    PangoStyle

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

Flags: Read / Write

Default value: PANGO_STYLE_NORMAL


The “style-set” property

  “style-set”                gboolean

Whether this tag affects the font style.

Flags: Read / Write

Default value: FALSE


The “tabs” property

  “tabs”                     PangoTabArray *

Custom tabs for this text.

Flags: Read / Write


The “tabs-set” property

  “tabs-set”                 gboolean

Whether this tag affects tabs.

Flags: Read / Write

Default value: FALSE


The “underline” property

  “underline”                PangoUnderline

Style of underline for this text.

Flags: Read / Write

Default value: PANGO_UNDERLINE_NONE


The “underline-rgba” property

  “underline-rgba”           GdkRGBA *

This property modifies the color of underlines. If not set, underlines will use the forground color.

If “underline” is set to PANGO_UNDERLINE_ERROR, an alternate color may be applied instead of the foreground. Setting this property will always override those defaults.

Flags: Read / Write

Since: 3.16


The “underline-rgba-set” property

  “underline-rgba-set”       gboolean

If the “underline-rgba” property has been set.

Flags: Read / Write

Default value: FALSE

Since: 3.16


The “underline-set” property

  “underline-set”            gboolean

Whether this tag affects underlining.

Flags: Read / Write

Default value: FALSE


The “variant” property

  “variant”                  PangoVariant

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

Flags: Read / Write

Default value: PANGO_VARIANT_NORMAL


The “variant-set” property

  “variant-set”              gboolean

Whether this tag affects the font variant.

Flags: Read / Write

Default value: FALSE


The “weight” property

  “weight”                   gint

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

Flags: Read / Write

Allowed values: >= 0

Default value: 400


The “weight-set” property

  “weight-set”               gboolean

Whether this tag affects the font weight.

Flags: Read / Write

Default value: FALSE


The “wrap-mode” property

  “wrap-mode”                GtkWrapMode

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

Flags: Read / Write

Default value: GTK_WRAP_NONE


The “wrap-mode-set” property

  “wrap-mode-set”            gboolean

Whether this tag affects line wrap mode.

Flags: Read / Write

Default value: FALSE

Signal Details

The “event” signal

gboolean
user_function (GtkTextTag  *tag,
               GObject     *object,
               GdkEvent    *event,
               GtkTextIter *iter,
               gpointer     user_data)

The ::event signal is emitted when an event occurs on a region of the buffer marked with this tag.

Parameters

tag

the GtkTextTag on which the signal is emitted

 

object

the object the event was fired from (typically a GtkTextView)

 

event

the event which triggered the signal

 

iter

a GtkTextIter pointing at the location the event occurred

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

Flags: Run Last