[Source] kiUi - minimal auto-layout Ui library

[N0vember]

kiUi

I am releasing kiUi as alpha, officially working with both Ogre 2.1 and 2.0
I believe this makes it one of the first few Ui libraries to officially support Ogre 2.1

kiUi also supports Emscripten, and has a live demo here : http://novembermonk.github.io/kiui/livedemo/kiui.html

kiUi
- is a very lightweight Ui library but feature-complete : it even has a docking space for your windows and a file tree browser
- auto-layouts : no manual positioning or sizing is ever needed except when explicitly specified (no messing with VSizers and HBoxes)
- is skinnable : provided in the example is a sample imitating the base skin of MyGui
- separates Ui logic from Ui appearance
- has few dependencies : only GLFW for the sample renderer, and only Ogre for the kiog renderer
- compiles under gcc, clang and visual studio, you can check for the Travis CI status stating that it builds, and you can look at the .travis.yml script to have an example of how to build it
- has : tables, dockspaces, tabs, radiobuttons, sliders, text inputs
- doesn't have yet : documentation, but it has a bunch of simple examples
- uses Gorilla for fast and efficient rendering on top of Ogre
- is not tied to Ogre, and has a standalone renderer using NanoVG : you can both use it in your Ogre app and outside of it

- is in an alpha state : if you wish to try it I will be happy to help, but a lot of things are probably gonna change (for the better), so it will need a bit of upkeep



Get it here :
https://github.com/novembermonk/kiui (The kiUi library)
https://github.com/novembermonk/kiog (The Ogre backend for kiUi)

A few screenies :

A resizable draggable window :

The same window with the MyGui example skin :

Original post

Here is the backstory : for years, I have been looking for a gUi solution that would cover some simple requirements :
- Separation of Ui appearance and logic
- Automatic layout as the norm, not the exception (as in HTML)
- Easy styling, separated from logic (as in CSS)
- Brevity and simplicity above everything else, especially in C++ code
- Good for both an editor Ui and a game Ui

So, year after year I have tried a handful of solutions and they all fell short of what I was looking for :
- CEGUI is an enormous piece of software and simplicity isn't its main advantage, especially not : convenient automatic layout and skinning
- Qt is a bloated framework that make you shoehorn all your code into their models, classes, toolchain (even though I would concur that Qt Creator is a great editor), and it is okay for writing an editor but not so much for a game
- These two (and let's add in MyGui) while being very good pieces of software are good examples of how "over-flexibility" actually kills flexibility and make you lose tons of time at the end of the day
- LibRocket at first seemed promising, in offering HTML/CSS layouting for games, but it is the opposite of "simple" or "modern", and it actually doesn't feature the main advantage of HTML layout which is that the layout is done automatically when nothing is specified. So in the end it is much like CEGUI, except you write stuff in HTML and you have to wire it to render manually


So after a few iterations and trying almost all of them I came to the realization that it didn't exist and that I'd have to write it, so I started working on it.
These days the features are coming together, and I am coming close to something that will be clean and functional enough to be shared soon, so I wanted to share first a general overview.
Code is not usable yet for a few reasons (no comments in the code, no examples, and it is still a bit coupled to the rest of my engine, so I'd have to take care of that)

To give a short description of what this Ui library is : think of a nice C++ api for HTML/CSS-similar layout and styling system, applied to game Ui and rendering to Gorilla / Ogre.

This screenshot, although from a work-in-progress, should show the basic functionality of the library : not one widget on this has had its position set manually. It's all wrapping and padding and one weight to set the (viewport on right/ tool tabs on left) size respectively.
Nothing fancy : no animations or deformations, visually we are targeting something similar to basic HTML and CSS, which already allows to do basically anything

Let me explain the main features and design principles :

Define your Element in C++

A lot of Ui solutions have dismissed the fact that an Ui is inevitably a more or less complex architecture in native code.
In kiUi we completely embrace that fact, and that you will have to write some C++ to make your Ui interact with your application.

That is probably one key in the simplicity of kiUi : we don't try to make complicated scripting workarounds, delegates systems, clumsy rewirable slots/signals architectures. We do it simple, in pure C++, just using an interface and virtual functions to control and propagate the events.

Otherwise, we commit to two things :
- C++ definitions will be short, concise, will not be intertwined with confusing appearance / layout code
- the styling and layout properties will be easily setup in a separated manner, and these definitions could be easily setup from a script file by a designer (although not implemented yet)

Code: Select all

class Menu : public Form
{
public:
    Menu()
        : Form("mainmenu")
    {
        this->insert<Button>("mainbutton", "Start Game", std::bind(&Menu::startGame, this));
        this->insert<Button>("mainbutton", "Load Game", std::bind(&Menu::loadGame, this));
    }
    
    void startGame()
    {}
    
    void loadGame()
    {}
};

That's it. Doesn't look so groundbreaking, right ? It's not, it is the simplicity we all strive for
No styling. We just specify the functional type of the element (Button), its Ui class (mainbutton), a label, and a callback for the buttons.

Style your Layout

Manual positioning and sizing is an antiquated way to go about Ui design, yet most Ui libraries still mainly rely on it, and automatic positioning is usually shoehorned on top of it.
Look at your screen : do you see a lot of widgets whose positions were manually hardcoded ?

Our Layout approach is the opposite, and relies on automatic positioning as the default, for ALL elements, called Flow (as in HTML I believe).
You can always set a widget as manually positioned, and it is pulled out of the Flow, but it's a rare occurrence.
The layout system mainly relies on an attribute that can take three values :
- either it shrinks around its contents
- either it expands to take all available space
- either it's fixed size (really rare occurrence too)

A Layout Style is defined by this property for each dimension (X,Y) and a few others, like margins, padding.
It is setup in code for each Ui class, and there is an inheritance mechanism so that you can define a hierarchy of layout styles :

Code: Select all

// wrap is a builtin layout style which wraps around its content in both X and Y dimensions
layout->add("mainmenu", "wrap");
layout->style("mainmenu")->d_layoutDim = DIM_Y;

layout->add("mainbutton", "wrap");

Ultimately, we want simple CSS-like scripts file to set these properties in much the same manner.

Skin your Elements

After the layout styling comes the graphic styling, which we will refer to as Skinning.
Again this is very much like CSS styling : it consists of a background (color, gradient, or image), text properties (size, colour), and border (thickness, radius for angles)

Code: Select all

inker->add("default")
inker->ink("default")->d_textColour = Colour(1.f, 1.f, 1.f);
inker->ink("default")->d_textSize = 7.f;

skinner->add("mainbutton", inker->style("default"));

Like the layout, ultimately we want CSS-like scripts to setup the skinning properties. It is planned but not implemented.

No code yet ?

I know it's harsh not to provide any code right away, but I need to get an idea of the (free) market here, would many people would be interested to try it out right away ? I could share it with a few people and keep in contact with them to iron out the basic usability problems before releasing it ?
If many people are interested in trying it out, it could motivate me to do the needed work sooner than never

So, am I the only one who needed that library ?

[Klaim]

I will be interested in trying it soon but not immediately.
Meanwhile I have questions, as I don't have source code to check it (BTW it's not a good strategy I think to not show source code which could be improved just by us staring at it for a few seconds):

1. You say it's built over gorilla, do you mean it relies on the presence of the silverback singleton?
2. Do you still retain the capability of moving ui in space?
3. Which Ogre version does it target? Do you plan to make it work on Ogre 2.0?

[N0vember]

I understand that it's better to release early, but I cannot release it with the rest of the engine, as both are tied in some ways right now. I must untie it and decouple some stuff before sharing anything.

The Ui is actually two parts, an abstract Ui library which doesn't rely on anything, and a front-end which draws the stuff using an Ogre / Gorilla setup.
So anything that I will say, understand it in this scope : you are not tied to the front end, so anything you dislike, you can write or modify it so that it works with your constraints.

1. As of now, the front-end it builds the Silverback object itself, yes. I actually use a version which I modified to allow for multiple viewports (and posted it in a post in the Ogre 2.0 forum)
2. It is possible, as I personally experimented with 3D huds in my game, and yes, they can be layout (laid-out) by the same system
3. I am personally using Ogre 2.0 So your concern should be more about retro-compatibility. For now, the front-end is written for Ogre 2.0

[Thyrion]

would many people would be interested to try it out right away ? I could share it with a few people and keep in contact with them to iron out the basic usability problems before releasing it ?

i don't know if many would be (because i don't see much activity here in last time), but i 'am interested.
I'am using Gorilla, too. Already switched to 2.0 and got my gorilla rectangles drawn with directx11 (shader posted in the same 2.0 thread as your code).

I used gui3d as base, but ended up writing a complete gui system from scratch (still not as far as you).

[Klaim]

I understand that it's better to release early, but I cannot release it with the rest of the engine, as both are tied in some ways right now. I must untie it and decouple some stuff before sharing anything.

The Ui is actually two parts, an abstract Ui library which doesn't rely on anything, and a front-end which draws the stuff using an Ogre / Gorilla setup.
So anything that I will say, understand it in this scope : you are not tied to the front end, so anything you dislike, you can write or modify it so that it works with your constraints.

1. As of now, the front-end it builds the Silverback object itself, yes. I actually use a version which I modified to allow for multiple viewports (and posted it in a post in the Ogre 2.0 forum)
2. It is possible, as I personally experimented with 3D huds in my game, and yes, they can be layout (laid-out) by the same system
3. I am personally using Ogre 2.0 So your concern should be more about retro-compatibility. For now, the front-end is written for Ogre 2.0

Nice!

[areay]

Good work N0vember

[N0vember]

Progress is being made towards a release, I successfully decoupled the library from my engine and separated it in two parts, kiUi, and kiOg (an Ogre / Gorilla / OIS / OpenAL example front-end for kiUi).
I also implemented some basic widgets
Tooltips
Dropdowns
Dockable windows with a grid Dockspace are on the way

Just some more cleanup, a few base widgets to implement and it should be ready.

However I would like to release it right away with CSS-like style sheets parsing, and I'm wondering if someone knows a lightweight CSS parser (hopefully in one header + one cpp) to give me a head start.
If it doesn't exist, I'm open to suggestions, other similarly simple formats like Yaml.
I imagine simple definition looking like this :

Code: Select all

button
{
     text-colour : rgb(255, 255, 255);
     background-colour : rgb(75, 75, 75);
     sizing : (shrink, shrink);
     border-width : 1px;
}

button.hovered
{
     inherit : button;
     background-colour : rgb(255, 0, 0);
}

specialbutton
{
    inherit : button;
    border-width : 0px;
}
 

[N0vember]

And here is a small peek on resizing :
This is a good stress test for the responsivity of the layouting system. (Cursor duplication is an artifact of the capture software)

[youtube]UIYkq2zx90U[/youtube]

[N0vember]

I finally managed to implement a grid docking system like in most applications. It took me a lot of time and I ironed out a lot of bugs in the process. I think it was one of the worst features on my todolist, there remain only :
- A few basic widgets
- Drag'n'drop
- Tables

I'm really hoping to release the code this week ! With an example sample it would be best

I'm actually quite happy to show it cause this is a feature no other ui solution for Ogre has

[youtube]aqfAznhEXAA[/youtube]

[Zonder]

Nice work I have never liked any of the gui systems as they don't auto arrange. Does it auto arrange based on text sizes in button/labels? (multi language ui's)

btw noesis gui also support the same layout system of course that's commercial though!

[N0vember]

Yeah, that's the spirit Auto-arrange or auto-layout is pretty much the reason I created this in the first place. Absolute positioning is so 1999. Then came other requirements like having clean logical interface code without any clutter due to layout information (like in Qt).

Every widget either shrinks around it's contents, or expands as much as it can. Lastly there is fixed size (almost only for windows)
The principle is that, with the right parameters (padding, spacing, alignment), anything you would think of with absolute positioning, you can do with auto-layout, but way more quickly.

[jacmoe]

Awesome project
Looks like you're actually doing something very Qt-like. Including the css-like stylesheet language. -> http://qt-project.org/doc/qt-4.8/stylesheet.html

[stealth977]

Heya November,

Was just wondering couple of things:

1 - Is your GUI's rendering decoupled from it's functionality? Like a IGUIRenderer interface which is used to make render calls instead of directly calling OGRE functions? (which would make it possible to render in any app even for those that dont use OGRE)

2 - Is your code free from OGRE? Like keeping all headers OGRE FREE, not using any OGRE types like float instead of Ogre::Real, std::string instead of Ogre::String etc... ?

I am wondering those because, I see most developers have a tendency to put an "Ogre.h" on top of their headers and use all OGRE types everywhere making their project/code not usable or not refactorable outside OGRE, not to mention making the compile times extremely longer...

[stealth977]

For example using modified Gorilla I use a renderer interface like this:

Code: Select all

        /// <summary>
        ///   Base Class for OGFGUI::Renderer
        /// </summary>
        class OGFGUI_API Renderer
        {
            friend class GUIManager;
        public:
            /// <summary>
            ///   Constructor.
            /// </summary>
            Renderer() {};
            /// <summary>
            ///   Destructor.
            /// </summary>
            virtual ~Renderer() {}

            virtual void Render( void* multi_purpose_ptr ) = 0;

            virtual void CreateVertexBuffer( void* identifier, unsigned int size ) = 0;
            
            virtual void ResizeVertexBuffer( void* identifier, unsigned int size ) = 0;

            virtual void DestroyVertexBuffer( void* identifier ) = 0;

            virtual void LoadTexture( const std::string& name ) = 0;

            virtual void UnLoadTexture( const std::string& name ) = 0;

            virtual void *LockVertexBuffer( void* identifier ) = 0;

            virtual void UnLockVertexBuffer( void* identifier ) = 0;
        };

        /// <summary>
        ///   Null Renderer
        /// </summary>
        class NullRenderer : public Renderer
        {
            friend class GUIManager;
        public:
            /// <summary>
            ///   Constructor.
            /// </summary>
            NullRenderer() {}
            /// <summary>
            ///   Destructor.
            /// </summary>
            virtual ~NullRenderer() {}

            virtual void Render( void* multi_purpose_ptr ) {}

            virtual void CreateVertexBuffer( void* identifier, unsigned int size ) {}
            
            virtual void ResizeVertexBuffer( void* identifier, unsigned int size ) {}

            virtual void DestroyVertexBuffer( void* identifier ) {}

            virtual void LoadTexture( const std::string& name ) {}

            virtual void UnLoadTexture( const std::string& name ) {}

            virtual void *LockVertexBuffer( void* identifier ) { return NULL; }

            virtual void UnLockVertexBuffer( void* identifier ) {}
        };

When gorilla initializes, it instantiates a NullRenderer, so nothing is actually created or rendered (you will need to check the return value of LockVertexBuffer though) application can call Gorilla::setRenderer to change the renderer with an implementation derived from Renderer and voila it starts rendering, the GUI Api doesnt care what the renderer uses, it just passes the Renderer implementation a vector of <Texture, buffer> pairs.

Of course a more complex api like yours may need some additions, but it makes your api OGRE FREE

[N0vember]

TL ; DR : No dependency on Ogre in the API

The library is split in two parts : Ui and Og (short nicknames).
The first, Ui, does all the work apart from rendering and you must feed it the inputs. It does the layout, event propagation, logic. Well it does all the Ui stuff except rendering.
It is completely self-contained, no dependency except on a side Object library that the Elements depend on.

The rendering is entirely contained in the second, Og, which uses Ogre, Gorilla, OIS, and it shouldn't be too hard to write another front-end based on the first. It implements the rendering interfaces defined by the Ui library. I guess the interface can only settle with a second renderer though, as always. The Og library actually does a lot more right now (it even has a sound manager) : it's a complete front-end.

The rendering API is really simple, all the work must be done within. It is based on four abstract interfaces that must be implemented : InkWindow, InkTarget, InkLayer, and InkBox.
The InkBox is the base graphic element, it is given a Frame object with all the information (position, size, clipping, caption) and the style information and must do the work by itself. The implementation on top of gorilla is just a matter of a 100 lines of code.
InkTarget, InkLayer are just hierarchical elements to allow to render to different z-orders and to different targets (3D, 2D, screen).

Comparing to your API, it's a lot more abstract. It doesn't care about vertices or textures. For example it could render to a 2D drawing engine. (Hell if I gave a shot at emscripten I could even embed it directly in the browser and experiment rendering to canvas) It just gets a frame, a style, is told when to update the frame, the style, or to show or hide, and that's it. The implementation does the rest.

I hope to release something like tommorow (which can be next week, as always :p ) but meanwhile you can look at the interfaces :

Code: Select all

	class InkWindow
	{
	public:
		virtual InkTarget* screenTarget() = 0;
	};

	class InkTarget
	{
	public:
		virtual std::unique_ptr<InkLayer> createLayer(size_t z = 0) = 0;
	};

	class InkLayer
	{
	public:
		virtual std::unique_ptr<Inkbox> createInkbox(Frame* frame) = 0;

		virtual void show() = 0;
		virtual void hide() = 0;
		virtual void moveToTop() = 0;
	};

	class Inkbox
	{
	public:
		Inkbox(Frame* frame) : mFrame(frame) {}
		virtual ~Inkbox() {}

		Frame* frame() { return mFrame; }

		virtual void show() = 0;
		virtual void hide() = 0;

		virtual void updateStyle() = 0;
		virtual void updateFrame() = 0;
		virtual void caption(const string& text) = 0;
		virtual DimFloat contentSize() = 0;

	protected:
		Frame* mFrame;
	};

[stealth977]

Cool

I may give it a try in Ogitor then

I am glad you did all in the right way, got so much frustrated to see nice projects with awful dependencies

[N0vember]

Progress report !
- Collapsable boxes are in
- Tables are in
- Style overrides are in (ala css ".x .z" to define style of x when inside of z)

Big tasks remaining (5 days) :
Simple Editor is on the way with tree view and style modifications to allow for visual debugging
The last piece of work is to write a light NanoVG renderer to have a proof of concept working without Ogre

Small tasks remaining (1-2 days) : drag'n'drop for list items, pivot point (and text alignment)

Then finally I will be set for release

As you probably guessed, I decided to ship a feature complete product from day 0, as perfectionism slowly but surely took a hold of me (and probably the angst of releasing a piece of software for the first time in my life, I want it to function well enough )

I noticed yesterday quite by mistake that the system handles really well long lists of widgets (tried with ~3000 widgets and it didn't flinch, so tens of thousands should be fluid)

All this means a release in about a week I hope !

[Thyrion]

looks impressive.
Can't wait to look into the source.

a treeview would be definitely nice.

[N0vember]

Well there is not going to be any MVC widgets like in Qt because I don't believe it is a sound design pattern at least not the way it's done in Qt, and I didn't try another.

But there will be a widget behaving like a tree node (a tree node is just an expanding box with the content padded on the left side, in practice), and I hope, a simple way to fill it from a collection of elements.
I will refine it as I implement the tree view for the editor.

[spookyboo]

Yes, the MVC pattern in Qt is a typical example of over-engineering. Wxwidgets is simpler. Good job though.

[N0vember]

Edited : much more polished screenshot now
This screen is cool for two reasons

First it is cool because I'm progressing on a small editor for kiui (and yes it's a really rough prototype of a tree view in the upper right corner )
But the real reason it is cool because, although it looks really similar to the previous ones, this one is actually from an app that doesn't use Ogre at all

It is based on a really tiny NanoVG / GLFW front-end for kiui that I pulled together really quickly thanks to these great libraries. Just ~400 LoC to flesh the rendering interfaces and the glfw window with input.
So now kiui has two renderers : one for Ogre (a bit bigger), and one for NanoVG / OpenGL (really tiny)

It works really well. The good news is it will finally allow me to test some shinier style properties like gradients, rounded borders, better text clipping.

[N0vember]

Progress ! kiUi editor is working real-time

[youtube]V0lSWvHtIRE[/youtube]

[jacmoe]

Great work

The look, however.. it would take a required taste to call it beautiful.
Keep it up!
Ogre can't seem to get enough gui libs.

[Zonder]

Great work

The look, however.. it would take a required taste to call it beautiful.
Keep it up!

Yeah , maybe he can pinch a skin from another ui

Ogre can't seem to get enough gui libs.

This one only has one competitor though and that's noesis gui which is commercial.

Keep up the good work N0vember

[N0vember]

Update : Source Release (Edited the first post

I have released the source code on github. It is a really early first step as I expect a lots of ambushes before someone manage to compile it and run the example.
The Visual Studio project files for VS2013 are included although you will have to setup the dependencies yourself : the only dependencies you need to build it and link are GLFW and OpenGL.
NanoVG and glew are just already included in the source.
I will be in touch we anyone who wants to try it and help me get it to a "shareable" quality

https://github.com/novembermonk/kiui

The Ogre backend will be released shortly in another repo.