From 2dab56e91e68dfc14e6bc0a8e45a664e4a323fc8 Mon Sep 17 00:00:00 2001
From: Julian Smart <julian@anthemion.co.uk>
Date: Wed, 16 Apr 2003 09:40:09 +0000
Subject: [PATCH] Added wxAccessible documentation

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@20235 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/latex/wx/accessible.tex | 428 +++++++++++++++++++++++++++++++++++
 docs/latex/wx/classes.tex    |   1 +
 docs/latex/wx/window.tex     |  17 ++
 3 files changed, 446 insertions(+)
 create mode 100644 docs/latex/wx/accessible.tex

diff --git a/docs/latex/wx/accessible.tex b/docs/latex/wx/accessible.tex
new file mode 100644
index 0000000000..c0935232f0
--- /dev/null
+++ b/docs/latex/wx/accessible.tex
@@ -0,0 +1,428 @@
+%
+% automatically generated by HelpGen $Revision$ from
+% access.h at 11/Apr/03 12:31:15
+%
+
+\section{\class{wxAccessible}}\label{wxaccessible}
+
+The wxAccessible class allows wxWindows applications, and
+wxWindows itself, to return extended information about user interface elements
+to client applications such as screen readers. This is the
+main way in which wxWindows implements accessibility features.
+
+At present, only Microsoft Active Accessibility is supported
+by this class.
+
+To use this class, derive from wxAccessible, implement appropriate
+functions, and associate an object of the class with a
+window using \helpref{wxWindow::SetAccessible}{wxwindowsetaccessible}.
+
+All functions return an indication of success, failure, or not implemented
+using values of the wxAccStatus enum type.
+
+If you return wxACC\_NOT\_IMPLEMENTED from any functioon, the system will try to
+implement the appropriate functionality. However this will not work with
+all functions.
+
+Most functions work with an {\it object id}, which can be zero to refer to
+'this' UI element, or greater than zero to refer to the nth child element.
+This allows you to specify elements that don't have a corresponding wxWindow or
+wxAccessible; for example, the sash of a splitter window.
+
+For details on the semantics of functions and types, please refer to the
+Microsoft Active Accessibility 1.2 documentation.
+
+This class is compiled into wxWindows only if the wxUSE\_ACCESSIBILITY setup
+symbol is set to 1.
+
+\wxheading{Derived from}
+
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/access.h>
+
+\wxheading{Data structures}
+
+Functions return a wxAccStatus error code, which
+may be one of the following:
+
+{\small \begin{verbatim}
+typedef enum
+{
+    wxACC\_FAIL,             // The function failed
+    wxACC\_FALSE,            // The function returned false
+    wxACC\_OK,               // The function completed successfully
+    wxACC\_NOT\_IMPLEMENTED, // The function is not implemented
+    wxACC\_NOT\_SUPPORTED    // The function is not supported
+} wxAccStatus
+\end{verbatim}}
+
+Directions of navigation are represented by
+the following:
+
+{\small \begin{verbatim}
+typedef enum
+{
+    wxNAVDIR\_DOWN,
+    wxNAVDIR\_FIRSTCHILD,
+    wxNAVDIR\_LASTCHILD,
+    wxNAVDIR\_LEFT,
+    wxNAVDIR\_NEXT,
+    wxNAVDIR\_PREVIOUS,
+    wxNAVDIR\_RIGHT,
+    wxNAVDIR\_UP
+} wxNavDir
+\end{verbatim}}
+
+The role of a user interface element is represented
+by the following type:
+
+{\small \begin{verbatim}
+typedef enum {  
+    wxROLE\_NONE,
+    wxROLE\_SYSTEM\_ALERT,
+    wxROLE\_SYSTEM\_ANIMATION,
+    wxROLE\_SYSTEM\_APPLICATION,
+    wxROLE\_SYSTEM\_BORDER,
+    wxROLE\_SYSTEM\_BUTTONDROPDOWN,
+    wxROLE\_SYSTEM\_BUTTONDROPDOWNGRID,
+    wxROLE\_SYSTEM\_BUTTONMENU,
+    wxROLE\_SYSTEM\_CARET,
+    wxROLE\_SYSTEM\_CELL,
+    wxROLE\_SYSTEM\_CHARACTER,
+    wxROLE\_SYSTEM\_CHART,
+    wxROLE\_SYSTEM\_CHECKBUTTON,
+    wxROLE\_SYSTEM\_CLIENT,
+    wxROLE\_SYSTEM\_CLOCK,
+    wxROLE\_SYSTEM\_COLUMN,
+    wxROLE\_SYSTEM\_COLUMNHEADER,
+    wxROLE\_SYSTEM\_COMBOBOX,
+    wxROLE\_SYSTEM\_CURSOR,
+    wxROLE\_SYSTEM\_DIAGRAM,
+    wxROLE\_SYSTEM\_DIAL,
+    wxROLE\_SYSTEM\_DIALOG,
+    wxROLE\_SYSTEM\_DOCUMENT,
+    wxROLE\_SYSTEM\_DROPLIST,
+    wxROLE\_SYSTEM\_EQUATION,
+    wxROLE\_SYSTEM\_GRAPHIC,
+    wxROLE\_SYSTEM\_GRIP,
+    wxROLE\_SYSTEM\_GROUPING,
+    wxROLE\_SYSTEM\_HELPBALLOON,
+    wxROLE\_SYSTEM\_HOTKEYFIELD,
+    wxROLE\_SYSTEM\_INDICATOR,
+    wxROLE\_SYSTEM\_LINK,
+    wxROLE\_SYSTEM\_LIST,
+    wxROLE\_SYSTEM\_LISTITEM,
+    wxROLE\_SYSTEM\_MENUBAR,
+    wxROLE\_SYSTEM\_MENUITEM,
+    wxROLE\_SYSTEM\_MENUPOPUP,
+    wxROLE\_SYSTEM\_OUTLINE,
+    wxROLE\_SYSTEM\_OUTLINEITEM,
+    wxROLE\_SYSTEM\_PAGETAB,
+    wxROLE\_SYSTEM\_PAGETABLIST,
+    wxROLE\_SYSTEM\_PANE,
+    wxROLE\_SYSTEM\_PROGRESSBAR,
+    wxROLE\_SYSTEM\_PROPERTYPAGE,
+    wxROLE\_SYSTEM\_PUSHBUTTON,
+    wxROLE\_SYSTEM\_RADIOBUTTON,
+    wxROLE\_SYSTEM\_ROW,
+    wxROLE\_SYSTEM\_ROWHEADER,
+    wxROLE\_SYSTEM\_SCROLLBAR,
+    wxROLE\_SYSTEM\_SEPARATOR,
+    wxROLE\_SYSTEM\_SLIDER,
+    wxROLE\_SYSTEM\_SOUND,
+    wxROLE\_SYSTEM\_SPINBUTTON,
+    wxROLE\_SYSTEM\_STATICTEXT,
+    wxROLE\_SYSTEM\_STATUSBAR,
+    wxROLE\_SYSTEM\_TABLE,
+    wxROLE\_SYSTEM\_TEXT,
+    wxROLE\_SYSTEM\_TITLEBAR,
+    wxROLE\_SYSTEM\_TOOLBAR,
+    wxROLE\_SYSTEM\_TOOLTIP,
+    wxROLE\_SYSTEM\_WHITESPACE,
+    wxROLE\_SYSTEM\_WINDOW
+} wxAccRole
+\end{verbatim}}
+
+Objects are represented by the following type:
+
+{\small \begin{verbatim}
+typedef enum {
+    wxOBJID\_WINDOW =    0x00000000,
+    wxOBJID\_SYSMENU =   0xFFFFFFFF,
+    wxOBJID\_TITLEBAR =  0xFFFFFFFE,
+    wxOBJID\_MENU =      0xFFFFFFFD,
+    wxOBJID\_CLIENT =    0xFFFFFFFC,
+    wxOBJID\_VSCROLL =   0xFFFFFFFB,
+    wxOBJID\_HSCROLL =   0xFFFFFFFA,
+    wxOBJID\_SIZEGRIP =  0xFFFFFFF9,
+    wxOBJID\_CARET =     0xFFFFFFF8,
+    wxOBJID\_CURSOR =    0xFFFFFFF7,
+    wxOBJID\_ALERT =     0xFFFFFFF6,
+    wxOBJID\_SOUND =     0xFFFFFFF5
+} wxAccObject
+\end{verbatim}}
+
+Selection actions are identified by
+this type:
+
+{\small \begin{verbatim}
+typedef enum
+{
+    wxACC\_SEL\_NONE            = 0,
+    wxACC\_SEL\_TAKEFOCUS       = 1,
+    wxACC\_SEL\_TAKESELECTION   = 2,
+    wxACC\_SEL\_EXTENDSELECTION = 4,
+    wxACC\_SEL\_ADDSELECTION    = 8,
+    wxACC\_SEL\_REMOVESELECTION = 16
+} wxAccSelectionFlags
+\end{verbatim}}
+
+States are represented by the following:
+
+{\small \begin{verbatim}
+#define wxACC\_STATE\_SYSTEM\_ALERT\_HIGH       0x00000001
+#define wxACC\_STATE\_SYSTEM\_ALERT\_MEDIUM     0x00000002
+#define wxACC\_STATE\_SYSTEM\_ALERT\_LOW        0x00000004
+#define wxACC\_STATE\_SYSTEM\_ANIMATED         0x00000008
+#define wxACC\_STATE\_SYSTEM\_BUSY             0x00000010
+#define wxACC\_STATE\_SYSTEM\_CHECKED          0x00000020
+#define wxACC\_STATE\_SYSTEM\_COLLAPSED        0x00000040
+#define wxACC\_STATE\_SYSTEM\_DEFAULT          0x00000080
+#define wxACC\_STATE\_SYSTEM\_EXPANDED         0x00000100
+#define wxACC\_STATE\_SYSTEM\_EXTSELECTABLE    0x00000200
+#define wxACC\_STATE\_SYSTEM\_FLOATING         0x00000400
+#define wxACC\_STATE\_SYSTEM\_FOCUSABLE        0x00000800
+#define wxACC\_STATE\_SYSTEM\_FOCUSED          0x00001000
+#define wxACC\_STATE\_SYSTEM\_HOTTRACKED       0x00002000
+#define wxACC\_STATE\_SYSTEM\_INVISIBLE        0x00004000
+#define wxACC\_STATE\_SYSTEM\_MARQUEED         0x00008000
+#define wxACC\_STATE\_SYSTEM\_MIXED            0x00010000
+#define wxACC\_STATE\_SYSTEM\_MULTISELECTABLE  0x00020000
+#define wxACC\_STATE\_SYSTEM\_OFFSCREEN        0x00040000
+#define wxACC\_STATE\_SYSTEM\_PRESSED          0x00080000
+#define wxACC\_STATE\_SYSTEM\_PROTECTED        0x00100000
+#define wxACC\_STATE\_SYSTEM\_READONLY         0x00200000
+#define wxACC\_STATE\_SYSTEM\_SELECTABLE       0x00400000
+#define wxACC\_STATE\_SYSTEM\_SELECTED         0x00800000
+#define wxACC\_STATE\_SYSTEM\_SELFVOICING      0x01000000
+#define wxACC\_STATE\_SYSTEM\_UNAVAILABLE      0x02000000
+\end{verbatim}}
+
+Event identifiers that can be sent via \helpref{wxAccessible::NotifyEvent}{wxaccessiblenotifyevent} are
+as follows:
+
+{\small \begin{verbatim}
+#define wxACC\_EVENT\_SYSTEM\_SOUND              0x0001
+#define wxACC\_EVENT\_SYSTEM\_ALERT              0x0002
+#define wxACC\_EVENT\_SYSTEM\_FOREGROUND         0x0003
+#define wxACC\_EVENT\_SYSTEM\_MENUSTART          0x0004
+#define wxACC\_EVENT\_SYSTEM\_MENUEND            0x0005
+#define wxACC\_EVENT\_SYSTEM\_MENUPOPUPSTART     0x0006
+#define wxACC\_EVENT\_SYSTEM\_MENUPOPUPEND       0x0007
+#define wxACC\_EVENT\_SYSTEM\_CAPTURESTART       0x0008
+#define wxACC\_EVENT\_SYSTEM\_CAPTUREEND         0x0009
+#define wxACC\_EVENT\_SYSTEM\_MOVESIZESTART      0x000A
+#define wxACC\_EVENT\_SYSTEM\_MOVESIZEEND        0x000B
+#define wxACC\_EVENT\_SYSTEM\_CONTEXTHELPSTART   0x000C
+#define wxACC\_EVENT\_SYSTEM\_CONTEXTHELPEND     0x000D
+#define wxACC\_EVENT\_SYSTEM\_DRAGDROPSTART      0x000E
+#define wxACC\_EVENT\_SYSTEM\_DRAGDROPEND        0x000F
+#define wxACC\_EVENT\_SYSTEM\_DIALOGSTART        0x0010
+#define wxACC\_EVENT\_SYSTEM\_DIALOGEND          0x0011
+#define wxACC\_EVENT\_SYSTEM\_SCROLLINGSTART     0x0012
+#define wxACC\_EVENT\_SYSTEM\_SCROLLINGEND       0x0013
+#define wxACC\_EVENT\_SYSTEM\_SWITCHSTART        0x0014
+#define wxACC\_EVENT\_SYSTEM\_SWITCHEND          0x0015
+#define wxACC\_EVENT\_SYSTEM\_MINIMIZESTART      0x0016
+#define wxACC\_EVENT\_SYSTEM\_MINIMIZEEND        0x0017
+#define wxACC\_EVENT\_OBJECT\_CREATE                 0x8000
+#define wxACC\_EVENT\_OBJECT\_DESTROY                0x8001
+#define wxACC\_EVENT\_OBJECT\_SHOW                   0x8002
+#define wxACC\_EVENT\_OBJECT\_HIDE                   0x8003
+#define wxACC\_EVENT\_OBJECT\_REORDER                0x8004
+#define wxACC\_EVENT\_OBJECT\_FOCUS                  0x8005
+#define wxACC\_EVENT\_OBJECT\_SELECTION              0x8006
+#define wxACC\_EVENT\_OBJECT\_SELECTIONADD           0x8007
+#define wxACC\_EVENT\_OBJECT\_SELECTIONREMOVE        0x8008
+#define wxACC\_EVENT\_OBJECT\_SELECTIONWITHIN        0x8009
+#define wxACC\_EVENT\_OBJECT\_STATECHANGE            0x800A
+#define wxACC\_EVENT\_OBJECT\_LOCATIONCHANGE         0x800B
+#define wxACC\_EVENT\_OBJECT\_NAMECHANGE             0x800C
+#define wxACC\_EVENT\_OBJECT\_DESCRIPTIONCHANGE      0x800D
+#define wxACC\_EVENT\_OBJECT\_VALUECHANGE            0x800E
+#define wxACC\_EVENT\_OBJECT\_PARENTCHANGE           0x800F
+#define wxACC\_EVENT\_OBJECT\_HELPCHANGE             0x8010
+#define wxACC\_EVENT\_OBJECT\_DEFACTIONCHANGE        0x8011
+#define wxACC\_EVENT\_OBJECT\_ACCELERATORCHANGE      0x8012
+\end{verbatim}}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxAccessible::wxAccessible}\label{wxaccessiblewxaccessible}
+
+\func{}{wxAccessible}{\param{wxWindow* }{win = NULL}}
+
+Constructor, taking an optional window. The object can be associated with
+a window later.
+
+\membersection{wxAccessible::\destruct{wxAccessible}}\label{wxaccessibledtor}
+
+\func{}{\destruct{wxAccessible}}{\void}
+
+Destructor.
+
+\membersection{wxAccessible::DoDefaultAction}\label{wxaccessibledodefaultaction}
+
+\func{virtual wxAccStatus}{DoDefaultAction}{\param{int }{childId}}
+
+Performs the default action for the object. {\it childId} is 0 (the action for this object)
+or greater than 0 (the action for a child). Return wxACC\_NOT\_SUPPORTED if there
+is no default action for this window (e.g. an edit control).
+
+\membersection{wxAccessible::GetChild}\label{wxaccessiblegetchild}
+
+\func{virtual wxAccStatus}{GetChild}{\param{int }{childId}, \param{wxAccessible** }{child}}
+
+Gets the specified child (starting from 1). If {\it child} is NULL and the return value is wxACC\_OK,
+this means that the child is a simple element and not an accessible object.
+
+\membersection{wxAccessible::GetChildCount}\label{wxaccessiblegetchildcount}
+
+\func{virtual wxAccStatus}{GetChildCount}{\param{int* }{childId}}
+
+Returns the number of children in {\it childId}.
+
+\membersection{wxAccessible::GetDefaultAction}\label{wxaccessiblegetdefaultaction}
+
+\func{virtual wxAccStatus}{GetDefaultAction}{\param{int }{childId}, \param{wxString* }{actionName}}
+
+Gets the default action for this object (0) or a child (greater than 0).
+Return wxACC\_OK even if there is no action. {\it actionName} is the action, or the empty
+string if there is no action. The retrieved string describes the action that is performed on an object,
+not what the object does as a result. For example, a toolbar button that prints
+a document has a default action of "Press" rather than "Prints the current document."
+
+\membersection{wxAccessible::GetDescription}\label{wxaccessiblegetdescription}
+
+\func{virtual wxAccStatus}{GetDescription}{\param{int }{childId}, \param{wxString* }{description}}
+
+Returns the description for this object or a child.
+
+\membersection{wxAccessible::GetFocus}\label{wxaccessiblegetfocus}
+
+\func{virtual wxAccStatus}{GetFocus}{\param{int* }{childId}, \param{wxAccessible** }{child}}
+
+Gets the window with the keyboard focus. If childId is 0 and child is NULL, no object in
+this subhierarchy has the focus. If this object has the focus, child should be 'this'.
+
+\membersection{wxAccessible::GetHelpText}\label{wxaccessiblegethelptext}
+
+\func{virtual wxAccStatus}{GetHelpText}{\param{int }{childId}, \param{wxString* }{helpText}}
+
+Returns help text for this object or a child, similar to tooltip text.
+
+\membersection{wxAccessible::GetKeyboardShortcut}\label{wxaccessiblegetkeyboardshortcut}
+
+\func{virtual wxAccStatus}{GetKeyboardShortcut}{\param{int }{childId}, \param{wxString* }{shortcut}}
+
+Returns the keyboard shortcut for this object or child.
+Return e.g. ALT+K.
+
+\membersection{wxAccessible::GetLocation}\label{wxaccessiblegetlocation}
+
+\func{virtual wxAccStatus}{GetLocation}{\param{wxRect\& }{rect}, \param{int }{elementId}}
+
+Returns the rectangle for this object (id is 0) or a child element (id is greater than 0).
+
+\membersection{wxAccessible::GetName}\label{wxaccessiblegetname}
+
+\func{virtual wxAccStatus}{GetName}{\param{int }{childId}, \param{wxString* }{name}}
+
+Gets the name of the specified object.
+
+\membersection{wxAccessible::GetParent}\label{wxaccessiblegetparent}
+
+\func{virtual wxAccStatus}{GetParent}{\param{wxAccessible** }{parent}}
+
+Returns the parent of this object, or NULL.
+
+\membersection{wxAccessible::GetRole}\label{wxaccessiblegetrole}
+
+\func{virtual wxAccStatus}{GetRole}{\param{int }{childId}, \param{wxAccRole* }{role}}
+
+Returns a role constant describing this object. See \helpref{wxAccessible}{wxaccessible} for a list
+of these roles.
+
+\membersection{wxAccessible::GetSelections}\label{wxaccessiblegetselections}
+
+\func{virtual wxAccStatus}{GetSelections}{\param{wxVariant* }{selections}}
+
+Gets a variant representing the selected children
+of this object.
+
+Acceptable values are:
+
+\begin{itemize}
+\item  a null variant (IsNull() returns TRUE)
+\item  a list variant (GetType() == wxT("list"))
+\item  an integer representing the selected child element,
+or 0 if this object is selected (GetType() == wxT("long"))
+\item a "void*" pointer to a wxAccessible child object
+\end{itemize}
+
+\membersection{wxAccessible::GetState}\label{wxaccessiblegetstate}
+
+\func{virtual wxAccStatus}{GetState}{\param{int }{childId}, \param{long* }{state}}
+
+Returns a state constant. See \helpref{wxAccessible}{wxaccessible} for a list
+of these states.
+
+\membersection{wxAccessible::GetValue}\label{wxaccessiblegetvalue}
+
+\func{virtual wxAccStatus}{GetValue}{\param{int }{childId}, \param{wxString* }{strValue}}
+
+Returns a localized string representing the value for the object
+or child.
+
+\membersection{wxAccessible::GetWindow}\label{wxaccessiblegetwindow}
+
+\func{wxWindow*}{GetWindow}{\void}
+
+Returns the window associated with this object.
+
+\membersection{wxAccessible::HitTest}\label{wxaccessiblehittest}
+
+\func{virtual wxAccStatus}{HitTest}{\param{const wxPoint\& }{pt}, \param{int* }{childId}, \param{wxAccessible** }{childObject}}
+
+Returns a status value and object id to indicate whether the given point was on this or
+a child object. Can return either a child object, or an integer
+representing the child element, starting from 1.
+
+\membersection{wxAccessible::Navigate}\label{wxaccessiblenavigate}
+
+\func{virtual wxAccStatus}{Navigate}{\param{wxNavDir }{navDir}, \param{int }{fromId}, \param{int* }{toId}, \param{wxAccessible** }{toObject}}
+
+Navigates from {\it fromId} to {\it toId}/{\it toObject}.
+
+\membersection{wxAccessible::Notify}\label{wxaccessiblenotify}
+
+\func{virtual static void}{Notify}{\param{int}{ eventType}, \param{wxWindow* }{window}, \param{wxAccObjectt }{objectType}, \param{int }{objectType}}
+
+Allows the application to send an event when something changes in an accessible object.
+
+\membersection{wxAccessible::Select}\label{wxaccessibleselect}
+
+\func{virtual wxAccStatus}{Select}{\param{int }{childId}, \param{wxAccSelectionFlags }{selectFlags}}
+
+Selects the object or child. See \helpref{wxAccessible}{wxaccessible} for a list
+of the selection actions.
+
+\membersection{wxAccessible::SetWindow}\label{wxaccessiblesetwindow}
+
+\func{void}{SetWindow}{\param{wxWindow* }{window}}
+
+Sets the window associated with this object.
+
diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex
index 783cfa71e2..ffacfd8ab7 100644
--- a/docs/latex/wx/classes.tex
+++ b/docs/latex/wx/classes.tex
@@ -6,6 +6,7 @@
 %     them and *not* in alphabetic order of the file names!
 
 \input accel.tex
+\input accessible.tex
 \input activevt.tex
 \input app.tex
 \input array.tex
diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 44bfe0a816..b78c4eb1dd 100644
--- a/docs/latex/wx/window.tex
+++ b/docs/latex/wx/window.tex
@@ -548,6 +548,14 @@ wxTextCtrl under wxGTK) but is not implemented on all platforms nor for all
 controls so it is mostly just a hint to wxWindows and not a mandatory
 directive.
 
+\membersection{wxWindow::GetAccessible}\label{wxwindowgetaccessible}
+
+\func{wxAccessibile*}{GetAccessible}{\void}
+
+Returns the accessible object for this window, if any.
+
+See also \helpref{wxAccessible}{wxaccessible}.
+
 \membersection{wxWindow::GetAdjustedBestSize}\label{wxwindowgetadjustedbestsize}
 
 \constfunc{wxSize}{GetAdjustedBestSize}{\void}
@@ -1929,6 +1937,15 @@ redrawn. Note that it is rarely required to call this function from a user progr
 
 Sets the accelerator table for this window. See \helpref{wxAcceleratorTable}{wxacceleratortable}.
 
+\membersection{wxWindow::SetAccessible}\label{wxwindowsetaccessible}
+
+\func{void}{SetAccessible}{\param{wxAccessibile*}{ accessible}}
+
+Sets the accessible for this window. Any existing accessible for this window
+will be deleted first, if not identical to {\it accessible}.
+
+See also \helpref{wxAccessible}{wxaccessible}.
+
 \membersection{wxWindow::SetAutoLayout}\label{wxwindowsetautolayout}
 
 \func{void}{SetAutoLayout}{\param{bool}{ autoLayout}}
-- 
2.50.0

