## GtkHotkeyListener

GtkHotkeyListener — Abstract base class providing platform independent hotkey listening capabilities

## Synopsis

                        GtkHotkeyListener;
    enum                GtkHotkeyListenerError;
    #define             GTK_HOTKEY_LISTENER_ERROR
    GtkHotkeyListener*  gtk_hotkey_listener_get_default     (void);
    void                gtk_hotkey_listener_activated       (GtkHotkeyListener *self,
                                                             GtkHotkeyInfo *hotkey,
                                                             guint event_time);
    gboolean            gtk_hotkey_listener_bind_hotkey     (GtkHotkeyListener *self,
                                                             GtkHotkeyInfo *hotkey,
                                                             GError **error);
    gboolean            gtk_hotkey_listener_unbind_hotkey   (GtkHotkeyListener *self,
                                                             GtkHotkeyInfo *hotkey,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GtkHotkeyListener

## Signals

      "activated"                                      : Run Last

## Description

GtkHotkeyListener is an abstract base class for implementing platform specific hotkey listeners - ie objects able to register when the user enters a certain keyboard combination, regardless of which window has focus.

Unless you have very special needs you should use the factory method `gtk_hotkey_listener_get_default()` to get a reference to a GtkHotkeyListener matching your platform. Although most applications will not need.

This class is part of the advanced API of GtkHotkey. Applications will not normally use a GtkHotkeyListener directly, since `gtk_hotkey_info_bind()` will call into `gtk_hotkey_listener_bind()` on the default listener for you.

## Details

### GtkHotkeyListener

    typedef struct _GtkHotkeyListener GtkHotkeyListener;

### enum GtkHotkeyListenerError

    typedef enum
    {
    	GTK_HOTKEY_LISTENER_ERROR_BIND,
    	GTK_HOTKEY_LISTENER_ERROR_UNBIND,
    } GtkHotkeyListenerError;

Error codes for GErrors related to GtkHotkeyListeners

`GTK_HOTKEY_LISTENER_ERROR_BIND` | An error occured when binding a hotkey with the listener
`GTK_HOTKEY_LISTENER_ERROR_UNBIND` | An error occured when unbinding a hotkey with the listener

### GTK_HOTKEY_LISTENER_ERROR

    #define GTK_HOTKEY_LISTENER_ERROR gtk_hotkey_listener_error_quark()

Error domain for GtkHotkeyListener.

### gtk_hotkey_listener_get_default ()

    GtkHotkeyListener*  gtk_hotkey_listener_get_default     (void);

Static factory method to get a reference to the default GtkHotkeyListener for the current platform.

FIXME: Currently hardcoded to X11

Returns : | A new reference to the default hotkey listener for the platform

### gtk_hotkey_listener_activated ()

    void                gtk_hotkey_listener_activated       (GtkHotkeyListener *self,
                                                             GtkHotkeyInfo *hotkey,
                                                             guint event_time);

Emit the "activated" signal on a hotkey listener.

`self` : | GtkHotkeyListener to emit the "activated" signal
`hotkey` : | The GtkHotkeyInfo the event happened for
`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_listener_bind_hotkey ()

    gboolean            gtk_hotkey_listener_bind_hotkey     (GtkHotkeyListener *self,
                                                             GtkHotkeyInfo *hotkey,
                                                             GError **error);

This method must be implemented by any child class of GtkHotkeyListener.

Start listening for keypresses matching the signature of `hotkey`. This method is notmally accessed indirectly by calling `gtk_hotkey_info_bind()`.

`self` : | The hotkey listener on which to bind a hotkey
`hotkey` : | The GtkHotkeyInfo to bind. See "signature"
`error` : | GError in which to store errors, or `NULL` to ignore
Returns : | `TRUE` if the binding succeeded, or `FALSE` otherwise. In case of runtime errors `error` will be set

### gtk_hotkey_listener_unbind_hotkey ()

    gboolean            gtk_hotkey_listener_unbind_hotkey   (GtkHotkeyListener *self,
                                                             GtkHotkeyInfo *hotkey,
                                                             GError **error);

This method must be implemented by any child class of GtkHotkeyListener.

Stop listening for keypresses matching the signature of `hotkey`. This method is notmally accessed indirectly by calling `gtk_hotkey_info_unbind()`.

`self` : | The hotkey listener on which to bind a hotkey
`hotkey` : | The GtkHotkeyInfo to bind. See "signature"
`error` : | GError in which to store errors, or `NULL` to ignore
Returns : | `TRUE` if the binding has been removed, or `FALSE` otherwise. In case of runtime errors `error` will be set

## Signal Details

### The `"activated"` signal

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

Emitted when a registered hotkey has been activated.

`listener` : | The object that emitted the signal
`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, GtkHotkeyInfo