| **Navigation:**  [[abc library reference.htm|ABC Library Reference]] > FilterLocatorClass >====== FilterLocatorClass Overview {{c6h0009.jpg|C6H0009.jpg}} ====== | [[filterlocatorclass.htm|{{btn_prev_n.gif|Previous page}}]][[abc library reference.htm|{{btn_home_n.gif|Return to chapter overview}}]][[filterlocatorclass properties.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

The FilterLocatorClass is an IncrementalLocatorClass that filters or limits the result set of the BrowseClass object's underlying view. That is, it not only locates matching items in the result set, but it limits the result set to only those items.

Use a Filter Locator when you want a multi-character search on alphanumeric keys and you want to //minimize network traffic//.

**FilterLocatorClass Concepts**

A Filter Locator is a multi-character locator, with no locator control required (but strongly recommended). The FilterLocatorClass lets you specify a locator control and a field on which to search for a BrowseClass object. The locator control accepts a search value which the FilterLocatorClass applies to the search field. The search can match the search value beginning with the first position of the search field ("begins with" search), or it can match the search value anywhere within the search field ("contains" search).

When the end user places one or more characters in the locator control, then //accepts //the control by pressing TAB, pressing a locator button, or selecting another control on the screen, the FilterLocatorClass creates a filter expression based on the input search value and applies the filter. Each additional (incremental) search character supplied results in a smaller, more refined result set. For example, a search value of 'A' returns all records from 'AA' to 'Az'; a search value of 'AB' returns all records from 'ABA' to 'ABz', and so on.

The Filter Locator determines the boundaries for the search based on the user specified search value. The implementation of the boundaries depends on the database--for SQL databases, the Filter Locator uses a LIKE; for ISAM databases it supplies upper and lower bounds.

{{notebox.jpg|NoteBox.jpg}}

**The Filter Locator performs very well on SQL databases and on high order key component fields; however, performance may suffer if applied to non-key fields or low order key fields of non-SQL databases.**

**FilterLocatorClass Relationship to Other Application Builder Classes**

The BrowseClass optionally uses the FilterLocatorClass. Therefore, if your BrowseClass objects use a FilterLocator, then your program must instantiate the FilterLocatorClass for each use. Once you register the FilterLocatorClass object with the BrowseClass object (see BrowseClass.AddLocator), the BrowseClass object uses the FilterLocatorClass object as needed, with no other code required. See the [[filterlocatorclass overview.htm#apslywb|Conceptual Example]].

**FilterLocatorClass ABC Template Implementation**

The ABC BrowseBox template generates code to instantiate the FilterLocatorClass for your BrowseBoxes. The FilterLocatorClass objects are called BRW//n//::Sort#:Locator, where //n// is the template instance number and # is the sort sequence (id) number. As this implies, you can have a different locator for each BrowseClass object sort order.

You can use the BrowseBox's **Locator Behavior** dialog (the **Locator Class** button) to derive from the EntryLocatorClass. The templates provide the derived class so you can modify the locator's behavior on an instance-by-instance basis.

**FilterLocatorClass Source Files **

The FilterLocatorClass source code is installed by default to the Clarion \LIBSRC folder. The specific FilterLocatorClass source code and its respective components are contained in:

|  | ABBROWSE.INC | FilterLocatorClass declarations |
|  | ABBROWSE.CLW | FilterLocatorClass method definitions |

**FilterLocatorClass Conceptual Example**

The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate a BrowseClass object and related objects, including a Locator object. The example initializes and page-loads a LIST, then handles a number of associated events, including scrolling, updating, and locating records.

Note that the WindowManager and BrowseClass objects internally handle the normal events surrounding the locator.

**   PROGRAM**

**   INCLUDE('ABWINDOW.INC')          !declare WindowManager class**

**   INCLUDE('ABBROWSE.INC')          !declare BrowseClass and Locator**

**   MAP**

**   END**

**State        FILE,DRIVER('TOPSPEED'),PRE(ST),THREAD**

**StateCodeKey KEY(ST:STATECODE),NOCASE,OPT**

**Record        RECORD,PRE()**

**STATECODE      STRING(2)**

**STATENAME      STRING(20)**

**              END**

**             END**

**StView    VIEW(State)            !declare VIEW to process**

**          END**

**StateQ       QUEUE               !declare Q for LIST**

**ST:STATECODE  LIKE(ST:STATECODE) **

**ST:STATENAME  LIKE(ST:STATENAME)  **

**ViewPosition  STRING(512) **

**             END**

**Access:State CLASS(FileManager)     !declare Access:State object**

**Init          PROCEDURE**

**             END**

**Relate:State CLASS(RelationManager) !declare Relate:State object**

**Init          PROCEDURE**

**             END**

**VCRRequest  LONG(0),THREAD**

**StWindow WINDOW('Browse States'),AT(,,123,152),IMM,SYSTEM,GRAY**

**      PROMPT('Find:'),AT(9,6)**

**      ENTRY(@s2),AT(29,4),USE(ST:STATECODE)**

**      LIST,AT(8,5,108,124),USE(?StList),IMM,HVSCROLL,FROM(StateQ),|**

**      FORMAT('27L(2)|M~CODE~@s2@80L(2)|M~STATENAME~@s20@')**

**     END**

**ThisWindow CLASS(WindowManager)      !declare ThisWindow object**

**Init        PROCEDURE(),BYTE,PROC,VIRTUAL**

**Kill        PROCEDURE(),BYTE,PROC,VIRTUAL**

**           END**

**BrowseSt  CLASS(BrowseClass)         !declare BrowseSt object**

**Q          &StateQ**

**          END**

**StLocator  FilterLocatorClass        !declare StLocator object**

**StStep     StepStringClass           !declare StStep object**

** CODE**

** ThisWindow.Run()                    !run the window procedure**

**ThisWindow.Init  PROCEDURE()         !initialize things**

**ReturnValue    BYTE,AUTO**

** CODE**

** ReturnValue = PARENT.Init()         !call base class init**

** IF ReturnValue THEN RETURN ReturnValue. **

** Relate:State.Init                   !initialize Relate:State object**

** SELF.FirstField = ?ST:STATECODE     !set FirstField for ThisWindow**

** SELF.VCRRequest &= VCRRequest       !VCRRequest not used**

** Relate:State.Open                   !open State and related files**

** !Init BrowseSt object by naming its LIST,VIEW,Q,RelationManager & WindowManager**

** BrowseSt.Init(?StList,StateQ.ViewPosition,StView,StateQ,Relate:State,SELF)**

** OPEN(StWindow)**

** SELF.Opened=True**

** BrowseSt.Q &= StateQ                !reference the browse QUEUE**

** StStep.Init(+ScrollSort:AllowAlpha,ScrollBy:Runtime)!initialize the StStep object**

** BrowseSt.AddSortOrder(StStep,ST:StateCodeKey)    !set the browse sort order**

** BrowseSt.AddLocator(StLocator)      !plug in the browse locator**

** StLocator.Init(?ST:STATECODE,ST:STATECODE,1,BrowseSt)!initialize the locator object**

** BrowseSt.AddField(ST:STATECODE,BrowseSt.Q.ST:STATECODE) !set a column to browse**

** BrowseSt.AddField(ST:STATENAME,BrowseSt.Q.ST:STATENAME) !set a column to browse**

** SELF.SetAlerts()                    !alert any keys for ThisWindow**

** RETURN ReturnValue**

**ThisWindow.Kill  PROCEDURE()         !shut down things**

**ReturnValue    BYTE,AUTO**

** CODE**

** ReturnValue = PARENT.Kill()         !call base class shut down**

** IF ReturnValue THEN RETURN ReturnValue.**

** Relate:State.Close                  !close State and related files**

** Relate:State.Kill                   !shut down Relate:State object**

** GlobalErrors.Kill                   !shut down GlobalErrors object**

** RETURN ReturnValue**