MR::UI::TestEngine Namespace Reference

Namespaces
namespace	Control
namespace	detail

Classes
struct	ButtonEntry
struct	Entry
struct	EntryAttributes
	Optional attributes reported to the test engine each frame alongside a widget registration. More...
struct	GroupEntry
struct	ValueEntry
	For sliders, drags, etc. More...

Concepts
concept	AllowedValueType

Functions
bool	createButton (std::string_view name, const EntryAttributes &attrs={})
template<AllowedValueType T> requires std::is_arithmetic_v<T>
std::optional< T >	createValue (std::string_view name, T value, T min, T max, bool consumeValueOverride=true, const EntryAttributes &attrs={})
std::optional< std::string >	createValue (std::string_view name, std::string value, bool consumeValueOverride=true, std::optional< std::vector< std::string > > allowedValues=std::nullopt, const EntryAttributes &attrs={})
	This overload is for strings.
template<AllowedValueType T>
std::optional< T >	createValueTentative (std::string_view name, bool consumeValueOverride=true, const EntryAttributes &attrs={})
void	pushTree (std::string_view name)
	Use those to group buttons into named groups.
void	popTree ()
const GroupEntry &	getRootEntry ()
	Returns the current entry tree.
bool	wasFrameTriggered ()
void	markFrameTriggered ()
void	stageFileDialogPaths (std::vector< std::filesystem::path > paths)
std::vector< std::filesystem::path >	consumeStagedFileDialogPaths ()
void	appendStatusMessage (std::string msg)
std::vector< std::string >	consumeStatusMessages ()
	Drain and return all status messages accumulated since the last drain.

Detailed Description

This is a low-level header for implementing GUIs that can be interacted with programmatically. Most likely you don't need to touch this, just use widgets from MRUIStyle.h.

Function Documentation

appendStatusMessage()

void MR::UI::TestEngine::appendStatusMessage

(

std::string

msg

)

Append a status message describing a problem during a TE-driven action (e.g. "file dialog triggered but no paths staged"). MCP tool handlers drain these after dispatching input and surface them to the LLM.

consumeStagedFileDialogPaths()

std::vector< std::filesystem::path > MR::UI::TestEngine::consumeStagedFileDialogPaths ( )

nodiscard

Consume the staged paths. Returns empty if nothing is staged. File-dialog code calls this; not normally called by user code.

consumeStatusMessages()

std::vector< std::string > MR::UI::TestEngine::consumeStatusMessages ( )

nodiscard

Drain and return all status messages accumulated since the last drain.

createButton()

bool MR::UI::TestEngine::createButton ( std::string_view name, const EntryAttributes & attrs = {} )

nodiscard

Call this every frame when drawing a button you want to track (regardless of whether it returns true of false). If this returns true, simulate a button click.

createValue() [1/2]

std::optional< std::string > MR::UI::TestEngine::createValue ( std::string_view name, std::string value, bool consumeValueOverride = true, std::optional< std::vector< std::string > > allowedValues = std::nullopt, const EntryAttributes & attrs = {} )

nodiscard

This overload is for strings.

createValue() [2/2]

template<AllowedValueType T>
requires std::is_arithmetic_v<T>

std::optional< T > MR::UI::TestEngine::createValue ( std::string_view name, T value, T min, T max, bool consumeValueOverride = true, const EntryAttributes & attrs = {} )

nodiscard

Create a "value" (slider/drag/...). T must be a scalar; vector support must be implemented manually. Pass min >= max to disable the range checks. If this returns non-null, use the new value in place of the current one.

Parameters

consumeValueOverride

If true, retrieves (deletes) a value from storage. If false, copies the value from the storage (keeps the original value in the storage to be retrieved again in the next frame). Note that regardless of consumeValueOverride, you can't call this function multiple times per frame with the same name (unless the names are in different groups created with pushTree()/popTree()).

createValueTentative()

template<AllowedValueType T>

std::optional< T > MR::UI::TestEngine::createValueTentative ( std::string_view name, bool consumeValueOverride = true, const EntryAttributes & attrs = {} )

nodiscard

Usually you don't need this function. This is for widgets that require you to specify the value override before drawing it, such as ImGui::CollapsingHeader(). For those, call this version first to read the value override, then draw the widget, then call the normal createValue() with the same name and with the new value, and discard its return value.

getRootEntry()

const GroupEntry & MR::UI::TestEngine::getRootEntry ( )

nodiscard

Returns the current entry tree.

markFrameTriggered()

void MR::UI::TestEngine::markFrameTriggered

(

)

Explicitly mark the current frame as TestEngine-driven. Use from MCP tool handlers that fire plugin actions on a path that does NOT go through createButton() (e.g. tools.action) but should still trigger TE-gated hooks (file-dialog bypass, etc.). Call from the GUI thread before invoking the action.

popTree()

void MR::UI::TestEngine::popTree

(

)

pushTree()

void MR::UI::TestEngine::pushTree

(

std::string_view

name

)

Use those to group buttons into named groups.

stageFileDialogPaths()

void MR::UI::TestEngine::stageFileDialogPaths

(

std::vector< std::filesystem::path >

paths

)

Stage the path(s) that the next TE-triggered file dialog should return. Replaces any previously staged value; empty vector is treated as "not staged". Single-shot: consumed by the next file dialog opened during a TE-triggered frame.

wasFrameTriggered()

bool MR::UI::TestEngine::wasFrameTriggered ( )

nodiscard

True if a TestEngine-driven action ran during the current ImGui frame: either a createButton(...) call returned a simulated click, a createValueLow(...) call consumed a value override, or a caller explicitly invoked markFrameTriggered(). Cleared at frame boundary. Read by code that wants to behave differently under TE control — e.g. file dialogs that should bypass the OS modal.