+ @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(),
+ wxWindow::PushEventHandler, wxWindow::PopEventHandler
+ */
+ wxEvtHandler* GetNextHandler() const;
+
+ /**
+ Returns the pointer to the previous handler in the chain.
+
+ @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(),
+ wxWindow::PushEventHandler, wxWindow::PopEventHandler
+ */
+ wxEvtHandler* GetPreviousHandler() const;
+
+ /**
+ Processes an event, searching event tables and calling zero or more suitable
+ event handler function(s).
+
+ Normally, your application would not call this function: it is called in the
+ wxWidgets implementation to dispatch incoming user interface events to the
+ framework (and application).
+
+ However, you might need to call it if implementing new functionality
+ (such as a new control) where you define new event types, as opposed to
+ allowing the user to override virtual functions.
+
+ An instance where you might actually override the ProcessEvent function is where
+ you want to direct event processing to event handlers not normally noticed by
+ wxWidgets. For example, in the document/view architecture, documents and views
+ are potential event handlers. When an event reaches a frame, ProcessEvent will
+ need to be called on the associated document and view in case event handler functions
+ are associated with these objects. The property classes library (wxProperty) also
+ overrides ProcessEvent for similar reasons.
+
+ The normal order of event table searching is as follows:
+ -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
+ the function skips to step (6).
+ -# If the object is a wxWindow, ProcessEvent() is recursively called on the
+ window's wxValidator. If this returns @true, the function exits.
+ -# SearchEventTable() is called for this event handler. If this fails, the base
+ class table is tried, and so on until no more tables exist or an appropriate
+ function was found, in which case the function exits.
+ -# The search is applied down the entire chain of event handlers (usually the
+ chain has a length of one). If this succeeds, the function exits.
+ -# If the object is a wxWindow and the event is a wxCommandEvent, ProcessEvent()
+ is recursively applied to the parent window's event handler.
+ If this returns true, the function exits.
+ -# Finally, ProcessEvent() is called on the wxApp object.
+
+ @param event
+ Event to process.
+
+ @returns @true if a suitable event handler function was found and
+ executed, and the function did not call wxEvent::Skip.
+
+ @see SearchEventTable()
+ */
+ virtual bool ProcessEvent(wxEvent& event);
+
+ /**
+ Processes an event by calling ProcessEvent() and handles any exceptions
+ that occur in the process.
+ If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called.
+
+ @param event
+ Event to process.
+
+ @returns @true if the event was processed, @false if no handler was found
+ or an exception was thrown.
+
+ @see wxWindow::HandleWindowEvent
+ */
+ bool SafelyProcessEvent(wxEvent& event);
+
+ /**
+ Searches the event table, executing an event handler function if an appropriate
+ one is found.
+
+ @param table
+ Event table to be searched.
+ @param event
+ Event to be matched against an event table entry.
+
+ @returns @true if a suitable event handler function was found and
+ executed, and the function did not call wxEvent::Skip.
+
+ @remarks This function looks through the object's event table and tries
+ to find an entry that will match the event.
+ An entry will match if:
+ @li The event type matches, and
+ @li the identifier or identifier range matches, or the event table
+ entry's identifier is zero.
+ If a suitable function is called but calls wxEvent::Skip, this
+ function will fail, and searching will continue.
+
+ @see ProcessEvent()
+ */
+ virtual bool SearchEventTable(wxEventTable& table,
+ wxEvent& event);
+
+ /**
+ Sets user-supplied client data.
+
+ @param data
+ Data to be associated with the event handler.
+
+ @remarks Normally, any extra data the programmer wishes to associate
+ with the object should be made available by deriving a new
+ class with new data members. You must not call this method
+ and SetClientObject on the same class - only one of them.
+
+ @see GetClientData()
+ */
+ void SetClientData(void* data);
+
+ /**
+ Set the client data object. Any previous object will be deleted.
+
+ @see GetClientObject(), wxClientData
+ */
+ void SetClientObject(wxClientData* data);
+
+ /**
+ Enables or disables the event handler.
+
+ @param enabled
+ @true if the event handler is to be enabled, @false if it is to be disabled.
+
+ @remarks You can use this function to avoid having to remove the event
+ handler from the chain, for example when implementing a
+ dialog editor and changing from edit to test mode.
+
+ @see GetEvtHandlerEnabled()
+ */
+ void SetEvtHandlerEnabled(bool enabled);
+
+ /**
+ Sets the pointer to the next handler.
+
+ @param handler
+ Event handler to be set as the next handler.
+
+ @see GetNextHandler(), SetPreviousHandler(), GetPreviousHandler(),
+ wxWindow::PushEventHandler, wxWindow::PopEventHandler
+ */
+ void SetNextHandler(wxEvtHandler* handler);
+
+ /**
+ Sets the pointer to the previous handler.
+
+ @param handler
+ Event handler to be set as the previous handler.
+ */
+ void SetPreviousHandler(wxEvtHandler* handler);
+};
+
+
+/**
+ @class wxKeyEvent
+ @wxheader{event.h}
+
+ This event class contains information about keypress (character) events.
+
+ Notice that there are three different kinds of keyboard events in wxWidgets:
+ key down and up events and char events. The difference between the first two
+ is clear - the first corresponds to a key press and the second to a key
+ release - otherwise they are identical. Just note that if the key is
+ maintained in a pressed state you will typically get a lot of (automatically
+ generated) down events but only one up so it is wrong to assume that there is
+ one up event corresponding to each down one.
+
+ Both key events provide untranslated key codes while the char event carries
+ the translated one. The untranslated code for alphanumeric keys is always
+ an upper case value. For the other keys it is one of @c WXK_XXX values
+ from the @ref page_keycodes.
+ The translated key is, in general, the character the user expects to appear
+ as the result of the key combination when typing the text into a text entry
+ zone, for example.
+
+ A few examples to clarify this (all assume that CAPS LOCK is unpressed
+ and the standard US keyboard): when the @c 'A' key is pressed, the key down
+ event key code is equal to @c ASCII A == 65. But the char event key code
+ is @c ASCII a == 97. On the other hand, if you press both SHIFT and
+ @c 'A' keys simultaneously , the key code in key down event will still be
+ just @c 'A' while the char event key code parameter will now be @c 'A'
+ as well.
+
+ Although in this simple case it is clear that the correct key code could be
+ found in the key down event handler by checking the value returned by
+ wxKeyEvent::ShiftDown(), in general you should use @c EVT_CHAR for this as
+ for non-alphanumeric keys the translation is keyboard-layout dependent and
+ can only be done properly by the system itself.
+
+ Another kind of translation is done when the control key is pressed: for
+ example, for CTRL-A key press the key down event still carries the
+ same key code @c 'a' as usual but the char event will have key code of 1,
+ the ASCII value of this key combination.
+
+ You may discover how the other keys on your system behave interactively by
+ running the @ref page_samples_text wxWidgets sample and pressing some keys
+ in any of the text controls shown in it.
+
+ @b Tip: be sure to call @c event.Skip() for events that you don't process in
+ key event function, otherwise menu shortcuts may cease to work under Windows.
+
+ @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler
+ does not call @c event.Skip() then the corresponding char event
+ (@c EVT_CHAR) will not happen.
+ This is by design and enables the programs that handle both types of
+ events to be a bit simpler.
+
+ @note For Windows programmers: The key and char events in wxWidgets are
+ similar to but slightly different from Windows @c WM_KEYDOWN and
+ @c WM_CHAR events. In particular, Alt-x combination will generate a
+ char event in wxWidgets (unless it is used as an accelerator).
+
+
+ @beginEventTable{wxKeyEvent}
+ @event{EVT_KEY_DOWN(func)}
+ Process a wxEVT_KEY_DOWN event (any key has been pressed).
+ @event{EVT_KEY_UP(func)}
+ Process a wxEVT_KEY_UP event (any key has been released).
+ @event{EVT_CHAR(func)}
+ Process a wxEVT_CHAR event.
+ @endEventTable
+
+ @library{wxcore}
+ @category{events}
+*/
+class wxKeyEvent : public wxEvent
+{
+public:
+ /**
+ Constructor.
+ Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK.
+ */
+ wxKeyEvent(wxEventType keyEventType = wxEVT_NULL);
+
+ /**
+ Returns @true if the Alt key was down at the time of the key event.
+
+ Notice that GetModifiers() is easier to use correctly than this function
+ so you should consider using it in new code.
+ */
+ bool AltDown() const;
+
+ /**
+ CMD is a pseudo key which is the same as Control for PC and Unix
+ platforms but the special APPLE (a.k.a as COMMAND) key under Macs:
+ it makes often sense to use it instead of, say, ControlDown() because Cmd
+ key is used for the same thing under Mac as Ctrl elsewhere (but Ctrl still
+ exists, just not used for this purpose under Mac). So for non-Mac platforms
+ this is the same as ControlDown() and under Mac this is the same as MetaDown().
+ */
+ bool CmdDown() const;
+
+ /**
+ Returns @true if the control key was down at the time of the key event.
+
+ Notice that GetModifiers() is easier to use correctly than this function
+ so you should consider using it in new code.
+ */
+ bool ControlDown() const;
+
+ /**
+ Returns the virtual key code. ASCII events return normal ASCII values,
+ while non-ASCII events return values such as @b WXK_LEFT for the left cursor
+ key. See @ref page_keycodes for a full list of the virtual key codes.
+
+ Note that in Unicode build, the returned value is meaningful only if the
+ user entered a character that can be represented in current locale's default
+ charset. You can obtain the corresponding Unicode character using GetUnicodeKey().
+ */
+ int GetKeyCode() const;
+
+ /**
+ Return the bitmask of modifier keys which were pressed when this event
+ happened. See @ref page_keymodifiers 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 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;
+
+ //@{
+ /**
+ Obtains the position (in client coordinates) at which the key was pressed.
+ */
+ wxPoint GetPosition() const;
+ void GetPosition(long* x, long* y) const;
+ //@}
+
+ /**
+ Returns the raw key code for this event. This is a platform-dependent scan code
+ which should only be used in advanced applications.
+
+ @note Currently the raw key codes are not supported by all ports, use
+ @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available.
+ */
+ wxUint32 GetRawKeyCode() const;
+
+ /**
+ Returns the low level key flags for this event. The flags are
+ platform-dependent and should only be used in advanced applications.
+
+ @note Currently the raw key flags are not supported by all ports, use
+ @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available.
+ */
+ wxUint32 GetRawKeyFlags() const;
+
+ /**
+ Returns the Unicode character corresponding to this key event.
+
+ This function is only available in Unicode build, i.e. when
+ @c wxUSE_UNICODE is 1.
+ */
+ wxChar GetUnicodeKey() const;
+
+ /**
+ Returns the X position (in client coordinates) of the event.
+ */
+ wxCoord GetX() const;
+
+ /**
+ Returns the Y position (in client coordinates) of the event.
+ */
+ wxCoord GetY() const;
+
+ /**
+ Returns @true if either CTRL or ALT keys was down at the time of the
+ key event.
+
+ Note that this function does not take into account neither SHIFT nor
+ META key states (the reason for ignoring the latter is that it is
+ common for NUMLOCK key to be configured as META under X but the key
+ presses even while NUMLOCK is on should be still processed normally).
+ */
+ bool HasModifiers() const;
+
+ /**
+ Returns @true if the Meta key was down at the time of the key event.
+
+ Notice that GetModifiers() is easier to use correctly than this function
+ so you should consider using it in new code.
+ */
+ bool MetaDown() const;
+
+ /**
+ Returns @true if the shift key was down at the time of the key event.
+
+ Notice that GetModifiers() is easier to use correctly than this function
+ so you should consider using it in new code.
+ */
+ bool ShiftDown() const;
+};
+
+
+
+/**
+ @class wxJoystickEvent
+ @wxheader{event.h}
+
+ This event class contains information about joystick events, particularly
+ events received by windows.
+
+ @beginEventTable{wxJoystickEvent}
+ @style{EVT_JOY_BUTTON_DOWN(func)}
+ Process a wxEVT_JOY_BUTTON_DOWN event.
+ @style{EVT_JOY_BUTTON_UP(func)}
+ Process a wxEVT_JOY_BUTTON_UP event.
+ @style{EVT_JOY_MOVE(func)}
+ Process a wxEVT_JOY_MOVE event.
+ @style{EVT_JOY_ZMOVE(func)}
+ Process a wxEVT_JOY_ZMOVE event.
+ @style{EVT_JOYSTICK_EVENTS(func)}
+ Processes all joystick events.
+ @endEventTable
+
+ @library{wxcore}
+ @category{events}
+
+ @see wxJoystick
+*/
+class wxJoystickEvent : public wxEvent
+{
+public:
+ /**
+ Constructor.
+ */
+ wxJoystickEvent(wxEventType eventType = wxEVT_NULL, int state = 0,
+ int joystick = wxJOYSTICK1,
+ int change = 0);
+
+ /**
+ Returns @true if the event was a down event from the specified button
+ (or any button).
+
+ @param button
+ Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
+ indicate any button down event.
+ */
+ bool ButtonDown(int button = wxJOY_BUTTON_ANY) const;
+
+ /**
+ Returns @true if the specified button (or any button) was in a down state.
+
+ @param button
+ Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
+ indicate any button down event.
+ */
+ bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const;
+
+ /**
+ Returns @true if the event was an up event from the specified button
+ (or any button).
+
+ @param button
+ Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
+ indicate any button down event.
+ */
+ bool ButtonUp(int button = wxJOY_BUTTON_ANY) const;
+
+ /**
+ Returns the identifier of the button changing state.
+
+ This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
+ */
+ int GetButtonChange() const;
+
+ /**
+ Returns the down state of the buttons.
+
+ This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
+ */
+ int GetButtonState() const;
+
+ /**
+ Returns the identifier of the joystick generating the event - one of
+ wxJOYSTICK1 and wxJOYSTICK2.
+ */
+ int GetJoystick() const;
+
+ /**
+ Returns the x, y position of the joystick event.
+ */
+ wxPoint GetPosition() const;
+
+ /**
+ Returns the z position of the joystick event.
+ */
+ int GetZPosition() const;
+
+ /**
+ Returns @true if this was a button up or down event
+ (@e not 'is any button down?').
+ */
+ bool IsButton() const;
+
+ /**
+ Returns @true if this was an x, y move event.
+ */
+ bool IsMove() const;
+
+ /**
+ Returns @true if this was a z move event.
+ */
+ bool IsZMove() const;
+};
+
+
+
+/**
projects / wxWidgets.git / blobdiff