From: Julian Smart Date: Wed, 16 Apr 2003 09:40:09 +0000 (+0000) Subject: Added wxAccessible documentation X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/2dab56e91e68dfc14e6bc0a8e45a664e4a323fc8 Added wxAccessible documentation git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@20235 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- 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} + + + +\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}}