source/modules/juce_gui_basics/native/accessibility/juce_win32_AccessibilityElement.cpp

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    By using JUCE, you agree to the terms of both the JUCE 7 End-User License
  11    Agreement and JUCE Privacy Policy.
  12
  13    End User License Agreement: www.juce.com/juce-7-licence
  14    Privacy Policy: www.juce.com/juce-privacy-policy
  15
  16    Or: You may also use this code under the terms of the GPL v3 (see
  17    www.gnu.org/licenses).
  18
  19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  21    DISCLAIMED.
  22
  23   ==============================================================================
  24 */
  25
  26 namespace juce
  27 {
  28
  29 JUCE_BEGIN_IGNORE_WARNINGS_GCC_LIKE ("-Wlanguage-extension-token")
  30
  31 int AccessibilityNativeHandle::idCounter = 0;
  32
  33 //==============================================================================
  34 static String getAutomationId (const AccessibilityHandler& handler)
  35 {
  36     auto result = handler.getTitle();
  37     auto* parentComponent = handler.getComponent().getParentComponent();
  38
  39     while (parentComponent != nullptr)
  40     {
  41         if (auto* parentHandler = parentComponent->getAccessibilityHandler())
  42         {
  43             auto parentTitle = parentHandler->getTitle();
  44             result << "." << (parentTitle.isNotEmpty() ? parentTitle : "<empty>");
  45         }
  46
  47         parentComponent = parentComponent->getParentComponent();
  48     }
  49
  50     return result;
  51 }
  52
  53 static auto roleToControlTypeId (AccessibilityRole roleType)
  54 {
  55     switch (roleType)
  56     {
  57         case AccessibilityRole::popupMenu:
  58         case AccessibilityRole::dialogWindow:
  59         case AccessibilityRole::splashScreen:
  60         case AccessibilityRole::window:        return ComTypes::UIA_WindowControlTypeId;
  61
  62         case AccessibilityRole::label:
  63         case AccessibilityRole::staticText:    return ComTypes::UIA_TextControlTypeId;
  64
  65         case AccessibilityRole::column:
  66         case AccessibilityRole::row:           return ComTypes::UIA_HeaderItemControlTypeId;
  67
  68         case AccessibilityRole::button:        return ComTypes::UIA_ButtonControlTypeId;
  69         case AccessibilityRole::toggleButton:  return ComTypes::UIA_CheckBoxControlTypeId;
  70         case AccessibilityRole::radioButton:   return ComTypes::UIA_RadioButtonControlTypeId;
  71         case AccessibilityRole::comboBox:      return ComTypes::UIA_ComboBoxControlTypeId;
  72         case AccessibilityRole::image:         return ComTypes::UIA_ImageControlTypeId;
  73         case AccessibilityRole::slider:        return ComTypes::UIA_SliderControlTypeId;
  74         case AccessibilityRole::editableText:  return ComTypes::UIA_EditControlTypeId;
  75         case AccessibilityRole::menuItem:      return ComTypes::UIA_MenuItemControlTypeId;
  76         case AccessibilityRole::menuBar:       return ComTypes::UIA_MenuBarControlTypeId;
  77         case AccessibilityRole::table:         return ComTypes::UIA_TableControlTypeId;
  78         case AccessibilityRole::tableHeader:   return ComTypes::UIA_HeaderControlTypeId;
  79         case AccessibilityRole::cell:          return ComTypes::UIA_DataItemControlTypeId;
  80         case AccessibilityRole::hyperlink:     return ComTypes::UIA_HyperlinkControlTypeId;
  81         case AccessibilityRole::list:          return ComTypes::UIA_ListControlTypeId;
  82         case AccessibilityRole::listItem:      return ComTypes::UIA_ListItemControlTypeId;
  83         case AccessibilityRole::tree:          return ComTypes::UIA_TreeControlTypeId;
  84         case AccessibilityRole::treeItem:      return ComTypes::UIA_TreeItemControlTypeId;
  85         case AccessibilityRole::progressBar:   return ComTypes::UIA_ProgressBarControlTypeId;
  86         case AccessibilityRole::group:         return ComTypes::UIA_GroupControlTypeId;
  87         case AccessibilityRole::scrollBar:     return ComTypes::UIA_ScrollBarControlTypeId;
  88         case AccessibilityRole::tooltip:       return ComTypes::UIA_ToolTipControlTypeId;
  89
  90         case AccessibilityRole::ignored:
  91         case AccessibilityRole::unspecified:   break;
  92     };
  93
  94     return ComTypes::UIA_CustomControlTypeId;
  95 }
  96
  97 //==============================================================================
  98 AccessibilityNativeHandle::AccessibilityNativeHandle (AccessibilityHandler& handler)
  99     : ComBaseClassHelper (0),
 100       accessibilityHandler (handler)
 101 {
 102 }
 103
 104 //==============================================================================
 105 JUCE_COMRESULT AccessibilityNativeHandle::QueryInterface (REFIID refId, void** result)
 106 {
 107     *result = nullptr;
 108
 109     if (! isElementValid())
 110         return (HRESULT) UIA_E_ELEMENTNOTAVAILABLE;
 111
 112     if ((refId == __uuidof (ComTypes::IRawElementProviderFragmentRoot) && ! isFragmentRoot()))
 113         return E_NOINTERFACE;
 114
 115     return ComBaseClassHelper::QueryInterface (refId, result);
 116 }
 117
 118 //==============================================================================
 119 JUCE_COMRESULT AccessibilityNativeHandle::get_HostRawElementProvider (IRawElementProviderSimple** pRetVal)
 120 {
 121     return withCheckedComArgs (pRetVal, *this, [&]
 122     {
 123         if (isFragmentRoot())
 124             if (auto* wrapper = WindowsUIAWrapper::getInstanceWithoutCreating())
 125                 return wrapper->hostProviderFromHwnd ((HWND) accessibilityHandler.getComponent().getWindowHandle(), pRetVal);
 126
 127         return S_OK;
 128     });
 129 }
 130
 131 JUCE_COMRESULT AccessibilityNativeHandle::get_ProviderOptions (ProviderOptions* options)
 132 {
 133     if (options == nullptr)
 134         return E_INVALIDARG;
 135
 136     *options = (ProviderOptions) (ProviderOptions_ServerSideProvider | ProviderOptions_UseComThreading);
 137     return S_OK;
 138 }
 139
 140 JUCE_COMRESULT AccessibilityNativeHandle::GetPatternProvider (PATTERNID pId, IUnknown** pRetVal)
 141 {
 142     return withCheckedComArgs (pRetVal, *this, [&]
 143     {
 144         *pRetVal = [&]() -> IUnknown*
 145         {
 146             const auto role = accessibilityHandler.getRole();
 147             const auto fragmentRoot = isFragmentRoot();
 148
 149             switch (pId)
 150             {
 151                 case ComTypes::UIA_WindowPatternId:
 152                 {
 153                     if (fragmentRoot)
 154                         return new UIAWindowProvider (this);
 155
 156                     break;
 157                 }
 158                 case ComTypes::UIA_TransformPatternId:
 159                 {
 160                     if (fragmentRoot)
 161                         return new UIATransformProvider (this);
 162
 163                     break;
 164                 }
 165                 case ComTypes::UIA_TextPatternId:
 166                 case ComTypes::UIA_TextPattern2Id:
 167                 {
 168                     if (accessibilityHandler.getTextInterface() != nullptr)
 169                         return new UIATextProvider (this);
 170
 171                     break;
 172                 }
 173                 case ComTypes::UIA_ValuePatternId:
 174                 {
 175                     if (accessibilityHandler.getValueInterface() != nullptr)
 176                         return new UIAValueProvider (this);
 177
 178                     break;
 179                 }
 180                 case ComTypes::UIA_RangeValuePatternId:
 181                 {
 182                     if (accessibilityHandler.getValueInterface() != nullptr
 183                         && accessibilityHandler.getValueInterface()->getRange().isValid())
 184                     {
 185                         return new UIARangeValueProvider (this);
 186                     }
 187
 188                     break;
 189                 }
 190                 case ComTypes::UIA_TogglePatternId:
 191                 {
 192                     if (accessibilityHandler.getCurrentState().isCheckable()
 193                         && (accessibilityHandler.getActions().contains (AccessibilityActionType::toggle)
 194                             || accessibilityHandler.getActions().contains (AccessibilityActionType::press)))
 195                     {
 196                         return new UIAToggleProvider (this);
 197                     }
 198
 199                     break;
 200                 }
 201                 case ComTypes::UIA_SelectionPatternId:
 202                 {
 203                     if (role == AccessibilityRole::list
 204                         || role == AccessibilityRole::popupMenu
 205                         || role == AccessibilityRole::tree)
 206                     {
 207                         return new UIASelectionProvider (this);
 208                     }
 209
 210                     break;
 211                 }
 212                 case ComTypes::UIA_SelectionItemPatternId:
 213                 {
 214                     auto state = accessibilityHandler.getCurrentState();
 215
 216                     if (state.isSelectable() || state.isMultiSelectable()
 217                         || role == AccessibilityRole::radioButton)
 218                     {
 219                         return new UIASelectionItemProvider (this);
 220                     }
 221
 222                     break;
 223                 }
 224                 case ComTypes::UIA_GridPatternId:
 225                 {
 226                     if (accessibilityHandler.getTableInterface() != nullptr)
 227                         return new UIAGridProvider (this);
 228
 229                     break;
 230                 }
 231                 case ComTypes::UIA_GridItemPatternId:
 232                 {
 233                     if (accessibilityHandler.getCellInterface() != nullptr)
 234                         return new UIAGridItemProvider (this);
 235
 236                     break;
 237                 }
 238                 case ComTypes::UIA_InvokePatternId:
 239                 {
 240                     if (accessibilityHandler.getActions().contains (AccessibilityActionType::press))
 241                         return new UIAInvokeProvider (this);
 242
 243                     break;
 244                 }
 245                 case ComTypes::UIA_ExpandCollapsePatternId:
 246                 {
 247                     if (accessibilityHandler.getActions().contains (AccessibilityActionType::showMenu)
 248                         && accessibilityHandler.getCurrentState().isExpandable())
 249                         return new UIAExpandCollapseProvider (this);
 250
 251                     break;
 252                 }
 253             }
 254
 255             return nullptr;
 256         }();
 257
 258         return S_OK;
 259     });
 260 }
 261
 262 JUCE_COMRESULT AccessibilityNativeHandle::GetPropertyValue (PROPERTYID propertyId, VARIANT* pRetVal)
 263 {
 264     return withCheckedComArgs (pRetVal, *this, [&]
 265     {
 266         VariantHelpers::clear (pRetVal);
 267
 268         const auto role    = accessibilityHandler.getRole();
 269         const auto state   = accessibilityHandler.getCurrentState();
 270         const auto ignored = accessibilityHandler.isIgnored();
 271
 272         switch (propertyId)
 273         {
 274             case UIA_AutomationIdPropertyId:
 275                 VariantHelpers::setString (getAutomationId (accessibilityHandler), pRetVal);
 276                 break;
 277             case UIA_ControlTypePropertyId:
 278                 VariantHelpers::setInt (roleToControlTypeId (role), pRetVal);
 279                 break;
 280             case UIA_FrameworkIdPropertyId:
 281                 VariantHelpers::setString ("JUCE", pRetVal);
 282                 break;
 283             case UIA_FullDescriptionPropertyId:
 284                 VariantHelpers::setString (accessibilityHandler.getDescription(), pRetVal);
 285                 break;
 286             case UIA_HelpTextPropertyId:
 287                 VariantHelpers::setString (accessibilityHandler.getHelp(), pRetVal);
 288                 break;
 289             case UIA_IsContentElementPropertyId:
 290                 VariantHelpers::setBool (! ignored && accessibilityHandler.isVisibleWithinParent(),
 291                                          pRetVal);
 292                 break;
 293             case UIA_IsControlElementPropertyId:
 294                 VariantHelpers::setBool (true, pRetVal);
 295                 break;
 296             case UIA_IsDialogPropertyId:
 297                 VariantHelpers::setBool (role == AccessibilityRole::dialogWindow, pRetVal);
 298                 break;
 299             case UIA_IsEnabledPropertyId:
 300                 VariantHelpers::setBool (accessibilityHandler.getComponent().isEnabled(), pRetVal);
 301                 break;
 302             case UIA_IsKeyboardFocusablePropertyId:
 303                 VariantHelpers::setBool (state.isFocusable(), pRetVal);
 304                 break;
 305             case UIA_HasKeyboardFocusPropertyId:
 306                 VariantHelpers::setBool (accessibilityHandler.hasFocus (true), pRetVal);
 307                 break;
 308             case UIA_IsOffscreenPropertyId:
 309                 VariantHelpers::setBool (! accessibilityHandler.isVisibleWithinParent(), pRetVal);
 310                 break;
 311             case UIA_IsPasswordPropertyId:
 312                 if (auto* textInterface = accessibilityHandler.getTextInterface())
 313                     VariantHelpers::setBool (textInterface->isDisplayingProtectedText(), pRetVal);
 314
 315                 break;
 316             case ComTypes::UIA_IsPeripheralPropertyId:
 317                 VariantHelpers::setBool (role == AccessibilityRole::tooltip
 318                                          || role == AccessibilityRole::popupMenu
 319                                          || role == AccessibilityRole::splashScreen,
 320                                          pRetVal);
 321                 break;
 322             case UIA_NamePropertyId:
 323                 if (! ignored)
 324                      VariantHelpers::setString (getElementName(), pRetVal);
 325
 326                 break;
 327             case UIA_ProcessIdPropertyId:
 328                 VariantHelpers::setInt ((int) GetCurrentProcessId(), pRetVal);
 329                 break;
 330             case UIA_NativeWindowHandlePropertyId:
 331                 if (isFragmentRoot())
 332                     VariantHelpers::setInt ((int) (pointer_sized_int) accessibilityHandler.getComponent().getWindowHandle(), pRetVal);
 333
 334                 break;
 335         }
 336
 337         return S_OK;
 338     });
 339 }
 340
 341 //==============================================================================
 342 JUCE_COMRESULT AccessibilityNativeHandle::Navigate (ComTypes::NavigateDirection direction, ComTypes::IRawElementProviderFragment** pRetVal)
 343 {
 344     return withCheckedComArgs (pRetVal, *this, [&]
 345     {
 346         auto* handler = [&]() -> AccessibilityHandler*
 347         {
 348             if (direction == ComTypes::NavigateDirection_Parent)
 349                 return accessibilityHandler.getParent();
 350
 351             if (direction == ComTypes::NavigateDirection_FirstChild
 352                 || direction == ComTypes::NavigateDirection_LastChild)
 353             {
 354                 auto children = accessibilityHandler.getChildren();
 355
 356                 return children.empty() ? nullptr
 357                                         : (direction == ComTypes::NavigateDirection_FirstChild ? children.front()
 358                                                                                                : children.back());
 359             }
 360
 361             if (direction == ComTypes::NavigateDirection_NextSibling
 362                 || direction == ComTypes::NavigateDirection_PreviousSibling)
 363             {
 364                 if (auto* parent = accessibilityHandler.getParent())
 365                 {
 366                     const auto siblings = parent->getChildren();
 367                     const auto iter = std::find (siblings.cbegin(), siblings.cend(), &accessibilityHandler);
 368
 369                     if (iter == siblings.end())
 370                         return nullptr;
 371
 372                     if (direction == ComTypes::NavigateDirection_NextSibling && iter != std::prev (siblings.cend()))
 373                         return *std::next (iter);
 374
 375                     if (direction == ComTypes::NavigateDirection_PreviousSibling && iter != siblings.cbegin())
 376                         return *std::prev (iter);
 377                 }
 378             }
 379
 380             return nullptr;
 381         }();
 382
 383         if (handler != nullptr)
 384             if (auto* provider = handler->getNativeImplementation())
 385                 if (provider->isElementValid())
 386                     provider->QueryInterface (IID_PPV_ARGS (pRetVal));
 387
 388         return S_OK;
 389     });
 390 }
 391
 392 JUCE_COMRESULT AccessibilityNativeHandle::GetRuntimeId (SAFEARRAY** pRetVal)
 393 {
 394     return withCheckedComArgs (pRetVal, *this, [&]
 395     {
 396         if (! isFragmentRoot())
 397         {
 398             *pRetVal = SafeArrayCreateVector (VT_I4, 0, 2);
 399
 400             if (*pRetVal == nullptr)
 401                 return E_OUTOFMEMORY;
 402
 403             for (LONG i = 0; i < 2; ++i)
 404             {
 405                 auto hr = SafeArrayPutElement (*pRetVal, &i, &rtid[(size_t) i]);
 406
 407                 if (FAILED (hr))
 408                     return E_FAIL;
 409             }
 410         }
 411
 412         return S_OK;
 413     });
 414 }
 415
 416 JUCE_COMRESULT AccessibilityNativeHandle::get_BoundingRectangle (ComTypes::UiaRect* pRetVal)
 417 {
 418     return withCheckedComArgs (pRetVal, *this, [&]
 419     {
 420         auto bounds = Desktop::getInstance().getDisplays()
 421                         .logicalToPhysical (accessibilityHandler.getComponent().getScreenBounds());
 422
 423         pRetVal->left   = bounds.getX();
 424         pRetVal->top    = bounds.getY();
 425         pRetVal->width  = bounds.getWidth();
 426         pRetVal->height = bounds.getHeight();
 427
 428         return S_OK;
 429     });
 430 }
 431
 432 JUCE_COMRESULT AccessibilityNativeHandle::GetEmbeddedFragmentRoots (SAFEARRAY** pRetVal)
 433 {
 434     return withCheckedComArgs (pRetVal, *this, []
 435     {
 436         return S_OK;
 437     });
 438 }
 439
 440 JUCE_COMRESULT AccessibilityNativeHandle::SetFocus()
 441 {
 442     if (! isElementValid())
 443         return (HRESULT) UIA_E_ELEMENTNOTAVAILABLE;
 444
 445     const WeakReference<Component> safeComponent (&accessibilityHandler.getComponent());
 446
 447     accessibilityHandler.getActions().invoke (AccessibilityActionType::focus);
 448
 449     if (safeComponent != nullptr)
 450         accessibilityHandler.grabFocus();
 451
 452     return S_OK;
 453 }
 454
 455 JUCE_COMRESULT AccessibilityNativeHandle::get_FragmentRoot (ComTypes::IRawElementProviderFragmentRoot** pRetVal)
 456 {
 457     return withCheckedComArgs (pRetVal, *this, [&]() -> HRESULT
 458     {
 459         auto* handler = [&]() -> AccessibilityHandler*
 460         {
 461             if (isFragmentRoot())
 462                 return &accessibilityHandler;
 463
 464             if (auto* peer = accessibilityHandler.getComponent().getPeer())
 465                 return peer->getComponent().getAccessibilityHandler();
 466
 467             return nullptr;
 468         }();
 469
 470         if (handler != nullptr)
 471         {
 472             handler->getNativeImplementation()->QueryInterface (IID_PPV_ARGS (pRetVal));
 473             return S_OK;
 474         }
 475
 476         return (HRESULT) UIA_E_ELEMENTNOTAVAILABLE;
 477     });
 478 }
 479
 480 //==============================================================================
 481 JUCE_COMRESULT AccessibilityNativeHandle::ElementProviderFromPoint (double x, double y, ComTypes::IRawElementProviderFragment** pRetVal)
 482 {
 483     return withCheckedComArgs (pRetVal, *this, [&]
 484     {
 485         auto* handler = [&]
 486         {
 487             auto logicalScreenPoint = Desktop::getInstance().getDisplays()
 488                                         .physicalToLogical (Point<int> (roundToInt (x),
 489                                                                         roundToInt (y)));
 490
 491             if (auto* child = accessibilityHandler.getChildAt (logicalScreenPoint))
 492                 return child;
 493
 494             return &accessibilityHandler;
 495         }();
 496
 497         handler->getNativeImplementation()->QueryInterface (IID_PPV_ARGS (pRetVal));
 498
 499         return S_OK;
 500     });
 501 }
 502
 503 JUCE_COMRESULT AccessibilityNativeHandle::GetFocus (ComTypes::IRawElementProviderFragment** pRetVal)
 504 {
 505     return withCheckedComArgs (pRetVal, *this, [&]
 506     {
 507         const auto getFocusHandler = [this]() -> AccessibilityHandler*
 508         {
 509             if (auto* modal = Component::getCurrentlyModalComponent())
 510             {
 511                 const auto& component = accessibilityHandler.getComponent();
 512
 513                 if (! component.isParentOf (modal)
 514                      && component.isCurrentlyBlockedByAnotherModalComponent())
 515                 {
 516                     if (auto* modalHandler = modal->getAccessibilityHandler())
 517                     {
 518                         if (auto* focusChild = modalHandler->getChildFocus())
 519                             return focusChild;
 520
 521                         return modalHandler;
 522                     }
 523                 }
 524             }
 525
 526             if (auto* focusChild = accessibilityHandler.getChildFocus())
 527                 return focusChild;
 528
 529             return nullptr;
 530         };
 531
 532         if (auto* focusHandler = getFocusHandler())
 533             focusHandler->getNativeImplementation()->QueryInterface (IID_PPV_ARGS (pRetVal));
 534
 535         return S_OK;
 536     });
 537 }
 538
 539 //==============================================================================
 540 String AccessibilityNativeHandle::getElementName() const
 541 {
 542     if (accessibilityHandler.getRole() == AccessibilityRole::tooltip)
 543         return accessibilityHandler.getDescription();
 544
 545     auto name = accessibilityHandler.getTitle();
 546
 547     if (name.isEmpty() && isFragmentRoot())
 548         return getAccessibleApplicationOrPluginName();
 549
 550     return name;
 551 }
 552
 553 JUCE_END_IGNORE_WARNINGS_GCC_LIKE
 554
 555 } // namespace juce