action-publisher

action-publisher — Publish action data to the HUD

Stability Level

Stable, unless otherwise indicated

Functions

Signals

void action-group-added Run Last
void action-group-removed Run Last
void changed Has Details

Types and Values

Object Hierarchy

    GObject
    ├── HudActionDescription
    ╰── HudActionPublisher

Includes

#include <libhud/action-publisher.h>

Description

Each context in the application should have a HudActionPublisher object to represents the actions that are available to the user when that window and context are visible. This acts as a set of actions that can be activated by either the window manager changing focus or the application changing contexts.

On each action publisher there exits several action groups which can be separated by allowing different prefixes for those action groups. A particular prefix should only be used once per action publisher, but an action group can by used by several action publishers.

The values describing the action, including the label and description that show up in the HUD are set via creating a HudActionDescription for a action. Each action can have more than one description if there is a reason to do so. But, it is probably better to use the keywords attribute in the majority cases.

Functions

HUD_ACTION_PUBLISHER_NO_CONTEXT

#define HUD_ACTION_PUBLISHER_NO_CONTEXT                     (NULL)

Can be passed to hud_action_publisher_new() to request that it build it's own context.


HUD_ACTION_PUBLISHER_ALL_WINDOWS

#define HUD_ACTION_PUBLISHER_ALL_WINDOWS                    (0)

Can be passed to hud_action_publisher_new() to request that these actions apply to all windows for the application.


hud_action_publisher_new ()

HudActionPublisher *
hud_action_publisher_new (guint window_id,
                          const gchar *context_id);

Creates a new HudActionPublisher based on the window ID passed in via window_id and context ID from context_id .

Either one of them can be not used by passing in eithe of the defines HUD_ACTION_PUBLISHER_ALL_WINDOWS or HUD_ACTION_PUBLISHER_NO_CONTEXT for the appropriate parameter.

Parameters

window_id

A window ID.

[allow-none]

context_id

A context ID.

[allow-none]

Returns

A new HudActionPublisher object.

[transfer full]


hud_action_publisher_new_for_application ()

HudActionPublisher *
hud_action_publisher_new_for_application
                               (GApplication *application);

Creates a new HudActionPublisher and automatically registers the default actions under the "app" prefix.

Parameters

application

A GApplication object

 

Returns

A new HudActionPublisher object.

[transfer full]


hud_action_publisher_add_description ()

void
hud_action_publisher_add_description (HudActionPublisher *publisher,
                                      HudActionDescription *description);

Adds description to the list of actions that the application exports to the HUD.

If the application is already exporting an action with the same name and target value as description then it will be replaced.

You should only use this API for situations like recent documents and bookmarks.

Parameters

publisher

the HudActionPublisher

 

description

an action description

 

hud_action_publisher_add_action_group ()

void
hud_action_publisher_add_action_group (HudActionPublisher *publisher,
                                       const gchar *prefix,
                                       const gchar *object_path);

Informs the HUD of the existance of an action group.

The action group must be published on the shared session bus connection of this process at object_path .

The prefix defines the type of action group. Currently "app" and "win" are supported. For example, if the exported action group contained a "quit" action and you wanted to refer to it as "app.quit" from action descriptions, then you would use the prefix "app" here.

identifier is a piece of identifying information, depending on which prefix is used. Currently, this should be NULL for the "app" prefix and should be a uint32 specifying the window ID (eg: XID) for the "win" prefix .

You do not need to manually export your action groups if you are using GApplication.

Parameters

publisher

a HudActionPublisher

 

prefix

the action prefix for the group (like "app")

 

object_path

the object path of the exported group

 

hud_action_publisher_remove_action_group ()

void
hud_action_publisher_remove_action_group
                               (HudActionPublisher *publisher,
                                const gchar *prefix,
                                GVariant *identifier);

Informs the HUD that an action group no longer exists.

This reverses the effect of a previous call to hud_action_publisher_add_action_group() with the same parameters.

Parameters

publisher

a HudActionPublisher

 

prefix

the action prefix for the group (like "app")

 

identifier

an identifier, or NULL.

[allow-none]

hud_action_publisher_get_window_id ()

guint
hud_action_publisher_get_window_id (HudActionPublisher *publisher);

Gets the window ID for this publisher

Parameters

publisher

A HudActionPublisher object

 

Returns

The Window ID associtaed with this action publisher


hud_action_publisher_get_context_id ()

const gchar *
hud_action_publisher_get_context_id (HudActionPublisher *publisher);

Gets the context ID for this publisher

Parameters

publisher

A HudActionPublisher object

 

Returns

The context ID associtaed with this action publisher


hud_action_publisher_get_action_groups ()

GList *
hud_action_publisher_get_action_groups
                               (HudActionPublisher *publisher);

Grabs the action groups for this publisher

Parameters

publisher

A HudActionPublisher object

 

Returns

The groups in this publisher.

[transfer container][element-type HudActionPublisherActionGroupSet *]


hud_action_publisher_get_description_path ()

const gchar *
hud_action_publisher_get_description_path
                               (HudActionPublisher *publisher);

Grabs the object path of the description for this publisher

Parameters

publisher

A HudActionPublisher object

 

Returns

The object path of the descriptions


hud_action_description_new ()

HudActionDescription *
hud_action_description_new (const gchar *action_name,
                            GVariant *action_target);

Creates a new HudActionDescription.

The situations in which you want to do this are limited to "dynamic" types of actions -- things like bookmarks or recent documents.

Use hud_action_publisher_add_descriptions_from_file() to take care of the bulk of the actions in your application.

Parameters

action_name

a (namespaced) action name

 

action_target

an action target

 

Returns

a new HudActionDescription with no attributes


hud_action_description_ref ()

HudActionDescription *
hud_action_description_ref (HudActionDescription *description);

Increase the reference count to an action description

Parameters

description

A HudActionDescription

 

Returns

Value of description .

[transfer none]


hud_action_description_unref ()

void
hud_action_description_unref (HudActionDescription *description);

Decrease the reference count to an action description

Parameters

description

A HudActionDescription

 

hud_action_description_get_action_name ()

const gchar *
hud_action_description_get_action_name
                               (HudActionDescription *description);

Gets the action name of description .

This, together with the action target, uniquely identify an action description.

Parameters

description

a HudActionDescription

 

Returns

the action name.

[transfer none]


hud_action_description_get_action_target ()

GVariant *
hud_action_description_get_action_target
                               (HudActionDescription *description);

Gets the action target of description (ie: the GVariant that will be passed to invocations of the action).

This may be NULL.

This, together with the action name, uniquely identify an action description.

Parameters

description

a HudActionDescription

 

Returns

the target value.

[transfer none]


hud_action_description_set_attribute_value ()

void
hud_action_description_set_attribute_value
                               (HudActionDescription *description,
                                const gchar *attribute_name,
                                GVariant *value);

Sets or unsets an attribute on description .

You may not change the "action" or "target" attributes.

If value is non-NULL then it is the new value for attribute. A NULL value unsets attribute_name .

value is consumed if it is floating.

Parameters

description

a HudActionDescription

 

attribute_name

an attribute name

 

value

the new value for the attribute.

[allow-none]

hud_action_description_set_attribute ()

void
hud_action_description_set_attribute (HudActionDescription *description,
                                      const gchar *attribute_name,
                                      const gchar *format_string,
                                      ...);

Sets or unsets an attribute on description .

You may not change the "action" or "target" attributes.

If format_string is non-NULL then this call is equivalent to g_variant_new() and hud_action_description_set_attribute_value().

If format_string is NULL then this call is equivalent to hud_action_description_set_attribute_value() with a NULL value.

Parameters

description

a HudActionDescription

 

attribute_name

an attribute name

 

format_string

a GVariant format string.

[allow-none]

...

arguments to format_string

 

hud_action_description_set_parameterized ()

void
hud_action_description_set_parameterized
                               (HudActionDescription *parent,
                                GMenuModel *child);

A function to put one action description as a child for the first one. This is used for parameterized actions where one can set up children that are displayed on the 'dialog' mode of the HUD.

Parameters

parent

a HudActionDescription

 

child

The child GMenuModel to add

 

Types and Values

HUD_ACTION_PUBLISHER_SIGNAL_ACTION_GROUP_ADDED

#define HUD_ACTION_PUBLISHER_SIGNAL_ACTION_GROUP_ADDED      "action-group-added"

Define for the string to access the signal HudActionPublisher::action-group-added


HUD_ACTION_PUBLISHER_SIGNAL_ACTION_GROUP_REMOVED

#define HUD_ACTION_PUBLISHER_SIGNAL_ACTION_GROUP_REMOVED    "action-group-removed"

Define for the string to access the signal HudActionPublisher::action-group-removed


struct HudActionPublisherActionGroupSet

struct HudActionPublisherActionGroupSet {
	gchar * prefix;
	gchar * path;
};

A set of properties of that describe the action group.

Members

gchar *prefix;

Action prefix for the action group

 

gchar *path;

Path that the action group is exported on DBus

 

HudActionPublisher

typedef struct _HudActionPublisher HudActionPublisher;

An object representing the actions that are published for a particular context within the application. Most often this is a window, but could also be used for tabs or other modal style user contexts in the application.

Signal Details

The “action-group-added” signal

void
user_function (HudActionPublisher *param1,
               gchar              *param2,
               gchar              *arg2,
               gpointer            user_data)

Emitted when a new action group is added to the publisher

Parameters

param1

Prefix for the action group

 

param2

Path group is exported on DBus

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “action-group-removed” signal

void
user_function (HudActionPublisher *param1,
               gchar              *param2,
               gchar              *arg2,
               gpointer            user_data)

Emitted when a new action group is removed from the publisher

Parameters

param1

Prefix for the action group

 

param2

Path group is exported on DBus

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “changed” signal

void
user_function (HudActionDescription *param1,
               gchar                *arg1,
               gpointer              user_data)

Flags: Has Details