cf5d676cb610413dbf4dc18630bee74b2cffff06
[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     
165     // ARIA Grouping roles
166     LandmarkApplicationRole,
167     LandmarkBannerRole,
168     LandmarkComplementaryRole,
169     LandmarkContentInfoRole,
170     LandmarkMainRole,
171     LandmarkNavigationRole,
172     LandmarkSearchRole,
173     
174     ApplicationLogRole,
175     ApplicationMarqueeRole,
176     ApplicationStatusRole,
177     ApplicationTimerRole,
178     
179     DocumentRole,
180     DocumentArticleRole,
181     DocumentNoteRole,
182     DocumentRegionRole,
183     
184     UserInterfaceTooltipRole
185 };
186
187 enum AccessibilityOrientation {
188     AccessibilityOrientationVertical,
189     AccessibilityOrientationHorizontal,
190 };
191     
192 enum AccessibilityObjectPlatformInclusion {
193     IncludeObject,
194     IgnoreObject,
195     DefaultBehavior,
196 };
197
198 struct VisiblePositionRange {
199
200     VisiblePosition start;
201     VisiblePosition end;
202
203     VisiblePositionRange() {}
204
205     VisiblePositionRange(const VisiblePosition& s, const VisiblePosition& e)
206         : start(s)
207         , end(e)
208     { }
209
210     bool isNull() const { return start.isNull() || end.isNull(); }
211 };
212
213 struct PlainTextRange {
214         
215     unsigned start;
216     unsigned length;
217     
218     PlainTextRange()
219         : start(0)
220         , length(0)
221     { }
222     
223     PlainTextRange(unsigned s, unsigned l)
224         : start(s)
225         , length(l)
226     { }
227     
228     bool isNull() const { return start == 0 && length == 0; }
229 };
230
231 class AccessibilityObject : public RefCounted<AccessibilityObject> {
232 protected:
233     AccessibilityObject();
234 public:
235     virtual ~AccessibilityObject();
236     virtual void detach();
237         
238     typedef Vector<RefPtr<AccessibilityObject> > AccessibilityChildrenVector;
239     
240     virtual bool isAccessibilityRenderObject() const { return false; };
241     virtual bool isAnchor() const { return false; };
242     virtual bool isAttachment() const { return false; };
243     virtual bool isHeading() const { return false; };
244     virtual bool isLink() const { return false; };
245     virtual bool isImage() const { return false; };
246     virtual bool isNativeImage() const { return false; };
247     virtual bool isImageButton() const { return false; };
248     virtual bool isPasswordField() const { return false; };
249     virtual bool isTextControl() const { return false; };
250     virtual bool isNativeTextControl() const { return false; };
251     virtual bool isWebArea() const { return false; };
252     virtual bool isCheckboxOrRadio() const { return false; };
253     virtual bool isListBox() const { return roleValue() == ListBoxRole; };
254     virtual bool isMediaTimeline() const { return false; }
255     virtual bool isMenuRelated() const { return false; }
256     virtual bool isMenu() const { return false; }
257     virtual bool isMenuBar() const { return false; }
258     virtual bool isMenuButton() const { return false; }
259     virtual bool isMenuItem() const { return false; }
260     virtual bool isFileUploadButton() const { return false; };
261     virtual bool isInputImage() const { return false; }
262     virtual bool isProgressIndicator() const { return false; };
263     virtual bool isSlider() const { return false; };
264     virtual bool isControl() const { return false; };
265     virtual bool isList() const { return false; };
266     virtual bool isDataTable() const { return false; };
267     virtual bool isTableRow() const { return false; };
268     virtual bool isTableColumn() const { return false; };
269     virtual bool isTableCell() const { return false; };
270     virtual bool isFieldset() const { return false; };
271     virtual bool isGroup() const { return false; };
272     bool isRadioGroup() const { return roleValue() == RadioGroupRole; }
273     
274     virtual bool isChecked() const { return false; };
275     virtual bool isEnabled() const { return false; };
276     virtual bool isSelected() const { return false; };
277     virtual bool isFocused() const { return false; };
278     virtual bool isHovered() const { return false; };
279     virtual bool isIndeterminate() const { return false; };
280     virtual bool isLoaded() const { return false; };
281     virtual bool isMultiSelect() const { return false; };
282     virtual bool isOffScreen() const { return false; };
283     virtual bool isPressed() const { return false; };
284     virtual bool isReadOnly() const { return false; };
285     virtual bool isVisited() const { return false; };
286     virtual bool isRequired() const { return false; };
287     virtual bool isLinked() const { return false; }
288
289     virtual bool canSetFocusAttribute() const { return false; };
290     virtual bool canSetTextRangeAttributes() const { return false; };
291     virtual bool canSetValueAttribute() const { return false; };
292     virtual bool canSetSelectedAttribute() const { return false; }
293     virtual bool canSetSelectedChildrenAttribute() const { return false; }
294     
295     virtual bool hasIntValue() const { return false; };
296
297     bool accessibilityShouldUseUniqueId() const { return true; };
298     virtual bool accessibilityIsIgnored() const  { return true; };
299
300     virtual int headingLevel() const { return 0; }
301     virtual int intValue() const { return 0; }
302     virtual String valueDescription() const { return String(); }
303     virtual float valueForRange() const { return 0.0f; }
304     virtual float maxValueForRange() const { return 0.0f; }
305     virtual float minValueForRange() const { return 0.0f; }
306     virtual AccessibilityObject* selectedRadioButton() { return 0; }
307     virtual int layoutCount() const { return 0; }
308     static bool isARIAControl(AccessibilityRole);
309     static bool isARIAInput(AccessibilityRole);
310     
311     virtual AccessibilityObject* doAccessibilityHitTest(const IntPoint&) const { return 0; }
312     virtual AccessibilityObject* focusedUIElement() const { return 0; }
313
314     virtual AccessibilityObject* firstChild() const { return 0; }
315     virtual AccessibilityObject* lastChild() const { return 0; }
316     virtual AccessibilityObject* previousSibling() const { return 0; }
317     virtual AccessibilityObject* nextSibling() const { return 0; }
318     virtual AccessibilityObject* parentObject() const = 0;
319     virtual AccessibilityObject* parentObjectUnignored() const;
320     virtual AccessibilityObject* parentObjectIfExists() const { return 0; }
321     static AccessibilityObject* firstAccessibleObjectFromNode(const Node*);
322
323     virtual AccessibilityObject* observableObject() const { return 0; }
324     virtual void linkedUIElements(AccessibilityChildrenVector&) const { }
325     virtual AccessibilityObject* titleUIElement() const { return 0; }
326     virtual bool exposesTitleUIElement() const { return true; }
327     virtual AccessibilityObject* correspondingControlForLabelElement() const { return 0; }
328
329     virtual AccessibilityRole ariaRoleAttribute() const { return UnknownRole; }
330     virtual bool isPresentationalChildOfAriaRole() const { return false; }
331     virtual bool ariaRoleHasPresentationalChildren() const { return false; }
332
333     void setRoleValue(AccessibilityRole role) { m_role = role; }
334     virtual AccessibilityRole roleValue() const { return m_role; }
335     virtual String ariaAccessibilityName(const String&) const { return String(); }
336     virtual String ariaLabeledByAttribute() const { return String(); }
337     virtual String ariaDescribedByAttribute() const { return String(); }
338     virtual String accessibilityDescription() const { return String(); }
339     virtual PassRefPtr<Range> ariaSelectedTextDOMRange() const { return 0; }
340
341     virtual AXObjectCache* axObjectCache() const { return 0; }
342     AXID axObjectID() const { return m_id; }
343     void setAXObjectID(AXID axObjectID) { m_id = axObjectID; }
344     
345     static AccessibilityObject* anchorElementForNode(Node*);
346     virtual Element* anchorElement() const { return 0; }
347     virtual Element* actionElement() const { return 0; }
348     virtual IntRect boundingBoxRect() const { return IntRect(); }
349     virtual IntRect elementRect() const = 0;
350     virtual IntSize size() const = 0;
351     virtual IntPoint clickPoint() const;
352
353     virtual PlainTextRange selectedTextRange() const { return PlainTextRange(); }
354     unsigned selectionStart() const { return selectedTextRange().start; }
355     unsigned selectionEnd() const { return selectedTextRange().length; }
356     
357     virtual KURL url() const { return KURL(); }
358     virtual VisibleSelection selection() const { return VisibleSelection(); }
359     virtual String stringValue() const { return String(); }
360     virtual String title() const { return String(); }
361     virtual String helpText() const { return String(); }
362     virtual String textUnderElement() const { return String(); }
363     virtual String text() const { return String(); }
364     virtual int textLength() const { return 0; }
365     virtual String selectedText() const { return String(); }
366     virtual const AtomicString& accessKey() const { return nullAtom; }
367     const String& actionVerb() const;
368     virtual Widget* widget() const { return 0; }
369     virtual Widget* widgetForAttachmentView() const { return 0; }
370     virtual Document* document() const { return 0; }
371     virtual FrameView* topDocumentFrameView() const { return 0; }
372     virtual FrameView* documentFrameView() const;
373     virtual String language() const;
374
375     virtual void setFocused(bool) { }
376     virtual void setSelectedText(const String&) { }
377     virtual void setSelectedTextRange(const PlainTextRange&) { }
378     virtual void setValue(const String&) { }
379     virtual void setSelected(bool) { }
380
381     virtual void makeRangeVisible(const PlainTextRange&) { }
382     virtual bool press() const;
383     bool performDefaultAction() const { return press(); }
384
385     virtual AccessibilityOrientation orientation() const;
386     virtual void increment() { };
387     virtual void decrement() { };
388
389     virtual void childrenChanged() { }
390     virtual const AccessibilityChildrenVector& children() { return m_children; }
391     virtual void addChildren() { }
392     virtual bool canHaveChildren() const { return true; }
393     virtual bool hasChildren() const { return m_haveChildren; }
394     virtual void selectedChildren(AccessibilityChildrenVector&) { }
395     virtual void visibleChildren(AccessibilityChildrenVector&) { }
396     virtual bool shouldFocusActiveDescendant() const { return false; }
397     virtual AccessibilityObject* activeDescendant() const { return 0; }    
398     virtual void handleActiveDescendantChanged() { }
399
400     virtual VisiblePositionRange visiblePositionRange() const { return VisiblePositionRange(); }
401     virtual VisiblePositionRange visiblePositionRangeForLine(unsigned) const { return VisiblePositionRange(); }
402     
403     VisiblePositionRange visiblePositionRangeForUnorderedPositions(const VisiblePosition&, const VisiblePosition&) const;
404     VisiblePositionRange positionOfLeftWord(const VisiblePosition&) const;
405     VisiblePositionRange positionOfRightWord(const VisiblePosition&) const;
406     VisiblePositionRange leftLineVisiblePositionRange(const VisiblePosition&) const;
407     VisiblePositionRange rightLineVisiblePositionRange(const VisiblePosition&) const;
408     VisiblePositionRange sentenceForPosition(const VisiblePosition&) const;
409     VisiblePositionRange paragraphForPosition(const VisiblePosition&) const;
410     VisiblePositionRange styleRangeForPosition(const VisiblePosition&) const;
411     VisiblePositionRange visiblePositionRangeForRange(const PlainTextRange&) const;
412
413     String stringForVisiblePositionRange(const VisiblePositionRange&) const;
414     virtual IntRect boundsForVisiblePositionRange(const VisiblePositionRange&) const { return IntRect(); }
415     int lengthForVisiblePositionRange(const VisiblePositionRange&) const;
416     virtual void setSelectedVisiblePositionRange(const VisiblePositionRange&) const { }
417
418     virtual VisiblePosition visiblePositionForPoint(const IntPoint&) const { return VisiblePosition(); }
419     VisiblePosition nextVisiblePosition(const VisiblePosition& visiblePos) const { return visiblePos.next(); }
420     VisiblePosition previousVisiblePosition(const VisiblePosition& visiblePos) const { return visiblePos.previous(); }
421     VisiblePosition nextWordEnd(const VisiblePosition&) const;
422     VisiblePosition previousWordStart(const VisiblePosition&) const;
423     VisiblePosition nextLineEndPosition(const VisiblePosition&) const;
424     VisiblePosition previousLineStartPosition(const VisiblePosition&) const;
425     VisiblePosition nextSentenceEndPosition(const VisiblePosition&) const;
426     VisiblePosition previousSentenceStartPosition(const VisiblePosition&) const;
427     VisiblePosition nextParagraphEndPosition(const VisiblePosition&) const;
428     VisiblePosition previousParagraphStartPosition(const VisiblePosition&) const;
429     virtual VisiblePosition visiblePositionForIndex(unsigned, bool /*lastIndexOK */) const { return VisiblePosition(); }
430     
431     virtual VisiblePosition visiblePositionForIndex(int) const { return VisiblePosition(); }
432     virtual int indexForVisiblePosition(const VisiblePosition&) const { return 0; }
433
434     AccessibilityObject* accessibilityObjectForPosition(const VisiblePosition&) const;
435     int lineForPosition(const VisiblePosition&) const;
436     PlainTextRange plainTextRangeForVisiblePositionRange(const VisiblePositionRange&) const;
437     virtual int index(const VisiblePosition&) const { return -1; }
438
439     virtual PlainTextRange doAXRangeForLine(unsigned) const { return PlainTextRange(); }
440     PlainTextRange doAXRangeForPosition(const IntPoint&) const;
441     virtual PlainTextRange doAXRangeForIndex(unsigned) const { return PlainTextRange(); }
442     PlainTextRange doAXStyleRangeForIndex(unsigned) const;
443
444     virtual String doAXStringForRange(const PlainTextRange&) const { return String(); }
445     virtual IntRect doAXBoundsForRange(const PlainTextRange&) const { return IntRect(); }
446     String listMarkerTextForNodeAndPosition(Node*, const VisiblePosition&) const;
447
448     unsigned doAXLineForIndex(unsigned);
449
450     virtual String stringValueForMSAA() const { return String(); }
451     virtual String stringRoleForMSAA() const { return String(); }
452     virtual String nameForMSAA() const { return String(); }
453     virtual String descriptionForMSAA() const { return String(); }
454
455 #if HAVE(ACCESSIBILITY)
456 #if PLATFORM(GTK)
457     AccessibilityObjectWrapper* wrapper() const;
458     void setWrapper(AccessibilityObjectWrapper*);
459 #else
460     AccessibilityObjectWrapper* wrapper() const { return m_wrapper.get(); }
461     void setWrapper(AccessibilityObjectWrapper* wrapper) 
462     {
463         m_wrapper = wrapper;
464     }
465 #endif
466 #endif
467
468     // a platform-specific method for determining if an attachment is ignored
469 #if HAVE(ACCESSIBILITY)
470     bool accessibilityIgnoreAttachment() const;
471 #else
472     bool accessibilityIgnoreAttachment() const { return true; }
473 #endif
474
475     // gives platforms the opportunity to indicate if and how an object should be included
476 #if HAVE(ACCESSIBILITY)
477     AccessibilityObjectPlatformInclusion accessibilityPlatformIncludesObject() const;
478 #else
479     AccessibilityObjectPlatformInclusion accessibilityPlatformIncludesObject() const { return DefaultBehavior; }
480 #endif
481
482     // allows for an AccessibilityObject to update its render tree or perform
483     // other operations update type operations
484     virtual void updateBackingStore() { }
485     
486 protected:
487     AXID m_id;
488     AccessibilityChildrenVector m_children;
489     mutable bool m_haveChildren;
490     AccessibilityRole m_role;
491     
492     virtual void clearChildren();
493     virtual bool isDetached() const { return true; }
494     RenderListItem* renderListItemContainerForNode(Node* node) const;
495     
496 #if PLATFORM(MAC)
497     RetainPtr<AccessibilityObjectWrapper> m_wrapper;
498 #elif PLATFORM(WIN) && !PLATFORM(WINCE)
499     COMPtr<AccessibilityObjectWrapper> m_wrapper;
500 #elif PLATFORM(GTK)
501     AtkObject* m_wrapper;
502 #elif PLATFORM(CHROMIUM)
503     RefPtr<AccessibilityObjectWrapper> m_wrapper;
504 #endif
505 };
506
507 } // namespace WebCore
508
509 #endif // AccessibilityObject_h