## MatePanelApplet MatePanelApplet — The MatePanelApplet object. |

## Synopsis

    #include <mate-panel-applet.h>

    struct              MatePanelApplet;
    enum                MatePanelAppletOrient;
    enum                MatePanelAppletBackgroundType;
    enum                MatePanelAppletFlags;
    gboolean            (*MatePanelAppletFactoryCallback)       (MatePanelApplet *applet,
                                                             const gchar *iid,
                                                             gpointer user_data);
    GtkWidget *         mate_panel_applet_new                    (void);
    MatePanelAppletOrient   mate_panel_applet_get_orient             (MatePanelApplet *applet);
    guint               mate_panel_applet_get_size               (MatePanelApplet *applet);
    MatePanelAppletBackgroundType  mate_panel_applet_get_background  (MatePanelApplet *applet,
                                                             GdkColor *color,
                                                             GdkPixmap **pixmap);
    gchar *             mate_panel_applet_get_preferences_key    (MatePanelApplet *applet);
    void                mate_panel_applet_add_preferences        (MatePanelApplet *applet,
                                                             const gchar *schema_dir,
                                                             GError **opt_error);
    MatePanelAppletFlags    mate_panel_applet_get_flags              (MatePanelApplet *applet);
    void                mate_panel_applet_set_flags              (MatePanelApplet *applet,
                                                             MatePanelAppletFlags flags);
    void                mate_panel_applet_set_size_hints         (MatePanelApplet *applet,
                                                             const int *size_hints,
                                                             int n_elements,
                                                             int base_size);
    gboolean            mate_panel_applet_get_locked_down        (MatePanelApplet *applet);
    void                mate_panel_applet_request_focus          (MatePanelApplet *applet,
                                                             guint32 timestamp);
    void                mate_panel_applet_setup_menu             (MatePanelApplet *applet,
                                                             const gchar *xml,
                                                             GtkActionGroup *action_group);
    void                mate_panel_applet_setup_menu_from_file   (MatePanelApplet *applet,
                                                             const gchar *filename,
                                                             GtkActionGroup *action_group);
    int                 mate_panel_applet_factory_main           (const gchar *factory_id,
                                                             gboolean out_process,
                                                             GType applet_type,
                                                             MatePanelAppletFactoryCallback callback,
                                                             gpointer data);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBin
                                     +----GtkEventBox
                                           +----MatePanelApplet

## Implemented Interfaces

MatePanelApplet implements AtkImplementorIface and GtkBuildable.

## Properties

      "background"               gchar*                : Read / Write
      "closure"                  gpointer              : Read / Write / Construct Only
      "connection"               GDBusConnection*      : Read / Write / Construct Only
      "flags"                    guint                 : Read / Write
      "id"                       gchar*                : Read / Write / Construct Only
      "locked"                   gboolean              : Read / Write
      "locked-down"              gboolean              : Read / Write
      "orient"                   guint                 : Read / Write
      "prefs-key"                gchar*                : Read / Write
      "size"                     guint                 : Read / Write
      "size-hints"               gpointer              : Read / Write

## Signals

      "change-background"                              : Run Last
      "change-orient"                                  : Run Last
      "change-size"                                    : Run Last
      "move-focus-out-of-applet"                       : Action

## Description

The MatePanelApplet object is an object which encapsulates an applet. It is a GtkContainer which may contain a single widget. This widget, in turn, should contain all widgets exposed by the applet.

A MatePanelApplet is associated with a MateComponentControl. The control makes the cross process UI emmbedding required by applets possible.

## Details

### struct MatePanelApplet

    struct MatePanelApplet;

The MatePanelApplet struct contains private data only.

### enum MatePanelAppletOrient

    typedef enum {
    	MATE_PANEL_APPLET_ORIENT_UP,
    	MATE_PANEL_APPLET_ORIENT_DOWN,
    	MATE_PANEL_APPLET_ORIENT_LEFT,
    	MATE_PANEL_APPLET_ORIENT_RIGHT
    } MatePanelAppletOrient;

The MatePanelAppletOrient type specifies the orientation of the applet. The values may seem backward (e.g. `MATE_PANEL_APPLET_ORIENT_LEFT` means the panel is on the right hand side), but this is because the value is representative of the applet's orientation, not the panel's position.

### enum MatePanelAppletBackgroundType

    typedef enum {
    	PANEL_NO_BACKGROUND,
    	PANEL_COLOR_BACKGROUND,
    	PANEL_PIXMAP_BACKGROUND
    } MatePanelAppletBackgroundType;

The MatePanelAppletBackgroundType enumerated type specifies the type of background of a panel.

`PANEL_NO_BACKGROUND` | The panel has no background, the default is used.
`PANEL_COLOR_BACKGROUND` | The panel has a color, i.e rgb value, background.
`PANEL_PIXMAP_BACKGROUND` | The panel has either an image background or is translucent.

### enum MatePanelAppletFlags

    typedef enum {
    	MATE_PANEL_APPLET_FLAGS_NONE   = 0,
    	MATE_PANEL_APPLET_EXPAND_MAJOR = 1 << 0,
    	MATE_PANEL_APPLET_EXPAND_MINOR = 1 << 1,
    	MATE_PANEL_APPLET_HAS_HANDLE   = 1 << 2
    } MatePanelAppletFlags;

The MatePanelAppletFlags associated with the applet are boolean flags which the panel may read in order to figure out how to handle the applet.

`MATE_PANEL_APPLET_FLAGS_NONE` | No flags are to be associated with the applet.
`MATE_PANEL_APPLET_EXPAND_MAJOR` | The applet should expand horizontally on an horizontal panel and vertically on a vertical panel - e.g. the behaviour of the Window List applet.
`MATE_PANEL_APPLET_EXPAND_MINOR` | The applet should expand vertically on an horizontal panel and horizontally on a vertical panel. Most applets should set this flag in order to utilise the full panel width and allow the applet to be Fitt's Law compliant.
`MATE_PANEL_APPLET_HAS_HANDLE` | The panel should draw a grab handle around the applet - e.g. the Window List and Notification Area applets both set this flag.

### MatePanelAppletFactoryCallback ()

    gboolean            (*MatePanelAppletFactoryCallback)       (MatePanelApplet *applet,
                                                             const gchar *iid,
                                                             gpointer user_data);

This callback is invoked when the applet is loaded onto the panel. Typically the callback will check that `iid` matches and fill the `applet` with the widgets which make up the applet.

Prior to the callback being invoked the MatePanelApplet (or an instance of the sub-class specified by the GType passed to the factory macros) is instantiated and initialized.

`applet` : | The MatePanelApplet.
`iid` : | The MateComponent IID of the applet requested.
`user_data` : | The data passed to the factory macros.
Returns : | `TRUE` on success, `FALSE` on failure.

### mate_panel_applet_new ()

    GtkWidget *         mate_panel_applet_new                    (void);

Creates a new MatePanelApplet. This function is typically not useful as the applet is created before the MatePanelAppletFactoryCallback is invoked.

Returns : | The MatePanelApplet.

### mate_panel_applet_get_orient ()

    MatePanelAppletOrient   mate_panel_applet_get_orient             (MatePanelApplet *applet);

Get the current orientation of the applet.

`applet` : | The MatePanelApplet.
Returns : | The orientation of the applet.

### mate_panel_applet_get_size ()

    guint               mate_panel_applet_get_size               (MatePanelApplet *applet);

Get the current size hint for the panel. The size hint is not useful for most applets.

Note: The return value is not an integer value specifying the pixel size of the panel. Do not use this value to calculate the size of the applet. Use it only as a hint by which to decide the applet's layout.

`applet` : | The MatePanelApplet.
Returns : | The panel's size hint.

### mate_panel_applet_get_background ()

    MatePanelAppletBackgroundType  mate_panel_applet_get_background  (MatePanelApplet *applet,
                                                             GdkColor *color,
                                                             GdkPixmap **pixmap);

Returns the current background type. If the background type is `PANEL_NO_BACKGROUND` both `color` and `pixmap` will be unaffected. If the background type is `PANEL_COLOR_BACKGROUND` then `color` will contain the current panel background colour. If the background type is `PANEL_PIXMAP_BACKGROUND`, `pixmap` will contain a pointer to a GdkPixmap which is a copy of the applet's portion of the panel's background pixmap.

`applet` : | A MatePanelApplet.
`color` : | A GdkColor to be filled in.
`pixmap` : | Returned GdkPixmap.
Returns : | The background type.

### mate_panel_applet_get_preferences_key ()

    gchar *             mate_panel_applet_get_preferences_key    (MatePanelApplet *applet);

Returns the MateConf path to the directory containing the applet's per-instance preference keys. Using this you may construct the full path for the applet's preference keys. See Panel Applet MateConf Utilities(3) for more information.

`applet` : | The MatePanelApplet.
Returns : | A MateConf path.

### mate_panel_applet_add_preferences ()

    void                mate_panel_applet_add_preferences        (MatePanelApplet *applet,
                                                             const gchar *schema_dir,
                                                             GError **opt_error);

Associates each schema in `schema_dir` with a key in the applet's preferences directory (i.e. the directory returned by `mate_panel_applet_get_preferences_key()`). Each applet preference should have an associated schema to ensure that the key has a defined type, sane default and documentation.

If you pass `NULL` for `opt_error`, this function will print a warning message from any GError which MateConf may return.

`applet` : | The MatePanelApplet.
`schema_dir` : | The MateConf path where the applet's schemas are installed e.g. /schemas/apps/my_applet
`opt_error` : | Optional GError.

### mate_panel_applet_get_flags ()

    MatePanelAppletFlags    mate_panel_applet_get_flags              (MatePanelApplet *applet);

Retrieve the MatePanelAppletFlags associated with the applet.

`applet` : | The MatePanelApplet.
Returns : | The MatePanelAppletFlags.

### mate_panel_applet_set_flags ()

    void                mate_panel_applet_set_flags              (MatePanelApplet *applet,
                                                             MatePanelAppletFlags flags);

Set the MatePanelAppletFlags associated with the applet. See MatePanelAppletFlags for more details on the possible uses of these flags.

`applet` : | The MatePanelApplet.
`flags` : | The MatePanelAppletFlags to associate.

### mate_panel_applet_set_size_hints ()

    void                mate_panel_applet_set_size_hints         (MatePanelApplet *applet,
                                                             const int *size_hints,
                                                             int n_elements,
                                                             int base_size);

Set a list of desired size ranges for an applet with the MATE_PANEL_APPLET_EXPAND_MAJOR flags set. `size_hints` is an array of (max, min) pairs where min(i) > max(i + 1).

The panel will endeavour to allocate the applet a size in one of the (`base` + max, `base` + min) ranges.

`applet` : | The MatePanelApplet.
`size_hints` : | Array of size_hints.
`n_elements` : | Number of elements in the array. Not the number of pairs.
`base_size` : | The base size of the applet.

### mate_panel_applet_get_locked_down ()

    gboolean            mate_panel_applet_get_locked_down        (MatePanelApplet *applet);

Check if the `applet` is locked down. A locked down applet should not allow any change to its configuration.

`applet` : | The MatePanelApplet.
Returns : | `TRUE` if the `applet` is locked down, `FALSE` otherwise.

### mate_panel_applet_request_focus ()

    void                mate_panel_applet_request_focus          (MatePanelApplet *applet,
                                                             guint32 timestamp);

Set keyboard focus to `applet`.

`applet` : | The MatePanelApplet.
`timestamp` : | timestamp of the event triggering the window focus

### mate_panel_applet_setup_menu ()

    void                mate_panel_applet_setup_menu             (MatePanelApplet *applet,
                                                             const gchar *xml,
                                                             GtkActionGroup *action_group);

Sets up a popup menu for `applet` described by the xml string, `xml`. See Writing Applets section for a description of the format of the xml.

`applet` : | A MatePanelApplet.
`xml` : | The xml character string describing the popup menu.
`action_group` : |

### mate_panel_applet_setup_menu_from_file ()

    void                mate_panel_applet_setup_menu_from_file   (MatePanelApplet *applet,
                                                             const gchar *filename,
                                                             GtkActionGroup *action_group);

Sets up a popup menu for `applet` described by the xml file, `file`. See Writing Applets for a description of the format of the xml.

`applet` : | A MatePanelApplet.
`filename` : |
`action_group` : |

### mate_panel_applet_factory_main ()

    int                 mate_panel_applet_factory_main           (const gchar *factory_id,
                                                             gboolean out_process,
                                                             GType applet_type,
                                                             MatePanelAppletFactoryCallback callback,
                                                             gpointer data);

A generic 'main' routine for applets. This should not normally be used directly because it is invoked by MATE_PANEL_APPLET_MATECOMPONENT_FACTORY.

`factory_id` : |
`out_process` : |
`applet_type` : | The GType to instantiate.
`callback` : | The factory callback.
`data` : | The factory user data pointer.
Returns : | 0 on success, 1 on failure.

## Property Details

### The `"background"` property

      "background"               gchar*                : Read / Write

Panel Applet Background.

Default value: NULL

### The `"closure"` property

      "closure"                  gpointer              : Read / Write / Construct Only

The Applet closure.

### The `"connection"` property

      "connection"               GDBusConnection*      : Read / Write / Construct Only

The DBus Connection.

### The `"flags"` property

      "flags"                    guint                 : Read / Write

Panel Applet flags.

Default value: 0

### The `"id"` property

      "id"                       gchar*                : Read / Write / Construct Only

The Applet identifier.

Default value: NULL

### The `"locked"` property

      "locked"                   gboolean              : Read / Write

Whether Panel Applet is locked.

Default value: FALSE

### The `"locked-down"` property

      "locked-down"              gboolean              : Read / Write

Whether Panel Applet is locked down.

Default value: FALSE

### The `"orient"` property

      "orient"                   guint                 : Read / Write

Panel Applet Orientation.

Default value: 0

### The `"prefs-key"` property

      "prefs-key"                gchar*                : Read / Write

MateConf Preferences Key.

Default value: NULL

### The `"size"` property

      "size"                     guint                 : Read / Write

Panel Applet Size.

Default value: 0

### The `"size-hints"` property

      "size-hints"               gpointer              : Read / Write

Panel Applet Size Hints.

## Signal Details

### The `"change-background"` signal

    void                user_function                      (MatePanelApplet              *matepanelapplet,
                                                            MatePanelAppletBackgroundType arg1,
                                                            GdkColor                 *arg2,
                                                            GdkPixmap                *arg3,
                                                            gpointer                  user_data)        : Run Last

Emitted when the background of the panel changes. Use `type` to determine which, if any, of `color` and `pimxap` is valid.

`matepanelapplet` : | The object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`user_data` : | user data set when the signal handler was connected.

### The `"change-orient"` signal

    void                user_function                      (MatePanelApplet *matepanelapplet,
                                                            guint        arg1,
                                                            gpointer     user_data)        : Run Last

Emitted when the orientation of the panel changes.

`matepanelapplet` : | The object which received the signal.
`orient` : | The new MatePanelAppletOrient of the applet.
`user_data` : | user data set when the signal handler was connected.

### The `"change-size"` signal

    void                user_function                      (MatePanelApplet *matepanelapplet,
                                                            gint         arg1,
                                                            gpointer     user_data)        : Run Last

Emitted when the size of the panel changes.

Note: this is different for size negotiation which is handled by `size_request()` and `size_allocate()` as usual. This signal should be used to determine what font size or widget layout to use depending on the size of the panel. See `mate_panel_applet_get_size()`.

`matepanelapplet` : | The object which received the signal.
`size` : | The size hint of the panel.
`user_data` : | user data set when the signal handler was connected.

### The `"move-focus-out-of-applet"` signal

    void                user_function                      (MatePanelApplet     *matepanelapplet,
                                                            GtkDirectionType arg1,
                                                            gpointer         user_data)        : Action

Emitted when the applet has lost focus. This signal is used internally and is not meant to be used by applets themselves.

`matepanelapplet` : | The object which received the signal.
`direction` : | The direction of focus movement.
`user_data` : | user data set when the signal handler was connected.