PyGameUI Documentation: Basics

With PyGameUI, all of this can be created with just a few lines of code!

Basics: Getting started <-- (Start Here!)

Start by downloading the PyGameUI python file:

Than place the PyGameUI file in the same folder as your project files.

Your project directory should now look like this:

            
project_folder/
└───pygameui.py
└───main.py
            
        

To use PyGameUI in a project, the projects needs to have at least a basic pygame script with PyGameUI imported as any other library:

            
import pygame, sys
import pygameui

pygame.init()

win = pygame.display.set_mode((500, 500))

clock = pygame.time.Clock()
while True:
    win.fill((0, 0, 0))
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()
            sys.exit()

    pygame.display.flip()
    clock.tick(60)
            
        

With this done you are ready to get started using PyGameUI!

Basics: Text elements

Creating a text element

Adding a text element only requires 1 line of code:
The two arguments are position (x, y) and content

            
example_text = pygameui.Text((200, 200), "My cool text")
            
        

Drawing the text only requires 1 line of code too:

            
example_text.draw(win)
            
        

Final code:

            
import pygame, sys, pygameui

pygame.init()

win = pygame.display.set_mode((500, 500))

# Create text element
example_text = pygameui.Text((200, 200), "My cool text")

clock = pygame.time.Clock()
while True:
    win.fill((0, 0, 0))
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()
            sys.exit()
    
    # Draw text
    example_text.draw(win)

    pygame.display.flip()
    clock.tick(60)
            
        

Result:

Customizing our text element

In addition to the required parameters, we can pass in optional ones. This allows even more customizing!

The text element has so far four optional parameters: font, fontSize, color and centerMode.

To edit an optional argument just add another parameter when creating the element.
Example:

            
# Adding one parameter
example_text = pygameui.Text((200, 200), "My cool text", (255, 255, 200), fontName = "elephant")
# Adding multiple parameters
example_text_2 = pygameui.Text((200, 200), "My cool not centermoded text", (255, 255, 100), fontSize = 50, centerMode = False)
            
        

Final code:

            
import pygame, sys, pygameui

pygame.init()

win = pygame.display.set_mode((500, 500))

# Adding one parameter
example_text = pygameui.Text((200, 200), "My cool text", (255, 255, 200), font_name = "elephant")
# Adding multiple parameters
example_text_2 = pygameui.Text((200, 200), "My cool not centermoded text", (255, 255, 100), font_size = 50, center_mode = False)

clock = pygame.time.Clock()
while True:
    win.fill((0, 0, 0))
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()
            sys.exit()
    
    example_text.draw(win)
    example_text_2.draw(win)

    pygame.display.flip()
    clock.tick(60)
            
        

Result:

Notice how the both text elements have the same position but still are placed at different locations.
This is because the larger one has centerMode set to false.

Basics: General elements

Creating a general element

A general element can be anything from just a decorative rectangle to an image or button.
They are created in the same way as text elements but only requires a position:

            
example_element = pygameui.Element((300, 300))
            
        

General elements can also contain text or images:

            
# Creating an element with text
element_with_text = pygameui.Element((300, 300), "My cool element")

# Creating an element with an image
my_amaizing_image = pygame.image.load("my_amaizing_image.png")
element_with_image = pygameui.Element((300, 300), content=my_amaizing_image)
        
            
        

General elements are drawn in the same way as text elements:

            
example_element.draw(win)
            
        

Final code:

            
import pygame, sys, pygameui

pygame.init()

win = pygame.display.set_mode((500, 500))

example_element = pygameui.Element((300, 300))

clock = pygame.time.Clock()
while True:
    win.fill((0, 0, 0))
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()
            sys.exit()
    
    example_element.draw(win)

    pygame.display.flip()
    clock.tick(60)
            
        

Result:

Customizing general elements

General elements are customized in the same way as text elements, but have a lot more posible parameters.

Basics: Input elements

Creating an input element

To add an input element just follow the same process as the other elements:
The only required argument is the position.

            
example_input = pygameui.Input((200, 200))
            
        

Input elements are drawn in the same way as any other element:

            
example_input.draw(win)
            
        

Final code:

            
import pygame, sys
import pygameui

pygame.init()

win = pygame.display.set_mode((500, 500))

# Creating an input
example_input = pygameui.Input((200, 200))

clock = pygame.time.Clock()
while True:
    win.fill((0, 0, 0))
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()
            sys.exit()
    # Drawing the input
    example_input.draw(win)

    # Updating the display
    pygame.display.flip()
    clock.tick(60)
            
        

Result:

Giving the input element functionality

As you probatly have notices our input element looks nice and all that, but lacks any functionality...
We first have to store the events from the pygame.event.get(). To do this swap this code:

            
for event in pygame.event.get():
    if event.type == pygame.QUIT:
        pygame.quit()
        sys.exit()
            
        

With this code:

            
events = pygame.event.get()
for event in events:
    if event.type == pygame.QUIT:
        pygame.quit()
        sys.exit()
            
        

Now we can add functionality to the input element. To do this we need to add a few lines of code.
First we have to create a list of the clickable elements in our project. This list tells PyGameUI when
it should change the cursor to a hand. (Indicating that the element is clickable)

Right now our project only includes one clickable element so our list can be created like this:

            
clickable_elements = [example_input]
            
        

Now we can add the functionality to the input element. This is done by just adding a line of code to the main loop:

            
example_input.work(events, clickable_elements)
            
        

Final code:

            
import pygame, sys
import pygameui

pygame.init()

win = pygame.display.set_mode((500, 500))

# Creating an input
example_input = pygameui.Input((200, 200))

# Creating a list of all clickable elements
clickable_elements = [example_input]

clock = pygame.time.Clock()
while True:
    win.fill((0, 0, 0))

    events = pygame.event.get()
    for event in events:
        if event.type == pygame.QUIT:
            pygame.quit()
            sys.exit()

    # Give the input funcionality
    example_input.work(events, clickable_elements)

    # Drawing the input
    example_input.draw(win)

    # Updating the display
    pygame.display.flip()
    clock.tick(60)
            
        

Result:

Now just click on the input to activate it, write to your heart's content, and click the input or outside of it to deactivate.

Obtaining input text

Now that we have a working input element, we can obtain the text from it. This is done by calling the getValue() method on the input element.

            
input_text = example_input.getValue()
print(input_text)
            
        

Final code:

            
import pygame, sys
import pygameui

pygame.init()

win = pygame.display.set_mode((500, 500))

# Creating an input
example_input = pygameui.Input((200, 200))

# Creating a list of all clickable elements
clickable_elements = [example_input]

clock = pygame.time.Clock()
while True:
    win.fill((0, 0, 0))

    events = pygame.event.get()
    for event in events:
        if event.type == pygame.QUIT:
            pygame.quit()
            sys.exit()

    # Give the input funcionality
    example_input.work(events, clickable_elements)

    # Obtaining the input value and printing it
    input_text = example_input.getValue()
    print("You have written: " + input_text)

    # Drawing the input
    example_input.draw(win)

    # Updating the display
    pygame.display.flip()
    clock.tick(60)  
            
        

Customizing input elements

Input elements are customized in the same way as the other elements.

What to do now?

Now that you have learned the basics of PyGameUI, you can start giving your project even more functionality or bling!