diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore index cbc990eb2c..0256910f06 100644 --- a/docs/reference/gdk/tmpl/.gitignore +++ b/docs/reference/gdk/tmpl/.gitignore @@ -2,6 +2,7 @@ cairo_interaction.sgml colors.sgml cursors.sgml dnd.sgml +events.sgml gdkapplaunchcontext.sgml gdkdisplay.sgml gdkdisplaymanager.sgml diff --git a/docs/reference/gdk/tmpl/events.sgml b/docs/reference/gdk/tmpl/events.sgml deleted file mode 100644 index b8c3370f97..0000000000 --- a/docs/reference/gdk/tmpl/events.sgml +++ /dev/null @@ -1,430 +0,0 @@ - -Events - - -Functions for handling events from the window system - - - -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. - - - - - - -Event Structures - -The structs used for each type of event. - - - - - - - - - - - - - -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. -@GDK_SCROLL: the scroll wheel was turned -@GDK_WINDOW_STATE: the state of a window has changed. See #GdkWindowState -for the possible window states -@GDK_SETTING: a setting has been modified. -@GDK_OWNER_CHANGE: the owner of a selection has changed. This event type - was added in 2.6 -@GDK_GRAB_BROKEN: a pointer or keyboard grab was broken. This event type - was added in 2.8. -@GDK_DAMAGE: the content of the window has been changed. This event type - was added in 2.14. -@GDK_EVENT_LAST: marks the end of the GdkEventType enumeration. Added in 2.18 - - - -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 lag behind the position of the mouse. When using -%GDK_POINTER_MOTION_HINT_MASK, fewer %GDK_MOTION_NOTIFY events will be sent, -some of which are marked as a hint (the is_hint member is %TRUE). -To receive more motion events after a motion hint event, the application -needs to asks for more, by calling gdk_event_request_motions(). - - -@GDK_EXPOSURE_MASK: receive expose events -@GDK_POINTER_MOTION_MASK: receive all pointer motion events -@GDK_POINTER_MOTION_HINT_MASK: see the explanation above -@GDK_BUTTON_MOTION_MASK: receive pointer motion events while any button is pressed -@GDK_BUTTON1_MOTION_MASK: receive pointer motion events while 1 button is pressed -@GDK_BUTTON2_MOTION_MASK: receive pointer motion events while 2 button is pressed -@GDK_BUTTON3_MOTION_MASK: receive pointer motion events while 3 button is pressed -@GDK_BUTTON_PRESS_MASK: receive button press events -@GDK_BUTTON_RELEASE_MASK: receive button release events -@GDK_KEY_PRESS_MASK: receive key press events -@GDK_KEY_RELEASE_MASK: receive key release events -@GDK_ENTER_NOTIFY_MASK: receive window enter events -@GDK_LEAVE_NOTIFY_MASK: receive window leave events -@GDK_FOCUS_CHANGE_MASK: receive focus change events -@GDK_STRUCTURE_MASK: receive events about window configuration change -@GDK_PROPERTY_CHANGE_MASK: receive property change events -@GDK_VISIBILITY_NOTIFY_MASK: receive visibility change events -@GDK_PROXIMITY_IN_MASK: receive proximity in events -@GDK_PROXIMITY_OUT_MASK: receive proximity out events -@GDK_SUBSTRUCTURE_MASK: receive events about window configuration changes of - child windows -@GDK_SCROLL_MASK: receive scroll events -@GDK_ALL_EVENTS_MASK: the combination of all the above event masks. - - - -Represents the current time, and can be used anywhere a time is expected. - - - - - - -This is the priority that events from the X server are given in the -GLib Main Loop. - - - - - - -This is the priority that the idle handler processing window updates -is given in the GLib Main Loop. - - - - - - - - -@void: -@Returns: - - - - - - -@void: -@Returns: - - - - - - -@void: -@Returns: - - - - - - -@event: - - - - - - - -@type: -@Returns: - - - - - - -@event: -@Returns: - - - - - - -@event: a #GdkEvent. - - - - - - -@event: -@Returns: - - - - - - - -@event: -@state: -@Returns: - - - - - - - -@event: -@axis_use: -@value: -@Returns: - - - - - - - -@event: -@x_win: -@y_win: -@Returns: - - - - - - - -@event: -@x_root: -@y_root: -@Returns: - - - - - - - -@event: - - - - - - - -@event1: -@event2: -@angle: -@Returns: - - - - - - - -@event1: -@event2: -@x: -@y: -@Returns: - - - - - - - -@event1: -@event2: -@distance: -@Returns: - - - - - - -@func: -@data: -@notify: - - - - -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(). - - - - - - -@event: -@winid: -@Returns: - - - - - - - -@display: -@event: -@winid: -@Returns: - - - - - - -@event: - - - - - - -@message_type: -@func: -@data: - - - - - - -@void: -@Returns: - - - - - - -@show_events: - - - - - - - -@event: -@screen: - - - - - - - -@event: -@Returns: - - - - - - - -@event: -@Returns: - - - - - - - -@event: -@device: - - - - - - -@name: -@value: -@Returns: - - diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c index 920245d8cd..fa61e082b9 100644 --- a/gdk/gdkevents.c +++ b/gdk/gdkevents.c @@ -31,6 +31,23 @@ #include #include + +/** + * SECTION:events + * @Short_description: Functions for handling events from the window system + * @Title: Events + * @See_also: Event Structures + * + * 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 struct _GdkIOClosure GdkIOClosure; struct _GdkIOClosure diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h index e3441af2b7..9dd7e52dd8 100644 --- a/gdk/gdkevents.h +++ b/gdk/gdkevents.h @@ -40,7 +40,21 @@ G_BEGIN_DECLS #define GDK_TYPE_EVENT (gdk_event_get_type ()) +/** + * GDK_PRIORITY_EVENTS: + * + * This is the priority that events from the X server are given in the + * GLib Main Loop. + */ #define GDK_PRIORITY_EVENTS (G_PRIORITY_DEFAULT) + +/** + * GDK_PRIORITY_REDRAW: + * + * This is the priority that the idle handler processing window updates + * is given in the + * GLib Main Loop. + */ #define GDK_PRIORITY_REDRAW (G_PRIORITY_HIGH_IDLE + 20) @@ -67,6 +81,15 @@ typedef struct _GdkEventGrabBroken GdkEventGrabBroken; typedef union _GdkEvent GdkEvent; +/** + * GdkEventFunc: + * @event: the #GdkEvent to process. + * @data: user data set when the event handler was installed with + * gdk_event_handler_set(). + * + * Specifies the type of function passed to gdk_event_handler_set() to + * handle all GDK events. + */ typedef void (*GdkEventFunc) (GdkEvent *event, gpointer data); @@ -121,28 +144,69 @@ typedef GdkFilterReturn (*GdkFilterFunc) (GdkXEvent *xevent, gpointer data); -/* Event types. - * Nothing: No event occurred. - * Delete: A window delete event was sent by the window manager. - * The specified window should be deleted. - * Destroy: A window has been destroyed. - * Expose: Part of a window has been uncovered. - * NoExpose: Same as expose, but no expose event was generated. - * VisibilityNotify: A window has become fully/partially/not obscured. - * MotionNotify: The mouse has moved. - * ButtonPress: A mouse button was pressed. - * ButtonRelease: A mouse button was release. - * KeyPress: A key was pressed. - * KeyRelease: A key was released. - * EnterNotify: A window was entered. - * LeaveNotify: A window was exited. - * FocusChange: The focus window has changed. (The focus window gets - * keyboard events). - * Resize: A window has been resized. - * Map: A window has been mapped. (It is now visible on the screen). - * Unmap: A window has been unmapped. (It is no longer visible on - * the screen). - * Scroll: A mouse wheel was scrolled either up or down. +/** + * GdkEventType: + * @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. + * @GDK_SCROLL: the scroll wheel was turned + * @GDK_WINDOW_STATE: the state of a window has changed. See #GdkWindowState + * for the possible window states + * @GDK_SETTING: a setting has been modified. + * @GDK_OWNER_CHANGE: the owner of a selection has changed. This event type + * was added in 2.6 + * @GDK_GRAB_BROKEN: a pointer or keyboard grab was broken. This event type + * was added in 2.8. + * @GDK_DAMAGE: the content of the window has been changed. This event type + * was added in 2.14. + * @GDK_EVENT_LAST: marks the end of the GdkEventType enumeration. Added in 2.18 + * + * 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. */ typedef enum { diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h index de5ebe27c7..a7c1e5713e 100644 --- a/gdk/gdktypes.h +++ b/gdk/gdktypes.h @@ -46,6 +46,12 @@ #include /* some common magic values */ + +/** + * GDK_CURRENT_TIME: + * + * Represents the current time, and can be used anywhere a time is expected. + */ #define GDK_CURRENT_TIME 0L /** @@ -272,9 +278,46 @@ typedef enum GDK_OWNERSHIP_APPLICATION } GdkGrabOwnership; -/* Event masks. (Used to select what types of events a window - * * will receive). - * */ +/** + * GdkEventMask: + * @GDK_EXPOSURE_MASK: receive expose events + * @GDK_POINTER_MOTION_MASK: receive all pointer motion events + * @GDK_POINTER_MOTION_HINT_MASK: see the explanation above + * @GDK_BUTTON_MOTION_MASK: receive pointer motion events while any button is pressed + * @GDK_BUTTON1_MOTION_MASK: receive pointer motion events while 1 button is pressed + * @GDK_BUTTON2_MOTION_MASK: receive pointer motion events while 2 button is pressed + * @GDK_BUTTON3_MOTION_MASK: receive pointer motion events while 3 button is pressed + * @GDK_BUTTON_PRESS_MASK: receive button press events + * @GDK_BUTTON_RELEASE_MASK: receive button release events + * @GDK_KEY_PRESS_MASK: receive key press events + * @GDK_KEY_RELEASE_MASK: receive key release events + * @GDK_ENTER_NOTIFY_MASK: receive window enter events + * @GDK_LEAVE_NOTIFY_MASK: receive window leave events + * @GDK_FOCUS_CHANGE_MASK: receive focus change events + * @GDK_STRUCTURE_MASK: receive events about window configuration change + * @GDK_PROPERTY_CHANGE_MASK: receive property change events + * @GDK_VISIBILITY_NOTIFY_MASK: receive visibility change events + * @GDK_PROXIMITY_IN_MASK: receive proximity in events + * @GDK_PROXIMITY_OUT_MASK: receive proximity out events + * @GDK_SUBSTRUCTURE_MASK: receive events about window configuration changes of + * child windows + * @GDK_SCROLL_MASK: receive scroll events + * @GDK_ALL_EVENTS_MASK: the combination of all the above event masks. + * + * 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 lag behind the position of the mouse. When using + * %GDK_POINTER_MOTION_HINT_MASK, fewer %GDK_MOTION_NOTIFY events will be sent, + * some of which are marked as a hint (the is_hint member is %TRUE). + * To receive more motion events after a motion hint event, the application + * needs to asks for more, by calling gdk_event_request_motions(). + */ typedef enum { GDK_EXPOSURE_MASK = 1 << 1,