Clarion Community Help

The IncrementalLocatorClass is an EntryLocatorClass that activates on each additional search character added to the search value (not when the locator control is accepted).

Use an Incremental locator when you want a multi-character search on numeric or alphanumeric keys and you want the search to take place immediately upon the end user's keystroke.

IncrementalLocatorClass Concepts

An IncrementalLocator is a multi-character locator, with no locator control required (but strongly recommended).

The locator control may be a STRING, ENTRY, COMBO, or SPIN, however, any control other than a STRING causes the Incremental locator to behave like an Entry locator–the search is delayed until the control is accepted.

With a STRING control (or no control), when the BrowseClass LIST has focus, keyboard input characters are automatically added to the locator's search value string for each keystroke, and the BrowseClass immediately advances to the nearest matching record. The Backspace key removes characters from the locator's search value string.

We strongly recommend using a STRING control as the Incremental Locator control for the following reasons:

So the search occurs immediately with each keystoke, and

So the user can see the value for which the BrowseClass object is searching.

IncrementalLocatorClass Relationship to Other Application Builder Classes

The BrowseClass uses the IncrementalLocatorClass to locate and scroll to the nearest matching item. Therefore, if your program's BrowseClass objects use an Incremental Locator, your program must instantiate the IncrementalLocatorClass for each use. Once you register the IncrementalLocatorClass object with the BrowseClass object (see BrowseClass.AddLocator), the BrowseClass object uses the IncrementalLocatorClass object as needed, with no other code required. See the Conceptual Example.

IncrementalLocatorClass ABC Template Implementation

The ABC BrowseBox template generates code to instantiate the IncrementalLocatorClass for your BrowseBoxes. The IncrementalLocatorClass 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.

IncrementalLocatorClass Source Files

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

IncrementalLocatorClass 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 IncrementalLocatorClass 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)

     STRING(@s2),AT(29,4),USE(ST:STATECODE)  !locator control

     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  IncrementalLocatorClass   !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 = ?StList           !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