Coordinates the dependency index with change notifications. More...

#include <text_var_dependency.h>

Public Types
using	SourceKeyExtractor = std::function<std::vector<TEXT_VAR_REF_KEY>( EDA_ITEM* )>
	Return the keys `aItem` could source as a cross-reference target.

using	InvalidateCallback
	Called when a dependent item should recompute its resolved text.

using	ListenerHandle = std::size_t
	Opaque handle returned by AddInvalidateListener and consumed by RemoveInvalidateListener.

Public Member Functions
	TEXT_VAR_TRACKER (SourceKeyExtractor aSourceKeyExtractor={})

TEXT_VAR_DEPENDENCY_INDEX &	Index ()

const TEXT_VAR_DEPENDENCY_INDEX &	Index () const

void	SetSourceKeyExtractor (SourceKeyExtractor aExtractor)

ListenerHandle	AddInvalidateListener (InvalidateCallback aCallback)
	Register a listener that fires for every invalidation.

void	RemoveInvalidateListener (ListenerHandle aHandle)
	Drop a previously-registered listener.

void	RegisterItem (EDA_ITEM *aItem, const std::vector< TEXT_VAR_REF_KEY > &aKeys)
	Register `aItem` in the index.

void	UnregisterItem (EDA_ITEM *aItem)
	Remove `aItem` from the index.

void	HandleItemChanged (EDA_ITEM *aItem, const std::vector< TEXT_VAR_REF_KEY > &aUpdatedKeys)
	Handle a composite change for `aItem:` register its updated keys and fan out invalidation for every key it could source.

void	InvalidateKey (const TEXT_VAR_REF_KEY &aKey)
	Fan out invalidation for a single explicit key — used when a non-item source changes (e.g., project text variables, env vars, title block fields).

void	InvalidateByKind (std::initializer_list< TEXT_VAR_REF_KEY::KIND > aKinds)
	Fan out invalidation for every registered key whose KIND is one of the supplied set.

void	InvalidateProjectScoped ()
	Invalidate every non-item source: title-block, special, project/env vars, and LOCAL (which may be a project text var that we couldn't classify at lex time).

void	InvalidateVariantScoped ()
	Invalidate every source whose resolved value can differ between variants: CROSS_REF (footprint/symbol field values with variant overrides) and LOCAL (a symbol's own variant-overridden VALUE/MPN/etc.).

void	Clear ()

Static Public Attributes
static constexpr ListenerHandle	INVALID_LISTENER = 0

Private Member Functions
void	fanOutSourceKeys (EDA_ITEM *aItem)

Private Attributes
TEXT_VAR_DEPENDENCY_INDEX	m_index

SourceKeyExtractor	m_extractSourceKeys

std::shared_mutex	m_listenersMutex

std::unordered_map< ListenerHandle, InvalidateCallback >	m_invalidateListeners

ListenerHandle	m_nextListenerHandle = 1

Detailed Description

Coordinates the dependency index with change notifications.

The tracker is the generic core of the reactive text-variable system. It owns a TEXT_VAR_DEPENDENCY_INDEX and exposes a uniform entry point (OnItems*) for per-module listener adapters. Module-specific logic (which fields on a SCH_SYMBOL or FOOTPRINT can be sourced via ${REFDES:FIELD}) is plugged in via the SourceKeyExtractor functor, keeping this class free of board/schematic dependencies.

Invalidation is delivered via the consumer-supplied callback so the tracker does not have to know how each kind of dependent (EDA_TEXT glyph cache, title block resolved string, dialog row) wants to refresh itself.

Definition at line 194 of file text_var_dependency.h.

Member Typedef Documentation

◆ InvalidateCallback

using TEXT_VAR_TRACKER::InvalidateCallback

Initial value:

std::function<void( EDA_ITEM* aDependent,

const TEXT_VAR_REF_KEY& aKey )>

EDA_ITEM

A base class for most all the KiCad significant classes used in schematics and boards.

Definition eda_item.h:100

TEXT_VAR_REF_KEY

Identifies a single resolvable source that a text item's ${...} reference depends on.

Definition text_var_dependency.h:48

Called when a dependent item should recompute its resolved text.

The callback runs on the thread that drove the originating edit (the BOARD/SCHEMATIC main thread for commits and undo/redo).

Definition at line 211 of file text_var_dependency.h.

◆ ListenerHandle

using TEXT_VAR_TRACKER::ListenerHandle = std::size_t

Opaque handle returned by AddInvalidateListener and consumed by RemoveInvalidateListener.

A default-constructed handle is inert.

Definition at line 218 of file text_var_dependency.h.

◆ SourceKeyExtractor

using TEXT_VAR_TRACKER::SourceKeyExtractor = std::function<std::vector<TEXT_VAR_REF_KEY>( EDA_ITEM* )>

Return the keys aItem could source as a cross-reference target.

For a footprint U1 with fields REFERENCE/VALUE/MPN this returns keys for ${U1:VALUE}, ${U1:MPN}, etc. Returns empty for items that cannot be cross-reference sources.

Definition at line 204 of file text_var_dependency.h.

Constructor & Destructor Documentation

◆ TEXT_VAR_TRACKER()

TEXT_VAR_TRACKER::TEXT_VAR_TRACKER ( SourceKeyExtractor aSourceKeyExtractor = {} )

explicit

Definition at line 285 of file text_var_dependency.cpp.

References m_extractSourceKeys, and move.

Member Function Documentation

◆ AddInvalidateListener()

TEXT_VAR_TRACKER::ListenerHandle TEXT_VAR_TRACKER::AddInvalidateListener ( InvalidateCallback aCallback )

nodiscard

Register a listener that fires for every invalidation.

Multiple listeners may coexist — each consumer (frame, drawing-sheet proxy, dialog) adds its own. The returned handle must be passed to RemoveInvalidateListener when the consumer is destroyed, otherwise the lambda's captured state (often this) outlives its owner and becomes a dangling reference on the next invalidation.

Definition at line 297 of file text_var_dependency.cpp.

References m_invalidateListeners, m_listenersMutex, and m_nextListenerHandle.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), KIGFX::SCH_VIEW::DisplaySheet(), and PCB_EDIT_FRAME::SetPageSettings().

◆ Clear()

void TEXT_VAR_TRACKER::Clear ( )

inline

Definition at line 295 of file text_var_dependency.h.

References m_index.

Referenced by BOOST_AUTO_TEST_CASE().

◆ fanOutSourceKeys()

void TEXT_VAR_TRACKER::fanOutSourceKeys ( EDA_ITEM * aItem )

private

Definition at line 330 of file text_var_dependency.cpp.

References InvalidateKey(), and m_extractSourceKeys.

Referenced by HandleItemChanged().

◆ HandleItemChanged()

void TEXT_VAR_TRACKER::HandleItemChanged	(	EDA_ITEM *	aItem,
		const std::vector< TEXT_VAR_REF_KEY > &	aUpdatedKeys )

Handle a composite change for aItem: register its updated keys and fan out invalidation for every key it could source.

Either step is skipped if the corresponding hook isn't configured.

Definition at line 342 of file text_var_dependency.cpp.

References fanOutSourceKeys(), and RegisterItem().

Referenced by BOOST_AUTO_TEST_CASE().

◆ Index() [1/2]

TEXT_VAR_DEPENDENCY_INDEX & TEXT_VAR_TRACKER::Index ( )

inline

◆ Index() [2/2]

const TEXT_VAR_DEPENDENCY_INDEX & TEXT_VAR_TRACKER::Index ( ) const

inline

Definition at line 224 of file text_var_dependency.h.

References m_index.

◆ InvalidateByKind()

void TEXT_VAR_TRACKER::InvalidateByKind ( std::initializer_list< TEXT_VAR_REF_KEY::KIND > aKinds )

Fan out invalidation for every registered key whose KIND is one of the supplied set.

Used by project-settings / text-var / env-var change handlers that don't know precisely which tokens moved but want to bulk-refresh every project-scoped dependent.

Definition at line 354 of file text_var_dependency.cpp.

References InvalidateKey(), and m_index.

Referenced by BOOST_AUTO_TEST_CASE(), InvalidateProjectScoped(), and InvalidateVariantScoped().

◆ InvalidateKey()

void TEXT_VAR_TRACKER::InvalidateKey ( const TEXT_VAR_REF_KEY & aKey )

Fan out invalidation for a single explicit key — used when a non-item source changes (e.g., project text variables, env vars, title block fields).

Definition at line 393 of file text_var_dependency.cpp.

References m_index, m_invalidateListeners, and m_listenersMutex.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), fanOutSourceKeys(), and InvalidateByKind().

◆ InvalidateProjectScoped()

void TEXT_VAR_TRACKER::InvalidateProjectScoped ( )

Invalidate every non-item source: title-block, special, project/env vars, and LOCAL (which may be a project text var that we couldn't classify at lex time).

Excludes CROSS_REF (driven by per-item commit events) and OP (not tracked). Called by frames after PROJECT::IncrementTextVarsTicker().

Definition at line 376 of file text_var_dependency.cpp.

References TEXT_VAR_REF_KEY::ENV_VAR, InvalidateByKind(), TEXT_VAR_REF_KEY::LOCAL, TEXT_VAR_REF_KEY::PROJECT_VAR, TEXT_VAR_REF_KEY::SPECIAL, and TEXT_VAR_REF_KEY::TITLE_BLOCK.

◆ InvalidateVariantScoped()

void TEXT_VAR_TRACKER::InvalidateVariantScoped ( )

Invalidate every source whose resolved value can differ between variants: CROSS_REF (footprint/symbol field values with variant overrides) and LOCAL (a symbol's own variant-overridden VALUE/MPN/etc.).

Called after BOARD::SetCurrentVariant / SCHEMATIC::SetCurrentVariant.

Definition at line 386 of file text_var_dependency.cpp.

References TEXT_VAR_REF_KEY::CROSS_REF, InvalidateByKind(), and TEXT_VAR_REF_KEY::LOCAL.

Referenced by BOOST_AUTO_TEST_CASE().

◆ RegisterItem()

void TEXT_VAR_TRACKER::RegisterItem	(	EDA_ITEM *	aItem,
		const std::vector< TEXT_VAR_REF_KEY > &	aKeys )

Register aItem in the index.

Caller has already extracted aKeys (typically via EDA_TEXT::GetTextVarReferences). An empty key vector unregisters. This entry point does no RTTI — safe to call across DSO boundaries.

Definition at line 314 of file text_var_dependency.cpp.

References m_index.

Referenced by DS_PROXY_VIEW_ITEM::AttachToTracker(), and HandleItemChanged().

◆ RemoveInvalidateListener()

void TEXT_VAR_TRACKER::RemoveInvalidateListener ( ListenerHandle aHandle )

Drop a previously-registered listener.

Safe to call with INVALID_LISTENER or a handle that was already removed.

Definition at line 307 of file text_var_dependency.cpp.

References m_invalidateListeners, and m_listenersMutex.

◆ SetSourceKeyExtractor()

void TEXT_VAR_TRACKER::SetSourceKeyExtractor ( SourceKeyExtractor aExtractor )

Definition at line 291 of file text_var_dependency.cpp.

References m_extractSourceKeys.

Referenced by BOOST_AUTO_TEST_CASE().

◆ UnregisterItem()

void TEXT_VAR_TRACKER::UnregisterItem ( EDA_ITEM * aItem )

Remove aItem from the index.

No-op if not registered.

Definition at line 324 of file text_var_dependency.cpp.

References m_index.

Member Data Documentation

◆ INVALID_LISTENER

ListenerHandle TEXT_VAR_TRACKER::INVALID_LISTENER = 0

staticconstexpr

Definition at line 219 of file text_var_dependency.h.

Referenced by KIGFX::SCH_VIEW::DetachTextVarTracker(), PCB_EDIT_FRAME::detachTextVarTracker(), KIGFX::SCH_VIEW::DisplaySheet(), and PCB_EDIT_FRAME::SetPageSettings().

◆ m_extractSourceKeys

SourceKeyExtractor TEXT_VAR_TRACKER::m_extractSourceKeys

private

Definition at line 301 of file text_var_dependency.h.

Referenced by fanOutSourceKeys(), SetSourceKeyExtractor(), and TEXT_VAR_TRACKER().

◆ m_index

TEXT_VAR_DEPENDENCY_INDEX TEXT_VAR_TRACKER::m_index

private

Definition at line 300 of file text_var_dependency.h.

Referenced by Clear(), Index(), Index(), InvalidateByKind(), InvalidateKey(), RegisterItem(), and UnregisterItem().

◆ m_invalidateListeners

std::unordered_map<ListenerHandle, InvalidateCallback> TEXT_VAR_TRACKER::m_invalidateListeners

private

Definition at line 309 of file text_var_dependency.h.

Referenced by AddInvalidateListener(), InvalidateKey(), and RemoveInvalidateListener().

◆ m_listenersMutex

std::shared_mutex TEXT_VAR_TRACKER::m_listenersMutex

mutableprivate

Definition at line 308 of file text_var_dependency.h.

Referenced by AddInvalidateListener(), InvalidateKey(), and RemoveInvalidateListener().

◆ m_nextListenerHandle

ListenerHandle TEXT_VAR_TRACKER::m_nextListenerHandle = 1

private

Definition at line 310 of file text_var_dependency.h.

Referenced by AddInvalidateListener().

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ InvalidateCallback

◆ ListenerHandle

◆ SourceKeyExtractor

Constructor & Destructor Documentation

◆ TEXT_VAR_TRACKER()

Member Function Documentation

◆ AddInvalidateListener()

◆ Clear()

◆ fanOutSourceKeys()

◆ HandleItemChanged()

◆ Index() [1/2]

◆ Index() [2/2]

◆ InvalidateByKind()

◆ InvalidateKey()

◆ InvalidateProjectScoped()

◆ InvalidateVariantScoped()

◆ RegisterItem()

◆ RemoveInvalidateListener()

◆ SetSourceKeyExtractor()

◆ UnregisterItem()

Member Data Documentation

◆ INVALID_LISTENER

◆ m_extractSourceKeys

◆ m_index

◆ m_invalidateListeners

◆ m_listenersMutex

◆ m_nextListenerHandle