Класс QKeySequence

Класс QKeySequence инкапсулирует последовательность нажатий клавиш, используемую в сокращениях. Подробнее...

• Список всех членов, включая унаследованные

Типы публичного доступа

Функции публичного доступа

Статические члены публичного доступа

Связанные внешние члены

Подробное описание

В большинстве случаев последовательность нажатий клавиш описывает сочетание клавиш, которое необходимо использовать вместе для выполнения некоторого действия. Последовательности нажатий клавиш используются с объектами QAction для указания сочетаний клавиш, которые могут использоваться для запуска действий.

Последовательности нажатий клавиш можно создавать для использования в качестве сочетаний клавиш тремя различными способами:

• Для стандартных сочетаний клавиш можно использовать стандартную клавишу, чтобы запросить платформозависимую последовательность клавиш, связанную с каждым сочетанием.
• Для пользовательских сочетаний можно использовать удобочитаемые строки, такие как "Ctrl+X", которые можно перевести в соответствующие сочетания для пользователей различных языков. Переводы выполняются в контексте "QShortcut".
• Для жёстко закодированных сочетаний можно указать целые коды клавиш в сочетании с значениями, определёнными перечислениями Qt::Key и Qt::Modifier. Каждый код клавиши состоит из одного значения Qt::Key и нуля или более модификаторов, таких как Qt::SHIFT, Qt::CTRL, Qt::ALT и Qt::META.

Например, Ctrl P может быть последовательностью, используемой как сочетание для печати документа, и может быть указана любым из следующих способов:

QKeySequence(QKeySequence::Print);
QKeySequence(tr("Ctrl+P"));
QKeySequence(tr("Ctrl+p"));
QKeySequence(Qt::CTRL | Qt::Key_P);
QKeySequence(Qt::CTRL + Qt::Key_P); // deprecated

Обратите внимание, что для букв регистр, используемый в строке задания, не имеет значения. В приведенных выше примерах пользователю не нужно удерживать клавишу Shift, чтобы активировать сочетание, заданное "Ctrl+P". Однако для других клавиш использование Shift как неуказанного дополнительного модификатора может привести к путанице для пользователей приложения, у которых раскладки клавиатур отличаются от используемых разработчиками. Подробности см. в разделе Проблемы с раскладкой клавиатуры ниже.

Предпочтительно использовать стандартные сочетания клавиш, когда это возможно. При создании последовательностей нажатий клавиш для нестандартных сочетаний клавиш следует использовать удобочитаемые строки вместо жёстко закодированных целых значений.

Объекты QKeySequence можно преобразовать в QString, чтобы получить удобочитаемый переведённый вариант последовательности. Аналогично, функция toString() производит удобочитаемые строки для использования в меню. В macOS используются соответствующие символы для описания сочетаний клавиш с использованием специальных клавиш на клавиатуре Macintosh.

Альтернативный способ задания жёстко закодированных кодов клавиш — использовать код Юникода символа; например, 'A' даёт ту же последовательность клавиш, что и Qt::Key_A.

Стандартные Сокращения

QKeySequence определяет множество стандартных сочетаний клавиш, чтобы уменьшить количество усилий, требуемых при настройке действий в типичном приложении. В таблице ниже показаны некоторые распространенные сочетания клавиш, которые часто используются для этих стандартных сочетаний клавиш приложениями на четырёх широко используемых платформах. Обратите внимание, что на macOS значение Ctrl соответствует клавишам Command на клавиатуре Macintosh, а значение Meta - клавишам Control.

Обратите внимание, что, поскольку последовательности клавиш для стандартных сокращений различаются между платформами, вам по-прежнему необходимо тестировать свои сокращения на каждой платформе, чтобы убедиться, что вы не назначили одну и ту же последовательность клавиш для нескольких действий.

Проблемы с раскладкой клавиатуры

Многие спецификации последовательностей клавиш выбираются разработчиками на основе раскладки определённых типов клавиатур, а не на основе выбора клавиш, представляющих первую букву имени действия, таких как Ctrl S («Ctrl+S») или Ctrl C («Ctrl+C»). Кроме того, поскольку некоторые символы могут вводиться только с помощью модификаторных клавиш на определённых раскладках клавиатуры, последовательности клавиш, предназначенные для использования с одной раскладкой клавиатуры, могут отображаться на другой клавише, не отображаться вовсе или требовать использования дополнительной модификаторной клавиши на других раскладках.

Например, сокращения Ctrl плюс и Ctrl минус часто используются как сокращения для операций масштабирования в графических приложениях, и эти сокращения могут быть указаны соответственно как «Ctrl++» и «Ctrl+-». Однако способ указания и интерпретации этих сокращений зависит от раскладки клавиатуры. Пользователи норвежских клавиатур заметят, что клавиши + и - не расположены рядом на клавиатуре, но всё же смогут активировать оба сокращения без необходимости нажатия клавиши Shift. Однако пользователям британских клавиатур потребуется удерживать клавишу Shift, чтобы ввести символ +, что делает сокращение фактически таким же, как «Ctrl+Shift+=".

Хотя некоторые разработчики могут прибегнуть к полному указанию всех модификаторов, используемых на их клавиатуре для активации сокращения, это также приведёт к неожиданному поведению для пользователей с разными раскладками клавиатуры.

Например, разработчик, использующий британскую клавиатуру, может решить указать «Ctrl+Shift+» в качестве последовательности клавиш, чтобы создать сокращение, которое случайно будет работать так же, как Ctrl плюс. Однако клавиша = должна вводиться с помощью клавиши Shift на норвежской клавиатуре, что делает необходимым сокращение фактически Ctrl Shift Shift = (невозможная комбинация клавиш).

В результате, как удобочитаемые строки, так и жёстко закодированные коды клавиш могут быть проблематичными при указании последовательности клавиш, которые могут использоваться на различных раскладках клавиатуры. Только использование стандартных сокращений гарантирует, что пользователь сможет использовать сокращения, задуманные разработчиком.

Несмотря на это, мы можем решить эту проблему, гарантировав, что используются удобочитаемые строки, что позволит переводить последовательности клавиш для пользователей разных языков. Этот подход будет успешным для пользователей, чьи клавиатуры имеют наиболее типичную раскладку для используемого ими языка.

Последовательности клавиш в стиле GNU Emacs

Последовательности клавиш, аналогичные используемым в GNU Emacs, позволяющие использовать до четырёх кодов клавиш, могут быть созданы с помощью конструктора с несколькими аргументами или путём передачи удобочитаемой строки, содержащей последовательности клавиш, разделённых запятыми.

Например, последовательность клавиш Ctrl X, за которой следует Ctrl C, может быть указана одним из следующих способов:

QKeySequence(tr("Ctrl+X, Ctrl+C"));
QKeySequence(Qt::CTRL | Qt::Key_X, Qt::CTRL | Qt::Key_C);
QKeySequence(Qt::CTRL + Qt::Key_X, Qt::CTRL + Qt::Key_C); // deprecated

См. также QShortcut.

Документация по типам элементов

перечисление QKeySequence::SequenceFormat

перечисление QKeySequence::SequenceMatch

перечисление QKeySequence::StandardKey

Это перечисление представляет стандартные сочетания клавиш. Они могут использоваться для назначения зависящих от платформы сочетаний клавиш для QAction.

Обратите внимание, что сочетания клавиш зависят от платформы. Текущие привязанные сокращения можно запросить с помощью keyBindings().

Документация по функциям-членам

QKeySequence::QKeySequence(QKeySequence::StandardKey key)

Создает объект QKeySequence для заданного key. Результат будет зависеть от текущей платформы.

Полученный объект будет основан на первом элементе в списке сочетаний клавиш для key.

QKeySequence::QKeySequence(const QKeySequence &keysequence)

Конструктор копирования. Создает копию keysequence.

QKeySequence::QKeySequence(QKeyCombination k1, QKeyCombination k2 = QKeyCombination::fromCombined(0), QKeyCombination k3 = QKeyCombination::fromCombined(0), QKeyCombination k4 = QKeyCombination::fromCombined(0))

Создает последовательность клавиш с максимум 4 клавишами k1, k2, k3 и k4.

См. также QKeyCombination.

QKeySequence::QKeySequence(int k1, int k2 = 0, int k3 = 0, int k4 = 0)

Создает последовательность клавиш с максимум 4 клавишами k1, k2, k3 и k4.

Коды клавиш перечислены в Qt::Key и могут быть объединены с модификаторами (см. Qt::Modifier), такими как Qt::SHIFT, Qt::CTRL, Qt::ALT или Qt::META.

QKeySequence::QKeySequence(const QString &key, QKeySequence::SequenceFormat format = NativeText)

Создает последовательность клавиш из строки key, основываясь на format.

Например, "Ctrl+O" даёт CTRL+'O'. Строки "Ctrl", "Shift", "Alt" и "Meta" распознаются, а также их переводы в контексте "QShortcut" (используя QObject::tr()).

До четырёх кодов клавиш можно ввести, разделив их запятыми, например: "Alt+X,Ctrl+S,Q".

Этот конструктор обычно используется с tr(), чтобы сочетания клавиш можно было заменить при переводах:

QMenu *file = new QMenu(this);
file->addAction(tr("&Open..."), this, SLOT(open()),
                  QKeySequence(tr("Ctrl+O", "File|Open")));

Обратите внимание на комментарий к переводу "File|Open". Он не является необходимым, но он предоставляет контекст для переводчика.

QKeySequence::QKeySequence()

Создаёт пустую последовательность клавиш.

[since 5.2] QKeySequence &QKeySequence::operator=(QKeySequence &&other)

Перемещающее присваивание other данному экземпляру QKeySequence.

Эта функция была добавлена в Qt 5.2.

QKeySequence &QKeySequence::operator=(const QKeySequence &other)

Оператор присваивания. Присваивает последовательность клавиш other этому объекту.

QKeySequence::~QKeySequence()

Уничтожает последовательность клавиш.

int QKeySequence::count() const

Возвращает количество клавиш в последовательности клавиш. Максимальное значение равно 4.

[static] QKeySequence QKeySequence::fromString(const QString &str, QKeySequence::SequenceFormat format = PortableText)

Возвращает QKeySequence из строки str, основываясь на format.

См. также toString().

bool QKeySequence::isEmpty() const

Возвращает true, если последовательность клавиш пустая; в противном случае возвращает false.

[static] QList<QKeySequence> QKeySequence::keyBindings(QKeySequence::StandardKey key)

Возвращает список сочетаний клавиш для заданного key. Результат вызова этой функции будет варьироваться в зависимости от целевой платформы. Первый элемент списка указывает основное сочетание клавиш для данной платформы. Если результат содержит более одного результата, их можно рассматривать как альтернативные сочетания клавиш на той же платформе для заданного key.

[static, since 5.1] QList<QKeySequence> QKeySequence::listFromString(const QString &str, QKeySequence::SequenceFormat format = PortableText)

Возвращает список QKeySequence из строки str, основываясь на format.

Эта функция была добавлена в Qt 5.1.

См. также fromString() и listToString().

[static, since 5.1] QString QKeySequence::listToString(const QList<QKeySequence> &list, QKeySequence::SequenceFormat format = PortableText)

Возвращает строковое представление list, основываясь на format.

Эта функция была добавлена в Qt 5.1.

См. также toString() и listFromString().

QKeySequence::SequenceMatch QKeySequence::matches(const QKeySequence &seq) const

Сопоставляет последовательность с seq. Возвращает ExactMatch, если успешно, PartialMatch, если seq частично совпадает, и NoMatch, если последовательности не имеют ничего общего. Возвращает NoMatch, если seq короче.

[static] QKeySequence QKeySequence::mnemonic(const QString &text)

Возвращает сочетание клавиш для мнемоники в text или пустую последовательность клавиш, если мнемоники не найдены.

Например, mnemonic("E&xit") возвращает Qt::ALT+Qt::Key_X, mnemonic("&Quit") возвращает ALT+Key_Q, а mnemonic("Quit") возвращает пустую QKeySequence.

Мы предоставляем список общих мнемоник на английском языке. На момент написания данной документации Microsoft и Open Group, по-видимому, не выпустили эквивалентные рекомендации для других языков.

void QKeySequence::swap(QKeySequence &other)

Меняет местами последовательность клавиш other с этой последовательностью клавиш. Эта операция очень быстрая и никогда не терпит неудачу.

QString QKeySequence::toString(QKeySequence::SequenceFormat format = PortableText) const

Возвращает строковое представление последовательности клавиш, основываясь на format.

Например, значение Qt::CTRL+Qt::Key_O приводит к "Ctrl+O". Если последовательность клавиш имеет несколько кодов клавиш, каждый из них разделяется запятыми в возвращаемой строке, например "Alt+X, Ctrl+Y, Z". Строки "Ctrl", "Shift" и т.д. переводятся с использованием QObject::tr() в контексте "QShortcut".

Если последовательность клавиш не содержит клавиш, возвращается пустая строка.

В macOS возвращаемая строка напоминает последовательность, отображаемую в строке меню, если format равен QKeySequence::NativeText; в противном случае строка использует "портативный" формат, подходящий для записи в файл.

См. также fromString().

QVariant QKeySequence::operator QVariant() const

Возвращает последовательность клавиш как QVariant.

bool QKeySequence::operator!=(const QKeySequence &other) const

Возвращает true, если эта последовательность клавиш не равна other; в противном случае возвращает false.

bool QKeySequence::operator<(const QKeySequence &other) const

Предоставляет произвольное сравнение этой последовательности клавиш и последовательности клавиш other. Гарантируется только то, что оператор возвращает false если обе последовательности клавиш равны, и что (ks1 < ks2) == !( ks2 < ks1), если последовательности клавиш не равны.

Эта функция полезна в некоторых случаях, например, если вы хотите использовать объекты QKeySequence в качестве ключей в QMap.

См. также operator==(), operator!=(), operator>(), operator<=() и operator>=().

bool QKeySequence::operator<=(const QKeySequence &other) const

Возвращает true если эта последовательность клавиш меньше или равна последовательности клавиш other; в противном случае возвращает false.

См. также operator==(), operator!=(), operator<(), operator>() и operator>=().

bool QKeySequence::operator==(const QKeySequence &other) const

Возвращает true если эта последовательность клавиш равна последовательности клавиш other; в противном случае возвращает false.

bool QKeySequence::operator>(const QKeySequence &other) const

Возвращает true если эта последовательность клавиш больше последовательности клавиш other; в противном случае возвращает false.

См. также operator==(), operator!=(), operator<(), operator<=() и operator>=().

bool QKeySequence::operator>=(const QKeySequence &other) const

Возвращает true если эта последовательность клавиш больше или равна последовательности клавиш other; в противном случае возвращает false.

См. также operator==(), operator!=(), operator<(), operator>() и operator<=().

QKeyCombination QKeySequence::operator[](uint index) const

Возвращает ссылку на элемент в позиции index в последовательности клавиш. Это можно использовать только для чтения элемента.