GtkTextTag

Name

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

Synopsis


#include <gtk/gtk.h>


struct      GtkTextTag;
enum        GtkWrapMode;
struct      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);
struct      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

struct GtkTextTag

struct GtkTextTag;


enum GtkWrapMode

typedef enum
{
  GTK_WRAP_NONE,
  GTK_WRAP_CHAR,
  GTK_WRAP_WORD
} 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


struct GtkTextAttributes

struct GtkTextAttributes
{
  guint refcount;

  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;

  /* I'm not sure this can really be used without breaking some things
   * an app might do :-/
   */
  gpointer padding1;
  
  /* 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;

  guint pad1 : 1;
  guint pad2 : 1;
  guint pad3 : 1;
  guint pad4 : 1;
};

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.

guint refcount

private field, ignore

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

gpointer padding1

guint invisible : 1

guint bg_full_height : 1

guint editable : 1

guint realized : 1

guint pad1 : 1

guint pad2 : 1

guint pad3 : 1

guint pad4 : 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)


struct GtkTextAppearance

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

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

  /* I'm not sure this can really be used without breaking some things
   * an app might do :-/
   */
  gpointer padding1;
  
  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;

  guint pad1 : 1;
  guint pad2 : 1;
  guint pad3 : 1;
  guint pad4 : 1;
};


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

"background" (gchararray : Write)

Background color as a string.

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

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

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

Whether this tag affects background height.

"background-gdk" (GdkColor : Read / Write)

Background color as a GdkColor.

"background-set" (gboolean : Read / Write)

Whether this tag affects the background color.

"background-stipple" (GdkPixmap : Read / Write)

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

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

Whether this tag affects the background stipple.

"direction" (GtkTextDirection : Read / Write)

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

"editable" (gboolean : Read / Write)

Whether the text can be modified by the user.

"editable-set" (gboolean : Read / Write)

Whether this tag affects text editability.

"family" (gchararray : Read / Write)

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

"family-set" (gboolean : Read / Write)

Whether this tag affects the font family.

"font" (gchararray : Read / Write)

Font description as a string.

"font-desc" (PangoFontDescription : Read / Write)

Font description as a PangoFontDescription struct.

"foreground" (gchararray : Write)

Foreground color as a string.

"foreground-gdk" (GdkColor : Read / Write)

Foreground color as a GdkColor.

"foreground-set" (gboolean : Read / Write)

Whether this tag affects the foreground color.

"foreground-stipple" (GdkPixmap : Read / Write)

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

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

Whether this tag affects the foreground stipple.

"indent" (gint : Read / Write)

Amount to indent the paragraph, in pixels.

"indent-set" (gboolean : Read / Write)

Whether this tag affects indentation.

"invisible" (gboolean : Read / Write)

Whether this text is hidden.

"invisible-set" (gboolean : Read / Write)

Whether this tag affects text visibility.

"justification" (GtkJustification : Read / Write)

Left, right, or center justification.

"justification-set" (gboolean : Read / Write)

Whether this tag affects paragraph justification.

"language" (gchararray : Read / Write)

Language engine code to use for rendering the text.

"language-set" (gboolean : Read / Write)

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

"left-margin" (gint : Read / Write)

Width of the left margin in pixels.

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

Whether this tag affects the left margin.

"name" (gchararray : Read / Write / Construct Only)

Name used to refer to the text tag.

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

Pixels of blank space above paragraphs.

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

Whether this tag affects the number of pixels above lines.

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

Pixels of blank space below paragraphs.

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

Whether this tag affects the number of pixels above lines.

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

Pixels of blank space between wrapped lines in a paragraph.

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

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

"right-margin" (gint : Read / Write)

Width of the right margin in pixels.

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

Whether this tag affects the right margin.

"rise" (gint : Read / Write)

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

"rise-set" (gboolean : Read / Write)

Whether this tag affects the rise.

"scale" (gdouble : Read / Write)

Font scale.

"scale-set" (gboolean : Read / Write)

Whether this tag scales the font size by a factor.

"size" (gint : Read / Write)

Font size.

"size-points" (gdouble : Read / Write)

Font size in points.

"size-set" (gboolean : Read / Write)

Whether this tag affects the font size.

"stretch" (PangoStretch : Read / Write)

Font stretch.

"stretch-set" (gboolean : Read / Write)

Whether this tag affects the font stretch.

"strikethrough" (gboolean : Read / Write)

Whether to strike through the text.

"strikethrough-set" (gboolean : Read / Write)

Whether this tag affects strikethrough.

"style" (PangoStyle : Read / Write)

Font style.

"style-set" (gboolean : Read / Write)

Whether this tag affects the font style.

"tabs" (PangoTabArray : Read / Write)

Custom tabs for this text.

"tabs-set" (gboolean : Read / Write)

Whether this tag affects tabs.

"underline" (PangoUnderline : Read / Write)

Style of underline for this text.

"underline-set" (gboolean : Read / Write)

Whether this tag affects underlining.

"variant" (PangoVariant : Read / Write)

Font variant.

"variant-set" (gboolean : Read / Write)

Whether this tag affects the font variant.

"weight" (gint : Read / Write)

Font weight.

"weight-set" (gboolean : Read / Write)

Whether this tag affects the font weight.

"wrap-mode" (GtkWrapMode : Read / Write)

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

"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 :