atk-1.0/atk/atkcomponent.h

0001 /* ATK -  Accessibility Toolkit
0002  * Copyright 2001 Sun Microsystems Inc.
0003  *
0004  * This library is free software; you can redistribute it and/or
0005  * modify it under the terms of the GNU Library General Public
0006  * License as published by the Free Software Foundation; either
0007  * version 2 of the License, or (at your option) any later version.
0008  *
0009  * This library is distributed in the hope that it will be useful,
0010  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0012  * Library General Public License for more details.
0013  *
0014  * You should have received a copy of the GNU Library General Public
0015  * License along with this library; if not, write to the
0016  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
0017  * Boston, MA 02111-1307, USA.
0018  */
0019
0020 #ifndef __ATK_COMPONENT_H__
0021 #define __ATK_COMPONENT_H__
0022
0023 #if defined(ATK_DISABLE_SINGLE_INCLUDES) && !defined(__ATK_H_INSIDE__) && !defined(ATK_COMPILATION)
0024 #error "Only <atk/atk.h> can be included directly."
0025 #endif
0026
0027 #include <atk/atkobject.h>
0028 #include <atk/atkutil.h>
0029
0030 G_BEGIN_DECLS
0031
0032 /**
0033  * AtkScrollType:
0034  * @ATK_SCROLL_TOP_LEFT: Scroll the object vertically and horizontally to bring
0035  *   its top left corner to the top left corner of the window.
0036  * @ATK_SCROLL_BOTTOM_RIGHT: Scroll the object vertically and horizontally to
0037  *   bring its bottom right corner to the bottom right corner of the window.
0038  * @ATK_SCROLL_TOP_EDGE: Scroll the object vertically to bring its top edge to
0039  *   the top edge of the window.
0040  * @ATK_SCROLL_BOTTOM_EDGE: Scroll the object vertically to bring its bottom
0041  *   edge to the bottom edge of the window.
0042  * @ATK_SCROLL_LEFT_EDGE: Scroll the object vertically and horizontally to bring
0043  *   its left edge to the left edge of the window.
0044  * @ATK_SCROLL_RIGHT_EDGE: Scroll the object vertically and horizontally to
0045  *   bring its right edge to the right edge of the window.
0046  * @ATK_SCROLL_ANYWHERE: Scroll the object vertically and horizontally so that
0047  *   as much as possible of the object becomes visible. The exact placement is
0048  *   determined by the application.
0049  *
0050  * Specifies where an object should be placed on the screen when using scroll_to.
0051  *
0052  * Since: 2.30
0053  */
0054 typedef enum
0055 {
0056   ATK_SCROLL_TOP_LEFT,
0057   ATK_SCROLL_BOTTOM_RIGHT,
0058   ATK_SCROLL_TOP_EDGE,
0059   ATK_SCROLL_BOTTOM_EDGE,
0060   ATK_SCROLL_LEFT_EDGE,
0061   ATK_SCROLL_RIGHT_EDGE,
0062   ATK_SCROLL_ANYWHERE
0063 } AtkScrollType;
0064
0065 #define ATK_TYPE_COMPONENT (atk_component_get_type ())
0066 #define ATK_IS_COMPONENT(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_COMPONENT)
0067 #define ATK_COMPONENT(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_COMPONENT, AtkComponent)
0068 #define ATK_COMPONENT_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), ATK_TYPE_COMPONENT, AtkComponentIface))
0069
0070 #ifndef _TYPEDEF_ATK_COMPONENT_
0071 #define _TYPEDEF_ATK_COMPONENT_
0072 typedef struct _AtkComponent AtkComponent;
0073 #endif
0074 typedef struct _AtkComponentIface AtkComponentIface;
0075
0076 /**
0077  * AtkFocusHandler:
0078  * @object: the #AtkObject that receives/lose the focus
0079  * @focus_in: TRUE if the object receives the focus
0080  *
0081  * The type of callback function used for
0082  * atk_component_add_focus_handler() and
0083  * atk_component_remove_focus_handler()
0084  *
0085  * Deprecated: 2.9.4: Deprecated with atk_component_add_focus_handler()
0086  * and atk_component_remove_focus_handler(). See those
0087  * methods for more information.
0088  */
0089 typedef void (*AtkFocusHandler) (AtkObject *object, gboolean focus_in);
0090
0091 typedef struct _AtkRectangle AtkRectangle;
0092
0093 /**
0094  * AtkRectangle:
0095  * @x: X coordinate of the left side of the rectangle.
0096  * @y: Y coordinate of the top side of the rectangle.
0097  * @width: width of the rectangle.
0098  * @height: height of the rectangle.
0099  *
0100  * A data structure for holding a rectangle. Those coordinates are
0101  * relative to the component top-level parent.
0102  */
0103 struct _AtkRectangle
0104 {
0105   gint x;
0106   gint y;
0107   gint width;
0108   gint height;
0109 };
0110
0111 ATK_AVAILABLE_IN_ALL
0112 GType atk_rectangle_get_type (void);
0113
0114 #define ATK_TYPE_RECTANGLE (atk_rectangle_get_type ())
0115
0116 /**
0117  * AtkComponentIface:
0118  * @add_focus_handler: This virtual function is deprecated since 2.9.4
0119  *   and it should not be overriden. See atk_component_add_focus_handler()
0120  *   for more information.
0121  * @get_position: This virtual function is deprecated since 2.12 and
0122  *   it should not be overriden. Use @AtkComponentIface.get_extents instead.
0123  * @get_size: This virtual function is deprecated since 2.12 and it
0124  *   should not be overriden. Use @AtkComponentIface.get_extents instead.
0125  * @remove_focus_handler: This virtual function is deprecated since
0126  *   2.9.4 and it should not be overriden. See atk_component_remove_focus_handler()
0127  *   for more information.
0128  * @contains:
0129  * @ref_accessible_at_point:
0130  * @get_extents:
0131  * @grab_focus:
0132  * @set_extents:
0133  * @set_position:
0134  * @set_size:
0135  * @get_layer:
0136  * @get_mdi_zorder:
0137  * @bounds_changed:
0138  * @get_alpha:
0139  * @scroll_to:
0140  * @scroll_to_point:
0141  *
0142  * The AtkComponent interface should be supported by any object that is
0143  * rendered on the screen. The interface provides the standard mechanism
0144  * for an assistive technology to determine and set the graphical
0145  * representation of an object.
0146  */
0147 struct _AtkComponentIface
0148 {
0149   /*< private >*/
0150   GTypeInterface parent;
0151
0152   /*< public >*/
0153   guint (*add_focus_handler) (AtkComponent *component,
0154                               AtkFocusHandler handler);
0155
0156   gboolean (*contains) (AtkComponent *component,
0157                         gint x,
0158                         gint y,
0159                         AtkCoordType coord_type);
0160
0161   AtkObject *(*ref_accessible_at_point) (AtkComponent *component,
0162                                          gint x,
0163                                          gint y,
0164                                          AtkCoordType coord_type);
0165   void (*get_extents) (AtkComponent *component,
0166                        gint *x,
0167                        gint *y,
0168                        gint *width,
0169                        gint *height,
0170                        AtkCoordType coord_type);
0171   void (*get_position) (AtkComponent *component,
0172                         gint *x,
0173                         gint *y,
0174                         AtkCoordType coord_type);
0175   void (*get_size) (AtkComponent *component,
0176                     gint *width,
0177                     gint *height);
0178   gboolean (*grab_focus) (AtkComponent *component);
0179   void (*remove_focus_handler) (AtkComponent *component,
0180                                 guint handler_id);
0181   gboolean (*set_extents) (AtkComponent *component,
0182                            gint x,
0183                            gint y,
0184                            gint width,
0185                            gint height,
0186                            AtkCoordType coord_type);
0187   gboolean (*set_position) (AtkComponent *component,
0188                             gint x,
0189                             gint y,
0190                             AtkCoordType coord_type);
0191   gboolean (*set_size) (AtkComponent *component,
0192                         gint width,
0193                         gint height);
0194
0195   AtkLayer (*get_layer) (AtkComponent *component);
0196   gint (*get_mdi_zorder) (AtkComponent *component);
0197
0198   /*
0199    * signal handlers
0200    */
0201   void (*bounds_changed) (AtkComponent *component,
0202                           AtkRectangle *bounds);
0203   gdouble (*get_alpha) (AtkComponent *component);
0204
0205   /*
0206    * Scrolls this object so it becomes visible on the screen.
0207    *
0208    * scroll_to lets the implementation compute an appropriate target
0209    * position on the screen, with type used as a positioning hint.
0210    *
0211    * scroll_to_point lets the client specify a precise target position
0212    * on the screen for the top-left of the object.
0213    *
0214    * Since ATK 2.30
0215    */
0216   gboolean (*scroll_to) (AtkComponent *component,
0217                          AtkScrollType type);
0218
0219   gboolean (*scroll_to_point) (AtkComponent *component,
0220                                AtkCoordType coords,
0221                                gint x,
0222                                gint y);
0223 };
0224
0225 ATK_AVAILABLE_IN_ALL
0226 GType atk_component_get_type (void);
0227
0228 /* convenience functions */
0229 ATK_DEPRECATED_IN_2_10
0230 guint atk_component_add_focus_handler (AtkComponent *component,
0231                                        AtkFocusHandler handler);
0232 ATK_AVAILABLE_IN_ALL
0233 gboolean atk_component_contains (AtkComponent *component,
0234                                  gint x,
0235                                  gint y,
0236                                  AtkCoordType coord_type);
0237 ATK_AVAILABLE_IN_ALL
0238 AtkObject *atk_component_ref_accessible_at_point (AtkComponent *component,
0239                                                   gint x,
0240                                                   gint y,
0241                                                   AtkCoordType coord_type);
0242 ATK_AVAILABLE_IN_ALL
0243 void atk_component_get_extents (AtkComponent *component,
0244                                 gint *x,
0245                                 gint *y,
0246                                 gint *width,
0247                                 gint *height,
0248                                 AtkCoordType coord_type);
0249 ATK_DEPRECATED_IN_2_12_FOR (atk_component_get_extents)
0250 void atk_component_get_position (AtkComponent *component,
0251                                  gint *x,
0252                                  gint *y,
0253                                  AtkCoordType coord_type);
0254 ATK_DEPRECATED_IN_2_12_FOR (atk_component_get_extents)
0255 void atk_component_get_size (AtkComponent *component,
0256                              gint *width,
0257                              gint *height);
0258 ATK_AVAILABLE_IN_ALL
0259 AtkLayer atk_component_get_layer (AtkComponent *component);
0260 ATK_AVAILABLE_IN_ALL
0261 gint atk_component_get_mdi_zorder (AtkComponent *component);
0262 ATK_AVAILABLE_IN_ALL
0263 gboolean atk_component_grab_focus (AtkComponent *component);
0264 ATK_DEPRECATED_IN_2_10
0265 void atk_component_remove_focus_handler (AtkComponent *component,
0266                                          guint handler_id);
0267 ATK_AVAILABLE_IN_ALL
0268 gboolean atk_component_set_extents (AtkComponent *component,
0269                                     gint x,
0270                                     gint y,
0271                                     gint width,
0272                                     gint height,
0273                                     AtkCoordType coord_type);
0274 ATK_AVAILABLE_IN_ALL
0275 gboolean atk_component_set_position (AtkComponent *component,
0276                                      gint x,
0277                                      gint y,
0278                                      AtkCoordType coord_type);
0279 ATK_AVAILABLE_IN_ALL
0280 gboolean atk_component_set_size (AtkComponent *component,
0281                                  gint width,
0282                                  gint height);
0283 ATK_AVAILABLE_IN_ALL
0284 gdouble atk_component_get_alpha (AtkComponent *component);
0285
0286 ATK_AVAILABLE_IN_2_30
0287 gboolean atk_component_scroll_to (AtkComponent *component,
0288                                   AtkScrollType type);
0289
0290 ATK_AVAILABLE_IN_2_30
0291 gboolean atk_component_scroll_to_point (AtkComponent *component,
0292                                         AtkCoordType coords,
0293                                         gint x,
0294                                         gint y);
0295
0296 G_END_DECLS
0297
0298 #endif /* __ATK_COMPONENT_H__ */