pfodWeb
Control re-use with insertDwg

by Matthew Ford 24th July 2025 (originally posted 24th July 2025)
© Forward Computing and Control Pty. Ltd. NSW Australia
All rights reserved.

How to Re-use Controls
in you pfodApp and pfodWeb GUI's
with the insertDwg msg

Tutorial List

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.

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 – This one. Covers copying dwgs and using insertDwg to insert multiple copies into the main drawing.
more tutorials will follow

Introduction

This is the second tutorial on using pfodWeb Designer to create interactive and responsive GUI for pfodApp and the free, open source, pfodWeb.
This tutorial will cover making copies of an existing control and inserting multiple controls into a single, main, drawing, handling the commands sent and updating the GUI with the current state.
Your micro serves all the necessary code to run the web page controls. No third party js libraries or internet access is needed.

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 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 board, e.g. Dfrobot ESP32 board.

Copying Drawings

This tutorial builds on the previous one, but you can start here by loading this file, LedOnOff.json, into pfodWeb designer.

Having loaded the LedOnOff drawing, click Copy to make a copy. Call it LedOn. Then Edit LedOn and change the Label text to Turn Led On
Having changed the label text, go back to the control panel and save the LedOn drawing.
Then make another copy called LedOff and edit it to have a white text, Turn Led Off, on a black rectangle and save that drawing as well.

Use Index

Note that the label still needs to be indexed even though it will not be updated AND it needs to be below the indexed rectangle is the list of drawing items.
This is because indexed items are layered (drawn) in order of their numeric index which is assigned by pfodParser in the order the item is processed for sending to pfodApp/pfodWeb. Higher indices go on top.

The rectangle needs to be indexed so it has a reference for updating when 'touched'. If you un-index the label or move it above the rectangle, it will be completely covered and will not be visible.

Items without Use Index ticked are drawn first in the order they are received. That is in the order they appear in the list of item. Then indexed items are drawn in index order. The order they appear in the list.
The index name under Use Index is the name of the code variable that holds the numeric index. Changing that name has no effect on the index assigned.

Inserting Drawings in the Main Drawing

Create a new drawing called TwoButtons. Size 40 x 15, Silver (light Grey, Color 7) background and 5sec refresh.

Open it in Edit and Add New Item and choose Insert Drawing.
From the drop down list of loaded drawings choose LedOn

Note: The background color of the LedOn dwg is ignored. Only its drawing items are added. Any refresh interval set on an inserted drawing is also ignored. The refresh interval of the main drawing is used.

The Default Scaling of Inserted Drawings

By default when you insert a drawing to occupies its original dimensions. So inserting a 50 x 25 sized drawing in a 40 x 15 main drawing will clip the inserted drawing.

Panning the Inserted Drawing

You can reposition the inserted drawing by using its X and Y zero settings. These set the Column,Row value of the inserted drawing that is positioned at (0,0) in the main drawing.
Increasing the X,Y moves the inserted drawing to the left and up. Negative and floating point numbers are accepted. Try changing the values and see how the inserted drawing re-positions.
Reset them to 0,0 and click Add Item.

pushZero and popZero

As you can see from above, the inserted drawing is the wrong size and in the wrong position. The pushZero command changes the position and scale for all following drawing items, until a matching popZero is found.
pushZero commands can be nested so you can use them in the main and inserted drawings.

Click Add New Item again and add a pushZero item and click Add Item to accept it. Then in the Item List click the up arrow for the pushZero to move it above the insertDwg.

Then click on Edit in the pushZero row to edit it in its new position. Set the scale factor to 0.5 and adjust the X, Y to position the inserted LedOn drawing.

Click Update Item to save the changes.

Insert the second LedOff drawing. You can either add a popZero and another pushZero, or it is easier just add another pushZero which will inherit the 0.5 scaling and Y translation that currenlty in effect.
This will keep the LedOff drawing with the same scale and Y position as the LedOn drawing. The new pushZero has an X translation of 33 to position the LedOff to the right of the LedOn dwg.

Finally add an indexed label to the main drawing to show the current state of the Led on or off. It is indexed because the label will be updated with the current led state.
But first add top popZeros to restore the (0,0) position and scaling of the main drawing.
Remember you can use floating point numbers for the X,Y positions to put the label just where you want it.

To back to the Control Panel and save the TwoButtons drawing. This will also prompt you to save the inserted dwgs as well. You can also view the final design from there.
Then click the Arduino Export button to generate the Arduino code.
That Arduino code zip file, Dwg_TwoButtons.zip, also includes the json files the all the drawings so you can reload them for later editing.

Get a clean copy of pfod_ESP32 and unzip the Dwg_TwoButtons.zip to that directory and compile and upload to your ESP32. That will display the basic display on either pfodApp or pfodWeb.

Handling the Button commands to complete the Code

The sketch needs code to turn the board led on and off as the buttons are clicked and to update the “Led is Off” text to reflect the current led state. The final code is in pfodWeb_ESP32_TwoButtons.zip

In the pfod_ESP32.ino file, add the methods to turn the led on and off. These are copied from the LedOnOff example in the previous tutorial.

int ledPin = BUILTIN_LED; //D9 on Dfrobot FireBeetle 2 ESP32-E
bool ledOn = false;

void setLedOn() {
  pinMode(ledPin,OUTPUT);
  digitalWrite(ledPin,HIGH);
  ledOn = true;
}
void setLedOff() {
  pinMode(ledPin,OUTPUT);
  digitalWrite(ledPin,LOW);
  ledOn = false;
}

void toggleLed() {
  if (ledOn) {
    setLedOff();
  } else {
    setLedOn();
  }
}

In Dwg_TwoButtons.cpp file update the sendIndexedItems() to reflect the current state of the led. Add an extern bool ledOn; to the top of the file to access the current led state from pfod_ESP32.ino

extern bool ledOn;
. . . 
void Dwg_TwoButtons::sendIndexedItems() {
  if (ledOn) {
    dwgsPtr->label().idx(idx_1).color(dwgsPtr->RED).text("Led is On").bold().offset(20,11.5).center().decimals(2).send();
  } else { // off  
    dwgsPtr->label().idx(idx_1).color(dwgsPtr->BLACK).text("Led is Off").bold().offset(20,11.5).center().decimals(2).send();
  }  
}

Then in the Dwg_LedOff.cpp file add

extern void setLedOff();

to access the method in the pfod_ESP32.ino file and in the bool Dwg_LedOff::processDwgCmds() method add setLedOff(); and comment out sendUpdate(); and return true;

bool Dwg_LedOff::processDwgCmds() {
// byte dwgCmd = parserPtr->parseDwgCmd(); // pfodParse calls this automagically before calling this method
  if (!(*(parserPtr->getDwgCmd()))) {  // ==> getDwgCmd returned pointer to empty string
    return false; // not dwg cmd, not handled
  }
  if (parserPtr->dwgCmdEquals(cmd_c1)) { // handle touchZone cmd_c1
    setLedOff();      // add your cmd handling code here
    //sendUpdate(); // don't send update from here
    //return true; // don't mark this command as being handled
  }

  // Serial.print("dwgCmd did not match:");Serial.println(cmd_c1);
  return false; // not handled
}

Do a similar change for Dwg_LedOn::processDwgCmds(), using setLedOn().

When the Turn Led Off or Turn Led On button is pressed, the pfodParser first passes the command to each registered drawing for it to process. In this case Dwg_LedOff::processDwgCmds() will match the the Turn Led Off button command and set the Led off. But returning false, from processDwgCmds() allows the command to propagate up to the top level of the parser processing in pfodMainMenu.cpp There the processing for menu item A, which holds the main drawing, will call send MainMenuUpdate which reload the main dwg with the updated Led state.

The debug output from pfodMainMenu.cpp is

Handling Menu Cmd 'A'
     touchZone cmd c3 at (8,4) touch type:TOUCHED

The result is the animated GUI at the top of this page. As you select the button it immediately changes color and sends a command to the ESP32 to change LED state. When the ESP32 responds, its message sets the buttons new color and the new text.

Updating Drawing Code

After the first design you may want to revise the GUI's colors, size, position etc. After you generate the new Arduino code zip file, use a file comparison tool like Beyond Compare to transfer the GUI changes to your project without disturbing the command processing code you have added.

Conclusion

This page covered using insertDwg to re-use controls. It also covered using pushZero / popZero to change the scaling and the (0,0) of following drawing items.
The example used was TwoButtons, shown at the top of the page.

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.

pfodWeb Control re-use with insertDwg

How to Re-use Controlsin you pfodApp and pfodWeb GUI'swith the insertDwg msg