sections tagged as incomplete.
+2006-03-21 Bill Haneman <bill.haneman@sun.com>
+
+ gtk-doc documentation fixes: ATK now has 100% API coverage
+ with no incomplete function/struct descriptions.
+
+ * atk/atkdocument.c: Edited docs to make gtk-doc happier.
+ * atk/atkimage.c: Ditto.
+ * atk/atkobject.c: Moved 'Deprecated' tag relative to 'Returns',
+ to make gtk-doc happier.
+ * atk/atkobject.h: Documented AtkPropertyValues.
+ * atk/atkrelationtypes: Documented the unused/invalid types
+ ATK_RELATION_TYPE_NULL and ATK_RELATION_TYPE_LAST_DEFINED.
+ * atk/atktext.h: Documented AtkTextBoundaryType.
+ * atk/atkutil.h: Documented AtkKeyEventStruct.
+ * docs/atksections.txt: Added missing function entries.
+ * docs/tmpl/atkhypertext.sgml: Added long description.
+ * docs/tmpl/atkregistry.sgml: Added long description.
+ * docs/tmpl/atkrelationset.sgml: Added long description.
+ * docs/tmpl/atkstreamablecontent.sgml: Added long description.
+
2006-03-21 Tor Lillqvist <tml@novell.com>
* atk/atkobject.c (get_atk_locale_dir): Fix fatal typo.
* Gets an AtkAttributeSet which describes document-wide
* attributes as name-value pairs.
*
+ * @Since: ATK 1.12
+ *
* Returns: An AtkAttributeSet containing the explicitly
* set name-value-pair attributes associated with this document
* as a whole.
- * @Since: ATK 1.12
**/
AtkAttributeSet *
atk_document_get_attributes (AtkDocument *document)
* @attribute_name: a character string representing the name of the attribute
* whose value is being queried.
*
+ * @Since: ATK 1.12
+ *
* Returns: a string value associated with the named attribute for this
* document, or NULL if a value for #attribute_name has not been specified
* for this document.
- * @Since: ATK 1.12
*/
G_CONST_RETURN gchar *
atk_document_get_attribute_value (AtkDocument *document,
* @document: a #GObject instance that implements AtkDocumentIface
* @attribute_name: a character string representing the name of the attribute
* whose value is being set.
- * @value: a string value to be associated with #attribute_name.
+ * @attribute_value: a string value to be associated with #attribute_name.
+ *
+ * @Since: ATK 1.12
*
* Returns: TRUE if #value is successfully associated with #attribute_name
* for this document, FALSE otherwise (e.g. if the document does not
* allow the attribute to be modified).
- * @Since ATK 1.12
*/
gboolean
atk_document_set_attribute_value (AtkDocument *document,
const gchar *attribute_name,
- const gchar *value)
+ const gchar *attribute_value)
{
AtkDocumentIface *iface;
if (iface->set_document_attribute)
{
- return (iface->set_document_attribute) (document, attribute_name, value);
+ return (iface->set_document_attribute) (document, attribute_name, attribute_value);
}
else
{
}
}
-/**
- * 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.
+/**
+ * atk_image_get_image_locale:
* @image: An #AtkImage
+ *
* @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.
+ *
*/
G_CONST_RETURN gchar*
atk_image_get_image_locale (AtkImage *image)
*
* Gets the layer of the accessible.
*
- * Returns: an #AtkLayer which is the layer of the accessible
- *
* @Deprecated: Use atk_component_get_layer instead.
+ *
+ * Returns: an #AtkLayer which is the layer of the accessible
**/
AtkLayer
atk_object_get_layer (AtkObject *accessible)
* Gets the zorder of the accessible. The value G_MININT will be returned
* if the layer of the accessible is not ATK_LAYER_MDI.
*
+ * @Deprecated: Use atk_component_get_mdi_zorder instead.
+ *
* Returns: a gint which is the zorder of the accessible, i.e. the depth at
* which the component is shown in relation to other components in the same
* container.
*
- * @Deprecated: Use atk_component_get_mdi_zorder instead.
**/
gint
atk_object_get_mdi_zorder (AtkObject *accessible)
/**
* atk_object_get_attributes:
- *
* @accessible: An #AtkObject.
+ *
* Get a list of properties applied to this object as a whole, as an #AtkAttributeSet consisting of
* name-value pairs. As such these attributes may be considered weakly-typed properties or annotations,
* as distinct from strongly-typed object data available via other get/set methods.
* Not all objects have explicit "name-value pair" #AtkAttributeSet properties.
+ *
* @Since ATK 1.12
+ *
+ * Returns: an #AtkAttributeSet consisting of all explicit properties/annotations applied to
+ * the object, or an empty set if the object has no name-value pair attributes assigned to it.
*/
AtkAttributeSet *
atk_object_get_attributes (AtkObject *accessible)
typedef struct _AtkRelationSet AtkRelationSet;
typedef struct _AtkStateSet AtkStateSet;
+/**
+ * AtkPropertyValues:
+ * @property_name: The name of the ATK property which is being presented or which has been changed.
+ * @old_value: The old property value, NULL; in some contexts this value is undefined (see note below).
+ * @new_value: The new value of the named property.
+ *
+ * @note: For most properties the old_value field of AtkPropertyValues will
+ * not contain a valid value.
+ *
+ * Currently, the only property for which old_value is used is
+ * accessible-state; for instance if there is a focus state the
+ * property change handler will be called for the object which lost the focus
+ * with the old_value containing an AtkState value corresponding to focused
+ * and the property change handler will be called for the object which
+ * received the focus with the new_value containing an AtkState value
+ * corresponding to focused.
+ *
+ **/
struct _AtkPropertyValues
{
const gchar *property_name;
/**
*AtkRelationType:
- *@ATK_RELATION_NULL:
+ *@ATK_RELATION_NULL: Not used, represens "no relationship" or an error condition.
*@ATK_RELATION_CONTROLLED_BY: Indicates an object controlled by one or more target objects.
*@ATK_RELATION_CONTROLLER_FOR: Indicates an object is an controller for one or more target objects.
*@ATK_RELATION_LABEL_FOR: Indicates an object is a label for one or more target objects.
* this object's content is visualy embedded in another object.
*@ATK_RELATION_POPUP_FOR: Indicates that an object is a popup for another object.
*@ATK_RELATION_PARENT_WINDOW_OF: Indicates that an object is a parent window of another object.
- *@ATK_RELATION_LAST_DEFINED:
+ *@ATK_RELATION_LAST_DEFINED: Not used, this value indicates the end of the enumeration.
*
*Describes the type of the relation
**/
/**
*AtkTextBoundary:
- *@ATK_TEXT_BOUNDARY_CHAR:
- *@ATK_TEXT_BOUNDARY_WORD_START:
- *@ATK_TEXT_BOUNDARY_WORD_END:
- *@ATK_TEXT_BOUNDARY_SENTENCE_START:
- *@ATK_TEXT_BOUNDARY_SENTENCE_END:
- *@ATK_TEXT_BOUNDARY_LINE_START:
- *@ATK_TEXT_BOUNDARY_LINE_END:
+ *@ATK_TEXT_BOUNDARY_CHAR: Boundary is the boundary between characters
+ * (including non-printing characters)
+ *@ATK_TEXT_BOUNDARY_WORD_START: Boundary is the start (i.e. first character) of a word.
+ *@ATK_TEXT_BOUNDARY_WORD_END: Boundary is the end (i.e. last character) of a word.
+ *@ATK_TEXT_BOUNDARY_SENTENCE_START: Boundary is the first character in a sentence.
+ *@ATK_TEXT_BOUNDARY_SENTENCE_END: Boundary is the last (terminal) character in a sentence;
+ * in languages which use "sentence stop" punctuation such as English, the boundary is thus the
+ * '.', '?', or similar terminal punctuation character.
+ *@ATK_TEXT_BOUNDARY_LINE_START: Boundary is the initial character of the content or a
+ * character immediately following a newline, linefeed, or return character.
+ *@ATK_TEXT_BOUNDARY_LINE_END: Boundary is the linefeed, or return character.
*
*Text boundary types used for specifying boundaries for regions of text
**/
typedef gint (*AtkKeySnoopFunc) (AtkKeyEventStruct *event,
gpointer func_data);
+/**
+ * AtkKeyEventStruct:
+ * @type: An AtkKeyEventType, generally one of ATK_KEY_EVENT_PRESS or ATK_KEY_EVENT_RELEASE
+ * @state: A bitmask representing the state of the modifier keys immediately after the event takes place.
+ * The meaning of the bits is currently defined to match the bitmask used by GDK in
+ * GdkEventType.state, see
+ * http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html#GdkEventKey
+ * @keyval: A guint representing a keysym value corresponding to those used by GDK and X11: see
+ * /usr/X11/include/keysymdef.h.
+ * @length: The length of member #string.
+ * @string: A string containing one of the following: either a string approximating the text that would
+ * result from this keypress, if the key is a control or graphic character, or a symbolic name for this keypress.
+ * Alphanumeric and printable keys will have the symbolic key name in this string member, for instance "A". "0",
+ * "semicolon", "aacute". Keypad keys have the prefix "KP".
+ * @keycode: The raw hardware code that generated the key event. This field is raraly useful.
+ * @timestamp: A timestamp in milliseconds indicating when the event occurred.
+ * These timestamps are relative to a starting point which should be considered arbitrary,
+ * and only used to compare the dispatch times of events to one another.
+ *
+ * Encapsulates information about a key event.
+ **/
struct _AtkKeyEventStruct {
gint type;
guint state;
atk_component_set_extents
atk_component_set_position
atk_component_set_size
+atk_component_get_alpha
<SUBSECTION Standard>
AtkComponentIface
ATK_COMPONENT
AtkDocument
atk_document_get_document_type
atk_document_get_document
+atk_document_get_attribute_value
+atk_document_set_attribute_value
+atk_document_get_attributes
+atk_document_get_locale
<SUBSECTION Standard>
AtkDocumentIface
ATK_DOCUMENT
atk_image_get_image_description
atk_image_set_image_description
atk_image_get_image_size
+atk_image_get_image_locale
<SUBSECTION Standard>
AtkImageIface
ATK_IMAGE
atk_object_initialize
atk_object_add_relationship
atk_object_remove_relationship
+atk_object_get_attributes
atk_role_get_name
atk_role_get_localized_name
atk_role_for_name
@Returns:
+<!-- ##### FUNCTION atk_component_get_alpha ##### -->
+<para>
+
+</para>
+
+@component:
+@Returns:
+
+
@Returns:
+<!-- ##### FUNCTION atk_document_get_attribute_value ##### -->
+<para>
+
+</para>
+
+@document:
+@attribute_name:
+@Returns:
+
+
+<!-- ##### FUNCTION atk_document_set_attribute_value ##### -->
+<para>
+
+</para>
+
+@document:
+@attribute_name:
+@attribute_value:
+@Returns:
+
+
+<!-- ##### FUNCTION atk_document_get_attributes ##### -->
+<para>
+
+</para>
+
+@document:
+@Returns:
+
+
+<!-- ##### FUNCTION atk_document_get_locale ##### -->
+<para>
+
+</para>
+
+@document:
+@Returns:
+
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+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.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+AtkHyperlink
</para>
<!-- ##### SECTION Stability_Level ##### -->
@height:
+<!-- ##### FUNCTION atk_image_get_image_locale ##### -->
+<para>
+
+</para>
+
+@image:
+@Returns:
+
+
</para>
-@data:
-@Returns:
+@data: a gpointer to parameter data.
+@Returns: Nothing useful, this is only a dummy prototype.
<!-- ##### USER_FUNCTION AtkPropertyChangeHandler ##### -->
@Returns:
+<!-- ##### FUNCTION atk_object_get_attributes ##### -->
+<para>
+
+</para>
+
+@accessible:
+@Returns:
+
+
<!-- ##### FUNCTION atk_role_get_name ##### -->
<para>
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The AtkRegistry is normally used to create appropriate ATK "peers" for user
+interface components. Application developers usually need only interact with
+the AtkRegistry by associating appropriate ATK implementation classes with
+GObject classes via the atk_registry_set_factory_type call, passing the
+appropriate GType for application custom widget classes.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The AtkRelationSet held by an object establishes its relationships with
+objects beyond the normal "parent/child" hierarchical relationships that all
+user interface objects have. AtkRelationSets establish whether objects are
+labelled or controlled by other components, share group membership with other
+components (for instance within a radio-button group), or share content which
+"flows" between them, among other types of possible relationships.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+An interface whereby an object allows its backing content to be streamed to
+clients. Typical implementors would be images or icons, HTML content, or
+multimedia display/rendering widgets.
+</para>
+<para>
+Negotiation of content type is allowed. Clients may examine the backing data
+and transform, convert, or parse the content in order to present it in an alternate form to end-users.
+</para>
+<para>
+The AtkStreamableContent 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 AtkStreamableContent interface can help
+address performance issues. Unlike most ATK 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.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT AtkUtil ##### -->
<para>
-
+The AtkUtil struct does not contain any fields.
</para>
projects / platform / upstream / atk.git / commitdiff