diff options
author | Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@theqtcompany.com> | 2015-10-13 10:55:08 +0200 |
---|---|---|
committer | Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@theqtcompany.com> | 2015-10-26 09:17:46 +0000 |
commit | 699c44e3dc2d7099fdd87060c39309e318c55616 (patch) | |
tree | e4895a5e4ebc047e7c1f5bf7d164f4544f9e21fb /src/compositor | |
parent | 36e62983bfe53a6e1f79bf6acaa052bc58a5af63 (diff) |
Add documentation to Qt Wayland Compositor
This adds some preliminary documentation for the Qt Wayland Compositor.
There are a few classes which remain undocumented. The documentation
in some areas may be a bit minimal, but this can be expanded gradually
with code examples and more details.
Change-Id: I5d285a5a25e8602ac2fdddc84c3fd217e7b77c95
Reviewed-by: Paul Olav Tvete <paul.tvete@theqtcompany.com>
Reviewed-by: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@theqtcompany.com>
Diffstat (limited to 'src/compositor')
29 files changed, 2014 insertions, 38 deletions
diff --git a/src/compositor/compositor.pro b/src/compositor/compositor.pro index 127ed2577..6a64cd70a 100644 --- a/src/compositor/compositor.pro +++ b/src/compositor/compositor.pro @@ -11,6 +11,7 @@ CONFIG -= precompile_header CONFIG += link_pkgconfig DEFINES += QT_WAYLAND_WINDOWMANAGER_SUPPORT +QMAKE_DOCS = $$PWD/doc/compositor.qdocconf !contains(QT_CONFIG, no-pkg-config) { PKGCONFIG_PRIVATE += wayland-server diff --git a/src/compositor/compositor_api/qwaylandbufferref.cpp b/src/compositor/compositor_api/qwaylandbufferref.cpp index 057a47148..cff9bc35d 100644 --- a/src/compositor/compositor_api/qwaylandbufferref.cpp +++ b/src/compositor/compositor_api/qwaylandbufferref.cpp @@ -52,12 +52,27 @@ public: } }; +/*! + * \class QWaylandBufferRef + * \inmodule QtWaylandCompositor + * \brief A class which holds a reference to a surface buffer + * + * This class can be used to reference a surface buffer. As long as a reference + * to the buffer exists, it is owned by the compositor and the client cannot modify it. + */ + +/*! + * Constructs a null buffer ref. + */ QWaylandBufferRef::QWaylandBufferRef() : d(new QWaylandBufferRefPrivate) { d->buffer = 0; } +/*! + * Constructs a reference to \a buffer. + */ QWaylandBufferRef::QWaylandBufferRef(QtWayland::SurfaceBuffer *buffer) : d(new QWaylandBufferRefPrivate) { @@ -66,6 +81,9 @@ QWaylandBufferRef::QWaylandBufferRef(QtWayland::SurfaceBuffer *buffer) buffer->ref(); } +/*! + * Creates a new reference to the buffer referenced by \a ref. + */ QWaylandBufferRef::QWaylandBufferRef(const QWaylandBufferRef &ref) : d(new QWaylandBufferRefPrivate) { @@ -74,6 +92,9 @@ QWaylandBufferRef::QWaylandBufferRef(const QWaylandBufferRef &ref) d->buffer->ref(); } +/*! + * Dereferences the buffer. + */ QWaylandBufferRef::~QWaylandBufferRef() { if (d->buffer) @@ -81,6 +102,10 @@ QWaylandBufferRef::~QWaylandBufferRef() delete d; } +/*! + * Assigns \a ref to this buffer. The previously referenced buffer is + * dereferenced and the new one gets a new reference. + */ QWaylandBufferRef &QWaylandBufferRef::operator=(const QWaylandBufferRef &ref) { if (d->buffer) @@ -93,36 +118,66 @@ QWaylandBufferRef &QWaylandBufferRef::operator=(const QWaylandBufferRef &ref) return *this; } +/*! + * Returns true if this QWaylandBufferRef references the same buffer as \a ref. + * Otherwise returns false. + */ bool QWaylandBufferRef::operator==(const QWaylandBufferRef &ref) { return d->buffer == ref.d->buffer; } +/*! + * Returns false if this QWaylandBufferRef references the same buffer as \a ref. + * Otherwise returns true. + */ bool QWaylandBufferRef::operator!=(const QWaylandBufferRef &ref) { return d->buffer != ref.d->buffer; } +/*! + * Returns true if this QWaylandBufferRef does not reference a buffer. + * Otherwise returns false. + * + * \sa hasBuffer() + */ bool QWaylandBufferRef::isNull() const { return !d->buffer; } +/*! + * Returns true if this QWaylandBufferRef references a buffer. Otherwise returns false. + * + * \sa isNull() + */ bool QWaylandBufferRef::hasBuffer() const { return d->buffer; } +/*! + * Returns true if this QWaylandBufferRef references a buffer that + * has been destroyed. Otherwise returns false. + */ bool QWaylandBufferRef::isDestroyed() const { return d->buffer && d->buffer->isDestroyed(); } +/*! + * Returns the Wayland resource for the buffer. + */ struct ::wl_resource *QWaylandBufferRef::wl_buffer() const { return d->buffer ? d->buffer->waylandBufferHandle() : Q_NULLPTR; } +/*! + * Returns the size of the buffer. + * If the buffer referenced is null, an invalid QSize() is returned. + */ QSize QWaylandBufferRef::size() const { if (d->nullOrDestroyed()) @@ -131,6 +186,11 @@ QSize QWaylandBufferRef::size() const return d->buffer->size(); } +/*! + * Returns the origin of the buffer. + * If the buffer referenced is null, QWaylandSurface::OriginBottomLeft + * is returned. + */ QWaylandSurface::Origin QWaylandBufferRef::origin() const { if (d->buffer) @@ -139,6 +199,9 @@ QWaylandSurface::Origin QWaylandBufferRef::origin() const return QWaylandSurface::OriginBottomLeft; } +/*! + * Returns true if the buffer is a shared memory buffer. Otherwise returns false. + */ bool QWaylandBufferRef::isShm() const { if (d->nullOrDestroyed()) @@ -147,6 +210,9 @@ bool QWaylandBufferRef::isShm() const return d->buffer->isShm(); } +/*! + * Returns an image with the contents of the buffer. + */ QImage QWaylandBufferRef::image() const { if (d->nullOrDestroyed()) @@ -155,6 +221,11 @@ QImage QWaylandBufferRef::image() const return d->buffer->image(); } +/*! + * Binds the buffer to the current OpenGL texture. This may + * perform a copy of the buffer data, depending on the platform + * and the type of the buffer. + */ void QWaylandBufferRef::bindToTexture() const { if (d->nullOrDestroyed()) diff --git a/src/compositor/compositor_api/qwaylandclient.cpp b/src/compositor/compositor_api/qwaylandclient.cpp index 8eb1eb1b6..65f1d6349 100644 --- a/src/compositor/compositor_api/qwaylandclient.cpp +++ b/src/compositor/compositor_api/qwaylandclient.cpp @@ -84,6 +84,27 @@ public: Listener listener; }; +/*! + * \qmltype WaylandClient + * \inqmlmodule QtWayland.Compositor + * \brief A client connecting to the WaylandCompositor. + * + * This type represents a client connecting to the compositor using the Wayland protocol. + * It corresponds to the Wayland interface wl_client. + */ + +/*! + * \class QWaylandClient + * \inmodule QtWaylandCompositor + * \brief A client connecting to the QWaylandCompositor. + * + * This class corresponds to a client connecting to the compositor using the Wayland protocol. + * It corresponds to the Wayland interface wl_client. + */ + +/*! + * Constructs a QWaylandClient for the \a compositor and the Wayland \a client. + */ QWaylandClient::QWaylandClient(QWaylandCompositor *compositor, wl_client *client) : QObject(*new QWaylandClientPrivate(compositor, client)) { @@ -97,6 +118,9 @@ QWaylandClient::QWaylandClient(QWaylandCompositor *compositor, wl_client *client QWaylandCompositorPrivate::get(compositor)->addClient(this); } +/*! + * Destroys the QWaylandClient. + */ QWaylandClient::~QWaylandClient() { Q_D(QWaylandClient); @@ -107,6 +131,11 @@ QWaylandClient::~QWaylandClient() QWaylandCompositorPrivate::get(d->compositor)->removeClient(this); } +/*! + * Returns the QWaylandClient corresponding to the Wayland client \a wl_client and \a compositor. + * If a QWaylandClient has not already been created for \a client, it is + * created and returned. + */ QWaylandClient *QWaylandClient::fromWlClient(QWaylandCompositor *compositor, wl_client *wlClient) { if (!wlClient) @@ -132,6 +161,9 @@ QWaylandClient *QWaylandClient::fromWlClient(QWaylandCompositor *compositor, wl_ return client; } +/*! + * Returns the Wayland client of this QWaylandClient. + */ wl_client *QWaylandClient::client() const { Q_D(const QWaylandClient); @@ -139,6 +171,17 @@ wl_client *QWaylandClient::client() const return d->client; } +/*! + * \qmlproperty int QtWaylandCompositor::WaylandClient::userId + * + * This property holds the user id of this WaylandClient. + */ + +/*! + * \property QWaylandClient::userId + * + * This property holds the user id of this QWaylandClient. + */ qint64 QWaylandClient::userId() const { Q_D(const QWaylandClient); @@ -146,6 +189,17 @@ qint64 QWaylandClient::userId() const return d->uid; } +/*! + * \qmlproperty int QtWaylandCompositor::WaylandClient::groupId + * + * This property holds the group id of this WaylandClient. + */ + +/*! + * \property int QWaylandClient::groupId + * + * This property holds the group id of this QWaylandClient. + */ qint64 QWaylandClient::groupId() const { Q_D(const QWaylandClient); @@ -153,6 +207,17 @@ qint64 QWaylandClient::groupId() const return d->gid; } +/*! + * \qmlproperty int QtWaylandCompositor::WaylandClient::processId + * + * This property holds the process id of this WaylandClient. + */ + +/*! + * \property QWaylandClient::processId + * + * This property holds the process id of this QWaylandClient. + */ qint64 QWaylandClient::processId() const { Q_D(const QWaylandClient); @@ -160,13 +225,31 @@ qint64 QWaylandClient::processId() const return d->pid; } -void QWaylandClient::kill(int sig) +/*! + * \qmlmethod void QtWaylandCompositor::WaylandClient::kill(signal) + * + * Kills the client with the specified \a signal. + */ + +/*! + * Kills the client with the specified \a signal. + */ +void QWaylandClient::kill(int signal) { Q_D(QWaylandClient); - ::kill(d->pid, sig); + ::kill(d->pid, signal); } +/*! + * \qmlmethod void QtWaylandCompositor::WaylandClient::close() + * + * Closes the client + */ + +/*! + * Closes the client. + */ void QWaylandClient::close() { Q_D(QWaylandClient); diff --git a/src/compositor/compositor_api/qwaylandclient.h b/src/compositor/compositor_api/qwaylandclient.h index 42051cb61..800013d3d 100644 --- a/src/compositor/compositor_api/qwaylandclient.h +++ b/src/compositor/compositor_api/qwaylandclient.h @@ -70,7 +70,7 @@ public: qint64 processId() const; - Q_INVOKABLE void kill(int sig = SIGTERM); + Q_INVOKABLE void kill(int signal = SIGTERM); public Q_SLOTS: void close(); diff --git a/src/compositor/compositor_api/qwaylandcompositor.cpp b/src/compositor/compositor_api/qwaylandcompositor.cpp index ccc4b1dfd..99819d0b5 100644 --- a/src/compositor/compositor_api/qwaylandcompositor.cpp +++ b/src/compositor/compositor_api/qwaylandcompositor.cpp @@ -233,15 +233,38 @@ void QWaylandCompositorPrivate::addPolishObject(QObject *object) } /*! + \qmlsignal void QtWaylandCompositor::WaylandCompositor::createSurface(object client, int id, int version) + + This signal is emitted when a client has created a surface. + The slot connecting to this signal may create and initialize + a WaylandSurface instance in the scope of the slot. + Otherwise a default surface is created. +*/ + +/*! \fn void QWaylandCompositor::createSurface(QWaylandClient *client, uint id, int version) - This signal is emitted when a client has created a wl_surface object on the - server side. The slot connecting to this signal has to create and initialize - a QWaylandSurface instance in the scope of the slot. Connections to this - signal has to be of Qt::DirectConnection connection type. + This signal is emitted when a client has created a surface. + The slot connecting to this signal may create and initialize + a QWaylandSurface instance in the scope of the slot. + Otherwise a default surface is created. + Connections to this signal must be of Qt::DirectConnection connection type. */ +/* + \qmlsignal void surfaceCreated(QWaylandSurface *surface) + + This signal is emitted when a new WaylandSurface instance has been created. +*/ + +/* + \fn void surfaceCreated(QWaylandSurface *surface) + + This signal is emitted when a new QWaylandSurface instance has been created. +*/ + + void QWaylandCompositorPrivate::compositor_create_surface(Resource *resource, uint32_t id) { Q_Q(QWaylandCompositor); @@ -350,37 +373,105 @@ void QWaylandCompositorPrivate::loadServerBufferIntegration() #endif } +/*! + \qmltype WaylandCompositor + \inqmlmodule QtWayland.Compositor + \brief Type managing the Wayland display server. + + The WaylandCompositor manages the connections to the clients, as well as the different + \l{WaylandOutput}{outputs} and \l{WaylandInput}{input devices}. + + Normally, a compositor application will have a single WaylandCompositor + instance, which can have several outputs as children. When a client + requests the compositor to create a surface, the request is handled by + the onCreateSurface handler. + + Extensions that are supported by the compositor should be instantiated and added to the + extensions property. +*/ + + +/*! + \class QWaylandCompositor + \inmodule QtWaylandCompositor + \brief Class managing the Wayland display server. + + The QWaylandCompositor manages the connections to the clients, as well as the different \l{QWaylandOutput}{outputs} + and \l{QWaylandInput}{input devices}. + + Normally, a compositor application will have a single WaylandCompositor + instance, which can have several outputs as children. +*/ + +/*! + * Constructs a QWaylandCompositor with the given \a parent. + */ QWaylandCompositor::QWaylandCompositor(QObject *parent) : QWaylandObject(*new QWaylandCompositorPrivate(this), parent) { } +/*! + * \internal + * Constructs a QWaylandCompositor with the private object \a dptr and \a parent. + */ QWaylandCompositor::QWaylandCompositor(QWaylandCompositorPrivate &dptr, QObject *parent) : QWaylandObject(dptr, parent) { } +/*! + * Destroys the QWaylandCompositor + */ QWaylandCompositor::~QWaylandCompositor() { } +/*! + * Initializes the QWaylandCompositor. + * If you override this function in your subclass, be sure to call the base class implementation. + */ void QWaylandCompositor::create() { Q_D(QWaylandCompositor); d->init(); } +/*! + * Returns true if the QWaylandCompositor has been initialized. Otherwise returns false. + */ bool QWaylandCompositor::isCreated() const { Q_D(const QWaylandCompositor); return d->initialized; } +/*! + * \qmlproperty string QtWaylandCompositor::WaylandCompositor::socketName + * + * This property holds the socket name used by WaylandCompositor to communicate with + * clients. It must be set before the component is completed. + * + * If the socketName is empty (the default), the contents of the environment + * variable WAYLAND_DISPLAY is used instead. If this is not set, the + * default "wayland-0" is used. + */ + +/*! + * \property QWaylandCompositor::socketName + * + * This property holds the socket name used by QWaylandCompositor to communicate with + * clients. This must be set before the QWaylandCompositor is \l{create()}{created}. + * + * If the socketName is empty (the default), the contents of the environment + * variable WAYLAND_DISPLAY is used instead. If this is not set, the + * default "wayland-0" is used. + */ void QWaylandCompositor::setSocketName(const QByteArray &name) { Q_D(QWaylandCompositor); if (d->initialized) { - qWarning("%s: It is not supported to alter the compostors socket name after the compositor is initialized\n", Q_FUNC_INFO); + qWarning("%s: Changing socket name after initializing the compositor is not supported.\n", Q_FUNC_INFO); return; } d->socket_name = name; @@ -392,29 +483,56 @@ QByteArray QWaylandCompositor::socketName() const return d->socket_name; } +/*! + * \internal + */ struct wl_display *QWaylandCompositor::display() const { Q_D(const QWaylandCompositor); return d->display; } +/*! + * \internal + */ uint32_t QWaylandCompositor::nextSerial() { Q_D(QWaylandCompositor); return wl_display_next_serial(d->display); } +/*! + * \internal + */ QList<QWaylandClient *>QWaylandCompositor::clients() const { Q_D(const QWaylandCompositor); return d->clients; } +/*! + * \qmlmethod QtWaylandCompositor::WaylandCompositor::destroyClientForSurface(surface) + * + * Destroys the client for the WaylandSurface \a surface. + */ + +/*! + * Destroys the client for the \a surface. + */ void QWaylandCompositor::destroyClientForSurface(QWaylandSurface *surface) { destroyClient(surface->client()); } +/*! + * \qmlmethod QtWaylandCompositor::WaylandCompositor::destroyClient(client) + * + * Destroys the given WaylandClient \a client. + */ + +/*! + * Destroys the \a client. + */ void QWaylandCompositor::destroyClient(QWaylandClient *client) { if (!client) @@ -427,6 +545,9 @@ void QWaylandCompositor::destroyClient(QWaylandClient *client) wl_client_destroy(client->client()); } +/*! + * \internal + */ QList<QWaylandSurface *> QWaylandCompositor::surfacesForClient(QWaylandClient* client) const { Q_D(const QWaylandCompositor); @@ -438,12 +559,18 @@ QList<QWaylandSurface *> QWaylandCompositor::surfacesForClient(QWaylandClient* c return surfs; } +/*! + * \internal + */ QList<QWaylandSurface *> QWaylandCompositor::surfaces() const { Q_D(const QWaylandCompositor); return d->all_surfaces; } +/*! + * Returns the QWaylandOutput that is connected to the given \a window. + */ QWaylandOutput *QWaylandCompositor::outputFor(QWindow *window) const { Q_D(const QWaylandCompositor); @@ -455,6 +582,27 @@ QWaylandOutput *QWaylandCompositor::outputFor(QWindow *window) const return Q_NULLPTR; } +/*! + * \qmlproperty object QtWaylandCompositor::WaylandCompositor::defaultOutput + * + * This property contains the first in the list of outputs added to the + * WaylandCompositor, or null if no outputs have been added. + * + * Setting a new default output prepends it to the output list, making + * it the new default, but the previous default is not removed from + * the list. + */ +/*! + * \property QWaylandCompositor::defaultOutput + * + * This property contains the first in the list of outputs added to the + * QWaylandCompositor, or null if no outputs have been added. + * + * Setting a new default output prepends it to the output list, making + * it the new default, but the previous default is not removed from + * the list. If the new default output was already in the list of outputs, + * it is moved to the beginning of the list. + */ QWaylandOutput *QWaylandCompositor::defaultOutput() const { Q_D(const QWaylandCompositor); @@ -471,19 +619,27 @@ void QWaylandCompositor::setDefaultOutput(QWaylandOutput *output) defaultOutputChanged(); } +/*! + * \internal + */ QList<QWaylandOutput *> QWaylandCompositor::outputs() const { Q_D(const QWaylandCompositor); return d->outputs; } +/*! + * \internal + */ uint QWaylandCompositor::currentTimeMsecs() const { Q_D(const QWaylandCompositor); return d->timer.elapsed(); } - +/*! + * \internal + */ void QWaylandCompositor::processWaylandEvents() { Q_D(QWaylandCompositor); @@ -493,27 +649,49 @@ void QWaylandCompositor::processWaylandEvents() wl_display_flush_clients(d->display); } - +/*! + * \internal + */ QWaylandInputDevice *QWaylandCompositor::createInputDevice() { return new QWaylandInputDevice(this); } +/*! + * \internal + */ QWaylandPointer *QWaylandCompositor::createPointerDevice(QWaylandInputDevice *inputDevice) { return new QWaylandPointer(inputDevice); } +/*! + * \internal + */ QWaylandKeyboard *QWaylandCompositor::createKeyboardDevice(QWaylandInputDevice *inputDevice) { return new QWaylandKeyboard(inputDevice); } +/*! + * \internal + */ QWaylandTouch *QWaylandCompositor::createTouchDevice(QWaylandInputDevice *inputDevice) { return new QWaylandTouch(inputDevice); } +/*! + * \qmlproperty bool QtWaylandCompositor::WaylandCompositor::retainedSelection + * + * This property holds whether retained selection is enabled. + */ + +/*! + * \property QWaylandCompositor::retainedSelection + * + * This property holds whether retained selection is enabled. + */ void QWaylandCompositor::setRetainedSelectionEnabled(bool enabled) { Q_D(QWaylandCompositor); @@ -526,16 +704,35 @@ bool QWaylandCompositor::retainedSelectionEnabled() const return d->retainSelection; } +/*! + * \internal + */ void QWaylandCompositor::retainedSelectionReceived(QMimeData *) { } +/*! + * \internal + */ void QWaylandCompositor::overrideSelection(const QMimeData *data) { Q_D(QWaylandCompositor); d->data_device_manager->overrideSelection(*data); } +/*! + * \qmlproperty object QtWaylandCompositor::WaylandCompositor::defaultInputDevice + * + * This property contains the default input device for this + * WaylandCompositor. + */ + +/*! + * \property QWaylandCompositor::defaultInputDevice + * + * This property contains the default input device for this + * QWaylandCompositor. + */ QWaylandInputDevice *QWaylandCompositor::defaultInputDevice() const { Q_D(const QWaylandCompositor); @@ -544,6 +741,12 @@ QWaylandInputDevice *QWaylandCompositor::defaultInputDevice() const return Q_NULLPTR; } +/*! + * \internal + * + * Currently, Qt only supports a single input device, so this exists for + * future proofing the APIs. + */ QWaylandInputDevice *QWaylandCompositor::inputDeviceFor(QInputEvent *inputEvent) { Q_D(QWaylandCompositor); @@ -558,6 +761,23 @@ QWaylandInputDevice *QWaylandCompositor::inputDeviceFor(QInputEvent *inputEvent) return dev; } +/*! + * \qmlproperty bool QtWaylandCompositor::WaylandCompositor::useHardwareIntegrationExtension + * + * This property holds whether the hardware integration extension should be enabled for + * this WaylandCompositor. + * + * This property must be set before the compositor component is completed. + */ + +/*! + * \property QWaylandCompositor::useHardwareIntegrationExtension + * + * This property holds whether the hardware integration extension should be enabled for + * this QWaylandCompositor. + * + * This property must be set before the compositor is \l{create()}{created}. + */ bool QWaylandCompositor::useHardwareIntegrationExtension() const { Q_D(const QWaylandCompositor); diff --git a/src/compositor/compositor_api/qwaylanddrag.cpp b/src/compositor/compositor_api/qwaylanddrag.cpp index 2348907f0..cc45c1279 100644 --- a/src/compositor/compositor_api/qwaylanddrag.cpp +++ b/src/compositor/compositor_api/qwaylanddrag.cpp @@ -65,7 +65,6 @@ public: QWaylandInputDevice *inputDevice; }; - QWaylandDrag::QWaylandDrag(QWaylandInputDevice *inputDevice) : QObject(* new QWaylandDragPrivate(inputDevice)) { diff --git a/src/compositor/compositor_api/qwaylandinput.cpp b/src/compositor/compositor_api/qwaylandinput.cpp index 07987f0eb..6cb476d88 100644 --- a/src/compositor/compositor_api/qwaylandinput.cpp +++ b/src/compositor/compositor_api/qwaylandinput.cpp @@ -142,56 +142,100 @@ QWaylandKeymap::QWaylandKeymap(const QString &layout, const QString &variant, co } - -QWaylandInputDevice::QWaylandInputDevice(QWaylandCompositor *compositor, CapabilityFlags caps) +/*! + * \class QWaylandInputDevice + * \inmodule QtWaylandCompositor + * \brief The QWaylandInputDevice class provides access to keyboard, mouse and touch input. + * + * The QWaylandInputDevice provides access to different types of user input and maintains + * a keyboard focus and a mouse pointer. It corresponds to the wl_seat interface in the Wayland protocol. + */ + +/*! + * \enum QWaylandInputDevice::CapabilityFlag + * + * This enum type describes the capabilities of a QWaylandInputDevice. + * + * \value Pointer The QWaylandInputDevice supports pointer input. + * \value Keyboard The QWaylandInputDevice supports keyboard input. + * \value Touch The QWaylandInputDevice supports touch input. + */ + +/*! + * Constructs a QWaylandInputDevice for the given \a compositor and with the given \a capabilityFlags. + */ +QWaylandInputDevice::QWaylandInputDevice(QWaylandCompositor *compositor, CapabilityFlags capabilityFlags) : QWaylandObject(*new QWaylandInputDevicePrivate(this,compositor)) { - d_func()->setCapabilities(caps); + d_func()->setCapabilities(capabilityFlags); } +/*! + * Destroys the QWaylandInputDevice + */ QWaylandInputDevice::~QWaylandInputDevice() { } +/*! + * Sends a mouse press event for \a button to the QWaylandInputDevice's pointer device. + */ void QWaylandInputDevice::sendMousePressEvent(Qt::MouseButton button) { Q_D(QWaylandInputDevice); d->pointer->sendMousePressEvent(button); } +/*! + * Sends a mouse release event for \a button to the QWaylandInputDevice's pointer device. + */ void QWaylandInputDevice::sendMouseReleaseEvent(Qt::MouseButton button) { Q_D(QWaylandInputDevice); d->pointer->sendMouseReleaseEvent(button); } -/** Convenience function that will set the mouse focus to the surface, then send the mouse move event. - * If the mouse focus is the same surface as the surface passed in, then only the move event is sent +/*! + * Sets the mouse focus to \a view and sends a mouse move event to the pointer device with the + * local position \a localPos and output space position \a outputSpacePos. **/ -void QWaylandInputDevice::sendMouseMoveEvent(QWaylandView *view, const QPointF &localPos, const QPointF &globalPos) +void QWaylandInputDevice::sendMouseMoveEvent(QWaylandView *view, const QPointF &localPos, const QPointF &outputSpacePos) { Q_D(QWaylandInputDevice); - d->pointer->sendMouseMoveEvent(view, localPos,globalPos); + d->pointer->sendMouseMoveEvent(view, localPos, outputSpacePos); } +/*! + * Sends a mouse wheel event to the QWaylandInputDevice's pointer device with the given \a orientation and \a delta. + */ void QWaylandInputDevice::sendMouseWheelEvent(Qt::Orientation orientation, int delta) { Q_D(QWaylandInputDevice); d->pointer->sendMouseWheelEvent(orientation, delta); } +/*! + * Sends a key press event with the key \a code to the keyboard device. + */ void QWaylandInputDevice::sendKeyPressEvent(uint code) { Q_D(QWaylandInputDevice); d->keyboard->sendKeyPressEvent(code); } +/*! + * Sends a key release event with the key \a code to the keyboard device. + */ void QWaylandInputDevice::sendKeyReleaseEvent(uint code) { Q_D(QWaylandInputDevice); d->keyboard->sendKeyReleaseEvent(code); } +/*! + * Sends a touch point event with the given \a id and \a state to the touch device. The position + * of the touch point is given by \a point. + */ void QWaylandInputDevice::sendTouchPointEvent(int id, const QPointF &point, Qt::TouchPointState state) { Q_D(QWaylandInputDevice); @@ -201,6 +245,9 @@ void QWaylandInputDevice::sendTouchPointEvent(int id, const QPointF &point, Qt:: d->touch->sendTouchPointEvent(id, point,state); } +/*! + * Sends a frame event to the touch device. + */ void QWaylandInputDevice::sendTouchFrameEvent() { Q_D(QWaylandInputDevice); @@ -209,6 +256,9 @@ void QWaylandInputDevice::sendTouchFrameEvent() } } +/*! + * Sends a cancel event to the touch device. + */ void QWaylandInputDevice::sendTouchCancelEvent() { Q_D(QWaylandInputDevice); @@ -217,6 +267,9 @@ void QWaylandInputDevice::sendTouchCancelEvent() } } +/*! + * Sends the \a event to the touch device. + */ void QWaylandInputDevice::sendFullTouchEvent(QTouchEvent *event) { Q_D(QWaylandInputDevice); @@ -231,6 +284,9 @@ void QWaylandInputDevice::sendFullTouchEvent(QTouchEvent *event) d->touch->sendFullTouchEvent(event); } +/*! + * Sends the \a event to the keyboard device. + */ void QWaylandInputDevice::sendFullKeyEvent(QKeyEvent *event) { Q_D(QWaylandInputDevice); @@ -251,12 +307,18 @@ void QWaylandInputDevice::sendFullKeyEvent(QKeyEvent *event) } } +/*! + * Returns the keyboard for this input device. + */ QWaylandKeyboard *QWaylandInputDevice::keyboard() const { Q_D(const QWaylandInputDevice); return d->keyboard.data(); } +/*! + * Returns the current focused surface for keyboard input. + */ QWaylandSurface *QWaylandInputDevice::keyboardFocus() const { Q_D(const QWaylandInputDevice); @@ -266,6 +328,9 @@ QWaylandSurface *QWaylandInputDevice::keyboardFocus() const return d->keyboard->focus(); } +/*! + * Sets the current keyboard focus to \a surface. + */ bool QWaylandInputDevice::setKeyboardFocus(QWaylandSurface *surface) { Q_D(QWaylandInputDevice); @@ -283,24 +348,36 @@ bool QWaylandInputDevice::setKeyboardFocus(QWaylandSurface *surface) return false; } +/*! + * Sets the key map of this QWaylandInputDevice to \a keymap. + */ void QWaylandInputDevice::setKeymap(const QWaylandKeymap &keymap) { if (keyboard()) keyboard()->setKeymap(keymap); } +/*! + * Returns the pointer device for this QWaylandInputDevice. + */ QWaylandPointer *QWaylandInputDevice::pointer() const { Q_D(const QWaylandInputDevice); return d->pointer.data(); } +/*! + * Returns the view that currently has mouse focus. + */ QWaylandView *QWaylandInputDevice::mouseFocus() const { Q_D(const QWaylandInputDevice); return d->mouseFocus; } +/*! + * Sets the current mouse focus to \a view. + */ void QWaylandInputDevice::setMouseFocus(QWaylandView *view) { Q_D(QWaylandInputDevice); @@ -312,33 +389,55 @@ void QWaylandInputDevice::setMouseFocus(QWaylandView *view) emit mouseFocusChanged(d->mouseFocus, oldFocus); } +/*! + * Returns the compositor for this QWaylandInputDevice. + */ QWaylandCompositor *QWaylandInputDevice::compositor() const { Q_D(const QWaylandInputDevice); return d->compositor; } +/*! + * Returns the drag object for this QWaylandInputDevice. + */ QWaylandDrag *QWaylandInputDevice::drag() const { Q_D(const QWaylandInputDevice); return d->drag_handle.data(); } +/*! + * Returns the capability flags for this QWaylandInputDevice. + */ QWaylandInputDevice::CapabilityFlags QWaylandInputDevice::capabilities() const { Q_D(const QWaylandInputDevice); return d->capabilities; } +/*! + * \internal + */ bool QWaylandInputDevice::isOwner(QInputEvent *inputEvent) const { Q_UNUSED(inputEvent); return true; } +/*! + * Returns the QWaylandInputDevice corresponding to the \a resource. The \a resource is expected + * to have the type wl_seat. + */ QWaylandInputDevice *QWaylandInputDevice::fromSeatResource(struct ::wl_resource *resource) { return static_cast<QWaylandInputDevicePrivate *>(QWaylandInputDevicePrivate::Resource::fromResource(resource)->seat_object)->q_func(); } +/*! + * \fn void mouseFocusChanged(QWaylandView *newFocus, QWaylandView *oldFocus) + * + * This signal is emitted when the mouse focus has changed from \a oldFocus to \a newFocus. + */ + QT_END_NAMESPACE diff --git a/src/compositor/compositor_api/qwaylandinput.h b/src/compositor/compositor_api/qwaylandinput.h index 0b5c14288..e4b6e1275 100644 --- a/src/compositor/compositor_api/qwaylandinput.h +++ b/src/compositor/compositor_api/qwaylandinput.h @@ -79,12 +79,12 @@ public: Q_DECLARE_FLAGS(CapabilityFlags, CapabilityFlag) Q_ENUM(CapabilityFlags) - QWaylandInputDevice(QWaylandCompositor *compositor, CapabilityFlags caps = DefaultCapabilities); + QWaylandInputDevice(QWaylandCompositor *compositor, CapabilityFlags capabilityFlags = DefaultCapabilities); virtual ~QWaylandInputDevice(); void sendMousePressEvent(Qt::MouseButton button); void sendMouseReleaseEvent(Qt::MouseButton button); - void sendMouseMoveEvent(QWaylandView *surface , const QPointF &localPos, const QPointF &globalPos = QPointF()); + void sendMouseMoveEvent(QWaylandView *surface , const QPointF &localPos, const QPointF &outputSpacePos = QPointF()); void sendMouseWheelEvent(Qt::Orientation orientation, int delta); void sendKeyPressEvent(uint code); diff --git a/src/compositor/compositor_api/qwaylandkeyboard.cpp b/src/compositor/compositor_api/qwaylandkeyboard.cpp index 2c2febead..d7aa76e60 100644 --- a/src/compositor/compositor_api/qwaylandkeyboard.cpp +++ b/src/compositor/compositor_api/qwaylandkeyboard.cpp @@ -338,25 +338,46 @@ void QWaylandKeyboardPrivate::createXKBKeymap() } #endif -QWaylandKeyboard::QWaylandKeyboard(QWaylandInputDevice *seat, QObject *parent) - : QWaylandObject(* new QWaylandKeyboardPrivate(seat), parent) +/*! + * \class QWaylandKeyboard + * \inmodule QtWaylandCompositor + * \brief The QWaylandKeyboard class provides access to a keyboard device. + * + * This class provides access to the keyboard device in a QWaylandInputDevice. It corresponds to + * the Wayland interface wl_keyboard. + */ + +/*! + * Constructs a QWaylandKeyboard for the given \a inputDevice and with the given \a parent. + */ +QWaylandKeyboard::QWaylandKeyboard(QWaylandInputDevice *inputDevice, QObject *parent) + : QWaylandObject(* new QWaylandKeyboardPrivate(inputDevice), parent) { Q_D(QWaylandKeyboard); connect(&d->focusDestroyListener, &QWaylandDestroyListener::fired, this, &QWaylandKeyboard::focusDestroyed); } +/*! + * Returns the input device for this QWaylandKeyboard. + */ QWaylandInputDevice *QWaylandKeyboard::inputDevice() const { Q_D(const QWaylandKeyboard); return d->seat; } +/*! + * Returns the compositor for this QWaylandKeyboard. + */ QWaylandCompositor *QWaylandKeyboard::compositor() const { Q_D(const QWaylandKeyboard); return d->seat->compositor(); } +/*! + * \internal + */ void QWaylandKeyboard::focusDestroyed(void *data) { Q_UNUSED(data); @@ -367,6 +388,9 @@ void QWaylandKeyboard::focusDestroyed(void *data) d->focusResource = 0; } +/*! + * Returns the client that currently has keyboard focus. + */ QWaylandClient *QWaylandKeyboard::focusClient() const { Q_D(const QWaylandKeyboard); @@ -375,6 +399,9 @@ QWaylandClient *QWaylandKeyboard::focusClient() const return QWaylandClient::fromWlClient(compositor(), d->focusResource->client()); } +/*! + * Sends the current key modifiers to \a client with the given \a serial. + */ void QWaylandKeyboard::sendKeyModifiers(QWaylandClient *client, uint serial) { Q_D(QWaylandKeyboard); @@ -383,24 +410,36 @@ void QWaylandKeyboard::sendKeyModifiers(QWaylandClient *client, uint serial) d->send_modifiers(resource->handle, serial, d->modsDepressed, d->modsLatched, d->modsLocked, d->group); } +/*! + * Sends a key press event with the key \a code to the current keyboard focus. + */ void QWaylandKeyboard::sendKeyPressEvent(uint code) { Q_D(QWaylandKeyboard); d->sendKeyEvent(code, WL_KEYBOARD_KEY_STATE_PRESSED); } +/*! + * Sends a key release event with the key \a code to the current keyboard focus. + */ void QWaylandKeyboard::sendKeyReleaseEvent(uint code) { Q_D(QWaylandKeyboard); d->sendKeyEvent(code, WL_KEYBOARD_KEY_STATE_RELEASED); } +/*! + * Returns the currently focused surface. + */ QWaylandSurface *QWaylandKeyboard::focus() const { Q_D(const QWaylandKeyboard); return d->focus; } +/*! + * Sets the current focus to \a surface. + */ bool QWaylandKeyboard::setFocus(QWaylandSurface *surface) { Q_D(QWaylandKeyboard); @@ -411,6 +450,9 @@ bool QWaylandKeyboard::setFocus(QWaylandSurface *surface) return true; } +/*! + * Sets the keyboard's keymap to \a keymap. + */ void QWaylandKeyboard::setKeymap(const QWaylandKeymap &keymap) { Q_D(QWaylandKeyboard); @@ -425,6 +467,9 @@ void QWaylandKeyboard::setKeymap(const QWaylandKeymap &keymap) } } +/*! + * \internal + */ void QWaylandKeyboard::addClient(QWaylandClient *client, uint32_t id) { Q_D(QWaylandKeyboard); diff --git a/src/compositor/compositor_api/qwaylandkeyboard.h b/src/compositor/compositor_api/qwaylandkeyboard.h index ccc140bb4..81b8bee08 100644 --- a/src/compositor/compositor_api/qwaylandkeyboard.h +++ b/src/compositor/compositor_api/qwaylandkeyboard.h @@ -75,7 +75,7 @@ class Q_COMPOSITOR_EXPORT QWaylandKeyboard : public QWaylandObject Q_DECLARE_PRIVATE(QWaylandKeyboard) public: - QWaylandKeyboard(QWaylandInputDevice *seat, QObject *parent = 0); + QWaylandKeyboard(QWaylandInputDevice *inputDevice, QObject *parent = 0); QWaylandInputDevice *inputDevice() const; QWaylandCompositor *compositor() const; diff --git a/src/compositor/compositor_api/qwaylandoutput.cpp b/src/compositor/compositor_api/qwaylandoutput.cpp index 9d791a9d3..b3c94645d 100644 --- a/src/compositor/compositor_api/qwaylandoutput.cpp +++ b/src/compositor/compositor_api/qwaylandoutput.cpp @@ -186,6 +186,40 @@ QWaylandOutput::QWaylandOutput() { } +/*! + \qmltype WaylandOutput + \inqmlmodule QtWayland.Compositor + \brief Type providing access to a displayable area managed by the compositor. + + The WaylandOutput manages a rectangular part of the compositor's geometry that + can be used for displaying client content. This could, for instance, be a screen + managed by the WaylandCompositor. + + The type corresponds to the wl_output interface in the Wayland protocol. +*/ + +/*! + \class QWaylandOutput + \inmodule QtWaylandCompositor + \brief The QWaylandOutput class provides access to a displayable area managed by the compositor. + + The QWaylandOutput manages a rectangular part of the compositor's geometry that + can be used for displaying client content. This could, for instance, be a screen + managed by the QWaylandCompositor. + + The class corresponds to the wl_output interface in the Wayland protocol. +*/ + +/*! + * Constructs a QWaylandOutput in \a compositor and with the specified \a window. The + * \l{QWaylandCompositor::create()}{create()} function must have been called on the + * \a compositor before a QWaylandOutput is constructed for it. + * + * The QWaylandOutput object is initialized later, in reaction to an event. + * At this point it is added as an output for the \a compositor. If it is the + * first QWaylandOutput object created for this \a compositor, it becomes the + * \l{QWaylandCompositor::defaultOutput()}{default output}. + */ QWaylandOutput::QWaylandOutput(QWaylandCompositor *compositor, QWindow *window) : QWaylandObject(*new QWaylandOutputPrivate()) { @@ -195,6 +229,9 @@ QWaylandOutput::QWaylandOutput(QWaylandCompositor *compositor, QWindow *window) QWaylandCompositorPrivate::get(compositor)->addPolishObject(this); } +/*! + * Destroys the QWaylandOutput. + */ QWaylandOutput::~QWaylandOutput() { Q_D(QWaylandOutput); @@ -202,6 +239,9 @@ QWaylandOutput::~QWaylandOutput() QWaylandCompositorPrivate::get(d->compositor)->removeOutput(this); } +/*! + * \internal + */ void QWaylandOutput::initialize() { Q_D(QWaylandOutput); @@ -224,11 +264,17 @@ void QWaylandOutput::initialize() d->initialized = true; } +/*! + * Returns the QWaylandOutput corresponding to \a resource. + */ QWaylandOutput *QWaylandOutput::fromResource(wl_resource *resource) { return static_cast<QWaylandOutputPrivate *>(QWaylandOutputPrivate::Resource::fromResource(resource)->output_object)->q_func(); } +/*! + * \internal + */ struct ::wl_resource *QWaylandOutput::resourceForClient(QWaylandClient *client) const { Q_D(const QWaylandOutput); @@ -239,6 +285,11 @@ struct ::wl_resource *QWaylandOutput::resourceForClient(QWaylandClient *client) return Q_NULLPTR; } +/*! + * Schedules a QEvent::UpdateRequest to be delivered to the QWaylandOutput's \l{window()}{window}. + * + * \sa QWindow::requestUpdate() + */ void QWaylandOutput::update() { Q_D(QWaylandOutput); @@ -247,11 +298,24 @@ void QWaylandOutput::update() d->window->requestUpdate(); } +/*! + * \qmlproperty object QtWaylandCompositor::WaylandOutput::compositor + * + * This property holds the compositor displaying content on this QWaylandOutput. + * This property can only be set once, before the WaylandOutput component is completed. + */ + +/*! + * Returns the compositor for this QWaylandOutput. + */ QWaylandCompositor *QWaylandOutput::compositor() const { return d_func()->compositor; } +/*! + * \internal + */ void QWaylandOutput::setCompositor(QWaylandCompositor *compositor) { Q_D(QWaylandOutput); @@ -272,7 +336,17 @@ void QWaylandOutput::setCompositor(QWaylandCompositor *compositor) QWaylandCompositorPrivate::get(compositor)->addPolishObject(this); } +/*! + * \qmlproperty string QtWaylandCompositor::WaylandOutput::manufacturer + * + * This property holds a textual description of the manufacturer of this WaylandOutput. + */ +/*! + * \property QWaylandOutput::manufacturer + * + * This property holds a textual description of the manufacturer of this QWaylandOutput. + */ QString QWaylandOutput::manufacturer() const { return d_func()->manufacturer; @@ -283,6 +357,17 @@ void QWaylandOutput::setManufacturer(const QString &manufacturer) d_func()->manufacturer = manufacturer; } +/*! + * \qmlproperty string QtWaylandCompositor::WaylandOutput::model + * + * This property holds a textual description of the model of this WaylandOutput. + */ + +/*! + * \property QWaylandOutput::model + * + * This property holds a textual description of the model of this QWaylandOutput. + */ QString QWaylandOutput::model() const { return d_func()->model; @@ -293,6 +378,17 @@ void QWaylandOutput::setModel(const QString &model) d_func()->model = model; } +/*! + * \qmlproperty point QtWaylandCompositor::WaylandOutput::position + * + * This property holds the position of this WaylandOutput in the compositor's coordinate system. + */ + +/*! + * \property QWaylandOutput::position + * + * This property holds the position of this QWaylandOutput in the compositor's coordinate system. + */ QPoint QWaylandOutput::position() const { return d_func()->position; @@ -312,6 +408,11 @@ void QWaylandOutput::setPosition(const QPoint &pt) Q_EMIT geometryChanged(); } +/*! + * \property QWaylandOutput::mode + * + * This property holds the output's size in pixels and refresh rate in Hz. + */ QWaylandOutput::Mode QWaylandOutput::mode() const { return d_func()->mode; @@ -343,6 +444,19 @@ void QWaylandOutput::setMode(const Mode &mode) } } +/*! + * \qmlproperty rect QtWaylandCompositor::WaylandOutput::geometry + * + * This property holds the geometry of the WaylandOutput. + */ + +/*! + * \property QWaylandOutput::geometry + * + * This property holds the geometry of the QWaylandOutput. + * + * \sa QWaylandOutput::mode + */ QRect QWaylandOutput::geometry() const { Q_D(const QWaylandOutput); @@ -374,6 +488,21 @@ void QWaylandOutput::setGeometry(const QRect &geometry) Q_EMIT modeChanged(); } +/*! + * \qmlproperty rect QtWaylandCompositor::WaylandOutput::availableGeometry + * + * This property holds the geometry of the WaylandOutput available for displaying content. + * + * \sa QWaylandOutput::geometry + */ + +/*! + * \property QWaylandOutput::availableGeometry + * + * This property holds the geometry of the QWaylandOutput available for displaying content. + * + * \sa QWaylandOutput::mode, QWaylandOutput::geometry + */ QRect QWaylandOutput::availableGeometry() const { Q_D(const QWaylandOutput); @@ -394,6 +523,21 @@ void QWaylandOutput::setAvailableGeometry(const QRect &availableGeometry) Q_EMIT availableGeometryChanged(); } +/*! + * \qmlproperty size QtWaylandCompositor::WaylandOutput::physicalSize + * + * This property holds the physical size of the WaylandOutput in millimeters. + * + * \sa QWaylandOutput::geometry + */ + +/*! + * \property QWaylandOutput::physicalSize + * + * This property holds the physical size of the QWaylandOutput in millimeters. + * + * \sa QWaylandOutput::geometry, QWaylandOutput::mode + */ QSize QWaylandOutput::physicalSize() const { return d_func()->physicalSize; @@ -412,6 +556,44 @@ void QWaylandOutput::setPhysicalSize(const QSize &size) Q_EMIT physicalSizeChanged(); } +/*! + * \enum QWaylandOutput::Subpixel + * + * This enum type is used to specify the subpixel arrangement of a QWaylandOutput. + * + * \value SubpixelUnknown The subpixel arrangement is not set. + * \value SubpixelNone There are no subpixels. + * \value SubpixelHorizontalRgb The subpixels are arranged horizontally in red, green, blue order. + * \value SubpixelHorizontalBgr The subpixels are arranged horizontally in blue, green, red order. + * \value SubpixelVerticalRgb The subpixels are arranged vertically in red, green, blue order. + * \value SubpixelVerticalBgr The subpixels are arranged vertically in blue, green, red order. + * + * \sa QWaylandOutput::subpixel + */ + +/*! + * \qmlproperty enum QtWaylandCompositor::WaylandOutput::subpixel + * + * This property holds the subpixel arrangement of this WaylandOutput. + * + * \list + * \li WaylandOutput.SubpixelUnknown The subpixel arrangement is not set. + * \li WaylandOutput.SubpixelNone There are no subpixels. + * \li WaylandOutput.SubpixelHorizontalRgb The subpixels are arranged horizontally in red, green, blue order. + * \li WaylandOutput.SubpixelHorizontalBgr The subpixels are arranged horizontally in blue, green, red order. + * \li WaylandOutput.SubpixelVerticalRgb The subpixels are arranged vertically in red, green, blue order. + * \li WaylandOutput.SubpixelVerticalBgr The subpixels are arranged vertically in blue, green, red order. + * \endlist + * + * The default is WaylandOutput.SubpixelUnknown. + */ + +/*! + * \property QWaylandOutput::subpixel + * + * This property holds the subpixel arrangement of this QWaylandOutput. The default is + * QWaylandOutput::SubpixelUnknown. + */ QWaylandOutput::Subpixel QWaylandOutput::subpixel() const { return d_func()->subpixel; @@ -430,6 +612,50 @@ void QWaylandOutput::setSubpixel(const Subpixel &subpixel) Q_EMIT subpixelChanged(); } +/*! \enum QWaylandOutput::Transform + * + * This enum type is used to specify the orientation of a QWaylandOutput. + * + * \value TransformNormal The QWaylandOutput orientation is normal. + * \value Transform90 The QWaylandOutput is rotated 90 degrees. + * \value Transform180 The QWaylandOutput is rotated 180 degrees. + * \value Transform270 The QWaylandOutput is rotated 270 degrees. + * \value TransformFlipped The QWaylandOutput is mirrored. + * \value TransformFlipped90 The QWaylandOutput is mirrored, and rotated 90 degrees. + * \value TransformFlipped180 The QWaylandOutput is mirrored, and rotated 180 degrees. + * \value TransformFlipped270 The QWaylandOutput is mirrored, and rotated 270 degrees. + * + * \sa QWaylandOutput::transform +*/ + +/*! + * \qmlproperty enum QtWaylandCompositor::WaylandOutput::transform + * + * This property holds the transformation that the QWaylandCompositor applies to a surface + * to compensate for the orientation of the QWaylandOutput. + * + * \list + * \li WaylandOutput.TransformNormal The QWaylandOutput orientation is normal. + * \li WaylandOutput.Transform90 The QWaylandOutput is rotated 90 degrees. + * \li WaylandOutput.Transform180 The QWaylandOutput is rotated 180 degrees. + * \li WaylandOutput.Transform270 The QWaylandOutput is rotated 270 degrees. + * \li WaylandOutput.TransformFlipped The QWaylandOutput is mirrored. + * \li WaylandOutput.TransformFlipped90 The QWaylandOutput is mirrored, then rotated 90 degrees. + * \li WaylandOutput.TransformFlipped180 The QWaylandOutput is mirrored, then rotated 180 degrees. + * \li WaylandOutput.TransformFlipped270 The QWaylandOutput is mirrored, then rotated 270 degrees. + * \endlist + * + * The default is WaylandOutput.TransformNormal. + */ + +/*! + * \property QWaylandOutput::transform + * + * This property holds the transformation that the QWaylandCompositor applies to a surface + * to compensate for the orientation of the QWaylandOutput. + * + * The default is QWaylandOutput::TransformNormal. + */ QWaylandOutput::Transform QWaylandOutput::transform() const { return d_func()->transform; @@ -448,6 +674,29 @@ void QWaylandOutput::setTransform(const Transform &transform) Q_EMIT transformChanged(); } +/*! + * \qmlproperty int QtWaylandCompositor::WaylandOutput::scaleFactor + * + * This property holds the factor by which the WaylandCompositor scales surface buffers + * before they are displayed. This is used on high density output devices where unscaled content + * would be too small to be practical. The client can in turn set the scale factor of its + * buffer to match the output if it prefers to provide high resolution content that is + * suitable for the output device. + * + * The default is 1 (no scaling). + */ + +/*! + * \property QWaylandOutput::scaleFactor + * + * This property holds the factor by which the QWaylandCompositor scales surface buffers + * before they are displayed. This is used on high density output devices where unscaled content + * would be too small to be practical. The client can in turn set the scale factor of its + * buffer to match the output if it prefers to provide high resolution content that is + * suitable for the output device. + * + * The default is 1 (no scaling). + */ int QWaylandOutput::scaleFactor() const { return d_func()->scaleFactor; @@ -471,6 +720,23 @@ void QWaylandOutput::setScaleFactor(int scale) Q_EMIT scaleFactorChanged(); } +/*! + * \qmlproperty bool QtWaylandCompositor::WaylandOutput::sizeFollowsWindow + * + * This property controls whether the size of the WaylandOutput matches the + * size of its window. + * + * The default is true. + */ + +/*! + * \property QWaylandOutput::sizeFollowsWindow + * + * This property controls whether the size of the QWaylandOutput matches the + * size of its window. + * + * The default is true. + */ bool QWaylandOutput::sizeFollowsWindow() const { return d_func()->sizeFollowsWindow; @@ -492,6 +758,18 @@ void QWaylandOutput::setSizeFollowsWindow(bool follow) } } +/*! + * \qmlproperty object QtWaylandCompositor::WaylandOutput::window + * + * This property holds the Window for this WaylandOutput. This property can only be set once, + * before the WaylandOutput component is completed. + */ + +/*! + * \property QWaylandOutput::window + * + * This property holds the QWindow for this QWaylandOutput. + */ QWindow *QWaylandOutput::window() const { return d_func()->window; @@ -510,6 +788,9 @@ void QWaylandOutput::setWindow(QWindow *window) emit windowChanged(); } +/*! + * Tells the QWaylandOutput that a frame has started. + */ void QWaylandOutput::frameStarted() { Q_D(QWaylandOutput); @@ -520,6 +801,9 @@ void QWaylandOutput::frameStarted() } } +/*! + * Sends pending frame callbacks. + */ void QWaylandOutput::sendFrameCallbacks() { Q_D(QWaylandOutput); @@ -537,6 +821,9 @@ void QWaylandOutput::sendFrameCallbacks() wl_display_flush_clients(d->compositor->display()); } +/*! + * \internal + */ void QWaylandOutput::surfaceEnter(QWaylandSurface *surface) { if (!surface) @@ -544,6 +831,9 @@ void QWaylandOutput::surfaceEnter(QWaylandSurface *surface) QWaylandSurfacePrivate::get(surface)->send_enter(resourceForClient(surface->client())); } +/*! + * \internal + */ void QWaylandOutput::surfaceLeave(QWaylandSurface *surface) { if (!surface || !surface->client()) @@ -551,6 +841,11 @@ void QWaylandOutput::surfaceLeave(QWaylandSurface *surface) QWaylandSurfacePrivate::get(surface)->send_leave(resourceForClient(surface->client())); } +/*! + * This functions sets the width of this QWaylandOutput to \a newWidth. + * + * \sa setHeight, QWaylandOutput::geometry + */ void QWaylandOutput::setWidth(int newWidth) { Q_D(QWaylandOutput); @@ -562,6 +857,11 @@ void QWaylandOutput::setWidth(int newWidth) setGeometry(QRect(d->position, s)); } +/*! + * This functions sets the height of this QWaylandOutput to \a newHeight. + * + * \sa setWidth, QWaylandOutput::geometry + */ void QWaylandOutput::setHeight(int newHeight) { Q_D(QWaylandOutput); @@ -573,6 +873,9 @@ void QWaylandOutput::setHeight(int newHeight) setGeometry(QRect(d->position, s)); } +/*! + * \internal + */ void QWaylandOutput::handleWindowDestroyed() { Q_D(QWaylandOutput); @@ -580,6 +883,9 @@ void QWaylandOutput::handleWindowDestroyed() emit windowDestroyed(); } +/*! + * \internal + */ bool QWaylandOutput::event(QEvent *event) { if (event->type() == QEvent::Polish) diff --git a/src/compositor/compositor_api/qwaylandpointer.cpp b/src/compositor/compositor_api/qwaylandpointer.cpp index 567f99f68..74a513344 100644 --- a/src/compositor/compositor_api/qwaylandpointer.cpp +++ b/src/compositor/compositor_api/qwaylandpointer.cpp @@ -78,31 +78,55 @@ void QWaylandPointerPrivate::pointer_set_cursor(wl_pointer::Resource *resource, seat->cursorSurfaceRequest(s, hotspot_x, hotspot_y); } -QWaylandPointer::QWaylandPointer(QWaylandInputDevice *seat, QObject *parent) - : QWaylandObject(* new QWaylandPointerPrivate(this, seat), parent) +/*! + * \class QWaylandPointer + * \inmodule QtWaylandCompositor + * \brief The QWaylandPointer class provides access to a pointer device. + * + * This class provides access to the pointer device in a QWaylandInputDevice. It corresponds to + * the Wayland interface wl_pointer. + */ + +/*! + * Constructs a QWaylandPointer for the given \a inputDevice and with the given \a parent. + */ +QWaylandPointer::QWaylandPointer(QWaylandInputDevice *inputDevice, QObject *parent) + : QWaylandObject(* new QWaylandPointerPrivate(this, inputDevice), parent) { connect(&d_func()->focusDestroyListener, &QWaylandDestroyListener::fired, this, &QWaylandPointer::focusDestroyed); - connect(seat, &QWaylandInputDevice::mouseFocusChanged, this, &QWaylandPointer::pointerFocusChanged); + connect(inputDevice, &QWaylandInputDevice::mouseFocusChanged, this, &QWaylandPointer::pointerFocusChanged); } +/*! + * Returns the input device for this QWaylandPointer. + */ QWaylandInputDevice *QWaylandPointer::inputDevice() const { Q_D(const QWaylandPointer); return d->seat; } +/*! + * Returns the compositor for this QWaylandPointer. + */ QWaylandCompositor *QWaylandPointer::compositor() const { Q_D(const QWaylandPointer); return d->compositor(); } +/*! + * Returns the output for this QWaylandPointer. + */ QWaylandOutput *QWaylandPointer::output() const { Q_D(const QWaylandPointer); return d->output; } +/*! + * Sets the output for this QWaylandPointer to \a output. + */ void QWaylandPointer::setOutput(QWaylandOutput *output) { Q_D(QWaylandPointer); @@ -111,6 +135,9 @@ void QWaylandPointer::setOutput(QWaylandOutput *output) outputChanged(); } +/*! + * Sends a mouse press event for \a button to the view currently holding mouse focus. + */ void QWaylandPointer::sendMousePressEvent(Qt::MouseButton button) { Q_D(QWaylandPointer); @@ -124,6 +151,9 @@ void QWaylandPointer::sendMousePressEvent(Qt::MouseButton button) } } +/*! + * Sends a mouse release event for \a button to the view currently holding mouse focus. + */ void QWaylandPointer::sendMouseReleaseEvent(Qt::MouseButton button) { Q_D(QWaylandPointer); @@ -137,6 +167,10 @@ void QWaylandPointer::sendMouseReleaseEvent(Qt::MouseButton button) emit buttonPressedChanged(); } +/*! + * Sets the current mouse focus to \a view and sends a mouse move event to it with the + * local position \a localPos and output space position \a outputSpacePos. + */ void QWaylandPointer::sendMouseMoveEvent(QWaylandView *view, const QPointF &localPos, const QPointF &outputSpacePos) { Q_D(QWaylandPointer); @@ -185,6 +219,9 @@ void QWaylandPointer::sendMouseMoveEvent(QWaylandView *view, const QPointF &loca } } +/*! + * Sends a mouse wheel event with the given \a orientation and \a delta to the view that currently holds mouse focus. + */ void QWaylandPointer::sendMouseWheelEvent(Qt::Orientation orientation, int delta) { Q_D(QWaylandPointer); @@ -197,36 +234,54 @@ void QWaylandPointer::sendMouseWheelEvent(Qt::Orientation orientation, int delta d->send_axis(d->focusResource, time, axis, wl_fixed_from_int(-delta / 12)); } +/*! + * Returns the view that currently holds mouse focus. + */ QWaylandView *QWaylandPointer::mouseFocus() const { Q_D(const QWaylandPointer); return d->seat->mouseFocus(); } +/*! + * Returns the current local position of the QWaylandPointer. + */ QPointF QWaylandPointer::currentLocalPosition() const { Q_D(const QWaylandPointer); return d->localPosition; } +/*! + * Returns the current output space position of the QWaylandPointer. + */ QPointF QWaylandPointer::currentSpacePosition() const { Q_D(const QWaylandPointer); return d->spacePosition; } +/*! + * Returns true if any button is currently pressed. Otherwise returns false. + */ bool QWaylandPointer::isButtonPressed() const { Q_D(const QWaylandPointer); return d->buttonCount > 0; } +/*! + * \internal + */ void QWaylandPointer::addClient(QWaylandClient *client, uint32_t id) { Q_D(QWaylandPointer); d->add(client->client(), id, QtWaylandServer::wl_pointer::interfaceVersion()); } +/*! + * Returns the Wayland resource for this QWaylandPointer. + */ struct wl_resource *QWaylandPointer::focusResource() const { Q_D(const QWaylandPointer); @@ -236,6 +291,9 @@ struct wl_resource *QWaylandPointer::focusResource() const return d->focusResource; } +/*! + * \internal + */ void QWaylandPointer::sendButton(struct wl_resource *resource, uint32_t time, Qt::MouseButton button, uint32_t state) { Q_D(QWaylandPointer); @@ -243,6 +301,9 @@ void QWaylandPointer::sendButton(struct wl_resource *resource, uint32_t time, Qt d->send_button(resource, serial, time, toWaylandButton(button), state); } +/*! + * \internal + */ uint32_t QWaylandPointer::toWaylandButton(Qt::MouseButton button) { #ifndef BTN_LEFT @@ -272,6 +333,9 @@ uint32_t QWaylandPointer::toWaylandButton(Qt::MouseButton button) } } +/*! + * \internal + */ void QWaylandPointer::focusDestroyed(void *data) { Q_D(QWaylandPointer); @@ -283,6 +347,9 @@ void QWaylandPointer::focusDestroyed(void *data) d->buttonCount = 0; } +/*! + * \internal + */ void QWaylandPointer::pointerFocusChanged(QWaylandView *newFocus, QWaylandView *oldFocus) { Q_UNUSED(newFocus); @@ -299,4 +366,3 @@ void QWaylandPointer::pointerFocusChanged(QWaylandView *newFocus, QWaylandView * } QT_END_NAMESPACE - diff --git a/src/compositor/compositor_api/qwaylandpointer.h b/src/compositor/compositor_api/qwaylandpointer.h index 2ef70b221..acb9349a1 100644 --- a/src/compositor/compositor_api/qwaylandpointer.h +++ b/src/compositor/compositor_api/qwaylandpointer.h @@ -54,7 +54,7 @@ class Q_COMPOSITOR_EXPORT QWaylandPointer : public QWaylandObject Q_DECLARE_PRIVATE(QWaylandPointer) Q_PROPERTY(bool isButtonPressed READ isButtonPressed NOTIFY buttonPressedChanged) public: - QWaylandPointer(QWaylandInputDevice *seat, QObject *parent = 0); + QWaylandPointer(QWaylandInputDevice *inputDevice, QObject *parent = 0); QWaylandInputDevice *inputDevice() const; QWaylandCompositor *compositor() const; diff --git a/src/compositor/compositor_api/qwaylandquickcompositor.cpp b/src/compositor/compositor_api/qwaylandquickcompositor.cpp index e909caae1..8a7ef7451 100644 --- a/src/compositor/compositor_api/qwaylandquickcompositor.cpp +++ b/src/compositor/compositor_api/qwaylandquickcompositor.cpp @@ -66,6 +66,27 @@ QWaylandQuickCompositor::QWaylandQuickCompositor(QObject *parent) { } +/*! + * \qmlproperty list QtWaylandCompositor::WaylandCompositor::extensions + * + * A list of extensions that the compositor advertises to its clients. For + * any Wayland extension the compositor should support, instantiate its component, + * and add it to the list of extensions. + * + * For instance, the following code would allow the clients to request shell surfaces + * in the compositor using the wl_shell interface. + * + * \code + * import QtWayland.Compositor 1.0 + * + * WaylandCompositor { + * extensions: [ Shell { + * // ... + * } ] + * } + * \endcode + */ + void QWaylandQuickCompositor::create() { QWaylandCompositor::create(); diff --git a/src/compositor/compositor_api/qwaylandquickitem.cpp b/src/compositor/compositor_api/qwaylandquickitem.cpp index eea2814b1..f684f64c5 100644 --- a/src/compositor/compositor_api/qwaylandquickitem.cpp +++ b/src/compositor/compositor_api/qwaylandquickitem.cpp @@ -120,18 +120,47 @@ private: QWaylandBufferRef m_ref; }; +/*! + * \qmltype WaylandQuickItem + * \inqmlmodule QtWayland.Compositor + * \brief A Qt Quick item representing a WaylandView. + * + * When writing a WaylandCompositor in Qt Quick, this type can be used to display a + * client's contents on an output device and will pass user input to the + * client. + */ + +/*! + * \class QWaylandQuickItem + * \inmodule QtWaylandCompositor + * \brief A Qt Quick item representing a QWaylandView. + * + * When writing a QWaylandCompositor in Qt Quick, this class can be used to display a + * client's contents on an output device and will pass user input to the + * client. + */ + +/*! + * Constructs a QWaylandQuickItem with the given \a parent. + */ QWaylandQuickItem::QWaylandQuickItem(QQuickItem *parent) : QQuickItem(*new QWaylandQuickItemPrivate(), parent) { d_func()->init(); } +/*! + * \internal + */ QWaylandQuickItem::QWaylandQuickItem(QWaylandQuickItemPrivate &dd, QQuickItem *parent) : QQuickItem(dd, parent) { d_func()->init(); } +/*! + * Destroy the QWaylandQuickItem. + */ QWaylandQuickItem::~QWaylandQuickItem() { Q_D(QWaylandQuickItem); @@ -141,18 +170,52 @@ QWaylandQuickItem::~QWaylandQuickItem() d->provider->deleteLater(); } +/*! + * \qmlproperty object QtWaylandCompositor::WaylandQuickItem::compositor + * + * This property holds the compositor for the surface rendered by this WaylandQuickItem. + */ + +/*! + * \property QWaylandQuickItem::compositor + * + * This property holds the compositor for the surface rendered by this QWaylandQuickItem. + */ QWaylandCompositor *QWaylandQuickItem::compositor() const { Q_D(const QWaylandQuickItem); return d->view->surface() ? d->view->surface()->compositor() : Q_NULLPTR; } +/*! + * \qmlproperty object QWaylandQuickItem::view + * + * This property holds the view rendered by this WaylandQuickItem. + */ + +/*! + * \property QWaylandQuickItem::view + * + * This property holds the view rendered by this QWaylandQuickItem. + */ QWaylandView *QWaylandQuickItem::view() const { Q_D(const QWaylandQuickItem); return d->view.data(); } +/*! + * \qmlproperty object QWaylandQuickItem::surface + * + * This property holds the surface rendered by this WaylandQuickItem. + */ + +/*! + * \property QWaylandQuickItem::surface + * + * This property holds the surface rendered by this QWaylandQuickItem. + */ + QWaylandSurface *QWaylandQuickItem::surface() const { Q_D(const QWaylandQuickItem); @@ -166,19 +229,35 @@ void QWaylandQuickItem::setSurface(QWaylandSurface *surface) update(); } +/*! + * \qmlproperty enum QtWaylandCompositor::WaylandQuickItem::origin + * + * This property holds the origin of the QWaylandQuickItem. + */ + +/*! + * \property QWaylandQuickItem::origin + * + * This property holds the origin of the QWaylandQuickItem. + */ QWaylandSurface::Origin QWaylandQuickItem::origin() const { Q_D(const QWaylandQuickItem); return d->origin; } +/*! + * Returns the texture provider of this QWaylandQuickItem. + */ QSGTextureProvider *QWaylandQuickItem::textureProvider() const { Q_D(const QWaylandQuickItem); return d->provider; } - +/*! + * \internal + */ void QWaylandQuickItem::mousePressEvent(QMouseEvent *event) { Q_D(QWaylandQuickItem); @@ -200,6 +279,9 @@ void QWaylandQuickItem::mousePressEvent(QMouseEvent *event) inputDevice->sendMousePressEvent(event->button()); } +/*! + * \internal + */ void QWaylandQuickItem::mouseMoveEvent(QMouseEvent *event) { Q_D(QWaylandQuickItem); @@ -212,6 +294,9 @@ void QWaylandQuickItem::mouseMoveEvent(QMouseEvent *event) } } +/*! + * \internal + */ void QWaylandQuickItem::mouseReleaseEvent(QMouseEvent *event) { Q_D(QWaylandQuickItem); @@ -224,6 +309,9 @@ void QWaylandQuickItem::mouseReleaseEvent(QMouseEvent *event) } } +/*! + * \internal + */ void QWaylandQuickItem::hoverEnterEvent(QHoverEvent *event) { Q_D(QWaylandQuickItem); @@ -239,6 +327,9 @@ void QWaylandQuickItem::hoverEnterEvent(QHoverEvent *event) } } +/*! + * \internal + */ void QWaylandQuickItem::hoverMoveEvent(QHoverEvent *event) { Q_D(QWaylandQuickItem); @@ -256,6 +347,9 @@ void QWaylandQuickItem::hoverMoveEvent(QHoverEvent *event) } } +/*! + * \internal + */ void QWaylandQuickItem::hoverLeaveEvent(QHoverEvent *event) { Q_D(QWaylandQuickItem); @@ -267,6 +361,9 @@ void QWaylandQuickItem::hoverLeaveEvent(QHoverEvent *event) } } +/*! + * \internal + */ void QWaylandQuickItem::wheelEvent(QWheelEvent *event) { Q_D(QWaylandQuickItem); @@ -283,6 +380,9 @@ void QWaylandQuickItem::wheelEvent(QWheelEvent *event) } } +/*! + * \internal + */ void QWaylandQuickItem::keyPressEvent(QKeyEvent *event) { Q_D(QWaylandQuickItem); @@ -294,6 +394,9 @@ void QWaylandQuickItem::keyPressEvent(QKeyEvent *event) } } +/*! + * \internal + */ void QWaylandQuickItem::keyReleaseEvent(QKeyEvent *event) { Q_D(QWaylandQuickItem); @@ -305,6 +408,9 @@ void QWaylandQuickItem::keyReleaseEvent(QKeyEvent *event) } } +/*! + * \internal + */ void QWaylandQuickItem::touchEvent(QTouchEvent *event) { Q_D(QWaylandQuickItem); @@ -337,6 +443,9 @@ void QWaylandQuickItem::touchEvent(QTouchEvent *event) } } +/*! + * \internal + */ void QWaylandQuickItem::mouseUngrabEvent() { if (surface()) { @@ -345,12 +454,18 @@ void QWaylandQuickItem::mouseUngrabEvent() } } +/*! + * \internal + */ void QWaylandQuickItem::surfaceChangedEvent(QWaylandSurface *newSurface, QWaylandSurface *oldSurface) { Q_UNUSED(newSurface); Q_UNUSED(oldSurface); } +/*! + * \internal + */ void QWaylandQuickItem::handleSurfaceChanged() { Q_D(QWaylandQuickItem); @@ -384,6 +499,10 @@ void QWaylandQuickItem::handleSurfaceChanged() d->oldSurface = d->view->surface(); } +/*! + * Calling this function causes the item to take the focus of the + * input \a device. + */ void QWaylandQuickItem::takeFocus(QWaylandInputDevice *device) { setFocus(true); @@ -398,11 +517,17 @@ void QWaylandQuickItem::takeFocus(QWaylandInputDevice *device) target->setKeyboardFocus(surface()); } +/*! + * \internal + */ void QWaylandQuickItem::surfaceMappedChanged() { update(); } +/*! + * \internal + */ void QWaylandQuickItem::parentChanged(QWaylandSurface *newParent, QWaylandSurface *oldParent) { Q_UNUSED(oldParent); @@ -415,6 +540,9 @@ void QWaylandQuickItem::parentChanged(QWaylandSurface *newParent, QWaylandSurfac } } +/*! + * \internal + */ void QWaylandQuickItem::updateSize() { Q_D(QWaylandQuickItem); @@ -423,6 +551,23 @@ void QWaylandQuickItem::updateSize() } } +/*! + * \qmlproperty bool QtWaylandCompositor::WaylandQuickItem::focusOnClick + * + * This property specifies whether the WaylandQuickItem should take focus when + * it is clicked. + * + * The default is true. + */ + +/*! + * \property QWaylandQuickItem::focusOnClick + * + * This property specifies whether the QWaylandQuickItem should take focus when + * it is clicked. + * + * The default is true. + */ bool QWaylandQuickItem::focusOnClick() const { Q_D(const QWaylandQuickItem); @@ -439,13 +584,34 @@ void QWaylandQuickItem::setFocusOnClick(bool focus) emit focusOnClickChanged(); } -bool QWaylandQuickItem::inputRegionContains(QPointF localPosition) +/*! + * Returns true if the input region of this item's surface contains the + * position given by \a localPosition. + */ +bool QWaylandQuickItem::inputRegionContains(const QPointF &localPosition) { if (QWaylandSurface *s = surface()) return s->inputRegionContains(localPosition.toPoint()); return false; } +/*! + * \qmlproperty bool QtWaylandCompositor::WaylandQuickItem::sizeFollowsSurface + * + * This property specifies whether the size of the item should always match + * the size of its surface. + * + * The default is true. + */ + +/*! + * \property QWaylandQuickItem::sizeFollowsSurface + * + * This property specifies whether the size of the item should always match + * the size of its surface. + * + * The default is true. + */ bool QWaylandQuickItem::sizeFollowsSurface() const { Q_D(const QWaylandQuickItem); diff --git a/src/compositor/compositor_api/qwaylandquickitem.h b/src/compositor/compositor_api/qwaylandquickitem.h index 7737fe30f..298e2ec37 100644 --- a/src/compositor/compositor_api/qwaylandquickitem.h +++ b/src/compositor/compositor_api/qwaylandquickitem.h @@ -94,7 +94,7 @@ public: bool focusOnClick() const; void setFocusOnClick(bool focus); - bool inputRegionContains(QPointF localPosition); + bool inputRegionContains(const QPointF &localPosition); bool sizeFollowsSurface() const; void setSizeFollowsSurface(bool sizeFollowsSurface); diff --git a/src/compositor/compositor_api/qwaylandquickoutput.cpp b/src/compositor/compositor_api/qwaylandquickoutput.cpp index 0c48d1410..712413b44 100644 --- a/src/compositor/compositor_api/qwaylandquickoutput.cpp +++ b/src/compositor/compositor_api/qwaylandquickoutput.cpp @@ -80,6 +80,14 @@ void QWaylandQuickOutput::update() } } +/*! + * \qmlproperty bool QtWaylandCompositor::WaylandOutput::automaticFrameCallback + * + * This property holds whether the WaylandOutput automatically sends frame + * callbacks when rendering. + * + * The default is true. + */ bool QWaylandQuickOutput::automaticFrameCallback() const { return m_automaticFrameCallback; @@ -94,6 +102,9 @@ void QWaylandQuickOutput::setAutomaticFrameCallback(bool automatic) automaticFrameCallbackChanged(); } +/*! + * \internal + */ void QWaylandQuickOutput::updateStarted() { m_updateScheduled = false; diff --git a/src/compositor/compositor_api/qwaylandquicksurface.cpp b/src/compositor/compositor_api/qwaylandquicksurface.cpp index 7d01b8fd5..0fc07c6c5 100644 --- a/src/compositor/compositor_api/qwaylandquicksurface.cpp +++ b/src/compositor/compositor_api/qwaylandquicksurface.cpp @@ -86,6 +86,11 @@ QWaylandQuickSurface::~QWaylandQuickSurface() } +/*! + * \qmlproperty QtWaylandCompositor::WaylandSurface::useTextureAlpha + * + * This property specifies whether the surface should use texture alpha. + */ bool QWaylandQuickSurface::useTextureAlpha() const { Q_D(const QWaylandQuickSurface); @@ -102,6 +107,11 @@ void QWaylandQuickSurface::setUseTextureAlpha(bool useTextureAlpha) } } +/*! + * \qmlproperty QtWaylandCompositor::WaylandSurface::clientRenderingEnabled + * + * This property specifies whether client rendering is enabled for the surface. + */ bool QWaylandQuickSurface::clientRenderingEnabled() const { Q_D(const QWaylandQuickSurface); diff --git a/src/compositor/compositor_api/qwaylandsurface.cpp b/src/compositor/compositor_api/qwaylandsurface.cpp index be20326c0..3ac791eb2 100644 --- a/src/compositor/compositor_api/qwaylandsurface.cpp +++ b/src/compositor/compositor_api/qwaylandsurface.cpp @@ -352,22 +352,53 @@ QtWayland::SurfaceBuffer *QWaylandSurfacePrivate::createSurfaceBuffer(struct ::w return newBuffer; } +/*! + * \qmltype WaylandSurface + * \inqmlmodule QtWayland.Compositor + * \brief A rectangular area which is displayed on an output device. + * + * This type encapsulates a rectangular area of pixels that is displayed on an output device. It + * corresponds to the interface wl_surface in the Wayland protocol. + */ + +/*! + * \class QWaylandSurface + * \inmodule QtWaylandCompositor + * \brief A rectangular area which is displayed on an output device. + * + * This class encapsulates a rectangular area of pixels that is displayed on an output device. It + * corresponds to the interface wl_surface in the Wayland protocol. + */ + +/*! + * Constructs a an uninitialized QWaylandSurface. + */ QWaylandSurface::QWaylandSurface() : QWaylandObject(*new QWaylandSurfacePrivate()) { } +/*! + * Constructs and initializes a QWaylandSurface for the given \a compositor and \a client, and with the given \a id + * and \a version. + */ QWaylandSurface::QWaylandSurface(QWaylandCompositor *compositor, QWaylandClient *client, uint id, int version) : QWaylandObject(*new QWaylandSurfacePrivate()) { initialize(compositor, client, id, version); } +/*! + * \internal + */ QWaylandSurface::QWaylandSurface(QWaylandSurfacePrivate &dptr) : QWaylandObject(dptr) { } +/*! + * Destroys the QWaylandSurface. + */ QWaylandSurface::~QWaylandSurface() { Q_D(QWaylandSurface); @@ -375,6 +406,17 @@ QWaylandSurface::~QWaylandSurface() d->notifyViewsAboutDestruction(); } +/*! + * \qmlmethod void QtWaylandCompositor::WaylandSurface::initialize(object compositor, object client, int id, int version) + * + * Initializes the QWaylandSurface with the given \a compositor and \a client, and with the given \a id + * and \a version. + */ + +/*! + * Initializes the QWaylandSurface with the given \a compositor and \a client, and with the given \a id + * and \a version. + */ void QWaylandSurface::initialize(QWaylandCompositor *compositor, QWaylandClient *client, uint id, int version) { Q_D(QWaylandSurface); @@ -387,12 +429,26 @@ void QWaylandSurface::initialize(QWaylandCompositor *compositor, QWaylandClient #endif } +/*! + * Returns true if the QWaylandSurface has been initialized. + */ bool QWaylandSurface::isInitialized() const { Q_D(const QWaylandSurface); return d->isInitialized; } +/*! + * \qmlproperty object QtWaylandCompositor::WaylandSurface::client + * + * This property holds the client using this QWaylandSurface. + */ + +/*! + * \property QWaylandSurface::client + * + * This property holds the client using this QWaylandSurface. + */ QWaylandClient *QWaylandSurface::client() const { Q_D(const QWaylandSurface); @@ -402,36 +458,107 @@ QWaylandClient *QWaylandSurface::client() const return d->client; } +/*! + * \qmlproperty bool QtWaylandCompositor::WaylandSurface::isMapped + * + * This property holds whether the WaylandSurface has content. + */ + +/*! + * \property QWaylandSurface::isMapped + * + * This property holds whether the QWaylandSurface has content. + */ bool QWaylandSurface::isMapped() const { Q_D(const QWaylandSurface); return d->mapped; } +/*! + * \qmlproperty size QtWaylandCompositor::WaylandSurface::size + * + * This property holds the WaylandSurface's size in pixels. + */ + +/*! + * \property QWaylandSurface::size + * + * This property holds the QWaylandSurface's size in pixels. + */ QSize QWaylandSurface::size() const { Q_D(const QWaylandSurface); return d->size; } +/*! + * \qmlproperty enum QtWaylandCompositor::WaylandSurface::contentOrientation + * + * This property holds the orientation of the WaylandSurface's contents. + * + * \sa QtWaylandCompositor::WaylandOutput::transform + */ + +/*! + * \property QWaylandSurface::contentOrientation + * + * This property holds the orientation of the QWaylandSurface's contents. + * + * \sa QWaylandOutput::transform + */ Qt::ScreenOrientation QWaylandSurface::contentOrientation() const { Q_D(const QWaylandSurface); return d->contentOrientation; } +/*! + * \enum QWaylandSurface::Origin + * + * This enum type is used to specify the origin of a QWaylandSurface's buffer. + * + * \value OriginTopLeft The origin is the top left corner of the buffer. + * \value OriginBottomLeft The origin is the bottom left corner of the buffer. + */ + +/*! + * \qmlproperty enum QtWaylandCompositor::WaylandSurface::origin + * + * This property holds the origin of the WaylandSurface's buffer, or + * WaylandSurface.OriginTopLeft if the surface has no buffer. + * + * It can have the following values: + * \list + * \li WaylandSurface.OriginTopLeft The origin is the top left corner of the buffer. + * \li WaylandSurface.OriginBottomLeft The origin is the bottom left corner of the buffer. + * \endlist + */ + +/*! + * \property QWaylandSurface::origin + * + * This property holds the origin of the QWaylandSurface's buffer, or + * QWaylandSurface::OriginTopLeft if the surface has no buffer. + */ QWaylandSurface::Origin QWaylandSurface::origin() const { Q_D(const QWaylandSurface); return d->buffer ? d->buffer->origin() : QWaylandSurface::OriginTopLeft; } +/*! + * Returns the compositor for this QWaylandSurface. + */ QWaylandCompositor *QWaylandSurface::compositor() const { Q_D(const QWaylandSurface); return d->compositor; } +/*! + * Prepares all frame callbacks for sending. + */ void QWaylandSurface::frameStarted() { Q_D(QWaylandSurface); @@ -439,6 +566,9 @@ void QWaylandSurface::frameStarted() c->canSend = true; } +/*! + * Sends pending frame callbacks. + */ void QWaylandSurface::sendFrameCallbacks() { Q_D(QWaylandSurface); @@ -455,6 +585,9 @@ void QWaylandSurface::sendFrameCallbacks() } } +/*! + * Returns true if the QWaylandSurface has an input panel surface. Otherwise returns false. + */ bool QWaylandSurface::hasInputPanelSurface() const { Q_D(const QWaylandSurface); @@ -462,24 +595,57 @@ bool QWaylandSurface::hasInputPanelSurface() const return d->inputPanelSurface != 0; } +/*! + * Returns true if the QWaylandSurface's input region contains the point \a p. + * Otherwise returns false. + */ bool QWaylandSurface::inputRegionContains(const QPoint &p) const { Q_D(const QWaylandSurface); return d->inputRegion.contains(p); } +/*! + * \qmlmethod void QtWaylandCompositor::WaylandSurface::destroy() + * + * Destroys the QWaylandSurface. + */ + +/*! + * Destroys the QWaylandSurface. + */ void QWaylandSurface::destroy() { Q_D(QWaylandSurface); d->deref(); } +/*! + * \qmlmethod bool QtWaylandCompositor::WaylandSurface::isDestroyed() + * + * Returns true if the WaylandSurface has been destroyed. Otherwise returns false. + */ + +/*! + * Returns true if the QWaylandSurface has been destroyed. Otherwise returns false. + */ bool QWaylandSurface::isDestroyed() const { Q_D(const QWaylandSurface); return d->destroyed; } +/*! + * \qmlproperty bool QtWaylandCompositor::WaylandSurface::cursorSurface + * + * This property holds whether the WaylandSurface is a cursor surface. + */ + +/*! + * \property QWaylandSurface::cursorSurface + * + * This property holds whether the QWaylandSurface is a cursor surface. + */ void QWaylandSurface::markAsCursorSurface(bool cursorSurface) { Q_D(QWaylandSurface); @@ -493,10 +659,10 @@ bool QWaylandSurface::isCursorSurface() const } /*! - Updates the surface with the compositor's retained clipboard selection. While this - is done automatically when the surface receives keyboard focus, this function is - useful for updating clients which do not have keyboard focus. -*/ + * Updates the surface with the compositor's retained clipboard selection. While this + * is done automatically when the surface receives keyboard focus, this function is + * useful for updating clients which do not have keyboard focus. + */ void QWaylandSurface::updateSelection() { Q_D(QWaylandSurface); @@ -510,6 +676,11 @@ void QWaylandSurface::updateSelection() } } +/*! + * Returns this QWaylandSurface's throttling view. + * + * \sa QWaylandView::advance() + */ QWaylandView *QWaylandSurface::throttlingView() const { Q_D(const QWaylandSurface); @@ -518,6 +689,15 @@ QWaylandView *QWaylandSurface::throttlingView() const return d->views.first(); } +/*! + * Sets this QWaylandSurface's throttling view to \a view, in case there are + * multiple views of this surface. The throttling view is the view that + * governs the client's refresh rate. It takes care of discarding buffer + * references when QWaylandView::advance() is called. See the documentation + * for QWaylandView::advance() for more details. + * + * \sa QWaylandView::advance() + */ void QWaylandSurface::setThrottlingView(QWaylandView *view) { Q_D(QWaylandSurface); @@ -535,17 +715,26 @@ void QWaylandSurface::setThrottlingView(QWaylandView *view) d->views.move(index, 0); } +/*! + * Returns the views for this QWaylandSurface. + */ QList<QWaylandView *> QWaylandSurface::views() const { Q_D(const QWaylandSurface); return d->views; } +/*! + * Returns the QWaylandSurface corresponding to the Wayland resource \a res. + */ QWaylandSurface *QWaylandSurface::fromResource(::wl_resource *res) { return static_cast<QWaylandSurfacePrivate *>(QWaylandSurfacePrivate::Resource::fromResource(res)->surface_object)->q_func(); } +/*! + * Returns the Wayland resource corresponding to this QWaylandSurface. + */ struct wl_resource *QWaylandSurface::resource() const { Q_D(const QWaylandSurface); diff --git a/src/compositor/compositor_api/qwaylandtouch.cpp b/src/compositor/compositor_api/qwaylandtouch.cpp index 57c9dae2f..7d5e4254b 100644 --- a/src/compositor/compositor_api/qwaylandtouch.cpp +++ b/src/compositor/compositor_api/qwaylandtouch.cpp @@ -101,24 +101,49 @@ void QWaylandTouchPrivate::sendMotion(uint32_t time, int touch_id, const QPointF wl_fixed_from_double(position.x()), wl_fixed_from_double(position.y())); } -QWaylandTouch::QWaylandTouch(QWaylandInputDevice *seat, QObject *parent) - : QWaylandObject(*new QWaylandTouchPrivate(this, seat), parent) +/*! + * \class QWaylandTouch + * \inmodule QtWaylandCompositor + * \brief The QWaylandTouch class provides access to a touch device. + * + * This class provides access to the touch device in a QWaylandInputDevice. It corresponds to + * the Wayland interface wl_touch. + */ + +/*! + * Constructs a QWaylandTouch for the \a inputDevice and with the given \a parent. + */ +QWaylandTouch::QWaylandTouch(QWaylandInputDevice *inputDevice, QObject *parent) + : QWaylandObject(*new QWaylandTouchPrivate(this, inputDevice), parent) { connect(&d_func()->focusDestroyListener, &QWaylandDestroyListener::fired, this, &QWaylandTouch::focusDestroyed); } +/*! + * Returns the input device for this QWaylandTouch. + */ QWaylandInputDevice *QWaylandTouch::inputDevice() const { Q_D(const QWaylandTouch); return d->seat; } +/*! + * Returns the compositor for this QWaylandTouch. + */ QWaylandCompositor *QWaylandTouch::compositor() const { Q_D(const QWaylandTouch); return d->compositor(); } +/*! + * Sends a touch point event for the touch device with the given \a id, + * \a position, and \a state. + * + * + * \sa mouseFocus() + */ void QWaylandTouch::sendTouchPointEvent(int id, const QPointF &position, Qt::TouchPointState state) { Q_D(QWaylandTouch); @@ -141,6 +166,10 @@ void QWaylandTouch::sendTouchPointEvent(int id, const QPointF &position, Qt::Tou } } +/*! + * Sends a touch frame event for the touch device. This indicates the end of a + * contact point list. + */ void QWaylandTouch::sendFrameEvent() { Q_D(QWaylandTouch); @@ -148,6 +177,9 @@ void QWaylandTouch::sendFrameEvent() d->send_frame(d->focusResource->handle); } +/*! + * Sends a touch cancel event for the touch device. + */ void QWaylandTouch::sendCancelEvent() { Q_D(QWaylandTouch); @@ -155,6 +187,12 @@ void QWaylandTouch::sendCancelEvent() d->send_cancel(d->focusResource->handle); } +/*! + * Sends all the touch points in \a event for this touch device, followed + * by a touch frame event. + * + * \sa sendTouchPointEvent(), sendFrameEvent() + */ void QWaylandTouch::sendFullTouchEvent(QTouchEvent *event) { Q_D(QWaylandTouch); @@ -180,12 +218,18 @@ void QWaylandTouch::sendFullTouchEvent(QTouchEvent *event) sendFrameEvent(); } +/*! + * \internal + */ void QWaylandTouch::addClient(QWaylandClient *client, uint32_t id) { Q_D(QWaylandTouch); d->add(client->client(), id, 3); } +/*! + * Returns the Wayland resource for this QWaylandTouch. + */ struct wl_resource *QWaylandTouch::focusResource() const { Q_D(const QWaylandTouch); @@ -194,12 +238,18 @@ struct wl_resource *QWaylandTouch::focusResource() const return d->focusResource->handle; } +/*! + * Returns the view currently holding mouse focus in the input device. + */ QWaylandView *QWaylandTouch::mouseFocus() const { Q_D(const QWaylandTouch); return d->seat->mouseFocus(); } +/*! + * \internal + */ void QWaylandTouch::focusDestroyed(void *data) { Q_UNUSED(data) @@ -207,6 +257,9 @@ void QWaylandTouch::focusDestroyed(void *data) d->resetFocusState(); } +/*! + * \internal + */ void QWaylandTouch::mouseFocusChanged(QWaylandView *newFocus, QWaylandView *oldFocus) { Q_UNUSED(newFocus); diff --git a/src/compositor/compositor_api/qwaylandtouch.h b/src/compositor/compositor_api/qwaylandtouch.h index 14d9b6a71..47fa4b22b 100644 --- a/src/compositor/compositor_api/qwaylandtouch.h +++ b/src/compositor/compositor_api/qwaylandtouch.h @@ -55,7 +55,7 @@ class Q_COMPOSITOR_EXPORT QWaylandTouch : public QWaylandObject Q_OBJECT Q_DECLARE_PRIVATE(QWaylandTouch) public: - QWaylandTouch(QWaylandInputDevice *seat, QObject *parent = 0); + QWaylandTouch(QWaylandInputDevice *inputDevice, QObject *parent = 0); QWaylandInputDevice *inputDevice() const; QWaylandCompositor *compositor() const; diff --git a/src/compositor/compositor_api/qwaylandview.cpp b/src/compositor/compositor_api/qwaylandview.cpp index 8707b22d3..dd27308ad 100644 --- a/src/compositor/compositor_api/qwaylandview.cpp +++ b/src/compositor/compositor_api/qwaylandview.cpp @@ -56,12 +56,36 @@ void QWaylandViewPrivate::markSurfaceAsDestroyed(QWaylandSurface *surface) emit q->surfaceDestroyed(); } +/*! + * \qmltype WaylandView + * \inqmlmodule QtWayland.Compositor + * \brief Represents a view of a surface on an output. + * + * The WaylandView corresponds to the presentation of a surface on a specific output, managing + * the buffers that contain the contents to be rendered. You can have several views into the same surface. + */ + +/*! + * \class QWaylandView + * \inmodule QtWaylandCompositor + * \brief Represents a view of a surface on an output. + * + * The WaylandView corresponds to the presentation of a surface on a specific output, managing + * the buffers that contain the contents to be rendered. You can have several views into the same surface. + */ + +/*! + * Constructs a QWaylandView with the given \a renderObject and \a parent. + */ QWaylandView::QWaylandView(QObject *renderObject, QObject *parent) : QObject(*new QWaylandViewPrivate(),parent) { d_func()->renderObject = renderObject; } +/*! + * Destroys the QWaylandView. + */ QWaylandView::~QWaylandView() { Q_D(QWaylandView); @@ -77,12 +101,26 @@ QWaylandView::~QWaylandView() } +/*! + \internal Didn't we decide to remove this property? +*/ QObject *QWaylandView::renderObject() const { Q_D(const QWaylandView); return d->renderObject; } +/*! + * \qmlproperty object QtWaylandCompositor::WaylandView::surface + * + * This property holds the surface viewed by this WaylandView. + */ + +/*! + * \property QWaylandView::surface + * + * This property holds the surface viewed by this QWaylandView. + */ QWaylandSurface *QWaylandView::surface() const { Q_D(const QWaylandView); @@ -122,6 +160,17 @@ void QWaylandView::setSurface(QWaylandSurface *newSurface) } +/*! + * \qmlproperty object QtWaylandCompositor::WaylandView::surface + * + * This property holds the output on which this view displays its surface. + */ + +/*! + * \property QWaylandView::output + * + * This property holds the output on which this view displays its surface. + */ QWaylandOutput *QWaylandView::output() const { Q_D(const QWaylandView); @@ -145,6 +194,10 @@ void QWaylandView::setOutput(QWaylandOutput *newOutput) emit outputChanged(); } +/*! + * Attaches a new buffer \a ref and \a damage region to this QWaylandView. These + * will become current the next time advance() is called. + */ void QWaylandView::attach(const QWaylandBufferRef &ref, const QRegion &damage) { Q_D(QWaylandView); @@ -153,6 +206,23 @@ void QWaylandView::attach(const QWaylandBufferRef &ref, const QRegion &damage) d->nextDamage = damage; } +/*! + * Sets the next buffer and damage to current and returns true. If the buffer + * is locked or if no new buffer has been attached since the last call to + * advance(), the function returns false and does nothing. + * + * If this view is set as its surface's throttling view, discardCurrentBuffer() + * will be called on all views of the same surface for which the + * \l{QWaylandView::discardFrontBuffers}{discardFrontBuffers} + * property is set to true and the current buffer is the same as the + * throttling view's current buffer. + * + * This allows for a design where a primary + * view can make sure that views running on a lower frequency will release their + * front buffer references so that the buffer can be reused on the client side, + * avoiding the situation where the lower frequency views throttle the frame rate + * of the client application. + */ bool QWaylandView::advance() { Q_D(QWaylandView); @@ -176,6 +246,9 @@ bool QWaylandView::advance() return true; } +/*! + * Force the view to discard its current buffer, to allow it to be reused on the client side. + */ void QWaylandView::discardCurrentBuffer() { Q_D(QWaylandView); @@ -184,6 +257,9 @@ void QWaylandView::discardCurrentBuffer() d->forceAdvanceSucceed = true; } +/*! + * Returns a reference to this view's current buffer. + */ QWaylandBufferRef QWaylandView::currentBuffer() { Q_D(QWaylandView); @@ -191,6 +267,9 @@ QWaylandBufferRef QWaylandView::currentBuffer() return d->currentBuffer; } +/*! + * Returns the current damage region of this view. + */ QRegion QWaylandView::currentDamage() { Q_D(QWaylandView); @@ -198,6 +277,25 @@ QRegion QWaylandView::currentDamage() return d->currentDamage; } +/*! + * \qmlproperty bool QtWaylandCompositor::WaylandView::bufferLock + * + * This property holds whether the view's buffer is currently locked. When + * the buffer is locked, advance() will not advance to the next buffer, + * but will instead return false. + * + * The default is false. + */ + +/*! + * \property QWaylandView::bufferLock + * + * This property holds whether the view's buffer is currently locked. When + * the buffer is locked, advance() will not advance to the next buffer, + * but will instead return false. + * + * The default is false. + */ bool QWaylandView::isBufferLocked() const { Q_D(const QWaylandView); @@ -210,6 +308,12 @@ void QWaylandView::setBufferLock(bool locked) d->bufferLock = locked; } +/*! + * \property bool QWaylandView::discardFrontBuffers + * + * By default, the view locks the current buffer until advance() is called. Set this property + * to true to allow Qt to release the buffer when the throttling view is no longer using it. + */ bool QWaylandView::discardFrontBuffers() const { Q_D(const QWaylandView); @@ -225,6 +329,9 @@ void QWaylandView::setDiscardFrontBuffers(bool discard) emit discardFrontBuffersChanged(); } +/*! + * Returns the Wayland surface resource for this QWaylandView. + */ struct wl_resource *QWaylandView::surfaceResource() const { Q_D(const QWaylandView); diff --git a/src/compositor/doc/compositor.qdocconf b/src/compositor/doc/compositor.qdocconf new file mode 100644 index 000000000..cca12a541 --- /dev/null +++ b/src/compositor/doc/compositor.qdocconf @@ -0,0 +1,47 @@ +include($QT_INSTALL_DOCS/global//qt-module-defaults.qdocconf) + +project = QtWaylandCompositor +description = Qt Wayland Compositor Reference Documentation +url = http://doc.qt.io/QtWaylandCompositor/ +version = 1.0.0 + +qhp.projects = QtWaylandCompositor + +qhp.QtWaylandCompositor.file = qtwaylandcompositor.qhp +qhp.QtWaylandCompositor.namespace = org.qtproject.qtwaylandcompositor.1.0 +qhp.QtWaylandCompositor.virtualFolder = qtwaylandcompositor +qhp.QtWaylandCompositor.indexTitle = Qt Wayland Compositor +qhp.QtWaylandCompositor.indexRoot = +qhp.QtWaylandCompositor.filterAttributes = qtwaylandcompositor 1.0 qtrefdoc +qhp.QtWaylandCompositor.customFilters.Qt.name = QtWaylandCompositor 1.0 +qhp.QtWaylandCompositor.customFilters.Qt.filterAttributes = qtwaylandcompositor 1.0 + +qhp.QtWaylandCompositor.subprojects = qmltypes classes examples +qhp.QtWaylandCompositor.subprojects.qmltypes.title = QML Types +qhp.QtWaylandCompositor.subprojects.qmltypes.indexTitle = Qt Wayland Compositor QML Types +qhp.QtWaylandCompositor.subprojects.qmltypes.selectors = qmlclass +qhp.QtWaylandCompositor.subprojects.qmltypes.sortPages = true +qhp.QtWaylandCompositor.subprojects.classes.title = C++ Classes +qhp.QtWaylandCompositor.subprojects.classes.indexTitle = Qt Wayland Compositor C++ Classes +qhp.QtWaylandCompositor.subprojects.classes.selectors = class fake:headerfile +qhp.QtWaylandCompositor.subprojects.classes.sortPages = true +qhp.QtWaylandCompositor.subprojects.examples.title = Examples +qhp.QtWaylandCompositor.subprojects.examples.indexTitle = Qt Wayland Compositor Examples +qhp.QtWaylandCompositor.subprojects.examples.selectors = fake:example + +indexes += $QT_INSTALL_DOCS/qtqml/qtqml.index \ + $QT_INSTALL_DOCS/qtquick/qtquick.index \ + $QT_INSTALL_DOCS/qtdoc/qtdoc.index \ + $QT_INSTALL_DOCS/qtquickcontrols/qtquickcontrols.index + +exampledirs += ../../../examples/wayland/ +headerdirs += ../ +sourcedirs += ../ +imagedirs += images + +examplesinstallpath = waylandcompositor + +navigation.landingpage = "Qt Wayland Compositor" +navigation.qmltypespage = "Qt Wayland Compositor QML Types" +navigation.cppclassespage = "Qt Wayland Compositor C++ Classes" +buildversion = "Qt Wayland Compositor 1.0" diff --git a/src/compositor/doc/src/qtwaylandcompositor-cpp.qdoc b/src/compositor/doc/src/qtwaylandcompositor-cpp.qdoc new file mode 100644 index 000000000..4b38c8613 --- /dev/null +++ b/src/compositor/doc/src/qtwaylandcompositor-cpp.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see http://www.qt.io/terms-conditions. For further +** information use the contact form at http://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QtWaylandCompositor + \title Qt Wayland Compositor C++ Classes + \ingroup modules + \qtvariable waylandcompositor + + \brief Provides C++ classes for writing custom Wayland display servers. + + To include the definitions of the module's classes, use the following directive: + + \code + #include <QtWaylandCompositor> + \endcode + + To link against the module, add this line to your \l qmake \c .pro file: + + \code + QT += waylandcompositor + \endcode + + For more information about using these classes in your application, + see the \l{Qt Wayland Compositor} documentation. +*/ diff --git a/src/compositor/doc/src/qtwaylandcompositor-examples.qdoc b/src/compositor/doc/src/qtwaylandcompositor-examples.qdoc new file mode 100644 index 000000000..2b8511281 --- /dev/null +++ b/src/compositor/doc/src/qtwaylandcompositor-examples.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see http://www.qt.io/terms-conditions. For further +** information use the contact form at http://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group qtwaylandcompositor-examples + \title Qt Wayland Compositor Examples + \brief Examples for the Qt Wayland Compositor module + + These are the Qt Wayland Compositor examples. + +*/ + diff --git a/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc b/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc new file mode 100644 index 000000000..0fc89e6bd --- /dev/null +++ b/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see http://www.qt.io/terms-conditions. For further +** information use the contact form at http://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page index.html + \title Qt Wayland Compositor + \brief An API to develop display servers supporting the Wayland protocol + + Qt Wayland Compositor is a module consisting of QML and C++ APIs for developing + custom display servers based on the \l{http://wayland.freedesktop.org}{Wayland protocol}. + The server displays content from client applications that support the Wayland protocol. + + \section1 Environment Variables and Command-line Arguments + + The Qt Wayland Compositor API recognizes some environment variables and command-line arguments + that can be used to customize its behavior. + + The environment variables: + \list + \li QT_WAYLAND_HARDWARE_INTEGRATION Selects which hardware integration plugin to use. + \li QT_WAYLAND_CLIENT_BUFFER_INTEGRATION Selects which client buffer integration plugin to use. + \li QT_WAYLAND_SERVER_BUFFER_INTEGRATION Selects which server integration plugin to use. + \endlist + + The command-line arguments: + \list + \li --wayland-socket-name Overrides the default socket name used for communicating with clients. + \endlist + + \section1 Examples + + Take a look at the \l{Qt Wayland Compositor Examples} for a demonstration on + how the APIs can be used to write custom display servers. + + \section1 API Reference + + The Qt Wayland Compositor API can be used from C++ or QML. + + \list + \li \l{Qt Wayland Compositor QML Types} + \li \l{Qt Wayland Compositor C++ Classes} + \endlist + +*/ diff --git a/src/compositor/doc/src/qtwaylandcompositor-qmltypes.qdoc b/src/compositor/doc/src/qtwaylandcompositor-qmltypes.qdoc new file mode 100644 index 000000000..ae8398735 --- /dev/null +++ b/src/compositor/doc/src/qtwaylandcompositor-qmltypes.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see http://www.qt.io/terms-conditions. For further +** information use the contact form at http://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \qmlmodule QtWayland.Compositor 1.0 + \title Qt Wayland Compositor QML Types + \ingroup qmlmodules + \brief Provides QML types for writing custom Wayland display servers. + + The Qt Wayland module provides QML types that can be used to create custom + display servers supporting the Wayland protocol. + + The QML types can be imported into your application using the following + import statement: + + \code + import QtWayland.Compositor 1.0 + \endcode + + To link against the module, add this line to your \l qmake \c .pro file: + + \code + QT += waylandcompositor + \endcode + + For more information about using these types in your application, + see the \l{Qt Wayland Compositor} documentation. +*/ diff --git a/src/compositor/extensions/qwaylandquickshellsurfaceitem.cpp b/src/compositor/extensions/qwaylandquickshellsurfaceitem.cpp index 2dcc8f762..7589ba175 100644 --- a/src/compositor/extensions/qwaylandquickshellsurfaceitem.cpp +++ b/src/compositor/extensions/qwaylandquickshellsurfaceitem.cpp @@ -42,16 +42,53 @@ QT_BEGIN_NAMESPACE +/*! + * \qmltype ShellSurfaceItem + * \inqmlmodule QtWayland.Compositor + * \brief An item representing a ShellSurface. + * + * This type can be used to render shell surfaces as part of a Qt Quick scene. + * It handles moving and resizing triggered by clicking on the window decorations. + */ + +/*! + * \class QWaylandQuickShellSurfaceItem + * \inmodule QtWaylandCompositor + * \brief A Qt Quick item for QWaylandShellSurface. + * + * This class can be used to create Qt Quick items representing shell surfaces. + * It handles moving and resizing triggered by clicking on the window decorations. + * + * \sa QWaylandQuickItem + */ + +/*! + * Constructs a QWaylandQuickShellSurfaceItem with the given \a parent. + */ QWaylandQuickShellSurfaceItem::QWaylandQuickShellSurfaceItem(QQuickItem *parent) : QWaylandQuickItem(*new QWaylandQuickShellSurfaceItemPrivate(), parent) { } +/*! + * \internal + */ QWaylandQuickShellSurfaceItem::QWaylandQuickShellSurfaceItem(QWaylandQuickShellSurfaceItemPrivate &dd, QQuickItem *parent) : QWaylandQuickItem(dd, parent) { } +/*! + * \qmlproperty object QtWaylandCompositor::ShellSurfaceItem::shellSurface + * + * This property holds the shell surface rendered by this ShellSurfaceItem. + */ + +/*! + * \property QWaylandQuickShellSurfaceItem::shellSurface + * + * This property holds the shell surface rendered by this QWaylandQuickShellSurfaceItem. + */ QWaylandShellSurface *QWaylandQuickShellSurfaceItem::shellSurface() const { Q_D(const QWaylandQuickShellSurfaceItem); @@ -76,6 +113,12 @@ void QWaylandQuickShellSurfaceItem::setShellSurface(QWaylandShellSurface *shellS emit shellSurfaceChanged(); } +/*! + * \internal + * \property QWaylandQuickShellSurfaceItem::moveItem + * + * This property holds the move item for this QWaylandQuickShellSurfaceItem. + */ QQuickItem *QWaylandQuickShellSurfaceItem::moveItem() const { Q_D(const QWaylandQuickShellSurfaceItem); @@ -91,6 +134,9 @@ void QWaylandQuickShellSurfaceItem::setMoveItem(QQuickItem *moveItem) moveItemChanged(); } +/*! + * \internal + */ void QWaylandQuickShellSurfaceItem::handleStartMove(QWaylandInputDevice *inputDevice) { Q_D(QWaylandQuickShellSurfaceItem); @@ -99,6 +145,9 @@ void QWaylandQuickShellSurfaceItem::handleStartMove(QWaylandInputDevice *inputDe d->moveState.initialized = false; } +/*! + * \internal + */ void QWaylandQuickShellSurfaceItem::handleStartResize(QWaylandInputDevice *inputDevice, QWaylandShellSurface::ResizeEdge edges) { Q_D(QWaylandQuickShellSurfaceItem); @@ -109,6 +158,9 @@ void QWaylandQuickShellSurfaceItem::handleStartResize(QWaylandInputDevice *input d->resizeState.initialized = false; } +/*! + * \internal + */ void QWaylandQuickShellSurfaceItem::adjustOffsetForNextFrame(const QPointF &offset) { Q_D(QWaylandQuickShellSurfaceItem); @@ -116,6 +168,9 @@ void QWaylandQuickShellSurfaceItem::adjustOffsetForNextFrame(const QPointF &offs moveItem->setPosition(moveItem->position() + offset); } +/*! + * \internal + */ void QWaylandQuickShellSurfaceItem::mouseMoveEvent(QMouseEvent *event) { Q_D(QWaylandQuickShellSurfaceItem); @@ -146,6 +201,9 @@ void QWaylandQuickShellSurfaceItem::mouseMoveEvent(QMouseEvent *event) } } +/*! + * \internal + */ void QWaylandQuickShellSurfaceItem::mouseReleaseEvent(QMouseEvent *event) { Q_D(QWaylandQuickShellSurfaceItem); @@ -156,6 +214,9 @@ void QWaylandQuickShellSurfaceItem::mouseReleaseEvent(QMouseEvent *event) QWaylandQuickItem::mouseReleaseEvent(event); } +/*! + * \internal + */ void QWaylandQuickShellSurfaceItem::surfaceChangedEvent(QWaylandSurface *newSurface, QWaylandSurface *oldSurface) { if (oldSurface) @@ -165,6 +226,9 @@ void QWaylandQuickShellSurfaceItem::surfaceChangedEvent(QWaylandSurface *newSurf connect(newSurface, &QWaylandSurface::offsetForNextFrame, this, &QWaylandQuickShellSurfaceItem::adjustOffsetForNextFrame); } +/*! + * \internal + */ void QWaylandQuickShellSurfaceItem::componentComplete() { Q_D(QWaylandQuickShellSurfaceItem); diff --git a/src/compositor/extensions/qwaylandshell.cpp b/src/compositor/extensions/qwaylandshell.cpp index fc4e3fdb3..5a08b9e01 100644 --- a/src/compositor/extensions/qwaylandshell.cpp +++ b/src/compositor/extensions/qwaylandshell.cpp @@ -218,14 +218,61 @@ void QWaylandShellSurfacePrivate::shell_surface_set_class(Resource *resource, emit q->classNameChanged(); } +/*! + * \qmltype Shell + * \inqmlmodule QtWayland.Compositor + * \brief Extension for desktop-style user interfaces. + * + * The Shell extension provides a way to assiociate a \l{ShellSurface} + * with a regular Wayland surface. Using the shell surface interface, the client + * can request that the surface is resized, moved, and so on. + * + * Shell corresponds to the Wayland interface wl_shell. + * + * To provide the functionality of the shell extension in a compositor, create + * an instance of the Shell component and add it to the list of extensions + * supported by the compositor: + * \code + * import QtWayland.Compositor 1.0 + * + * WaylandCompositor { + * extensions: Shell { + * // ... + * } + * } + * \endcode + */ + +/*! + * \class QWaylandShell + * \inmodule QtWaylandCompositor + * \brief Extension for desktop-style user interfaces. + * + * The QWaylandShell extension provides a way to assiociate a QWaylandShellSurface with + * a regular Wayland surface. Using the shell surface interface, the client + * can request that the surface is resized, moved, and so on. + * + * Shell corresponds to the Wayland interface wl_shell. + */ + +/*! + * Constructs a QWaylandShell object. + */ QWaylandShell::QWaylandShell() : QWaylandExtensionTemplate<QWaylandShell>(*new QWaylandShellPrivate()) { } +/*! + * Constructs a QWaylandShell object for the provided \a compositor. + */ QWaylandShell::QWaylandShell(QWaylandCompositor *compositor) : QWaylandExtensionTemplate<QWaylandShell>(compositor, *new QWaylandShellPrivate()) { } + +/*! + * Initializes the shell extension. + */ void QWaylandShell::initialize() { Q_D(QWaylandShell); @@ -238,27 +285,91 @@ void QWaylandShell::initialize() d->init(compositor->display(), 1); } +/*! + * Returns the Wayland interface for the QWaylandShell. + */ const struct wl_interface *QWaylandShell::interface() { return QWaylandShellPrivate::interface(); } +/*! + * \qmlsignal void QtWaylandCompositor::Shell::createShellSurface(object surface, object client, int id) + * + * This signal is emitted when the \a client has requested a shell surface to be associated + * with \a surface and be assigned the given \a id. The handler for this signal is + * expected to create the shell surface and initialize it within the scope of the + * signal emission. + */ + +/*! + * \fn void QWaylandShell::createShellSurface(QWaylandSurface *surface, QWaylandClient *client, uint id) + * + * This signal is emitted when the \a client has requested a shell surface to be associated + * with \a surface and be assigned the given \a id. The handler for this signal is + * expected to create the shell surface and initialize it within the scope of the + * signal emission. + */ + +/*! + * \internal + */ QByteArray QWaylandShell::interfaceName() { return QWaylandShellPrivate::interfaceName(); } +/*! + * \qmltype ShellSurface + * \inqmlmodule QtWayland.Compositor + * \brief A shell surface providing desktop-style compositor-specific features to a surface. + * + * This type is part of the \l{Shell} extension and provides a way to extend + * the functionality of an existing WaylandSurface with features specific to desktop-style + * compositors, such as resizing and moving the surface. + * + * It corresponds to the Wayland interface wl_shell_surface. + */ + +/*! + * \class QWaylandShellSurface + * \inmodule QtWaylandCompositor + * \brief A shell surface providing desktop-style compositor-specific features to a surface. + * + * This class is part of the QWaylandShell extension and provides a way to extend + * the functionality of an existing QWaylandSurface with features specific to desktop-style + * compositors, such as resizing and moving the surface. + * + * It corresponds to the Wayland interface wl_shell_surface. + */ + +/*! + * Constructs a QWaylandShellSurface. + */ QWaylandShellSurface::QWaylandShellSurface() : QWaylandExtensionTemplate<QWaylandShellSurface>(*new QWaylandShellSurfacePrivate) { } +/*! + * Constructs a QWaylandShellSurface for \a surface and initializes it with the given \a shell, \a client, + * and \a id. + */ QWaylandShellSurface::QWaylandShellSurface(QWaylandShell *shell, QWaylandSurface *surface, QWaylandClient *client, uint id) : QWaylandExtensionTemplate<QWaylandShellSurface>(*new QWaylandShellSurfacePrivate) { initialize(shell, surface, client, id); } +/*! + * \qmlmethod void QtWaylandCompositor::ShellSurface::initialize(object shell, object surface, object client, int id) + * + * Initializes the ShellSurface, associating it with the given \a shell, \a surface, \a client, and \a id. + */ + +/*! + * Initializes the QWaylandShellSurface, associating it with the given \a shell, \a surface, \a client, and \a id. + */ void QWaylandShellSurface::initialize(QWaylandShell *shell, QWaylandSurface *surface, QWaylandClient *client, uint id) { Q_D(QWaylandShellSurface); @@ -269,6 +380,10 @@ void QWaylandShellSurface::initialize(QWaylandShell *shell, QWaylandSurface *sur emit surfaceChanged(); QWaylandExtension::initialize(); } + +/*! + * \internal + */ void QWaylandShellSurface::initialize() { QWaylandExtensionTemplate::initialize(); @@ -279,6 +394,9 @@ const struct wl_interface *QWaylandShellSurface::interface() return QWaylandShellSurfacePrivate::interface(); } +/*! + * \internal + */ QByteArray QWaylandShellSurface::interfaceName() { return QWaylandShellSurfacePrivate::interfaceName(); @@ -301,36 +419,130 @@ QSize QWaylandShellSurface::sizeForResize(const QSizeF &size, const QPointF &del return QSizeF(width, height).toSize(); } +/*! + * \enum QWaylandShellSurface::ResizeEdge + * + * This enum type provides a way to specify a specific edge or corner of + * the surface. + * + * \value DefaultEdge The default edge. + * \value TopEdge The top edge. + * \value BottomEdge The bottom edge. + * \value LeftEdge The left edge. + * \value TopLeftEdge The top left corner. + * \value BottomLeftEdge The bottom left corner. + * \value RightEdge The right edge. + * \value TopRightEdge The top right corner. + * \value BottomRightEdge The bottom right corner. + */ + +/*! + * \qmlmethod void QtWaylandCompositor::ShellSurface::sendConfigure(size size, enum edges) + * + * Sends a configure event to the client, suggesting that it resize its surface to + * the provided \a size. The \a edges provide a hint about how the surface + * was resized. + */ + +/*! + * Sends a configure event to the client, suggesting that it resize its surface to + * the provided \a size. The \a edges provide a hint about how the surface + * was resized. + */ void QWaylandShellSurface::sendConfigure(const QSize &size, ResizeEdge edges) { Q_D(QWaylandShellSurface); d->send_configure(edges, size.width(), size.height()); } +/*! + * \qmlmethod void QtWaylandCompositor::ShellSurface::sendPopupDone() + * + * Sends a popup_done event to the client to indicate that the user has clicked + * somewhere outside the client's surfaces. + */ + +/*! + * Sends a popup_done event to the client to indicate that the user has clicked + * somewhere outside the client's surfaces. + */ void QWaylandShellSurface::sendPopupDone() { Q_D(QWaylandShellSurface); d->send_popup_done(); } +/*! + * \qmlproperty object QtWaylandCompositor::ShellSurface::surface + * + * This property holds the surface associated with this ShellSurface. + */ + +/*! + * \property QWaylandShellSurface::surface + * + * This property holds the surface associated with this QWaylandShellSurface. + */ QWaylandSurface *QWaylandShellSurface::surface() const { Q_D(const QWaylandShellSurface); return d->m_surface; } +/*! + * \enum QWaylandShellSurface::FocusPolicy + * + * This enum type is used to specify the focus policy of a shell surface. + * + * \value DefaultFocus The default focus policy should be used. + * \value NoKeyboardFocus The shell surface should not get keyboard focus. + */ + +/*! + * \qmlproperty enum QtWaylandCompositor::ShellSurface::focusPolicy + * + * This property holds the focus policy of the ShellSurface. + */ + +/*! + * \property QWaylandShellSurface::focusPolicy + * + * This property holds the focus policy of the QWaylandShellSurface. + */ QWaylandShellSurface::FocusPolicy QWaylandShellSurface::focusPolicy() const { Q_D(const QWaylandShellSurface); return d->m_focusPolicy; } +/*! + * \qmlproperty string QtWaylandCompositor::ShellSurface::title + * + * This property holds the title of the ShellSurface. + */ + +/*! + * \property QWaylandShellSurface::title + * + * This property holds the title of the QWaylandShellSurface. + */ QString QWaylandShellSurface::title() const { Q_D(const QWaylandShellSurface); return d->m_title; } +/*! + * \qmlproperty string QtWaylandCompositor::ShellSurface::className + * + * This property holds the class name of the ShellSurface. + */ + +/*! + * \property QWaylandShellSurface::className + * + * This property holds the class name of the QWaylandShellSurface. + */ QString QWaylandShellSurface::className() const { Q_D(const QWaylandShellSurface); |