ThunarxPropertyPage

## ThunarxPropertyPage ThunarxPropertyPage — The base class for pages added to the properties dialog |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <thunarx/thunarx.h>

                        ThunarxPropertyPage;
    GtkWidget *         thunarx_property_page_new           (const gchar *label);
    GtkWidget *         thunarx_property_page_new_with_label_widget
                                                            (GtkWidget *label_widget);
    const gchar *       thunarx_property_page_get_label     (ThunarxPropertyPage *property_page);
    void                thunarx_property_page_set_label     (ThunarxPropertyPage *property_page,
                                                             const gchar *label);
    GtkWidget *         thunarx_property_page_get_label_widget
                                                            (ThunarxPropertyPage *property_page);
    void                thunarx_property_page_set_label_widget
                                                            (ThunarxPropertyPage *property_page,
                                                             GtkWidget *label_widget);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBin
                                     +----ThunarxPropertyPage

## Implemented Interfaces

ThunarxPropertyPage implements AtkImplementorIface and GtkBuildable.

## Properties

      "label"                    gchar*                : Read / Write
      "label-widget"             GtkWidget*            : Read / Write

## Description

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.

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 `"file"`, which is the ThunarxFileInfo whose tags are displayed in the property page. For example, the `tag-page.h` 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):

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    ##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__ */

And the `tag-page.c` source file could look like this:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    ##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 <a class="link" href="ThunarxFileInfo.html" title="ThunarxFileInfo">ThunarxFileInfo</a> displayed by this <GTKDOCLINK HREF="TagPage">TagPage</GTKDOCLINK>.
       **/
      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");
    }

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).

What is important to remember is that you should connect to the `"changed"` signal of the ThunarxFileInfos you are displaying, and update the user interface whenever the file changes.

## Details

### ThunarxPropertyPage

    typedef struct _ThunarxPropertyPage ThunarxPropertyPage;

Base instance type for property pages.

### thunarx_property_page_new ()

    GtkWidget *         thunarx_property_page_new           (const gchar *label);

Allocates a new ThunarxPropertyPage widget and sets its label to the specified `label`. If `label` is `NULL`, the label is omitted.

`label` : | the text to use as the label of the page.
Returns : | the newly allocated ThunarxPropertyPage widget.

### thunarx_property_page_new_with_label_widget ()

    GtkWidget *         thunarx_property_page_new_with_label_widget
                                                            (GtkWidget *label_widget);

Allocates a new ThunarxPropertyPage widget and sets its label to the specified `label_widget`.

`label_widget` : | a GtkWidget, which should be used as label.
Returns : | the newly allocated ThunarxPropertyPage widget.

### thunarx_property_page_get_label ()

    const gchar *       thunarx_property_page_get_label     (ThunarxPropertyPage *property_page);

If the `property_page`'s label widget is a GtkLabel, returns the text in the label widget (the `property_page` will have a GtkLabel for the label widget if a non-`NULL` argument was passed to `thunarx_property_page_new()`).

`property_page` : | a ThunarxPropertyPage.
Returns : | the text in the label or `NULL` if there was no label widget or the label widget was not a GtkLabel. The returned string is owned by the `property_page` and must not be modified or freed.

### thunarx_property_page_set_label ()

    void                thunarx_property_page_set_label     (ThunarxPropertyPage *property_page,
                                                             const gchar *label);

Sets the text of the label. If `label` is `NULL`, the current label is removed.

`property_page` : | a ThunarxPropertyPage.
`label` : | the text to use as the label of the page.

### thunarx_property_page_get_label_widget ()

    GtkWidget *         thunarx_property_page_get_label_widget
                                                            (ThunarxPropertyPage *property_page);

Returns the label widget for the `property_page`. See `thunarx_property_page_set_label_widget()`.

`property_page` : | a ThunarxPropertyPage.
Returns : | the label widget or `NULL` if there is none.

### thunarx_property_page_set_label_widget ()

    void                thunarx_property_page_set_label_widget
                                                            (ThunarxPropertyPage *property_page,
                                                             GtkWidget *label_widget);

Sets the label widget for the `property_page`. This is the widget that will appear in the notebook header for the `property_page`.

`property_page` : | a ThunarxPropertyPage.
`label_widget` : | the new label widget.

## Property Details

### The `"label"` property

      "label"                    gchar*                : Read / Write

Text of the page's label.

Default value: NULL

### The `"label-widget"` property

      "label-widget"             GtkWidget*            : Read / Write

A widget to display in place of the usual page label.

## See Also

The description of the ThunarxPropertyPageProvider interface.