Getting Started

Hello World

The smallest possible gui app is as follows:

#include <liblec/lecui/form.h>
using namespace liblec::lecui;

int main() {
    form("Form").message("Hello world!");
    return 0;
}

The above code displays the following form:

Surely, it doesn't get easier than that!

Your First App

Below are step-by-step instructions on how to use the library to build a Windows gui app in C++.

Inherit from the form base class

To make a form we need to inherit from the form base class and since there is no default constructor we need to explicitly call one of the form's constructors. The one that we shall use here set's the form's caption (the text that is displayed on the top left corner of the form).

#include <liblec/lecui/form.h>
using namespace liblec::lecui;

class sample_form : public form {
public:
    sample_form() :
        form("Sample Form") {}
};

Add a handler for the layout event

The layout event handler is where we add content to the form.

#include <liblec/lecui/form.h>
using namespace liblec::lecui;

class sample_form : public form {
public:
    sample_form() :
        form("Sample Form") {
        events().layout = [this](std::string& error) {
            return true;
        };
    }
};

Things to note:

1. The layout event handler takes only one parameter, a string. If an error occurs it is written back to this string.
2. The layout event returns a boolean. If the method is successful true is returned and if not false is returned (in which case error information must be written to the parameter we just mentioned).

Add a page to the form and show it

Content can only be added to containers, and only two containers can be added directly to the form: a page and a status_pane. To add a page we need the page_manager class. It is common for the page_manager class to be used in various places in the class and so it is recommended that we add it as an in-class object.

#include <liblec/lecui/containers/page.h>
using namespace liblec::lecui;

class sample_form : public form {
    page_manager _page_man{ *this };

public:
    sample_form() :
        form("Sample Form") {
        events().layout = [this](std::string& error) {
            auto& home = _page_man.add("home");
            _page_man.show("home");
            return true;
        };
    }
};

Things to note:

1. The add() method takes only one parameter, the alias of the page. Every page MUST have an alias and it must be unique. This is how the page is distinguished from others.
2. The add() method returns a reference to the page. We can then use this reference to add widgets to the page.
3. The show() method takes one parameter, the alias of the page to show when the form is displayed. Several pages can be created but only one can be displayed at a time.
4. Once we include any other lecui header other than <.../form.h> we no longer need <.../form.h> because it is included in every other header.

Add a widget to the page

Widgets can be added to any container. We will add a simple label to the page.

#include <liblec/lecui/containers/page.h>
#include <liblec/lecui/widgets/label.h>
using namespace liblec::lecui;

class sample_form : public form {
    page_manager _page_man{ *this };

public:
    sample_form() :
        form("Sample Form") {
        events().layout = [this](std::string& error) {
            auto& home = _page_man.add("home");

            auto& label = widgets::label::add(home);
            label
                .text("This is a simple label")
                .rect().left(10.f);

            _page_man.show("home");
            return true;
        };
    }
};

Things to note: The rect() method is used to specify the coordinates of the widget. Chaining is used here to set the left margin of the label to 10 pixels from the left side of the page.

Make an instance of the class and create the form

We can instantiate our class and call the create() method as follows to display the form:

int main() {
    sample_form form;
    std::string error;
    if (!form.create(error))
        form.message(error);
    return 0;
}

The code above displays the following form:

Things to note:

1. The create() method takes only one parameter, a string. If an error occurs it is written back to this string.
2. The create() method returns a boolean. If the method is successful true is returned and if not false is returned (in which case error information will be available in the parameter we just mentioned).
3. The message() method is used to display a message box to the user. It's a simple message box with an Ok button.