Customising input and display tcMenu plugins

Sometimes the input or rendering capabilities of the built in plugins may not be customisable enough for your needs. In these cases it is possible to either write a custom renderer from scratch, or more likely alter the stock renderer to work how you want it to.

This article assumes you are customising an input or display renderer plugin, so that it handles input or displays content differently, rather than building one from scratch. Note that this is an advanced topic and requires considerable C++ experience.

Moving from existing driver to custom driver

Firstly, build your menu along with the display driver for your display. This will put the rendering files into your project that are compatible with your display. It is recommended at this point that you ensure all is working, before moving forward to make any modifications.

Generally the first step is to locate and then rename the renderer header and source file. These will normally contain the name of the underlying driver such as u8g2 for example. You should rename these files in order to avoid them being overwritten by any future operations in the designer UI.

Next in the designer UI’s code generator dialog, change the display type to custom display. This means that the designer will no longer manage the display code for you, and you’ll be free to adjust as needed.

That’s it, at this point you can make adjustments to the renderer safely, without risking the changes being lost by round-tripping with the designer.

More detail on display drivers

Nearly all real world rendering classes extend from the base renderer BaseMenuRenderer and they will override the render function. Before trying to modify the class you should probably read through the API documentation, especially look at the documenation for file BaseRenderers.h. Never make changes to files inside tcMenu library, these will be overwritten in future updates.

There’s also a dialog class within most renderers that will normally extend from BaseDialog. The API documentation for this is in BaseDialog.h. If you want to also override how dialogs look, you’ll need to change the rendering here too.

More detail on how menu input works

Most of the input plugins work based on IoAbstraction’s switches SwitchInput class. It’s worth fully understanding this class, as it’s used by most input methods in tcMenu. Generally speaking the generator will add code to the setupMenu() method that’s located in the <projectName>_tcMenu.cpp. Do not directly modify this file. Instead, follow the steps below:

• Select no input for the input type in the generator.
• In the setup of your application prepare your own input facilities.
• When your equivalent of the OK button is pressed, call menuMgr.onMenuSelect(buttonHeld); where button held indicates if the button is held down.
• The standard renderer is based on values being chosen based on values between 0 and a maximum value. Generally this is done by a rotary encoder (or a simulation thereof). If you are not using a rotary encoder you’d probably still need to implement RotaryEncoder using the interface to capture the changes in range when menus are selected or editing starts. See the IoAbstraction documentation around rotary encoders.

Back to tcMenu main page