git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: wx/kbdstate.h
	3	// Purpose: documentation of wxKeyboardState
	4	// Author: wxWidgets team
	5	// Created: 2008-09-19
	6	// RCS-ID: $Id$
	7	// Licence: wxWindows licence
	8	/////////////////////////////////////////////////////////////////////////////
	9
	10	/**
	11	Provides methods for testing the state of the keyboard modifier keys.
	12
	13	This class is used as a base class of wxKeyEvent and wxMouseState and,
	14	hence, indirectly, of wxMouseEvent, so its methods may be used to get
	15	information about the modifier keys which were pressed when the event
	16	occurred.
	17
	18	This class is implemented entirely inline in @<wx/kbdstate.h@> and thus has
	19	no linking requirements.
	20
	21	@nolibrary
	22	@category{events}
	23
	24	@see wxKeyEvent, wxMouseState
	25	*/
	26	class wxKeyboardState
	27	{
	28	public:
	29	/**
	30	Constructor initializes the modifier key settings.
	31
	32	By default, no modifiers are active.
	33	*/
	34	wxKeyboardState(bool controlDown = false,
	35	bool shiftDown = false,
	36	bool altDown = false,
	37	bool metaDown = false);
	38
	39	/**
	40	Return the bit mask of all pressed modifier keys.
	41
	42	The return value is a combination of @c wxMOD_ALT, @c wxMOD_CONTROL,
	43	@c wxMOD_SHIFT and @c wxMOD_META bit masks. Additionally, @c wxMOD_NONE
	44	is defined as 0, i.e. corresponds to no modifiers (see HasAnyModifiers())
	45	and @c wxMOD_CMD is either @c wxMOD_CONTROL (MSW and Unix) or
	46	@c wxMOD_META (Mac), see CmdDown().
	47	See ::wxKeyModifier for the full list of modifiers.
	48
	49	Notice that this function is easier to use correctly than, for example,
	50	ControlDown() because when using the latter you also have to remember to
	51	test that none of the other modifiers is pressed:
	52
	53	@code
	54	if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() )
	55	... handle Ctrl-XXX ...
	56	@endcode
	57
	58	and forgetting to do it can result in serious program bugs (e.g. program
	59	not working with European keyboard layout where @c AltGr key which is
	60	seen by the program as combination of CTRL and ALT is used). On the
	61	other hand, you can simply write:
	62
	63	@code
	64	if ( GetModifiers() == wxMOD_CONTROL )
	65	... handle Ctrl-XXX ...
	66	@endcode
	67
	68	with this function.
	69	*/
	70	int GetModifiers() const;
	71
	72	/**
	73	Returns true if any modifiers at all are pressed.
	74
	75	This is equivalent to @c GetModifiers() @c != @c wxMOD_NONE.
	76
	77	Notice that this is different from HasModifiers() method which doesn't
	78	take e.g. Shift modifier into account. This method is most suitable for
	79	mouse events when any modifier, including Shift, can change the
	80	interpretation of the event.
	81
	82	@since 2.9.5
	83	*/
	84	bool HasAnyModifiers() const;
	85
	86	/**
	87	Returns true if Control or Alt are pressed.
	88
	89	Checks if Control, Alt or, under OS X only, Command key are pressed
	90	(notice that the real Control key is still taken into account under OS
	91	X too).
	92
	93	This method returns @false if only Shift is pressed for compatibility
	94	reasons and also because pressing Shift usually doesn't change the
	95	interpretation of key events, see HasAnyModifiers() if you want to
	96	take Shift into account as well.
	97	*/
	98	bool HasModifiers() const;
	99
	100	/**
	101	Returns true if the Control key or Apple/Command key under OS X is pressed.
	102
	103	This function doesn't distinguish between right and left control keys.
	104
	105	Notice that GetModifiers() should usually be used instead of this one.
	106	*/
	107	bool ControlDown() const;
	108
	109	/**
	110	Returns true if the Control key (also under OS X).
	111
	112	This function doesn't distinguish between right and left control keys.
	113
	114	Notice that GetModifiers() should usually be used instead of this one.
	115	*/
	116	bool RawControlDown() const;
	117
	118	/**
	119	Returns true if the Shift key is pressed.
	120
	121	This function doesn't distinguish between right and left shift keys.
	122
	123	Notice that GetModifiers() should usually be used instead of this one.
	124	*/
	125	bool ShiftDown() const;
	126
	127	/**
	128	Returns true if the Meta/Windows/Apple key is pressed.
	129
	130	This function tests the state of the key traditionally called Meta
	131	under Unix systems, Windows keys under MSW
	132	Notice that GetModifiers() should usually be used instead of this one.
	133
	134	@see CmdDown()
	135	*/
	136	bool MetaDown() const;
	137
	138	/**
	139	Returns true if the Alt key is pressed.
	140
	141	Notice that GetModifiers() should usually be used instead of this one.
	142	*/
	143	bool AltDown() const;
	144
	145	/**
	146	Returns true if the key used for command accelerators is pressed. Same as
	147	ControlDown(). Deprecated.
	148
	149	Notice that GetModifiers() should usually be used instead of this one.
	150	*/
	151	bool CmdDown() const;
	152
	153
	154	void SetControlDown(bool down);
	155	void SetRawControlDown(bool down);
	156	void SetShiftDown(bool down);
	157	void SetAltDown(bool down);
	158	void SetMetaDown(bool down);
	159
	160	};
	161