Fixed some more docs and added some examples

Author: trymbf

__pycache__/pygameui.cpython-313.pyc

@@ -51,8 +51,3 @@ centered: bool = False
 - `font_size`: Size of the text font
 - `font_family`: Font family for the text
 - `centered`: If True, the button is centered on the provided position
-
-### Button States
-- Normal: Default appearance
-- Hover: When mouse is over the button
-- Click: When button is being pressed

assets/gifs/add_pygameui.gif

@@ -1,6 +1,7 @@
 # Getting Started with PygameUI
 
 ## Installation
+
 Ensure you have Python and PyGame installed.
 
 Start by downloading the PyGameUI python file from the [releases page](https://github.com/trymbf/pygameui/releases).
@@ -33,9 +34,36 @@ while running:
         if event.type == pygame.QUIT:
             running = False
 
-    # Update and draw
+    # Reset screen
     screen.fill(background_color)
+  
+    # Update element, moves, checks actions etc
     ui_element.update()
+
+    # Draw element on screen
     ui_element.draw(screen)
+
+    # Update pygame display
     pygame.display.flip()
 ```
+
+To add more UI elements, simply create more instances of the `Element` class or its subclasses (like `Button`, `Text`, etc.) and follow the same pattern.
+
+## Example create text
+First create a text object:
+```python
+my_text = pygameui.Text(
+    text="Hello World", 
+    position=(100, 100), 
+    font_size=30, 
+    color=(255, 255, 255)
+    )
+```
+
+And then in the main loop, you would call:
+```python
+my_text.update()
+my_text.draw(screen)
+```
+
+And that's it! You now have a text object on your screen. You can customize the text by changing its properties like `font_size`, `color`, and `position`. [See the Text class documentation for more details.](components/text.md)

assets/imgs/avatar.jpeg

@@ -0,0 +1,102 @@
+"""
+Dashboard UI using pygameui
+This code creates a simple dashboard UI using the pygameui library.
+It includes a user profile section, a main content area with statistics,
+and a notification area.
+"""
+
+import pygame
+import pygameui
+
+pygame.init()
+screen = pygame.display.set_mode((800, 600))
+pygame.display.set_caption("PyGameUI Dashboard")
+
+# Define colors
+DARK_BG = (30, 30, 40)
+LIGHT_BG = (45, 45, 60)
+ACCENT = (86, 140, 235)
+ACCENT_HOVER = (120, 170, 255)
+TEXT_COLOR = (240, 240, 245)
+ERROR_COLOR = (235, 86, 86)
+SUCCESS_COLOR = (86, 235, 120)
+
+# Create UI elements
+header = pygameui.Text((400, 50), "Dashboard", TEXT_COLOR, font_size=40, centered=True)
+
+# User profile section - using Element instead of Panel which doesn't exist
+profile_bg = pygameui.Element((20, 100), 250, 480, LIGHT_BG, border_radius=10)
+# Use proper Image parameters according to implementation
+try:
+    avatar = pygameui.Image((145, 180), "assets/imgs/avatar.jpeg", 
+                         width=150, height=150, centered=True)
+except Exception as e:
+    # Fallback if image can't be loaded
+    pass
+
+username_display = pygameui.Text((145, 280), "trymbf", TEXT_COLOR, font_size=24, centered=True)
+status = pygameui.Text((145, 310), "Online", SUCCESS_COLOR, font_size=18, centered=True)
+logout_btn = pygameui.Button((145, 530), 200, 40, 4, "Logout", ACCENT, ACCENT_HOVER, text_color=TEXT_COLOR, centered=True)
+
+# Main content area - using Element instead of Panel
+content_bg = pygameui.Element((290, 100), 490, 480, LIGHT_BG, border_radius=10)
+welcome_text = pygameui.Text((535, 140), "Welcome back!", TEXT_COLOR, font_size=28, centered=True)
+
+# Stats section - remove ProgressBar and use Element instead
+stats_title = pygameui.Text((535, 200), "Your Statistics", TEXT_COLOR, font_size=22, centered=True)
+stat1_bg = pygameui.Element((535, 250), 400, 30, (100, 100, 120), centered=True)
+stat1_fill = pygameui.Element((535 - (400-300)/2, 250), 300, 30, ACCENT, centered=True) # 75% filled
+stat1_label = pygameui.Text((535, 280), "Projects Completed: 75%", TEXT_COLOR, font_size=16, centered=True)
+stat2_bg = pygameui.Element((535, 330), 400, 30, (100, 100, 120), centered=True)
+stat2_fill = pygameui.Element((535 - (400-160)/2, 330), 160, 30, ACCENT, centered=True) # 40% filled
+stat2_label = pygameui.Text((535, 360), "Tasks Finished: 40%", TEXT_COLOR, font_size=16, centered=True)
+
+# Notification area
+notif_title = pygameui.Text((535, 410), "Recent Notifications", TEXT_COLOR, font_size=22, centered=True)
+notif1 = pygameui.Text((535, 450), "New message from Alex", TEXT_COLOR, font_size=16, centered=True)
+notif2 = pygameui.Text((535, 480), "Project deadline tomorrow", ERROR_COLOR, font_size=16, centered=True)
+clear_notif_btn = pygameui.Button((535, 530), 200, 40, 4, "Clear All", ACCENT, ACCENT_HOVER, text_color=TEXT_COLOR, centered=True)
+
+# Put all elements in a list for easy updating and drawing
+elements = [
+    header, profile_bg, username_display, status, logout_btn,
+    content_bg, welcome_text, stats_title, stat1_bg, stat1_fill, stat1_label, 
+    stat2_bg, stat2_fill, stat2_label, notif_title, notif1, notif2, clear_notif_btn
+]
+
+# Try to add avatar if it was loaded
+try:
+    if avatar:
+        elements.append(avatar)
+except:
+    pass
+
+run = True
+while run:
+    events = pygame.event.get()
+    
+    # Handle events
+    for event in events:
+        if event.type == pygame.QUIT:
+            run = False
+
+    if logout_btn.was_clicked():
+        status.change_text("Logging out...")
+        status.change_text_color(ERROR_COLOR)
+
+    if clear_notif_btn.was_clicked():
+        notif1.change_text("No new notifications")
+        notif2.change_text("")
+
+    # Update elements - the update method doesn't take parameters
+    for element in elements:
+        element.update()
+
+    # Draw everything
+    screen.fill(DARK_BG)
+    
+    for element in elements:
+        element.draw(screen)
+
+    # Update screen
+    pygame.display.flip()

docs/components/button.md

@@ -0,0 +1,223 @@
+import pygame
+import sys
+import pygameui
+import random
+
+# Initialize pygame
+pygame.init()
+screen = pygame.display.set_mode((800, 600))
+pygame.display.set_caption("PyGameUI Game Interface Example")
+
+# Define colors
+BG_COLOR = (15, 20, 30)
+PANEL_COLOR = (30, 35, 45)
+DARK_PANEL = (25, 25, 35)
+ACCENT_COLOR = (86, 140, 235)
+ACCENT_HOVER = (120, 170, 255)
+TEXT_COLOR = (230, 230, 240)
+HEALTH_COLOR = (235, 86, 86)
+MANA_COLOR = (86, 110, 235)
+XP_COLOR = (86, 235, 120)
+GOLD_COLOR = (235, 200, 86)
+
+# Game state
+health = 75
+max_health = 100
+mana = 50
+max_mana = 100
+experience = 35
+max_experience = 100
+gold = 1250
+player_name = "Hero"
+level = 5
+
+# Create UI elements
+# Main game panel (simulating game window)
+game_panel = pygameui.Element((400, 250), 780, 390, DARK_PANEL, border_radius=10, centered=True)
+game_title = pygameui.Text((400, 250), "GAME AREA", (100, 100, 130), font_size=72, centered=True)
+
+# Top bar - player info
+top_panel = pygameui.Element((400, 20), 780, 50, PANEL_COLOR, border_radius=8, centered=True)
+player_name_text = pygameui.Text((70, 20), player_name, TEXT_COLOR, font_size=22, centered=True)
+level_text = pygameui.Text((140, 20), f"Level {level}", GOLD_COLOR, font_size=20, centered=True)
+gold_text = pygameui.Text((700, 20), f"Gold: {gold}", GOLD_COLOR, font_size=20, centered=True)
+
+# Bottom bar - health, mana, experience
+bottom_panel = pygameui.Element((400, 570), 780, 70, PANEL_COLOR, border_radius=8, centered=True)
+
+# Health bar
+health_label = pygameui.Text((70, 550), "HP", TEXT_COLOR, font_size=18, centered=True)
+health_bg = pygameui.Element((200, 550), 200, 20, (60, 40, 40), centered=True)
+health_bar = pygameui.Element((200 - (200-(health/max_health*200))/2, 550), health/max_health*200, 20, HEALTH_COLOR, centered=True)
+health_text = pygameui.Text((200, 570), f"{health}/{max_health}", TEXT_COLOR, font_size=14, centered=True)
+
+# Mana bar
+mana_label = pygameui.Text((350, 550), "MP", TEXT_COLOR, font_size=18, centered=True)
+mana_bg = pygameui.Element((480, 550), 200, 20, (40, 40, 60), centered=True)
+mana_bar = pygameui.Element((480 - (200-(mana/max_mana*200))/2, 550), mana/max_mana*200, 20, MANA_COLOR, centered=True)
+mana_text = pygameui.Text((480, 570), f"{mana}/{max_mana}", TEXT_COLOR, font_size=14, centered=True)
+
+# Experience bar
+xp_bg = pygameui.Element((400, 595), 600, 15, (40, 60, 40), centered=True)
+xp_bar = pygameui.Element((400 - (600-(experience/max_experience*600))/2, 595), experience/max_experience*600, 15, XP_COLOR, centered=True)
+xp_text = pygameui.Text((730, 595), f"XP: {experience}/{max_experience}", TEXT_COLOR, font_size=14, centered=True)
+
+# Action buttons
+attack_btn = pygameui.Button((690, 550), 120, 40, 5, "Attack", HEALTH_COLOR, (255, 100, 100), text_color=TEXT_COLOR, centered=True)
+spell_btn = pygameui.Button((690, 500), 120, 40, 5, "Spell", MANA_COLOR, (100, 140, 255), text_color=TEXT_COLOR, centered=True)
+item_btn = pygameui.Button((560, 550), 120, 40, 5, "Item", GOLD_COLOR, (255, 220, 100), text_color=TEXT_COLOR, centered=True)
+run_btn = pygameui.Button((560, 500), 120, 40, 5, "Run", (150, 150, 150), (200, 200, 200), text_color=TEXT_COLOR, centered=True)
+
+# Action log
+log_panel = pygameui.Element((110, 500), 200, 140, DARK_PANEL, border_radius=5, centered=True)
+log_title = pygameui.Text((110, 445), "Combat Log", TEXT_COLOR, font_size=16, centered=True)
+log_entry1 = pygameui.Text((110, 470), "Battle started", TEXT_COLOR, font_size=12, centered=True)
+log_entry2 = pygameui.Text((110, 490), "Enemy appeared", TEXT_COLOR, font_size=12, centered=True)
+log_entry3 = pygameui.Text((110, 510), "Waiting for action...", TEXT_COLOR, font_size=12, centered=True)
+
+# Group all elements
+elements = [
+    game_panel, game_title,
+    top_panel, player_name_text, level_text, gold_text,
+    bottom_panel, 
+    health_label, health_bg, health_bar, health_text,
+    mana_label, mana_bg, mana_bar, mana_text,
+    xp_bg, xp_bar, xp_text,
+    attack_btn, spell_btn, item_btn, run_btn,
+    log_panel, log_title, log_entry1, log_entry2, log_entry3
+]
+
+# Action functions
+def perform_attack():
+    global health, mana, gold, experience
+    
+    # Update combat log
+    log_entry3.change_text(log_entry2.content)
+    log_entry2.change_text(log_entry1.content)
+    log_entry1.change_text("You attack! Damage dealt!")
+    
+    # Simulate battle effects
+    health -= random.randint(5, 15)
+    health = max(0, health)
+    mana += random.randint(5, 10)
+    mana = min(mana, max_mana)
+    experience += random.randint(3, 8)
+    gold += random.randint(10, 30)
+    
+    # Update UI
+    update_stats()
+
+def cast_spell():
+    global health, mana, gold, experience
+    
+    if mana < 15:
+        log_entry3.change_text(log_entry2.content)
+        log_entry2.change_text(log_entry1.content)
+        log_entry1.change_text("Not enough mana!")
+        return
+    
+    # Update combat log
+    log_entry3.change_text(log_entry2.content)
+    log_entry2.change_text(log_entry1.content)
+    log_entry1.change_text("You cast a spell! Critical hit!")
+    
+    # Simulate battle effects
+    health += random.randint(5, 15)
+    health = min(health, max_health)
+    mana -= random.randint(10, 20)
+    mana = max(0, mana)
+    experience += random.randint(5, 12)
+    gold += random.randint(15, 40)
+    
+    # Update UI
+    update_stats()
+
+def use_item():
+    global health, mana, gold
+    
+    if gold < 50:
+        log_entry3.change_text(log_entry2.content)
+        log_entry2.change_text(log_entry1.content)
+        log_entry1.change_text("Not enough gold!")
+        return
+    
+    # Update combat log
+    log_entry3.change_text(log_entry2.content)
+    log_entry2.change_text(log_entry1.content)
+    log_entry1.change_text("You used a health potion!")
+    
+    # Simulate item use
+    health += random.randint(20, 35)
+    health = min(health, max_health)
+    gold -= 50
+    
+    # Update UI
+    update_stats()
+
+def attempt_run():
+    # Update combat log
+    log_entry3.change_text(log_entry2.content)
+    log_entry2.change_text(log_entry1.content)
+    
+    if random.random() > 0.5:
+        log_entry1.change_text("You escaped successfully!")
+    else:
+        log_entry1.change_text("Failed to escape!")
+        # Take damage for trying to run
+        global health
+        health -= random.randint(10, 20)
+        health = max(0, health)
+        update_stats()
+
+def update_stats():
+    # Update text elements
+    health_text.change_text(f"{health}/{max_health}")
+    mana_text.change_text(f"{mana}/{max_mana}")
+    xp_text.change_text(f"XP: {experience}/{max_experience}")
+    gold_text.change_text(f"Gold: {gold}")
+    
+    # Update bar elements - adjust width and position
+    health_bar.rect.width = (health/max_health) * 200
+    health_bar.rect.centerx = 200 - (200-(health/max_health*200))/2
+    
+    mana_bar.rect.width = (mana/max_mana) * 200
+    mana_bar.rect.centerx = 480 - (200-(mana/max_mana*200))/2
+    
+    xp_bar.rect.width = (experience/max_experience) * 600
+    xp_bar.rect.centerx = 400 - (600-(experience/max_experience*600))/2
+
+# Main game loop
+running = True
+while running:
+    events = pygame.event.get()
+    
+    # Handle events
+    for event in events:
+        if event.type == pygame.QUIT:
+            running = False
+        
+        # Handle button clicks
+        if event.type == pygame.MOUSEBUTTONDOWN:
+            if attack_btn.is_hovered():
+                perform_attack()
+            elif spell_btn.is_hovered():
+                cast_spell()
+            elif item_btn.is_hovered():
+                use_item()
+            elif run_btn.is_hovered():
+                attempt_run()
+    
+    # Update all elements
+    for element in elements:
+        element.update()
+    
+    # Draw everything
+    screen.fill(BG_COLOR)
+    for element in elements:
+        element.draw(screen)
+    
+    # Update display
+    pygame.display.flip()
+
+pygame.quit()
+sys.exit()