<?xml version="1.0" encoding="utf-8"?>
<sect2 id="usage-where">
  <title>Locating the action</title>
    <figure id="cact-FIG-target-location-where">
      <title>Target configuration</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-target-location.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Shows the three fields which let you configure the target of your action.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
  <para>
    <productname>Caja</productname> file manager may display your action in different places,
    depending on what you will request here, and if some item is currently
    selected (or not).
  </para>
  <para>
    <!-- i18n: "Action" is a UI label -->
    Click on the <guilabel>Action</guilabel> tab to show the page
    which will permit you to configure the locations your action
    targets.
  </para>

  <sect3 id="usage-where-selection">
    <title>Targeting the selection context menu</title>
    <para>
      When <guilabel>Display item in selection context menu</guilabel>
      is checked, then your action will be a candidate to be displayed in 
      <productname>Caja</productname>' context menu as soon as at least one item is selected in 
      the file manager. Your action will so deal with currently selected
      item(s).In order to be
      actually displayed, all the conditions defined in
      your candidate action must be met by each item currently selected
      in the <productname>Caja</productname> file manager. 
    </para>
    <tip>
      <para>
        When an action targets the selection context menu, and is actually 
        displayed in <productname>Caja</productname>' context menu, then it is also displayed
        in <productname>Caja</productname>' <guimenu>Edit</guimenu> menu.
      </para>
    </tip>
    <para>
      This target is checked by default.
    </para>
  </sect3>

  <sect3 id="usage-where-location">
    <title>Targeting the location context menu</title>
    <para>
      When <guilabel>Display item in location context menu</guilabel> checkbox
      is activated, then your action will be a candidate to be displayed in 
      <productname>Caja</productname>' context menu when the file manager selection is empty.
      Your action will so deal with currently displayed location.
      In order to be
      actually displayed, all the conditions defined in
      your candidate action must be met by the location currently displayed
      in the <productname>Caja</productname> file manager. 
    </para>
    <tip>
      <para>
        When an action targets the location context menu, and is actually 
        displayed in <productname>Caja</productname>' context menu, then it is also displayed
        in <productname>Caja</productname>' <guimenu>File</guimenu> menu.
      </para>
    </tip>
  </sect3>

  <sect3 id="usage-where-toolbar">
    <title>Targeting the toolbar</title>
    <para>
      When <guilabel>Display item in the toolbar</guilabel> checkbox
      is activated, then your action will be a candidate to be displayed in 
      <productname>Caja</productname>' toolbar.
    </para>
    <para>
      Actions displayed in the toolbar only deal with the location which
      is currently displayed in the file-manager, not with the items which
      may be currently selected (or not). In order to be displayed, all the
      conditions defined in your candidate action must so be met by the
      current location. 
    </para>
  </sect3>

  <sect3 id="usage-where-notes">
    <title>Notes</title>

    <formalpara>
      <title>If your action is to be displayed in a context menu</title>
      <para>
        Whether it is the selection context menu or the location
        context menu, and both in <productname>Caja</productname>' context menus and in 
        <guimenu>File</guimenu> or <guimenu>Edit</guimenu> menus, it
        will be displayed as
      </para>
    </formalpara>
    <itemizedlist>
      <listitem>
        <para>
          <!-- i18n: "Context label" is a UI label -->
          the <guilabel>Context label</guilabel> as a label,
        </para>
      </listitem>
      <listitem>
        <para>
          <!-- i18n: "Icon" is a UI label -->
          the <guilabel>Icon</guilabel>,
        </para>
      </listitem>
      <listitem>
        <para>
          these two properties being associated with the
          <!-- i18n: "Tooltip" is a UI label -->
          <guilabel>Tooltip</guilabel>.
        </para>
      </listitem>
    </itemizedlist>
    <note>
      <para>
        Depending of the exact configuration of your desktop environment,
        the icon may or may not be displayed in front of the label in
        the menu.
      </para>
    </note>
    <tip>
      <para>
        You may embed some parameters in the label, the icon name or the
        tooltip. These parameters will be dynamically substituted at runtime
        with values which will depend on currently selected item(s). 
      </para>
    </tip>

    <formalpara>
      <title>If your action is to be displayed in the toolbar</title>
      <para>
        It will be displayed as
      </para>
    </formalpara>
    <itemizedlist>
      <listitem>
        <para>
          <!-- i18n: "Toolbar label" is a UI label -->
          the <guilabel>Toolbar label</guilabel> as a label,
        </para>
      </listitem>
      <listitem>
        <para>
          <!-- i18n: "Icon" is a UI label -->
          the <guilabel>Icon</guilabel>,
        </para>
      </listitem>
      <listitem>
        <para>
          these two properties being associated with the
          <!-- i18n: "Tooltip" is a UI label -->
          <guilabel>Tooltip</guilabel>.
        </para>
      </listitem>
    </itemizedlist>
    <note>
      <para>
        Depending of the exact configuration of your desktop environment,
        the toolbar label may or may not be displayed in front of the icon
        in the toolbar.
      </para>
    </note>
    <tip>
      <para>
        The toolbar label defaults to the same label as
        those used in menus. By unchecking the
        <guilabel>Use same label for icon in the toolbar</guilabel>
        checkbox you can define a label specific to the
        toolbar, which is usually shorter that those defined for the
        menus.
      </para>
    </tip>
    <tip>
      <para>
        You may embed some parameters in the toolbar label, the icon
        name or the tooltip. These parameters will be dynamically
        substituted at runtime with values which will depend on currently
        selected item(s). 
      </para>
    </tip>

    <formalpara>
      <title>Defining several targets</title>
      <para>
        An action may target the selection context menu, the location context
        menu and the toolbar, or one or more of these.
      </para>
    </formalpara>

    <formalpara>
      <title>Defining no target at all</title>
      <para>
        If no target is defined,
        <abbrev>i.e.</abbrev> if the three checkboxes are unchecked,
        then your action will never be displayed.
      </para>
    </formalpara>
  </sect3>
</sect2>
