Clean up and extend QAccessible::State.

The state should contain useful and clear information.
Some of the old enum/bitfield members were not really clear.
Make them follow Qt terminology and shift the burden of interpreting
them to the bridge.

Apart from the previous commit changing from enum to bitfield, these
flags have changed names:

unavailable -> disabled
mixed -> checkStateMixed
protected -> passwordEdit (in the last commit)

floating is completely removed, even MSAA documentation states it is unsupported.

Some new states have been added.
Documentation added.

Change-Id: I152256e77a061f28ee5780f527524c80a2c7e333
Reviewed-by: Jan-Arve Sæther <jan-arve.saether@nokia.com>

8 files changed, 99 insertions, 48 deletions

diff --git a/src/gui/accessible/qaccessible.cpp b/src/gui/accessible/qaccessible.cpp
index edd4616446..de37f67943 100644
--- a/src/gui/accessible/qaccessible.cpp
+++ b/src/gui/accessible/qaccessible.cpp
@@ -120,48 +120,67 @@ QT_BEGIN_NAMESPACE
     \sa QAccessibleInterface
 */
 
+
 /*!
-    \enum QAccessible::StateFlag
+    \class QAccessible::State
 
-    This enum type defines bit flags that can be combined to indicate
+    This structure defines bit flags that indicate
     the state of an accessible object. The values are:
 
-    \value Animated         The object's appearance changes frequently.
-    \value Busy             The object cannot accept input at the moment.
-    \value Checked          The object's check box is checked.
-    \value Collapsed        The object is collapsed, e.g. a closed listview item, or an iconified window.
-    \value DefaultButton    The object represents the default button in a dialog.
-    \value Expandable       The object is expandable, mostly used for cells in a tree view.
-    \value Expanded         The object is expanded, currently its children are visible.
-    \value ExtSelectable    The object supports extended selection.
-    \value Focusable        The object can receive focus. Only objects in the active window can receive focus.
-    \value Focused          The object has keyboard focus.
-    \value HasPopup         The object opens a popup.
-    \value HotTracked       The object's appearance is sensitive to the mouse cursor position.
-    \value Invisible        The object is not visible to the user.
-    \value Linked           The object is linked to another object, e.g. a hyperlink.
-    \value Marqueed         The object displays scrolling contents, e.g. a log view.
-    \value Mixed            The state of the object is not determined, e.g. a tri-state check box that is neither checked nor unchecked.
-    \value Modal            The object blocks input from other objects.
-    \value Movable          The object can be moved.
-    \value MultiSelectable  The object supports multiple selected items.
-    \value Normal           The normal state.
-    \value Offscreen        The object is clipped by the visible area. Objects that are off screen are also invisible.
-    \value Pressed          The object is pressed.
-    \value Protected        The object is password protected, e.g. a line edit for entering a Password.
-    \value ReadOnly         The object can usually be edited, but is explicitly set to read-only.
-    \value Selectable       The object is selectable.
-    \value Selected         The object is selected.
-    \value SelfVoicing      The object describes itself through speech or sound.
-    \value Sizeable         The object can be resized, e.g. top-level windows.
-    \value Traversed        The object is linked and has been visited.
-    \value Unavailable      The object is unavailable to the user, e.g. a disabled widget.
+    \value active                  The object is the active window or the active sub-element in a container (that would get focus when focusing the container).
+    \value adjustable              The object represents an adjustable value, e.g. sliders.
+    \value animated                The object's appearance changes frequently.
+    \value busy                    The object cannot accept input at the moment.
+    \value checkable               The object is checkable.
+    \value checked                 The object's check box is checked.
+    \value checkStateMixed         The third state of checkboxes (half checked in tri-state check boxes).
+    \value collapsed               The object is collapsed, e.g. a closed listview item, or an iconified window.
+    \value defaultButton           The object represents the default button in a dialog.
+    \value defunct                 The object no longer exists.
+    \value editable                The object has a text carret (and often implements the text interface).
+    \value expandable              The object is expandable, mostly used for cells in a tree view.
+    \value expanded                The object is expanded, currently its children are visible.
+    \value extSelectable           The object supports extended selection.
+    \value focusable               The object can receive focus. Only objects in the active window can receive focus.
+    \value focused                 The object has keyboard focus.
+    \value hasPopup                The object opens a popup.
+    \value hotTracked              The object's appearance is sensitive to the mouse cursor position.
+    \value invalid                 The object is no longer valid (because it has been deleted).
+    \value invalidEntry            Input validation current input invalid.
+    \value invisible               The object is not visible to the user.
+    \value linked                  The object is linked to another object, e.g. a hyperlink.
+    \value marqueed                The object displays scrolling contents, e.g. a log view.
+    \value modal                   The object blocks input from other objects.
+    \value movable                 The object can be moved.
+    \value multiLine               The object has multiple lines of text (word wrap), as opposed to a single line.
+    \value multiSelectable         The object supports multiple selected items.
+    \value offscreen               The object is clipped by the visible area. Objects that are off screen are also invisible.
+    \value passwordEdit            The object is a password field, e.g. a line edit for entering a Password.
+    \value playsSound              The object produces sound when interacted with.
+    \value pressed                 The object is pressed.
+    \value readOnly                The object can usually be edited, but is explicitly set to read-only.
+    \value selectable              The object is selectable.
+    \value selectableText          The object has text which can be selected. This is different from selectable which refers to the object's children.
+    \value selected                The object is selected.
+    \value selfVoicing             The object describes itself through speech or sound.
+    \value sizeable                The object can be resized, e.g. top-level windows.
+    \value summaryElement          The object summarizes the state of the window and should be treated with priority.
+    \value supportsAutoCompletion  The object has auto-completion, for example in line edits or combo boxes.
+    \value traversed               The object is linked and has been visited.
+    \value updatesFrequently       The object changes frequently and needs to be refreshed when accessing it.
+    \value disabled                The object is unavailable to the user, e.g. a disabled widget.
 
     Implementations of QAccessibleInterface::state() return a combination
     of these flags.
 */
 
 /*!
+    \fn QAccessible::State::State()
+
+    Creates a new QAccessible::State with all states set to false.
+*/
+
+/*!
     \enum QAccessible::Event
 
     This enum type defines accessible event types.
diff --git a/src/gui/accessible/qaccessible.h b/src/gui/accessible/qaccessible.h
index 38f52fb2fd..bafd3a8a6b 100644
--- a/src/gui/accessible/qaccessible.h
+++ b/src/gui/accessible/qaccessible.h
@@ -151,19 +151,21 @@ public:
     // 64 bit enums seem hard on some platforms (windows...)
     // which makes using a bit field a sensible alternative
     struct State {
-        quint64 unavailable : 1;
+        // http://msdn.microsoft.com/en-us/library/ms697270.aspx
+        quint64 disabled : 1; // used to be Unavailable
         quint64 selected : 1;
+        quint64 focusable : 1;
         quint64 focused : 1;
         quint64 pressed : 1;
+        quint64 checkable : 1;
         quint64 checked : 1;
-        quint64 mixed : 1;
+        quint64 checkStateMixed : 1; // used to be Mixed
         quint64 readOnly : 1;
         quint64 hotTracked : 1;
         quint64 defaultButton : 1;
         quint64 expanded : 1;
         quint64 collapsed : 1;
         quint64 busy : 1;
-        //       quint64 Floating : 1;
         quint64 expandable : 1;
         quint64 marqueed : 1;
         quint64 animated : 1;
@@ -172,24 +174,54 @@ public:
         quint64 sizeable : 1;
         quint64 movable : 1;
         quint64 selfVoicing : 1;
-        quint64 focusable : 1;
         quint64 selectable : 1;
         quint64 linked : 1;
         quint64 traversed : 1;
         quint64 multiSelectable : 1;
         quint64 extSelectable : 1;
-        //       quint64 alertLow : 1;
-        //       quint64 alertMedium : 1;
-        //       quint64 alertHigh : 1;
-        quint64 passwordEdit : 1;
+        quint64 passwordEdit : 1; // used to be Protected
         quint64 hasPopup : 1;
         quint64 modal : 1;
 
+        // IA2 - we chose to not add some IA2 states for now
+        // Below the ones that seem helpful
+        quint64 active : 1;
+        quint64 invalid : 1; // = defunct
+        quint64 editable : 1;
+        quint64 multiLine : 1;
+        quint64 selectableText : 1;
+        quint64 supportsAutoCompletion : 1;
+
+        // quint64 horizontal : 1;
+        // quint64 vertical : 1;
+        // quint64 invalidEntry : 1;
+        // quint64 managesDescendants : 1;
+        // quint64 singleLine : 1; // we have multi line, this is redundant.
+        // quint64 stale : 1;
+        // quint64 transient : 1;
+        // quint64 pinned : 1;
+
+        // Apple - see http://mattgemmell.com/2010/12/19/accessibility-for-iphone-and-ipad-apps/
+        // quint64 playsSound : 1;
+        // quint64 summaryElement : 1;
+        // quint64 updatesFrequently : 1;
+        // quint64 adjustable : 1;
+        // more and not included here: http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Attributes.html
+
+        // MSAA
+        // quint64 alertLow : 1;
+        // quint64 alertMedium : 1;
+        // quint64 alertHigh : 1;
+
         State() {
             qMemSet(this, 0, sizeof(State));
         }
     };
 
+
+
+
+
     enum Role {
         NoRole         = 0x00000000,
         TitleBar       = 0x00000001,
diff --git a/src/plugins/accessible/widgets/qaccessiblemenu.cpp b/src/plugins/accessible/widgets/qaccessiblemenu.cpp
index 77157d1b62..fcd118e745 100644
--- a/src/plugins/accessible/widgets/qaccessiblemenu.cpp
+++ b/src/plugins/accessible/widgets/qaccessiblemenu.cpp
@@ -273,7 +273,7 @@ QAccessible::State QAccessibleMenuItem::state() const
     if (own->style()->styleHint(QStyle::SH_Menu_MouseTracking))
         s.hotTracked = true;
     if (m_action->isSeparator() || !m_action->isEnabled())
-        s.unavailable = true;
+        s.disabled = true;
     if (m_action->isChecked())
         s.checked = true;
 
diff --git a/src/plugins/accessible/widgets/qaccessiblewidgets.cpp b/src/plugins/accessible/widgets/qaccessiblewidgets.cpp
index bb744232f4..ffd87dd834 100644
--- a/src/plugins/accessible/widgets/qaccessiblewidgets.cpp
+++ b/src/plugins/accessible/widgets/qaccessiblewidgets.cpp
@@ -714,7 +714,7 @@ QAccessible::State QAccessibleMdiSubWindow::state() const
     if (!mdiSubWindow()->parentWidget()->contentsRect().contains(mdiSubWindow()->geometry()))
         state.offscreen = true;
     if (!mdiSubWindow()->isEnabled())
-        state.unavailable = true;
+        state.disabled = true;
     return state;
 }
 
@@ -1035,7 +1035,7 @@ QAccessible::State QAccessibleTitleBar::state() const
     if (w->hasFocus())
         state.focused = true;
     if (!w->isEnabled())
-        state.unavailable = true;
+        state.disabled = true;
 
     return state;
 }
diff --git a/src/plugins/accessible/widgets/simplewidgets.cpp b/src/plugins/accessible/widgets/simplewidgets.cpp
index 74e9645693..d645ad2d22 100644
--- a/src/plugins/accessible/widgets/simplewidgets.cpp
+++ b/src/plugins/accessible/widgets/simplewidgets.cpp
@@ -142,7 +142,7 @@ QAccessible::State QAccessibleButton::state() const
     if (b->isChecked())
         state.checked = true;
     else if (cb && cb->checkState() == Qt::PartiallyChecked)
-        state.mixed = true;
+        state.checkStateMixed = true;
     if (b->isDown())
         state.pressed = true;
     QPushButton *pb = qobject_cast<QPushButton*>(b);
diff --git a/src/plugins/platforms/windows/qwindowsaccessibility.cpp b/src/plugins/platforms/windows/qwindowsaccessibility.cpp
index 4de4294e8f..fdf6c9116e 100644
--- a/src/plugins/platforms/windows/qwindowsaccessibility.cpp
+++ b/src/plugins/platforms/windows/qwindowsaccessibility.cpp
@@ -1093,7 +1093,7 @@ HRESULT STDMETHODCALLTYPE QWindowsAccessible::get_accState(VARIANT varID, VARIAN
         st |= STATE_SYSTEM_LINKED;
     if (state.marqueed)
         st |= STATE_SYSTEM_MARQUEED;
-    if (state.mixed)
+    if (state.checkStateMixed)
         st |= STATE_SYSTEM_MIXED;
     if (state.movable)
         st |= STATE_SYSTEM_MOVEABLE;
diff --git a/src/widgets/accessible/qaccessiblewidget.cpp b/src/widgets/accessible/qaccessiblewidget.cpp
index 3c215ba64c..ae09b011dd 100644
--- a/src/widgets/accessible/qaccessiblewidget.cpp
+++ b/src/widgets/accessible/qaccessiblewidget.cpp
@@ -706,7 +706,7 @@ QAccessible::State QAccessibleWidget::state() const
     if (w->hasFocus())
         state.focused = true;
     if (!w->isEnabled())
-        state.unavailable = true;
+        state.disabled = true;
     if (w->isWindow()) {
         if (w->windowFlags() & Qt::WindowSystemMenuHint)
             state.movable = true;
diff --git a/tests/auto/other/qaccessibility/tst_qaccessibility.cpp b/tests/auto/other/qaccessibility/tst_qaccessibility.cpp
index 3190ef74eb..90ab5b4c67 100644
--- a/tests/auto/other/qaccessibility/tst_qaccessibility.cpp
+++ b/tests/auto/other/qaccessibility/tst_qaccessibility.cpp
@@ -466,7 +466,7 @@ void tst_QAccessibility::deletedWidget()
 void tst_QAccessibility::statesStructTest()
 {
     QAccessible::State s1;
-    QVERIFY(s1.unavailable == 0);
+    QVERIFY(s1.disabled == 0);
     QVERIFY(s1.focusable == 0);
     QVERIFY(s1.modal == 0);
 
@@ -1741,7 +1741,7 @@ void tst_QAccessibility::mdiSubWindowTest()
     QVERIFY(interface->state().invisible);
     testWindow->setVisible(true);
     testWindow->setEnabled(false);
-    QVERIFY(interface->state().unavailable);
+    QVERIFY(interface->state().disabled);
     testWindow->setEnabled(true);
     qApp->setActiveWindow(&mdiArea);
     mdiArea.setActiveSubWindow(testWindow);