GtkHotkeyInfo

GtkHotkeyInfo — Primary representation of a hotkey

Synopsis

                    GtkHotkeyInfo;
gboolean            gtk_hotkey_info_bind                (GtkHotkeyInfo *self,
                                                         GError **error);
gboolean            gtk_hotkey_info_unbind              (GtkHotkeyInfo *self,
                                                         GError **error);
const gchar*        gtk_hotkey_info_get_application_id  (GtkHotkeyInfo *self);
const gchar*        gtk_hotkey_info_get_key_id          (GtkHotkeyInfo *self);
GAppInfo*           gtk_hotkey_info_get_app_info        (GtkHotkeyInfo *self);
const gchar*        gtk_hotkey_info_get_signature       (GtkHotkeyInfo *self);
const gchar*        gtk_hotkey_info_get_description     (GtkHotkeyInfo *self);
void                gtk_hotkey_info_set_description     (GtkHotkeyInfo *self,
                                                         const gchar *description);
gboolean            gtk_hotkey_info_equals              (GtkHotkeyInfo *hotkey1,
                                                         GtkHotkeyInfo *hotkey2,
                                                         gboolean sloppy_equals);
void                gtk_hotkey_info_activated           (GtkHotkeyInfo *self,
                                                         guint event_time);
GtkHotkeyInfo*      gtk_hotkey_info_new                 (const gchar *app_id,
                                                         const gchar *key_id,
                                                         const gchar *signature,
                                                         GAppInfo *app_info);

Object Hierarchy

  GObject
   +----GtkHotkeyInfo

Properties

  "app-info"                 GAppInfo*             : Read / Write / Construct Only
  "application-id"           gchar*                : Read / Write / Construct Only
  "bound"                    gboolean              : Read
  "description"              gchar*                : Read / Write
  "key-id"                   gchar*                : Read / Write / Construct Only
  "signature"                gchar*                : Read / Write / Construct Only

Signals

  "activated"                                      : Run Last

Description

GtkHotkeyInfo is the primary object around which the GtkHotkey library revolves.

Hotkeys are stored and managed via a GtkHotkeyRegistry, while the actual binding and listening for key-presses is done by a GtkHotkeyListener.

Details

GtkHotkeyInfo

typedef struct _GtkHotkeyInfo GtkHotkeyInfo;


gtk_hotkey_info_bind ()

gboolean            gtk_hotkey_info_bind                (GtkHotkeyInfo *self,
                                                         GError **error);

Register the hotkey with the system. The "activated" signal will now be emitted when the user presses the keyboard combination matching the hotkey's signature.

self :

The hotkey to bind

error :

Place to return a GError, or NULL to ignore

Returns :

TRUE on success, and FALSE on error in which case error is also set

gtk_hotkey_info_unbind ()

gboolean            gtk_hotkey_info_unbind              (GtkHotkeyInfo *self,
                                                         GError **error);

Remove the hotkey binding from the system. The "activated" signal will no longer be emitted when the hotkey is pressed.

self :

The hotkey to unbind

error :

Place to return a GError, or NULL to ignore

Returns :

TRUE on success, and FALSE on error in which case error is also set

gtk_hotkey_info_get_application_id ()

const gchar*        gtk_hotkey_info_get_application_id  (GtkHotkeyInfo *self);

Get the unique system identifier for the hotkey. See "application-id" for details.

self :

Returns :


gtk_hotkey_info_get_key_id ()

const gchar*        gtk_hotkey_info_get_key_id          (GtkHotkeyInfo *self);

Get the identifier the owning application use to identify this hotkey. See "key-id" for details.

self :

Returns :


gtk_hotkey_info_get_app_info ()

GAppInfo*           gtk_hotkey_info_get_app_info        (GtkHotkeyInfo *self);

Not to be confused with the value of the "application-id" property. The hotkey can be associated with an installed desktop application via a GAppInfo. This is not mandatory and this method returns NULL if no desktop application has been associated with this hotkey.

See the "app-info" property for details.

self :

Returns :


gtk_hotkey_info_get_signature ()

const gchar*        gtk_hotkey_info_get_signature       (GtkHotkeyInfo *self);

Get the keyboard signature of the hotkey. This could for example be '<Alt>F3' or '<Control><Shift>G'.

self :

Returns :


gtk_hotkey_info_get_description ()

const gchar*        gtk_hotkey_info_get_description     (GtkHotkeyInfo *self);

Get the free form description of the hotkey. The description is not guaranteed to be set and may be NULL.

FIXME: Do we need to take i18n into account here?

self :

Returns :

The description of the hotkey or NULL if none is set

gtk_hotkey_info_set_description ()

void                gtk_hotkey_info_set_description     (GtkHotkeyInfo *self,
                                                         const gchar *description);

Set a description for the hotkey. See also gtk_hotkey_info_get_description().

self :

description :


gtk_hotkey_info_equals ()

gboolean            gtk_hotkey_info_equals              (GtkHotkeyInfo *hotkey1,
                                                         GtkHotkeyInfo *hotkey2,
                                                         gboolean sloppy_equals);

Compare two GtkHotkeyInfos to see if they are equal. This method allows an optional 'sloppy equality' which ignores "description" and "app-info".

hotkey1 :

The first hotkey to compare

hotkey2 :

Second hotkey to compare to

sloppy_equals :

If TRUE sloppy equality will be used. This ignores the "description" and "app-info" properties of the objects.

Returns :

TRUE if all the properties of the hotkeys match. Two NULL hotkeys are also considered equal.

gtk_hotkey_info_activated ()

void                gtk_hotkey_info_activated           (GtkHotkeyInfo *self,
                                                         guint event_time);

Emit the "activated" signal on a hotkey. Mainly called by GtkHotkeyListener implementations. This method should not normally be used by applications.

self :

GtkHotkeyInfo to emit the "activated" signal

event_time :

The system time the event happened on. This is useful for applications to pass through focus stealing prevention when mapping windows

gtk_hotkey_info_new ()

GtkHotkeyInfo*      gtk_hotkey_info_new                 (const gchar *app_id,
                                                         const gchar *key_id,
                                                         const gchar *signature,
                                                         GAppInfo *app_info);

Create a new hotkey. To actually trigger the hotkey when the user enters the right keyboard combination call gtk_hotkey_info_bind(). To save and load your hotkey settings use the GtkHotkeyRegistry provided by gtk_hotkey_registry_get_default().

app_id :

Unique identifier the running application can choose for it self. May be a free form string, but a descriptive name is encouraged

key_id :

A key the application uses to recognize the hotkey. May be a free form string, but a descriptive name is encouraged

signature :

A key press signature parsable by gtk_accelerator_parse(). For examplpe '<Alt>F3' or '<Control><Shift>G'.

app_info :

An optional GAppInfo to associate with the hotkey. Pass NULL to ignore this

Returns :

A new GtkHotkeyInfo or NULL on error. Error conditions could for example be invalid an invalid signature, or NULL arguments.

Property Details

The "app-info" property

  "app-info"                 GAppInfo*             : Read / Write / Construct Only

A GAppInfo associated with the key. This is mainly useful for external applications which can use the information provided by the GAppInfo to display meaningful messages to the user. Like 'The keyboard combination <Alt>F3' is already assigned to the application "Deskbar Applet", please select another'.


The "application-id" property

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

A free form string chosen by the application using the hotkey, under which the application identifies itself.

Default value: NULL


The "bound" property

  "bound"                    gboolean              : Read

Property reflecting whether or not this hotkey has been bound to a GtkHotkeyListener. If this property is TRUE you will receive "activated" signals when the hotkey is triggered by the user.

Default value: FALSE


The "description" property

  "description"              gchar*                : Read / Write

An optional free form description of the hotkey.

Default value: ""


The "key-id" property

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

A free form string the application using the hotkey has attributed the hotkey so that it can be identified later on. Applications are encouraged to choose descriptive key ids.

Default value: NULL


The "signature" property

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

The keyboard signature of the hotkey. This could for example by '<Alt>F3' or '<Control><Shift>G'. The signature should be parsable by gtk_accelerator_parse().

Default value: NULL

Signal Details

The "activated" signal

void                user_function                      (GtkHotkeyInfo *hotkey,
                                                        guint          event_time,
                                                        gpointer       user_data)       : Run Last

Emitted when a hotkey has been activated.

hotkey :

a GtkHotkeyInfo for the hotkey that was activated

event_time :

Time for event triggering the keypress. This is mainly used to pass to window management functions to pass through focus stealing prevention

user_data :

user data set when the signal handler was connected.

See Also

#GtkHotkeyRegistry