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      GdkEventMotion;
struct      GdkEventExpose;
struct      GdkEventVisibility;
struct      GdkEventCrossing;
struct      GdkEventFocus;
struct      GdkEventConfigure;
struct      GdkEventProperty;
struct      GdkEventSelection;
struct      GdkEventDND;
struct      GdkEventProximity;
struct      GdkEventClient;
struct      GdkEventNoExpose;

enum        GdkVisibilityState;
enum        GdkCrossingMode;
enum        GdkNotifyType;
enum        GdkPropertyState;

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;
  GdkEventKey		    key;
  GdkEventCrossing	    crossing;
  GdkEventFocus		    focus_change;
  GdkEventConfigure	    configure;
  GdkEventProperty	    property;
  GdkEventSelection	    selection;
  GdkEventProximity	    proximity;
  GdkEventClient	    client;
  GdkEventDND               dnd;
};

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:

  GdkEvent *event;  
  GdkEventType type;

  type = event->type;

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:

  GdkEvent *event;  
  gdouble x;

  x = ((GdkEventButton*)event)->x;

or:

  GdkEvent *event;  
  gdouble x;

  x = event->button.x;


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.

GdkEventType typethe type of the event.
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).


struct GdkEventKey

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

Describes a key press or key release event.

GdkEventType typethe type of the event (GDK_KEY_PRESS or GDK_KEY_RELEASE).
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
guint32 timethe time of the event in milliseconds.
guint statea bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See GdkModifierType.
guint keyvalthe key that was pressed or released. See the <gdk/gdkkeysym.h> header file for a complete list of GDK key codes.
gint lengththe length of string.
gchar *stringa null-terminated multi-byte string containing the composed characters resulting from the key press. When text is being input, in a GtkEntry for example, it is these characters which should be added to the input buffer. When using Input Methods to support internationalized text input, the composed characters appear here after the pre-editing has been completed.


struct GdkEventButton

struct GdkEventButton
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  guint32 time;
  gdouble x;
  gdouble y;
  gdouble pressure;
  gdouble xtilt;
  gdouble ytilt;
  guint state;
  guint button;
  GdkInputSource source;
  guint32 deviceid;
  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.

GdkEventType typethe type of the event (GDK_BUTTON_PRESS, GDK_2BUTTON_PRESS, GDK_3BUTTON_PRESS or GDK_BUTTON_RELEASE).
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
guint32 timethe time of the event in milliseconds.
gdouble xthe x coordinate of the mouse relative to the window.
gdouble ythe y coordinate of the mouse relative to the window.
gdouble pressurethe pressure of the button press, intended for input devices such as graphics tablets. It defaults to 0.5.
gdouble xtiltthe horizontal tilt of the input device. Defaults to 0.
gdouble ytiltthe vertical tilt of the input device. Defaults to 0.
guint statea bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See GdkModifierType.
guint buttonthe button which was pressed or released, numbered from 1 to 5. Normally button 1 is the left mouse button, 2 is the middle button, and 3 is the right button. On 2-button mice, the middle button can often be simulated by pressing both mouse buttons together.
GdkInputSource sourcethe input device where the event came from, usually GDK_SOURCE_MOUSE.
guint32 deviceidthe input device ID, usually GDK_CORE_POINTER but may be different if touch screens or graphics tablets are being used.
gdouble x_rootthe x coordinate of the mouse relative to the root of the screen.
gdouble y_rootthe y coordinate of the mouse relative to the root of the screen.


struct GdkEventMotion

struct GdkEventMotion
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  guint32 time;
  gdouble x;
  gdouble y;
  gdouble pressure;
  gdouble xtilt;
  gdouble ytilt;
  guint state;
  gint16 is_hint;
  GdkInputSource source;
  guint32 deviceid;
  gdouble x_root, y_root;
};

GdkEventType typethe type of the event.
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
guint32 time 
gdouble x 
gdouble y 
gdouble pressure 
gdouble xtilt 
gdouble ytilt 
guint state 
gint16 is_hint 
GdkInputSource source 
guint32 deviceid 
gdouble x_root 
gdouble y_root 


struct GdkEventExpose

struct GdkEventExpose
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  GdkRectangle area;
  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.

GdkEventType typethe type of the event (GDK_EXPOSE).
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
GdkRectangle areathe area that needs to be redrawn.
gint countthe number of contiguous GDK_EXPOSE events following this one. The only use for this is "exposure compression", i.e. handling all contiguous GDK_EXPOSE events in one go, though GDK performs some exposure compression so this is not normally needed.


struct GdkEventVisibility

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

Generated when the window visibility status has changed.

GdkEventType typethe type of the event (GDK_VISIBILITY_NOTIFY).
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
GdkVisibilityState statethe new visibility state (GDK_VISIBILITY_FULLY_OBSCURED, GDK_VISIBILITY_PARTIAL or GDK_VISIBILITY_UNOBSCURED).


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;
};

GdkEventType typethe type of the event.
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
GdkWindow *subwindow 
guint32 timethe time of the event in milliseconds.
gdouble x 
gdouble y 
gdouble x_root 
gdouble y_root 
GdkCrossingMode mode 
GdkNotifyType detail 
gboolean focus 
guint state 


struct GdkEventFocus

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

Describes a change of keyboard focus.

GdkEventType typethe type of the event (GDK_FOCUS_CHANGE).
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
gint16 inTRUE if the window has gained the keyboard focus, FALSE if it has lost the focus.


struct GdkEventConfigure

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

Generated when a window size or position has changed.

GdkEventType typethe type of the event (GDK_CONFIGURE).
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
gint16 xthe new x coordinate of the window, relative to its parent.
gint16 ythe new y coordinate of the window, relative to its parent.
gint16 widththe new width of the window.
gint16 heightthe new height of the window.


struct GdkEventProperty

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

Describes a property change on a window.

GdkEventType typethe type of the event (GDK_PROPERTY_NOTIFY).
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
GdkAtom atomthe property that was changed.
guint32 timethe time of the event in milliseconds.
guint statewhether the property was changed (GDK_PROPERTY_NEW_VALUE) or deleted (GDK_PROPERTY_DELETE).


struct GdkEventSelection

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

GdkEventType typethe type of the event.
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
GdkAtom selection 
GdkAtom target 
GdkAtom property 
guint32 requestor 
guint32 timethe time of the event in milliseconds.


struct GdkEventDND

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

  guint32 time;
  gshort x_root, y_root;
};

GdkEventType typethe type of the event.
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
GdkDragContext *context 
guint32 timethe time of the event in milliseconds.
gshort x_root 
gshort y_root 


struct GdkEventProximity

struct GdkEventProximity
{
  GdkEventType type;
  GdkWindow *window;
  gint8 send_event;
  guint32 time;
  GdkInputSource source;
  guint32 deviceid;
};

GdkEventType typethe type of the event.
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
guint32 timethe time of the event in milliseconds.
GdkInputSource source 
guint32 deviceid 


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.

GdkEventType typethe type of the event (GDK_CLIENT_EVENT).
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).
GdkAtom message_typethe type of the message, which can be defined by the application.
gushort data_formatthe format of the data, given as the number of bits in each data element, i.e. 8, 16, or 32. 8-bit data uses the b array of the data union, 16-bit data uses the s array, and 32-bit data uses the l array.


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_pixmap() or gdk_window_copy_area(), was completely available.

FIXME: add more here.

GdkEventType typethe type of the event (GDK_NO_EXPOSE).
GdkWindow *windowthe window which received the event.
gint8 send_eventTRUE if the event was sent explicitly (e.g. using XSendEvent).


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.

GDK_VISIBILITY_UNOBSCUREDthe window is completely visible.
GDK_VISIBILITY_PARTIALthe window is partially visible.
GDK_VISIBILITY_FULLY_OBSCUREDthe window is not visible at all.


enum GdkCrossingMode

typedef enum
{
  GDK_CROSSING_NORMAL,
  GDK_CROSSING_GRAB,
  GDK_CROSSING_UNGRAB
} GdkCrossingMode;


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;


enum GdkPropertyState

typedef enum
{
  GDK_PROPERTY_NEW_VALUE,
  GDK_PROPERTY_DELETE
} GdkPropertyState;

Specifies the type of a property change for a GdkEventProperty.

GDK_PROPERTY_NEW_VALUEthe property value wan changed.
GDK_PROPERTY_DELETEthe property was deleted.