ProgUI – the evolution of a programmers UI library.

I made the first version version of a simple framework for UI that would then come to be used in all my coming projects in one way or another.

In each project new features were added, bugs fixed and if I may say so myself it has proved to be quite successful. However some features were also dropped as they were not needed and design changes made them obsolete.

I have not been the only one to use it and I have gotten good feedback from those that did. The introduction can be a bit daunting as it is has a little bit unconventional design, but after a bit of initial support they have been able to be productive and have admitted that it was a helpful thing that made it easier for them to code up a working UI.

A slight problem, I felt, was that the code base was branching as it was developed in several projects at the same time. It was hard to keep track of updates, bugs and features. I found myself fixing the same bugs more than once.

That is the background to why I choose to make the final project of my own choosing to wrap up all this experience and try to make a reusable modular code base that I and others, if they find it interesting, can continue to develop from a single repository and be added as a dependency to projects rather than as part of the individual projects code.

The following sections will detail each layer from the bottom up. Fell free to skip around between them, I have tried to make each section as stand-alone as possible so you can jump to the parts that interest you the most.

This is how the integration API ended up. It still needs a bit more for input handling but I am not sure exactly how I want to do that bit, so for now it is only what I needed for my demo code. I would also like to add some documentation for each function to make clear how they are intended to be used, though most of them should be pretty self-explanatory.

The entry point for the application for working with ProgUI is the UI class that handles initialization and creation of the top level UIElements.

Some things to note that might not be quite obvious:

1. Since ProgUI needs an instance of ProgUI::IntegrationInterface it is passed in as a mandatory argument in the constructor. I am not quite happy with this, I was just not sure how to do it right. It takes a pointer which is used to initialize a std::unique_ptr internally, thus taking ownership of the integration and that is not obvious from the API. I will have to do a bit more homework on move semantics I guess. 
2. The API contains two callback functions OnSerialize and OnDeserialize these are intended for the application level code to add any global scope data that it needs to restore a serialized UI.
3. The application shall call Init, then keep calling Update each frame with a UIUpdateContext, this is meant as a way for the application to be able to pass on needed data to the custom code. By default it only contains a single float for the frames delta time since the last frame. But the idea is that it can be inherited from and cast to the application specific version as needed.

Every UI needs a model for managing positions and sizes when the UI is rendered in a variety of resolutions and aspect ratios.

ProgUI uses the concept of a DesignSize to which all relative positions and sizes are normalized. The idea here is that artists and programmers agree on a resolution for which the UI is optimized for example 1920 x 1080. When the UI is rendered at its DesignSize it should not need to scale any assets and look its crispest.

ProgUI does not have an explicit canvas as is traditional, however the concept is there in an implicit manner. Canvas in ProgUI is referring to the rectangular viewport where it is rendered, this might be the full area or part of the screen or window client area depending on settings. Currently the canvas is fixed to the center of the screen/window, a future item is to be able to anchor the canvas relatives to points on the screen/window. 

To handle how it should behave when rendered in any other size ProgUI relies on two parts. The first part is that all UIElements are positioned relative to one of nine anchor point of its parent, the four corners, its center and the mid points of each edge. This gives an extra level of control over where they should end up on screen.

The second part is that one can choose a scale mode for the UI that determines the form of the canvas. The scale modes are:

• Stretch – This will stretch the canvas to the full size of the screen or window client area. This will not stretch the UIElements as well but determines where they will end up on the screen as the relative positions of the canvas’s anchor points are affected by changes in aspect ratio of the canvas.
• FitToWidth – This will keep the aspect ratio of the DesignSize and scale the canvas so that its full width fit on the screen/window. This will cause empty space above and below the UI if rendered with a lower horizontal aspect ratio than the DesignSize and with a higher part of the top and bottom would be outside the viewport.
• FitToHeight – this works the same as FitToWitdh but it ensures the full height is visible rather than width.
• BestFit – this will keep the DesignSize aspect ratio for the canvas and choose to scale either to width or height of the viewport to ensure the whole UI is visible, creating empty borders on top and bottom or left and right.

The first one adds a slider to set the progress value which can be useful for testing that it works. Nothing more interesting there really.

The second is the update function that grabs the UILayer with the bar sprite and figure out a scale and position offset for it based on the current progress value. At the end the UIElement Refresh function is called to make sure it will be properly reformatted with the new layer setting, this is probably redundant and an artefact of a dubious design choice where I use a flag to indicate if a UIElement needs to be refreshed due to any changes like this. However the system was never extended does to the UILayer level and is not perfectly reliable. For now it will remain on the known bugs list. 

The member variable myUI is an instance of the ProgUI::UI class and was initialized with an integration implementation for the engine used in the containing class’s constructor.

We can now access that integration and set the callback to use for de serializing custom UIElement data, we use a common function for all widgets in DemoUI analogous to the SerializeElement callback seen previously.

We then also set a callback for reading the data binding data at de serialization time using a different technique.

Then we give it a name and initialize it with our chosen design size and scale mode.

Then we check if there exists a json serialization file and if so we load that to set up the rest. If it does not we call the function BuildUI that programmatically does the set up. Lets take a look at that code as well.

We have already taken a look at the progress bar, here is just showing that we can do both vertical and horizontal bars. It also show that the same function is used but with other sprites, in this case they are the same just rotated 90 degrees.

Artists can make them in any size and form that match the games theme.

In the top part i set up the slightly more complicated radial menu that is made from a center button and a number of child buttons that are laid out radially around the center button.

I also add a background image, this is commonly done when making menus but here I just needed a backdrop to get more of a game feel in the demo. 

Another thing to note is that I add a panel directly under the canvas and add all the widgets as children to this. Together they form a tree structure and can be moved around and scaled as a unit which is rather practical.