X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=idl%2FAccessibility_Component.idl;h=f4f063ea1ce6d60af2ec123e79b68bf98467b4b8;hb=47fb2ca13ddf2a891a0439c8046a7800ef5d8aee;hp=cb88cf0b3be54eaaa5e7463f9ed5a74081e199f5;hpb=a90cc5cacb5efd233b714287297034c079def8aa;p=platform%2Fcore%2Fuifw%2Fat-spi2-atk.git diff --git a/idl/Accessibility_Component.idl b/idl/Accessibility_Component.idl index cb88cf0..f4f063e 100644 --- a/idl/Accessibility_Component.idl +++ b/idl/Accessibility_Component.idl @@ -24,36 +24,147 @@ module Accessibility { + /** + * 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, - LAYER_BACKGROUND, - LAYER_CANVAS, - LAYER_WIDGET, - LAYER_MDI, - LAYER_POPUP, - LAYER_OVERLAY, - LAYER_LAST_DEFINED + 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. */ }; + /** + * 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); + /** @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 */ }; };