PyGraphica 1.0.1

By Luke Campbell

PyGraphica is a simple GUI and game development module designed for Python, built of the Python bindings (pysdl2) for SDL-2.

One important note before we start. For all coordinates and lengths, if represented as an integer will be interpreted as a measurement in pixels, and if represented as a string (e.g. '35') will be interpreted as a  percentage of the height or width.



Installation

The most simple installation is via pip, i.e

    py -m pip install PyGraphica

(for windows)

    python -m pip install PyGraphica

(for linux)

However the source code can be downloaded from GitHub (https://github.com/LukeCampbell5853/PyGraphica) if pip installation fails.

Once the module has been imported, add it to your Python project like this:

    from PyGraphica import draw, colours, origins, fonts



Colours, Origins, and Fonts files

The colours file contains a series of default RGB tuples, which can be used to simplify coding. The colours can be accessed by the following variable names:

    BLACK
    DARK_GREY
    GREY
    LIGHT_GREY
    WHITE

    DARK_RED
    RED
    PASTEL_PINK
    ORANGE
    PINK

    DARK_GREEN
    GREEN
    PASTEL_GREEN
    LIGHT_GREEN
    NEON_GREEN

    NAVY_BLUE
    DARK_BLUE
    PASTEL_BLUE
    BLUE
    PURPLE

    MUSTARD
    YELLOW
    LIGHT_YELLOW

    TURQUISE
    LIGHT_BLUE
    PALE_BLUE

    DARK_PINK
    LIGHTPINK
    PALE_PINK

For example:

    colours.PASTEL_BLUE


The Origins file contains the five origin options, top-left, top-right, bottom-left, bottom-right, and centre. These origins can be accessed using the following variable names:

    TOP_LEFT
    TOP_RIGHT
    BOTTOM_LEFT
    BOTTOM_RIGHT
    CENTRE

For example:

    origins.BOTTOM_LEFT


The fonts file contains the path to the default fonts included in PyGraphica. These paths can be accessed using the following names:

    Arial
    Baskerville
    BrushScript
    Calibri
    Courier
    Garamond
    Helvetica
    Impact
    OpenDyslexic
    TimesNewRoman
    Trebuchet

For example:

    fonts.OpenDyslexic



Creating a window

The window class can be defined by the following attributes:

    attribute  default       type                                          description                                                             

    name       'PyGraphica'  string                                        name that will appear above the window                                  
    size       (800, 600)    tuple of two integers or strings of integers  dimensions (in px) of the screen                                        
    resizable  False         boolean                                       whether the user can resize the window by dragging                      
    icon       False         Path (string) to file, or False for no icon   The image that will be  displayed in the  top left corner of the window 
    position   (0,20)        tuple of two integers or strings of integers  The location (px) of the window on the screen                           
    origin     top left      variable from origins file                    The location of the origin and corresponding coordinate system          
    colour     black         variable from colours file or RGB tuple       background colour of the window                                         

An example window could be:

    NavCS = draw.window("NavCS", (400,600), True, "NavCS_logo_icon.jpg", (0,20), origins.CENTRE, colours.WHITE)

Once the window has been created the following attributes can be called:

    attribute     description                                                   

    keys          keys currently held by the user                               
    comms         command keys currently held by the user                       
    key_changes   keys newly pressed by the user (not held)                     
    comm_changes  command keys newly pressed by the user (not held)             
    caps          whether capslock is on or shift is held                       
    mouse_x       x position of the mouse                                       
    mouse_y       y position of the mouse                                       
    mouse_down    whether the mouse button is held down                         
    mouse_held    whether the mouse button is held down for more than one cycle 

A window object has two important methods, running() and update(). running() will return whether the window's close button has been pressed yet, and update() will display all your objects to the screen. These two can be combined into the following cycle:

    while app.running():
        #do stuff
        app.update()



Creating a line

The line class can be defined by the following attributes:

    attribute  type                                     description                            

    window     window object                            window which the line will be drawn to 
    x1         integer or string of integer             x component of the start coordinate    
    x2         integer or string of integer             x component of the end coordinate      
    y1         integer or string of integer             y component of the start coordinate    
    y2         integer or string of integer             y component of the end coordinate      
    colour     variable from colours file or RGB tuple  colour of the line                     

For example

    line1 = draw.line(app, 100, 70, 250, 300, colours.RED)

Once the line has been created the following attributes can be called:

    name     description                                        

    visible  whether the line is displayed to the screen or not 



Creating a rectangle

The rectangle class can be defined by the following attributes:

    name              default  type                                                         description                            

    window            NA       window object                                                window which the line will be drawn to 
    x1                NA       integer or string of integer                                 x component of the start coordinate    
    x2                NA       integer or string of integer                                 x component of the end coordinate      
    y1                NA       integer or string of integer                                 y component of the start coordinate    
    y2                NA       integer or string of integer                                 y component of the end coordinate      
    colour            False    variable from colours file, RGB tuple, or False for no fill  fill colour of rectangle               
    border_colour     False    integer or False for no border                               colour of the border of the rectangle  
    border_thickness   1       positive integer                                             thickness of the border                

For example:

    my_rect = draw.rectangle(app, 10, 20, 600, 750, colours.PURPLE, colours.YELLOW, 2)

Once the rectangle has been created the following attributes can be called:

    name     description                                             

    visible  whether the rectangle is displayed to the screen or not 
    hover    whether the mouse is hovered over the rectangle         
    clicked  whether theuser has selected the rectangle              

For example:

    if my_rect.clicked:
        my_rect.visible = False



Creating text

The text class can be defined by the following attributes:

    name     default   type                                            description                            

    window   NA        window object                                   window which the text will be drawn to 
    x1       NA        integer                                         x component of the start coordinate    
    y1       NA        integer                                         y component of the start coordinate    
    size     NA        positive integer or string of positive integer  height of the text             
    colour   NA        variable from colours file or RGB tuple         colour of the text                     
    content  NA        string                                          content of the text                    
    font     OpenSans  string                                          font of the text                       

For example:

    title = draw.text(app, 100, -50, 20, colours.NAVY_BLUE, "Hello world!", "OpenSans")

Once the text object has been creeated the following attributes can be called:

    name     description                                        

    visible  whether the text is displayed to the screen or not 
    hover    whether the mouse is hovered over the text         
    clicked  whether the user has selected the text             
    x2       x component of the end coordinate                  
    y2       y component of the end coordinate                  

For example:

    if title.clicked:
        title.colour = colours.PASTEL_BLUE
    elif title.hover:
        title.colour = colours.BLUE
    else:
        title.colour = colours.NAVY_BLUE



Creating a textbox

A textbox is an input field in which users can type text. A textbox can be defined by the following attributes:

 name          default       type                          description                                                                          

 window        NA            window object                 window to which the textbox will be drawn                                            
 x1            NA            integer or string of integer  x component of the start coordinate                                                  
 y1            NA            integer or string of integer  y component of the start coordinate                                                  
 size          NA            integer or string of integer  height of text                                                                       
 width         1             integer or string of integer  width of textbox (NB: textbox will expand if text goes out of textbox)               
 default_text  Type here...  string                        text which will be displayed in lighter shade if the user has not yet typed anything 

For example:

    code_input = draw.textbox(app,"20","10","3","80","ENTER CODE HERE")

 name     description                                           

 visible  whether the textbox is displayed to the screen or not 
 hover    whether the mouse is hovered over the textbox         
 clicked  whether the user has selected the textbox             
 x2       x component of the end coordinate                     
 y2       y component of the end coordinate                     
 content  the content the user has typed into the textbox       

For example:

    def submit():
        response = code_input.content
        if response == "open sesame":
            #let them to the next stage
        else:
            code_input.content = ""



Creating an image

The image class can be defined by the following parameters:

 Name    Default  Type                                                                                                         Description                             

 window  NA       window object                                                                                                window to which the image will be drawn 
 path    NA       string                                                                                                       path to image file                      
 x1      NA       integer or string of integer                                                                                 x component of the start coordinate     
 y1      NA       integer or string of integer                                                                                 y component of the start coordinate     
 height  False    positive integer, string of positive integer or False if height is to be defined by width and aspect  ratio  height of the image                     
 width   False    positive integer, string of positive integer or False if width is to be defined by height and aspect  ratio  width of the image                      

For example:

    background = draw.image(app, "/my_images/background_image.jpg", 0, 0,  width = "100")



Collision function

The collision function takes two objects as input, and then returns a boolean for whether their hitboxes overlap. For example:

    if draw.collision(rect1,image2):
        #do something



To_front and to_back functions

These functions can be used to reorder the elements on the screen. For example:

    draw.to_back(background_img)

Or

    draw.to_font(player)



Delete function

This function is used to delete an object. For example:

    draw.delete(rect1)