GtkSourceView 3 Reference Manual: GtkSourceGutterRenderer

## GtkSourceGutterRenderer GtkSourceGutterRenderer — Gutter cell renderer |

## Functions

void | gtk_source_gutter_renderer_begin ()
void | gtk_source_gutter_renderer_draw ()
void | gtk_source_gutter_renderer_end ()
gint | gtk_source_gutter_renderer_get_size ()
void | gtk_source_gutter_renderer_set_size ()
void | gtk_source_gutter_renderer_set_visible ()
gboolean | gtk_source_gutter_renderer_get_visible ()
void | gtk_source_gutter_renderer_get_padding ()
void | gtk_source_gutter_renderer_set_padding ()
void | gtk_source_gutter_renderer_get_alignment ()
void | gtk_source_gutter_renderer_set_alignment ()
void | gtk_source_gutter_renderer_set_alignment_mode ()
GtkTextWindowType | gtk_source_gutter_renderer_get_window_type ()
GtkTextView * | gtk_source_gutter_renderer_get_view ()
GtkSourceGutterRendererAlignmentMode | gtk_source_gutter_renderer_get_alignment_mode ()
gboolean | gtk_source_gutter_renderer_get_background ()
void | gtk_source_gutter_renderer_set_background ()
void | gtk_source_gutter_renderer_activate ()
gboolean | gtk_source_gutter_renderer_query_activatable ()
void | gtk_source_gutter_renderer_queue_draw ()
gboolean | gtk_source_gutter_renderer_query_tooltip ()
void | gtk_source_gutter_renderer_query_data ()

## Properties

GtkSourceGutterRendererAlignmentMode | alignment-mode | Read / Write / Construct
GdkRGBA * | background-rgba | Read / Write
gboolean | background-set | Read / Write / Construct
gint | size | Read / Write / Construct
GtkTextView * | view | Read
gboolean | visible | Read / Write / Construct
GtkTextWindowType | window-type | Read
gfloat | xalign | Read / Write / Construct
gint | xpad | Read / Write / Construct
gfloat | yalign | Read / Write / Construct
gint | ypad | Read / Write / Construct

## Signals

void | activate | Run Last
gboolean | query-activatable | Run Last
void | query-data | Run Last
gboolean | query-tooltip | Run Last
void | queue-draw | Run Last

## Types and Values

| GtkSourceGutterRenderer
enum | GtkSourceGutterRendererState
enum | GtkSourceGutterRendererAlignmentMode

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkSourceGutterRenderer
                ├── GtkSourceGutterRendererPixbuf
                ╰── GtkSourceGutterRendererText

## Includes

    #include <gtksourceview/gtksource.h>

## Description

A GtkSourceGutterRenderer represents a column in a GtkSourceGutter. The column contains one cell for each visible line of the GtkTextBuffer. Due to text wrapping, a cell can thus span multiple lines of the GtkTextView. In this case, GtkSourceGutterRendererAlignmentMode controls the alignment of the cell.

The gutter renderer must announce its “size”. The height is determined by the text view height. The width must be determined by the gutter renderer. The width generally takes into account the entire text buffer. For instance, to display the line numbers, if the buffer contains 100 lines, the gutter renderer will always set its width such as three digits can be printed, even if only the first 20 lines are shown. Another strategy is to take into account only the visible lines. In this case, only two digits are necessary to display the line numbers of the first 20 lines. To take another example, the gutter renderer for GtkSourceMarks doesn't need to take into account the text buffer to announce its width. It only depends on the icons size displayed in the gutter column.

An horizontal and vertical padding can be added with `gtk_source_gutter_renderer_set_padding()`. The total width of a gutter renderer is its size (“size”) plus two times the horizontal padding (“xpad”).

When the available size to render a cell is greater than the required size to render the cell contents, the cell contents can be aligned horizontally and vertically with `gtk_source_gutter_renderer_set_alignment()`.

The cells rendering occurs in three phases:

- begin: the `gtk_source_gutter_renderer_begin()` function is called when some cells need to be redrawn. It provides the associated region of the GtkTextBuffer. The cells need to be redrawn when the GtkTextView is scrolled, or when the state of the cells change (see GtkSourceGutterRendererState).

- draw: `gtk_source_gutter_renderer_draw()` is called for each cell that needs to be drawn.

- end: finally, `gtk_source_gutter_renderer_end()` is called.

## Functions

### gtk_source_gutter_renderer_begin ()

    void
    gtk_source_gutter_renderer_begin (GtkSourceGutterRenderer *renderer,
                                      cairo_t *cr,
                                      GdkRectangle *background_area,
                                      GdkRectangle *cell_area,
                                      GtkTextIter *start,
                                      GtkTextIter *end);

Called when drawing a region begins. The region to be drawn is indicated by `start` and `end` . The purpose is to allow the implementation to precompute some state before the draw method is called for each cell.

#### Parameters

renderer | a GtkSourceGutterRenderer |
cr | a cairo_t |
background_area | a GdkRectangle |
cell_area | a GdkRectangle |
start | a GtkTextIter |
end | a GtkTextIter |

### gtk_source_gutter_renderer_draw ()

    void
    gtk_source_gutter_renderer_draw (GtkSourceGutterRenderer *renderer,
                                     cairo_t *cr,
                                     GdkRectangle *background_area,
                                     GdkRectangle *cell_area,
                                     GtkTextIter *start,
                                     GtkTextIter *end,
                                     GtkSourceGutterRendererState state);

Main renderering method. Implementations should implement this method to draw onto the cairo context. The `background_area` indicates total area of the cell (without padding or margin) to be drawn. The `cell_area` indicates the area where content can be drawn (text, images, etc).

The `state` argument indicates the current state of the renderer and should be taken into account to properly draw the different possible states (cursor, prelit, selected) if appropriate.

#### Parameters

renderer | a GtkSourceGutterRenderer |
cr | the cairo render context |
background_area | a GdkRectangle indicating the total area to be drawn |
cell_area | a GdkRectangle indicating the area to draw content |
start | a GtkTextIter |
end | a GtkTextIter |
state | a GtkSourceGutterRendererState |

### gtk_source_gutter_renderer_end ()

    void
    gtk_source_gutter_renderer_end (GtkSourceGutterRenderer *renderer);

Called when drawing a region of lines has ended.

#### Parameters

renderer | a GtkSourceGutterRenderer |

### gtk_source_gutter_renderer_get_size ()

    gint
    gtk_source_gutter_renderer_get_size (GtkSourceGutterRenderer *renderer);

Get the size of the renderer.

#### Parameters

renderer | a GtkSourceGutterRenderer |

#### Returns

the size of the renderer.

### gtk_source_gutter_renderer_set_size ()

    void
    gtk_source_gutter_renderer_set_size (GtkSourceGutterRenderer *renderer,
                                         gint size);

Sets the size of the renderer. A value of -1 specifies that the size is to be determined dynamically.

#### Parameters

renderer | a GtkSourceGutterRenderer |
size | the size |

### gtk_source_gutter_renderer_set_visible ()

    void
    gtk_source_gutter_renderer_set_visible
                                   (GtkSourceGutterRenderer *renderer,
                                    gboolean visible);

Set whether the gutter renderer is visible.

#### Parameters

renderer | a GtkSourceGutterRenderer |
visible | the visibility |

### gtk_source_gutter_renderer_get_visible ()

    gboolean
    gtk_source_gutter_renderer_get_visible
                                   (GtkSourceGutterRenderer *renderer);

Get whether the gutter renderer is visible.

#### Parameters

renderer | a GtkSourceGutterRenderer |

#### Returns

`TRUE` if the renderer is visible, `FALSE` otherwise

### gtk_source_gutter_renderer_get_padding ()

    void
    gtk_source_gutter_renderer_get_padding
                                   (GtkSourceGutterRenderer *renderer,
                                    gint *xpad,
                                    gint *ypad);

Get the x-padding and y-padding of the gutter renderer.

#### Parameters

renderer | a GtkSourceGutterRenderer |
xpad | return location for the x-padding (can be `NULL`). | [out caller-allocates][allow-none]
ypad | return location for the y-padding (can be `NULL`). | [out caller-allocates][allow-none]

### gtk_source_gutter_renderer_set_padding ()

    void
    gtk_source_gutter_renderer_set_padding
                                   (GtkSourceGutterRenderer *renderer,
                                    gint xpad,
                                    gint ypad);

Set the padding of the gutter renderer. Both `xpad` and `ypad` can be -1, which means the values will not be changed (this allows changing only one of the values).

`xpad` is the left and right padding. `ypad` is the top and bottom padding.

#### Parameters

renderer | a GtkSourceGutterRenderer |
xpad | the x-padding |
ypad | the y-padding |

### gtk_source_gutter_renderer_get_alignment ()

    void
    gtk_source_gutter_renderer_get_alignment
                                   (GtkSourceGutterRenderer *renderer,
                                    gfloat *xalign,
                                    gfloat *yalign);

Get the x-alignment and y-alignment of the gutter renderer.

#### Parameters

renderer | a GtkSourceGutterRenderer |
xalign | return location for the x-alignment (can be `NULL`). | [out caller-allocates][allow-none]
yalign | return location for the y-alignment (can be `NULL`). | [out caller-allocates][allow-none]

### gtk_source_gutter_renderer_set_alignment ()

    void
    gtk_source_gutter_renderer_set_alignment
                                   (GtkSourceGutterRenderer *renderer,
                                    gfloat xalign,
                                    gfloat yalign);

Set the alignment of the gutter renderer. Both `xalign` and `yalign` can be -1, which means the values will not be changed (this allows changing only one of the values).

`xalign` is the horizontal alignment. Set to 0 for a left alignment. 1 for a right alignment. And 0.5 for centering the cells. `yalign` is the vertical alignment. Set to 0 for a top alignment. 1 for a bottom alignment.

#### Parameters

renderer | a GtkSourceGutterRenderer |
xalign | the x-alignment |
yalign | the y-alignment |

### gtk_source_gutter_renderer_set_alignment_mode ()

    void
    gtk_source_gutter_renderer_set_alignment_mode
                                   (GtkSourceGutterRenderer *renderer,
                                    GtkSourceGutterRendererAlignmentMode mode);

Set the alignment mode. The alignment mode describes the manner in which the renderer is aligned (see :xalign and :yalign).

#### Parameters

renderer | a GtkSourceGutterRenderer |
mode | a GtkSourceGutterRendererAlignmentMode |

### gtk_source_gutter_renderer_get_window_type ()

    GtkTextWindowType
    gtk_source_gutter_renderer_get_window_type
                                   (GtkSourceGutterRenderer *renderer);

Get the GtkTextWindowType associated with the gutter renderer.

#### Parameters

renderer | a GtkSourceGutterRenderer |

#### Returns

a GtkTextWindowType

### gtk_source_gutter_renderer_get_view ()

    GtkTextView *
    gtk_source_gutter_renderer_get_view (GtkSourceGutterRenderer *renderer);

Get the view associated to the gutter renderer

#### Parameters

renderer | a GtkSourceGutterRenderer |

#### Returns

a GtkTextView.

[transfer none]

### gtk_source_gutter_renderer_get_alignment_mode ()

    GtkSourceGutterRendererAlignmentMode
    gtk_source_gutter_renderer_get_alignment_mode
                                   (GtkSourceGutterRenderer *renderer);

Get the alignment mode. The alignment mode describes the manner in which the renderer is aligned (see :xalign and :yalign).

#### Parameters

renderer | a GtkSourceGutterRenderer |

#### Returns

a GtkSourceGutterRendererAlignmentMode

### gtk_source_gutter_renderer_get_background ()

    gboolean
    gtk_source_gutter_renderer_get_background
                                   (GtkSourceGutterRenderer *renderer,
                                    GdkRGBA *color);

Get the background color of the renderer.

#### Parameters

renderer | a GtkSourceGutterRenderer |
color | return value for a GdkRGBA. | [out caller-allocates][allow-none]

#### Returns

`TRUE` if the background color is set, `FALSE` otherwise

### gtk_source_gutter_renderer_set_background ()

    void
    gtk_source_gutter_renderer_set_background
                                   (GtkSourceGutterRenderer *renderer,
                                    const GdkRGBA *color);

Set the background color of the renderer. If `color` is set to `NULL`, the renderer will not have a background color.

#### Parameters

renderer | a GtkSourceGutterRenderer |
color | a GdkRGBA or `NULL`. | [allow-none]

### gtk_source_gutter_renderer_activate ()

    void
    gtk_source_gutter_renderer_activate (GtkSourceGutterRenderer *renderer,
                                         GtkTextIter *iter,
                                         GdkRectangle *area,
                                         GdkEvent *event);

Emits the “activate” signal of the renderer. This is called from GtkSourceGutter and should never have to be called manually.

#### Parameters

renderer | a GtkSourceGutterRenderer |
iter | a GtkTextIter at the start of the line where the renderer is activated |
area | a GdkRectangle of the cell area where the renderer is activated |
event | the event that triggered the activation |

### gtk_source_gutter_renderer_query_activatable ()

    gboolean
    gtk_source_gutter_renderer_query_activatable
                                   (GtkSourceGutterRenderer *renderer,
                                    GtkTextIter *iter,
                                    GdkRectangle *area,
                                    GdkEvent *event);

Get whether the renderer is activatable at the location in `event` . This is called from GtkSourceGutter to determine whether a renderer is activatable using the mouse pointer.

#### Parameters

renderer | a GtkSourceGutterRenderer |
iter | a GtkTextIter at the start of the line to be activated |
area | a GdkRectangle of the cell area to be activated |
event | the event that triggered the query |

#### Returns

`TRUE` if the renderer can be activated, `FALSE` otherwise

### gtk_source_gutter_renderer_queue_draw ()

    void
    gtk_source_gutter_renderer_queue_draw (GtkSourceGutterRenderer *renderer);

Emits the “queue-draw” signal of the renderer. Call this from an implementation to inform that the renderer has changed such that it needs to redraw.

#### Parameters

renderer | a GtkSourceGutterRenderer |

### gtk_source_gutter_renderer_query_tooltip ()

    gboolean
    gtk_source_gutter_renderer_query_tooltip
                                   (GtkSourceGutterRenderer *renderer,
                                    GtkTextIter *iter,
                                    GdkRectangle *area,
                                    gint x,
                                    gint y,
                                    GtkTooltip *tooltip);

Emits the “query-tooltip” signal. This function is called from GtkSourceGutter. Implementations can override the default signal handler or can connect to the signal externally.

#### Parameters

renderer | a GtkSourceGutterRenderer. |
iter | a GtkTextIter. |
area | a GdkRectangle. |
x | The x position of the tooltip. |
y | The y position of the tooltip. |
tooltip | a GtkTooltip. |

#### Returns

`TRUE` if the tooltip has been set, `FALSE` otherwise

### gtk_source_gutter_renderer_query_data ()

    void
    gtk_source_gutter_renderer_query_data (GtkSourceGutterRenderer *renderer,
                                           GtkTextIter *start,
                                           GtkTextIter *end,
                                           GtkSourceGutterRendererState state);

Emit the “query-data” signal. This function is called to query for data just before rendering a cell. This is called from the GtkSourceGutter. Implementations can override the default signal handler or can connect a signal handler externally to the “query-data” signal.

#### Parameters

renderer | a GtkSourceGutterRenderer. |
start | a GtkTextIter. |
end | a GtkTextIter. |
state | a GtkSourceGutterRendererState. |

## Types and Values

### GtkSourceGutterRenderer

    typedef struct _GtkSourceGutterRenderer GtkSourceGutterRenderer;

### enum GtkSourceGutterRendererState

#### Members

GTK_SOURCE_GUTTER_RENDERER_STATE_NORMAL | normal state |
GTK_SOURCE_GUTTER_RENDERER_STATE_CURSOR | area in the renderer represents the line on which the insert cursor is currently positioned |
GTK_SOURCE_GUTTER_RENDERER_STATE_PRELIT | the mouse pointer is currently over the activatable area of the renderer |
GTK_SOURCE_GUTTER_RENDERER_STATE_SELECTED | area in the renderer represents a line in the buffer which contains part of the selection |

### enum GtkSourceGutterRendererAlignmentMode

The alignment mode of the renderer, when a cell spans multiple lines (due to text wrapping).

#### Members

GTK_SOURCE_GUTTER_RENDERER_ALIGNMENT_MODE_CELL | The full cell. |
GTK_SOURCE_GUTTER_RENDERER_ALIGNMENT_MODE_FIRST | The first line. |
GTK_SOURCE_GUTTER_RENDERER_ALIGNMENT_MODE_LAST | The last line. |

## Property Details

### The `“alignment-mode”` property

      “alignment-mode”           GtkSourceGutterRendererAlignmentMode

The alignment mode of the renderer. This can be used to indicate that in the case a cell spans multiple lines (due to text wrapping) the alignment should work on either the full cell, the first line or the last line.

Flags: Read / Write / Construct

Default value: GTK_SOURCE_GUTTER_RENDERER_ALIGNMENT_MODE_CELL

### The `“background-rgba”` property

      “background-rgba”          GdkRGBA *

The background color.

Flags: Read / Write

### The `“background-set”` property

      “background-set”           gboolean

Whether the background color is set.

Flags: Read / Write / Construct

Default value: FALSE

### The `“size”` property

      “size”                     gint

The size.

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 0

### The `“view”` property

      “view”                     GtkTextView *

The view on which the renderer is placed.

Flags: Read

### The `“visible”` property

      “visible”                  gboolean

The visibility of the renderer.

Flags: Read / Write / Construct

Default value: TRUE

### The `“window-type”` property

      “window-type”              GtkTextWindowType

The window type of the view on which the renderer is placed (left, or right).

Flags: Read

Default value: GTK_TEXT_WINDOW_PRIVATE

### The `“xalign”` property

      “xalign”                   gfloat

The horizontal alignment of the renderer. Set to 0 for a left alignment. 1 for a right alignment. And 0.5 for centering the cells. A value lower than 0 doesn't modify the alignment.

Flags: Read / Write / Construct

Allowed values: [-1,1]

Default value: 0

### The `“xpad”` property

      “xpad”                     gint

The left and right padding of the renderer.

Flags: Read / Write / Construct

Allowed values: >= -1

Default value: 0

### The `“yalign”` property

      “yalign”                   gfloat

The vertical alignment of the renderer. Set to 0 for a top alignment. 1 for a bottom alignment. And 0.5 for centering the cells. A value lower than 0 doesn't modify the alignment.

Flags: Read / Write / Construct

Allowed values: [-1,1]

Default value: 0

### The `“ypad”` property

      “ypad”                     gint

The top and bottom padding of the renderer.

Flags: Read / Write / Construct

Allowed values: >= -1

Default value: 0

## Signal Details

### The `“activate”` signal

    void
    user_function (GtkSourceGutterRenderer *renderer,
                   GtkTextIter             *iter,
                   GdkRectangle            *area,
                   GdkEvent                *event,
                   gpointer                 user_data)

The ::activate signal is emitted when the renderer is activated.

#### Parameters

renderer | the GtkSourceGutterRenderer who emits the signal |
iter | a GtkTextIter |
area | a GdkRectangle |
event | the event that caused the activation |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“query-activatable”` signal

    gboolean
    user_function (GtkSourceGutterRenderer *renderer,
                   GtkTextIter             *iter,
                   GdkRectangle            *area,
                   GdkEvent                *event,
                   gpointer                 user_data)

The ::query-activatable signal is emitted when the renderer can possibly be activated.

#### Parameters

renderer | the GtkSourceGutterRenderer who emits the signal |
iter | a GtkTextIter |
area | a GdkRectangle |
event | the GdkEvent that is causing the activatable query |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“query-data”` signal

    void
    user_function (GtkSourceGutterRenderer     *renderer,
                   GtkTextIter                 *start,
                   GtkTextIter                 *end,
                   GtkSourceGutterRendererState state,
                   gpointer                     user_data)

The ::query-data signal is emitted when the renderer needs to be filled with data just before a cell is drawn. This can be used by general renderer implementations to allow render data to be filled in externally.

#### Parameters

renderer | the GtkSourceGutterRenderer who emits the signal |
start | a GtkTextIter |
end | a GtkTextIter |
state | the renderer state |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“query-tooltip”` signal

    gboolean
    user_function (GtkSourceGutterRenderer *renderer,
                   GtkTextIter             *iter,
                   GdkRectangle            *area,
                   gint                     x,
                   gint                     y,
                   GtkTooltip              *tooltip,
                   gpointer                 user_data)

The ::query-tooltip signal is emitted when the renderer can show a tooltip.

#### Parameters

renderer | the GtkSourceGutterRenderer who emits the signal |
iter | a GtkTextIter |
area | a GdkRectangle |
x | the x position (in window coordinates) |
y | the y position (in window coordinates) |
tooltip | a GtkTooltip |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“queue-draw”` signal

    void
    user_function (GtkSourceGutterRenderer *renderer,
                   gpointer                 user_data)

The ::queue-draw signal is emitted when the renderer needs to be redrawn. Use `gtk_source_gutter_renderer_queue_draw()` to emit this signal from an implementation of the GtkSourceGutterRenderer interface.

#### Parameters

renderer | the GtkSourceGutterRenderer who emits the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

GtkSourceGutter