Property Class Reference

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

Inheritance diagram for Property:

PropBoolean PropCategory PropCommand PropEnumEntry PropEnumeration PropFloat PropInteger PropRegister PropString

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< PropertyselectedProperties (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:

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]propThe 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]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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]cbCallback function to be called when an aspect of the property has changed.
[out]errReference 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]tokenA token that was returned when registering an event handler using Property::eventAddNotification().
[out]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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]otherA 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
otherA 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]otherA 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]errReference 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]errReference 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]errReference 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]errReference 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.