* Boston, MA 02111-1307, USA.
*/
-#include <Event.idl>
+#include <Accessibility_Event.idl>
module Accessibility {
- interface Component {
+ /**
+ * The ComponentLayer of a Component instance indicates its relative stacking order
+ * with respect to the onscreen visual representation of the UI.
+ * ComponentLayer, in combination with Component bounds information, can be used
+ * to compute the visibility of all or part of a component. This is important in
+ * programmatic determination of region-of-interest for magnification, and in
+ * ¨flat screen review¨ models of the screen, as well as for other uses.
+ * Objects residing in two of the ComponentLayer categories support
+ * further z-ordering information, with respect to their peers in the same layer:
+ * namely, LAYER_WINDOW and LAYER_MDI. Relative stacking order for other objects within
+ * the same layer is not available; the recommended heuristic is ¨first child paints first¨,
+ * in other words, assume that the first siblings in the child list are subject to being
+ * overpainted by later siblings if their bounds intersect.
+ *
+ * The order of layers, from bottom to top, is:
+ * \li LAYER_BACKGROUND
+ * \li LAYER_WINDOW
+ * \li LAYER_MDI
+ * \li LAYER_CANVAS
+ * \li LAYER_WIDGET
+ * \li LAYER_POPUP
+ * \li LAYER_OVERLAY
+ */
+ enum ComponentLayer {
+ LAYER_INVALID,/**< Indicates an error condition or uninitialized value. */
+ LAYER_BACKGROUND,/**< The bottom-most layer, over which everything else is painted.
+ * The 'desktop background' is generally in this layer. */
+ LAYER_CANVAS,/**< The 'background' layer for most content renderers and UI Component
+ * containers. */
+ LAYER_WIDGET,/**< The layer in which the majority of ordinary 'foreground' widgets reside.*/
+ LAYER_MDI,/**< A special layer between LAYER_CANVAS and LAYER_WIDGET, in which the
+ * 'pseudo windows' (e.g. the MDI frames) reside.
+ * @see Component::getMDIZOrder */
+ LAYER_POPUP,/**< A layer for popup window content, above LAYER_WIDGET. */
+ LAYER_OVERLAY,/**< The topmost layer. */
+ LAYER_WINDOW,/**< The layer in which a toplevel window background usually resides. */
+ LAYER_LAST_DEFINED/**< Used only to determine the end of the enumeration. */
+ };
- boolean contains (in long x, in long y);
- Accessible getAccessibleAtPoint (in long x, in long y);
- void getExtents (out long x, out long y, out long width, out long height);
- void getPosition (out long x, out long y);
- void getPositionOnScreen (out long rootX, out long rootY);
+ /**
+ * The Component interface is implemented by objects which occupy on-screen space, e.g. objects
+ * which have onscreen visual representations. The methods in Component allow clients to identify
+ * where the objects lie in the onscreen coordinate system, their relative size, stacking order, and
+ * position. It also provides a mechanism whereby keyboard focus may be transferred to specific
+ * user interface elements programmatically. This is a 2D API, coordinates of 3D objects are projected into the
+ * 2-dimensional screen view for purposes of this interface.
+ *
+ * @note the meaning and defined values of the \c short \c coord_type parameter used by some
+ * Component methods is as follows:
+ * \li 0 indicates coord_type_xy_screen, coordinates are relative to the display screen, in pixels.
+ * \li 1 indicates coord_type_xy_window, coordinates are relative to the current toplevel window, in pixels.
+ *
+ * @note Events emitted by Component instances include:
+ * \li \c "object:bounds-changed"
+ * \li \c "object:visible-data-changed"
+ */
+ interface Component : Bonobo::Unknown {
+
+ /**
+ * @returns \c True if the specified point lies within the Component's bounding box,
+ * \c False otherwise.
+ */
+ boolean contains (in long x, in long y, in short coord_type);
+ /**
+ * @returns the Accessible child whose bounding box contains the specified point.
+ */
+ Accessible getAccessibleAtPoint (in long x, in long y, in short coord_type);
+ /**
+ * Obtain the Component's bounding box, in pixels, relative to the specified coordinate system.
+ * @returns a BoundingBox which entirely contains the object's onscreen visual representation.
+ **/
+ BoundingBox getExtents (in short coord_type);
+ /**
+ * Obtain the position of the current component in the coordinate system specified
+ * by \c coord_type.
+ * @param coord_type
+ * @param x an out parameter which will be back-filled with the returned x coordinate.
+ * @param y an out parameter which will be back-filled with the returned y coordinate.
+ */
+ void getPosition (out long x, out long y, in short coord_type);
+ /**
+ * Obtain the size, in the coordinate system specified by \c coord_type,
+ * of the rectangular area which fully contains the object's
+ * visual representation, without accounting for viewport clipping.
+ * @param width the object's horizontal extents in the specified coordinate system.
+ * @param height the object's vertical extents in the specified coordinate system.
+ */
void getSize (out long width, out long height);
- void grabFocus ();
+ /** @returns the ComponentLayer in which this object resides. */
+ ComponentLayer getLayer ();
+ /**
+ * Obtain the relative stacking order (i.e. 'Z' order) of an object.
+ * Larger values indicate that an object is on "top" of the stack, therefore
+ * objects with smaller MDIZOrder may be obscured by objects with a larger MDIZOrder,
+ * but not vice-versa.
+ * @note only relevant for objects in LAYER_MDI or LAYER_WINDOW
+ * @returns an integer indicating the object's place in the stacking order.
+ */
+ short getMDIZOrder ();
+ /**
+ * Request that the object obtain keyboard focus.
+ *
+ * @returns \c True if keyboard focus was successfully transferred to the Component.
+ */
+ boolean grabFocus ();
+ /**
+ * Register an EventListener for notification when this object receives keyboard focus.
+ * @note you probably want to register for ¨focus:¨ events via
+ * Registry::registerGlobalEventListener instead.
+ */
void registerFocusHandler (in EventListener handler);
+ /**
+ * Request that an EventListener registered via registerFocusHandler no longer be notified
+ * when this object receives keyboard focus.
+ */
void deregisterFocusHandler (in EventListener handler);
- };
+
+ /**
+ * Obtain the alpha value of the component. An alpha value of 1.0 or greater
+ * indicates that the object is fully opaque, and an alpha value of 0.0 indicates
+ * that the object is fully transparent. Negative alpha values have no defined
+ * meaning at this time.
+ *
+ * @note alpha values are used in conjunction with Z-order calculations to
+ * determine whether an object wholly or partially obscures another object's
+ * visual intersection, in the event that their bounds intersect.
+ *
+ * @see STATE_OPAQUE
+ *
+ * @since AT-SPI 1.7.0
+ */
+ double getAlpha ();
+
+ /** \cond
+ * unImplemented:
+ *
+ * placeholders for future expansion.
+ */
+ void unImplemented ();
+ void unImplemented2 ();
+ void unImplemented3 ();
+ /** \endcond */
+ };
};
projects / platform / core / uifw / at-spi2-atk.git / blobdiff