diff options
author | Romain B <skunnyk@alteroot.org> | 2017-09-17 17:18:24 +0200 |
---|---|---|
committer | Andre Miranda <andreldm@xfce.org> | 2017-09-17 21:23:03 -0300 |
commit | a44af0f35ba58a5580cf9efb84d1716369b923f8 (patch) | |
tree | 0509896ab3e57f7fc9e6c650a2bb8ba973ae1fe5 /docs | |
parent | 4f8037f2c7a4f953f3f2ce3f869f5fc84efc1c67 (diff) | |
download | thunar-a44af0f35ba58a5580cf9efb84d1716369b923f8.tar.gz |
Better documentation for thunarx
- Get ride of sgml template, use xml
- Update thunar website
- Next commit will migrate all documentation inside c-source for better gtk-doc processing
Diffstat (limited to 'docs')
-rw-r--r-- | docs/reference/thunarx/Makefile.am | 2 | ||||
-rw-r--r-- | docs/reference/thunarx/thunarx-docs.xml (renamed from docs/reference/thunarx/thunarx-docs.sgml) | 6 | ||||
-rw-r--r-- | docs/reference/thunarx/tmpl/thunarx-file-info.sgml | 195 | ||||
-rw-r--r-- | docs/reference/thunarx/tmpl/thunarx-menu-provider.sgml | 159 | ||||
-rw-r--r-- | docs/reference/thunarx/tmpl/thunarx-preferences-provider.sgml | 117 | ||||
-rw-r--r-- | docs/reference/thunarx/tmpl/thunarx-property-page-provider.sgml | 50 | ||||
-rw-r--r-- | docs/reference/thunarx/tmpl/thunarx-property-page.sgml | 337 | ||||
-rw-r--r-- | docs/reference/thunarx/tmpl/thunarx-provider-factory.sgml | 50 | ||||
-rw-r--r-- | docs/reference/thunarx/tmpl/thunarx-provider-plugin.sgml | 262 | ||||
-rw-r--r-- | docs/reference/thunarx/tmpl/thunarx-renamer-provider.sgml | 48 | ||||
-rw-r--r-- | docs/reference/thunarx/tmpl/thunarx-renamer.sgml | 169 | ||||
-rw-r--r-- | docs/reference/thunarx/tmpl/thunarx-version-information.sgml | 99 |
12 files changed, 4 insertions, 1490 deletions
diff --git a/docs/reference/thunarx/Makefile.am b/docs/reference/thunarx/Makefile.am index 3ffc3ad3..16f61426 100644 --- a/docs/reference/thunarx/Makefile.am +++ b/docs/reference/thunarx/Makefile.am @@ -4,7 +4,7 @@ AUTOMAKE_OPTIONS = 1.8 DOC_MODULE=thunarx # The top-level SGML file. -DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml +DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml # Extra options to supply to gtkdoc-scan SCAN_OPTIONS=--deprecated-guards="EXO_DISABLE_DEPRECATED" diff --git a/docs/reference/thunarx/thunarx-docs.sgml b/docs/reference/thunarx/thunarx-docs.xml index 518213b7..0d6cc095 100644 --- a/docs/reference/thunarx/thunarx-docs.sgml +++ b/docs/reference/thunarx/thunarx-docs.xml @@ -14,7 +14,7 @@ <!ENTITY thunarx-version-information SYSTEM "xml/thunarx-version-information.xml"> <!ENTITY version SYSTEM "version.xml"> -<!ENTITY date "January 2010"> +<!ENTITY date "2017"> ]> <book id="index"> @@ -71,7 +71,7 @@ <para> The Thunar Extension Framework (<systemitem class="library">thunarx</systemitem>) provides developers with an easy way to extend the basic functionality provided by - the <ulink type="http" url="http://thunar.xfce.org/">Thunar File Manager</ulink>. + the <ulink type="http" url="https://docs.xfce.org/xfce/thunar/start/">Thunar File Manager</ulink>. The <systemitem class="library">thunarx</systemitem> library includes interfaces that can be implemented by extensions for various purposes. </para> @@ -136,7 +136,7 @@ <para> This section explains the basic steps required to write an extension for the <ulink type="http" - url="http://thunar.xfce.org">Thunar File Manager</ulink> using the C language interface. It is + url="https://docs.xfce.org/xfce/thunar/start">Thunar File Manager</ulink> using the C language interface. It is just a short introduction and not meant to provide extensive details about the internal workings of the file manager. </para> diff --git a/docs/reference/thunarx/tmpl/thunarx-file-info.sgml b/docs/reference/thunarx/tmpl/thunarx-file-info.sgml deleted file mode 100644 index 410a6cf9..00000000 --- a/docs/reference/thunarx/tmpl/thunarx-file-info.sgml +++ /dev/null @@ -1,195 +0,0 @@ -<!-- ##### SECTION Title ##### --> -ThunarxFileInfo - -<!-- ##### SECTION Short_Description ##### --> -Abstraction of a file handled within the file manager - -<!-- ##### SECTION Long_Description ##### --> -<para> - The <interface>ThunarxFileInfo</interface> interface provides extensions with - a way to access information about a file handled within the file manager. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> -Stable - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT ThunarxFileInfoIface ##### --> -<para> - Interface with virtual methods implemented by the file manager and accessible - from the extensions. -</para> - -@get_name: See thunarx_file_info_get_name(). -@get_uri: See thunarx_file_info_get_uri(). -@get_parent_uri: See thunarx_file_info_get_parent_uri(). -@get_uri_scheme: See thunarx_file_info_get_uri_scheme(). -@get_mime_type: See thunarx_file_info_get_mime_type(). -@has_mime_type: See thunarx_file_info_has_mime_type(). -@is_directory: See thunarx_file_info_is_directory(). -@get_file_info: See thunarx_file_info_get_file_info(). -@get_filesystem_info: See thunarx_filesystem_info_get_filesystem_info(). -@get_location: See thunarx_location_get_location(). -@changed: See thunarx_file_info_changed(). -@renamed: See thunarx_file_info_renamed(). - -<!-- ##### STRUCT ThunarxFileInfo ##### --> -<para> - File info type, which is mapped to the real file info implementation - within the file manager. -</para> - - -<!-- ##### SIGNAL ThunarxFileInfo::changed ##### --> -<para> - -</para> - -@thunarxfileinfo: the object which received the signal. - -<!-- ##### SIGNAL ThunarxFileInfo::renamed ##### --> -<para> - -</para> - -@thunarxfileinfo: the object which received the signal. - -<!-- ##### FUNCTION thunarx_file_info_get_name ##### --> -<para> - -</para> - -@file_info: -@Returns: - - -<!-- ##### FUNCTION thunarx_file_info_get_uri ##### --> -<para> - -</para> - -@file_info: -@Returns: - - -<!-- ##### FUNCTION thunarx_file_info_get_parent_uri ##### --> -<para> - -</para> - -@file_info: -@Returns: - - -<!-- ##### FUNCTION thunarx_file_info_get_uri_scheme ##### --> -<para> - -</para> - -@file_info: -@Returns: - - -<!-- ##### FUNCTION thunarx_file_info_get_mime_type ##### --> -<para> - -</para> - -@file_info: -@Returns: - - -<!-- ##### FUNCTION thunarx_file_info_has_mime_type ##### --> -<para> - -</para> - -@file_info: -@mime_type: -@Returns: - - -<!-- ##### FUNCTION thunarx_file_info_is_directory ##### --> -<para> - -</para> - -@file_info: -@Returns: - - -<!-- ##### FUNCTION thunarx_file_info_get_file_info ##### --> -<para> - -</para> - -@file_info: -@Returns: - - -<!-- ##### FUNCTION thunarx_file_info_get_filesystem_info ##### --> -<para> - -</para> - -@file_info: -@Returns: - - -<!-- ##### FUNCTION thunarx_file_info_get_location ##### --> -<para> - -</para> - -@file_info: -@Returns: - - -<!-- ##### FUNCTION thunarx_file_info_changed ##### --> -<para> - -</para> - -@file_info: - - -<!-- ##### FUNCTION thunarx_file_info_renamed ##### --> -<para> - -</para> - -@file_info: - - -<!-- ##### MACRO THUNARX_TYPE_FILE_INFO_LIST ##### --> -<para> - The #GType for a boxed type holding a #GList of #ThunarxFileInfo<!---->s. - See thunarx_file_info_list_copy() and thunarx_file_info_list_free(). -</para> - - - -<!-- ##### FUNCTION thunarx_file_info_list_copy ##### --> -<para> - -</para> - -@file_infos: -@Returns: - - -<!-- ##### FUNCTION thunarx_file_info_list_free ##### --> -<para> - -</para> - -@file_infos: - - diff --git a/docs/reference/thunarx/tmpl/thunarx-menu-provider.sgml b/docs/reference/thunarx/tmpl/thunarx-menu-provider.sgml deleted file mode 100644 index b294fcb9..00000000 --- a/docs/reference/thunarx/tmpl/thunarx-menu-provider.sgml +++ /dev/null @@ -1,159 +0,0 @@ -<!-- ##### SECTION Title ##### --> -ThunarxMenuProvider - -<!-- ##### SECTION Short_Description ##### --> -The interface to extensions that provide additional menu items - -<!-- ##### SECTION Long_Description ##### --> -<para> - The <interface>ThunarxMenuProvider</interface> interface is implemented by - extensions which provide additional menu items that should be displayed in - the file or folder context menus for certain types of files. -</para> - -<para> - Extensions that implement this interface should do its best to respond as - fast as possible to method invokations by the file manager. That said, when - the file manager calls the thunarx_menu_provider_get_file_actions() or the - thunarx_menu_provider_get_folder_actions() method, the implementation in the - extension should use only the thunarx_file_info_has_mime_type() and - thunarx_file_info_is_directory() methods to determine the actions that should - be added to the file manager's context menu. Don't perform any complicated I/O - to determine the action list, as that would block the whole file manager process. -</para> - -<para> - The <link linkend="GtkAction">GtkAction</link>s returned from the - thunarx_menu_provider_get_file_actions() and thunarx_menu_provider_get_folder_actions() - methods 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 <systemitem class="library">ThunarOpenTerminal</systemitem> extension should be - called <literal>ThunarOpenTerminal::open-terminal</literal>. -</para> - -<example> - <title>Menu provider example</title> - - <programlisting> -static void hello_menu_provider_init (ThunarxMenuProviderIface *iface); -static GList *hello_get_file_actions (ThunarxMenuProvider *provider, - GtkWidget *window, - GList *files); - -THUNARX_DEFINE_TYPE_WITH_CODE (Hello, hello, G_TYPE_OBJECT, - THUNARX_IMPLEMENT_INTERFACE (THUNARX_TYPE_MENU_PROVIDER, - hello_menu_provider_init)); - -static void -hello_menu_provider_init (ThunarxMenuProviderIface *iface) -{ - iface->get_file_actions = hello_get_file_actions; -} - -static void -hello_activated (GtkWidget *window) -{ - GtkWidget *dialog; - - dialog = gtk_message_dialog_new (GTK_WINDOW (window), - GTK_DIALOG_MODAL - | GTK_DIALOG_DESTROY_WITH_PARENT, - GTK_MESSAGE_INFO, - GTK_BUTTONS_OK, - "Hello World!"); - gtk_dialog_run (GTK_DIALOG (dialog)); - gtk_widget_destroy (dialog); -} - -static GList* -hello_get_file_actions (ThunarxMenuProvider *provider, - GtkWidget *window, - GList *files) -{ - GtkAction *action; - GClosure *closure; - - action = gtk_action_new ("Hello::say-hello", "Say hello", "Say hello", NULL); - closure = g_cclosure_new_object_swap (G_CALLBACK (hello_activated), G_OBJECT (window)); - g_signal_connect_closure (G_OBJECT (action), "activate", closure, TRUE); - - return g_list_append (NULL, action); -}</programlisting> - - <para> - The above example will add an item <guimenu><guimenuitem>Say hello</guimenuitem></guimenu> - to the file context menus as shown in the picture below: - </para> - - <para> - <inlinegraphic fileref="say-hello.png" format="PNG" /> - </para> -</example> - -<!-- ##### SECTION See_Also ##### --> -<para> - The description of the <link linkend="ThunarxFileInfo">ThunarxFileInfo</link> - interface. -</para> - -<!-- ##### SECTION Stability_Level ##### --> -Stable - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT ThunarxMenuProviderIface ##### --> -<para> - Interface with virtual methods implemented by extensions that provide - additional menu items for the file manager's context menus. -</para> - -<para> - Providers don't need to implement all of the virtual methods listed in - the interface. -</para> - -@get_file_actions: See thunarx_menu_provider_get_file_actions(). -@get_folder_actions: See thunarx_menu_provider_get_folder_actions(). -@get_dnd_actions: See thunarx_menu_provider_get_dnd_actions(). - -<!-- ##### STRUCT ThunarxMenuProvider ##### --> -<para> - Menu provider type. -</para> - - -<!-- ##### FUNCTION thunarx_menu_provider_get_file_actions ##### --> -<para> - -</para> - -@provider: -@window: -@files: -@Returns: - - -<!-- ##### FUNCTION thunarx_menu_provider_get_folder_actions ##### --> -<para> - -</para> - -@provider: -@window: -@folder: -@Returns: - - -<!-- ##### FUNCTION thunarx_menu_provider_get_dnd_actions ##### --> -<para> - -</para> - -@provider: -@window: -@folder: -@files: -@Returns: - - diff --git a/docs/reference/thunarx/tmpl/thunarx-preferences-provider.sgml b/docs/reference/thunarx/tmpl/thunarx-preferences-provider.sgml deleted file mode 100644 index 8514b69a..00000000 --- a/docs/reference/thunarx/tmpl/thunarx-preferences-provider.sgml +++ /dev/null @@ -1,117 +0,0 @@ -<!-- ##### SECTION Title ##### --> -ThunarxPreferencesProvider - -<!-- ##### SECTION Short_Description ##### --> -The interface to extensions that provide preferences - -<!-- ##### SECTION Long_Description ##### --> -<para> - The ThunarxPreferencesProvider interface is implemented by extensions that - want to register additional actions in the preferences menu of the file - manager. In general this should only be done by extensions that are closely - tied to the file manager (for example, the <literal>thunar-uca</literal> is - such an extension, while an extension that just adds <guimenuitem>Compress - file</guimenuitem> and <guimenuitem>Uncompress file</guimenuitem> to the - context menu of compressed files should not add their own preferences to - the file manager menu, because it should use desktop-wide settings for - archive managers instead). -</para> - -<para> - The <link linkend="GtkAction"><type>GtkAction</type></link>s returned from the - thunarx_preferences_provider_get_actions() method must be namespaced with the - model to avoid collision with internal file manager actions and actions provided - by other extensions. For example, the preferences action provided by the - <literal>thunar-uca</literal> extension is called - <literal>ThunarUca::manage-actions</literal>. -</para> - -<example> - <title>Preferences provider example</title> - - <programlisting> -static void hello_preferences_provider_init (ThunarxPreferencesProviderIface *iface); -static void hello_get_actions (ThunarxPreferencesProvider *provider, - GtkWidget *window); - -THUNARX_DEFINE_TYPE_WITH_CODE (Hello, hello, G_TYPE_OBJECT, - THUNARX_IMPLEMENT_INTERFACE (THUNARX_TYPE_PREFERENCES_PROVIDER, - hello_preferences_provider_init)); - -static void -hello_preferences_provider_init (ThunarxPreferencesProviderIface *iface) -{ - iface->get_actions = hello_get_actions; -} - -static void -hello_activated (GtkWidget *window) -{ - GtkWidget *dialog; - - dialog = gtk_message_dialog_new (GTK_WINDOW (window), - GTK_DIALOG_MODAL - | GTK_DIALOG_DESTROY_WITH_PARENT, - GTK_MESSAGE_INFO, - GTK_BUTTONS_OK, - "Hello World!"); - gtk_dialog_run (GTK_DIALOG (dialog)); - gtk_widget_destroy (dialog); -} - -static GList* -hello_get_actions (ThunarxPreferencesProvider *provider, - GtkWidget *window) -{ - GtkAction *action; - GClosure *closure; - - action = gtk_action_new ("Hello::say-hello", "Say hello", "Say hello", NULL); - closure = g_cclosure_new_object_swap (G_CALLBACK (hello_activated), G_OBJECT (window)); - g_signal_connect_closure (G_OBJECT (action), "activate", closure, TRUE); - - return g_list_prepend (NULL, action); -} - </programlisting> -</example> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> -Stable - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT ThunarxPreferencesProviderIface ##### --> -<para> - Interface with virtual methods implementation by extensions that - want to install preferences actions in the file managers menu. -</para> - -<para> - Providers don't need to implement all of the virtual methods listed - in the interface. -</para> - -@get_actions: See thunarx_preferences_provider_get_actions(). - -<!-- ##### STRUCT ThunarxPreferencesProvider ##### --> -<para> - Preferences provider type. -</para> - - -<!-- ##### FUNCTION thunarx_preferences_provider_get_actions ##### --> -<para> - -</para> - -@provider: -@window: -@Returns: - - diff --git a/docs/reference/thunarx/tmpl/thunarx-property-page-provider.sgml b/docs/reference/thunarx/tmpl/thunarx-property-page-provider.sgml deleted file mode 100644 index 0a6339fb..00000000 --- a/docs/reference/thunarx/tmpl/thunarx-property-page-provider.sgml +++ /dev/null @@ -1,50 +0,0 @@ -<!-- ##### SECTION Title ##### --> -ThunarxPropertyPageProvider - -<!-- ##### SECTION Short_Description ##### --> -The interface to extensions that provide additional property pages - -<!-- ##### SECTION Long_Description ##### --> -<para> - To add a property page to the file properties dialog, extensions must implement the - <type>ThunarxPropertyPageProvider</type> interface. This interface has only one virtual - method, <function>get_pages</function>, that is passed a list of <link - linkend="ThunarxFileInfo"><type>ThunarxFileInfo</type></link> objects and returns a list - of <link linkend="ThunarxPropertyPage"><type>ThunarxPropertyPage</type></link> objects. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - The description of the <link linkend="ThunarxPropertyPage"><type>ThunarxPropertyPage</type></link> class. -</para> - -<!-- ##### SECTION Stability_Level ##### --> -Stable - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT ThunarxPropertyPageProvider ##### --> -<para> - Property page provider type. -</para> - - -<!-- ##### STRUCT ThunarxPropertyPageProviderIface ##### --> -<para> - Interface with virtual methods implemented by extensions that provide - additional pages for the file properties dialog. -</para> - -@get_pages: see thunarx_property_page_provider_get_pages(). - -<!-- ##### FUNCTION thunarx_property_page_provider_get_pages ##### --> -<para> - -</para> - -@provider: -@files: -@Returns: - - diff --git a/docs/reference/thunarx/tmpl/thunarx-property-page.sgml b/docs/reference/thunarx/tmpl/thunarx-property-page.sgml deleted file mode 100644 index 53bc1618..00000000 --- a/docs/reference/thunarx/tmpl/thunarx-property-page.sgml +++ /dev/null @@ -1,337 +0,0 @@ -<!-- ##### SECTION Title ##### --> -ThunarxPropertyPage - -<!-- ##### SECTION Short_Description ##### --> -The base class for pages added to the properties dialog - -<!-- ##### SECTION Long_Description ##### --> -<para> - The class for pages that can be added to Thunar's file properties dialog - by extensions implementing the #ThunarxPropertyPageProvider interface. The - pages returned by extensions from thunarx_property_page_provider_get_pages() - method are instances of this class or a derived class. Note that extensions - do not need to subclass #ThunarxPropertyPage, but may also instantiate it - directly and add widgets to it, but I strongly suggest to create a subclass - as it usually leads to better modularization and thereby better maintainability - in the code. -</para> - -<para> - To pick up the #TagPage example from the thunarx_property_page_provider_get_pages() - description again, you'd create a new class #TagPage, that inherits #ThunarxPropertyPage - (using the #THUNARX_DEFINE_TYPE macro), which provides several user interface elements - in the property, and defines atleast one property named <literal>"file"</literal>, which - is the #ThunarxFileInfo whose tags are displayed in the property page. For example, the - <filename>tag-page.h</filename> header file would look like this (this is really just - an example of the suggested way to implement property pages, you may of course choose - a different way): -</para> - -<informalexample><programlisting> -##ifndef __TAG_PAGE_H__ -##define __TAG_PAGE_H__ - -##include <thunarx/thunarx.h> - -G_BEGIN_DECLS; - -typedef struct _TagPageClass TagPageClass; -typedef struct _TagPage TagPage; - -#define TAG_TYPE_PAGE (tag_page_get_type ()) -#define TAG_PAGE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), TAG_TYPE_PAGE, TagPage)) -#define TAG_PAGE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), TAG_TYPE_PAGE, TagPageClass)) -#define TAG_IS_PAGE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), TAG_TYPE_PAGE)) -#define TAG_IS_PAGE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), TAG_TYPE_PAGE)) -#define TAG_PAGE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), TAG_TYPE_PAGE, TagPageClass)) - -/* these two functions are implemented automatically by the THUNARX_DEFINE_TYPE macro */ -GType tag_page_get_type (void) G_GNUC_CONST; -void tag_page_register_type (ThunarxProviderPlugin *plugin); - -GtkWidget *tag_page_new (ThunarxFileInfo *file) G_GNUC_MALLOC; - -ThunarxFileInfo *tag_page_get_file (TagPage *tag_page); -void tag_page_set_file (TagPage *tag_page, - ThunarxFileInfo *file); - -G_END_DECLS; - -##endif /* !__TAG_PAGE_H__ */ -</programlisting></informalexample> - -<para> - And the <filename>tag-page.c</filename> source file could look like this: -</para> - -<informalexample><programlisting> -##include "tag-page.h" - -/* Property identifiers */ -enum -{ - PROP_0, - PROP_FILE, -}; - -static void tag_page_class_init (TagPageClass *klass); -static void tag_page_init (TagPage *tag_page); -static void tag_page_finalize (GObject *object); -static void tag_page_get_property (GObject *object, - guint prop_id, - GValue *value, - GParamSpec *pspec); -static void tag_page_set_property (GObject *object, - guint prop_id, - const GValue *value, - GParamSpec *pspec); -static void tag_page_file_changed (ThunarxFileInfo *file, - TagPage *tag_page); - -struct _TagPageClass -{ - ThunarxPropertyPageClass __parent__; -}; - -struct _TagPage -{ - ThunarxPropertyPage __parent__; - ThunarxFileInfo *file; - - /* your widgets... */ -}; - -/* implements the tag_page_get_type() and tag_page_register_type() functions */ -THUNARX_DEFINE_TYPE (TagPage, tag_page, THUNARX_TYPE_PROPERTY_PAGE); - -static void -tag_page_class_init (TagPageClass *klass) -{ - GObjectClass *gobject_class; - - gobject_class = G_OBJECT_CLASS (klass); - gobject_class->finalize = tag_page_finalize; - gobject_class->get_property = tag_page_get_property; - gobject_class->set_property = tag_page_set_property; - - /** - * TagPage:file: - * - * The #ThunarxFileInfo displayed by this #TagPage. - **/ - g_object_class_install_property (gobject_class, - PROP_FILE, - g_param_spec_object ("file", "file", "file, - THUNARX_TYPE_FILE_INFO, - G_PARAM_READWRITE)); -} - -static void -tag_page_init (TagPage *tag_page) -{ - GtkWidget *table; - - /* you can of course also use a GtkVBox here, or whatever */ - table = gtk_table_new (2, 2, FALSE); - gtk_container_add (GTK_CONTAINER (tag_page), table); - gtk_widget_show (table); - - /* add your widgets to the table... */ -} - -static void -tag_page_finalize (GObject *object) -{ - TagPage *tag_page = TAG_PAGE (object); - - /* disconnect from the file */ - tag_page_set_file (tag_page, NULL); - - /* release any additional resources... */ - - (*G_OBJECT_CLASS (tag_page_parent_class)->finalize) (object); -} - -static void -tag_page_get_property (GObject *object, - guint prop_id, - GValue *value, - GParamSpec *pspec) -{ - TagPage *tag_page = TAG_PAGE (object); - - switch (prop_id) - { - case PROP_FILE: - g_value_set_object (value, tag_page_get_file (tag_page)); - break; - - default: - G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec); - break; - } -} - -static void -tag_page_set_property (GObject *object, - guint prop_id, - const GValue *value, - GParamSpec *pspec) -{ - TagPage *tag_page = TAG_PAGE (object); - - switch (prop_id) - { - case PROP_FILE: - tag_page_set_file (tag_page, g_value_get_object (value)); - break; - - default: - G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec); - break; - } -} - -static void -tag_page_file_changed (ThunarxFileInfo *file, - TagPage *tag_page) -{ - /* update your user interface elements in the tag_page - * to display the new state of the file... - */ -} - -GtkWidget* -tag_page_new (ThunarxFileInfo *file) -{ - return g_object_new (TAG_TYPE_PAGE, "file", file, NULL); -} - -ThunarxFileInfo* -tag_page_get_file (TagPage *tag_page) -{ - g_return_val_if_fail (TAG_IS_PAGE (tag_page), NULL); - return tag_page->file; -} - -void -tag_page_set_file (TagPage *tag_page, - ThunarxFileInfo *file) -{ - g_return_if_fail (TAG_IS_PAGE (tag_page)); - g_return_if_fail (file == NULL || THUNARX_IS_FILE_INFO (file)); - - if (tag_page->file != NULL) - { - g_signal_handlers_disconnect_by_func (tag_page->file, tag_page_file_changed, tag_page); - g_object_unref (G_OBJECT (tag_page->file)); - } - - tag_page->file = file; - - if (file != NULL) - { - g_object_ref (file); - tag_page_file_changed (file, tag_page); - g_signal_connect (file, "changed", G_CALLBACK (tag_page_file_changed), tag_page); - } - - g_object_notify (G_OBJECT (tag_page), "file"); -} -</programlisting></informalexample> - -<para> - If this seems to be too complicated to you, just don't follow the suggestion. But keep in mind, that - while the above solution is a little longer than a less structured solution, it yields great flexbility - and maintainability. For example the #TagPage class described above, once filled with user interface - elements, may be used for a standalone MP3-Tag editor out of the box (i.e. as an action returned from - the thunarx_renamer_get_actions() method). -</para> - -<para> - What is important to remember is that you should connect to the <literal>"changed"</literal> signal - of the #ThunarxFileInfo<!---->s you are displaying, and update the user interface whenever the file - changes. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - The description of the <link linkend="ThunarxPropertyPageProvider"><type>ThunarxPropertyPageProvider</type></link> interface. -</para> - -<!-- ##### SECTION Stability_Level ##### --> -Stable - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT ThunarxPropertyPage ##### --> -<para> - Base instance type for property pages. -</para> - - -<!-- ##### ARG ThunarxPropertyPage:label ##### --> -<para> - -</para> - -<!-- ##### ARG ThunarxPropertyPage:label-widget ##### --> -<para> - -</para> - -<!-- ##### FUNCTION thunarx_property_page_new ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION thunarx_property_page_new_with_label_widget ##### --> -<para> - -</para> - -@label_widget: -@Returns: - - -<!-- ##### FUNCTION thunarx_property_page_get_label ##### --> -<para> - -</para> - -@property_page: -@Returns: - - -<!-- ##### FUNCTION thunarx_property_page_set_label ##### --> -<para> - -</para> - -@property_page: -@label: - - -<!-- ##### FUNCTION thunarx_property_page_get_label_widget ##### --> -<para> - -</para> - -@property_page: -@Returns: - - -<!-- ##### FUNCTION thunarx_property_page_set_label_widget ##### --> -<para> - -</para> - -@property_page: -@label_widget: - - diff --git a/docs/reference/thunarx/tmpl/thunarx-provider-factory.sgml b/docs/reference/thunarx/tmpl/thunarx-provider-factory.sgml deleted file mode 100644 index 988a510c..00000000 --- a/docs/reference/thunarx/tmpl/thunarx-provider-factory.sgml +++ /dev/null @@ -1,50 +0,0 @@ -<!-- ##### SECTION Title ##### --> -ThunarxProviderFactory - -<!-- ##### SECTION Short_Description ##### --> -The provider factory support for applications - -<!-- ##### SECTION Long_Description ##### --> -<para> - The #ThunarxProviderFactory class allows applications to use Thunar plugins. It handles - the loading of the installed extensions and instantiates providers for the application. - For example, Thunar uses this class to access the installed extensions. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - #ThunarxMenuProvider, #ThunarxPropertyPageProvider, #ThunarxRenamerProvider -</para> - -<!-- ##### SECTION Stability_Level ##### --> -Stable - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT ThunarxProviderFactory ##### --> -<para> - The #ThunarxProviderFactory struct contains only private data. It should - only be accessed with the methods described below. -</para> - - -<!-- ##### FUNCTION thunarx_provider_factory_get_default ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION thunarx_provider_factory_list_providers ##### --> -<para> - -</para> - -@factory: -@type: -@Returns: - - diff --git a/docs/reference/thunarx/tmpl/thunarx-provider-plugin.sgml b/docs/reference/thunarx/tmpl/thunarx-provider-plugin.sgml deleted file mode 100644 index 2c78acce..00000000 --- a/docs/reference/thunarx/tmpl/thunarx-provider-plugin.sgml +++ /dev/null @@ -1,262 +0,0 @@ -<!-- ##### SECTION Title ##### --> -ThunarxProviderPlugin - -<!-- ##### SECTION Short_Description ##### --> -The interface to the plugin type registration - -<!-- ##### SECTION Long_Description ##### --> -<para> - #ThunarxProviderPlugin is the interface to the file manager's type plugin loader implementation. It - provides methods to extensions - also called <emphasis>provider plugins</emphasis> - to register dynamic - types and control certain aspects of the plugin (see thunarx_provider_plugin_set_resident()). -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - #ThunarxProviderFactory -</para> - -<!-- ##### SECTION Stability_Level ##### --> -Stable - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT ThunarxProviderPlugin ##### --> -<para> - The #ThunarxProviderPlugin struct is just a typedef for - the interface instance type. -</para> - - -<!-- ##### ARG ThunarxProviderPlugin:resident ##### --> -<para> - -</para> - -<!-- ##### STRUCT ThunarxProviderPluginIface ##### --> -<para> - Interface with virtual methods implemented by the file manager and - accessible from the extensions. -</para> - -@get_resident: see thunarx_provider_plugin_get_resident(). -@set_resident: see thunarx_provider_plugin_set_resident(). -@register_type: see thunarx_provider_plugin_register_type(). -@add_interface: see thunarx_provider_plugin_add_interface(). -@register_enum: see thunarx_provider_plugin_register_enum(). -@register_flags: see thunarx_provider_plugin_register_flags(). - -<!-- ##### FUNCTION thunarx_provider_plugin_get_resident ##### --> -<para> - -</para> - -@plugin: -@Returns: - - -<!-- ##### FUNCTION thunarx_provider_plugin_set_resident ##### --> -<para> - -</para> - -@plugin: -@resident: - - -<!-- ##### FUNCTION thunarx_provider_plugin_register_type ##### --> -<para> - -</para> - -@plugin: -@type_parent: -@type_name: -@type_info: -@type_flags: -@Returns: - - -<!-- ##### FUNCTION thunarx_provider_plugin_add_interface ##### --> -<para> - -</para> - -@plugin: -@instance_type: -@interface_type: -@interface_info: - - -<!-- ##### FUNCTION thunarx_provider_plugin_register_enum ##### --> -<para> - -</para> - -@plugin: -@name: -@const_static_values: -@Returns: - - -<!-- ##### FUNCTION thunarx_provider_plugin_register_flags ##### --> -<para> - -</para> - -@plugin: -@name: -@const_static_values: -@Returns: - - -<!-- ##### MACRO THUNARX_DEFINE_TYPE ##### --> -<para> - A convenience macro for plugin type implementations, which declares a class - initialization function, a static variable named @t_n<!---->_parent_class - pointing to the parent and a static variable named @t_n<!---->_type containing - the #GType of the type to define. Furthermore, it defines a @t_n<!---->_get_type() - function and a @t_n<!---->_register_type() function. See THUNARX_DEFINE_TYPE_EXTENDED() - for an example. -</para> - -@TN: the name of the new type, in Camel case. -@t_n: the name of the new type, in lowercase, with words separated by '_'. -@T_P: the #GType of the parent type. - - -<!-- ##### MACRO THUNARX_DEFINE_TYPE_WITH_CODE ##### --> -<para> - A convenience macro for plugin type implementations. Similar to THUNARX_DEFINE_TYPE(), but - allows to insert custom code into the <code>*_get_type()</code> function, e.g. interface - implemenations via THUNARX_IMPLEMENT_INTERFACE(). See THUNARX_DEFINE_TYPE_EXTENDED() for - an example. -</para> - -@TN: the name of the new type, in Camel case. -@t_n: the name of the new type, in lowercase, with words separated by '_'. -@T_P: the #GType of the parent type. -@_C_: custom code that gets inserted in the <code>*_get_type()</code> function. - - -<!-- ##### MACRO THUNARX_DEFINE_ABSTRACT_TYPE ##### --> -<para> - A convenience macro for plugin type implementations. Similar to THUNARX_DEFINE_TYPE(), but defines - an abstract type. See THUNARX_DEFINE_TYPE_EXTENDED() for an example. -</para> - -@TN: the name of the new type, in Camel case. -@t_n: the name of the new type, in lowercase, with words separated by '_'. -@T_P: the #GType of the parent type. - - -<!-- ##### MACRO THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE ##### --> -<para> - A convenience macro for plugin type implementations. Similar to THUNARX_DEFINE_TYPE_WITH_CODE(), but defines - an abstract type and allows to insert custom code into the <code>*_get_type()</code> function, e.g. interface - implementations via THUNARX_IMPLEMENT_INTERFACE(). See THUNARX_DEFINE_TYPE_EXTENDED() for an example. -</para> - -@TN: the name of the new type, in Camel case. -@t_n: the name of the new type, in lowercase, with words separated by '_'. -@T_P: the #GType of the parent type. -@_C_: custom code that gets inserted in the <code>*_get_type()</code> function. - - -<!-- ##### MACRO THUNARX_DEFINE_TYPE_EXTENDED ##### --> -<para> - The most general convenience macro for plugin type implementations, on which THUNARX_DEFINE_TYPE(), THUNARX_DEFINE_TYPE_WITH_CODE(), - THUNARX_DEFINE_ABSTRACT_TYPE() and THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE() are based. - -</para> - -<informalexample><programlisting> -THUNARX_DEFINE_TYPE_EXTENDED (FooExtension, - foo_extension, - G_TYPE_OBJECT, - 0, - THUNARX_IMPLEMENT_INTERFACE (TYPE_BAR, - foo_extension_bar_init)); -</programlisting></informalexample> - -<para> - expands to -</para> - -<informalexample><programlisting> -static gpointer foo_extension_parent_class = NULL; -static GType foo_extension_type = G_TYPE_INVALID; - -static void foo_extension_init (FooExtension *self); -static void foo_extension_class_init (FooExtensionClass *klass); -static void foo_extension_class_intern_init (FooExtensionClass *klass) -{ - foo_extension_parent_class = g_type_class_peek_parent (klass); - foo_extension_class_init (klass); -} - -GType -foo_extension_get_type (void) -{ - return foo_extension_type; -} - -void -foo_extension_register_type (ThunarxProviderPlugin *plugin) -{ - GType thunarx_define_type_id; - static const thunarx_define_type_info = - { - sizeof (FooExtensionClass), - NULL, - NULL, - (GClassInitFunc) foo_extension_class_intern_init, - NULL, - NULL, - sizeof (FooExtension), - 0, - (GInstanceInitFunc) foo_extension_init, - NULL, - }; - thunarx_define_type_id = thunarx_provider_plugin_register_type (thunarx_define_type_plugin, G_TYPE_OBJECT, - "FooExtension", &thunarx_define_type_info, 0); - { - static const GInterfaceInfo thunarx_implement_interface_info = - { - (GInterfaceInitFunc) foo_extension_bar_init, - }; - thunarx_provider_plugin_add_interface (thunarx_define_type_plugin, thunarx_define_type_id, - TYPE_BAR, &thunarx_implement_interface_info); - }; - foo_extension_type = thunarx_define_type_id; -} -</programlisting></informalexample> - -<para> - The only pieces which have to be manually provided are the definitions of the instance and - class structure and the definitions of the instance and class init functions. -</para> - -@TypeName: The name of the new type, in Camel case. -@type_name: The name of the new type, in lowercase, with words separated by '_'. -@TYPE_PARENT: The #GType of the parent type. -@flags: #GTypeFlags to pass to thunarx_provider_plugin_register_type(). -@CODE: Custom code that gets inserted in the <code>*_register_type()</code> function. - - -<!-- ##### MACRO THUNARX_IMPLEMENT_INTERFACE ##### --> -<para> - A convenience macro to ease interface addition in the @_C_ section of THUNARX_DEFINE_TYPE_WITH_CODE() - or THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE(). See THUNARX_DEFINE_TYPE_EXTENDED() for an example. -</para> - -<para> - Note that this macro can only be used together with the <code>THUNARX_DEFINE_*</code> macros, since - it depends on variable names used by those macros. -</para> - -@TYPE_IFACE: the #GType of the interface to add. -@iface_init: the interface init function. - - diff --git a/docs/reference/thunarx/tmpl/thunarx-renamer-provider.sgml b/docs/reference/thunarx/tmpl/thunarx-renamer-provider.sgml deleted file mode 100644 index a71f0750..00000000 --- a/docs/reference/thunarx/tmpl/thunarx-renamer-provider.sgml +++ /dev/null @@ -1,48 +0,0 @@ -<!-- ##### SECTION Title ##### --> -ThunarxRenamerProvider - -<!-- ##### SECTION Short_Description ##### --> -The interface to extensions that provide additional bulk renamers - -<!-- ##### SECTION Long_Description ##### --> -<para> - The <interface>ThunarxRenamerProvider</interface> interface is implemented by - extensions which provide additional bulk renamers that should be used by the - bulk rename dialog in Thunar. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - The description of the abstract base class - <link linkend="ThunarxRenamer"><type>ThunarxRenamer</type></link>. -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT ThunarxRenamerProvider ##### --> -<para> - Bulk renamer provider type. -</para> - - -<!-- ##### STRUCT ThunarxRenamerProviderIface ##### --> -<para> - Interface with virtual methods implemented by extensions that provide - additional bulk renamers for the integrated bulk renamer in Thunar. -</para> - -@get_renamers: see thunarx_renamer_provider_get_renamers(). - -<!-- ##### FUNCTION thunarx_renamer_provider_get_renamers ##### --> -<para> - -</para> - -@provider: -@Returns: - - diff --git a/docs/reference/thunarx/tmpl/thunarx-renamer.sgml b/docs/reference/thunarx/tmpl/thunarx-renamer.sgml deleted file mode 100644 index 4988a8f0..00000000 --- a/docs/reference/thunarx/tmpl/thunarx-renamer.sgml +++ /dev/null @@ -1,169 +0,0 @@ -<!-- ##### SECTION Title ##### --> -ThunarxRenamer - -<!-- ##### SECTION Short_Description ##### --> -The abstract base class for bulk renamers - -<!-- ##### SECTION Long_Description ##### --> -<para> - The abstract base class <type>ThunarxRenamer</type> is implemented by - extensions which provide additional bulk renamers that should be used in - the bulk rename dialog. -</para> - -<para> - 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 <type>ThunarSbrReplaceRenamer</type> class included in the - <literal>thunar-sbr</literal> plugin (which is part of the Thunar distribution) - provides a bulk renamer, named <emphasis>Search & Replace</emphasis>, - 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. -</para> - -<para> - <inlinegraphic fileref="bulk-rename.png" format="PNG" /> -</para> - -<para> - The active <type>ThunarxRenamer</type>s 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 <guibutton>Advanced</guibutton>, - button which opens a dialog with the additional settings. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - The description of the <link linkend="ThunarxRenamerProvider"><type>ThunarxRenamerProvider</type></link> - interface. -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT ThunarxRenamer ##### --> -<para> - Abstract base instance type for bulk renamers. -</para> - - -<!-- ##### SIGNAL ThunarxRenamer::changed ##### --> -<para> - -</para> - -@thunarxrenamer: the object which received the signal. - -<!-- ##### ARG ThunarxRenamer:help-url ##### --> -<para> - -</para> - -<!-- ##### ARG ThunarxRenamer:name ##### --> -<para> - -</para> - -<!-- ##### STRUCT ThunarxRenamerClass ##### --> -<para> - Abstract base class with virtual methods implemented by extensions - that provide additional bulk renamers for the integrated bulk - rename module in Thunar. -</para> - -@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(). - -<!-- ##### FUNCTION thunarx_renamer_get_help_url ##### --> -<para> - -</para> - -@renamer: -@Returns: - - -<!-- ##### FUNCTION thunarx_renamer_set_help_url ##### --> -<para> - -</para> - -@renamer: -@help_url: - - -<!-- ##### FUNCTION thunarx_renamer_get_name ##### --> -<para> - -</para> - -@renamer: -@Returns: - - -<!-- ##### FUNCTION thunarx_renamer_set_name ##### --> -<para> - -</para> - -@renamer: -@name: - - -<!-- ##### FUNCTION thunarx_renamer_process ##### --> -<para> - -</para> - -@renamer: -@file: -@text: -@index: -@Returns: - - -<!-- ##### FUNCTION thunarx_renamer_load ##### --> -<para> - -</para> - -@renamer: -@settings: - - -<!-- ##### FUNCTION thunarx_renamer_save ##### --> -<para> - -</para> - -@renamer: -@settings: - - -<!-- ##### FUNCTION thunarx_renamer_get_actions ##### --> -<para> - -</para> - -@renamer: -@window: -@files: -@Returns: - - -<!-- ##### FUNCTION thunarx_renamer_changed ##### --> -<para> - -</para> - -@renamer: - - diff --git a/docs/reference/thunarx/tmpl/thunarx-version-information.sgml b/docs/reference/thunarx/tmpl/thunarx-version-information.sgml deleted file mode 100644 index 4d49acbe..00000000 --- a/docs/reference/thunarx/tmpl/thunarx-version-information.sgml +++ /dev/null @@ -1,99 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Version information - -<!-- ##### SECTION Short_Description ##### --> -Variables and functions to check the library version - -<!-- ##### SECTION Long_Description ##### --> -<para> - The Thunar Extension library provides version information, - which should be used by extensions. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> -Stable - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### VARIABLE thunarx_major_version ##### --> -<para> - -</para> - - -<!-- ##### VARIABLE thunarx_minor_version ##### --> -<para> - -</para> - - -<!-- ##### VARIABLE thunarx_micro_version ##### --> -<para> - -</para> - - -<!-- ##### FUNCTION thunarx_check_version ##### --> -<para> - -</para> - -@required_major: -@required_minor: -@required_micro: -@Returns: - - -<!-- ##### MACRO THUNARX_MAJOR_VERSION ##### --> -<para> - The major version number of the <systemitem class="library">thunarx</systemitem> library. - Like thunarx_major_version, but from the headers used at application compile time, rather - than from the library linked against at application run time. -</para> - - - -<!-- ##### MACRO THUNARX_MINOR_VERSION ##### --> -<para> - The minor version number of the <systemitem class="library">thunarx</systemitem> library. - Like thunarx_minor_version, but from the headers used at application compile time, rather - than from the library linked against at application run time. -</para> - - - -<!-- ##### MACRO THUNARX_MICRO_VERSION ##### --> -<para> - The micro version number of the <systemitem class="library">thunarx</systemitem> library. - Like thunarx_micro_version, but from the headers used at application compile time, rather - than from the library linked against at application run time. -</para> - - - -<!-- ##### MACRO THUNARX_CHECK_VERSION ##### --> -<para> - Checks the version of the <systemitem class="library">thunarx</systemitem> library. Returns - %TRUE if the version of the <systemitem class="library">thunarx</systemitem> header files is - the same as or newer than the passed-in version. -</para> - -<example> - <title>Checking the version of the Thunar Extension library</title> - - <programlisting> -if (!THUNARX_CHECK_VERSION (0, 1, 0)) - g_error ("Thunarx version 0.1.0 or above is required");</programlisting> -</example> - -@major: the major version number. -@minor: the minor version number -@micro: the micro version number. - - |