<!DOCTYPE page
[<!ENTITY % balsa SYSTEM "balsa.entities"> %balsa; ]>
<page xmlns="http://projectmallard.org/1.0/" type="topic"
id="win-filters">
  <info>
    <link type="guide" xref="index" />
  </info>
  <title>The Filters Window</title>
  <p>This window is divided in two parts: the left part is the list
  of all filters. When you select one of them, the right part
  displays its properties. The right part is a two-page notebook
  (the
  <link xref="win-filters#wf-match-page">match page</link>, and the
  <link xref="win-filters#wf-action-page">action page</link>); their
  descriptions follow.</p>
  <p>There are two buttons under the filters list:</p>
  <list>
    <item>
      <p>The
      <gui>New</gui> button: you click on it to create a new filter;
      the filter is initially named “New Filter”, and contains no
      condition. Then you fill in the different fields in the
      notebook pages (in particular remember to change the name of
      the filter), add the conditions that will describe how this
      filter matches a message, and to confirm the modifications
      push the
      <gui>Apply</gui> button on the right hand side of the Filters
      window.</p>
    </item>
    <item>
      <p>The
      <gui>Remove</gui> button: removes the currently selected
      filter.</p>
    </item>
  </list>
  <section id="wf-match-page">
    <title>The Match Page</title>
    <p>Each filter is made of one or several conditions; each
    condition represents a test to be applied to the messages. The
    results of these tests is then combined following the type of
    operation specified:</p>
    <list>
      <item>
        <p>AND: all condition tests must be true to make the
        match.</p>
      </item>
      <item>
        <p>OR: one condition test must be true to make the
        match.</p>
      </item>
    </list>
    <p>Then the page displays the name of the filter and the
    conditions that describes how the filters matches a message.
    The list displays the type of the conditions (the conditions
    will be described later):</p>
    <list>
      <item>
        <p>
        <gui>Simple</gui>: the match is done by a simple substring
        test.</p>
      </item>
      <item>
        <p>
        <gui>Regular expression</gui>: the match uses regular
        expressions on the message headers.</p>
      </item>
      <item>
        <p>
        <gui>Date interval</gui>: the match is done by checking if
        the date of the message is within certain bounds.</p>
      </item>
      <item>
        <p>
        <gui>Flag condition</gui>: the match is done by checking
        the flags of the message: unread, replied, deleted,
        flagged.</p>
      </item>
    </list>
    <p>The three buttons under the list allows you to edit the
    selected condition, add a new one, or remove one. Editing or
    creating a condition is done in the
    <link xref="win-filters#win-condition">condition window</link>, which
    pops up when you click on the
    <gui>Edit</gui> or the
    <gui>New</gui> button.</p>
    <p>The two buttons under the notebook at the right hand side of
    the window lets you manipulate the currently selected filter.
    The
    <gui>Apply</gui> button is used to confirm the modifications you
    have made on any field. If you make changes and select another
    filter without first clicking on the
    <gui>Apply</gui> button, all your changes will be lost.</p>
    <p>The
    <gui>Revert</gui> button cancels all previous changes: the
    current filter is reverted to its state just before the last
    click on the
    <gui>Apply</gui> button.</p>
  </section>
  <section id="wf-action-page">
    <title>The Action Page</title>
    <p>This page describes the actions to take in case the filter
    matches. First you specify the notification to inform you that
    the one or several messages has matched the filter in the
    <gui>Notification</gui> frame. Then in the
    <gui>Action</gui> frame you tell what to do with the matching
    messages. You can ask &Balsa; to copy or move them to any
    mailbox, or to send them to the trash can. The other actions
    are not yet implemented.</p>
  </section>
  <section id="win-condition">
    <title>The Condition Window</title>
    <p>This window is used to edit an existing condition or to
    create a new one. It displays all the information needed to
    describe the condition, it is launched when you click on the
    <gui>Edit</gui> or
    <gui>New</gui> buttons under the conditions list in the match
    page of the notebook in the right part of the
    <link xref="win-filters">filters window</link>.</p>
    <p>This window is made of three frames:</p>
    <list>
      <item>
        <p>The
        <gui>Match Fields</gui> frame: it's a set of check boxes, one
        per match field. For example if you want to match all
        messages that was sent by hotmail users, you just have to
        check the
        <gui>From</gui> box, or if you want to match all messages
        about &Balsa;, check the
        <gui>Subject</gui> box.</p>
        <note style="warning">
          <p>Be careful with
          <gui>Body</gui> match, this can take time for large
          messages.</p>
        </note>
        <p>For advanced use you can also specify directly the name
        of the header to match on. A standard example the
        “X-Mailer” is a header added to your message by the MUAs
        with their name and versions.</p>
        <p>The
        <gui>All</gui> button will check all boxes, whereas the
        <gui>Clear</gui> button will uncheck all boxes (as you might
        have guessed).</p>
        <p>If you specify several headers, a message will match
        this condition if one of the headers matches. For example if
        you want to filter all messages talking about &Balsa;,
        you should check the
        <gui>Body</gui> and the
        <gui>Subject</gui> boxes, so that all mails with the word
        “Balsa” in its subject or its body will match.
        You can also, if you're fed up with &Balsa; ;-), match
        all mails that do NOT contain the word
        “Balsa” in their subject and in their body
        neither. See the description of the search types to see how
        to do this.</p>
      </item>
      <item>
        <p>The
        <gui>Search Type</gui> frame: it's a list of the different
        condition types. You choose
        <gui>Simple</gui>,
        <gui>Regular expression</gui>,
        <gui>Date interval</gui>, or
        <gui>Flag condition</gui>. Your choice will change the
        third frame so that it displays the fields needed by the
        type of match chosen.</p>
      </item>
      <item>
        <p>This part depends on the search type you've chosen:</p>
        <list>
          <item>
            <p>
            <gui>Simple</gui> type: a text entry lets you input the
            string to look for (case does not matter, the search is
            case-insensitive). The button lets you specify if a
            message matches when the string is or is NOT a
            substring of the specified headers, the sentence above
            the text entry will be updated accordingly.</p>
          </item>
          <item>
            <p>
            <gui>Regular expression</gui>: you can input a list of
            regular expressions. You type your regular expression
            in the text entry, then you click on the
            <gui>Add</gui> button to put it into the list. Of course
            the
            <gui>Remove</gui> button destroys the selected regular
            expression in the list. The last button
            <gui>One matches/None matches</gui> lets you specify
            when a message matches the condition: when one of the
            regular expression matches or when none matches. The
            sentence above the list will be updated accordingly.</p>
          </item>
          <item>
            <p>
            <gui>Date interval</gui>: you can input the interval by
            the mean of the two text entries. A blank entry means
            no bound. The button tells to match when the message
            date is within the bounds or not. The sentence above
            the text entries will be updated accordingly.</p>
          </item>
          <item>
            <p>
            <gui>Flag condition</gui>: the four check boxes let you
            select which messages will match this condition. If you
            want to match all replied OR unread messages, check the
            corresponding boxes. The button let you specify that
            the match will be done when none of the specified flags
            are set, the sentence above the check boxes will be
            updated accordingly. For example if you want to filter
            all read and replied messages, check the
            <gui>unread</gui> and
            <gui>replied</gui> boxes, and click on the button.</p>
          </item>
        </list>
      </item>
    </list>
  </section>
</page>
