Sign in Join
Wiki copytemporary

LCL Accessibility: what changed

Revision 3 to 4. Removed lines have a minus sign; added lines have a plus sign.

OldNewLine
11Accessibility means planning and developing applications in a way in which allows an individual with visual impairments or other disabilities to perform a task that they would otherwise be unable to do, or increase the ease and safety with which a task can be performed, or anything that assists individuals to carry-out daily activities.
22
33# LCL Accessibility Introduction
44
55The LCL should automatically provide accessibility for all of its standard controls, or allow the underlying widgetset to provide its own accessibility for the controls utilized directly from the widgetset. LCL users need to provide accessibility only for TCustomControl descendents introduced in the application. LCL developers need to provide accessibility for all TCustomControl descendents in the LCL and also for all non-windowed controls in the LCL (such as TLabel).
66
77The accessibility information provided is a tree of accessible objects which represent the controls hierarchy in the application and which can cover both windowed and non-windowed controls. What the screen reader does exactly with this information is theoretically up to it to decide, but of course it is necessary to test to verify if the most popular screen readers are actually using the information provided in the expected way. The LCL is responsible for making these bridges, since it provides a quite simple accessibility interface. Platform APIs, especially the one from macOS, are more complex.
88
99TControl will automatically create an accessible object and place it correctly in the accessible objects tree, so it is not necessary to manually create accessible objects unless a control has sub-items which should be represented individually and are not TControl-descendents. One typical example are the items of the TTreeView control. They are not controls, but can be selected individually and therefore each item should be an accessible object on its own.
1010
1111``` pascal
1212 TLazAccessibilityRole = (
1313 larAnimation, // An object that displays an animation.
1414 larButton, // A button.
1515 larCell, // A cell in a table.
1616 larChart, // An object that displays a graphical representation of data.
1717 larCheckBox, // An object that can be checked or unchecked, or sometimes in an intermediary state
1818 larClock, // A clock displaying time.
1919 larColorPicker, // A control which allows selecting a color.
2020 larComboBox, // A list of choices that the user can select from.
2121 larDateField, // A controls which displays and possibly allows to choose a date.
2222 larGrid, // A grid control which displays cells
2323 larGroup, // A control which groups others, such as a TGroupBox.
2424 larIgnore, // Something to be ignored. For example a blank space between other objects.
2525 larImage, // A graphic or picture or an icon.
2626 larLabel, // A text label as usually placed near other widgets.
2727 larListBox, // A list of items, from which the user can select one or more items.
2828 larListItem, // An item in a list of items.
2929 larMenuBar, // A main menu bar.
3030 larMenuItem, // A item in a menu.
3131 larProgressIndicator, // A control which shows a progress indication.
3232 larResizeGrip, // A grip that the user can drag to change the size of widgets.
3333 larScrollBar, // A control to scroll another one
3434 larSpinner, // A control which allows to increment / decrement a value.
3535 larTabControl, // A control with tabs, like TPageControl.
3636 larTextEditorMultiline, // A multi-line text editor (for example: TMemo, SynEdit)
3737 larTextEditorSingleline, // A single-line text editor (for example: TEdit)
3838 larTrackBar, // A control which allows to drag a slider.
3939 larTreeView, // A list of items in a tree structure.
4040 larTreeItem, // An item in a tree structure.
4141 larWindow // A top level window.
4242 );
4343
4444 // The Child Accessible Objects are designed for non-TControl children
4545 // of a TCustomControl descendent, for example the items of a TTreeView
4646
4747 { TLazAccessibleObject }
4848
4949 TLazAccessibleObject = class
5050 private
5151 FHandle: PtrInt;
5252 FPosition: TPoint;
5353 FSize: TSize;
5454 function GetHandle: PtrInt;
5555 function GetPosition: TPoint;
5656 function GetSize: TSize;
5757 procedure SetPosition(AValue: TPoint);
5858 procedure SetSize(AValue: TSize);
5959 protected
6060 FChildren: TFPList; // of TLazAccessibleObject
6161 FAccessibleDescription: TCaption;
6262 FAccessibleValue: TCaption;
6363 FAccessibleRole: TLazAccessibilityRole;
6464 class procedure WSRegisterClass; virtual;//override;
6565 public
6666 OwnerControl: TControl;
6767 Parent: TLazAccessibleObject;
6868 DataObject: TObject; // Available to be used to connect to an object
6969 SecondaryHandle: PtrInt; // Available for Widgetsets to use
7070 constructor Create(AOwner: TControl); virtual;
7171 destructor Destroy; override;
7272 procedure SetAccessibleDescription(const ADescription: TCaption);
7373 procedure SetAccessibleValue(const AValue: TCaption);
7474 procedure SetAccessibleRole(const ARole: TLazAccessibilityRole);
7575 function FindOwnerWinControl: TWinControl;
7676 function AddChildAccessibleObject: TLazAccessibleObject; virtual;
7777 procedure ClearChildAccessibleObjects;
7878 procedure RemoveChildAccessibleObject(AObject: TLazAccessibleObject);
7979 function GetChildAccessibleObject(AIndex: Integer): TLazAccessibleObject;
8080 function GetChildAccessibleObjectWithDataObject(ADataObject: TObject): TLazAccessibleObject;
8181 function GetChildAccessibleObjectsCount: Integer;
8282 function GetSelectedChildAccessibleObject: TLazAccessibleObject; virtual;
8383 function GetChildAccessibleObjectAtPos(APos: TPoint): TLazAccessibleObject; virtual;
8484 // Primary information
8585 property AccessibleDescription: TCaption read FAccessibleDescription write SetAccessibleDescription;
8686 property AccessibleValue: TCaption read FAccessibleValue write SetAccessibleValue;
8787 property AccessibleRole: TLazAccessibilityRole read FAccessibleRole write SetAccessibleRole;
8888 property Position: TPoint read GetPosition write SetPosition;
8989 property Size: TSize read GetSize write SetSize;
9090 property Handle: PtrInt read GetHandle write FHandle;
9191 end;
9292
9393 TControl = class(TLCLComponent)
9494 private
9595...
9696 // accessibility
9797 function GetAccessibleObject: TLazAccessibleObject;
9898 function CreateAccessibleObject: TLazAccessibleObject; virtual;
9999 function GetSelectedChildAccessibleObject: TLazAccessibleObject; virtual;
100100 function GetChildAccessibleObjectAtPos(APos: TPoint): TLazAccessibleObject; virtual;
101101 public
102102 // standard properties, which should be supported by all descendants
103103 property AccessibleDescription: TCaption read GetAccessibleDescription write SetAccessibleDescription;
104104 property AccessibleValue: TCaption read GetAccessibleValue write SetAccessibleValue;
105105 property AccessibleRole: TLazAccessibilityRole read GetAccessibleRole write SetAccessibleRole;
106106...
107107 end;
108108```
109109
110110## Obtaining the accessible object associated with a control
111111
112112Use TControl.GetAccessibleObject: TLazAccessibleObject;
113113
114114## Setting the basic accessible fields for a control
115115
116116Use TControl.AcessibleDescription, TControl.AccessibleValue, TControl.AccessibleRole. TControl.GetAccessibleObject().AccessibleDescription is the same thing as TControl.AccessibleDescription and they are connected.
117117
118118# Screen Readers
119119
120120The first step in testing screen reader support is installing one and being able to use it to check what users will see when using your application.
121121
122122## macOS VoiceOver
123123
124124The screen reader for the vast majority of users in macOS is VoiceOver which comes pre-installed with the operating system. To activate it go to System Preferences \> Accessibility and turn VoiceOver on. It couldnt be any simpler. Using it is also mostly easy and intuitive.
125125
126126![](/wiki-images/4/49/Voiceover_screenshot.png)
127127
128128## Orca for Linux
129129
130130Orca is currently the most popular screen reader in Linux for both GNOME and KDE. See: <http://en.wikipedia.org/wiki/Orca_(assistive_technology)>
131131
132132# Speech synthesis
133133
134134An intelligible text-to-speech program allows individuals with visual impairments or reading disabilities to listen to written words on their computer. See the [[Speech Synthesis]] article for details of cross-platform and native operating system solutions.
135135
136136# Accessibility Inspector Tools
137137
138138Accessibility inspectors can help a lot at checking if the application is giving correct information.
139139
140140## macOS
141141
142142In /Applications/Xcode.app/Contents/Applications/ there is an Accessibility Inspector application which will be very useful when developing in this platform.
143143
144144See also:
145145
146146- Apple's [macOS accessibility documentation](https://developer.apple.com/accessibility/macos/)
147147- Apple's [Using the Accessibility Inspector](https://developer.apple.com/library/archive/documentation/Accessibility/Conceptual/AccessibilityMacOSX/OSXAXTestingApps.html)
148148
149149# Accessibility APIs
150150
151151## Carbon
152152
153153Search Google for:
154154
155-`site:developer.apple.com carbon accessibility`
155+```text
156+site:developer.apple.com carbon accessibility
157+```
156158
157159The main accessibility code for Carbon is in lcl/interfaces/carbon/carbonprivatecontrol.inc in the function CarbonControl_Accessibility
158160
159161The events for this handler are:
160162
161163- kEventAccessibleGetChildAtPoint
162164- kEventAccessibleGetFocusedChild
163165- kEventAccessibleGetAllAttributeNames
164166- kEventAccessibleGetAllParameterizedAttributeNames
165167- kEventAccessibleGetNamedAttribute
166168- kEventAccessibleSetNamedAttribute
167169- kEventAccessibleIsNamedAttributeSettable
168170- kEventAccessibleGetAllActionNames
169171- kEventAccessiblePerformNamedAction
170172- kEventAccessibleGetNamedActionDescription
171173
172174For kEventAccessibleGetNamedAttribute the main named attributes are:
173175
174176- AXRole
175177- AXRoleDescription
176178- AXDescription
177179- AXHelp
178180- AXParent
179181- AXChildren
180182- AXWindow
181183- AXTopLevelUIElement
182184- AXEnabled
183185- AXSize
184186- AXPosition
185187
186188And besides the ones listed here there are tons more. See which attributes each role should implement here: [http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Role.html#//apple_ref/doc/uid/TP40007870-Roles-AXStaticText](http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Role.html#//apple_ref/doc/uid/TP40007870-Roles-AXStaticText)
187189
188190Table explaining the events: <http://developer.apple.com/library/mac/#documentation/Accessibility/Reference/AccessibilityCarbonRef/Reference/reference.html>
189191
190192Documentation explaining in details which attributes are required for each Role: <http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Attributes.html>
191193
192194List of routines to handle a AXUIElementRef: <http://developer.apple.com/library/mac/#documentation/Accessibility/Reference/AccessibilityLowlevel/AXUIElement_h/CompositePage.html>
193195
194196## Cocoa
195197
196198- Apple [Accessibility Programming Guide](https://developer.apple.com/library/archive/documentation/Accessibility/Conceptual/AccessibilityMacOSX/index.html)
197199- Apple docs for the [NSAccessibility Protocol](http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/ApplicationKit/Protocols/NSAccessibility_Protocol/Reference/Reference.html)
198200- Apple docs for [Accessibility Roles and Attributes Reference](http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Notifications.html)
199201
200202## Microsoft Active Accessibility
201203
202204See: <http://en.wikipedia.org/wiki/Microsoft_Active_Accessibility>
203205
204206Also: <http://www.stevetrefethen.com/blog/UsingtheMSAAIAccessibleinterfacewithinaDelphiApplication.aspx>
205207
206208Concrete code from MS: <http://msdn.microsoft.com/en-us/library/windows/desktop/cc307844.aspx>
207209
208210## AT-SPI for Linux
209211
210212See: <http://en.wikipedia.org/wiki/AT-SPI>
211213
212214For making an application support AT-SPI there are two solutions:
213215
2142161-\> Make the application a DBus server and serve the interface described in the following XML files: <http://git.gnome.org/browse/at-spi2-core/tree/xml>
215217
2162182-\> Use libatk, but this library requires a GLib main loop
217219
218220## Qt
219221
220222See: <http://doc.qt.nokia.com/4.3/qaccessiblewidget.html>
221223
222224Also: <http://doc.qt.nokia.com/4.3/qaccessible.html#Role-enum>
223225
224226Also: <http://doc.qt.nokia.com/qq/qq24-accessibility.html>
225227
226228## Concepts mapping
227229
228230| TLazAccessibleObject | Qt | macOS | MSAA | AT-SPI | Comments |
229231|----|----|----|----|----|----|
230232| AccessibleRole | QAccessible::Role | AXRole | Role | ?\|\|- | |
231233| AccessibleDescription | QAccessibleWidget::setDescription | AXRoleDescription, AXDescription, AXTitleUIElement | ? | ?\|\|- | |
232234| AccessibleValue | QAccessibleWidget::setValue | AXValue | Value, Name, State | ?\|\|- | |
233235| Position | ? | AXPosition | ? | ?\|\|- | |
234236| Size | ? | AXSize | ? | ?\|\|- | |
235237| Handle | ? | AXUIElementRef | ? | ?\|\|- | |
236238| Parent | ? | AXParent | ? | ?\|\|- | |
237239| SecondaryHandle | Vacant | Vacant | Vacant | Vacant\|\|- | |
238240
239241---
240242*From the Free Pascal wiki, page "LCL Accessibility", as it stood on 2021-02-24 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*
241243Category: Accessibility
242244Category: GUI
243245Category: LCL
244246Category: Linux
245247Category: Windows
246248Category: macOS

Back to history