QWidget 애플리케이션의 접근성

소개

이 문서에서는 Qt 접근성 인터페이스인 QAccessibleInterface 와 애플리케이션을 접근성 지원이 가능하게 만드는 방법에 중점을 둡니다.

QWidget 기반 애플리케이션의 접근성

보조 기술과 통신할 때는 보조 기술이 이해할 수 있는 방식으로 Qt의 사용자 인터페이스를 설명해야 합니다. Qt 애플리케이션은 QAccessibleInterface 를 사용하여 개별 UI 요소에 대한 정보를 노출합니다. 현재 Qt는 위젯 및 위젯 구성 요소(예: 슬라이더 핸들)에 대한 지원을 제공하지만, 필요한 경우 어떤 QObject 에 대해서도 이 인터페이스를 구현할 수 있습니다. QAccessible 에는 UI를 설명하는 열거형(enums)이 포함되어 있습니다. 이 문서를 통해 해당 열거형들을 자세히 살펴보겠습니다.

UI의 구조는 ` QAccessibleInterface ` 하위 클래스의 트리 형태로 표현됩니다. 이는 대개 애플리케이션의 UI를 구성하는 `QWidget`의 계층 구조를 반영합니다.

서버는 updateAccessibility()를 통해 이벤트를 전송함으로써 객체의 변경 사항을 클라이언트에 알리고, 클라이언트는 이벤트를 수신하기 위해 등록합니다. 사용 가능한 이벤트는 QAccessible::Event 열거형에 의해 정의됩니다. 그런 다음 클라이언트는 QAccessible::queryAccessibleInterface()를 통해 이벤트를 발생시킨 객체를 조회할 수 있습니다.

QAccessible 의 멤버와 열거형은 접근 가능한 객체를 설명하는 데 사용됩니다:

• Role: 객체가 사용자 인터페이스에서 수행하는 역할을 설명합니다(예: 창, 텍스트 편집 상자, 표의 셀 등).
• Relation: 객체 계층 구조 내의 객체 간 관계를 설명합니다.
• State: 객체는 여러 가지 다른 상태를 가질 수 있습니다. 상태의 예로는 객체가 비활성화되었는지, 포커스를 가지고 있는지, 또는 팝업 메뉴를 제공하는지 여부 등이 있습니다.

클라이언트는 또한 객체의 내용(예: 버튼의 텍스트)을 가져올 수 있는 몇 가지 방법을 가지고 있습니다. 객체는 콘텐츠에 대한 정보를 제공하는 ` QAccessible::Text ` 열거형으로 정의된 문자열을 제공합니다.

접근 가능한 객체 트리

앞서 언급했듯이, 애플리케이션의 접근 가능한 객체들로 트리 구조가 구축됩니다. 클라이언트는 이 트리를 탐색하여 UI의 모든 요소에 접근할 수 있습니다. 객체 간 관계는 클라이언트에게 UI에 대한 정보를 제공합니다. 예를 들어, 슬라이더 핸들은 해당 슬라이더의 자식 객체입니다. ` QAccessible::Relation `는 클라이언트가 객체에 대해 요청할 수 있는 다양한 관계를 설명합니다.

Qt의 QObject 트리와 접근 가능한 객체 트리 간에는 직접적인 대응 관계가 없다는 점에 유의하십시오. 예를 들어, 스크롤 바 핸들은 접근 가능한 객체이지만 Qt에서는 위젯이나 객체가 아닙니다.

AT 클라이언트는 트리의 루트 객체인 ` QApplication`를 통해 접근성 객체 트리에 접근할 수 있습니다. 이들은 ` QAccessibleInterface::parent()`, ` QAccessibleInterface::childCount()` 및 ` QAccessibleInterface::child()` 함수를 사용하여 트리를 탐색할 수 있습니다.

Qt Widgets와 Qt Quick Controls 에 대한 접근성 인터페이스를 제공합니다. QObject 의 모든 하위 클래스에 대한 인터페이스는 QAccessible::queryInterface()를 통해 요청할 수 있습니다. 보다 특화된 인터페이스가 정의되어 있지 않은 경우, 기본 구현이 제공됩니다. AT 클라이언트는 스크롤 바 핸들처럼 동등한 QObject 가 없는 접근 가능한 객체에 대한 인터페이스를 획득할 수 없으나, 이러한 객체는 부모 접근 가능한 객체의 인터페이스를 통해 일반 객체로 나타납니다. 예를 들어, QAccessibleInterface::relations()를 통해 해당 객체 간의 관계를 조회할 수 있습니다.

이를 설명하기 위해 접근 가능한 객체 트리의 이미지를 제시합니다. 트리 아래에는 객체 관계의 예시가 담긴 표가 있습니다.

위에서 아래로 순서대로 표시된 레이블은 다음과 같습니다: ` QAccessibleInterface ` 클래스 이름, 인터페이스가 제공되는 위젯, 그리고 객체의 ` Role `. `Position`, `PageLeft` 및 `PageRight`는 각각 슬라이더 핸들, 슬라이더 홈 왼쪽, 슬라이더 홈 오른쪽에 해당합니다. 이러한 접근 가능한 객체에는 이에 상응하는 ` QObject`가 없습니다.

QAccessible의 정적 함수

접근성은 QAccessible 의 정적 함수들에 의해 관리되며, 이에 대해서는 잠시 후에 자세히 살펴보겠습니다. 이 함수들은 QAccessible 인터페이스를 생성하고, 객체 트리를 구축하며, MSAA 또는 기타 플랫폼별 기술을 통해 연결을 시작합니다. 단순히 애플리케이션을 접근 가능하게 만드는 방법만 알고 싶다면, 이 섹션을 건너뛰고 '접근성 구현' 섹션으로 바로 넘어가도 됩니다.

클라이언트와 서버 간의 통신은 setRootObject()이 호출될 때 시작됩니다. 이는 QApplication 인스턴스가 생성될 때 자동으로 이루어지므로, 사용자가 직접 수행할 필요는 없습니다.

QObject 가 updateAccessibility()를 호출하면, 이벤트를 수신 대기 중인 클라이언트에게 변경 사항이 알림됩니다. 이 함수는 보조 기술에 이벤트를 전송하는 데 사용되며, 접근 가능한 events 는 updateAccessibility()에 의해 전송됩니다.

queryAccessibleInterface()는 QObject에 대한 접근 가능한 인터페이스를 반환합니다. Qt의 모든 위젯은 인터페이스를 제공하며, 다른 QObject 하위 클래스의 동작을 제어하기 위한 인터페이스가 필요한 경우, QAccessibleObject 편의 클래스가 기능의 일부를 대신 구현해 주기는 하지만, 인터페이스를 직접 구현해야 합니다.

QObject에 대한 접근성 인터페이스를 생성하는 팩토리는 QAccessible::InterfaceFactory 유형의 함수입니다. 여러 개의 팩토리를 설치할 수 있습니다. 마지막으로 설치된 팩토리가 인터페이스 요청을 가장 먼저 받게 됩니다. queryAccessibleInterface()는 팩토리를 사용하여 QObject에 대한 인터페이스를 생성합니다. 일반적으로 인터페이스를 생성하는 플러그인을 직접 구현할 수 있으므로 팩토리에 대해 신경 쓸 필요는 없습니다. 나중에 두 가지 접근 방식에 대한 예제를 제시하겠습니다.

접근성 구현

위젯이나 기타 사용자 인터페이스 요소에 대한 접근성 지원을 제공하려면, QAccessibleInterface 을 구현하고 이를 QAccessiblePlugin 에 포함시켜야 합니다. 또한 인터페이스를 애플리케이션에 컴파일하여 포함시키고, 이에 대한 QAccessible::InterfaceFactory 를 제공할 수도 있습니다. 정적 링크를 사용하거나 플러그인으로 인한 복잡성을 피하고 싶은 경우 팩토리(factory)를 사용할 수 있습니다. 예를 들어 타사 라이브러리를 제공하는 경우, 이는 장점이 될 수 있습니다.

모든 위젯 및 기타 사용자 인터페이스 요소에는 인터페이스와 플러그인이 있어야 합니다. 애플리케이션이 접근성을 지원하도록 하려면 다음 사항을 고려해야 합니다:

• Qt는 자체 위젯에 대해 이미 접근성을 구현하고 있습니다. 따라서 가능한 한 Qt Widgets를 사용할 것을 권장합니다.
• 접근성 클라이언트가 사용할 수 있도록 하려는 각 요소에 대해 ` QAccessibleInterface `를 구현해야 합니다.
• 구현한 사용자 정의 사용자 인터페이스 요소에서 접근성 이벤트를 전송해야 합니다.

일반적으로 Qt의 접근성 지원이 원래 구축된 기반인 MSAA에 대해 어느 정도 익숙해지는 것이 좋습니다. 또한 고려해야 할 역할, 동작, 관계 및 이벤트를 설명하는 ` QAccessible`의 열거형 값을 숙지해야 합니다.

Qt Widgets가 접근성을 어떻게 구현하는지 살펴볼 수 있다는 점에 유의하십시오. MSAA 표준의 주요 문제점 중 하나는 인터페이스가 종종 일관성 없이 구현된다는 것입니다. 이로 인해 클라이언트의 작업이 어려워지며, 종종 객체 기능에 대해 추측해야 하는 상황이 발생합니다.

QAccessibleInterface 을 상속받고 그 순수 가상 함수를 구현하여 인터페이스를 구현할 수 있습니다. 그러나 실제로는 기능의 일부를 미리 구현해 주는 QAccessibleObject 이나 QAccessibleWidget 을 상속받는 것이 일반적으로 더 바람직합니다. 다음 섹션에서는 QAccessibleWidget 클래스를 상속받아 위젯의 접근성을 구현하는 예제를 살펴보겠습니다.

QAccessibleObject 및 QAccessibleWidget 편의 클래스

위젯에 대한 접근성 인터페이스를 구현할 때는 원칙적으로 위젯용 편의 클래스인 QAccessibleWidget 를 상속받습니다. QAccessibleWidget 가 상속받는 또 다른 편의 클래스로는 QAccessibleObject 가 있으며, 이 클래스는 QObject에 대한 인터페이스의 일부를 구현합니다.

QAccessibleWidget 는 다음과 같은 기능을 제공합니다:

• 트리 탐색과 객체의 히트 테스트를 처리합니다.
• 모든 ` QWidget`에 공통적인 이벤트, 역할 및 액션을 처리합니다.
• 모든 위젯에서 수행할 수 있는 액션과 메서드를 처리합니다.
• rect()를 사용하여 경계 사각형을 계산합니다.
• 일반 위젯에 적합한 text() 문자열을 반환합니다.
• 모든 위젯에 공통적인 states 를 설정합니다.

QAccessibleWidget 예제

사용자 정의 위젯을 만들고 이에 대한 인터페이스를 구현하는 대신, Qt의 표준 위젯 중 하나인 QSlider 에 대해 접근성이 어떻게 구현되는지 보여드리겠습니다. 접근성 인터페이스인 QAccessibleSlider는 QAccessibleAbstractSlider를 상속받으며, QAccessibleAbstractSlider는 QAccessibleWidget 를 상속받습니다. 이 섹션을 읽는 데 QAccessibleAbstractSlider 클래스를 자세히 살펴볼 필요는 없습니다. 확인해 보고 싶다면, Qt의 모든 접근성 인터페이스 코드는 qtbase/src/widgets/accessible에서 찾을 수 있습니다. 다음은 QAccessibleSlider의 생성자입니다:

QAccessibleSlider::QAccessibleSlider(QWidget *w)
: QAccessibleAbstractSlider(w)
{
    Q_ASSERT(slider());
    addControllingSignal(QLatin1String("valueChanged(int)"));
}

슬라이더는 접근 가능한 자식 요소들에 대해 ‘ Controller ’ 역할을 수행하는 복합 컨트롤입니다. 이 관계는 인터페이스( parent(), child(), relations())에서 인식되어야 합니다. 이는 QAccessibleWidget 에서 제공하는 메커니즘인 제어 신호를 사용하여 구현할 수 있습니다. 다음은 생성자에서 이를 구현한 예입니다:

여기서 표시된 신호의 선택은 중요하지 않습니다. 이러한 방식으로 선언된 모든 신호에 동일한 원리가 적용됩니다. 신호 이름이 올바르게 지정되었는지 확인하기 위해 ` QLatin1String `를 사용한다는 점에 유의하십시오.

접근 가능한 객체가 사용자가 알아야 할 방식으로 변경되면, 해당 객체는 접근 가능한 인터페이스를 통해 이벤트를 전송하여 클라이언트에 변경 사항을 알립니다. 다음은 QSlider 가 값이 변경되었음을 알리기 위해 updateAccessibility()을 호출하는 방식입니다:

void QAbstractSlider::setValue(int value)
    ...
    QAccessibleValueChangeEvent event(this, d->value);
    QAccessible::updateAccessibility(&event);
    ...
}

클라이언트가 이벤트를 수신한 직후 새로운 값을 조회할 수 있으므로, 이 호출은 슬라이더의 값이 변경된 후에 이루어진다는 점에 유의하십시오.

인터페이스는 자체 및 별도의 인터페이스를 제공하지 않는 모든 자식 요소의 경계 사각형을 계산할 수 있어야 합니다. QAccessibleSlider 에는 비공개 열거형 SliderElements 로 식별되는 세 개의 자식 요소가 있으며, 이 열거형의 값은 다음과 같습니다. PageLeft (슬라이더 핸들 왼쪽의 사각형), PageRight (슬라이더 핸들 오른쪽의 사각형), Position (슬라이더 핸들). 다음은 rect()의 구현 예시입니다:

QRect QAccessibleSlider::rect(int child) const
{
    ...
    switch (child) {
    case PageLeft:
        if (slider()->orientation() == Qt::Vertical)
            rect = QRect(0, 0, slider()->width(), srect.y());
        else
            rect = QRect(0, 0, srect.x(), slider()->height());
        break;
    case Position:
        rect = srect;
        break;
    case PageRight:
        if (slider()->orientation() == Qt::Vertical)
            rect = QRect(0, srect.y() + srect.height(), slider()->width(), slider()->height()- srect.y() - srect.height());
        else
            rect = QRect(srect.x() + srect.width(), 0, slider()->width() - srect.x() - srect.width(), slider()->height());
        break;
    default:
        return QAccessibleAbstractSlider::rect(child);
    }
    ...

생략한 이 함수의 첫 번째 부분에서는 현재 style 를 사용하여 슬라이더 핸들의 경계 사각형을 계산하며, 이 결과는 srect 에 저장됩니다. 위 코드의 기본 경우에서 다루는 자식 0은 슬라이더 자체이므로, 슈퍼클래스에서 얻은 QSlider 경계 사각형을 그대로 반환하면 됩니다. 이는 사실상 QAccessibleWidget::rect()에서 얻은 값과 동일합니다.

    QPoint tp = slider()->mapToGlobal(QPoint(0,0));
    return QRect(tp.x() + rect.x(), tp.y() + rect.y(), rect.width(), rect.height());
}

사각형을 반환하기 전에 이를 화면 좌표로 변환해야 합니다.

QAccessibleSlider는 인터페이스가 없는 자식 요소를 관리하므로 QAccessibleInterface::childCount() 메서드를 재구현해야 합니다.

text() 함수는 슬라이더에 대한 QAccessible::Text 문자열을 반환합니다:

QString QAccessibleSlider::text(Text t, int child) const
{
    if (!slider()->isVisible())
        return QString();
    switch (t) {
    case Value:
        if (!child || child == 2)
            return QString::number(slider()->value());
        return QString();
    case Name:
        switch (child) {
        case PageLeft:
            return slider()->orientation() == Qt::Horizontal ?
                QSlider::tr("Page left") : QSlider::tr("Page up");
        case Position:
            return QSlider::tr("Position");
        case PageRight:
            return slider()->orientation() == Qt::Horizontal ?
                QSlider::tr("Page right") : QSlider::tr("Page down");
        }
        break;
    default:
        break;
    }
    return QAccessibleAbstractSlider::text(t, child);
}

slider() 함수는 인터페이스의 QSlider 에 대한 포인터를 반환합니다. 일부 값은 슈퍼클래스의 구현에 맡겨져 있습니다. QAccessible::Value 사례에서 볼 수 있듯이, 모든 값이 모든 접근 가능한 객체에 적합한 것은 아닙니다. 관련 텍스트를 제공할 수 없는 값에 대해서는 빈 문자열을 반환해야 합니다.

role() 함수의 구현은 간단합니다:

QAccessible::Role QAccessibleSlider::role(int child) const
{
    switch (child) {
    case PageLeft:
    case PageRight:
        return PushButton;
    case Position:
        return Indicator;
    default:
        return Slider;
    }
}

role 함수는 모든 객체에서 재구현되어야 하며, 해당 객체 자체와 자체적으로 접근 가능한 인터페이스를 제공하지 않는 자식 객체들의 역할을 설명합니다.

다음으로, 접근 가능한 인터페이스는 슬라이더가 가질 수 있는 ` states `를 반환해야 합니다. ` state() ` 구현의 일부를 살펴보며 몇 가지 상태가 어떻게 처리되는지 확인해 보겠습니다:

QAccessible::State QAccessibleSlider::state(int child) const
{
    const State parentState = QAccessibleAbstractSlider::state(0);
    ...
    switch (child) {
    case PageLeft:
        if (slider->value() <= slider->minimum())
            state |= Unavailable;
        break;
    case PageRight:
        if (slider->value() >= slider->maximum())
            state |= Unavailable;
        break;
    case Position:
    default:
        break;
    }

    return state;
}

state()의 슈퍼클래스 구현은 QAccessibleInterface::state() 구현을 사용합니다. 슬라이더가 최소값이나 최대값에 있을 경우 버튼을 비활성화하기만 하면 됩니다.

이제 슬라이더에 대한 정보를 클라이언트에 공개했습니다. 클라이언트가 슬라이더를 변경할 수 있도록 하려면(예를 들어, 값을 변경할 수 있도록), 수행 가능한 작업에 대한 정보를 제공하고 요청이 있을 때 해당 작업을 수행해야 합니다. 이에 대해서는 다음 섹션에서 다루겠습니다.

클라이언트의 액션 요청 처리

애플리케이션은 클라이언트가 호출할 수 있는 액션을 노출할 수 있습니다. 객체에서 액션을 지원하려면 ` QAccessibleActionInterface`을 상속받아야 합니다.

상호작용 가능한 요소는 예를 들어 마우스 상호작용에 의해 트리거되는 기능을 노출해야 합니다. 예를 들어, 버튼은 클릭 동작을 구현해야 합니다.

포커스를 받을 수 있는 위젯의 경우, 포커스 설정도 구현해야 할 또 다른 액션입니다.

객체가 지원하는 모든 액션의 목록을 반환하려면 ` actionNames()`를 재구현해야 합니다. 이 목록은 현지화되어서는 안 됩니다.

액션에 대한 정보를 제공하는 두 가지 함수, 즉 ` localizedActionName()`와 ` localizedActionDescription()`는 현지화된 문자열을 반환해야 합니다. 클라이언트는 이 함수들을 사용하여 사용자에게 액션을 표시할 수 있습니다. 일반적으로 이름은 간결해야 하며, “press”와 같이 단 하나의 단어로만 구성되어야 합니다.

해당 액션에 적합한 경우 사용해야 할 표준 액션 이름 및 현지화 목록이 제공됩니다. 이를 통해 클라이언트가 의미론을 더 쉽게 이해할 수 있으며, Qt는 다양한 플랫폼에서 이를 올바르게 노출하도록 시도합니다.

물론 액션은 실행될 수 있는 방법도 필요합니다. ` doAction()`는 이름과 설명에 따라 해당 액션을 호출해야 합니다.

액션과 메서드를 구현하는 방법에 대한 예제를 보려면, QAccessiblePushButton과 같은 Qt Widgets의 표준 위젯 구현을 참고할 수 있습니다.

접근성 플러그인 구현

이 섹션에서는 인터페이스에 대한 접근성 플러그인을 구현하는 절차를 설명합니다. 플러그인은 런타임에 로드될 수 있는 공유 라이브러리에 저장된 클래스입니다. 인터페이스는 필요할 때만 로드되므로 플러그인 형태로 배포하는 것이 편리합니다.

접근성 플러그인을 생성하려면 ` QAccessiblePlugin`를 상속받고, 플러그인의 JSON 설명에 지원되는 클래스 이름을 정의하며, ` QAccessiblePlugin`의 ` create()`를 재구현하면 됩니다. ` .pro ` 파일을 수정하여 플러그인 템플릿을 사용하도록 해야 하며, 플러그인이 포함된 라이브러리는 Qt가 접근성 플러그인을 검색하는 경로에 배치되어야 합니다.

이제 QAccessibleWidget 예제에서 QAccessibleSlider 인터페이스를 생성하는 접근성 플러그인인 SliderPlugin 의 구현 과정을 살펴보겠습니다. 먼저 key() 함수부터 시작하겠습니다:

QStringList SliderPlugin::keys() const
{
    return QStringList() << QLatin1String("QSlider");
}

플러그인이 접근성 인터페이스를 생성할 수 있는 단일 인터페이스의 클래스 이름을 반환하기만 하면 됩니다. 플러그인은 여러 클래스를 지원할 수 있으며, 문자열 목록에 클래스 이름을 추가하기만 하면 됩니다. 이제 create() 함수로 넘어가 보겠습니다:

QAccessibleInterface *SliderPlugin::create(const QString &classname, QObject *object)
{
    QAccessibleInterface *interface = 0;

    if (classname == QLatin1String("QSlider") && object && object->isWidgetType())
        interface = new QAccessibleSlider(static_cast<QWidget *>(object));

    return interface;
}

요청된 인터페이스가 ` QSlider`용인지 확인합니다. 해당 클래스라면, 해당 인터페이스를 생성하여 반환합니다. ` object `는 항상 ` classname`의 인스턴스라는 점에 유의하십시오. 해당 클래스를 지원하지 않는 경우 반드시 0을 반환해야 합니다. ` updateAccessibility()`는 0을 반환하지 않는 플러그인을 찾을 때까지 사용 가능한 접근성 플러그인들을 차례로 확인합니다.

마지막으로, cpp 파일에 매크로를 포함시켜야 합니다:

    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.Examples.Accessibility.SliderPlugin" FILE "slider.json")

Q_PLUGIN_METADATA 매크로는 SliderPlugin 클래스 내의 플러그인을 acc_sliderplugin 라이브러리로 내보냅니다. 첫 번째 인수는 플러그인의 IID이며, 두 번째 인수는 플러그인의 메타데이터 정보를 포함하는 선택적 JSON 파일입니다. 플러그인에 대한 자세한 내용은 플러그인 개요 문서를 참조하십시오.

플러그인을 애플리케이션에 정적으로 링크할지 동적으로 링크할지는 상관없습니다.

인터페이스 팩토리 구현

접근성 인터페이스에 대한 플러그인을 제공하지 않으려면 인터페이스 팩토리(QAccessible::InterfaceFactory)를 사용할 수 있으며, 이는 정적 링크된 애플리케이션에서 접근 가능한 인터페이스를 제공하는 권장 방법입니다.

팩토리는 QAccessiblePlugin 의 create()와 동일한 매개변수, 즉 QString 와 QObject 를 받는 함수에 대한 함수 포인터입니다. 작동 방식도 동일합니다. installFactory() 함수를 사용하여 팩토리를 등록합니다. 다음은 QAccessibleSlider 인터페이스에 대한 팩토리를 생성하는 예시입니다:

QAccessibleInterface *sliderFactory(const QString &classname, QObject *object)
{
    QAccessibleInterface *interface = 0;

    if (classname == QLatin1String("QSlider") && object && object->isWidgetType())
        interface = new QAccessibleSlider(static_cast<QWidget *>(object));

    return interface;
}

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    QAccessible::installFactory(sliderFactory);
    ...
}

관련 클래스