GtkSourceGutterRenderer

GtkSourceGutterRenderer — Gutter cell renderer

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

Object Hierarchy

    GEnum
    ╰── GtkSourceGutterRendererAlignmentMode
    GFlags
    ╰── GtkSourceGutterRendererState
    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:

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 the total area of the cell to be drawn. The cell_area indicates the area where content can be drawn (text, images, etc).

The background_area is the cell_area plus the padding on each side (two times the “xpad” horizontally and two times the “ypad” vertically, so that the cell_area is centered inside background_area ).

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_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_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_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_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_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_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, or NULL to ignore.

[out caller-allocates][optional]

ypad

return location for the y-padding, or NULL to ignore.

[out caller-allocates][optional]

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, or NULL to ignore.

[out caller-allocates][optional]

yalign

return location for the y-alignment, or NULL to ignore.

[out caller-allocates][optional]

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

 

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


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][optional]

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.

[nullable]

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

 

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

 

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