<refentry id="ThunarxMenuProvider">
<refmeta>
<refentrytitle role="top_of_page" id="ThunarxMenuProvider.top_of_page">ThunarxMenuProvider</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>THUNARX Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>ThunarxMenuProvider</refname>
<refpurpose>The interface to extensions that provide additional menu items</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>
<refsect1 id="ThunarxMenuProvider.stability-level">
<title>Stability Level</title>
Stable, unless otherwise indicated
</refsect1>

<refsynopsisdiv id="ThunarxMenuProvider.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;thunarx/thunarx.h&gt;

                    <link linkend="ThunarxMenuProviderIface">ThunarxMenuProviderIface</link>;
                    <link linkend="ThunarxMenuProvider-struct">ThunarxMenuProvider</link>;
<link linkend="GList">GList</link>*              <link linkend="thunarx-menu-provider-get-file-actions">thunarx_menu_provider_get_file_actions</link>
                                                        (<link linkend="ThunarxMenuProvider">ThunarxMenuProvider</link> *provider,
                                                         <link linkend="GtkWidget">GtkWidget</link> *window,
                                                         <link linkend="GList">GList</link> *files);
<link linkend="GList">GList</link>*              <link linkend="thunarx-menu-provider-get-folder-actions">thunarx_menu_provider_get_folder_actions</link>
                                                        (<link linkend="ThunarxMenuProvider">ThunarxMenuProvider</link> *provider,
                                                         <link linkend="GtkWidget">GtkWidget</link> *window,
                                                         <link linkend="ThunarxFileInfo">ThunarxFileInfo</link> *folder);
<link linkend="GList">GList</link>*              <link linkend="thunarx-menu-provider-get-dnd-actions">thunarx_menu_provider_get_dnd_actions</link>
                                                        (<link linkend="ThunarxMenuProvider">ThunarxMenuProvider</link> *provider,
                                                         <link linkend="GtkWidget">GtkWidget</link> *window,
                                                         <link linkend="ThunarxFileInfo">ThunarxFileInfo</link> *folder,
                                                         <link linkend="GList">GList</link> *files);
</synopsis>
</refsynopsisdiv>

<refsect1 id="ThunarxMenuProvider.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GInterface">GInterface</link>
   +----ThunarxMenuProvider
</synopsis>

</refsect1>

<refsect1 id="ThunarxMenuProvider.prerequisites" role="prerequisites">
<title role="prerequisites.title">Prerequisites</title>
<para>
ThunarxMenuProvider requires
 <link linkend="GObject">GObject</link>.</para>

</refsect1>







<refsect1 id="ThunarxMenuProvider.description" role="desc">
<title role="desc.title">Description</title>
<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 <link linkend="thunarx-menu-provider-get-file-actions"><function>thunarx_menu_provider_get_file_actions()</function></link> or the
  <link linkend="thunarx-menu-provider-get-folder-actions"><function>thunarx_menu_provider_get_folder_actions()</function></link> method, the implementation in the
  extension should use only the <link linkend="thunarx-file-info-has-mime-type"><function>thunarx_file_info_has_mime_type()</function></link> and
  <link linkend="thunarx-file-info-is-directory"><function>thunarx_file_info_is_directory()</function></link> 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
  <link linkend="thunarx-menu-provider-get-file-actions"><function>thunarx_menu_provider_get_file_actions()</function></link> and <link linkend="thunarx-menu-provider-get-folder-actions"><function>thunarx_menu_provider_get_folder_actions()</function></link>
  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_object_new_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>
</refsect1>

<refsect1 id="ThunarxMenuProvider.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="ThunarxMenuProviderIface" role="struct">
<title>ThunarxMenuProviderIface</title>
<indexterm zone="ThunarxMenuProviderIface"><primary>ThunarxMenuProviderIface</primary></indexterm><programlisting>typedef struct {
  GList *(*get_file_actions)    (ThunarxMenuProvider *provider,
                                 GtkWidget           *window,
                                 GList               *files);

  GList *(*get_folder_actions)  (ThunarxMenuProvider *provider,
                                 GtkWidget           *window,
                                 ThunarxFileInfo     *folder);

  GList *(*get_dnd_actions)     (ThunarxMenuProvider *provider,
                                 GtkWidget           *window,
                                 ThunarxFileInfo     *folder,
                                 GList               *files);
} ThunarxMenuProviderIface;
</programlisting>
<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><variablelist role="struct">
<varlistentry>
<term><structfield>get_file_actions</structfield>&nbsp;()</term>
<listitem><simpara>See <link linkend="thunarx-menu-provider-get-file-actions"><function>thunarx_menu_provider_get_file_actions()</function></link>.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>get_folder_actions</structfield>&nbsp;()</term>
<listitem><simpara>See <link linkend="thunarx-menu-provider-get-folder-actions"><function>thunarx_menu_provider_get_folder_actions()</function></link>.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>get_dnd_actions</structfield>&nbsp;()</term>
<listitem><simpara>See <link linkend="thunarx-menu-provider-get-dnd-actions"><function>thunarx_menu_provider_get_dnd_actions()</function></link>.

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="ThunarxMenuProvider-struct" role="struct">
<title>ThunarxMenuProvider</title>
<indexterm zone="ThunarxMenuProvider-struct"><primary>ThunarxMenuProvider</primary></indexterm><programlisting>typedef struct _ThunarxMenuProvider ThunarxMenuProvider;</programlisting>
<para>
  Menu provider type.
</para></refsect2>
<refsect2 id="thunarx-menu-provider-get-file-actions" role="function">
<title>thunarx_menu_provider_get_file_actions ()</title>
<indexterm zone="thunarx-menu-provider-get-file-actions"><primary>thunarx_menu_provider_get_file_actions</primary></indexterm><programlisting><link linkend="GList">GList</link>*              thunarx_menu_provider_get_file_actions
                                                        (<link linkend="ThunarxMenuProvider">ThunarxMenuProvider</link> *provider,
                                                         <link linkend="GtkWidget">GtkWidget</link> *window,
                                                         <link linkend="GList">GList</link> *files);</programlisting>
<para>
Returns the list of <link linkend="GtkAction"><type>GtkAction</type></link><!---->s that <parameter>provider</parameter> has to offer for
<parameter>files</parameter>.
</para>
<para>
As a special note, this method automatically takes a reference on the
<parameter>provider</parameter> for every <link linkend="GtkAction"><type>GtkAction</type></link> object returned from the real implementation
of this method in <parameter>provider</parameter>. This is to make sure that the extension stays
in memory for atleast the time that the actions are used. If the extension
wants to stay in memory for a longer time, it'll need to take care of this
itself (e.g. by taking an additional reference on the <parameter>provider</parameter> itself,
that's released at a later time).
</para>
<para>
The caller is responsible to free the returned list of actions using
something like this when no longer needed:
<informalexample><programlisting>
g_list_foreach (list, (GFunc) g_object_unref, NULL);
g_list_free (list);
</programlisting></informalexample></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>provider</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="ThunarxMenuProvider"><type>ThunarxMenuProvider</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>window</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="GtkWindow"><type>GtkWindow</type></link> within which the actions will be used.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>files</parameter>&nbsp;:</term>
<listitem><simpara> the list of <link linkend="ThunarxFileInfo"><type>ThunarxFileInfo</type></link><!---->s to which the actions will be applied.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the list of <link linkend="GtkAction"><type>GtkAction</type></link><!---->s that <parameter>provider</parameter> has to offer
              for <parameter>files</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="thunarx-menu-provider-get-folder-actions" role="function">
<title>thunarx_menu_provider_get_folder_actions ()</title>
<indexterm zone="thunarx-menu-provider-get-folder-actions"><primary>thunarx_menu_provider_get_folder_actions</primary></indexterm><programlisting><link linkend="GList">GList</link>*              thunarx_menu_provider_get_folder_actions
                                                        (<link linkend="ThunarxMenuProvider">ThunarxMenuProvider</link> *provider,
                                                         <link linkend="GtkWidget">GtkWidget</link> *window,
                                                         <link linkend="ThunarxFileInfo">ThunarxFileInfo</link> *folder);</programlisting>
<para>
Returns the list of <link linkend="GtkAction"><type>GtkAction</type></link><!---->s that <parameter>provider</parameter> has to offer for
<parameter>folder</parameter>.
</para>
<para>
As a special note, this method automatically takes a reference on the
<parameter>provider</parameter> for every <link linkend="GtkAction"><type>GtkAction</type></link> object returned from the real implementation
of this method in <parameter>provider</parameter>. This is to make sure that the extension stays
in memory for atleast the time that the actions are used. If the extension
wants to stay in memory for a longer time, it'll need to take care of this
itself (e.g. by taking an additional reference on the <parameter>provider</parameter> itself,
that's released at a later time).
</para>
<para>
The caller is responsible to free the returned list of actions using
something like this when no longer needed:
<informalexample><programlisting>
g_list_foreach (list, (GFunc) g_object_unref, NULL);
g_list_free (list);
</programlisting></informalexample></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>provider</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="ThunarxMenuProvider"><type>ThunarxMenuProvider</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>window</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="GtkWindow"><type>GtkWindow</type></link> within which the actions will be used.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>folder</parameter>&nbsp;:</term>
<listitem><simpara> the folder to which the actions should will be applied.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the list of <link linkend="GtkAction"><type>GtkAction</type></link><!---->s that <parameter>provider</parameter> has to offer
              for <parameter>folder</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="thunarx-menu-provider-get-dnd-actions" role="function" condition="since:0.4.1">
<title>thunarx_menu_provider_get_dnd_actions ()</title>
<indexterm zone="thunarx-menu-provider-get-dnd-actions" role="0.4.1"><primary>thunarx_menu_provider_get_dnd_actions</primary></indexterm><programlisting><link linkend="GList">GList</link>*              thunarx_menu_provider_get_dnd_actions
                                                        (<link linkend="ThunarxMenuProvider">ThunarxMenuProvider</link> *provider,
                                                         <link linkend="GtkWidget">GtkWidget</link> *window,
                                                         <link linkend="ThunarxFileInfo">ThunarxFileInfo</link> *folder,
                                                         <link linkend="GList">GList</link> *files);</programlisting>
<para>
Returns the list of <link linkend="GtkAction"><type>GtkAction</type></link><!---->s that <parameter>provider</parameter> has to offer for
dropping the <parameter>files</parameter> into the <parameter>folder</parameter>. For example, the thunar-archive-plugin
provides <guilabel>Extract Here</guilabel> actions when dropping archive
files into a folder that is writable by the user.
</para>
<para>
As a special note, this method automatically takes a reference on the
<parameter>provider</parameter> for every <link linkend="GtkAction"><type>GtkAction</type></link> object returned from the real implementation
of this method in <parameter>provider</parameter>. This is to make sure that the extension stays
in memory for atleast the time that the actions are used. If the extension
wants to stay in memory for a longer time, it'll need to take care of this
itself (e.g. by taking an additional reference on the <parameter>provider</parameter> itself,
that's released at a later time).
</para>
<para>
The caller is responsible to free the returned list of actions using
something like this when no longer needed:
<informalexample><programlisting>
g_list_foreach (list, (GFunc) g_object_unref, NULL);
g_list_free (list);
</programlisting></informalexample></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>provider</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="ThunarxMenuProvider"><type>ThunarxMenuProvider</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>window</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="GtkWindow"><type>GtkWindow</type></link> within which the actions will be used.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>folder</parameter>&nbsp;:</term>
<listitem><simpara> the folder into which the <parameter>files</parameter> are being dropped
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>files</parameter>&nbsp;:</term>
<listitem><simpara> the list of <link linkend="ThunarxFileInfo"><type>ThunarxFileInfo</type></link><!---->s for the files that are 
            being dropped to <parameter>folder</parameter> in <parameter>window</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the list of <link linkend="GtkAction"><type>GtkAction</type></link><!---->s that <parameter>provider</parameter> has to offer
              for dropping <parameter>files</parameter> to <parameter>folder</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since  0.4.1
</para></refsect2>

</refsect1>



<refsect1 id="ThunarxMenuProvider.see-also">
<title>See Also</title>
<para>
  The description of the <link linkend="ThunarxFileInfo">ThunarxFileInfo</link>
  interface.
</para>
</refsect1>

</refentry>
