## ThunarxRenamer

ThunarxRenamer — The abstract base class for bulk renamers

## Synopsis

    #include <thunarx/thunarx.h>

                        ThunarxRenamer;
                        ThunarxRenamerClass;
    const gchar*        thunarx_renamer_get_help_url        (ThunarxRenamer *renamer);
    void                thunarx_renamer_set_help_url        (ThunarxRenamer *renamer,
                                                             const gchar *help_url);
    const gchar*        thunarx_renamer_get_name            (ThunarxRenamer *renamer);
    void                thunarx_renamer_set_name            (ThunarxRenamer *renamer,
                                                             const gchar *name);
    gchar*              thunarx_renamer_process             (ThunarxRenamer *renamer,
                                                             ThunarxFileInfo *file,
                                                             const gchar *text,
                                                             guint index);
    void                thunarx_renamer_load                (ThunarxRenamer *renamer,
                                                             GHashTable *settings);
    void                thunarx_renamer_save                (ThunarxRenamer *renamer,
                                                             GHashTable *settings);
    GList*              thunarx_renamer_get_actions         (ThunarxRenamer *renamer,
                                                             GtkWindow *window,
                                                             GList *files);
    void                thunarx_renamer_changed             (ThunarxRenamer *renamer);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBox
                                     +----GtkVBox
                                           +----ThunarxRenamer

## Implemented Interfaces

ThunarxRenamer implements AtkImplementorIface and GtkBuildable.

## Properties

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

## Signals

      "changed"                                        : Run First

## 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.

## Details

### ThunarxRenamer

    typedef struct _ThunarxRenamer ThunarxRenamer;

Abstract base instance type for bulk renamers.

### ThunarxRenamerClass

    typedef struct {
      /* 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_actions) (ThunarxRenamer  *renamer,
                             GtkWindow       *window,
                             GList           *files);

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

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

`process` () | see `thunarx_renamer_process()`.
`load` () | see `thunarx_renamer_load()`.
`save` () | see `thunarx_renamer_save()`.
`get_actions` () | see `thunarx_renamer_get_actions()`.
`changed` () | see `thunarx_renamer_changed()`.

### 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.

`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.

`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()`.

`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()`.

`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.

`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()`.

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

    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()`.

`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_actions ()

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

Returns the list of GtkActions 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 actions for files in the bulk renamer dialog list.

The returned GtkActions 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 action "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 actions 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 actions may only work properly if only a single file ist 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 actions as usual, but make them insensitive, using:

    gtk_action_set_sensitive (action, FALSE);

The latter has the advantage that the user will still notice the existance of the action 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_foreach (list, (GFunc) g_object_unref, NULL);
    g_list_free (list);

As a special note, this method automatically takes a reference on the `renamer` for every GtkAction object returned from the real implementation of this method in `renamer`. This is to make sure that the extension stays in memory for atleast the time that the actions are used.

The GtkActions returned from this method must be namespaced with the module to avoid collision with internal file manager actions and actions provided by other extensions. For example, the menu action 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 GtkActions 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 action (which is likely to be the case in most situations).

`renamer` : | a ThunarxRenamer.
`window` : | a GtkWindow or `NULL`.
`files` : | a GList of ThunarxFileInfos.
Returns : | the list of GtkActions provided by `renamer` for the given list of `files`.

### 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.

`renamer` : | a ThunarxRenamer.

## Property Details

### The `"help-url"` property

      "help-url"                 gchar*                : Read / Write

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.

Default value: NULL

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

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.

Default value: NULL

## Signal Details

### The `"changed"` signal

    void                user_function                      (ThunarxRenamer *renamer,
                                                            gpointer        user_data)      : Run First

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.

`renamer` : | a ThunarxRenamer.
`user_data` : | user data set when the signal handler was connected.

## See Also

The description of the ThunarxRenamerProvider interface.