Renamed OSystem::set_timer() to setTimerCallback(); more OSystem Doxygen changes

svn-id: r13289

13 files changed, 37 insertions, 21 deletions

diff --git a/backends/PalmOS/Src/palm.cpp b/backends/PalmOS/Src/palm.cpp
index 1c4948ad9c..8bcbea07d8 100644
--- a/backends/PalmOS/Src/palm.cpp
+++ b/backends/PalmOS/Src/palm.cpp
@@ -739,7 +739,7 @@ void OSystem_PALMOS::delay_msecs(uint msecs) {
 	} while (current < last);
 }
 
-void OSystem_PALMOS::set_timer(TimerProc callback, int timer) {
+void OSystem_PALMOS::setTimerCallback(TimerProc callback, int timer) {
 	if (callback != NULL) {
 		_timer.duration = timer;
 		_timer.nextExpiry = get_msecs() + timer;
diff --git a/backends/PalmOS/Src/palm.h b/backends/PalmOS/Src/palm.h
index 7e39b43862..910daff9c0 100644
--- a/backends/PalmOS/Src/palm.h
+++ b/backends/PalmOS/Src/palm.h
@@ -126,7 +126,7 @@ public:
 	void update_cdrom();
 
 	// Add a callback timer
-	void set_timer(TimerProc callback, int timer);
+	void setTimerCallback(TimerProc callback, int timer);
 
 	// Mutex handling
 	MutexRef createMutex();
diff --git a/backends/dc/dc.h b/backends/dc/dc.h
index 7a17b964a1..b040edab92 100644
--- a/backends/dc/dc.h
+++ b/backends/dc/dc.h
@@ -135,7 +135,7 @@ class OSystem_Dreamcast : public OSystem {
   void copy_rect_overlay(const int16 *buf, int pitch, int x, int y, int w, int h);
 
   // Add a callback timer
-  void set_timer(TimerProc callback, int timer);
+  void setTimerCallback(TimerProc callback, int timer);
 
   // Mutex handling
   MutexRef createMutex();
diff --git a/backends/dc/time.cpp b/backends/dc/time.cpp
index b508b3c45d..2771fc33c2 100644
--- a/backends/dc/time.cpp
+++ b/backends/dc/time.cpp
@@ -53,7 +53,7 @@ void OSystem_Dreamcast::delay_msecs(uint msecs)
   get_msecs();
 }
 
-void OSystem_Dreamcast::set_timer(TimerProc callback, int timer)
+void OSystem_Dreamcast::setTimerCallback(TimerProc callback, int timer)
 {
   if (callback != NULL) {
     _timer_duration = timer;
diff --git a/backends/gp32/gp32.cpp b/backends/gp32/gp32.cpp
index c8662beca6..8d5462e48e 100644
--- a/backends/gp32/gp32.cpp
+++ b/backends/gp32/gp32.cpp
@@ -1069,7 +1069,7 @@ void OSystem_GP32::stop_cdrom() { }
 void OSystem_GP32::update_cdrom() { }
 
 // Add a new callback timer
-void OSystem_GP32::set_timer(TimerProc callback, int timer) { }
+void OSystem_GP32::setTimerCallback(TimerProc callback, int timer) { }
 
 // Mutex handling
 OSystem::MutexRef OSystem_GP32::createMutex() {
diff --git a/backends/gp32/gp32.h b/backends/gp32/gp32.h
index 6fddf3fcfd..11f44c9a61 100644
--- a/backends/gp32/gp32.h
+++ b/backends/gp32/gp32.h
@@ -100,7 +100,7 @@ public:
 	void update_cdrom();
 
 	// Add a new callback timer
-	void set_timer(TimerProc callback, int timer);
+	void setTimerCallback(TimerProc callback, int timer);
 
 	// Mutex handling
 	OSystem::MutexRef createMutex();
diff --git a/backends/morphos/morphos.cpp b/backends/morphos/morphos.cpp
index d8c00e3d4e..a68b818295 100644
--- a/backends/morphos/morphos.cpp
+++ b/backends/morphos/morphos.cpp
@@ -322,9 +322,9 @@ void OSystem_MorphOS::delay_msecs(uint msecs)
    TimeDelay(UNIT_MICROHZ, 0, msecs*1000);
 }
 
-void OSystem_MorphOS::set_timer(TimerProc callback, int timer)
+void OSystem_MorphOS::setTimerCallback(TimerProc callback, int timer)
 {
-	warning("set_timer() unexpectedly called");
+	warning("setTimerCallback() unexpectedly called");
 }
 
 OSystem::MutexRef OSystem_MorphOS::createMutex()
diff --git a/backends/morphos/morphos.h b/backends/morphos/morphos.h
index 6e606c61ff..fd40369fd1 100644
--- a/backends/morphos/morphos.h
+++ b/backends/morphos/morphos.h
@@ -85,7 +85,7 @@ class OSystem_MorphOS : public OSystem
 		virtual void delay_msecs(uint msecs);
 
 		// Add a new callback timer
-		virtual void set_timer(TimerProc callback, int timer);
+		virtual void setTimerCallback(TimerProc callback, int timer);
 
 		// Mutex handling
 		virtual MutexRef createMutex();
diff --git a/backends/sdl/sdl-common.h b/backends/sdl/sdl-common.h
index 18ad04aabf..c71e147956 100644
--- a/backends/sdl/sdl-common.h
+++ b/backends/sdl/sdl-common.h
@@ -102,7 +102,7 @@ public:
 
 
 	// Add a callback timer
-	void set_timer(TimerProc callback, int timer);
+	void setTimerCallback(TimerProc callback, int timer);
 
 	// Mutex handling
 	MutexRef createMutex();
diff --git a/backends/sdl/sdl.cpp b/backends/sdl/sdl.cpp
index e87c661c1b..783238f802 100644
--- a/backends/sdl/sdl.cpp
+++ b/backends/sdl/sdl.cpp
@@ -122,7 +122,7 @@ void OSystem_SDL::delay_msecs(uint msecs) {
 	SDL_Delay(msecs);
 }
 
-void OSystem_SDL::set_timer(TimerProc callback, int timer) {
+void OSystem_SDL::setTimerCallback(TimerProc callback, int timer) {
 	SDL_SetTimer(timer, (SDL_TimerCallback) callback);
 }
 
diff --git a/backends/x11/x11.cpp b/backends/x11/x11.cpp
index b48d4244eb..92e034644f 100644
--- a/backends/x11/x11.cpp
+++ b/backends/x11/x11.cpp
@@ -123,7 +123,7 @@ public:
 	uint32 property(int param, Property *value);
 
 	// Add a callback timer
-	void set_timer(TimerProc callback, int interval);
+	void setTimerCallback(TimerProc callback, int interval);
 
 	// Mutex handling
 	MutexRef createMutex();
@@ -1033,7 +1033,7 @@ bool OSystem_X11::poll_event(Event *scumm_event)
 	return false;
 }
 
-void OSystem_X11::set_timer(TimerProc callback, int interval)
+void OSystem_X11::setTimerCallback(TimerProc callback, int interval)
 {
 	if (callback != NULL) {
 		_timer_duration = interval;
diff --git a/common/system.h b/common/system.h
index 3db60fcf9d..3afe519617 100644
--- a/common/system.h
+++ b/common/system.h
@@ -339,10 +339,11 @@ public:
 	 * can be passed to poll_event. 
 	 */
 	struct Event {
+		/** The type of the event. */
 		EventCode event_code;
 		/**
-		  * Keyboard data; only valid for keyboard events (i.e. EVENT_KEYDOWN
-		  * and EVENT_KEYUP). For all other event types, content is undefined.
+		  * Keyboard data; only valid for keyboard events (EVENT_KEYDOWN and
+		  * EVENT_KEYUP). For all other event types, content is undefined.
 		  */
 		struct {
 			/**
@@ -367,6 +368,12 @@ public:
 			 */
 			byte flags;
 		} kbd;
+		/**
+		 * The mouse coordinates, in virtual screen coordinates. Only valid
+		 * for mouse events.
+		 * Virtual screen coordinatest means: the coordinate system of the
+		 * screen area as defined by the most recent call to initSize().
+		 */
 		Common::Point mouse;
 	};
 
@@ -384,10 +391,19 @@ public:
 	virtual void delay_msecs(uint msecs) = 0;
 
 	/**
-	 * Set the timer callback.
+	 * Set the timer callback, a function which is periodically invoked by the
+	 * backend. This can for example be done via a background thread.
+	 * There is at most one active timer; if this method is called while there
+	 * is already an active timer, then the new timer callback should replace
+	 * the previous one. In particular, passing a callback pointer value of 0
+	 * is legal and can be used to clear the current timer callback.
 	 * @see Common::Timer
+	 *
+	 * @param callback	pointer to the callback. May be 0 to reset the timer
+	 * @param interval	the intervall (in milliseconds) between invocations
+	 *                  of the callback
 	 */
-	virtual void set_timer(TimerProc callback, int interval) = 0;
+	virtual void setTimerCallback(TimerProc callback, int interval) = 0;
 
 	//@}
 
diff --git a/common/timer.cpp b/common/timer.cpp
index 06f3b6af90..88ac735f7e 100644
--- a/common/timer.cpp
+++ b/common/timer.cpp
@@ -46,12 +46,12 @@ Timer::Timer(OSystem *system) :
 	_thisTime = _system->get_msecs();
 
 	// Set the timer last, after everything has been initialised
-	_system->set_timer(&timer_handler, 10);
+	_system->setTimerCallback(&timer_handler, 10);
 
 }
 
 Timer::~Timer() {
-	_system->set_timer(0, 0);
+	_system->setTimerCallback(0, 0);
 
 	{
 		Common::StackLock lock(_mutex);
@@ -64,8 +64,8 @@ Timer::~Timer() {
 
 
 	// FIXME: There is still a potential race condition here, depending on how
-	// the system backend implements set_timer: If timers are done using
-	// threads, and if set_timer does *not* gurantee that after it terminates
+	// the system backend implements setTimerCallback: If timers are done using
+	// threads, and if setTimerCallback does *not* gurantee that after it terminates
 	// that timer thread is not run anymore, we are fine. However, if the timer
 	// is still running in parallel to this destructor, then it might be that
 	// it is still waiting for the _mutex. So, again depending on the backend,