Containers

From uGFX Wiki
Jump to: navigation, search

Note: Make sure you read the widget article first!

The container class is based on the widget. The main property of a container is that it can hold children windows. A child window does inherit the attributes and properties of his parent.

API reference

The reference of the common container API can be found here.

Container Implementations

These are the currently implemented containers:

Container creation

Each container provides a creation call with is named gwinXxxCreate() where Xxx is the name of the container. The first parameter is either a pointer to a static container object or NULL. If NULL, the object will be allocated dynamically from the heap. The second parameter is a pointer to a GWidgetInit struct. This struct contains all the attributes which are needed to create the container (position, size, font, colors...):

typedef struct GWidgetInit {
    GWindowInit                g;			// The GWIN initializer
    const char*                text;			// The initial text
    CustomWidgetDrawFunction   customDraw;		// A custom draw function - use NULL for the standard
    void*                      customParam;		// A parameter for the custom draw function (default = NULL)
    const GWidgetStyle*        customStyle;		// A custom style to use - use NULL for the default style
} GWidgetInit;

As the container class is based on the widget and therefore the window class, the widget initialization structure contains a window initialization structure. See window creation to learn more about the window initialization structure.
Examples on how to use this struct correctly can be found on each container documentation page.

gwinDestroy() can be used to destroy a window that is no longer needed.

Coordinates

The coordinates of a child are always relative to it's parent.

As a container can have a border, gwinGetInnerWidth and gwinGetInnerHeight can be used to retrieve the dimensions of the container area that is relevant for the children.

Visibility

The children inherit the visibility state of their parent. However, a child can still be invisible although his parent is visible by using gwinHide() on the child itself.

Enable state

The children inherit the enable state of their parent. However, a child can still be disabled although his parent is enabled by using gwinDisable() on the child itself.