Support ARIA "tab" roles
[WebKit-https.git] / WebCore / accessibility / AccessibilityObject.h
1 /*
2  * Copyright (C) 2008, 2009 Apple Inc. All rights reserved.
3  * Copyright (C) 2008 Nuanti Ltd.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * 1.  Redistributions of source code must retain the above copyright
10  *     notice, this list of conditions and the following disclaimer.
11  * 2.  Redistributions in binary form must reproduce the above copyright
12  *     notice, this list of conditions and the following disclaimer in the
13  *     documentation and/or other materials provided with the distribution.
14  * 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
15  *     its contributors may be used to endorse or promote products derived
16  *     from this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY
19  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
20  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21  * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY
22  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
24  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
25  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28  */
29
30 #ifndef AccessibilityObject_h
31 #define AccessibilityObject_h
32
33 #include "IntRect.h"
34 #include "Range.h"
35 #include "VisiblePosition.h"
36 #include "VisibleSelection.h"
37 #include <wtf/Platform.h>
38 #include <wtf/RefPtr.h>
39 #include <wtf/Vector.h>
40
41 #if PLATFORM(MAC)
42 #include <wtf/RetainPtr.h>
43 #elif PLATFORM(WIN) && !PLATFORM(WINCE)
44 #include "AccessibilityObjectWrapperWin.h"
45 #include "COMPtr.h"
46 #elif PLATFORM(CHROMIUM)
47 #include "AccessibilityObjectWrapper.h"
48 #endif
49
50 typedef struct _NSRange NSRange;
51
52 #ifdef __OBJC__
53 @class AccessibilityObjectWrapper;
54 @class NSArray;
55 @class NSAttributedString;
56 @class NSData;
57 @class NSMutableAttributedString;
58 @class NSString;
59 @class NSValue;
60 @class NSView;
61 #else
62 class NSArray;
63 class NSAttributedString;
64 class NSData;
65 class NSMutableAttributedString;
66 class NSString;
67 class NSValue;
68 class NSView;
69 #if PLATFORM(GTK)
70 typedef struct _AtkObject AtkObject;
71 typedef struct _AtkObject AccessibilityObjectWrapper;
72 #else
73 class AccessibilityObjectWrapper;
74 #endif
75 #endif
76
77 namespace WebCore {
78
79 class AXObjectCache;
80 class Element;
81 class Frame;
82 class FrameView;
83 class HTMLAnchorElement;
84 class HTMLAreaElement;
85 class IntPoint;
86 class IntSize;
87 class Node;
88 class RenderObject;
89 class RenderListItem;
90 class VisibleSelection;
91 class String;
92 class Widget;
93
94 typedef unsigned AXID;
95
96 enum AccessibilityRole {
97     UnknownRole = 1,
98     ButtonRole,
99     RadioButtonRole,
100     CheckBoxRole,
101     SliderRole,
102     TabGroupRole,
103     TextFieldRole,
104     StaticTextRole,
105     TextAreaRole,
106     ScrollAreaRole,
107     PopUpButtonRole,
108     MenuButtonRole,
109     TableRole,
110     ApplicationRole,
111     GroupRole,
112     RadioGroupRole,
113     ListRole,
114     ScrollBarRole,
115     ValueIndicatorRole,
116     ImageRole,
117     MenuBarRole,
118     MenuRole,
119     MenuItemRole,
120     ColumnRole,
121     RowRole,
122     ToolbarRole,
123     BusyIndicatorRole,
124     ProgressIndicatorRole,
125     WindowRole,
126     DrawerRole,
127     SystemWideRole,
128     OutlineRole,
129     IncrementorRole,
130     BrowserRole,
131     ComboBoxRole,
132     SplitGroupRole,
133     SplitterRole,
134     ColorWellRole,
135     GrowAreaRole,
136     SheetRole,
137     HelpTagRole,
138     MatteRole,
139     RulerRole,
140     RulerMarkerRole,
141     LinkRole,
142     DisclosureTriangleRole,
143     GridRole,
144     CellRole, 
145     ColumnHeaderRole,
146     RowHeaderRole,
147     // AppKit includes SortButtonRole but it is misnamed and really a subrole of ButtonRole so we do not include it here.
148
149     // WebCore-specific roles
150     WebCoreLinkRole,
151     ImageMapLinkRole,
152     ImageMapRole,
153     ListMarkerRole,
154     WebAreaRole,
155     HeadingRole,
156     ListBoxRole,
157     ListBoxOptionRole,
158     TableHeaderContainerRole,
159     DefinitionListTermRole,
160     DefinitionListDefinitionRole,
161     AnnotationRole,
162     SliderThumbRole,
163     IgnoredRole,
164     TabRole,
165     TabListRole,
166     TabPanelRole,
167     
168     // ARIA Grouping roles
169     LandmarkApplicationRole,
170     LandmarkBannerRole,
171     LandmarkComplementaryRole,
172     LandmarkContentInfoRole,
173     LandmarkMainRole,
174     LandmarkNavigationRole,
175     LandmarkSearchRole,
176     
177     ApplicationLogRole,
178     ApplicationMarqueeRole,
179     ApplicationStatusRole,
180     ApplicationTimerRole,
181     
182     DocumentRole,
183     DocumentArticleRole,
184     DocumentNoteRole,
185     DocumentRegionRole,
186     
187     UserInterfaceTooltipRole
188 };
189
190 enum AccessibilityOrientation {
191     AccessibilityOrientationVertical,
192     AccessibilityOrientationHorizontal,
193 };
194     
195 enum AccessibilityObjectPlatformInclusion {
196     IncludeObject,
197     IgnoreObject,
198     DefaultBehavior,
199 };
200
201 struct VisiblePositionRange {
202
203     VisiblePosition start;
204     VisiblePosition end;
205
206     VisiblePositionRange() {}
207
208     VisiblePositionRange(const VisiblePosition& s, const VisiblePosition& e)
209         : start(s)
210         , end(e)
211     { }
212
213     bool isNull() const { return start.isNull() || end.isNull(); }
214 };
215
216 struct PlainTextRange {
217         
218     unsigned start;
219     unsigned length;
220     
221     PlainTextRange()
222         : start(0)
223         , length(0)
224     { }
225     
226     PlainTextRange(unsigned s, unsigned l)
227         : start(s)
228         , length(l)
229     { }
230     
231     bool isNull() const { return start == 0 && length == 0; }
232 };
233
234 class AccessibilityObject : public RefCounted<AccessibilityObject> {
235 protected:
236     AccessibilityObject();
237 public:
238     virtual ~AccessibilityObject();
239     virtual void detach();
240         
241     typedef Vector<RefPtr<AccessibilityObject> > AccessibilityChildrenVector;
242     
243     virtual bool isAccessibilityRenderObject() const { return false; };
244     virtual bool isAnchor() const { return false; };
245     virtual bool isAttachment() const { return false; };
246     virtual bool isHeading() const { return false; };
247     virtual bool isLink() const { return false; };
248     virtual bool isImage() const { return false; };
249     virtual bool isNativeImage() const { return false; };
250     virtual bool isImageButton() const { return false; };
251     virtual bool isPasswordField() const { return false; };
252     virtual bool isTextControl() const { return false; };
253     virtual bool isNativeTextControl() const { return false; };
254     virtual bool isWebArea() const { return false; };
255     virtual bool isCheckboxOrRadio() const { return false; };
256     virtual bool isListBox() const { return roleValue() == ListBoxRole; };
257     virtual bool isMediaTimeline() const { return false; }
258     virtual bool isMenuRelated() const { return false; }
259     virtual bool isMenu() const { return false; }
260     virtual bool isMenuBar() const { return false; }
261     virtual bool isMenuButton() const { return false; }
262     virtual bool isMenuItem() const { return false; }
263     virtual bool isFileUploadButton() const { return false; };
264     virtual bool isInputImage() const { return false; }
265     virtual bool isProgressIndicator() const { return false; };
266     virtual bool isSlider() const { return false; };
267     virtual bool isControl() const { return false; };
268     virtual bool isList() const { return false; };
269     virtual bool isDataTable() const { return false; };
270     virtual bool isTableRow() const { return false; };
271     virtual bool isTableColumn() const { return false; };
272     virtual bool isTableCell() const { return false; };
273     virtual bool isFieldset() const { return false; };
274     virtual bool isGroup() const { return false; };
275     bool isTabList() const { return roleValue() == TabListRole; }
276     bool isTabItem() const { return roleValue() == TabRole; }
277     bool isRadioGroup() const { return roleValue() == RadioGroupRole; }
278     
279     virtual bool isChecked() const { return false; };
280     virtual bool isEnabled() const { return false; };
281     virtual bool isSelected() const { return false; };
282     virtual bool isFocused() const { return false; };
283     virtual bool isHovered() const { return false; };
284     virtual bool isIndeterminate() const { return false; };
285     virtual bool isLoaded() const { return false; };
286     virtual bool isMultiSelect() const { return false; };
287     virtual bool isOffScreen() const { return false; };
288     virtual bool isPressed() const { return false; };
289     virtual bool isReadOnly() const { return false; };
290     virtual bool isVisited() const { return false; };
291     virtual bool isRequired() const { return false; };
292     virtual bool isLinked() const { return false; }
293
294     virtual bool canSetFocusAttribute() const { return false; };
295     virtual bool canSetTextRangeAttributes() const { return false; };
296     virtual bool canSetValueAttribute() const { return false; };
297     virtual bool canSetSelectedAttribute() const { return false; }
298     virtual bool canSetSelectedChildrenAttribute() const { return false; }
299     
300     virtual bool hasIntValue() const { return false; };
301
302     bool accessibilityShouldUseUniqueId() const { return true; };
303     virtual bool accessibilityIsIgnored() const  { return true; };
304
305     virtual int headingLevel() const { return 0; }
306     virtual int intValue() const { return 0; }
307     virtual String valueDescription() const { return String(); }
308     virtual float valueForRange() const { return 0.0f; }
309     virtual float maxValueForRange() const { return 0.0f; }
310     virtual float minValueForRange() const { return 0.0f; }
311     virtual AccessibilityObject* selectedRadioButton() { return 0; }
312     virtual AccessibilityObject* selectedTabItem() { return 0; }    
313     virtual int layoutCount() const { return 0; }
314     static bool isARIAControl(AccessibilityRole);
315     static bool isARIAInput(AccessibilityRole);
316     
317     virtual AccessibilityObject* doAccessibilityHitTest(const IntPoint&) const { return 0; }
318     virtual AccessibilityObject* focusedUIElement() const { return 0; }
319
320     virtual AccessibilityObject* firstChild() const { return 0; }
321     virtual AccessibilityObject* lastChild() const { return 0; }
322     virtual AccessibilityObject* previousSibling() const { return 0; }
323     virtual AccessibilityObject* nextSibling() const { return 0; }
324     virtual AccessibilityObject* parentObject() const = 0;
325     virtual AccessibilityObject* parentObjectUnignored() const;
326     virtual AccessibilityObject* parentObjectIfExists() const { return 0; }
327     static AccessibilityObject* firstAccessibleObjectFromNode(const Node*);
328
329     virtual AccessibilityObject* observableObject() const { return 0; }
330     virtual void linkedUIElements(AccessibilityChildrenVector&) const { }
331     virtual AccessibilityObject* titleUIElement() const { return 0; }
332     virtual bool exposesTitleUIElement() const { return true; }
333     virtual AccessibilityObject* correspondingControlForLabelElement() const { return 0; }
334
335     virtual AccessibilityRole ariaRoleAttribute() const { return UnknownRole; }
336     virtual bool isPresentationalChildOfAriaRole() const { return false; }
337     virtual bool ariaRoleHasPresentationalChildren() const { return false; }
338
339     void setRoleValue(AccessibilityRole role) { m_role = role; }
340     virtual AccessibilityRole roleValue() const { return m_role; }
341     virtual String ariaLabeledByAttribute() const { return String(); }
342     virtual String ariaDescribedByAttribute() const { return String(); }
343     virtual String accessibilityDescription() const { return String(); }
344     virtual PassRefPtr<Range> ariaSelectedTextDOMRange() const { return 0; }
345
346     virtual AXObjectCache* axObjectCache() const { return 0; }
347     AXID axObjectID() const { return m_id; }
348     void setAXObjectID(AXID axObjectID) { m_id = axObjectID; }
349     
350     static AccessibilityObject* anchorElementForNode(Node*);
351     virtual Element* anchorElement() const { return 0; }
352     virtual Element* actionElement() const { return 0; }
353     virtual IntRect boundingBoxRect() const { return IntRect(); }
354     virtual IntRect elementRect() const = 0;
355     virtual IntSize size() const = 0;
356     virtual IntPoint clickPoint() const;
357
358     virtual PlainTextRange selectedTextRange() const { return PlainTextRange(); }
359     unsigned selectionStart() const { return selectedTextRange().start; }
360     unsigned selectionEnd() const { return selectedTextRange().length; }
361     
362     virtual KURL url() const { return KURL(); }
363     virtual VisibleSelection selection() const { return VisibleSelection(); }
364     virtual String stringValue() const { return String(); }
365     virtual String title() const { return String(); }
366     virtual String helpText() const { return String(); }
367     virtual String textUnderElement() const { return String(); }
368     virtual String text() const { return String(); }
369     virtual int textLength() const { return 0; }
370     virtual String selectedText() const { return String(); }
371     virtual const AtomicString& accessKey() const { return nullAtom; }
372     const String& actionVerb() const;
373     virtual Widget* widget() const { return 0; }
374     virtual Widget* widgetForAttachmentView() const { return 0; }
375     virtual Document* document() const { return 0; }
376     virtual FrameView* topDocumentFrameView() const { return 0; }
377     virtual FrameView* documentFrameView() const;
378     virtual String language() const;
379
380     virtual void setFocused(bool) { }
381     virtual void setSelectedText(const String&) { }
382     virtual void setSelectedTextRange(const PlainTextRange&) { }
383     virtual void setValue(const String&) { }
384     virtual void setSelected(bool) { }
385
386     virtual void makeRangeVisible(const PlainTextRange&) { }
387     virtual bool press() const;
388     bool performDefaultAction() const { return press(); }
389
390     virtual AccessibilityOrientation orientation() const;
391     virtual void increment() { };
392     virtual void decrement() { };
393
394     virtual void childrenChanged() { }
395     virtual const AccessibilityChildrenVector& children() { return m_children; }
396     virtual void addChildren() { }
397     virtual bool canHaveChildren() const { return true; }
398     virtual bool hasChildren() const { return m_haveChildren; }
399     virtual void selectedChildren(AccessibilityChildrenVector&) { }
400     virtual void visibleChildren(AccessibilityChildrenVector&) { }
401     virtual void tabChildren(AccessibilityChildrenVector&) { }
402     virtual bool shouldFocusActiveDescendant() const { return false; }
403     virtual AccessibilityObject* activeDescendant() const { return 0; }    
404     virtual void handleActiveDescendantChanged() { }
405
406     virtual VisiblePositionRange visiblePositionRange() const { return VisiblePositionRange(); }
407     virtual VisiblePositionRange visiblePositionRangeForLine(unsigned) const { return VisiblePositionRange(); }
408     
409     VisiblePositionRange visiblePositionRangeForUnorderedPositions(const VisiblePosition&, const VisiblePosition&) const;
410     VisiblePositionRange positionOfLeftWord(const VisiblePosition&) const;
411     VisiblePositionRange positionOfRightWord(const VisiblePosition&) const;
412     VisiblePositionRange leftLineVisiblePositionRange(const VisiblePosition&) const;
413     VisiblePositionRange rightLineVisiblePositionRange(const VisiblePosition&) const;
414     VisiblePositionRange sentenceForPosition(const VisiblePosition&) const;
415     VisiblePositionRange paragraphForPosition(const VisiblePosition&) const;
416     VisiblePositionRange styleRangeForPosition(const VisiblePosition&) const;
417     VisiblePositionRange visiblePositionRangeForRange(const PlainTextRange&) const;
418
419     String stringForVisiblePositionRange(const VisiblePositionRange&) const;
420     virtual IntRect boundsForVisiblePositionRange(const VisiblePositionRange&) const { return IntRect(); }
421     int lengthForVisiblePositionRange(const VisiblePositionRange&) const;
422     virtual void setSelectedVisiblePositionRange(const VisiblePositionRange&) const { }
423
424     virtual VisiblePosition visiblePositionForPoint(const IntPoint&) const { return VisiblePosition(); }
425     VisiblePosition nextVisiblePosition(const VisiblePosition& visiblePos) const { return visiblePos.next(); }
426     VisiblePosition previousVisiblePosition(const VisiblePosition& visiblePos) const { return visiblePos.previous(); }
427     VisiblePosition nextWordEnd(const VisiblePosition&) const;
428     VisiblePosition previousWordStart(const VisiblePosition&) const;
429     VisiblePosition nextLineEndPosition(const VisiblePosition&) const;
430     VisiblePosition previousLineStartPosition(const VisiblePosition&) const;
431     VisiblePosition nextSentenceEndPosition(const VisiblePosition&) const;
432     VisiblePosition previousSentenceStartPosition(const VisiblePosition&) const;
433     VisiblePosition nextParagraphEndPosition(const VisiblePosition&) const;
434     VisiblePosition previousParagraphStartPosition(const VisiblePosition&) const;
435     virtual VisiblePosition visiblePositionForIndex(unsigned, bool /*lastIndexOK */) const { return VisiblePosition(); }
436     
437     virtual VisiblePosition visiblePositionForIndex(int) const { return VisiblePosition(); }
438     virtual int indexForVisiblePosition(const VisiblePosition&) const { return 0; }
439
440     AccessibilityObject* accessibilityObjectForPosition(const VisiblePosition&) const;
441     int lineForPosition(const VisiblePosition&) const;
442     PlainTextRange plainTextRangeForVisiblePositionRange(const VisiblePositionRange&) const;
443     virtual int index(const VisiblePosition&) const { return -1; }
444
445     virtual PlainTextRange doAXRangeForLine(unsigned) const { return PlainTextRange(); }
446     PlainTextRange doAXRangeForPosition(const IntPoint&) const;
447     virtual PlainTextRange doAXRangeForIndex(unsigned) const { return PlainTextRange(); }
448     PlainTextRange doAXStyleRangeForIndex(unsigned) const;
449
450     virtual String doAXStringForRange(const PlainTextRange&) const { return String(); }
451     virtual IntRect doAXBoundsForRange(const PlainTextRange&) const { return IntRect(); }
452     String listMarkerTextForNodeAndPosition(Node*, const VisiblePosition&) const;
453
454     unsigned doAXLineForIndex(unsigned);
455
456     virtual String stringValueForMSAA() const { return String(); }
457     virtual String stringRoleForMSAA() const { return String(); }
458     virtual String nameForMSAA() const { return String(); }
459     virtual String descriptionForMSAA() const { return String(); }
460
461 #if HAVE(ACCESSIBILITY)
462 #if PLATFORM(GTK)
463     AccessibilityObjectWrapper* wrapper() const;
464     void setWrapper(AccessibilityObjectWrapper*);
465 #else
466     AccessibilityObjectWrapper* wrapper() const { return m_wrapper.get(); }
467     void setWrapper(AccessibilityObjectWrapper* wrapper) 
468     {
469         m_wrapper = wrapper;
470     }
471 #endif
472 #endif
473
474     // a platform-specific method for determining if an attachment is ignored
475 #if HAVE(ACCESSIBILITY)
476     bool accessibilityIgnoreAttachment() const;
477 #else
478     bool accessibilityIgnoreAttachment() const { return true; }
479 #endif
480
481     // gives platforms the opportunity to indicate if and how an object should be included
482 #if HAVE(ACCESSIBILITY)
483     AccessibilityObjectPlatformInclusion accessibilityPlatformIncludesObject() const;
484 #else
485     AccessibilityObjectPlatformInclusion accessibilityPlatformIncludesObject() const { return DefaultBehavior; }
486 #endif
487
488     // allows for an AccessibilityObject to update its render tree or perform
489     // other operations update type operations
490     virtual void updateBackingStore() { }
491     
492 protected:
493     AXID m_id;
494     AccessibilityChildrenVector m_children;
495     mutable bool m_haveChildren;
496     AccessibilityRole m_role;
497     
498     virtual void clearChildren();
499     virtual bool isDetached() const { return true; }
500     RenderListItem* renderListItemContainerForNode(Node* node) const;
501     
502 #if PLATFORM(MAC)
503     RetainPtr<AccessibilityObjectWrapper> m_wrapper;
504 #elif PLATFORM(WIN) && !PLATFORM(WINCE)
505     COMPtr<AccessibilityObjectWrapper> m_wrapper;
506 #elif PLATFORM(GTK)
507     AtkObject* m_wrapper;
508 #elif PLATFORM(CHROMIUM)
509     RefPtr<AccessibilityObjectWrapper> m_wrapper;
510 #endif
511 };
512
513 } // namespace WebCore
514
515 #endif // AccessibilityObject_h