Navigation: ABC Library Reference > StepLocatorClass >====== StepLocatorClass Overview  ====== |    |
The StepLocatorClass is a LocatorClass that accepts a single character search value, and does a continuous (wrap around) search starting from the current item so you can, for example, find the next item that begins with the search value (say, 'T'), then continue to the next item that begins with the same search value, etc. If there are no matching values, the step locator proceeds the the next highest item.
Use a Step Locator when the search field is a STRING, CSTRING, or PSTRING, a single character search is sufficient (a step locator is not appropriate when there are many key values that begin with the same character), and you want the search to take place immediately upon the end user's keystroke. Step Locators are not appropriate for numeric keys.
StepLocatorClass Concepts
A Step Locator is a single-character locator with no locator control required.
The StepLocatorClass 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 StepLocatorClass to locate and scroll to the nearest matching item.
When the BrowseClass LIST has focus and the user types a character, the BrowseClass object advances the list to the next matching item (or the subsequent item if there is no match).
StepLocatorClass Relationship to Other Application Builder Classes
The BrowseClass uses the StepLocatorClass to locate and scroll to the nearest matching item. Therefore, if your program's BrowseClass objects use a Step Locator, your program must instantiate the StepLocatorClass for each use. Once you register the StepLocatorClass object with the BrowseClass object (see BrowseClass.AddLocator), the BrowseClass object uses the StepLocatorClass object as needed, with no other code required. See the Conceptual Example.
StepLocatorClass ABC Template Implementation
The ABC BrowseBox template generates code to instantiate the StepLocatorClass for your BrowseBoxes. The StepLocatorClass 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.
StepLocatorClass Source Files
The StepLocatorClass source code is installed by default to the Clarion \LIBSRC folder. The StepLocatorClass source code and its respective components are contained in:
| ABBROWSE.INC | StepLocatorClass declarations | |
| ABBROWSE.CLW | StepLocatorClass method definitions |
StepLocatorClass 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 StepLocatorClass 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 .
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
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 StepLocatorClass !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,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