Commit 0676d539 authored by Martin Flöser's avatar Martin Flöser
Browse files

[server] Another round of docu improvements

parent 5e3bb706
......@@ -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:
......
......@@ -36,6 +36,7 @@ class SurfaceInterface;
/**
* @brief Resource for the wl_pointer interface.
*
* @see SeatInterface
**/
class KWAYLANDSERVER_EXPORT PointerInterface : public Resource
{
......
......@@ -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);
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment