UITools

• UITools.py
  • Global Variables
    • mouseIsDown
    • screenwidth, screenheight
    • mousex, mousey
    • startMouseX, startMouseY
    • fgcol, bgcol
    • adjustMenuX
    • sxh, syh
    • showMsg
  • Functions
    • def nullfunc()
    • def drawImage(drawsurface, filepath, x, y, angle=0)
    • def showMessage(msgmiddle, msgupper, msglower, releaseontouch)
    • def showAskMessage(message, yestext, yesfunction, notext, nofunction)
    • def drawText(screen, text, centerx, centery, fgcol, bgcol)
    • def drawCloseButton(screen)
    • def isOverCloseButton(x, y, checkForStartMouse)
    • def drawAppButton(screen, text, ypos, forecol, backcol)
    • def isOverAppButton(mx, my, checkForStartMouse)
  • INTERNAL USED STUFF
    • menuFont
    • releaseMsgOnTouch
    • globalmessage_middle, globalmessage_upper, globalmessage_lower
    • def initialize()
    • def mouseIsOverAskButton(mx, my)
    • def __ getMousePosition()
    • def __ drawMessage(screen)

UITools.py

Go back [Home]

UITools.py provides some helper variables and functions to draw stuff in the "system style".
Not all variables and functions are described here: Some are used internally and you don't need to use them directly or at all.

Global Variables

mouseIsDown

Will be set to True when ANY mouse button is down (display is touched) and to False when the display is released.

screenwidth, screenheight

The width and height of the display.
Set it here directly when your display has another size.

mousex, mousey

The actual mouse position. Will be set in APP_BASE.update().

startMouseX, startMouseY

The mouse x and y position when the display first gets touched/clicked.
Used to determine if a button was clicked or if it just was moved over accidentally.

fgcol, bgcol

The system wide Foreground Color (fgcol) and Background Color (bgcol).
Use them if you want your App to be colored like the other Apps.

adjustMenuX

Move stuff this amount inwards on the left and right x position so that the App fits into (my) cutted out screen hole.

sxh, syh

All over used HALF screenwidth and HALF screenheight.

showMsg

True if a (global) message is shown on the display with UITools.showMessage.
Use this to determine if your App is "paused" when a message is shown.
Set it to False to hide the message.
This is set to False internally on touch/click of the screen.

All other (global) variables are internally used and do not need to be affected by you directly.
Internal used variables are described at the end of this page.

---

Functions

def nullfunc()

Just returns. Used for empty menu buttons.

def drawImage(drawsurface, filepath, x, y, angle=0)

Draws the image with the given filepath onto the (pygame) drawsurface at position x and y and rotated by angle.
It will load the image when it is not loaded or get it from a dictionary when it's already loaded.
The dictionary uses the filepath as key.

drawsurface is the pygame surface to draw on, usually the screen variable from the Apps update function.
filepath is the full or relative file path to your image. Use APP_BASE.HOME_PATH to create the full path. Don't use relative paths because the scripts could be started from another directory.
x, y are the position where the image should be drawed on the drawsurface. It's the upper left corner of the image. You may need to center it for yourself.
angle is an angle in degrees to rotate the image on the drawsurface.

def showMessage(msgmiddle, msgupper, msglower, releaseontouch)

Shows a global message which is hidden when the user touches/clicks the display.

msgmiddle is mandatory: The text to be shown on the middle of the display.
msgupper can be ommited. Default is empty (""). The text to be shown above the middle line.
msglower can be ommited. Default is empty(""). The text to be shown under the middle line.
releaseontouch can be ommited. Default is False. If this is set to True, it will hide the message directly when the user touches the screen, and the App will continue and interact with the already touched display. If it is False, it will hide the message after the display was released. The App will continue but you have to touch again to interact. (E.g. it is set to True in the Breakout Game App so that the user can play directly when the finger is on the display.)

def showAskMessage(message, yestext, yesfunction, notext, nofunction)

Shows a message with two buttons to select from. The first button will call yesfunction and the second one will call nofunction if pressed.

notext and nofunction can be ommited. Its 'Cancel' and nullfunc then.

message is the message text to be shown in the message window.
yestext is the text shown on the left button.
yesfunction is the function that will be called when pressing the left button.
notext is the text shown on the right button. Default is 'Cancel'.
nofunction is the function called when pressing the right button. Default is nullfunc.

def drawText(screen, text, centerx, centery, fgcol, bgcol)

Draws a text at the specified center position with the given colors.
It is relatively complex in pygame to draw a text. This function shortens it.

fgcol and bgcol can be ommited. They are white and black then.

It uses the systemwide menuFont, which is 32px in height. (Use 35px for setting line y)

screen is the pygame surface to draw on. If you want to draw directly to the display, use the screen variable from your Apps update function.
Note that you can only draw directly to the display in the Apps update function, where a screen variable is passed to.
text is the text to be drawed, of course.
centerx, centery are the center position of your text on the screen.
fgcol is the foreground color - the color of the characters from the text.
bgcol is the background color, the color of your texts surrounding rectangle. You can not set it to transparent (right now).

def drawCloseButton(screen)

This is a short to drawAppButton, where button 0 is drawed with an X on it.
That is the topmost button.

screen is the pygame surface to draw on, respectively the screen variable from your Apps update function.

def isOverCloseButton(x, y, checkForStartMouse)

A short to isOverAppButton. It checks for button 0.
Returns True or False.

x, y are the position to be checked.
checkForStartMouse is the checkForStartMouse flag passed to isOverAppButton. Look there for reference.

def drawAppButton(screen, text, ypos, forecol, backcol)

Draws one of the 5 or 6(?) visible App buttons which you can use in your App. Maybe later there will be more.
The buttons are drawed on the right side of the screen, descending from button 0 at y 0 to button 5 at y 550.
Each button is 100x100px in size and is drawed 10px below the previous one.

screen is the pygame surface to draw on, respectively the screen variable from your Apps update function.
text is the text do be shown on the button. It can have max 3 characters, else it won't fit into the box.
ypos is the button INDEX where the button should be drawed. It is multiplicated with 110.
(e.g. 0 is at y-pixel 0, 1 is at 110, 2 is at 220, etc.)
forecol and backcol are the foreground color and the background color for this button. Can be ommitted, it's fgcol and bgcol then.

def isOverAppButton(mx, my, checkForStartMouse)

Checks, if mx and my are over an App button.
Returns the index of the button where the mouse is over.

mx and my are usually the mouse position.
If checkForStartMouse is True, it will check if UITools.startMouseX and UITools.startMouseY are over the button, too.
If not, it will return -1, even if mx and my are over the button.
This is used to not accidentally use the button if one moves over the display (from somewhere else than the button position) and releases over the button.

Note that you can check the buttons even if they are NOT drawn.

mx, my are the position variables to be checked. Usually set to UITools.mousex and UITools.mousey.
checkForStartMouse is a flag. Default is True. When True, it checks, if UITools.startMouseX and UITools.startMouseY are on the button, too, and returns -1 if not.

---

INTERNAL USED STUFF

This is only here for reference. DO NOT USE, it's used by the system itself.

menuFont

pygame font
The pygame font variable with the system font in 32px size. Will be initialized in the UITools.initialize function.
This font is used by the drawText function.

releaseMsgOnTouch

True or False
If this is True, the global message will be hidden when the user touches the display FIRST, not when it is released.
The App will continue directly and interact with the touched display.
Set with UITools.showMessage.

globalmessage_middle, globalmessage_upper, globalmessage_lower

The text which is shown on the global message.
Set with UITools.showMessage.

def initialize()

Initializes the UITools.
Creates and sets the menuFont variable.
Called in APP_BASE.initialize().

def mouseIsOverAskButton(mx, my)

Returns 1 if mx, my are over the left (Yes) button of the ask-message-window,
0 if mx, my are over the right (Cancel) button and
-1 if mx, my are not over a button of the ask-message-window at all.

mx, my are usually the actual mouse position (ui.mousex and ui.mousey)

def __ getMousePosition()

Sets UITools.mousex and UITools.mousey to the actual mouse position.
Called in APP_BASE.update().

def __ drawMessage(screen)

Draws the global message.
Also draws the ask-message-window.
Called in APP_BASE.update when UITools.showMsg is True.

---

You have now learned all you have to learn to create and use your own App.
If you want to have a deeper look into the system, have a look into [APP_BASE]

If there is need for another main menu App, you can use [APP_MENU] as template.
But why? Just use [APP_MENU] for itself as described in the [Complex Main Example] and everything works fine.

Go back [Home] if you want to have a look into the other Apps provided here.