Skip to content
SplashKit
Announcements

User Inputs in Graphical Applications

Introductory guide on reading text and mouse input functionality.
Written by: Various
Last updated: July 2025

Reading Text in Graphical Applications

Section titled “Reading Text in Graphical Applications”

Reading input from users in graphical applications is more complex than using command line inputs, as blocking operations will cause the entire graphical interface to freeze.

With a graphical application, you need to keep redrawing, processing events, updating elements, and refreshing the screen. If you stop doing this to wait for user input, then any dynamic visuals will stop!

Example Code

Section titled “Example Code”

Let’s see how to read input from the user using some example code. We can then talk through the different parts to understand how they come together to give you a dynamic application with user input.

#include "splashkit.h"


int main()
{
    // Lets read into this string...
    string name = "unknown";


    // Open a window to show the user...
    open_window("Reading Input.", 800, 600);


    // Load a font for text rendering
    load_font("input", "arial.ttf");


    // Define area where text should appear
    rectangle rect = rectangle_from(230.0, 50.0, 200.0, 30.0);


    // Start reading text in this area
    start_reading_text(rect);


    // Here is our game loop
    do
    {
        // Listen for input... this will update the text read
        process_events();


        // Click anywhere on the screen to trigger the text input
        if (mouse_clicked(LEFT_BUTTON))
        {
            // Start reading text in the rectagle area
            start_reading_text(rect);
        }


        // Looks like we finished reading text...
        if (not reading_text())
        {
            // Was input cancelled?
            if (text_entry_cancelled())
            {
                name = "unknown";
            }
            else
            {
                // Get the name from the text input
                name = text_input();
            }
        }


        // Draw the screen...
        clear_screen(COLOR_WHITE);
        draw_rectangle(COLOR_BLACK, rect);


        // If we are reading text... then show what it is
        if (reading_text())
        {
            draw_collected_text(COLOR_BLACK, font_named("input"), 18, option_defaults());
        }


        // Draw text instructions
        draw_text("Click anywhere to start reading text", COLOR_RED, font_named("input"), 18, 200, 100);


        // Draw what we have in the name
        draw_text(name, COLOR_BLACK, font_named("input"), 18, 10, 10);


        // Show it..
        refresh_screen(60);
    } while (!quit_requested());


    close_all_windows();
    return 0;
}

Understanding the code

Section titled “Understanding the code”

  1. In the above program we want to read in the user’s name and store it in the name variable. To get started with this we need to open a window and load a font to draw the text and input. There is also the standard event loop that repeats the basic actions of checking user input and drawing the screen until the program is closed.

  2. The logic for reading input starts with the call to Start Reading Text. This tells SplashKit that you want it to collect text input by the user, and that you want it drawn into the passed-in Rectangle (in this case rect). SplashKit is now listening for input from, and collecting this text for you when you call Process Events.

  3. SplashKit will continue reading text from the user until they hit the Escape or Enter key. You can check if text is still being read by calling the Reading Text function. In this example, we use this to update the name. You can also end text input yourself using the End Reading Text function.

  4. When the SplashKit is no longer reading text, you can use Text Entry Cancelled to check if the user cancelled (by hitting Escape) the input. To read the actual value entered, you call Text Input. This will return the value entered by the user. If they did cancel the input, then this will be an empty string.

  5. The key with graphical input will be to keep updating the data associated with the graphical elements. This will keep the screen updating as you collect the input from the user. For this, you need to Start Reading Text, then at some point collect the Text Input and End Reading Text.

Using Mouse Inputs in Graphical Applications

Section titled “Using Mouse Inputs in Graphical Applications”

Mouse Button Functionality

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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;
}