GtkSourceSpaceDrawer: GtkSourceView 3 Reference Manual

## GtkSourceSpaceDrawer GtkSourceSpaceDrawer — Represent white space characters with symbols |

## Functions

GtkSourceSpaceDrawer * | gtk_source_space_drawer_new ()
void | gtk_source_space_drawer_set_types_for_locations ()
GtkSourceSpaceTypeFlags | gtk_source_space_drawer_get_types_for_locations ()
void | gtk_source_space_drawer_set_matrix ()
GVariant * | gtk_source_space_drawer_get_matrix ()
void | gtk_source_space_drawer_set_enable_matrix ()
gboolean | gtk_source_space_drawer_get_enable_matrix ()
void | gtk_source_space_drawer_bind_matrix_setting ()

## Properties

gboolean | enable-matrix | Read / Write / Construct
GVariant * | matrix | Read / Write / Construct

## Types and Values

| GtkSourceSpaceDrawer
enum | GtkSourceSpaceTypeFlags
enum | GtkSourceSpaceLocationFlags

## Object Hierarchy

        GFlags
        ├── GtkSourceSpaceLocationFlags
        ╰── GtkSourceSpaceTypeFlags
        GObject
        ╰── GtkSourceSpaceDrawer

## Includes

    #include <gtksourceview/gtksource.h>

## Description

GtkSourceSpaceDrawer provides a way to visualize white spaces, by drawing symbols.

Call `gtk_source_view_get_space_drawer()` to get the GtkSourceSpaceDrawer instance of a certain GtkSourceView.

By default, no white spaces are drawn because the “enable-matrix” is `FALSE`.

To draw white spaces, `gtk_source_space_drawer_set_types_for_locations()` can be called to set the “matrix” property (by default all space types are enabled at all locations). Then call `gtk_source_space_drawer_set_enable_matrix()`.

For a finer-grained method, there is also the GtkSourceTag's “draw-spaces” property.

### Example

To draw non-breaking spaces everywhere and draw all types of trailing spaces except newlines:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    gtk_source_space_drawer_set_types_for_locations (space_drawer,
                                                     GTK_SOURCE_SPACE_LOCATION_ALL,
                                                     GTK_SOURCE_SPACE_TYPE_NBSP);

    gtk_source_space_drawer_set_types_for_locations (space_drawer,
                                                     GTK_SOURCE_SPACE_LOCATION_TRAILING,
                                                     GTK_SOURCE_SPACE_TYPE_ALL &
                                                     ~GTK_SOURCE_SPACE_TYPE_NEWLINE);

    gtk_source_space_drawer_set_enable_matrix (space_drawer, TRUE);

### Use-case: draw unwanted white spaces

A possible use-case is to draw only unwanted white spaces. Examples:

- Draw all trailing spaces.

- If the indentation and alignment must be done with spaces, draw tabs.

And non-breaking spaces can always be drawn, everywhere, to distinguish them from normal spaces.

## Functions

### gtk_source_space_drawer_new ()

    GtkSourceSpaceDrawer *
    gtk_source_space_drawer_new (void);

Creates a new GtkSourceSpaceDrawer object. Useful for storing space drawing settings independently of a GtkSourceView.

#### Returns

a new GtkSourceSpaceDrawer.

Since: 3.24

### gtk_source_space_drawer_set_types_for_locations ()

    void
    gtk_source_space_drawer_set_types_for_locations
                                   (GtkSourceSpaceDrawer *drawer,
                                    GtkSourceSpaceLocationFlags locations,
                                    GtkSourceSpaceTypeFlags types);

Modifies the “matrix” property at the specified `locations` .

#### Parameters

drawer | a GtkSourceSpaceDrawer. |
locations | one or several GtkSourceSpaceLocationFlags. |
types | a combination of GtkSourceSpaceTypeFlags. |

Since: 3.24

### gtk_source_space_drawer_get_types_for_locations ()

    GtkSourceSpaceTypeFlags
    gtk_source_space_drawer_get_types_for_locations
                                   (GtkSourceSpaceDrawer *drawer,
                                    GtkSourceSpaceLocationFlags locations);

If only one location is specified, this function returns what kind of white spaces are drawn at that location. The value is retrieved from the “matrix” property.

If several locations are specified, this function returns the logical AND for those locations. Which means that if a certain kind of white space is present in the return value, then that kind of white space is drawn at all the specified `locations` .

#### Parameters

drawer | a GtkSourceSpaceDrawer. |
locations | one or several GtkSourceSpaceLocationFlags. |

#### Returns

a combination of GtkSourceSpaceTypeFlags.

Since: 3.24

### gtk_source_space_drawer_set_matrix ()

    void
    gtk_source_space_drawer_set_matrix (GtkSourceSpaceDrawer *drawer,
                                        GVariant *matrix);

Sets a new value to the “matrix” property, as a GVariant. If `matrix` is `NULL`, then an empty array is set.

If `matrix` is floating, it is consumed.

The `gtk_source_space_drawer_set_types_for_locations()` function may be more convenient to use.

#### Parameters

drawer | a GtkSourceSpaceDrawer. |
matrix | the new matrix value, or `NULL`. | [transfer floating][nullable]

Since: 3.24

### gtk_source_space_drawer_get_matrix ()

    GVariant *
    gtk_source_space_drawer_get_matrix (GtkSourceSpaceDrawer *drawer);

Gets the value of the “matrix” property, as a GVariant. An empty array can be returned in case the matrix is a zero matrix.

The `gtk_source_space_drawer_get_types_for_locations()` function may be more convenient to use.

#### Parameters

drawer | a GtkSourceSpaceDrawer. |

#### Returns

the “matrix” value as a new floating GVariant instance.

Since: 3.24

### gtk_source_space_drawer_set_enable_matrix ()

    void
    gtk_source_space_drawer_set_enable_matrix
                                   (GtkSourceSpaceDrawer *drawer,
                                    gboolean enable_matrix);

Sets whether the “matrix” property is enabled.

#### Parameters

drawer | a GtkSourceSpaceDrawer. |
enable_matrix | the new value. |

Since: 3.24

### gtk_source_space_drawer_get_enable_matrix ()

    gboolean
    gtk_source_space_drawer_get_enable_matrix
                                   (GtkSourceSpaceDrawer *drawer);

#### Parameters

drawer | a GtkSourceSpaceDrawer. |

#### Returns

whether the “matrix” property is enabled.

Since: 3.24

### gtk_source_space_drawer_bind_matrix_setting ()

    void
    gtk_source_space_drawer_bind_matrix_setting
                                   (GtkSourceSpaceDrawer *drawer,
                                    GSettings *settings,
                                    const gchar *key,
                                    GSettingsBindFlags flags);

Binds the “matrix” property to a GSettings key.

The GSettings key must be of the same type as the “matrix” property, that is, `"au"`.

The `g_settings_bind()` function cannot be used, because the default GIO mapping functions don't support GVariant properties (maybe it will be supported by a future GIO version, in which case this function can be deprecated).

#### Parameters

drawer | a GtkSourceSpaceDrawer object. |
settings | a GSettings object. |
key | the `settings` key to bind. |
flags | flags for the binding. |

Since: 3.24

## Types and Values

### GtkSourceSpaceDrawer

    typedef struct _GtkSourceSpaceDrawer GtkSourceSpaceDrawer;

### enum GtkSourceSpaceTypeFlags

GtkSourceSpaceTypeFlags contains flags for white space types.

#### Members

GTK_SOURCE_SPACE_TYPE_NONE | No flags. |
GTK_SOURCE_SPACE_TYPE_SPACE | Space character. |
GTK_SOURCE_SPACE_TYPE_TAB | Tab character. |
GTK_SOURCE_SPACE_TYPE_NEWLINE | Line break character. If the “implicit-trailing-newline” property is `TRUE`, GtkSourceSpaceDrawer also draws a line break at the end of the buffer. |
GTK_SOURCE_SPACE_TYPE_NBSP | Non-breaking space character. |
GTK_SOURCE_SPACE_TYPE_ALL | All white spaces. |

Since: 3.24

### enum GtkSourceSpaceLocationFlags

GtkSourceSpaceLocationFlags contains flags for white space locations.

If a line contains only white spaces (no text), the white spaces match both `GTK_SOURCE_SPACE_LOCATION_LEADING` and `GTK_SOURCE_SPACE_LOCATION_TRAILING`.

#### Members

GTK_SOURCE_SPACE_LOCATION_NONE | No flags. |
GTK_SOURCE_SPACE_LOCATION_LEADING | Leading white spaces on a line, i.e. the indentation. |
GTK_SOURCE_SPACE_LOCATION_INSIDE_TEXT | White spaces inside a line of text. |
GTK_SOURCE_SPACE_LOCATION_TRAILING | Trailing white spaces on a line. |
GTK_SOURCE_SPACE_LOCATION_ALL | White spaces anywhere. |

Since: 3.24

## Property Details

### The `“enable-matrix”` property

      “enable-matrix”            gboolean

Whether the “matrix” property is enabled.

Flags: Read / Write / Construct

Default value: FALSE

Since: 3.24

### The `“matrix”` property

      “matrix”                   GVariant *

The :matrix property is a GVariant property to specify where and what kind of white spaces to draw.

The GVariant is of type `"au"`, an array of unsigned integers. Each integer is a combination of GtkSourceSpaceTypeFlags. There is one integer for each GtkSourceSpaceLocationFlags, in the same order as they are defined in the enum (`GTK_SOURCE_SPACE_LOCATION_NONE` and `GTK_SOURCE_SPACE_LOCATION_ALL` are not taken into account).

If the array is shorter than the number of locations, then the value for the missing locations will be `GTK_SOURCE_SPACE_TYPE_NONE`.

By default, `GTK_SOURCE_SPACE_TYPE_ALL` is set for all locations.

Flags: Read / Write / Construct

Allowed values: GVariant<au>

Default value: [uint32 15, 15, 15]

Since: 3.24

## See Also

GtkSourceView