<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- properties.qdoc -->
<title>The Property System | Qt Core 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qtcore-index.html">Qt Core</a></td><td >The Property System</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#requirements-for-declaring-properties">Requirements for Declaring Properties</a></li>
<li class="level1"><a href="#reading-and-writing-properties-with-the-meta-object-system">Reading and Writing Properties with the Meta-Object System</a></li>
<li class="level1"><a href="#a-simple-example">A Simple Example</a></li>
<li class="level1"><a href="#dynamic-properties">Dynamic Properties</a></li>
<li class="level1"><a href="#properties-and-custom-types">Properties and Custom Types</a></li>
<li class="level1"><a href="#adding-additional-information-to-a-class">Adding Additional Information to a Class</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">The Property System</h1>
<span class="subtitle"></span>
<!-- $$$properties.html-description -->
<div class="descr"> <a name="details"></a>
<p>Qt provides a sophisticated property system similar to the ones supplied by some compiler vendors. However, as a compiler- and platform-independent library, Qt does not rely on non-standard compiler features like <code>__property</code> or <code>[property]</code>. The Qt solution works with <i>any</i> standard C++ compiler on every platform Qt supports. It is based on the <a href="metaobjects.html">Meta-Object System</a> that also provides inter-object communication via <a href="signalsandslots.html">signals and slots</a>.</p>
<a name="requirements-for-declaring-properties"></a>
<h2 id="requirements-for-declaring-properties">Requirements for Declaring Properties</h2>
<p>To declare a property, use the <a href="qobject.html#Q_PROPERTY">Q_PROPERTY()</a> macro in a class that inherits <a href="qobject.html">QObject</a>.</p>
<pre class="cpp">
Q_PROPERTY(type name
(READ getFunction <span class="operator">[</span>WRITE setFunction<span class="operator">]</span> <span class="operator">|</span>
MEMBER memberName <span class="operator">[</span>(READ getFunction <span class="operator">|</span> WRITE setFunction)<span class="operator">]</span>)
<span class="operator">[</span>RESET resetFunction<span class="operator">]</span>
<span class="operator">[</span>NOTIFY notifySignal<span class="operator">]</span>
<span class="operator">[</span>REVISION <span class="type">int</span><span class="operator">]</span>
<span class="operator">[</span>DESIGNABLE bool<span class="operator">]</span>
<span class="operator">[</span>SCRIPTABLE bool<span class="operator">]</span>
<span class="operator">[</span>STORED bool<span class="operator">]</span>
<span class="operator">[</span>USER bool<span class="operator">]</span>
<span class="operator">[</span>CONSTANT<span class="operator">]</span>
<span class="operator">[</span>FINAL<span class="operator">]</span>)
</pre>
<p>Here are some typical examples of property declarations taken from class <a href="../qtwidgets/qwidget.html">QWidget</a>.</p>
<pre class="cpp">
Q_PROPERTY(bool focus READ hasFocus)
Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled)
Q_PROPERTY(<span class="type"><a href="../qtgui/qcursor.html">QCursor</a></span> cursor READ cursor WRITE setCursor RESET unsetCursor)
</pre>
<p>Here is an example showing how to export member variables as Qt properties using the <code>MEMBER</code> keyword. Note that a <code>NOTIFY</code> signal must be specified to allow QML property bindings.</p>
<pre class="cpp">
Q_PROPERTY(<span class="type"><a href="../qtgui/qcolor.html">QColor</a></span> color MEMBER m_color NOTIFY colorChanged)
Q_PROPERTY(<span class="type"><a href="qtglobal.html#qreal-typedef">qreal</a></span> spacing MEMBER m_spacing NOTIFY spacingChanged)
Q_PROPERTY(<span class="type"><a href="qstring.html">QString</a></span> text MEMBER m_text NOTIFY textChanged)
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="keyword">signals</span>:
<span class="type">void</span> colorChanged();
<span class="type">void</span> spacingChanged();
<span class="type">void</span> textChanged(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>newText);
<span class="keyword">private</span>:
<span class="type"><a href="../qtgui/qcolor.html">QColor</a></span> m_color;
<span class="type"><a href="qtglobal.html#qreal-typedef">qreal</a></span> m_spacing;
<span class="type"><a href="qstring.html">QString</a></span> m_text;
</pre>
<p>A property behaves like a class data member, but it has additional features accessible through the <a href="metaobjects.html">Meta-Object System</a>.</p>
<ul>
<li>A <code>READ</code> accessor function is required if no <code>MEMBER</code> variable was specified. It is for reading the property value. Ideally, a const function is used for this purpose, and it must return either the property's type or a const reference to that type. e.g., <a href="../qtwidgets/qwidget.html#focus-prop">QWidget::focus</a> is a read-only property with <code>READ</code> function, <a href="../qtwidgets/qwidget.html#focus-prop">QWidget::hasFocus</a>().</li>
<li>A <code>WRITE</code> accessor function is optional. It is for setting the property value. It must return void and must take exactly one argument, either of the property's type or a pointer or reference to that type. e.g., <a href="../qtwidgets/qwidget.html#enabled-prop">QWidget::enabled</a> has the <code>WRITE</code> function <a href="../qtwidgets/qwidget.html#enabled-prop">QWidget::setEnabled</a>(). Read-only properties do not need <code>WRITE</code> functions. e.g., <a href="../qtwidgets/qwidget.html#focus-prop">QWidget::focus</a> has no <code>WRITE</code> function.</li>
<li>A <code>MEMBER</code> variable association is required if no <code>READ</code> accessor function is specified. This makes the given member variable readable and writable without the need of creating <code>READ</code> and <code>WRITE</code> accessor functions. It's still possible to use <code>READ</code> or <code>WRITE</code> accessor functions in addition to <code>MEMBER</code> variable association (but not both), if you need to control the variable access.</li>
<li>A <code>RESET</code> function is optional. It is for setting the property back to its context specific default value. e.g., <a href="../qtwidgets/qwidget.html#cursor-prop">QWidget::cursor</a> has the typical <code>READ</code> and <code>WRITE</code> functions, <a href="../qtwidgets/qwidget.html#cursor-prop">QWidget::cursor</a>() and <a href="../qtwidgets/qwidget.html#cursor-prop">QWidget::setCursor</a>(), and it also has a <code>RESET</code> function, <a href="../qtwidgets/qwidget.html#cursor-prop">QWidget::unsetCursor</a>(), since no call to <a href="../qtwidgets/qwidget.html#cursor-prop">QWidget::setCursor</a>() can mean <i>reset to the context specific cursor</i>. The <code>RESET</code> function must return void and take no parameters.</li>
<li>A <code>NOTIFY</code> signal is optional. If defined, it should specify one existing signal in that class that is emitted whenever the value of the property changes. <code>NOTIFY</code> signals for <code>MEMBER</code> variables must take zero or one parameter, which must be of the same type as the property. The parameter will take the new value of the property. The <code>NOTIFY</code> signal should only be emitted when the property has really been changed, to avoid bindings being unnecessarily re-evaluated in QML, for example. Qt emits automatically that signal when needed for MEMBER properties that do not have an explicit setter.</li>
<li>A <code>REVISION</code> number is optional. If included, it defines the property and its notifier signal to be used in a particular revision of the API (usually for exposure to QML). If not included, it defaults to 0.</li>
<li>The <code>DESIGNABLE</code> attribute indicates whether the property should be visible in the property editor of GUI design tool (e.g., Qt Designer). Most properties are <code>DESIGNABLE</code> (default true). Instead of true or false, you can specify a boolean member function.</li>
<li>The <code>SCRIPTABLE</code> attribute indicates whether this property should be accessible by a scripting engine (default true). Instead of true or false, you can specify a boolean member function.</li>
<li>The <code>STORED</code> attribute indicates whether the property should be thought of as existing on its own or as depending on other values. It also indicates whether the property value must be saved when storing the object's state. Most properties are <code>STORED</code> (default true), but e.g., <a href="../qtwidgets/qwidget.html#minimumWidth-prop">QWidget::minimumWidth</a>() has <code>STORED</code> false, because its value is just taken from the width component of property <a href="../qtwidgets/qwidget.html#minimumSize-prop">QWidget::minimumSize</a>(), which is a <a href="qsize.html">QSize</a>.</li>
<li>The <code>USER</code> attribute indicates whether the property is designated as the user-facing or user-editable property for the class. Normally, there is only one <code>USER</code> property per class (default false). e.g., <a href="../qtwidgets/qabstractbutton.html#checked-prop">QAbstractButton::checked</a> is the user editable property for (checkable) buttons. Note that <a href="../qtwidgets/qitemdelegate.html">QItemDelegate</a> gets and sets a widget's <code>USER</code> property.</li>
<li>The presence of the <code>CONSTANT</code> attibute indicates that the property value is constant. For a given object instance, the READ method of a constant property must return the same value every time it is called. This constant value may be different for different instances of the object. A constant property cannot have a WRITE method or a NOTIFY signal.</li>
<li>The presence of the <code>FINAL</code> attribute indicates that the property will not be overridden by a derived class. This can be used for performance optimizations in some cases, but is not enforced by moc. Care must be taken never to override a <code>FINAL</code> property.</li>
</ul>
<p>The <code>READ</code>, <code>WRITE</code>, and <code>RESET</code> functions can be inherited. They can also be virtual. When they are inherited in classes where multiple inheritance is used, they must come from the first inherited class.</p>
<p>The property type can be any type supported by <a href="qvariant.html">QVariant</a>, or it can be a user-defined type. In this example, class <a href="qdate.html">QDate</a> is considered to be a user-defined type.</p>
<pre class="cpp">
Q_PROPERTY(<span class="type"><a href="qdate.html">QDate</a></span> date READ getDate WRITE setDate)
</pre>
<p>Because <a href="qdate.html">QDate</a> is user-defined, you must include the <code><QDate></code> header file with the property declaration.</p>
<p>For historical reasons, <i>QMap</i> and <i>QList</i> as property types are synonym of <i>QVariantMap</i> and <i>QVariantList</i>.</p>
<a name="reading-and-writing-properties-with-the-meta-object-system"></a>
<h2 id="reading-and-writing-properties-with-the-meta-object-system">Reading and Writing Properties with the Meta-Object System</h2>
<p>A property can be read and written using the generic functions <a href="qobject.html#property">QObject::property</a>() and <a href="qobject.html#setProperty">QObject::setProperty</a>(), without knowing anything about the owning class except the property's name. In the code snippet below, the call to <a href="../qtwidgets/qabstractbutton.html#down-prop">QAbstractButton::setDown</a>() and the call to <a href="qobject.html#setProperty">QObject::setProperty</a>() both set property "down".</p>
<pre class="cpp">
<span class="type"><a href="../qtwidgets/qpushbutton.html">QPushButton</a></span> <span class="operator">*</span>button <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="../qtwidgets/qpushbutton.html">QPushButton</a></span>;
<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>object <span class="operator">=</span> button;
button<span class="operator">-</span><span class="operator">></span>setDown(<span class="keyword">true</span>);
object<span class="operator">-</span><span class="operator">></span>setProperty(<span class="string">"down"</span><span class="operator">,</span> <span class="keyword">true</span>);
</pre>
<p>Accessing a property through its <code>WRITE</code> accessor is the better of the two, because it is faster and gives better diagnostics at compile time, but setting the property this way requires that you know about the class at compile time. Accessing properties by name lets you access classes you don't know about at compile time. You can <i>discover</i> a class's properties at run time by querying its <a href="qobject.html">QObject</a>, <a href="qmetaobject.html">QMetaObject</a>, and <a href="qmetaproperty.html">QMetaProperties</a>.</p>
<pre class="cpp">
<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>object <span class="operator">=</span> <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="keyword">const</span> <span class="type"><a href="qmetaobject.html">QMetaObject</a></span> <span class="operator">*</span>metaobject <span class="operator">=</span> object<span class="operator">-</span><span class="operator">></span>metaObject();
<span class="type">int</span> count <span class="operator">=</span> metaobject<span class="operator">-</span><span class="operator">></span>propertyCount();
<span class="keyword">for</span> (<span class="type">int</span> i<span class="operator">=</span><span class="number">0</span>; i<span class="operator"><</span>count; <span class="operator">+</span><span class="operator">+</span>i) {
<span class="type"><a href="qmetaproperty.html">QMetaProperty</a></span> metaproperty <span class="operator">=</span> metaobject<span class="operator">-</span><span class="operator">></span>property(i);
<span class="keyword">const</span> <span class="type">char</span> <span class="operator">*</span>name <span class="operator">=</span> metaproperty<span class="operator">.</span>name();
<span class="type"><a href="qvariant.html">QVariant</a></span> value <span class="operator">=</span> object<span class="operator">-</span><span class="operator">></span>property(name);
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
}
</pre>
<p>In the above snippet, <a href="qmetaobject.html#property">QMetaObject::property</a>() is used to get <a href="qmetaproperty.html">metadata</a> about each property defined in some unknown class. The property name is fetched from the metadata and passed to <a href="qobject.html#property">QObject::property</a>() to get the <a href="qvariant.html">value</a> of the property in the current <a href="qobject.html">object</a>.</p>
<a name="a-simple-example"></a>
<h2 id="a-simple-example">A Simple Example</h2>
<p>Suppose we have a class MyClass, which is derived from <a href="qobject.html">QObject</a> and which uses the <a href="qobject.html#Q_OBJECT">Q_OBJECT</a> macro in its private section. We want to declare a property in MyClass to keep track of a priority value. The name of the property will be <i>priority</i>, and its type will be an enumeration type named <i>Priority</i>, which is defined in MyClass.</p>
<p>We declare the property with the <a href="qobject.html#Q_PROPERTY">Q_PROPERTY</a>() macro in the private section of the class. The required <code>READ</code> function is named <code>priority</code>, and we include a <code>WRITE</code> function named <code>setPriority</code>. The enumeration type must be registered with the <a href="metaobjects.html">Meta-Object System</a> using the <a href="qobject.html#Q_ENUM">Q_ENUM</a>() macro. Registering an enumeration type makes the enumerator names available for use in calls to <a href="qobject.html#setProperty">QObject::setProperty</a>(). We must also provide our own declarations for the <code>READ</code> and <code>WRITE</code> functions. The declaration of MyClass then might look like this:</p>
<pre class="cpp">
<span class="keyword">class</span> MyClass : <span class="keyword">public</span> <span class="type"><a href="qobject.html">QObject</a></span>
{
Q_OBJECT
Q_PROPERTY(Priority priority READ priority WRITE setPriority NOTIFY priorityChanged)
<span class="keyword">public</span>:
MyClass(<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>parent <span class="operator">=</span> <span class="number">0</span>);
<span class="operator">~</span>MyClass();
<span class="keyword">enum</span> Priority { High<span class="operator">,</span> Low<span class="operator">,</span> VeryHigh<span class="operator">,</span> VeryLow };
Q_ENUM(Priority)
<span class="type">void</span> setPriority(Priority priority)
{
m_priority <span class="operator">=</span> priority;
<span class="keyword">emit</span> priorityChanged(priority);
}
Priority priority() <span class="keyword">const</span>
{ <span class="keyword">return</span> m_priority; }
<span class="keyword">signals</span>:
<span class="type">void</span> priorityChanged(Priority);
<span class="keyword">private</span>:
Priority m_priority;
};
</pre>
<p>The <code>READ</code> function is const and returns the property type. The <code>WRITE</code> function returns void and has exactly one parameter of the property type. The meta-object compiler enforces these requirements.</p>
<p>Given a pointer to an instance of MyClass or a pointer to a <a href="qobject.html">QObject</a> that is an instance of MyClass, we have two ways to set its priority property:</p>
<pre class="cpp">
MyClass <span class="operator">*</span>myinstance <span class="operator">=</span> <span class="keyword">new</span> MyClass;
<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>object <span class="operator">=</span> myinstance;
myinstance<span class="operator">-</span><span class="operator">></span>setPriority(MyClass<span class="operator">::</span>VeryHigh);
object<span class="operator">-</span><span class="operator">></span>setProperty(<span class="string">"priority"</span><span class="operator">,</span> <span class="string">"VeryHigh"</span>);
</pre>
<p>In the example, the enumeration type that is the property type is declared in MyClass and registered with the <a href="metaobjects.html">Meta-Object System</a> using the <a href="qobject.html#Q_ENUM">Q_ENUM</a>() macro. This makes the enumeration values available as strings for use as in the call to <a href="qobject.html#setProperty">setProperty()</a>. Had the enumeration type been declared in another class, its fully qualified name (i.e., OtherClass::Priority) would be required, and that other class would also have to inherit <a href="qobject.html">QObject</a> and register the enumeration type there using the <a href="qobject.html#Q_ENUM">Q_ENUM</a>() macro.</p>
<p>A similar macro, <a href="qobject.html#Q_FLAG">Q_FLAG</a>(), is also available. Like <a href="qobject.html#Q_ENUM">Q_ENUM</a>(), it registers an enumeration type, but it marks the type as being a set of <i>flags</i>, i.e. values that can be OR'd together. An I/O class might have enumeration values <code>Read</code> and <code>Write</code> and then <a href="qobject.html#setProperty">QObject::setProperty</a>() could accept <code>Read | Write</code>. <a href="qobject.html#Q_FLAG">Q_FLAG</a>() should be used to register this enumeration type.</p>
<a name="dynamic-properties"></a>
<h2 id="dynamic-properties">Dynamic Properties</h2>
<p><a href="qobject.html#setProperty">QObject::setProperty</a>() can also be used to add <i>new</i> properties to an instance of a class at runtime. When it is called with a name and a value, if a property with the given name exists in the <a href="qobject.html">QObject</a>, and if the given value is compatible with the property's type, the value is stored in the property, and true is returned. If the value is <i>not</i> compatible with the property's type, the property is <i>not</i> changed, and false is returned. But if the property with the given name doesn't exist in the <a href="qobject.html">QObject</a> (i.e., if it wasn't declared with <a href="qobject.html#Q_PROPERTY">Q_PROPERTY</a>()), a new property with the given name and value is automatically added to the <a href="qobject.html">QObject</a>, but false is still returned. This means that a return of false can't be used to determine whether a particular property was actually set, unless you know in advance that the property already exists in the <a href="qobject.html">QObject</a>.</p>
<p>Note that <i>dynamic</i> properties are added on a per instance basis, i.e., they are added to <a href="qobject.html">QObject</a>, not <a href="qmetaobject.html">QMetaObject</a>. A property can be removed from an instance by passing the property name and an invalid <a href="qvariant.html">QVariant</a> value to <a href="qobject.html#setProperty">QObject::setProperty</a>(). The default constructor for <a href="qvariant.html">QVariant</a> constructs an invalid <a href="qvariant.html">QVariant</a>.</p>
<p>Dynamic properties can be queried with <a href="qobject.html#property">QObject::property</a>(), just like properties declared at compile time with <a href="qobject.html#Q_PROPERTY">Q_PROPERTY</a>().</p>
<a name="properties-and-custom-types"></a>
<h2 id="properties-and-custom-types">Properties and Custom Types</h2>
<p>Custom types used by properties need to be registered using the <a href="qmetatype.html#Q_DECLARE_METATYPE">Q_DECLARE_METATYPE</a>() macro so that their values can be stored in <a href="qvariant.html">QVariant</a> objects. This makes them suitable for use with both static properties declared using the <a href="qobject.html#Q_PROPERTY">Q_PROPERTY</a>() macro in class definitions and dynamic properties created at run-time.</p>
<a name="adding-additional-information-to-a-class"></a>
<h2 id="adding-additional-information-to-a-class">Adding Additional Information to a Class</h2>
<p>Connected to the property system is an additional macro, <a href="qobject.html#Q_CLASSINFO">Q_CLASSINFO</a>(), that can be used to attach additional <i>name</i>--<i>value</i> pairs to a class's meta-object, for example:</p>
<pre class="cpp">
Q_CLASSINFO(<span class="string">"Version"</span><span class="operator">,</span> <span class="string">"3.0.0"</span>)
</pre>
<p>Like other meta-data, class information is accessible at run-time through the meta-object; see <a href="qmetaobject.html#classInfo">QMetaObject::classInfo</a>() for details.</p>
</div>
<p><b>See also </b><a href="metaobjects.html">Meta-Object System</a>, <a href="signalsandslots.html">Signals and Slots</a>, <a href="qmetatype.html#Q_DECLARE_METATYPE">Q_DECLARE_METATYPE</a>(), <a href="qmetatype.html">QMetaType</a>, and <a href="qvariant.html">QVariant</a>.</p>
<!-- @@@properties.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
armv5tl
>
media
>
core-updates
>
by-pkgid
>
768f7d9f703884aa2562bf0a651086df
>
files
>
260
