12 releases 12 tags

RSS feed

• 3.0.0 b25fda67c0

  Compare

  3.0.0 Stable

  abart27 released this 2025-10-25 22:40:13 +00:00 | 46 commits to main since this release

  Summary

  ugui 3.0.0 brings with it buffered scene processing and various flexibility
  improvements.

  Control logic is still executed immediately, but input processing and rendering are now done at the end of the frame. This has implications for certain use-cases, so make sure to read the "Breaking Changes" section.

  Scenes with overlapping controls are now handled correctly and control focus behaviour should be more consistent.

  New Stuff

  💡 Control metadata

  Controls now return a second value, the meta table (not to be confused with
  metatable).

  local pressed, meta = ugui.button({
      uid = 10,
      rectangle = {x = 120, y = 10, width = 100, height = 23},
      text = 'Hello, world!',
  })
  
  print(meta) -- prints: { signal_change = 0 }
  

  The meta table contains miscellaneous information about a control's state.

  The signal_change field makes it easier to detect changes in the return value
  of a control without relying solely on state diffing.

  For more information, consult the Meta type docs and ./demos/interaction_state.lua.

  ⚛️ ugui.control()

  You can now spawn controls of arbitrary types at runtime using ugui.control()

  Usage example:

  local result = ugui.control({
      uid = 1,
      ...
  }, 'button')
  
  local pressed = result.primary
  if pressed then
      print("Hello World!")
  end
  

  For more information, consult the ugui.control() docs.

  📋 Control Registry

  Control-specific code (with the exception of composite controls, such as
  spinner) is now located in the "ugui registry" instead of scattered across
  individual functions.

  Given that this is an implementation detail, it's irrelevant to library
  consumers.

  If you are writing a ugui extension, consult the ControlRegistry type
  definition for more information on how to integrate your own control with the
  registry.

  Breaking Changes

  ⌛ One Frame of Delay

  Return values of controls are now delayed by one frame.

  For instance, this manifests as a button returning true one frame after it
  was clicked, and not immediately.

  If you are experiencing state diffing issues (e.g. change detection based on
  control return values failing because of the delay) due to this change, consult
  the "Meta" section of the changelog.

  ✏️ Styler Overrides

  Overriding a specific control's rendering by overwriting a method in the
  standard_styler is no longer possible.

  To achieve this, utilize styler mixins instead. For more info, see the
  documentation for Control.styler_mixin.

  - local prev_font_name = ugui.standard_styler.params.font_name
  - ugui.standard_styler.params.font_name = "Comic Sans"
  - ugui.button(...)
  - ugui.standard_styler.params.font_name =  prev_font_name
  
  +ugui.button({
  +  ...
  +  styler_mixin = {
  +      font_name = "Comic Sans"
  +  }
  +)
  

  📦 Control UID Sharing

  Controls of different types may not share UIDs anymore.

  Placing a button with uid 5 means you are no longer allowed to place any
  non-button control with uid 5. This scenario will cause an error, so check the
  error message to find out what went wrong.

  ⬆️ Control UID Requirements Changing

  The spinner control now requires 4 UID slots instead of 3.

  👁️ Stricter Control Validation

  Controls are now validated more strictly, meaning that your script might error
  out when placing a control.

  The errors are pretty descriptive, so check that the data you pass into the
  controls matches what they want - you can check the respective control type for
  that.

  ❌ Layout System Removal

  The layout system has been removed - ugui.push, ugui.pop, ugui.stackpanel
  are no longer available.

  There is currently no alternative to the layout system, but it might be added
  back in future releases.

  Downloads

  • Source code (ZIP)
    0 downloads
  • Source code (TAR.GZ)
    0 downloads