From: Mark Doffman Date: Fri, 29 Aug 2008 09:26:27 +0000 (+0100) Subject: 2008-08-29 Mark Doffman X-Git-Tag: AT_SPI2_CORE_0_1_3~135 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=fb77cfa4dc9c4cbd95fba08dae5fdf4318b3e6b3;hp=934b4235535872e0e62a76e7104b5eaef308c9d9;p=platform%2Fupstream%2Fat-spi2-core.git 2008-08-29 Mark Doffman * xml/ Finish cleaning up documentation of the D-Bus protocol XML * xml/org.freedesktop.atspi.Event.xml Add a host of Event interfaces that emit signals corresponding to the AT-SPI events. --- diff --git a/xml/Accessibility.xml b/xml/Accessibility.xml index f15646e..7c8f3f8 100644 --- a/xml/Accessibility.xml +++ b/xml/Accessibility.xml @@ -91,8 +91,7 @@ - - + diff --git a/xml/Makefile.am b/xml/Makefile.am index cd16642..7b571ae 100644 --- a/xml/Makefile.am +++ b/xml/Makefile.am @@ -12,7 +12,7 @@ XML_SPEC= \ org.freedesktop.atspi.Hypertext.xml \ org.freedesktop.atspi.Image.xml \ org.freedesktop.atspi.LoginHelper.xml \ - org.freedesktop.atspi.Registry.Common.xml \ + org.freedesktop.atspi.DeviceEvent.xml \ org.freedesktop.atspi.Registry.xml \ org.freedesktop.atspi.DeviceEventController.xml \ org.freedesktop.atspi.DeviceEventListener.xml \ diff --git a/xml/org.freedesktop.atspi.Registry.Common.xml b/xml/org.freedesktop.atspi.DeviceEvent.xml similarity index 99% rename from xml/org.freedesktop.atspi.Registry.Common.xml rename to xml/org.freedesktop.atspi.DeviceEvent.xml index ceeeb31..2c5e71c 100644 --- a/xml/org.freedesktop.atspi.Registry.Common.xml +++ b/xml/org.freedesktop.atspi.DeviceEvent.xml @@ -1,10 +1,5 @@ - - - - - Deprecated, DO NOT USE! diff --git a/xml/org.freedesktop.atspi.Event.xml b/xml/org.freedesktop.atspi.Event.xml index bf74a93..aaaf981 100644 --- a/xml/org.freedesktop.atspi.Event.xml +++ b/xml/org.freedesktop.atspi.Event.xml @@ -1,362 +1,87 @@ - - - -

A structure that encapsulates the characteristics of the event notifications - that should be sent to an EventListener in response to a call to - DeviceEventController.registerKeystrokeListener or - DeviceEventController.registerDeviceEventListener.

- - - -

If \c True, specifies that - DeviceEventController should block while waiting - for client to process the requested event notifications; - ordinarily should be used only when client needs to perform - operations synchronously with event delivery. Note that because - of the architecture of device event systems in general, - use of this flag may not block delivery of the event to - the currently focussed application unless it is used in - conjunction with the preemptive flag.

- - - - -

If True, specifies that - Listener is allowed to pre-empt the delivery of the event, - effectively 'consuming' it such that it is not delivered - to the currently focussed desktop application. - Key events consumed via this API will not be - available for use by other applications or services, so this - option should be used sparingly.

- - - - -

If True, specifies that - Event notifications should be sent regardless of whether the - currently focussed application participates in the AT-SPI - infrastructure. On systems with the XEvIE X extension, this flag - also allows access to events which are already subject to - interception via a 'system keygrab' (as described in the X Window System - documentation for XGrabKey). The 'global' and 'preemptive' flags - should only be used together for the purposes of registering - 'system global key shortcuts' i.e. command keys for use by the - assistive technology.

- - - - - - A structure which encapsulates information about a device event. - - - - Identifies the type of the containing DeviceEvent. - - - - -

An identifier which identifies this event in the event stream. - On X Window systems this corresponds to the XEvent serial number.

- - - - -

A numeric code which is hardware and system-dependent, identifying the - specific hardware button or key on the device for which the event has - occurred. On X Window systems, for global key notifications and for most - non-global key notifications as well, this code corresponds to the - XKeycode. For switch and button events it indicates the switch - or button number. -

-

- For technical reasons, this code may differ from the XKeycode - when generated by Java applications for consumption by non-global - key listeners. This is subject to change in future versions of the - DeviceEventController implementation. -

- - - - -

An unsigned short int consisting of zero or more of the following - values OR'ed together: -

    -
  1. MODIFIER_SHIFT (=1, corresponds to Xlib's ShiftMask)
    2. -
  2. MODIFIER_SHIFTLOCK (=2, corresponds to Xlib's LockMask)
    3. -
  3. MODIFIER_CONTROL (=4, corresponds to Xlib's ControlMask)
    4. -
  4. MODIFIER_ALT (=8, corresponds to Xlib's Mod1Mask)
    5. -
  5. MODIFIER_META (=16, corresponds to Xlib's Mod2Mask)
    6. -
  6. MODIFIER_META2 (=32, corresponds to Xlib's Mod3Mask)
    7. -
  7. MODIFIER_META3 (=64, corresponds to Xlib's Mod4Mask)
    8. -
-

- - - - -

An unsigned integer representing the time that the - event occurred. On X Window systems this event is - a time in milliseconds from some arbitrary starting - point; it therefore has a cycle time of approximately - 50 days.

- - - - -

A string representation of the event. If is_text is - True, then this string represents the character or typographic - sequence that would be received by a focussed text input field. - event_string is in general suitable for exposure to the - end-user for purposes of keyboard echo.

- - - - -

True if the event results in the insertion of characters - into an input text buffer, or would do so if delivered to a focussed - text input field. 'Typographical' key events have this field set to - True, whereas 'control' key events generally do not.

- - + + + + + + The generic application event structure. The event source is specified by the D-Bus path + and Bus-Name fields in the header of the D-Bus message. + + + + + - - -

A structure which defines the identity of a key for which notifications - are to be requested. The data in the members of a KeyDefinition are used to - determine which keyboard events 'match' the notification request filed by a client.

-

Ordinarily a KeyDefinition specifies one and only one of the criteria below; - the result of using a KeyDefinition with multiple members defined as nonzero is - undefined.

+ + + + + + + + + + + + + + + + + + + + + + + + - - - - If nonzero, the numeric, system-dependent value corresponding to a - physical key on the keyboard. Keycode values have no semantic meaning to the end-user, - and may depend on the user's hardware and operating environment. They therefore are - rarely useful 'as-is' to AT clients, unless the client has used operating system - services to identify the hardward keycode associated with a particular key symbol. - Notifications for key events requested by keycode are less dependent on modifier state - than keysym based notifications, but some hardware (notably many laptops) may generate - more than one keycode for the same physical key, depending on the state of physical - shift/modifier keys. - - - - - If nonzero, the numeric value corresponding to the X Keysym of the key for which - notification is requested. Note that the presence of active modifiers will affect - whether notification for key events requested via 'keysym' specification takes place, - since the keysym depends on the modifier state for most keys. - - - - - If non-NULL, the string value of the inserted characters if the corresponding - key event has KeyEvent:.is_text set to True, or the string representing the - 'name' of the key. On X11 systems, the string 'name' of non-printing keysyms corresponds - to the values in 'keysymdef.h' as provided by Xlib, with the leading 'XK_'; stripped off. - - - - - -

This interface should be implemented by AT-SPI clients who wish to - make use of the DeviceEventController to receive device event notifications. - DeviceEvents include keyboard events and mouse button/motion events.

- - - - Notify an interested DeviceEventListener that a DeviceEvent has occurred. - - - - - True if the recipient/consumer wishes to consume the event, i.e.prevent it from being delivered to the desktop, False if the event should continue to be delivered as normal. - - - + + + + + + + + + + + + + + + + + + + - - -

The interface via which clients request notification of device events, and - through which device events may be simulated.

- - - -

Register to intercept keyboard events, and either pass them on or - consume them.

- - - - A DeviceEventListener which will intercept key events. - - - - - A KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS. - - - - - A ControllerEventMask filtering the intercepted key events. - - - - - A KeyEventTypeSeq that may created by ORing event types together. - - - - - An EventListenerMode indicating whether the listener should receive the events synchronously, potentially consuming them,or just be notified asynchronously of those events that havebeen generated. - - Some platforms have limited support for global, preemptive EventListenerMode.Such a registration may fail if another client already has priority for preemptiveaccess to one or more of the members of the KeySet. AT consumers have the optionof re-trying the request without the global flag, or without the preemptive flag,or of re-trying with a different KeySet. The best support for pre-emptiveglobal keyboard listeners is provided on platforms whose Xserver implementationprovides the XEvIE extension. - - - - - True if the DeviceEventListener was successfully registeredfor the requested KeySet, ControllerEventMask, event types, and EventListenerMode; otherwise returns False. - - - - - - De-register a previously registered keyboard eventlistener. - - - - A DeviceEventListener which will intercept key events. - - - - - A KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS. - - - - - A ControllerEventMask filtering the intercepted key events. - - - - - An EventType mask that may created by ORing event types together. - - - - - -

Register to intercept events, and either pass them on or - consume them. To listen to keyboard events use registerKeystrokeListener - instead.

- - - - A DeviceEventListener which will intercept events. - - - - - An EventTypeSeq indicating which event types to listen for. - - - - - True if successful, False if not - - - - - - De-register a previously registered keyboard eventlistener. - - - - a DeviceEventListener which will intercept events. - - - - - An EventTypeSeq indicating which event types to stoplistening for. - - - - - -

Notify the Registry instance that a device event has taken place, and - allow pre-emptive listeners the opportunity to 'consume' the event - and thus prevent its further issuance/forwarding. This is the - method used by accessibility bridges to forward 'toolkit dependent' - device events to the Registry from the application's process space.

-

AT clients do not normally need to use this method, it is intended for use - by toolkit bridges and special-purpose applications.

- - - - - True if the event was consumed by a (pre-emptive) listener, False if not (in which case the device event will be forwardedas normal to any application which would normally receive it, e.g.the currently active application in the case of mouse or keyboard events). - - - - - -

Notify the Registry instance that a device event has taken place in - an asynchronous manner. This is the - method used by accessibility bridges to forward 'toolkit dependent' - device events to the Registry from the application's process space. - If the event in question is potentially pre-emptible. - notifyListenersSync should be used instead.

+ + + + + -

AT clients do not normally need to use this method, it is intended for use - by toolkit bridges and special-purpose applications.

- - - - - - Synthesize a keyboard event. - - - - A long integer indicating the keycode ofthe keypress to be synthesized. - - - - - An optional UTF-8 string indicating a complexkeyboard input event. - - - - -

A KeySynthType indicating the type of event(s) to be synthesized: a key press, release, press-release pair,or a complex input string (for instance from aninternationalized or complex text input method, ora composed character).

+ + + + + + + + + + + + + + + -

Keycode may be truncated before beingprocessed, as keycode length may be platform-dependentand keycode ranges are generally much smaller thanCORBA_long. One or the other of keycode or keystring are generally NULL, (but not both), depending on the value of type.

- - - - - - Synthesize a mouse event. - - - - A long integer indicating the screen x coord for the mouse event. - - - - - A long integer indicating the screen y coord for the mouse event. - - - - - A string indicating the type of mouse event, e.g. 'button1up'. - - - + + + diff --git a/xml/org.freedesktop.atspi.LoginHelper.xml b/xml/org.freedesktop.atspi.LoginHelper.xml index 80932f6..08f3c4f 100644 --- a/xml/org.freedesktop.atspi.LoginHelper.xml +++ b/xml/org.freedesktop.atspi.LoginHelper.xml @@ -2,7 +2,7 @@ -

@brief An interface for use by assistive technologies by which +

An interface for use by assistive technologies by which they can access system information and services on a 'need to know' basis while the screen is locked, during user authentication, or during other sensitive operations.

@@ -15,23 +15,23 @@ service.

Such 'applications' (for instance, screen lock dialogs and - security-enabled web browsers) use the ::LoginHelper client + security-enabled web browsers) use the LoginHelper client interfaces, and the bonobo-activation query service, to - query for assistive technologies which advertise the ::LoginHelper + query for assistive technologies which advertise the LoginHelper service. The client then queries these assistive technologies - for their device I/O requirements, via the ::getDeviceReqs call. - The client may then issue the advisory request ::setSafe (TRUE), - which requests that the ::LoginHelper -implementing service make a + for their device I/O requirements, via the getDeviceReqs call. + The client may then issue the advisory request setSafe (TRUE), + which requests that the LoginHelper -implementing service make a best-effort attempt to make itself more secure (for instance, an onscreen keyboard might turn off word prediction, and a screenreader may turn off keyboard echo via speech). The return - value of ::setSafe is an advisory indication of whether this attempt + value of setSafe is an advisory indication of whether this attempt was successful (no specific guarantees are implied). Once the 'security sensitive' state is exited, the client should - call ::setSafe (FALSE).

+ call setSafe (FALSE).

-

The return values from ::getDeviceReqs inform the client of which - services the ::LoginHelper service (e. g. assistive technology) needs +

The return values from getDeviceReqs inform the client of which + services the LoginHelper service (e. g. assistive technology) needs in order to do its job. The client may use this information to loosen any restrictions on access which it may currently have in place (for instance, keyboard grabs, etc.). If it does not do so, @@ -41,70 +41,64 @@

A structure containing info about toplevel X windows that - the ::LoginHelper instance wishes to have raised.

+ the LoginHelper instance wishes to have raised.

- -

string display; - short screen;

- -

DeviceReq:

-

The system and device access and services which the LoginHelper-implementing assistive technology requires in order to enable the user to use the system.

- !<: Needs access to the GUI event subsystem (e.g. Xserver) + Needs access to the GUI event subsystem (e.g. Xserver) - !<: Needs access to the system keyboard events (read and write) + Needs access to the system keyboard events (read and write) - !<: Needs access to the onscreen pointer (e.g. mouse pointer) + Needs access to the onscreen pointer (e.g. mouse pointer) - !<: Reads XInput extended input devices + Reads XInput extended input devices - !<: Posts Windows, and needs for toplevel windows to be visible + Posts Windows, and needs for toplevel windows to be visible - !<: Writes to audio device + Writes to audio device - !<: Reads from audio device + Reads from audio device - !<: Requires access to general network services, including remote access + Requires access to general network services, including remote access - !<: Requires network services hosted on LOCALHOST only + Requires network services hosted on LOCALHOST only - !<: Writes to a serial port + Writes to a serial port @@ -119,40 +113,47 @@ - \c TRUE if the client is requesting that 'safe mode' be initiated, \c FALSE if the client is advising that 'safe mode' may beexited, i.e. normal operation may be resumed.Request a LoginHelper to enter "safe" mode, orinform LoginHelper that "safe" mode may be exited.If \a safe_mode is \c TRUE, but the return value is \c FALSE,the requesting client may wish to deny services to the ::LoginHelper, for instance avoid raising its toplevels.The return value is purely advisory, and no guarantees are intended about what the implementing LoginHelper will do to improve security when in "safe" mode. + True if the client is requesting that 'safe mode' be initiated. + False if the client is advising that 'safe mode' may be + exited. i.e. Normal operation may be resumed. + + Request a LoginHelper to enter "safe" mode, orinform LoginHelper that "safe" mode may be exited. + If safe_mode is True, but the return value is False ,the requesting + client may wish to deny services to the LoginHelper, for instance avoid raising its toplevels. + The return value is purely advisory, and no guarantees are intended about what the implementing + LoginHelper will do to improve security when in "safe" mode. - whether the ::LoginHelper is now "safe" or not. + whether the LoginHelper is now "safe" or not. -

getDeviceReqs:

- -

Query a ::LoginHelper for the types of +

Query a LoginHelper for the types of device I/O it requires, in order to do its job. - For instance, a ::LoginHelper which needs to receive keyboard + For instance, a LoginHelper which needs to receive keyboard events will include Accessibility_LoginHelper_CORE_KEYBOARD in this list.

- A sequence of ::LoginHelper_DeviceReq indicatingthe device I/O required in order to facilitate end-user access to the system. + A sequence of LoginHelper_DeviceReq indicatingthe device I/O required in order to facilitate end-user + access to the system. -

getRaiseWindows:

- -

Get a list of window IDs that need raising on login.

+

Get a list of window IDs that need raising on login.

 - a sequence containing window IDS for toplevels whichneed to be raised/made visible during user authentication, inorder for the ::LoginHelper to facilitate end-user access to the system. + A sequence containing window IDS for toplevels whichneed to be raised/made + visible during user authentication, inorder for the LoginHelper to facilitate + end-user access to the system. diff --git a/xml/org.freedesktop.atspi.Registry.xml b/xml/org.freedesktop.atspi.Registry.xml index d8baa97..52cc31c 100644 --- a/xml/org.freedesktop.atspi.Registry.xml +++ b/xml/org.freedesktop.atspi.Registry.xml @@ -1,10 +1,5 @@ - - - - -

The Registry is a service through which applications providing @@ -14,33 +9,29 @@ interact with those applications.

The Registry service provides four basic functions to Assistive Technology (AT) clients: - \li it provides a list of the applications who have registered with the AT-SPI - framework, thereby announcing their participation in the AT-SPI framework; - \li it allows AT clients to register for notification of changes in application - state (at-spi Events); - \li it dispatches/relays said events from participating applications to - the registered listeners; - \li it gives access to system device events via the associated DeviceEventController - interface.

+
    +
  1. It provides a list of the applications who have registered with the + AT-SPI framework, thereby announcing their participation in the AT-SPI framework.
    2. +
  2. It gives access to system device events via the associated DeviceEventController interface.
    3. +
+

From the point of view of accessible applications (i.e. AT-SPI service producers), the Registry is primarily a registration and event delivery service. Applications normally only call the registerApplication and deregisterApplication Registry methods, and its inherited EventListener::notifyEvent method.

-

@note Although all application events are dispatched via the Registry, other AT client +

Although all application events are dispatched via the Registry, other AT client calls are serviced directly by the applications, rather than being relayed via the Registry. The AT client obtains references to these application objects via the enumeration of Desktop instances whose children are Application instances - (Registry::getDesktopList) and via examination of the 'source' member of the Event + (Registry.getDesktopList) and via examination of the 'source' member of the Event structure.

The Registry normally lives in its own process space; communication via Registry and both application services and AT clients takes place via IPC. A process space diagram - illustrating the relationship between applications, Registry, and AT is shown below. - @image html "http://developer.gnome.org/projects/gap/tech-docs/SPIBlockDiagram.png"

- -

@see Desktop, Application, Event, EventListener

+ illustrating the relationship between applications, Registry, and AT is shown at: + http://developer.gnome.org/projects/gap/tech-docs/SPIBlockDiagram.png

@@ -54,7 +45,7 @@ - a reference to the Application to be deregistered. + A reference to the Application to be deregistered. @@ -65,43 +56,37 @@ - a reference to the requesting ::EventListener. + A reference to the requesting EventListener. - a string which indicates the type of events about which the client desires notification. + A string which indicates the type of events about which the client desires notification. - - deregisterGlobalEventListenerAll: - - the requesting EventListenerRequest that a previously registered client stop receivingglobal notifications for all events for which it was registered. + The requesting EventListenerRequest that a previously registered client stop receiving global notifications for all events for which it was registered. - - deregisterGlobalEventListener: - - the requesting EventListener + The requesting EventListener - a string indicating the type of eventsRequest that a previously registered client stop receivingglobal notifications for events of a certain type. + A string indicating the type of eventsRequest that a previously registered client stop receiving global notifications for events of a certain type. -

event types: "Window" "Desktop" +

Event types: "Window" "Desktop" "Window:Create" "Window:Destroy" "Window:Iconify" "Window:Restore" "Window:Fullscreen" "Window:Resize" @@ -110,32 +95,27 @@ "Desktop:Reorder" "Focus" "GtkWidget:show" - "GObject:notify:<propertyname>"

+ "GObject:notify:propertyname"

( not sure we should allow these last 2 forms, since they are toolkit-specific, but they're powerful )

-

getDesktopCount:

-

Get the current number of desktops.

 - a short integer indicating the current number of Desktops. + A short integer indicating the current number of Desktops. -

getDesktop: - @n: the index of the requested Desktop.

-

Get the nth accessible desktop.

- a reference to the requested Desktop. + A reference to the requested Desktop. @@ -145,7 +125,7 @@ - a sequence containing references tothe Desktops. + A sequence containing references tothe Desktops. @@ -155,7 +135,7 @@ - an object implementing DeviceEventController + An object implementing DeviceEventController diff --git a/xml/org.freedesktop.atspi.Relation.xml b/xml/org.freedesktop.atspi.Relation.xml index eafb5d0..792899c 100644 --- a/xml/org.freedesktop.atspi.Relation.xml +++ b/xml/org.freedesktop.atspi.Relation.xml @@ -1,10 +1,5 @@ - - - - -

RelationType specifies a relationship between objects (possibly one-to-many or many-to-one) @@ -14,7 +9,7 @@ that should accompany the accessibleName property when presenting an object's content or identity to the end user. Similarly, RELATION_CONTROLLER_FOR can be used to further specify the context in which a valuator is useful, and/or the other UI components which are directly effected by - user interactions with the valuator. Common examples include association of scrollbars with + user interactions with the valuator. Common examples include association of scrollbars with the viewport or panel which they control.

 @@ -46,7 +41,7 @@ - Object has a grouping relationship (e.g. ¨same group as¨) to one or more other objects. + Object has a grouping relationship (e.g. 'same group as') to one or more other objects. @@ -69,7 +64,7 @@

Object renders content which flows logically to another object. For instance, text in a paragraph may flow to another object which is not the - ¨next sibling¨ in the accessibility hierarchy.

+ 'next sibling' in the accessibility hierarchy.

@@ -100,7 +95,7 @@

Denotes that the object is a transient window or frame associated with another onscreen object. Similar to TOOLTIP_FOR, but more general. Useful for windows which are technically toplevels but which, for one or more reasons, do not explicitly cause their associated - window to lose ¨window focus¨. Creation of a ROLE_WINDOW object with the POPUP_FOR relation + window to lose 'window focus'. Creation of a ROLE_WINDOW object with the POPUP_FOR relation usually requires some presentation action on the part of assistive technology clients, even though the previous toplevel ROLE_FRAME object may still be the active window.

diff --git a/xml/org.freedesktop.atspi.Role.xml b/xml/org.freedesktop.atspi.Role.xml index 7467919..ea455fb 100644 --- a/xml/org.freedesktop.atspi.Role.xml +++ b/xml/org.freedesktop.atspi.Role.xml @@ -1,10 +1,5 @@ - - - - - @@ -119,7 +114,7 @@ - XXX Don't use, reserved for future use. + Don't use, reserved for future use. @@ -327,7 +322,7 @@

An object which labels a particular row in a Table. Table rows and columns may also be labelled via the RELATION_LABEL_FOR/RELATION_LABELLED_BY relationships; - \see Accessibility::RelationSet.

+ see Accessibility.RelationSet.

@@ -406,7 +401,7 @@ - An object which is contains a single paragraph of text content. \see also ROLE_TEXT. + An object which is contains a single paragraph of text content. See also ROLE_TEXT. @@ -448,11 +443,9 @@

The object is a component whose textual content may be entered or modified by the user, - provided STATE_EDITABLE is present. - @note a readonly ROLE_ENTRY object (i.e. where STATE_EDITABLE is not present) implies a - read-only ¨text field¨ in a form, as opposed to a title, label, or caption.

- -

@since AT-SPI 1.7.0

+ provided STATE_EDITABLE is present.

+

A readonly ROLE_ENTRY object (i.e. where STATE_EDITABLE is not present) implies a + read-only 'text field' in a form, as opposed to a title, label, or caption.

@@ -462,17 +455,13 @@ quantitative data and information about how the data is being presented. The LABELLED_BY relation is particularly important in interpreting objects of this type, as is the accessible-description property. - @see ROLE_CAPTION

- -

@since AT-SPI 1.7.0

+ See ROLE_CAPTION

The object contains descriptive information, usually textual, about another user interface element such as a table, chart, or image.

- -

@since AT-SPI 1.7.0

 @@ -482,8 +471,6 @@ document may be said to be embedded in the containing instance. HTML frames are often ROLE_DOCUMENT_FRAME. Either this object, or a singleton descendant, should implement the Document interface.

- -

@since AT-SPI 1.7.0

 @@ -491,8 +478,6 @@

The object serves as a heading for content which follows it in a document. The 'heading level' of the heading, if availabe, may be obtained by querying the object's attributes.

- -

@since AT-SPI 1.7.0

 @@ -500,8 +485,6 @@

The object is a containing instance which encapsulates a page of information. ROLE_PAGE is used in documents and content which support a paginated navigation model.

- -

@since AT-SPI 1.7.0

 @@ -510,8 +493,6 @@ a particular 'logical' section of the document. The type of content within a section, and the nature of the section division itself, may be obtained by querying the object's attributes. Sections may be nested.

- -

@since AT-SPI 1.7.0

 @@ -519,8 +500,6 @@

The object is redundant with another object in the hierarchy, and is exposed for purely technical reasons. Objects of this role should be ignored by clients, if they are encountered at all.

- -

@since AT-SPI 1.7.6

 @@ -536,8 +515,6 @@ application instances, ROLE_FORM containers' components are associated with the current document, rather than the current foreground application or viewer instance.

- -

@since AT-SPI 1.7.6

 @@ -547,8 +524,6 @@ content which may also use the Hypertext/Hyperlink interfaces to indicate the range/location within a text object where an inline or embedded object lies.

- -

@since AT-SPI 1.7.6

 @@ -556,13 +531,11 @@

The object is a window or similar viewport which is used to allow composition or input of a 'complex character', in other words it is an "input method window."

- -

@since AT-SPI 1.7.6

 - not a valid role, used for finding end of enumeration. + Not a valid role, used for finding end of enumeration. diff --git a/xml/org.freedesktop.atspi.Selection.xml b/xml/org.freedesktop.atspi.Selection.xml index 3d7fa3f..3429103 100644 --- a/xml/org.freedesktop.atspi.Selection.xml +++ b/xml/org.freedesktop.atspi.Selection.xml @@ -1,26 +1,21 @@ - - - - -

An interface which indicates that an object exposes a 'selection' model, allowing the selection of one or more of its children. Read-only Selection instances are possible, in which case the interface is used to programmatically - determine the selected-ness of its children. A selected child has ::State::STATE_SELECTED, + determine the selected-ness of its children. A selected child has State.STATE_SELECTED, and a child which may hypothetically be selected (though possibly not programmatically - selectable) has ::State::STATE_SELECTABLE. - @note Events emitted by implementors of Selection include: - \li \c "object:selection-changed" An instance of Selection has undergone a change in the + selectable) has State.STATE_SELECTABLE.

+

Events emitted by implementors of Selection include: + object:selection-changed An instance of Selection has undergone a change in the 'selected-ness' of its children, i.e. had a selection added, removed, and/or modified. Usually accompanied by - corresponding \c "object:state-changed:selected" events + corresponding object:state-changed:selected events from the corresponding children, unless the children are previously un-queried via AT-SPI and the Selection instance - has ::State::STATE_MANAGES_DESCENDANTS.

+ has State.STATE_MANAGES_DESCENDANTS.

 @@ -30,81 +25,81 @@ -

Get the i-th selected Accessible child of a Selection. - @note \c selectedChildIndex refers to the index in the list of +

Get the i-th selected Accessible child of a Selection.

+

selectedChildIndex refers to the index in the list of 'selected' children as opposed to the more general 'child index' of an object; as such it generally differs from that used in - Accessible::getChildAtIndex() or returned by - Accessible::getIndexInParent(). - \c selectedChildIndex must lie between 0 - and Selection::nSelectedChildren-1, inclusive.

+ Accessible.getChildAtIndex() or returned by + Accessible.getIndexInParent(). + selectedChildIndex must lie between 0 + and Selection.nSelectedChildren-1, inclusive.

 - a long integer indicating which of the selected children of an object is being requested. + A long integer indicating which of the selected children of an object is being requested. - a pointer to a selected Accessible child object,specified by \c selectedChildIndex. + A pointer to a selected Accessible child object,specified by selectedChildIndex. -

Add a child to the selected children list of a Selection. - @note For Selection implementors that only allow +

Add a child to the selected children list of a Selection.

+

For Selection implementors that only allow single selections, this call may result in the replacement of the (single) current - selection. The call may return \c False if - the child is not selectable (i.e. does not have ::State::STATE_SELECTABLE), + selection. The call may return False if + the child is not selectable (i.e. does not have State.STATE_SELECTABLE), if the user does not have permission to change the selection, - or if the Selection instance does not have ::State::STATE_SENSITIVE.

+ or if the Selection instance does not have State.STATE_SENSITIVE.

- a long integer indicating which child of theSelection is to be selected. + A long integer indicating which child of theSelection is to be selected. - \c True if the child was successfully selected, \c False otherwise. + True if the child was successfully selected, False otherwise. -

Remove a child to the selected children list of a Selection. - @note \c childIndex is the index in the selected-children list, - not the index in the parent container. \c selectedChildIndex in this - method, and \c childIndex in Selection::selectChild - are asymmettric.

+

Remove a child to the selected children list of a Selection.

+

childIndex is the index in the selected-children list, + not the index in the parent container. selectedChildIndex in this + method, and childIndex in Selection.selectChild + are asymmettric.

 - a long integer indicating which of the selected children of the Selection is to be deselected. The indexis a zero-offset index into the 'selected child list', nota zero-offset index into the list of all children of the Selection. + A long integer indicating which of the selected children of the Selection is to be deselected. The indexis a zero-offset index into the 'selected child list', nota zero-offset index into the list of all children of the Selection. - \c True if the child was successfully deselected, \c False otherwise.@see deselectChild + True if the child was successfully deselected, False otherwise, see deselectChild

Determine whether a particular child of an Selection implementor - is currently selected. Note that \c childIndex is the zero-offset + is currently selected. Note that childIndex is the zero-offset index into the standard Accessible container's list of children.

- an index into the Selection's list of children. + An index into the Selection's list of children. - \c True if the specified child is currently selected,\c False otherwise. + True if the specified child is currently selected,False otherwise. @@ -112,11 +107,11 @@

Attempt to select all of the children of a Selection implementor. Not all Selection implementors support this operation (for instance, - implementations which support only "single selection" do not support this operation).

+ implementations which support only "single selection" do not support this operation).

 - \c True if successful, \c False otherwise. + True if successful, False otherwise. @@ -125,13 +120,13 @@

Attempt to clear all selections (i.e. deselect all children) of a Selection. Not all Selection implementations allow the removal of all selections.

-

@note this operation may fail if the object must have at least one selected child, +

This operation may fail if the object must have at least one selected child, if the user does not have permission to change the selection, or if the Selection - does not have ::State::STATE_SENSITIVE.

+ does not have State.STATE_SENSITIVE.

- \c True if the selections were successfully cleared, \c False otherwise. + True if the selections were successfully cleared, False otherwise. @@ -140,7 +135,7 @@

Remove a child from the selected children list of a Selection, if the child is currently selected.

-

@note unlike deselectSelectedChild, \c childIndex is the zero-offset +

Unlike deselectSelectedChild, childIndex is the zero-offset index into the Accessible instance's list of children, not the index into the 'selected child list'.

@@ -151,20 +146,9 @@ - \c True if the child was successfully selected, \c False otherwise.@see deselectSelectedChild@since AT-SPI 1.8.0 + True if the child was successfully selected, False otherwise, see deselectSelectedChild. - - -

unImplemented:

- -

placeholders for future expansion.

- - - - - - diff --git a/xml/org.freedesktop.atspi.Selector.xml b/xml/org.freedesktop.atspi.Selector.xml index 647ac59..a06a18e 100644 --- a/xml/org.freedesktop.atspi.Selector.xml +++ b/xml/org.freedesktop.atspi.Selector.xml @@ -1,10 +1,5 @@ - - - - - A structure which encapsulates both a string representation of a command and a unique command ID @@ -15,12 +10,14 @@

Notify the CommandListener instance of changes to the currently - available commands, by sending the current ::CommandList.

- -

@param commands The newly-available list of ::Command objects which - may be invoked by the listener.

+ available commands, by sending the current CommandList.

- + + +

The newly-available list of Command objects which + may be invoked by the listener.

+ + @@ -31,34 +28,33 @@

Examples of the use of this interface include voice-command and remote-control applications, in which the user interaction is wholly or partly delegated by the - implementor to an external agent. - @since AT-SPI 1.7.0

+ implementor to an external agent.

 -

A code returned by a call to ::activateCommand, indicating +

A code returned by a call to activateCommand, indicating the result of the activation request.

 -

< The command was invalid or ill-formed; usually indicates +

The command was invalid or ill-formed; usually indicates an error condition.

- < The command was successfully activated. + The command was successfully activated. -

< The command was valid, but could not be activated. +

The command was valid, but could not be activated. This may be due to problems with permissions or error conditions.

 -

< The command is no longer valid in the current program context. +

The command is no longer valid in the current program context. This may mean that the application has changed state in such a way that the specified command it no longer applicable, or because changes to the application state have rendered it @@ -68,23 +64,23 @@ -

< Defines size of enumeration; +

Defines size of enumeration; do not use this value as a parameter.

 - This attribute is TRUE if this Selector allows its ::CommandList to be specified by the client + This attribute is True if this Selector allows its CommandList to be specified by the client -

Query the ::Selector for the current ::CommandList.

+

Query the Selector for the current CommandList.

 - the currently available ::CommandList + The currently available CommandList @@ -92,68 +88,64 @@ - TRUE if the replacement request was successful, FALSE if the request could not be honored. + True if the replacement request was successful, True if the + request could not be honored. -

Ask the ::Selector to re-calculate its ::CommandList. - @note in most cases the ::Selector will continuously - update its ::CommandList without recourse to this call. - This call is equivalent to ::getCommands, except that - after ::refreshCommands the new ::CommandList will be returned - via any registered ::CommandListener instances rather than - synchronously via this call.

+

Ask the Selector to re-calculate its CommandList.

+

In most cases the Selector will continuously + update its CommandList without recourse to this call. + This call is equivalent to getCommands, except that + after refreshCommands the new CommandList will be returned + via any registered CommandListener instances rather than + synchronously via this call.

 - TRUE if the ::CommandList changed. + True if the CommandList changed. -

Request that the ::Selector invoke the specified ::Command. - @param cmd the ::Command to activate/invoke.

+

Request that the Selector invoke the specified Command.

 - + + +

The Command to activate/invoke.

+ + - a ::CommandResult indicating whether the request was honored, and the reason for failure if the::Command could not be activated or invoked. + A CommandResult indicating whether the request was honored, and the reason for failure if the Command could not be activated or invoked.

Register a :CommandListener instance for notification of - changes to the command set. - @param listener the ::CommandListener to be notified of changes.

+ changes to the command set.

 - + + +

The CommandListener to be notified of changes.

+ + -

Tell the ::Selector instance to cease notifying the - specified ::CommandListener of changes to the command list. - @param listener the ::CommandListener to remove from the - notification list.

- - - - - -

\cond - unImplemented:

- -

placeholders for future expansion.

+

Tell the Selector instance to cease notifying the + specified CommandListener of changes to the command list.

 - - - - - - + + +

The CommandListener to remove from the + notification list.

+ + diff --git a/xml/org.freedesktop.atspi.State.xml b/xml/org.freedesktop.atspi.State.xml index 2c1753d..3581a4d 100644 --- a/xml/org.freedesktop.atspi.State.xml +++ b/xml/org.freedesktop.atspi.State.xml @@ -1,10 +1,5 @@ - - - - - @@ -180,8 +175,8 @@ -

Indicates this object is visible, e.g. has been explicitly marked for exposure to the user. - @note: STATE_VISIBLE is no guarantee that the object is actually unobscured on the screen, only +

Indicates this object is visible, e.g. has been explicitly marked for exposure to the user.

+

STATE_VISIBLE is no guarantee that the object is actually unobscured on the screen, only that it is 'potentially' visible, barring obstruction, being scrolled or clipped out of the field of view, or having an ancestor container that has not yet made visible. A widget is potentially onscreen if it has both STATE_VISIBLE and STATE_SHOWING. @@ -222,21 +217,18 @@ -

Indicates that an object's onscreen content is truncated, e.g. a text value in a spreadsheet cell. - @since AT-SPI 1.7.0.

+

Indicates that an object's onscreen content is truncated, e.g. a text value in a spreadsheet cell.

Indicates this object's visual representation is dynamic, not static. This state may be applied to an object during an animated 'effect' and - be removed from the object once its visual representation becomes static. - @note some applications, notably content viewers, may not be able to detect + be removed from the object once its visual representation becomes static.

+

some applications, notably content viewers, may not be able to detect all kinds of animated content. Therefore the absence of this state should not be taken as definitive evidence that the object's visual representation is - static; this state is advisory.

- -

@since AT-SPI 1.7.0

+ static; this state is advisory.

 @@ -244,8 +236,6 @@

This object has indicated 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.

- -

@since AT-SPI 1.7.0

@@ -258,8 +248,6 @@ In some cases the typeahead behavior may result in full or partial ¨completion¨ of the data in the input field, in which case these input events may trigger text-changed events from the source.

- -

@since AT-SPI 1.7.0

@@ -270,8 +258,6 @@ the object in question is a selectable child of an object which implements Selection. While similar, text selection and subelement selection are distinct operations.

- -

@since AT-SPI 1.7.0

@@ -279,8 +265,6 @@

This state indicates that the object in question is the 'default' interaction object in a dialog, i.e. the one that gets activated if the user presses "Enter" when the dialog is initially posted.

- -

@since AT-SPI 1.7.0

@@ -288,8 +272,6 @@

This state indicates that the object (typically a hyperlink) has already been activated or invoked, with the result that some backing data has been downloaded or rendered.

- -

@since AT-SPI 1.7.1

@@ -307,13 +289,16 @@ -

Query a StateSet for a specific StateType. - @param state the StateType being queried for.

+

Query a StateSet for a specific StateType.

 - + + +

The StateType being queried for.

+ + - \c TRUE if the StateSet contains StateType \a state. + True if the StateSet contains StateType state. @@ -331,13 +316,16 @@ -

Compare two statesets for equivalence. - @param tarStateSet the StateSet to be compared with this one.

+

Compare two statesets for equivalence.

 - + + +

The StateSet to be compared with this one.

+ + - \c TRUE if the two StateSet objects are composed of the same StateTypes. + True if the two StateSet objects are composed of the same StateTypes. @@ -348,36 +336,19 @@ - a 'difference set', i.e. a StateSet consisting of those states not shared by the two sets being compared. + A 'difference set', i.e. a StateSet consisting of those states not shared by the two sets being compared. - \c TRUE if the StateSet contains no states. + True if the StateSet contains no states. - -

\cond - Private

- - - -

unImplemented:

- -

placeholders for future expansion.

- - - - - - - - diff --git a/xml/org.freedesktop.atspi.StreamableContent.xml b/xml/org.freedesktop.atspi.StreamableContent.xml index 5402ca4..6fed868 100644 --- a/xml/org.freedesktop.atspi.StreamableContent.xml +++ b/xml/org.freedesktop.atspi.StreamableContent.xml @@ -1,18 +1,9 @@ - - - - -

An interface by which the requested data from a StreamableContent object - may be read by the client. - @note this interface supercedes the use of BonoboStream by previous - versions of StreamableContent.

- -

@since AT-SPI 1.7.0

+ may be read by the client.

 @@ -24,17 +15,17 @@ - < Seek from the start of the stream or data source. + Seek from the start of the stream or data source. - < Seek relative to the current position. + Seek relative to the current position. - < Seek from the end of the file, stream, or data source. + Seek from the end of the file, stream, or data source. @@ -57,18 +48,24 @@ -

Seek to a specified position in the Stream. - @param offset an offset specifying the requested position in the stream, - relative to the SeekType specified in \c whence. - @param whence a SeekType specifying the reference point from which the - seek offset is calculated. Some forms of seek are not supported by certain - implementations of Stream, in which case a NotSupported exception will be raised.

+

Seek to a specified position in the Stream.

 - - + + + An offset specifying the requested position in the stream, + relative to the SeekType specified in whence. + + + + + A SeekType specifying the reference point from which the + seek offset is calculated. Some forms of seek are not supported by certain + implementations of Stream, in which case a NotSupported exception will be raised. + + - the actual resulting offset, if no exception was raised. + The actual resulting offset, if no exception was raised. @@ -85,7 +82,7 @@ - the number of bytes actually read into the client buffer. + The number of bytes actually read into the client buffer. @@ -97,16 +94,9 @@

close the stream and release associated resources. A client should not perform further operations on a - StreamableContent::Stream object after closing it.

- - - - - /cond + StreamableContent.Stream object after closing it.

 - -

An interface whereby an object allows its backing content @@ -115,53 +105,31 @@ transform, convert, or parse the content in order to present it in an alternate form to end-users.

-

@note The StreamableContent interface is particularly useful for saving, +

The StreamableContent interface is particularly useful for saving, printing, or post-processing entire documents, or for persisting alternate views of a document. If document content itself is being serialized, stored, or converted, then use of the StreamableContent interface can help address performance - issues. Unlike most AT-SPI/Accessibility interfaces, this interface + issues. Unlike most AT-SPI/Accessibility interfaces, this interface is not strongly tied to the current user-agent view of the a particular document, but may in some cases give access to the underlying model data.

 - - getContentTypes: - - the list of available mimetypes for this object's content. + The list of available mimetypes for this object's content. -

\n DEPRECATED, use getStream instead. +

DEPRECATED, use getStream instead. getContent: Retrieve this object's content, in a format appropriate to a requested mimetype.

- -

@note the data is returned as an object of type ::Bonobo::Stream. - The primary methods which are supported on Bonobo::Streams for the - purposes of the ::StreamableContent API are \c seek and \c read. - \c seek may not be supported for all mimetypes or - all implementors.

- -

\verbatim - long Bonobo::Stream:seek (in long offset, in SeekType whence) - raises (NoPermission, IOError) - void Bonobo::Stream:read (in long count, out iobuf buffer) - raises (NoPermission, IOError) - \endverbatim

- -

@see ::Bonobo::Stream

- - - - - a ::Bonobo::Stream whose mimetype matches \a contentType,if available, or \c NIL. + @@ -169,17 +137,15 @@

Retrieve this object's content, in a format appropriate to a requested mimetype, as a ::ContentStream instance.

-

@note This method supercedes the older getContent method, which - relied on the Bonobo::Stream API. - \c seek may not be supported for all mimetypes or - all implementors.

- -

@param contentType a string specifying the desired mimetype for the content stream.

- + + +

A string specifying the desired mimetype for the content stream.

+ + - a Stream whose mimetype matches \a contentType,if available, or \c NIL.@since AT-SPI 1.8.0 + A Stream whose mimetype matches contentType,if available, or NIL. @@ -187,26 +153,18 @@

Get a URI pointing to the content of the specified type, if such a URI can be obtained. Not all streamable content providers have URI representations.

- -

@param contentType a string specifying the desired mimetype for the content stream. - If NULL, then a URI for the default content type will be returned, if available.

- + + +

A string specifying the desired mimetype for the content stream. + If NULL, then a URI for the default content type will be returned, if available.

+ + - a string which constitutes a URI for a stream of the specifiedcontent type, or NULL if no such URI can be obtained. + A string which constitutes a URI for a stream of the specifiedcontent type, or NULL if no such URI can be obtained. - - -

\cond - unImplemented:

- -

placeholders for future expansion.

- - - - diff --git a/xml/org.freedesktop.atspi.Table.xml b/xml/org.freedesktop.atspi.Table.xml index fa9affa..59596d4 100644 --- a/xml/org.freedesktop.atspi.Table.xml +++ b/xml/org.freedesktop.atspi.Table.xml @@ -1,14 +1,9 @@ - - - - -

An interface used by containers whose contained data is arranged in - a "tabular" (i.e.\ row-column) fashion. Tables may resemble a two-dimensional + a "tabular" (i.e. row/column) fashion. Tables may resemble a two-dimensional grid, as in a spreadsheet, or may feature objects which span multiple rows and/or columns, but whose bounds are aligned on a row/column matrix. Thus, the Table interface may be used to represent "spreadsheets" as well as "frames".

@@ -50,262 +45,270 @@

The number of rows currently selected. A selected row is one in which all included cells are selected. - @note Not all tables support row selection.

+ Not all tables support row selection.

The number of columns currently selected. A selected column is one in which all included cells are selected. - @note Not all tables support column selection.

+ Not all tables support column selection.

Get the table cell at the specified row and column indices. - @note To get the accessible object at a particular (x, y) screen coordinate, - use Accessible::getAccessibleAtPoint ().

+ To get the accessible object at a particular (x, y) screen coordinate, + use Accessible.getAccessibleAtPoint ().

 - the specified table row, zero-indexed. + The specified table row, zero-indexed. - the specified table column, zero-indexed. + The specified table column, zero-indexed. - an Accessible object representing the specified table cell. + An Accessible object representing the specified table cell.

Get the 1-D child index corresponding to the specified 2-D row and column indices. - @note To get the accessible object at a particular (x, y) screen coordinate, - use Accessible::getAccessibleAtPoint.

+ To get the accessible object at a particular (x, y) screen coordinate, + use Accessible.getAccessibleAtPoint.

- the specified table row, zero-indexed. + The specified table row, zero-indexed. - the specified table column, zero-indexed.@see getRowAtIndex, getColumnAtIndex + The specified table column, zero-indexed. - a long integer which serves as the index of a specified cell in thetable, in a form usable by Accessible::getChildAtIndex. + A long integer which serves as the index of a specified cell in the table, + in a form usable by Accessible.getChildAtIndex. -

Get the table row index occupied by the child at a particular 1-D child index.

+

Get the table row index occupied by the child at a particular 1-D child index.

 - the specified child index, zero-indexed.@see getIndexAt(), getColumnAtIndex() + The specified child index, zero-indexed. - a long integer indicating the first row spanned by the child of atable, at the specified 1-D (zero-offset) \c index. + A long integer indicating the first row spanned by the child of atable, at the specified 1-D (zero-offset) index. -

Get the table column index occupied by the child at a particular 1-D child index.

+

Get the table column index occupied by the child at a particular 1-D child index.

 - the specified child index, zero-indexed.@see getIndexAt(), getRowAtIndex() + The specified child index, zero-indexed. - a long integer indicating the first column spanned by the child of atable, at the specified 1-D (zero-offset) \c index. + A long integer indicating the first column spanned by the child of a table, + at the specified 1-D (zero-offset) index. -

Get a text description of a particular table row. This differs from - AccessibleTable_getRowHeader, which returns an Accessible.

+

Get a text description of a particular table row. This differs from + AccessibleTable.getRowHeader, which returns an Accessible.

 - the specified table row, zero-indexed. + The specified table row, zero-indexed. - a UTF-8 string describing the specified table row, if available. + A UTF-8 string describing the specified table row, if available. -

Get a text description of a particular table column. This differs from - AccessibleTable_getColumnHeader, which returns an Accessible.

+

Get a text description of a particular table column. This differs from + AccessibleTable.getColumnHeader, which returns an Accessible.

 - the specified table column, zero-indexed. + The specified table column, zero-indexed. - a UTF-8 string describing the specified table column, if available. + A UTF-8 string describing the specified table column, if available.

Get the number of rows spanned by the table cell at the specific row and column. - (some tables can have cells which span multiple rows and/or columns).

+ (some tables can have cells which span multiple rows and/or columns).

 - the specified table row, zero-indexed. + The specified table row, zero-indexed. - the specified table column, zero-indexed. + The specified table column, zero-indexed. - a long integer indicating the number of rows spanned by the specified cell. + A long integer indicating the number of rows spanned by the specified cell.

Get the number of columns spanned by the table cell at the specific row and column. - (some tables can have cells which span multiple rows and/or columns).

+ (some tables can have cells which span multiple rows and/or columns).

 - the specified table row, zero-indexed. + The specified table row, zero-indexed. - the specified table column, zero-indexed. + The specified table column, zero-indexed. - a long integer indicating the number of columns spanned by the specified cell. + A long integer indicating the number of columns spanned by the specified cell.

Get the header associated with a table row, if available. This differs from - getRowDescription, which returns a string.

+ getRowDescription, which returns a string.

 - the specified table row, zero-indexed. + The specified table row, zero-indexed. - an Accessible representatin of the specified table row, if available. + An Accessible representatin of the specified table row, if available.

Get the header associated with a table column, if available, as an - instance of Accessible. This differs from - getColumnDescription, which returns a string.

+ instance of Accessible. This differs from + getColumnDescription, which returns a string.

 - the specified table column, zero-indexed. + The specified table column, zero-indexed. - an Accessible representatin of the specified table column, if available. + An Accessible representatin of the specified table column, if available.

Obtain the indices of all rows which are currently selected. - @note Not all tables support row selection.

+ Not all tables support row selection.

- a sequence of integers comprising the indices of rows currently selected. + A sequence of integers comprising the indices of rows currently selected.

Obtain the indices of all columns which are currently selected. - @note Not all tables support column selection.

+ Not all tables support column selection.

- a sequence of integers comprising the indices of columns currently selected. + A sequence of integers comprising the indices of columns currently selected.

Determine whether a table row is selected. - @note Not all tables support row selection.

+ Not all tables support row selection.

- the row being queried. + The row being queried. - \c True if the specified row is currently selected, \c False if not. + True if the specified row is currently selected, False if not.

Determine whether a table column is selected. - @note Not all tables support column selection.

+ Not all tables support column selection.

- the column being queried. + The column being queried. - \c True if the specified column is currently selected, \c False if not. + True if the specified column is currently selected, False if not. -

Determine whether the cell at a specific row and column is selected. - @param row a row occupied by the cell whose state is being queried. - @param column a column occupied by the cell whose state is being queried.

+

Determine whether the cell at a specific row and column is selected.

 - - + + + A row occupied by the cell whose state is being queried. + + + + + A column occupied by the cell whose state is being queried. + + - \c True if the specified cell is currently selected, \c False if not. + True if the specified cell is currently selected, False if not. @@ -313,24 +316,26 @@

Select the specified row, adding it to the current row selection, if the table's selection model permits it.

- -

@param row - @note Possible reasons for addRowSelection to return \c False + + + +

+ Possible reasons for addRowSelection to return False include: - \li The table does not support Selection - \li The table row includes cells which do not have STATE_SELECTABLE - \li The table does not support selection by row - \li The table does not support selection of multiple rows, and - one row is already selected. - \li The table does not support non-contiguous selections (i.e. - does not include STATE_MULTISELECTABLE), and the specified row - would result in selection of non-contiguous rows. - \li The table does not support user-instigated selection.

- - +
    +
  1. The table does not support Selection
    2. +
  2. The table row includes cells which do not have STATE_SELECTABLE
    3. +
  3. The table does not support selection by row
    4. +
  4. The table does not support selection of multiple rows, and one row is already selected.
    5. +
  5. The table does not support non-contiguous selections (i.e. does not include STATE_MULTISELECTABLE), and the specified row would result in selection of non-contiguous rows.
    6. +
  6. The table does not support user-instigated selection
    7. +
+

+ + - \c True if the specified row was successfully selected, \c False if not. + True if the specified row was successfully selected, False if not. @@ -338,24 +343,26 @@

Select the specified column, adding it to the current column selection, if the table's selection model permits it.

- -

@param column - @note Possible reasons for addColumnSelection to return \c False + + + +

+ Possible reasons for addColumnSelection to return False include: - \li The table does not support Selection - \li The table column includes cells which do not have STATE_SELECTABLE - \li The table does not support selection by column - \li The table does not support selection of multiple columns, and - one column is already selected. - \li The table does not support non-contiguous selections (i.e. - does not include STATE_MULTISELECTABLE), and the specified column - would result in selection of non-contiguous columns. - \li The table does not support user-instigated selection.

- - +
    +
  1. The table does not support Selection
    2. +
  2. The table column includes cells which do not have STATE_SELECTABLE
    3. +
  3. The table does not support selection by column
    4. +
  4. The table does not support selection of multiple column, and one column is already selected.
    5. +
  5. The table does not support non-contiguous selections (i.e. does not include STATE_MULTISELECTABLE), and the specified column would result in selection of non-contiguous columns.
    6. +
  6. The table does not support user-instigated selection
    7. +
+

+ + - \c True if the specified column was successfully selected, \c False if not. + True if the specified column was successfully selected, False if not. @@ -364,16 +371,22 @@

Remove the specified row from current row selection, if the table's selection model permits it.

-

@param row - @note Possible reasons for removeRowSelection to return \c False - include: - \li The table does not support user-instigated Selection - \li The table has no selected rows or does not support deselection by row

- + + +

+ Possible reasons for removeRowSelection to return False + include: +

    +
  1. The table does not support user-instigated Selection
    2. +
  2. The table has no selected rows or does not support deselection by row
    3. +
+

+ + - \c True if the specified row was successfully de-selected, \c False if not. + True if the specified row was successfully de-selected, False if not. @@ -382,18 +395,22 @@

Remove the specified column from current column selection, if the table's selection model permits it.

-

@param column - @note Possible reasons for removeColumnSelection to return \c False - include: - \li The table does not support user-instigated modification of - selection state - \li The table has no selected columns or does not support - deselection by column.

- + + +

+ Possible reasons for removeColumnSelection to return \c False + include: +

    +
  1. The table does not support user-instigated modification of selection state
    2. +
  2. The table has no selected columns or does not support deselection by column.
    3. +
+

+ + - \c True if the specified column was successfully de-selected, \c False if not. + True if the specified column was successfully de-selected, False if not. @@ -401,68 +418,69 @@

Given a child index, determine the row and column indices and extents, and whether the cell is currently selected. If - the child at \c index is not a cell (for instance, if it is - a summary, caption, etc.), \c False is returned.

+ the child at index is not a cell (for instance, if it is + a summary, caption, etc.), False is returned.

-

@param index the index of the Table child whose row/column - extents are requested. - @param row back-filled with the first table row associated with - the cell with child index \c index. - @param col back-filled with the first table column associated - with the cell with child index \c index. - @param row_extents back-filled with the number of table rows - across which child \c i extends. - @param col_extents back-filled with the number of table columns - across which child \c i extends. - @param is_selected a boolean which is back-filled with \c True - if the child at index \c i corresponds to a selected table cell, - \c False otherwise.

Example: If the Table child at index '6' extends across columns 5 and 6 of row 2 of a Table instance, and is currently selected, then - \code + retval = table::getRowColumnExtentsAtIndex (6, row, col, row_extents, col_extents, is_selected); - \endcode - will return True, and after the call - \c row, \c col, \c row_extents, \c col_extents, - and \c is_selected will contain \c 2, \c 5, \c 1, \c 2, and - \c True, respectively.

- - - - - - - + + will return True, and after the call + row, col, row_extents, col_extents, + is_selected will contain 2, 5, 1, 2, and + True, respectively. +

+ + + + Ihe index of the Table child whose row/column + extents are requested. + + + + + Back-filled with the first table row associated with + the cell with child index index. + + + + + Back-filled with the first table column associated + with the cell with child index index. + + + + + Back-filled with the number of table rows + across which child i extends. + + + + + Back-filled with the number of table columns + across which child i extends. + + + + + A boolean which is back-filled with True + if the child at index i corresponds to a selected table cell, + False otherwise. + + - \c True if the index is associated with a valid tablecell, \c False if the index does not correspond to a cell. If \c False is returned, the values of the out parameters are undefined.@since AT-SPI 1.7.0 + True if the index is associated with a valid table-cell, + False if the index does not correspond to a cell. + If False is returned, the values of the out parameters are undefined. - - -

\cond - unImplemented:

- -

placeholders for future expansion.

- - - - - - - - - - - - - - diff --git a/xml/org.freedesktop.atspi.Text.xml b/xml/org.freedesktop.atspi.Text.xml index 67d0857..ca26016 100644 --- a/xml/org.freedesktop.atspi.Text.xml +++ b/xml/org.freedesktop.atspi.Text.xml @@ -1,10 +1,5 @@ - - - - -

Specifies the boundary conditions determining a run of text as returned from @@ -12,21 +7,21 @@ -

< Text is bounded by this character only. +

Text is bounded by this character only. Start and end offsets differ by one, by definition, for this value.

-

< Boundary condition is start of a word; i.e. range is from start of +

Boundary condition is start of a word; i.e. range is from start of one word to the start of another word.

-

< Boundary condition is the end of a word; i.e. range is from - the end of one word to the end of another. - @note some locales may not distinguish between words and +

Boundary condition is the end of a word; i.e. range is from + the end of one word to the end of another.

+

Some locales may not distinguish between words and characters or glyphs, in particular those locales which use wholly or partially ideographic character sets. In these cases, characters may be returned in lieu of multi-character substrings.

@@ -34,32 +29,32 @@ -

< Boundary condition is start of a sentence, as determined - by the application. - @note Some locales or character sets may not include explicit sentence +

Boundary condition is start of a sentence, as determined + by the application.

+

Some locales or character sets may not include explicit sentence delimiters, so this boundary type can not always be honored. Some locales will return lines of text instead of grammatical sentences.

 -

< Boundary condition is end of a sentence, as determined by the application, - including the sentence-delimiting character, for instance '.' - @note Some locales or character sets may not include explicit sentence +

Boundary condition is end of a sentence, as determined by the application, + including the sentence-delimiting character, for instance '.'

+

Some locales or character sets may not include explicit sentence delimiters, so this boundary type can not always be honored. Some locales will return lines of text instead of grammatical sentences.

 -

< Boundary condition is the start of a line; i.e. range is +

Boundary condition is the start of a line; i.e. range is from start of one line to the start of another. This generally means that an end-of-line character will appear at the end of the range.

-

< Boundary condition is the end of a line; i.e. range is +

Boundary condition is the end of a line; i.e. range is from start of one line to the start of another. This generally means that an end-of-line character will be the first character of the range.

@@ -75,17 +70,17 @@ - < characters/glyphs clipped by the minimum coordinate are omitted + Characters/glyphs clipped by the minimum coordinate are omitted - < characters/glyphs which intersect the maximum coordinate are omitted + Characters/glyphs which intersect the maximum coordinate are omitted - < only glyphs falling entirely within the region bounded by min and max are retained. + Only glyphs falling entirely within the region bounded by min and max are retained. @@ -99,34 +94,37 @@

In some cases a Text object may have, as its content, an empty string. In particular this can occur in the case of Hypertext objects which do not display explicitly textual information onscreen, - as Hypertext is derived from the Text interface. @see Hypertext.

+ as Hypertext is derived from the Text interface, see Hypertext.

Typographic and semantic attributes of onscreen textual content, for instance typeface, weight, language, and such qualities as 'emphasis' or 'blockquote', are represented as text attributes. Contiguous sequences of characters over which these attributes are unchanged are referred to as - "attribute runs", and are available via Text::getAttributeRun. Where possible, implementing clients + 'attribute runs', and are available via Text.getAttributeRun. Where possible, implementing clients will report textual attributes which are the same over the entire text object, for instance those inherited from a default or document-scope style, via getDefaultAttributes instead of reporting them explicitly for each character. Therefore, for any span of text, the attributes in effect are the union - of the set returned by Text::getDefaultAttributes, and the set returned at a particular character - offset via Text::getAttributeRun.

+ of the set returned by Text.getDefaultAttributes, and the set returned at a particular character + offset via Text.getAttributeRun.

-

@note Events that may be emitted by instances of Text include: - \li \c "object:text-attributes-changed" The attributes of a range of text, or the range over - which attributes apply, has changed. - \li \c "object:text-changed" The text content of this object has changed. - \li \c "object:text-bounds-changed" The character bounds of a text object have changed, - for instance in response to a reformatting or reflow operation. - \li \c "object:text-caret-moved" The character offset of the text caret (visible or notional) within - this object has changed. Events of this type may also be generated when an onscreen - text caret appears or disappears. - \li \c "object:text-selection-changed" The range or number of text selections within this text object - has changed.

+

Events that may be emitted by instances of Text include: +

    +
  1. 'object:text-attributes-changed' The attributes of a range of text, or the range + over which attributes apply, has changed.
    2. +
  2. 'object:text-changed' The text content of this object has changed.
    3. +
  3. 'object:text-bounds-changed' The character bounds of a text object have changed, + for instance in response to a reformatting or reflow operation.
    4. +
  4. 'object:text-caret-moved' The character offset of the text caret + (visible or notional) within this object has changed. Events of this + type may also be generated when an onscreen text caret appears or disappears.
    5. +
  5. 'object:text-selection-changed' The range or number of text selections within + this text object has changed.
    6. +
+

-

@note In some cases, objects which are not onscreen may implement Text, but if such objects +

In some cases, objects which are not onscreen may implement Text, but if such objects implement Component, their potential visibility should be examined (via comparison with STATE_VISIBLE and STATE_SHOWING) before exposing them to the user. Objects which implement Text but not Component - may be encountered in special-purpose interfaces or as special ¨accessibility¨ extensions to visual + may be encountered in special-purpose interfaces or as special 'accessibility' extensions to visual interfaces to allow non-graphical access to application features. These instances should be considered the exception, rather than the rule.

@@ -159,7 +157,7 @@

Obtain all or part of the onscreen textual content of a Text object. If endOffset is specified as "-1", then this method will return the entire onscreen textual contents of the Text object. - @note 'onscreen' in this context means "potentially onscreen", this method does not perform any sort + onscreen' in this context means "potentially onscreen", this method does not perform any sort of coordinate visibility clipping or window-stack-ordering clipping. The text thus reported corresponds to the text which would be presented onscreen if the object implementing the Text interface were entirely unobscured.

@@ -168,99 +166,135 @@ - the textual content of the current Text object beginning startOffset (inclusive) up to but not including the character at endOffset. + The textual content of the current Text object beginning startOffset (inclusive) up to but not including the character at endOffset. -

Programmatically move the text caret (visible or virtual, as above) to a given position. - @param offset a long int indicating the desired character offset. Not all implementations of - Text will honor setCaretOffset requests, so the return value below should be checked by the client.

+

Programmatically move the text caret (visible or virtual, as above) to a given position.

 - + + + A long int indicating the desired character offset. Not all implementations of + Text will honor setCaretOffset requests, so the return value below should be checked by the client. + + - \c TRUE if the request was carried out, or \c FALSE if the caret could not be moved to the requested position. + True if the request was carried out, or False if the caret could not be moved to the requested position. -

Obtain a subset of the text content of an object which entirely precedes \c offset, - delimited by character, word, line, or sentence boundaries as specified by \c type. The - starting and ending offsets of the resulting substring are returned in \c startOffset - and \c endOffset. By definition, if such a substring exists, \c endOffset is less than or - equal to \c offset. - @param offset the offset from which the substring search begins. - @param type the text-boundary delimiter which determines whether the returned text constitures +

Obtain a subset of the text content of an object which entirely precedes offset, + delimited by character, word, line, or sentence boundaries as specified by type. The + starting and ending offsets of the resulting substring are returned in startOffset + and startOffset. By definition, if such a substring exists, startOffset + is less than or equal to offset.

+ + + + The offset from which the substring search begins. + + + + + The text-boundary delimiter which determines whether the returned text constitures a character, word, line, or sentence (and possibly attendant whitespace), and whether the start or ending of such a substring forms the boundary condition. - @param startOffset back-filled with the starting offset of the resulting substring, if one exists. - @param endOffset back-filled with the offset of the character immediately following the resulting + + + + + Back-filled with the starting offset of the resulting substring, if one exists. + + + + + Back-filled with the offset of the character immediately following the resulting substring, if one exists. - @see TEXT_BOUNDARY_TYPE

- - - - - + + - a string which is a substring of the text content of the object, delimited by thespecified boundary condition. + A string which is a substring of the text content of the object, delimited by thespecified boundary condition. -

Obtain a subset of the text content of an object which includes the specified \c offset, - delimited by character, word, line, or sentence boundaries as specified by \c type. The - starting and ending offsets of the resulting substring are returned in \c startOffset - and \c endOffset. - @param offset the offset from which the substring search begins, and which must +

Obtain a subset of the text content of an object which includes the specified offset, + delimited by character, word, line, or sentence boundaries as specified by type. The + starting and ending offsets of the resulting substring are returned in startOffset + and endOffset.

+ + + + The offset from which the substring search begins, and which must lie within the returned substring. - @param type the text-boundary delimiter which determines whether the returned text constitures + + + + + The text-boundary delimiter which determines whether the returned text constitures a character, word, line, or sentence (and possibly attendant whitespace), and whether the start or ending of such a substring forms the boundary condition. - @param startOffset back-filled with the starting offset of the resulting substring, if one exists. - @param endOffset back-filled with the offset of the character immediately following the resulting + + + + + Back-filled with the starting offset of the resulting substring, if one exists. + + + + + Back-filled with the offset of the character immediately following the resulting substring, if one exists. - @see TEXT_BOUNDARY_TYPE

- - - - - + + - a string which is a substring of the text content of the object, delimited by thespecified boundary condition. + A string which is a substring of the text content of the object, delimited by thespecified boundary condition. -

Obtain a subset of the text content of an object which entirely follows \c offset, - delimited by character, word, line, or sentence boundaries as specified by \c type. The - starting and ending offsets of the resulting substring are returned in \c startOffset - and \c endOffset. By definition, if such a substring exists, \c startOffset must be greater than - \c offset. - @param offset the offset from which the substring search begins, and which must +

Obtain a subset of the text content of an object which entirely follows offset, + delimited by character, word, line, or sentence boundaries as specified by type. The + starting and ending offsets of the resulting substring are returned in startOffset + and endOffset. By definition, if such a substring exists, startOffset + must be greater than offset.

+ + + + The offset from which the substring search begins, and which must lie before the returned substring. - @param type the text-boundary delimiter which determines whether the returned text constitures + + + + + The text-boundary delimiter which determines whether the returned text constitures a character, word, line, or sentence (and possibly attendant whitespace), and whether the start or ending of such a substring forms the boundary condition. - @param startOffset back-filled with the starting offset of the resulting substring, if one exists. - @param endOffset back-filled with the offset of the character immediately following the resulting + + + + + Back-filled with the starting offset of the resulting substring, if one exists. + + + + + Back-filled with the offset of the character immediately following the resulting substring, if one exists. - @see TEXT_BOUNDARY_TYPE

- - - - - + + - a string which is a substring of the text content of the object, delimited by thespecified boundary condition. + A string which is a substring of the text content of the object, delimited by thespecified boundary condition. @@ -268,32 +302,47 @@ - an unsigned long integer whose value corresponds to the UCS-4 representation of the + An unsigned long integer whose value corresponds to the UCS-4 representation of the character at the specified text offset, or 0 if offset is out of range. - long instead of wchar, to allow unicode chars > 16 bits + long instead of wchar, to allow unicode chars 16 bits -

Get the string value of a named attribute at a given offset, if defined. - @param offset the offset of the character for which the attribute run is to be obtained. - @param attributeName the name of the attribute for which the value is to be returned, if defined. - @param startOffset back-filled with the offset of the first character in the attribute run - containing the character at \c offset. - @param endOffset back-filled with the offset of the first character past the end of the - attribute run containing the character at \c offset. - @param defined back-filled with \c True if the attributeName has a defined value at \c offset, - \c False otherwise.

+

Get the string value of a named attribute at a given offset, if defined.

 - - - - - + + + The offset of the character for which the attribute run is to be obtained. + + + + + The name of the attribute for which the value is to be returned, if defined. + + + + + Back-filled with the offset of the first character in the attribute run + containing the character at offset. + + + + + Back-filled with the offset of the first character past the end of the + attribute run containing the character at offset. + + + + + Back-filled with True if the attributeName has a defined value at offset, + False otherwise. + + - the value of attribute (name-value pair) corresponding to "name", if defined. + The value of attribute (name-value pair) corresponding to "name", if defined. @@ -306,7 +355,7 @@ - the attributes at offset, as a semicolon-delimited set of colon-delimited name-value pairs. @see getAttributeRun + The attributes at offset, as a semicolon-delimited set of colon-delimited name-value pairs. @see getAttributeRun @@ -316,7 +365,7 @@ - the attributes which apply to the entire text content, but which were not explicitlyspecified by the content creator.@see getDefaultAttributeSet + The attributes which apply to the entire text content, but which were not explicitlyspecified by the content creator. @@ -326,44 +375,63 @@ character offset in this object's text content. The coordinate system in which the results are reported is specified by coordType. If an onscreen glyph corresponds to multiple character offsets, for instance if the glyph is a ligature, the bounding box reported will include the entire glyph and - therefore may apply to more than one character offset. - @param offset the character offset of the character or glyph being queried. - @param x the minimum horizontal coordinate of the bounding box of the glyph representing - the character at \c offset. - @param y the minimum vertical coordinate of the bounding box of the glyph representing - the character at \c offset. - @param width the horizontal extent of the bounding box of the glyph representing - the character at \c offset. - @param height the vertical extent of the bounding box of the glyph representing - the character at \c offset. - @param coordType If 0, the results will be reported in screen coordinates, i.e. in pixels + therefore may apply to more than one character offset.

+ + + + The character offset of the character or glyph being queried. + + + + + The minimum horizontal coordinate of the bounding box of the glyph representing + the character at offset. + + + + + The minimum vertical coordinate of the bounding box of the glyph representing + the character at offset. + + + + + The horizontal extent of the bounding box of the glyph representing + the character at offset. + + + + + The vertical extent of the bounding box of the glyph representing + the character at offset. + + + + +

If 0, the results will be reported in screen coordinates, i.e. in pixels relative to the upper-left corner of the screen, with the x axis pointing right and the y axis pointing down. If 1, the results will be reported relative to the containing toplevel window, with the x axis pointing right and the y axis pointing down.

- - - - - - - + +

Get the offset of the character at a given onscreen coordinate. The coordinate system used to interpret - x and y is determined by parameter coordType. - @param x - @param y - @param coordType if 0, the input coordinates are interpreted relative to the entire screen, if 1, - they are relative to the toplevel window containing this Text object.

+ x and y is determined by parameter coordType.

 - + + + If 0, the input coordinates are interpreted relative to the entire screen, if 1, + they are relative to the toplevel window containing this Text object. + + - the text offset (as an offset into the character array) of the glyph whose onscreen bounds contain the point x,y, or -1 if the point is outside the bounds of any glyph. + The text offset (as an offset into the character array) of the glyph whose onscreen bounds contain the point x,y, or -1 if the point is outside the bounds of any glyph. @@ -377,7 +445,7 @@ - the number of contiguous selections in the current Text object. + The number of contiguous selections in the current Text object. @@ -399,7 +467,7 @@ - \c True of the selection was successfully added, \c False otherwise. Selection mayfail if the object does not support selection of text (see STATE_SELECTABLE_TEXT), if theobject does not support multiple selections and a selection is already defined, or for other reasons(for instance if the user does not have permission to copy the text into the relevant selection buffer). + True of the selection was successfully added, False otherwise. Selection mayfail if the object does not support selection of text (see STATE_SELECTABLE_TEXT), if theobject does not support multiple selections and a selection is already defined, or for other reasons(for instance if the user does not have permission to copy the text into the relevant selection buffer). @@ -411,7 +479,7 @@ - \c True if the selection was successfully removed, \c False otherwise. + True if the selection was successfully removed, False otherwise. @@ -421,17 +489,27 @@

Calling setSelection for a selectionNum that is not already defined has no effect. The result of calling setSelection with a selectionNum greater than 0 for objects that - do not include STATE_MULTISELECTABLE is undefined. - @param selectionNum indicates which of a set of non-contiguous selections to modify. - @param startOffset the new starting offset for the selection - @param endOffset the new ending offset for the selection

+ do not include STATE_MULTISELECTABLE is undefined.

- - - + + + Indicates which of a set of non-contiguous selections to modify. + + + + + The new starting offset for the selection + + + + + The new ending offset for the selection + + - \c True if the selection corresponding to selectionNum is successfully modified, \c False otherwise. + True if the selection corresponding to selectionNum is successfully + modified, False otherwise. @@ -439,29 +517,50 @@

Obtain the bounding box which entirely contains a given text range. Negative values may be returned for the bounding box parameters in the event - that all or part of the text range is offscreen or not mapped to the screen. + that all or part of the text range is offscreen or not mapped to the screen.

+ + + @param startOffset the offset of the first character in the specified range. - @param endOffset the offset of the character immediately after the last + + + + + The offset of the character immediately after the last character in the specified range. - @param x an integer parameter which is back-filled with the minimum + + + + + An integer parameter which is back-filled with the minimum horizontal coordinate of the resulting bounding box. - @param y an integer parameter which is back-filled with the minimum + + + + + An integer parameter which is back-filled with the minimum vertical coordinate of the resulting bounding box. - @param width an integer parameter which is back-filled with the + + + + + An integer parameter which is back-filled with the horizontal extent of the bounding box. - @param height an integer parameter which is back-filled with the + + + + + + An integer parameter which is back-filled with the vertical extent of the bounding box. - @param coordType If 0, the above coordinates are reported in pixels relative to + + + + If 0, the above coordinates are reported in pixels relative to corner of the screen; if 1, the coordinates are reported relative to the - corner of the containing toplevel window.

+ corner of the containing toplevel window. - - - - - - - + @@ -470,29 +569,49 @@ Depending on the TEXT_CLIP_TYPE parameters, glyphs which are clipped by the bounding box (i.e. which lie partially inside and partially outside it) may or may not be included in the ranges returned. - @note This method may be of particular interest to screen review algorithms. - @see TEXT_CLIP_TYPE. - @param x the minimum x ( i.e. leftmost) coordinate of the bounding box. - @param y the minimum y coordinate of the bounding box. - @param width the horizontal size of the bounding box. The rightmost bound of the bounding box + This method may be of particular interest to screen review algorithms.

+ + + + The minimum x ( i.e. leftmost) coordinate of the bounding box. + + + + + The minimum y coordinate of the bounding box. + + + + + The horizontal size of the bounding box. The rightmost bound of the bounding box is (x + width); - @param height the vertical size of the bounding box. The maximum y value of the bounding box + + + + + The vertical size of the bounding box. The maximum y value of the bounding box is (y + height); - @param coordType If 0, the above coordinates are interpreted as pixels relative to + + + + + If 0, the above coordinates are interpreted as pixels relative to corner of the screen; if 1, the coordinates are interpreted as pixels relative to the corner of the containing toplevel window. - @param xClipType determines whether text which intersects the bounding box in the x direction + + + + + Determines whether text which intersects the bounding box in the x direction is included. - @param yClipType determines whether text which intersects the bounding box in the y direction - is included.

- - - - - - - - + + + + + Determines whether text which intersects the bounding box in the y direction + is included. + + @@ -510,70 +629,68 @@ WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/). Those attributes from the aforementioned specifications and recommendations which do not concern typographic, presentational, or semantic aspects of text should be exposed via the more general Accessible::getAttributes() API - (if at all).

+ (if at all).

For example, CSS attributes which should be exposed on text (either as default attributes, or as explicitly-set attributes when non-default values are specified in the content view) include the Font attributes (i.e. "css2:font-weight", "css2:font-style"), the "css2:color" and "css2:background-color" attributes, and "css2:text-decoration" attribute.

-

If includeDefaults is TRUE, then this AttributeSet should include the default +

If includeDefaults is True, then this AttributeSet should include the default attributes as well as those which are explicitly assigned to the attribute run in question. startOffset and endOffset will be back-filled to indicate the start and end of the attribute run which contains 'offset' - an attribute run is a contiguous section of text whose attributes are - homogeneous. - @param offset the offset of the character whose attributes will be reported. - @param startOffset backfilled with the starting offset of the character range over which all - text attributes match those of \c offset, i.e. the start of the homogeneous - attribute run including \c offset. - @param endOffset backfilled with the offset of the first character past the character range over which all - text attributes match those of \c offset, i.e. the character immediately after - the homogeneous attribute run including \c offset. - @param includeDefaults if False, the call should only return those attributes which are - explicitly set on the current attribute run, omitting any attributes which are inherited from - the default values. See also Text::getDefaultAttributes.

+ homogeneous.

-

@note Clients seeking annotations or properties of a more general nature, which +

Clients seeking annotations or properties of a more general nature, which are not specific to the onscreen textual content of objects and cannot logically be applied to specific character offset ranges, - should use Accessible::getAttributes instead. - The attributes returned by Text::getAttributeRun (with or without 'default attributes'), - are distinct from the properties/attributes returned by Accessible::getAttributes.

- -

@see Accessible::getAttributes

- - - - - + should use Accessible.getAttributes instead. + The attributes returned by Text.getAttributeRun (with or without 'default attributes'), + are distinct from the properties/attributes returned by Accessible.getAttributes.

+ + + + The offset of the character whose attributes will be reported. + + + + + Backfilled with the starting offset of the character range over which all + text attributes match those of offset, i.e. the start of the homogeneous + attribute run including offset. + + + + + Backfilled with the offset of the first character past the character range over which all + text attributes match those of offset, i.e. the character immediately after + the homogeneous attribute run including offset. + + + + + If False, the call should only return those attributes which are + explicitly set on the current attribute run, omitting any attributes which are inherited from + the default values. See also Text.getDefaultAttributes. + + - the AttributeSet defined at offset, optionally including the 'default' attributes. @since AT-SPI 1.7.0 + The AttributeSet defined at offset, optionally including the 'default' attributes. -

Return an ::AttributeSet containing the text attributes which apply to all text in the object +

Return an AttributeSet containing the text attributes which apply to all text in the object by virtue of the default settings of the document, view, or user agent; e.g. those attributes which are implied rather than explicitly applied to the text object. For instance, an object whose entire text content has been explicitly marked as 'bold' will report the 'bold' attribute via getAttributeRun(), whereas an object whose text weight is inspecified may report the default or implied text weight in the default AttributeSet.

- -

@since AT-SPI 1.7.0

 - - -

\cond - unImplemented:

- -

placeholders for future expansion.

- - - - diff --git a/xml/org.freedesktop.atspi.Tree.xml b/xml/org.freedesktop.atspi.Tree.xml index 21e50ea..cf79a66 100644 --- a/xml/org.freedesktop.atspi.Tree.xml +++ b/xml/org.freedesktop.atspi.Tree.xml @@ -1,11 +1,5 @@ - - - - - -

The wire structure of an Accessible object proxy

diff --git a/xml/org.freedesktop.atspi.Value.xml b/xml/org.freedesktop.atspi.Value.xml index cb96f8a..8c7d2ac 100644 --- a/xml/org.freedesktop.atspi.Value.xml +++ b/xml/org.freedesktop.atspi.Value.xml @@ -1,10 +1,5 @@ - - - - -

An interface supporting controls which allow a @@ -12,8 +7,8 @@ reflect a scalar quantity. (If STATE_EDITABLE is not present, the valuator is treated as "read only".

-

@note Events generated by Image instances include: - \li \c "object:value-changed"

+

Events generated by Image instances include: + 'object:value-changed'

 @@ -38,19 +33,5 @@ The current value of the valuator. - - -

\cond - unImplemented:

- -

placeholders for future expansion.

- - - - - - - -