FILTER <Name="filter name"> [<Reverse=Yes|No>] [<Join=None|or|and>]
The FILTER command enables you to select and apply a saved filter.
Name = The saved filter name.
Reverse = This parameter is now deprecated, but left in for backwards compatibility. This parameter was added before the option was enabled in the GUI and saved settings. So if your saved filter already has the reverse option ticked, this option has no effect and will [B]not[/B] reverse/negate it. Yes - To invert/reverse the filter (That is, give you all the waypoints that do not match your selection criteria). No - do not reverse. The default value is No
Join = Action to perform with the current filter. The default of "none" meaning the Filter command does not do any "joining" and behaves exactly the same as setting a new filter. Any other value will compare the current filter against this filter using the "join" type and produce a new subset/filter (which will then become the current filter and you can do another "join" and so forth). See notes at end for a full explanation of Join.
Note: If the filter does not return any waypoints it will automatically be canceled and your subset will contain all waypoints. You can test for this situation using the $_FilterCount system variable. For example:
FILTER Name="User Flagged"
IF $_FilterCount > 0
... do some action
ELSE
PAUSE Msg="No waypoints in filter, action canceled"
ENDIF
Alpha List Category List
Join notes
This matrix represents the results of applying the corresponding "bitwise" operation. Read 1 as meaning the waypoint satisfies the condition of the filter and 0 meaning it does not.
AND
Current Filter 0 1 0 1
AND filter 1 1 0 0
Result 0 1 0 0
OR
Current Filter 0 1 0 1
OR Filter 1 1 0 0
Result 1 1 0 1
Another explanation that some may find easier to understand:
AND - Resulting waypoints exists in both filters (intersection)
OR - Resulting waypoints exists in either filter (union)
For those that prefer a graphical overview take the following example:
"Found Caches" and "Traditionals" are 2 stored filters, which are joined together with one of the available joining operators.
Macro code in GSAK would be:
FILTER Name="Found Caches" FILTER Name="Traditionals" Join="and | or " |
While joining, you can specify to REVERSE the second condition. Macro code in GSAK would be:
FILTER Name="Found Caches" FILTER Name="Traditionals" Reverse=Yes Join="and | or " |
By using multiple Filter commands with the join parameter you are not limited to just 2 filters. For example, to find waypoints that exist in all three filters:
Filter Name=Filter1 If $_FilterCount > 0 Filter Name=Filter2 Join=and endif if $_FilterCount > 0 Filter Name=Filter3 Join=and Endif If $_FilterCount = 0 Pause Msg="Bummer, no waypoints that match all 3 filters" EndIf |
Note1: The current filter (or any joined filter) may have initially returned zero records. However, the current default behaviour in GSAK is to clear the filter and return the full sub set of caches. When using the "join" parameter, GSAK respects the initial result of the filter (zero records) when it does the join operation. Like normal filters you can always test the final result using the $_FilterCount system variable.
Note2: Because of the complexity of a "joined" filter, the resulting filter is "static" (similar behaviour to setting colours with the COLOR command). That means if you change any waypoints in your "joined filter" you must run the same sequence of "join" filters to determine which waypoints should logically now be in your filter.
Related: CancelFilter MFilter
Alpha List Category List