API Reference

Core Classes

struct App

Convenience struct for managing a TUI application.

This class holds the pvtui::ArgParser, pvtui::PVGroup, pvac::ClientProvider, and ftxui::ScreenInteractive to reduce boilerplate in PVTUI applications.

Public Functions

App(int argc, char *argv[])

Constructs an App which internally manages a pvac::ClientProvider pvtui::PVGroup, pvtui::ArgParser, and ftxui::ScreenInteractive.

Parameters:

  • argc – Command line argument count

  • argv – Command line arguments

void run(const ftxui::Component &renderer, int poll_period_ms = 100)

Runs the main FTXUI loop.

Parameters:

  • renderer – The ftxui::Component which defines the application layout

  • poll_period_ms – Render loop polling period in milliseconds

Public Members

std::function<void(App&, const ftxui::Component&, int)> main_loop

The main loop function to run with App::run. Can be redefined by the user.

pvtui::ArgParser args

pvtui::ArgParser to store the cmd line arguments

pvac::ClientProvider provider

EPICS client provider.

PVGroup pvgroup

pvtui::PVGroup to manage PVs used in the application

ftxui::ScreenInteractive screen

screen instance for FTXUI rendering

class ArgParser

Parses command-line arguments for PVTUI applications.

Handles macro definitions similar to MEDM, and any additional flags

Public Functions

ArgParser(int argc, char *argv[])

Constructs an ArgParser from command-line arguments.

Parameters:

  • argc – Argument count.

  • argv – Argument values.

bool macros_present(const std::vector<std::string> &macro_list) const

Checks if all specified macros are present in the parsed arguments.

Parameters:

macro_list – A list of macro names to check.

Returns:

True if all macros are present, false otherwise.

template<typename T>
inline bool help(const T &msg)

Prints a help message and returns true if help flags given.

Parameters:

msg – The help message, as a type streamable to std::cout

Returns:

True if help flag present, false otherwise

bool flag(const std::string &f) const

Checks if a specific command-line flag is set.

Parameters:

f – The flag name (e.g., “-h”, “–version”).

Returns:

True if the flag is present, false otherwise.

std::string replace(const std::string &str) const

Replaces macros in a string with their corresponding values.

Parameters:

str – A string with macros like , , etc.

Returns:

A new string with all macros replaced by their values.

Public Members

std::unordered_map<std::string, std::string> macros

Parsed macros (e.g., “P=VAL”).

std::string provider = "ca"

The EPICS provider type (e.g., “ca”, “pva”).

struct PVGroup

Manages a collection of EPICS Process Variables (PVs).

This class provides a centralized way to add, access, and monitor a group of PVs, handling the underlying connections and data updates.

Public Functions

PVGroup(pvac::ClientProvider &provider, const std::vector<std::string> &pv_list)

Constructs a PVGroup and initializes it with a list of PVs.

Parameters:

  • provider – The PVA client provider.

  • pv_list – A list of PV names to add to the group.

PVGroup(pvac::ClientProvider &provider)

Constructs an empty PVGroup.

Parameters:

provider – The PVA client provider.

void add(const std::string &pv_name)

Adds a new PV to the group.

Parameters:

pv_name – The name of the PV to add.

Throws:

std::runtime_error – if a PV with the same name already exists.

template<typename T>
inline void set_monitor(const std::string &pv_name, T &var)

Registers a variable to be updated by a specific PV in the group.

Template Parameters:

T – The type of the variable to monitor.

Parameters:

  • pv_name – The name of the PV to monitor.

  • var – A reference to the variable that will be updated.

Throws:

std::runtime_error – if the PV is not found in the group.

PVHandler &get_pv(const std::string &pv_name)

Retrieves a PVHandler from the group by its name.

Parameters:

pv_name – The name of the PV to retrieve.

Throws:

std::runtime_error – if the PV is not found.

Returns:

A reference to the corresponding PVHandler object.

std::shared_ptr<PVHandler> get_pv_shared(const std::string &pv_name)

Returns a shared_ptr<PVHandler> from the group by its name.

Parameters:

pv_name – The name of the PV to retrieve.

Throws:

std::runtime_error – if the PV is not found.

Returns:

A shared_ptr<PVHandler> to the corresponding PVHandler object.

PVHandler &operator[](const std::string &pv_name)

Provides array-like access to a PVHandler in the group.

Parameters:

pv_name – The name of the PV to access.

Throws:

std::runtime_error – if the PV is not found.

Returns:

A reference to the corresponding PVHandler object.

bool sync()

Checks if any PV in the group has received new data.

Returns:

True if new data is available in any monitor, false otherwise.

struct PVHandler : public pvac::ClientChannel::MonitorCallback

Manages a single EPICS Process Variable (PV).

Handles connection, monitoring, and value updates for a PV.

Public Functions

PVHandler(pvac::ClientProvider &provider, const std::string &pv_name)

Constructs a PVHandler.

Parameters:

  • provider – PVA client provider.

  • pv_name – Name of the process variable.

bool connected() const

Checks if the PV channel is connected.

Returns:

True if connected, false otherwise.

bool sync()

Safely copies the internal monitored value to the user variable.

Returns:

True if new data is available, false otherwise.

template<typename T>
inline void set_monitor(T &var)

Registers a variable to be updated when the PV monitor receives new data and sync() is called.

Template Parameters:

T – The type of the variable to monitor.

Parameters:

var – A reference to the variable that will be updated.

inline pvac::Monitor &get_monitor()

Gets the underlying PVA monitor instance.

Returns:

A reference to the pvac::Monitor object.

inline std::shared_ptr<ConnectionMonitor> get_connection_monitor() const

Gets a shared_ptr to the ConnectionMonitor.

Returns:

A shared_ptr to the ConnectionMonitor

Public Members

pvac::ClientChannel channel

PVA client channel.

std::string name

Name of the process variable.

UI Widgets

class InputWidget : public pvtui::WidgetBase

An editable input field linked to a PV.

Supports typed PV put operations (int, double, string).

Public Functions

InputWidget(PVGroup &pvgroup, const ArgParser &args, const std::string &pv_name, PVPutType put_type, InputTransform tf = nullptr)

Constructs an InputWidget with macro expansion.

Parameters:

  • pvgroup – The PVGroup managing the PVs used in this widget.

  • args – ArgParser for macro replacement.

  • pv_name – The PV name with macros, e.g. “$(P)$(M).VAL”.

  • put_type – Specifies how the input value is written to the PV.

  • tf – optional ftxui transformation function

InputWidget(PVGroup &pvgroup, const std::string &pv_name, PVPutType put_type)

Constructs an InputWidget with an already expanded PV name.

Parameters:

  • pvgroup – The PVGroup managing the PVs used in this widget.

  • pv_name – The PV name.

  • put_type – Specifies how the input value is written to the PV.

InputWidget(App &app, const std::string &pv_name, PVPutType put_type)

Constructs an InputWidget from an App class.

Parameters:

  • app – A reference to the App.

  • pv_name – The PV name.

  • put_type – Specifies how the input value is written to the PV.

const std::string &value() const

Gets the current value of the string displayed in the UI.

Returns:

The current string value from the UI.

class ButtonWidget : public pvtui::WidgetBase

A simple button widget that writes a fixed value when pressed.

Public Functions

ButtonWidget(PVGroup &pvgroup, const ArgParser &args, const std::string &pv_name, const std::string &label, int press_val = 1)

Constructs a ButtonWidget with macro expansion.

Parameters:

  • pvgroup – The PVGroup managing the PVs used in this widget.

  • args – ArgParser for macro replacement.

  • pv_name – The PV name with macros, e.g. “$(P)$(M).VAL”.

  • label – The text displayed on the button.

  • press_val – The value written to the PV on press.

ButtonWidget(PVGroup &pvgroup, const std::string &pv_name, const std::string &label, int press_val = 1)

Constructs a ButtonWidget with an expanded PV name.

Parameters:

  • pvgroup – The PVGroup managing the PVs used in this widget.

  • pv_name – The PV name.

  • label – The text displayed on the button.

  • press_val – The value written to the PV on press.

ButtonWidget(App &app, const std::string &pv_name, const std::string &label, int press_val = 1)

Constructs a ButtonWidget from an App class.

Parameters:

  • app – A reference to the App.

  • pv_name – The PV name.

  • label – The text displayed on the button.

  • press_val – The value written to the PV on press.

template<typename T>
class VarWidget : public pvtui::WidgetBase

A read-only widget that monitors a PV but has no visible UI component.

This is useful for tracking a PV’s value (e.g., a readback) and making it available to other parts of the application without rendering it directly.

Template Parameters:

T – The C++ type used to store the PV value.

Public Functions

inline VarWidget(PVGroup &pvgroup, const ArgParser &args, const std::string &pv_name)

Constructs a VarWidget with macro expansion.

Parameters:

  • pvgroup – The PVGroup managing the PVs used in this widget.

  • args – ArgParser for macro replacement.

  • pv_name – The PV name with macros, e.g. “$(P)$(M).VAL”.

inline VarWidget(PVGroup &pvgroup, const std::string &pv_name)

Constructs a VarWidget with a fully expanded PV name.

Parameters:

  • pvgroup – The PVGroup managing the PVs used in this widget.

  • pv_name – The PV name.

inline VarWidget(App &app, const std::string &pv_name)

Constructs a VarWidget from an App class.

Parameters:

  • app – A reference to the App.

  • pv_name – The PV name.

inline const T &value() const

Gets the current value of the variable for use with the UI.

Returns:

The current value stored in the widget.

ftxui::Component component() const = delete

This widget does not have a UI element, so the component method is deleted.

class ChoiceWidget : public pvtui::WidgetBase

A widget for selecting an enum-style PV value from a list.

Supports vertical, horizontal, or dropdown layout styles.

Public Functions

ChoiceWidget(PVGroup &pvgroup, const ArgParser &args, const std::string &pv_name, ChoiceStyle style)

Constructs a ChoiceWidget with macro expansion.

Parameters:

  • pvgroup – The PVGroup managing the PVs used in this widget.

  • args – ArgParser for macro replacement.

  • pv_name – The PV name with macros, e.g. “$(P)$(M).VAL”.

  • style – Layout style (vertical, horizontal, dropdown).

ChoiceWidget(PVGroup &pvgroup, const std::string &pv_name, ChoiceStyle style)

Constructs a ChoiceWidget with a PV name without macros.

Parameters:

  • pvgroup – The PVGroup managing the PVs used in this widget.

  • pv_name – The PV name.

  • style – Layout style (vertical, horizontal, dropdown).

ChoiceWidget(App &app, const std::string &pv_name, ChoiceStyle style)

Constructs a ChoiceWidget from an App class.

Parameters:

  • app – A reference to the App.

  • pv_name – The PV name.

  • style – Layout style (vertical, horizontal, dropdown).

const PVEnum &value() const

Gets the current enum value displayed in the UI.

Returns:

The current PVEnum value from the UI.

class WidgetBase

A base class for all TUI widgets that interact with EPICS PVs.

This class provides a standard interface for managing PV connections, accessing PV names, and retrieving the underlying FTXUI component.

Subclassed by pvtui::ButtonWidget, pvtui::ChoiceWidget, pvtui::InputWidget, pvtui::VarWidget< T >

Public Functions

std::string pv_name() const

Gets the PV name associated with the widget.

Returns:

The fully expanded PV name.

ftxui::Component component() const

Gets the underlying FTXUI component for rendering.

Throws:

std::runtime_error – if the component has not been set.

Returns:

A valid FTXUI component.

bool connected() const

Checks if the widget’s PV is currently connected.

Returns:

True if the PV is connected, false otherwise.

class DisplayBase

Base class for PVTUI displays.

Provides common functionality for managing a group of PVs and rendering a UI.

Public Functions

inline DisplayBase(pvtui::PVGroup &pvgroup)

Constructs a DisplayBase object.

Parameters:

pvgroup – A reference to the PVGroup managing the PVs for this display.

inline DisplayBase(pvtui::App &app)

Constructs a DisplayBase object.

Parameters:

app – A reference to the app.

virtual ~DisplayBase() = default

Destroys the DisplayBase object.

inline virtual bool sync()

Checks if new data is available from and of the monitors in the group.

Returns:

True if any PV received new data, false otherwise.

virtual ftxui::Element get_renderer() = 0

Pure virtual function to get the FTXUI Element for rendering the display.

Returns:

An FTXUI Element representing the display’s visual content.

virtual ftxui::Component get_container() = 0

Pure virtual function to get the FTXUI Component container for the display.

Returns:

An FTXUI Component that acts as the main container for the display’s interactive elements.

Utility Namespaces

namespace unicode

Provides unicode characters for TUI elements.

Functions

std::string rectangle(int len)

Generates a vertical string of full block characters.

Parameters:

len – The number of full blocks (lines) to generate.

Returns:

A string containing len full block characters, each on a new line.

Variables

constexpr std::string_view full_block = "█"

Unicode character for a full block.

constexpr std::string_view green_circle = "🟢"

Unicode character for a green circle.

constexpr std::string_view red_circle = "🔴"

Unicode character for a red circle.

namespace EPICSColor

Functions to generate FTXUI decorators for EPICS-style UI elements. To align stylistically with MEDM, caQtDM etc, when PVs are disconnected, the widget is drawn as a white rectangle.

Functions

inline ftxui::Decorator edit(const WidgetBase &w)

Light blue with black text for editable controls.

inline ftxui::Decorator menu(const WidgetBase &w)

Dark green with white text for “related display” menus.

inline ftxui::Decorator readback(const WidgetBase &w)

Dark blue text on gray background for readbacks.

inline ftxui::Decorator link(const WidgetBase &w)

Pinkish/purple with black text for links.

inline ftxui::Decorator custom(const WidgetBase &w, ftxui::Decorator style)

A custom color.

inline ftxui::Decorator background()

@ Default gray background color

Variables

static const ftxui::Decorator WHITE_ON_WHITE = bgcolor(ftxui::Color::White) | color(ftxui::Color::White)

White foreground and background for disconnected widgets.

Enums and Types

struct PVEnum

Represents the state of an EPICS enumeration (e.g., mbbo/mbbi).

Public Members

int index = 0

The current integer index of the selected choice.

std::vector<std::string> choices

The list of all available string choices for the enum.

std::string choice = ""

The string value of the currently selected choice.

enum class pvtui::PVPutType

Defines the data types for PV put operations for InputWidget.

Values:

enumerator Integer
enumerator Double
enumerator String
enum class pvtui::ChoiceStyle

Style options for ChoiceWidget.

Values:

enumerator Vertical
enumerator Horizontal
enumerator Dropdown
using pvtui::InputTransform = std::function<ftxui::Element(ftxui::InputState)>