digxel.hpp File Reference

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/operators.hpp>
#include <boost/lexical_cast.hpp>
#include <functional>
#include <string>
#include <cstdio>
#include <cmath>

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

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

Namespaces
	lib
	Implementation namespace for support and library code.

Typedef Documentation

FrameCnt

typedef int64_t FrameCnt

relative framecount or frame number.

Used within the engine at places where the underlying grid and origin is obvious from the call context.

Warning

do not mix up gavl_time_t and FrameCnt.

use 64bit consistently. beware: long is 32bit on i386

Note

any conversion to frame numbers should go through time quantisation followed by conversion to FrameNr

Definition at line 312 of file digxel.hpp.