X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=atk%2Fatkcomponent.c;h=f0beb10f7b9fb269439c422e29ea18be8af47565;hb=dd7c22e2586adf23bc7d9f52c793cbf127b2a753;hp=bacc3ef09a74b1004ce719910ed227d3bb631fb8;hpb=f33a524c445c5d72b03e1c01305c60083b7de965;p=platform%2Fupstream%2Fatk.git

diff --git a/atk/atkcomponent.c b/atk/atkcomponent.c
old mode 100755
new mode 100644
index bacc3ef..f0beb10
--- 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,
@@ -87,7 +116,8 @@ atk_component_base_init (AtkComponentIface *class)
                       G_STRUCT_OFFSET (AtkComponentIface, bounds_changed),
                       (GSignalAccumulator) NULL, NULL,
                       g_cclosure_marshal_VOID__BOXED,
-                      G_TYPE_NONE, 0);
+                      G_TYPE_NONE, 1,
+                      ATK_TYPE_RECTANGLE | G_SIGNAL_TYPE_STATIC_SCOPE);
 
       initialized = TRUE;
     }
@@ -95,7 +125,7 @@ atk_component_base_init (AtkComponentIface *class)
 
 
 /**
- * atk_component_add_focus_handler:
+ * atk_component_add_focus_handler: (skip)
  * @component: The #AtkComponent to attach the @handler to
  * @handler: The #AtkFocusHandler to be attached to @component
  *
@@ -103,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 the #AtkObject::state-change "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
@@ -130,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 the #AtkObject::state-change "focused" notification instead.
+ *
  **/
 void
 atk_component_remove_focus_handler (AtkComponent    *component,
@@ -154,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
  **/
@@ -185,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,
@@ -207,10 +249,10 @@ atk_component_ref_accessible_at_point (AtkComponent    *component,
 /**
  * atk_component_get_extents:
  * @component: an #AtkComponent
- * @x: address of #gint to put x coordinate
- * @y: address of #gint to put y coordinate
- * @width: address of #gint to put width
- * @height: address of #gint to put height
+ * @x: (out) (optional): address of #gint to put x coordinate
+ * @y: (out) (optional): address of #gint to put y coordinate
+ * @width: (out) (optional): address of #gint to put width
+ * @height: (out) (optional): address of #gint to put height
  * @coord_type: specifies whether the coordinates are relative to the screen
  * or to the components top level window
  *
@@ -257,13 +299,15 @@ atk_component_get_extents    (AtkComponent    *component,
 /**
  * atk_component_get_position:
  * @component: an #AtkComponent
- * @x: address of #gint to put x coordinate position
- * @y: address of #gint to put y coordinate position
+ * @x: (out) (optional): address of #gint to put x coordinate position
+ * @y: (out) (optional): address of #gint to put y coordinate position
  * @coord_type: specifies whether the coordinates are relative to the screen
  * or to the components top level window
  *
  * 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,
@@ -295,10 +339,12 @@ atk_component_get_position   (AtkComponent    *component,
 /**
  * atk_component_get_size:
  * @component: an #AtkComponent
- * @width: address of #gint to put width of @component
- * @height: address of #gint to put height of @component
+ * @width: (out) (optional): address of #gint to put width of @component
+ * @height: (out) (optional): 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,
@@ -376,6 +422,31 @@ atk_component_get_mdi_zorder (AtkComponent *component)
 }
 
 /**
+ * atk_component_get_alpha:
+ * @component: an #AtkComponent
+ *
+ * Returns the alpha value (i.e. the opacity) for this
+ * @component, on a scale from 0 (fully transparent) to 1.0
+ * (fully opaque).
+ *
+ * Returns: An alpha value from 0 to 1.0, inclusive.
+ * Since: 1.12
+ **/
+gdouble
+atk_component_get_alpha (AtkComponent    *component)
+{
+  AtkComponentIface *iface;
+
+  g_return_val_if_fail (ATK_IS_COMPONENT (component), G_MININT);
+
+  iface = ATK_COMPONENT_GET_IFACE (component);
+  if (iface->get_alpha)
+    return (iface->get_alpha) (component);
+  else
+    return (gdouble) 1.0;
+}
+
+/**
  * atk_component_grab_focus:
  * @component: an #AtkComponent
  *
@@ -564,5 +635,24 @@ atk_component_real_get_size (AtkComponent *component,
   atk_component_get_extents (component, &x, &y, width, height, coord_type);
 }
 
+static AtkRectangle *
+atk_rectangle_copy (const AtkRectangle *rectangle)
+{
+  AtkRectangle *result = g_new (AtkRectangle, 1);
+  *result = *rectangle;
+
+  return result;
+}
+
+GType
+atk_rectangle_get_type (void)
+{
+  static GType our_type = 0;
 
+  if (our_type == 0)
+    our_type = g_boxed_type_register_static ("AtkRectangle",
+                                             (GBoxedCopyFunc)atk_rectangle_copy,
+                                             (GBoxedFreeFunc)g_free);
+  return our_type;
+}