Thunar Extensions Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
#include <thunarx/thunarx.h> ThunarxRenamer; struct 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
);
GObject +----GInitiallyUnowned +----GtkObject +----GtkWidget +----GtkContainer +----GtkBox +----GtkVBox +----ThunarxRenamer
ThunarxRenamer implements AtkImplementorIface, GtkBuildable and GtkOrientable.
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 , button which opens a dialog with the additional settings.
typedef struct _ThunarxRenamer ThunarxRenamer;
Abstract base instance type for bulk renamers.
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_actions) (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.
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.
|
a ThunarxRenamer. |
Returns : |
the URL of the documentation for renamer . |
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.
|
a ThunarxRenamer. |
|
the new URL to the documentation of renamer . |
const gchar * thunarx_renamer_get_name (ThunarxRenamer *renamer
);
Returns the user visible name for renamer
, previously
set with thunarx_renamer_set_name()
.
|
a ThunarxRenamer. |
Returns : |
the user visible name for renamer . |
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()
.
|
a ThunarxRenamer. |
|
the new user visible name for renamer . |
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.
|
a ThunarxRenamer. |
|
the ThunarxFileInfo for the file whose new
name - according to renamer - should be
determined. |
|
the part of the filename to which the
renamer should be applied. |
Returns : |
the string with which to replace text . |
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()
.
|
a ThunarxRenamer. |
|
a GHashTable which contains the previously saved
settings for renamer as key/value pairs of strings. |
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()
.
|
a ThunarxRenamer. |
|
a GHashTable to which the current settings of renamer
should be stored as key/value pairs of strings. |
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).
|
a ThunarxRenamer. |
|
a GtkWindow or NULL . |
|
a GList of ThunarxFileInfos. |
Returns : |
the list of GtkActions provided by renamer
for the given list of files . |
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.
|
a ThunarxRenamer. |
"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
"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
"changed"
signalvoid 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.
|
a ThunarxRenamer. |
|
user data set when the signal handler was connected. |