1.. _scripting-api: 2 3Scripting API 4============= 5 6CopyQ provides scripting capabilities to automatically handle clipboard 7changes, organize items, change settings and much more. 8 9Supported language features and base function can be found at `ECMAScript 10Reference <http://doc.qt.io/qt-5/ecmascript.html>`__. 11 12CopyQ-specific features described in this document: 13 14- `Functions`_ 15- `Types`_ 16- `Objects`_ 17- `MIME types`_ 18- `Plugins`_ 19 20.. note:: 21 22 These terms are equivalent: format, MIME type, media type 23 24Execute Script 25-------------- 26 27The scripts can be executed from: 28 29a. Action or Command dialogs (F5, F6 shortcuts), if 30 the first line starts with ``copyq:`` 31b. command line as ``copyq eval '<SCRIPT>'`` 32c. command line as ``cat script.js | copyq eval -`` 33d. command line as 34 ``copyq <SCRIPT_FUNCTION> <FUNCTION_ARGUMENT_1> <FUNCTION_ARGUMENT_2> ...`` 35 36When run from command line, result of last expression is printed on 37stdout. 38 39Command exit values are: 40 41- 0 - script finished without error 42- 1 - :js:func:`fail` was called 43- 2 - bad syntax 44- 3 - exception was thrown 45 46Command Line 47------------ 48 49If number of arguments that can be passed to function is limited you can 50use 51 52.. code-block:: bash 53 54 copyq <FUNCTION1> <FUNCTION1_ARGUMENT_1> <FUNCTION1_ARGUMENT_2> \ 55 <FUNCTION2> <FUNCTION2_ARGUMENT> \ 56 <FUNCTION3> <FUNCTION3_ARGUMENTS> ... 57 58where ``<FUNCTION1>`` and ``<FUNCTION2>`` are scripts where result of 59last expression is functions that take two and one arguments 60respectively. 61 62Example: 63 64.. code-block:: bash 65 66 copyq tab clipboard separator "," read 0 1 2 67 68After :js:func:`eval` no arguments are treated as functions since it can access 69all arguments. 70 71Arguments recognize escape sequences ``\n`` (new line), ``\t`` 72(tabulator character) and ``\\`` (backslash). 73 74Argument ``-e`` is identical to :js:func:`eval`. 75 76Argument ``-`` is replaced with data read from stdin. 77 78Argument ``--`` is skipped and all the remaining arguments are 79interpreted as they are (escape sequences are ignored and ``-e``, ``-``, 80``--`` are left unchanged). 81 82Functions 83--------- 84 85Argument list parts ``...`` and ``[...]`` are optional and can be 86omitted. 87 88Comment `/*set*/` in function declaration indicates a specific function 89overload. 90 91Item **row** values in scripts always **start from 0** (like array index), 92unlike in GUI, where row numbers start from 1 by default. 93 94.. js:function:: version() 95 96 Returns version string. 97 98 :returns: Version string. 99 :rtype: string 100 101 Example of the version string:: 102 103 CopyQ Clipboard Manager v4.0.0-19-g93d95a7f 104 Qt: 5.15.2 105 KNotifications: 5.79.0 106 Compiler: GCC 107 Arch: x86_64-little_endian-lp64 108 OS: Fedora 33 (Workstation Edition) 109 110.. js:function:: help() 111 112 Returns help string. 113 114 :returns: Help string. 115 :rtype: string 116 117.. js:function:: /*search*/ help(searchString, ...) 118 119 Returns help for matched commands. 120 121 :returns: Help string. 122 :rtype: string 123 124.. js:function:: show() 125 126 Shows main window. 127 128.. js:function:: /*tab*/ show(tabName) 129 130 Shows tab. 131 132.. js:function:: showAt(x, y, [width, height]) 133 134 Shows main window with given geometry. 135 136.. js:function:: /*cursor*/ showAt() 137 138 Shows main window under mouse cursor. 139 140.. js:function:: /*tab*/ showAt(x, y, width, height, tabName) 141 142 Shows tab with given geometry. 143 144.. js:function:: hide() 145 146 Hides main window. 147 148.. js:function:: toggle() 149 150 Shows or hides main window. 151 152 :returns: ``true`` only if main window is being shown, otherwise ``false``. 153 :rtype: bool 154 155.. js:function:: menu() 156 157 Opens context menu. 158 159.. js:function:: /*tab*/ menu(tabName, [maxItemCount, [x, y]]) 160 161 Shows context menu for given tab. 162 163 This menu doesn't show clipboard and doesn't have any special actions. 164 165 Second argument is optional maximum number of items. The default value 166 same as for tray (i.e. value of ``config('tray_items')``). 167 168 Optional arguments x, y are coordinates in pixels on screen where menu 169 should show up. By default menu shows up under the mouse cursor. 170 171.. js:function:: exit() 172 173 Exits server. 174 175.. js:function:: disable() 176 enable() 177 178 Disables or enables clipboard content storing. 179 180.. js:function:: monitoring() 181 182 Returns true only if clipboard storing is enabled. 183 184 :returns: ``true`` if clipboard storing is enabled, otherwise ``false``. 185 :rtype: bool 186 187.. js:function:: visible() 188 189 Returns true only if main window is visible. 190 191 :returns: ``true`` if main window is visible, otherwise ``false``. 192 :rtype: bool 193 194.. js:function:: focused() 195 196 Returns true only if main window has focus. 197 198 :returns: ``true`` if main window has focus, otherwise ``false``. 199 :rtype: bool 200 201.. js:function:: focusPrevious() 202 203 Activates window that was focused before the main window. 204 205 :throws Error: Thrown if previous window cannot be activated. 206 207.. js:function:: preview([true|false]) 208 209 Shows/hides item preview and returns true only if preview was visible. 210 211 Example -- toggle the preview: 212 213 .. code-block:: js 214 215 preview(false) || preview(true) 216 217.. js:function:: filter() 218 219 Returns the current text for filtering items in main window. 220 221 :returns: Current filter. 222 :rtype: string 223 224.. js:function:: /*set*/ filter(filterText) 225 226 Sets text for filtering items in main window. 227 228.. js:function:: ignore() 229 230 Ignores current clipboard content (used for automatic commands). 231 232 This does all of the below. 233 234 - Skips any next automatic commands. 235 - Omits changing window title and tray tool tip. 236 - Won't store content in clipboard tab. 237 238.. js:function:: clipboard([mimeType]) 239 240 Returns clipboard data for MIME type (default is text). 241 242 Pass argument ``"?"`` to list available MIME types. 243 244 :returns: Clipboard data. 245 :rtype: :js:class:`ByteArray` 246 247.. js:function:: selection([mimeType]) 248 249 Same as :js:func:`clipboard` for `Linux mouse selection`_. 250 251 :returns: Selection data. 252 :rtype: :js:class:`ByteArray` 253 254.. js:function:: hasClipboardFormat(mimeType) 255 256 Returns true only if clipboard contains MIME type. 257 258 :returns: ``true`` if clipboad contans the format, otherwise ``false``. 259 :rtype: bool 260 261.. js:function:: hasSelectionFormat(mimeType) 262 263 Same as :js:func:`hasClipboardFormat` for `Linux mouse selection`_. 264 265 :returns: ``true`` if selection contans the format, otherwise ``false``. 266 :rtype: bool 267 268.. js:function:: isClipboard() 269 270 Returns true only in automatic command triggered by clipboard change. 271 272 This can be used to check if current automatic command was triggered by 273 clipboard and not `Linux mouse selection`_ change. 274 275 :returns: ``true`` if current automatic command is triggered by clipboard 276 change, otherwise ``false``. 277 :rtype: bool 278 279.. js:function:: copy(text) 280 281 Sets clipboard plain text. 282 283 Same as ``copy(mimeText, text)``. 284 285 :throws Error: Thrown if clipboard fails to be set. 286 287.. js:function:: /*data*/ copy(mimeType, data, [mimeType, data]...) 288 289 Sets clipboard data. 290 291 This also sets :js:data:`mimeOwner` format so automatic commands are not run 292 on the new data and it's not stored in clipboard tab. 293 294 All other data formats are dropped from clipboard. 295 296 :throws Error: Thrown if clipboard fails to be set. 297 298 Example -- set both text and rich text: 299 300 .. code-block:: js 301 302 copy(mimeText, 'Hello, World!', 303 mimeHtml, '<p>Hello, World!</p>') 304 305.. js:function:: /*item*/ copy(Item) 306 307 Function override with an item argument. 308 309 :throws Error: Thrown if clipboard fails to be set. 310 311 Example -- set both text and rich text: 312 313 .. code-block:: js 314 315 var item = {} 316 item[mimeText] = 'Hello, World!' 317 item[mimeHtml] = '<p>Hello, World!</p>' 318 copy(item) 319 320.. js:function:: /*window*/ copy() 321 322 Sends ``Ctrl+C`` to current window. 323 324 :throws Error: Thrown if clipboard doesn't change (clipboard is reset before 325 sending the shortcut). 326 327 Example: 328 329 .. code-block:: js 330 331 try { 332 copy(arguments) 333 } catch (e) { 334 // Coping failed! 335 popup('Coping Failed', e) 336 abort() 337 } 338 var text = str(clipboard()) 339 popup('Copied Text', text) 340 341.. js:function:: copySelection(...) 342 343 Same as :js:func:`copy` for `Linux mouse selection`_. 344 345 There is no ``copySelection()`` without parameters. 346 347 :throws Error: Thrown if selection fails to be set. 348 349.. js:function:: paste() 350 351 Pastes current clipboard. 352 353 This is basically only sending ``Shift+Insert`` shortcut to current 354 window. 355 356 Correct functionality depends a lot on target application and window 357 manager. 358 359 :throws Error: Thrown if paste operation fails. 360 361 Example: 362 363 .. code-block:: js 364 365 try { 366 paste() 367 } catch (e) { 368 // Pasting failed! 369 popup('Pasting Failed', e) 370 abort() 371 } 372 popup('Pasting Successful') 373 374.. js:function:: tab() 375 376 Returns tab names. 377 378 :returns: Array with names of existing tab. 379 :rtype: array of strings 380 381.. js:function:: /*set*/ tab(tabName) 382 383 Sets current tab for the script. 384 385 Example -- select third item at index 2 from tab "Notes": 386 387 .. code-block:: js 388 389 tab('Notes') 390 select(2) 391 392.. js:function:: removeTab(tabName) 393 394 Removes tab. 395 396.. js:function:: renameTab(tabName, newTabName) 397 398 Renames tab. 399 400.. js:function:: tabIcon(tabName) 401 402 Returns path to icon for tab. 403 404 :returns: Path to icon for tab. 405 :rtype: string 406 407.. js:function:: /*set*/ tabIcon(tabName, iconPath) 408 409 Sets icon for tab. 410 411.. js:function:: unload([tabNames...]) 412 413 Unload tabs (i.e. items from memory). 414 415 If no tabs are specified, unloads all tabs. 416 417 If a tab is open and visible or has an editor open, it won't be unloaded. 418 419 :returns: Array of successfully unloaded tabs. 420 :rtype: array of strings 421 422.. js:function:: forceUnload([tabNames...]) 423 424 Force-unload tabs (i.e. items from memory). 425 426 If no tabs are specified, unloads all tabs. 427 428 Refresh button needs to be clicked to show the content of a force-unloaded 429 tab. 430 431 If a tab has an editor open, the editor will be closed first even if it has 432 unsaved changes. 433 434.. js:function:: count() 435 length() 436 size() 437 438 Returns amount of items in current tab. 439 440 :returns: Item count. 441 :rtype: int 442 443.. js:function:: select(row) 444 445 Copies item in the row to clipboard. 446 447 Additionally, moves selected item to top depending on settings. 448 449.. js:function:: next() 450 451 Copies next item from current tab to clipboard. 452 453.. js:function:: previous() 454 455 Copies previous item from current tab to clipboard. 456 457.. js:function:: add(text|Item...) 458 459 Same as ``insert(0, ...)``. 460 461.. js:function:: insert(row, text|Item...) 462 463 Inserts new items to current tab. 464 465 :throws Error: Thrown if space for the items cannot be allocated. 466 467.. js:function:: remove(row, ...) 468 469 Removes items in current tab. 470 471 :throws Error: Thrown if some items cannot be removed. 472 473.. js:function:: move(row) 474 475 Moves selected items to given row in same tab. 476 477.. js:function:: edit([row|text] ...) 478 479 Edits items in current tab. 480 481 Opens external editor if set, otherwise opens internal editor. 482 483.. js:function:: read([mimeType]) 484 485 Same as :js:func:`clipboard`. 486 487.. js:function:: /*row*/ read(mimeType, row, ...) 488 489 Returns concatenated data from items, or clipboard if row is negative. 490 491 Pass argument ``"?"`` to list available MIME types. 492 493 :returns: Concatenated data in the rows. 494 :rtype: :js:class:`ByteArray` 495 496.. js:function:: write(row, mimeType, data, [mimeType, data]...) 497 498 Inserts new item to current tab. 499 500 :throws Error: Thrown if space for the items cannot be allocated. 501 502.. js:function:: /*item*/ write(row, Item...) 503 504 Function override with one or more item arguments. 505 506.. js:function:: /*items*/ write(row, Item[]) 507 508 Function override with item list argument. 509 510.. js:function:: change(row, mimeType, data, [mimeType, data]...) 511 512 Changes data in item in current tab. 513 514 If data is ``undefined`` the format is removed from item. 515 516.. js:function:: /*item*/ change(row, Item...) 517 518 Function override with one or more item arguments. 519 520.. js:function:: /*items*/ change(row, Item[]) 521 522 Function override with item list argument. 523 524.. js:function:: separator() 525 526 Returns item separator (used when concatenating item data). 527 528 :returns: Current separator. 529 :rtype: string 530 531.. js:function:: /*set*/ separator(separator) 532 533 Sets item separator for concatenating item data. 534 535.. js:function:: action() 536 537 Opens action dialog. 538 539.. js:function:: /*row*/ action([rows, ...], command, [outputItemSeparator]) 540 541 Runs command for items in current tab. 542 543 If rows arguments is specified, ``%1`` in the command will be replaced with 544 concatenated text of the rows. 545 546 If no rows are specified, ``%1`` in the command will be replaced with 547 clipboard text. 548 549 The concatenated text (if rows are defined) or clipboard text is also passed 550 on standard input of the command. 551 552.. js:function:: popup(title, message, [time=8000]) 553 554 Shows popup message for given time in milliseconds. 555 556 If ``time`` argument is set to -1, the popup is hidden only after mouse 557 click. 558 559.. js:function:: notification(...) 560 561 Shows popup message with icon and buttons. 562 563 Each button can have script and data. 564 565 If button is clicked the notification is hidden and script is executed 566 with the data passed as stdin. 567 568 The function returns immediately (doesn't wait on user input). 569 570 Special arguments: 571 572 - '.title' - notification title 573 - '.message' - notification message (can contain basic HTML) 574 - '.icon' - notification icon (path to image or font icon) 575 - '.id' - notification ID - this replaces notification with same ID 576 - '.time' - duration of notification in milliseconds (default is -1, 577 i.e. waits for mouse click) 578 - '.button' - adds button (three arguments: name, script and data) 579 580 Example: 581 582 .. code-block:: js 583 584 notification( 585 '.title', 'Example', 586 '.message', 'Notification with button', 587 '.button', 'Cancel', '', '', 588 '.button', 'OK', 'copyq:popup(input())', 'OK Clicked' 589 ) 590 591.. js:function:: exportTab(fileName) 592 593 Exports current tab into file. 594 595 :throws Error: Thrown if export fails. 596 597.. js:function:: importTab(fileName) 598 599 Imports items from file to a new tab. 600 601 :throws Error: Thrown if import fails. 602 603.. js:function:: exportData(fileName) 604 605 Exports all tabs and configuration into file. 606 607 :throws Error: Thrown if export fails. 608 609.. js:function:: importData(fileName) 610 611 Imports all tabs and configuration from file. 612 613 :throws Error: Thrown if import fails. 614 615.. js:function:: config() 616 617 Returns help with list of available application options. 618 619 Users can change most of these options via the CopyQ GUI, mainly via 620 the "Preferences" window. 621 622 These options are persisted within the ``[Options]`` section of a corresponding 623 ``copyq.ini`` or ``copyq.conf`` file (``copyq.ini`` is used on Windows). 624 625 :returns: Available options. 626 :rtype: string 627 628.. js:function:: /*get*/ config(optionName) 629 630 Returns value of given application option. 631 632 :returns: Current value of the option. 633 :rtype: string 634 :throws Error: Thrown if the option is invalid. 635 636.. js:function:: /*set*/ config(optionName, value) 637 638 Sets application option and returns new value. 639 640 :returns: New value of the option. 641 :rtype: string 642 :throws Error: Thrown if the option is invalid. 643 644.. js:function:: /*set-more*/ config(optionName, value, ...) 645 646 Sets multiple application options and return list with values in format 647 ``optionName=newValue``. 648 649 :returns: New values of the options. 650 :rtype: string 651 :throws Error: Thrown if there is an invalid option in which case it won't set 652 any options. 653 654.. js:function:: toggleConfig(optionName) 655 656 Toggles an option (true to false and vice versa) and returns the new value. 657 658 :returns: New value of the option. 659 :rtype: bool 660 661.. js:function:: info([pathName]) 662 663 Returns paths and flags used by the application. 664 665 :returns: Path for given identifier. 666 :rtype: string 667 668 Example -- print path to the configuration file: 669 670 .. code-block:: js 671 672 info('config') 673 674.. js:function:: eval(script) 675 676 Evaluates script and returns result. 677 678 :returns: Result of the last expression. 679 680.. js:function:: source(fileName) 681 682 Evaluates script file and returns result of last expression in the script. 683 684 This is useful to move some common code out of commands. 685 686 :returns: Result of the last expression. 687 688 .. code-block:: js 689 690 // File: c:/copyq/replace_clipboard_text.js 691 replaceClipboardText = function(replaceWhat, replaceWith) 692 { 693 var text = str(clipboard()) 694 var newText = text.replace(replaceWhat, replaceWith) 695 if (text != newText) 696 copy(newText) 697 } 698 699 .. code-block:: js 700 701 source('c:/copyq/replace_clipboard_text.js') 702 replaceClipboardText('secret', '*****') 703 704.. js:function:: currentPath() 705 706 Get current path. 707 708 :returns: Current path. 709 :rtype: string 710 711 .. code-block:: bash 712 713 cd /tmp 714 copyq currentPath 715 # Prints: /tmp 716 717.. js:function:: /*set*/ currentPath(path) 718 719 Set current path. 720 721.. js:function:: str(value) 722 723 Converts a value to string. 724 725 If ByteArray object is the argument, it assumes UTF8 encoding. To use 726 different encoding, use :js:func`toUnicode`. 727 728 :returns: Value as string. 729 :rtype: string 730 731.. js:function:: input() 732 733 Returns standard input passed to the script. 734 735 :returns: Data on stdin. 736 :rtype: :js:class:`ByteArray` 737 738.. js:function:: toUnicode(ByteArray) 739 740 Returns string for bytes with encoding detected by checking Byte Order Mark (BOM). 741 742 :returns: Value as string. 743 :rtype: string 744 745.. js:function:: /*encoding*/ toUnicode(ByteArray, encodingName) 746 747 Returns string for bytes with given encoding. 748 749 :returns: Value as string. 750 :rtype: string 751 752.. js:function:: fromUnicode(String, encodingName) 753 754 Returns encoded text. 755 756 :returns: Value as ByteArray. 757 :rtype: :js:class:`ByteArray` 758 759.. js:function:: data(mimeType) 760 761 Returns data for automatic commands or selected items. 762 763 If run from menu or using non-global shortcut the data are taken from 764 selected items. 765 766 If run for automatic command the data are clipboard content. 767 768 :returns: Data for the format. 769 :rtype: :js:class:`ByteArray` 770 771.. js:function:: setData(mimeType, data) 772 773 Modifies data for :js:func:`data` and new clipboard item. 774 775 Next automatic command will get updated data. 776 777 This is also the data used to create new item from clipboard. 778 779 :returns: ``true`` if data were set, ``false`` if parsing data failed (in 780 case of :js:data:`mimeItems`). 781 :rtype: bool 782 783 Example -- automatic command that adds a creation time data and tag to new 784 items: 785 786 :: 787 788 copyq: 789 var timeFormat = 'yyyy-MM-dd hh:mm:ss' 790 setData('application/x-copyq-user-copy-time', dateString(timeFormat)) 791 setData(mimeTags, 'copied: ' + time) 792 793 Example -- menu command that adds a tag to selected items: 794 795 :: 796 797 copyq: 798 setData('application/x-copyq-tags', 'Important') 799 800.. js:function:: removeData(mimeType) 801 802 Removes data for :js:func:`data` and new clipboard item. 803 804.. js:function:: dataFormats() 805 806 Returns formats available for :js:func:`data`. 807 808 :returns: Array of data formats. 809 :rtype: array of strings 810 811.. js:function:: print(value) 812 813 Prints value to standard output. 814 815.. js:function:: serverLog(value) 816 817 Prints value to application log. 818 819.. js:function:: logs() 820 821 Returns application logs. 822 823 :returns: Application logs. 824 :rtype: string 825 826.. js:function:: abort() 827 828 Aborts script evaluation. 829 830.. js:function:: fail() 831 832 Aborts script evaluation with nonzero exit code. 833 834.. js:function:: setCurrentTab(tabName) 835 836 Focus tab without showing main window. 837 838.. js:function:: selectItems(row, ...) 839 840 Selects items in current tab. 841 842.. js:function:: selectedTab() 843 844 Returns tab that was selected when script was executed. 845 846 :returns: Currently selected tab name, empty if called outside the main 847 window context (see `Selected Items`_). 848 :rtype: string 849 850.. js:function:: selectedItems() 851 852 Returns selected rows in current tab. 853 854 :returns: Currently selected rows, empty if called outside the main 855 window context (see `Selected Items`_). 856 :rtype: array of ints 857 858.. js:function:: selectedItemData(index) 859 860 Returns data for given selected item. 861 862 The data can empty if the item was removed during execution of the 863 script. 864 865 :returns: Currently selected items, empty if called outside the main 866 window context (see `Selected Items`_). 867 :rtype: array of :js:class:`Item` 868 869.. js:function:: setSelectedItemData(index, Item) 870 871 Set data for given selected item. 872 873 Returns false only if the data cannot be set, usually if item was 874 removed. 875 876 See `Selected Items`_. 877 878 :returns: ``true`` if data were set, otherwise ``false``. 879 :rtype: bool 880 881.. js:function:: selectedItemsData() 882 883 Returns data for all selected items. 884 885 Some data can be empty if the item was removed during execution of the 886 script. 887 888 :returns: Currently selected item data, empty if called outside the main 889 window context (see `Selected Items`_). 890 :rtype: array of :js:class:`Item` 891 892.. js:function:: setSelectedItemsData(Item[]) 893 894 Set data to all selected items. 895 896 Some data may not be set if the item was removed during execution of the 897 script. 898 899 See `Selected Items`_. 900 901.. js:function:: currentItem() 902 index() 903 904 Returns current row in current tab. 905 906 See `Selected Items`_. 907 908 :returns: Current row, ``-1`` if called outside the main 909 window context (see `Selected Items`_). 910 :rtype: int 911 912.. js:function:: escapeHtml(text) 913 914 Returns text with special HTML characters escaped. 915 916 :returns: Escaped HTML text. 917 :rtype: string 918 919.. js:function:: unpack(data) 920 921 Returns deserialized object from serialized items. 922 923 :returns: Deserialize item. 924 :rtype: :js:class:`Item` 925 926.. js:function:: pack(Item) 927 928 Returns serialized item. 929 930 :returns: Serialize item. 931 :rtype: :js:class:`ByteArray` 932 933.. js:function:: getItem(row) 934 935 Returns an item in current tab. 936 937 :returns: Item data for the row. 938 :rtype: :js:class:`Item` 939 940 Example -- show data of the first item in a tab in popups: 941 942 .. code-block:: js 943 944 tab('work') // change current tab for the script to 'work' 945 var item = getItem(0) 946 for (var format in item) { 947 var data = item[format] 948 popup(format, data) 949 } 950 951 .. seealso:: 952 953 - :js:func:`selectedItemsData` 954 955.. js:function:: setItem(row, text|Item) 956 957 Inserts item to current tab. 958 959 Same as ``insert(row, something)``. 960 961 .. seealso:: 962 963 - :js:func:`insert` 964 - :js:func:`setSelectedItemsData` 965 966.. js:function:: toBase64(data) 967 968 Returns base64-encoded data. 969 970 :returns: Base64-encoded data. 971 :rtype: string 972 973.. js:function:: fromBase64(base64String) 974 975 Returns base64-decoded data. 976 977 :returns: Base64-decoded data. 978 :rtype: :js:class:`ByteArray` 979 980.. js:function:: md5sum(data) 981 982 Returns MD5 checksum of data. 983 984 :returns: MD5 checksum of the data. 985 :rtype: :js:class:`ByteArray` 986 987.. js:function:: sha1sum(data) 988 989 Returns SHA1 checksum of data. 990 991 :returns: SHA1 checksum of the data. 992 :rtype: :js:class:`ByteArray` 993 994.. js:function:: sha256sum(data) 995 996 Returns SHA256 checksum of data. 997 998 :returns: SHA256 checksum of the data. 999 :rtype: :js:class:`ByteArray` 1000 1001.. js:function:: sha512sum(data) 1002 1003 Returns SHA512 checksum of data. 1004 1005 :returns: SHA512 checksum of the data. 1006 :rtype: :js:class:`ByteArray` 1007 1008.. js:function:: open(url, ...) 1009 1010 Tries to open URLs in appropriate applications. 1011 1012 :returns: ``true`` if all URLs were successfully opened, otherwise ``false``. 1013 :rtype: bool 1014 1015.. js:function:: execute(argument, ..., null, stdinData, ...) 1016 1017 Executes a command. 1018 1019 All arguments after ``null`` are passed to standard input of the 1020 command. 1021 1022 If argument is function it will be called with array of lines read from 1023 stdout whenever available. 1024 1025 :returns: Finished command properties or ``undefined`` if executable was not 1026 found or could not be executed. 1027 :rtype: :js:class:`FinishedCommand` or ``undefined`` 1028 1029 Example -- create item for each line on stdout: 1030 1031 .. code-block:: js 1032 1033 execute('tail', '-f', 'some_file.log', 1034 function(lines) { add.apply(this, lines) }) 1035 1036 Returns object for the finished command or ``undefined`` on failure. 1037 1038.. js:function:: String currentWindowTitle() 1039 1040 Returns window title of currently focused window. 1041 1042 :returns: Current window title. 1043 :rtype: string 1044 1045.. js:function:: dialog(...) 1046 1047 Shows messages or asks user for input. 1048 1049 Arguments are names and associated values. 1050 1051 Special arguments: 1052 1053 - '.title' - dialog title 1054 - '.icon' - dialog icon (see below for more info) 1055 - '.style' - Qt style sheet for dialog 1056 - '.height', '.width', '.x', '.y' - dialog geometry 1057 - '.label' - dialog message (can contain basic HTML) 1058 1059 :returns: Value or values from accepted dialog or ``undefined`` if dialog 1060 was canceled. 1061 1062 .. code-block:: js 1063 1064 dialog( 1065 '.title', 'Command Finished', 1066 '.label', 'Command <b>successfully</b> finished.' 1067 ) 1068 1069 Other arguments are used to get user input. 1070 1071 .. code-block:: js 1072 1073 var amount = dialog('.title', 'Amount?', 'Enter Amount', 'n/a') 1074 var filePath = dialog('.title', 'File?', 'Choose File', new File('/home')) 1075 1076 If multiple inputs are required, object is returned. 1077 1078 .. code-block:: js 1079 1080 var result = dialog( 1081 'Enter Amount', 'n/a', 1082 'Choose File', new File(str(currentPath)) 1083 ) 1084 print('Amount: ' + result['Enter Amount'] + '\n') 1085 print('File: ' + result['Choose File'] + '\n') 1086 1087 A combo box with an editable custom text/value can be created by passing an 1088 array argument. The default text can be provided using ``.defaultChoice`` 1089 (by default it's the first item). 1090 1091 .. code-block:: js 1092 1093 var text = dialog('.defaultChoice', '', 'Select', ['a', 'b', 'c']) 1094 1095 A combo box with non-editable text can be created by prefixing the label 1096 argument with ``.combo:``. 1097 1098 .. code-block:: js 1099 1100 var text = dialog('.combo:Select', ['a', 'b', 'c']) 1101 1102 An item list can be created by prefixing the label argument with ``.list:``. 1103 1104 .. code-block:: js 1105 1106 var items = ['a', 'b', 'c'] 1107 var selected_index = dialog('.list:Select', items) 1108 if (selected_index !== undefined) 1109 print('Selected item: ' + items[selected_index]) 1110 1111 Icon for custom dialog can be set from icon font, file path or theme. 1112 Icons from icon font can be copied from icon selection dialog in Command 1113 dialog or dialog for setting tab icon (in menu 'Tabs/Change Tab Icon'). 1114 1115 .. code-block:: js 1116 1117 var search = dialog( 1118 '.title', 'Search', 1119 '.icon', 'search', // Set icon 'search' from theme. 1120 'Search', '' 1121 ) 1122 1123.. js:function:: menuItems(text...) 1124 1125 Opens menu with given items and returns selected item or an empty string. 1126 1127 :returns: Selected item or empty string if menu was canceled. 1128 :rtype: string 1129 1130 .. code-block:: js 1131 1132 var selectedText = menuItems('x', 'y', 'z') 1133 if (selectedText) 1134 popup('Selected', selectedText) 1135 1136.. js:function:: /*items*/ menuItems(items[]) 1137 1138 Opens menu with given items and returns index of selected item or -1. 1139 1140 Menu item label is taken from :js:data:`mimeText` format an icon is taken 1141 from :js:data:`mimeIcon` format. 1142 1143 :returns: Selected item index or `-1` if menu was canceled. 1144 :rtype: int 1145 1146 .. code-block:: js 1147 1148 var items = selectedItemsData() 1149 var selectedIndex = menuItems(items) 1150 if (selectedIndex != -1) 1151 popup('Selected', items[selectedIndex][mimeText]) 1152 1153.. js:function:: settings() 1154 1155 Returns array with names of all custom user options. 1156 1157 These options can be managed by various commands, much like cookies 1158 are used by web applications in a browser. A typical usage is to remember 1159 options lastly selected by user in a custom dialog displayed by a command. 1160 1161 These options are persisted within the ``[General]`` section of a corresponding 1162 ``copyq-scripts.ini`` file. But if an option is named like ``group/...``, 1163 then it is written to a section named ``[group]`` instead. 1164 By grouping options like this, we can avoid potential naming collisions 1165 with other commands. 1166 1167 :returns: Available custom options. 1168 :rtype: array of strings 1169 1170.. js:function:: /*get*/ Value settings(optionName) 1171 1172 Returns value for a custom user option. 1173 1174 :returns: Current value of the custom options, ``undefined`` if the option 1175 was not set. 1176 1177.. js:function:: /*set*/ settings(optionName, value) 1178 1179 Sets value for a new custom user option or overrides existing one. 1180 1181.. js:function:: dateString(format) 1182 1183 Returns text representation of current date and time. 1184 1185 See 1186 `QDateTime::toString() <http://doc.qt.io/qt-5/qdatetime.html#toString>`__ 1187 for details on formatting date and time. 1188 1189 :returns: Current date and time as string. 1190 :rtype: string 1191 1192 Example: 1193 1194 .. code-block:: js 1195 1196 var now = dateString('yyyy-MM-dd HH:mm:ss') 1197 1198.. js:function:: commands() 1199 1200 Return list of all commands. 1201 1202 :returns: Array of all commands. 1203 :rtype: array of :js:class:`Command` 1204 1205.. js:function:: setCommands(Command[]) 1206 1207 Clear previous commands and set new ones. 1208 1209 To add new command: 1210 1211 .. code-block:: js 1212 1213 var cmds = commands() 1214 cmds.unshift({ 1215 name: 'New Command', 1216 automatic: true, 1217 input: 'text/plain', 1218 cmd: 'copyq: popup("Clipboard", input())' 1219 }) 1220 setCommands(cmds) 1221 1222.. js:function:: Command[] importCommands(String) 1223 1224 Return list of commands from exported commands text. 1225 1226 :returns: Array of commands loaded from a file path. 1227 :rtype: array of :js:class:`Command` 1228 1229.. js:function:: String exportCommands(Command[]) 1230 1231 Return exported command text. 1232 1233 :returns: Serialized commands. 1234 :rtype: string 1235 1236.. js:function:: addCommands(Command[]) 1237 1238 Opens Command dialog, adds commands and waits for user to confirm the 1239 dialog. 1240 1241.. js:function:: NetworkReply networkGet(url) 1242 1243 Sends HTTP GET request. 1244 1245 :returns: HTTP reply. 1246 :rtype: :js:class:`NetworkReply` 1247 1248.. js:function:: NetworkReply networkPost(url, postData) 1249 1250 Sends HTTP POST request. 1251 1252 :returns: HTTP reply. 1253 :rtype: :js:class:`NetworkReply` 1254 1255.. js:function:: NetworkReply networkGetAsync(url) 1256 1257 Same as :js:func:`networkGet` but the request is asynchronous. 1258 1259 The request is handled asynchronously and may not be finished until you get 1260 a property of the reply. 1261 1262 :returns: HTTP reply. 1263 :rtype: :js:class:`NetworkReply` 1264 1265.. js:function:: NetworkReply networkPostAsync(url, postData) 1266 1267 Same as :js:func:`networkPost` but the request is asynchronous. 1268 1269 The request is handled asynchronously and may not be finished until you get 1270 a property of the reply. 1271 1272 :returns: HTTP reply. 1273 :rtype: :js:class:`NetworkReply` 1274 1275.. js:function:: env(name) 1276 1277 Returns value of environment variable with given name. 1278 1279 :returns: Value of the environment variable. 1280 :rtype: :js:class:`ByteArray` 1281 1282.. js:function:: setEnv(name, value) 1283 1284 Sets environment variable with given name to given value. 1285 1286 :returns: ``true`` if the variable was set, otherwise ``false``. 1287 :rtype: bool 1288 1289.. js:function:: sleep(time) 1290 1291 Wait for given time in milliseconds. 1292 1293.. js:function:: afterMilliseconds(time, function) 1294 1295 Executes function after given time in milliseconds. 1296 1297.. js:function:: screenNames() 1298 1299 Returns list of available screen names. 1300 1301 :returns: Available screen names. 1302 :rtype: array of strings 1303 1304.. js:function:: screenshot(format='png', [screenName]) 1305 1306 Returns image data with screenshot. 1307 1308 Default ``screenName`` is name of the screen with mouse cursor. 1309 1310 You can list valid values for ``screenName`` with :js:func:`screenNames`. 1311 1312 :returns: Image data. 1313 :rtype: :js:class:`ByteArray` 1314 1315 Example: 1316 1317 .. code-block:: js 1318 1319 copy('image/png', screenshot()) 1320 1321.. js:function:: screenshotSelect(format='png', [screenName]) 1322 1323 Same as :js:func:`screenshot` but allows to select an area on screen. 1324 1325 :returns: Image data. 1326 :rtype: :js:class:`ByteArray` 1327 1328.. js:function:: queryKeyboardModifiers() 1329 1330 Returns list of currently pressed keyboard modifiers which can be 'Ctrl', 1331 'Shift', 'Alt', 'Meta'. 1332 1333 :returns: Currently pressed keyboard modifiers. 1334 :rtype: array of strings 1335 1336.. js:function:: pointerPosition() 1337 1338 Returns current mouse pointer position (x, y coordinates on screen). 1339 1340 :returns: Current mouse pointer coordinates. 1341 :rtype: array of ints (with two elements) 1342 1343.. js:function:: setPointerPosition(x, y) 1344 1345 Moves mouse pointer to given coordinates on screen. 1346 1347 :throws Error: Thrown if the pointer position couldn't be set (for example, 1348 unsupported on current the system). 1349 1350.. js:function:: iconColor() 1351 1352 Get current tray and window icon color name. 1353 1354 :returns: Current icon color. 1355 :rtype: string 1356 1357.. js:function:: /*set*/ iconColor(colorName) 1358 1359 Set current tray and window icon color name (examples: 'orange', '#ffa500', '#09f'). 1360 1361 Resets color if color name is empty string. 1362 1363 :throws Error: Thrown if the color name is empty or invalid. 1364 1365 .. code-block:: js 1366 1367 // Flash icon for few moments to get attention. 1368 var color = iconColor() 1369 for (var i = 0; i < 10; ++i) { 1370 iconColor("red") 1371 sleep(500) 1372 iconColor(color) 1373 sleep(500) 1374 } 1375 1376 .. seealso:: 1377 1378 :js:data:`mimeColor` 1379 1380.. js:function:: iconTag() 1381 1382 Get current tray and window icon tag text. 1383 1384 :returns: Current icon tag. 1385 :rtype: string 1386 1387.. js:function:: /*set*/ iconTag(tag) 1388 1389 Set current tray and window tag text. 1390 1391.. js:function:: iconTagColor() 1392 1393 Get current tray and window tag color name. 1394 1395 :returns: Current icon tag color. 1396 :rtype: string 1397 1398.. js:function:: /*set*/ iconTagColor(colorName) 1399 1400 Set current tray and window tag color name. 1401 1402 :throws Error: Thrown if the color name is invalid. 1403 1404.. js:function:: loadTheme(path) 1405 1406 Loads theme from an INI file. 1407 1408 :throws Error: Thrown if the file cannot be read or is not valid INI format. 1409 1410.. js:function:: onClipboardChanged() 1411 1412 Called when clipboard or `Linux mouse selection`_ changes. 1413 1414 Default implementation is: 1415 1416 .. code-block:: js 1417 1418 if (!hasData()) { 1419 updateClipboardData(); 1420 } else if (runAutomaticCommands()) { 1421 saveData(); 1422 updateClipboardData(); 1423 } else { 1424 clearClipboardData(); 1425 } 1426 1427.. js:function:: onOwnClipboardChanged() 1428 1429 Called when clipboard or `Linux mouse selection`_ changes by a CopyQ instance. 1430 1431 Owned clipboard data contains :js:data:`mimeOwner` format. 1432 1433 Default implementation calls :js:func:`updateClipboardData`. 1434 1435.. js:function:: onHiddenClipboardChanged() 1436 1437 Called when hidden clipboard or `Linux mouse selection`_ changes. 1438 1439 Hidden clipboard data contains :js:data:`mimeHidden` format set to ``1``. 1440 1441 Default implementation calls :js:func:`updateClipboardData`. 1442 1443.. js:function:: onClipboardUnchanged() 1444 1445 Called when clipboard or `Linux mouse selection`_ changes but data remained the same. 1446 1447 Default implementation does nothing. 1448 1449.. js:function:: onStart() 1450 1451 Called when application starts. 1452 1453.. js:function:: onExit() 1454 1455 Called just before application exists. 1456 1457.. js:function:: runAutomaticCommands() 1458 1459 Executes automatic commands on current data. 1460 1461 If an executed command calls :js:func:`ignore` or have "Remove Item" or 1462 "Transform" check box enabled, following automatic commands won't be 1463 executed and the function returns ``false``. Otherwise ``true`` is returned. 1464 1465 :returns: ``true`` if clipboard data should be stored, otherwise ``false``. 1466 :rtype: bool 1467 1468.. js:function:: clearClipboardData() 1469 1470 Clear clipboard visibility in GUI. 1471 1472 Default implementation is: 1473 1474 .. code-block:: js 1475 1476 if (isClipboard()) { 1477 setTitle(); 1478 hideDataNotification(); 1479 } 1480 1481.. js:function:: updateTitle() 1482 1483 Update main window title and tool tip from current data. 1484 1485 Called when clipboard changes. 1486 1487.. js:function:: updateClipboardData() 1488 1489 Sets current clipboard data for tray menu, window title and notification. 1490 1491 Default implementation is: 1492 1493 .. code-block:: js 1494 1495 if (isClipboard()) { 1496 updateTitle(); 1497 showDataNotification(); 1498 setClipboardData(); 1499 } 1500 1501.. js:function:: setTitle([title]) 1502 1503 Set main window title and tool tip. 1504 1505.. js:function:: synchronizeToSelection(text) 1506 1507 Synchronize current data from clipboard to `Linux mouse selection`_. 1508 1509 Called automatically from clipboard monitor process if option 1510 ``copy_clipboard`` is enabled. 1511 1512 Default implementation calls :js:func:`provideSelection`. 1513 1514.. js:function:: synchronizeFromSelection(text) 1515 1516 Synchronize current data from `Linux mouse selection`_ to clipboard. 1517 1518 Called automatically from clipboard monitor process if option 1519 ``copy_selection`` is enabled. 1520 1521 Default implementation calls :js:func:`provideClipboard`. 1522 1523.. js:function:: clipboardFormatsToSave() 1524 1525 Returns list of clipboard format to save automatically. 1526 1527 :returns: Formats to get and save automatically from clipboard. 1528 :rtype: array of strings 1529 1530 Override the funtion, for example, to save only plain text: 1531 1532 .. code-block:: js 1533 1534 global.clipboardFormatsToSave = function() { 1535 return ["text/plain"] 1536 } 1537 1538 Or to save additional formats: 1539 1540 .. code-block:: js 1541 1542 var originalFunction = global.clipboardFormatsToSave; 1543 global.clipboardFormatsToSave = function() { 1544 return originalFunction().concat([ 1545 "text/uri-list", 1546 "text/xml" 1547 ]) 1548 } 1549 1550.. js:function:: saveData() 1551 1552 Save current data (depends on `mimeOutputTab`). 1553 1554.. js:function:: hasData() 1555 1556 Returns true only if some non-empty data can be returned by data(). 1557 1558 Empty data is combination of whitespace and null characters or some internal 1559 formats (`mimeWindowTitle`, `mimeClipboardMode` etc.) 1560 1561 :returns: ``true`` if there are some data, otherwise ``false``. 1562 :rtype: bool 1563 1564.. js:function:: showDataNotification() 1565 1566 Show notification for current data. 1567 1568.. js:function:: hideDataNotification() 1569 1570 Hide notification for current data. 1571 1572.. js:function:: setClipboardData() 1573 1574 Sets clipboard data for menu commands. 1575 1576.. js:function:: styles() 1577 1578 List available styles for ``style`` option. 1579 1580 :returns: Style identifiers. 1581 :rtype: array of strings 1582 1583 To change or update style use:: 1584 1585 .. code-block:: js 1586 1587 config("style", styleName) 1588 1589Types 1590----- 1591 1592.. js:class:: ByteArray 1593 1594 Wrapper for QByteArray Qt class. 1595 1596 See `QByteArray <http://doc.qt.io/qt-5/qbytearray.html>`__. 1597 1598 ``ByteArray`` is used to store all item data (image data, HTML and even 1599 plain text). 1600 1601 Use :js:func:`str` to convert it to string. Strings are usually more 1602 versatile. For example to concatenate two items, the data need to be 1603 converted to strings first. 1604 1605 .. code-block:: js 1606 1607 var text = str(read(0)) + str(read(1)) 1608 1609.. js:class:: File 1610 1611 Wrapper for QFile Qt class. 1612 1613 See `QFile <http://doc.qt.io/qt-5/qfile.html>`__. 1614 1615 To open file in different modes use: 1616 1617 - `open()` - read/write 1618 - `openReadOnly()` - read only 1619 - `openWriteOnly()` - write only, truncates the file 1620 - `openAppend()` - write only, appends to the file 1621 1622 Following code reads contents of "README.md" file from current 1623 directory: 1624 1625 .. code-block:: js 1626 1627 var f = new File('README.md') 1628 if (!f.openReadOnly()) 1629 throw 'Failed to open the file: ' + f.errorString() 1630 var bytes = f.readAll() 1631 1632 Following code writes to a file in home directory: 1633 1634 .. code-block:: js 1635 1636 var dataToWrite = 'Hello, World!' 1637 var filePath = Dir().homePath() + '/copyq.txt' 1638 var f = new File(filePath) 1639 if (!f.openWriteOnly() || f.write(dataToWrite) == -1) 1640 throw 'Failed to save the file: ' + f.errorString() 1641 1642 // Always flush the data and close the file, 1643 // before opening the file in other application. 1644 f.close() 1645 1646.. js:class:: Dir 1647 1648 Wrapper for QDir Qt class. 1649 1650 Use forward slash as path separator, for example "D:/Documents/". 1651 1652 See `QDir <http://doc.qt.io/qt-5/qdir.html>`__. 1653 1654.. js:class:: TemporaryFile 1655 1656 Wrapper for QTemporaryFile Qt class. 1657 1658 See `QTemporaryFile <https://doc.qt.io/qt-5/qtemporaryfile.html>`__. 1659 1660 .. code-block:: js 1661 1662 var f = new TemporaryFile() 1663 f.open() 1664 f.setAutoRemove(false) 1665 popup('New temporary file', f.fileName()) 1666 1667 To open file in different modes, use same open methods as for `File`. 1668 1669.. js:class:: Item 1670 1671 Object with MIME types of an item. 1672 1673 Each property is MIME type with data. 1674 1675 Example: 1676 1677 .. code-block:: js 1678 1679 var item = {} 1680 item[mimeText] = 'Hello, World!' 1681 item[mimeHtml] = '<p>Hello, World!</p>' 1682 write(mimeItems, pack(item)) 1683 1684.. js:class:: ItemSelection 1685 1686 List of items from given tab. 1687 1688 An item in the list represents the same item in tab even if it is moved to a 1689 different row. 1690 1691 New items in the tab are not added automatically into the selection. 1692 1693 To create new empty selection use ``ItemSelection()`` then add items with 1694 ``select*()`` methods. 1695 1696 Example - move matching items to the top of the tab: 1697 1698 .. code-block:: js 1699 1700 ItemSelection().select(/^prefix/).move(0) 1701 1702 Example - remove all items from given tab but keep pinned items: 1703 1704 .. code-block:: js 1705 1706 ItemSelection(tabName).selectRemovable().removeAll(); 1707 1708 Example - modify items containing "needle" text: 1709 1710 .. code-block:: js 1711 1712 var sel = ItemSelection().select(/needle/, mimeText); 1713 for (var index = 0; index < sel.length; ++index) { 1714 var item = sel.itemAtIndex(index); 1715 item[mimeItemNotes] = 'Contains needle'; 1716 sel.setItemAtIndex(item); 1717 } 1718 1719 Example - selection with new items only: 1720 1721 .. code-block:: js 1722 1723 var sel = ItemSelection().selectAll() 1724 add("New Item 1") 1725 add("New Item 2") 1726 sel.invert() 1727 sel.items(); 1728 1729 .. js:attribute:: tab 1730 1731 Tab name 1732 1733 .. js:attribute:: length 1734 1735 Number of filtered items in the selection 1736 1737 .. js:method:: selectAll() 1738 1739 Select all items in the tab. 1740 1741 :returns: self 1742 :rtype: ItemSelection 1743 1744 .. js:method:: select(regexp, [mimeType]) 1745 1746 Select additional items matching the regular expression. 1747 1748 If regexp is a valid regular expression and ``mimeType`` is not set, 1749 this selects items with matching text. 1750 1751 If regexp matches empty strings and ``mimeType`` is set, this selects 1752 items containing the MIME type. 1753 1754 If regexp is ``undefined`` and ``mimeType`` is set, this select items 1755 not containing the MIME type. 1756 1757 :returns: self 1758 :rtype: ItemSelection 1759 1760 .. js:method:: selectRemovable() 1761 1762 Select only items that can be removed. 1763 1764 :returns: self 1765 :rtype: ItemSelection 1766 1767 .. js:method:: invert() 1768 1769 Select only items not in the selection. 1770 1771 :returns: self 1772 :rtype: ItemSelection 1773 1774 .. js:method:: deselectIndexes(int[]) 1775 1776 Deselect items at given indexes in the selection. 1777 1778 :returns: self 1779 :rtype: ItemSelection 1780 1781 .. js:method:: deselectSelection(ItemSelection) 1782 1783 Deselect items in other selection. 1784 1785 :returns: self 1786 :rtype: ItemSelection 1787 1788 .. js:method:: current() 1789 1790 Deselects all and selects only the items which were selected when the 1791 command was triggered. 1792 1793 See `Selected Items`_. 1794 1795 :returns: self 1796 :rtype: ItemSelection 1797 1798 .. js:method:: removeAll() 1799 1800 Delete all items in the selection (if possible). 1801 1802 :returns: self 1803 :rtype: ItemSelection 1804 1805 .. js:method:: move(row) 1806 1807 Move all items in the selection to the target row. 1808 1809 :returns: self 1810 :rtype: ItemSelection 1811 1812 .. js:method:: copy() 1813 1814 Clone the selection object. 1815 1816 :returns: cloned object 1817 :rtype: ItemSelection 1818 1819 .. js:method:: rows() 1820 1821 Returns selected rows. 1822 1823 :returns: Selected rows 1824 :rtype: array of ints 1825 1826 .. js:method:: itemAtIndex(index) 1827 1828 Returns item data at given index in the selection. 1829 1830 :returns: Item data 1831 :rtype: :js:class:`Item` 1832 1833 .. js:method:: setItemAtIndex(index, Item) 1834 1835 Sets data to the item at given index in the selection. 1836 1837 :returns: self 1838 :rtype: ItemSelection 1839 1840 .. js:method:: items() 1841 1842 Return list of data from selected items. 1843 1844 :returns: Selected item data 1845 :rtype: array of :js:class:`Item` 1846 1847 .. js:method:: setItems(Item[]) 1848 1849 Set data for selected items. 1850 1851 :returns: self 1852 :rtype: ItemSelection 1853 1854 .. js:method:: itemsFormat(mimeType) 1855 1856 Return list of data from selected items containing specified MIME type. 1857 1858 :returns: Selected item data containing only the format 1859 :rtype: array of :js:class:`Item` 1860 1861 .. js:method:: setItemsFormat(mimeType, data) 1862 1863 Set data for given MIME type for the selected items. 1864 1865 :returns: self 1866 :rtype: ItemSelection 1867 1868.. js:class:: FinishedCommand 1869 1870 Properties of finished command. 1871 1872 .. js:attribute:: stdout 1873 1874 Standard output 1875 1876 .. js:attribute:: stderr 1877 1878 Standard error output 1879 1880 .. js:attribute:: exit_code 1881 1882 Exit code 1883 1884.. js:class:: NetworkReply 1885 1886 Received network reply object. 1887 1888 .. js:attribute:: data 1889 1890 Reply data 1891 1892 .. js:attribute:: status 1893 1894 HTTP status 1895 1896 .. js:attribute:: error`` 1897 1898 Error string (set only if an error occurred) 1899 1900 .. js:attribute:: redirect 1901 1902 URL for redirection (set only if redirection is needed) 1903 1904 .. js:attribute:: headers 1905 1906 Reply headers (array of pairs with header name and header content) 1907 1908 .. js:attribute:: finished 1909 1910 True only if request has been completed, false only for unfinished 1911 asynchronous requests 1912 1913.. js:class:: Command 1914 1915 Wrapper for a command (from Command dialog). 1916 1917 Properties are same as members of `Command 1918 struct <https://github.com/hluk/CopyQ/blob/master/src/common/command.h>`__. 1919 1920Objects 1921------- 1922 1923.. js:data:: arguments (Array) 1924 1925 Array for accessing arguments passed to current function or the script 1926 (``arguments[0]`` is the script itself). 1927 1928.. js:data:: global 1929 1930 Object allowing to modify global scope which contains all functions like 1931 :js:func:`copy` or :js:func:`add`. 1932 1933 This is useful for :ref:`commands-script`. 1934 1935.. js:data:: console 1936 1937 Allows some logging and debugging. 1938 1939 .. code-block:: js 1940 1941 // Print a message if COPYQ_LOG_LEVEL=DEBUG 1942 // environment variable is set 1943 console.log( 1944 'Supported console properties/functions:', 1945 Object.getOwnPropertyNames(console)) 1946 console.warn('Changing clipboard...') 1947 1948 // Elapsed time 1949 console.time('copy') 1950 copy('TEST') 1951 console.timeEnd('copy') 1952 1953 // Ensure a condition is true before continuing 1954 console.assert(str(clipboard()) == 'TEST') 1955 1956MIME Types 1957---------- 1958 1959Item and clipboard can provide multiple formats for their data. Type of 1960the data is determined by MIME type. 1961 1962Here is list of some common and builtin (start with 1963``application/x-copyq-``) MIME types. 1964 1965These MIME types values are assigned to global variables prefixed with 1966``mime``. 1967 1968.. note:: 1969 1970 Content for following types is UTF-8 encoded. 1971 1972.. js:data:: mimeText (text/plain) 1973 1974 Data contains plain text content. 1975 1976.. js:data:: mimeHtml (text/html) 1977 1978 Data contains HTML content. 1979 1980.. js:data:: mimeUriList (text/uri-list) 1981 1982 Data contains list of links to files, web pages etc. 1983 1984.. js:data:: mimeWindowTitle (application/x-copyq-owner-window-title) 1985 1986 Current window title for copied clipboard. 1987 1988.. js:data:: mimeItems (application/x-copyq-item) 1989 1990 Serialized items. 1991 1992.. js:data:: mimeItemNotes (application/x-copyq-item-notes) 1993 1994 Data contains notes for item. 1995 1996.. js:data:: mimeIcon (application/x-copyq-item-icon) 1997 1998 Data contains icon for item. 1999 2000.. js:data:: mimeOwner (application/x-copyq-owner) 2001 2002 If available, the clipboard was set from CopyQ (from script or copied items). 2003 2004 Such clipboard is ignored in CopyQ, i.e. it won't be stored in clipboard 2005 tab and automatic commands won't be executed on it. 2006 2007.. js:data:: mimeClipboardMode (application/x-copyq-clipboard-mode) 2008 2009 Contains ``selection`` if data is from `Linux mouse selection`_. 2010 2011.. js:data:: mimeCurrentTab (application/x-copyq-current-tab) 2012 2013 Current tab name when invoking command from main window. 2014 2015 Following command print the tab name when invoked from main window: 2016 2017 :: 2018 2019 copyq data application/x-copyq-current-tab 2020 copyq selectedTab 2021 2022.. js:data:: mimeSelectedItems (application/x-copyq-selected-items) 2023 2024 Selected items when invoking command from main window. 2025 2026.. js:data:: mimeCurrentItem (application/x-copyq-current-item) 2027 2028 Current item when invoking command from main window. 2029 2030.. js:data:: mimeHidden (application/x-copyq-hidden) 2031 2032 If set to ``1``, the clipboard or item content will be hidden in GUI. 2033 2034 This won't hide notes and tags. 2035 2036 Example -- clear window title and tool tip: 2037 2038 :: 2039 2040 copyq copy application/x-copyq-hidden 1 plain/text "This is secret" 2041 2042.. js:data:: mimeShortcut (application/x-copyq-shortcut) 2043 2044 Application or global shortcut which activated the command. 2045 2046 :: 2047 2048 copyq: 2049 var shortcut = data(mimeShortcut) 2050 popup("Shortcut Pressed", shortcut) 2051 2052.. js:data:: mimeColor (application/x-copyq-color) 2053 2054 Item color (same as the one used by themes). 2055 2056 Examples:: 2057 2058 #ffff00 2059 rgba(255,255,0,0.5) 2060 bg - #000099 2061 2062.. js:data:: mimeOutputTab (application/x-copyq-output-tab) 2063 2064 Name of the tab where to store new item. 2065 2066 The clipboard data will be stored in tab with this name after all 2067 automatic commands are run. 2068 2069 Clear or remove the format to omit storing the data. 2070 2071 Example -- automatic command that avoids storing clipboard data: 2072 2073 .. code-block:: js 2074 2075 removeData(mimeOutputTab) 2076 2077 Valid only in automatic commands. 2078 2079Selected Items 2080-------------- 2081 2082Functions that get and set data for selected items and current tab are 2083only available if called from Action dialog or from a command which is 2084in menu. 2085 2086Selected items are indexed from top to bottom as they appeared in the 2087current tab at the time the command is executed. 2088 2089Linux Mouse Selection 2090--------------------- 2091 2092In many application on Linux, if you select a text with mouse, it's possible to 2093paste it with middle mouse button. 2094 2095The text is stored separately from normal clipboard content. 2096 2097On non-Linux system, functions that support mouse selection will do nothing 2098(for example :js:func:`copySelection`) or return ``undefined`` (in case of 2099:js:func:`selection`). 2100 2101Plugins 2102------- 2103 2104Use ``plugins`` object to access functionality of plugins. 2105 2106.. js:function:: plugins.itemsync.selectedTabPath() 2107 2108 Returns synchronization path for current tab (mimeCurrentTab). 2109 2110 .. code-block:: js 2111 2112 var path = plugins.itemsync.selectedTabPath() 2113 var baseName = str(data(plugins.itemsync.mimeBaseName)) 2114 var absoluteFilePath = Dir(path).absoluteFilePath(baseName) 2115 // NOTE: Known file suffix/extension can be missing in the full path. 2116 2117.. js:class:: plugins.itemsync.tabPaths 2118 2119 Object that maps tab name to synchronization path. 2120 2121 .. code-block:: js 2122 2123 var tabName = 'Downloads' 2124 var path = plugins.itemsync.tabPaths[tabName] 2125 2126.. js:data:: plugins.itemsync.mimeBaseName (application/x-copyq-itemsync-basename) 2127 2128 MIME type for accessing base name (without full path). 2129 2130 Known file suffix/extension can be missing in the base name. 2131 2132.. js:data:: plugins.itemtags.userTags (Array) 2133 2134 List of user-defined tags. 2135 2136.. js:function:: plugins.itemtags.tags(row, ...) 2137 2138 List of tags for items in given rows. 2139 2140.. js:function:: plugins.itemtags.tag(tagName, [rows, ...]) 2141 2142 Add given tag to items in given rows or selected items. 2143 2144 See `Selected Items`_. 2145 2146.. js:function:: plugins.itemtags.untag(tagName, [rows, ...]) 2147 2148 Remove given tag from items in given rows or selected items. 2149 2150 See `Selected Items`_. 2151 2152.. js:function:: plugins.itemtags.clearTags([rows, ...]) 2153 2154 Remove all tags from items in given rows or selected items. 2155 2156 See `Selected Items`_. 2157 2158.. js:function:: plugins.itemtags.hasTag(tagName, [rows, ...]) 2159 2160 Return true if given tag is present in any of items in given rows or 2161 selected items. 2162 2163 See `Selected Items`_. 2164 2165.. js:data:: plugins.itemtags.mimeTags (application/x-copyq-tags) 2166 2167 MIME type for accessing list of tags. 2168 2169 Tags are separated by comma. 2170 2171.. js:function:: plugins.itempinned.isPinned(rows, ...) 2172 2173 Returns true only if any item in given rows is pinned. 2174 2175.. js:function:: plugins.itempinned.pin(rows, ...) 2176 2177 Pin items in given rows or selected items or new item created from clipboard 2178 (if called from automatic command). 2179 2180.. js:function:: plugins.itempinned.unpin(rows, ...) 2181 2182 Unpin items in given rows or selected items. 2183 2184.. js:data:: plugins.itempinned.mimePinned (application/x-copyq-item-pinned) 2185 2186 Presence of the format in an item indicates that it is pinned. 2187 2188