In this entry, we will show you how to create different types of UI components.
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:
--inline
for creating inline components--window
for creating window components--title-bar
for creating title bar componentsThere are 3 component types:
--inline
--window
--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:
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:
Here is a window that is docked to the side:
Here is a window that is rendered outside the main window:
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.
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:
begin
- gets called when the application is openedtick
- gets called every frame and takes the float deltaTime
parameter that is equal to the current delta timeend
- gets called when the application closes or the widget is destroyedKeep 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.
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!
The begin
and tick
members are flagged as All ready
and end
is flagged as Pre-destruct
. The rest are flagged as Any time
.