GNOME.org
 

[gtk+/xi2: 1176/1239] Add missing documentation for new API.

commit d2ea67fafd16375569f1dfea523da12547df6425
Author: Carlos Garnacho <carlos gnome org>
Date:   Thu Sep 17 16:35:10 2009 +0200

    Add missing documentation for new API.

 gdk/gdkdevice.c         |   69 ++++++++++++++++++++++++++++++++++
 gdk/gdkdevicemanager.c  |   30 +++++++++++++++
 gdk/gdkdisplay.c        |   35 +++++++++++++++++
 gdk/gdkevents.c         |    9 ++++
 gdk/gdkwindow.c         |   95 ++++++++++++++++++++++++++++++++++++++++++++--
 gdk/x11/gdkwindow-x11.c |   20 ++++++++++
 6 files changed, 253 insertions(+), 5 deletions(-)
---
diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index e614641..ec4be9b 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -371,6 +371,15 @@ gdk_device_set_axis_use (GdkDevice   *device,
     }
 }
 
+/**
+ * gdk_device_get_display:
+ * @device: a #GdkDevice
+ *
+ * Returns the #GdkDisplay to which @device pertains.
+ *
+ * Returns: a #GdkDisplay. This memory is owned by GTK+,
+ *          and must not be freed or unreffed.
+ **/
 GdkDisplay *
 gdk_device_get_display (GdkDevice *device)
 {
@@ -419,6 +428,14 @@ _gdk_device_set_relative (GdkDevice *device,
     priv->relative = g_object_ref (relative);
 }
 
+/**
+ * gdk_device_get_device_type:
+ * @device: a #GdkDevice
+ *
+ * Returns the device type for @device.
+ *
+ * Returns: the #GdkDeviceType for @device.
+ **/
 GdkDeviceType
 gdk_device_get_device_type (GdkDevice *device)
 {
@@ -431,6 +448,15 @@ gdk_device_get_device_type (GdkDevice *device)
   return priv->type;
 }
 
+/**
+ * gdk_device_list_axes:
+ * @device: a #GdkDevice
+ *
+ * Returns a #GList of #GdkAtom<!-- -->s, containing the labels for
+ * the axes that @device currently has.
+ *
+ * Returns: A #GList of #GdkAtom<!-- -->s, free with g_list_free().
+ **/
 GList *
 gdk_device_list_axes (GdkDevice *device)
 {
@@ -521,6 +547,49 @@ gdk_device_get_axis (GdkDevice  *device,
   return FALSE;
 }
 
+/**
+ * gdk_device_grab:
+ * @device: a #GdkDevice
+ * @window: the #GdkWindow which will own the grab (the grab window)
+ * @grab_ownership: 
+ * @owner_events: if %FALSE then all device events are reported with respect to
+ *                @window and are only reported if selected by @event_mask. If
+ *                %TRUE then pointer events for this application are reported
+ *                as normal, but pointer events outside this application are
+ *                reported with respect to @window and only if selected by
+ *                @event_mask. In either mode, unreported events are discarded.
+ * @event_mask: specifies the event mask, which is used in accordance with
+ *              @owner_events.
+ * @cursor: the cursor to display while the grab is active if the device is
+ *          a pointer. If this is %NULL then the normal cursors are used for
+ *          @window and its descendants, and the cursor for @window is used
+ *          elsewhere.
+ * @time_: the timestamp of the event which led to this pointer grab. This
+ *         usually comes from the #GdkEvent struct, though %GDK_CURRENT_TIME
+ *         can be used if the time isn't known.
+ *
+ * Grabs the device so that all events coming from this device are passed to
+ * this application until the device is ungrabbed with gdk_display_device_ungrab(),
+ * or the window becomes unviewable. This overrides any previous grab on the device
+ * by this client.
+ *
+ * Device grabs are used for operations which need complete control over the
+ * given device events (either pointer or keyboard). For example in GTK+ this
+ * is used for Drag and Drop operations, popup menus and such.
+ *
+ * Note that if the event mask of an X window has selected both button press
+ * and button release events, then a button press event will cause an automatic
+ * pointer grab until the button is released. X does this automatically since
+ * most applications expect to receive button press and release events in pairs.
+ * It is equivalent to a pointer grab on the window with @owner_events set to
+ * %TRUE.
+ *
+ * If you set up anything at the time you take the grab that needs to be
+ * cleaned up when the grab ends, you should handle the #GdkEventGrabBroken
+ * events that are emitted when the grab ends unvoluntarily.
+ *
+ * Returns: %GDK_GRAB_SUCCESS if the grab was successful.
+ **/
 GdkGrabStatus
 gdk_device_grab (GdkDevice        *device,
                  GdkWindow        *window,
diff --git a/gdk/gdkdevicemanager.c b/gdk/gdkdevicemanager.c
index 8d7c20e..445bbfa 100644
--- a/gdk/gdkdevicemanager.c
+++ b/gdk/gdkdevicemanager.c
@@ -75,6 +75,15 @@ gdk_device_manager_class_init (GdkDeviceManagerClass *klass)
 							GDK_TYPE_DISPLAY,
  							G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+  /**
+   * GdkDeviceManager::device-added:
+   * @device_manager: the object on which the signal is emitted
+   * @device: the newly added #GdkDevice.
+   *
+   * The ::device-added signal is emitted either when a new master
+   * pointer is created, or when a slave (Hardware) input device
+   * is plugged in.
+   */
   signals [DEVICE_ADDED] =
     g_signal_new (g_intern_static_string ("device-added"),
                   G_TYPE_FROM_CLASS (klass),
@@ -85,6 +94,15 @@ gdk_device_manager_class_init (GdkDeviceManagerClass *klass)
                   G_TYPE_NONE, 1,
                   GDK_TYPE_DEVICE);
 
+  /**
+   * GdkDeviceManager::device-removed:
+   * @device_manager: the object on which the signal is emitted
+   * @device: the just removed #GdkDevice.
+   *
+   * The ::device-added signal is emitted either when a master
+   * pointer is removed, or when a slave (Hardware) input device
+   * is unplugged.
+   */
   signals [DEVICE_REMOVED] =
     g_signal_new (g_intern_static_string ("device-removed"),
                   G_TYPE_FROM_CLASS (klass),
@@ -95,6 +113,18 @@ gdk_device_manager_class_init (GdkDeviceManagerClass *klass)
                   G_TYPE_NONE, 1,
                   GDK_TYPE_DEVICE);
 
+  /**
+   * GdkDeviceManager::device-changed:
+   * @device_manager: the object on which the signal is emitted
+   * @device: the #GdkDevice that changed.
+   *
+   * The ::device-changed signal is emitted either when some
+   * #GdkDevice has changed the number of either axes or keys.
+   * For example In X this will normally happen when the slave
+   * device routing events through the master device changes,
+   * in that case the master device will change to reflect the
+   * new slave device axes and keys.
+   */
   signals [DEVICE_CHANGED] =
     g_signal_new (g_intern_static_string ("device-changed"),
                   G_TYPE_FROM_CLASS (klass),
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index 90f143e..10d308d 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -623,6 +623,17 @@ _gdk_display_enable_motion_hints (GdkDisplay *display)
     }
 }
 
+/**
+ * gdk_display_get_device_state:
+ * @display: a #GdkDisplay.
+ * @device: device to query status to.
+ * @screen: location to store the #GdkScreen the @device is on, or %NULL.
+ * @x: location to store root window X coordinate of @device, or %NULL.
+ * @y: location to store root window Y coordinate of @device, or %NULL.
+ * @mask: location to store current modifier mask for @device, or %NULL.
+ *
+ * Gets the current location and state of @device for a given display.
+ **/
 void
 gdk_display_get_device_state (GdkDisplay       *display,
                               GdkDevice        *device,
@@ -650,6 +661,18 @@ gdk_display_get_device_state (GdkDisplay       *display,
     *mask = tmp_mask;
 }
 
+/**
+ * gdk_display_get_window_at_device_position:
+ * @display: a #GdkDisplay.
+ * @device: #GdkDevice to query info to.
+ * @win_x: return location for the X coordinate of the device location, relative to the window origin, or %NULL.
+ * @win_y: return location for the Y coordinate of the device location, relative to the window origin, or %NULL.
+ *
+ * Obtains the window underneath @device, returning the location of the device in @win_x and @win_y. Returns
+ * %NULL if the window tree under @device is not known to GDK (for example, belongs to another application).
+ *
+ * Returns: the #GdkWindow under the device position, or %NULL.
+ **/
 GdkWindow *
 gdk_display_get_window_at_device_position (GdkDisplay *display,
                                            GdkDevice  *device,
@@ -672,6 +695,18 @@ gdk_display_get_window_at_device_position (GdkDisplay *display,
   return window;
 }
 
+/**
+ * gdk_display_set_device_hooks:
+ * @display: a #GdkDisplay.
+ * @new_hooks: a table of pointers to functions for getting quantities related to all
+ *             devices position, or %NULL to restore the default table.
+ *
+ * This function allows for hooking into the operation of getting the current location of any
+ * #GdkDevice on a particular #GdkDisplay. This is only useful for such low-level tools as
+ * an event recorder. Applications should never have any reason to use this facility.
+ *
+ * Returns: The previous device hook table.
+ **/
 GdkDisplayDeviceHooks *
 gdk_display_set_device_hooks (GdkDisplay                  *display,
                               const GdkDisplayDeviceHooks *new_hooks)
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index 58bb9fa..80a621b 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -918,6 +918,15 @@ gdk_event_get_axis (const GdkEvent *event,
   return gdk_device_get_axis (device, axes, axis_use, value);
 }
 
+/**
+ * gdk_event_get_device:
+ * @event: a #GdkEvent.
+ *
+ * If the event contains a "device" field, this function will return
+ * it, else it will return %NULL.
+ *
+ * Returns: a #GdkDevice, or %NULL.
+ **/
 GdkDevice *
 gdk_event_get_device (const GdkEvent *event)
 {
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 142ac61..ac4f422 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -5883,6 +5883,22 @@ gdk_window_get_pointer (GdkWindow	  *window,
   return gdk_window_get_device_position (window, display->core_pointer, x, y, mask);
 }
 
+/**
+ * gdk_window_get_device_position:
+ * @window: a #GdkWindow.
+ * @device: #GdkDevice to query to.
+ * @x: return location for the X coordinate of @device, or %NULL.
+ * @y: return location for the Y coordinate of @device, or %NULL.
+ * @mask: return location for the modifier mask, or %NULL.
+ *
+ * Obtains the current device position and modifier state.
+ * The position is given in coordinates relative to the upper left
+ * corner of @window.
+ *
+ * Returns: The window underneath @device (as with
+ * gdk_display_get_window_at_device_position()), or %NULL if the
+ * window is not known to GDK.
+ **/
 GdkWindow *
 gdk_window_get_device_position (GdkWindow       *window,
                                 GdkDevice       *device,
@@ -6548,9 +6564,10 @@ gdk_window_withdraw (GdkWindow *window)
  * @event_mask: event mask for @window
  *
  * The event mask for a window determines which events will be reported
- * for that window. For example, an event mask including #GDK_BUTTON_PRESS_MASK
- * means the window should report button press events. The event mask
- * is the bitwise OR of values from the #GdkEventMask enumeration.
+ * for that window from all master input devices. For example, an event mask
+ * including #GDK_BUTTON_PRESS_MASK means the window should report button
+ * press events. The event mask is the bitwise OR of values from the
+ * #GdkEventMask enumeration.
  **/
 void
 gdk_window_set_events (GdkWindow       *window,
@@ -6584,7 +6601,8 @@ gdk_window_set_events (GdkWindow       *window,
  * gdk_window_get_events:
  * @window: a #GdkWindow
  *
- * Gets the event mask for @window. See gdk_window_set_events().
+ * Gets the event mask for @window for all master input devices. See
+ * gdk_window_set_events().
  *
  * Return value: event mask for @window
  **/
@@ -6602,6 +6620,18 @@ gdk_window_get_events (GdkWindow *window)
   return private->event_mask;
 }
 
+/**
+ * gdk_window_set_device_events:
+ * @window: a #GdkWindow
+ * @device: #GdkDevice to enable events for.
+ * @event_mask: event mask for @window
+ *
+ * Sets the event mask for a given device (Normally a floating device, not
+ * attached to any visible pointer) to @window. For example, an event mask
+ * including #GDK_BUTTON_PRESS_MASK means the window should report button
+ * press events. The event mask is the bitwise OR of values from the
+ * #GdkEventMask enumeration.
+ **/
 void
 gdk_window_set_device_events (GdkWindow    *window,
                               GdkDevice    *device,
@@ -6661,6 +6691,15 @@ gdk_window_set_device_events (GdkWindow    *window,
   GDK_DEVICE_GET_CLASS (device)->select_window_events (device, window, device_mask);
 }
 
+/**
+ * gdk_window_get_device_events:
+ * @window: a #GdkWindow.
+ * @device: a #GdkDevice.
+ *
+ * Returns the event mask for @window corresponding to an specific device.
+ *
+ * Returns: device event mask for @window
+ **/
 GdkEventMask
 gdk_window_get_device_events (GdkWindow *window,
                               GdkDevice *device)
@@ -7403,7 +7442,7 @@ gdk_window_get_cursor (GdkWindow *window)
  * @window: a #GdkWindow
  * @cursor: a cursor
  *
- * Sets the mouse pointer for a #GdkWindow. Use gdk_cursor_new_for_display()
+ * Sets the default mouse pointer for a #GdkWindow. Use gdk_cursor_new_for_display()
  * or gdk_cursor_new_from_pixmap() to create the cursor. To make the cursor
  * invisible, use %GDK_BLANK_CURSOR. Passing %NULL for the @cursor argument
  * to gdk_window_set_cursor() means that @window will use the cursor of its
@@ -7440,6 +7479,20 @@ gdk_window_set_cursor (GdkWindow *window,
     }
 }
 
+/**
+ * gdk_window_get_device_cursor:
+ * @window: a #GdkWindow.
+ * @device: a #GdkDevice.
+ *
+ * Retrieves a #GdkCursor pointer for the @device currently set on the
+ * specified #GdkWindow, or %NULL.  If the return value is %NULL then
+ * there is no custom cursor set on the specified window, and it is
+ * using the cursor for its parent window.
+ *
+ * Returns: a #GdkCursor, or %NULL. The returned object is owned
+ *   by the #GdkWindow and should not be unreferenced directly. Use
+ *   gdk_window_set_cursor() to unset the cursor of the window
+ **/
 GdkCursor *
 gdk_window_get_device_cursor (GdkWindow *window,
                               GdkDevice *device)
@@ -7454,6 +7507,19 @@ gdk_window_get_device_cursor (GdkWindow *window,
   return g_hash_table_lookup (private->device_cursor, device);
 }
 
+/**
+ * gdk_window_set_device_cursor:
+ * @window: a #Gdkwindow
+ * @device: a #GdkDevice
+ * @cursor: a #GdkCursor
+ *
+ * Sets a specific #GdkCursor for a given device when it gets inside @window.
+ * Use gdk_cursor_new_for_display() or gdk_cursor_new_from_pixmap() to create
+ * the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. Passing
+ * %NULL for the @cursor argument to gdk_window_set_cursor() means that
+ * @window will use the cursor of its parent window. Most windows should
+ * use this default.
+ **/
 void
 gdk_window_set_device_cursor (GdkWindow *window,
                               GdkDevice *device,
@@ -8779,6 +8845,16 @@ gdk_window_beep (GdkWindow *window)
     gdk_display_beep (display);
 }
 
+/**
+ * gdk_window_set_support_multidevice:
+ * @window: a #GdkWindow.
+ * @support_multidevice: %TRUE to enable multidevice support in @window.
+ *
+ * This function will enable multidevice features in @window.
+ *
+ * Multidevice aware windows will need to handle properly some things such
+ * as multiple per enter/leave events (one per device) and grab ownerships.
+ **/
 void
 gdk_window_set_support_multidevice (GdkWindow *window,
                                     gboolean   support_multidevice)
@@ -8798,6 +8874,15 @@ gdk_window_set_support_multidevice (GdkWindow *window,
   /* FIXME: What to do if called when some pointers are inside the window ? */
 }
 
+/**
+ * gdk_window_get_support_multidevice:
+ * @window: a #GdkWindow.
+ *
+ * Returns %TRUE if the window is aware of the existence of multiple
+ * devices.
+ *
+ * Returns: %TRUE if the window handles multidevice features.
+ **/
 gboolean
 gdk_window_get_support_multidevice (GdkWindow *window)
 {
diff --git a/gdk/x11/gdkwindow-x11.c b/gdk/x11/gdkwindow-x11.c
index 5088444..8578d57 100644
--- a/gdk/x11/gdkwindow-x11.c
+++ b/gdk/x11/gdkwindow-x11.c
@@ -3207,6 +3207,26 @@ gdk_display_warp_pointer (GdkDisplay *display,
   GDK_DEVICE_GET_CLASS (device)->warp (device, screen, x, y);
 }
 
+/**
+ * gdk_display_warp_device:
+ * @display: a #GdkDisplay.
+ * @device: a #GdkDevice.
+ * @screen: the screen of @display to warp @device to.
+ * @x: the X coordinate of the destination.
+ * @y: the Y coordinate of the destination.
+ *
+ * Warps @device in @display to the point @x,@y on
+ * the screen @screen, unless the device is confined
+ * to a window by a grab, in which case it will be moved
+ * as far as allowed by the grab. Warping the pointer
+ * creates events as if the user had moved the mouse
+ * instantaneously to the destination.
+ *
+ * Note that the pointer should normally be under the
+ * control of the user. This function was added to cover
+ * some rare use cases like keyboard navigation support
+ * for the color picker in the #GtkColorSelectionDialog.
+ **/
 void
 gdk_display_warp_device (GdkDisplay *display,
                          GdkDevice  *device,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]