Класс QKeySequence

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

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

Типы public

Функции public

Статические public члены

Связанные non-члены

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

В наиболее распространённом случае последовательность нажатий клавиш описывает комбинацию клавиш, которые необходимо использовать вместе для выполнения какого-либо действия. Последовательности нажатий клавиш используются с объектами 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.

Примечание: В 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);
QKeySequence(Qt::CTRL + Qt::Key_X, Qt::CTRL + Qt::Key_C); // deprecated

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

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

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

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