Recoll user manual

Searching with the Qt graphical user interface

The Query Fragments window can be used to control filtering query language elements modifying the current query, simply by clicking a button. This can be useful to save typing, or avoid memorizing, simple clauses of common usage (e.g. selecting only standalone documents or attachments, or filtering out WEB results, selecting a file system subtree, a file type, etc.).

Selecting the Tools → Query Fragments menu entry will open the dialog.

The contents of the window are entirely customizable, and defined by the contents of a XML text file, named fragment-buttons.xml and which will be looked for in the current index configuration directory. The sample file distributed with Recoll contains a number of example filters. This will be automatically copied to the configuration directory if the file does not exist in there (e.g. ~/.recoll/fragment-buttons.xml under Linux and MacOS, $HOME/AppData/Local/Recoll/fragment-buttons.xml for Windows). Editing the copy will allow you to configure the tool for your needs .

Here follows an example window:

And the corresponding configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<fragbuttons version="1.0">

  <radiobuttons>
    <!-- Toggle WEB queue results inclusion -->
    <fragbutton>
      <label>Include Web Results</label>
      <frag></frag>
    </fragbutton>
    <fragbutton>
      <label>Exclude Web Results</label>
      <frag>-rclbes:BGL</frag>
    </fragbutton>
    <fragbutton>
      <label>Only Web Results</label>
      <frag>rclbes:BGL</frag>
    </fragbutton>
  </radiobuttons>

  <radiobuttons>
    <!-- Standalone vs embedded switch -->
    <fragbutton>
      <label>Include embedded documents</label>
      <frag></frag>
    </fragbutton>
    <fragbutton>
      <label>Only standalone documents</label>
      <frag>issub:0</frag>
    </fragbutton>
    <fragbutton>
      <label>Only embedded documents</label>
      <frag>issub:1</frag>
    </fragbutton>
  </radiobuttons>

  <buttons>
    <fragbutton>
      <label>Example: Year 2010</label>
      <frag>date:2010-01-01/2010-12-31</frag>
    </fragbutton>
    <fragbutton>
      <label>Example: c++ files</label>
      <frag>ext:cpp OR ext:cxx</frag>
    </fragbutton>
    <fragbutton>
      <label>Example: My Great Directory</label>
      <frag>dir:/my/great/directory</frag>
    </fragbutton>
  </buttons>
</fragbuttons>
        

There are two types of groupings radiobuttons and buttons, each defining a line of checkbuttons or radiobuttons inside the window. Any number of buttons can be selected, but the radiobuttons in a line are exclusive.

Buttons are defined by a fragbutton section, which provides the label for a button, and the Query Language fragment which will be added (as an AND filter) before performing the query if the button is active.

    <fragbutton>
      <label>Example: My Great Directory</label>
      <frag>dir:/my/great/directory</frag>
    </fragbutton>
  

It is also possible to add message elements inside the groups, for documenting the behaviour. message elements have a label but no frag element. Example:

  <buttons>
    <message>
      <label>This is a message</label> 
    </message>
  </buttons>
  

The label contents are interpreted as HTML. Take care to replace opening < characters with the < entity if you use tags.

The only thing that you need to know about XML for editing this file is that any opening tag like <label> needs to be matched by a closing tag after the value: </label>.

You will normally edit the file with a regular text editor, like, e.g. vi or notepad. Double-clicking the file in a file manager may not work, because this usually opens it in a WEB browser, which will not let you modify the contents.