MultiFilter

Overview	MultiFilter Facts	The MultiFilter Editor
Notes

Overview

This chapter explains how to design new filters based on the MultiFilter filter type. The MultiFilter filter type allows you to group multiple filters into a single action which can be easily invoked from the Filter menu or palette. It allows you to perform multiple actions with a single step and clean complex documents with ease. If you find yourself repeatedly selecting the same filters in the same order to process your documents, you should create one or more MultiFilters to apply the filters automatically.

This chapter assumes that you already know how to create new filters and open filter editors, and that you know how to use the elements common to all filter editors. If not, please read Editing Filters before proceeding.

MultiFilter Facts

MultiFilters are like folders which contain other filters. When you apply a MultiFilter you're applying every single filter within the folder, in order, to the text.

MultiFilters can contain both internal filters and aliases. An internal filter is a filter which exists only within the MultiFilter. It does not appear by itself in the Filter menu or palette, and you cannot apply it except by applying the MultiFilter. No other MultiFilters may call upon it. If you delete the MultiFilter, you delete the internal filters it contains as well.

An alias is an external reference to another filter in the TextSpresso filter library. When a MultiFilter is running and it comes upon an alias it looks that filter up in the TextSpresso filter library and, if it finds it, tells it to do its job. The external filter is an independent filter which shows up in the Filter menu and palette, and which can be applied separately by the user. If you delete a MultiFilter aliased filters are untouched. This is normally how a MultiFilter works, by calling other more basic filters within the library.

Important Note: Currently the aliases of a MultiFilter are nothing more than the name of the filter. If you change the name of a referenced filter all MultiFilters which call upon it will lose track of it. The same is true if you delete a referenced filter or move it into a MultiFilter so that it no longer exists independently within the filter library.

The MultiFilter Editor

The MultiFilter editor consists of a scroll list which lists the names of all of the filters contained in or referenced by the MultiFilter. They are listed in the order in which they are applied, starting at the top and moving down. Next to the scroll list there are 5 buttons.

Adding New Filters: To create a new filter which is internal to the MultiFilter:

1. Click the New button.
2. Select your filter type.
3. Edit the filter using the filter editor which appears and click Save.

The new filter will be saved in the MultiFilter.

Adding Existing Filters: To add an existing filter in the library to the MultiFilter, as an alias:

1. Click the Add button.
2. Select the filters or filters you wish to add.
3. Click OK.

References to the filters will be added, but they will still remain in the TextSpresso filter library.

Deleting Filters & References: To delete a filter or alias from the MultiFilter:

1. Select the filters you wish to remove.
2. Click the Delete button.

If your selection includes internal filters you will be asked if you're sure you want to delete the filters. Decide carefully as you cannot undo this action. Aliases are removed without warning, but the filters remain in the filter library.

Editing Filters: To edit a filter in the MultiFilter:

1. Select the filter you wish to edit. If you select more than one filter, the first filter selected will be edited.
2. Click the Edit button.
3. Edit the filter using the filter editor which appears, and click Save.

This works with both internal filters and aliased filters.

Moving Filters: To move a filter into or out of a MultiFilter:

1. Select the filter or filters to move.
2. Click the Move button.
3. You will be asked if you want to move the filters into the filter library or into the MultiFilter. Make your selection.

Filters which are moved from the library to the MultiFilter are duplicated, which means they leave a copy of themselves behind in the library, and they replace the aliases that were previously in the MultiFilter. Filters moved from the MultiFilter to the library leave behind aliases in the MultiFilter.

Changing The Filter Order: To change the order in which the filters are applied simply drag and drop the filters you want to move within the scroll list.

Notes

(Under Construction)

MultiFilters may themselves contain and reference other MultiFilters. Currently there's no hard limit placed upon the 'depth' of a MultiFilter, i.e. how many levels of filters it can contain. But you should be careful not to design MultiFilters with too many levels. We may have to place a limit on the depth of MultiFilters in the future.

Also, you need to be careful not to call a MultiFilter which in turn calls its caller. For instance, you don't want MultiFilter A to call MultiFilter B if B already calls A. This will create an endless loop and, currently, will crash the program with a stack overflow.