some documentation

Author: CMurtagh-LGTM

src/wayland/input_method/c_helpers.hpp

@@ -13,6 +13,7 @@ struct FreeDeleter {
 using uniqueCString = std::unique_ptr<const char, FreeDeleter>;
 
 // this is a bit half baked but works for what I need it for
+/// Handles the lifetime of a memory mapped shm
 class SharedMemory {
 public:
 	SharedMemory(const char* shmName, int oFlag, size_t size);

src/wayland/input_method/input_method.hpp

@@ -9,6 +9,7 @@ namespace qs::wayland::input_method::impl {
 
 class InputMethodKeyboardGrab;
 
+/// A lightweight handle for the wayland input_method protocol
 class InputMethodHandle
     : public QObject
     , private QtWayland::zwp_input_method_v2 {

src/wayland/input_method/key_map_state.hpp

@@ -11,6 +11,7 @@
 
 namespace qs::wayland::input_method::impl {
 
+/// A wrapper that handles xkb_keymap and xkb_state lifetime with some convenience functions
 class KeyMapState {
 public:
 	KeyMapState() = default;

src/wayland/input_method/keyboard_grab.hpp

@@ -11,10 +11,14 @@ namespace qs::wayland::input_method::impl {
 
 class VirtualKeyboardHandle;
 
+// TODO(cmurtagh-lgtm) Implement the popup-surface part of the protocol
 class InputMethodPopupSurface: QObject {
 	Q_OBJECT;
 };
 
+/// A wrapper around the input_method_keyboard_grab protocol
+/// Only some control keys and keys that are representable by utf32 are captured,
+/// other keys are passed back to the compositor via virtual keyboard.
 class InputMethodKeyboardGrab
     : public QObject
     , private QtWayland::zwp_input_method_keyboard_grab_v2 {

src/wayland/input_method/manager.cpp

@@ -15,8 +15,9 @@ InputMethodManager::InputMethodManager(): QWaylandClientExtensionTemplate(1) { t
 InputMethodManager::~InputMethodManager() { this->destroy(); }
 
 InputMethodManager* InputMethodManager::instance() {
-	static auto instance = std::unique_ptr<InputMethodManager>(new InputMethodManager());
-	return instance.get();
+	// The OS should free this memory when we exit
+	static auto* instance = new InputMethodManager();
+	return instance;
 }
 
 namespace {
@@ -45,8 +46,9 @@ VirtualKeyboardManager::VirtualKeyboardManager(): QWaylandClientExtensionTemplat
 }
 
 VirtualKeyboardManager* VirtualKeyboardManager::instance() {
-	static auto instance = std::unique_ptr<VirtualKeyboardManager>(new VirtualKeyboardManager());
-	return instance.get();
+	// The OS should free this memory when we exit
+	static auto* instance = new VirtualKeyboardManager();
+	return instance;
 }
 
 std::unique_ptr<VirtualKeyboardHandle>

src/wayland/input_method/qml.hpp

@@ -34,9 +34,11 @@ class KeyboardDirectionKey: public QObject {
 	static Enum fromDirection(impl::DirectionKey direction);
 };
 
+/// Provides keyboard handling logic for an @@InputMethod$'s grab protocol.
+/// Use @@KeyboardTextEdit$ for a higher level and easier to use version.
 class Keyboard: public QObject {
 	Q_OBJECT;
-	/// The surface that will be created for the keyboard. Must create a @@KeyboardSurface$.
+	/// TODO The surface that will be created for the keyboard. Must create a @@KeyboardSurface$.
 	// Q_PROPERTY(QQmlComponent* surface READ surfaceComponent WRITE setSurfaceComponent NOTIFY surfaceComponentChanged);
 	// Q_CLASSINFO("DefaultProperty", "surface");
 	QML_ELEMENT;
@@ -49,6 +51,7 @@ class Keyboard: public QObject {
 signals:
 	void keyPress(QChar character);
 	void returnPress();
+	/// Note that internally Quickshell will release the keyboard when escape is pressed.
 	void escapePress();
 	void directionPress(KeyboardDirectionKey::Enum);
 	void backspacePress();
@@ -62,16 +65,36 @@ private slots:
 	// QQmlComponent* mSurfaceComponent = nullptr;
 };
 
+/// Provides the ability to send text input to the compositor
+///
+/// A simple example that sends text to the currently focused input method:
+/// ```
+/// QSInputMethod {
+///   id: input_method
+/// }
+/// IpcHandler {
+///   target: "input_method"
+///   function hi(): void { input_method.sendString("hi"); }
+/// }
+/// ```
+/// We can now call the ipc handler and see that `hi` is printed to the terminal input.
+/// `$ qs ipc call input_method hi`
 class InputMethod: public QObject {
 	Q_OBJECT;
+	/// If a text input is focused
 	Q_PROPERTY(bool active READ isActive NOTIFY activeChanged);
+	/// Is false if another input method is already registered to the compositor, otherwise is true
 	Q_PROPERTY(bool hasInput READ hasInput NOTIFY hasInputChanged);
+	/// If the input method has grabbed the keyboard
 	Q_PROPERTY(bool hasKeyboard READ hasKeyboard NOTIFY hasKeyboardChanged);
+	/// TODO(cmurtagh-lgtm)
 	Q_PROPERTY(
 	    bool clearPreeditOnKeyboardRelease MEMBER mClearPreeditOnKeyboardRelease NOTIFY
 	        clearPreeditOnKeyboardReleaseChanged
 	);
 	// Q_PROPERTY(QString preedit)
+	/// The @@Keyboard$ that will handle the grabbed keyboard.
+	/// Use @@KeyboardTextEdit$ for most cases.
 	Q_PROPERTY(
 	    QQmlComponent* keyboard READ keyboardComponent WRITE setKeyboardComponent NOTIFY
 	        keyboardComponentChanged
@@ -82,22 +105,39 @@ class InputMethod: public QObject {
 public:
 	explicit InputMethod(QObject* parent = nullptr);
 
+	/// Sends a string to the text input currently focused
 	Q_INVOKABLE void sendString(const QString& text);
+	/// Provides virtual text in the text input so the user can visualise what they write
+	/// This will override any previous preedit text
+	/// If `cursorBegin == cursorEnd == -1` the text input will not show a cursor
+	/// If `cursorBegin == cursorEnd == n` the text input will show a cursor at n
+	/// If `cursorBegin == n` and `cursorEnd == m` the text from n to m will be highlighted
 	Q_INVOKABLE void
 	sendPreeditString(const QString& text, int32_t cursorBegin = -1, int32_t cursorEnd = -1);
+	/// Removes text before the cursor by `before` and after by `after`.
+	/// If preedit text is present, then text will be deleted before the preedit text and after the preedit text instead of the cursor.
 	Q_INVOKABLE void deleteText(int before = 1, int after = 0);
 
+	/// If there is a focused text input that we can write to
 	Q_INVOKABLE [[nodiscard]] bool isActive() const;
 
+	/// @@keyboard$
 	Q_INVOKABLE [[nodiscard]] QQmlComponent* keyboardComponent() const;
+	/// @@keyboard$
 	Q_INVOKABLE void setKeyboardComponent(QQmlComponent* keyboardComponent);
 
+	/// @@hasInput$
 	Q_INVOKABLE [[nodiscard]] bool hasInput() const;
+	/// Retries getting the input method.
 	Q_INVOKABLE void getInput();
+	/// Releases the input method so another program can use it.
 	Q_INVOKABLE void releaseInput();
 
+	/// @@hasKeyboard$
 	Q_INVOKABLE [[nodiscard]] bool hasKeyboard() const;
+	/// Grabs the current keyboard so the input can be intercepted by the @@keyboard$ object
 	Q_INVOKABLE void grabKeyboard();
+	/// Releases the grabbed keyboard so it can be used normally.
 	Q_INVOKABLE void releaseKeyboard();
 
 signals:

src/wayland/input_method/qml_helpers.hpp

@@ -8,10 +8,39 @@
 
 namespace qs::wayland::input_method {
 
+/// A keyboard handler for @@InputMethod$'s keyboard grab protocol.
+///
+/// As text is typed on the keyboard this will be displayed in the input method as virtual/preedit text.
+/// A cursor enables some control over the composition of the text.
+/// When return is pressed the transform function is called and the returned string is sent to the input text
+/// and the keyboard is released.
+/// 
+/// ```
+/// QSInputMethod {
+///   id: input_method
+///   KeyboardTextEdit {
+///     transform: function (text: string): string {
+///       return {
+///           "cool": "😎"
+///           // etc.
+///       }[text];
+///     }
+///   }
+/// }
+/// IpcHandler {
+///   target: "emoji"
+///   function get(): void { input_method.grabKeyboard(); }
+/// }
+/// ```
+///
+/// If you need a lower level view of the key events use @@Keyboard$.
 class KeyboardTextEdit: public Keyboard {
 	Q_OBJECT;
+	/// A function that has a string parameter and returns a string.
 	Q_PROPERTY(QJSValue transform READ transform WRITE setTransform NOTIFY transformChanged FINAL)
+	/// The position of the cursor within the @@editText$.
 	Q_PROPERTY(int cursor MEMBER mCursor READ cursor WRITE setCursor NOTIFY cursorChanged);
+	/// The text that is currently being edited and displayed.
 	Q_PROPERTY(
 	    QString editText MEMBER mEditText READ editText WRITE setEditText NOTIFY editTextChanged
 	);