GtkHotkeyInfo

GtkHotkeyInfo — Primary representation of a hotkey

Synopsis




                    GtkHotkeyInfoPrivate;
                    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"           gchararray            : Read / Write / Construct Only
  "bound"                    gboolean              : Read
  "description"              gchararray            : Read / Write
  "key-id"                   gchararray            : Read / Write / Construct Only
  "signature"                gchararray            : 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

GtkHotkeyInfoPrivate

typedef struct _GtkHotkeyInfoPrivate GtkHotkeyInfoPrivate;


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 GtkHotkeyInfo::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 GtkHotkeyInfo::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 GtkHotkeyInfo: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 GtkHotkeyInfo: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 GtkHotkeyInfo: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 GtkHotkeyInfo: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 GtkHotkeyInfo:description and GtkHotkeyInfo: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 GtkHotkeyInfo:description and GtkHotkeyInfo: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 GtkHotkeyInfo::activated signal on a hotkey. Mainly called by GtkHotkeyListener implementations. This method should not normally be used by applications.

self : GtkHotkeyInfo to emit the GtkHotkeyInfo::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"           gchararray            : 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 GtkHotkeyInfo::activated signals when the hotkey is triggered by the user.

Default value: FALSE


The "description" property

  "description"              gchararray            : Read / Write

An optional free form description of the hotkey.

Default value: ""


The "key-id" property

  "key-id"                   gchararray            : 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"                gchararray            : 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