Skip to content

docs: clarify copySelection() and Linux mouse selection documentation #3459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hluk wants to merge 2 commits into
base: master
Choose a base branch
from
+82 −39
Open

docs: clarify copySelection() and Linux mouse selection documentation #3459

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3286592
Ignore com.github.hluk.copyq.desktop.in in codespell
Mar 6, 2026
1d86801
docs: clarify copySelection() and primary selection documentation
hluk Mar 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/commands-script.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
90 changes: 66 additions & 24 deletions docs/scripting-api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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
Expand All @@ -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``.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:
Expand All @@ -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.
Expand All @@ -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``.
Expand All @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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`.

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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 <https://invent.kde.org/frameworks/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 <https://doc.qt.io/qt-6/qclipboard.html#notes-for-x11-users>`_
- `freedesktop.org Clipboards Wiki <https://www.freedesktop.org/wiki/Specifications/ClipboardsWiki/>`_

Plugins
-------

Expand Down
1 change: 1 addition & 0 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
28 changes: 14 additions & 14 deletions src/gui/commandcompleterdocumentation.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.");
Expand Down Expand Up @@ -157,22 +157,22 @@ 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.");
addDocumentation("clearClipboardData", "clearClipboardData()", "Clear clipboard visibility in GUI.");
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`).");
Expand Down Expand Up @@ -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'.");
Expand Down
Loading