OSDL::Events::EventsModule Class Reference

Handles the asynchronous event-based interaction model, general input handling, and basic time management, including the logic and rendering frequencies. More...

#include <OSDLEvents.h>

Collaboration diagram for OSDL::Events::EventsModule:

[legend]

List of all members.

Public Member Functions
virtual void	waitForAnyKey (bool displayWaitingMessage=true) const
	Waits for any key to be hit.
virtual void	waitForAnyUserInput () const
	Waits for any user input: a key being hit, a mouse button being clicked, etc.
virtual bool	hasPendingUserInput () const
	Returns true iff there is at least one pending user input, like a key hit, a mouse or joystick button pushed.
virtual bool	getGrabInputMode () const
	Returns whether mouse and keyboard inputs are grabbed.
virtual void	setGrabInputMode (bool newMode)
	Tells whether mouse and keyboard inputs should be grabbed.
virtual bool	sleepFor (Ceylan::System::Second seconds, Ceylan::System::Microsecond micros) const
	Sleeps for the specified duration.
virtual void	useScheduler (bool on=true)
	Defines whether a scheduler should be used by the event loop.
virtual bool	isGUIEnabled () const
	Tells whether a GUI (Graphical User Interface) is to be supported by this events module.
virtual void	setGUIEnableStatus (bool newStatus)
	Determines whether a GUI (Graphical User Interface) should be supported by this events module.
virtual void	setIdleCallback (Ceylan::System::Callback idleCallback, void *callbackData=0, Ceylan::System::Microsecond callbackExpectedMaxDuration=0)
	Sets the idle function, which is called whenever the current scheduling system, either the main event loop or the scheduler, detects a period of idle activity.
virtual void	setEventLoopTargetFrequency (Ceylan::Maths::Hertz targetFrequency)
	Sets the actual target frequency that the basic event loop will try to run at.
virtual void	enterMainLoop ()
	Enters the main event loop.
virtual void	requestQuit ()
	Requests the application to quit by exiting the main loop.
virtual bool	hasKeyboardHandler () const
	Tells whether a keyboard handler is available.
virtual KeyboardHandler &	getKeyboardHandler () const
	Returns the keyboard handler currently used.
virtual void	setKeyboardHandler (KeyboardHandler &newHandler)
	Sets a new keyboard handler.
virtual bool	hasJoystickHandler () const
	Tells whether a joystick handler is available.
virtual JoystickHandler &	getJoystickHandler () const
	Returns the joystick handler currently used.
virtual void	setJoystickHandler (JoystickHandler &newHandler)
	Sets a new joystick handler.
virtual bool	hasMouseHandler () const
	Tells whether a mouse handler is available.
virtual MouseHandler &	getMouseHandler () const
	Returns the mouse handler currently used.
virtual void	setMouseHandler (MouseHandler &newHandler)
	Sets a new mouse handler.
virtual void	updateInputState ()
	Updates the state of the various inputs of interest (keyboard, mouse, joystick).
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns an user-friendly description of the state of this object.
Static Public Member Functions
static std::string	DescribeEnvironmentVariables ()
	Returns a summary about the possible use of events-related environment variables, for the selected back-end.
static bool	IsEventsInitialized ()
	Tells whether event system has already been initialized.
static Ceylan::System::Millisecond	GetMillisecondsSinceStartup ()
	Gets the number of milliseconds since the back-end initialization.
static std::string	DescribeEvent (const FocusEvent &focusEvent)
	Describes a focus event.
static std::string	DescribeEvent (const KeyboardEvent &keyboardEvent)
	Describes a keyboard event.
static std::string	DescribeEvent (const MouseMotionEvent &mouseMotionEvent)
	Describes a mouse motion event.
static std::string	DescribeEvent (const MouseButtonEvent &mouseButtonEvent)
	Describes a mouse button event.
static std::string	DescribeEvent (const JoystickAxisEvent &axisEvent)
	Describes a joystick axis event.
static std::string	DescribeEvent (const JoystickTrackballEvent &ballEvent)
	Describes a joystick trackball event.
static std::string	DescribeEvent (const JoystickHatEvent &hatEvent)
	Describes a joystick hat event.
static std::string	DescribeEvent (const JoystickButtonEvent &buttonEvent)
	Describes a joystick button event.
static std::string	DescribeEvent (const UserRequestedQuitEvent &quitEvent)
	Describes a quit event.
static std::string	DescribeEvent (const SystemSpecificWindowManagerEvent &windowManagerEvent)
	Describes a window manager event (system specific).
static std::string	DescribeEvent (const WindowResizedEvent &resizeEvent)
	Describes a window resized event.
static std::string	DescribeEvent (const ScreenExposedEvent &redrawEvent)
	Describes a screen exposed event (needs redraw).
static std::string	DescribeEvent (const UserEvent &userEvent)
	Describes an user event.
static Ceylan::System::Microsecond	EvaluateCallbackduration (Ceylan::System::Callback callback, void *callbackData)
	Tries to guess an upper-bound for the average duration of the execution of the specified callback.
static std::string	DescribeEvent (BasicEvent anEvent)
	Returns a string describing the specified basic event.
Static Public Attributes
static const BasicEventType	ApplicationFocusChanged = 1
	Identifies the event corresponding to application gaining or loosing focus(es).
static const BasicEventType	KeyPressed = 2
	Identifies the event corresponding to a key press.
static const BasicEventType	KeyReleased = 3
	Identifies the event corresponding to a key release.
static const BasicEventType	MouseMoved = 4
	Identifies the event corresponding to a mouse motion.
static const BasicEventType	MouseButtonPressed = 5
	Identifies the event corresponding to a mouse button press.
static const BasicEventType	MouseButtonReleased = 6
	Identifies the event corresponding to a mouse button release.
static const BasicEventType	JoystickAxisChanged = 7
	Identifies the event corresponding to a joystick axis move.
static const BasicEventType	JoystickTrackballChanged = 8
	Identifies the event corresponding to a joystick trackball motion.
static const BasicEventType	JoystickHatPositionChanged = 9
	Identifies the event corresponding to a change of joystick hat position.
static const BasicEventType	JoystickButtonPressed = 10
	Identifies the event corresponding to a joystick button being pressed.
static const BasicEventType	JoystickButtonReleased = 11
	Identifies the event corresponding to a joystick button being released.
static const BasicEventType	UserRequestedQuit = 12
	Identifies the event corresponding to the user requesting to quit.
static const BasicEventType	SystemSpecificTriggered = 13
	Identifies the event corresponding to system specific event.
static const BasicEventType	UserResizedVideoMode = 16
	Identifies the event corresponding to a resize of user's video mode.
static const BasicEventType	ScreenNeedsRedraw = 17
	Identifies the event corresponding to a need to redraw screen.
static const BasicEventType	FirstUserEventTriggered = 24
	Identifies the first event that can be user-defined.
static const BasicEventType	LastUserEventTriggered = 31
	Identifies the last event that can be user-defined.
static const UserEventType	NoEvent = 0
	Void event, useful to return when no event should be generated.
static const UserEventType	QuitRequested = 1
	Identifies the user event corresponding to a quit request.
static const Ceylan::Maths::Hertz	DefaultEventLoopTargetedFrequency = 100
	The default frequency targeted by the basic event loop.
Protected Member Functions
virtual void	enterBasicMainLoop ()
	Enters the basic event loop, not using any scheduler.
virtual void	onKeyboardFocusGained (const FocusEvent &keyboardFocusEvent)
	Called whenever the application gained keyboard focus.
virtual void	onKeyboardFocusLost (const FocusEvent &keyboardFocusEvent)
	Called whenever the application lost keyboard focus.
virtual void	onKeyPressed (const KeyboardEvent &keyboardEvent)
	Called whenever a key is pressed.
virtual void	onKeyReleased (const KeyboardEvent &keyboardEvent)
	Called whenever a key is released.
virtual void	onMouseFocusGained (const FocusEvent &mouseFocus)
	Called whenever the application gained mouse focus.
virtual void	onMouseFocusLost (const FocusEvent &mouseFocus)
	Called whenever t application lost mouse focus.
virtual void	onMouseMotion (const MouseMotionEvent &mouseEvent)
	Called whenever the mouse moved.
virtual void	onMouseButtonPressed (const MouseButtonEvent &mouseEvent)
	Called whenever a mouse button is pressed.
virtual void	onMouseButtonReleased (const MouseButtonEvent &mouseEvent)
	Called whenever a mouse button is released.
virtual void	onJoystickAxisChanged (const JoystickAxisEvent &joystickEvent)
	Called whenever the joystick axis changed.
virtual void	onJoystickTrackballChanged (const JoystickTrackballEvent &joystickEvent)
	Called whenever the joystick trackball changed.
virtual void	onJoystickHatChanged (const JoystickHatEvent &joystickEvent)
	Called whenever the joystick hat changed.
virtual void	onJoystickButtonPressed (const JoystickButtonEvent &joystickEvent)
	Called whenever the joystick button is pressed.
virtual void	onJoystickButtonReleased (const JoystickButtonEvent &joystickEvent)
	Called whenever the joystick button is released.
virtual void	onIdle ()
	Called whenever the application is deemed idle.
virtual void	onApplicationFocusChanged (const FocusEvent &focusEvent)
	Called whenever at least one of the three focuses (mouse, keyboard or application visibility) changed.
virtual void	onApplicationIconified (const FocusEvent &focusEvent)
	Called whenever the application is iconified (minimized ).
virtual void	onApplicationRestored (const FocusEvent &focusEvent)
	Called whenever the application is restored.
virtual void	onQuitRequested ()
	Called whenever the application is requested to quit.
virtual void	onSystemSpecificWindowManagerEvent (const SystemSpecificWindowManagerEvent &wmEvent)
	Called whenever a system-specific window manager event is received.
virtual void	onResizedWindow (const WindowResizedEvent &resizeEvent)
	Called whenever the window is resized.
virtual void	onScreenNeedsRedraw ()
	Called whenever the screen has been modified outside of the application, usually by the window manager, and needs to be redrawn.
virtual void	onUserEvent (const UserEvent &userEvent)
	Called whenever an user-defined event occurs.
virtual void	onUnknownEventType (const BasicEvent &unknownEvent)
	Called whenever an unknown event type occurs during the input update phase.
Protected Attributes
bool	_useScheduler
	Tells whether a scheduler should be used.
bool	_isGuiEnabled
	Tells whether a graphical user interface is to be managed.
KeyboardHandler *	_keyboardHandler
	The internal keyboard handler.
JoystickHandler *	_joystickHandler
	The internal joystick handler, if any.
MouseHandler *	_mouseHandler
	The internal mouse handler, if any.
bool	_quitRequested
	Tells whether the user asked to quit.
Ceylan::Maths::Hertz	_loopTargetedFrequency
	The targeted frequency of the basic event loop.
Ceylan::Uint32	_idleCallsCount
	Count the number of idle calls made during the current event loop.
Ceylan::System::Callback	_loopIdleCallback
	The idle callback, if any, to be called by the basic event loop.
void *	_loopIdleCallbackData
	The data, if any, to provide to the idle callback, should the basic event loop be used.
Ceylan::System::Microsecond	_loopIdleCallbackMaxDuration
	An estimated upper bound of the duration of current idle callback.
Static Protected Attributes
static const std::string	_SDLEnvironmentVariables [] = {}
	Array of all known environment variables related to events, for the SDL back-end.
static bool	_EventsInitialized = false
	Tells whether event system has already been initialized.
static const Ceylan::Uint32	_FrameTimingSlotsCount
	Number of available slots used to keep track of frame rate.
static const Ceylan::Sint16	_MouseFocus = 0x01
	Designates the mouse focus.
static const Ceylan::Sint16	_KeyboardFocus = 0x02
	Designates the keyboard focus.
static const Ceylan::Sint16	_ApplicationFocus = 0x04
	Designates the application focus (iconified or restored).
static const std::string	_MessageHeader = "[OSDL event] "
	Header of messages sent by default implementations (ex: onMouseFocusGained).
static const Ceylan::Uint32	_MouseButtonCount = 5
	Records the total number of buttons supported for a mouse.
Private Member Functions
	EventsModule (Ceylan::Flags eventsFlag)
	Initializes the events module.
virtual	~EventsModule () throw ()
	Deletes the events module.
	EventsModule (const EventsModule &source)
	Copy constructor made private to ensure that it will never be called.
EventsModule &	operator= (const EventsModule &source)
	Assignment operator made private to ensure that it will never be called.
Friends
class	OSDL::CommonModule

Detailed Description

Handles the asynchronous event-based interaction model, general input handling, and basic time management, including the logic and rendering frequencies.

Our optional scheduler allows to uncouple all these times.

The user is given the choice between a basic event loop, for which input management, rendering and logic have to happen at the same frequency, and a scheduler, that allows him to set a different frequency for each of these concerns, and permits fine-grained activation of the scheduled objects, be it periodic or specifically programmed.

Both scheduling choices allow idle calls to be performed if, CPU-wise, the process can afford it.

The default idle call is the smallest possible OS sleep (one time slice), to avoid the operating system to take counter-measures against this process, which otherwise would be deemed too CPU-hungry.

The user can supply a specific idle callback, if wanted.

Under all circumstances, the callback function should last for very small durations, compared to the frequencies requested (better multiple idle calls than too long too few), otherwise the scheduling may constantly fail.

Event module notes:

The event modules comes with no joystick handler registered, but with a keyboard handler.

Scheduler notes:

Note:: Even though logic and rendering are not as tightly linked as they often are, if the sum of their processing needs exceeds what the hosting computer can give, they will have to overcome this resource limitation.

The logic is deemed more important than rendering, therefore jerked graphics will be preferred by the scheduler to frame-rate dependent logic.

Basic settings are as follow:

an engine tick lasts for 1 millisecond (engine frequency: 1 kHz)

a simulation tick lasts for 10 engine ticks (logic frequency: 100 Hz)

a rendering tick lasts for 25 engine ticks (rendering frequency, also known as framerate: 40 Hz, i.e. 40 frames per second), if there is enough processing power

an input tick lasts for 20 ticks (input frequency: 50 Hz)

Note:: With the SDL back-end, a created window (see VideoModule::setMode) is needed to have the event system working.

Definition at line 236 of file OSDLEvents.h.

Constructor & Destructor Documentation

OSDL::Events::EventsModule::EventsModule ( Ceylan::Flags eventsFlag ) [explicit, private]

Initializes the events module.

Parameters:

eventsFlag

flag describing which input device should be enabled (keyboard, mouse, joystick, etc.)

Exceptions:

EventsException

if the initialization of an input subsystem failed.

Note:: Some input device handlers (ex: mouse or joystick) may be created even though not specifically requested, because some events may have to be managed anyway (ex: keyboard or mouse focus lost, etc.).

EventsModule::~EventsModule ( ) throw () [private, virtual]

Deletes the events module.

Definition at line 365 of file OSDLEvents.cc.

References _joystickHandler, _keyboardHandler, and _mouseHandler.

OSDL::Events::EventsModule::EventsModule ( const EventsModule & source ) [explicit, private]

Copy constructor made private to ensure that it will never be called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Member Function Documentation

string EventsModule::DescribeEnvironmentVariables ( ) [static]

Returns a summary about the possible use of events-related environment variables, for the selected back-end.

Note:: The SDL back-end can be partly driven by a set of environment variables.

Definition at line 1144 of file OSDLEvents.cc.

References _SDLEnvironmentVariables, and toString().

string EventsModule::DescribeEvent ( BasicEvent anEvent ) [static]

Returns a string describing the specified basic event.

Definition at line 1205 of file OSDLEvents.cc.

References ApplicationFocusChanged, DescribeEvent(), JoystickAxisChanged, JoystickButtonPressed, JoystickButtonReleased, JoystickHatPositionChanged, JoystickTrackballChanged, KeyPressed, KeyReleased, MouseButtonPressed, MouseButtonReleased, MouseMoved, ScreenNeedsRedraw, SystemSpecificTriggered, UserRequestedQuit, and UserResizedVideoMode.

string EventsModule::DescribeEvent ( const UserEvent & userEvent ) [static]

Describes an user event.

Definition at line 2407 of file OSDLEvents.cc.

References NoSDLSupportAvailable, and toString().

string EventsModule::DescribeEvent ( const ScreenExposedEvent & redrawEvent ) [static]

Describes a screen exposed event (needs redraw).

Definition at line 2390 of file OSDLEvents.cc.

References NoSDLSupportAvailable.

string EventsModule::DescribeEvent ( const WindowResizedEvent & resizeEvent ) [static]

Describes a window resized event.

Definition at line 2372 of file OSDLEvents.cc.

References NoSDLSupportAvailable, and toString().

string EventsModule::DescribeEvent ( const SystemSpecificWindowManagerEvent & windowManagerEvent ) [static]

Describes a window manager event (system specific).

Definition at line 2348 of file OSDLEvents.cc.

References NoSDLSupportAvailable.

string EventsModule::DescribeEvent ( const UserRequestedQuitEvent & quitEvent ) [static]

Describes a quit event.

Definition at line 2331 of file OSDLEvents.cc.

References NoSDLSupportAvailable.

string EventsModule::DescribeEvent ( const JoystickButtonEvent & buttonEvent ) [static]

Describes a joystick button event.

Definition at line 2311 of file OSDLEvents.cc.

References NoSDLSupportAvailable.

string EventsModule::DescribeEvent ( const JoystickHatEvent & hatEvent ) [static]

Describes a joystick hat event.

Definition at line 2292 of file OSDLEvents.cc.

References NoSDLSupportAvailable, and toString().

string EventsModule::DescribeEvent ( const JoystickTrackballEvent & ballEvent ) [static]

Describes a joystick trackball event.

Definition at line 2271 of file OSDLEvents.cc.

References NoSDLSupportAvailable, and toString().

string EventsModule::DescribeEvent ( const JoystickAxisEvent & axisEvent ) [static]

Describes a joystick axis event.

Definition at line 2252 of file OSDLEvents.cc.

References NoSDLSupportAvailable, and toString().

string EventsModule::DescribeEvent ( const MouseButtonEvent & mouseButtonEvent ) [static]

Describes a mouse button event.

Definition at line 2193 of file OSDLEvents.cc.

References NoSDLSupportAvailable, and toString().

string EventsModule::DescribeEvent ( const MouseMotionEvent & mouseMotionEvent ) [static]

Describes a mouse motion event.

Definition at line 2164 of file OSDLEvents.cc.

References _MouseButtonCount, NoSDLSupportAvailable, and toString().

string EventsModule::DescribeEvent ( const KeyboardEvent & keyboardEvent ) [static]

Describes a keyboard event.

Definition at line 2127 of file OSDLEvents.cc.

References OSDL::Events::KeyboardHandler::DescribeKey(), OSDL::Events::KeyboardHandler::DescribeModifier(), OSDL::Events::KeyboardHandler::DescribeUnicode(), OSDL::Events::KeyboardHandler::GetMode(), KeyPressed, NoSDLSupportAvailable, and OSDL::Events::textInput.

string EventsModule::DescribeEvent ( const FocusEvent & focusEvent ) [static]

void EventsModule::enterBasicMainLoop ( ) [protected, virtual]

Enters the basic event loop, not using any scheduler.

The loop will aim to enforce the specified frequency, i.e. the current frame per second target.

Note:: This is basically a never-return method, if no exit handler is registered.

Exceptions:

EventsException

if a time-related problem, more serious than deadline misses, occurs.

Definition at line 1323 of file OSDLEvents.cc.

References _idleCallsCount, _loopIdleCallback, _loopIdleCallbackMaxDuration, _loopTargetedFrequency, _quitRequested, OSDL::getExistingCommonModule(), OSDL::Rendering::Renderer::GetExistingRootRenderer(), OSDL::CommonModule::getVideoModule(), OSDL::Rendering::Renderer::HasExistingRootRenderer(), LOG_DEBUG_EVENTS, onIdle(), OSDL::Video::VideoModule::redraw(), OSDL::Rendering::Renderer::render(), OSDL::Video::Pixels::toString(), OSDL::Rendering::Renderer::toString(), and updateInputState().

Referenced by enterMainLoop().

void EventsModule::enterMainLoop ( ) [virtual]

Enters the main event loop.

If a scheduler is being used, will start it, and stop it on exit.

Otherwise the basic event loop will be used.

Note:: If an idle callback is set, it will be executed appropriately.

Exceptions:

EventsException

if a serious scheduling or event-related problem occured.

Definition at line 722 of file OSDLEvents.cc.

References _useScheduler, enterBasicMainLoop(), OSDL::CommonModule::IsBackendInitialized(), and LOG_DEBUG_EVENTS.

Ceylan::System::Microsecond EventsModule::EvaluateCallbackduration	(	Ceylan::System::Callback	callback,
		void *	callbackData
	)			`[static]`

Tries to guess an upper-bound for the average duration of the execution of the specified callback.

Parameters:

	callback	the callback whose duration will be evaluated.
	callbackData	the data that will be given to the callback for the evaluation.

Returns:: A guessed upper-bound for the duration of the callback.

Note:: Will run the callback once, and return the measured duration increased of 20%.

Definition at line 2434 of file OSDLEvents.cc.

References LOG_DEBUG_EVENTS, and OSDL::Video::Pixels::toString().

Referenced by setIdleCallback().

bool EventsModule::getGrabInputMode ( ) const [virtual]

Returns whether mouse and keyboard inputs are grabbed.

Exceptions:

EventsException

if the operation failed or is not supported.

Definition at line 569 of file OSDLEvents.cc.

JoystickHandler & EventsModule::getJoystickHandler ( ) const [virtual]

Returns the joystick handler currently used.

Exceptions:

EventsException

if no joystick handler is available.

Definition at line 849 of file OSDLEvents.cc.

References _joystickHandler.

KeyboardHandler & EventsModule::getKeyboardHandler ( ) const [virtual]

Returns the keyboard handler currently used.

Exceptions:

EventsException

if no keyboard handler is available.

Definition at line 813 of file OSDLEvents.cc.

References _keyboardHandler.

Millisecond EventsModule::GetMillisecondsSinceStartup ( ) [static]

Gets the number of milliseconds since the back-end initialization.

Note:: This value wraps (overflows) if the program runs for more than about 49 days.

Exceptions:

EventsException

if the back-end is not already initialized.

Definition at line 1290 of file OSDLEvents.cc.

References OSDL::CommonModule::IsBackendInitialized().

MouseHandler & EventsModule::getMouseHandler ( ) const [virtual]

Returns the mouse handler currently used.

Exceptions:

EventsException

if no mouse handler is available.

Definition at line 887 of file OSDLEvents.cc.

References _mouseHandler.

bool EventsModule::hasJoystickHandler ( ) const [virtual]

Tells whether a joystick handler is available.

Definition at line 840 of file OSDLEvents.cc.

References _joystickHandler.

bool EventsModule::hasKeyboardHandler ( ) const [virtual]

Tells whether a keyboard handler is available.

Definition at line 804 of file OSDLEvents.cc.

References _keyboardHandler.

bool EventsModule::hasMouseHandler ( ) const [virtual]

Tells whether a mouse handler is available.

Definition at line 878 of file OSDLEvents.cc.

References _mouseHandler.

bool EventsModule::hasPendingUserInput ( ) const [virtual]

Returns true iff there is at least one pending user input, like a key hit, a mouse or joystick button pushed.

Note:: Useful to poll events without blocking.

Definition at line 516 of file OSDLEvents.cc.

References JoystickButtonPressed, KeyPressed, MouseButtonPressed, and UserRequestedQuit.

bool EventsModule::IsEventsInitialized ( ) [static]

Tells whether event system has already been initialized.

Note:: This method is static so that calling it is convenient: no need to explicitly retrieve the common module, then events module before knowing the result.

The need to retrieve the right module from scratch at each call is rather inefficient though.

Definition at line 2425 of file OSDLEvents.cc.

References _EventsInitialized.

bool EventsModule::isGUIEnabled ( ) const [virtual]

Tells whether a GUI (Graphical User Interface) is to be supported by this events module.

Definition at line 662 of file OSDLEvents.cc.

References _isGuiEnabled.

void EventsModule::onApplicationFocusChanged ( const FocusEvent & focusEvent ) [protected, virtual]

Called whenever at least one of the three focuses (mouse, keyboard or application visibility) changed.

Note:: Call specialized methods such as onMouseFocusGained to handle each case.

Definition at line 1892 of file OSDLEvents.cc.

References _ApplicationFocus, _KeyboardFocus, _MouseFocus, LOG_DEBUG_EVENTS, onApplicationIconified(), onApplicationRestored(), onKeyboardFocusGained(), onKeyboardFocusLost(), onMouseFocusGained(), and onMouseFocusLost().

Referenced by updateInputState().

void EventsModule::onApplicationIconified ( const FocusEvent & focusEvent ) [protected, virtual]

Called whenever the application is iconified (minimized ).

Note:: Made to be overriden, basically just writes the event in the standard output.

Definition at line 1934 of file OSDLEvents.cc.

References DescribeEvent(), and LOG_DEBUG_EVENTS.

Referenced by onApplicationFocusChanged().

void EventsModule::onApplicationRestored ( const FocusEvent & focusEvent ) [protected, virtual]

Called whenever the application is restored.

Note:: Made to be overriden, basically just writes the event in the standard output.

Definition at line 1948 of file OSDLEvents.cc.

References DescribeEvent(), and LOG_DEBUG_EVENTS.

Referenced by onApplicationFocusChanged().

void EventsModule::onIdle ( ) [protected, virtual]

Called whenever the application is deemed idle.

Applies the idle behaviour, which can be user-defined (setIdleCallback), or otherwise which will default to micro-sleeps.

See also:: setIdleCallback

Definition at line 1856 of file OSDLEvents.cc.

References _idleCallsCount, _loopIdleCallback, _loopIdleCallbackData, and LOG_DEBUG_EVENTS.

Referenced by enterBasicMainLoop().

void EventsModule::onJoystickAxisChanged ( const JoystickAxisEvent & joystickEvent ) [protected, virtual]

Called whenever the joystick axis changed.

Parameters:

joystickEvent

the joystick axis event.

Note:: All opened joysticks can be updated.

Definition at line 1738 of file OSDLEvents.cc.

References _joystickHandler, OSDL::Events::JoystickHandler::axisChanged(), and LOG_DEBUG_EVENTS.

Referenced by updateInputState().

void EventsModule::onJoystickButtonPressed ( const JoystickButtonEvent & joystickEvent ) [protected, virtual]

Called whenever the joystick button is pressed.

Parameters:

joystickEvent

the joystick button event.

Note:: All opened joysticks can be updated.

Definition at line 1805 of file OSDLEvents.cc.

References _joystickHandler, OSDL::Events::JoystickHandler::buttonPressed(), and LOG_DEBUG_EVENTS.

Referenced by updateInputState().

void EventsModule::onJoystickButtonReleased ( const JoystickButtonEvent & joystickEvent ) [protected, virtual]

Called whenever the joystick button is released.

Parameters:

joystickEvent

the joystick button event.

Note:: All opened joysticks can be updated.

Definition at line 1828 of file OSDLEvents.cc.

References _joystickHandler, OSDL::Events::JoystickHandler::buttonReleased(), and LOG_DEBUG_EVENTS.

Referenced by updateInputState().

void EventsModule::onJoystickHatChanged ( const JoystickHatEvent & joystickEvent ) [protected, virtual]

Called whenever the joystick hat changed.

Parameters:

joystickEvent

the joystick hat event.

Note:: All opened joysticks can be updated.

Definition at line 1783 of file OSDLEvents.cc.

References _joystickHandler, OSDL::Events::JoystickHandler::hatChanged(), and LOG_DEBUG_EVENTS.

Referenced by updateInputState().

void EventsModule::onJoystickTrackballChanged ( const JoystickTrackballEvent & joystickEvent ) [protected, virtual]

Called whenever the joystick trackball changed.

Parameters:

joystickEvent

the joystick trackball event.

Note:: All opened joysticks can be updated.

Definition at line 1760 of file OSDLEvents.cc.

References _joystickHandler, LOG_DEBUG_EVENTS, and OSDL::Events::JoystickHandler::trackballChanged().

Referenced by updateInputState().

void EventsModule::onKeyboardFocusGained ( const FocusEvent & keyboardFocusEvent ) [protected, virtual]

Called whenever the application gained keyboard focus.

Parameters:

keyboardFocusEvent

the keyboard focus event.

Note:: Made to be overriden, basically just writes the event in the standard output.

Definition at line 1537 of file OSDLEvents.cc.

References _keyboardHandler, OSDL::Events::KeyboardHandler::focusGained(), and LOG_DEBUG_EVENTS.

Referenced by onApplicationFocusChanged().

void EventsModule::onKeyboardFocusLost ( const FocusEvent & keyboardFocusEvent ) [protected, virtual]

Called whenever the application lost keyboard focus.

Parameters:

	keyboardFocusEvent	the keyboard focus event.
	keyboardFocusEvent	the keyboard focus event.

Note:: Made to be overriden, basically just writes the event in the standard output.

Definition at line 1559 of file OSDLEvents.cc.

References _keyboardHandler, OSDL::Events::KeyboardHandler::focusLost(), and LOG_DEBUG_EVENTS.

Referenced by onApplicationFocusChanged().

void EventsModule::onKeyPressed ( const KeyboardEvent & keyboardEvent ) [protected, virtual]

Called whenever a key is pressed.

Parameters:

keyboardEvent

the keyboard event.

Definition at line 1581 of file OSDLEvents.cc.

References _keyboardHandler, OSDL::Events::KeyboardHandler::keyPressed(), and LOG_DEBUG_EVENTS.

Referenced by updateInputState().

void EventsModule::onKeyReleased ( const KeyboardEvent & keyboardEvent ) [protected, virtual]

Called whenever a key is released.

Parameters:

keyboardEvent

the keyboard event.

Definition at line 1602 of file OSDLEvents.cc.

References _keyboardHandler, OSDL::Events::KeyboardHandler::keyReleased(), and LOG_DEBUG_EVENTS.

Referenced by updateInputState().

void EventsModule::onMouseButtonPressed ( const MouseButtonEvent & mouseEvent ) [protected, virtual]

Called whenever a mouse button is pressed.

Parameters:

mouseEvent

the mouse button event.

Definition at line 1691 of file OSDLEvents.cc.

References _mouseHandler, OSDL::Events::MouseHandler::buttonPressed(), and LOG_DEBUG_EVENTS.

Referenced by updateInputState().

void EventsModule::onMouseButtonReleased ( const MouseButtonEvent & mouseEvent ) [protected, virtual]

Called whenever a mouse button is released.

Parameters:

mouseEvent

the mouse button event.

Definition at line 1712 of file OSDLEvents.cc.

References _mouseHandler, OSDL::Events::MouseHandler::buttonReleased(), and LOG_DEBUG_EVENTS.

Referenced by updateInputState().

void EventsModule::onMouseFocusGained ( const FocusEvent & mouseFocus ) [protected, virtual]

Called whenever the application gained mouse focus.

Parameters:

mouseFocus

the mouse that gained focus.

Note:: Made to be overriden, basically just writes the event in the standard output.

Definition at line 1628 of file OSDLEvents.cc.

References _mouseHandler, OSDL::Events::MouseHandler::focusGained(), and LOG_DEBUG_EVENTS.

Referenced by onApplicationFocusChanged().

void EventsModule::onMouseFocusLost ( const FocusEvent & mouseFocus ) [protected, virtual]

Called whenever t application lost mouse focus.

Parameters:

mouse

the mouse that lost focus.

Note:: Made to be overriden, basically just writes the event in the standard output.

Definition at line 1649 of file OSDLEvents.cc.

References _mouseHandler, OSDL::Events::MouseHandler::focusLost(), and LOG_DEBUG_EVENTS.

Referenced by onApplicationFocusChanged().

void EventsModule::onMouseMotion ( const MouseMotionEvent & mouseEvent ) [protected, virtual]

Called whenever the mouse moved.

Parameters:

mouseEvent

the mouse motion event.

Definition at line 1670 of file OSDLEvents.cc.

References _mouseHandler, LOG_DEBUG_EVENTS, and OSDL::Events::MouseHandler::mouseMoved().

Referenced by updateInputState().

void EventsModule::onQuitRequested ( ) [protected, virtual]

Called whenever the application is requested to quit.

Definition at line 1961 of file OSDLEvents.cc.

References LOG_DEBUG_EVENTS, and requestQuit().

Referenced by updateInputState().

void EventsModule::onResizedWindow ( const WindowResizedEvent & resizeEvent ) [protected, virtual]

Called whenever the window is resized.

Only applications that have been specified as resizable in the setMode call can receive that event.

Note:: The window should be resized to the new dimensions using setMode.

Definition at line 1997 of file OSDLEvents.cc.

References OSDL::getExistingCommonModule(), OSDL::CommonModule::getVideoModule(), LOG_DEBUG_EVENTS, OSDL::Video::VideoModule::resize(), and OSDL::Video::Pixels::toString().

Referenced by updateInputState().

void EventsModule::onScreenNeedsRedraw ( ) [protected, virtual]

Called whenever the screen has been modified outside of the application, usually by the window manager, and needs to be redrawn.

Definition at line 2028 of file OSDLEvents.cc.

References OSDL::getExistingCommonModule(), OSDL::CommonModule::getVideoModule(), LOG_DEBUG_EVENTS, and OSDL::Video::VideoModule::redraw().

Referenced by updateInputState().

void EventsModule::onSystemSpecificWindowManagerEvent ( const SystemSpecificWindowManagerEvent & wmEvent ) [protected, virtual]

Called whenever a system-specific window manager event is received.

These unhandled events are received from the window manager, and can be used, for example, to implement cut-and-paste in your application.

Definition at line 1976 of file OSDLEvents.cc.

References LOG_DEBUG_EVENTS.

Referenced by updateInputState().

void EventsModule::onUnknownEventType ( const BasicEvent & unknownEvent ) [protected, virtual]

Called whenever an unknown event type occurs during the input update phase.

Definition at line 2063 of file OSDLEvents.cc.

References LOG_DEBUG_EVENTS.

Referenced by updateInputState().

void EventsModule::onUserEvent ( const UserEvent & userEvent ) [protected, virtual]

Called whenever an user-defined event occurs.

Note:: Data is transmitted alongside this event.

Definition at line 2048 of file OSDLEvents.cc.

References LOG_DEBUG_EVENTS.

Referenced by updateInputState().

EventsModule& OSDL::Events::EventsModule::operator= ( const EventsModule & source ) [private]

Assignment operator made private to ensure that it will never be called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

void EventsModule::requestQuit ( ) [virtual]

Requests the application to quit by exiting the main loop.

Note:: This method is useful for input handlers to send too quit notifications, otherwise the only way of quitting would be provided by the window manager, if any.

Definition at line 771 of file OSDLEvents.cc.

References _quitRequested, and _useScheduler.

Referenced by onQuitRequested().

virtual void OSDL::Events::EventsModule::setEventLoopTargetFrequency ( Ceylan::Maths::Hertz targetFrequency ) [virtual]

Sets the actual target frequency that the basic event loop will try to run at.

Note:: Will not take effect until the next call to the basic event loop.

void EventsModule::setGrabInputMode ( bool newMode ) [virtual]

Tells whether mouse and keyboard inputs should be grabbed.

Parameters:

newMode

inputs will be grabbed iff true.

Exceptions:

EventsException

if the operation failed or is not supported.

Definition at line 588 of file OSDLEvents.cc.

void EventsModule::setGUIEnableStatus ( bool newStatus ) [virtual]

Determines whether a GUI (Graphical User Interface) should be supported by this events module.

Parameters:

newStatus

the new enable status of the GUI.

Definition at line 671 of file OSDLEvents.cc.

References _isGuiEnabled.

Referenced by OSDL::CommonModule::enableGUI().

void EventsModule::setIdleCallback	(	Ceylan::System::Callback	idleCallback,
		void *	callbackData = `0`,
		Ceylan::System::Microsecond	callbackExpectedMaxDuration = `0`
	)			`[virtual]`

Sets the idle function, which is called whenever the current scheduling system, either the main event loop or the scheduler, detects a period of idle activity.

The callback can be useful when dealing with animations for example, or to execute background activities (such as counting the frame rate), or to let the process yield some CPU time so that the OS does not consider it as too CPU-hungry, and does not take counter-measures against it.

Note:: Ensure that the maximum time spent in the callback is negligible compared to the period corresponding to the maximum frequency being set, so that it does not result in a too heavy load which would make the scheduler fail constantly.

Parameters:

	idleCallback	the idle callback, which can be null (0) to specify no idle callback is wanted.
	callbackData	the user-supplied data pointer that the idle callback will be given, if not null.
	callbackExpectedMaxDuration	the maximum duration, in microseconds, expected for this idle call-back. Helps the main loop enforcing its target frequency. If this value is null, the idle callback will be launched once immediately (during the call of this method), and the measured duration, increased of 20%, will be kept as upper bound.

Any prior callback or callback data will be replaced by the one specified.

Definition at line 681 of file OSDLEvents.cc.

References _loopIdleCallback, _loopIdleCallbackData, _loopIdleCallbackMaxDuration, _useScheduler, and EvaluateCallbackduration().

void EventsModule::setJoystickHandler ( JoystickHandler & newHandler ) [virtual]

Sets a new joystick handler.

Parameters:

newHandler

the new joystick handler.

Note:: If a joystick handler was already registered, it is unregistered and deallocated first.

Definition at line 865 of file OSDLEvents.cc.

References _joystickHandler.

void EventsModule::setKeyboardHandler ( KeyboardHandler & newHandler ) [virtual]

Sets a new keyboard handler.

Parameters:

newHandler

the new keyboard handler.

Note:: If a keyboard handler was already registered, it is unregistered and deallocated first.

Definition at line 828 of file OSDLEvents.cc.

References _keyboardHandler.

void EventsModule::setMouseHandler ( MouseHandler & newHandler ) [virtual]

Sets a new mouse handler.

Parameters:

newHandler

the new joystcik handler.

Note:: If a mouse handler was already registered, it is unregistered and deallocated first.

Definition at line 902 of file OSDLEvents.cc.

References _mouseHandler.

virtual bool OSDL::Events::EventsModule::sleepFor	(	Ceylan::System::Second	seconds,
		Ceylan::System::Microsecond	micros
	)			const `[virtual]`

Sleeps for the specified duration.

Parameters:

	seconds	the number of seconds to wait.
	micros	the remaining part of the time to wait, expressed as a number of microseconds.

As full seconds should be taken into account with the parameter seconds, micros should be less than one second, i.e. should be in the range 0 to 10E6 - 1.

Exceptions:

EventsException

if a system call failed.

Returns:: whether the deadline was successfully met, i.e. if the waiting was on schedule.

Note:: This method must cope with the operating system scheduling, its precision should be of about a few microseconds.

See also:: Ceylan::System::smartSleep

const string EventsModule::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const [virtual]

Returns an user-friendly description of the state of this object.

Parameters:

level

the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: Ceylan::TextDisplayable

Definition at line 1076 of file OSDLEvents.cc.

References _isGuiEnabled, _joystickHandler, _keyboardHandler, _loopIdleCallback, _mouseHandler, _useScheduler, OSDL::Events::MouseHandler::toString(), OSDL::Events::JoystickHandler::toString(), OSDL::Events::KeyboardHandler::toString(), and OSDL::Video::Pixels::toString().

Referenced by DescribeEnvironmentVariables(), and DescribeEvent().

void EventsModule::updateInputState ( ) [virtual]

Updates the state of the various inputs of interest (keyboard, mouse, joystick).

Reads all pending low-level events and dispatch them to the appropriate manager.

Note:: Useful for event loops, public for allowing the scheduler to call it.

Definition at line 914 of file OSDLEvents.cc.

References _isGuiEnabled, ApplicationFocusChanged, FirstUserEventTriggered, JoystickAxisChanged, JoystickButtonPressed, JoystickButtonReleased, JoystickHatPositionChanged, JoystickTrackballChanged, KeyPressed, KeyReleased, LastUserEventTriggered, MouseButtonPressed, MouseButtonReleased, MouseMoved, onApplicationFocusChanged(), onJoystickAxisChanged(), onJoystickButtonPressed(), onJoystickButtonReleased(), onJoystickHatChanged(), onJoystickTrackballChanged(), onKeyPressed(), onKeyReleased(), onMouseButtonPressed(), onMouseButtonReleased(), onMouseMotion(), onQuitRequested(), onResizedWindow(), onScreenNeedsRedraw(), onSystemSpecificWindowManagerEvent(), onUnknownEventType(), onUserEvent(), ScreenNeedsRedraw, SystemSpecificTriggered, UserRequestedQuit, and UserResizedVideoMode.

Referenced by enterBasicMainLoop().

void EventsModule::useScheduler ( bool on = true ) [virtual]

Defines whether a scheduler should be used by the event loop.

If a scheduler is wanted but does not already exist, it will be created with default settings.

This scheduler will be in charge of all the active objects that will be registered subsequently.

Parameters:

on

tells whether a scheduler is wanted.

See also:: Scheduler::GetScheduler method to further customize the scheduler.

Definition at line 640 of file OSDLEvents.cc.

References _useScheduler.

void EventsModule::waitForAnyKey ( bool displayWaitingMessage = true ) const [virtual]

Waits for any key to be hit.

Will not work with the SDL back-end unless a window is opened thanks to VideoModule::setMode: otherwise, no event would be generated.

Parameters:

displayWaitingMessage

the default waiting message will be displayed iff true.

Note:: This waiting method does not poll indefinitively for events, which would use 100% of the CPU all the time.

It just waits for an event, consuming almost no ressource on most platforms.

Exceptions:

EventsException

if the operation failed or is not supported.

Definition at line 397 of file OSDLEvents.cc.

References KeyPressed.

void EventsModule::waitForAnyUserInput ( ) const [virtual]

Waits for any user input: a key being hit, a mouse button being clicked, etc.

Will not work with the SDL back-end unless a window is opened thanks to VideoModule::setMode: otherwise, no event would be generated.

Note:: This waiting method does not poll indefinitively for events, which would use 100% of the CPU all the time.

It just waits for an event, consuming almost no resource on most platforms.

Exceptions:

EventsException

if the operation failed or is not supported.

Definition at line 459 of file OSDLEvents.cc.

References JoystickButtonPressed, KeyPressed, MouseButtonPressed, and UserRequestedQuit.

Friends And Related Function Documentation

friend class OSDL::CommonModule [friend]

Definition at line 242 of file OSDLEvents.h.

Member Data Documentation

const Ceylan::Sint16 EventsModule::_ApplicationFocus = 0x04 [static, protected]

Designates the application focus (iconified or restored).

Definition at line 1418 of file OSDLEvents.h.

Referenced by DescribeEvent(), and onApplicationFocusChanged().

bool EventsModule::_EventsInitialized = false [static, protected]

Tells whether event system has already been initialized.

Definition at line 1398 of file OSDLEvents.h.

Referenced by IsEventsInitialized().

const Ceylan::Uint32 OSDL::Events::EventsModule::_FrameTimingSlotsCount [static, protected]

Number of available slots used to keep track of frame rate.

Definition at line 1403 of file OSDLEvents.h.

Ceylan::Uint32 OSDL::Events::EventsModule::_idleCallsCount [protected]

Count the number of idle calls made during the current event loop.

Definition at line 1359 of file OSDLEvents.h.

Referenced by enterBasicMainLoop(), and onIdle().

bool OSDL::Events::EventsModule::_isGuiEnabled [protected]

Tells whether a graphical user interface is to be managed.

Definition at line 1292 of file OSDLEvents.h.

Referenced by isGUIEnabled(), setGUIEnableStatus(), toString(), and updateInputState().

JoystickHandler* OSDL::Events::EventsModule::_joystickHandler [protected]

The internal joystick handler, if any.

Definition at line 1307 of file OSDLEvents.h.

Referenced by getJoystickHandler(), hasJoystickHandler(), onJoystickAxisChanged(), onJoystickButtonPressed(), onJoystickButtonReleased(), onJoystickHatChanged(), onJoystickTrackballChanged(), setJoystickHandler(), toString(), and ~EventsModule().

const Ceylan::Sint16 EventsModule::_KeyboardFocus = 0x02 [static, protected]

Designates the keyboard focus.

Definition at line 1413 of file OSDLEvents.h.

Referenced by DescribeEvent(), and onApplicationFocusChanged().

KeyboardHandler* OSDL::Events::EventsModule::_keyboardHandler [protected]

The internal keyboard handler.

Definition at line 1299 of file OSDLEvents.h.

Referenced by getKeyboardHandler(), hasKeyboardHandler(), onKeyboardFocusGained(), onKeyboardFocusLost(), onKeyPressed(), onKeyReleased(), setKeyboardHandler(), toString(), and ~EventsModule().

Ceylan::System::Callback OSDL::Events::EventsModule::_loopIdleCallback [protected]

The idle callback, if any, to be called by the basic event loop.

Definition at line 1368 of file OSDLEvents.h.

Referenced by enterBasicMainLoop(), onIdle(), setIdleCallback(), and toString().

void* OSDL::Events::EventsModule::_loopIdleCallbackData [protected]

The data, if any, to provide to the idle callback, should the basic event loop be used.

Definition at line 1377 of file OSDLEvents.h.

Referenced by onIdle(), and setIdleCallback().

Ceylan::System::Microsecond OSDL::Events::EventsModule::_loopIdleCallbackMaxDuration [protected]

An estimated upper bound of the duration of current idle callback.

Helps the event loop to respect its expected pace.

Definition at line 1388 of file OSDLEvents.h.

Referenced by enterBasicMainLoop(), and setIdleCallback().

Ceylan::Maths::Hertz OSDL::Events::EventsModule::_loopTargetedFrequency [protected]

The targeted frequency of the basic event loop.

The loop will try to enforce it.

Should there be time left for an iteration, then the event loop will call the idle callback multiple times, until the next iteration is to occur.

If no idle callback is registered, then for each iteration with time left, the event loop will call the basic sleep mecanism, as provided by the operating system.

This will be the smallest possible actual sleep duration, which is at least 1 millisecond with Linux 2.6 kernels.

Definition at line 1350 of file OSDLEvents.h.

Referenced by enterBasicMainLoop().

const string EventsModule::_MessageHeader = "[OSDL event] " [static, protected]

Header of messages sent by default implementations (ex: onMouseFocusGained).

Definition at line 1427 of file OSDLEvents.h.

const Ceylan::Uint32 EventsModule::_MouseButtonCount = 5 [static, protected]

Records the total number of buttons supported for a mouse.

Includes left, middle, right, wheel up, wheel down buttons.

Definition at line 1435 of file OSDLEvents.h.

Referenced by DescribeEvent().

const Ceylan::Sint16 EventsModule::_MouseFocus = 0x01 [static, protected]