Recent changes to UITools

UITools modified by Benedict Jäggi

Benedict Jäggi — Wed, 20 Mar 2024 04:16:36 -0000

--- v17
+++ v18
@@ -6,8 +6,12 @@
 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.
+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()`.
@@ -38,6 +42,19 @@
 -------

 ##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.

@@ -45,6 +62,17 @@
 `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.
@@ -61,36 +89,11 @@
 `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 drawAppButton(screen, text, ypos)
-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.)
-
 ###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 isOverAppButton(y, mx, my, checkForStartMouse)
-Checks, if `mx` and `my` are over the App button with index `y`.
-Returns `True` or `False`.
-`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 `False`, 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.
-
-`y` is the button index of the button to be checked. Ranges from 0 - which is usually the close button - to 5 or 6, depending on your display size.
-`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 `False` if not.

 ###def isOverCloseButton(x, y, checkForStartMouse)
 A short to `isOverAppButton`. It checks for button **0**.
@@ -99,7 +102,36 @@
 `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.

@@ -123,12 +155,20 @@
 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`.

 -------

UITools modified by Benedict Jäggi

Benedict Jäggi — Fri, 08 Mar 2024 21:45:31 -0000

--- v16
+++ v17
@@ -1,3 +1,4 @@
+[TOC]
 #UITools.py
 Go back [Home]

UITools modified by Benedict Jäggi

Benedict Jäggi — Fri, 08 Mar 2024 20:25:53 -0000

--- v15
+++ v16
@@ -137,4 +137,4 @@
 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 look into the other Apps provided here.
+Go back [Home] if you want to have a look into the other Apps provided here.

UITools modified by Benedict Jäggi

Benedict Jäggi — Fri, 08 Mar 2024 20:25:01 -0000

--- v14
+++ v15
@@ -1,4 +1,6 @@
 #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.

@@ -127,3 +129,12 @@
 ###def __ drawMessage(screen)
 Draws the global message.
 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 look into the other Apps provided here.

UITools modified by Benedict Jäggi

Benedict Jäggi — Fri, 08 Mar 2024 20:20:46 -0000

--- v13
+++ v14
@@ -30,7 +30,7 @@
 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.
+Internal used variables are described at the end of this page.

 -------

UITools modified by Benedict Jäggi

Benedict Jäggi — Fri, 08 Mar 2024 20:20:04 -0000

--- v12
+++ v13
@@ -98,7 +98,7 @@

 --------
 ## INTERNAL USED STUFF
-This is only here for reference. DO NOT USE, it's used by the system.
+This is only here for reference. **DO NOT USE**, it's used by the system itself.

 ###menuFont
 `pygame font`

UITools modified by Benedict Jäggi

Benedict Jäggi — Fri, 08 Mar 2024 20:19:21 -0000

--- v11
+++ v12
@@ -95,3 +95,35 @@

 `x`, `y` are the position to be checked.
 `checkForStartMouse` is the checkForStartMouse flag passed to isOverAppButton. Look there for reference.
+
+--------
+## INTERNAL USED STUFF
+This is only here for reference. DO NOT USE, it's used by the system.
+
+###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 __ getMousePosition()
+Sets `UITools.mousex` and `UITools.mousey` to the actual mouse position.
+Called in `APP_BASE.update()`.
+
+###def __ drawMessage(screen)
+Draws the global message.
+Called in `APP_BASE.update` when `UITools.showMsg` is `True`.

UITools modified by Benedict Jäggi

Benedict Jäggi — Fri, 08 Mar 2024 20:07:59 -0000

--- v10
+++ v11
@@ -45,7 +45,7 @@

 ###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.
+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.

UITools modified by Benedict Jäggi

Benedict Jäggi — Fri, 08 Mar 2024 20:06:46 -0000

--- v9
+++ v10
@@ -41,9 +41,7 @@
 `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.)
+`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 drawText(screen, text, centerx, centery, fgcol, bgcol)
 Draws a text at the specified center position with the given colors.

UITools modified by Benedict Jäggi

Benedict Jäggi — Fri, 08 Mar 2024 20:05:44 -0000

--- v8
+++ v9
@@ -35,6 +35,16 @@
 -------

 ##Functions
+###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 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.
@@ -43,7 +53,7 @@

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

-`screen` is the pygame surface to be drawed on. If you want to draw directly to the display, use the `screen` variable from your Apps `update` function.
+`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`.
@@ -55,7 +65,7 @@
 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.
+`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.)
@@ -63,6 +73,9 @@
 ###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 isOverAppButton(y, mx, my, checkForStartMouse)
 Checks, if `mx` and `my` are over the App button with index `y`.
@@ -72,6 +85,15 @@
 If not, it will return `False`, 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.
+
 `y` is the button index of the button to be checked. Ranges from 0 - which is usually the close button - to 5 or 6, depending on your display size.
 `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 `False` if not.
+
+###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.