Module qtjambi
Package io.qt.core

Class QObject.QProperty<T>

java.lang.Object
io.qt.internal.QtJambiObject
io.qt.QtObject
io.qt.core.QUntypedPropertyData
io.qt.core.QPropertyData<T>
io.qt.core.QObject.QProperty<T>
All Implemented Interfaces:
QtObjectInterface
Enclosing class:
QObject
public final class QObject.QProperty<T>
extends QPropertyData<T>

The QProperty class enables automatic property bindings. The Java type QProperty corresponds to the C++ type QObjectBindableProperty.

It is only allowed to use QProperty as final-declared member variable of a QObject subtype.

Example:

public class MyObject extends QObject{
    private final QProperty<QColor> color = new QProperty<>();
    public final Signal0 colorChanged = new Signal0();
    
    public QColor color(){
        return color.value();
    }
    
    public void setColor(QColor color){
        color.setValue(color);
    }
    
    public QBindable<QColor> bindableColor(){
        return new QBindable<>(color);
    }
}

QProperty fields should meet the following naming conventions to let metaobject system identify them as accessible property. For a property called "foo" call the QProperty field either "foo", "fooProp" or "fooProperty". Then, QtJambi will identify the method "public T foo()" as it's getter, "public void setFoo(T)" as it's setter, "public final Signal0 fooChanged" as it's notify signal and "public QBindable<T> bindableFoo()" as it's bindable supplier.

Instead of meeting these naming conventions you can use the io.qt.QtProperty... annotations to make the fields and methods identified as property:

public class MyObject extends QObject{
    @QtPropertyMember(name="color")
    private final QProperty<QColor> _c = new QProperty<>();
    
    @QtPropertyNotify(name="color")
    public final Signal0 colorChangeAppeared = new Signal0();
    
    @QtPropertyReader(name="color")
    public QColor get_color(){
        return _c.value();
    }
    
    @QtPropertyWriter(name="color")
    public void change_color(QColor color){
        _c.setValue(color);
    }
    
    @QtPropertyBindable(name="color")
    public QBindable<QColor> get_bindable_color(){
        return new QBindable<>(_c);
    }
}

By declaring a QProperty field public or by using the QtPropertyMember annotation QtJambi identifies a readable, writable and bindable property without the need to specify getter, setter and bindable methods:

public class MyObject extends QObject{
    public final QProperty<QColor> color = new QProperty<>();
    public final Signal0 colorChanged = new Signal0();
}

For primitive-typed implementations see:

  • Constructor Details

    • QProperty

      public QProperty()

      Constructs a property whose type is taken from it's field declaration.

    • QProperty

      public QProperty​(T initialValue)

      Constructs a property with the provided initialValue.

      The property type is taken from it's field declaration. The initialValue has to be assignable to the property type. Otherwise, a default value is used.

      Parameters:
      initialValue -

    • QProperty

      public QProperty​(QUntypedPropertyBinding binding)

      Constructs a property with the provided binding.

      The property type is taken from it's field declaration. The binding's type has to be assignable to the property type. Otherwise, a default value is used.

      Parameters:
      binding -

    • QProperty

      public QProperty​(QtUtilities.Supplier<T> functor)

      Constructs a property bound to the provided functor.

      The property type is taken from it's field declaration. The functor's return type (QtUtilities.Supplier.get()) has to be assignable to the property type. Otherwise, a default value is used.

      Parameters:
      functor -

  • Method Details

    • value

      @QtUninvokable public T value()
      Returns the value of the property. This may evaluate a binding expression that is tied to this property, before returning the value.
      Returns:
      value

    • setValue

      @QtUninvokable public void setValue​(T newValue)

      Assigns newValue to this property and removes the property's associated binding, if present.

      Parameters:
      newValue -

    • setBinding

      @QtUninvokable public QPropertyBinding<T> setBinding​(QPropertyBinding<T> newBinding)

      Associates the value of this property with the provided newBinding expression and returns the previously associated binding.

      The binding's value type (QUntypedPropertyBinding.valueMetaType()) has to be equals to the property's type T, otherwise the property remains unchanged.

      The first time the property value is read, the binding is evaluated. Whenever a dependency of the binding changes, the binding will be re-evaluated the next time the value of this property is read.

      Parameters:
      newBinding -
      Returns:
      oldBinding

    • setBinding

      @QtUninvokable public boolean setBinding​(QUntypedPropertyBinding newBinding)

      Associates the value of this property with the provided newBinding expression.

      The binding's value type (QUntypedPropertyBinding.valueMetaType()) has to be equals to the property's type T, otherwise the property remains unchanged and the method returns false.

      The first time the property value is read, the binding is evaluated. Whenever a dependency of the binding changes, the binding will be re-evaluated the next time the value of this property is read.

      Returns true if the type of this property is the same as the type the binding function returns; false otherwise.

      Parameters:
      newBinding -
      Returns:
      true if types match, false otherwise.

    • setBinding

      @QtUninvokable public QPropertyBinding<T> setBinding​(QtUtilities.Supplier<T> functor)

      Associates the value of this property with the provided functor and returns the previously associated binding.

      The first time the property value is read, the binding is evaluated by invoking QtUtilities.Supplier.get() of functor. Whenever a dependency of the binding changes, the binding will be re-evaluated the next time the value of this property is read.

      Parameters:
      functor -
      Returns:
      oldBinding

    • hasBinding

      @QtUninvokable public boolean hasBinding()
      Checks if the property has a binding.
      Returns:
      true if the property has a binding, false otherwise.

    • binding

      @QtUninvokable public QPropertyBinding<T> binding()
      Returns the binding expression that is associated with this property. A default constructed {@link QPropertyBinding<T>} will be returned if no such association exists.
      Returns:
      binding

    • takeBinding

      @QtUninvokable public QPropertyBinding<T> takeBinding()

      Disassociates the binding expression from this property and returns it.

      After calling this function, the value of the property will only change if you assign a new value to it, or when a new binding is set.

      Returns:
      the removed binding

    • onValueChanged

      @QtUninvokable public QPropertyChangeHandler onValueChanged​(Runnable f)

      Registers the given functor f as a callback that shall be called whenever the value of the property changes.

      The returned property change handler object keeps track of the registration. As long as the change handler is alive i.e. as long as a reference to the QPropertyChangeHandler instance exists, the callback remains installed. When the garbage collection deletes the instance, the callback is de-registered.

      Parameters:
      f -
      Returns:
      property change handler
      See Also:
      QPropertyChangeHandler

    • subscribe

      @QtUninvokable public QPropertyChangeHandler subscribe​(Runnable f)
      Subscribes the given functor f as a callback that is called immediately and whenever the value of the property changes in the future.
      Parameters:
      f -
      Returns:
      property change handler
      See Also:
      QPropertyChangeHandler, onValueChanged(Runnable)

    • getValueBypassingBindings

      @QtUninvokable public final T getValueBypassingBindings()

      Returns the data stored in this property.

      Note: As this will bypass any binding evaluation it might return an outdated value if a binding is set on this property. Using this method will also not register the property access with any currently executing binding.

      Specified by:
      getValueBypassingBindings in class QPropertyData<T>
      Returns:
      value bypassing bindings

    • setValueBypassingBindings

      @QtUninvokable public final boolean setValueBypassingBindings​(T val)

      Sets the data value stored in this property to val.

      Note: Using this method will bypass any potential binding registered for this property.

      Specified by:
      setValueBypassingBindings in class QPropertyData<T>