Skip to content
SplashKit
Announcements

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