Event-driven real-time clock input element. More...

#include <Clock.h>

Inheritance diagram for Clock:

Public Member Functions
QList< std::pair< int, QString > >	appearanceStates () const override
	Clock (QGraphicsItem *parent=nullptr)
	Constructs the element with optional parent.
double	delay () const override
double	frequency () const override
	Returns the clock frequency in Hz.
QString	genericProperties () override
	Returns a summary string of the clock's current frequency and delay settings.
bool	isOn (const int port=0) const override
	Returns `true` if the clock output is currently logic-high.
void	load (QDataStream &stream, SerializationContext &context) override
void	resetClock (std::chrono::steady_clock::time_point globalTime)
	Resets the clock phase reference to globalTime.
void	save (QDataStream &stream, SerializationOptions options) const override
void	setDelay (const double delay) override
void	setFrequency (const double freq) override
	Sets the clock output frequency to freq Hz.
void	setOff () override
	Drives all output ports logic-low.
void	setOn () override
	Drives all output ports logic-high.
virtual void	setOn (const bool value, const int port=0)
	Sets output port to value.
void	updateClock (std::chrono::steady_clock::time_point globalTime)
	Advances the clock state based on elapsed time since globalTime.
Public Member Functions inherited from GraphicElementInput
	GraphicElementInput (ElementType type, QGraphicsItem *parent=nullptr)
bool	isLocked () const
	Returns `true` if the element is locked against user interaction.
virtual int	outputSize () const
	Returns the number of output ports (default 1 for most input elements).
virtual int	outputValue () const
	Returns the integer encoding of the current output value.
void	setAppearance (const bool defaultAppearance, const QString &fileName) override
void	setLocked (const bool locked)
	Locks or unlocks user interaction on this element.
virtual void	setWaveformValue (const bool value, const int port=0)
	Applies a waveform-sweep cell value to output port.
void	updateOutputs ()
	Propagates the current on/off state of each output to the backing logic element.
	~GraphicElementInput () override=default
Public Member Functions inherited from GraphicElement
QVector< Port * >	allPorts () const
	Returns a combined list of all input and output ports as Port pointers.
QPixmap	appearancePreviewPixmap (const int index, const QSize &size) const
	Returns a small preview pixmap for the appearance at index (see appearanceStates()).
virtual QString	audio () const
	Returns the name of the audio file currently associated with this element.
void	beginDeferredCommit ()
virtual const QString &	blobName () const
	Returns the blob name for embedded ICs, empty string otherwise. Base returns empty.
QRectF	boundingRect () const override
	Returns the bounding rectangle of this element in local coordinates.
bool	canChangeAppearance () const
	Returns `true` if the user is allowed to choose a custom appearance for this element.
void	clearOutputChanged ()
	Clears the simulation output-changed flag.
virtual QString	color () const
	Returns the name of the color currently applied to this element.
void	commitDeferredOutputs ()
void	connectPredecessor (const int inputIndex, GraphicElement *source, const int outputPort)
	Connects simulation input inputIndex to output outputPort of source element.
QList< PropertyDescriptor >	editableProperties () const
	Returns the list of editable properties this element exposes in the ElementEditor.
ElementGroup	elementGroup () const
	Returns the group this element belongs to.
ElementType	elementType () const
	Returns the type identifier for this element.
virtual QStringList	externalFiles () const
	GraphicElement (ElementType type, QGraphicsItem *parent=nullptr)
	Constructs a graphic element of the given type, fetching all properties from the metadata registry.
bool	hasAudio () const
	Returns `true` if this element type supports audio output.
bool	hasAudioBox () const
	Returns `true` if this element type shows an audio selection box.
bool	hasColors () const
	Returns `true` if this element type supports color selection.
bool	hasDelay () const
	Returns `true` if this element type exposes a configurable clock phase delay.
bool	hasFrequency () const
	Returns `true` if this element type exposes a configurable clock frequency.
bool	hasLabel () const
	Returns `true` if this element type supports a user-editable label.
bool	hasTrigger () const
	Returns `true` if this element type supports a keyboard trigger.
bool	hasTruthTable () const
	Returns `true` if this element type has an editable truth table.
bool	hasVolume () const
	Returns `true` if this element type supports volume control.
virtual bool	hasWirelessMode () const
	Returns true if this element supports a configurable wireless routing mode.
void	initSimulationVectors (const int inputCount, const int outputCount)
	Allocates simulation I/O vectors with inputs inputs and outputs outputs.
void	inlineEditRequested (GraphicElement *element)
InputPort *	inputPort (const int index=0) const
	Returns the input port at index (default 0).
const QVector< InputPort * > &	inputs () const
	Returns a const reference to the vector of all input ports.
int	inputSize () const
	Returns the current number of input ports.
virtual bool	isEmbedded () const
	Returns true if this element is an embedded IC (not file-backed). Base returns false.
bool	isFlippedX () const
	Returns `true` if this element is mirrored along the X axis (horizontal flip).
bool	isFlippedY () const
	Returns `true` if this element is mirrored along the Y axis (vertical flip).
bool	isValid ()
	Returns `true` if the element is fully initialised and connected correctly.
QString	label () const
	Returns the user-visible label text for this element.
QRectF	labelSceneBoundingRect () const
virtual void	loadFromDrop (const QString &fileName, const QString &contextDir)
	Polymorphic interface for drag-drop initialization (replaces elementType() == IC checks).
int	maxInputSize () const
	Returns the maximum allowed number of input ports.
int	maxOutputSize () const
	Returns the maximum allowed number of output ports.
int	minInputSize () const
	Returns the minimum allowed number of input ports.
int	minOutputSize () const
	Returns the minimum allowed number of output ports.
QString	nextColor () const
	Returns the name of the next color in the element's color list.
bool	outputChanged () const
OutputPort *	outputPort (const int index=0) const
	Returns the output port at index (default 0).
const QVector< OutputPort * > &	outputs () const
	Returns a const reference to the vector of all output ports.
int	outputSize () const
	Returns the current number of output ports.
Status	outputValue (const int index=0) const
	Returns the four-state signal value on simulation output port index.
void	paint (QPainter painter, const QStyleOptionGraphicsItem option, QWidget *widget) override
	Paints the element onto the scene.
QPointF	pixmapCenter () const
	Returns the centre point of the element's pixmap in local coordinates.
QString	previousColor () const
	Returns the name of the previous color in the element's color list.
void	reapplyAppearanceOrientation ()
virtual void	refresh ()
	Forces a visual refresh of the element's pixmap and ports.
virtual void	resetSimState ()
	Resets all simulation-visible state to power-on defaults.
virtual void	resettleCombinational ()
	Re-evaluates combinational outputs after the synchronous sequential commit, propagating just-committed flip-flop/latch state to downstream logic and IC output boundaries within the same tick.
void	retranslate ()
	Updates the translated display name, tooltip, and port object name after a locale change.
void	rotatePorts ()
bool	rotatesGraphic () const
qreal	rotation () const
	Returns the current rotation angle of this element in degrees.
void	setAppearanceAt (const int index, const QString &fileName)
	Sets a custom appearance at a specific index in the appearance list.
virtual void	setAudio (const QString &audio)
	Sets the audio file associated with this element to audio.
virtual void	setColor (const QString &color)
	Sets the element color to color and refreshes the pixmap.
void	setFlippedX (bool flipped)
	Sets the horizontal mirror state and updates the item transform.
void	setFlippedY (bool flipped)
	Sets the vertical mirror state and updates the item transform.
void	setInputs (const QVector< InputPort * > &inputs)
	Replaces the input port vector with inputs.
virtual void	setInputSize (const int size)
	Adjusts the number of input ports to size, adding or removing ports as needed.
void	setLabel (const QString &label)
	Sets the label text to label and refreshes the display.
virtual void	setOutputSize (const int size)
	Adjusts the number of output ports to size, adding or removing ports as needed.
void	setOutputValue (const bool value)
	Convenience overload — converts `bool` to Active/Inactive for port 0.
void	setOutputValue (const int index, const bool value)
	Convenience overload — converts `bool` to Active/Inactive for port index.
void	setOutputValue (const int index, const Status value)
	Sets simulation output port index to value.
void	setOutputValue (const Status value)
	Sets simulation output port 0 to value.
void	setPixmap (const int index)
	Loads and applies the appearance at position index in the appearance list.
void	setPixmap (const QString &pixmapPath)
	Loads and applies the pixmap located at pixmapPath.
void	setPortName (const QString &name)
	Sets the object name of all ports to name for identification.
void	setRotation (const qreal angle)
	Rotates the element to angle degrees and updates port positions.
void	setTrigger (const QKeySequence &trigger)
	Sets the keyboard shortcut to trigger and updates the label.
virtual void	setVolume (float vol)
	Sets the audio playback volume to vol (0.0–1.0).
const QVector< Status > &	simInputs () const
	Read-only view of the cached simulation input values.
const QVector< Status > &	simOutputs () const
	Read-only view of the current simulation output values.
qsizetype	simOutputSize () const
	Returns the number of simulation output slots.
QKeySequence	trigger () const
	Returns the keyboard shortcut that activates this element.
int	type () const override
	Returns the custom type identifier for this item.
void	updateLabel ()
	Repositions and updates the label child item to reflect current state.
virtual void	updateLogic ()
	Computes this element's output values from its current inputs.
virtual void	updatePortsProperties ()
	Repositions and reconfigures all ports after the port count changes.
virtual void	updateTheme ()
	Updates the element's visual theme according to the current dark/light palette.
virtual float	volume () const
	Returns the audio playback volume (0.0–1.0).
virtual WirelessMode	wirelessMode () const
	Returns the wireless routing mode for this element.
	~GraphicElement () override
	Out-of-line so the unique_ptr to the forward-declared QSvgRenderer can be destroyed.
Public Member Functions inherited from ItemWithId
int	id () const
	Returns the unique integer identifier of this item, or -1 if unassigned.
	ItemWithId ()=default
	Constructs a new ItemWithId with an unassigned ID of -1.
void	setId (const int id)
	Sets the identifier to id.
virtual	~ItemWithId ()
	Self-unregisters from the current SceneItemRegistry, if any.

Static Public Member Functions
static constexpr std::chrono::microseconds	halfPeriod (const double freq)
Static Public Member Functions inherited from GraphicElement
static int	colorNameToIndex (const QString &color)
	Maps a color name ("White","Red","Green","Blue","Purple") to indices 0–4.

Static Public Attributes
static constexpr double	kDefaultFrequency = 1.0

Additional Inherited Members
Public Types inherited from GraphicElement
enum	{ Type = QGraphicsItem::UserType + 3 }
Protected Member Functions inherited from GraphicElement
int	decodeSelectValue (int offset, int count) const
	Decodes count select-line statuses from simInputs() into a binary index.
QVariant	itemChange (GraphicsItemChange change, const QVariant &value) override
	Handles item state changes such as position, rotation, and selection.
virtual void	labelContentChanged ()
void	mouseDoubleClickEvent (QGraphicsSceneMouseEvent *event) override
	Requests inline label editing on double-click.
QPixmap	pixmap () const
	Returns the pixmap currently displayed by this element.
QRectF	portsBoundingRect () const
	Returns the bounding rectangle that encompasses all child ports.
QRectF	renderBodyBounds () const
	Footprint of a "procedural render body" (IC/Mux/Demux/TruthTable): the nominal 64x64 body unioned with wherever the ports actually land, which extends past it once an instance has enough ports.
bool	sceneEvent (QEvent *event) override
	Intercepts mouse-press and mouse-release events to handle Ctrl+click.
void	setHasColors (const bool hasColors)
	Sets whether this element type supports color selection.
void	setLabelAnchor (const QPointF &pos)
void	setMaxInputSize (const int maxInputSize)
	Sets the maximum number of input ports to maxInputSize.
void	setMaxOutputSize (const int maxOutputSize)
	Sets the maximum number of output ports to maxOutputSize.
void	setMinInputSize (const int minInputSize)
	Sets the minimum number of input ports to minInputSize.
void	setMinOutputSize (const int minOutputSize)
	Sets the minimum number of output ports to minOutputSize.
bool	simUpdateInputs ()
	Snapshots each predecessor's output into the simulation input cache.
bool	simUpdateInputsAllowUnknown ()
	Like simUpdateInputs(), but allows Unknown/Error values through.
Protected Attributes inherited from GraphicElementInput
bool	m_isOn = false
bool	m_locked = false
Protected Attributes inherited from GraphicElement
ElementAppearance	m_appearance {this}
QGraphicsSimpleTextItem *	m_label = new QGraphicsSimpleTextItem(this)
	Child text item that displays the label and optional trigger shortcut.
QPointF	m_labelAnchor
	The label's intended anchor point in the element's un-rotated local frame; see setLabelAnchor().
ElementPorts	m_ports {this}
QString	m_titleText
	Translated title text shown in UI panels (from metadata).
QString	m_translatedName
	Translated element name used as tooltip and port object name.

Detailed Description

Event-driven real-time clock input element.

Toggles its output at a configurable frequency (Hz) and optional initial phase delay. The clock is the only element driven by wall-clock time rather than the synchronous simulation cycle.

Definition at line 22 of file Clock.h.

Constructor & Destructor Documentation

◆ Clock()

Clock::Clock ( QGraphicsItem * parent = nullptr )

explicit

Constructs the element with optional parent.

Definition at line 54 of file Clock.cpp.

References Clock(), GraphicElementInput::GraphicElementInput(), and setOff().

Referenced by Clock().

Member Function Documentation

◆ appearanceStates()

QList< std::pair< int, QString > > Clock::appearanceStates ( ) const

overridevirtual

Reimplemented from base class.

Reimplemented from GraphicElement.

Definition at line 239 of file Clock.cpp.

◆ delay()

double Clock::delay ( ) const

overridevirtual

Returns the clock phase delay as a fraction of the period, in [-1, 1]. Negative delays advance the clock; positive delays retard it (see setDelay()).

Reimplemented from GraphicElement.

Definition at line 204 of file Clock.cpp.

Referenced by save(), and setDelay().

◆ frequency()

double Clock::frequency ( ) const

overridevirtual

Returns the clock frequency in Hz.

Reimplemented from GraphicElement.

Definition at line 182 of file Clock.cpp.

Referenced by genericProperties(), and save().

◆ genericProperties()

QString Clock::genericProperties ( )

overridevirtual

Returns a summary string of the clock's current frequency and delay settings.

Reimplemented from GraphicElement.

Definition at line 234 of file Clock.cpp.

References frequency().

◆ halfPeriod()

constexpr std::chrono::microseconds Clock::halfPeriod ( const double freq )

inlinestaticconstexpr

Half-period (the duration of one HIGH or LOW phase) for freq Hz: the full period is 1/freq seconds, so each phase lasts 1/(2·freq). Shared by the m_interval member initializer and setFrequency() so the two derivations can never diverge. Callers guard the input (see setFrequency()); this assumes a positive, finite freq.

Definition at line 37 of file Clock.h.

Referenced by setFrequency().

◆ isOn()

bool Clock::isOn ( const int port = 0 ) const

overridevirtual

Returns true if the clock output is currently logic-high.

Implements GraphicElementInput.

Definition at line 96 of file Clock.cpp.

References GraphicElementInput::m_isOn.

◆ load()

void Clock::load	(	QDataStream &	stream,
		SerializationContext &	context )

overridevirtual

Reimplemented from base class.

Reimplemented from GraphicElement.

Definition at line 134 of file Clock.cpp.

References VersionInfo::hasClock(), VersionInfo::hasDelayFix(), VersionInfo::hasLockState(), VersionInfo::hasQMapFormat(), GraphicElement::load(), GraphicElementInput::m_locked, Serialization::readBoundedMetadata(), setDelay(), setFrequency(), and SerializationContext::version.

◆ resetClock()

void Clock::resetClock ( std::chrono::steady_clock::time_point globalTime )

Resets the clock phase reference to globalTime.

Definition at line 220 of file Clock.cpp.

References setOn().

Referenced by updateClock().

◆ save()

void Clock::save	(	QDataStream &	stream,
		SerializationOptions	options ) const

overridevirtual

Reimplemented from base class.

Reimplemented from GraphicElement.

Definition at line 112 of file Clock.cpp.

References delay(), frequency(), kDefaultFrequency, GraphicElementInput::m_locked, PortableFile, SerializationOptions::purpose, and GraphicElement::save().

◆ setDelay()

void Clock::setDelay ( const double delay )

overridevirtual

Sets the clock phase delay to delay (fraction of period), clamped to [-1, 1]. Negative delays advance the clock (trigger earlier); positive delays delay it.

Reimplemented from GraphicElement.

Definition at line 209 of file Clock.cpp.

References delay().

Referenced by load().

◆ setFrequency()

void Clock::setFrequency ( const double freq )

overridevirtual

Sets the clock output frequency to freq Hz.

Reimplemented from GraphicElement.

Definition at line 187 of file Clock.cpp.

References halfPeriod().

Referenced by load().

◆ setOff()

void Clock::setOff ( )

overridevirtual

Drives all output ports logic-low.

Implements GraphicElementInput.

Definition at line 102 of file Clock.cpp.

References setOn().

Referenced by Clock().

◆ setOn() [1/2]

void Clock::setOn ( )

overridevirtual

Drives all output ports logic-high.

Implements GraphicElementInput.

Definition at line 107 of file Clock.cpp.

References setOn().

Referenced by resetClock(), setOff(), setOn(), and updateClock().

◆ setOn() [2/2]

void GraphicElementInput::setOn	(	const bool	value,
		const int	port = 0 )

virtual

Sets output port to value.

Default implementation stores value in m_isOn, updates the pixmap (index 0 = off, 1 = on), and drives the output port status. Override when the element has more than one output port or non-standard pixmap indexing (e.g. InputRotary).

Parameters

value	New logic value.
port	Port index (default 0, unused by this base implementation).

Reimplemented from GraphicElementInput.

Definition at line 68 of file GraphicElementInput.cpp.

◆ updateClock()

void Clock::updateClock ( std::chrono::steady_clock::time_point globalTime )

Advances the clock state based on elapsed time since globalTime.

Definition at line 62 of file Clock.cpp.

References GraphicElementInput::m_isOn, GraphicElementInput::m_locked, resetClock(), and setOn().

Member Data Documentation

◆ kDefaultFrequency

double Clock::kDefaultFrequency = 1.0

staticconstexpr

Default output frequency in Hz. Single source of truth: used by the m_frequency/m_interval member initializers and serialization's default-elision check.

Definition at line 30 of file Clock.h.

Referenced by save().

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Clock()

Member Function Documentation

◆ appearanceStates()

◆ delay()

◆ frequency()

◆ genericProperties()

◆ halfPeriod()

◆ isOn()

◆ load()

◆ resetClock()

◆ save()

◆ setDelay()

◆ setFrequency()

◆ setOff()

◆ setOn() [1/2]

◆ setOn() [2/2]

◆ updateClock()

Member Data Documentation

◆ kDefaultFrequency