/* * AT-SPI - Assistive Technology Service Provider Interface * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap) * * Copyright 2001 Sun Microsystems, Inc. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ #include 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,/**< 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 */ }; };