GDK Reference Manual | |||
---|---|---|---|
<<< Previous Page | Home | Up | Next Page >>> |
#include <gdk/gdk.h> enum GdkEventType; enum GdkEventMask; #define GDK_CURRENT_TIME #define GDK_PRIORITY_EVENTS gboolean gdk_events_pending (void); GdkEvent* gdk_event_peek (void); GdkEvent* gdk_event_get (void); GdkEvent* gdk_event_get_graphics_expose (GdkWindow *window); void gdk_event_put (GdkEvent *event); GdkEvent* gdk_event_copy (GdkEvent *event); void gdk_event_free (GdkEvent *event); guint32 gdk_event_get_time (GdkEvent *event); void gdk_event_handler_set (GdkEventFunc func, gpointer data, GDestroyNotify notify); void (*GdkEventFunc) (GdkEvent *event, gpointer data); gboolean gdk_event_send_client_message (GdkEvent *event, guint32 xid); void gdk_event_send_clientmessage_toall (GdkEvent *event); void gdk_add_client_message_filter (GdkAtom message_type, GdkFilterFunc func, gpointer data); gint gdk_get_show_events (void); void gdk_set_show_events (gint show_events); |
This section describes functions dealing with events from the window system.
In GTK+ applications the events are handled automatically in gtk_main_do_event() and passed on to the appropriate widgets, so these functions are rarely needed. Though some of the fields in the Event Structures are useful.
typedef enum { GDK_NOTHING = -1, GDK_DELETE = 0, GDK_DESTROY = 1, GDK_EXPOSE = 2, GDK_MOTION_NOTIFY = 3, GDK_BUTTON_PRESS = 4, GDK_2BUTTON_PRESS = 5, GDK_3BUTTON_PRESS = 6, GDK_BUTTON_RELEASE = 7, GDK_KEY_PRESS = 8, GDK_KEY_RELEASE = 9, GDK_ENTER_NOTIFY = 10, GDK_LEAVE_NOTIFY = 11, GDK_FOCUS_CHANGE = 12, GDK_CONFIGURE = 13, GDK_MAP = 14, GDK_UNMAP = 15, GDK_PROPERTY_NOTIFY = 16, GDK_SELECTION_CLEAR = 17, GDK_SELECTION_REQUEST = 18, GDK_SELECTION_NOTIFY = 19, GDK_PROXIMITY_IN = 20, GDK_PROXIMITY_OUT = 21, GDK_DRAG_ENTER = 22, GDK_DRAG_LEAVE = 23, GDK_DRAG_MOTION = 24, GDK_DRAG_STATUS = 25, GDK_DROP_START = 26, GDK_DROP_FINISHED = 27, GDK_CLIENT_EVENT = 28, GDK_VISIBILITY_NOTIFY = 29, GDK_NO_EXPOSE = 30 } GdkEventType; |
Specifies the type of the event.
Do not confuse these events with the signals that GTK+ widgets emit. Although many of these events result in corresponding signals being emitted, the events are often transformed or filtered along the way.
GDK_NOTHING | a special code to indicate a null event. |
GDK_DELETE | the window manager has requested that the toplevel window be hidden or destroyed, usually when the user clicks on a special icon in the title bar. |
GDK_DESTROY | the window has been destroyed. |
GDK_EXPOSE | all or part of the window has become visible and needs to be redrawn. |
GDK_MOTION_NOTIFY | the pointer (usually a mouse) has moved. |
GDK_BUTTON_PRESS | a mouse button has been pressed. |
GDK_2BUTTON_PRESS | a mouse button has been double-clicked (clicked twice within a short period of time). Note that each click also generates a GDK_BUTTON_PRESS event. |
GDK_3BUTTON_PRESS | a mouse button has been clicked 3 times in a short period of time. Note that each click also generates a GDK_BUTTON_PRESS event. |
GDK_BUTTON_RELEASE | a mouse button has been released. |
GDK_KEY_PRESS | a key has been pressed. |
GDK_KEY_RELEASE | a key has been released. |
GDK_ENTER_NOTIFY | the pointer has entered the window. |
GDK_LEAVE_NOTIFY | the pointer has left the window. |
GDK_FOCUS_CHANGE | the keyboard focus has entered or left the window. |
GDK_CONFIGURE | the size, position or stacking order of the window has changed. Note that GTK+ discards these events for GDK_WINDOW_CHILD windows. |
GDK_MAP | the window has been mapped. |
GDK_UNMAP | the window has been unmapped. |
GDK_PROPERTY_NOTIFY | a property on the window has been changed or deleted. |
GDK_SELECTION_CLEAR | the application has lost ownership of a selection. |
GDK_SELECTION_REQUEST | another application has requested a selection. |
GDK_SELECTION_NOTIFY | a selection has been received. |
GDK_PROXIMITY_IN | an input device has moved into contact with a sensing surface (e.g. a touchscreen or graphics tablet). |
GDK_PROXIMITY_OUT | an input device has moved out of contact with a sensing surface. |
GDK_DRAG_ENTER | the mouse has entered the window while a drag is in progress. |
GDK_DRAG_LEAVE | the mouse has left the window while a drag is in progress. |
GDK_DRAG_MOTION | the mouse has moved in the window while a drag is in progress. |
GDK_DRAG_STATUS | the status of the drag operation initiated by the window has changed. |
GDK_DROP_START | a drop operation onto the window has started. |
GDK_DROP_FINISHED | the drop operation initiated by the window has completed. |
GDK_CLIENT_EVENT | a message has been received from another application. |
GDK_VISIBILITY_NOTIFY | the window visibility status has changed. |
GDK_NO_EXPOSE | indicates that the source region was completely available when parts of a drawable were copied. This is not very useful. |
typedef enum { GDK_EXPOSURE_MASK = 1 << 1, GDK_POINTER_MOTION_MASK = 1 << 2, GDK_POINTER_MOTION_HINT_MASK = 1 << 3, GDK_BUTTON_MOTION_MASK = 1 << 4, GDK_BUTTON1_MOTION_MASK = 1 << 5, GDK_BUTTON2_MOTION_MASK = 1 << 6, GDK_BUTTON3_MOTION_MASK = 1 << 7, GDK_BUTTON_PRESS_MASK = 1 << 8, GDK_BUTTON_RELEASE_MASK = 1 << 9, GDK_KEY_PRESS_MASK = 1 << 10, GDK_KEY_RELEASE_MASK = 1 << 11, GDK_ENTER_NOTIFY_MASK = 1 << 12, GDK_LEAVE_NOTIFY_MASK = 1 << 13, GDK_FOCUS_CHANGE_MASK = 1 << 14, GDK_STRUCTURE_MASK = 1 << 15, GDK_PROPERTY_CHANGE_MASK = 1 << 16, GDK_VISIBILITY_NOTIFY_MASK = 1 << 17, GDK_PROXIMITY_IN_MASK = 1 << 18, GDK_PROXIMITY_OUT_MASK = 1 << 19, GDK_SUBSTRUCTURE_MASK = 1 << 20, GDK_ALL_EVENTS_MASK = 0x0FFFFF } GdkEventMask; |
A set of bit-flags to indicate which events a window is to receive. Most of these masks map onto one or more of the GdkEventType event types above.
GDK_POINTER_MOTION_HINT_MASK is a special mask which is used to reduce the number of GDK_MOTION_NOTIFY events received. Normally a GDK_MOTION_NOTIFY event is received each time the mouse moves. However, if the application spends a lot of time processing the event (updating the display, for example), it can easily lag behind the position of the mouse. When using the GDK_POINTER_MOTION_HINT_MASK the server will only send GDK_MOTION_NOTIFY events when the application asks for them, by calling gdk_window_get_pointer().
GDK_EXPOSURE_MASK | |
GDK_POINTER_MOTION_MASK | |
GDK_POINTER_MOTION_HINT_MASK | |
GDK_BUTTON_MOTION_MASK | |
GDK_BUTTON1_MOTION_MASK | |
GDK_BUTTON2_MOTION_MASK | |
GDK_BUTTON3_MOTION_MASK | |
GDK_BUTTON_PRESS_MASK | |
GDK_BUTTON_RELEASE_MASK | |
GDK_KEY_PRESS_MASK | |
GDK_KEY_RELEASE_MASK | |
GDK_ENTER_NOTIFY_MASK | |
GDK_LEAVE_NOTIFY_MASK | |
GDK_FOCUS_CHANGE_MASK | |
GDK_STRUCTURE_MASK | |
GDK_PROPERTY_CHANGE_MASK | |
GDK_VISIBILITY_NOTIFY_MASK | |
GDK_PROXIMITY_IN_MASK | |
GDK_PROXIMITY_OUT_MASK | |
GDK_SUBSTRUCTURE_MASK | |
GDK_ALL_EVENTS_MASK | the combination of all the above event masks. |
#define GDK_CURRENT_TIME 0L |
Represents the current time, and can be used anywhere a time is expected.
#define GDK_PRIORITY_EVENTS (G_PRIORITY_DEFAULT) |
This is the priority that events from the X server are given in the GLib Main Loop.
gboolean gdk_events_pending (void); |
Checks if any events are waiting to be processed.
GdkEvent* gdk_event_peek (void); |
Gets a copy of the first GdkEvent in the event queue. (Note that this function will not get more events from the X server. It only checks the events that have already been moved to the GDK event queue.)
Returns : | a copy of the first GdkEvent on the event queue, or NULL if no events are in the queue. The returned GdkEvent should be freed with gdk_event_free(). |
GdkEvent* gdk_event_get (void); |
Gets the next GdkEvent to be processed, fetching events from the X server if necessary.
Returns : | the next GdkEvent to be processed, or NULL if no events are pending. The returned GdkEvent should be freed with gdk_event_free(). |
GdkEvent* gdk_event_get_graphics_expose (GdkWindow *window); |
Waits for a GraphicsExpose or NoExpose event from the X server. This is used in the GtkText and GtkCList widgets in GTK+ to make sure any GraphicsExpose events are handled before the widget is scrolled.
window : | the GdkWindow to wait for the events for. |
Returns : | a GdkEventExpose if a GraphicsExpose was received, or NULL if a NoExpose event was received. |
void gdk_event_put (GdkEvent *event); |
Appends a copy of the given event onto the front of the event queue.
event : | a GdkEvent. |
GdkEvent* gdk_event_copy (GdkEvent *event); |
Copies a GdkEvent, copying or incrementing the reference count of the resources associated with it (e.g. GdkWindow's and strings).
event : | a GdkEvent. |
Returns : | a copy of event. The returned GdkEvent should be freed with gdk_event_free(). |
void gdk_event_free (GdkEvent *event); |
Frees a GdkEvent, freeing or decrementing any resources associated with it. Note that this function should only be called with events returned from gdk_event_peek(), gdk_event_get(), gdk_event_get_graphics_expose() and gdk_event_copy().
event : | a GdkEvent. |
guint32 gdk_event_get_time (GdkEvent *event); |
Gets the timestamp from a GdkEvent.
event : | a GdkEvent. |
Returns : | the timestamp from event, or GDK_CURRENT_TIME if the event has no timestamp. |
void gdk_event_handler_set (GdkEventFunc func, gpointer data, GDestroyNotify notify); |
Sets the function to call to handle all events from GDK.
Note that GTK+ uses this to install its own event handler, so it is probably not useful for GTK+ applications.
func : | the function to call to handle events from GDK. |
data : | user data to pass to the function. |
notify : | the function to call when the handler function is removed, i.e. when gdk_event_handler_set() is called with another event handler. |
void (*GdkEventFunc) (GdkEvent *event, gpointer data); |
Specifies the type of function passed to gdk_event_handler_set() to handle all GDK events.
event : | the GdkEvent to process. |
data : | user data set when the event handler was installed with gdk_event_handler_set(). |
gboolean gdk_event_send_client_message (GdkEvent *event, guint32 xid); |
Sends an X ClientMessage event to a given window.
This could be used for communicating between different applications, though the amount of data is limited to 20 bytes.
event : | the GdkEvent to send, which should be a GdkEventClient. |
xid : | the window to send the X ClientMessage event to. |
Returns : | non-zero on success. |
void gdk_event_send_clientmessage_toall (GdkEvent *event); |
Sends an X ClientMessage event to all toplevel windows.
Toplevel windows are determined by checking for the WM_STATE property, as described in the Inter-Client Communication Conventions Manual (ICCCM). If no windows are found with the WM_STATE property set, the message is sent to all children of the root window.
event : | the GdkEvent to send, which should be a GdkEventClient. |
void gdk_add_client_message_filter (GdkAtom message_type, GdkFilterFunc func, gpointer data); |
Adds a filter to be called when X ClientMessage events are received.
gint gdk_get_show_events (void); |
Returns non-zero if event debugging output is enabled.
void gdk_set_show_events (gint show_events); |
Sets whether event debugging information is output. Note that GTK+ must be compiled with debugging enabled, i.e. using the '--enable-debug' configure option.