Initial commit

doc/docportal/advanced_topics/understand_search_box.rst

@@ -0,0 +1,130 @@
+======================================================
+Understanding the search box
+======================================================
+
+This guide expands on the information contained in the :ref:`the search box <search_box>` section of the Launcher interface description.
+
+
+Main functionality
+===========================================
+
+- A filter is applied as you type, so there is no need to press Enter or click anything to perform the search.
+- All searches are case insensitive.
+- To reset the filter and get the full list of games, click on the cross icon next to the text input field.
+- Whitespace breaks the search input into separate tokens or search patterns.
+
+
+Search patterns
+===========================================
+
+
+Simple patterns
+___________________________________________
+
+The simplest way to search is to use the substring search functionality. For example, type ``m`` to get all the games containing an 'M' or 'm' in description, and type ``monkey`` to get games like "The Curse of Monkey Island (Demo/Windows)", "Infinite Monkeys" or "Three Monkeys, One Cage". Ensure the search pattern does not contain ``:``/``=``/``~`` characters and it does not start with the ``!`` character.
+
+
+Searching configuration key values
+___________________________________________
+
+
+Advanced patterns
+**************************
+
+To search for game properties listed in the :doc:`configuration_file` there are 3 available patterns:
+
+.. csv-table::
+  	:header-rows: 1
+	:class: config
+
+		Type,Description,Example,Example result
+		"<key>=<value>", check exact value of ``<key>``, ``gameid=reversion2``, games with exact gameid "reversion2"
+		"<key>:<value>", search substring at ``<key>``, ``description::``, games with ":" substring at description
+		"<key>~<value>", match wildcard against ``<key>``, ``path~D:\\games\\*``, games located at Windows folder D:\\Games\\
+
+
+.. note::
+
+	Escape the ``\`` character used in Windows paths by using ``\\`` when using wildcards.
+
+
+Available configuration keys
+*******************************************
+
+You can use any :ref:`configuration key <configuration_keys>` as a ``<key>`` part of the search pattern.
+
+Here are some more examples:
+
+- ``show_fps=true`` - games with "Show FPS" option set to true
+- ``extra~?*`` - games with non-empty extra part of the description
+- ``guioptions:noLang`` - games without displayed language
+- ``keymap_engine-default_LCLK:MOUSE_RIGHT`` - games with right mouse button remapped to left mouse button
+
+Abbreviating configuration keys
+*******************************************
+
+To abbreviate the 6 most common configuration keys, just type any prefix instead of full strings for those keys:
+
+.. csv-table::
+  	:header-rows: 1
+	:class: config
+
+		Full key,Description,Examples
+		``description``, game description as displayed on the game list,"
+
+	- ``d:monkey``
+	- ``desc:monkey``
+	- ``descr:monkey``
+	- ``description:monkey``"
+		``engineid``, internal ID of the game engine,"
+
+	- ``e:ags``
+	- ``engine:monkey``
+	- ``engineid:monkey``"
+		``gameid``, internal ID of the game,"
+
+	- ``g:monkey``
+	- ``game:monkey``
+	- ``gameid:monkey``"
+		``language``, internal ID of the language (usually 2 letter code like "de"/"en"/"fr"/"jp","
+
+	- ``l=en``
+	- ``lang=en``
+	- ``language=en``"
+		``path``, Filesystem path for the game,"
+
+	- ``p~D:*``
+	- ``path~D:*``"
+		``platform``, internal ID of the platform,"
+
+	- ``pl~windows``
+	- ``platform~windows``"
+
+.. note::
+
+	The ``platform`` key can't be abbreviated to ``p``, since ``p`` is already used for ``path``.
+
+
+Inverting the search pattern
+___________________________________________
+
+To invert the search result, prefix the search pattern with the`!` character. For example:
+
+- ``!GOG`` - games that don't contain "GOG" substring in description
+- ``!lang=ru`` - games not in Russian language
+- ``!p:demo`` - games that don't have "demo" substring in game path
+- ``!engine~sword#`` - games not made with "sword1" and "sword2" engines (but "sword25" is fine)
+
+
+How do the search patterns work together?
+===========================================
+
+If you have provided several search patterns, only games that match all of them are displayed.
+
+The matches are independent and not ordered, which means that if you search for ``Open Quest``, you get all the games with words "Open" and "Quest" in description. The results would contain games like "Open Quest (Windows/English)" and "Police Quest IV: Open Season (DOS/Demo)".
+
+Here are some more examples of complex requests:
+
+- ``engine=ags path:steamapps !extra:Steam`` - AGS games at your /SteamApps/ folder, but not marked as Steam game at "extra"
+- ``e=wintermute l=`` - Wintermute games with empty "language" property
+- ``pl:dos lang=he desc~a*`` - Hebrew games for DOS with description starting with letter "A"