FilterLocatorClass Overview

Top  Previous  Next

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.

 

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 Conceptual Example.

FilterLocatorClass ABC Template Implementation

The ABC BrowseBox template generates code to instantiate the FilterLocatorClass for your BrowseBoxes. The FilterLocatorClass objects are called BRWn::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