Sign in Join
Wiki copytemporary

LCL Accessibility: what changed

Revision 1 to 2. 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
126-<figure>
127126<img src="Voiceover_screenshot.png" title="Voiceover_screenshot.png" width="800" />
128-<figcaption>Voiceover_screenshot.png</figcaption>
129-</figure>
130127
131128## Orca for Linux
132129
133130Orca is currently the most popular screen reader in Linux for both GNOME and KDE. See: <http://en.wikipedia.org/wiki/Orca_(assistive_technology)>
134131
135132# Speech synthesis
136133
137134An 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.
138135
139136# Accessibility Inspector Tools
140137
141138Accessibility inspectors can help a lot at checking if the application is giving correct information.
142139
143140## macOS
144141
145142In /Applications/Xcode.app/Contents/Applications/ there is an Accessibility Inspector application which will be very useful when developing in this platform.
146143
147144See also:
148145
149146- Apple's [macOS accessibility documentation](https://developer.apple.com/accessibility/macos/)
150147- Apple's [Using the Accessibility Inspector](https://developer.apple.com/library/archive/documentation/Accessibility/Conceptual/AccessibilityMacOSX/OSXAXTestingApps.html)
151148
152149# Accessibility APIs
153150
154151## Carbon
155152
156153Search Google for:
157154
158155`site:developer.apple.com carbon accessibility`
159156
160157The main accessibility code for Carbon is in lcl/interfaces/carbon/carbonprivatecontrol.inc in the function CarbonControl_Accessibility
161158
162159The events for this handler are:
163160
164161- kEventAccessibleGetChildAtPoint
165162- kEventAccessibleGetFocusedChild
166163- kEventAccessibleGetAllAttributeNames
167164- kEventAccessibleGetAllParameterizedAttributeNames
168165- kEventAccessibleGetNamedAttribute
169166- kEventAccessibleSetNamedAttribute
170167- kEventAccessibleIsNamedAttributeSettable
171168- kEventAccessibleGetAllActionNames
172169- kEventAccessiblePerformNamedAction
173170- kEventAccessibleGetNamedActionDescription
174171
175172For kEventAccessibleGetNamedAttribute the main named attributes are:
176173
177174- AXRole
178175- AXRoleDescription
179176- AXDescription
180177- AXHelp
181178- AXParent
182179- AXChildren
183180- AXWindow
184181- AXTopLevelUIElement
185182- AXEnabled
186183- AXSize
187184- AXPosition
188185
189186And 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)
190187
191188Table explaining the events: <http://developer.apple.com/library/mac/#documentation/Accessibility/Reference/AccessibilityCarbonRef/Reference/reference.html>
192189
193190Documentation explaining in details which attributes are required for each Role: <http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Attributes.html>
194191
195192List of routines to handle a AXUIElementRef: <http://developer.apple.com/library/mac/#documentation/Accessibility/Reference/AccessibilityLowlevel/AXUIElement_h/CompositePage.html>
196193
197194## Cocoa
198195
199196- Apple [Accessibility Programming Guide](https://developer.apple.com/library/archive/documentation/Accessibility/Conceptual/AccessibilityMacOSX/index.html)
200197- Apple docs for the [NSAccessibility Protocol](http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/ApplicationKit/Protocols/NSAccessibility_Protocol/Reference/Reference.html)
201198- Apple docs for [Accessibility Roles and Attributes Reference](http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Notifications.html)
202199
203200## Microsoft Active Accessibility
204201
205202See: <http://en.wikipedia.org/wiki/Microsoft_Active_Accessibility>
206203
207204Also: <http://www.stevetrefethen.com/blog/UsingtheMSAAIAccessibleinterfacewithinaDelphiApplication.aspx>
208205
209206Concrete code from MS: <http://msdn.microsoft.com/en-us/library/windows/desktop/cc307844.aspx>
210207
211208## AT-SPI for Linux
212209
213210See: <http://en.wikipedia.org/wiki/AT-SPI>
214211
215212For making an application support AT-SPI there are two solutions:
216213
2172141-\> 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>
218215
2192162-\> Use libatk, but this library requires a GLib main loop
220217
221218## Qt
222219
223220See: <http://doc.qt.nokia.com/4.3/qaccessiblewidget.html>
224221
225222Also: <http://doc.qt.nokia.com/4.3/qaccessible.html#Role-enum>
226223
227224Also: <http://doc.qt.nokia.com/qq/qq24-accessibility.html>
228225
229226## Concepts mapping
230227
231228| TLazAccessibleObject | Qt | macOS | MSAA | AT-SPI | Comments |
232229|----|----|----|----|----|----|
233230| AccessibleRole | QAccessible::Role | AXRole | Role | ?\|\|- | |
234231| AccessibleDescription | QAccessibleWidget::setDescription | AXRoleDescription, AXDescription, AXTitleUIElement | ? | ?\|\|- | |
235232| AccessibleValue | QAccessibleWidget::setValue | AXValue | Value, Name, State | ?\|\|- | |
236233| Position | ? | AXPosition | ? | ?\|\|- | |
237234| Size | ? | AXSize | ? | ?\|\|- | |
238235| Handle | ? | AXUIElementRef | ? | ?\|\|- | |
239236| Parent | ? | AXParent | ? | ?\|\|- | |
240237| SecondaryHandle | Vacant | Vacant | Vacant | Vacant\|\|- | |
241238
242239---
243240*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).*
244241Category: Accessibility
245242Category: GUI
246243Category: LCL
247244Category: Linux
248245Category: Windows
249246Category: macOS

Back to history