BrowseClass Overview

Top  Previous  Next

The BrowseClass is a ViewManager with a user interface for navigating through the result set of the underlying VIEW.

BrowseClass Concepts

The BrowseClass uses several related classes to provide standard browse functionality--that is, file-loaded or page-loaded lists with automatic scrolling, searching, ranging, filtering, resets, conditional colors, conditional icons, etc. These classes can be used to build other components and functionality as well.

Added to this standard functionality, is Edit-In-Place--that is, you can update the VIEW's primary file by typing directly into the browse list. No separate update procedure is required, and the updates are appropriately autoincremented, referentially constrained, and field validated.

Following are the classes that provide this browse functionality. The classes and their respective roles are:

BrowseClass

Browse list "supervisor" class

 

StepClass

Scrollbar/Progress Bar base class

 

 

LongStepClass

Numeric Runtime distribution

 

RealStepClass

Numeric Runtime distribution

 

StringStepClass

Alpha/Lastname distribution

 

CustomStepClass

Custom distribution

LocatorClass

Locator base class

 

 

StepLocatorClass

Step Locator

 

EntryLocatorClass

Entry Locator

 

IncrementalLocatorClass

Incremental Locator

 

FilterLocatorClass

Filter Locator

EditClass

Edit-In-Place

 

The BrowseClass is fully documented in the remainder of this chapter. Each related class is documented in its own chapter.

BrowseClass Relationship to Other Application Builder Classes

The BrowseClass is closely integrated with several other ABC Library objects--in particular the WindowManager and ToolbarClass objects. These objects register their presence with each other, set each other's properties, and call each other's methods as needed to accomplish their respective tasks.

The BrowseClass is derived from the ViewManager, plus it relies on many of the other Application Builder Classes (RelationManager, FieldPairsClass, ToolbarClass, PopupClass, etc.) to accomplish its tasks. Therefore, if your program instantiates the BrowseClass, it must also instantiate these other classes. Much of this is automatic when you INCLUDE the BrowseClass header (ABBROWSE.INC) in your program's data section. See the Conceptual Example.

BrowseClass ABC Template Implementation

The ABC Templates automatically include all the classes and generate all the code necessary to support the functionality specified in your application's Browse Procedure and BrowseBox Control templates.

The templates derive a class from the BrowseClass for each BrowseBox in the application. By default, the derived class is called BRW# where # is the BrowseBox control template instance number. This derived class object supports all the functionality specified in the BrowseBox template.

The derived BrowseClass is local to the procedure, is specific to a single BrowseBox and relies on the global file-specific RelationManager and FileManager objects for the browsed files. The templates provide the derived class so you can customize the BrowseBox behavior on a per-instance basis. See Control Templates--BrowseBox for more information.

BrowseClass Source Files

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

ABBROWSE.INC

BrowseClass declarations

ABBROWSE.CLW

BrowseClass method definitions

ABBROWSE.TRN

BrowseClass translation strings

BrowseClass Conceptual Example

The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate a BrowseClass object and related objects. The example initializes and page-loads a LIST, then handles a number of associated events, including searching, scrolling, and updating. When they are initialized properly, the BrowseClass and WindowManager objects do most of the work (default event handling) internally.

  PROGRAM

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

  INCLUDE('ABBROWSE.INC')               !declare BrowseClass

  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 for BrowseSt

         END

 

StateQ       QUEUE                  !declare Q for LIST

ST:STATECODE  LIKE(ST:STATECODE)

ST:STATENAME  LIKE(ST:STATENAME)

ViewPosition  STRING(512)

            END

 

GlobalErrors ErrorClass             !declare GlobalErrors object

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

 

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

 

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@')

         BUTTON('&Insert'),AT(8,133),USE(?Insert)

         BUTTON('&Change'),AT(43,133),USE(?Change),DEFAULT

         BUTTON('&Delete'),AT(83,133),USE(?Delete)

        END

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.

GlobalErrors.Init                       !initialize GlobalErrors object

Relate:State.Init                       !initialize Relate:State object

SELF.FirstField = ?StList               !set FirstField for ThisWindow

SELF.VCRRequest &= VCRRequest           !VCRRequest not used

SELF.Errors &= GlobalErrors             !set error handler for ThisWindow

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

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

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

BrowseSt.InsertControl=?Insert          !set the control to add records

BrowseSt.ChangeControl=?Change          !set the control to change records

BrowseSt.DeleteControl=?Delete          !set the control to delete records

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

 

Access:State.Init PROCEDURE

CODE

PARENT.Init(State,GlobalErrors)

SELF.FileNameValue = 'State'

SELF.Buffer &= ST:Record

SELF.AddKey(ST:StateCodeKey,'ST:StateCodeKey',0)

 

Relate:State.Init PROCEDURE

CODE

Access:State.Init

PARENT.Init(Access:State,1)