StelProperty Class Reference

Wrapper around a Q_PROPERTY (see the Qt property system for more information) of a specific object, which provides access to the property through a unique ID. More...

#include <StelPropertyMgr.hpp>

Public Slots
QString	getId () const
	Returns the unique ID which is used to identify this property.
QVariant	getValue () const
	Returns the current value of this property as a QVariant.
bool	setValue (const QVariant &value) const
	Sets the value of the property. More...
bool	isReadOnly () const
	If false, setValue can be used.
bool	isSynchronizable () const
	True when this property can be synchronized with external sources. More...
bool	canNotify () const
	If true, the Q_PROPERTY has a NOTIFY signal and the changed() signal can be used.
QMetaType::Type	getType () const
	Returns the data type of the StelProperty.
QMetaProperty	getMetaProp () const
	Returns the actual Q_PROPERTY wrapped by this instance.
QObject *	getTarget () const
	Returns the object to which this property belongs.

Signals
void	changed (const QVariant &newValue)
	Emitted when the value of the property changed.

Protected Slots
void	propertyChanged ()
	Reacts to NOTIFY signals from the object (ignoring the optional parameter), and emits the changed signal.

Protected Member Functions
	StelProperty (const QString &id, QObject *target, const QMetaProperty &prop)

Protected Attributes
QString	id
QObject *	target
QMetaProperty	prop

Friends
class	StelPropertyMgr

Detailed Description

A StelProperty basically is a tuple of <QObject* target, QMetaProperty prop> identified by a unique string ID that allows to access the property prop of the target, without the requirement of needing information about the classes, data types and method signatures involved. The StelPropertyMgr acts as a global registry for this information. In some ways, this is similar to how StelAction worked with boolean properties - but with arbitrary data.

The use of this class allows easy access to non-boolean Stellarium settings for GUI data-binding (see StelDialog for binding functions) and enables external interfaces, such scripting or the Remote Control Plug-in plugin to access and change the property dynamically. The main differences to StelAction are:

• The most important difference is that StelAction is primarily intended for user actions through keyboard shortcuts and/or GUI buttons. StelProperty is not intended to be directly used/configurable by users, but rather as a development tool, to easily access and modify the configurable options of all StelModule objects.
• StelProperty always requires a Q_PROPERTY while StelAction can also work directly with argumentless or boolean slots (i.e. func(), func(bool))
• StelAction actually registers and uses a StelProperty internally, if possible. This is the case when connected to a bool Q_PROPERTY instead of a slot. The created StelProperty has the same ID as the StelAction.
• StelProperty uses the NOTIFY handler to find out when the value changes, even if the change originated outside in non-StelProperty code by calling the WRITE slot directly. StelAction (if not using a StelProperty, as explained in the previous point) has to track boolean states on its own, so there may be a mismatch between the state as StelAction sees it and the real state in some cases

To register a new StelProperty, use the StelPropertyMgr, which can be retrieved using StelApp::getStelPropertyManager(). By default, if you are using a StelModule (and it is registered with the StelModuleMgr), all the properties of your object are automatically exposed through StelProperty instances, so in most cases you don't need to do anything more than define your Q_PROPERTY correctly.

To register all properties of a QObject automatically, you can use StelPropertyMgr::registerObject, which generates a StelProperty with an ID in the format <objectName>.<propertyName> for all Q_PROPERTY definitions on the class. Single properties can be registered with StelPropertyMgr::registerProperty.

The linked Q_PROPERTY must be valid, that is it has to have at least the READ function and/or a MEMBER definition. Furthermore, it is highly recommended to have the NOTIFY signal correctly implemented, so that interested objects can be notified as soon as the property changes. If a property has the WRITE function (or is defined as MEMBER), its value can be set through this class. For optimal results, when changing the property (e.g. through the WRITE slot), it should be checked if the value really has changed before emitting the NOTIFY signal to prevent unnecessary processing. StelProperty supports all data types that work with Q_PROPERTY and QVariant. When using custom types, Q_DECLARE_METATYPE and/or qRegisterMetaType() may be needed. If custom data types are required to be accessed from outside the program (for example through the [Remote Control Plug-in documentation](RemoteControl plugin) ), some further work may be required to serialize/deserialize them, but all standard data types (bool, int, double, QString ...) work seamlessly out of the box.

Each StelProperty is identified by an unique QString ID. Properties registered by StelPropertyMgr::registerObject, which includes all StelModule instances registered with the StelModuleMgr, are identified with an ID in the format <objectName>.<propertyName>.

A full example how to define a Q_PROPERTY, using a StelModule:

class MyCustomModule : public StelModule
{
    Q_OBJECT
    Q_PROPERTY(int awesomeProperty READ getAwesomeProperty WRITE setAwesomeProperty NOTIFY awesomePropertyChanged)

public:
    MyCustomModule()
    {
        //this is not even required for a StelModule
        //because the base class constructor sets the object name to the class name
        //using QMetaObject runtime information
        setObjectName("MyCustomModule");
    }
    ...
    void init() Q_DECL_OVERRIDE
    {
        ...
        // to manually register the property as a StelProperty, this could be used,
        // but it is not even required (nor recommended!) because we are in a StelModule!
        //registerProperty("my_arbitrary_ID_for_MyCustomModule_awesomeProperty", "awesomeProperty");
        ...
    }

    void printProperty()
    {
        qDebug()<<prop;
    }
public slots:
    //Returns the current awesomeProperty value
    int getAwesomeProperty() const { return prop; }

    //Sets the awesomeProperty
    //Don't forget to emit the NOTIFY signal if the value actually changed!
    void setAwesomeProperty(int val) { if(val!=prop) { prop = val; emit awesomePropertyChanged(val); } }
signals:
    void awesomePropertyChanged(int newVal);
private:
    int prop;
};

After registration, the property can then be used from arbitrary other code, like so:

StelProperty* prop = StelApp::getInstance().getStelPropertyManager()->getProperty("MyCustomModule.awesomeProperty");
prop->setValue(123);  //this performs data type conversion if necessary, using QVariant

//alternatively, use this to skip having to get the StelProperty instance:
//StelApp::getInstance().getStelPropertyManager()->setStelPropertyValue("MyCustomModule.awesomeProperty", 123);

//to see the effect
MyCustomModule *module = GETSTELMODULE(MyCustomModule);
module->printProperty(); //prints 123

The changed() signal can be used to detect whenever the property changes. To connect the changed() signal to slots which expect a specific type instead of a QVariant, a StelPropertyProxy implementation can be used. This file defines StelPropertyIntProxy, StelPropertyBoolProxy and StelPropertyDoubleProxy, which use QVariant-based type conversion if necessary.

Of course, the whole StelProperty system does not prevent you from directly using/connecting the properties' signals and slots, which is still recommended if you don't need two-way data binding (for example only reading the current value) because of a lower overhead. Other connections using a StelProperty will work seamlessly.

StelDialog supports helper methods for two-way binding using common Qt Widgets and datatypes.

Note

Good candidates for a StelProperty are properties that do not change too often. This includes most settings configurable through the GUI. Bad examples are properties which potentially change very often (e.g. each frame), such as the current view vector, field of view etc. They may cause considerable overhead if used, and therefore should be avoided.

See also

StelPropertyMgr, StelDialog, StelAction

Member Function Documentation

bool StelProperty::isSynchronizable ( ) const

slot

This is the case when it is writable, and it is marked as STORED true (default).

bool StelProperty::setValue ( const QVariant &  value ) const

slot

This can only be used if isReadOnly is false, meaning a WRITE function is defined on the Q_PROPERTY. Data type conversion is performed, if necessary, using the internal logic of QVariant. This basically means that QVariant::canConvert() from the given value to the actual data type of the Q_PROPERTY must be true for the operation to succeed.

Returns

true if the new value was successfully set