X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=atk%2Fatkcomponent.c;h=9be4011eea389cc32894aeeddf088ac5c41d3a86;hb=refs%2Fchanges%2F24%2F93124%2F1;hp=6e9bd573c1c76884e040453a554c192f56cf98c2;hpb=5d9db2b46dfe8cfa91948d8f45f22e6f14f12fd6;p=platform%2Fupstream%2Fatk.git

diff --git a/atk/atkcomponent.c b/atk/atkcomponent.c
index 6e9bd57..9be4011 100755
--- a/atk/atkcomponent.c
+++ b/atk/atkcomponent.c
@@ -17,9 +17,29 @@
  * Boston, MA 02111-1307, USA.
  */
 
+#include "config.h"
 
 #include "atkcomponent.h"
 
+/**
+ * SECTION:atkcomponent
+ * @Short_description: The ATK interface provided by UI components
+ * which occupy a physical area on the screen.
+ * which the user can activate/interact with.
+ * @Title:AtkComponent
+ *
+ * #AtkComponent should be implemented by most if not all UI elements
+ * with an actual on-screen presence, i.e. components which can be
+ * said to have a screen-coordinate bounding box.  Virtually all
+ * widgets will need to have #AtkComponent implementations provided
+ * for their corresponding #AtkObject class.  In short, only UI
+ * elements which are *not* GUI elements will omit this ATK interface.
+ *
+ * A possible exception might be textual information with a
+ * transparent background, in which case text glyph bounding box
+ * information is provided by #AtkText.
+ */
+
 enum {
   BOUNDS_CHANGED,
   LAST_SIGNAL
@@ -80,6 +100,15 @@ atk_component_base_init (AtkComponentIface *class)
       class->get_position = atk_component_real_get_position;
       class->get_size = atk_component_real_get_size;
 
+
+      /**
+       * AtkComponent::bounds-changed:
+       * @atkcomponent: the object which received the signal.
+       * @arg1: The AtkRectangle giving the new position and size.
+       *
+       * The 'bounds-changed" signal is emitted when the bposition or
+       * size of the component changes.
+       */
       atk_component_signals[BOUNDS_CHANGED] =
         g_signal_new ("bounds_changed",
                       ATK_TYPE_COMPONENT,
@@ -104,7 +133,10 @@ atk_component_base_init (AtkComponentIface *class)
  * when this object receives focus events (in or out). If the handler is
  * already added it is not added again
  *
- * Returns: a handler id which can be used in atk_component_remove_focus_handler
+ * Deprecated: 2.9.4: If you need to track when an object gains or
+ * lose the focus, use state-changed:focused notification instead.
+ *
+ * Returns: a handler id which can be used in atk_component_remove_focus_handler()
  * or zero if the handler was already added.
  **/
 guint
@@ -131,6 +163,10 @@ atk_component_add_focus_handler (AtkComponent    *component,
  * Remove the handler specified by @handler_id from the list of
  * functions to be executed when this object receives focus events 
  * (in or out).
+ *
+ * Deprecated: 2.9.4: If you need to track when an object gains or
+ * lose the focus, use state-changed:focused notification instead.
+ *
  **/
 void
 atk_component_remove_focus_handler (AtkComponent    *component,
@@ -155,6 +191,10 @@ atk_component_remove_focus_handler (AtkComponent    *component,
  *
  * Checks whether the specified point is within the extent of the @component.
  *
+ * Toolkit implementor note: ATK provides a default implementation for
+ * this virtual method. In general there are little reason to
+ * re-implement it.
+ *
  * Returns: %TRUE or %FALSE indicating whether the specified point is within
  * the extent of the @component or not
  **/
@@ -186,7 +226,8 @@ atk_component_contains (AtkComponent    *component,
  * Gets a reference to the accessible child, if one exists, at the
  * coordinate point specified by @x and @y.
  *
- * Returns: a reference to the accessible child, if one exists
+ * Returns: (nullable) (transfer full): a reference to the accessible
+ * child, if one exists
  **/
 AtkObject*
 atk_component_ref_accessible_at_point (AtkComponent    *component,
@@ -265,6 +306,8 @@ atk_component_get_extents    (AtkComponent    *component,
  *
  * Gets the position of @component in the form of 
  * a point specifying @component's top-left corner.
+ *
+ * Deprecated: Since 2.12. Use atk_component_get_extents() instead.
  **/
 void
 atk_component_get_position   (AtkComponent    *component,
@@ -300,6 +343,8 @@ atk_component_get_position   (AtkComponent    *component,
  * @height: address of #gint to put height of @component
  *
  * Gets the size of the @component in terms of width and height.
+ *
+ * Deprecated: Since 2.12. Use atk_component_get_extents() instead.
  **/
 void
 atk_component_get_size       (AtkComponent    *component,
@@ -385,7 +430,7 @@ atk_component_get_mdi_zorder (AtkComponent *component)
  * (fully opaque).
  *
  * Returns: An alpha value from 0 to 1.0, inclusive.
- * Since: ATK 1.12
+ * Since: 1.12
  **/
 gdouble
 atk_component_get_alpha (AtkComponent    *component)
@@ -424,6 +469,72 @@ atk_component_grab_focus (AtkComponent    *component)
 }
 
 /**
+ * atk_component_grab_highlight:
+ * @component: an #AtkComponent
+ *
+ * Grabs highlight for this @component.
+ *
+ * Returns: %TRUE if successful, %FALSE otherwise.
+ **/
+gboolean
+atk_component_grab_highlight (AtkComponent    *component)
+{
+  AtkComponentIface *iface = NULL;
+  g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
+
+  iface = ATK_COMPONENT_GET_IFACE (component);
+
+  if (iface->grab_highlight)
+    return (iface->grab_highlight) (component);
+  else
+    return FALSE;
+}
+
+/**
+ * atk_component_clear_highlight:
+ * @component: an #AtkComponent
+ *
+ * Clears highlight for this @component.
+ *
+ * Returns: %TRUE if successful, %FALSE otherwise.
+ **/
+gboolean
+atk_component_clear_highlight (AtkComponent    *component)
+{
+  AtkComponentIface *iface = NULL;
+  g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
+
+  iface = ATK_COMPONENT_GET_IFACE (component);
+
+  if (iface->clear_highlight)
+    return (iface->clear_highlight) (component);
+  else
+    return FALSE;
+}
+
+/**
+ * atk_component_get_highlight_index:
+ * @component: an #AtkComponent
+ *
+ * Returns: highlight index of the @component (if >0),
+ * 0 if highlight index is not set or -1 if an error occured.
+ *
+ **/
+gint
+atk_component_get_highlight_index (AtkComponent    *component)
+{
+  AtkComponentIface *iface = NULL;
+  g_return_val_if_fail (ATK_IS_COMPONENT (component), -1);
+
+  iface = ATK_COMPONENT_GET_IFACE (component);
+
+  if (iface->get_highlight_index)
+    return (iface->get_highlight_index) (component);
+  else
+    return -1;
+}
+
+/**
  * atk_component_set_extents:
  * @component: an #AtkComponent
  * @x: x coordinate
@@ -590,12 +701,6 @@ atk_component_real_get_size (AtkComponent *component,
   atk_component_get_extents (component, &x, &y, width, height, coord_type);
 }
 
-static gdouble
-atk_component_real_get_alpha (AtkComponent    *component)
-{
-    return (gdouble) 1.0;
-}
-
 static AtkRectangle *
 atk_rectangle_copy (const AtkRectangle *rectangle)
 {