From 1f3843d72458da51ffc10aa55cfb004c0b8d8f6a Mon Sep 17 00:00:00 2001 From: billh Date: Thu, 17 Aug 2006 16:44:33 +0000 Subject: [PATCH] Documentation fixed for bug #351657. Fixed the cspi return value demarshalling for AccessibleDocument_getAttributes. git-svn-id: http://svn.gnome.org/svn/at-spi/trunk@850 e2bd861d-eb25-0410-b326-f6ed22b6b98c --- ChangeLog | 30 +++++++++++++++++++ cspi/spi-private.h | 2 +- cspi/spi.h | 13 ++++++-- cspi/spi_accessible.c | 4 +-- cspi/spi_document.c | 42 ++++++++++++++++++++++++-- cspi/spi_streamablecontent.c | 2 +- cspi/spi_table.c | 44 +++++++++++++++++++++++++++- cspi/spi_text.c | 4 +-- docs/reference/cspi/at-spi-cspi-docs.sgml | 4 +++ docs/reference/cspi/at-spi-cspi-sections.txt | 24 +++++++++++++++ docs/reference/cspi/tmpl/spi_accessible.sgml | 18 ++++++++++++ docs/reference/cspi/tmpl/spi_event.sgml | 2 -- docs/reference/cspi/tmpl/spi_main.sgml | 14 ++++++--- docs/reference/cspi/tmpl/spi_registry.sgml | 2 -- docs/reference/cspi/tmpl/spi_selection.sgml | 10 +++++++ docs/reference/cspi/tmpl/spi_table.sgml | 15 ++++++++++ docs/reference/cspi/tmpl/spi_text.sgml | 22 ++++++++++++++ docs/reference/cspi/tmpl/spi_value.sgml | 9 ++++++ test/Makefile.am | 5 ++++ test/keysynth-test.c | 2 +- 20 files changed, 248 insertions(+), 20 deletions(-) diff --git a/ChangeLog b/ChangeLog index 91e9a70..ce77424 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,33 @@ +2006-08-17 Bill Haneman + + * cspi/spi-private.h, cspi/spi_accessible.c: + (_cspi_attribute_set_from_sequence): Renamed from + cspi_attribute_set_from_sequence, to suppress export. + + * cspi/spi.h: + (SPIRelationType): Fixed typo in PARENT_WINDOW_OF + inline docs, which was keeping the doc from appearing. + (SPIExceptionHandler): Doc this. + + * cspi/spi_document.c: + Added inline gtk-docs cut-n-pasted from the doxygen + docs in the corresponding IDL files. + (AccessibleDocument_getAttributes): Fix the retval here. + + * cspi/spi_streamablecontent.c: + Fixed some 'Since' tags that were accidentally doxygen-style. + + * cspi/spi_table.c: + (AccessibleTable_getRowColumnExtentsAtIndex): Cut and pasted + docs from the IDL file. + + * docs/reference/cspi/at-spi-cspi-docs.sgml: + Added entities for Document and StreamableContent interfaces. + + * docs/reference/cspi/at-spi-cspi-sections.txt: + Added some docs that were present inline but not getting + exported to HTML. + 2006-07-31 Bill Haneman * libspi/text.c: diff --git a/cspi/spi-private.h b/cspi/spi-private.h index 6fd19eb..1ea32bf 100644 --- a/cspi/spi-private.h +++ b/cspi/spi-private.h @@ -84,7 +84,7 @@ void cspi_streams_close_all (void); gboolean cspi_exception_throw (CORBA_Environment *ev, char *desc_prefix); AccessibleAttributeSet - *cspi_attribute_set_from_sequence (const Accessibility_AttributeSet *seq); + *_cspi_attribute_set_from_sequence (const Accessibility_AttributeSet *seq); #define cspi_return_if_fail(val) \ if (!(val)) \ return diff --git a/cspi/spi.h b/cspi/spi.h index 124b328..955977c 100644 --- a/cspi/spi.h +++ b/cspi/spi.h @@ -115,7 +115,8 @@ more target objects. * another's content. *@SPI_RELATION_EMBEDDED_BY: Inverse of %SPI_RELATION_EMBEDS, indicates that * this object's content is visualy embedded in another object. - *@SPI_RELATION_POPUP_FOR: Indicates that an object is a popup for another objec *@SPI_RELATION_PARENT_WINDOW_OF: Indicates that an object is a parent window of another object. + *@SPI_RELATION_POPUP_FOR: Indicates that an object is a popup for another object. + *@SPI_RELATION_PARENT_WINDOW_OF: Indicates that an object is a parent window of another object. *@SPI_RELATION_DESCRIBED_BY: Indicates that another object provides descriptive information about this object; more verbose than %SPI_RELATION_LABELLED_BY. *@SPI_RELATION_DESCRIPTION_FOR: Indicates that an object provides descriptive information about another object; more verbose than %SPI_RELATION_LABEL_FOR. *@SPI_RELATION_LAST_DEFINED: Do not use, this is an implementation detail used @@ -244,7 +245,15 @@ typedef enum **/ typedef struct _SPIException SPIException; - +/** + * SPIExceptionHandler: + * @err: points to the SPIException opaque object. + * @is_fatal: indicates whether the exception is a fatal error or not. + * + * A function type for functions to be called when exceptions occur. + * + * Returns + **/ typedef SPIBoolean (*SPIExceptionHandler) (SPIException *err, SPIBoolean is_fatal); /** diff --git a/cspi/spi_accessible.c b/cspi/spi_accessible.c index bd61aff..c59ba1c 100644 --- a/cspi/spi_accessible.c +++ b/cspi/spi_accessible.c @@ -243,7 +243,7 @@ cspi_role_from_spi_role (Accessibility_Role role) } AccessibleAttributeSet * -cspi_attribute_set_from_sequence (const Accessibility_AttributeSet *seq) +_cspi_attribute_set_from_sequence (const Accessibility_AttributeSet *seq) { AccessibleAttributeSet *set = g_new0 (AccessibleAttributeSet, 1); int i; @@ -627,7 +627,7 @@ Accessible_getAttributes (Accessible *obj) CSPI_OBJREF (obj), cspi_ev ()); cspi_return_val_if_ev ("getAttributes", NULL); - retval = cspi_attribute_set_from_sequence (corba_seq); + retval = _cspi_attribute_set_from_sequence (corba_seq); CORBA_free (corba_seq); return retval; diff --git a/cspi/spi_document.c b/cspi/spi_document.c index 07f449b..025dcb5 100644 --- a/cspi/spi_document.c +++ b/cspi/spi_document.c @@ -24,7 +24,6 @@ #include #include - /** * AccessibleDocument_ref: * @obj: a pointer to the #AccessibleDocument object on which to operate. @@ -51,6 +50,15 @@ AccessibleDocument_unref (AccessibleDocument *obj) } +/** + * AccessibleDocument_getLocale: + * @obj: a pointer to the #Accessible object on which to operate. + * + * Gets the locale associated with the document's content. + * e.g. the locale for LOCALE_TYPE_MESSAGES. + * + * Returns: a string compliant with the POSIX standard for locale description. + **/ char * AccessibleDocument_getLocale (AccessibleDocument *obj) { @@ -67,6 +75,18 @@ AccessibleDocument_getLocale (AccessibleDocument *obj) } +/** + * AccessibleDocument_getAttributeValue: + * @obj: a pointer to the #Accessible object on which to operate. + * @attribute: a string indicating the name of a specific attribute + * + * Gets the value of a single attribute, if specified for the document as a whole. + * + * (name-value pair) being queried. + * + * Returns a string corresponding to the value of the specified attribute, or + * an empty string if the attribute is unspecified for the object. + **/ char * AccessibleDocument_getAttributeValue (AccessibleDocument *obj, char *attribute) @@ -87,17 +107,35 @@ AccessibleDocument_getAttributeValue (AccessibleDocument *obj, } +/** + * AccessibleDocument_getAttributes: + * @obj: a pointer to the #Accessible object on which to operate. + * + * Gets all attributes specified for a document as a whole. + * + * For attributes which change within + * the document content, see Accessibility::Text::getAttributes instead. + * + * Returns an ::AttributeSet containing the attributes of the document, + * as name-value pairs. + * + * Since AT-SPI 1.8.0 + **/ AccessibleAttributeSet * AccessibleDocument_getAttributes (AccessibleDocument *obj){ AccessibleAttributeSet *retval; + Accessibility_AttributeSet *corba_seq; cspi_return_val_if_fail (obj != NULL, NULL); - retval = Accessibility_Document_getAttributes (CSPI_OBJREF (obj), + corba_seq = Accessibility_Document_getAttributes (CSPI_OBJREF (obj), cspi_ev ()); cspi_return_val_if_ev ("getAttributes", NULL); + retval = _cspi_attribute_set_from_sequence (corba_seq); + CORBA_free (corba_seq); + return retval; } diff --git a/cspi/spi_streamablecontent.c b/cspi/spi_streamablecontent.c index 11fce9c..d79aa64 100644 --- a/cspi/spi_streamablecontent.c +++ b/cspi/spi_streamablecontent.c @@ -232,7 +232,7 @@ AccessibleStreamableContent_getContentTypes (AccessibleStreamableContent *obj) * Free the memory associated with a call to #AccessibleStreamableContent_getContentTypes, once * the result has been used. * -* @Since: AT-SPI 1.4 +* Since: AT-SPI 1.4 **/ void AccessibleStreamableContent_freeContentTypesList (AccessibleStreamableContent *obj, diff --git a/cspi/spi_table.c b/cspi/spi_table.c index a42f4bc..759418c 100644 --- a/cspi/spi_table.c +++ b/cspi/spi_table.c @@ -717,7 +717,49 @@ AccessibleTable_removeColumnSelection (AccessibleTable *obj, return retval; } - +/** + * AccessibleTable_getRowColumnExtentsAtIndex: + * @obj: a pointer to the #AccessibleTable implementor on which to operate. + * @index: the index of the Table child whose row/column + * extents are requested. + * @row: back-filled with the first table row associated with + * the cell with child index \c index. + * @col: back-filled with the first table column associated + * with the cell with child index \c index. + * @row_extents: back-filled with the number of table rows + * across which child \c i extends. + * @col_extents: back-filled with the number of table columns + * across which child \c i extends. + * @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. + * + * 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. + * + * 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 + * + * retval = table::getRowColumnExtentsAtIndex (6, row, col, + * row_extents, + * col_extents, + * is_selected); + * + * will return True, and after the call + * row, col, row_extents, col_extents, + * and \c is_selected will contain 2, 5, 1, 2, and + * True, respectively. + * + * Returns: \c True if the index is associated with a valid table + * cell, \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 + **/ SPIBoolean AccessibleTable_getRowColumnExtentsAtIndex (AccessibleTable *obj, long int index, long int *row, long int *col, diff --git a/cspi/spi_text.c b/cspi/spi_text.c index b3ee577..13a9be4 100644 --- a/cspi/spi_text.c +++ b/cspi/spi_text.c @@ -964,7 +964,7 @@ AccessibleText_getAttributeRun (AccessibleText *obj, *endOffset = retEndOffset; } - retval = cspi_attribute_set_from_sequence (attributes); + retval = _cspi_attribute_set_from_sequence (attributes); return retval; @@ -999,7 +999,7 @@ AccessibleText_getDefaultAttributeSet (AccessibleText *obj){ attributes = Accessibility_Text_getDefaultAttributeSet (CSPI_OBJREF (obj), cspi_ev ()); cspi_return_val_if_ev ("getDefaultAttributeSet", NULL); - retval = cspi_attribute_set_from_sequence (attributes); + retval = _cspi_attribute_set_from_sequence (attributes); retval = NULL; return retval; } diff --git a/docs/reference/cspi/at-spi-cspi-docs.sgml b/docs/reference/cspi/at-spi-cspi-docs.sgml index fb96e1f..377e49b 100644 --- a/docs/reference/cspi/at-spi-cspi-docs.sgml +++ b/docs/reference/cspi/at-spi-cspi-docs.sgml @@ -8,10 +8,12 @@ + + @@ -44,10 +46,12 @@ Subinterface Methods &at-spi-spi-action; &at-spi-spi-component; + &at-spi-spi-document; &at-spi-spi-editabletext; &at-spi-spi-hypertext; &at-spi-spi-image; &at-spi-spi-selection; + &at-spi-spi-streamable-content; &at-spi-spi-table; &at-spi-spi-text; &at-spi-spi-value; diff --git a/docs/reference/cspi/at-spi-cspi-sections.txt b/docs/reference/cspi/at-spi-cspi-sections.txt index 6e59950..4987a7f 100644 --- a/docs/reference/cspi/at-spi-cspi-sections.txt +++ b/docs/reference/cspi/at-spi-cspi-sections.txt @@ -16,6 +16,7 @@ SPIException_getSourceType SPIException SPIExceptionCode SPIExceptionType +SPIExceptionHandler SPIBoolean SPIRect SPI_freeRect @@ -122,6 +123,7 @@ Accessible_getLocalizedRoleName Accessible_isAction Accessible_isApplication Accessible_isComponent +Accessible_isDocument Accessible_isEditableText Accessible_isHypertext Accessible_isImage @@ -133,6 +135,7 @@ Accessible_isValue Accessible_getAction Accessible_getApplication Accessible_getComponent +Accessible_getDocument Accessible_getEditableText Accessible_getHypertext Accessible_getImage @@ -164,13 +167,17 @@ cspi_return_val_if_fail cspi_return_if_ev cspi_return_val_if_ev cspi_check_ev +cspi_peek_ev cspi_dup_ref cspi_release_unref cspi_exception_get_text +cspi_exception_throw cspi_init cspi_ping cspi_main cspi_main_quit +cspi_role_from_spi_role +cspi_streams_close_all cspi_event_listener_get_type cspi_event_listener_new cspi_event_listener_get_corba @@ -247,6 +254,16 @@ AccessibleComponent_getAlpha
+spi_document +AccessibleDocument Interface +AccessibleDocument_ref +AccessibleDocument_unref +AccessibleDocument_getAttributeValue +AccessibleDocument_getAttributes +AccessibleDocument_getLocale +
+ +
spi_editabletext AccessibleEditableText Interface AccessibleEditableText_ref @@ -292,6 +309,7 @@ AccessibleSelection_getSelectedChild AccessibleSelection_selectChild AccessibleSelection_isChildSelected AccessibleSelection_deselectSelectedChild +AccessibleSelection_deselectChild AccessibleSelection_clearSelection AccessibleSelection_selectAll
@@ -299,6 +317,8 @@ AccessibleSelection_selectAll
spi_streamable_content AccessibleStreamableContent Interface +AccessibleStreamableContentSeekType +AccessibleStreamableContent_freeContentTypesList AccessibleStreamableContent_ref AccessibleStreamableContent_unref AccessibleStreamableContent_getContentTypes @@ -325,6 +345,7 @@ AccessibleTable_getNColumns AccessibleTable_getNRows AccessibleTable_getNSelectedColumns AccessibleTable_getNSelectedRows +AccessibleTable_getRowColumnExtentsAtIndex AccessibleTable_getRowAtIndex AccessibleTable_getRowDescription AccessibleTable_getRowExtentAt @@ -367,6 +388,8 @@ AccessibleText_setCaretOffset AccessibleText_setSelection AccessibleText_getCharacterAtOffset AccessibleText_getDefaultAttributes +AccessibleText_getAttributeRun +AccessibleText_getDefaultAttributeSet AccessibleTextRange_freeRanges
@@ -379,6 +402,7 @@ AccessibleValue_getCurrentValue AccessibleValue_getMaximumValue AccessibleValue_getMinimumValue AccessibleValue_setCurrentValue +AccessibleValue_getMinimumIncrement
diff --git a/docs/reference/cspi/tmpl/spi_accessible.sgml b/docs/reference/cspi/tmpl/spi_accessible.sgml index 454d8e1..5de4673 100644 --- a/docs/reference/cspi/tmpl/spi_accessible.sgml +++ b/docs/reference/cspi/tmpl/spi_accessible.sgml @@ -196,6 +196,15 @@ object corresponding to an user interface element. @Returns: + + + + + +@obj: +@Returns: + + @@ -295,6 +304,15 @@ object corresponding to an user interface element. @Returns: + + + + + +@obj: +@Returns: + + diff --git a/docs/reference/cspi/tmpl/spi_event.sgml b/docs/reference/cspi/tmpl/spi_event.sgml index 8ba9078..ae70925 100644 --- a/docs/reference/cspi/tmpl/spi_event.sgml +++ b/docs/reference/cspi/tmpl/spi_event.sgml @@ -24,8 +24,6 @@ AccessibleEvent is a struct used to encapsulate event information. @type: @source: -@detail1: -@detail2: diff --git a/docs/reference/cspi/tmpl/spi_main.sgml b/docs/reference/cspi/tmpl/spi_main.sgml index 3b1b453..5683a09 100644 --- a/docs/reference/cspi/tmpl/spi_main.sgml +++ b/docs/reference/cspi/tmpl/spi_main.sgml @@ -140,15 +140,21 @@ SPI main loop and initialization @SPI_EXCEPTION_SOURCE_REGISTRY: @SPI_EXCEPTION_SOURCE_DEVICE: + + + + + +@err: +@is_fatal: +@Returns: + + -@x: -@y: -@width: -@height: diff --git a/docs/reference/cspi/tmpl/spi_registry.sgml b/docs/reference/cspi/tmpl/spi_registry.sgml index 63fd0ac..458a961 100644 --- a/docs/reference/cspi/tmpl/spi_registry.sgml +++ b/docs/reference/cspi/tmpl/spi_registry.sgml @@ -259,9 +259,7 @@ This is a synonym for AccessibleDeviceEvent. AccessibleDeviceEvent is a struct which encapsulates a device event. -@keyID: @keystring: -@timestamp: @type: @is_text: diff --git a/docs/reference/cspi/tmpl/spi_selection.sgml b/docs/reference/cspi/tmpl/spi_selection.sgml index f19caaa..39822f5 100644 --- a/docs/reference/cspi/tmpl/spi_selection.sgml +++ b/docs/reference/cspi/tmpl/spi_selection.sgml @@ -82,6 +82,16 @@ AccessibleSelection Interface @Returns: + + + + + +@obj: +@childIndex: +@Returns: + + diff --git a/docs/reference/cspi/tmpl/spi_table.sgml b/docs/reference/cspi/tmpl/spi_table.sgml index b3f5ecf..cafd3dd 100644 --- a/docs/reference/cspi/tmpl/spi_table.sgml +++ b/docs/reference/cspi/tmpl/spi_table.sgml @@ -141,6 +141,21 @@ AccessibleTable Interface @Returns: + + + + + +@obj: +@index: +@row: +@col: +@row_extents: +@col_extents: +@is_selected: +@Returns: + + diff --git a/docs/reference/cspi/tmpl/spi_text.sgml b/docs/reference/cspi/tmpl/spi_text.sgml index a4fa387..9e151cf 100644 --- a/docs/reference/cspi/tmpl/spi_text.sgml +++ b/docs/reference/cspi/tmpl/spi_text.sgml @@ -277,6 +277,28 @@ AccessibleText Interface @Returns: + + + + + +@obj: +@offset: +@startOffset: +@endOffset: +@includeDefaults: +@Returns: + + + + + + + +@obj: +@Returns: + + diff --git a/docs/reference/cspi/tmpl/spi_value.sgml b/docs/reference/cspi/tmpl/spi_value.sgml index 6be0fb6..4c0a4ae 100644 --- a/docs/reference/cspi/tmpl/spi_value.sgml +++ b/docs/reference/cspi/tmpl/spi_value.sgml @@ -77,3 +77,12 @@ be programmatically set, if the implementor's state does not include READONLY. @Returns: + + + + + +@obj: +@Returns: + + diff --git a/test/Makefile.am b/test/Makefile.am index d2ef5e1..d01d290 100644 --- a/test/Makefile.am +++ b/test/Makefile.am @@ -40,3 +40,8 @@ INCLUDES = -I$(top_srcdir) \ LDADD = ../libspi/libspi.la ../cspi/libcspi.la ../login-helper/libloginhelper.la $(TESTS_LIBS) $(X_LIBS) $(XINPUT_LIBS) TESTS = test-simple + +TESTS_ENVIRONMENT = \ + LD_LIBRARY_PATH=$(top_builddir)/libspi/.libs/:$(top_builddir)/cspi/.libs/ \ + PATH=$(top_builddir)/registryd/.libs + diff --git a/test/keysynth-test.c b/test/keysynth-test.c index 78d59bc..22adf46 100644 --- a/test/keysynth-test.c +++ b/test/keysynth-test.c @@ -42,7 +42,7 @@ static TextTest text[] = { {65, NULL, SPI_KEY_PRESSRELEASE}, {64, NULL, SPI_KEY_SYM}, {0, "--hello!", SPI_KEY_STRING}, - {0, "StudlyCaps", SPI_KEY_STRING} + {0, "StudlyCaps!", SPI_KEY_STRING} }; static void -- 2.7.4