pfodWeb Creating Reusable Controls

by Matthew Ford 15^th August 2026 (originally posted 27th August 2025)
© Forward Computing and Control Pty. Ltd. NSW Australia
All rights reserved.

How to Build Reusable Controls
for your pfod User Interface

Introduction

This is the fifth tutorial on using pfodWeb Dwg Designer to create interactive and responsive GUI for pfodApp and the free, open source, pfodWeb.
This tutorial will cover building a reusable popup help component you can add to your GUI designs.
Your microprocessor serves all the necessary code to run the web page controls. No third party javascript libraries or internet access is needed.
Your microprocessor pre-loads the help message on the display and a ? button displays it while the mouse is held down.

pfodWeb.html is a free web based replacement for the paid Android app, pfodApp. pfodWeb.html runs in any browser and connects to your Arduino board via either Serial, Classic Bluetooth, BLE, TCP/IP socket or HTTP. Using Serial you can connect to any Arduino board and display the interactive controls it serves. pfodWeb.html runs competely off-line. No internet connection is needed. See pfodWeb Quick Start for installation setup.

The interactive controls are completely defined by the code (generated by pfodWeb Designer) in your Arduino. Very compact pfod messages are used to send the controls and receive the user's commands.
If your Arduino board supports HTTP and has a file system with 550Kb free, then you can load the pfodWeb.html files onto your microprocessor and serve them directly from there.

pfodWeb Dwg Designer is just another connection option in pfodWeb.html. It provides a free web based replacement for the free Android apps, pfodDesignerV3 and pfodGUIdesigner. PfodWeb's Designer allows you to design interactive and responsive user interfaces for your microprocessor. The Designer generates Arduino code that works with all pfodDevices that connect via Serial, Bluetooth, BLE, SMS and WiFi, not just those that have WiFi support. Individual pfodWeb Designer dwg controls are stored as JSON files which you can duplicate, modify and reuse in other designs. Each reused control can be individually scaled and positioned in the final design.

Tutorial List

Introductory pfodWebDesigner Tutorial – Covers setting up the pfodWeb Designer local server and install the pfodWeb support on an ESP32. A simple press button example illustrates touchZone and touchAction.
Reuse Controls with insertDwg – Covers copying dwgs and using insertDwg to insert multiple copies into the main drawing.
touchActions for Instant Feedback – Covers using touchActions to give instant feedback in a slider control.
TouchActionInput for text/number entry – Covers using touchActionInput to input text / numbers to your micro
Building Reusable Controls – This one. Covers building a reusable popup help button component.

Support pfodWeb

pfodWeb is free and open source. If you want to support this work, purchase the Android pfodApp which will work with the same code developed here.

Parts List and Installation

See the Introductory Tutorial for the parts list and the Quick Start instructions.
The tutorial uses the SafeString library to safely copy text and validate number inputs. Install the SafeString library using the Arduino Library manager.
Arduino Mega or higher recommended for these tutorials.
The complete source code for pfodWeb.html is available in pfodWeb_src.zip and on Github.

Note: The final sketch, SliderWithHelp, is too large for an Arduino UNO, you need to use a board with more memory such as Arduino Mega.

PopUp Help Design

This control uses the tools and drawing objects covered in the previous tutorials, Rectangles, indexed items, touchActions, hide / unhide and insertDwg to add the control to the main drawing

The design of the popup help is as follows:-

• Two filled, indexed rectangles providing a background box and border for the help text.

• A multi-line label of the help text.

• All of these drawing items are normally hidden.

• The help ? button is a filled circle with a ? in it and a touchZone covering it.

• The touchZone has a number of touchActions which unhide the help text, and its background, while the mouse is held down on the help button.

• When the mouse is release, the original drawing , with the help box hidden, is restored.

• The touchZone sends a message to the pfodDevice (your microprocessor) when it is triggered, but the code just ignores that.

This control will be the last one added to the main drawing using insertDwg. Inserting the drawing last ensures it is assigned the highest index numbers so that the help box and text and help button will overlay all other components of the GUI

Here is the completed sketch, popUpHelp_serial.zip. You can load the popUpHelp.pfodDwg_json into pfodWeb Dwg Designer or step through the build steps below.

Building the PopUp Help

Open pfodWeb Dwg Designer and start a new drawing, called popUpHelp, 50 x 30 with a neutral (grey, 7) background and no refresh. You can adjust the drawing size once you have laded out the help box and button. The background colour will be discarded when this control in inserted in the main drawing.

The help text will be for the previous slider example.
Drag the slider to adjust it
OR
Click on the Slider ...% text
to set a value.

NOTE: All these drawing items (except pushZero/popZero) have Use Index ticked. The index names, idx_buttonTxt, etc are variable names. The actual index numbers are assigned in order the drawing elements are listed.

The Help Text Box

The help text box consists of two fill rectangles and the multi-line text. The larger, outer rectangle forms the border. While the smaller, inner rectangle sets the background colour for the text box.

1. Add a pushZero, X transation 15, Y transation 7, Scale 1, that you can edit to move all the following drawing items to a suitable position.

2. Add a label, offset(0,0) to the drawing containing the multi-line line text, above. Choose a suitable color (Blue, 12) and font size, -4 and alignment Center. Set Use Index, idx_helpTxt

3. Add a rounded rectangle, centered, offset(0,0) (unfilled for now) to enclose the text (24 x 10, Black). When filled this will be the border. Set Use Index. idx_helpBorder.

4. Add another rounded rectangle, centered, offset(0,0) (unfilled for now) inside the last one (23 x 9, White). When filled this will be the text background color. Set Use Index, idx_helpBkgn

5. Move the first, outer rectangle, idx_helpBorder, above the label in the drawing items list and edit it to be filled with the border color, Black

6. Move the second, inner rectangle, idx_helpBkgn, above the label in the drawing items list and edit it to be filled with the text background color, White.

7. Add a popZero at the bottom of the list to close out the pushZero.

The Help Button

The help button consists of a two circles, border and text background, in which a ? is placed. A touchZone is placed around the button, which when triggered will unhide the help text box while the mouse is held down.

1. Add a pushZero (1,0) to start the help button layout. This can be used later to position the help button on any corner of the help text box.

2. Add a ? in a label (color Black, 0) and position it, offset(1,2) font size -2, centered) Use Index, idx_buttonTxt

3. Add a circle around the ?, for the border, offset(1,1.8) ,radius 1.8, Black). Use Index, idx_buttonBorder.

4. Add a second slightly small circle around the ?, for the background offset(1,1.8), radius 1.5, White). Use Index, idx_buttonBkgn.

5. Move the circles above the ? label and fill them in with the border (Black) and background (White) colors to form a white button with a black border.

Adding the Help Button touchZone and touchActions

1. Add a touchZone to cover the ? button offset(1,1.8) size(3.5,3.5) and centered on it, with the filter, DOWN_DRAG_UP, which will keep the help showing until the mouse is released.

2. Add a popZero to close out the help button's pushZero and keep help button and its touchZone in the same push/pop zero group.

3. Add hide items for each of the text box items, the two rectangles and the label, (idx_helpBorder, idx_helpBkgn and idx_helpTxt). This will make them disappear from the preview and this will be how they will be normally when not triggered by the ? help button.

4. Edit the ? button touchZone to add three touchActions to unhide the text boxes and label, when the button is pressed. The TARGET INDEXT ITEM drop down has an Unhide invisable Item at the bottom. You can use the eye icon to flash the item to see where it is. Hidden items will be come unhidden, visible items will be hidden.

Clicking the help button in the preview now shows the help text box while the mouse is held down.
If the help text just flashes, go back and edit the touchZone to have filter DOWN_DRAG_UP, instead of the default TOUCH

The completed popUpHelp Control

Trim the size of the drawing to better enclose the control, say 30 x 15. That completes the basic popUpHelp control.
Use Generate Code to export the Arduino sketch, popUpHelp_serial.zip, that displays this popUpHelp control.
If you find that the ? is missing, go back and edit the popUpHelp to make the ? Label color Black, 0. instead of BLACK_WHITE

Reusing the popupHelp Control

Here the popupHelp control will be added to the SliderInputErr drawing from the previous tutorial. The completed drawing is SliderWithHelp.zip

To add the popUpHelp control in your own GUI :-

1. Load the SliderInputErr.pfodDwg_json and popUpHelp.pfodDwg_json drawings into pfodWeb Dwg Designer

2. Create a new drawing SliderWithHelp, 110 x 45, BLUE background.

3. Edit SliderWithHelp and insert the SliderInputErr drawing

4. Add a pushZero(2, 2, 2.5) to position (2,2) and scale 2.5, the popUpHelp drawing

5. Insert the popupHelp drawing and close with a popZero.

6. Generate the SliderWithHelp.zip file and add the SliderControl files and replace the SliderInputErr files with the completed code from the previous tutorial.

That provides a popup help button at the top left of the slider as shown above.
Note that the popupHelp drawing is inserted last, this ensures that when the idx numbers are allocated when the drawings are sent, that all the popupHelp items have higher indices then any other drawing item so that they always display on top when visible.

Completing the Code

Use Generate Code to export the SliderWithHelp_serial.zip Arduino sketch files. Unzip to your Arduino sketch directory.
Note: This SliderWithHelp sketch is too large for an Arduino UNO, you need to use a board with more memory such as Arduino Mega.

Inserting existing drawing controls into a new drawing, keeps their file names unchanged when the Arduino code is generated so you can just copy over the SliderInputErrorControl.cpp / .h files from the previous tutorial to get the complete working sketch. SliderWithHelp.zip has this completed sketch with the SliderInputErrorControl files.

Placing the Help Button Top Right

The popUpHelp control can be customized to suit various situations. As well as editing the help text, you can easily change the position of the help text box relative to the ? button by editing the popUpHelp dwg to position the ? at the top right and then adjust the pushZero in the SliderWithHelp drawing to position the whole popupHelp to the right.

Optimization to Reduce Message Size

The code generated for popUpHelp puts all the indexed items in the Dwg_popUpHelp::sendIndexedItems() method. Usually indexed items are the ones update. However in this case once the text is sent in this example it does not change, but with those items appearing in the sendIndexedItems() method which is called from Dwg_popupHelp::sendUpdate() each time the ? Button is released, all the text is sent again.

Commenting out the sendIndexedItems() call from the sendUpdate() method eliminates the resending the static help text every time the help button is released or the drawing is refreshed.

void Dwg_popUpHelp::sendUpdate() {
    dwgsPtr->startUpdate();
  //  sendIndexedItems(); // not send indexed item in update as nothing changes
    dwgsPtr->end();
}

1024 byte Message Limit for pfodDevice msgs

There is a 1024 bytes hard limit for messages sent to pfodWeb.html (and pfodApp) from the pfodDevice, the microprocessor. This limits the complexity of dwgs. The message size of each drawing is shown in its description. E.g. 308 bytes for the popUpHelp dwg.

If a drawing exceeds the 1024 limit, it will still be drawn, but parts of the drawing will be missing. The solution is to split large drawings into multiple smaller dwgs that are inserted in the final drawing. Each inserted dwg has its own 1024 byte limit.

Conclusion

This page covered designing a re-usable control, in this case a popUpHelp control, that can be copied and customized and added you any of your own GUIs. The result is instant display of help text while the ? button is pressed regardless of how slow the connection the microprocessor is.

Android^TM is a trademark of Google Inc. For use of the Arduino name see http://arduino.cc/en/Main/FAQ

The General Purpose Android/Arduino Control App.
pfodDevice™ and pfodApp™ are trade marks of Forward Computing and Control Pty. Ltd.

Contact Forward Computing and Control by
©Copyright 1996-2024 Forward Computing and Control Pty. Ltd. ACN 003 669 994