> For the complete documentation index, see [llms.txt](https://i58215.gitbook.io/component-sdl2-en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://i58215.gitbook.io/component-sdl2-en/getting-started-with-the-library/getting-started.md).

# Getting started

## Initial setup

To use the library, include the `component-sdl2` header file:

```cpp
#include <component-sdl2>
```

The library is located in the `Kit` namespace, and in order not to write `Kit::*` each time, the following line will be implied in the following examples:

```cpp
using namespace Kit;
```

> The main function must take two parameters `int , char **`!

After connecting the library, access to the library object is via the `$` variable. To start the library, you need to call the `run` method.&#x20;

So the simplest code would look like this:

```cpp
#include <component-sdl2>
using namespace Kit;

int main(int argc, char** argv)
{
    return $.run();
}
```

## Adding Windows

The main method of the main library class is `addWindow`, which is used to add windows. It has the following form:

```cpp
Window* addWindow(Window* window);
```

The `Window` class is the base class for any application window. It has a single constructor:

```cpp
// SimpleRect is struct { x, y, w, h }
Window(std::string title, SimpleRect size, noBorder = false);
```

The first parameter is the window title, the second is the size and position of the window (specifying -1 in the position coordinates aligns the window in the center), and the third is a flag indicating whether the window will have a standard frame.&#x20;

Let's see how to add a window:

```cpp
#include <component-sdl2>
using namespace Kit;

int main(int, char**)
{
    $.addWindow(new Window("Test Window", { -1, -1, 300, 300 }, false));
    return $.run();
}
```

As a result, an empty window will be displayed in the center with a size of 300 by 300 pixels.

![](/files/-LzTcsn-DLDuvkIpLGLe)

## Adding Components

There are several ways to add new components to a window. The first way is to add components to the main function. To add components, use the `add` method.&#x20;

The `add` method has several prototypes:

```cpp
Component* add(const string& id, const string& classes, 
               const vector<Component*>& childrens = {});

Component* add(const string& classes = "", 
               const vector<Component*>& childrens = {});

Component* add(Component* component);
```

The first prototype, as the most common.

The method takes the identifier string of the component as the first parameter **(identifiers must begin with the `#` character!)**. In this case, the window cannot contain two components with the same identifier!&#x20;

The second parameter is a string of class identifiers separated by a space. **(class identifiers must begin with `.` character!)**. Class identifiers, in contrast to ordinary identifiers, can be repeated from component to component.

The third parameter is an *optional* vector of child components. Usually, to add components, you can use just calling `new Component (...)`, but it is better to use the static create method of the Component class. This method completely repeats the add method discussed above.

The second prototype differs only in that it does not accept an identifier. This prototype will generate a random identifier for the component, which may be convenient in some cases.&#x20;

The third prototype simply accepts a pointer to a Component. This prototype will be used when adding standard components (Button, Checkbox, etc.). Usually, as with the child components from the second prototype, it is better to use the create method on the Component class or on standard component classes.

#### Example

Let's add the components in the first way:

```cpp
#include <component-sdl2>
using namespace Kit;

int main(int, char**)
{
    auto window = $.addWindow(new Window("Test Window", { -1, -1, 300, 300 }, false));

    // add a simple component
    window->add("#test", ".test");

    // add component with child components
    window->add("#test-childs", ".test", {
        Component::create("#inner", ".inner"),
        Component::create("#inner-1", ".inner", {
            Component::create("#inner-inner", ".inner-inner")
        })
    });


    return $.run();
}
```

So far, if you run the program, nothing will change from the last run without components. This is because the components in the window exist, but are not stylized!

## Component Styling

The library uses `css` to style components. Each window can store the styles of all its components. To add a css file, use the style method:

```cpp
void style(const string& path);
```

> The path to the css file must be relative to the executable!

#### Example

Add the `css` folder in the same folder as `main.cpp`, and add the `style.css` file to it. And add the following code to it:

```css
.test
{
    width: 70px;
    height: 24px;

    top: 100px;
    left: 100px;

    background-color: #263238;
    outline: #0F1518;
}
```

What happens here? First, all styles are set for `class identifiers`, which allows you to reuse styles from different components. Second, size and position are set using standard `css` attributes. More information about what values ​​these attributes can take in the `css` [section](/component-sdl2-en/api/all-css-styles-supported.md). Third, the background color and the color of the single-pixel stroke are set, more about these and other possible properties in the `css` [section.](/component-sdl2-en/api/all-css-styles-supported.md)

Let's call the `style` method and write the path to the styles:

```cpp
#include <component-sdl2>
using namespace Kit;

int main(int, char**)
{
    auto window = $.addWindow(new Window("Test Window", { -1, -1, 300, 300 }, false));

    // Add styles to the window
    window->style("../test/css/style.css");

    window->add("#test", ".test");

    return $.run();
}
```

After that, if you run the program, a rectangle with the specified dimensions with a stroke will appear in the window!

### Extended styling

For more flexible style settings in different situations, the library allows you to use 3 css pseudo-classes.

The `hover` pseudo-class sets styles for the component that is currently hovering over the mouse.&#x20;

The `active` pseudo-class sets styles for the component that the mouse button is clicked on.&#x20;

The `focus` pseudo-class sets styles for the component that is currently in focus.&#x20;

Pseudo-classes are defined as follows:

```css
.classname:pseudo-classname
{ 
    
}
```

## Adding components (preferred)

In many cases, adding components to windows in the first way is not convenient, and sometimes it is not advisable, for example, if you need to create two identical windows.&#x20;

Especially for this, there is a second way. The second way is to inherit from the `Window` class.&#x20;

Let's create a `MyWindow` in the same folder as `main.cpp` and add the `MyWindow.h` header file to it. To inherit, you must include the header file of the Window class.

```cpp
#include "window/window.h"
```

Next, you need to create a class based on `Window`, add the constructor and the `setup` method, which is called in the constructor:

```cpp
#pragma once

#include "window/window.h"
using namespace Kit;

class MyWindow : public Window
{
public:
    MyWindow(string title, SimpleRect size, bool noBorder = false)
        : Window(title, size, noBorder) 
    {
        setup();
    };

public:
    void setup()
    {

    }

};
```

The `setup` method is needed to configure the components in the window. Everything described in the first method also works here, let's rewrite the last example:

```cpp
#pragma once

#include "window/window.h"
using namespace Kit;

class MyWindow : public Window
{
public:
    MyWindow(string title, SimpleRect size, bool noBorder = false)
        : Window(title, size, noBorder) 
    {
        setup();
    };

public:
    void setup()
    {
        style("../test/css/style.css");

        add("#test", ".test");
    }

};
```

Connect this window to `main.cpp`, and replace `Window` with `MyWindow`:

```cpp
#include <component-sdl2>

#include "MyWindow/MyWindow.h"

using namespace Kit;

int main(int, char**)
{
    // создаем объект нестандартного окна
    $.addWindow(new MyWindow("Test Window", { -1, -1, 300, 300 }, false));

    return $.run();
}
```

Now, if you run the program, then we will get the same result as in the previous example. At the same time, we can create, for example, two windows with the same interface:

```cpp
#include <component-sdl2>

#include "MyWindow/MyWindow.h"

using namespace Kit;

int main(int, char**)
{
    // create a custom window object
    $.addWindow(new MyWindow("Test Window", { -1, -1, 300, 300 }, false));
    // and one more
    $.addWindow(new MyWindow("Test Window 2", { 200, 200, 300, 300 }, false));

    return $.run();
}
```

## Interaction with components.

### Access to components by their id

To access the added components in the window, the static method `getElementById` of the `Window` class is used, where the identifier of the component is passed as the only parameter:

```cpp
Component* getElementById(string id);
```

### Adding text to a component

To set text, the `Component` class has a `setText` method. Add the text to the newly created component (we will only consider the `setup` method of the `MyWindow`):

```cpp
void setup()
{
    style("../test/css/style.css");

    add("#test", ".test");

    Window::getElementById("#test")->setText("ok");
}
```

All styles for the text can be found in the `css` section.

### Add event listeners

Components can track the following events:

| Event         | Description                                             |
| ------------- | ------------------------------------------------------- |
| `click`       | Event occurs when a component is clicked                |
| `hover`       | An event occurs when you hover over a component         |
| `focus`       | The event occurs when focusing on the component         |
| `focusout`    | Event occurs when component loses focus                 |
| `mousemotion` | The event occurs when the mouse moves on the component  |
| `onmousedown` | An event occurs when a button is pressed on a component |
| `onmouseup`   | An event occurs when a button is released               |
| `onmouseover` | An event occurs when the mouse enters the component     |
| `onmouseout`  | An event occurs when the mouse leaves the component     |

To add a listener, use the `addEventListener` method, where the first argument is the name of the event that we are listening to, and the second is the function that will be called when this event occurs:

```cpp
void addEventListener(const string& name_event, 
                      function<void(Component* sender, Event* e) callback>);
```

#### Example

Let's add a click event listener to our component using the lambda function:

```cpp
void setup()
{
    style("../test/css/style.css");

    add("#test", ".test");

    Window::getElementById("#test")->addEventListener("click", 
    [](Component* sender, Event* e)
    {
        std::cout << "Component clicked" << std::endl;
    });
}
```

Now, when you click on a component, a message will be displayed in the console.

### Removing a listener for an event

To remove the listener, use the `removeEventListener` method:

```cpp
void removeEventListener(const string& action);
```

### Additional information in the component

Any component can store additional information. To add, use the `addUserData` method:

```cpp
void addUserData(string key, std::any data);
```

And to get information by key — `userData` method:

```cpp
std::any userData(string key);
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://i58215.gitbook.io/component-sdl2-en/getting-started-with-the-library/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.