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

svn-id: r13289

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;

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();

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();

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;

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() {

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();

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()

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();

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();

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);
 }
 

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;

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;
 
 	//@}
 

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,