Класс 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 плюс и 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::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(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 QKeySequence &keysequence)

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

QKeySequence::QKeySequence(QKeySequence::StandardKey key)

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

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

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

QKeySequence::~QKeySequence()

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

int QKeySequence::count() const

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

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

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

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

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

bool QKeySequence::isEmpty() const

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

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

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

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

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

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

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

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

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 короче.

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