Warning

Development of Opal has moved to Codeberg. Please update your bookmarks and local clones to point to the new URL.

---

PropertyMacros

This module provides C++ macros to help with defining QML properties in classes derived from QObject and QGadget.

Instead of writing a Q_PROPERTY entry, with custom signals, setters, and getters, you can now define a property in a single line. The macros will then define all necessary boilerplate for you.

Include the property_macros.h header in your C++ classes to use this module. Documentation is included in the main header file.

Usage

#include <libs/opal/propertymacros/property_macros.h>

class MyClass : public QObject
{
    Q_OBJECT

    // This is a read-write property with signals, getter, and setter.
    // It can be changed from QML and is "notifiable".
    RW_PROPERTY(QString, name, Name, {"Jane Doe"})

    // This is read-only property with signals ("notifiable") and getter.
    // It is unchangeable from QML but manual changes in C++ are possible.
    RO_PROPERTY(uint, age, Age, {30})

public:
    explicit MyClass(QObject *parent = nullptr);
    ~MyClass();
}

Adding QtCreator snippets

You can use snippets in QtCreator to enable autocompletion for the macros. Select "Extras" in the main menu bar, then go to Settings → Text editor → Snippets → Group: C++.

Select "Add" and add the following snippets:

Name	Value
RW_PROPERTY	RW_PROPERTY($type$, $name$, $name:c$, $initializer$)
RO_PROPERTY	RO_PROPERTY($type$, $name$, $initializer$)
RW_PROPERTY_CUSTOM	RW_PROPERTY_CUSTOM($type$, $name$, $name:c$, $initializer$) public slots: void set$name:c$(const $type$& newValue) { m_$name$ = newValue; emit $name$Changed(); }
RO_PROPERTY_CUSTOM	RO_PROPERTY_CUSTOM($type$, $name$, $initializer$) public: $type$ $name$() const { return m_$name$; }

See also QtCreator's documentation of the snippet feature. Snippets are saved in ~/.config/SailfishSDK/qtcreator/snippets/snippets.xml.

Screenshots

This is a purely technical module.

How to use

You do not need to clone this repository if you only intend to use the module in another project. Simply download the latest release bundle from the "Releases" page.

Setup

Follow the main documentation for installing Opal modules here.

Configuration

See doc/gallery.qml for an example. Read the file to get started.

Documentation

Documentation is included in the release bundle and can be added to QtCreator via Extras → Settings → Help → Documentation → Add.

Translations

To use packaged translations in your project, follow the main documentation for using Opal modules here.

You can also contribute translations. If an app uses Opal modules, consider updating its translations at the source (i.e. here), so that all Opal users can benefit from it. Translations are managed using Weblate.

Please prefer Weblate over pull requests (which are still welcome, of course). If you just found a minor problem, you can also leave a comment in the forum or open an issue.

Please include the following details:

1. the language you were using
2. where you found the error
3. the incorrect text
4. the correct translation

See the Qt documentation for details on how to translate date formats to your local format.

Anti-AI policy

Important

• LLM/“AI”-generated contributions are forbidden.
• Using this project in whole or in part for AI training or data mining is likewise forbidden.

Please be transparent, respect the Free Software community, and adhere to the licenses. This is a welcoming place for human creativity and diversity, but LLM/“AI”-generated slop is going against these values.

Apart from all the ethical, moral, legal, environmental, societal, social, political, technical, and overall human, reasons against LLMs/“AI”, I also simply don't have any spare time to review generated contributions.

See also this list for more reasons against supporting “AI”.

License

Copyright (C)  Mirian Margiani
Program: opal-propertymacros

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

This project and related materials must not be used for AI training and/or data mining.