docs: Add section Pin Items

docs/index.rst

@@ -26,6 +26,7 @@ advanced topics like scripting and application development process.
 
     command-line
     sessions
+    pin-items
     password-protection
     writing-commands-and-adding-functionality
     scripting

docs/pin-items.rst

@@ -0,0 +1,74 @@
+Pin Items
+=========
+
+This page describes how to pin selected items in a tab so they cannot be
+accidentally removed or moved from current row.
+
+Why pin items?
+--------------
+
+There are two main reasons to pin items.
+
+If a new item is added to a list (e.g. automatically when clipboard changed),
+rest of the items need to move one row down, except pinned items which stay on
+the same row. This is useful to **pin important items to the top of the list**.
+
+If a tab is full (see option "Maximum number of items in history" in "History"
+configuration tab), adding a new item removes old item from bottom of the list.
+**Pinned items cannot be removed** so the last unpinned item is removed
+instead.
+
+.. note::
+
+    New items cannot be added to a tab if all its items are pinned and the tab
+    is full.
+
+Configuration
+-------------
+
+.. note::
+
+    On Windows, to enable this feature you need to install "Pinned Items"
+    plugin.
+
+Add menu items and keyboard shortcuts for Pin and Unpin actions.
+
+1. Open "Preferences" (``Ctrl+P`` shortcut),
+2. go to "Items" tab,
+3. select "Pinned Items",
+
+    .. image:: images/pin-items-add-actions.png
+       :scale: 50%
+       :alt: Add Pin and Unpin menu items
+
+4. click "Add Actions to Menu and Toolbar",
+5. optionally change keyboard shortcuts for the two new menu items,
+
+    .. image:: images/pin-items-shortcuts.png
+       :scale: 50%
+       :alt: Set Pin and Unpin shortcuts
+
+6. click OK to save changes.
+
+.. note::
+
+    Keyboard shortcut for both menu items can be the same since at most one of
+    the menu items is always visible.
+
+Pinning Items
+-------------
+
+If set up correctly, when you select items, Pin action should be available in
+toolbar, context menu and "Item" menu.
+
+Selecting the Pin menu item (or pressing assigned keyboard shortcut) will pin
+selected items to their current rows.
+
+Pinned items will show with **gray bar on the right side** in the list.
+
+Deleting pinned items won't work, unpin the items first.
+Unpin action is available if an pinned item is selected.
+
+Pinned items also will stay in same rows unless you **move them with mouse or
+using keyboard shortcuts** (``Ctrl+Up/Down/Home/End``).
+