Event Structures

Name

Event Structures -- data structures specific to each type of event.

Synopsis


#include <gdk/gdk.h>


union       GdkEvent;

struct      GdkEventAny;
struct      GdkEventKey;
struct      GdkEventButton;
struct      GdkEventScroll;
struct      GdkEventMotion;
struct      GdkEventExpose;
struct      GdkEventVisibility;
struct      GdkEventCrossing;
struct      GdkEventFocus;
struct      GdkEventConfigure;
struct      GdkEventProperty;
struct      GdkEventSelection;
typedef     GdkNativeWindow;
struct      GdkEventDND;
struct      GdkEventProximity;
struct      GdkEventClient;
struct      GdkEventNoExpose;
struct      GdkEventWindowState;
struct      GdkEventSetting;

enum        GdkScrollDirection;
enum        GdkVisibilityState;
enum        GdkCrossingMode;
enum        GdkNotifyType;
enum        GdkPropertyState;
enum        GdkWindowState;
enum        GdkSettingAction;


Description

The event structs contain data specific to each type of event in GDK.

Note: A common mistake is to forget to set the event mask of a widget so that the required events are received. See gtk_widget_set_events().

Details

union GdkEvent

union GdkEvent
{
  GdkEventType		    type;
  GdkEventAny		    any;
  GdkEventExpose	    expose;
  GdkEventNoExpose	    no_expose;
  GdkEventVisibility	    visibility;
  GdkEventMotion	    motion;
  GdkEventButton	    button;
  GdkEventScroll            scroll;
  GdkEventKey		    key;
  GdkEventCrossing	    crossing;
  GdkEventFocus		    focus_change;
  GdkEventConfigure	    configure;
  GdkEventProperty	    property;
  GdkEventSelection	    selection;
  GdkEventProximity	    proximity;
  GdkEventClient	    client;
  GdkEventDND               dnd;
  GdkEventWindowState       window_state;
  GdkEventSetting           setting;
};

The GdkEvent struct contains a union of all of the event structs, and allows access to the data fields in a number of ways.

The event type is always the first field in all of the event structs, and can always be accessed with the following code, no matter what type of event it is:

To access other fields of the event structs, the pointer to the event can be cast to the appropriate event struct pointer, or the union member name can be used. For example if the event type is GDK_BUTTON_PRESS then the x coordinate of the button press can be accessed with:

or:


struct GdkEventAny

struct GdkEventAny
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
};

Contains the fields which are common to all event structs. Any event pointer can safely be cast to a pointer to a GdkEventAny to access these fields.


struct GdkEventKey

struct GdkEventKey
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  guint32 time;
  guint state;
  guint keyval;
  gint length;
  gchar *string;
  guint16 hardware_keycode;
  guint8 group;
};

Describes a key press or key release event.


struct GdkEventButton

struct GdkEventButton
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  guint32 time;
  gdouble x;
  gdouble y;
  gdouble *axes;
  guint state;
  guint button;
  GdkDevice *device;
  gdouble x_root, y_root;
};

Used for button press and button release events. The type field will be one of GDK_BUTTON_PRESS, GDK_2BUTTON_PRESS, GDK_3BUTTON_PRESS, and GDK_BUTTON_RELEASE.

Double and triple-clicks result in a sequence of events being received. For double-clicks the order of events will be:

  1. GDK_BUTTON_PRESS

  2. GDK_BUTTON_RELEASE

  3. GDK_BUTTON_PRESS

  4. GDK_2BUTTON_PRESS

  5. GDK_BUTTON_RELEASE

Note that the first click is received just like a normal button press, while the second click results in a GDK_2BUTTON_PRESS being received just after the GDK_BUTTON_PRESS.

Triple-clicks are very similar to double-clicks, except that GDK_3BUTTON_PRESS is inserted after the third click. The order of the events is:

  1. GDK_BUTTON_PRESS

  2. GDK_BUTTON_RELEASE

  3. GDK_BUTTON_PRESS

  4. GDK_2BUTTON_PRESS

  5. GDK_BUTTON_RELEASE

  6. GDK_BUTTON_PRESS

  7. GDK_3BUTTON_PRESS

  8. GDK_BUTTON_RELEASE

For a double click to occur, the second button press must occur within 1/4 of a second of the first. For a triple click to occur, the third button press must also occur within 1/2 second of the first button press.


struct GdkEventScroll

struct GdkEventScroll
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  guint32 time;
  gdouble x;
  gdouble y;
  guint state;
  GdkScrollDirection direction;
  GdkDevice *device;
  gdouble x_root, y_root;
};

Generated from button presses for the buttons 4 to 7. Wheel mice are usually configured to generate button press events for buttons 4 and 5 when the wheel is turned.


struct GdkEventMotion

struct GdkEventMotion
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  guint32 time;
  gdouble x;
  gdouble y;
  gdouble *axes;
  guint state;
  gint16 is_hint;
  GdkDevice *device;
  gdouble x_root, y_root;
};

Generated when the pointer moves.


struct GdkEventExpose

struct GdkEventExpose
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  GdkRectangle area;
  GdkRegion *region;
  gint count; /* If non-zero, how many more events follow. */
};

Generated when all or part of a window becomes visible and needs to be redrawn.


struct GdkEventVisibility

struct GdkEventVisibility
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  GdkVisibilityState state;
};

Generated when the window visibility status has changed.


struct GdkEventCrossing

struct GdkEventCrossing
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  GdkWindow *subwindow;
  guint32 time;
  gdouble x;
  gdouble y;
  gdouble x_root;
  gdouble y_root;
  GdkCrossingMode mode;
  GdkNotifyType detail;
  gboolean focus;
  guint state;
};

Generated when the pointer enters or leaves a window.


struct GdkEventFocus

struct GdkEventFocus
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  gint16 in;
};

Describes a change of keyboard focus.


struct GdkEventConfigure

struct GdkEventConfigure
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  gint x, y;
  gint width;
  gint height;
};

Generated when a window size or position has changed.


struct GdkEventProperty

struct GdkEventProperty
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  GdkAtom atom;
  guint32 time;
  guint state;
};

Describes a property change on a window.


struct GdkEventSelection

struct GdkEventSelection
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  GdkAtom selection;
  GdkAtom target;
  GdkAtom property;
  guint32 time;
  GdkNativeWindow requestor;
};

Generated when a selection is requested or ownership of a selection is taken over by another client application.


GdkNativeWindow

Used to represent native windows (Windows for the X11 backend, HWNDs for Win32).


struct GdkEventDND

struct GdkEventDND {
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  GdkDragContext *context;

  guint32 time;
  gshort x_root, y_root;
};

Generated during DND operations.


struct GdkEventProximity

struct GdkEventProximity
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  guint32 time;
  GdkDevice *device;
};

Proximity events are generated when using GDK's wrapper for the XInput extension. The XInput extension is an add-on for standard X that allows you to use nonstandard devices such as graphics tablets. A proximity event indicates that the stylus has moved in or out of contact with the tablet, or perhaps that the user's finger has moved in or out of contact with a touch screen.


struct GdkEventClient

struct GdkEventClient
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  GdkAtom message_type;
  gushort data_format;
  union {
    char b[20];
    short s[10];
    long l[5];
  } data;
};

An event sent by another client application.


struct GdkEventNoExpose

struct GdkEventNoExpose
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  /* XXX: does anyone need the X major_code or minor_code fields? */
};

Generated when the area of a GdkDrawable being copied, with gdk_draw_drawable() or gdk_window_copy_area(), was completely available.

FIXME: add more here.


struct GdkEventWindowState

struct GdkEventWindowState
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  GdkWindowState changed_mask;
  GdkWindowState new_window_state;
};

Generated when the state of a toplevel window changes.


struct GdkEventSetting

struct GdkEventSetting
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  GdkSettingAction action;
  char *name;
};

Generated when a setting is modified.


enum GdkScrollDirection

typedef enum
{
  GDK_SCROLL_UP,
  GDK_SCROLL_DOWN,
  GDK_SCROLL_LEFT,
  GDK_SCROLL_RIGHT
} GdkScrollDirection;

Specifies the direction for GdkEventScroll.


enum GdkVisibilityState

typedef enum
{
  GDK_VISIBILITY_UNOBSCURED,
  GDK_VISIBILITY_PARTIAL,
  GDK_VISIBILITY_FULLY_OBSCURED
} GdkVisibilityState;

Specifies the visiblity status of a window for a GdkEventVisibility.


enum GdkCrossingMode

typedef enum
{
  GDK_CROSSING_NORMAL,
  GDK_CROSSING_GRAB,
  GDK_CROSSING_UNGRAB
} GdkCrossingMode;

Specifies the crossing mode for GdkEventCrossing.


enum GdkNotifyType

typedef enum
{
  GDK_NOTIFY_ANCESTOR		= 0,
  GDK_NOTIFY_VIRTUAL		= 1,
  GDK_NOTIFY_INFERIOR		= 2,
  GDK_NOTIFY_NONLINEAR		= 3,
  GDK_NOTIFY_NONLINEAR_VIRTUAL	= 4,
  GDK_NOTIFY_UNKNOWN		= 5
} GdkNotifyType;

Specifies the kind of crossing for GdkEventCrossing.

See the X11 protocol specification of LeaveNotify for full details of crossing event generation.


enum GdkPropertyState

typedef enum
{
  GDK_PROPERTY_NEW_VALUE,
  GDK_PROPERTY_DELETE
} GdkPropertyState;

Specifies the type of a property change for a GdkEventProperty.


enum GdkWindowState

typedef enum
{
  GDK_WINDOW_STATE_WITHDRAWN = 1 << 0,
  GDK_WINDOW_STATE_ICONIFIED = 1 << 1,
  GDK_WINDOW_STATE_MAXIMIZED = 1 << 2,
  GDK_WINDOW_STATE_STICKY    = 1 << 3
} GdkWindowState;

Specifies the state of a toplevel window.


enum GdkSettingAction

typedef enum
{
  GDK_SETTING_ACTION_NEW,
  GDK_SETTING_ACTION_CHANGED,
  GDK_SETTING_ACTION_DELETED
} GdkSettingAction;

Specifies the kind of modification applied to a setting in a GdkEventSetting.