Property Class Reference

Represents a property of a component, usually a video capture device. More...

Inheritance diagram for Property:

Public Types

using	NotificationHandler = std::function< void(Property &prop)> Function prototype for property notification event handlers.
using	NotificationToken = void * Represents a registered callback.

Public Member Functions

	Property ()=default Creates an invalid object.
bool	is_valid () const noexcept Checks whether this property is a valid object.
bool	operator== (const Property &other) const noexcept Checks whether a property object refers to the same property as another property object.
bool	operator!= (const Property &other) const noexcept Checks whether a property object refers to a different property as another property object
bool	operator< (const Property &other) const noexcept Provides an ordering of property objects.
PropType	type (Error &err=Error::Default()) const Returns the type of the property.
std::string	name (Error &err=Error::Default()) const Returns the name of the property.
bool	isAvailable (Error &err=Error::Default()) const Checks whether a property is currently available.
bool	isLocked (Error &err=Error::Default()) const Checks whether a property is currently locked
bool	isLikelyLockedByStream (Error &err=Error::Default()) const Tries to determine whether a property is locked because a data stream is active.
bool	isReadOnly (Error &err=Error::Default()) const Checks whether a property is read-only.
PropVisibility	visibility (Error &err=Error::Default()) const Returns a visibility hint for the property.
std::string	displayName (Error &err=Error::Default()) const Returns the display name of the property.
std::string	tooltip (Error &err=Error::Default()) const Returns a tooltip for the property.
std::string	description (Error &err=Error::Default()) const Returns a description for the property.
PropCommand	asCommand (Error &err=Error::Default()) const Converts this property into a PropCommand.
PropInteger	asInteger (Error &err=Error::Default()) const Converts this property into a PropInteger.
PropBoolean	asBoolean (Error &err=Error::Default()) const Converts this property into a PropBoolean.
PropFloat	asFloat (Error &err=Error::Default()) const Converts this property into a PropFloat.
PropString	asString (Error &err=Error::Default()) const Converts this property into a PropString.
PropEnumeration	asEnumeration (Error &err=Error::Default()) const Converts this property into a PropEnumeration.
PropEnumEntry	asEnumEntry (Error &err=Error::Default()) const Converts this property into a PropEnumEntry.
PropRegister	asRegister (Error &err=Error::Default()) const Converts this property into a PropRegister.
PropCategory	asCategory (Error &=Error::Default()) cons Converts this property into a PropCategory.
NotificationToken	eventAddNotification (NotificationHandler cb, Error &err=Error::Default()) Registers a new property notification event handler.
bool	eventRemoveNotification (NotificationToken token, Error &err=Error::Default()) Unregisters a previously registered property notification event handler.
bool	isSelector (Error &err=Error::Default()) const Indicates whether this property's value changes the meaning and/or value of other properties.
std::vector< Property >	selectedProperties (Error &err=Error::Default()) const Returns the list of properties whose values' meaning depend on this property.

Detailed Description

Represents a property of a component, usually a video capture device.

All property types are derived from Property, e.g. PropInteger, PropCommand or PropEnumeration.

PropEnumEntry is also derived from Property, even though they are not part of the category tree. Nevertheless, enumeration entries support all standard property operations.

To convert a Property to one of the specialized classes, use one of the designated conversion methods such as Property::asInteger() or Property::asFloat().

All Property objects are copyable value types, and comparable using operator==, operator!= and operator<.

Property objects are created in multiple ways:

By calling PropertyMap::find() or one of its typed sibling functions like PropertyMap::findInteger().
By calling PropCategory::features() to get all properties from a category.
By calling PropEnumeration::entries() to get the enumeration entries of an enumeration property.
By calling PropertyMap::all() to get all properties in a property map's category tree.
By calling Property::selectedProperties() to get the properties selected by a property.
By calling one of the conversion function, e.g. Property::asInteger()

The direct get functions and conversion functions can return an invalid property object in case of an error. Check Property::is_valid() or the function's err output parameter. Default-constructed Property objects are also invalid.

Property objects are copyable.

Member Typedef Documentation

◆ NotificationHandler

using NotificationHandler = std::function<void(Property& prop)>

Function prototype for property notification event handlers.

Parameters

[in] prop The property on which the event handler was registered.

◆ NotificationToken

using NotificationToken = void*

Represents a registered callback.

When a callback function is registered using Property::eventAddNotification, a token is returned.

The token can then be used to remove the callback using Property::eventRemoveNotification at a later time.

Member Function Documentation

◆ asBoolean()

PropBoolean asBoolean ( Error & err = Error::Default() ) const

inline

Converts this property into a PropBoolean.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: This property converted into a PropBoolean.
If this property is not a boolean property, an invalid property object is returned.
Check Property::is_valid() or the err output parameter.

◆ asCategory()

PropCategory asCategory ( Error & err = Error::Default() ) const

inline

Converts this property into a PropCategory.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: This property converted into a PropCategory.
If this property is not a category property, an invalid property object is returned.
Check Property::is_valid() or the err output parameter.

◆ asCommand()

PropCommand asCommand ( Error & err = Error::Default() ) const

inline

Converts this property into a PropCommand.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: This property converted into a PropCommand.
If this property is not a command property, an invalid property object is returned.
Check Property::is_valid() or the err output parameter.

◆ asEnumEntry()

PropEnumEntry asEnumEntry ( Error & err = Error::Default() ) const

inline

Converts this property into a PropEnumEntry.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: This property converted into a PropEnumEntry.
If this property is not an enumeration entry property, an invalid property object is returned.
Check Property::is_valid() or the err output parameter.

◆ asEnumeration()

PropEnumeration asEnumeration ( Error & err = Error::Default() ) const

inline

Converts this property into a PropEnumeration.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: This property converted into a PropEnumeration.
If this property is not an enumeration property, an invalid property object is returned.
Check Property::is_valid() or the err output parameter.

◆ asFloat()

PropFloat asFloat ( Error & err = Error::Default() ) const

inline

Converts this property into a PropFloat.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: This property converted into a PropFloat.
If this property is not a float property, an invalid property object is returned.
Check Property::is_valid() or the err output parameter.

◆ asInteger()

PropInteger asInteger ( Error & err = Error::Default() ) const

inline

Converts this property into a PropInteger.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: This property converted into a PropInteger.
If this property is not an integer property, an invalid property object is returned.
Check Property::is_valid() or the err output parameter.

◆ asRegister()

PropRegister asRegister ( Error & err = Error::Default() ) const

inline

Converts this property into a PropRegister.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: This property converted into a PropRegister.
If this property is not a register property, an invalid property object is returned.
Check Property::is_valid() or the err output parameter.

◆ asString()

PropString asString ( Error & err = Error::Default() ) const

inline

Converts this property into a PropString.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: This property converted into a PropString.
If this property is not a string property, an invalid property object is returned.
Check Property::is_valid() or the err output parameter.

◆ description()

std::string description ( Error & err = Error::Default() ) const

inline

Returns a description for the property.

A property's description is a short text that describes the property, usually in more detail than the tooltip.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: A description text for the property, or an empty string if an error occurred.
Check the err output parameter for error code and error message.

◆ displayName()

std::string displayName ( Error & err = Error::Default() ) const

inline

Returns the display name of the property.

A property's display name is a text representation of the property that is meant to be displayed in user interfaces. For example, the display name of the ExposureTime property usually is Exposure Time.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: The display name of the property, or an empty string if an error occurred.
Check the err output parameter for error code and error message.

◆ eventAddNotification()

NotificationToken eventAddNotification	(	NotificationHandler	cb,
		Error &	err = `Error::Default()`
	)

inline

Registers a new property notification event handler.

The property notification handler is called whenever an aspect of the property changes, for example its value or locked status.

Parameters

[in]	cb	Callback function to be called when an aspect of the property has changed.
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: A token that can be used to unregister the callback using .\n If an error occurrs, the function returns nullptr.

See also: Property::eventRemoveNotification

◆ eventRemoveNotification()

bool eventRemoveNotification	(	NotificationToken	token,
		Error &	err = `Error::Default()`
	)

inline

Unregisters a previously registered property notification event handler.

Parameters

[in]	token	A token that was returned when registering an event handler using Property::eventAddNotification().
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: true on success, otherwise false.
Check the err output parameter for error code and error message.

See also: Property::eventAddNotification

◆ is_valid()

bool is_valid ( ) const

inlinenoexcept

Checks whether this property is a valid object.

If there is an error in the function creating this property object, and function was not configured to throw on error, an invalid object is created. All member function calls will fail.

Returns: true, if this property object was constructed successfully, otherwise false.
In case of an error, check the creating function's error parameter for details.

See also: Error Handling

◆ isAvailable()

bool isAvailable ( Error & err = Error::Default() ) const

inline

Checks whether a property is currently available.

If a property is not available, attempts to read or write its value will fail.

A property may become unavailable, if its value does not have a meaning in the current state of the device. The property's availability status can change upon writing to another property.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: true, if the property is currently available, otherwise false. If an error occurred, the function returns false. Check the err output parameter for error code and error message.

See also: Property::isLocked(); Property::isReadOnly()

◆ isLikelyLockedByStream()

bool isLikelyLockedByStream ( Error & err = Error::Default() ) const

inline

Tries to determine whether a property is locked because a data stream is active.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: true, if the property is currently locked, and will likely be unlocked if the data stream is stopped.
false, if the property is not currently locked, or stopping the data stream will probably not lead to the property being unlocked.
If there is an error, this function returns false. Check the err output parameter for error code and error message.

Remarks: For technical reasons, this function cannot always accurately predict the future.

See also: Property::isLocked()

◆ isLocked()

bool isLocked ( Error & err = Error::Default() ) const

inline

Checks whether a property is currently locked.

A locked property can be read, but attempts to write its value will fail.

A property's locked status may change upon writing to another property.

Common examples for locked properties are ExposureTime or Gain if ExposureAuto or GainAuto are enabled.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: true, if the property is currently locked, otherwise false.
If an error occurred, the function returns false. Check the err output parameter for error code and error message.

See also: Property::isAvailable(); Property::isReadOnly(); Property::isLikelyLockedByStream()

◆ isReadOnly()

bool isReadOnly ( Error & err = Error::Default() ) const

inline

Checks whether a property is read-only.

A read-only property will never be writable, the read-only status will never change.

A Common examples for a read-only property is DeviceTemperature.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: true, if the property is read-only, otherwise false.
If an error occurred, the function returns false. Check the err output parameter for error code and error message.

See also: Property::isAvailable(); Property::isLocked()

◆ isSelector()

bool isSelector ( Error & err = Error::Default() ) const

inline

Indicates whether this property's value changes the meaning and/or value of other properties.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: true if this property is a selector, otherwise false.
If an error occurred, the function returns false. Check the err output parameter for error code and error message.

◆ name()

std::string name ( Error & err = Error::Default() ) const

inline

Returns the name of the property.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: The name of the property, or an empty string if an error occurred.
Check the err output parameter for details.

◆ operator!=()

bool operator!= ( const Property & other ) const

inlinenoexcept

Checks whether a property object refers to a different property as another property object.

Parameters

[in] other A property object

Returns: true, if this property refers to a different as other, otherwise false.

◆ operator<()

bool operator< ( const Property & other ) const

inlinenoexcept

Provides an ordering of property objects.

The ordering is arbitrary but stable.

Parameters

other A property object

Returns: A bool indicating the ordering relation between this and other.

◆ operator==()

bool operator== ( const Property & other ) const

inlinenoexcept

Checks whether a property object refers to the same property as another property object.

Parameters

[in] other A property object

Returns: true, if this property refers to the same property as other, otherwise false.

◆ selectedProperties()

std::vector< Property > selectedProperties ( Error & err = Error::Default() ) const

inline

Returns the list of properties whose values' meaning depend on this property.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: A std::vector containing the selected properties.
If an error occurred, the function returns an empty vector. Check the err output parameter for error code and error message.

◆ tooltip()

std::string tooltip ( Error & err = Error::Default() ) const

inline

Returns a tooltip for the property.

A property's tooltip is a text that can be used when a tooltip is required by a user interface. Usually, the tooltip is a very short description of the property.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: A tooltip for the property, or an empty string if an error occurred.
Check the err output parameter for error code and error message.

◆ type()

PropType type ( Error & err = Error::Default() ) const

inline

Returns the type of the property.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: The type of the property, or PropType::Invalid if an error occurred.
Check the err output parameter for details.

◆ visibility()

PropVisibility visibility ( Error & err = Error::Default() ) const

inline

Returns a visibility hint for the property.

The visibility hint can be used to create user interfaces with different complexities. The most commonly used properties have the beginner visibility, while rarely used or diagnostic features might be tagged guru or even invisible.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: The visibility hint for the property.
If there is an error, the function returns PropVisibility::Invisible. Check the err output parameter for details.