Commit f6eae23d authored by Benedikt Meurer's avatar Benedikt Meurer

2005-11-21 Benedikt Meurer <benny@xfce.org>

	* thunarx/thunarx-provider-plugin.{c,h}, thunarx/Makefile.am,
	  thunarx/thunarx.h, thunarx/thunarx.symbols: Add ThunarxProviderPlugin
	  interface, which abstracts from the details of the dynamic type
	  registration, and is accessible to the extensions.
	* thunarx/thunarx-provider-module.{c,h}, thunarx/Makefile.am: Add
	  implementation for the ThunarxProviderPlugin interface, based on
	  GTypeModule, which is used on the file manager's side to manage the
	  type plugins.
	* thunarx/thunarx-provider-factory.{c,h}, thunarx/Makefile.am,
	  thunarx/thunarx.h, thunarx/thunarx.symbols: Add ThunarxProviderFactory
	  based on the ThunarExtensionManager as public interface to the
	  provider plugin mechanism. This may also be used by other applications
	  in the future.
	* thunarx/thunarx.h: Provide convenience macros ala G_DEFINE_TYPE() to
	  ease type registration for plugin writers.
	* examples/, configure.in.in: Update the "Open Terminal Here" example.
	* docs/reference/thunarx/: Update the thunarx reference manual to
	  include the new classes and interfaces.
	* thunar/thunar-extension-manager.{c,h}: Drop the old extension manager
	  class in favour of the new provider factory class.
	* thunar/thunar-properties-dialog.c, thunar/thunar-standard-view.c: Use
	  ThunarxProviderFactory to load the providers from the installed
	  extensions.
	* po/POTFILES.in: Update with new file list.
	* thunar/thunar-file.{c,h}: Implement thunar_file_list_copy() using
	  thunarx_file_info_list_copy() and thunar_file_list_free() using
	  thunarx_file_info_list_free().
	* docs/reference/thunar-vfs/thunar-vfs-overrides.txt,
	  docs/reference/thunarx/thunarx-overrides.txt: Fix build error with
	  older gtk-doc versions.




(Old svn revision: 18919)
parent 5dcf7a66
2005-11-21 Benedikt Meurer <benny@xfce.org>
* thunarx/thunarx-provider-plugin.{c,h}, thunarx/Makefile.am,
thunarx/thunarx.h, thunarx/thunarx.symbols: Add ThunarxProviderPlugin
interface, which abstracts from the details of the dynamic type
registration, and is accessible to the extensions.
* thunarx/thunarx-provider-module.{c,h}, thunarx/Makefile.am: Add
implementation for the ThunarxProviderPlugin interface, based on
GTypeModule, which is used on the file manager's side to manage the
type plugins.
* thunarx/thunarx-provider-factory.{c,h}, thunarx/Makefile.am,
thunarx/thunarx.h, thunarx/thunarx.symbols: Add ThunarxProviderFactory
based on the ThunarExtensionManager as public interface to the
provider plugin mechanism. This may also be used by other applications
in the future.
* thunarx/thunarx.h: Provide convenience macros ala G_DEFINE_TYPE() to
ease type registration for plugin writers.
* examples/, configure.in.in: Update the "Open Terminal Here" example.
* docs/reference/thunarx/: Update the thunarx reference manual to
include the new classes and interfaces.
* thunar/thunar-extension-manager.{c,h}: Drop the old extension manager
class in favour of the new provider factory class.
* thunar/thunar-properties-dialog.c, thunar/thunar-standard-view.c: Use
ThunarxProviderFactory to load the providers from the installed
extensions.
* po/POTFILES.in: Update with new file list.
* thunar/thunar-file.{c,h}: Implement thunar_file_list_copy() using
thunarx_file_info_list_copy() and thunar_file_list_free() using
thunarx_file_info_list_free().
* docs/reference/thunar-vfs/thunar-vfs-overrides.txt,
docs/reference/thunarx/thunarx-overrides.txt: Fix build error with
older gtk-doc versions.
2005-11-16 Benedikt Meurer <benny@xfce.org>
* thunar-vfs/thunar-vfs-mime-application.{c,h},
......
......@@ -328,7 +328,7 @@ docs/reference/thunar-vfs/version.xml
docs/reference/thunarx/Makefile
docs/reference/thunarx/version.xml
examples/Makefile
examples/open-terminal-here/Makefile
examples/tex-open-terminal/Makefile
icons/Makefile
icons/24x24/Makefile
icons/48x48/Makefile
......
......@@ -6,6 +6,8 @@
<!ENTITY ThunarxMenuProvider SYSTEM "xml/thunarx-menu-provider.xml">
<!ENTITY ThunarxPropertyPage SYSTEM "xml/thunarx-property-page.xml">
<!ENTITY ThunarxPropertyPageProvider SYSTEM "xml/thunarx-property-page-provider.xml">
<!ENTITY ThunarxProviderFactory SYSTEM "xml/thunarx-provider-factory.xml">
<!ENTITY ThunarxProviderPlugin SYSTEM "xml/thunarx-provider-plugin.xml">
<!ENTITY thunarx-version-information SYSTEM "xml/thunarx-version-information.xml">
<!ENTITY version SYSTEM "version.xml">
......@@ -133,7 +135,7 @@
<para>
<emphasis>Thunar Extensions</emphasis> are shared libraries that extend the basic functionality
provided by the Thunar File Manager. An extension exports one or more <link
linkend="GObject"><type>GObject</type></link>s, called <emphasis>providers</emphasis> to Thunar.
linkend="GObject"><type>GObject</type></link>s, called <emphasis>providers</emphasis>, to Thunar.
</para>
<para>
......@@ -153,7 +155,7 @@
Thunar passes file references to the provider using <link linkend="ThunarxFileInfo"><type>ThunarxFileInfo</type></link>
objects. The <link linkend="ThunarxFileInfo"><type>ThunarxFileInfo</type></link> interface provides access to the file
information that Thunar has already read - mime type, URI, name, etc. Extensions should use the data from
from the <link linkend="ThunarxFileInfo"><type>ThunarxFileInfo</type></link> rather than reading it themselves, to
the <link linkend="ThunarxFileInfo"><type>ThunarxFileInfo</type></link> rather than reading it themselves, to
prevent excessive I/O.
</para>
......@@ -172,8 +174,10 @@
Most objects created by the extensions need names, e.g. the <link linkend="GtkAction"><type>GtkAction</type></link>s
returned from the <link linkend="ThunarxMenuProvider"><type>ThunarxMenuProvider</type></link>s. These names must be
namespaced with the name of the extension. For example the main action returned from the
<application>OpenTerminal</application> extension should be called <literal>OpenTerminal::open-terminal</literal>.
The namespace must be global among the providers exported by a certain extension.
<application>TexOpenTerminal</application> extension (which can be found in the <filename
role="directory">examples/tex-open-terminal</filename> subdirectory of the Thunar distribution) should be called
<literal>TexOpenTerminal::open-terminal</literal>. The namespace must be global among the providers exported by
a certain extension.
</para>
</sect2>
......@@ -183,9 +187,10 @@
<para>
Thunar extensions are loaded as <link linkend="GTypeModule"><type>GTypeModule</type></link>s. This means that all GTypes
created by the extension must be registered with the <link linkend="GTypeModule"><type>GTypeModule</type></link>, using
<link linkend="g-type-module-register-type"><function>g_type_module_register_type()</function></link> function rather
than <link linked="g-type-register-static"><function>g_type_register_static()</function></link>. All types exported by
an extension must be registered in
<link linkend="thunarx-provider-plugin-register-type"><function>thunarx_provider_plugin_register_type()</function></link>
function (or one of the convenience macros like <link linkend="THUNARX-DEFINE-TYPE:CAPS"><function>THUNARX_DEFINE_TYPE()</function></link>)
rather than <link linked="g-type-register-static"><function>g_type_register_static()</function></link>. All types
exported by an extension must be registered in
<link linkend="thunar-extension-initialize"><function>thunar_extension_initialize()</function></link>.
</para>
</sect2>
......@@ -195,8 +200,8 @@
<title>Getting Started</title>
<para>
Providers are <link linkend="GTypeModule"><type>GTypeModule</type></link>s loaded from shared libraries installed in
<filename role="directory">$libdir/thunarx-1/</filename>. The shared libraries are linked against the
Providers are <link linkend="ThunarxProviderPlugin"><type>ThunarxProviderPlugin</type></link>s loaded from shared libraries
installed in <filename role="directory">$libdir/thunarx-1/</filename>. The shared libraries are linked against the
<systemitem class="library">thunarx-1</systemitem> library.
</para>
......@@ -206,8 +211,8 @@
</para>
<para>
<function>thunar_extension_initialize()</function> is passed a <link linkend="GTypeModule"><type>GTypeModule</type></link>
object, and must register all GTypes that the extension needs. <function>thunar_extension_shutdown()</function> should
<function>thunar_extension_initialize()</function> is passed a <link linkend="ThunarxProviderPlugin"><type>ThunarxProviderPlugin</type></link>
object, and is responsible to register all GTypes required by the extension. <function>thunar_extension_shutdown()</function> should
perform any extension-specific shutdown required prior to unloading the extension. <function>thunar_extension_list_types()</function>
returns an array of GTypes that represent the types of the providers exported by the extension. Thunar will instantiate
objects of those types when needed.
......@@ -223,7 +228,7 @@
static GType type_list[1];
static void
foo_extension_register_type (GTypeModule *module)
foo_extension_register_type (ThunarxProviderPlugin *plugin)
{
static const GTypeInfo info =
{
......@@ -239,10 +244,10 @@ foo_extension_register_type (GTypeModule *module)
NULL,
};
type_list[0] = g_type_module_register_type (module,
G_TYPE_OBJECT,
"FooExtension",
&amp;info, 0);
type_list[0] = thunarx_provider_plugin_register_type (plugin,
G_TYPE_OBJECT,
"FooExtension",
&amp;info, 0);
/* implement the desired provider interfaces */
}
......@@ -254,7 +259,7 @@ foo_extension_get_type (void)
}
G_MODULE_EXPORT void
thunar_extension_initialize (GTypeModule *module)
thunar_extension_initialize (ThunarxProviderPlugin *plugin)
{
const gchar *mismatch;
......@@ -268,7 +273,7 @@ thunar_extension_initialize (GTypeModule *module)
return;
}
foo_extension_register_type (module);
foo_extension_register_type (plugin);
}
G_MODULE_EXPORT void
......@@ -286,6 +291,12 @@ thunar_extension_list_types (const GType **types,
}</programlisting>
</example>
<para>
You should check the <application>TexOpenTerminal</application> extension, which is included in the Thunar
distribution in the <filename role="directory">examples/tex-open-terminal</filename> directory, for a more
complete example of how to write a Thunar extension.
</para>
<sect2 id="thunarx-writing-extensions-compiling-thunar-extensions">
<title>Compiling Thunar Extensions</title>
......@@ -362,24 +373,23 @@ $ install -c -m 0755 foo.so `pkg-config --variable=extensionsdir thunarx-1`/foo.
</para>
<para>
Such extensions must set the <literal>resident</literal> property of the type
module in its <function>thunar_extension_initialize()</function> function to
<literal>TRUE</literal>.
Such extensions must set the <literal>resident</literal> property of the provider plugin in its
<function>thunar_extension_initialize()</function> function to <literal>TRUE</literal>, using the <link
linkend="thunarx-provider-plugin-set-resident"><function>thunarx_provider_plugin_set_resident()</function></link>
method.
</para>
<example>
<title>Making an extension memory resident</title>
<programlisting>
G_MODULE_EXPORT void
thunar_extension_initialize (GTypeModule *module)
thunar_extension_initialize (ThunarxProviderPlugin *plugin)
{
/* setup the types for the extension */
...
/* ensure that the extension will never be unloaded */
g_object_set (G_OBJECT (module),
"resident", TRUE,
NULL);
thunarx_provider_plugin_set_resident (plugin, TRUE);
}</programlisting>
</example>
</sect2>
......@@ -397,8 +407,8 @@ thunar_extension_initialize (GTypeModule *module)
<para>
In order to hide the internals of the file manager from the extensions, the <systemitem
class="library">thunarx</systemitem> provides an abstraction layer, which includes interfaces
accessible to the extension, that are implemented by the file manager at runtime.
class="library">thunarx</systemitem> library provides an abstraction layer, which includes
interfaces accessible to the extension, that are implemented by the file manager at runtime.
</para>
<para>
......@@ -409,14 +419,17 @@ thunar_extension_initialize (GTypeModule *module)
Currently the abstraction layer consists of the interface <link
linkend="ThunarxFileInfo"><type>ThunarxFileInfo</type></link>, which provides
extensions with a way to access information about a file handled within
the file manager, and the class <link
the file manager, the class <link
linkend="ThunarxPropertyPage"><type>ThunarxPropertyPage</type></link>, which
is the base class for widgets that can be added to the properties dialog by
extensions.
extensions, and the interface <link
linkend="ThunarxProviderPlugin"><type>ThunarxProviderPlugin</type></link>, which
hides the details of dynamic type registration from the extensions.
</para>
&ThunarxFileInfo;
&ThunarxPropertyPage;
&ThunarxProviderPlugin;
</part>
<part id="thunarx-providers">
......@@ -444,6 +457,12 @@ thunar_extension_initialize (GTypeModule *module)
&ThunarxPropertyPageProvider;
</part>
<part id="thunarx-using-extensions">
<title>Using Thunar extensions in applications</title>
&ThunarxProviderFactory;
</part>
<index>
<title>Index</title>
</index>
......
......@@ -77,6 +77,50 @@ THUNARX_PROPERTY_PAGE_PROVIDER_GET_IFACE
thunarx_property_page_provider_get_type
</SECTION>
<SECTION>
<FILE>thunarx-provider-factory</FILE>
<TITLE>ThunarxProviderFactory</TITLE>
ThunarxProviderFactory
thunarx_provider_factory_get_default
thunarx_provider_factory_list_providers
<SUBSECTION Standard>
ThunarxProviderFactoryClass
THUNARX_TYPE_PROVIDER_FACTORY
THUNARX_PROVIDER_FACTORY
THUNARX_PROVIDER_FACTORY_CLASS
THUNARX_IS_PROVIDER_FACTORY
THUNARX_IS_PROVIDER_FACTORY_CLASS
THUNARX_PROVIDER_FACTORY_GET_CLASS
<SUBSECTION Private>
thunarx_provider_factory_get_type
</SECTION>
<SECTION>
<FILE>thunarx-provider-plugin</FILE>
<TITLE>ThunarxProviderPlugin</TITLE>
ThunarxProviderPlugin
ThunarxProviderPluginIface
thunarx_provider_plugin_get_resident
thunarx_provider_plugin_set_resident
thunarx_provider_plugin_register_type
thunarx_provider_plugin_add_interface
thunarx_provider_plugin_register_enum
thunarx_provider_plugin_register_flags
THUNARX_DEFINE_TYPE
THUNARX_DEFINE_TYPE_WITH_CODE
THUNARX_DEFINE_ABSTRACT_TYPE
THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE
THUNARX_DEFINE_TYPE_EXTENDED
THUNARX_IMPLEMENT_INTERFACE
<SUBSECTION Standard>
THUNARX_TYPE_PROVIDER_PLUGIN
THUNARX_PROVIDER_PLUGIN
THUNARX_IS_PROVIDER_PLUGIN
THUNARX_PROVIDER_PLUGIN_GET_IFACE
<SUBSECTION Private>
thunarx_provider_plugin_get_type
</SECTION>
<SECTION>
<FILE>thunarx-version-information</FILE>
<TITLE>Variables and functions to check the library version</TITLE>
......
......@@ -4,3 +4,5 @@ thunarx_file_info_get_type
thunarx_menu_provider_get_type
thunarx_property_page_get_type
thunarx_property_page_provider_get_type
thunarx_provider_factory_get_type
thunarx_provider_plugin_get_type
......@@ -35,43 +35,14 @@ The interface to extensions that provide additional menu items
<title>Menu provider example</title>
<programlisting>
static GType hello_type;
static void hello_menu_provider_init (ThunarxMenuProviderIface *iface);
static GList *hello_get_file_actions (ThunarxMenuProvider *provider,
GtkWidget *window,
GList *files);
static void
hello_register_type (GTypeModule *module)
{
static const GTypeInfo info =
{
sizeof (HelloClass),
NULL,
NULL,
NULL,
NULL,
NULL,
sizeof (Hello),
0,
NULL,
NULL,
};
static const GInterfaceInfo menu_provider_info =
{
(GInterfaceInitFunc) hello_menu_provider_init,
NULL,
NULL,
};
hello_type = g_type_module_register_type (module, G_TYPE_OBJECT,
"Hello", &amp;info, 0);
g_type_module_add_interface (module, hello_type,
THUNARX_TYPE_MENU_PROVIDER,
&amp;menu_provider_info);
}
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)
......
<!-- ##### SECTION Title ##### -->
ThunarxProviderFactory
<!-- ##### SECTION Short_Description ##### -->
Provider factory support
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#ThunarxMenuProvider, #ThunarxPropertyPageProvider
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT ThunarxProviderFactory ##### -->
<para>
</para>
<!-- ##### FUNCTION thunarx_provider_factory_get_default ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION thunarx_provider_factory_list_providers ##### -->
<para>
</para>
@factory:
@type:
@Returns:
<!-- ##### SECTION Title ##### -->
ThunarxProviderPlugin
<!-- ##### SECTION Short_Description ##### -->
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
<!-- ##### STRUCT ThunarxProviderPlugin ##### -->
<para>
</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", &amp;thunarx_define_type_info, 0);
{
static const GInterfaceInfo thunarx_implement_interface_info =
{