Home | pfodApps/pfodDevices | WebStringTemplates | Java/J2EE | Unix | Torches | Superannuation | CRPS Treatment | | About Us
 

Forward Logo (image)      

pfodWeb
Creating Reusable Controls

by Matthew Ford 4th October 2025 (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

Tutorial List

This is the fifth tutorial on using pfodWebDesigner 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.

pfodWebDesigner is a free web based replacement for the free Android app, pfodGUIdesigner. pfodWebDesigner allows you to design interactive and responsive user interfaces for your microprocessor. pfodWebDesigner generates Arduino code that works with all pfodDevices that connect via Bluetooth, BLE, SMS and WiFi, not just those that have WiFi support. See how to install pfodWebDesigner in the previous tutorial. Individual pfodWebDesigner 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.

pfodWeb is a free web based partial replacement for the paid Android app, pfodApp. pfodWeb runs in a browser and connects via http. ESP32, ESP8266 and Raspberry Pi Pico W microprocessors are supported. pfodWeb provides interactive and responsive web browser controls built with pfodWebDesigner. pfodWeb is a set of less than 200K of zipped javascript and html files that run in your browser and connect to your microprocessor, render the interface design and send the commands as the user interacts with it. The actual messages exchanged are tiny compared to a typical web page.

Introductory 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 a free web based version of the paid Android app, pfodApp. pfodWeb implements a significant subset of pfodApp's capabilities that is interactive dwgs.
Your micro serves all the necessary code to run the web page controls. No third party or internet access is needed.

If you want to support this work, purchase the Android pfodApp which will work with the same code developed here and which provides more features such as charting and data logging.
See the free pfodDesigner Android app for creating menus and charts for pfodApp.

Parts List and Installation

See the Introductory Tutorial for the parts list and the Installation instructions. Physical parts consist of just an ESP32, ESP8266, Pi PicoW/2W board, e.g. Dfrobot ESP32 board

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:-


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 popupHelp.json you can load into pfodWebDesigner or step through the build steps below.

Building the PopUp Help

Open pfodWebDesigner and start a new drawing, called popupHelp, 50 x 25 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_1, 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 14, Y transation 6, Scale 1, that you can edit to move all the following drawing items to a suitable position.

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

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

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

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

  6. Move the second, inner rectangles 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 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. ( (1,2) font size -2, centered) Use Index.

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

  4. Adjust the pushZero to (1,1) to position the button next to the text box.

  5. Add a second slightly small circle around the ?, for the background (radius 1.5, White). Use Index

  6. Move the circles above the ? Label and fill them in with the border (Black) and background (White) colors.


Adding the Help Button touchZone and touchActions

  1. Add a touchZone to cover the ? button (3.5 x 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_1, idx_2 and idx_3). 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 (idx_1, idx_2 and idx_3), when the button is pressed. The Replace on Touch drop down has an Unhide option at the bottom.


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. The popupHelp.json contains the completed control.

Reusing the popupHelp Control

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

To use the popupHelp control in your own GUI :-

  1. Make a copy of popupHelp (popupHelp.json) called sliderHelp.

  2. Load the SliderInputErr (SliderInputErr.json) drawing and make a copy called SliderWithHelp.

  3. Edit SliderWithHelp and add a pushZero to adjust the location and size of the popup help.

  4. Then use insertDwg to insert the sliderHelp.

  5. Change the pushZero scale to 4 to make the button visible.

  6. Add a popZero to close off the pushZero for this control.

That provides a popup help button at the top left of the slider as shown above.
If you find that the ? is missing, go back and edit the sliderHelp to make the ? Lable color Black, 0. instead of BLACK_WHITE

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.

To put the help button in the top right hand corner of the slider control :-

  1. Go back the the Control Panel and Edit the sliderHelp drawing.

  2. Edit the pushZero item that starts the help button section of the control (the second pushZero) and make the X Translation 26 to move the whole help button to the to right hand corner of the text box

  3. Go back to the Control Panel and edit the SliderWithHelp drawing.

  4. Edit the pushZero that precedes the the sliderHelp insertDwg item and make the X Translation 70 to position the help button at the top right.

Completing the Code

Having completed the drawing with the popup help (at top right), export the Arduino code, Dwg_SliderWithHelp.zip.
Open Arduino IDE 2 and save the previous tutorial's SliderInputErr sketch (SliderInputErr.zip) as SliderWithHelp. Then unzip the Dwg_SliderWithHelp.zip to that sketch directory, replacing any existing files. That will update the pfodMainDrawing files and add the new Dwg_sliderHelp and Dwg_SliderWithHelp files. The existing SliderInputErr files are unchanged and you can then merge their code additions into the new Dwg_SliderWithHelp.cpp file.

Note: If the Arduino linker complains of duplicate symbols, it has not cleared out the old cached compiled files. Change the board to a different one (any one) and start a compile. Then cancel the compile and change back to the correct board and re-compile.

Testing this slider in pfodApp showed the text box was a bit small for easy reading. That was quickly fixed by increasing the scaling of the inserted drawing sliderHelp. This also made the help button larger so its scaling in sliderHelp was reduced.

Finally, each time the help text is viewed the microprocessor (pfodDevice) sends the whole help text again as an update. This is not necessary as the help text is fixed. In bool Dwg_sliderHelp::processDwgCmds() replace sendUpdate() with parserPtr->print(“{}”); 

  //sendUpdate();
  parserPtr->print("{}"); // empty msg response

Every message must be responded to, but sending the unchanged help text is redundant. Just sending an empty response {} saves bandwidth.
The completed code in in SliderWithHelp.zip

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.

AndroidTM 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.

Forward home page link (image)

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