py-sdl2 / doc / modules / sdl2ext_gui.rst

User interface elements

User interface elements within :mod:`sdl2.ext` are simple :class:`Sprite` objects, which are enhanced by certain input hooks; as such, they are not classes on their own, but implemented as mixins. The user input itself is handled by an :class:`UIProcessor` object, which takes care of delegating input events, such as mouse movements, clicks and keyboard input, to the correct UI element.

Depending on the event type (e.g. pressing a mouse button), the UIProcessor will execute its matching method (e.g. mousedown()) with only those UI elements, which support the event type.

images/uiprocessing.png

UI element types

Every :class:`sdl2.ext` UI element is a simple :class:`Sprite` object, to which additional attributes and methods are bound.

Every UI element features the following attributes

element.uitype

The uitype attribute can have one of the following values, identifying the UI element:

  • BUTTON - a UI element, which can react on mouse input
  • CHECKBUTTON - as BUTTON, but it retains its state on clicks
  • TEXTENTRY - a UI element that reacts on keyboard input

element.events

A dictionary containing the SDL2 event mappings. Each supported SDL2 event (e.g. SDL_MOUSEMOTION) is associated with a bound :class:`EventHandler` acting as callback for user code (e.g. mousemotion()).

Depending on the exact type of the element, it will feature additional methods and attributes explained below.

Button elements

BUTTON UI elements feature a state attribute, which can be one of the following values.

state Description
RELEASED Indicates that the UI element is not pressed.
HOVERED Indicates that the mouse cursor is currently hovering the UI element.
PRESSED Indicates that a mouse button is pressed on the UI element.

BUTTON UI elements react with the following event handlers on events:

button.motion(event : sdl2.events.SDL_Event)

An :class:`EventHandler` that is invoked, if the mouse moves around while being over the BUTTON.

button.pressed(event : sdl2.events.SDL_Event)

An :class:`EventHandler` that is invoked, if a mouse button is pressed on the BUTTON.

button.released(event : sdl2.events.SDL_Event)

An :class:`EventHandler` that is invoked, if a mouse button is released on the BUTTON.

button.click(event : sdl2.events.SDL_Event)

An :class:`EventHandler` that is invoked, if a mouse button is pressed and released on the BUTTON.

Besides the BUTTON a special CHECKBUTTON UI element type exists, which enhances the BUTTON bindings by an additional checked attribute. The checked attribute switches its status (False to True and True to False) every time the UI element is clicked.

Text input elements

TEXTENTRY elements react on text input, once they are activated. Text being input, once a TEXTENTRY has been activated, is stored in its text attribute.

The TEXTENTRY reacts with the following event handlers on events:

textentry.motion(event : sdl2.events.SDL_Event)

An :class:`EventHandler` that is invoked, if the mouse moves around while being over the TEXTENTRY.

textentry.pressed(event : sdl2.events.SDL_Event)

An :class:`EventHandler` that is invoked, if a mouse button is pressed on the TEXTENTRY.

textentry.released(event : sdl2.events.SDL_Event)

An :class:`EventHandler` that is invoked, if a mouse button is released on the TEXTENTRY.

textentry.keydown(event : sdl2.events.SDL_Event)

An :class:`EventHandler` that is invoked on pressing a key.

textentry.keyup(event : sdl2.events.SDL_Event)

An :class:`EventHandler` that is invoked on releasing a key.

textentry.input(event : sdl2.events.SDL_Event)

An :class:`EventHandler` that is invoked on text input events. Text input events are automatically created, once the :class:`UIProcessor` activates a TEXTENTRY UI element.

textentry.editing(event : sdl2.events.SDL_Event)

An :class:`EventHandler` that is invoked on text editing events. Text editing events are automatically created, once the :class:`UIProcessor` activates a TEXTENTRY UI element.

Text editing events are however only raised, if an IME system is involved, which combines glyphs and symbols to characters or word fragments.

API

A processing system for user interface elements and events.

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.