diff --git a/src/wayland/compositor_interface.h b/src/wayland/compositor_interface.h index 9d66e1de21..347d3fd30a 100644 --- a/src/wayland/compositor_interface.h +++ b/src/wayland/compositor_interface.h @@ -36,6 +36,10 @@ namespace Server class Display; class SurfaceInterface; +/** + * @brief Represents the Global for wl_compositor interface. + * + **/ class KWAYLANDSERVER_EXPORT CompositorInterface : public Global { Q_OBJECT @@ -43,7 +47,13 @@ public: virtual ~CompositorInterface(); Q_SIGNALS: + /** + * Emitted whenever this CompositorInterface created a SurfaceInterface. + **/ void surfaceCreated(KWayland::Server::SurfaceInterface*); + /** + * Emitted whenever this CompositorInterface created a RegionInterface. + **/ void regionCreated(KWayland::Server::RegionInterface*); private: diff --git a/src/wayland/pointer_interface.h b/src/wayland/pointer_interface.h index 6d23e75709..eb18a0101b 100644 --- a/src/wayland/pointer_interface.h +++ b/src/wayland/pointer_interface.h @@ -36,6 +36,7 @@ class SurfaceInterface; /** * @brief Resource for the wl_pointer interface. * + * @see SeatInterface **/ class KWAYLANDSERVER_EXPORT PointerInterface : public Resource { diff --git a/src/wayland/seat_interface.h b/src/wayland/seat_interface.h index 36adfed828..d4f23bee43 100644 --- a/src/wayland/seat_interface.h +++ b/src/wayland/seat_interface.h @@ -38,17 +38,83 @@ namespace Server { class Display; -class KeyboardInterface; class SurfaceInterface; +/** + * @brief Represents a Seat on the Wayland Display. + * + * A Seat is a set of input devices (e.g. Keyboard, Pointer and Touch) the client can connect + * to. The server needs to announce which input devices are supported and passes dedicated input + * focus to a SurfaceInterface. Only the focused surface receives input events. + * + * The SeatInterface internally handles enter and release events when setting a focused surface. + * Also it handles input translation from global to the local coordination, removing the need from + * the user of the API to track the focused surfaces and can just interact with this class. + * + * To create a SeatInterface use @link Display::createSeat @endlink. Then one can set up what is + * supported. Last but not least create needs to be called. + * + * @code + * SeatInterface *seat = display->createSeat(); + * // set up + * seat->setName(QStringLiteral("seat0")); + * seat->setHasPointer(true); + * seat->setHasKeyboard(true); + * seat->setHasTouch(false); + * // now fully create + * seat->create(); + * @endcode + * + * To forward input events one needs to set the focused surface, update time stamp and then + * forward the actual events: + * + * @code + * // example for pointer + * seat->setFocusedPointerSurface(surface, QPointF(100, 200)); // surface at it's global position + * seat->setTimestamp(100); + * seat->setPointerPos(QPointF(350, 210)); // global pos, local pos in surface: 250,10 + * seat->setTimestamp(110); + * seat->pointerButtonPressed(Qt::LeftButton); + * seat->setTimestamp(120); + * seat->pointerButtonReleased(Qt::LeftButton); + * @endcode + * + * @see KeyboardInterface + * @see PointerInterface + * @see TouchInterface + * @see SurfaceInterface + **/ class KWAYLANDSERVER_EXPORT SeatInterface : public Global { Q_OBJECT + /** + * The name of the Seat + **/ Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged) + /** + * Whether the SeatInterface supports a pointer device. + **/ Q_PROPERTY(bool pointer READ hasPointer WRITE setHasPointer NOTIFY hasPointerChanged) + /** + * Whether the SeatInterface supports a keyboard device. + **/ Q_PROPERTY(bool keyboard READ hasKeyboard WRITE setHasKeyboard NOTIFY hasKeyboardChanged) + /** + * Whether the SeatInterface supports a touch device. + * @deprecated use touch + **/ Q_PROPERTY(bool tourch READ hasTouch WRITE setHasTouch NOTIFY hasTouchChanged) + /** + * Whether the SeatInterface supports a touch device. + **/ + Q_PROPERTY(bool touch READ hasTouch WRITE setHasTouch NOTIFY hasTouchChanged) + /** + * The global pointer position. + **/ Q_PROPERTY(QPointF pointerPos READ pointerPos WRITE setPointerPos NOTIFY pointerPosChanged) + /** + * The current timestamp passed to the input events. + **/ Q_PROPERTY(quint32 timestamp READ timestamp WRITE setTimestamp NOTIFY timestampChanged) public: virtual ~SeatInterface(); @@ -66,25 +132,113 @@ public: void setTimestamp(quint32 time); quint32 timestamp() const; - // pointer related methods + /** + * @name Pointer related methods + **/ + ///@{ + /** + * Updates the global pointer @p pos. + * + * Sends a pointer motion event to the focused pointer surface. + **/ void setPointerPos(const QPointF &pos); + /** + * @returns the global pointer position + **/ QPointF pointerPos() const; + /** + * Sets the focused pointer @p surface. + * All pointer events will be sent to the @p surface till a new focused pointer surface gets + * installed. When the focus pointer surface changes a leave event is sent to the previous + * focused surface. + * + * To unset the focused pointer surface pass @c nullptr as @p surface. + * + * Pointer motion events are adjusted to the local position based on the @p surfacePosition. + * If the surface changes it's position in the global coordinate system + * use setFocusedPointerSurfacePosition to update. + * + * @param surface The surface which should become the new focused pointer surface. + * @param surfacePosition The position of the surface in the global coordinate system + * + * @see setPointerPos + * @see focucedPointerSurface + * @see focusedPointer + * @see setFocusedPointerSurfacePosition + * @see focusedPointerSurfacePosition + **/ void setFocusedPointerSurface(SurfaceInterface *surface, const QPointF &surfacePosition = QPoint()); + /** + * @returns The currently focused pointer surface, that is the surface receiving pointer events. + * @see setFocusedPointerSurface + **/ SurfaceInterface *focusedPointerSurface() const; + /** + * @returns The PointerInterface belonging to the focused pointer surface, if any. + * @see setFocusedPointerSurface + **/ PointerInterface *focusedPointer() const; + /** + * Updates the global position of the currently focused pointer surface + * + * @param surfacePosition The new global position of the focused pointer surface + * @see focusedPointerSurface + * @see setFocusedPointerSurface + **/ void setFocusedPointerSurfacePosition(const QPointF &surfacePosition); + /** + * @returns The position of the focused pointer surface in global coordinates. + * @see setFocusedPointerSurfacePosition + * @see setFocusedPointerSurface + **/ QPointF focusedPointerSurfacePosition() const; + /** + * Marks the @p button as pressed. + * + * If there is a focused pointer surface a button pressed event is sent to it. + * + * @param button The Linux button code + **/ void pointerButtonPressed(quint32 button); + /** + * @overload + **/ void pointerButtonPressed(Qt::MouseButton button); + /** + * Marks the @p button as released. + * + * If there is a focused pointer surface a button release event is sent to it. + * + * @param button The Linux button code + **/ void pointerButtonReleased(quint32 button); + /** + * @overload + **/ void pointerButtonReleased(Qt::MouseButton button); + /** + * @returns whether the @p button is pressed + **/ bool isPointerButtonPressed(quint32 button) const; + /** + * @returns whether the @p button is pressed + **/ bool isPointerButtonPressed(Qt::MouseButton button) const; + /** + * @returns the last serial for @p button. + **/ quint32 pointerButtonSerial(quint32 button) const; + /** + * @returns the last serial for @p button. + **/ quint32 pointerButtonSerial(Qt::MouseButton button) const; void pointerAxis(Qt::Orientation orientation, quint32 delta); + ///@} - // keyboard related methods + /** + * @name keyboard related methods + **/ + ///@{ void setKeymap(int fd, quint32 size); void keyPressed(quint32 key); void keyReleased(quint32 key); @@ -129,8 +283,12 @@ public: void setFocusedKeyboardSurface(SurfaceInterface *surface); SurfaceInterface *focusedKeyboardSurface() const; KeyboardInterface *focusedKeyboard() const; + ///@} - // touch related methods + /** + * @name touch related methods + **/ + ///@{ void setFocusedTouchSurface(SurfaceInterface *surface, const QPointF &surfacePosition = QPointF()); SurfaceInterface *focusedTouchSurface() const; TouchInterface *focusedTouch() const; @@ -142,6 +300,7 @@ public: void touchFrame(); void cancelTouchSequence(); bool isTouchSequence() const; + ///@} static SeatInterface *get(wl_resource *native);