From 32865922bafc968d8195a6f840e6a366ef999ad5 Mon Sep 17 00:00:00 2001 From: CopyQ Date: Fri, 6 Mar 2026 06:55:58 +0100 Subject: [PATCH 1/2] Ignore com.github.hluk.copyq.desktop.in in codespell --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 68728b1a97..a0cf2f6370 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,6 +4,7 @@ skip = [ '*.svg', './build/', './plugins/itemfakevim/fakevim', + './shared/com.github.hluk.copyq.desktop.in', './shared/gpl-3.0.rtf', './src/gui/icon_list.h', './src/platform/x11/systemclipboard/wlr-data-control-unstable-v1.xml', From 1d86801c8f8353af6d0111928b14d739041903c7 Mon Sep 17 00:00:00 2001 From: Lukas Holecek Date: Tue, 3 Mar 2026 08:03:08 +0000 Subject: [PATCH 2/2] docs: clarify copySelection() and primary selection documentation Rewrite copySelection() overload descriptions to be brief and refer to the Primary Selection section for details. Use the term "primary selection" consistently instead of "Linux mouse selection". Rename the "Linux Mouse Selection" section to "Primary Selection": the feature is not specific to Linux (BSD is also supported) and is not limited to mouse input. Rewrite the Primary Selection section to: - Acknowledge BSD in addition to Linux. - Note that the feature works on both X11 and Wayland. - Document that Wayland support depends on the compositor and the KGuiAddons library. - Mention that GNOME does not support it natively, but CopyQ 14.0.0+ works around this via the bundled CopyQ Clipboard Monitor extension. Update all cross-references in scripting-api.rst and commands-script.rst. Regenerate src/gui/commandcompleterdocumentation.h via utils/script_docs_to_cpp.py. Based-on-patch-by: Chealer Resolves: https://github.com/hluk/CopyQ/issues/3437 Assisted-by: Claude (Anthropic) --- docs/commands-script.rst | 2 +- docs/scripting-api.rst | 90 ++++++++++++++++++------- src/gui/commandcompleterdocumentation.h | 28 ++++---- 3 files changed, 81 insertions(+), 39 deletions(-) diff --git a/docs/commands-script.rst b/docs/commands-script.rst index 162202af03..7990e8c0bd 100644 --- a/docs/commands-script.rst +++ b/docs/commands-script.rst @@ -73,7 +73,7 @@ pasting clipboard: throw 'Failed to run xdotool: ' + str(x.stderr) } -E.g. show custom notifications for clipboard and Linux mouse selection changes. +E.g. show custom notifications for clipboard and primary selection changes. .. code-block:: js diff --git a/docs/scripting-api.rst b/docs/scripting-api.rst index 9e1cc123c3..4b4f799bf7 100644 --- a/docs/scripting-api.rst +++ b/docs/scripting-api.rst @@ -264,7 +264,7 @@ unlike in GUI, where row numbers start from 1 by default. .. js:function:: selection([mimeType]) - Same as :js:func:`clipboard` for `Linux mouse selection`_. + Same as :js:func:`clipboard` for `primary selection`_. :returns: Selection data. :rtype: :js:class:`ByteArray` @@ -278,7 +278,7 @@ unlike in GUI, where row numbers start from 1 by default. .. js:function:: hasSelectionFormat(mimeType) - Same as :js:func:`hasClipboardFormat` for `Linux mouse selection`_. + Same as :js:func:`hasClipboardFormat` for `primary selection`_. :returns: ``true`` if selection contains the format, otherwise ``false``. :rtype: bool @@ -288,7 +288,7 @@ unlike in GUI, where row numbers start from 1 by default. Returns true only in automatic command triggered by clipboard change. This can be used to check if current automatic command was triggered by - clipboard and not `Linux mouse selection`_ change. + clipboard and not `primary selection`_ change. :returns: ``true`` if current automatic command is triggered by clipboard change, otherwise ``false``. @@ -363,22 +363,25 @@ unlike in GUI, where row numbers start from 1 by default. .. js:function:: copySelection(text) - Equivalent to the ``copy`` function with the same arguments, but for `Linux - mouse selection`_. + Sets primary selection plain text. + + Equivalent to ``copy(text)`` but for `primary selection`_. :throws Error: Thrown if selection fails to be set. .. js:function:: /*data*/ copySelection(mimeType, data, [mimeType, data]...) - Equivalent to the ``copy`` function with the same arguments, but for `Linux - mouse selection`_. + Sets primary selection data. + + Equivalent to ``copy(mimeType, data, ...)`` but for `primary selection`_. :throws Error: Thrown if selection fails to be set. .. js:function:: /*item*/ copySelection(Item) - Equivalent to the ``copy`` function with the same arguments, but for `Linux - mouse selection`_. + Sets primary selection from an item. + + Equivalent to ``copy(Item)`` but for `primary selection`_. :throws Error: Thrown if selection fails to be set. @@ -1497,7 +1500,7 @@ unlike in GUI, where row numbers start from 1 by default. .. js:function:: onClipboardChanged() - Called when clipboard or `Linux mouse selection`_ changes and is not set by + Called when clipboard or `primary selection`_ changes and is not set by CopyQ, is not marked as hidden nor secret (see the other callbacks). Default implementation is: @@ -1515,7 +1518,7 @@ unlike in GUI, where row numbers start from 1 by default. .. js:function:: onOwnClipboardChanged() - Called when clipboard or `Linux mouse selection`_ is set by CopyQ and is not + Called when clipboard or `primary selection`_ is set by CopyQ and is not marked as hidden nor secret (see the other callbacks). Owned clipboard data contains :js:data:`mimeOwner` format. @@ -1524,7 +1527,7 @@ unlike in GUI, where row numbers start from 1 by default. .. js:function:: onHiddenClipboardChanged() - Called when clipboard or `Linux mouse selection`_ changes and is marked as + Called when clipboard or `primary selection`_ changes and is marked as hidden but not secret (see the other callbacks). Hidden clipboard data contains :js:data:`mimeHidden` format set to ``1``. @@ -1533,7 +1536,7 @@ unlike in GUI, where row numbers start from 1 by default. .. js:function:: onSecretClipboardChanged() - Called if the clipboard or `Linux mouse selection`_ changes and contains a + Called if the clipboard or `primary selection`_ changes and contains a password or other secret (for example, copied from clipboard manager). The default implementation clears all data, so they are not accessible using @@ -1548,7 +1551,7 @@ unlike in GUI, where row numbers start from 1 by default. .. js:function:: onClipboardUnchanged() - Called when clipboard or `Linux mouse selection`_ changes but data remained the same. + Called when clipboard or `primary selection`_ changes but data remained the same. Default implementation does nothing. @@ -1610,7 +1613,7 @@ unlike in GUI, where row numbers start from 1 by default. .. js:function:: synchronizeToSelection(text) - Synchronize current data from clipboard to `Linux mouse selection`_. + Synchronize current data from clipboard to `primary selection`_. Called automatically from clipboard monitor process if option ``copy_clipboard`` is enabled. @@ -1619,7 +1622,7 @@ unlike in GUI, where row numbers start from 1 by default. .. js:function:: synchronizeFromSelection(text) - Synchronize current data from `Linux mouse selection`_ to clipboard. + Synchronize current data from `primary selection`_ to clipboard. Called automatically from clipboard monitor process if option ``copy_selection`` is enabled. @@ -1636,7 +1639,7 @@ unlike in GUI, where row numbers start from 1 by default. .. js:function:: provideSelection() - Starts a process that provides a data for `Linux mouse selection`_. + Starts a process that provides a data for `primary selection`_. The data can be set using :js:func:`setData`. @@ -2291,7 +2294,7 @@ These MIME types values are assigned to global variables prefixed with .. js:data:: mimeClipboardMode - Contains ``selection`` if data is from `Linux mouse selection`_. Value: 'application/x-copyq-clipboard-mode'. + Contains ``selection`` if data is from `primary selection`_. Value: 'application/x-copyq-clipboard-mode'. .. js:data:: mimeCurrentTab @@ -2397,18 +2400,57 @@ for item data. For example ``selectedItems()`` returning ``[0,1]`` will return If tab is renamed, all references to current and selected items are invalidated because the tab data need to be initiated again. -Linux Mouse Selection ---------------------- +Primary Selection +----------------- -In many application on Linux, if you select a text with mouse, it's possible to -paste it with middle mouse button. +On many Linux and BSD desktop environments, selecting text with the mouse +places it in the *primary selection*, which can be pasted with a middle mouse +button click. This is separate from the regular clipboard used by copy/paste +shortcuts. -The text is stored separately from normal clipboard content. +CopyQ supports reading and writing the primary selection on platforms that +provide it (X11 and Wayland). On Wayland, support depends on the compositor +and the `KGuiAddons `_ library; +notably, GNOME does not support it natively, but CopyQ 14.0.0 and later work +around this via the bundled *CopyQ Clipboard Monitor* GNOME extension. -On non-Linux system, functions that support mouse selection will do nothing +On unsupported platforms, functions that use the primary selection do nothing (for example :js:func:`copySelection`) or return ``undefined`` (in case of :js:func:`selection`). +CopyQ can synchronize the clipboard with the primary selection. This can be +enabled in Preferences on the General tab under *Clipboard Manipulation*, or +from the command line: + +.. code-block:: js + + config('copy_clipboard', 'true') // clipboard to primary selection + config('copy_selection', 'true') // primary selection to clipboard + +For synchronization, CopyQ runs a helper process (for example +``copyq --clipboard-access synchronizeToSelection``). Running helpers can be +inspected from *File — Process Manager*. + +Custom automatic commands run on primary selection changes by default. This +can be disabled in the *Clipboard Manipulation* section or from the command +line: + +.. code-block:: js + + config('run_selection', 'false') + +CopyQ can also store primary selection data automatically. Enable it in the +*Clipboard Manipulation* section or from the command line: + +.. code-block:: js + + config('check_selection', 'true') + +See also: + +- `QClipboard — Notes for X11 Users `_ +- `freedesktop.org Clipboards Wiki `_ + Plugins ------- diff --git a/src/gui/commandcompleterdocumentation.h b/src/gui/commandcompleterdocumentation.h index 74e3d4dea6..f03c771191 100644 --- a/src/gui/commandcompleterdocumentation.h +++ b/src/gui/commandcompleterdocumentation.h @@ -28,17 +28,17 @@ void addDocumentation(AddDocumentationCallback addDocumentation) addDocumentation("filter", "filter(filterText)", "Sets text for filtering items in main window."); addDocumentation("ignore", "ignore()", "Ignores current clipboard content (used for automatic commands)."); addDocumentation("clipboard", "clipboard([mimeType]) -> `ByteArray`", "Returns clipboard data for MIME type (default is text)."); - addDocumentation("selection", "selection([mimeType]) -> `ByteArray`", "Same as `clipboard()` for `Linux mouse selection`_."); + addDocumentation("selection", "selection([mimeType]) -> `ByteArray`", "Same as `clipboard()` for `primary selection`_."); addDocumentation("hasClipboardFormat", "hasClipboardFormat(mimeType) -> bool", "Returns true only if clipboard contains MIME type."); - addDocumentation("hasSelectionFormat", "hasSelectionFormat(mimeType) -> bool", "Same as `hasClipboardFormat()` for `Linux mouse selection`_."); + addDocumentation("hasSelectionFormat", "hasSelectionFormat(mimeType) -> bool", "Same as `hasClipboardFormat()` for `primary selection`_."); addDocumentation("isClipboard", "isClipboard() -> bool", "Returns true only in automatic command triggered by clipboard change."); addDocumentation("copy", "copy(text)", "Sets clipboard plain text."); addDocumentation("copy", "copy(mimeType, data, [mimeType, data]...)", "Sets clipboard data."); addDocumentation("copy", "copy(Item)", "Function override with an item argument."); addDocumentation("copy", "copy()", "Sends `Ctrl+C` to the current application or window to trigger a copy operation."); - addDocumentation("copySelection", "copySelection(text)", "Equivalent to the `copy` function with the same arguments, but for `Linux mouse selection`_."); - addDocumentation("copySelection", "copySelection(mimeType, data, [mimeType, data]...)", "Equivalent to the `copy` function with the same arguments, but for `Linux mouse selection`_."); - addDocumentation("copySelection", "copySelection(Item)", "Equivalent to the `copy` function with the same arguments, but for `Linux mouse selection`_."); + addDocumentation("copySelection", "copySelection(text)", "Sets primary selection plain text."); + addDocumentation("copySelection", "copySelection(mimeType, data, [mimeType, data]...)", "Sets primary selection data."); + addDocumentation("copySelection", "copySelection(Item)", "Sets primary selection from an item."); addDocumentation("paste", "paste()", "Sends `Shift+Insert` (or `Ctrl+V`) to the current application or window to trigger a paste operation."); addDocumentation("tab", "tab() -> array of strings", "Returns tab names."); addDocumentation("tab", "tab(tabName)", "Sets current tab for the script."); @@ -157,11 +157,11 @@ void addDocumentation(AddDocumentationCallback addDocumentation) addDocumentation("iconTagColor", "iconTagColor() -> string", "Get current tray and window tag color name."); addDocumentation("iconTagColor", "iconTagColor(colorName)", "Set current tray and window tag color name."); addDocumentation("loadTheme", "loadTheme(path)", "Loads theme from an INI file."); - addDocumentation("onClipboardChanged", "onClipboardChanged()", "Called when clipboard or `Linux mouse selection`_ changes and is not set by CopyQ, is not marked as hidden nor secret (see the other callbacks)."); - addDocumentation("onOwnClipboardChanged", "onOwnClipboardChanged()", "Called when clipboard or `Linux mouse selection`_ is set by CopyQ and is not marked as hidden nor secret (see the other callbacks)."); - addDocumentation("onHiddenClipboardChanged", "onHiddenClipboardChanged()", "Called when clipboard or `Linux mouse selection`_ changes and is marked as hidden but not secret (see the other callbacks)."); - addDocumentation("onSecretClipboardChanged", "onSecretClipboardChanged()", "Called if the clipboard or `Linux mouse selection`_ changes and contains a password or other secret (for example, copied from clipboard manager)."); - addDocumentation("onClipboardUnchanged", "onClipboardUnchanged()", "Called when clipboard or `Linux mouse selection`_ changes but data remained the same."); + addDocumentation("onClipboardChanged", "onClipboardChanged()", "Called when clipboard or `primary selection`_ changes and is not set by CopyQ, is not marked as hidden nor secret (see the other callbacks)."); + addDocumentation("onOwnClipboardChanged", "onOwnClipboardChanged()", "Called when clipboard or `primary selection`_ is set by CopyQ and is not marked as hidden nor secret (see the other callbacks)."); + addDocumentation("onHiddenClipboardChanged", "onHiddenClipboardChanged()", "Called when clipboard or `primary selection`_ changes and is marked as hidden but not secret (see the other callbacks)."); + addDocumentation("onSecretClipboardChanged", "onSecretClipboardChanged()", "Called if the clipboard or `primary selection`_ changes and contains a password or other secret (for example, copied from clipboard manager)."); + addDocumentation("onClipboardUnchanged", "onClipboardUnchanged()", "Called when clipboard or `primary selection`_ changes but data remained the same."); addDocumentation("onStart", "onStart()", "Called when application starts."); addDocumentation("onExit", "onExit()", "Called just before application exists."); addDocumentation("runAutomaticCommands", "runAutomaticCommands() -> bool", "Executes automatic commands on current data."); @@ -169,10 +169,10 @@ void addDocumentation(AddDocumentationCallback addDocumentation) addDocumentation("updateTitle", "updateTitle()", "Update main window title and tool tip from current data."); addDocumentation("updateClipboardData", "updateClipboardData()", "Sets current clipboard data for tray menu, window title and notification."); addDocumentation("setTitle", "setTitle([title])", "Set main window title and tool tip."); - addDocumentation("synchronizeToSelection", "synchronizeToSelection(text)", "Synchronize current data from clipboard to `Linux mouse selection`_."); - addDocumentation("synchronizeFromSelection", "synchronizeFromSelection(text)", "Synchronize current data from `Linux mouse selection`_ to clipboard."); + addDocumentation("synchronizeToSelection", "synchronizeToSelection(text)", "Synchronize current data from clipboard to `primary selection`_."); + addDocumentation("synchronizeFromSelection", "synchronizeFromSelection(text)", "Synchronize current data from `primary selection`_ to clipboard."); addDocumentation("provideClipboard", "provideClipboard()", "Starts a process provides a data for clipboard."); - addDocumentation("provideSelection", "provideSelection()", "Starts a process that provides a data for `Linux mouse selection`_."); + addDocumentation("provideSelection", "provideSelection()", "Starts a process that provides a data for `primary selection`_."); addDocumentation("monitorClipboard", "monitorClipboard()", "Starts a clipboard monitor process."); addDocumentation("clipboardFormatsToSave", "clipboardFormatsToSave() -> array of strings", "Returns list of clipboard format to save automatically."); addDocumentation("saveData", "saveData()", "Save current data (depends on `mimeOutputTab`)."); @@ -208,7 +208,7 @@ void addDocumentation(AddDocumentationCallback addDocumentation) addDocumentation("mimeItemNotes", "mimeItemNotes", "Data contains notes for item. Value: 'application/x-copyq-item-notes'."); addDocumentation("mimeIcon", "mimeIcon", "Data contains icon for item. Value: 'application/x-copyq-item-icon'."); addDocumentation("mimeOwner", "mimeOwner", "If available, the clipboard was set from CopyQ (from script or copied items). Value: 'application/x-copyq-owner'."); - addDocumentation("mimeClipboardMode", "mimeClipboardMode", "Contains `selection` if data is from `Linux mouse selection`_. Value: 'application/x-copyq-clipboard-mode'."); + addDocumentation("mimeClipboardMode", "mimeClipboardMode", "Contains `selection` if data is from `primary selection`_. Value: 'application/x-copyq-clipboard-mode'."); addDocumentation("mimeCurrentTab", "mimeCurrentTab", "Current tab name when invoking command from main window. Value: 'application/x-copyq-current-tab'."); addDocumentation("mimeSelectedItems", "mimeSelectedItems", "Selected items when invoking command from main window. Value: 'application/x-copyq-selected-items'."); addDocumentation("mimeCurrentItem", "mimeCurrentItem", "Current item when invoking command from main window. Value: 'application/x-copyq-current-item'.");