Difference between revisions of "Label"

From uGFX Wiki
Jump to: navigation, search
(Small label improvements)
(→‎API reference)
 
(20 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
A label is a simple rectangular widget which takes no input. The label will automatically redraw it the text changed. If the label is smaller than the text it displays, the text gets clipped.
 
A label is a simple rectangular widget which takes no input. The label will automatically redraw it the text changed. If the label is smaller than the text it displays, the text gets clipped.
−
The text of the label can be set using the ''gwinSetText()'' routine.
+
The text of the label can be set using the <code>gwinSetText()</code> routine.
 +
 
 +
== API reference ==
 +
The API reference of the label widget can be found [http://api.ugfx.io/group___label.html here].
  
 
== Border ==
 
== Border ==
−
The default drawing routine of the labels allows to enable or disable a border. This can be done using gwinLabelSetBorder().  
+
The default drawing routine of the labels allows to enable or disable a border. This can be done using <code>gwinLabelSetBorder()</code>.
  
 
== Auto scale ==
 
== Auto scale ==
−
If you apply a size of 0 to the width or the height of the label, the corresponding dimension will be scaled automatically. This also happens when you change the text or the font of the label. However, if you're using a border, this will certainly change the look of your application.
+
Applying a size of 0 to the width or the height of the label will automatically set the corresponding dimension to fit the entire label text. Updating the label text will update the label dimensions each time.
 +
Note: If the the board is enabled the auto-sizing feature of the label will certainly change the look of the application.
  
 
== Justification ==
 
== Justification ==
−
The text of a label is currently always justified to the left side. We'll update dynamic justification soon.
+
By default the text of the label is left justified. The justification of the label text can be controlled through different built-in rendering functions.
 +
 
 +
The following rendering functions are available:
 +
* gwinLabelDrawJustifiedLeft
 +
* gwinLabelDrawJustifiedRight
 +
* gwinLabelDrawJustifiedCenter
 +
 
 +
== Font size and color ==
 +
As with any other widget the look-and-feel of the label widget can be fully customized. The font can be changed by using <code>gwinSetFont()</code> and the font color is controlled through the [[Widgets#Widget_Style|widget styles]]. The widget rendering can be fully customized by implementing a [[Creating_a_custom_rendering_routine|custom rendering routine]].
  
 
== Attribute ==
 
== Attribute ==
−
Often you want to display multiple text elements below each other where an element consists of a static text which will always be the same and some variable one. The static text is called the attribute and can be optionally set through gwinLabelSetAttribute() once you enabled this feature in your gfxconf.h. The function does also take a tab parameter which allows to align multiple labels vertically as the following example shows:
+
Often you want to display multiple text elements below each other where an element consists of a static text which will always be the same and some variable one. The static text is called the attribute and can be optionally set through <code>gwinLabelSetAttribute()</code> once you enabled this feature in your [[configuration|configuration file]]. The function does also take a tab parameter which allows to align multiple labels vertically as the following example shows:
  
 
<pre>
 
<pre>
Line 19: Line 31:
 
DHCP:      On
 
DHCP:      On
 
</pre>
 
</pre>
−
 
+
'''IMPORTANT:''' Use of the attribute capability is discouraged. This feature should be considered deprecated and will be removed in future releases. The proper way of doing this is using two separate labels.
−
== API reference ==
+
−
The API reference of the label widget can be found [http://api.ugfx.org/master/group___label.html here].
+
  
 
== Example ==
 
== Example ==
 
The following example shows how to create a label.
 
The following example shows how to create a label.
−
<syntaxhighlight lang="php">
+
<source lang="php">
 
#include "gfx.h"
 
#include "gfx.h"
 
   
 
   
 
static GHandle ghLabel1;
 
static GHandle ghLabel1;
 
   
 
   
−
static void createWidgets(void) {
+
static void createWidgets(void)
−
GWidgetInit wi;
+
{
 +
    GWidgetInit wi;
 +
    gwinWidgetClearInit(&wi);
 
   
 
   
−
// Apply some default values for GWIN
+
    // Apply the label parameters
−
wi.customDraw = 0;
+
    wi.g.show = gTrue;
−
wi.customParam = 0;
+
    wi.g.y = 10;
−
wi.customStyle = 0;
+
    wi.g.x = 10;
−
wi.g.show = TRUE;
+
    wi.g.width = 100;
 +
    wi.g.height = 20;
 +
    wi.text = "Label 1";
 
   
 
   
−
// Apply the label parameters
+
    // Create the actual label
−
wi.g.y = 10;
+
    ghLabel1 = gwinLabelCreate(NULL, &wi);
−
wi.g.x = 10;
+
−
wi.g.width = 100;
+
−
wi.g.height = 20;
+
−
wi.text = "Label 1";
+
−
+
−
// Create the actual label
+
−
ghLabel1 = gwinLabelCreate(NULL, &wi);
+
 
}
 
}
 
   
 
   
−
int main(void) {
+
int main(void)
−
// Initialize the display
+
{
−
gfxInit();
+
    // Initialize the uGFX library
 +
    gfxInit();
 
   
 
   
−
// Set the widget defaults
+
    // Set the widget defaults
−
gwinSetDefaultFont(gdispOpenFont("UI2"));
+
    gwinSetDefaultFont(gdispOpenFont("UI2"));
−
gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);
+
    gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);
−
gdispClear(White);
+
    gdispClear(White);
 
   
 
   
−
// create the widget
+
    // Create the widget
−
createWidgets();
+
    createWidgets();
 
   
 
   
−
while(1) {
+
    while(1) {
−
gwinSetText(ghLabel1, "This is some text", TRUE);
+
        gwinSetText(ghLabel1, "This is some text", gTrue);
−
gfxSleepMilliseconds(1000);
+
        gfxSleepMilliseconds(1000);
−
gwinSetText(ghLabel1, "Aaaand some other text", TRUE);
+
 
−
gfxSleepMilliseconds(1000);
+
        gwinSetText(ghLabel1, "Aaaand some other text", gTrue);
−
}
+
        gfxSleepMilliseconds(1000);
 +
    }
 
   
 
   
−
return 0;
+
    return 0;
 
}
 
}
−
</syntaxhighlight>
+
</source>
  
 
[[Category:Widget]]
 
[[Category:Widget]]

Latest revision as of 13:38, 19 August 2021

A label is a simple rectangular widget which takes no input. The label will automatically redraw it the text changed. If the label is smaller than the text it displays, the text gets clipped. The text of the label can be set using the gwinSetText() routine.

API reference

The API reference of the label widget can be found here.

Border

The default drawing routine of the labels allows to enable or disable a border. This can be done using gwinLabelSetBorder().

Auto scale

Applying a size of 0 to the width or the height of the label will automatically set the corresponding dimension to fit the entire label text. Updating the label text will update the label dimensions each time. Note: If the the board is enabled the auto-sizing feature of the label will certainly change the look of the application.

Justification

By default the text of the label is left justified. The justification of the label text can be controlled through different built-in rendering functions.

The following rendering functions are available:

  • gwinLabelDrawJustifiedLeft
  • gwinLabelDrawJustifiedRight
  • gwinLabelDrawJustifiedCenter

Font size and color

As with any other widget the look-and-feel of the label widget can be fully customized. The font can be changed by using gwinSetFont() and the font color is controlled through the widget styles. The widget rendering can be fully customized by implementing a custom rendering routine.

Attribute

Often you want to display multiple text elements below each other where an element consists of a static text which will always be the same and some variable one. The static text is called the attribute and can be optionally set through gwinLabelSetAttribute() once you enabled this feature in your configuration file. The function does also take a tab parameter which allows to align multiple labels vertically as the following example shows: 

Current IP: 192.168.1.42
Netmask:    255.255.255.0
DHCP:       On

IMPORTANT: Use of the attribute capability is discouraged. This feature should be considered deprecated and will be removed in future releases. The proper way of doing this is using two separate labels.

Example

The following example shows how to create a label. 

#include "gfx.h"
 
static GHandle ghLabel1;
 
static void createWidgets(void)
{
    GWidgetInit wi;
    gwinWidgetClearInit(&wi);
 
    // Apply the label parameters
    wi.g.show = gTrue;
    wi.g.y = 10;
    wi.g.x = 10;
    wi.g.width = 100;
    wi.g.height = 20;
    wi.text = "Label 1";
 
    // Create the actual label
    ghLabel1 = gwinLabelCreate(NULL, &wi);
}
 
int main(void)
{
    // Initialize the uGFX library
    gfxInit();
 
    // Set the widget defaults
    gwinSetDefaultFont(gdispOpenFont("UI2"));
    gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);
    gdispClear(White);
 
    // Create the widget
    createWidgets();
 
    while(1) {
        gwinSetText(ghLabel1, "This is some text", gTrue);
        gfxSleepMilliseconds(1000);
 
        gwinSetText(ghLabel1, "Aaaand some other text", gTrue);
        gfxSleepMilliseconds(1000);
    }
 
    return 0;
}
Retrieved from "https://wiki.ugfx.io/index.php?title=Label&oldid=1938"