Add theme options to place button images on button surface relative to button

[Ztaoxx]

Describe the bug
I'm trying to draw a image on a button with .image or .set_image attributes but they neither works, with .image i have TypeError:
TypeError: 'pygame.Surface' object is not callable

To Reproduce
Steps to reproduce the behaviour:

1. Create a button
2. Draw a button on a screen
3. Set a Image

Platform and software (please complete the following information):

• OS: Windows 10
• Pygame GUI version Newest One
• Pygame version Newest One

Additional context
Code:
self.draw = pygame_gui.elements.UIButton(pygame.Rect((self.x, self.y), (150, 40)), self.text, self.manager,
None, self.text_tip)
self.draw.set_image(screen,'LVLUP.bmp')
or:
self.draw = pygame_gui.elements.UIButton(pygame.Rect((self.x, self.y), (150, 40)), self.text, self.manager,
None, self.text_tip)
self.draw.image(screen,'LVLUP.bmp')

[MyreMylar]

OK, that's not the right way to add an image to a button.

There are two approaches:

1. For a static image (i.e. one the button has on it all the time in the button state) use the theming file to add an image, you can add an individual image to a specific button with an object_id theming block or you can add the same image to a group of buttons with class_ids, or all buttons with the 'button' element ID. There is some documentation on the image syntax for buttons here:

https://pygame-gui.readthedocs.io/en/latest/theme_reference/theme_button.html#images

2. For dynamic images - say you want to add something to a button after some event in your game, but it's not always there. This is more tricky because lots of things can cause the button's image to be redrawn, but there are a few sub steps to try:

   1. load your image into a surface - generally you want to do this only once as loading data is slow, that's why the static images are setup how they are. You do this with something like loaded_image_surface = pygame.image.load('file_path_here.bmp').
   2. Buttons have multiple states. When you hover over a button, click it, or disable it switches to a different image surface. To make your dynamic image stick around you ideally want to paste it onto whichever states you want it to be on. All these surfaces can be found at button.drawable_shape.states['state_id_here'].surface with the normal state id being 'normal'.
   3. Once you have the state surface or surfaces you want, you'll need to blit your loaded dynamic image onto it so you don't lose the original surface data. e.g. button.drawable_shape.states['normal'].surface.blit(loaded_image_surface, (0,0))
   4. If you've added your image to the currently active button state you'll also want to let the button know by setting button.drawable_shape.active_state.has_fresh_surface = True

I think that should work for most cases, but if you redraw the button for any reason you'll have to reset the dynamic image on it and it takes a few frames to load all the button states into memory so you might want have to handle that.

Likely the easier approach is to stick to static images for most scenarios and just switch the button out to an identical one with the image on it if you want to add an image to it dynamically.

Currently there is no extra support for more than one image on a button, aligning images on a button or any sort of animated series of images on a button. It's possible they might be added in the future but are not planned for the immediate future.

[Ztaoxx]

Got this error
UserWarning: Unable to load resource with path: C:\Users\Akush\Desktop\PythonProjects\untitled\ClickerGameProject
warnings.warn(str(loading_error))

[Ztaoxx]

here is my theme.json:

{
"button":
{
"images":
{
"normal_image": {
"path":"C:\Users\Akush\Desktop\PythonProjects\untitled\ClickerGameProject",
"resource":"LVLUP.bmp"
}
}
}
}

[MyreMylar]

Usually we use relative paths from the working directory, so if LVLUP.bmp is in the same directory as your script then you just need:

{
    "button":
    {
        "images":
        {
             "normal_image": {
                 "path": "LVLUP.bmp"
             }
        }
    }
}

[xlla]

How to specifical image postion on a UIButton, if image rect is smaller than button's.
To implement a vivid button with an icon a head the text.

[MyreMylar]

Right now there is no way to set the position in the theming data, images are just always centred. It's something I would like to change eventually, along with support for multiple images on elements.

The easiest approach right now, assuming the button is statically sized, would just be to pad the image itself with transparent pixels so it appears where you want in the final button.

[xlla]

I am using icon for uidropdown in this way, and have to care for all states like expaned/closed/selected/normal...