BudgieApplet: budgie-desktop Reference Manual

## BudgieApplet BudgieApplet — Budgie Panel GTK+ Widget |

## Functions

BudgieApplet * | budgie_applet_new ()
void | budgie_applet_invoke_action ()
gboolean | budgie_applet_supports_settings ()
GtkWidget * | budgie_applet_get_settings_ui ()
GSettings * | budgie_applet_get_applet_settings ()
void | budgie_applet_set_settings_schema ()
const gchar * | budgie_applet_get_settings_schema ()
void | budgie_applet_set_settings_prefix ()
const gchar * | budgie_applet_get_settings_prefix ()
void | budgie_applet_update_popovers ()
BudgiePanelAction | budgie_applet_get_supported_actions ()

## Properties

char * | settings-prefix | Read / Write
char * | settings-schema | Read / Write
BudgiePanelAction | supported-actions | Read / Write

## Signals

void | panel-position-changed | Action
void | panel-size-changed | Action

## Types and Values

#define | BUDGIE_APPLET_KEY_NAME
#define | BUDGIE_APPLET_KEY_ALIGN
#define | BUDGIE_APPLET_KEY_POS
enum | BudgiePanelAction
enum | BudgiePanelPosition
struct | BudgieAppletClass

## Object Hierarchy

        GFlags
        ├── BudgiePanelAction
        ╰── BudgiePanelPosition
        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkEventBox
                            ╰── BudgieApplet

## Description

The BudgieApplet is the main event when it comes to providing a Budgie Panel extension. This is the widget that is visible to the user, and is provided by, and instaniated by, your BudgiePlugin.

Those implementing applets have a specific API available to them in order to achieve better integration with the overall desktop. At the bare minimum you should at least ensure that your applet respects the sizes exposed by the managing panel, via the “panel-size-changed” signal.

BudgieApplet extends GtkEventBox to leave you free to make your own choices on internal applet layout and configuration. Do note, however, that the panel implementation will not call gtk_widget_show_all, it is solely your responsibility to ensure all of your contents are displayed. This is to enable applet's to contextually hide part of their user interface when required.

## Functions

### budgie_applet_new ()

    BudgieApplet *
    budgie_applet_new (void);

#### Returns

A new BudgieApplet.

[transfer full]

### budgie_applet_invoke_action ()

    void
    budgie_applet_invoke_action (BudgieApplet *self,
                                 BudgiePanelAction action);

Invoke the given action on this applet. This action will only be one that has been declared in supported actions bitmask.

To allow better integration between the Budgie Desktop, and the applets that live within it, the panel will relay actions to applets that have set their “supported-actions” to a matching bitmask.

For example, if we wish to listen for Menu Key events, we can simply do the following in C:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    static void my_applet_invoke_action(BudgieApplet *applet, BudgiePanelAction action)
    {
            if (action == BUDGIE_PANEL_ACTION_MENU) {
                    my_applet_do_predict_the_lottery(MY_APPLET(applet));
            }
    }

    static void my_class_init(GObjectClass *class)
    {
            MyClass *mc = MY_CLASS(klass);
            ..
            mc->invoke_action = my_applet_invoke_action;
    }

Likewise, a Vala implementation might look like the following:

    1
    2
    3
    4
    5
    6
    public override void invoke_action(Budgie.PanelAction action)
    {
        if (action == Budgie.PanelAction.MENU) {
            this.predict_the_lottery();
        }
    }

#### Parameters

action | Action to invoke |

### budgie_applet_supports_settings ()

    gboolean
    budgie_applet_supports_settings (BudgieApplet *self);

Implementations should override this to return TRUE if they support a settings UI

#### Returns

true if this implementation supports a Settings UI

### budgie_applet_get_settings_ui ()

    GtkWidget *
    budgie_applet_get_settings_ui (BudgieApplet *self);

For applets that need to expose settings, they should both override the “supports_settings” method and return a new widget instance whenever this function is invoked.

This UI will live in the Raven sidebar within the Budgie Desktop, and will be destroyed as soon as it's not being used. It's advisable to keep this widget implementation light, and to prefer vertical space.

#### Returns

A GTK Settings UI.

[transfer full][nullable]

### budgie_applet_get_applet_settings ()

    GSettings *
    budgie_applet_get_applet_settings (BudgieApplet *self,
                                       gchar *uuid);

If your BudgiePlugin implementation passes the UUID to your BudgieApplet implementation on construction, you can take advantage of per-instance settings.

For most applets, global GSettings keys are more than suffice. However, in some situations, it may be beneficial to enable multiple unique instances of your applet, each with their own configuration.

To facilitate this, use this function to create a new relocatable settings instance using your UUID. Make sure you set the “settings-schema” and “settings-prefix” properties first.

#### Parameters

uuid | UUID for this instance |

#### Returns

A newly created GSettings for this applet instance.

[transfer full]

### budgie_applet_set_settings_schema ()

    void
    budgie_applet_set_settings_schema (BudgieApplet *self,
                                       const gchar *schema);

Utility function for Python usage. See “settings-schema”

### budgie_applet_get_settings_schema ()

    const gchar *
    budgie_applet_get_settings_schema (BudgieApplet *self);

Utility function for Python usage. See “settings-schema”

### budgie_applet_set_settings_prefix ()

    void
    budgie_applet_set_settings_prefix (BudgieApplet *self,
                                       const gchar *prefix);

Utility function for Python usage. See: “settings-prefix”

### budgie_applet_get_settings_prefix ()

    const gchar *
    budgie_applet_get_settings_prefix (BudgieApplet *self);

Utility function for Python usage. See: “settings-prefix”

### budgie_applet_update_popovers ()

    void
    budgie_applet_update_popovers (BudgieApplet *self,
                                   BudgiePopoverManager *manager);

This virtual method should be implemented by panel applets that wish to support GtkPopover's natively. As each Budgie Panel may house multiple GtkPopover widgets, each one must be registered with the `manager` .

During this call, it is safe to store a reference to the `manager` . In this call you should invoke “register_popover” to register your popover with the panel manager.

Each registered popover joins the global menu system of popovers in the panel. It is a requirement to register, otherwise the panel will not know when to expand and collapse the main panel harness to accommodate the GtkPopover.

#### Parameters

manager | . | [nullable]

### budgie_applet_get_supported_actions ()

    BudgiePanelAction
    budgie_applet_get_supported_actions (BudgieApplet *self);

Utility function for Python bindings. See “supported-actions”

## Types and Values

### BUDGIE_APPLET_KEY_NAME

    #define BUDGIE_APPLET_KEY_NAME "name"

### BUDGIE_APPLET_KEY_ALIGN

    #define BUDGIE_APPLET_KEY_ALIGN "alignment"

### BUDGIE_APPLET_KEY_POS

    #define BUDGIE_APPLET_KEY_POS "position"

### enum BudgiePanelAction

BudgiePanelAction's are bitwise OR'd so that a BudgieApplet may expose the actions that it supports, when the panel is interacted with in a global fashion (such as via the D-BUS API)

#### Members

BUDGIE_PANEL_ACTION_NONE |  |
BUDGIE_PANEL_ACTION_MENU | Invoke the menu action |
BUDGIE_PANEL_ACTION_MAX |  |

### enum BudgiePanelPosition

Each applet lives on a unique panel which can live on any one of the 4 screen edges. Internally this is represented with a bitmask to enable efficient screen management.

#### Members

BUDGIE_PANEL_POSITION_NONE | No position is yet assigned |
BUDGIE_PANEL_POSITION_BOTTOM | The bottom edge has been assigned |
BUDGIE_PANEL_POSITION_TOP | The top edge has been assigned |
BUDGIE_PANEL_POSITION_LEFT | The left edge has been assigned |
BUDGIE_PANEL_POSITION_RIGHT | The right edge has been assigned |

### struct BudgieAppletClass

    struct BudgieAppletClass {
    	GtkEventBoxClass parent_class;

    	void (*invoke_action)(BudgieApplet* self, BudgiePanelAction action);
    	gboolean (*supports_settings)(BudgieApplet* self);
    	GtkWidget* (*get_settings_ui)(BudgieApplet* self);
    	void (*panel_size_changed)(BudgieApplet* applet, int panel_size, int icon_size, int small_icon_size);
    	void (*panel_position_changed)(BudgieApplet* applet, BudgiePanelPosition position);
    	void (*update_popovers)(BudgieApplet* applet, BudgiePopoverManager* manager);

    	gpointer padding[12];
    };

#### Members

`invoke_action` () | Virtual invoke_action function |
`supports_settings` () | Virtual supports_settings function |
`get_settings_ui` () | Virtual get_settings_ui function |
`panel_size_changed` () | Virtual panel_size_changed function |
`panel_position_changed` () |  |
`update_popovers` () | Virtual update_popovers method |
gpointer `padding`[12]; |  |

## Property Details

### The `“settings-prefix”` property

      “settings-prefix”          char *

The GSettings schema path prefix for this applet

For applets that require unique instance configuration, the panel management must know where to initialise the settings within the tree. The path takes the form:

`$SETTINGS_PREFIX/{$UUID}`

As an example, the Budgie Menu Applet set's the `settings-prefix` to: `/com/solus-project/budgie-panel/instance/budgie-menu`.

This results in relocatable schemas being created at:

`/com/solus-project/budgie-panel/instance/budgie-menu/{$UUID}`

Owner: BudgieApplet

Flags: Read / Write

Default value: NULL

### The `“settings-schema”` property

      “settings-schema”          char *

The ID of the GSettings schema used by this applet

This only takes effect when you've also set “settings-prefix”, and is used by the panel managemen to both initialise and delete your per-instance settings, respectively.

As an example, the Budgie Menu Applet uses the schema:

`com.solus-project.budgie-menu`

as defined by the accompanying gschema XML file. Providing an incorrect schema ID is considered programmer error.

Owner: BudgieApplet

Flags: Read / Write

Default value: NULL

### The `“supported-actions”` property

      “supported-actions”        BudgiePanelAction

The actions supported by this applet instance

Owner: BudgieApplet

Flags: Read / Write

Default value: BUDGIE_PANEL_ACTION_NONE

## Signal Details

### The `“panel-position-changed”` signal

    void
    user_function (BudgieApplet       *applet,
                   BudgiePanelPosition position,
                   gpointer            user_data)

Used to notify this applet of a change in the panel's placement on screen, so that it may adjust its own layout to better suit the geometry.

#### Parameters

applet | The applet receiving the signal |
position | The new position (screen edge) |
user_data | user data set when the signal handler was connected. |

Flags: Action

### The `“panel-size-changed”` signal

    void
    user_function (BudgieApplet *applet,
                   int           panel_size,
                   int           icon_size,
                   int           small_icon_size,
                   gpointer      user_data)

Used to notify this applet of a change in the panel size

#### Parameters

applet | The applet receiving the signal |
panel_size | The new panel size |
icon_size | Larget possible icon size for the panel |
small_icon_size | Smaller icon that will still fit on the panel |
user_data | user data set when the signal handler was connected. |

Flags: Action