ThunarxRenamer

ThunarxRenamer — The abstract base class for bulk renamers

Functions

Properties

gchar * help-url Read / Write
gchar * name Read / Write / Construct Only

Signals

void changed Run First

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ╰── GtkBox
                    ╰── ThunarxRenamer

Implemented Interfaces

ThunarxRenamer implements AtkImplementorIface, GtkBuildable and GtkOrientable.

Includes

#include <thunarx/thunarx.h>

Description

The abstract base class ThunarxRenamer is implemented by extensions which provide additional bulk renamers that should be used in the bulk rename dialog.

Derived classes must override the thunarx_renamer_process() method, which is called by the bulk rename dialog for every file to generate a new name. For example, the ThunarSbrReplaceRenamer class included in the thunar-sbr plugin (which is part of the Thunar distribution) provides a bulk renamer, named Search & Replace, which allows the user to rename multiple files by searching for a pattern in each file name and, if the pattern is found, replacing it with the specified replacement text.

The active ThunarxRenamers user interface is displayed in a frame below the file list, as shown in the screenshot above. Derived classes should try to limit the number of widgets displayed in the main user interface. For example, if you have more than six settings, you should consider adding an Advanced, button which opens a dialog with the additional settings.

Functions

thunarx_renamer_get_help_url ()

const gchar *
thunarx_renamer_get_help_url (ThunarxRenamer *renamer);

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

Parameters

renamer

a ThunarxRenamer.

 

Returns

the URL of the documentation for renamer .


thunarx_renamer_set_help_url ()

void
thunarx_renamer_set_help_url (ThunarxRenamer *renamer,
                              const gchar *help_url);

The URL to the documentation of this ThunarxRenamer. 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.

Parameters

renamer

a ThunarxRenamer.

 

help_url

the new URL to the documentation of renamer .

 

thunarx_renamer_get_name ()

const gchar *
thunarx_renamer_get_name (ThunarxRenamer *renamer);

Returns the user visible name for renamer , previously set with thunarx_renamer_set_name().

Parameters

renamer

a ThunarxRenamer.

 

Returns

the user visible name for renamer .


thunarx_renamer_set_name ()

void
thunarx_renamer_set_name (ThunarxRenamer *renamer,
                          const gchar *name);

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

Parameters

renamer

a ThunarxRenamer.

 

name

the new user visible name for renamer .

 

thunarx_renamer_process ()

gchar *
thunarx_renamer_process (ThunarxRenamer *renamer,
                         ThunarxFileInfo *file,
                         const gchar *text,
                         guint index);

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 g_free() when no longer needed.

Parameters

renamer

a ThunarxRenamer.

 

file

the ThunarxFileInfo for the file whose new name - according to renamer - should be determined.

 

text

the part of the filename to which the renamer should be applied.

 

index

the index of the file in the list, used for renamers that work on numbering.

 

Returns

the string with which to replace text .


thunarx_renamer_load ()

void
thunarx_renamer_load (ThunarxRenamer *renamer,
                      GHashTable *settings);

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

If you decide to override this method for your ThunarxRenamer implementation, you should also override thunarx_renamer_save().

Parameters

renamer

a ThunarxRenamer.

 

settings

a GHashTable which contains the previously saved settings for renamer as key/value pairs of strings.

 

thunarx_renamer_save ()

void
thunarx_renamer_save (ThunarxRenamer *renamer,
                      GHashTable *settings);

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 g_strdup(), both the keys and the values. For example to store the string Bar for the setting Foo, you'd use:

1
g_hash_table_replace (settings, g_strdup ("Foo"), g_strdup ("Bar"));

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

If you decide to override this method for your ThunarxRenamer implementation, you should also override thunarx_renamer_load().

Parameters

renamer

a ThunarxRenamer.

 

settings

a GHashTable to which the current settings of renamer should be stored as key/value pairs of strings.

 

thunarx_renamer_get_menu_items ()

GList *
thunarx_renamer_get_menu_items (ThunarxRenamer *renamer,
                                GtkWindow *window,
                                GList *files);

Returns the list of ThunarxMenuItems provided by renamer for the given list of files . By default, this method returns NULL (the empty list), but derived classes may override this method to provide additional items for files in the bulk renamer dialog list.

The returned ThunarxMenuItems 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 NULL), 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 ThunarxFileInfos 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_file_info_has_mime_type() of the ThunarxFileInfo 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 NULL here if files does not contain exactly one item, or you can return the menu items as usual, but make them insensitive, using:

1
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:

1
g_list_free_full (list, g_object_unref);

As a special note, this method automatically takes a reference on the renamer for every ThunarxMenuItem 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 ThunarxMenuItems 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 ThunarxMenuItems should be returned from extensions and the way they are used, read the description of the ThunarxMenuProvider 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 NULL, 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).

Parameters

renamer

a ThunarxRenamer.

 

window

a GtkWindow or NULL.

 

files

a GList of ThunarxFileInfos.

[element-type ThunarxFileInfo]

Returns

the list of ThunarxMenuItems provided by renamer for the given list of files .

[transfer full][element-type ThunarxMenuItem]


thunarx_renamer_changed ()

void
thunarx_renamer_changed (ThunarxRenamer *renamer);

This method should be used by derived classes to emit the "changed" signal for renamer . See the documentation of the "changed" signal for details.

Parameters

renamer

a ThunarxRenamer.

 

Types and Values

struct ThunarxRenamer

struct ThunarxRenamer;

struct ThunarxRenamerClass

struct ThunarxRenamerClass {
  /* virtual methods */
  gchar *(*process)        (ThunarxRenamer  *renamer,
                            ThunarxFileInfo *file,
                            const gchar     *text,
                            guint            index);

  void   (*load)           (ThunarxRenamer  *renamer,
                            GHashTable      *settings);
  void   (*save)           (ThunarxRenamer  *renamer,
                            GHashTable      *settings);

  GList *(*get_menu_items) (ThunarxRenamer  *renamer,
                            GtkWindow       *window,
                            GList           *files);

  /* signals */
  void (*changed) (ThunarxRenamer *renamer);
};

Abstract base class with virtual methods implemented by extensions that provide additional bulk renamers for the integrated bulk rename module in Thunar.

Members

process ()

see thunarx_renamer_process().

 

load ()

see thunarx_renamer_load().

 

save ()

see thunarx_renamer_save().

 

get_menu_items ()

see thunarx_renamer_get_menu_items().

 

changed ()

see thunarx_renamer_changed().

 

Property Details

The “help-url” property

  “help-url”                 gchar *

The URL to the documentation of this ThunarxRenamer. 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.

Owner: ThunarxRenamer

Flags: Read / Write

Default value: NULL


The “name” property

  “name”                     gchar *

The user visible name of the renamer, that is displayed in the bulk rename dialog of the file manager. Derived classes should set a useful name.

Owner: ThunarxRenamer

Flags: Read / Write / Construct Only

Default value: NULL

Signal Details

The “changed” signal

void
user_function (ThunarxRenamer *renamer,
               gpointer        user_data)

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.

Parameters

renamer

a ThunarxRenamer.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First