In this entry, we will show you how to create different types of UI components.

Generating your files

A swift introduction to the UVKBuildTool

The UVKBuildTool is a custom build tool we built to generate production builds, source files and more. The tool binary is located under the UVKBuildTool/build directory. Running it with the --help argument shows you the different options you have on hand:

    --generate <project path> - Regenerates all required generated files for the given project
    --install <project path> - Generates the project files when installing for the first time
    --build <project path> - Bundles the application and compiles it for production
The following arguments generate source files for UI components:
    --inline <name> <project path> - Creates an inline component
    --window <name> <project path> - Creates a window widget
    --title-bar <name> <project path> - Creates a titlebar widget

As you can see from the comments, the first flag --generate regenerates the files of a project. This is necessary for applying changes to project file templates, but most of the time we don’t break the API, so you won’t use it frequently.

The --install command is used to generate project files for first time installation. You shouldn’t run this alone, but rather use the create-project.sh script to create a project.

The --build argument builds a given project for production.

Finally, we have the 3 component commands, when given a name and a path to a project they generate different components:

  1. --inline for creating inline components
  2. --window for creating window components
  3. --title-bar for creating title bar components

Component types

There are 3 component types:

  1. --inline
  2. --window
  3. --title-bar

Inline components are ones that are drawn directly to the framebuffer just like how standard applications render UI. Here is an application that uses inline components:

image


Window components are components that are drawn inside separate Windows. These windows can be docked, dragged out of the main window and moved by the user to create their own layout. Below is a window in floating mode:

image

Here is a window that is docked to the side:

image

Here is a window that is rendered outside the main window:

image


Finally, title bar components are components that render the main title bar, which can be seen at the top of the window in the window component examples.

Working with UI components

After you have generated your components with the UVKBuildTool, you can now start using them. The header file of a component looks like this:

#pragma once
#include <Framework.hpp>

namespace UntitledTextEditor
{
    class UIMGUI_PUBLIC_API Exit : public UImGui::WindowComponent
    {
    public:
        Exit();
        virtual void begin() override;
        virtual void tick(float deltaTime) override;
        virtual void end() override;
        virtual ~Exit() override;
    private:

    };
}

It contains the essential event functions: the constructor, destructor, begin, end and tick functions. Here is information on them:

  1. begin - gets called when the application is opened
  2. tick - gets called every frame and takes the float deltaTime parameter that is equal to the current delta time
  3. end - gets called when the application closes or the widget is destroyed
  4. The constructor - Should contain variable initialization code(event safety is unknown and depends on how you wrote your application)
  5. The destructor - Should contain cleanup code

Keep event safety in mind and preferably call most framework dependent code in the begin, end or tick functions.

Since the tick function gets called every frame, you should use it to render dear imgui code.

Writing a Hello World application

First generate an inline class:

cd UVKBuildTool/build
./UVKBuildTool --inline hello ../../Projects/YourProjectNameHere

Next, refresh your CMakeLists.txt file under your project directory and enter the Source folder. The hello.cpp and hello.hpp header will have been generated.

Open hello.cpp, it should look like this:

#include "hello.hpp"

Example::hello::hello()
{

}

void Example::hello::begin()
{
    beginAutohandle();

}

void Example::hello::tick(float deltaTime)
{
    tickAutohandle(deltaTime);

}

void Example::hello::end()
{
    endAutohandle();

}

Example::hello::~hello()
{

}

In the tick function, add the following code so that it looks like this:

void Example::hello::tick(float deltaTime)
{
    tickAutohandle(deltaTime);
    ImGui::Text("Hello, World")
}

Compile your application and run!

Oh… there is no text here. That’s because you haven’t initialized the framework with your component. The next wiki entry shows you how to do that!

Event safety

The begin and tick members are flagged as All ready and end is flagged as Pre-destruct. The rest are flagged as Any time.