Clarion Community Help

The EntryLocatorClass is a LocatorClass with an input control (ENTRY, COMBO, or SPIN). An Entry Locator is a multi-character locator that activates when the locator control is accepted (not upon each keystroke).

Use an Entry Locator when you want a multi-character search on numeric or alphanumeric keys and you want to delay the search until the user accepts the locator control. This delayed search reduces network traffic and provides a smoother search in a client-server environment.

EntryLocatorClass Concepts

The EntryLocatorClass lets you specify a locator control and a sort field on which to search (the free key element) for a BrowseClass object. The BrowseClass object uses the EntryLocatorClass to locate and scroll to the nearest matching item.

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 EntryLocatorClass object advances the BrowseClass object's LIST to the nearest matching record.

EntryLocatorClass Relationship to Other Application Builder Classes

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

EntryLocatorClass ABC Template Implementation

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

EntryLocatorClass Source Files

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

EntryLocatorClass 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 an EntryLocatorClass 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 EntryLocatorClass            !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

!initialize the StStep object

StStep.Init(+ScrollSort:AllowAlpha,ScrollBy:Runtime)

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

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

!initialize the locator object

StLocator.Init(?ST:STATECODE,ST:STATECODE,1,BrowseSt)

!set a column to browse

BrowseSt.AddField(ST:STATECODE,BrowseSt.Q.ST:STATECODE)

!set a column to browse

BrowseSt.AddField(ST:STATENAME,BrowseSt.Q.ST:STATENAME)

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