Commit 0f1e31ad authored by Alejandro Piñeiro's avatar Alejandro Piñeiro
Browse files

doc: removing several .sgml files and fixing gtk-doc warnings

The static documentation of those .sgml (so the reason of
tracking those objects) where moved to the source files.

Some other stuff was changed in order to prevent gtk-doc warnings
(like replacing "Returns blah" for the correct "Returns: blah")

https://bugzilla.gnome.org/show_bug.cgi?id=684665
parent c568794a
......@@ -41,3 +41,46 @@ atkversion.h
tests/testrelation
tests/testrole
tests/teststateset
docs/.libs
docs/atk.args
docs/atk.hierarchy
docs/atk.interfaces
docs/atk.prerequisites
docs/atk.signals
docs/html
docs/tmpl/atkaction.sgml
docs/tmpl/atkcomponent.sgml
docs/tmpl/atkdocument.sgml
docs/tmpl/atkhyperlinkimpl.sgml
docs/tmpl/atkobject.sgml
docs/tmpl/atkmisc.sgml
docs/tmpl/atktext.sgml
docs/tmpl/atkplug.sgml
docs/tmpl/atksocket.sgml
docs/tmpl/atkutil.sgml
docs/tmpl/atkversion.sgml
docs/tmpl/atkwindow.sgml
docs/atk.signals
docs/xml
docs/atk-decl-list.txt
docs/atk-decl.txt
docs/atk-undeclared.txt
docs/atk-undocumented.txt
docs/atk-unused.txt
docs/tmpl/atkeditabletext.sgml
docs/tmpl/atkgobjectaccessible.sgml
docs/tmpl/atkhyperlink.sgml
docs/tmpl/atkhypertext.sgml
docs/tmpl/atkimage.sgml
docs/tmpl/atknoopobject.sgml
docs/tmpl/atknoopobjectfactory.sgml
docs/tmpl/atkobjectfactory.sgml
docs/tmpl/atkregistry.sgml
docs/tmpl/atkrelation.sgml
docs/tmpl/atkrelationset.sgml
docs/tmpl/atkselection.sgml
docs/tmpl/atkstate.sgml
docs/tmpl/atkstateset.sgml
docs/tmpl/atkstreamablecontent.sgml
docs/tmpl/atktable.sgml
docs/tmpl/atkvalue.sgml
......@@ -19,6 +19,32 @@
#include "atkaction.h"
/**
* SECTION:atkaction
* @Short_description: The ATK interface provided by UI components
* which the user can activate/interact with.
* @Title:AtkAction
*
* #AtkAction should be implemented by instances of #AtkObject classes
* with which the user can interact directly, i.e. buttons,
* checkboxes, scrollbars, e.g. components which are not "passive"
* providers of UI information.
*
* Exceptions: when the user interaction is already covered by another
* appropriate interface such as #AtkEditableText (insert/delete text,
* etc.) or #AtkValue (set value) then these actions should not be
* exposed by #AtkAction as well.
*
* Though most UI interactions on components should be invocable via
* keyboard as well as mouse, there will generally be a close mapping
* between "mouse actions" that are possible on a component and the
* AtkActions. Where mouse and keyboard actions are redundant in
* effect, #AtkAction should expose only one action rather than
* exposing redundant actions if possible. By convention we have been
* using "mouse centric" terminology for #AtkAction names.
*
*/
GType
atk_action_get_type (void)
{
......@@ -98,8 +124,8 @@ atk_action_get_n_actions (AtkAction *obj)
*
* Returns a description of the specified action of the object.
*
* Returns a description string, or %NULL
* if @action does not implement this interface.
* Returns: a description string, or %NULL if @action does not
* implement this interface.
**/
const gchar*
atk_action_get_description (AtkAction *obj,
......@@ -137,8 +163,8 @@ atk_action_get_description (AtkAction *obj,
* i.e. the result of some actions via atk_action_do_action() may be
* NIL.
*
* Returns a name string, or %NULL
* if @action does not implement this interface.
* Returns: a name string, or %NULL if @action does not implement this
* interface.
**/
const gchar*
atk_action_get_name (AtkAction *obj,
......@@ -163,8 +189,8 @@ atk_action_get_name (AtkAction *obj,
*
* Returns the localized name of the specified action of the object.
*
* Returns a name string, or %NULL
* if @action does not implement this interface.
* Returns: a name string, or %NULL if @action does not implement this
* interface.
**/
const gchar*
atk_action_get_localized_name (AtkAction *obj,
......@@ -210,8 +236,8 @@ atk_action_get_localized_name (AtkAction *obj,
* for the German locale. If, hypothetically, this menu item lacked a mnemonic,
* it would be represented by ";;Ctrl+N" and ";;Strg+N" respectively.
*
* Returns the keybinding which can be used to activate this action, or %NULL
* if there is no keybinding for this action.
* Returns: the keybinding which can be used to activate this action,
* or %NULL if there is no keybinding for this action.
*
**/
const gchar*
......
......@@ -20,6 +20,25 @@
#include "atkcomponent.h"
/**
* SECTION:atkcomponent
* @Short_description: The ATK interface provided by UI components
* which occupy a physical area on the screen.
* which the user can activate/interact with.
* @Title:AtkComponent
*
* #AtkComponent should be implemented by most if not all UI elements
* with an actual on-screen presence, i.e. components which can be
* said to have a screen-coordinate bounding box. Virtually all
* widgets will need to have #AtkComponent implementations provided
* for their corresponding #AtkObject class. In short, only UI
* elements which are *not* GUI elements will omit this ATK interface.
*
* A possible exception might be textual information with a
* transparent background, in which case text glyph bounding box
* information is provided by #AtkText.
*/
enum {
BOUNDS_CHANGED,
LAST_SIGNAL
......@@ -80,6 +99,15 @@ atk_component_base_init (AtkComponentIface *class)
class->get_position = atk_component_real_get_position;
class->get_size = atk_component_real_get_size;
/**
* AtkComponent::bounds-changed:
* @atkcomponent: the object which received the signal.
* @arg1: The AtkRectangle giving the new position and size.
*
* The 'bounds-changed" signal is emitted when the bposition or
* size of the component changes.
*/
atk_component_signals[BOUNDS_CHANGED] =
g_signal_new ("bounds_changed",
ATK_TYPE_COMPONENT,
......
......@@ -19,6 +19,22 @@
#include "atkdocument.h"
/**
* SECTION:atkdocument
* @Short_description: The ATK interface which represents the toplevel
* container for document content.
* @Title:AtkDocument
*
* The AtkDocument interface should be supported by any object whose
* content is a representation or view of a document. The AtkDocument
* interface should appear on the toplevel container for the document
* content; however AtkDocument instances may be nested (i.e. an
* AtkDocument may be a descendant of another AtkDocument) in those
* cases where one document contains "embedded content" which can
* reasonably be considered a document in its own right.
*
*/
enum {
LOAD_COMPLETE,
RELOAD,
......@@ -56,6 +72,20 @@ atk_document_base_init (AtkDocumentIface *class)
static gboolean initialized = FALSE;
if (!initialized)
{
/**
* AtkDocument::load-complete:
* @atkdocument: the object which received the signal.
*
* The 'load-complete' signal is emitted when a pending load of
* a static document has completed. This signal is to be
* expected by ATK clients if and when AtkDocument implementors
* expose ATK_STATE_BUSY. If the state of an AtkObject which
* implements AtkDocument does not include ATK_STATE_BUSY, it
* should be safe for clients to assume that the AtkDocument's
* static contents are fully loaded into the container.
* (Dynamic document contents should be exposed via other
* signals.)
*/
atk_document_signals[LOAD_COMPLETE] =
g_signal_new ("load_complete",
ATK_TYPE_DOCUMENT,
......@@ -64,6 +94,16 @@ atk_document_base_init (AtkDocumentIface *class)
(GSignalAccumulator) NULL, NULL,
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE, 0);
/**
* AtkDocument::reload:
* @atkdocument: the object which received the signal.
*
* The 'reload' signal is emitted when the contents of a
* document is refreshed from its source. Once 'reload' has
* been emitted, a matching 'load-complete' or 'load-stopped'
* signal should follow, which clients may await before
* interrogating ATK for the latest document content.
*/
atk_document_signals[RELOAD] =
g_signal_new ("reload",
ATK_TYPE_DOCUMENT,
......@@ -72,6 +112,18 @@ atk_document_base_init (AtkDocumentIface *class)
(GSignalAccumulator) NULL, NULL,
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE, 0);
/**
* AtkDocument::load-stopped:
* @atkdocument: the object which received the signal.
*
* The 'load-stopped' signal is emitted when a pending load of
* document contents is cancelled, paused, or otherwise
* interrupted by the user or application logic. It should not
* however be emitted while waiting for a resource (for instance
* while blocking on a file or network read) unless a
* user-significant timeout has occurred.
*/
atk_document_signals[LOAD_STOPPED] =
g_signal_new ("load_stopped",
ATK_TYPE_DOCUMENT,
......
......@@ -19,6 +19,22 @@
#include "atkeditabletext.h"
/**
* SECTION:atkeditabletext
* @Short_description: The ATK interface implemented by components
* containing user-editable text content.
* @Title:AtkEditableText
*
* #AtkEditableText should be implemented by UI components which
* contain text which the user can edit, via the #AtkObject
* corresponding to that component (see #AtkObject).
*
* #AtkEditableText is a subclass of #AtkText, and as such, an object
* which implements #AtkEditableText is by definition an #AtkText
* implementor as well.
*
* See also: #AtkText
*/
GType
atk_editable_text_get_type (void)
......
......@@ -21,6 +21,17 @@
#include <atk/atkregistry.h>
#include <atk/atkutil.h>
/**
* SECTION:atkgobjectaccessible
* @Short_description: This object class is derived from AtkObject and
* can be used as a basis implementing accessible objects.
* @Title:AtkGObjectAccessible
*
* This object class is derived from AtkObject. It can be used as a
* basis for implementing accessible objects for GObjects which are
* not derived from GtkWidget. One example of its use is in providing
* an accessible object for GnomeCanvasItem in the GAIL library.
*/
static void atk_gobject_accessible_class_init (AtkGObjectAccessibleClass *klass);
static void atk_real_gobject_accessible_initialize (AtkObject *atk_obj,
gpointer data);
......
......@@ -21,6 +21,20 @@
#include "atkhyperlink.h"
#include "atkintl.h"
/**
* SECTION:atkhyperlink
* @Short_description: An ATK object which encapsulates a link or set
* of links in a hypertext document.
* @Title:AtkHyperlink
*
* An ATK object which encapsulates a link or set of links (for
* instance in the case of client-side image maps) in a hypertext
* document. It may implement the AtkAction interface. AtkHyperlink
* may also be used to refer to inline embedded content, since it
* allows specification of a start and end offset within the host
* AtkHypertext object.
*/
enum
{
LINK_ACTIVATED,
......@@ -132,6 +146,13 @@ atk_hyperlink_class_init (AtkHyperlinkClass *klass)
G_MAXINT,
0,
G_PARAM_READABLE));
/**
* AtkHyperlink::link-activated:
* @atkhyperlink: the object which received the signal.
*
* The signal link-activated is emitted when a link is activated.
*/
atk_hyperlink_signals[LINK_ACTIVATED] =
g_signal_new ("link_activated",
G_TYPE_FROM_CLASS (klass),
......
......@@ -20,6 +20,42 @@
#include <string.h>
#include "atkhyperlinkimpl.h"
/**
* SECTION:atkhyperlinkimpl
* @Short_description: An interface from which the AtkHyperlink
* associated with an AtkObject may be obtained.
* @Title:AtkHyperlinImpl
*
* AtkHyperlinkImpl allows AtkObjects to refer to their associated
* AtkHyperlink instance, if one exists. AtkHyperlinkImpl differs
* from AtkHyperlink in that AtkHyperlinkImpl is an interface, whereas
* AtkHyperlink is a object type. The AtkHyperlinkImpl interface
* allows a client to query an AtkObject for the availability of an
* associated AtkHyperlink instance, and obtain that instance. It is
* thus particularly useful in cases where embedded content or inline
* content within a text object is present, since the embedding text
* object implements AtkHypertext and the inline/embedded objects are
* exposed as children which implement AtkHyperlinkImpl, in addition
* to their being obtainable via AtkHypertext:getLink followed by
* AtkHyperlink:getObject.
*
* The AtkHyperlinkImpl interface should be supported by objects
* exposed within the hierarchy as children of an AtkHypertext
* container which correspond to "links" or embedded content within
* the text. HTML anchors are not, for instance, normally exposed
* this way, but embedded images and components which appear inline in
* the content of a text object are. The AtkHyperlinkIface interface
* allows a means of determining which children are hyperlinks in this
* sense of the word, and for obtaining their corresponding
* AtkHyperlink object, from which the embedding range, URI, etc. can
* be obtained.
*
* To some extent this interface exists because, for historical
* reasons, AtkHyperlink was defined as an object type, not an
* interface. Thus, in order to interact with AtkObjects via
* AtkHyperlink semantics, a new interface was required.
*/
GType
atk_hyperlink_impl_get_type (void)
{
......
......@@ -29,23 +29,6 @@
G_BEGIN_DECLS
/*
* The AtkHyperlinkImpl interface should be supported by objects
* exposed within the hierarchy as children of an AtkHypertext container
* which correspond to "links" or embedded content within the text.
* HTML anchors are not, for instance, normally exposed this way,
* but embedded images and components which appear inline in the
* content of a text object are. The AtkHyperlinkIface interface
* allows a means of determining which children are hyperlinks in this
* sense of the word, and for obtaining their corresponding AtkHyperlink
* object, from which the embedding range, URI, etc. can be obtained.
*
* To some extent this interface exists because, for historical
* reasons, AtkHyperlink was defined as an object type, not an interface.
* Thus, in order to interact with AtkObjects via AtkHyperlink semantics,
* a new interface was required.
*/
#define ATK_TYPE_HYPERLINK_IMPL (atk_hyperlink_impl_get_type ())
#define ATK_IS_HYPERLINK_IMPL(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_HYPERLINK_IMPL)
#define ATK_HYPERLINK_IMPL(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_HYPERLINK_IMPL, AtkHyperlinkImpl)
......@@ -53,6 +36,16 @@ G_BEGIN_DECLS
#ifndef _TYPEDEF_ATK_HYPERLINK_IMPL_
#define _TYPEDEF_ATK_HYPERLINK_IMPL__
/**
* AtkHyperlinkImpl:
*
* A queryable interface which allows AtkHyperlink instances
* associated with an AtkObject to be obtained. AtkHyperlinkImpl
* corresponds to AT-SPI's Hyperlink interface, and differs from
* AtkHyperlink in that AtkHyperlink is an object type, rather than an
* interface, and thus cannot be directly queried. FTW
*/
typedef struct _AtkHyperlinkImpl AtkHyperlinkImpl;
#endif
typedef struct _AtkHyperlinkImplIface AtkHyperlinkImplIface;
......
......@@ -19,6 +19,22 @@
#include "atkhypertext.h"
/**
* SECTION:atkhypertext
* @Short_description: The ATK interface which provides standard
* mechanism for manipulating hyperlinks.
* @Title:AtkHypertext
*
* An interface used for objects which implement linking between
* multiple resource or content locations, or multiple 'markers'
* within a single document. A Hypertext instance is associated with
* one or more Hyperlinks, which are associated with particular
* offsets within the Hypertext's included content. While this
* interface is derived from Text, there is no requirement that
* Hypertext instances have textual content; they may implement Image
* as well, and Hyperlinks need not have non-zero text offsets.
*/
enum {
LINK_SELECTED,
LAST_SIGNAL
......@@ -56,6 +72,15 @@ atk_hypertext_base_init (AtkHypertextIface *class)
if (!initialized)
{
/**
* AtkHypertext::link-selected:
* @atkhypertext: the object which received the signal.
* @arg1: the index of the hyperlink which is selected
*
* The "link-selected" signal is emitted by an AtkHyperText
* object when one of the hyperlinks associated with the object
* is selected.
*/
atk_hypertext_signals[LINK_SELECTED] =
g_signal_new ("link_selected",
ATK_TYPE_HYPERTEXT,
......
......@@ -19,6 +19,27 @@
#include "atkimage.h"
/**
* SECTION:atkimage
* @Short_description: The ATK Interface implemented by components
* which expose image or pixmap content on-screen.
* @Title:AtkImage
*
* #AtkImage should be implemented by #AtkObject subtypes on behalf of
* components which display image/pixmap information onscreen, and
* which provide information (other than just widget borders, etc.)
* via that image content. For instance, icons, buttons with icons,
* toolbar elements, and image viewing panes typically should
* implement #AtkImage.
*
* #AtkImage primarily provides two types of information: coordinate
* information (useful for screen review mode of screenreaders, and
* for use by onscreen magnifiers), and descriptive information. The
* descriptive information is provided for alternative, text-only
* presentation of the most significant information present in the
* image.
*/
GType
atk_image_get_type (void)
{
......@@ -189,7 +210,9 @@ atk_image_get_image_position (AtkImage *image,
*
* Since ATK 1.12
*
* Returns a string corresponding to the POSIX LC_MESSAGES locale used by the image description, or NULL if the image does not specify a locale.
* Returns: a string corresponding to the POSIX LC_MESSAGES locale
* used by the image description, or NULL if the image does not
* specify a locale.
*
*/
const gchar*
......
......@@ -20,6 +20,19 @@
#include "atk.h"
#include "atknoopobject.h"
/**
* SECTION:atknoopobject
* @Short_description: An AtkObject which purports to implement all ATK interfaces.
* @Title:AtkNoOpObject
*
* An AtkNoOpObject is an AtkObject which purports to implement all
* ATK interfaces. It is the type of AtkObject which is created if an
* accessible object is requested for an object type for which no
* factory type is specified.
*
*/
static void atk_no_op_object_class_init (AtkNoOpObjectClass *klass);
static gpointer parent_class = NULL;
......
......@@ -21,6 +21,15 @@
#include "atknoopobject.h"
#include "atknoopobjectfactory.h"
/**
* SECTION:atknoopobjectfactory
* @Short_description: The AtkObjectFactory which creates an AtkNoOpObject.
* @Title:AtkNoOpObjectFactory
*
* The AtkObjectFactory which creates an AtkNoOpObject. An instance of
* this is created by an AtkRegistry if no factory type has not been
* specified to create an accessible object of a particular type.
*/
static void atk_no_op_object_factory_class_init (
AtkNoOpObjectFactoryClass *klass);
......
......@@ -35,6 +35,34 @@
#include "atk-enum-types.h"
#include "atkintl.h"
/**
* SECTION:atkobject
* @Short_description: The base object class for the Accessibility Toolkit API.
* @Title:AtkObject
*
* This class is the primary class for accessibility support via the
* Accessibility ToolKit (ATK). Objects which are instances of
* #AtkObject (or instances of AtkObject-derived types) are queried
* for properties which relate basic (and generic) properties of a UI
* component such as name and description. Instances of #AtkObject
* may also be queried as to whether they implement other ATK
* interfaces (e.g. #AtkAction, #AtkComponent, etc.), as appropriate
* to the role which a given UI component plays in a user interface.
*
* All UI components in an application which provide useful
* information or services to the user must provide corresponding
* #AtkObject instances on request (in GTK+, for instance, usually on
* a call to #gtk_widget_get_accessible ()), either via ATK support
* built into the toolkit for the widget class or ancestor class, or
* in the case of custom widgets, if the inherited #AtkObject
* implementation is insufficient, via instances of a new #AtkObject
* subclass.
*
* See also: #AtkObjectFactory, #AtkRegistry. (GTK+ users see also
* #GtkAccessible).
*
*/
static GPtrArray *role_names = NULL;
enum
......@@ -546,6 +574,17 @@ atk_object_class_init (AtkObjectClass *klass)
G_MAXINT,
0,
G_PARAM_READABLE));
/**
* AtkObject::children-changed:
* @atkobject: the object which received the signal.
* @arg1: The index of the added or removed child
* @arg2: A gpointer to the child AtkObject which was added or removed
*
* The signal "children-changed" is emitted when a child is added or
* removed form an object. It supports two details: "add" and
* "remove"
*/
atk_object_signals[CHILDREN_CHANGED] =
g_signal_new ("children_changed",
G_TYPE_FROM_CLASS (klass),
......@@ -576,6 +615,15 @@ atk_object_class_init (AtkObjectClass *klass)
g_cclosure_marshal_VOID__BOOLEAN,
G_TYPE_NONE,
1, G_TYPE_BOOLEAN);
/**
* AtkObject::property-change:
* @atkobject: the object which received the signal.
* @arg1: The new value of the property which changed.
*
* The signal "property-change" is emitted when an object's property
* value changes. The detail identifies the name of the property
* whose value has changed.
*/
atk_object_signals[PROPERTY_CHANGE] =
g_signal_new ("property_change",
G_TYPE_FROM_CLASS (klass),
......@@ -585,6 +633,17 @@ atk_object_class_init (AtkObjectClass *klass)
g_cclosure_marshal_VOID__POINTER,
G_TYPE_NONE, 1,
G_TYPE_POINTER);
/**
* AtkObject::state-change:
* @atkobject: the object which received the signal.
* @arg1: The name of the state which has changed
* @arg2: A boolean which indicates whether the state has been set or unset.
*
* The "state-change" signal is emitted when an object's state
* changes. The detail value identifies the state type which has
* changed.
*/
atk_object_signals[STATE_CHANGE] =
g_signal_new ("state_change",
G_TYPE_FROM_CLASS (klass),
......@@ -595,6 +654,14 @@ atk_object_class_init (AtkObjectClass *klass)
G_TYPE_NONE, 2,
G_TYPE_STRING,
G_TYPE_BOOLEAN);
/**
* AtkObject::visible-data-changed:
* @atkobject: the object which received the signal.
*
* The "visible-data-changed" signal is emitted when the visual
* appearance of the object changed.
*/
atk_object_signals[VISIBLE_DATA_CHANGED] =
g_signal_new ("visible_data_changed",
G_TYPE_FROM_CLASS (klass),
......@@ -603,6 +670,17 @@ atk_object_class_init (AtkObjectClass *klass)
(GSignalAccumulator) NULL, NULL,
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE, 0);
/**
* AtkObject::active-descendant-changed:
* @atkobject: the object which received the signal.
* @arg1: the newly focused object.
*
* The "active-descendant-changed" signal is emitted by an object
* which has the state ATK_STATE_MANAGES_DESCENDANTS when the focus
* object in the object changes. For instance, a table will emit the
* signal when the cell in the table which has focus changes.
*/
atk_object_signals[ACTIVE_DESCENDANT_CHANGED] =
g_signal_new ("active_descendant_changed",
G_TYPE_FROM_CLASS (klass),
......@@ -1564,7 +1642,7 @@ atk_role_for_name (const gchar *name)
*
* Adds a relationship of the specified type with the specified target.
*
* Returns TRUE if the relationship is added.
* Returns: TRUE if the relationship is added.
**/
gboolean
atk_object_add_relationship (AtkObject *object,
......@@ -1597,7 +1675,7 @@ atk_object_add_relationship (AtkObject *object,