<sect2 id="usage-conditions">
  <title>Defining the conditions</title>
  <para>
    Whether your action will eventually be displayed in <productname>Caja</productname> file manager
    context menus or in its toolbar depends on the conditions you will have
    defined for it.
  </para>
  <para>
    Conditions may be put against the location the file manager currently
    points to, or against the currently selected items in this location.
  </para>
  <para>
    Each time the selection or the location change in the file manager,
    <productname>Caja-Actions</productname> checks all your actions, comparing the defined conditions
    against the new location and selection: all defined conditions must
    be satisfied in order your action be actually displayed. 
  </para>

  <sect3 id="usage-conditions-basenames">
    <title>Basename-based conditions</title>
    <para>
      You may decide that your action will appear depending on the basenames
      of the items currently selected in the file-manager: you may define that each
      item of the selection must meet some sort of basename, and you may simultaneously
      decide that none of the selected item(s) can have some other sort of basename.
    </para>
    <para>
      <!-- i18n: "Basenames" is a UI label -->
      Click on the <guilabel>Basenames</guilabel> tab to show the page
      which will permit you to configure your basename-based conditions.
    </para>
    <figure id="cact-FIG-tab-basenames">
      <title>Basename-based conditions</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-basenames-tab.png" format="PNG" />
          </imageobject>
          <textobject>
            <phrase>Shows the tab which lets you define basename-based conditions.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
    <para>
      In fact, basename-based conditions are built as a list of
      &#171;&#160;must match one of&#160;&#187; and &#171;&#160;must not match any of&#160;&#187;
      patterns. In order for your action to be a candidate regarding these
      basename-based conditions, each element of the selection must be valid
      for all the listed conditions: the basename of each element must match
      at least one of the defined &#171;&#160;must match one of&#160;&#187; patterns, and must not match
      any of the defined &#171;&#160;must not match any of&#160;&#187; patterns.
    </para>
    <para>
      If at least one element of the selection does not match all the defined
      conditions, then your action will not be displayed.
    </para>
    <para>
      When targeting the selection context menu, your basename-based conditions
      will be checked against the currently selected items. When targeting the
      location context menu or the toolbar, your basename-based conditions will
      be checked against the basename of the current location.
    </para>
    <para>
      Defining a new basename-based condition involves two steps.
    </para>
    <orderedlist>
      <listitem>
        <para>
          Define the new condition filter.
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <!-- i18n: "Insert" is a key name -->
              Press <keycap>Insert</keycap> or click on 
              <guibutton><inlinegraphic fileref="figures/add.png"/></guibutton>
              button to insert a new condition filter
            </para>
          </listitem>
          <listitem>
            <para>
              Edit the newly inserted condition filter to the basename you
              want match.
            </para>
            <tip>
              <para>
                A basename-based condition may use &#171;&#160;<literal>*</literal>&#160;&#187; or
                &#171;&#160;<literal>?</literal>&#160;&#187; wildcard characters.
              </para>
            </tip>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>
          Indicates whether this a &#171;&#160;must match one of&#160;&#187;
          or a &#171;&#160;must not match any of&#160;&#187; condition.
        </para>
        <para>
          <!-- i18n: "Must match one of" is a UI label -->
          Click on the <guilabel>Must match one of</guilabel> or
          <!-- i18n: "Must not match any of" is a UI label -->
          <guilabel>Must not match any of</guilabel> radio button in the
          same row to set the corresponding condition.
        </para>
      </listitem>
    </orderedlist>
    <para>
      Depending of your target operating system, make sure that the
      <!-- i18n: "Match case" is a UI label -->
      <guilabel>Match case</guilabel> checkbox is activated (or not). 
    </para>
    <itemizedlist>
      <listitem>
        <para>
          When activated, all filters are considered as case sensitive,
          <!-- i18n: "/my/file" is an example of *nix filename, and may be translated -->
          which means that <filename>/my/file</filename> filename is
          <!-- i18n: "/My/File" is an example of *nix filename, and may be translated -->
          considered distinct from <filename>/My/File</filename> one.
        </para>
        <para>
          This is the default behavior on Unix-like systems.
        </para>
      </listitem>
      <listitem>
        <para>
          When deactivated, filters are considered as case insensitive,
          <!-- i18n: "/my/file" is an example of *nix filename, and may be translated -->
          which means that <filename>/my/file</filename> and
          <!-- i18n: "/My/File" is an example of *nix filename, and may be translated -->
          <filename>/My/File</filename> filenames are considered the same
          name.
        </para>
        <para>
          This is most probably what you want if you target some sort of
          <productname>Windows</productname> system.
        </para>
      </listitem>
    </itemizedlist>
    <para>
      Removing a defined basename-based condition is as simple as selecting
      <!-- i18n: "Del" is a key name -->
      it, and pressing <keycap>Del</keycap> (or clicking on 
      <guibutton><inlinegraphic fileref="figures/remove.png"/></guibutton>
      button).
    </para>
    <para>
      By default, the basename-based condition is just one
      <!-- i18n: "must match one of" matches a UI label, may be translated -->
      &#171;&#160;<literal>must match one of *</literal>&#160;&#187; condition.
      As all basenames always match the &#171;&#160;<literal>*</literal>&#160;&#187;
      condition, this just means that basename-based conditions are not
      considered as relevant for the action.
    </para>
  </sect3>

  <sect3 id="usage-conditions-mimetypes">
    <title>Mimetype-based conditions</title>
    <para>
      You may decide that your action will appear depending on the mimetypes
      of the items currently selected in the file-manager: you may define
      that each item of the selection must meet some sort of mimetype; and
      you may simultaneously decide that none of the selected item(s) can
      have some other sort of mimetype.
    </para>
    <para>
      <!-- i18n: "Mimetypes" is a UI label -->
      Click on the <guilabel>Mimetypes</guilabel> tab to show the page
      which will permit you to configure your mimetype-based conditions.
    </para>
    <figure id="cact-FIG-tab-mimetypes">
      <title>Mimetype-based conditions</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-mimetypes-tab.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Shows the tab which lets you define mimetype-based conditions.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
    <para>
      In fact, mimetype-based conditions are built as a list of
      &#171;&#160;must match one of&#160;&#187; and &#171;&#160;must not match any of&#160;&#187; patterns.
      In order for your action to be a candidate regarding these
      mimetype-based conditions, each element of the selection must be
      valid for all the listed conditions: the mimetype of each element
      must match at least one of the defined &#171;&#160;must match one of&#160;&#187; patterns, and
      must not match any of the defined &#171;&#160;must not match any of&#160;&#187; patterns.
    </para>
    <para>
      If at least one element of the selection does not match all the
      defined conditions, then your action will not be displayed.
    </para>
    <para>
      When targeting the selection context menu, your mimetype-based
      conditions will be checked against the currently selected items.
      When targeting the location context menu or the toolbar, your
      mimetype-based conditions will be checked against the mimetype of
      the current location, which happens to be the well known
      <!-- i18n: "inode/directory" is a mimetype, not translatable -->
      &#171;&#160;inode/directory&#160;&#187; mimetype.
    </para>
    <para>
      Defining a new mimetype-based condition involves two steps.
    </para>
    <orderedlist>
      <listitem>
        <para>
          Define the new condition filter.
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <!-- i18n: "Insert" is a key name -->
              Press <keycap>Insert</keycap> or click on 
              <guibutton><inlinegraphic fileref="figures/add.png"/></guibutton>
              button to insert a new condition filter
            </para>
          </listitem>
          <listitem>
            <para>
              Edit the newly inserted condition filter to the mimetype
              you want match.
            </para>
            <para>
              A mimetype must be defined as a
              <!-- i18n: "group/subgroup" stands for a mimetype template, may be translated -->
               <literal>group/subgroup</literal>
              expression.
            </para>
            <tip>
              <para>
                The &#171;&#160;<literal>*</literal>&#160;&#187; wildcard is supported only in some
                situations:
              </para>
              <itemizedlist>
                <listitem>
                  <para>
                    The &#171;&#160;<literal>*/*</literal>&#160;&#187; expression
                    matches all mimetypes. As a convenient shortcut, the
                    &#171;&#160;<literal>*</literal>&#160;&#187; literal is also accepted for this same purpose.
                  </para>
                </listitem>
                <listitem>
                  <para>
                    <!-- i18n: "group" stands for the first part of a mimetype, may be translated -->
                    A <literal>group/*</literal> string
                    <!-- i18n: "group" stands for the first part of a mimetype, may be translated -->
                    matches all subgroups of <literal>group</literal> mimetype.
                  </para>
                </listitem>
                <listitem>
                  <para>
                    <!-- i18n: "subgroup" stands for the second part of a mimetype, may be translated -->
                    The <literal>*/subgroup</literal> string
                    is not accepted as a valid wildcard.
                  </para>
                </listitem>
              </itemizedlist>
            </tip>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>
          Indicates whether this a &#171;&#160;must match one of&#160;&#187; or a &#171;&#160;must not match any of&#160;&#187;
          condition.
        </para>
        <para>
          <!-- "Must match one of" is a UI label -->
          Click on the <guilabel>Must match one of</guilabel> or
          <!-- "Must not match any of" is a UI label -->
          <guilabel>Must not match any of</guilabel> radio button in the
          same row to set the corresponding condition.
        </para>
      </listitem>
    </orderedlist>
    <para>
      Removing a defined mimetype-based condition is as simple as
      <!-- i18n: "Del" is a key name -->
      selecting it, and pressing <keycap>Del</keycap> (or clicking on 
      <guibutton><inlinegraphic fileref="figures/remove.png"/></guibutton>
      button).
    </para>
    <para>
      By default, the mimetype-based condition is just one
      <!-- i18n: "must match one of */*" matches a UI label, and may be translated -->
      &#171;&#160;<literal>must match one of */*</literal>&#160;&#187; condition.
      As all mimetypes always match the &#171;&#160;<literal>*/*</literal>&#160;&#187;,
      this just means that mimetypes are not considered as relevant 
      for the action.
    </para>
    <example>
      <title>Example of usual mimetypes</title>
      <variablelist>
        <varlistentry>
          <term>
            <!-- i18n: "all/all" is a mimetype, not translatable -->
            <literal>all/all</literal>
          </term>
          <listitem>
            <para>
              Matches all items.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <!-- i18n: "all/allfiles" is a mimetype, not translatable -->
            <literal>all/allfiles</literal>
          </term>
          <listitem>
            <para>
              Matches all regular files.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <!-- i18n: "inode/directory" is a mimetype, not translatable -->
            <literal>inode/directory</literal>
          </term>
          <listitem>
            <para>
              Matches only directories.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </example>
  </sect3>

  <sect3 id="usage-conditions-folders">
    <title>Folder-based conditions</title>
    <para>
      You may decide that your action will appear depending on the
      directory the items currently selected in the file-manager are
      located in: you may define that each item of the selection must
      be located in one hierarchy or in another; and you may simultaneously
      decide that none of the selected item(s) can be located in some
      other hierarchy.
    </para>
    <para>
      A folder-based condition must be understood as the specification
      of the hierarchy in which the currently examined item should (or
      should not) stay: this is a pattern on the dirname of the element.
    </para>
    <para>
      <!-- i18n: "Folders" is a UI label -->
      Click on the <guilabel>Folders</guilabel> tab to show the page
      which will permit you to configure your folder-based conditions.
    </para>
    <figure id="cact-FIG-tab-folders">
      <title>Folder-based conditions</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-folders-tab.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Shows the tab which lets you define folder-based conditions.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
    <para>
      In fact, folder-based conditions are built as a list of
      &#171;&#160;must match one of&#160;&#187; and &#171;&#160;must not match any of&#160;&#187; patterns.
      In order for your action to be a candidate regarding these
      folder-based conditions, each element of the selection must be
      valid for all the listed conditions: each element must be located
      in one of the defined &#171;&#160;must match one of&#160;&#187; folders, and must not match
      any of the defined &#171;&#160;must not match any of&#160;&#187; folders.
    </para>
    <para>
      If at least one element of the selection does not match all the
      defined conditions, then your action will not be displayed.
    </para>
    <para>
      When targeting the selection context menu, your folder-based
      conditions will be checked against the dirname of each currently
      selected items.
      When targeting the location context menu or the toolbar,
      your folder-based conditions will be checked against the current
      location.
    </para>
    <para>
      Defining a new folder-based condition involves two steps.
    </para>
    <orderedlist>
      <listitem>
        <para>
          Define the new condition filter.
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <!-- i18n: "Insert" is a key name -->
              Press <keycap>Insert</keycap> or click on 
              <guibutton><inlinegraphic fileref="figures/add.png"/></guibutton>
              button to insert a new condition filter
            </para>
          </listitem>
          <listitem>
            <para>
              Edit the newly inserted condition filter to the folder you
              want match.
            </para>
            <tip>
              <para>
                The &#171;&#160;<literal>*</literal>&#160;&#187; and &#171;&#160;<literal>?</literal>&#160;&#187; characters
                are accepted as wildcards at any level of the defined
                folder filter.
              </para>
            </tip>
          </listitem>
          <listitem>
            <para>
              Or click on
              <guibutton>Browse</guibutton> to select a folder on the file system.
            </para>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>
          Indicates whether this a &#171;&#160;must match one of&#160;&#187; or a &#171;&#160;must not match any of&#160;&#187;
          condition.
        </para>
        <para>
          <!-- i18n: "Must match one of" is a UI label -->
          Click on the <guilabel>Must match one of</guilabel> or
          <!-- i18n: "Must not match any of" is a UI label -->
          <guilabel>Must not match any of</guilabel> radio button in
          the same row to set the corresponding condition.
        </para>
      </listitem>
    </orderedlist>
    <para>
      Removing a defined folder-based condition is as simple as
      <!-- i18n: "Del" is a key name -->
      selecting it, and pressing <keycap>Del</keycap> (or clicking on 
      <guibutton><inlinegraphic fileref="figures/remove.png"/></guibutton>
      button).
    </para>
    <para>
      By default, the folder-based condition is just one
      <!-- i18n: "must match one of /" matches a UI label -->
      &#171;&#160;<literal>must match one of /</literal>&#160;&#187; condition.
      As <literal>/</literal> is always the top of an Unix-like file system,
      then all selected items always match this condition.
    </para>
    <note>
      <para>
        If you target a <productname>Windows</productname> system, then this default value may
        not be what you actually want.
      </para>
    </note>
  </sect3>

  <sect3 id="usage-conditions-schemes">
    <title>Scheme-base-conditions</title>
    <para>
      You may decide that your action will appear depending on the
      schemes of the URIs of the items currently selected in the
      file-manager: you may define that each item of the selection must
      have some scheme; and you may simultaneously decide that none of
      the selected item(s) may have some other scheme.
    </para>
    <para>
      <!-- i18n: "Schemes" is a UI label -->
      Click on the <guilabel>Schemes</guilabel> tab to show the page
      which will permit you to configure your scheme-based conditions.
    </para>
    <figure id="cact-FIG-tab-schemes">
      <title>Scheme-based conditions</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-schemes-tab.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Shows the tab which lets you define scheme-based conditions.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
    <para>
      In fact, scheme-based conditions are built as a list of
      &#171;&#160;must match one of&#160;&#187; and &#171;&#160;must not match any of&#160;&#187; patterns.
      In order for your action to be a candidate regarding these
      scheme-based conditions, each element of the selection must be
      valid for all the listed conditions: the scheme of each element
      must match at least one of the defined &#171;&#160;must match one of&#160;&#187; patterns, and
      must not match any of the defined &#171;&#160;must not match any of&#160;&#187; patterns.
    </para>
    <para>
      If at least one element of the selection does not match all the
      defined conditions, then your action will not be displayed.
    </para>
    <para>
      When targeting the selection context menu, your scheme-based
      conditions will be checked against the currently selected items.
      When targeting the location context menu or the toolbar, your
      scheme-based conditions will be checked against the scheme of
      the current location.
    </para>
    <para>
      Defining a new scheme-based condition involves two steps.
    </para>
    <orderedlist>
      <listitem>
        <para>
          Define the new condition filter.
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <!-- i18n: "Insert" is a key name -->
              Press <keycap>Insert</keycap> or click on 
              <guibutton><inlinegraphic fileref="figures/add.png"/></guibutton>
              button to insert a new condition filter
            </para>
          </listitem>
          <listitem>
            <para>
              Edit the newly inserted condition filter to the scheme you
              want match.
            </para>
            <tip>
              <para>
                Scheme-based conditions only accept &#171;&#160;<literal>*</literal>&#160;&#187; wildcard,
                which stands for &#171;&#160;any scheme&#160;&#187;.
              </para>
            </tip>
          </listitem>
          <listitem>
            <para>Or click on <!-- i18n: "Common" is a UI (button) label --><guibutton>Common</guibutton> to select a scheme among those predefined in <menuchoice><!-- i18n: "Edit" is a menu item --><guimenu>Edit</guimenu><!-- i18n: "Preferences" is a menu item --><guimenuitem>Preferences</guimenuitem></menuchoice>.</para>
            <figure id="cact-FIG-add-scheme">
              <title>Selecting a scheme among predefined defaults</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/cact-new-scheme.png" format="PNG"/>
                  </imageobject>
                  <textobject>
                    <phrase>Show the list of predefined schemes.</phrase>
                  </textobject>
                </mediaobject>
              </screenshot>
            </figure>
            <para>
              A new scheme may only be selected here if it is not
              already defined as a scheme filter.
            </para>
            <para>
              <!-- i18n: "OK" is a UI (button) label -->
              To select a new scheme, click <guibutton>OK</guibutton>,
              or double-click on the desired row.
            </para>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>
          Indicates whether this a &#171;&#160;must match one of&#160;&#187; or a &#171;&#160;must not match any of&#160;&#187;
          condition.
        </para>
        <para>
          <!-- i18n: "Must match one of" is a UI label -->
          Click on the <guilabel>Must match one of</guilabel> or
          <!-- i18n: "Must not match any of" is a UI label -->
          <guilabel>Must not match any of</guilabel> radio button
          in the same row to set the corresponding condition.
        </para>
      </listitem>
    </orderedlist>
    <para>
      Removing a defined scheme-based condition is as simple as selecting
      <!-- i18n: "Del" is a key name -->
      it, and pressing <keycap>Del</keycap> (or clicking on 
      <guibutton><inlinegraphic fileref="figures/remove.png"/></guibutton>
      button).
    </para>
    <para>
      By default, the scheme-based condition is just one
      <!-- i18n: "must match one of *" matches a UI label -->
      &#171;&#160;<literal>must match one of *</literal>&#160;&#187; condition,
      which means that schemes are not relevant for this action.
    </para>
  </sect3>

  <sect3 id="usage-conditions-capabilities">
    <title>Capability-based conditions</title>
    <para>
      Capabilities are some properties that a file may exhibit to the
      user.
    </para>
    <para>
      <!-- i18n: "Local" is a capability keyword, not translatable -->
      But except for the <literal>Local</literal> capability, all others
      depend on the user who executes the command.
    </para>
    <para>
      You may so decide that your action will appear, or not, depending
      on the capabilities of the selected item(s) <abbrev>vs.</abbrev>
      the current user.
    </para>
    <para>
      <!-- i18n: "Capabilities" is a UI label -->
      Click on the <guilabel>Capabilities</guilabel> tab to show the page
      which will permit you to configure your capability-based conditions.
    </para>
    <figure id="cact-FIG-tab-capabilities">
      <title>Capability-based conditions</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-capabilities-tab.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Shows the tab which lets you define capability-based conditions.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
    <para>
      In fact, capability-based conditions are built as a list of
      &#171;&#160;must match all of&#160;&#187; and &#171;&#160;must not match any of&#160;&#187; patterns.
      In order for your action to be a candidate regarding these
      capability-based conditions, each element of the selection must be
      valid for all the listed conditions: the capability of each element
      must match each of the defined &#171;&#160;must match all of&#160;&#187;
      capabilities, and must not match any of the defined &#171;&#160;must not match any of&#160;&#187;
      ones.
    </para>
    <para>
      If at least one element of the selection does not match all the
      defined conditions, then your action will not be displayed.
    </para>
    <para>
      When targeting the selection context menu, your capability-based
      conditions will be checked against the currently selected items.
      When targeting the location context menu or the toolbar, your
      capability-based conditions will be checked against those of the
      current location.
    </para>
    <para>
      Defining a new capability-based condition involves two steps.
    </para>
    <orderedlist>
      <listitem>
        <para>
          Define the new condition filter.
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <!-- i18n: "Insert" is a key name -->
              Press <keycap>Insert</keycap> to insert a new condition
              filter.
            </para>
          </listitem>
          <listitem>
            <para>
              Edit the newly inserted condition filter to the capability
              you want match.
            </para>
          </listitem>
          <listitem>
            <para>
              Or click on
              <guibutton><inlinegraphic fileref="figures/add.png"/></guibutton>
              <!-- i18n: "Adding a new capability" is a UI (dialog title) label -->
              to open the <guilabel>Adding a new capability</guilabel> dialog
              box.
            </para>
            <figure id="cact-FIG-add-capability">
              <title>Managed capabilities</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/cact-new-capability.png" format="PNG"/>
                  </imageobject>
                  <textobject>
                    <phrase>Shows the list of managed capabilities.</phrase>
                  </textobject>
                </mediaobject>
              </screenshot>
            </figure>
            <para>
              A new capability may only be selected here if it is not
              already defined as a capability filter.
            </para>
            <para>
              <!-- i18n: "OK" is a UI (button) label -->
              To select a new capability, click <guibutton>OK</guibutton>,
              or double-click on the desired row.
            </para>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>
          Indicates whether this a &#171;&#160;must match all of&#160;&#187;
          or a &#171;&#160;must not match any of&#160;&#187; condition.
        </para>
        <para>
          <!-- i18n: "Must match all of" is a UI label -->
          Click on the <guilabel>Must match all of</guilabel> or
          <!-- i18n: "Must not match any of" is a UI label -->
          <guilabel>Must not match any of</guilabel> radio button in the
          same row to set the corresponding condition.
        </para>
      </listitem>
    </orderedlist>
    <para>
      Removing a defined capability-based condition is as simple as
      <!-- i18n: "Del" is a key name -->
      selecting it, and pressing <keycap>Del</keycap> (or clicking on 
      <guibutton><inlinegraphic fileref="figures/remove.png"/></guibutton>
      button).
    </para>
    <para>
      By default, the capability-based condition list is empty. This
      means that capabilities are not relevant for this action.
    </para>
  </sect3>

  <sect3 id="usage-conditions-count">
    <title>Selection count condition</title>
    <para>
      You may define that your action will only appear if the current
      selection in the file manager has some precise count, or some
      precise relation with a given count.
    </para>
    <example>
      <title>A selection count use case</title>
      <para>
        If your action consists in displaying the differences between
        two files, you may define here
        <!-- i18n: "Count = (equal to) 2" is a UI label -->
        &#171;&#160;<literal>Count = (equal to) 2</literal>&#160;&#187;.
      </para>
    </example>
    <para>
      <!-- i18n: "Environment" is a UI label -->
      Click on the <guilabel>Environment</guilabel> tab to show the
      page which will permit you to configure your environment-based
      conditions.
    </para>
    <figure id="cact-FIG-tab-environment">
      <title>Environment-based conditions</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-environment-tab.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>
              Shows the tab which lets you define environment-based conditions.
              This includes the selection count configuration, the desktop
              selection, along with the runtime filters.
            </phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
    <para>
      The selection count condition is defined in the
      <guilabel>'Appears if selection contains'</guilabel> frame.
    </para>
    <figure id="cact-FIG-frame-count">
      <title>Selection count condition frame</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-selection-count-frame.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>
              Focus on the <guilabel>Appears if selection contains</guilabel> frame.
            </phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
    <para>
      When targeting the selection context menu, the count condition
      defined here will be checked against the count of currently
      selected items. When targeting the location context menu or
      the toolbar, the count condition will be checked against zero
      because there is no selected item in this case.
    </para>
    <para>
      To define a selection count condition:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <!-- i18n: "Count" is a UI label -->
          Select in the <guilabel>Count</guilabel> drop-down list
          the operator you want apply to the selection count:
        </para>
        <simplelist type="vert">
          <member><literal>&lt;</literal> <termdef>(strictly less than)</termdef></member>
          <member><literal>=</literal> <termdef>(equal to)</termdef></member>
          <member><literal>&gt;</literal> <termdef>(strictly greater than)</termdef></member>
        </simplelist>
      </listitem>
      <listitem>
        <para>
          Enter the reference count you wish.
        </para>
      </listitem>
    </itemizedlist>
    <para>
      The selection count defaults to
          <!-- i18n: "Count > (strictly greater than) 0" is a UI label -->
      &#171;&#160;<literal>Count > (strictly greater than) 0</literal>&#160;&#187;,
      which means that the action will be a candidate to be displayed
      as soon as at least one item is selected in the file manager.
    </para>
  </sect3>

  <sect3 id="usage-conditions-desktop">
    <title>Desktop selection</title>
    <para>
      You may define that your action:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          will always appear,
        </para>
      </listitem>
      <listitem>
        <para>
          or will only appear in some given desktop environments,
        </para>
      </listitem>
      <listitem>
        <para>
          or will not appear in some given desktop environments.
        </para>
      </listitem>
    </itemizedlist>
    <para>
      Only one choice between these three items is possible.
    </para>
    <para>
      <!-- i18n: "Environment" is a UI label -->
      Click on the <guilabel>Environment</guilabel> tab to show the page
      which will permit you to configure your environment-based conditions.
    </para>
    <para>
      The desktop selection is defined in the
      <!-- i18n: "Desktop environment" is a UI label -->
      <guilabel>Desktop environment</guilabel> frame.
    </para>
    <figure id="cact-FIG-frame-desktop">
      <title>Desktop selection frame</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-desktop-environment-frame.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>
              Focus on the <guilabel>Desktop environment</guilabel> frame.
            </phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
    <para>
      To define the desktop environment condition:
    </para>
    <orderedlist>
      <listitem>
        <para>
          First select the type of filter:
        </para>
        <simplelist type="vert">
          <member>should your action always appear, regardless of
           the desktop environment ?</member>
          <member>should your action only appear in some desktop
           environment(s) ?</member>
          <member>should your action never appear in some
           desktop environment(s) ?</member>
        </simplelist>
      </listitem>
      <listitem>
        <para>
          If your action should not always appear, then
          select the relevant desktop environment(s) in the listbox
          in the right side.
        </para>
      </listitem>
    </orderedlist>
    <para>
      The targeted desktop environment condition defaults to
      <!-- i18n: "Always appear" is a UI label -->
      &#171;&#160;<literal>Always appear</literal>&#160;&#187;,
      which means that the action will be a candidate to be displayed
      regardless of the current desktop environment.
    </para>
  </sect3>

  <sect3 id="usage-conditions-executable">
    <title>Executable found condition</title>
    <para>
      You may define that your action will only appear if some
      prerequisite package is installed on your system. This is
      checked here by specifying that a specific file, known or
      at least supposed to be provided by the package, must be
      present on the file system, and executable.
    </para>
    <para>
      <!-- i18n: "Environment" is a UI label -->
      Click on the <guilabel>Environment</guilabel> tab to show the page
      which will permit you to configure your environment-based conditions.
    </para>
    <para>
      The executable found condition is defined in the
      <!-- i18n: "Execution environment" is a UI label -->
      <guilabel>Execution environment</guilabel> frame.
    </para>
    <figure id="cact-FIG-frame-execution-environment">
      <title>Execution environment frame</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-execution-environment-frame.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>
              Focus on the <guilabel>Execution environment</guilabel> frame.
            </phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
    <para>
      To define the relevant file, enter its full filename in the
      <guilabel>Appears if the file is executable</guilabel> entry
      <!-- i18n: "Browse" is a UI (button) label -->
      box, or click on <guibutton>Browse</guibutton> to select a file
      on the file system.
    </para>
    <para>
      Leave the field empty if this condition is not relevant for
      your action.
    </para>
    <tip>
      <para>
        You may embed some parameters in the searched filename.
        These parameters will be dynamically substituted at runtime with
        values which will depend on currently selected item(s). 
      </para>
    </tip>
  </sect3>

  <sect3 id="usage-conditions-dbus">
    <title>D-Bus registration condition</title>
    <para>
      You may define that your action will only appear if some given
      name is registered on the D-Bus system at runtime.
    </para>
    <para>
      <!-- i18n: "Environment" is a UI label -->
      Click on the <guilabel>Environment</guilabel> tab to show the page
      which will permit you to configure your environment-based conditions,
      <!-- i18n: "Execution environment" is a UI label -->
      and focus on <guilabel>Execution environment</guilabel> frame.
    </para>
    <para>
      To define the relevant name, enter it in the
      <guilabel>Appears if the name is registered on D-Bus</guilabel>
      entry box.
    </para>
    <para>
      Leave the field empty if this condition is not relevant for
      your action.
    </para>
    <tip>
      <para>
        You may embed some parameters in the searched name.
        These parameters will be dynamically substituted at runtime with
        values which will depend on currently selected item(s). 
      </para>
    </tip>
  </sect3>

  <sect3 id="usage-conditions-true">
    <title>Customized condition</title>
    <para>
      You may define that your action will only appear if some given
      <!-- i18n: "true" is a literal value, not translatable -->
      command outputs a <literal>true</literal> string on its standard
      output.
    </para>
    <para>
      <!-- i18n: "Environment" is a UI label -->
      Click on the <guilabel>Environment</guilabel> tab to show the page
      which will permit you to configure your environment-based conditions,
      <!-- i18n: "Execution environment" is a UI label -->
      and focus on <guilabel>Execution environment</guilabel> frame.
    </para>
    <para>
      This lets you define your own customized condition filter,
      by writing a small script which outputs, or not, the
      <!-- i18n: "true" is a literal value, not translatable -->
      <literal>true</literal> string on stdout when it is ran.
    </para>
    <para>
      To define the command, enter it in the
      <!-- i18n: "true" is a literal value, not translatable -->
      <guilabel>Appears if the command outputs "true"</guilabel>
      entry box.
    </para>
    <para>
      Leave the field empty if this condition is not relevant for
      your action.
    </para>
    <tip>
      <para>
        You may embed some parameters in the executed filename or its
        options. These parameters will be dynamically substituted at
        runtime with values which will depend on currently selected
        item(s). 
      </para>
    </tip>
  </sect3>

  <sect3 id="usage-conditions-run">
    <title>Running process condition</title>
    <para>
      You may define that your action will only appear if some given
      binary is currently running.
    </para>
    <para>
      <!-- i18n: "Environment" is a UI label -->
      Click on the <guilabel>Environment</guilabel> tab to show the page
      which will permit you to configure your environment-based conditions,
      <!-- i18n: "Execution environment" is a UI label -->
      and focus on <guilabel>Execution environment</guilabel> frame.
    </para>
    <para>
      To define the binary, enter its name in the
      <guilabel>Appears if the binary is running</guilabel>
      <!-- i18n: "Browse" is a UI (button) label -->
      entry box, or click on <guibutton>Browse</guibutton> to select
      a file on the file system.
    </para>
    <note>
      <para>
        Even if you enter here the full filename of a binary, only
        its basename will be searched for in the processes list
        at runtime.
      </para>
    </note>
    <para>
      Leave the field empty if this condition is not relevant for
      your action.
    </para>
    <tip>
      <para>
        You may embed some parameters in the searched name.
        These parameters will be dynamically substituted at runtime
        with values which will depend on currently selected item(s). 
      </para>
    </tip>
  </sect3>
</sect2>

