Skip to content

Using Mouse Inputs

Introductory Mouse Input functionality guide
Written by: Various Authors
Last updated: October 2024


Mouse Button Functionality

Here are some functions that are used to handle mouse button inputs. These functions all use SplashKit’s Mouse Button data type for the argument and check if the specified button has been clicked, held down, or released.

List of Mouse Button Enum Values

Mouse Button is an enumeration used by SplashKit to read inputs from the mouse. Understanding how to handle mouse buttons is crucial for developers who want users to control their programs using the mouse.

DescriptionEnum Value in Code
No mouse buttonNO_BUTTON
The left mouse buttonLEFT_BUTTON
The middle mouse buttonMIDDLE_BUTTON
The right mouse buttonRIGHT_BUTTON
The x1 mouse buttonMOUSE_X1_BUTTON
The x2 mouse buttonMOUSE_X2_BUTTON

Mouse Clicked

Mouse Clicked is a boolean function that checks if the specified Mouse Button has been clicked since the last time Process Events was called.

Here is a simple example using the left and right mouse buttons:

#include "splashkit.h"
int main()
{
open_window("Mouse Inputs", 800, 600);
while (!window_close_requested("Mouse Inputs"))
{
// process user input events
process_events();
// change screen colour to red if left mouse button is clicked
if (mouse_clicked(LEFT_BUTTON))
{
clear_screen(COLOR_RED);
}
// change screen colour to yellow if right mouse button is clicked
else if (mouse_clicked(RIGHT_BUTTON))
{
clear_screen(COLOR_YELLOW);
}
refresh_screen(60);
}
close_all_windows();
return 0;
}

Mouse Down

Mouse Down checks if the specified button is being held down.

Here is a simple example using the left and right mouse buttons:

#include "splashkit.h"
int main()
{
open_window("Mouse Inputs", 800, 600);
while (!window_close_requested("Mouse Inputs"))
{
// process user input events
process_events();
// change screen colour to red if left mouse button is held down
if (mouse_down(LEFT_BUTTON))
{
clear_screen(COLOR_RED);
}
// change screen colour to yellow if right mouse button is held down
else if (mouse_down(RIGHT_BUTTON))
{
clear_screen(COLOR_YELLOW);
}
// change screen colour to white if no mouse button held down
else
{
clear_screen(COLOR_WHITE);
}
refresh_screen(60);
}
close_all_windows();
return 0;
}

Mouse Up

Opposite to the previous function, Mouse Up checks if the specified button is released.

Here is a simple example using the left mouse button:

#include "splashkit.h"
int main()
{
open_window("Mouse Inputs", 800, 600);
while (!window_close_requested("Mouse Inputs"))
{
// process user input events
process_events();
// change screen colour to red if left mouse button is not pressed
if (mouse_up(LEFT_BUTTON))
{
clear_screen(COLOR_RED);
}
// change screen colour to white if left button is pressed
else
{
clear_screen(COLOR_WHITE);
}
refresh_screen(60);
}
close_all_windows();
return 0;
}

Mouse Movement Functionality

Another thing we can do with mouse input, other than checking button presses, is to check mouse movement in the program.

Mouse Movement

Mouse Movement is a function that returns the amount of accumulated mouse movement since the last time Process Events was called. It returns the value as a Vector 2D data type, which shows the direction and distance in the x and y scale.

Here is an example using the left mouse button combined with horizontal movement to change the hue of the screen colour, and the right mouse button combined with vertical movement to change the saturation of the screen colour:

#include "splashkit.h"
int main()
{
// colour variables
double hue = 0.8;
double saturation = 0.8;
double brightness = 0.8;
// mouse movement variable
vector_2d movement;
open_window("Mouse Movement", 800, 600);
while (!window_close_requested("Mouse Movement"))
{
// process user input events
process_events();
// store the mouse movement direction and distance to the movement variable
movement = mouse_movement();
// change screen colour 'hue' if left mouse button is held down
if (mouse_down(LEFT_BUTTON))
{
// change hue of screen colour based on horizontal mouse movement
hue += movement.x / screen_width();
}
// change screen colour 'saturation' if right mouse button is held down
if (mouse_down(RIGHT_BUTTON))
{
// change saturation of screen colour based on vertical mouse movement
saturation += movement.y / screen_height();
}
// display current screen colour
clear_screen(hsb_color(hue, saturation, brightness));
refresh_screen(60);
}
close_all_windows();
return 0;
}

Mouse Wheel Scroll

Mouse Wheel Scroll returns the distance and direction of the mouse scroll since the last time Process Events was called. Like the previous function, this function returns the Vector 2D data type.

Here is an example using vertical scrolling to change the hue of the screen colour:

#include "splashkit.h"
int main()
{
// color variables
double hue = 0.6;
double saturation = 0.6;
double brightness = 0.6;
// mouse scroll variable
vector_2d scroll;
open_window("Mouse Scrolling", 800, 600);
while (!window_close_requested("Mouse Scrolling"))
{
// process user input events
process_events();
// store the mouse wheel scroll direction and distance to the scroll variable
scroll = mouse_wheel_scroll();
// change hue of screen colour based on vertical mouse scrolling (two fingers if using trackpad)
hue += scroll.y / 100;
// display current screen colour
clear_screen(hsb_color(hue, saturation, brightness));
refresh_screen(60);
}
close_all_windows();
return 0;
}

Mouse Location Functionality

Now that we have learned how to handle mouse inputs and movements, let’s look at how to use the mouse’s location in the window, which can be used in your program to make the experience more interactive. Combined with the mouse input functions, it can be used to spawn items where the player clicked or respond to the player clicking where an item is located.

Mouse Position

Mouse Position returns the position of the mouse in the current window as a Point 2d data type, which is its x and y coordinates.

Here is a simple example that draws a circle at the mouse position:

#include "splashkit.h"
int main()
{
open_window("Mouse Location", 800, 600);
while (!window_close_requested("Mouse Location"))
{
// process user input events
process_events();
// draw blue circle at mouse position
clear_screen(COLOR_WHITE);
fill_circle(COLOR_LIGHT_BLUE, circle_at(mouse_position(), 20));
refresh_screen(60);
}
close_all_windows();
return 0;
}

Mouse Position Vector

Mouse Position Vector returns the position of the mouse relative to the window origin as a Vector 2d.

Here is a simple example that displays the mouse position vector as a line:

#include "splashkit.h"
int main()
{
open_window("Mouse Location", 800, 600);
while (!window_close_requested("Mouse Location"))
{
// process user input events
process_events();
// draw line from mouse position vector
clear_screen(COLOR_WHITE);
draw_line(COLOR_BLUE, line_from(mouse_position_vector()));
refresh_screen(60);
}
close_all_windows();
return 0;
}

Mouse X

Mouse X returns the distance of the mouse from the left edge of the window.

Here is an example using the left mouse button to drag a “curtain” across the screen from the left side, based on the mouse’s x coordinate:

#include "splashkit.h"
int main()
{
float x = 0;
open_window("Mouse Location", 800, 600);
while (!window_close_requested("Mouse Location"))
{
// process user input events
process_events();
if (mouse_down(LEFT_BUTTON))
{
x = mouse_x();
}
clear_screen(COLOR_WHITE);
fill_circle(COLOR_BLUE, 400, 300, 100);
// draw purple "curtain" from left side of screen to x coordinate of mouse
fill_rectangle(COLOR_PURPLE, 0, 0, x, screen_height());
refresh_screen(60);
}
close_all_windows();
return 0;
}

Mouse Y

Mouse Y returns the distance of the mouse from the top edge of the window.

Here is an example using the left mouse button to drag a “curtain/blind” down the screen from the top, based on the mouse’s y coordinate:

#include "splashkit.h"
int main()
{
float y = 0;
open_window("Mouse Location", 800, 600);
while (!window_close_requested("Mouse Location"))
{
// process user input events
process_events();
if (mouse_down(LEFT_BUTTON))
{
y = mouse_y();
}
clear_screen(COLOR_WHITE);
fill_circle(COLOR_BLUE, 400, 300, 100);
// draw purple "curtain" from top of screen to y coordinate of mouse
fill_rectangle(COLOR_PURPLE, 0, 0, screen_width(), y);
refresh_screen(60);
}
close_all_windows();
return 0;
}

Mouse Visibility

Finally, we can also alter the mouse visibility on SplashKit. The following functions handles the mouse visibility. These can be useful to create a more immersive environment for your game.

Hide/Show Mouse

Hide Mouse hides the mouse from the screen. Show Mouse shows the mouse to the screen.

Here is a simple example where the mouse “disappears in a black hole”:

#include "splashkit.h"
int main()
{
// create cirle variable for "black hole"
circle blackHole;
open_window("Mouse Visibility", 800, 600);
// create black hole in centre of screen
blackHole = circle_at(screen_center(), 50);
while (!window_close_requested("Mouse Visibility"))
{
// process user input events
process_events();
// mouse disappears in black hole
if (point_in_circle(mouse_position(), blackHole))
{
hide_mouse();
}
// mouse reappears once out of black hole
else
{
show_mouse();
}
// display "black hole" on screen
clear_screen(COLOR_WHITE);
fill_circle(COLOR_BLACK, blackHole);
refresh_screen(60);
}
close_all_windows();
return 0;
}

Show Mouse

There are two versions of the Show Mouse function. The first version is shown above. The second version shows or hides the mouse based on its boolean parameter. If true, it shows the mouse, while if false, it hides the mouse from the screen.

Here is a simple example where the mouse is only visible in the “spot light”:

#include "splashkit.h"
int main()
{
// create cirle variable for emulating a "stage spot light"
circle spotLight;
open_window("Mouse Visibility", 800, 600);
// create a "spot light" circle in centre of screen
spotLight = circle_at(screen_center(), 100);
while (!window_close_requested("Mouse Visibility"))
{
// process user input events
process_events();
// mouse disappears when not in the "spot light"
show_mouse(point_in_circle(mouse_position(), spotLight));
// display "spot light" on screen
clear_screen(COLOR_BLACK);
fill_circle(COLOR_ALICE_BLUE, spotLight);
refresh_screen(60);
}
close_all_windows();
return 0;
}