Difference between revisions of "Containers"

From uGFX Wiki
Jump to: navigation, search
 
(18 intermediate revisions by the same user not shown)
Line 1: Line 1:
The container class is based on the widget. Containers can have children windows which they can place within their borders. Containers control the visibility and enabled state of their children. By making a container invisible you make all its children invisible. Similarly with the enabled state.
+
'''''Note:''' Make sure you read the [[Widgets|widget]] article first!''
A list with descriptions of the common container API can be found [http://ugfx.org/images/resources/doxygen/master/group___container.html here].
+
 
 +
The container class is based on the widget. The main property of a container is that it can hold children. A child window inherits the attributes and properties of the parent.
 +
 
 +
== API reference ==
 +
The reference of the common container API can be found [http://api.ugfx.io/group___containers.html here].
  
 
== Container Implementations ==
 
== Container Implementations ==
 
These are the currently implemented containers:
 
These are the currently implemented containers:
[[Containers]]
+
* [[Container]]
[[Frame]]
+
* [[Frame]]
 +
* [[Tabset]]
 +
 
 +
== Container creation ==
 +
Each container provides a creation call with is named <code>gwinXxxCreate()</code> 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 <code>GWidgetInit</code> struct. This struct contains all the attributes which are needed to create the container (position, size, font, colors...):
 +
<syntaxhighlight lang=c>
 +
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;
 +
</syntaxhighlight>
 +
As the container class is based on the [[Widgets|widget]] and therefore the [[Windows|window]] class, the widget initialization structure contains a window initialization structure. See [[Windows#Window_creation|window creation]] to learn more about the window initialization structure.<br/>
 +
Examples on how to use this struct correctly can be found on each container documentation page.
 +
 
 +
<code>gwinDestroy()</code> 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, <code>gwinGetInnerWidth</code> and <code>gwinGetInnerHeight</code> 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 <code>gwinHide()</code> 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 <code>gwinDisable()</code> on the child itself.
  
  
[[Category:Container]]
+
[[Category:GWIN]]

Latest revision as of 13:56, 19 August 2021

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. A child window inherits the attributes and properties of the 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.