Blame atk/atkstate.h

Packit Service ef73c4
/* ATK -  Accessibility Toolkit
Packit Service ef73c4
 * Copyright 2001 Sun Microsystems Inc.
Packit Service ef73c4
 *
Packit Service ef73c4
 * This library is free software; you can redistribute it and/or
Packit Service ef73c4
 * modify it under the terms of the GNU Library General Public
Packit Service ef73c4
 * License as published by the Free Software Foundation; either
Packit Service ef73c4
 * version 2 of the License, or (at your option) any later version.
Packit Service ef73c4
 *
Packit Service ef73c4
 * This library is distributed in the hope that it will be useful,
Packit Service ef73c4
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
Packit Service ef73c4
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Packit Service ef73c4
 * Library General Public License for more details.
Packit Service ef73c4
 *
Packit Service ef73c4
 * You should have received a copy of the GNU Library General Public
Packit Service ef73c4
 * License along with this library; if not, write to the
Packit Service ef73c4
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Packit Service ef73c4
 * Boston, MA 02111-1307, USA.
Packit Service ef73c4
 */
Packit Service ef73c4
Packit Service ef73c4
#ifndef __ATK_STATE_H__
Packit Service ef73c4
#define __ATK_STATE_H__
Packit Service ef73c4
Packit Service ef73c4
#if defined(ATK_DISABLE_SINGLE_INCLUDES) && !defined (__ATK_H_INSIDE__) && !defined (ATK_COMPILATION)
Packit Service ef73c4
#error "Only <atk/atk.h> can be included directly."
Packit Service ef73c4
#endif
Packit Service ef73c4
Packit Service ef73c4
#include <glib-object.h>
Packit Service ef73c4
#include <atk/atkversion.h>
Packit Service ef73c4
Packit Service ef73c4
G_BEGIN_DECLS
Packit Service ef73c4
Packit Service ef73c4
/**
Packit Service ef73c4
 *AtkStateType:
Packit Service ef73c4
 *@ATK_STATE_INVALID: Indicates an invalid state - probably an error condition.
Packit Service ef73c4
 *@ATK_STATE_ACTIVE: Indicates a window is currently the active window, or an object is the active subelement within a container or table. ATK_STATE_ACTIVE should not be used for objects which have ATK_STATE_FOCUSABLE or ATK_STATE_SELECTABLE: Those objects should use ATK_STATE_FOCUSED and ATK_STATE_SELECTED respectively. ATK_STATE_ACTIVE is a means to indicate that an object which is not focusable and not selectable is the currently-active item within its parent container.
Packit Service ef73c4
 *@ATK_STATE_ARMED: Indicates that the object is 'armed', i.e. will be activated by if a pointer button-release event occurs within its bounds.  Buttons often enter this state when a pointer click occurs within their bounds, as a precursor to activation. ATK_STATE_ARMED has been deprecated since ATK-2.16 and should not be used in newly-written code.
Packit Service ef73c4
 *@ATK_STATE_BUSY:  Indicates the current object is busy, i.e. onscreen representation is in the process of changing, or the object is temporarily unavailable for interaction due to activity already in progress.  This state may be used by implementors of Document to indicate that content loading is underway.  It also may indicate other 'pending' conditions; clients may wish to interrogate this object when the ATK_STATE_BUSY flag is removed.
Packit Service ef73c4
 *@ATK_STATE_CHECKED: Indicates this object is currently checked, for instance a checkbox is 'non-empty'.
Packit Service ef73c4
 *@ATK_STATE_DEFUNCT: Indicates that this object no longer has a valid backing widget (for instance, if its peer object has been destroyed)
Packit Service ef73c4
 *@ATK_STATE_EDITABLE: Indicates that this object can contain text, and that the
Packit Service ef73c4
 * user can change the textual contents of this object by editing those contents
Packit Service ef73c4
 * directly. For an object which is expected to be editable due to its type, but
Packit Service ef73c4
 * which cannot be edited due to the application or platform preventing the user
Packit Service ef73c4
 * from doing so, that object's #AtkStateSet should lack ATK_STATE_EDITABLE and
Packit Service ef73c4
 * should contain ATK_STATE_READ_ONLY.
Packit Service ef73c4
 *@ATK_STATE_ENABLED: 	Indicates that this object is enabled, i.e. that it currently reflects some application state. Objects that are "greyed out" may lack this state, and may lack the STATE_SENSITIVE if direct user interaction cannot cause them to acquire STATE_ENABLED. See also: ATK_STATE_SENSITIVE
Packit Service ef73c4
 *@ATK_STATE_EXPANDABLE: Indicates this object allows progressive disclosure of its children
Packit Service ef73c4
 *@ATK_STATE_EXPANDED: Indicates this object its expanded - see ATK_STATE_EXPANDABLE above
Packit Service ef73c4
 *@ATK_STATE_FOCUSABLE: Indicates this object can accept keyboard focus, which means all events resulting from typing on the keyboard will normally be passed to it when it has focus
Packit Service ef73c4
 *@ATK_STATE_FOCUSED: Indicates this object currently has the keyboard focus
Packit Service ef73c4
 *@ATK_STATE_HORIZONTAL: Indicates the orientation of this object is horizontal; used, for instance, by objects of ATK_ROLE_SCROLL_BAR.  For objects where vertical/horizontal orientation is especially meaningful.
Packit Service ef73c4
 *@ATK_STATE_ICONIFIED: Indicates this object is minimized and is represented only by an icon
Packit Service ef73c4
 *@ATK_STATE_MODAL: Indicates something must be done with this object before the user can interact with an object in a different window
Packit Service ef73c4
 *@ATK_STATE_MULTI_LINE: Indicates this (text) object can contain multiple lines of text
Packit Service ef73c4
 *@ATK_STATE_MULTISELECTABLE: Indicates this object allows more than one of its children to be selected at the same time, or in the case of text objects, that the object supports non-contiguous text selections.
Packit Service ef73c4
 *@ATK_STATE_OPAQUE: Indicates this object paints every pixel within its rectangular region.
Packit Service ef73c4
 *@ATK_STATE_PRESSED: Indicates this object is currently pressed.
Packit Service ef73c4
 *@ATK_STATE_RESIZABLE: Indicates the size of this object is not fixed
Packit Service ef73c4
 *@ATK_STATE_SELECTABLE: Indicates this object is the child of an object that allows its children to be selected and that this child is one of those children that can be selected
Packit Service ef73c4
 *@ATK_STATE_SELECTED: Indicates this object is the child of an object that allows its children to be selected and that this child is one of those children that has been selected
Packit Service ef73c4
 *@ATK_STATE_SENSITIVE: Indicates this object is sensitive, e.g. to user interaction. 
Packit Service ef73c4
 * STATE_SENSITIVE usually accompanies STATE_ENABLED for user-actionable controls,
Packit Service ef73c4
 * but may be found in the absence of STATE_ENABLED if the current visible state of the 
Packit Service ef73c4
 * control is "disconnected" from the application state.  In such cases, direct user interaction
Packit Service ef73c4
 * can often result in the object gaining STATE_SENSITIVE, for instance if a user makes 
Packit Service ef73c4
 * an explicit selection using an object whose current state is ambiguous or undefined.
Packit Service ef73c4
 * @see STATE_ENABLED, STATE_INDETERMINATE.
Packit Service ef73c4
 *@ATK_STATE_SHOWING: Indicates this object, the object's parent, the object's parent's parent, and so on, 
Packit Service ef73c4
 * are all 'shown' to the end-user, i.e. subject to "exposure" if blocking or obscuring objects do not interpose
Packit Service ef73c4
 * between this object and the top of the window stack.
Packit Service ef73c4
 *@ATK_STATE_SINGLE_LINE: Indicates this (text) object can contain only a single line of text
Packit Service ef73c4
 *@ATK_STATE_STALE: Indicates that the information returned for this object may no longer be
Packit Service ef73c4
 * synchronized with the application state.  This is implied if the object has STATE_TRANSIENT,
Packit Service ef73c4
 * and can also occur towards the end of the object peer's lifecycle. It can also be used to indicate that 
Packit Service ef73c4
 * the index associated with this object has changed since the user accessed the object (in lieu of
Packit Service ef73c4
 * "index-in-parent-changed" events).
Packit Service ef73c4
 *@ATK_STATE_TRANSIENT: Indicates this object is transient, i.e. a snapshot which may not emit events when its
Packit Service ef73c4
 * state changes.  Data from objects with ATK_STATE_TRANSIENT should not be cached, since there may be no
Packit Service ef73c4
 * notification given when the cached data becomes obsolete.
Packit Service ef73c4
 *@ATK_STATE_VERTICAL: Indicates the orientation of this object is vertical
Packit Service ef73c4
 *@ATK_STATE_VISIBLE: Indicates this object is visible, e.g. has been explicitly marked for exposure to the user.
Packit Service ef73c4
 * @note: STATE_VISIBLE is no guarantee that the object is actually unobscured on the screen, only
Packit Service ef73c4
 * that it is 'potentially' visible, barring obstruction, being scrolled or clipped out of the 
Packit Service ef73c4
 * field of view, or having an ancestor container that has not yet made visible.
Packit Service ef73c4
 * A widget is potentially onscreen if it has both STATE_VISIBLE and STATE_SHOWING.
Packit Service ef73c4
 * The absence of STATE_VISIBLE and STATE_SHOWING is semantically equivalent to saying 
Packit Service ef73c4
 * that an object is 'hidden'.  See also STATE_TRUNCATED, which applies if a VISIBLE and SHOWING object
Packit Service ef73c4
 * lies within a viewport which means that its contents are clipped, e.g. a truncated spreadsheet cell or
Packit Service ef73c4
 * an image within a scrolling viewport.  Mostly useful for screen-review and magnification algorithms.
Packit Service ef73c4
 *@ATK_STATE_MANAGES_DESCENDANTS: Indicates that "active-descendant-changed" event
Packit Service ef73c4
 * is sent when children become 'active' (i.e. are selected or navigated to onscreen).
Packit Service ef73c4
 * Used to prevent need to enumerate all children in very large containers, like tables.
Packit Service ef73c4
 * The presence of STATE_MANAGES_DESCENDANTS is an indication to the client.
Packit Service ef73c4
 * that the children should not, and need not, be enumerated by the client.
Packit Service ef73c4
 * Objects implementing this state are expected to provide relevant state
Packit Service ef73c4
 * notifications to listening clients, for instance notifications of visibility
Packit Service ef73c4
 * changes and activation of their contained child objects, without the client 
Packit Service ef73c4
 * having previously requested references to those children.
Packit Service ef73c4
 *@ATK_STATE_INDETERMINATE: Indicates that the value, or some other quantifiable
Packit Service ef73c4
 * property, of this AtkObject cannot be fully determined. In the case of a large
Packit Service ef73c4
 * data set in which the total number of items in that set is unknown (e.g. 1 of
Packit Service ef73c4
 * 999+), implementors should expose the currently-known set size (999) along
Packit Service ef73c4
 * with this state. In the case of a check box, this state should be used to
Packit Service ef73c4
 * indicate that the check box is a tri-state check box which is currently
Packit Service ef73c4
 * neither checked nor unchecked.
Packit Service ef73c4
 *@ATK_STATE_TRUNCATED: Indicates that an object is truncated, e.g. a text value in a speradsheet cell.
Packit Service ef73c4
 *@ATK_STATE_REQUIRED: Indicates that explicit user interaction with an object is required by the user interface, e.g. a required field in a "web-form" interface.
Packit Service ef73c4
 *@ATK_STATE_INVALID_ENTRY: Indicates that the object has encountered an error condition due to failure of input validation. For instance, a form control may acquire this state in response to invalid or malformed user input.
Packit Service ef73c4
 *@ATK_STATE_SUPPORTS_AUTOCOMPLETION:  Indicates that the object in question implements some form of ¨typeahead¨ or 
Packit Service ef73c4
 * pre-selection behavior whereby entering the first character of one or more sub-elements
Packit Service ef73c4
 * causes those elements to scroll into view or become selected.  Subsequent character input
Packit Service ef73c4
 * may narrow the selection further as long as one or more sub-elements match the string.
Packit Service ef73c4
 * This state is normally only useful and encountered on objects that implement Selection.
Packit Service ef73c4
 * In some cases the typeahead behavior may result in full or partial ¨completion¨ of 
Packit Service ef73c4
 * the data in the input field, in which case these input events may trigger text-changed
Packit Service ef73c4
 * events from the AtkText interface.  This state supplants @ATK_ROLE_AUTOCOMPLETE.
Packit Service ef73c4
 *@ATK_STATE_SELECTABLE_TEXT:Indicates that the object in question supports text selection. It should only be exposed on objects which implement the Text interface, in order to distinguish this state from @ATK_STATE_SELECTABLE, which infers that the object in question is a selectable child of an object which implements Selection. While similar, text selection and subelement selection are distinct operations.
Packit Service ef73c4
 *@ATK_STATE_DEFAULT: Indicates that the object is the "default" active component, i.e. the object which is activated by an end-user press of the "Enter" or "Return" key.  Typically a "close" or "submit" button.
Packit Service ef73c4
 *@ATK_STATE_ANIMATED: Indicates that the object changes its appearance dynamically as an inherent part of its presentation.  This state may come and go if an object is only temporarily animated on the way to a 'final' onscreen presentation.
Packit Service ef73c4
 * @note some applications, notably content viewers, may not be able to detect
Packit Service ef73c4
 * all kinds of animated content.  Therefore the absence of this state should not
Packit Service ef73c4
 * be taken as definitive evidence that the object's visual representation is
Packit Service ef73c4
 * static; this state is advisory.
Packit Service ef73c4
 *@ATK_STATE_VISITED: Indicates that the object (typically a hyperlink) has already been 'activated', and/or its backing data has already been downloaded, rendered, or otherwise "visited".
Packit Service ef73c4
 *@ATK_STATE_CHECKABLE: Indicates this object has the potential to be
Packit Service ef73c4
 *  checked, such as a checkbox or toggle-able table cell. @Since:
Packit Service ef73c4
 *  ATK-2.12
Packit Service ef73c4
 *@ATK_STATE_HAS_POPUP: Indicates that the object has a popup context
Packit Service ef73c4
 * menu or sub-level menu which may or may not be showing. This means
Packit Service ef73c4
 * that activation renders conditional content.  Note that ordinary
Packit Service ef73c4
 * tooltips are not considered popups in this context. @Since: ATK-2.12
Packit Service ef73c4
 *@ATK_STATE_HAS_TOOLTIP: Indicates this object has a tooltip. @Since: ATK-2.16
Packit Service ef73c4
 *@ATK_STATE_READ_ONLY: Indicates that a widget which is ENABLED and SENSITIVE
Packit Service ef73c4
 * has a value which can be read, but not modified, by the user. Note that this
Packit Service ef73c4
 * state should only be applied to widget types whose value is normally directly
Packit Service ef73c4
 * user modifiable, such as check boxes, radio buttons, spin buttons, text input
Packit Service ef73c4
 * fields, and combo boxes, as a means to convey that the expected interaction
Packit Service ef73c4
 * with that widget is not possible. When the expected interaction with a
Packit Service ef73c4
 * widget does not include modification by the user, as is the case with
Packit Service ef73c4
 * labels and containers, ATK_STATE_READ_ONLY should not be applied. See also
Packit Service ef73c4
 * ATK_STATE_EDITABLE. @Since: ATK-2-16
Packit Service ef73c4
 *@ATK_STATE_LAST_DEFINED: Not a valid state, used for finding end of enumeration
Packit Service ef73c4
 *
Packit Service ef73c4
 *The possible types of states of an object
Packit Service ef73c4
 **/
Packit Service ef73c4
typedef enum
Packit Service ef73c4
{
Packit Service ef73c4
  ATK_STATE_INVALID,
Packit Service ef73c4
  ATK_STATE_ACTIVE,
Packit Service ef73c4
  ATK_STATE_ARMED,
Packit Service ef73c4
  ATK_STATE_BUSY,
Packit Service ef73c4
  ATK_STATE_CHECKED,
Packit Service ef73c4
  ATK_STATE_DEFUNCT,
Packit Service ef73c4
  ATK_STATE_EDITABLE,
Packit Service ef73c4
  ATK_STATE_ENABLED,
Packit Service ef73c4
  ATK_STATE_EXPANDABLE,
Packit Service ef73c4
  ATK_STATE_EXPANDED,
Packit Service ef73c4
  ATK_STATE_FOCUSABLE,
Packit Service ef73c4
  ATK_STATE_FOCUSED,
Packit Service ef73c4
  ATK_STATE_HORIZONTAL,
Packit Service ef73c4
  ATK_STATE_ICONIFIED,
Packit Service ef73c4
  ATK_STATE_MODAL,
Packit Service ef73c4
  ATK_STATE_MULTI_LINE,
Packit Service ef73c4
  ATK_STATE_MULTISELECTABLE,
Packit Service ef73c4
  ATK_STATE_OPAQUE,
Packit Service ef73c4
  ATK_STATE_PRESSED,
Packit Service ef73c4
  ATK_STATE_RESIZABLE,
Packit Service ef73c4
  ATK_STATE_SELECTABLE,
Packit Service ef73c4
  ATK_STATE_SELECTED,
Packit Service ef73c4
  ATK_STATE_SENSITIVE,
Packit Service ef73c4
  ATK_STATE_SHOWING,
Packit Service ef73c4
  ATK_STATE_SINGLE_LINE,
Packit Service ef73c4
  ATK_STATE_STALE,
Packit Service ef73c4
  ATK_STATE_TRANSIENT,
Packit Service ef73c4
  ATK_STATE_VERTICAL,
Packit Service ef73c4
  ATK_STATE_VISIBLE,
Packit Service ef73c4
  ATK_STATE_MANAGES_DESCENDANTS,
Packit Service ef73c4
  ATK_STATE_INDETERMINATE,
Packit Service ef73c4
  ATK_STATE_TRUNCATED,
Packit Service ef73c4
  ATK_STATE_REQUIRED,
Packit Service ef73c4
  ATK_STATE_INVALID_ENTRY,
Packit Service ef73c4
  ATK_STATE_SUPPORTS_AUTOCOMPLETION,
Packit Service ef73c4
  ATK_STATE_SELECTABLE_TEXT,
Packit Service ef73c4
  ATK_STATE_DEFAULT,
Packit Service ef73c4
  ATK_STATE_ANIMATED,
Packit Service ef73c4
  ATK_STATE_VISITED,
Packit Service ef73c4
  ATK_STATE_CHECKABLE,
Packit Service ef73c4
  ATK_STATE_HAS_POPUP,
Packit Service ef73c4
  ATK_STATE_HAS_TOOLTIP,
Packit Service ef73c4
  ATK_STATE_READ_ONLY,
Packit Service ef73c4
  ATK_STATE_LAST_DEFINED
Packit Service ef73c4
} AtkStateType;
Packit Service ef73c4
Packit Service ef73c4
typedef guint64      AtkState;
Packit Service ef73c4
Packit Service ef73c4
ATK_AVAILABLE_IN_ALL
Packit Service ef73c4
AtkStateType atk_state_type_register            (const gchar *name);
Packit Service ef73c4
Packit Service ef73c4
ATK_AVAILABLE_IN_ALL
Packit Service ef73c4
const gchar*          atk_state_type_get_name   (AtkStateType type);
Packit Service ef73c4
ATK_AVAILABLE_IN_ALL
Packit Service ef73c4
AtkStateType          atk_state_type_for_name   (const gchar  *name);
Packit Service ef73c4
Packit Service ef73c4
G_END_DECLS
Packit Service ef73c4
Packit Service ef73c4
#endif /* __ATK_STATE_H__ */