digxel.hpp File Reference

A self-contained numeric element for building structured numeric displays. More...

Go to the source code of this file.

Description

A self-contained numeric element for building structured numeric displays.

Within the GUI of an editing application, we got to build several display widgets to show numeric values in a structured fashion, like Colours or Timecode. While the actual formats of such display elements vary largely, the common property is that they use an underlying format to build the numbers out of individual numeric elements. For a timecode display these are for example the sexagesimal (base 60) "digits" of the common human readable time representation. A "Digxel" is an abstract element with specific properties to support building such display widgets. It doesn't contain any GUI code, but can be wrapped up to build a custom widget.

properties of a "Digxel"

Semantically, it's a number or number component. It holds an internal numeric representation and is implicitly convertible back to the underlying numeric type (usually int or double).

But at the same time, a Digxel has a definite textual format and the ability to present its numeric value formatted accordingly. To this end, the contract requires that numeric data pushed to the Digxel be kept within such limits to prevent exceeding the embedded formatting buffer. There is an assertion in debug mode, and a range check, but the result will be just truncated, so passing only sane values is clearly the caller's responsibility. Digxel might be considered an implementation support class, and performance is important to some limited degree; especially, formatted values will be cached.

To support in-place modification, the digxel stores a mutation signal (functor). This functor will be invoked, whenever a new value gets assigned. The actual functor is free to cause side effects; the value returned from this functor will be the new value to set. If not configured, the default implementation just accepts the given value unaltered. Usually this mutation functor should invoke some internal recalculations, maybe resulting in a new value being pushed to the Digxel for display.

configuration

the Digxel template can be configured to some degree to adjust the stored numeric data and the actual format to be applied

See also

timecode.hpp typical usage example

Definition in file digxel.hpp.

#include "lib/error.hpp"
#include "lib/symbol.hpp"
#include "lib/util.hpp"
#include <boost/lexical_cast.hpp>
#include <functional>
#include <string>
#include <cstdio>
#include <cmath>

Namespaces
namespace	lib
	Implementation namespace for support and library code.
namespace	lib::time
namespace	lib::time::digxel

Typedefs
using	CBuf = CStr
using	SexaDigit = Digxel< int, digxel::SexaFormatter >
	for displaying time components (sexagesimal)
using	HexaDigit = Digxel< uint, digxel::HexaFormatter >
	for displaying a hex byte
using	HourDigit = Digxel< int, digxel::HourFormatter >
	for displaying hours in H:M:S
using	FrameCnt = int64_t
	relative framecount or frame number.
using	CountVal = Digxel< FrameCnt, digxel::CountFormatter >
	for displaying a counter

Classes
class	PrintfFormatter< NUM, len >
	Default / base implementation for Digxel formatting. More...
struct	Formatter< int >
struct	Formatter< double >
struct	SexaFormatter
struct	HexaFormatter
struct	CountFormatter
struct	HourFormatter
struct	SignFormatter
class	Digxel< NUM, FMT >
	A number element for building structured numeric displays. More...
class	Signum
	special Digxel to show a sign. More...