Index: docs/src/allegro._tx
===================================================================
--- docs/src/allegro._tx	(revision 11532)
+++ docs/src/allegro._tx	(working copy)
@@ -3036,8 +3036,25 @@
    MOUSE_FLAG_MOVE_Z. Note that even if the mouse has more than three buttons,
    only the first three can be trapped using a callback.
 
+@@int @mouse_on_screen();
+@shortdesc Tells you whether the mouse pointer is currently on screen.
+   This function can be useful to prevent having two mouse pointers on the 
+   screen at the same time when running your program in windowed mode and 
+   drawing the mouse pointer yourself. Other possible uses include the 
+   ability to pause your game when the mouse goes off of the window, or 
+   only scrolling the view when the pointer is near the edge of the window,
+   but not while off of the window.
+   
+   Example :
+<codeblock>
+   if (mouse_on_screen()) {draw_sprite(buffer , mouse_sprite , mouse_x , mouse_y);}
+<endblock>
 
+@retval
+   Returns 0 if the mouse pointer is off of the screen, or non-zero otherwise.
 
+
+
 @heading
 Timer routines
 
Index: include/allegro/mouse.h
===================================================================
--- include/allegro/mouse.h	(revision 11532)
+++ include/allegro/mouse.h	(working copy)
@@ -111,6 +111,8 @@
 AL_FUNC(void, get_mouse_mickeys, (int *mickeyx, int *mickeyy));
 AL_FUNC(void, set_mouse_sprite, (struct BITMAP *sprite));
 AL_FUNC(int, show_os_cursor, (int cursor));
+AL_FUNC(int, mouse_on_screen , (void));
+
 #ifdef __cplusplus
    }
 #endif
Index: src/mouse.c
===================================================================
--- src/mouse.c	(revision 11532)
+++ src/mouse.c	(working copy)
@@ -906,6 +906,17 @@
 
 
 
+/* mouse_on_screen:
+ *  Tells whether the mouse pointer position is currently on the screen.
+ *  Returns 0 when offscreen, and non-zero otherwise.
+ */
+int mouse_on_screen()
+{
+   return _mouse_on;
+}
+
+
+
 /* enable_hardware_cursor:
  *  enabels the hardware cursor on platforms where this needs to be done
  *  explicitly and allows system cursors to be used.