<!DOCTYPE page
[<!ENTITY % balsa SYSTEM "balsa.entities"> %balsa; ]>
<page xmlns="http://projectmallard.org/1.0/" type="topic"
id="win-run-filters">
  <info>
    <link type="guide" xref="index" />
  </info>
  <title>The Select Filters Window</title>
  <p>This window is divided in two lists: the left one displays all
  available filters, and the right part displays all filters to be
  applied on the mailbox (the name of which is shown in the window
  title). See the
  <link xref="win-filters">filters window</link> section to see
  how to set up filters.</p>
  <p>The right list has three columns. The first one contains the
  filters name. The two others tells you if the filter will be
  automatically applied: e.g. if a dot is displayed in the second
  column
  (<gui>On reception</gui>), this tells you that whenever new
  messages arrived in this mailbox, they will be filtered by the
  corresponding filter (Note: the filter is applied only on the new
  messages, not the entire mailbox; this is similar to the use of
  procmail). In the same way, if a dot is displayed in the third
  column
  (<gui>On exit</gui>), the filter will be applied to the entire
  mailbox when you exit &Balsa;.</p>
  <p>Note: the
  <gui>On exit</gui> feature is not yet implemented.</p>
  <p>When you tell &Balsa; to apply several filters on the same
  mailbox (i.e. when you put several filters in the right list),
  only the first match counts: the filters are applied in the
  specified order and the first that matches on the current message
  will be applied but not the following ones.</p>
  <p>There are two buttons between the filters lists:</p>
  <list>
    <item>
      <p>The
      <gui>Add</gui> button: moves the selected filters from the
      left list to the right one, adding more filters to be applied
      to the mailbox.</p>
    </item>
    <item>
      <p>The
      <gui>Remove</gui> button: removes the currently selected
      filter in the right list and puts it back in the left
      list.</p>
    </item>
  </list>
  <p>The
  <gui>Up</gui> and
  <gui>Down</gui> buttons under the right list serve to reorder the
  filters that are to be applied. This is a sort of priority
  between filters, because if several filters could match the
  current message, only the first one will be applied. The
  <gui>Apply Now</gui> button applies all filters of the right list
  to the entire mailbox immediately (be patient, this can take a
  quite a long time on big mailboxes or remote ones).</p>
  <p>You can also use this dialog to apply a filter to a mailbox
  without actually attaching it to the mailbox. Select one or more
  filters in the left hand list, and click the
  <gui>Apply Selected</gui> button below that list.</p>
  <p>There are three buttons below the filters lists:</p>
  <list>
    <item>
      <p>The
      <gui>OK</gui> button: saves the list of filters associated to
      the mailbox. Note that this does not apply the filters to the
      mailbox. It is useful only when you have set up automatic
      filters, or when you have to manually apply a lot of filters
      frequently to this mailbox: the next time &Balsa; will
      reload the saved filters and you will only have to press the
      <gui>Apply</gui> button.</p>
    </item>
    <item>
      <p>The
      <gui>Cancel</gui> button: this discards any changes and closes
      the dialog box.</p>
    </item>
    <item>
      <p>The
      <gui>Help</gui> button: opens this help window.</p>
    </item>
  </list>
</page>
