Package org.polyfrost.polyui

Class PolyUI

  • All Implemented Interfaces:
    
public final class PolyUI

    PolyUI is a declarative UI framework developed for, and by Polyfrost.

    It is designed to be lightweight, fast, extensible and easy to use, while still being very powerful. Make sure to check out the examples for more information.

    PolyUI is split into two parts, being PolyUI and its logic, and it's accompanying Renderer implementation. This allows us to have PolyUI in many places, including inside Minecraft! It is declarative, meaning that you don't have to worry about the logic of the UI, just the layout and the components.

    PolyUI has the policy of 'render what you need ONLY WHEN you need it'. Most of the time, PolyUI will be drawing frame buffers to the screen instead of drawing directly to the screen, as long as they are suitably complex for it to be worth it; or not drawing at all! This allows us to have a very fast rendering pipeline, and allows us to have a lot of components on screen at once, without a performance hit.

    Rendering can be requested by components, and if so, it will be rendered during the next frame. This should only be requested if it is necessary, for example to do an animation or something.

    During a render cycle, PolyUI will systematically go through every layout, and render it to its framebuffer or to the screen. Each layout will then render its components and child layouts, and so on. Rendering happens in three steps:

    • preRender: This will do pre-rendering logic, such as setting up transformations, updating animations, and more.

    • render: This is where the actual rendering happens.

    • postRender: This will do post-rendering logic, such as cleaning up transformations.

    Check out some components to see how this works.

    Components are the interactive parts of the UI, such as buttons, text fields, etc.

    Interactions are driven by events, which thanks to Kotlin's inlining are a zero-overhead way of distributing events, such as mouse clicks, or key presses.

    PolyUI also supports a variety of animations and transitions, which can be used to make your UI more dynamic, along with dynamically adding and removing components.

    • Method Detail

      • getColors

         final Colors getColors()

        Colors attached to this PolyUI instance. This contains all the colors needed for the UI.

        Note that changing this value can be an expensive operation while the UI is running, as it has to update all the components.

        Since:

        0.17.0

      • setColors

         final Unit setColors(Colors colors)

        Colors attached to this PolyUI instance. This contains all the colors needed for the UI.

        Note that changing this value can be an expensive operation while the UI is running, as it has to update all the components.

        Since:

        0.17.0

      • getFonts

         final FontFamily getFonts()

        Fonts attached to this PolyUI instance. This contains all the fonts needed for the UI.

        Note that changing this value can be an expensive operation while the UI is running, as it has to update all the components.

        Since:

        0.22.0

      • setFonts

         final Unit setFonts(FontFamily fonts)

        Fonts attached to this PolyUI instance. This contains all the fonts needed for the UI.

        Note that changing this value can be an expensive operation while the UI is running, as it has to update all the components.

        Since:

        0.22.0

      • getMonospaceFont

         final Font getMonospaceFont()

        Monospace font attached to this PolyUI instance. This is used for debugging and other purposes.

      • setMonospaceFont

         final Unit setMonospaceFont(Font monospaceFont)

        Monospace font attached to this PolyUI instance. This is used for debugging and other purposes.

      • getWindow

         final Window getWindow()

        The window this polyUI was opened with.

        Since v1.1.3, a window is not required to be set. If it is not set, the clipboard, cursor and render hooks will not work.

        Since:

        0.18.3

      • setWindow

         final Unit setWindow(Window window)

        The window this polyUI was opened with.

        Since v1.1.3, a window is not required to be set. If it is not set, the clipboard, cursor and render hooks will not work.

        Since:

        0.18.3

      • getMaster

         final Drawable getMaster()

        This is the root layout of the UI. It is the parent of all other layouts.

      • getDrew

         final Boolean getDrew()

        weather this PolyUI instance drew on this frame.

        You can use this value to implement a 'render pausing' function, if you are using a dual-buffered rendering implementation (like OpenGL/GLFW) by enabling this flag:

        if (polyUI.drew) glfwSwapBuffers(handle)

        This is very handy as it will drastically reduce required system resources. If you are looking for more efficiency optimizations, see the settings for max fps and framebuffer settings.

      • getCursor

         final Cursor getCursor()

        The cursor currently being displayed.

        Since:

        0.18.4

      • getDelta

         final Long getDelta()

        the time since the last frame, in nanoseconds. It is used internally a lot for animations, etc.

      • every

         final Clock.Executor every(Long nanos, Integer repeats, Function0<Unit> func)

        add a function that is called every nanos nanoseconds.

        Note that the requested time is not guaranteed to be accurate, especially on small values (less than 5ms). It will be executed at the end of the next frame. The executor will overshoot much more often that it will undershoot.

        From testing, a requested time of 1 second is about 99.3% accurate. (+7ms, -0.01ms)

      • removeExecutor

         final Boolean removeExecutor(Clock.Executor executor)

        Remove a clock-based executor from this PolyUI instance.

        Returns:

        true if the executor was successfully removed.

        Since:

        1.0.5

      • focus

         final Boolean focus(Drawable focusable)

        Sets the focus to the specified focusable element.

        Parameters:
        focusable - the element to set focus on
        Returns:

        true if focus was successfully set, false if the provided focusable is already focused

      • getKeyName

         final String getKeyName(Integer key)

        Return the key name for the given key code, or "Unknown" if the key is not mapped / no window is present.

      • debugString

         final String debugString()

        return a string of this PolyUI instance's components and children in a list, like this:

        PolyUI(800.0 x 800.0) with 0 components and 2 layouts:
  PixelLayout@5bcab519 [Draggable](20.0x570.0, 540.0 x 150.0)
	 Text@6eebc39e(40.0x570.0, 520.0x32.0)
	 Block@2f686d1f(40.0x600.0, 120.0x120.0)
	 Block@7085bdee(220.0x600.0, 120.0x120.0)
	 Image@6fd02e5(400.0x600.0, 120.0x120.0 (auto))
	 ... 2 more
  FlexLayout@73846619 [Scrollable](20.0x30.0, 693.73267 x 409.47168, buffered, needsRedraw)
	 Block@32e6e9c3(20.0x30.0, 61.111263x42.21167)
	 Block@5056dfcb(86.11127x30.0, 40.909004x76.32132)
	 Block@6574b225(132.02026x30.0, 52.75415x52.59597)
	 Block@2669b199(189.77441x30.0, 76.59671x45.275665)

      • timed

         final Long timed(String msg, Function0<Unit> block)

        Time the block and return how long it took, as well as logging with the msg if debug is active.

        Since:

        0.18.5

      • cleanup

         final Unit cleanup()

        cleanup the polyUI instance. This will delete all resources, and render this instance unusable.

      • timed

         final static Long timed(Boolean log, String msg, Function0<Unit> block)

        Time the block and return how long it took, as well as logging with the msg if log is true.

        Since:

        1.1.61