Thunarx.Renamer¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Box (14), Gtk.Container (35), Gtk.Widget (278), GObject.Object (37), Gtk.Buildable (10), Gtk.Orientable (2)
Structs:: Gtk.ContainerClass (5), Gtk.WidgetClass (12), GObject.ObjectClass (5)

	`changed` ()
	`get_help_url` ()
	`get_menu_items` (window, files)
	`get_name` ()
	`load` (settings)
	`process` (file, text, index)
	`save` (settings)
	`set_help_url` (help_url)
	`set_name` (name)

Virtual Methods¶

Inherited:: Gtk.Container (10), Gtk.Widget (82), GObject.Object (7), Gtk.Buildable (10)

	`do_changed` ()
	`do_get_menu_items` (window, files)
	`do_load` (settings)
	`do_process` (file, text, index)
	`do_save` (settings)

Properties¶

Inherited:: Gtk.Box (3), Gtk.Container (3), Gtk.Widget (39), Gtk.Orientable (1)

Name	Type	Flags	Short Description
`help-url`	`str`	r/w	The URL to the documentation of the renamer

Child Properties¶

Inherited:: Gtk.Box (5)

Style Properties¶

Inherited:: Gtk.Widget (17)

Signals¶

Inherited:: Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)

Name	Short Description
`changed`	Derived classes should emit this signal using the `Thunarx.Renamer.changed`() method whenever the user changed a setting in the renamer GUI.

Fields¶

Inherited:: Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)

Class Details¶

class Thunarx.Renamer(*args, **kwargs)¶

Bases:: Gtk.Box
Abstract:: Yes
Structure:: Thunarx.RenamerClass

changed()¶: This method should be used by derived classes to emit the “changed” signal for self. See the documentation of the “changed” signal for details.

get_help_url()¶

Returns:: the URL of the documentation for self.
Return type:: str

Returns the URL of the documentation for self or None if no specific documentation is available for self and the general documentation of the Thunar renamers should be displayed instead.

get_menu_items(window, files)¶

Parameters:

window (Gtk.Window) – a Gtk.Window or None.
files ([Thunarx.FileInfo]) – a GLib.List of Thunarx.FileInfo<!—->s.

Returns:

the list of Thunarx.MenuItem<!—->s provided by self for the given list of files.

Return type:

[Thunarx.MenuItem]

Returns the list of Thunarx.MenuItem<!—->s provided by self for the given list of files. By default, this method returns None (the empty list), but derived classes may override this method to provide additional items for files in the bulk renamer dialog list.

The returned Thunarx.MenuItem<!—->s will be displayed in the file’s context menu of the bulk renamer dialog, when this self is active. For example, an ID3-Tag based renamer may add an menu item “Edit Tags” to the context menus of supported media files and, when activated, display a dialog (which should be transient and modal for window, if not None), which allows the users to edit media file tags on-the-fly.

Derived classes that override this method should always check first if all the Thunarx.FileInfo<!—->s in the list of files are supported, and only return menu items that can be performed on this specific list of files. For example, the ID3-Tag renamer mentioned above, should first check whether all items in files are actually audio files. The Thunarx.FileInfo.has_mime_type() of the Thunarx.FileInfo interface can be used to easily test whether a file in the files list is of a certain MIME type.

Some menu items may only work properly if only a single file is selected (for example, the ID3-Tag renamer will probably only supporting editing one file at a time). In this case you have basicly two options: Either you can return None here if files does not contain exactly one item, or you can return the menu items as usual, but make them insensitive, using:

thunarx_menu_item_set_sensitive (item, FALSE); The latter has the advantage that the user will still notice the existance of the menu item and probably realize that it can only be applied to a single item at once.

The caller is responsible to free the returned list using something like the following:

g_list_free_full (list, g_object_unref); As a special note, this method automatically takes a reference on the self for every Thunarx.MenuItem object returned from the real implementation of this method in self. This is to make sure that the extension stays in memory for at least the time that the menu items are used.

The name of Thunarx.MenuItem<!—->s returned from this method must be namespaced with the module to avoid collision with internal file manager menu items and menu items provided by other extensions. For example, the menu item provided by the ID3-Tag renamer mentioned above, should be named TagRenamer::edit-tags (if TagRenamer is the class name). For additional information about the way Thunarx.MenuItem<!—->s should be returned from extensions and the way they are used, read the description of the Thunarx.MenuProvider interface or read the introduction provided with this reference manual.

A note of warning concerning the window parameter. Plugins should avoid taking a reference on window, as that might introduce a circular reference and can thereby cause a quite large memory leak. Instead, if window is not None, add a weak reference using the g_object_weak_ref() or g_object_add_weak_pointer() method. But don’t forget to release the weak reference if window survived the lifetime of your menu item (which is likely to be the case in most situations).

get_name()¶

Returns:: the user visible name for self.
Return type:: str

Returns the user visible name for self, previously set with Thunarx.Renamer.set_name().

load(settings)¶

Parameters:: settings ({object: object}) – a GLib.HashTable which contains the previously saved settings for self as key/value pairs of strings.

Tells self to load its internal settings from the specified settings. The settings hash table contains previously saved settings, see Thunarx.Renamer.save(), as key/value pairs of strings. That is, both the keys and the values are strings.

Implementations of Thunarx.Renamer may decide to override this method to perform custom loading of settings. If you do not override this method, the default method of Thunarx.Renamer will be used, which simply loads all GObject.Object properties provided by self<!—->s class (excluding the ones provided by the parent classes) from the settings. The GObject.Object properties must be transformable to strings and from strings.

If you decide to override this method for your Thunarx.Renamer implementation, you should also override Thunarx.Renamer.save().

process(file, text, index)¶

Parameters:

file (Thunarx.FileInfo) – the Thunarx.FileInfo for the file whose new name - according to self - should be determined.
text (str) – the part of the filename to which the self should be applied.
index (int) – the index of the file in the list, used for renamers that work on numbering.

Returns:

the string with which to replace text.

Return type:

str

Determines the replacement for text (which is the relevant part of the full file name, i.e. either the suffix, the name or the name and the suffix).

The caller is responsible to free the returned string using GLib.free() when no longer needed.

save(settings)¶

Parameters:: settings ({object: object}) – a GLib.HashTable to which the current settings of self should be stored as key/value pairs of strings.

Tells self to save its internal settings to the specified settings, which can afterwards be loaded by Thunarx.Renamer.load().

The strings saved to settings must be allocated by GLib.strdup(), both the keys and the values. For example to store the string Bar for the setting Foo, you’d use: g_hash_table_replace (settings, g_strdup ("Foo"), g_strdup ("Bar"));

Implementations of Thunarx.Renamer may decide to override this method to perform custom saving of settings. If you do not overrride this method, the default method of Thunarx.Renamer will be used, which simply stores all GObject.Object properties provided by the self<!—->s class (excluding the ones provided by the parent classes) to the settings. The GObject.Object properties must be transformable to strings.

If you decide to override this method for your Thunarx.Renamer implementation, you should also override Thunarx.Renamer.load().

set_help_url(help_url)¶

Parameters:: help_url (str) – the new URL to the documentation of self.

The URL to the documentation of this Thunarx.Renamer. Derived classes can set this property to point to the documentation for the specific renamer. The documentation of the specific renamer in turn should contain a link to the general Thunar renamer documentation.

May also be unset, in which case the general Thunar renamer documentation will be shown when the user clicks the “Help” button.

set_name(name)¶

Parameters:: name (str) – the new user visible name for self.

Sets the user visible name for self to name. This method should only be called by derived classes and prior to returning the self is returned from thunarx_renamer_provider_get_renamers().

do_changed() virtual¶: This method should be used by derived classes to emit the “changed” signal for renamer. See the documentation of the “changed” signal for details.

do_get_menu_items(window, files) virtual¶

Parameters:

window (Gtk.Window) – a Gtk.Window or None.
files ([Thunarx.FileInfo]) – a GLib.List of Thunarx.FileInfo<!—->s.

Returns:

the list of Thunarx.MenuItem<!—->s provided by renamer for the given list of files.

Return type:

[Thunarx.MenuItem]

Returns the list of Thunarx.MenuItem<!—->s provided by renamer for the given list of files. By default, this method returns None (the empty list), but derived classes may override this method to provide additional items for files in the bulk renamer dialog list.

The returned Thunarx.MenuItem<!—->s will be displayed in the file’s context menu of the bulk renamer dialog, when this renamer is active. For example, an ID3-Tag based renamer may add an menu item “Edit Tags” to the context menus of supported media files and, when activated, display a dialog (which should be transient and modal for window, if not None), which allows the users to edit media file tags on-the-fly.

Derived classes that override this method should always check first if all the Thunarx.FileInfo<!—->s in the list of files are supported, and only return menu items that can be performed on this specific list of files. For example, the ID3-Tag renamer mentioned above, should first check whether all items in files are actually audio files. The Thunarx.FileInfo.has_mime_type() of the Thunarx.FileInfo interface can be used to easily test whether a file in the files list is of a certain MIME type.

Some menu items may only work properly if only a single file is selected (for example, the ID3-Tag renamer will probably only supporting editing one file at a time). In this case you have basicly two options: Either you can return None here if files does not contain exactly one item, or you can return the menu items as usual, but make them insensitive, using:

thunarx_menu_item_set_sensitive (item, FALSE); The latter has the advantage that the user will still notice the existance of the menu item and probably realize that it can only be applied to a single item at once.

The caller is responsible to free the returned list using something like the following:

g_list_free_full (list, g_object_unref); As a special note, this method automatically takes a reference on the renamer for every Thunarx.MenuItem object returned from the real implementation of this method in renamer. This is to make sure that the extension stays in memory for at least the time that the menu items are used.

The name of Thunarx.MenuItem<!—->s returned from this method must be namespaced with the module to avoid collision with internal file manager menu items and menu items provided by other extensions. For example, the menu item provided by the ID3-Tag renamer mentioned above, should be named TagRenamer::edit-tags (if TagRenamer is the class name). For additional information about the way Thunarx.MenuItem<!—->s should be returned from extensions and the way they are used, read the description of the Thunarx.MenuProvider interface or read the introduction provided with this reference manual.

A note of warning concerning the window parameter. Plugins should avoid taking a reference on window, as that might introduce a circular reference and can thereby cause a quite large memory leak. Instead, if window is not None, add a weak reference using the g_object_weak_ref() or g_object_add_weak_pointer() method. But don’t forget to release the weak reference if window survived the lifetime of your menu item (which is likely to be the case in most situations).

do_load(settings) virtual¶

Parameters:: settings ({object: object}) – a GLib.HashTable which contains the previously saved settings for renamer as key/value pairs of strings.

Tells renamer to load its internal settings from the specified settings. The settings hash table contains previously saved settings, see Thunarx.Renamer.save(), as key/value pairs of strings. That is, both the keys and the values are strings.

Implementations of Thunarx.Renamer may decide to override this method to perform custom loading of settings. If you do not override this method, the default method of Thunarx.Renamer will be used, which simply loads all GObject.Object properties provided by renamer<!—->s class (excluding the ones provided by the parent classes) from the settings. The GObject.Object properties must be transformable to strings and from strings.

If you decide to override this method for your Thunarx.Renamer implementation, you should also override Thunarx.Renamer.save().

do_process(file, text, index) virtual¶

Parameters:

file (Thunarx.FileInfo) – the Thunarx.FileInfo for the file whose new name - according to renamer - should be determined.
text (str) – the part of the filename to which the renamer should be applied.
index (int) – the index of the file in the list, used for renamers that work on numbering.

Returns:

the string with which to replace text.

Return type:

str

Determines the replacement for text (which is the relevant part of the full file name, i.e. either the suffix, the name or the name and the suffix).

The caller is responsible to free the returned string using GLib.free() when no longer needed.

do_save(settings) virtual¶

Parameters:: settings ({object: object}) – a GLib.HashTable to which the current settings of renamer should be stored as key/value pairs of strings.

Tells renamer to save its internal settings to the specified settings, which can afterwards be loaded by Thunarx.Renamer.load().

The strings saved to settings must be allocated by GLib.strdup(), both the keys and the values. For example to store the string Bar for the setting Foo, you’d use: g_hash_table_replace (settings, g_strdup ("Foo"), g_strdup ("Bar"));

Implementations of Thunarx.Renamer may decide to override this method to perform custom saving of settings. If you do not overrride this method, the default method of Thunarx.Renamer will be used, which simply stores all GObject.Object properties provided by the renamer<!—->s class (excluding the ones provided by the parent classes) to the settings. The GObject.Object properties must be transformable to strings.

If you decide to override this method for your Thunarx.Renamer implementation, you should also override Thunarx.Renamer.load().

Signal Details¶

Thunarx.Renamer.signals.changed(renamer)¶

Signal Name:: changed
Flags:: RUN_FIRST
Parameters:: renamer (Thunarx.Renamer) – The object which received the signal

Derived classes should emit this signal using the Thunarx.Renamer.changed() method whenever the user changed a setting in the renamer GUI.

The file manager will then invoke Thunarx.Renamer.process() for all files that should be renamed and update the preview.

Property Details¶

Thunarx.Renamer.props.help_url¶

Name:: help-url
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

The URL to the documentation of this Thunarx.Renamer. Derived classes can set this property to point to the documentation for the specific renamer. The documentation of the specific renamer in turn should contain a link to the general Thunar renamer documentation.

May also be unset, in which case the general Thunar renamer documentation will be shown when the user clicks the “Help” button.