Property Class Reference
Represents a property of a component, usually a video capture device. More...
Inheritance diagram for Property:
![](common/img/classic4_property.png)
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()
|
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()
|
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()
|
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()
|
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()
|
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()
|
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()
|
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()
|
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()
|
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()
|
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()
|
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()
|
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()
|
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, otherwisefalse
.
Check the err output parameter for error code and error message.
- See also
- Property::eventAddNotification
◆ is_valid()
|
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, otherwisefalse
.
In case of an error, check the creating function's error parameter for details.
- See also
- Error Handling
◆ isAvailable()
|
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, otherwisefalse
. If an error occurred, the function returnsfalse
. Check the err output parameter for error code and error message.
- See also
- Property::isLocked()
- Property::isReadOnly()
◆ isLikelyLockedByStream()
|
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 returnsfalse
. 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()
|
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, otherwisefalse
.
If an error occurred, the function returnsfalse
. Check the err output parameter for error code and error message.
- See also
- Property::isAvailable()
- Property::isReadOnly()
- Property::isLikelyLockedByStream()
◆ isReadOnly()
|
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, otherwisefalse
.
If an error occurred, the function returnsfalse
. Check the err output parameter for error code and error message.
- See also
- Property::isAvailable()
- Property::isLocked()
◆ isSelector()
|
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, otherwisefalse
.
If an error occurred, the function returnsfalse
. Check the err output parameter for error code and error message.
◆ name()
|
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 theerr
output parameter for details.
◆ operator!=()
|
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, otherwisefalse
.
◆ operator<()
|
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 betweenthis
andother
.
◆ operator==()
|
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, otherwisefalse
.
◆ selectedProperties()
|
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()
|
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()
|
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 theerr
output parameter for details.
◆ visibility()
|
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 theerr
output parameter for details.