Functions¶

	`encoding_iconv_get_all` ()
	`encoding_iconv_get_default_candidates` ()
	`finalize` ()
	`init` ()
	`io_error_info_bar_cant_create_backup` (location, error)
	`io_error_info_bar_externally_modified` (location, document_modified)
	`io_error_info_bar_file_already_open` (location)
	`io_error_info_bar_invalid_characters` (location)
	`io_error_info_bar_saving_externally_modified` (location)
	`iter_get_line_indentation` (iter)
	`menu_shell_append_edit_actions` (menu_shell)
	`pango_font_description_to_css` (desc)
	`prefs_create_color_scheme_component` (settings, style_scheme_key)
	`prefs_create_display_line_numbers_checkbutton` (settings, display_line_numbers_key)
	`prefs_create_files_component` (settings, create_backup_copy_key, auto_save_key, auto_save_interval)
	`prefs_create_font_component` (settings, use_default_font_key, editor_font_key)
	`prefs_create_highlighting_component` (settings, highlight_current_line_key, highlight_matching_brackets_key)
	`prefs_create_insert_spaces_component` (settings, insert_spaces_key, smart_backspace_key)
	`prefs_create_tab_width_spinbutton` (settings, tab_width_key)
	`utils_binding_transform_func_smart_bool` (binding, from_value, to_value, user_data)
	`utils_can_use_gsettings_key` (settings, key)
	`utils_can_use_gsettings_schema` (schema_id)
	`utils_create_close_button` ()
	`utils_create_parent_directories` (file, cancellable)
	`utils_decode_uri` (uri)
	`utils_file_query_exists_async` (file, cancellable, callback, *user_data)
	`utils_file_query_exists_finish` (file, result)
	`utils_get_file_extension` (filename)
	`utils_get_file_shortname` (filename)
	`utils_get_titled_component` (title, component)
	`utils_list_box_clear` (list_box)
	`utils_list_box_get_filtered_children` (list_box, filter_func, *user_data)
	`utils_list_box_get_row_at_index_with_filter` (list_box, index, filter_func, *user_data)
	`utils_list_box_scroll_to_row` (list_box, row)
	`utils_list_box_scroll_to_selected_row` (list_box)
	`utils_list_box_setup_scrolling` (list_box, scrolled_window)
	`utils_markup_escape_text` (src)
	`utils_override_font_description` (widget, font_desc)
	`utils_override_font_string` (widget, font_str)
	`utils_replace_home_dir_with_tilde` (filename)
	`utils_setup_statusbar` (statusbar)
	`utils_str_end_truncate` (str, truncate_length)
	`utils_str_middle_truncate` (str, truncate_length)
	`utils_str_replace` (string, search, replacement)

Details¶

Tepl.encoding_iconv_get_all()¶

Returns:: a list of Tepl.EncodingIconv's.
Return type:: [Tepl.EncodingIconv]

Gets a list of all encodings known by Tepl.EncodingIconv.

New in version 6.4.

Tepl.encoding_iconv_get_default_candidates()¶

Returns:: the list of default candidate encodings.
Return type:: [Tepl.EncodingIconv]

Gets the list of default candidate encodings to try when loading a file. See GtkSource.FileLoader.set_candidate_encodings().

This function returns a different list depending on the current locale (i.e. language, country and default encoding). The UTF-8 encoding and the current locale encoding are guaranteed to be present in the returned list.

Note that the returned list doesn’t contain all encodings known by Tepl.EncodingIconv, it is a limited list that contains only the encodings that have the most likelihood to fit for the current locale.

New in version 6.4.

Tepl.finalize()¶

Free the resources allocated by Tepl. For example it unrefs the singleton objects.

This function also calls Amtk.finalize() and GtkSource.finalize().

It is not mandatory to call this function, it’s just to be friendlier to memory debugging tools. This function is meant to be called at the end of main(). It can be called several times.

New in version 3.0.

Tepl.init()¶

Initializes the Tepl library (e.g. for the internationalization).

This function can be called several times, but is meant to be called at the beginning of main(), before any other Tepl function call.

This function also calls Amtk.init() and GtkSource.init().

New in version 3.0.

Tepl.io_error_info_bar_cant_create_backup(location, error)¶

Parameters:

location (Gio.File) – the Gio.File for which the backup failed to be created.
error (GLib.Error) – must be a Gio.IOErrorEnum.CANT_CREATE_BACKUP.

Returns:

the newly created Tepl.InfoBar.

Return type:

Tepl.InfoBar

When a Gio.IOErrorEnum.CANT_CREATE_BACKUP error occurs while saving location, offer two possible actions:

Save anyway: Gtk.ResponseType.YES.
Don’t save: Gtk.ResponseType.CANCEL.

New in version 5.0.

Tepl.io_error_info_bar_externally_modified(location, document_modified)¶

Parameters:

location (Gio.File) – the Gio.File for which there has been an external modification.
document_modified (bool) – whether the document (e.g. the Gtk.TextBuffer) has unsaved modifications.

Returns:

the newly created Tepl.InfoBar.

Return type:

Tepl.InfoBar

Creates a warning about location having changed on disk. The possible actions:

Depending on document_modified, “Reload” or “Drop changes and reload”: Gtk.ResponseType.OK.
Ignore: Gtk.ResponseType.CLOSE.

New in version 5.0.

Tepl.io_error_info_bar_file_already_open(location)¶

Parameters:: location (Gio.File) – the Gio.File already open in another window.
Returns:: the newly created Tepl.InfoBar.
Return type:: Tepl.InfoBar

Creates a warning about location being already open in another window, offering two possible actions:

Edit anyway: Gtk.ResponseType.YES.
Don’t edit: Gtk.ResponseType.CANCEL.

New in version 5.0.

Tepl.io_error_info_bar_invalid_characters(location)¶

Parameters:: location (Gio.File) – where to save the document.
Returns:: the newly created Tepl.InfoBar.
Return type:: Tepl.InfoBar

For file saving, creates a warning about invalid characters that can corrupt the file. Possible actions:

Save anyway: Gtk.ResponseType.YES.
Don’t save: Gtk.ResponseType.CANCEL.

New in version 5.0.

Tepl.io_error_info_bar_saving_externally_modified(location)¶

Parameters:: location (Gio.File) – a Gio.File.
Returns:: the newly created Tepl.InfoBar.
Return type:: Tepl.InfoBar

When attempting to save location, creates a warning about location having changed on disk. The possible actions:

Save anyway: Gtk.ResponseType.YES.
Don’t save: Gtk.ResponseType.CANCEL.

New in version 6.4.

Tepl.iter_get_line_indentation(iter)¶

Parameters:: iter (Gtk.TextIter) – a Gtk.TextIter.
Returns:: the line indentation at iter. Free with GLib.free().
Return type:: str

Gets the indentation, as a string, of the line at iter. iter can be anywhere in the line.

Possible use-case: to implement an action that inserts some text in a Gtk.TextBuffer. If the text to insert spans multiple lines, it is usually desired to keep the same indentation level.

New in version 2.0.

Tepl.menu_shell_append_edit_actions(menu_shell)¶

Parameters:: menu_shell (Gtk.MenuShell) – a Gtk.MenuShell.

Appends Gtk.MenuItem's to menu_shell for the following Gio.Action's:

"win.tepl-cut"
"win.tepl-copy"
"win.tepl-paste"
"win.tepl-delete"
"win.tepl-select-all"

See the ‘list of GActions implemented in TeplApplicationWindow [tepl-application-window-gactions]’. This function correctly uses the Amtk.FactoryFlags.IGNORE_ACCELS_FOR_APP flag to create the Gtk.MenuItem's.

New in version 3.0.

Tepl.pango_font_description_to_css(desc)¶

Parameters:: desc (Pango.FontDescription) – a Pango.FontDescription.
Returns:: A newly allocated string containing the CSS describing the font description. Free with GLib.free() when no longer needed.
Return type:: str

This function will generate CSS suitable for the GTK CSS engine based on the properties of the Pango.FontDescription.

The returned string contains only the CSS declarations, it is not a complete CSS rule set. So the selector and curly braces are not present. Each declaration, including the last one, ends with a semicolon.

New in version 6.0.

Tepl.prefs_create_color_scheme_component(settings, style_scheme_key)¶

Parameters:

settings (Gio.Settings) – a Gio.Settings.
style_scheme_key (str) – a key part of settings to store the style scheme ID. The type of the key must be a string.

Returns:

A component for choosing the GtkSource.StyleScheme to use.

Return type:

Gtk.Widget

This function creates a component containing a Tepl.StyleSchemeChooserWidget.

New in version 6.2.

Tepl.prefs_create_display_line_numbers_checkbutton(settings, display_line_numbers_key)¶

Parameters:

settings (Gio.Settings) – a Gio.Settings.
display_line_numbers_key (str) – a key part of settings. The type of the key must be a boolean.

Returns:

A Gtk.CheckButton intended for GtkSource.View :show-line-numbers.

Return type:

Gtk.Widget

New in version 6.2.

Tepl.prefs_create_files_component(settings, create_backup_copy_key, auto_save_key, auto_save_interval)¶

Parameters:

settings (Gio.Settings) – a Gio.Settings.
create_backup_copy_key (str) – a key part of settings. The type of the key must be a boolean. Intended to be used with Tepl.FileSaverFlags.CREATE_BACKUP (for example).
auto_save_key (str) – a key part of settings. The type of the key must be a boolean. Whether to autosave files.
auto_save_interval (str) – a key part of settings. The type of the key must be an unsigned integer, with a range. The interval is in minutes.

Returns:

a component for some files preferences.

Return type:

Gtk.Widget

New in version 6.2.

Tepl.prefs_create_font_component(settings, use_default_font_key, editor_font_key)¶

Parameters:

settings (Gio.Settings) – a Gio.Settings.
use_default_font_key (str) – a key part of settings to store whether to use the system font. The type of the key must be a boolean.
editor_font_key (str) – a key part of settings to store the editor font. The type of the key must be a string.

Returns:

A component for configuring the font.

Return type:

Gtk.Widget

New in version 6.2.

Tepl.prefs_create_highlighting_component(settings, highlight_current_line_key, highlight_matching_brackets_key)¶

Parameters:

settings (Gio.Settings) – a Gio.Settings.
highlight_current_line_key (str) – a key part of settings. The type of the key must be a boolean.
highlight_matching_brackets_key (str) – a key part of settings. The type of the key must be a boolean.

Returns:

a component intended for GtkSource.View :highlight-current-line and GtkSource.Buffer :highlight-matching-brackets.

Return type:

Gtk.Widget

New in version 6.2.

Tepl.prefs_create_insert_spaces_component(settings, insert_spaces_key, smart_backspace_key)¶

Parameters:

settings (Gio.Settings) – a Gio.Settings.
insert_spaces_key (str) – a key part of settings. The type of the key must be a boolean.
smart_backspace_key (str) – a key part of settings. The type of the key must be a boolean.

Returns:

a component intended for GtkSource.View :insert-spaces-instead-of-tabs and GtkSource.View :smart-backspace.

Return type:

Gtk.Widget

New in version 6.2.

Tepl.prefs_create_tab_width_spinbutton(settings, tab_width_key)¶

Parameters:

settings (Gio.Settings) – a Gio.Settings.
tab_width_key (str) – a key part of settings. The type of the key must be an unsigned integer, with a range.

Returns:

A widget containing a Gtk.SpinButton intended for GtkSource.View :tab-width.

Return type:

Gtk.Widget

New in version 6.2.

Tepl.utils_binding_transform_func_smart_bool(binding, from_value, to_value, user_data)¶

Parameters:

binding (GObject.Binding) – a GObject.Binding.
from_value (GObject.Value) – the GObject.Value containing the value to transform.
to_value (GObject.Value) – the GObject.Value in which to store the transformed value.
user_data (object or None) – data passed to the transform function.

Returns:

True if the transformation was successful, and False otherwise.

Return type:

bool

A GObject.BindingTransformFunc to transform between these two GObject.Value types:

A GObject.Value of type bool.
A GObject.Value of type GLib.Variant, with the GLib.Variant of type boolean.

For convenience, this function works in both directions (hence the “smart”), it introspects the types of from_value and to_value.

Note that if from_value and to_value are of the same GObject.Value type, this function won’t work and you shouldn’t use a custom GObject.BindingTransformFunc in the first place.

New in version 5.0.

Tepl.utils_can_use_gsettings_key(settings, key)¶

Parameters:

settings (Gio.Settings) – a Gio.Settings object.
key (str) – the key to introspect.

Returns:

whether the Gio.Settings key exists.

Return type:

bool

Especially useful for external Gio.Settings (provided by another application for instance).

See also: Tepl.utils_can_use_gsettings_schema() which is typically used before this function.

New in version 6.2.

Tepl.utils_can_use_gsettings_schema(schema_id)¶

Parameters:: schema_id (str) – a Gio.Settings schema ID.
Returns:: True if a Gio.Settings instance can be created with schema_id. False otherwise (in that case the program would crash).
Return type:: bool

Checks that a Gio.Settings schema exists.

Especially useful for external Gio.Settings (provided by another application for instance).

New in version 6.2.

Tepl.utils_create_close_button()¶

Returns:: a new close button (a Gtk.Button).
Return type:: Gtk.Widget

New in version 5.0.

Tepl.utils_create_parent_directories(file, cancellable)¶

Parameters:

file (Gio.File) – a file
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Raises:

GLib.Error

Returns:

whether the directories are correctly created. False is returned on error.

Return type:

bool

Synchronously creates parent directories of file, so that file can be saved.

New in version 5.0.

Tepl.utils_decode_uri(uri)¶

Parameters:

uri (str) – the uri to decode

Returns:

True if the uri could be properly decoded, False otherwise.

scheme:: return value pointer for the uri’s scheme (e.g. http, sftp, …), or None
user:: return value pointer for the uri user info, or None
host:: return value pointer for the uri host, or None
port:: return value pointer for the uri port, or None
path:: return value pointer for the uri path, or None

Return type:

(bool, scheme: str, user: str, host: str, port: str, path: str)

Parse and break an uri apart in its individual components like the uri scheme, user info, host, port and path. The return value pointer can be None to ignore certain parts of the uri. If the function returns True, then all return value pointers should be freed using GLib.free().

New in version 5.0.

Tepl.utils_file_query_exists_async(file, cancellable, callback, *user_data)¶

Parameters:

file (Gio.File) – a Gio.File.
cancellable (Gio.Cancellable or None) – a Gio.Cancellable.
callback (Gio.AsyncReadyCallback or None) – the callback to call when the operation is finished.
user_data (object or None) – the data to pass to the callback function.

The asynchronous version of Gio.File.query_exists(). When the operation is finished, callback will be called. You can then call Tepl.utils_file_query_exists_finish() to get the result of the operation.

New in version 5.0.

Tepl.utils_file_query_exists_finish(file, result)¶

Parameters:

file (Gio.File) – a Gio.File.
result (Gio.AsyncResult) – a Gio.AsyncResult.

Returns:

True if the file exists and the operation hasn’t been cancelled, False otherwise.

Return type:

bool

Finishes the operation started with Tepl.utils_file_query_exists_async(). There is no output GLib.Error parameter, so you should check if the operation has been cancelled (in which case False will be returned).

New in version 5.0.

Tepl.utils_get_file_extension(filename)¶

Parameters:: filename (str) – a filename.
Returns:: the filename's extension with the dot, in lowercase. Free with GLib.free().
Return type:: str

Examples:

“file.pdf” returns “.pdf”.
“file.PDF” returns “.pdf”.
“file.tar.gz” returns “.gz”.
“path/to/file.pdf” returns “.pdf”.
“file” (without an extension) returns “” (the empty string).

New in version 4.4.

Tepl.utils_get_file_shortname(filename)¶

Parameters:: filename (str) – a filename.
Returns:: the filename without its extension. Free with GLib.free().
Return type:: str

Returns filename without its extension. With the “extension” having the same definition as in Tepl.utils_get_file_extension(); in other words it returns the other part of filename.

New in version 4.4.

Tepl.utils_get_titled_component(title, component)¶

Parameters:

title (str) – the title.
component (Gtk.Widget) – a Gtk.Widget.

Returns:

a new widget containing the title above the component.

Return type:

Gtk.Widget

To add a title to a GUI component.

Useful for example in a Gtk.Dialog window, when there are several components, or logical groups.

The title will be in bold, left-aligned, and the component will have a left margin.

New in version 6.2.

Tepl.utils_list_box_clear(list_box)¶

Parameters:: list_box (Gtk.ListBox) – a Gtk.ListBox.

Removes all rows of list_box, to obtain an empty Gtk.ListBox.

New in version 6.0.

Tepl.utils_list_box_get_filtered_children(list_box, filter_func, *user_data)¶

Parameters:

list_box (Gtk.ListBox) – a Gtk.ListBox.
filter_func (Gtk.ListBoxFilterFunc) – non-None callback function.
user_data (object or None) – user data passed to filter_func.

Returns:

a None-terminated array of Gtk.ListBoxRow objects, or None. Free with GLib.free() when no longer needed.

n_filtered_children:: location to store the number of Gtk.ListBoxRow's present in the returned array, without counting the terminating None.

Return type:

([Gtk.ListBoxRow] or None, n_filtered_children: int)

Gets an array of all the Gtk.ListBoxRow childen of list_box for which filter_func returns True. The elements in the array are sorted by increasing index order (as returned by Gtk.ListBoxRow.get_index()).

New in version 6.0.

Tepl.utils_list_box_get_row_at_index_with_filter(list_box, index, filter_func, *user_data)¶

Parameters:

list_box (Gtk.ListBox) – a Gtk.ListBox.
index (int) – the index of the row, starting at 0. The index is among the filtered rows only.
filter_func (Gtk.ListBoxFilterFunc) – non-None callback function.
user_data (object or None) – user data passed to filter_func.

Returns:

the child Gtk.ListBoxRow or None.

Return type:

Gtk.ListBoxRow or None

This function has the same semantics as Gtk.ListBox.get_row_at_index(), but it takes into account only the rows for which filter_func returns True.

As an example, if index is 0, it returns the first Gtk.ListBoxRow for which filter_func returns True.

New in version 6.0.

Tepl.utils_list_box_scroll_to_row(list_box, row)¶

Parameters:

list_box (Gtk.ListBox) – a Gtk.ListBox.
row (Gtk.ListBoxRow) – a Gtk.ListBoxRow.

Scrolls to a specific Gtk.ListBoxRow.

Before using this function, Tepl.utils_list_box_setup_scrolling() must have been called.

New in version 6.0.

Tepl.utils_list_box_scroll_to_selected_row(list_box)¶

Parameters:: list_box (Gtk.ListBox) – a Gtk.ListBox.

Calls Tepl.utils_list_box_scroll_to_row() on the row returned by Gtk.ListBox.get_selected_row(). This function assumes that there is either zero or one selected row.

Before using this function, Tepl.utils_list_box_setup_scrolling() must have been called.

New in version 6.0.

Tepl.utils_list_box_setup_scrolling(list_box, scrolled_window)¶

Parameters:

list_box (Gtk.ListBox) – a Gtk.ListBox.
scrolled_window (Gtk.ScrolledWindow) – a Gtk.ScrolledWindow.

Setup vertical scrolling between list_box and scrolled_window, to be able to use Tepl.utils_list_box_scroll_to_row() afterwards.

This function is intended to be called only once per Gtk.ListBox, when initializing the list_box and scrolled_window widgets.

New in version 6.0.

Tepl.utils_markup_escape_text(src)¶

Parameters:: src (str) – a nul-terminated UTF-8 string.
Returns:: a newly allocated string with the escaped text, or None if src is not a valid UTF-8 string. Free with GLib.free() when no longer needed.
Return type:: str or None

The same as GLib.markup_escape_text(), but with an implementation that fully supports round-trip integrity. I.e. when GLib.MarkupParser or any other XML parser will decode/unescape the string, the exact same string as src will be brought back. As long as src is a valid UTF-8 string.

The other difference with GLib.markup_escape_text() is that the length parameter is not present for Tepl.utils_markup_escape_text().

GLib.markup_escape_text() doesn’t fully support round-trip integrity

In fact, GLib.markup_escape_text() doesn’t escape the tabstop, newline and carriage return characters. And the GLib.MarkupParser correctly processes whitespace and line endings according to the XML rules for normalization of line endings and attribute values.

For example "\t" (a tab) after a round-trip through GLib.markup_escape_text() and GLib.MarkupParser becomes a simple space.

New in version 5.0.

Tepl.utils_override_font_description(widget, font_desc)¶

Parameters:

widget (Gtk.Widget) – a Gtk.Widget.
font_desc (Pango.FontDescription or None) – the Pango.FontDescription to use, or None to undo the effect of previous calls to this function on widget.

A replacement for Gtk.Widget.override_font(). Because Gtk.Widget.override_font() is deprecated but was useful.

New in version 6.2.

Tepl.utils_override_font_string(widget, font_str)¶

Parameters:

widget (Gtk.Widget) – a Gtk.Widget.
font_str (str or None) – a string representation of a Pango.FontDescription, or None to undo the effect of previous calls to this function on widget.

A convenience function that calls Tepl.utils_override_font_description().

See Pango.FontDescription.from_string() for a description of the format of the string representation for font_str.

New in version 6.2.

Tepl.utils_replace_home_dir_with_tilde(filename)¶

Parameters:: filename (str) – the filename.
Returns:: the new filename. Free with GLib.free().
Return type:: str

Replaces the home directory with a tilde, if the home directory is present in the filename.

New in version 4.4.

Tepl.utils_setup_statusbar(statusbar)¶

Parameters:: statusbar (Gtk.Statusbar) – a Gtk.Statusbar.

To better configure a Gtk.Statusbar (to make it smaller).

New in version 6.8.

Tepl.utils_str_end_truncate(str, truncate_length)¶

Parameters:

str (str) – a UTF-8 string.
truncate_length (int) – truncate the string at that length, in UTF-8 characters (not bytes).

Returns:

the truncated string. Free with GLib.free().

Return type:

str

Like Tepl.utils_str_middle_truncate() but the “…” character is at the end.

New in version 4.4.

Tepl.utils_str_middle_truncate(str, truncate_length)¶

Parameters:

str (str) – a UTF-8 string.
truncate_length (int) – truncate the string at that length, in UTF-8 characters (not bytes).

Returns:

the truncated string. Free with GLib.free().

Return type:

str

If str is longer than truncate_length, then this function returns str truncated in the middle with a “…” character. Otherwise it just returns a copy of str.

New in version 4.4.

Tepl.utils_str_replace(string, search, replacement)¶

Parameters:

string (str) – a string
search (str) – the search string
replacement (str) – the replacement string

Returns:

A newly allocated string with the replacements. Free with GLib.free().

Return type:

str

Replaces all occurences of search by replacement.

The function does only one pass, for example:

tepl_utils_str_replace ("aaaa", "aa", "a");

returns “aa”, not “a”.

New in version 4.4.