#include <CTracker.h>

Inheritance diagram for CTracker:

Public Member Functions
	CTracker (IPMUnknown *boss)

virtual void	SetupTracker (IControlView theControlView, ISnapTo theSnapper=NULL, IItemContext *context=NULL)

virtual IControlView *	QueryControlView () const

virtual bool16	IsEnabled ()

virtual bool16	IsTracking ()

virtual void	EnableTracking ()

virtual void	DisableTracking ()

virtual bool16	BeginTracking (IEvent *theEvent)

virtual void	HandleContinueTracking (const GSysPoint &where)

virtual void	ContinueTracking (const PBPMPoint &where, bool16 mouseDidMove)

virtual bool16	EndTracking (IEvent *theEvent)

virtual void	AbortTracking (IEvent *theEvent)

virtual void	TimerMessage (int32 flags)

virtual bool16	WantTimer (ClassID trackerTimerBoss)

Public Member Functions inherited from ITracker
void	SetupTracker (IControlView *theControlView)

void	SetupSpecialTracker (IControlView theControlView, ISnapTo theSnapper, IItemContext *context)

Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0

virtual void	AddRef () const =0

virtual void	Release () const =0

Protected Member Functions
virtual void	Initialize (IEvent *theEvent)

virtual bool16	DoBeginTracking (IEvent *theEvent)

virtual bool16	DoEndTracking (IEvent *theEvent)

virtual void	NotifyBeginTracking (const PMPoint &startPt, IDynamicTrackerData::TrackingEffect effect=IDynamicTrackerData::kUnknown)

virtual void	NotifyContinueTracking (const PMPoint &startPt, const PMPoint &endPoint, IDynamicTrackerData::TrackingEffect effect=IDynamicTrackerData::kUnknown)

virtual void	NotifyEndTracking (const PMPoint &startPt, const PMPoint &endPoint, IDynamicTrackerData::TrackingEffect effect=IDynamicTrackerData::kUnknown)

virtual IDynamicTrackerData::TrackingEffect	GetTrackingEffect (IDynamicTrackerData::TrackingState state)

virtual void	PushEventHandler ()

virtual void	PopEventHandler ()

virtual bool16	WantsToAutoScroll (const PMPoint &currentPoint)

virtual PMPoint	AutoScroll (const PMPoint &scrollBy, const PMPoint &scrolledPoint)

virtual void	GlobalToPasteboard (const GSysPoint &thePoint, PBPMPoint &convertedPoint)

virtual PMPoint	PasteboardToGlobal (const PBPMPoint &pbPoint)

virtual IPanorama *	QueryPanorama (IControlView *pView) const

virtual void	DisableUpdates ()

virtual void	EnableUpdates ()

void	DeselectAllItems ()

virtual void	ComputeAdjustedPoint (PMPoint &adjustedPoint)

void	InitializeModalCursor ()

void	ChangeModalCursor (const CursorSpec &spec)

void	UpdateModalCursor ()

void	ReleaseModalCursor ()

virtual uint32	GetMouseMoveDelay ()

virtual uint32	GetMouseSteadyDelay ()

virtual bool16	AdjustPoint (PBPMPoint &point)

void	StartTimer (ClassID trackerTimerBoss, uint32 milliSeconds, uint32 mouseMoveDelay=kDefaultMouseMoveDelay, uint32 mouseSteadyDelay=kDefaultMouseSteadyDelay)

void	StopTimer (ClassID trackerTimerBoss)

bool16	GetTimerFlags ()

void	SetTimerFlags (int32 flags)

uint32	GetElapsedTime ()

virtual IDataBase *	GetTrackingDataBase () const

Static Protected Member Functions
static void	DeactivatePageItem ()

Protected Attributes
IControlView *	fControlView

IDataBase *	fDataBase

IItemContext *	fItemContext

ISnapTo *	fSnapTo

SnapType	fSnapType

bool16	fIsTracking

bool16	fWantsToAutoScroll

PMPoint	fPreviousPoint

PMPoint	fFirstPoint

GSysPoint	fFirstGlobalWhere

uint32	fFirstTicks

bool16	fEnabled

IRulerData *	fHorzRuler

IRulerData *	fVertRuler

AcquireModalCursor *	fModalCursor

AutoBusyCursor *	fAutoBusyCursor

uint32	fOldSchedulerMask

int32	fTimerFlags

K2Vector< ITrackerTimer * >	fTimerPtrs

Detailed Description

Concrete implementation for trackers.

A tracker monitors mouse movement while an object is being manipulated by a tool and provides visual feedback in the layout view. It makes the changes to the objects being manipulated using commands. A tool may have one or more trackers but only a single tracker will be active at any one time.

Tracking occurs when the user manipulates objects (or widgets) using the mouse. Tracking behavior is context sensitive and depends on the selected tool, where and on what the mouse down event occurs. Tracking the mouse can occur in order to create something or select something, or move a control in a widget for example.

ITracker is the main controlling interface for a tracker. It is the interface used by clients of the tracker to focus the tracker on a view and to which overall control is passed so the mouse can be tracked. It manages and controls all other interfaces in the boss.

Member Function Documentation

virtual void CTracker::AbortTracking ( IEvent * theEvent )

virtual

Override this method to provide any special behavior required if the tracker was aborted in the middle of tracking. For example the PlaceTextTracker needs to abort if a menu is selected after the tracker is enabled

Parameters

theEvent [IN] the associated event

Implements ITracker.

Reimplemented in CPathCreationTracker, CLayoutTracker, and CSliderTracker.

virtual bool16 CTracker::AdjustPoint ( PBPMPoint & point )

protectedvirtual

The CTracker will call this method to adjust the raw point. The current implemention will use fSnapTo or ComputeAdjustedPoint() to do this. Some classes may find it useful to override this method if they wish to only adjust/Snap one dimension.

Parameters

point to adjust

Returns: kTrue if the point changed

virtual PMPoint CTracker::AutoScroll	(	const PMPoint &	scrollBy,
		const PMPoint &	scrolledPoint
	)

protectedvirtual

Scroll the view by the indicated amount

Parameters

scrollBy	[IN] how much to scroll by. Typical value obtained from the panorama associated with this tracker's view.
scrolledPoint	[IN] the point from HandleContinueTracking that caused the autoscroll

Returns: PMPoint the amount that the panorama scrolled

See Also: QueryPanorama; IPanorama.h; GetAutoScrollDelta; ScrollBy

Reimplemented in CPathCreationTracker.

virtual bool16 CTracker::BeginTracking ( IEvent * theEvent )

virtual

Start tracking the mouse. Usually called as the result of a mouse down event.

Parameters

theEvent [IN] the associated event

Implements ITracker.

Reimplemented in SnapTracker, CPathCreationTracker, CLayoutTracker, and CSliderTracker.

void CTracker::ChangeModalCursor ( const CursorSpec & spec )

protected

Call this method to switch the cursor while tracking. Make sure CTracker::BeginTracking() gets called first, however.

Parameters

spec	[IN] the cursor spec to change to

virtual void CTracker::ComputeAdjustedPoint ( PMPoint & adjustedPoint )

protectedvirtual

Override if the base class wants to change the input value in any way. This method is called before snap to is called The implementation in CTracker computes the ruler adjusted value, if the tracker is tracking in the layout view

Parameters

adjustedPoint [IN/OUT] the adjusted value

virtual void CTracker::ContinueTracking	(	const PBPMPoint &	where,
		bool16	mouseDidMove
	)

virtual

The default implementation does nothing; client code will likely override this. Called after BeginTracking() and before EndTracking(). ContinueTracking is called repeatedly even when the mouse is not moving (to support things like auto scrolling)

Parameters

where	[IN] current location of mouse ptr
mouseDidMove	[IN] kTrue if mouse-event generated this call, kFalse otherwise (e.g. auto-scrolling)

Implements ITracker.

Reimplemented in CPathCreationTracker, CLayoutTracker, and CSliderTracker.

void CTracker::DeselectAllItems ( )

protected

Deselect all types of selection in the fControlView

See Also: ISelectionManager.h; DeselectAll

virtual void CTracker::DisableTracking ( )

virtual

Turns off tracking; this should rarely be overridden by client code. Removes the tracker's eventhandler from the stack, releases the mouse capture. Also stops the timer (fMouseTrackerThread). Called automatically in base class EndTracking (and AbortTracking).

Implements ITracker.

virtual void CTracker::DisableUpdates ( )

protectedvirtual

Helper method called in base class during BeginTracking to turn off updates.

See Also: ILayoutUIUtils.h; DisableUpdateAllDocumentViews

virtual bool16 CTracker::DoBeginTracking ( IEvent * theEvent )

protectedvirtual

A return value of kTrue means "continue tracking". i.e. this tracker did not simply spawn a different one

Parameters

theEvent [IN] event that is behind this call

Implements ITracker.

Reimplemented in CLayoutTracker.

virtual bool16 CTracker::DoEndTracking ( IEvent * theEvent )

protectedvirtual

Called by EndTracking, does the action end tracking would do without ending the tracking.

Parameters

theEvent [IN] event that is behind this call

Returns: bool16 return value appears to be unused.

Implements ITracker.

virtual void CTracker::EnableTracking ( )

virtual

Turn on tracking; means that the tracker's eventhandler is on the stack ready to accept events. Called automatically in base class BeginTracking.

Implements ITracker.

virtual void CTracker::EnableUpdates ( )

protectedvirtual

Helper method called in base class during EndTracking to turn on updates.

See Also: ILayoutUIUtils.h; EnableUpdateAllDocumentViews

virtual bool16 CTracker::EndTracking ( IEvent * theEvent )

virtual

Tracking is completed. Tidy up and post any dynamic commands.

Parameters

theEvent [IN] the associated event

Implements ITracker.

Reimplemented in CPathCreationTracker, CLayoutTracker, and CSliderTracker.

virtual uint32 CTracker::GetMouseMoveDelay ( )

inlineprotectedvirtual

Called to initialize tracker timer

virtual uint32 CTracker::GetMouseSteadyDelay ( )

inlineprotectedvirtual

Called to initialize tracker timer

bool16 CTracker::GetTimerFlags ( )

inlineprotected

Timer management flags, set when an tracker timer is run, typically when an ITrackerTimer's RunTask method is called.

virtual IDynamicTrackerData::TrackingEffect CTracker::GetTrackingEffect ( IDynamicTrackerData::TrackingState state )

protectedvirtual

If IDynamicTrackerData is present, use it to notify document observers. This function is called by NotifyBeginTracking(), NotifyContinueTracking(), and NotifyEndTracking() whenever a specific tracking state is not provided to determine what effect to use for notifying. (i.e. when effect is IDynamicTrackerData::kUnknown). By default kBeginTracking -> kAffectsXY, kContinueTracking -> kAffectsXYWH, kEndTracking -> kAffectsXYWH

Parameters

state,one of kNotTracking, kBeginTracking, kContinueTracking, kEndTracking, kAbortTracking.

Returns: - returns IDynamicTrackerData::TrackingEffect, IDynamicTrackerData::kAffectsXY by default.

virtual void CTracker::GlobalToPasteboard	(	const GSysPoint &	thePoint,
		PBPMPoint &	convertedPoint
	)

protectedvirtual

Convert a point from global system coordinate to pasteboard point.

Parameters

thePoint	[IN] input point
convertedPoint	[OUT] output point

Reimplemented in CSliderTracker.

virtual void CTracker::HandleContinueTracking ( const GSysPoint & where )

virtual

Called by the tracker event handler. This is a cover routine for ContinueTracking for things like autoscrolling. Generally this is not overridden in sub-classes of CTracker.

Parameters

where [IN] the global system point at time of call. Can convert to a pasteboard coordinate via GlobalToPasteboard method in CTracker.h.

Implements ITracker.

virtual void CTracker::Initialize ( IEvent * theEvent )

protectedvirtual

Subclasses of CTracker can override Initialize and DoBeginTracking() instead of overriding BeginTracking(). This way they are guaranteed that Initialize has been called first, and the thread only gets started if DoBeginTracking() returns kTrue.

Previously, overrides of BeginTracking() had to call the inherited method at the end, thereby losing the benefit of any initialization done by the base class.

Set initial fields. Called before DoBeginTracking()

Parameters

theEvent [IN] the event at time of call

Implements ITracker.

Reimplemented in CLayoutTracker.

void CTracker::InitializeModalCursor ( )

protected

Called internally during BeginTracking to set up the modal cursor during life of tracker.

virtual bool16 CTracker::IsEnabled ( )

virtual

Determine if tracking is turned on.

Implements ITracker.

virtual bool16 CTracker::IsTracking ( )

virtual

Determine if this tracker is actively tracking at present time. Means that the tracker's BeginTracking() method has been called, i.e. the tracker is actually tracking the mouse.

Returns: kTrue if tracking (BeginTracking() has been called), kFalse otherwise

Implements ITracker.

virtual void CTracker::NotifyBeginTracking	(	const PMPoint &	startPt,
		IDynamicTrackerData::TrackingEffect	effect = `IDynamicTrackerData::kUnknown`
	)

protectedvirtual

If IDynamicTrackerData is present, use it to notify document observers. Can pass effect directly, or GetTrackingEffect will be used to determine it if effect is IDynamicTrackerData::kUnknown.

Parameters

startPt
endPoint
effect,How	tracker affects x, y, w, h, etc values. See IDynamicTrackerData::TrackingEffect.

virtual void CTracker::NotifyContinueTracking	(	const PMPoint &	startPt,
		const PMPoint &	endPoint,
		IDynamicTrackerData::TrackingEffect	effect = `IDynamicTrackerData::kUnknown`
	)

protectedvirtual

If IDynamicTrackerData is present, use it to notify document observers. Can pass effect directly, or GetTrackingEffect will be used to determine it if effect is IDynamicTrackerData::kUnknown.

Parameters

startPt
endPoint

virtual void CTracker::NotifyEndTracking	(	const PMPoint &	startPt,
		const PMPoint &	endPoint,
		IDynamicTrackerData::TrackingEffect	effect = `IDynamicTrackerData::kUnknown`
	)

protectedvirtual

If IDynamicTrackerData is present, use it to notify document observers. Can pass effect directly, or GetTrackingEffect will be used to determine it if effect is IDynamicTrackerData::kUnknown.

Parameters

startPt
endPoint
effect,How	tracker affects x, y, w, h, etc values. See IDynamicTrackerData::TrackingEffect.

virtual PMPoint CTracker::PasteboardToGlobal ( const PBPMPoint & pbPoint )

protectedvirtual

Convert a point from pasteboard point to global system coordinate.

Parameters

pbPoint [IN] input point

Returns: PMPoint converted point in pasteboard coordinates

virtual void CTracker::PopEventHandler ( )

protectedvirtual

Pop tracker's event handler from the stack. In general should be for internal use only since this is called automatically in DisableTracking.

virtual void CTracker::PushEventHandler ( )

protectedvirtual

Push tracker's event handler on the stack. In general should be for internal use only since this is called automatically in EnableTracking.

virtual IControlView* CTracker::QueryControlView ( ) const

virtual

Acquire interface ptr to associated control-view.

Returns: reference-increment ptr to the associated IControlView

Implements ITracker.

virtual IPanorama* CTracker::QueryPanorama ( IControlView * pView ) const

protectedvirtual

Return a bumped reference to the panorama associated with this tracker's view.

void CTracker::ReleaseModalCursor ( )

protected

Called internally by CTracker in various places.

virtual void CTracker::SetupTracker	(	IControlView *	theControlView,
		ISnapTo *	theSnapper = `NULL`,
		IItemContext *	context = `NULL`
	)

virtual

Initialize the state of the tracker with a control-view and other optional abstractions. Indicate which control view the tracker is modifying. Used for access to graphics context. Snap to interface is optional, but it must be present if the tracker needs to do snap to.

Parameters

theControlView	[IN] the control view to track in.
theSnapper	[IN] the ISnapTo interface if the tracker want snap to behavior. Applies to tracker in the layout widget. May be nil.
context	[IN] the item context for the tracker to use. Obsolete.

See Also: IControlView.h; ISnapTo.h; IItemContext.h

Implements ITracker.

void CTracker::StartTimer	(	ClassID	trackerTimerBoss,
		uint32	milliSeconds,
		uint32	mouseMoveDelay = `kDefaultMouseMoveDelay`,
		uint32	mouseSteadyDelay = `kDefaultMouseSteadyDelay`
	)

protected

Called if WantTimer for a particular ITrackerTimer ClassID returns kTrue.

Parameters

trackerTimerBoss	[IN] ClassID for the tracker timer. Typical values are kMouseTrackerBoss, kPatientUserBoss and kDynamicPauseTimerBoss.
milliSeconds	[IN] delay until timer is first called. Typically the tracker timer would then call the tracker's TimerMessage method.
mouseMoveDelay	[IN] how frequently in milliseconds RunTask is called while mouse is moving.
mouseSteadyDelay	[IN] how frequently in milliseconds RunTask is called while mouse is not moving.

void CTracker::StopTimer ( ClassID trackerTimerBoss )

protected

Stop a tracker timer with a particular ClassID

Parameters

trackerTimerBoss [IN] ClassID for the tracker timer to stop.

virtual void CTracker::TimerMessage ( int32 flags )

inlinevirtual

Called after the ITrackerTimer has expired. Timer is started in BeginTracking. Used to turn on patient user tracking by CLayoutTracker. Can be used to change cursor feedback.

Parameters

flags [IN] int32 value, flags from IShape, typically draw flags such as kPatientUser or kDynamicPause

See Also: kMouseTrackerBoss; ITrackerTimer.h; CLayoutTracker.h; IShape.h; StartTimer, StopTimer, WantTimer

Implements ITracker.

Reimplemented in CLayoutTracker.

void CTracker::UpdateModalCursor ( )

protected

Call this after DoSnapTo() has been called and fSnapType is updated if your tracker wants to update the cursor as the mouse snaps and unsnaps.

virtual bool16 CTracker::WantsToAutoScroll ( const PMPoint & currentPoint )

protectedvirtual

Determine if this tracker wants to provide automatic scrolling.

Parameters

currentPoint [IN] the point in pasteboard coordinates.

Returns: bool16 return kTrue to autoscroll, kFalse otherwise.

virtual bool16 CTracker::WantTimer ( ClassID trackerTimerBoss )

virtual

Stop a tracker timer with a particular ClassID

Parameters

trackerTimerBoss [IN] ClassID for the tracker timer. Typical values are kMouseTrackerBoss, kPatientUserBoss and kDynamicPauseTimerBoss.

Returns: bool16 kTrue to start the timer for this class, kFalse otherwise. Default implemention returns kFalse.

Reimplemented in CLayoutTracker.

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation