[wxWidgets.git] / interface / wx / kbdstate.h

/////////////////////////////////////////////////////////////////////////////
// Name:        wx/kbdstate.h
// Purpose:     documentation of wxKeyboardState
// Author:      wxWidgets team
// Created:     2008-09-19
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    Provides methods for testing the state of the keyboard modifier keys.

    This class is used as a base class of wxKeyEvent and wxMouseState and,
    hence, indirectly, of wxMouseEvent, so its methods may be used to get
    information about the modifier keys which were pressed when the event
    occurred.

    This class is implemented entirely inline in @<wx/kbdstate.h@> and thus has
    no linking requirements.

    @nolibrary
    @category{events}

    @see wxKeyEvent, wxMouseState
 */
class wxKeyboardState
{
public:
    /**
        Constructor initializes the modifier key settings.

        By default, no modifiers are active.
     */
    wxKeyboardState(bool controlDown = false,
                    bool shiftDown = false,
                    bool altDown = false,
                    bool metaDown = false);

    /**
        Return the bit mask of all pressed modifier keys.

        The return value is a combination of @c wxMOD_ALT, @c wxMOD_CONTROL,
        @c wxMOD_SHIFT and @c wxMOD_META bit masks. Additionally, @c wxMOD_NONE
        is defined as 0, i.e. corresponds to no modifiers (see HasModifiers())
        and @c wxMOD_CMD is either @c wxMOD_CONTROL (MSW and Unix) or
        @c wxMOD_META (Mac), see CmdDown().
        See ::wxKeyModifier for the full list of modifiers.

        Notice that this function is easier to use correctly than, for example,
        ControlDown() because when using the latter you also have to remember to
        test that none of the other modifiers is pressed:

        @code
        if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() )
            ... handle Ctrl-XXX ...
        @endcode

        and forgetting to do it can result in serious program bugs (e.g. program
        not working with European keyboard layout where @c AltGr key which is
        seen by the program as combination of CTRL and ALT is used). On the
        other hand, you can simply write:

        @code
        if ( GetModifiers() == wxMOD_CONTROL )
            ... handle Ctrl-XXX ...
        @endcode

        with this function.
    */
    int GetModifiers() const;

    /**
        Returns true if any modifiers at all are pressed.

        This is equivalent to @c GetModifiers() @c != @c wxMOD_NONE.
     */
    bool HasModifiers() const;

    /**
        Returns true if the Control key is pressed.

        This function doesn't distinguish between right and left control keys.

        In portable code you usually want to use CmdDown() to automatically
        test for the more frequently used Command key (and not the rarely used
        Control one) under Mac.

        Notice that GetModifiers() should usually be used instead of this one.
     */
    bool ControlDown() const;

    /**
        Returns true if the Shift key is pressed.

        This function doesn't distinguish between right and left shift keys.

        Notice that GetModifiers() should usually be used instead of this one.
     */
    bool ShiftDown() const;

    /**
        Returns true if the Meta/Windows/Apple key is pressed.

        This function tests the state of the key traditionally called Meta
        under Unix systems, Windows keys under MSW and Apple, or Command, key
        under Mac.

        Notice that GetModifiers() should usually be used instead of this one.

        @see CmdDown()
     */
    bool MetaDown() const;

    /**
        Returns true if the Alt key is pressed.

        Notice that GetModifiers() should usually be used instead of this one.
     */
    bool AltDown() const;

    /**
        Returns true if the key used for command accelerators is pressed.

        @c Cmd is a pseudo key which is Control for PC and Unix platforms but
        Apple (or Command) key under Macs: it makes often sense to use it
        instead of ControlDown() because @c Command key is used for the same
        thing under Mac as @c Control elsewhere (even though @c Control still
        exists, it is usually not used for the same purpose under Mac).

        Notice that GetModifiers() should usually be used instead of this one.
     */
    bool CmdDown() const;
};
Commit	Line	Data
0e097789 VZ	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 license
	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
d4624460	18	This class is implemented entirely inline in @<wx/kbdstate.h@> and thus has
0e097789 VZ	19	no linking requirements.
0e097789 VZ	20
d4624460	21	@nolibrary
9e0ed083	22	@category{events}
0e097789 VZ	23
	24	@see wxKeyEvent, wxMouseState
	25	*/
	26	class wxKeyboardState
	27	{
	28	public:
	29	/**
ba4d737a	30	Constructor initializes the modifier key settings.
0e097789 VZ	31
	32	By default, no modifiers are active.
	33	*/
0a98423e FM	34	wxKeyboardState(bool controlDown = false,
	35	bool shiftDown = false,
	36	bool altDown = false,
	37	bool metaDown = false);
0e097789 VZ	38
	39	/**
	40	Return the bit mask of all pressed modifier keys.
0a98423e	41
0e097789 VZ	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 HasModifiers())
d4624460 FM	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.
0e097789 VZ	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	bool HasModifiers() const;
	78
	79	/**
	80	Returns true if the Control key is pressed.
	81
	82	This function doesn't distinguish between right and left control keys.
	83
	84	In portable code you usually want to use CmdDown() to automatically
	85	test for the more frequently used Command key (and not the rarely used
	86	Control one) under Mac.
	87
	88	Notice that GetModifiers() should usually be used instead of this one.
	89	*/
	90	bool ControlDown() const;
	91
	92	/**
	93	Returns true if the Shift key is pressed.
	94
	95	This function doesn't distinguish between right and left shift keys.
	96
	97	Notice that GetModifiers() should usually be used instead of this one.
	98	*/
	99	bool ShiftDown() const;
	100
	101	/**
	102	Returns true if the Meta/Windows/Apple key is pressed.
	103
	104	This function tests the state of the key traditionally called Meta
	105	under Unix systems, Windows keys under MSW and Apple, or Command, key
	106	under Mac.
	107
	108	Notice that GetModifiers() should usually be used instead of this one.
	109
	110	@see CmdDown()
	111	*/
112	bool MetaDown() const;
113
114	/**
115	Returns true if the Alt key is pressed.
116
117	Notice that GetModifiers() should usually be used instead of this one.
118	*/
119	bool AltDown() const;
120
121	/**
122	Returns true if the key used for command accelerators is pressed.
123
124	@c Cmd is a pseudo key which is Control for PC and Unix platforms but
125	Apple (or Command) key under Macs: it makes often sense to use it
126	instead of ControlDown() because @c Command key is used for the same
127	thing under Mac as @c Control elsewhere (even though @c Control still
128	exists, it is usually not used for the same purpose under Mac).
129
130	Notice that GetModifiers() should usually be used instead of this one.
131	*/
132	bool CmdDown() const;
133	};
134