GenericAccessibleInterfaces.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "Async/TaskGraphInterfaces.h"
#include "Containers/Array.h"
#include "Containers/Map.h"
#include "Containers/StringFwd.h"
#include "Containers/UnrealString.h"
#include "CoreMinimal.h"
#include "Delegates/Delegate.h"
#include "HAL/Platform.h"
#include "Logging/LogMacros.h"
#include "Math/Box2D.h"
#include "Misc/Variant.h"
#include "Stats/Stats.h"
#include "Templates/Function.h"
#include "Templates/SharedPointer.h"
 
enum class EAccessibleBehavior : uint8
{
    NotAccessible,
    Auto,
    Summary,
    Custom,
    ToolTip
};
 
APPLICATIONCORE_API DECLARE_LOG_CATEGORY_EXTERN(LogAccessibility, Log, All);
 
#if WITH_ACCESSIBILITY
 
class FGenericWindow;
class IAccessibleWidget;
 
DECLARE_STATS_GROUP(TEXT("Accessibility"), STATGROUP_Accessibility, STATCAT_Advanced);
 
enum class EAccessibleWidgetType : uint8
{
    Unknown,
    Button,
    CheckBox,
    ComboBox,
    Hyperlink,
    Image,
    Layout,
    ScrollBar,
    Slider,
    Text,
    TextEdit,
    Window,
    List,
    ListItem
};
 
enum class EAccessibleEvent : uint8
{
    FocusChange,
    Activate,
    Notification,
    ParentChanged,
    WidgetRemoved
};
 
typedef int32 FAccessibleUserIndex;
 
class FGenericAccessibleUser
{
    friend class FGenericAccessibleUserRegistry;
public:
    FGenericAccessibleUser(const FAccessibleUserIndex InUserIndex)
        : UserIndex(InUserIndex)
    {
        
    }
    virtual ~FGenericAccessibleUser() = default;
    FAccessibleUserIndex GetIndex() const
    {
        return UserIndex;
    }
    TSharedPtr<IAccessibleWidget> GetFocusedAccessibleWidget() const
    {
        return FocusedAccessibleWidget.IsValid() ? FocusedAccessibleWidget.Pin() : nullptr;
    }
    bool SetFocusedAccessibleWidget(const TSharedRef<IAccessibleWidget>& InWidget)
    {
        FocusedAccessibleWidget = InWidget;
        return true;
    }
    void ClearFocusedAccessibleWidget()
    {
        FocusedAccessibleWidget.Reset();
    }
protected:
    virtual void OnRegistered() {}
    virtual void OnUnregistered() {}
    
private:
    FAccessibleUserIndex UserIndex;
    TWeakPtr<IAccessibleWidget> FocusedAccessibleWidget;
};
 
class FGenericAccessibleUserRegistry
{
public:
    virtual ~FGenericAccessibleUserRegistry() = default;
    APPLICATIONCORE_API bool RegisterUser(const TSharedRef<FGenericAccessibleUser>& User);
    APPLICATIONCORE_API bool UnregisterUser(const FAccessibleUserIndex UserIndex);
    APPLICATIONCORE_API void UnregisterAllUsers();
    APPLICATIONCORE_API bool IsUserRegistered(const FAccessibleUserIndex UserIndex) const;
    APPLICATIONCORE_API TSharedPtr<FGenericAccessibleUser> GetUser(const FAccessibleUserIndex UserIndex) const;
    APPLICATIONCORE_API int32 GetNumberofUsers() const;
    APPLICATIONCORE_API TArray<TSharedRef<FGenericAccessibleUser>> GetAllUsers() const;
    static FAccessibleUserIndex GetPrimaryUserIndex()
    {
        // @TODOAccessibility: Consider allowing remapping of primary user index
        static const FAccessibleUserIndex PrimaryUserIndex = 0;
        return PrimaryUserIndex;
    }
protected:
    TMap<FAccessibleUserIndex, TSharedRef<FGenericAccessibleUser>> UsersMap;
};
 
class IAccessibleWindow
{
public:
    enum class EWindowDisplayState
    {
        Normal,
        Minimize,
        Maximize
    };
 
    virtual TSharedPtr<FGenericWindow> GetNativeWindow() const = 0;
 
    virtual TSharedPtr<IAccessibleWidget> GetChildAtPosition(int32 X, int32 Y) = 0;
    virtual TSharedPtr<IAccessibleWidget> GetUserFocusedWidget(const FAccessibleUserIndex UserIndex) const = 0;
    virtual void Close() = 0;
 
    virtual bool SupportsDisplayState(EWindowDisplayState State) const = 0;
    virtual EWindowDisplayState GetDisplayState() const = 0;
    virtual void SetDisplayState(EWindowDisplayState State) = 0;
    virtual bool IsModal() const = 0;
};
 
class IAccessibleActivatable
{
public:
    virtual void Activate() = 0;
    virtual bool IsCheckable() const { return false; }
    virtual bool GetCheckedState() const { return false; }
};
 
class IAccessibleProperty
{
public:
    virtual bool IsReadOnly() const { return true; }
    virtual bool IsPassword() const { return false; }
    virtual float GetStepSize() const { return 0.0f; }
    virtual float GetMaximum() const { return 0.0f; }
    virtual float GetMinimum() const { return 0.0f; }
    virtual FString GetValue() const = 0;
    virtual FVariant GetValueAsVariant() const { return FVariant(); }
    /*
     * Set the value stored by the widget. While this function accepts a String, there is no way to know
     * what the underlying data is stored as. The platform layer must retain some additional information
     * about what kind of widget this is, and ensure it's being called with valid arguments.
     *
     * @param Value The new value to assign to the widget, which may need to be converted before assigning to a variable.
     */
    virtual void SetValue(const FString& Value) {}
};
 
class IAccessibleText
{
public:
    virtual const FString& GetText() const = 0;
};
 
class IAccessibleTable
{
public: 
    virtual TArray<TSharedPtr<IAccessibleWidget>> GetSelectedItems() const { return TArray < TSharedPtr<IAccessibleWidget>>(); }
 
    virtual bool CanSupportMultiSelection() const { return false; }
 
    virtual bool IsSelectionRequired() const { return false; }
};
 
class IAccessibleTableRow
{
public:
    virtual void Select() {}
 
    virtual void AddToSelection() {}
 
    virtual void RemoveFromSelection() {}
 
    virtual bool IsSelected() const { return false; }
 
    virtual TSharedPtr<IAccessibleWidget> GetOwningTable() const { return nullptr; }
};
 
typedef int32 AccessibleWidgetId; 
 
class IAccessibleWidget : public TSharedFromThis<IAccessibleWidget>
{
public:
    IAccessibleWidget() {}
    virtual ~IAccessibleWidget() {}
 
    static const AccessibleWidgetId InvalidAccessibleWidgetId = -1;
 
    virtual AccessibleWidgetId GetId() const = 0;
    virtual bool IsValid() const = 0;
 
    virtual TSharedPtr<IAccessibleWidget> GetWindow() const = 0;
    virtual FBox2D GetBounds() const = 0;
    virtual TSharedPtr<IAccessibleWidget> GetParent() = 0;
    template<typename PredicateType>
    static TSharedPtr<IAccessibleWidget> SearchForAncestorFrom(const TSharedRef<IAccessibleWidget>& Source, PredicateType Predicate)
    {
        TSharedPtr<IAccessibleWidget> Ancestor = Source->GetParent();
        while (Ancestor)
        {
            if (Predicate(Ancestor.ToSharedRef()))
            {
                return Ancestor;
            }
            Ancestor = Ancestor->GetNextSibling();
        }
        return nullptr;
    }
    virtual TSharedPtr<IAccessibleWidget> GetNextSibling() = 0;
    template<typename PredicateType>
    static TSharedPtr<IAccessibleWidget> SearchForNextSiblingFrom(const TSharedRef<IAccessibleWidget>& Source, PredicateType Predicate)
    {
        TSharedPtr<IAccessibleWidget> NextSibling = Source->GetNextSibling();
        while (NextSibling)
        {
            if (Predicate(NextSibling.ToSharedRef()))
            {
                return NextSibling;
            }
            NextSibling = NextSibling->GetNextSibling();
        }
        return nullptr;
    }
    virtual TSharedPtr<IAccessibleWidget> GetPreviousSibling() = 0;
    template<typename PredicateType>
    static TSharedPtr<IAccessibleWidget> SearchForPreviousSiblingFrom(const TSharedRef<IAccessibleWidget>& Source, PredicateType Predicate)
    {
        TSharedPtr<IAccessibleWidget> PreviousSibling = Source->GetPreviousSibling();
        while(PreviousSibling)
        {
            if (Predicate(PreviousSibling.ToSharedRef()))
            {
                return PreviousSibling;
            }
            PreviousSibling = PreviousSibling->GetPreviousSibling();
        }
        return nullptr;
    }
    virtual TSharedPtr<IAccessibleWidget> GetNextWidgetInHierarchy() = 0;
    template<typename PredicateType>
    static TSharedPtr<IAccessibleWidget> SearchForNextWidgetInHierarchyFrom(const TSharedRef<IAccessibleWidget>& Source, PredicateType Predicate)
    {
        TSharedPtr<IAccessibleWidget> NextWidget = Source->GetNextWidgetInHierarchy();
        while(NextWidget)
        {
            if (Predicate(NextWidget.ToSharedRef()))
            {
                return NextWidget;
            }
            NextWidget = NextWidget->GetNextWidgetInHierarchy();
        }
        return nullptr;
    }
    virtual TSharedPtr<IAccessibleWidget> GetPreviousWidgetInHierarchy() = 0;
    template<typename PredicateType>
    static TSharedPtr<IAccessibleWidget> SearchForPreviousWidgetInHierarchyFrom(const TSharedRef<IAccessibleWidget>& Source, PredicateType Predicate)
    {
        TSharedPtr<IAccessibleWidget> PreviousWidget = Source->GetPreviousWidgetInHierarchy();
        while(PreviousWidget)
        {
            if (Predicate(PreviousWidget.ToSharedRef()))
            {
                return PreviousWidget;
            }
            PreviousWidget = PreviousWidget->GetPreviousWidgetInHierarchy();
        }
        return nullptr;
    }
    virtual TSharedPtr<IAccessibleWidget> GetChildAt(int32 Index) = 0;
    virtual int32 GetNumberOfChildren() = 0;
    template<typename PredicateType>
    static TSharedPtr<IAccessibleWidget> SearchForFirstChildFrom(const TSharedRef<IAccessibleWidget>& Source, PredicateType Predicate)
    {
        if (Source->GetNumberOfChildren() == 0)
        {
            return nullptr;
        }
        TSharedPtr<IAccessibleWidget> Child = nullptr;
        int32 NumChildren = Source->GetNumberOfChildren();
        for (int32 ChildIndex = 0; ChildIndex < NumChildren; ++ChildIndex)
        {
            Child = Source->GetChildAt(ChildIndex);
            if (Child && Predicate(Child.ToSharedRef()))
            {
                return Child;
            }
        }
        return nullptr;
    }
    virtual EAccessibleWidgetType GetWidgetType() const = 0;
 
    virtual FString GetClassName() const = 0;
    virtual FString GetWidgetName() const = 0;
    virtual FString GetHelpText() const = 0;
    virtual FString ToString() const
    {
        TStringBuilder<256> Builder;
        Builder.Appendf(TEXT("Label: %s. Role: %s."), *GetWidgetName(), *GetClassName());
        return Builder.ToString();
    }
 
    virtual bool IsEnabled() const = 0;
    virtual bool IsHidden() const = 0;
    virtual bool SupportsFocus() const = 0;
    virtual bool SupportsAccessibleFocus() const = 0;
    virtual bool CanCurrentlyAcceptAccessibleFocus() const = 0;
    virtual bool HasUserFocus(const FAccessibleUserIndex UserIndex) const = 0;
    virtual bool SetUserFocus(const FAccessibleUserIndex UserIndex) = 0;
 
    virtual IAccessibleWindow* AsWindow() { return nullptr; }
    virtual IAccessibleActivatable* AsActivatable() { return nullptr; }
    virtual IAccessibleProperty* AsProperty() { return nullptr; }
    virtual IAccessibleText* AsText() { return nullptr; }
 
    virtual IAccessibleTable* AsTable() { return nullptr; }
 
    virtual IAccessibleTableRow* AsTableRow() { return nullptr; }
};
 
struct FAccessibleEventArgs
{
    FAccessibleEventArgs(TSharedRef<IAccessibleWidget> InWidget, EAccessibleEvent InEvent, FVariant InOldValue = FVariant(), FVariant InNewValue = FVariant(), FAccessibleUserIndex InUserIndex = 0)
        : Widget(InWidget)
        , Event(InEvent)
        , OldValue(InOldValue)
        , NewValue(InNewValue)
        , UserIndex(InUserIndex)
    {}
    
    TSharedRef<IAccessibleWidget> Widget;
    EAccessibleEvent Event;
    FVariant OldValue;
    FVariant NewValue;
    FAccessibleUserIndex UserIndex;
};
 
class FGenericAccessibleMessageHandler
{
public:
    DECLARE_DELEGATE_OneParam(FAccessibleEvent, const FAccessibleEventArgs&);
 
    APPLICATIONCORE_API FGenericAccessibleMessageHandler();
    virtual ~FGenericAccessibleMessageHandler()
    {
        UnbindAccessibleEventDelegate();
    }
 
    APPLICATIONCORE_API bool ApplicationIsAccessible() const;
 
    bool IsActive() const { return bIsActive; }
 
    APPLICATIONCORE_API void SetActive(bool bActive);
 
    virtual TSharedPtr<IAccessibleWidget> GetAccessibleWindow(const TSharedRef<FGenericWindow>& InWindow) const { return nullptr; }
 
    virtual AccessibleWidgetId GetAccessibleWindowId(const TSharedRef<FGenericWindow>& InWindow) const { return IAccessibleWidget::InvalidAccessibleWidgetId; }
 
    virtual TSharedPtr<IAccessibleWidget> GetAccessibleWidgetFromId(AccessibleWidgetId Id) const { return nullptr; }
 
    void RaiseEvent(const FAccessibleEventArgs& Args)
    {
        AccessibleEventDelegate.ExecuteIfBound(Args);
    }
 
    void SetAccessibleEventDelegate(const FAccessibleEvent& Delegate)
    {
        AccessibleEventDelegate = Delegate;
    }
 
    void UnbindAccessibleEventDelegate()
    {
        AccessibleEventDelegate.Unbind();
    }
 
    virtual void RunInThread(const TFunction<void()>& Function, bool bWaitForCompletion = true, ENamedThreads::Type Thread = ENamedThreads::GameThread) { }
 
    virtual void MakeAccessibleAnnouncement(const FString& AnnouncementString) { }
 
    FGenericAccessibleUserRegistry& GetAccessibleUserRegistry()
    {
        return *AccessibleUserRegistry;
    }
    const FGenericAccessibleUserRegistry& GetAccessibleUserRegistry() const
    {
        return *AccessibleUserRegistry;
    }
    void SetAccessibleUserRegistry(const TSharedRef<FGenericAccessibleUserRegistry>& InAccessibleUserRegistry)
    {
        // @TODOAccessibility: Have some means of storing a default manager
        AccessibleUserRegistry = InAccessibleUserRegistry;
    }
protected:
    virtual void OnActivate() {}
    virtual void OnDeactivate() {}
    
    bool bApplicationIsAccessible;
 
private:
    bool bIsActive;
    FAccessibleEvent AccessibleEventDelegate;
    TSharedRef<FGenericAccessibleUserRegistry> AccessibleUserRegistry;
};
 
#endif