<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> <html><head><title> Allegro Manual: Mouse routines </title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Style-Type" content="text/css"> <link rel="stylesheet" title="Default" type="text/css" href="allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b"> <h1><a name="Mouse routines">Mouse routines</a></h1> <ul> <li><a href="#disable_hardware_cursor">disable_hardware_cursor</a> — Disables the OS hardware cursor. <li><a href="#enable_hardware_cursor">enable_hardware_cursor</a> — Enables the OS hardware cursor. <li><a href="#freeze_mouse_flag">freeze_mouse_flag</a> — Flag to avoid redrawing the mouse pointer. <li><a href="#get_mouse_mickeys">get_mouse_mickeys</a> — How far the mouse has moved since the last call to this function. <li><a href="#install_mouse">install_mouse</a> — Installs the Allegro mouse handler. <li><a href="#mouse_b">mouse_b</a> — Global variable with the mouse position/button state. <li><a href="#mouse_callback">mouse_callback</a> — User specified mouse callback. <li><a href="#mouse_needs_poll">mouse_needs_poll</a> — Tells if the mouse driver requires polling. <li><a href="#mouse_on_screen">mouse_on_screen</a> — Tells you whether the mouse pointer is currently on screen. <li><a href="#mouse_pos">mouse_pos</a> — Global variable with the mouse position/button state. <li><a href="#mouse_sprite">mouse_sprite</a> — Global variable with the mouse sprite and focus point. <li><a href="#mouse_w">mouse_w</a> — Global variable with the mouse position/button state. <li><a href="#mouse_x">mouse_x</a> — Global variable with the mouse position/button state. <li><a href="#mouse_x_focus">mouse_x_focus</a> — Global variable with the mouse sprite and focus point. <li><a href="#mouse_y">mouse_y</a> — Global variable with the mouse position/button state. <li><a href="#mouse_y_focus">mouse_y_focus</a> — Global variable with the mouse sprite and focus point. <li><a href="#mouse_z">mouse_z</a> — Global variable with the mouse position/button state. <li><a href="#poll_mouse">poll_mouse</a> — Polls the mouse. <li><a href="#position_mouse">position_mouse</a> — Moves the mouse to the specified screen position. <li><a href="#position_mouse_w">position_mouse_w</a> — Sets the horizontal mouse wheel position. <li><a href="#position_mouse_z">position_mouse_z</a> — Sets the mouse wheel position global variable. <li><a href="#remove_mouse">remove_mouse</a> — Removes the mouse handler. <li><a href="#scare_mouse">scare_mouse</a> — Helper for hiding the mouse pointer before drawing. <li><a href="#scare_mouse_area">scare_mouse_area</a> — Helper for hiding the mouse cursor before drawing in an area. <li><a href="#select_mouse_cursor">select_mouse_cursor</a> — Tells Allegro to select software or hardware cursor drawing. <li><a href="#set_mouse_cursor_bitmap">set_mouse_cursor_bitmap</a> — Changes the image Allegro uses for mouse cursors. <li><a href="#set_mouse_range">set_mouse_range</a> — Sets the area of the screen restricting mouse movement. <li><a href="#set_mouse_speed">set_mouse_speed</a> — Sets the mouse speed. <li><a href="#set_mouse_sprite">set_mouse_sprite</a> — Sets the mouse sprite. <li><a href="#set_mouse_sprite_focus">set_mouse_sprite_focus</a> — Sets the mouse sprite focus. <li><a href="#show_mouse">show_mouse</a> — Tells Allegro to display a mouse pointer on the screen. <li><a href="#show_os_cursor">show_os_cursor</a> — Low level function to display the operating system cursor. <li><a href="#unscare_mouse">unscare_mouse</a> — Undoes the effect of scare_mouse() or scare_mouse_area(). </ul> <p> Allegro provides functions for reading the mouse state and displaying a mouse cursor on-screen. You can read the absolute position of the mouse and the state of the mouse buttons from global variables. Additionally, you can read the mouse position difference as mouse mickeys, which is the number of pixels the cursor moved since the last time this information was read. <p> Allegro offers three ways to display the mouse cursor: <ul><li> Standard Allegro cursor<br> Allegro is responsible for drawing the mouse cursor from a timer. Use set_mouse_sprite() and show_mouse() to define your own cursor and display it on the screen. You need to call scare_mouse()/unscare_mouse() to hide the mouse cursor whenever you draw to the screen. <li> Custom operating system cursor (hardware cursor)<br> Allegro will let the operating system draw the mouse cursor. Use set_mouse_sprite() and show_mouse() (or show_os_cursor) to define your own cursor and display it on the screen. Not all graphics drivers are capable of this and some may only be able to display cursors up to a certain size. Allegro will fall back on its own cursor drawing if it cannot let the OS handle this. On some platforms, the hardware cursor is incompatible with get_mouse_mickeys() and it is therefor disabled by default. In such cases you need to call enable_hardware_cursor() to enable it explicitly. <li> Default operating system cursor<br> Allegro will not draw its own cursor, but use the operating system default cursor. You can use the select_mouse_cursor() function to select the cursor shape to display. As with custom operating system cursors, you need to call enable_hardware_cursor() before you can use this. Or you can use the low level show_os_cursor() function. </ul> Not all drivers will support all functionality. See the platform specific information for more details. <p><br> <div class="al-api"><b>int <a name="install_mouse">install_mouse</a>();</b></div><br> Installs the Allegro mouse handler. You must do this before using any other mouse functions. <p><b>Return value:</b> Returns -1 on failure, zero if the mouse handler is already installed (in which case this function does nothing) and the number of buttons on the mouse if the mouse handler has successfully been installed (ie. this is the first time a handler is installed or you have removed the previous one). <p> Note that the number of mouse buttons returned by this function is more an indication than a physical reality. With most devices there is no way of telling how many buttons there are, and any user can override the number of mouse buttons returned by this function with a custom configuration file and the variable num_buttons. Even if this value is overridden by the user, the global mouse variables will still report whatever the hardware is sending. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#remove_mouse" title="Removes the mouse handler.">remove_mouse</a>, <a class="xref" href="#poll_mouse" title="Polls the mouse.">poll_mouse</a>, <a class="xref" href="#mouse_x" title="Global variable with the mouse position/button state.">mouse_x</a>, <a class="xref" href="#show_mouse" title="Tells Allegro to display a mouse pointer on the screen.">show_mouse</a>, <a class="xref" href="#get_mouse_mickeys" title="How far the mouse has moved since the last call to this function.">get_mouse_mickeys</a>, <a class="xref" href="#position_mouse" title="Moves the mouse to the specified screen position.">position_mouse</a>, <a class="xref" href="#set_mouse_range" title="Sets the area of the screen restricting mouse movement.">set_mouse_range</a>, <a class="xref" href="#set_mouse_speed" title="Sets the mouse speed.">set_mouse_speed</a>, <a class="xref" href="alleg003.html#Standard config variables" title="">Standard config variables</a>.</blockquote> <blockquote class="eref"><em><b>Examples using this:</b></em> <a class="eref" href="alleg045.html#Available Allegro examples" title="">Available Allegro examples</a>.</blockquote> <div class="al-api"><b>void <a name="remove_mouse">remove_mouse</a>();</b></div><br> Removes the mouse handler. You don't normally need to bother calling this, because allegro_exit() will do it for you. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="alleg000.html#allegro_exit" title="Closes down the Allegro system.">allegro_exit</a>.</blockquote> <div class="al-api"><b>int <a name="poll_mouse">poll_mouse</a>();</b></div><br> Wherever possible, Allegro will read the mouse input asynchronously (ie. from inside an interrupt handler), but on some platforms that may not be possible, in which case you must call this routine at regular intervals to update the mouse state variables. To help you test your mouse polling code even if you are programming on a platform that doesn't require it, after the first time that you call this function Allegro will switch into polling mode, so from that point onwards you will have to call this routine in order to get any mouse input at all, regardless of whether the current driver actually needs to be polled or not. <p><b>Return value:</b> Returns zero on success, or a negative number on failure (ie. no mouse driver installed). <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#mouse_needs_poll" title="Tells if the mouse driver requires polling.">mouse_needs_poll</a>, <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#mouse_x" title="Global variable with the mouse position/button state.">mouse_x</a>.</blockquote> <blockquote class="eref"><em><b>Examples using this:</b></em> <a class="eref" href="alleg045.html#exlights" title="One way to do colored lighting effects in a hicolor video mode.">exlights</a>, <a class="eref" href="alleg045.html#exmouse" title="Getting input from the mouse.">exmouse</a>, <a class="eref" href="alleg045.html#exshade" title="Gouraud shaded sprites.">exshade</a>, <a class="eref" href="alleg045.html#exspline" title="Constructing smooth movement paths from spline curves.">exspline</a>, <a class="eref" href="alleg045.html#extrans" title="Lighting and translucency effects.">extrans</a>.</blockquote> <div class="al-api"><b>int <a name="mouse_needs_poll">mouse_needs_poll</a>();</b></div><br> Returns TRUE if the current mouse driver is operating in polling mode. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#poll_mouse" title="Polls the mouse.">poll_mouse</a>, <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#mouse_x" title="Global variable with the mouse position/button state.">mouse_x</a>.</blockquote> <div class="al-api"><b>void <a name="enable_hardware_cursor">enable_hardware_cursor</a>(void);</b></div><br> After calling this function, Allegro will let the operating system draw the mouse cursor instead of doing it itself. This is not possible with all graphics drivers though: you'll need to check the gfx_capabilities flags after calling show_mouse() to see if this works. On some platforms, enabling the hardware cursor causes get_mouse_mickeys() to return only a limited range of values, so you should not call this function if you need mouse mickeys. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#show_mouse" title="Tells Allegro to display a mouse pointer on the screen.">show_mouse</a>, <a class="xref" href="#set_mouse_sprite" title="Sets the mouse sprite.">set_mouse_sprite</a>, <a class="xref" href="#get_mouse_mickeys" title="How far the mouse has moved since the last call to this function.">get_mouse_mickeys</a>, <a class="xref" href="alleg008.html#gfx_capabilities" title="Bitfield describing video hardware capabilities.">gfx_capabilities</a>, <a class="xref" href="#disable_hardware_cursor" title="Disables the OS hardware cursor.">disable_hardware_cursor</a>, <a class="xref" href="#show_os_cursor" title="Low level function to display the operating system cursor.">show_os_cursor</a>.</blockquote> <blockquote class="eref"><em><b>Examples using this:</b></em> <a class="eref" href="alleg045.html#exsyscur" title="Hardware accelerated mouse cursors.">exsyscur</a>.</blockquote> <div class="al-api"><b>void <a name="disable_hardware_cursor">disable_hardware_cursor</a>(void);</b></div><br> After calling this function, Allegro will be responsible for drawing the mouse cursor rather than the operating system. On some platforms calling enable_hardware_cursor() makes the return values of get_mouse_mickeys() unreliable. After calling this function, get_mouse_mickeys() returns reliable results again. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#show_mouse" title="Tells Allegro to display a mouse pointer on the screen.">show_mouse</a>, <a class="xref" href="#set_mouse_sprite" title="Sets the mouse sprite.">set_mouse_sprite</a>, <a class="xref" href="#get_mouse_mickeys" title="How far the mouse has moved since the last call to this function.">get_mouse_mickeys</a>, <a class="xref" href="alleg008.html#gfx_capabilities" title="Bitfield describing video hardware capabilities.">gfx_capabilities</a>, <a class="xref" href="#enable_hardware_cursor" title="Enables the OS hardware cursor.">enable_hardware_cursor</a>.</blockquote> <div class="al-api"><b>void <a name="select_mouse_cursor">select_mouse_cursor</a>(int cursor);</b></div><br> This function allows you to use the operating system's native mouse cursors rather than some custom cursor. You will need to enable this functionality by calling enable_hardware_cursor() beforehand. If the operating system does not support this functionality, or if it has not been enabled, then Allegro will substitute its own cursor images. You can change these substitute images using set_mouse_cursor_bitmap(). <p> Note that the effects of this function are not apparent until show_mouse() is called. <p> To know whether the operating system's native cursor is being used, or if Allegro has made a substitution, you can check the GFX_SYSTEM_CURSOR flag in gfx_capabilities after calling show_mouse(). <p> The cursor argument selects the type of cursor to be displayed: <p> <b>MOUSE_CURSOR_NONE</b><br> Selects an invisible mouse cursor. In that sense, it is similar to calling show_mouse(NULL); <p> <b>MOUSE_CURSOR_ALLEGRO</b><br> Selects the custom Allegro cursor, i.e. the one that you set with set_mouse_sprite(). <p> <b>MOUSE_CURSOR_ARROW</b><br> The operating system default arrow cursor. <p> <b>MOUSE_CURSOR_BUSY</b><br> The operating system default <tt>`busy'</tt> cursor (hourglass). <p> <b>MOUSE_CURSOR_QUESTION</b><br> The operating system default <tt>`question'</tt> cursor (arrow with question mark). <p> <b>MOUSE_CURSOR_EDIT</b><br> The operating system default <tt>`edit'</tt> cursor (vertical bar). <p> Example: <blockquote class="code"><pre> /* initialize mouse sub-system */ <a href="#install_mouse" class="autotype" title="Installs the Allegro mouse handler.">install_mouse</a>(); <a href="#enable_hardware_cursor" class="autotype" title="Enables the OS hardware cursor.">enable_hardware_cursor</a>(); /* Set busy pointer */ <a href="#select_mouse_cursor" class="autotype" title="Tells Allegro to select software or hardware cursor drawing.">select_mouse_cursor</a>(MOUSE_CURSOR_BUSY); <a href="#show_mouse" class="autotype" title="Tells Allegro to display a mouse pointer on the screen.">show_mouse</a>(<a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a>); /* Initialize stuff */ ... /* Set normal arrow pointer */ <a href="#select_mouse_cursor" class="autotype" title="Tells Allegro to select software or hardware cursor drawing.">select_mouse_cursor</a>(MOUSE_CURSOR_ARROW); </pre></blockquote> <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#show_mouse" title="Tells Allegro to display a mouse pointer on the screen.">show_mouse</a>, <a class="xref" href="#set_mouse_sprite" title="Sets the mouse sprite.">set_mouse_sprite</a>, <a class="xref" href="alleg008.html#gfx_capabilities" title="Bitfield describing video hardware capabilities.">gfx_capabilities</a>, <a class="xref" href="#enable_hardware_cursor" title="Enables the OS hardware cursor.">enable_hardware_cursor</a>, <a class="xref" href="#set_mouse_cursor_bitmap" title="Changes the image Allegro uses for mouse cursors.">set_mouse_cursor_bitmap</a>, <a class="xref" href="#show_os_cursor" title="Low level function to display the operating system cursor.">show_os_cursor</a>.</blockquote> <blockquote class="eref"><em><b>Examples using this:</b></em> <a class="eref" href="alleg045.html#exsyscur" title="Hardware accelerated mouse cursors.">exsyscur</a>.</blockquote> <div class="al-api"><b>void <a name="set_mouse_cursor_bitmap">set_mouse_cursor_bitmap</a>(int cursor, <a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp);</b></div><br> This function changes the cursor image Allegro uses if select_mouse_cursor() is called but no native operating system cursor can be used, e.g. because you did not call enable_hardware_cursor(). <p> The cursor argument can be one of:<br> <b>MOUSE_CURSOR_ALLEGRO</b><br> <b>MOUSE_CURSOR_ARROW</b><br> <b>MOUSE_CURSOR_BUSY</b><br> <b>MOUSE_CURSOR_QUESTION</b><br> <b>MOUSE_CURSOR_EDIT</b><br> <p> but <i>not</i> MOUSE_CURSOR_NONE. <p> The bmp argument can either point to a valid bitmap or it can be NULL. Passing a bitmap makes Allegro use that image in place of its own default substitution (should the operating system's native cursor be unavailable). The bitmap must remain available for the duration in which it could be used. Passing NULL lets Allegro revert to its default substitutions. <p> The effect of this function will not be apparent until show_mouse() is called. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#show_mouse" title="Tells Allegro to display a mouse pointer on the screen.">show_mouse</a>, <a class="xref" href="#set_mouse_sprite" title="Sets the mouse sprite.">set_mouse_sprite</a>, <a class="xref" href="alleg008.html#gfx_capabilities" title="Bitfield describing video hardware capabilities.">gfx_capabilities</a>, <a class="xref" href="#enable_hardware_cursor" title="Enables the OS hardware cursor.">enable_hardware_cursor</a>, <a class="xref" href="#show_os_cursor" title="Low level function to display the operating system cursor.">show_os_cursor</a>.</blockquote> <div class="al-api"><b>extern volatile int <a name="mouse_x">mouse_x</a>;</b></div><br> <div class="al-api-cont"><b>extern volatile int <a name="mouse_y">mouse_y</a>;</b></div><br> <div class="al-api-cont"><b>extern volatile int <a name="mouse_z">mouse_z</a>;</b></div><br> <div class="al-api-cont"><b>extern volatile int <a name="mouse_w">mouse_w</a>;</b></div><br> <div class="al-api-cont"><b>extern volatile int <a name="mouse_b">mouse_b</a>;</b></div><br> <div class="al-api-cont"><b>extern volatile int <a name="mouse_pos">mouse_pos</a>;</b></div><br> Global variables containing the current mouse position and button state. Wherever possible these values will be updated asynchronously, but if mouse_needs_poll() returns TRUE, you must manually call poll_mouse() to update them with the current input state. The <tt>`mouse_x'</tt> and <tt>`mouse_y'</tt> positions are integers ranging from zero to the bottom right corner of the screen. The <tt>`mouse_z'</tt> and <tt>`mouse_w'</tt> variables hold the current vertical and horizontal wheel position, when using an input driver that supports wheel mice. The <tt>`mouse_b'</tt> variable is a bitfield indicating the state of each button: bit 0 is the left button, bit 1 the right, and bit 2 the middle button. Additional non standard mouse buttons might be available as higher bits in this variable. Usage example: <blockquote class="code"><pre> if (<a href="#mouse_b" class="autotype" title="Global variable with the mouse position/button state.">mouse_b</a> & 1) printf("Left button is pressed\n"); if (!(<a href="#mouse_b" class="autotype" title="Global variable with the mouse position/button state.">mouse_b</a> & 2)) printf("Right button is not pressed\n"); </pre></blockquote> The <tt>`mouse_pos'</tt> variable has the current X coordinate in the upper 16 bits and the Y in the lower 16 bits. This may be useful in tight polling loops where a mouse interrupt could occur between your reading of the two separate variables, since you can copy this value into a local variable with a single instruction and then split it up at your leisure. Example: <blockquote class="code"><pre> int pos, x, y; pos = <a href="#mouse_pos" class="autotype" title="Global variable with the mouse position/button state.">mouse_pos</a>; x = pos >> 16; y = pos & 0x0000ffff; </pre></blockquote> <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#poll_mouse" title="Polls the mouse.">poll_mouse</a>, <a class="xref" href="#mouse_needs_poll" title="Tells if the mouse driver requires polling.">mouse_needs_poll</a>.</blockquote> <blockquote class="eref"><em><b>Examples using this:</b></em> <a class="eref" href="alleg045.html#exalpha" title="Creating and using 32 bit RGBA sprites.">exalpha</a>, <a class="eref" href="alleg045.html#exlights" title="One way to do colored lighting effects in a hicolor video mode.">exlights</a>, <a class="eref" href="alleg045.html#exmouse" title="Getting input from the mouse.">exmouse</a>, <a class="eref" href="alleg045.html#exshade" title="Gouraud shaded sprites.">exshade</a>, <a class="eref" href="alleg045.html#exspline" title="Constructing smooth movement paths from spline curves.">exspline</a>, <a class="eref" href="alleg045.html#extrans" title="Lighting and translucency effects.">extrans</a>.</blockquote> <div class="al-api"><b>extern <a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *<a name="mouse_sprite">mouse_sprite</a>;</b></div><br> <div class="al-api-cont"><b>extern int <a name="mouse_x_focus">mouse_x_focus</a>;</b></div><br> <div class="al-api-cont"><b>extern int <a name="mouse_y_focus">mouse_y_focus</a>;</b></div><br> Global variables containing the current mouse sprite and the focus point. These are read-only, and only to be modified using the set_mouse_sprite() and set_mouse_sprite_focus() functions. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#set_mouse_sprite" title="Sets the mouse sprite.">set_mouse_sprite</a>, <a class="xref" href="#set_mouse_sprite_focus" title="Sets the mouse sprite focus.">set_mouse_sprite_focus</a>.</blockquote> <div class="al-api"><b>void <a name="show_mouse">show_mouse</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp);</b></div><br> Tells Allegro to display a mouse pointer on the screen. This will only work if the timer module has been installed. The mouse pointer will be drawn onto the specified bitmap, which should normally be <tt>`screen'</tt> (see later for information about bitmaps). To hide the mouse pointer, call show_mouse(NULL). <p> Warning: if you draw anything onto the screen while the pointer is visible, a mouse movement interrupt could occur in the middle of your drawing operation. If this happens the mouse buffering and graphics drawing code will get confused and will leave 'mouse droppings' all over the screen. To prevent this, you must make sure you turn off the mouse pointer whenever you draw onto the screen. This is not needed if you are using a hardware cursor. <p> Note: you must not be showing a mouse pointer on a bitmap at the time that the bitmap is destroyed with destroy_bitmap(), e.g. call show_mouse(NULL); before destroying the bitmap. This does not apply to <tt>`screen'</tt> since you never destroy <tt>`screen'</tt> with destroy_bitmap(). <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="alleg005.html#install_timer" title="Installs the Allegro timer interrupt handler.">install_timer</a>, <a class="xref" href="#set_mouse_sprite" title="Sets the mouse sprite.">set_mouse_sprite</a>, <a class="xref" href="#scare_mouse" title="Helper for hiding the mouse pointer before drawing.">scare_mouse</a>, <a class="xref" href="#freeze_mouse_flag" title="Flag to avoid redrawing the mouse pointer.">freeze_mouse_flag</a>, <a class="xref" href="#show_os_cursor" title="Low level function to display the operating system cursor.">show_os_cursor</a>.</blockquote> <blockquote class="eref"><em><b>Examples using this:</b></em> <a class="eref" href="alleg045.html#exmouse" title="Getting input from the mouse.">exmouse</a>, <a class="eref" href="alleg045.html#expal" title="Palette effects and color cycling.">expal</a>, <a class="eref" href="alleg045.html#exshade" title="Gouraud shaded sprites.">exshade</a>, <a class="eref" href="alleg045.html#exspline" title="Constructing smooth movement paths from spline curves.">exspline</a>, <a class="eref" href="alleg045.html#exsyscur" title="Hardware accelerated mouse cursors.">exsyscur</a>.</blockquote> <div class="al-api"><b>void <a name="scare_mouse">scare_mouse</a>();</b></div><br> Helper for hiding the mouse pointer prior to a drawing operation. This will temporarily get rid of the pointer, but only if that is really required (ie. the mouse is visible, and is displayed on the physical screen rather than some other memory surface, and it is not a hardware or OS cursor). The previous mouse state is stored for subsequent calls to unscare_mouse(). <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#unscare_mouse" title="Undoes the effect of scare_mouse() or scare_mouse_area().">unscare_mouse</a>, <a class="xref" href="#scare_mouse_area" title="Helper for hiding the mouse cursor before drawing in an area.">scare_mouse_area</a>, <a class="xref" href="#show_mouse" title="Tells Allegro to display a mouse pointer on the screen.">show_mouse</a>.</blockquote> <div class="al-api"><b>void <a name="scare_mouse_area">scare_mouse_area</a>(int x, int y, int w, int h);</b></div><br> Like scare_mouse(), but will only hide the cursor if it is inside the specified rectangle. Otherwise the cursor will simply be frozen in place until you call unscare_mouse(), so it cannot interfere with your drawing. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#unscare_mouse" title="Undoes the effect of scare_mouse() or scare_mouse_area().">unscare_mouse</a>, <a class="xref" href="#scare_mouse" title="Helper for hiding the mouse pointer before drawing.">scare_mouse</a>, <a class="xref" href="#show_mouse" title="Tells Allegro to display a mouse pointer on the screen.">show_mouse</a>.</blockquote> <div class="al-api"><b>void <a name="unscare_mouse">unscare_mouse</a>();</b></div><br> Undoes the effect of a previous call to scare_mouse() or scare_mouse_area(), restoring the original pointer state. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#scare_mouse" title="Helper for hiding the mouse pointer before drawing.">scare_mouse</a>, <a class="xref" href="#scare_mouse_area" title="Helper for hiding the mouse cursor before drawing in an area.">scare_mouse_area</a>.</blockquote> <div class="al-api"><b>int <a name="show_os_cursor">show_os_cursor</a>(int cursor);</b></div><br> In case you do not need Allegro's mouse cursor API, which automatically emulates a cursor in software if no other cursor is available, you can use this low level function to try to display or hide the system cursor directly. The cursor parameter takes the same values as select_mouse_cursor. This function is very similar to calling enable_hardware_cursor, select_mouse_cursor and show_mouse, but will not try to do anything if no system cursor is available. <p> The most common use for this function is to just call it once at the beginning of the program to tell it to display the system cursor inside the Allegro window. The return value can be used to see if this succeeded or not. On some systems (e.g. DirectX fullscreen) this is not supported and the function will always fail, and in other cases only some of the cursors will work, or in the case of MOUSE_CURSOR_ALLEGRO, only certain bitmap sizes may be supported. <p> You never should use show_os_cursor together with the function show_mouse and other functions affecting it (select_mouse_cursor, enable_hardware_cursor, disable_hardware_cursor, scare_mouse, unscare_mouse). They implement the standard high level mouse API, and don't work together with this low level function. <p><b>Return value:</b> Returns 0 if a system cursor is being displayed after the function returns, or -1 otherwise. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#show_mouse" title="Tells Allegro to display a mouse pointer on the screen.">show_mouse</a>, <a class="xref" href="#set_mouse_cursor_bitmap" title="Changes the image Allegro uses for mouse cursors.">set_mouse_cursor_bitmap</a>, <a class="xref" href="#select_mouse_cursor" title="Tells Allegro to select software or hardware cursor drawing.">select_mouse_cursor</a>.</blockquote> <div class="al-api"><b>extern volatile int <a name="freeze_mouse_flag">freeze_mouse_flag</a>;</b></div><br> If this flag is set, the mouse pointer won't be redrawn when the mouse moves. This can avoid the need to hide the pointer every time you draw to the screen, as long as you make sure your drawing doesn't overlap with the current pointer position. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#show_mouse" title="Tells Allegro to display a mouse pointer on the screen.">show_mouse</a>.</blockquote> <div class="al-api"><b>void <a name="position_mouse">position_mouse</a>(int x, int y);</b></div><br> Moves the mouse to the specified screen position. It is safe to call even when a mouse pointer is being displayed. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#position_mouse_z" title="Sets the mouse wheel position global variable.">position_mouse_z</a>, <a class="xref" href="#set_mouse_range" title="Sets the area of the screen restricting mouse movement.">set_mouse_range</a>, <a class="xref" href="#set_mouse_speed" title="Sets the mouse speed.">set_mouse_speed</a>, <a class="xref" href="#position_mouse_w" title="Sets the horizontal mouse wheel position.">position_mouse_w</a>.</blockquote> <div class="al-api"><b>void <a name="position_mouse_z">position_mouse_z</a>(int z);</b></div><br> Sets the mouse wheel position variable to the specified value. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#position_mouse" title="Moves the mouse to the specified screen position.">position_mouse</a>, <a class="xref" href="#position_mouse_w" title="Sets the horizontal mouse wheel position.">position_mouse_w</a>.</blockquote> <div class="al-api"><b>void <a name="position_mouse_w">position_mouse_w</a>(int w);</b></div><br> Sets the horizontal mouse wheel position to the specified value. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#position_mouse" title="Moves the mouse to the specified screen position.">position_mouse</a>.</blockquote> <div class="al-api"><b>void <a name="set_mouse_range">set_mouse_range</a>(int x1, int y1, int x2, int y2);</b></div><br> Sets the area of the screen within which the mouse can move. Pass the top left corner and the bottom right corner (inclusive). If you don't call this function the range defaults to (0, 0, SCREEN_W-1, SCREEN_H-1). <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#set_mouse_speed" title="Sets the mouse speed.">set_mouse_speed</a>, <a class="xref" href="#position_mouse" title="Moves the mouse to the specified screen position.">position_mouse</a>.</blockquote> <div class="al-api"><b>void <a name="set_mouse_speed">set_mouse_speed</a>(int xspeed, int yspeed);</b></div><br> Sets the mouse speed. Larger values of xspeed and yspeed represent slower mouse movement: the default for both is 2. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#set_mouse_range" title="Sets the area of the screen restricting mouse movement.">set_mouse_range</a>, <a class="xref" href="#position_mouse" title="Moves the mouse to the specified screen position.">position_mouse</a>.</blockquote> <div class="al-api"><b>void <a name="set_mouse_sprite">set_mouse_sprite</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *sprite);</b></div><br> You don't like Allegro's mouse pointer? No problem. Use this function to supply an alternative of your own. If you change the pointer and then want to get Allegro's lovely arrow back again, call set_mouse_sprite(NULL). <p> As a bonus, set_mouse_sprite(NULL) uses the current palette in choosing colors for the arrow. So if your arrow mouse sprite looks ugly after changing the palette, call set_mouse_sprite(NULL). <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>, <a class="xref" href="#show_mouse" title="Tells Allegro to display a mouse pointer on the screen.">show_mouse</a>, <a class="xref" href="#set_mouse_sprite_focus" title="Sets the mouse sprite focus.">set_mouse_sprite_focus</a>.</blockquote> <blockquote class="eref"><em><b>Examples using this:</b></em> <a class="eref" href="alleg045.html#exmouse" title="Getting input from the mouse.">exmouse</a>.</blockquote> <div class="al-api"><b>void <a name="set_mouse_sprite_focus">set_mouse_sprite_focus</a>(int x, int y);</b></div><br> The mouse focus is the bit of the pointer that represents the actual mouse position, ie. the (mouse_x, mouse_y) position. By default this is the top left corner of the arrow, but if you are using a different mouse pointer you might need to alter it. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#set_mouse_sprite" title="Sets the mouse sprite.">set_mouse_sprite</a>.</blockquote> <blockquote class="eref"><em><b>Examples using this:</b></em> <a class="eref" href="alleg045.html#exmouse" title="Getting input from the mouse.">exmouse</a>.</blockquote> <div class="al-api"><b>void <a name="get_mouse_mickeys">get_mouse_mickeys</a>(int *mickeyx, int *mickeyy);</b></div><br> Measures how far the mouse has moved since the last call to this function. The values of mickeyx and mickeyy will become negative if the mouse is moved left or up, respectively. The mouse will continue to generate movement mickeys even when it reaches the edge of the screen, so this form of input can be useful for games that require an infinite range of mouse movement. <p> Note that the infinite movement may not work in windowed mode, since under some platforms the mouse would leave the window, and may not work at all if the hardware cursor is in use. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>.</blockquote> <blockquote class="eref"><em><b>Examples using this:</b></em> <a class="eref" href="alleg045.html#exmouse" title="Getting input from the mouse.">exmouse</a>.</blockquote> <div class="al-api"><b>extern void (*<a name="mouse_callback">mouse_callback</a>)(int flags);</b></div><br> Called by the interrupt handler whenever the mouse moves or one of the buttons changes state. This function must be in locked memory, and must execute _very_ quickly! It is passed the event flags that triggered the call, which is a bitmask containing any of the values MOUSE_FLAG_MOVE, MOUSE_FLAG_LEFT_DOWN, MOUSE_FLAG_LEFT_UP, MOUSE_FLAG_RIGHT_DOWN, MOUSE_FLAG_RIGHT_UP, MOUSE_FLAG_MIDDLE_DOWN, MOUSE_FLAG_MIDDLE_UP, and 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. <blockquote class="xref"><em><b>See also:</b></em> <a class="xref" href="#install_mouse" title="Installs the Allegro mouse handler.">install_mouse</a>.</blockquote> <div class="al-api"><b>int <a name="mouse_on_screen">mouse_on_screen</a>();</b></div><br> 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. <p> Example : <blockquote class="code"><pre> if (<a href="#mouse_on_screen" class="autotype" title="Tells you whether the mouse pointer is currently on screen.">mouse_on_screen</a>()) {<a href="alleg014.html#draw_sprite" class="autotype" title="Draws a copy of the sprite onto the destination bitmap.">draw_sprite</a>(buffer , <a href="#mouse_sprite" class="autotype" title="Global variable with the mouse sprite and focus point.">mouse_sprite</a> , <a href="#mouse_x" class="autotype" title="Global variable with the mouse position/button state.">mouse_x</a> , <a href="#mouse_y" class="autotype" title="Global variable with the mouse position/button state.">mouse_y</a>);} </pre></blockquote> <p><b>Return value:</b> <p> Returns 0 if the mouse pointer is off of the screen, or non-zero otherwise. <p><br> <hr><div class="al-back-to-contents"><a href="allegro.html">Back to contents</a></div> </body> </html>