CNavigator

Heritage

Description

Usage

Enums

Protected Data Members

Public Methods

Constructor and Destructor Methods

Movement Methods

Jump Methods

Tab Stop Methods

Focus Methods

Adapter Methods

Protected Methods

Heritage

Subclasses: CRadioNavigator, CWindowNavigator, CFaceNavigator

Description

Usage

• CTabStops
  A navigator owns an ordered list of CTabStops, representing the tab order of the navigator. A navigator can have any number of tab stops.

• Movements
  A set of possible movements where a key event might take the focus. A dynamic mapping of key strokes to movements may be created by the user. For example, one may want to map the right-arrow key (K_RIGHT) to a right movement (M_Right). Navigate() responds to a given Movement.

• EndJump
  A set of decisions to take when tabbing past the last (or first) tab stop in the list. Options are: EJ_Circular, EJ_None, or EJ_Out. EJ_Out is an attribute used by those navigators that behave as if there is seamless navigation between one navigator and a sibling.

JumpInto

JI_Selected	Move down to selected tab stop
JI_End	Move down to home or end

Protected Data Members

Public Methods

CNavigator(CSubview* theEnclosure = NULL);

Constructor for the navigator, which takes a pointer to the enclosure where keyboard navigation is being added.

virtual ~CNavigator();

Destructor for the navigator which deletes all stored tab stops.

virtual CCourse GetMovement(const CKey& theKey) const;

Returns a CCourse ,object describing the movement taken by the navigator when a key event described by theKey is received.

void DefineMovement(const CKey& theKey, CCourse theCourse);

Used to define which direction the navigator should take when it receives a key event like the one described by theKey.

void SetEndJump(EndJump);

Describes what to do when the user tabs past the last tab stop. Options include:

EndJump GetEndJump() const;

Returns the EndJump action taken when the user tabs past the last tab stop.

void SetJumpInto(JumpInto);
JumpInto GetJumpInto() const;

Sets and gets the type of tab stop accessed when jumping into the navigator. Options include:

Tab Stop Methods

int TabStopCount() const;

Returns the number of tab stops in the navigator.

CTabStop* GetTabStopAt(int theIndex) const;

Returns the nth (n=theIndex) tab stop registered with the navigator, or NULL if theIndex is out of range.

void RemoveTabStop(CTabStop* theTabStop);

Removes theTabStop from the navigator, provided it was already inserted.

void ClearTabStops();

Removes and destroys all registered tab stops.

void InsertTabStop(int theIndex , CTabStop* theTabStop);

Inserts theTabStop at theIndex, before any item already stored in that location. The tab stop is consumed by the navigator and destroyed in the navigator's destructor.

void AppendTabStop(CTabStop* theTabStop);

Appends theTabStop to the end of the navigator. The tab stop is consumed by the navigator and destroyed in the navigator's destructor.

void InsertSubNavigator(int theIndex, CNavigator* theSubNavigator);

Creates a tab stop for theSubNavigator and inserts it at theIndex, before any item already stored in that location. The subnavigator is consumed by the navigator and destroyed in the navigator's destructor.

void AppendSubNavigator(CNavigator* 
	theSubNavigator);

Creates a tab stop for theSubNavigator and appends it to the end of the navigator. The subnavigator is consumed by the navigator and destroyed in the navigator's destructor.

void MoveTabStop(int theIndex, CTabStop* theTabStop);

Relocates theTabStop to the theIndex, before any item already stored in that location.

BOOLEAN AppendSubviews(const CSubview* theEnclosure);

Adds tab stops for all views directly nested in the enclosure (one level deep). The method handles CRadioGroup objects ,nested in theEnclosure as a special case, adding a special tab stop subnavigator that includes radio buttons nested inside the group.

CTabStop* FindTabStopHavingView(const CView*  theView);

Returns a pointer to the tab stop that manages theView. Returns NULL if no such tab stop exists.

void AddHotKeyToView(const CKey& theHotKey, CView* theView);

Adds a hot key which makes the navigator switch focus to theView. Whenever a key event is received like the event described by theHotKey, the navigator will provide theView with focus.

void InitFocus();

Initializes the focus to the first tab stop in the navigator. The methods should be called after the views of a window are created and registered as tab stops in the navigator.

BOOLEAN DoKey(int theKey, BOOLEAN itIsShifted, 
	BOOLEAN itIsControl);
BOOLEAN DoKey(const CKey&);

Delegate methods that handle keyboard events as required by the navigator.

void DeactivateCurrentTabStop();

Removes focus from the currently selected tab stop.

virtual BOOLEAN CurrentTabStopSearch(
	CNavigator*& theCurrentNav,
	CTabStop*& theCurrentTabStop);

Returns a pointer to theCurrent navigator and tab stop which contain focus. The current navigator could be the navigator itself or a nested navigator.

virtual BOOLEAN HotKeyTabStopSearch(
	const CKey& theHotKey, 
	CNavigator*& foundNav, 
	CTabStop*& foundTabStop);

Returns the navigator and tab stop managing the view that should receive focus when theHotKey is received as an event.

virtual void DeactivateTabStop(CTabStop* theTabStop);

Decativates the view associated with theTabStop, assuming that view has focus.

virtual void ActivateTabStop(CTabStop* theTabStop);

Changes focus to the view managed by theTabStop.

static CNavigatorManager* Manager();

Returns a pointer to the global navigator manager.

virtual BOOLEAN Navigate(const CCourse& theCourse,
	const CKey& theKey, CTabStop*, 
	CNavigator*& aNewNav, CTabStop*& aNewTabStop );

Finds the destination of the next tab stop:
• Finds the next destination tab stop relative to a current tab stop in the navigation tree defined by this navigator and all navigators to which it is linked.

• This default navigation method normalizes its tab stops into a 1-dimensional list representing the tab order: M_Up means the same as M_Left, M_DownMost means M_RightMost, etc.

• Typically, the navigation starts at the navigator servicing the current tab stop, and works its way up and out of the tree in search of a navigator that can process the key event. In particular, if this navigator does not recognize the key pressed, control is deferred to the parent navigator.

Parameters:
• theCourse

The movement that this navigator interprets from theKey, or M_None if the key is unrecognized.

• theKey

The user-entered key. This key is passed to other navigators during navigation, so that each navigator can interpret the key accordingly.

• theTabStop

The reference tab stop. This variable has two states:

theTabStop != NULL - theTabStop is a pointer to this navigator's tab stop list. This is the tab stop from which to navigate.

theTabStop == NULL - This navigator is called from this navigator's parent navigator and tab stop, which sends only M_*Most movements to its children.

• foundNav

The new destination navigator to jump to. It is the navigator immediately servicing foundTabStop.

• foundTabStop

The new destination tab stop. Once found, this deep tab stop is percolated up through the recursive calls.

Returns:

TRUE if the navigation took place, FALSE otherwise, in which case the key event still needs to be processed.

BOOLEAN Navigate(const CKey&, CTabStop*, 
	CNavigator*& aNewNav, 
	CTabStop*& aNewTabStop);

See Navigate() above.

const CSubview* GetEnclosure() const;
void SetEnclosure(const CSubview* theEnclosure);

Sets and gets the enclosure to which navigation has been added.

virtual CTabStop* ConstructNavTabStop(CNavigator*);
virtual CTabStop* ConstructViewTabStop(CView*);
virtual NRadioNavigator* ConstructRadioNavigator(CRadioGroup*);

These three methods act as virtual constructors (factory methods) for the internal creation of tab stops and subnavigators.

static RWBoolean TestTrue(void*, void*);
static RWBoolean TabStopTestViewIs(const CTabStop*, const CView*);
static RWBoolean TabStopTestCanActivate(const CTabStop*, void*);
static RWBoolean TabStopTestIsActive(const CTabStop*, void*);
static RWBoolean TabStopTestXvtWindowIs(const CTabStop*, void*);
static RWBoolean TabStopHasHotKey(const CTabStop*, const CKey*);

These are internal iteration helper functions used by the RWtestGenerics collection iterator. They are used internally by methods such as FindTabStop, TestTabStop, TraverseCurrentTabStops, etc.

virtual BOOLEAN TestTabStop(FindDirection, 
	CTabStop* theTabStop, CNavigator*& foundNav, 
	CTabStop*& foundTabStop, 
	BOOLEAN UpdateCurrentTabStop = FALSE, 
	RWtestGeneric theTabStopTest = 0, 
	void* theTabStopTestData = NULL, 
	RWtestGeneric theNavTest = 0, 
	void* theNavTestData = NULL);
virtual BOOLEAN FindTabStop(FindDirection, 
	FindEntryMethod, CTabStop* theStart, 
	CNavigator*& foundNav, CTabStop*& foundTabStop, 
	BOOLEAN UpdateCurrentTabStop = FALSE, 
	RWtestGeneric theTabStopTest = 0, 
	void* = NULL, RWtestGeneric theNavTest = 0, 
	void* = NULL);

CNavigator::FindTabStop - Finds a tab stop somewhere within this navigator

CNavigator::TestTabStop - Tests or finds a tab stop

The "Swiss Army Knife" pair of tab stop search methods, providing tab stop traversal with an assortment of modes and filters. These are recursive pairs of functions: each calls the other for deep, subnavigator traversal.

Parameters:

• theDirection (FindDirection)

Indicate forward or backward traversal through the tab stops. This direction will be used for all recursive deep searches as well.

• theEntryMethod (FindEntryMethod)

theEntryMethod, applies to the top level call only: All deep recursive calls use FE_None Can be one of:

FE_None: Start at beginning (or ending) tab stop.

FE_AtTabStop: Start at theStart tab stop.
FE_AfterTabStop: Start at the tab stop after (or, if theDirection is FD_Backward, before) theStart.

• theStart (const CTabStop*)

Reference tab stop for FindEntryMethod. Ignored if theEntryMethod is FE_None

• foundNav (CNavigator*&)

The parent navigator of the matching tab stop, if found.

• foundTabStop (CTabStop*&)

The tab stop, if found.

• UpdateCurrentTabStop (BOOLEAN)

TRUE if update each navigator's itsCurrentTabStop (which is why this method is not const).

• theTabStopTest (RWtestGeneric);

• Test applied to each encountered tab stop. If this callback is NULL or if (*theTabStopTest)(aTabstop, theTabStopTestData) returns TRUE, then a successful tab stop is found and this FindTabStop terminates, returning TRUE.

• theTabStopTestData (void*)

theTabStopTest's data.

• theNavTest (RWtestGeneric)

Test applied to each encountered tab stop that has a subnavigator. If (*theNavTest)(aSubNavigator, theNavTestData) returns TRUE on that tab stop's subnavigator, then its FindTabStop is called with these parameters. If it is successful, returns TRUE.

• theNavTestData (void*)

theNavTest's data.

Returns:
• TRUE if a valid tab stop is found, in which case foundNav and foundTabStop point to these matching items.

• FALSE otherwise, in which case foundNav and foundTabStop are unchanged.

  Note: These functions are made virtual to allow a subclassed CNavigator to expand search side effects at any depth (level).

virtual CTabStop* PickTabStop(RWtestGeneric theTabStopTest = 0, 
	void* = NULL, 
	RWtestGeneric theNavTest = 0, 
	void* = NULL);

Selects the "current" tab stop of this navigator.

Note: Subclasses have freedom of choice as to which tab stop is current: For example, the current NRadioNavigator tab stop would be the view of the tab stop whose id is itsRadioGroup->GetSelectedButton();

BOOLEAN TraverseCurrentTabStops(CNavigator*& foundNav, 
	CTabStop*& foundTabStop, 
	RWtestGeneric theTabStopTest = 0, 
	void* = NULL);

Traverses the itsCurrentTabStop chain of tab stops until a match is found.

Parameters:

• foundNav (CNavigator*&)

The parent navigator of the matching tab stop, if found.

• foundTabStop (CTabStop*&)

The tab stop, if found.

• theTabStopTest (RWtestGeneric)

Test applied to each encountered tab stop. If this callback is NULL or if (*theTabStopTest)(aTabstop, theTabStopTestData) returns TRUE, then a successful tab stop is found and this FindTabStop terminates, returning TRUE.

• theTabStopTestData (void*)

theTabStopTest's data.

Returns:
• TRUE if a matching current tab stop is found, in which case foundNav and foundTabStop point to these matching items.

• FALSE otherwise, in which case foundNav and foundTabStop are unchanged.

CTabStop* FindFocusable(FindDirection, 
	FindEntryMethod, CTabStop* theTabStop);

Used by Navigate() to locate a tab stop that can receive focus.