Evolution Filter Classes

This is an overview of the classes related to filtering mail in Evolution. Most of the classes can be found in the filter/ directory, but some are located in mail/.

Main Classes

EFilterElement

• Base class of all filter elements.
  • Roughly speaking, a EFilterElement is equivalent to a variable in a search expression
    • for example, for the "Specific header" filter, the user must specify the name of the header, the predicate (e.g. 'contains', 'starts with', etc), and the search string. These three things are all represented as EFilterElements. The full expression is a EFilterPart.
  • Has a virtual get_widget() function which returns a widget representation of the filter element. Would be nice if filter UI wasn't so tightly intertwined with filter definition.

  • Has a validate() vfunc that requires a GtkWindow* parent argument for displaying errors. Should probably just take a GError** ?

EFilterPart

• A EFilterPart can contain one or more EFilterElements and is generally constructed by reading a filter definition from an XML file
  • A EFilterPart is composed of the filter elements required to match against a certain thing. For example, for the 'sender' filter part will match against the sender of an email, and it contains an 'option' filter element (for selecting the predicate of the filter: "contains", "not contains", "starts with", etc), and an input filter element for specifying the word to match against.
• Has problematic validate() and get_widget() functions (see above)

EFilterRule

• A FilterRule is a set of EFilterParts that are combined together. They can be grouped by 'any' or 'all'. For 'any', if one EFilterPart matches a message, then the match is successful. For 'all', all EFilterParts must match the message in order for the match to be successful.

• Has problematic validate() and get_widget() functions (see above)

ERuleContext

• An object that loads the possible filter elements and rules from the filesystem and enables the creation new filter elements, etc.
• First it loads the 'system' filters. Then it loads the 'user' filters. These are both defined in an XML format on disk.

  • The system filter file can contain both a <partset> and a <ruleset>. The user filter file generally only contains a <ruleset>. These elements are described in more detail below.

  • <partset>

    • This element contains definitions for one or more filter parts. Conceptually, these are like filter templates. They describe a named filter part with named parameters. They also specify how to generate an s-expression from the filter part.

  • <ruleset>

    • This element contains the definitions for one or more filter rules. Conceptually, a filter rule is a saved search (or filter). A filter rule can be made up of one or more filter parts which are combined together with a grouping of 'any' or 'all'. Each part in the rule references the name of a part in the <partset> (see above) and provides values for each of the named parameters.

• On its own, a filter rule defined in a <ruleset> element does not contain enough information to construct the s-expression that will do the actual filtering. So the ERuleContext object's job is to provide context for the saved filter rules. In order to construct the s-expression for a saved user search (or filter), The rule context looks up the filter part from the system file and then plugs in the values that were specified in the user file.

Filter Elements

EFilterCode

• A filter element for specifying a Sexp expression (i.e. "code")
  • Subclass of EFilterInput

EFilterColor

• A filter element for specifying a particular color

  • Represented in the UI as a ColorButton

EFilterDatespec

• A filter element for specifying a date
  • Represented in the UI as a button that displays a dialog and allows the user to select several different date representations

EFilterFile

• A filter element that allows the user to select a file

  • Represented in the UI by a FileChooserButton

EFilterInput

• A filter element for specifying a string value

  • Represented in the UI as a text entry (GtkEntry)

EFilterInt

• A filter element for specifying an integer

  • Represented in the UI as a SpinButton

EFilterOption

• A filter element for selecting one option out of a list of alternatives
  • Represented in the UI as a combobox

Mail Filtering Specializations

EMFilterContext

• subclass of ERuleContext
• Adds concept of 'actions' that can be added to filters
• Adds ability to create a couple extra EFilterElement types: "folder", "system-flag", "score", "source"

EMFilterFolderElement

• A filter element for specifying the uri of a folder
  • Represented in the UI as a folder selection button

EMFilterRule

• Subclass of EFilterRule
• Adds concept of 'actions' that can be added to filter rules

EMFilterSourceElement

• A (pseudo-)filter element for specifying source folders to be filtered
  • Represented in the UI as a combobox for selecting the current source url (?)
• This doesn't really fit the concept of a EFilterElement very well, because it doesn't actually filter anything, it only specifies the input objects to be filtered. In other words, the virtual build_code() function is totally empty (e.g. it doesn't emit any Sexp expressions). As such, it feels a bit out of place in the EFilterElement heirarchy
  • Also, I don't actually see this element used anywhere...

UI Classes

ERuleEditor

• A Dialog for adding/editing filter rules

EMFilterEditor

• Subclass of ERuleEditor
• Support for editing all rules supported by EMFilterContext