<refentry id="ThunarxMenuProvider">
<refmeta>
<refentrytitle>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>
</refnamediv>
<refsect1>
<title>Stability Level</title>
Stable, unless otherwise indicated
</refsect1>

<refsynopsisdiv><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);


</synopsis>
</refsynopsisdiv>

<refsect1>
<title>Object Hierarchy</title>
<synopsis>

  <link linkend="GInterface">GInterface</link>
   +----ThunarxMenuProvider
</synopsis>

</refsect1>

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

</refsect1>







<refsect1>
<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 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);
}

static void
hello_menu_provider_init (ThunarxMenuProviderIface *iface)
{
  iface->get_file_actions = hello_get_file_actions;
}

static void
hello_activated (GtkAction *action,
                 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;

  action = gtk_action_new ("Hello::say-hello",
                           "Say hello", "Say hello",
                           NULL);
  g_signal_connect (G_OBJECT (action), "activate",
                    G_CALLBACK (hello_activated),
                    window);

  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>
<title>Details</title>
<refsect2>
<title><anchor id="ThunarxMenuProviderIface"/>ThunarxMenuProviderIface</title>
<indexterm><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);
} 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>
</variablelist></refsect2>
<refsect2>
<title><anchor id="ThunarxMenuProvider-struct"/>ThunarxMenuProvider</title>
<indexterm><primary>ThunarxMenuProvider</primary></indexterm><programlisting>typedef struct _ThunarxMenuProvider ThunarxMenuProvider;</programlisting>
<para>
  Menu provider type.
</para></refsect2>
<refsect2>
<title><anchor id="thunarx-menu-provider-get-file-actions"/>thunarx_menu_provider_get_file_actions ()</title>
<indexterm><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>
<title><anchor id="thunarx-menu-provider-get-folder-actions"/>thunarx_menu_provider_get_folder_actions ()</title>
<indexterm><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>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
  The description of the <link linkend="ThunarxFileInfo">ThunarxFileInfo</link>
  interface.
</para>
</refsect1>

</refentry>
