SpaceDrawer

class SpaceDrawer(**properties: Any)

Superclasses: Object

Represent white space characters with symbols.

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

Call get_space_drawer to get the GtkSourceSpaceDrawer instance of a certain View.

By default, no white spaces are drawn because the enable_matrix is False.

To draw white spaces, set_types_for_locations can be called to set the matrix property (by default all space types are enabled at all locations). Then call set_enable_matrix.

For a finer-grained method, there is also the Tag’s draw_spaces property.

Example

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

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.

Constructors

class SpaceDrawer

classmethod new() → SpaceDrawer

Creates a new SpaceDrawer object.

Useful for storing space drawing settings independently of a View.

Methods

class SpaceDrawer

bind_matrix_setting(settings: Settings, key: str, flags: SettingsBindFlags) → None

Binds the matrix property to a Settings key.

The Settings key must be of the same type as the matrix property, that is, "au".

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

Parameters:

settings – a Settings object.
key – the settings key to bind.
flags – flags for the binding.

get_enable_matrix() → bool

get_matrix() → Variant

Gets the value of the matrix property, as a Variant.

An empty array can be returned in case the matrix is a zero matrix.

The get_types_for_locations function may be more convenient to use.

get_types_for_locations(locations: SpaceLocationFlags) → SpaceTypeFlags

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:: locations – one or several SpaceLocationFlags.

set_enable_matrix(enable_matrix: bool) → None

Sets whether the matrix property is enabled.

Parameters:: enable_matrix – the new value.

set_matrix(matrix: Variant | None = None) → None

Sets a new value to the matrix property, as a Variant.

If matrix is None, then an empty array is set.

If matrix is floating, it is consumed.

The set_types_for_locations function may be more convenient to use.

Parameters:: matrix – the new matrix value, or None.

set_types_for_locations(locations: SpaceLocationFlags, types: SpaceTypeFlags) → None

Modifies the matrix property at the specified locations.

Parameters:

locations – one or several SpaceLocationFlags.
types – a combination of SpaceTypeFlags.

Properties

class SpaceDrawer

props.enable_matrix: bool: Whether the matrix property is enabled.

props.matrix: Variant

The property is a Variant property to specify where and what kind of white spaces to draw.

The Variant is of type "au", an array of unsigned integers. Each integer is a combination of SpaceTypeFlags. There is one integer for each SpaceLocationFlags, in the same order as they are defined in the enum (NONE and 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 NONE.

By default, ALL is set for all locations.4