QKeySequence Class Reference

The QKeySequence class encapsulates a key sequence as used by shortcuts. More...

#include <qkeysequence.h>

Public Types
typedef QKeySequencePrivate *	DataPtr
enum	SequenceFormat { NativeText, PortableText }
	This means that it will be shown translated and on the Mac it will resemble a key sequence from the menu bar. More...
enum	SequenceMatch { NoMatch, PartialMatch, ExactMatch }
enum	StandardKey {   UnknownKey, HelpContents, WhatsThis, Open,   Close, Save, New, Delete,   Cut, Copy, Paste, Undo,   Redo, Back, Forward, Refresh,   ZoomIn, ZoomOut, Print, AddTab,   NextChild, PreviousChild, Find, FindNext,   FindPrevious, Replace, SelectAll, Bold,   Italic, Underline, MoveToNextChar, MoveToPreviousChar,   MoveToNextWord, MoveToPreviousWord, MoveToNextLine, MoveToPreviousLine,   MoveToNextPage, MoveToPreviousPage, MoveToStartOfLine, MoveToEndOfLine,   MoveToStartOfBlock, MoveToEndOfBlock, MoveToStartOfDocument, MoveToEndOfDocument,   SelectNextChar, SelectPreviousChar, SelectNextWord, SelectPreviousWord,   SelectNextLine, SelectPreviousLine, SelectNextPage, SelectPreviousPage,   SelectStartOfLine, SelectEndOfLine, SelectStartOfBlock, SelectEndOfBlock,   SelectStartOfDocument, SelectEndOfDocument, DeleteStartOfWord, DeleteEndOfWord,   DeleteEndOfLine, InsertParagraphSeparator, InsertLineSeparator, SaveAs,   Preferences, Quit }
	This enum represent standard key bindings. More...

Public Functions
uint	count () const
	Returns the number of keys in the key sequence. More...
DataPtr &	data_ptr ()
bool	isDetached () const
bool	isEmpty () const
	Returns true if the key sequence is empty; otherwise returns false. More...
SequenceMatch	matches (const QKeySequence &seq) const
	Matches the sequence with seq. More...
	operator int () const
	For backward compatibility: returns the first keycode as integer. More...
	operator QString () const
	Use toString() instead. More...
	operator QVariant () const
	Returns the key sequence as a QVariant. More...
bool	operator!= (const QKeySequence &other) const
	Returns true if this key sequence is not equal to the other key sequence; otherwise returns false. More...
bool	operator< (const QKeySequence &ks) const
	Provides an arbitrary comparison of this key sequence and other key sequence. More...
bool	operator<= (const QKeySequence &other) const
	Returns true if this key sequence is smaller or equal to the other key sequence; otherwise returns false. More...
QKeySequence &	operator= (const QKeySequence &other)
	Assignment operator. More...
bool	operator== (const QKeySequence &other) const
	Returns true if this key sequence is equal to the other key sequence; otherwise returns false. More...
bool	operator> (const QKeySequence &other) const
	Returns true if this key sequence is larger than the other key sequence; otherwise returns false. More...
bool	operator>= (const QKeySequence &other) const
	Returns true if this key sequence is larger or equal to the other key sequence; otherwise returns false. More...
int	operator[] (uint i) const
	Returns a reference to the element at position index in the key sequence. More...
	QKeySequence ()
	Constructs an empty key sequence. More...
	QKeySequence (const QString &key)
	Creates a key sequence from the key string. More...
	QKeySequence (const QString &key, SequenceFormat format)
	Creates a key sequence from the key string based on format. More...
	QKeySequence (int k1, int k2=0, int k3=0, int k4=0)
	Constructs a key sequence with up to 4 keys k1, k2, k3 and k4. More...
	QKeySequence (const QKeySequence &ks)
	Copy constructor. More...
	QKeySequence (StandardKey key)
	Constructs a QKeySequence object for the given key. More...
void	swap (QKeySequence &other)
	Swaps key sequence other with this key sequence. More...
QString	toString (SequenceFormat format=PortableText) const
	Return a string representation of the key sequence, based on format. More...
	~QKeySequence ()
	Destroys the key sequence. More...

Static Public Functions
static QKeySequence	fromString (const QString &str, SequenceFormat format=PortableText)
	Return a QKeySequence from the string str based on format. More...
static QList< QKeySequence >	keyBindings (StandardKey key)
	Returns a list of key bindings for the given key. More...
static QKeySequence	mnemonic (const QString &text)
	Returns the shortcut key sequence for the mnemonic in text, or an empty key sequence if no mnemonics are found. More...

Private Functions
int	assign (const QString &str)
	Adds the given keys to the key sequence. More...
int	assign (const QString &str, SequenceFormat format)
	Adds the given keys to the key sequence (based on format). More...
void	setKey (int key, int index)
	KeySequences should never be modified, but rather just created. More...

Static Private Functions
static int	decodeString (const QString &ks)
	Constructs a single key from the string str. More...
static QString	encodeString (int key)
	Creates a shortcut string for key. More...

Properties
QKeySequencePrivate *	d

Friends
Q_GUI_EXPORT QDataStream &	operator<< (QDataStream &in, const QKeySequence &ks)
	Writes the key sequence to the stream. More...
Q_GUI_EXPORT QDataStream &	operator>> (QDataStream &in, QKeySequence &ks)
	Reads a key sequence from the stream into the key sequence. More...
class	Q3AccelManager
class	QShortcut
class	QShortcutMap

Detailed Description

The QKeySequence class encapsulates a key sequence as used by shortcuts.

In its most common form, a key sequence describes a combination of keys that must be used together to perform some action. Key sequences are used with QAction objects to specify which keyboard shortcuts can be used to trigger actions.

Key sequences can be constructed for use as keyboard shortcuts in three different ways:

• For standard shortcuts, a standard key can be used to request the platform-specific key sequence associated with each shortcut.
• For custom shortcuts, human-readable strings such as "Ctrl+X" can be used, and these can be translated into the appropriate shortcuts for users of different languages. Translations are made in the "QShortcut" context.
• For hard-coded shortcuts, integer key codes can be specified with a combination of values defined by the Qt::Key and Qt::Modifier enum values. Each key code consists of a single Qt::Key value and zero or more modifiers, such as Qt::SHIFT, Qt::CTRL, Qt::ALT and Qt::META.

For example, Ctrl P might be a sequence used as a shortcut for printing a document, and can be specified in any of the following ways:

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

Note that, for letters, the case used in the specification string does not matter. In the above examples, the user does not need to hold down the Shift key to activate a shortcut specified with "Ctrl+P". However, for other keys, the use of Shift as an unspecified extra modifier key can lead to confusion for users of an application whose keyboards have different layouts to those used by the developers. See the Keyboard Layout Issues section below for more details.

It is preferable to use standard shortcuts where possible. When creating key sequences for non-standard shortcuts, you should use human-readable strings in preference to hard-coded integer values.

QKeySequence objects can be cast to a QString to obtain a human-readable translated version of the sequence. Similarly, the toString() function produces human-readable strings for use in menus. On Mac OS X, the appropriate symbols are used to describe keyboard shortcuts using special keys on the Macintosh keyboard.

An alternative way to specify hard-coded key codes is to use the Unicode code point of the character; for example, 'A' gives the same key sequence as Qt::Key_A.

Note: On Mac OS X, references to "Ctrl", Qt::CTRL, Qt::Control and Qt::ControlModifier correspond to the Command keys on the Macintosh keyboard, and references to "Meta", Qt::META, Qt::Meta and Qt::MetaModifier correspond to the Control keys. Developers on Mac OS X can use the same shortcut descriptions across all platforms, and their applications will automatically work as expected on Mac OS X.

Standard Shortcuts

QKeySequence defines many standard keyboard shortcuts to reduce the amount of effort required when setting up actions in a typical application. The table below shows some common key sequences that are often used for these standard shortcuts by applications on four widely-used platforms. Note that on Mac OS X, the Ctrl value corresponds to the Command keys on the Macintosh keyboard, and the Meta value corresponds to the Control keys.

StandardKey	Windows	Mac OS X	KDE	GNOME	S60
HelpContents	F1	Ctrl+?	F1	F1	F2
WhatsThis	Shift+F1	Shift+F1	Shift+F1	Shift+F1	Shift+F1
Open	Ctrl+O	Ctrl+O	Ctrl+O	Ctrl+O	(none)
Close	Ctrl+F4, Ctrl+W	Ctrl+W, Ctrl+F4	Ctrl+W	Ctrl+W	(none)
Save	Ctrl+S	Ctrl+S	Ctrl+S	Ctrl+S	(none)
Quit		Ctrl+Q	Qtrl+Q	Qtrl+Q	(none)
SaveAs		Ctrl+Shift+S		Ctrl+Shift+S	(none)
New	Ctrl+N	Ctrl+N	Ctrl+N	Ctrl+N	(none)
Delete	Del	Del, Meta+D	Del, Ctrl+D	Del, Ctrl+D	Del
Cut	Ctrl+X, Shift+Del	Ctrl+X	Ctrl+X, F20, Shift+Del	Ctrl+X, F20, Shift+Del	Ctrl+X
Copy	Ctrl+C, Ctrl+Ins	Ctrl+C	Ctrl+C, F16, Ctrl+Ins	Ctrl+C, F16, Ctrl+Ins	Ctrl+C
Paste	Ctrl+V, Shift+Ins	Ctrl+V	Ctrl+V, F18, Shift+Ins	Ctrl+V, F18, Shift+Ins	Ctrl+V
Preferences		Ctrl+,			(none)
Undo	Ctrl+Z, Alt+Backspace	Ctrl+Z	Ctrl+Z, F14	Ctrl+Z, F14	Ctrl+Z
Redo	Ctrl+Y, Shift+Ctrl+Z, Alt+Shift+Backspace	Ctrl+Shift+Z	Ctrl+Shift+Z	Ctrl+Shift+Z	(none)
Back	Alt+Left, Backspace	Ctrl+[	Alt+Left	Alt+Left	(none)
Forward	Alt+Right, Shift+Backspace	Ctrl+]	Alt+Right	Alt+Right	(none)
Refresh	F5	F5	F5	Ctrl+R, F5	(none)
ZoomIn	Ctrl+Plus	Ctrl+Plus	Ctrl+Plus	Ctrl+Plus	(none)
ZoomOut	Ctrl+Minus	Ctrl+Minus	Ctrl+Minus	Ctrl+Minus	(none)
Print	Ctrl+P	Ctrl+P	Ctrl+P	Ctrl+P	(none)
AddTab	Ctrl+T	Ctrl+T	Ctrl+Shift+N, Ctrl+T	Ctrl+T	(none)
NextChild	Ctrl+Tab, Forward, Ctrl+F6	Ctrl+}, Forward, Ctrl+Tab	Ctrl+Tab, Forward, Ctrl+Comma	Ctrl+Tab, Forward	(none)
PreviousChild	Ctrl+Shift+Tab, Back, Ctrl+Shift+F6	Ctrl+{, Back, Ctrl+Shift+Tab	Ctrl+Shift+Tab, Back, Ctrl+Period	Ctrl+Shift+Tab, Back	(none)
Find	Ctrl+F	Ctrl+F	Ctrl+F	Ctrl+F	(none)
FindNext	F3, Ctrl+G	Ctrl+G	F3	Ctrl+G, F3	(none)
FindPrevious	Shift+F3, Ctrl+Shift+G	Ctrl+Shift+G	Shift+F3	Ctrl+Shift+G, Shift+F3	(none)
Replace	Ctrl+H	(none)	Ctrl+R	Ctrl+H	(none)
SelectAll	Ctrl+A	Ctrl+A	Ctrl+A	Ctrl+A	(none)
Bold	Ctrl+B	Ctrl+B	Ctrl+B	Ctrl+B	(none)
Italic	Ctrl+I	Ctrl+I	Ctrl+I	Ctrl+I	(none)
Underline	Ctrl+U	Ctrl+U	Ctrl+U	Ctrl+U	(none)
MoveToNextChar	Right	Right	Right	Right	Right
MoveToPreviousChar	Left	Left	Left	Left	Left
MoveToNextWord	Ctrl+Right	Alt+Right	Ctrl+Right	Ctrl+Right	Ctrl+Right
MoveToPreviousWord	Ctrl+Left	Alt+Left	Ctrl+Left	Ctrl+Left	Ctrl+Left
MoveToNextLine	Down	Down	Down	Down	Down
MoveToPreviousLine	Up	Up	Up	Up	Up
MoveToNextPage	PgDown	PgDown, Alt+PgDown, Meta+Down, Meta+PgDown	PgDown	PgDown	PgDown
MoveToPreviousPage	PgUp	PgUp, Alt+PgUp, Meta+Up, Meta+PgUp	PgUp	PgUp	PgUp
MoveToStartOfLine	Home	Ctrl+Left, Meta+Left	Home	Home	Home
MoveToEndOfLine	End	Ctrl+Right, Meta+Right	End	End	End
MoveToStartOfBlock	(none)	Alt+Up, Meta+A	(none)	(none)	(none)
MoveToEndOfBlock	(none)	Alt+Down, Meta+E	(none)	(none)	(none)
MoveToStartOfDocument	Ctrl+Home	Ctrl+Up, Home	Ctrl+Home	Ctrl+Home	Ctrl+Home
MoveToEndOfDocument	Ctrl+End	Ctrl+Down, End	Ctrl+End	Ctrl+End	Ctrl+End
SelectNextChar	Shift+Right	Shift+Right	Shift+Right	Shift+Right	Shift+Right
SelectPreviousChar	Shift+Left	Shift+Left	Shift+Left	Shift+Left	Shift+Left
SelectNextWord	Ctrl+Shift+Right	Alt+Shift+Right	Ctrl+Shift+Right	Ctrl+Shift+Right	Ctrl+Shift+Right
SelectPreviousWord	Ctrl+Shift+Left	Alt+Shift+Left	Ctrl+Shift+Left	Ctrl+Shift+Left	Ctrl+Shift+Left
SelectNextLine	Shift+Down	Shift+Down	Shift+Down	Shift+Down	Shift+Down
SelectPreviousLine	Shift+Up	Shift+Up	Shift+Up	Shift+Up	Shift+Up
SelectNextPage	Shift+PgDown	Shift+PgDown	Shift+PgDown	Shift+PgDown	Shift+PgDown
SelectPreviousPage	Shift+PgUp	Shift+PgUp	Shift+PgUp	Shift+PgUp	Shift+PgUp
SelectStartOfLine	Shift+Home	Ctrl+Shift+Left	Shift+Home	Shift+Home	Shift+Home
SelectEndOfLine	Shift+End	Ctrl+Shift+Right	Shift+End	Shift+End	Shift+End
SelectStartOfBlock	(none)	Alt+Shift+Up, Meta+Shift+A	(none)	(none)	(none)
SelectEndOfBlock	(none)	Alt+Shift+Down, Meta+Shift+E	(none)	(none)	(none)
SelectStartOfDocument	Ctrl+Shift+Home	Ctrl+Shift+Up, Shift+Home	Ctrl+Shift+Home	Ctrl+Shift+Home	Ctrl+Shift+Home
SelectEndOfDocument	Ctrl+Shift+End	Ctrl+Shift+Down, Shift+End	Ctrl+Shift+End	Ctrl+Shift+End	Ctrl+Shift+End
DeleteStartOfWord	Ctrl+Backspace	Alt+Backspace	Ctrl+Backspace	Ctrl+Backspace	(none)
DeleteEndOfWord	Ctrl+Del	(none)	Ctrl+Del	Ctrl+Del	(none)
DeleteEndOfLine	(none)	(none)	Ctrl+K	Ctrl+K	(none)
InsertParagraphSeparator	Enter	Enter	Enter	Enter	(none)
InsertLineSeparator	Shift+Enter	Meta+Enter	Shift+Enter	Shift+Enter	(none)

Note that, since the key sequences used for the standard shortcuts differ between platforms, you still need to test your shortcuts on each platform to ensure that you do not unintentionally assign the same key sequence to many actions.

Keyboard Layout Issues

Many key sequence specifications are chosen by developers based on the layout of certain types of keyboard, rather than choosing keys that represent the first letter of an action's name, such as Ctrl S ("Ctrl+S") or Ctrl C ("Ctrl+C"). Additionally, because certain symbols can only be entered with the help of modifier keys on certain keyboard layouts, key sequences intended for use with one keyboard layout may map to a different key, map to no keys at all, or require an additional modifier key to be used on different keyboard layouts.

For example, the shortcuts, Ctrl plus and Ctrl minus, are often used as shortcuts for zoom operations in graphics applications, and these may be specified as "Ctrl++" and "Ctrl+-" respectively. However, the way these shortcuts are specified and interpreted depends on the keyboard layout. Users of Norwegian keyboards will note that the + and - keys are not adjacent on the keyboard, but will still be able to activate both shortcuts without needing to press the Shift key. However, users with British keyboards will need to hold down the Shift key to enter the + symbol, making the shortcut effectively the same as "Ctrl+Shift+=".

Although some developers might resort to fully specifying all the modifiers they use on their keyboards to activate a shortcut, this will also result in unexpected behavior for users of different keyboard layouts.

For example, a developer using a British keyboard may decide to specify "Ctrl+Shift+=" as the key sequence in order to create a shortcut that coincidentally behaves in the same way as Ctrl plus. However, the = key needs to be accessed using the Shift key on Norwegian keyboard, making the required shortcut effectively Ctrl Shift Shift = (an impossible key combination).

As a result, both human-readable strings and hard-coded key codes can both be problematic to use when specifying a key sequence that can be used on a variety of different keyboard layouts. Only the use of standard shortcuts guarantees that the user will be able to use the shortcuts that the developer intended.

Despite this, we can address this issue by ensuring that human-readable strings are used, making it possible for translations of key sequences to be made for users of different languages. This approach will be successful for users whose keyboards have the most typical layout for the language they are using.

GNU Emacs Style Key Sequences

Key sequences similar to those used in GNU Emacs, allowing up to four key codes, can be created by using the multiple argument constructor, or by passing a human-readable string of comma-separated key sequences.

For example, the key sequence, Ctrl X followed by Ctrl C, can be specified using either of the following ways:

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

Warning

A QApplication instance must have been constructed before a QKeySequence is created; otherwise, your application may crash.

See also

QShortcut

Definition at line 72 of file qkeysequence.h.

Typedefs

DataPtr

QKeySequence::DataPtr

Warning

This function is not part of the public interface.

Definition at line 215 of file qkeysequence.h.

Enumerations

SequenceFormat

enum QKeySequence::SequenceFormat

This means that it will be shown translated and on the Mac it will resemble a key sequence from the menu bar.

• NativeText The key sequence as a platform specific string. This enum is best used when you want to display the string to the user.

• PortableText The key sequence is given in a "portable" format, suitable for reading and writing to a file. In many cases, it will look similar to the native text on Windows and X11.

Enumerator
NativeText
PortableText

Definition at line 144 of file qkeysequence.h.

                        {
        NativeText,
        PortableText
    };

SequenceMatch

enum QKeySequence::SequenceMatch

• NoMatch The key sequences are different; not even partially matching.
• PartialMatch The key sequences match partially, but are not the same.
• ExactMatch The key sequences are the same.
• Identical

Enumerator
NoMatch
PartialMatch
ExactMatch

Definition at line 160 of file qkeysequence.h.

                       {
        NoMatch,
        PartialMatch,
        ExactMatch
#ifdef QT3_SUPPORT
        , Identical = ExactMatch
#endif
    };

StandardKey

enum QKeySequence::StandardKey

This enum represent standard key bindings.

Since

4.2

They can be used to assign platform dependent keyboard shortcuts to a QAction.

Note that the key bindings are platform dependent. The currently bound shortcuts can be queried using keyBindings().

• AddTab Add new tab.
• Back Navigate back.
• Bold Bold text.
• Close Close document/tab.
• Copy Copy.
• Cut Cut.
• Delete Delete.
• DeleteEndOfLine Delete end of line.
• DeleteEndOfWord Delete word from the end of the cursor.
• DeleteStartOfWord Delete the beginning of a word up to the cursor.
• Find Find in document.
• FindNext Find next result.
• FindPrevious Find previous result.
• Forward Navigate forward.
• HelpContents Open help contents.
• InsertLineSeparator Insert a new line.
• InsertParagraphSeparator Insert a new paragraph.
• Italic Italic text.
• MoveToEndOfBlock Move cursor to end of block. This shortcut is only used on the OS X.
• MoveToEndOfDocument Move cursor to end of document.
• MoveToEndOfLine Move cursor to end of line.
• MoveToNextChar Move cursor to next character.
• MoveToNextLine Move cursor to next line.
• MoveToNextPage Move cursor to next page.
• MoveToNextWord Move cursor to next word.
• MoveToPreviousChar Move cursor to previous character.
• MoveToPreviousLine Move cursor to previous line.
• MoveToPreviousPage Move cursor to previous page.
• MoveToPreviousWord Move cursor to previous word.
• MoveToStartOfBlock Move cursor to start of a block. This shortcut is only used on OS X.
• MoveToStartOfDocument Move cursor to start of document.
• MoveToStartOfLine Move cursor to start of line.
• New Create new document.
• NextChild Navigate to next tab or child window.
• Open Open document.
• Paste Paste.
• Preferences Open the preferences dialog.
• PreviousChild Navigate to previous tab or child window.
• Print Print document.
• Quit Quit the application.
• Redo Redo.
• Refresh Refresh or reload current document.
• Replace Find and replace.
• SaveAs Save document after prompting the user for a file name.
• Save Save document.
• SelectAll Select all text.
• SelectEndOfBlock Extend selection to the end of a text block. This shortcut is only used on OS X.
• SelectEndOfDocument Extend selection to end of document.
• SelectEndOfLine Extend selection to end of line.
• SelectNextChar Extend selection to next character.
• SelectNextLine Extend selection to next line.
• SelectNextPage Extend selection to next page.
• SelectNextWord Extend selection to next word.
• SelectPreviousChar Extend selection to previous character.
• SelectPreviousLine Extend selection to previous line.
• SelectPreviousPage Extend selection to previous page.
• SelectPreviousWord Extend selection to previous word.
• SelectStartOfBlock Extend selection to the start of a text block. This shortcut is only used on OS X.
• SelectStartOfDocument Extend selection to start of document.
• SelectStartOfLine Extend selection to start of line.
• Underline Underline text.
• Undo Undo.
• UnknownKey Unbound key.
• WhatsThis Activate whats this.
• ZoomIn Zoom in.
• ZoomOut Zoom out.

Enumerator
UnknownKey
HelpContents
WhatsThis
Open
Close
Save
New
Delete
Cut
Copy
Paste
Undo
Redo
Back
Forward
Refresh
ZoomIn
ZoomOut
Print
AddTab
NextChild
PreviousChild
Find
FindNext
FindPrevious
Replace
SelectAll
Bold
Italic
Underline
MoveToNextChar
MoveToPreviousChar
MoveToNextWord
MoveToPreviousWord
MoveToNextLine
MoveToPreviousLine
MoveToNextPage
MoveToPreviousPage
MoveToStartOfLine
MoveToEndOfLine
MoveToStartOfBlock
MoveToEndOfBlock
MoveToStartOfDocument
MoveToEndOfDocument
SelectNextChar
SelectPreviousChar
SelectNextWord
SelectPreviousWord
SelectNextLine
SelectPreviousLine
SelectNextPage
SelectPreviousPage
SelectStartOfLine
SelectEndOfLine
SelectStartOfBlock
SelectEndOfBlock
SelectStartOfDocument
SelectEndOfDocument
DeleteStartOfWord
DeleteEndOfWord
DeleteEndOfLine
InsertParagraphSeparator
InsertLineSeparator
SaveAs
Preferences
Quit

Definition at line 75 of file qkeysequence.h.

                     {
        UnknownKey,
        HelpContents,
        WhatsThis,
        Open,
        Close,
        Save,
        New,
        Delete,
        Cut,
        Copy,
        Paste,
        Undo,
        Redo,
        Back,
        Forward,
        Refresh,
        ZoomIn,
        ZoomOut,
        Print,
        AddTab,
        NextChild,
        PreviousChild,
        Find,
        FindNext,
        FindPrevious,
        Replace,
        SelectAll,
        Bold,
        Italic,
        Underline,
        MoveToNextChar,
        MoveToPreviousChar,
        MoveToNextWord,
        MoveToPreviousWord,
        MoveToNextLine,
        MoveToPreviousLine,
        MoveToNextPage,
        MoveToPreviousPage,
        MoveToStartOfLine,
        MoveToEndOfLine,
        MoveToStartOfBlock,
        MoveToEndOfBlock,
        MoveToStartOfDocument,
        MoveToEndOfDocument,
        SelectNextChar,
        SelectPreviousChar,
        SelectNextWord,
        SelectPreviousWord,
        SelectNextLine,
        SelectPreviousLine,
        SelectNextPage,
        SelectPreviousPage,
        SelectStartOfLine,
        SelectEndOfLine,
        SelectStartOfBlock,
        SelectEndOfBlock,
        SelectStartOfDocument,
        SelectEndOfDocument,
        DeleteStartOfWord,
        DeleteEndOfWord,
        DeleteEndOfLine,
        InsertParagraphSeparator,
        InsertLineSeparator,
        SaveAs,
        Preferences,
        Quit
     };

Constructors and Destructors

QKeySequence() [1/6]

QKeySequence::QKeySequence

(

)

Constructs an empty key sequence.

Definition at line 912 of file qkeysequence.cpp.

Referenced by fromString(), keyBindings(), and mnemonic().

{
    static QKeySequencePrivate shared_empty;
    d = &shared_empty;
    d->ref.ref();
}

QKeySequence() [2/6]

QKeySequence::QKeySequence

(

const QString &

key

)

Creates a key sequence from the key string.

For example "Ctrl+O" gives CTRL+'O'. The strings "Ctrl", "Shift", "Alt" and "Meta" are recognized, as well as their translated equivalents in the "QShortcut" context (using QObject::tr()).

Up to four key codes may be entered by separating them with commas, e.g. "Alt+X,Ctrl+S,Q".

key should be in NativeText format.

This constructor is typically used with tr (), so that shortcut keys can be replaced in translations:

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

Note the "File|Open" translator comment. It is by no means necessary, but it provides some context for the human translator.

Definition at line 940 of file qkeysequence.cpp.

{
    d = new QKeySequencePrivate();
    assign(key);
}

QKeySequence() [3/6]

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

Creates a key sequence from the key string based on format.

Since

4.7

Definition at line 953 of file qkeysequence.cpp.

{
    d = new QKeySequencePrivate();
    assign(key, format);
}

QKeySequence() [4/6]

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

Constructs a key sequence with up to 4 keys k1, k2, k3 and k4.

The key codes are listed in Qt::Key and can be combined with modifiers (see Qt::Modifier) such as Qt::SHIFT, Qt::CTRL, Qt::ALT, or Qt::META.

Definition at line 967 of file qkeysequence.cpp.

{
    d = new QKeySequencePrivate();
    d->key[0] = k1;
    d->key[1] = k2;
    d->key[2] = k3;
    d->key[3] = k4;
}

QKeySequence() [5/6]

QKeySequence::QKeySequence

(

const QKeySequence &

keysequence

)

Copy constructor.

Makes a copy of keysequence.

Definition at line 979 of file qkeysequence.cpp.

    : d(keysequence.d)
{
    d->ref.ref();
}

QKeySequence() [6/6]

QKeySequence::QKeySequence

(

StandardKey

key

)

Constructs a QKeySequence object for the given key.

Since

4.2

The result will depend on the currently running platform.

The resulting object will be based on the first element in the list of key bindings for the key.

Definition at line 896 of file qkeysequence.cpp.

{
    const QList <QKeySequence> bindings = keyBindings(key);
    //pick only the first/primary shortcut from current bindings
    if (bindings.size() > 0) {
        d = bindings.first().d;
        d->ref.ref();
    }
    else
        d = new QKeySequencePrivate();
}

~QKeySequence()

QKeySequence::~QKeySequence

(

)

Destroys the key sequence.

Definition at line 1037 of file qkeysequence.cpp.

{
    if (!d->ref.deref())
        delete d;
}

Functions

assign() [1/2]

int QKeySequence::assign ( const QString &  keys )

private

Adds the given keys to the key sequence.

keys may contain up to four key codes, provided they are separated by a comma; for example, "Alt+X,Ctrl+S,Z". The return value is the number of key codes added. keys should be in NativeText format.

Definition at line 1149 of file qkeysequence.cpp.

{
    return assign(ks, NativeText);
}

assign() [2/2]

int QKeySequence::assign ( const QString &  keys, QKeySequence::SequenceFormat  format  )

private

Adds the given keys to the key sequence (based on format).

Since

4.7

keys may contain up to four key codes, provided they are separated by a comma; for example, "Alt+X,Ctrl+S,Z". The return value is the number of key codes added.

Definition at line 1166 of file qkeysequence.cpp.

{
    QString keyseq = ks;
    QString part;
    int n = 0;
    int p = 0, diff = 0;

    // Run through the whole string, but stop
    // if we have 4 keys before the end.
    while (keyseq.length() && n < 4) {
        // We MUST use something to separate each sequence, and space
        // does not cut it, since some of the key names have space
        // in them.. (Let's hope no one translate with a comma in it:)
        p = keyseq.indexOf(QLatin1Char(','));
        if (-1 != p) {
            if (p == keyseq.count() - 1) { // Last comma 'Ctrl+,'
                p = -1;
            } else {
                if (QLatin1Char(',') == keyseq.at(p+1)) // e.g. 'Ctrl+,, Shift+,,'
                    p++;
                if (QLatin1Char(' ') == keyseq.at(p+1)) { // Space after comma
                    diff = 1;
                    p++;
                } else {
                    diff = 0;
                }
            }
        }
        part = keyseq.left(-1 == p ? keyseq.length() : p - diff);
        keyseq = keyseq.right(-1 == p ? 0 : keyseq.length() - (p + 1));
        d->key[n] = QKeySequencePrivate::decodeString(part, format);
        ++n;
    }
    return n;
}

count()

uint QKeySequence::count

(

)

const

Returns the number of keys in the key sequence.

The maximum is 4.

Definition at line 1064 of file qkeysequence.cpp.

Referenced by QShortcutMap::matches(), matches(), operator int(), operator<<(), QMenuPrivate::QMacMenuPrivate::syncAction(), and toString().

{
    if (!d->key[0])
        return 0;
    if (!d->key[1])
        return 1;
    if (!d->key[2])
        return 2;
    if (!d->key[3])
        return 3;
    return 4;
}

data_ptr()

DataPtr & QKeySequence::data_ptr ( )

inline

Warning

This function is not part of the public interface.

Definition at line 216 of file qkeysequence.h.

{ return d; }

decodeString()

int QKeySequence::decodeString ( const QString &  ks )

staticprivate

Constructs a single key from the string str.

Definition at line 1216 of file qkeysequence.cpp.

{
    return QKeySequencePrivate::decodeString(str, NativeText);
}

encodeString()

QString QKeySequence::encodeString ( int  key )

staticprivate

Creates a shortcut string for key.

For example, Qt::CTRL+Qt::Key_O gives "Ctrl+O". The strings, "Ctrl", "Shift", etc. are translated (using QObject::tr()) in the "QShortcut" context.

Definition at line 1348 of file qkeysequence.cpp.

{
    return QKeySequencePrivate::encodeString(key, NativeText);
}

fromString()

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

static

Return a QKeySequence from the string str based on format.

Since

4.1

See also

toString()

Definition at line 1700 of file qkeysequence.cpp.

{
    return QKeySequence(str, format);
}

isDetached()

bool QKeySequence::isDetached

(

)

const

Warning

This function is not part of the public interface.

Definition at line 1649 of file qkeysequence.cpp.

{
    return d->ref == 1;
}

isEmpty()

bool QKeySequence::isEmpty

(

)

const

Returns true if the key sequence is empty; otherwise returns false.

Definition at line 1082 of file qkeysequence.cpp.

Referenced by QShortcutMap::addShortcut(), QGraphicsWidget::grabShortcut(), QWidget::grabShortcut(), QMenu::initStyleOption(), QAccessibleMenuItem::keyBindings(), QActionPrivate::redoGrab(), QShortcutPrivate::redoGrab(), QActionPrivate::redoGrabAlternate(), QShortcutMap::removeShortcut(), QShortcutMap::setShortcutAutoRepeat(), QShortcutMap::setShortcutEnabled(), QAccessibleMenuItem::text(), and QMenuPrivate::updateActionRects().

{
    return !d->key[0];
}

keyBindings()

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

static

Returns a list of key bindings for the given key.

Since

4.2

The result of calling this function will vary based on the target platform. The first element of the list indicates the primary shortcut for the given platform. If the result contains more than one result, these can be considered alternative shortcuts on the same platform for the given key.

Definition at line 1012 of file qkeysequence.cpp.

Referenced by QWorkspacePrivate::init(), and QAction::setShortcuts().

{
    uint platform = QApplicationPrivate::currentPlatform();
    QList <QKeySequence> list;
    for (uint i = 0; i < QKeySequencePrivate::numberOfKeyBindings ; ++i) {
        QKeyBinding keyBinding = QKeySequencePrivate::keyBindings[i];
        if (keyBinding.standardKey == key && (keyBinding.platform & platform)) {
            uint shortcut =
#ifdef Q_WS_MAC
                    maybeSwapShortcut(QKeySequencePrivate::keyBindings[i].shortcut);
#else
                    QKeySequencePrivate::keyBindings[i].shortcut;
#endif
            if (keyBinding.priority > 0)
                list.prepend(QKeySequence(shortcut));
            else
                list.append(QKeySequence(shortcut));
        }
    }
    return list;
}

matches()

QKeySequence::SequenceMatch QKeySequence::matches

(

const QKeySequence &

seq

)

const

Matches the sequence with seq.

Returns ExactMatch if successful, PartialMatch if seq matches incompletely, and NoMatch if the sequences have nothing in common. Returns NoMatch if seq is shorter.

Definition at line 1471 of file qkeysequence.cpp.

{
    uint userN = count(),
          seqN = seq.count();

    if (userN > seqN)
        return NoMatch;

    // If equal in length, we have a potential ExactMatch sequence,
    // else we already know it can only be partial.
    SequenceMatch match = (userN == seqN ? ExactMatch : PartialMatch);

    for (uint i = 0; i < userN; ++i) {
        int userKey = (*this)[i],
            sequenceKey = seq[i];
        if (userKey != sequenceKey)
            return NoMatch;
    }
    return match;
}

mnemonic()

QKeySequence QKeySequence::mnemonic ( const QString &  text )

static

Returns the shortcut key sequence for the mnemonic in text, or an empty key sequence if no mnemonics are found.

For example, mnemonic("E&xit") returns Qt::ALT+Qt::Key_X, mnemonic("&Quit") returns ALT+Key_Q, and mnemonic("Quit") returns an empty QKeySequence.

We provide a list of common mnemonics in English. At the time of writing, Microsoft and Open Group do not appear to have issued equivalent recommendations for other languages.

See also

qt_set_sequence_auto_mnemonic()

Definition at line 1103 of file qkeysequence.cpp.

Referenced by QTabBar::insertTab(), QMenu::keyPressEvent(), QTabBar::setTabText(), QAbstractButton::setText(), QGroupBox::setTitle(), QMenuBarPrivate::updateGeometries(), and QLabelPrivate::updateShortcut().

{
    QKeySequence ret;

    if(qt_sequence_no_mnemonics)
        return ret;

    bool found = false;
    int p = 0;
    while (p >= 0) {
        p = text.indexOf(QLatin1Char('&'), p) + 1;
        if (p <= 0 || p >= (int)text.length())
            break;
        if (text.at(p) != QLatin1Char('&')) {
            QChar c = text.at(p);
            if (c.isPrint()) {
                if (!found) {
                    c = c.toUpper();
                    ret = QKeySequence(c.unicode() + Qt::ALT);
#ifdef QT_NO_DEBUG
                    return ret;
#else
                    found = true;
                } else {
                    qWarning("QKeySequence::mnemonic: \"%s\" contains multiple occurrences of '&'", qPrintable(text));
#endif
                }
            }
        }
        p++;
    }
    return ret;
}

operator int()

QKeySequence::operator int

(

)

const

For backward compatibility: returns the first keycode as integer.

Definition at line 1526 of file qkeysequence.cpp.

{
    if (1 <= count())
        return d->key[0];
    return 0;
}

operator QString()

QKeySequence::operator QString

(

)

const

Use toString() instead.

Returns the key sequence as a QString. This is equivalent to calling toString(QKeySequence::NativeText). Note that the result is not platform independent.

Definition at line 1505 of file qkeysequence.cpp.

{
    return QKeySequence::toString(QKeySequence::NativeText);
}

operator QVariant()

QKeySequence::operator QVariant

(

)

const

Returns the key sequence as a QVariant.

Definition at line 1513 of file qkeysequence.cpp.

{
    return QVariant(QVariant::KeySequence, this);
}

operator!=()

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

inline

Returns true if this key sequence is not equal to the other key sequence; otherwise returns false.

Definition at line 188 of file qkeysequence.h.

    { return !(*this == other); }

operator<()

bool QKeySequence::operator<

(

const QKeySequence &

other

)

const

Provides an arbitrary comparison of this key sequence and other key sequence.

All that is guaranteed is that the operator returns false if both key sequences are equal and that (ks1 < ks2) == !( ks2 < ks1) if the key sequences are not equal.

This function is useful in some circumstances, for example if you want to use QKeySequence objects as keys in a QMap.

See also

operator==() operator!=() operator>() operator<=() operator>=()

Definition at line 1602 of file qkeysequence.cpp.

{
    for (int i = 0; i < 4; ++i)
        if (d->key[i] != other.d->key[i])
            return d->key[i] < other.d->key[i];
    return false;
}

operator<=()

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

inline

Returns true if this key sequence is smaller or equal to the other key sequence; otherwise returns false.

See also

operator==() operator!=() operator<() operator>() operator>=()

Definition at line 193 of file qkeysequence.h.

    { return !(other < *this); }

operator=()

QKeySequence & QKeySequence::operator=

(

const QKeySequence &

other

)

Assignment operator.

Assigns the other key sequence to this object.

Definition at line 1549 of file qkeysequence.cpp.

{
    qAtomicAssign(d, other.d);
    return *this;
}

operator==()

bool QKeySequence::operator==

(

const QKeySequence &

other

)

const

Returns true if this key sequence is equal to the other key sequence; otherwise returns false.

Definition at line 1581 of file qkeysequence.cpp.

{
    return (d->key[0] == other.d->key[0] &&
            d->key[1] == other.d->key[1] &&
            d->key[2] == other.d->key[2] &&
            d->key[3] == other.d->key[3]);
}

operator>()

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

inline

Returns true if this key sequence is larger than the other key sequence; otherwise returns false.

See also

operator==() operator!=() operator<() operator<=() operator>=()

Definition at line 191 of file qkeysequence.h.

    { return other < *this; }

operator>=()

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

inline

Returns true if this key sequence is larger or equal to the other key sequence; otherwise returns false.

See also

operator==() operator!=() operator<() operator>() operator<=()

Definition at line 195 of file qkeysequence.h.

    { return !(*this < other); }

operator[]()

int QKeySequence::operator[]

(

uint

index

)

const

Returns a reference to the element at position index in the key sequence.

This can only be used to read an element.

Definition at line 1538 of file qkeysequence.cpp.

{
    Q_ASSERT_X(index < 4, "QKeySequence::operator[]", "index out of range");
    return d->key[index];
}

setKey()

void QKeySequence::setKey ( int  key, int  index  )

private

KeySequences should never be modified, but rather just created.

Warning

This function is not part of the public interface.

Internally though we do need to modify to keep pace in event delivery.

Definition at line 1053 of file qkeysequence.cpp.

Referenced by QShortcutMap::createNewSequences().

{
    Q_ASSERT_X(index >= 0 && index < 4, "QKeySequence::setKey", "index out of range");
    qAtomicDetach(d);
    d->key[index] = key;
}

swap()

void QKeySequence::swap ( QKeySequence &  other )

inline

Swaps key sequence other with this key sequence.

Since

4.8

This operation is very fast and never fails.

Definition at line 186 of file qkeysequence.h.

{ qSwap(d, other.d); }

toString()

QString QKeySequence::toString

(

SequenceFormat

format = PortableText

)

const

Return a string representation of the key sequence, based on format.

Since

4.1

For example, the value Qt::CTRL+Qt::Key_O results in "Ctrl+O". If the key sequence has multiple key codes, each is separated by commas in the string returned, such as "Alt+X, Ctrl+Y, Z". The strings, "Ctrl", "Shift", etc. are translated using QObject::tr() in the "QShortcut" context.

If the key sequence has no keys, an empty string is returned.

On Mac OS X, the string returned resembles the sequence that is shown in the menu bar.

See also

fromString()

Definition at line 1676 of file qkeysequence.cpp.

Referenced by QAccessibleWidget::actionText(), QAccessibleButton::keyBindings(), QAccessibleMenuItem::keyBindings(), operator QString(), operator<<(), QMenuPrivate::QMacMenuPrivate::syncAction(), and QAccessibleMenuItem::text().

{
    QString finalString;
    // A standard string, with no translation or anything like that. In some ways it will
    // look like our latin case on Windows and X11
    int end = count();
    for (int i = 0; i < end; ++i) {
        finalString += d->encodeString(d->key[i], format);
        finalString += QLatin1String(", ");
    }
    finalString.truncate(finalString.length() - 2);
    return finalString;
}

Friends and Related Functions

operator<<

QDataStream & operator<< ( QDataStream &  stream, const QKeySequence &  sequence  )

friend

Writes the key sequence to the stream.

See also

Format of the QDataStream operators

Definition at line 1720 of file qkeysequence.cpp.

{
    QList<quint32> list;
    list << keysequence.d->key[0];

    if (s.version() >= 5 && keysequence.count() > 1) {
        list << keysequence.d->key[1];
        list << keysequence.d->key[2];
        list << keysequence.d->key[3];
    }
    s << list;
    return s;
}

operator>>

QDataStream & operator>> ( QDataStream &  stream, QKeySequence &  sequence  )

friend

Reads a key sequence from the stream into the key sequence.

See also

Format of the QDataStream operators

Definition at line 1746 of file qkeysequence.cpp.

{
    qAtomicDetach(keysequence.d);
    QList<quint32> list;
    s >> list;
    for (int i = 0; i < 4; ++i)
        keysequence.d->key[i] = list.value(i);
    return s;
}

Q3AccelManager

friend class Q3AccelManager

friend

Definition at line 210 of file qkeysequence.h.

QShortcut

friend class QShortcut

friend

Definition at line 212 of file qkeysequence.h.

QShortcutMap

friend class QShortcutMap

friend

Definition at line 211 of file qkeysequence.h.

Properties

d

QKeySequencePrivate* QKeySequence::d

private

Definition at line 206 of file qkeysequence.h.

Referenced by assign(), count(), isDetached(), isEmpty(), operator int(), operator<(), operator<<(), operator=(), operator==(), operator>>(), operator[](), QKeySequence(), setKey(), swap(), toString(), and ~QKeySequence().

---

The documentation for this class was generated from the following files:

• /src/gui/kernel/qkeysequence.h
• /src/gui/kernel/qkeysequence.cpp