GtkSource.SpaceDrawer¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`bind_matrix_setting` (settings, key, flags)
	`get_enable_matrix` ()
	`get_matrix` ()
	`get_types_for_locations` (locations)
	`set_enable_matrix` (enable_matrix)
	`set_matrix` (matrix)
	`set_types_for_locations` (locations, types)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`enable-matrix`	`bool`	r/w/c
`matrix`	`GLib.Variant`	r/w/c

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class GtkSource.SpaceDrawer(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: GtkSource.SpaceDrawerClass

Represent white space characters with symbols.

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

Call [method`View`.get_space_drawer] to get the GtkSourceSpaceDrawer instance of a certain [class`View`].

By default, no white spaces are drawn because the [property`SpaceDrawer`:py:data::enable-matrix<GtkSource.SpaceDrawer.props.enable_matrix>] is False.

To draw white spaces, [method`SpaceDrawer`.set_types_for_locations] can be called to set the [property`SpaceDrawer`:py:data::matrix<GtkSource.SpaceDrawer.props.matrix>] property (by default all space types are enabled at all locations). Then call [method`SpaceDrawer`.set_enable_matrix].

For a finer-grained method, there is also the [class`Tag`]’s [property`Tag`:py:data::draw-spaces<GtkSource.SpaceDrawer.props.draw_spaces>] property.

Example

To draw non-breaking spaces everywhere and draw all types of trailing spaces except newlines: ```c GtkSource.SpaceDrawer.set_types_for_locations (space_drawer, GtkSource.SpaceLocationFlags.ALL, GtkSource.SpaceTypeFlags.NBSP);

GtkSource.SpaceDrawer.set_types_for_locations (space_drawer, GtkSource.SpaceLocationFlags.TRAILING, GtkSource.SpaceTypeFlags.ALL & ~:obj:GtkSource.SpaceTypeFlags.NEWLINE);

GtkSource.SpaceDrawer.set_enable_matrix (space_drawer, True); `` ``python space_drawer.set_types_for_locations( locations=GtkSource.SpaceLocationFlags.ALL, types=GtkSource.SpaceTypeFlags.NBSP, )

all_types_except_newline = GtkSource.SpaceTypeFlags( int(GtkSource.SpaceTypeFlags.ALL) & ~int(GtkSource.SpaceTypeFlags.NEWLINE) ) space_drawer.set_types_for_locations( locations=GtkSource.SpaceLocationFlags.TRAILING, types=all_types_except_newline, )

space_drawer.set_enable_matrix(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.

classmethod new()¶

Returns:: a new GtkSource.SpaceDrawer.
Return type:: GtkSource.SpaceDrawer

Creates a new GtkSource.SpaceDrawer object.

Useful for storing space drawing settings independently of a [class`View`].

bind_matrix_setting(settings, key, flags)¶

Parameters:

settings (Gio.Settings) – a Gio.Settings object.
key (str) – the settings key to bind.
flags (Gio.SettingsBindFlags) – flags for the binding.

Binds the [property`SpaceDrawer`:py:data::matrix<GtkSource.SpaceDrawer.props.matrix>] property to a [class`Gio`.Settings] key.

The [class`Gio`.Settings] key must be of the same type as the [property`SpaceDrawer`:py:data::matrix<GtkSource.SpaceDrawer.props.matrix>] property, that is, "au".

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

get_enable_matrix()¶

Returns:: whether the GtkSource.SpaceDrawer :matrix property is enabled.
Return type:: bool

get_matrix()¶

Returns:: the GtkSource.SpaceDrawer :matrix value as a new floating GLib.Variant instance.
Return type:: GLib.Variant

Gets the value of the [property`SpaceDrawer`:py:data::matrix<GtkSource.SpaceDrawer.props.matrix>] property, as a [struct`GLib`.Variant].

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

The [method`SpaceDrawer`.get_types_for_locations] function may be more convenient to use.

get_types_for_locations(locations)¶

Parameters:: locations (GtkSource.SpaceLocationFlags) – one or several GtkSource.SpaceLocationFlags.
Returns:: a combination of GtkSource.SpaceTypeFlags.
Return type:: GtkSource.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 [property`SpaceDrawer`:py:data::matrix<GtkSource.SpaceDrawer.props.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.

set_enable_matrix(enable_matrix)¶

Parameters:: enable_matrix (bool) – the new value.

Sets whether the [property`SpaceDrawer`:py:data::matrix<GtkSource.SpaceDrawer.props.matrix>] property is enabled.

set_matrix(matrix)¶

Parameters:: matrix (GLib.Variant or None) – the new matrix value, or None.

Sets a new value to the [property`SpaceDrawer`:py:data::matrix<GtkSource.SpaceDrawer.props.matrix>] property, as a [struct`GLib`.Variant].

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

If matrix is floating, it is consumed.

The [method`SpaceDrawer`.set_types_for_locations] function may be more convenient to use.

set_types_for_locations(locations, types)¶

Parameters:

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

Modifies the [property`SpaceDrawer`:py:data::matrix<GtkSource.SpaceDrawer.props.matrix>] property at the specified locations.

Property Details¶

GtkSource.SpaceDrawer.props.enable_matrix¶

Name:: enable-matrix
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, CONSTRUCT

Whether the [property`SpaceDrawer`:py:data::matrix<GtkSource.SpaceDrawer.props.matrix>] property is enabled.

GtkSource.SpaceDrawer.props.matrix¶

Name:: matrix
Type:: GLib.Variant
Default Value:: GLib.Variant('au', [15, 15, 15])
Flags:: READABLE, WRITABLE, CONSTRUCT

The property is a [struct`GLib`.Variant] property to specify where and what kind of white spaces to draw.

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

By default, GtkSource.SpaceTypeFlags.ALL is set for all locations.4