web analytics
July 12, 2015

Widgets – Introduction

widgets

Phoenard has many cool widgets for you to use. But what are widgets exactly?

Widgets are small programs that handle the display of content and (touch) input for a portion of the screen. Widgets are buttons, sliders, text fields, graphs, lists and keyboards. Widgets make it much easier to quickly add user input to your sketch, not requiring a single draw function to get it started. They are also customizable: the size, scale, borders and color layout of all widgets can be changed easily.

For a full list of widget functions, see the documentation.

Usage

All widgets are used very similarly:

  1. Define the widget in your sketch
  2. Set the widget bounds (position and size)
  3. Set widget-specific settings
  4. Add the widget to the display
  5. Update the display routinely
  6. Check for changes (events) after the display update

In code, this looks like this:

#include "Phoenard.h"

PHN_Button myButton; // Define it

void setup() {
  // Setup and add to display
  myButton.setBounds(30, 30, 80, 40);
  myButton.setText("Test!");
  myButton.setColor(FOREGROUND, GREEN);
  display.addWidget(myButton);
}

void loop() {
  // Update the screen and all widgets
  display.update();
 
  // Handle button clicks
  if (myButton.isClicked()) {
    // Code run when clicked goes here
  }
}

 

Dialogs

When building dialogs and menus in a more advanced interface, you need to remove widgets when a dialog closes. This means widgets come and go, and special care must be taken so that no strange glitches occur.

The following code example shows how you can handle a dialog-based system:

void showDialog() {
  // Define, setup and add to display
  PHN_Button myButton;
  myButton.setBounds(30, 30, 80, 40);
  myButton.setText("Test!");
  myButton.setColor(FOREGROUND, GREEN);
  display.addWidget(myButton);
  
  // Add another widget
  PHN_Label myLabel;
  myLabel.setBounds(120, 30, 80, 40);
  display.addWidget(myLabel);
  
  // Update until the button is clicked
  while (true) {
    display.update();
    
    // Update value displayed in label
    myLabel.setText(analogRead(A0));
    
    if (myButton.isClicked()) {
      // Button click user code goes here
      
      // Exit the update loop
      break;
    }
  }
  
  // Remove widgets again on function end
  display.removeWidget(myButton);
  display.removeWidget(myLabel);
  
  // Alternative: remove all widgets added to the display
  // display.clearWidgets();

  // Note: When this function ends, the above declared
  // widgets become unusable
}

 

What you should not do

Do not create temporary widgets and add them to the display where the scope of the widget is lost. Losing scope, means that the widget is defined inside a function or block of code, getting deleted when the function or block of code ends. For example, the following will not work:

#include "Phoenard.h"

void setup() {
  PHN_Label myLabel;
  myLabel.setBounds(30, 30, 80, 40);
  myLabel.setText("Test!");
  display.addWidget(myLabel);
}

void loop() {
  display.update();
}

 

Widget documentation

You can find widget-specific usage examples down below: