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/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', 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'.");