## ThunarxPropertyPageProvider

ThunarxPropertyPageProvider — The interface to extensions that provide additional property pages

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <thunarx/thunarx.h>

                        ThunarxPropertyPageProvider;
                        ThunarxPropertyPageProviderIface;
    GList*              thunarx_property_page_provider_get_pages
                                                            (ThunarxPropertyPageProvider *provider,
                                                             GList *files);

## Object Hierarchy

      GInterface
       +----ThunarxPropertyPageProvider

## Prerequisites

ThunarxPropertyPageProvider requires GObject.

## Description

To add a property page to the file properties dialog, extensions must implement the ThunarxPropertyPageProvider interface. This interface has only one virtual method, `get_pages`, that is passed a list of ThunarxFileInfo objects and returns a list of ThunarxPropertyPage objects.

## Details

### ThunarxPropertyPageProvider

    typedef struct _ThunarxPropertyPageProvider ThunarxPropertyPageProvider;

Property page provider type.

### ThunarxPropertyPageProviderIface

    typedef struct {
      GList *(*get_pages) (ThunarxPropertyPageProvider *provider,
                           GList                       *files);
    } ThunarxPropertyPageProviderIface;

Interface with virtual methods implemented by extensions that provide additional pages for the file properties dialog.

`get_pages` () | see `thunarx_property_page_provider_get_pages()`.

### thunarx_property_page_provider_get_pages ()

    GList*              thunarx_property_page_provider_get_pages
                                                            (ThunarxPropertyPageProvider *provider,
                                                             GList *files);

Returns the list of ThunarxPropertyPages that `provider` has to offer for `files`.

Extensions that implement this interface, must first check whether they support all the ThunarxFileInfos in the list of `files`. Most extensions will probably only support ThunarxPropertyPages for exactly one file of a certain type. For example an MP3-Tag editor property page will most probably support only a single audio file, and so the method would be implemented like this

    GList*
    tag_provider_get_pages (ThunarxPropertyPageProvider *property_page_provider,
                            GList                       *files)
    {
      if (g_list_length (files) != 1)
        return NULL;
      else if (!thunarx_file_info_has_mime_type (files->data, "audio/mp3"))
        return NULL;
      else
        return g_list_append (NULL, tag_page_new (files->data));
    }

where `tag_page_new()` allocates a new TagPage instance for a ThunarxFileInfo object passed to it. See the description of the ThunarxPropertyPage class for additional information about the TagPage example class.

As a special note, this method automatically takes a reference on the `provider` for every ThunarxPropertyPage object returned from the real implementation of this method in `provider`. This is to make sure that the extension stays in memory for atleast the time that the pages 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 `provider` itself, that's released at a later time).

The caller is responsible to free the returned list of pages using something like this when no longer needed:

    g_list_foreach (list, (GFunc) g_object_ref, NULL);
    g_list_foreach (list, (GFunc) gtk_object_sink, NULL);
    g_list_foreach (list, (GFunc) g_object_unref, NULL);
    g_list_free (list);

`provider` : | a ThunarxPropertyPageProvider.
`files` : | the list of ThunarxFileInfos for which a properties dialog will be displayed.
Returns : | the list of ThunarxPropertyPages that `provider` has to offer for `files`.

## See Also

The description of the ThunarxPropertyPage class.