Using and Creating Common UI Components - skytreader/PyGame-Objects GitHub Wiki

Note: Bare bones documentation because this feature will still change heavily, to make things more convenient. Right now, only a Button object (with a click event) is provided so you might find that this document leans heavily towards that.

Using Common UI Components

  1. In the setup method of your GameScreen object instantiate the CommonUI components you will be using. The appropriate event handlers should also be set from here using the set_event_handler method of your CommonUI component.
  2. Add the CommonUI component to the ui_elements set of your GameScreen object. This step is necessary so that the event handlers associated with CommonUI components can be registered by GameLoopEvents, which handles all event-related things. However, this is inconvenient and we want to eliminate this.
  3. Draw the component in the appropriate GameScreen method (either draw_screen or draw_unchanging).

Writing Event Handlers

Event handlers for CommonUI components follow the same rules as event handlers for GameLoopEvents. However, unlike GameLoopEvents, CommonUI components should only respond to events explicitly directed to them; a button will not respond to all clicks, only those made inside its area.

To facilitate this, GameScreen provides an _is_drawable_clicked method for Drawable components (which CommonUI is a subclass of), which will return True if a click event happened within the bounds of the Drawable, and False otherwise.

Creating New Common UI Components

Common UI components are just drawables with a declaration of intent: that the user can interact with them by a predefined set of events. So aside from determining the necessary properties to define it as a Drawable, you also need to take these interactions into account.

These interactions are noted in the constructor of your Common UI component: using the _event_handlers dictionary property of CommonUI objects, set the events to be handled in your constructor. When users of your component attempt to call set_event_handler on an event that was not specified in _event_handlers to begin with, an UnsupportedEventException will be raised.