GNOME.org
 

[gtk+] docs: Move documentation to inline comments: gdkevents

commit 4400f997a8e1f40116a6754dbdf5a28619da90bf
Author: Javier Jardón <jjardon gnome org>
Date:   Mon Nov 15 19:15:00 2010 +0100

    docs: Move documentation to inline comments: gdkevents

 docs/reference/gdk/tmpl/.gitignore  |    1 +
 docs/reference/gdk/tmpl/events.sgml |  430 -----------------------------------
 gdk/gdkevents.c                     |   17 ++
 gdk/gdkevents.h                     |  108 +++++++--
 gdk/gdktypes.h                      |   49 ++++-
 5 files changed, 150 insertions(+), 455 deletions(-)
---
diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore
index cbc990e..0256910 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/gdk/gdkevents.c b/gdk/gdkevents.c
index 920245d..fa61e08 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -31,6 +31,23 @@
 #include <string.h>
 #include <math.h>
 
+
+/**
+ * SECTION:events
+ * @Short_description: Functions for handling events from the window system
+ * @Title: Events
+ * @See_also: <link linkend="gdk-Event-Structures">Event Structures</link>
+ *
+ * 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
+ * <link linkend="gdk-Event-Structures">Event Structures</link> are useful.
+ */
+
+
 typedef struct _GdkIOClosure GdkIOClosure;
 
 struct _GdkIOClosure
diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h
index e3441af..9dd7e52 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
+ * <link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
+ */
 #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
+ * <link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
+ */
 #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 de5ebe2..a7c1e57 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -46,6 +46,12 @@
 #include <gdkconfig.h>
 
 /* 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,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]