Класс QKeySequence

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

Альтернативный способ указания жестко закодированных кодов клавиш — использование кода Юникода символа; например, '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 plus и Ctrl minus часто используются в качестве ярлыков для операций масштабирования в графических приложениях, и они могут быть указаны соответственно как «Ctrl++» и «Ctrl+-». Однако способ указания и интерпретации этих ярлыков зависит от раскладки клавиатуры. Пользователи норвежских клавиатур заметят, что клавиши + и - не расположены рядом на клавиатуре, но все же смогут активировать оба ярлыка, не нажимая клавишу Shift. Однако пользователи британских клавиатур должны удерживать клавишу Shift, чтобы ввести символ +, что делает ярлык фактически таким же, как «Ctrl+Shift+='».

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

Например, разработчик, использующий британскую клавиатуру, может решить указать «Ctrl+Shift+='» в качестве последовательности клавиш, чтобы создать ярлык, который случайно ведет себя так же, как Ctrl plus. Однако для доступа к клавише = на норвежской клавиатуре требуется нажать клавишу 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::QKeySequence(const QString &key, 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(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 QKeySequence &keysequence)

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

QKeySequence::QKeySequence(StandardKey key)

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

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

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

QKeySequence::~QKeySequence()

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

int QKeySequence::count() const

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

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

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

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

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

bool QKeySequence::isEmpty() const

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

QList<QKeySequence> QKeySequence::keyBindings(StandardKey key)

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

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

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

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

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

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

QString QKeySequence::listToString(const QList<QKeySequence> &list, SequenceFormat format = PortableText)

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

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

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

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

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

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(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().

QKeySequence::operator QVariant() const

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

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

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

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

Обеспечивает произвольное сравнение этой последовательности клавиш и последовательности клавиш other. Гарантируется только то, что оператор возвращает true, если обе последовательности клавиш равны, и что (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>=().

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

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

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

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

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

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 в последовательности клавиш. Это можно использовать только для чтения элемента.