libnebular::PicturePropContainer Class Reference
[User API]

Property map container for use in Picture. More...

#include <libnebular.hpp>

Classes
class	DefaultImpl_
class	Impl_
class	PropKeyIterator
	C++ iterator, `ForwardIterator`, iterating through `PicturePropContainer` key names. More...
class	SubtreeProxyImpl_
Public Member Functions
PropKeyIterator	propKeyBegin ()
	Iterator value for first property key.
PropKeyIterator	propKeyEnd ()
	Iterator value for after-the-last property key.
template<typename R >
void	set (const String &key, const R &value)
	Main property "set"-ter.
template<typename R >
const R	get (const String &key) const
	Main property "get"-ter.
template<typename R >
void	get (const String &key, R &value) const
	Analog of `get<R>(const String&) const` differing by return of result in argument `value`.
void	unSet (const String &key)
	Main property "unset"-ter.
bool	isSet (const String &key) const
bool	isDefault (const String &key) const
	Whether property have "default" attribute set.
	PicturePropContainer ()
virtual	~PicturePropContainer ()
template<>
String	castToPropString (const bool &arg)
	Explicit specialization of `castToPropString<Src>(const Src&)` for `bool`.
template<>
void	set (const String &key, const String &value)
	Explicit specialization of `set<R>(const String&, const R&)` that's used by general implementation.
template<>
void	set (const String &key, const Blob &value)
	Explicit specialization of `set<R>(const String&, const R&)` for `Blob`.
helpers
Helper functions having functionality that can be achieved by combining others
void	move (const String &srcKey, const String &destKey)
	Moves value.
void	acceptOpt (const String &acceptedKey)
	If `string`("opt/")+key value is set, `move()-s` it to `key`.
bool	isSetAndTrue (const String &key) const
	Whether `key` is set and can be read as `bool` value `true`.
template<typename Value >
void	swap (const String &keyA, const String &keyB)
	Swaps values even when any, both of properties aren't set.
template<typename Value >
void	copyFromIfSet (const String &key, const PicturePropContainer &src)
	Copies value for `key` from `PicturePropContainer` `src` here if that's set.
void	setDefaultIfNotSet (const String &key, const String &defaultValue)
	Sets `key` to `defaultValue` and to be having "default" attribute.
Static Public Member Functions
template<typename Src >
static String	castToPropString (const Src &value)
	Casts `value` of arbitrary type to `String` to be used in property map of `PicturePropContainer`.
static String	castToPropString (const char *value)
	Overload of `castToPropString<Src>(const Src&)`.
template<typename Dest >
static Dest	castFromPropString (const String &value)
	Casts to arbitrary type from `value` of `String` been used in property map of `PicturePropContainer`.
Friends
template<class PicturePropContainerBased >
boost::shared_ptr < PicturePropContainerBased >	createSubtreeProxy (PicturePropContainer &realSubject, const String &subTreePrefix)
	Allows to work with property subtree given by `subTreePrefix` as with arbitrary object based on `PicturePropContainer`.
void	setDefault (PicturePropContainer &p, const String &key, const String &value)
	Sets `value` to property `key` of `PicturePropContainer` `p` as default.

Detailed Description

Property map container for use in Picture.

All property values will internally be stored in 2 types:

libnebular::String

Strings of dynamic length.

Design note:
They're more scalable for holding numbers, comparing to numeric values.
libnebular::Blob

BLOBs, for data which can have "\0", thus cannot be stored in std::string.

Now only bitmap data needs to be stored in Blob.

Design note:: Convenient built-in type conversions will be available (and are needed) only for libnebular::String data (i.e. not for libnebular::Blob).

Design note:: Properties are stored in plain list, there is no "real" hierarchy (There's some "hierarchy" in their names, where "hierarchy levels" are delimited by "/"). Because of: (1) there aren't many properties for hierarchy; (2) hierarchy raises specific problems. But you can use subtree of hierarchy by createSubtreeProxy().

Design note:: Not in SRS: Really can't allocate contiguous piece of memory for very large images. But IMHO that's not a thing that must be in SRS. (If library can't by itself allocate memory, then client should supply his memory area.)

Design note:: Notify plugins when doing set(), get()? No.

Design note:: I assume that when coping with properties we don't need a PictureHandler.

Design note:: Special names (or something stronger?) for "private" classes PicturePropContainer and PictureProps? No, because their interface is a part of Picture interface, so i should reveal it.

Design note:: What about being CopyConstructible and Assignable to ease Picture manipulations in containers? So, PicturePropContainer is too heavy to be deep-copied when treated as value class; shallow copy could be an application, but such technique can be achieved by boost::shared_ptr. So, give up CopyConstructible. And deep copy can be called through PictureProps::reproduce. Then, let's strike out Assignable.

Design note:: Set of symbols allowed to be in property names? Hmm, let's use (RegExp) "[a-z]\|[1-9]\|0\|-\|/" with "/" and some other sequences having predefined meaning

Note:: When converting Blob to String, there's lossy one-way conversion and resulting value is value of "some" hash function (boost::hash_range()) applied to Blob data. This is for property listing purposes.

Design note:: All PicturePropContainer template-d "get"-ters and "set"-ters with built-in conversions are specialized only for these types that they're explicitly instantiated in realization. So, at the time of writing:
Conversion to property String is alrealy specialized for: String, Integer, Real, bool, HexInteger<Integer>.
Conversion from property String is alrealy specialized for: String, Integer, Real, bool, int16_t, int32_t, uint16_t, uint32_t.

Design note:: Was it good idea to provide template definition to allow plugins instantiate castToPropString, castFromPropString by theirself? Hmm, but there is dependency on templated implementation details (such as boost::lexical_cast). Anyway, that's done in libnebular-extra.templates.hpp

By default, "set"-ters that only set value and not "default" attribute also have effect of resetting "default attribute to its unset state.

Definition at line 379 of file libnebular.hpp.

Constructor & Destructor Documentation

libnebular::PicturePropContainer::PicturePropContainer ( )

Definition at line 499 of file picture-prop-container.cpp.

libnebular::PicturePropContainer::~PicturePropContainer ( ) [virtual]

Definition at line 503 of file picture-prop-container.cpp.

Member Function Documentation

void libnebular::PicturePropContainer::acceptOpt ( const String & acceptedKey )

If string("opt/")+key value is set, move()-s it to key.

Definition at line 487 of file picture-prop-container.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

template uint32_t libnebular::PicturePropContainer::castFromPropString ( const String & value ) [inline, static]

Casts to arbitrary type from value of String been used in property map of PicturePropContainer.

Patch for documentation generator malfunction.

Explicitly specialization for bool.

Definition at line 520 of file picture-prop-container.cpp.

String libnebular::PicturePropContainer::castToPropString ( const bool & arg ) [inline]

Explicit specialization of castToPropString<Src>(const Src&) for bool.

Definition at line 512 of file picture-prop-container.cpp.

String libnebular::PicturePropContainer::castToPropString ( const char * value ) [static]

Overload of castToPropString<Src>(const Src&).

Definition at line 505 of file picture-prop-container.cpp.

template<typename Src >

static String libnebular::PicturePropContainer::castToPropString ( const Src & value ) [inline, static]

Casts value of arbitrary type to String to be used in property map of PicturePropContainer.

Here is the caller graph for this function:

template<typename Value >

void libnebular::PicturePropContainer::copyFromIfSet	(	const String &	key,
		const PicturePropContainer &	src
	)			`[inline]`

Copies value for key from PicturePropContainer src here if that's set.

Definition at line 75 of file libnebular.templates.hpp.

Here is the call graph for this function:

template<typename R >

void libnebular::PicturePropContainer::get	(	const String &	key,
		R &	value
	)			const `[inline]`

Analog of get<R>(const String&) const differing by return of result in argument value.

Definition at line 32 of file libnebular.templates.hpp.

const Blob libnebular::PicturePropContainer::get ( const String & key ) const [inline]

Main property "get"-ter.

With built-in type conversion.

Also specialized for String (general implementation always uses that); Blob.

Definition at line 43 of file libnebular.templates.hpp.

Here is the caller graph for this function:

bool libnebular::PicturePropContainer::isDefault ( const String & key ) const

Whether property have "default" attribute set.

Definition at line 479 of file picture-prop-container.cpp.

Here is the caller graph for this function:

bool libnebular::PicturePropContainer::isSet ( const String & key ) const

Definition at line 476 of file picture-prop-container.cpp.

Here is the caller graph for this function:

bool libnebular::PicturePropContainer::isSetAndTrue ( const String & key ) const

Whether key is set and can be read as bool value true.

Definition at line 483 of file picture-prop-container.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void libnebular::PicturePropContainer::move	(	const String &	srcKey,
		const String &	destKey
	)

Moves value.

Unsets srcKey.

Definition at line 464 of file picture-prop-container.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

PicturePropContainer::PropKeyIterator libnebular::PicturePropContainer::propKeyBegin ( )

Iterator value for first property key.

Definition at line 621 of file picture-prop-container.cpp.

Here is the caller graph for this function:

PicturePropContainer::PropKeyIterator libnebular::PicturePropContainer::propKeyEnd ( )

Iterator value for after-the-last property key.

Definition at line 624 of file picture-prop-container.cpp.

Here is the caller graph for this function:

void libnebular::PicturePropContainer::set	(	const String &	key,
		const Blob &	value
	)			`[inline]`

Explicit specialization of set<R>(const String&, const R&) for Blob.

Definition at line 543 of file picture-prop-container.cpp.

void libnebular::PicturePropContainer::set	(	const String &	key,
		const String &	value
	)			`[inline]`

Explicit specialization of set<R>(const String&, const R&) that's used by general implementation.

Definition at line 533 of file picture-prop-container.cpp.

template<typename R >

void libnebular::PicturePropContainer::set	(	const String &	key,
		const R &	value
	)			`[inline]`

Main property "set"-ter.

With built-in type conversion

Definition at line 37 of file libnebular.templates.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void libnebular::PicturePropContainer::setDefaultIfNotSet	(	const String &	key,
		const String &	defaultValue
	)

Sets key to defaultValue and to be having "default" attribute.

Definition at line 493 of file picture-prop-container.cpp.

Here is the call graph for this function:

template<typename Value >

void libnebular::PicturePropContainer::swap	(	const String &	keyA,
		const String &	keyB
	)			`[inline]`

Swaps values even when any, both of properties aren't set.

Definition at line 50 of file libnebular.templates.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void libnebular::PicturePropContainer::unSet ( const String & key )

Main property "unset"-ter.

Erases corresponding value and key from PicturePropContainer.

Definition at line 460 of file picture-prop-container.cpp.

Here is the caller graph for this function:

Friends And Related Function Documentation

template<class PicturePropContainerBased >

boost::shared_ptr<PicturePropContainerBased> createSubtreeProxy	(	PicturePropContainer &	realSubject,
		const String &	subTreePrefix
	)			`[friend]`

Allows to work with property subtree given by subTreePrefix as with arbitrary object based on PicturePropContainer.

Specialized for PicturePropContainer, PictureProps, Picture.

If extracted subtree "can be seen" as "real" Picture (as in "bm/palette"), that's recommended to extract it as Picture or PictureProps. Otherwise (case when subtree is "arbitrary", doesn't have enough properties that every Picture "should" have), extract that as PicturePropContainer.

Definition at line 709 of file picture-prop-container.cpp.

void setDefault	(	PicturePropContainer &	p,
		const String &	key,
		const String &	value
	)			`[friend]`

Sets value to property key of PicturePropContainer p as default.

Not in PicturePropContainer because public interface of that class is almost entirely should be in User API.

Definition at line 452 of file picture-prop-container.cpp.

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

libnebular::PicturePropContainer Class Reference [User API]

Classes

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

libnebular::PicturePropContainer Class Reference
[User API]