Класс 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);

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

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

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

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

Примечание: В macOS ссылки на "Ctrl", Qt::CTRL, Qt::Key_Control и Qt::ControlModifier соответствуют клавишам Command на клавиатуре Macintosh, а ссылки на "Meta", Qt::META, Qt::Key_Meta и Qt::MetaModifier соответствуют клавишам Control. Разработчики в macOS могут использовать одни и те же описания ярлыков на всех платформах, и их приложения будут автоматически работать как ожидается в macOS.

Стандартные ярлыки

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);

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

См. также QShortcut.

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

enum QKeySequence::SequenceFormat

enum QKeySequence::SequenceMatch

enum QKeySequence::StandardKey

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

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

Этот перечисление был добавлен или изменён в Qt 4.2.

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

QKeySequence::QKeySequence(QKeySequence::StandardKey key)

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

Результат будет основан на первом элементе в списке привязок клавиш к key.

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

QKeySequence::QKeySequence(const QKeySequence &keysequence)

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

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

Создаёт последовательность клавиш с до четырёх клавиш 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")));

Обратите внимание на комментарий к переводу "Файл|Открыть". Он совершенно не обязателен, но он даёт некоторый контекст для переводчика.

QKeySequence::QKeySequence()

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

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.

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

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

bool QKeySequence::isEmpty() const

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

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

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

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

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

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

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

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

[static] 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 с этой последовательностью клавиш. Эта операция очень быстрая и никогда не приводит к ошибке.

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

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; в противном случае строка использует «переносимый» формат, подходящий для записи в файл.

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

См. также 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<=().

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

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