CursorStack Class Reference

A stack of Cursor objects, which is part of the kernel (NB Cursor objects are part of the OIL). More...

#include <csrstack.h>

List of all members.

Public Member Functions
	CursorStack (INT32 maxdepth=10)
	Constructs an empty stack of Cursor objects, with a maximum depth (by default this is 10 deep).
virtual	~CursorStack ()
	Destroys a CursorStack object.
void	BeginBusy ()
	Tells the cursor stack to show the busy cursor. Multiple calls will increment a usage count, and the cursor won't disappear until the usage count drops to zero.
void	EndBusy ()
	Turns off the busy cursor (if there has only been one call to BeginBusy) for this cursor stack. Waits until BusyCount reaches zero before turning off the busy cursor.
void	SmashBusy ()
	Turns off the busy cursor (without exceptions) for this cursor stack. Resets the Busy count to zero. Called by Progress.cpp's SmashBusyJob to ensure the cursor is off.
Static Public Member Functions
static BOOL	Init ()
	Initialises the cursor system, loading the standard OS-provided cursors, such as the arrow and the hour-glass, creating the application's cursor stack etc.
static void	DeInit ()
	Shuts down the cursor system, releasing resources allocated by the Init() member function.
static BOOL	GIsValid ()
static INT32	GPush (Cursor *pCursor, BOOL ActivateNow=TRUE)
static Cursor *	GPop (INT32 cursorID)
static Cursor *	GSetTop (Cursor *pCursor, INT32 cursorID)
static void	GSetActive ()
static BOOL	GIsActive (const Cursor *pCursor)
static Cursor *	GetActive ()
Private Member Functions
	CC_DECLARE_MEMDUMP (CursorStack)
BOOL	IsValid () const
	Tests if the object was successfully constructed, and is coherent.
INT32	Push (Cursor *pCursor, BOOL ActivateNow=TRUE)
	Pushes the parameter onto the stack, making it top-most and hence the Cursor which will become active when SetActive() is called (this is done automatically by default, or if you pass in ActivateNow == TRUE) The Unique ID returned will be required by calls to SetTop and Pop so that we don't have any problems with the wrong cursors being popped and deleted.
Cursor *	Pop (INT32 cursorID=0)
	Removes a cursor from the stack. Because of the strange, asynchronous nature of Camelot, and the way cursors are seemingly added and removed from the stack at random, when popping a cursor from the stack, a unique ID is used to identify which cursor you actually want to remove. That one is removed, whether it's at the top of the stack or not.
Cursor *	SetTop (Cursor *pCursor, INT32 cursorID=0)
	Replaces a cursor on the stack with a new Cursor object. Combines a pop and a push. Note that the function detects if the stack is empty and will skip the initial pop if it is. The unique ID is used to find which cursor is actually to be replaced. If the cursor passed to this function is the same as the one already occupying the slot, no switching is done, otherwise the top cursor on the stack will be switched on (not necessarily the one passed to this function).
void	SetActive (bool fOnlyRendWnd=true) const
	Makes the Cursor object on the top of the stack the active cursor.
BOOL	IsActive (const Cursor *pCursor) const
	Tests if a particular cursor is on the top of the stack, ie. is currently visible and active.
Private Attributes
CursorIdent *	pcStack
INT32	nNextFreeSlot
INT32	nSentinel
INT32	BusyCount
Static Private Attributes
static CursorStack *	Global
Friends
void	BeginBusyCursor ()
	Tells the global cursor stack to display a busy cursor.
void	EndBusyCursor ()
	Tells the global cursor stack to stop displaying the busy cursor. If more than one call has been previously made to beginBusyCursor, the busy cursor isn't removed - a usage count is decremented.
void	SmashBusyCursor ()
	Tells the global cursor stack to stop displaying the busy cursor, regardless of how many calls have been previously made to beginBusyCursor.

---

Detailed Description

A stack of Cursor objects, which is part of the kernel (NB Cursor objects are part of the OIL).

Author:

Justin_Flude (Xara Group Ltd) <camelotdev@xara.com>

Date:

15th November, 1993

Definition at line 145 of file csrstack.h.

---

Constructor & Destructor Documentation

CursorStack::CursorStack (  INT32  maxdepth = 10  )

Constructs an empty stack of Cursor objects, with a maximum depth (by default this is 10 deep). Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/11/93 Parameters: -  [INPUTS] -  [OUTPUTS] Returns: - Errors: The allocation of the stack may fail, if so all subsequent calls to Push and Pop will be ignored. See also: CursorStack::CursorStack Definition at line 201 of file csrstack.cpp. { nSentinel = maxdepth; nNextFreeSlot = 0; BusyCount = 0; pcStack = new CursorIdent[maxdepth]; // array of CursorIdent objects #ifdef _DEBUG if( !pcStack ) TRACEUSER( "JustinF", _T("Failed to allocate stack in CursorStack::CursorStack!\n")); #endif // _DEBUG }

CursorStack::~CursorStack (   )  [virtual]

Destroys a CursorStack object. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/11/93 Parameters: -  [INPUTS] -  [OUTPUTS] Returns: - Errors: - See also: CursorStack::CursorStack Definition at line 231 of file csrstack.cpp. { #ifdef _DEBUG if (nNextFreeSlot != 0) TRACE( _T("WARNING: Cursor Stack at 0x%p not empty (%d deep) upon destruction!\n"), this, nNextFreeSlot); #endif // _DEBUG delete[] pcStack; }

---

Member Function Documentation

void CursorStack::BeginBusy (   )

Tells the cursor stack to show the busy cursor. Multiple calls will increment a usage count, and the cursor won't disappear until the usage count drops to zero. Author: Jim_Lynn (Xara Group Ltd) <camelotdev@xara.com> Date: 28/1/95 Parameters: -  [INPUTS] -  [OUTPUTS] Returns: - Errors: - See also: CursorStack::EndBusy; CursorStack::SmashBusy Definition at line 553 of file csrstack.cpp. { BusyCount++; SetActive(); }

CursorStack::CC_DECLARE_MEMDUMP (  CursorStack   )  [private]

void CursorStack::DeInit (   )  [static]

Shuts down the cursor system, releasing resources allocated by the Init() member function. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 12/11/93 Parameters: -  [INPUTS] -  [OUTPUTS] Returns: - Errors: - See also: CursorStack::Init; Cursor::DeInit Definition at line 174 of file csrstack.cpp. { if (!Global) return; Global->Pop(); // undo the push done in Init() delete Global; Global = 0; Cursor::DeInit(); }

void CursorStack::EndBusy (   )

Turns off the busy cursor (if there has only been one call to BeginBusy) for this cursor stack. Waits until BusyCount reaches zero before turning off the busy cursor. Author: Jim_Lynn (Xara Group Ltd) <camelotdev@xara.com> Date: 28/1/95 Parameters: -  [INPUTS] -  [OUTPUTS] Returns: - Errors: ERROR3 if busy count drops below zero. See also: CursorStack::BeginBusy; CursorStack::SmashBusy Definition at line 576 of file csrstack.cpp. { if ((--BusyCount) < 0) { BusyCount=0; ERROR3("Too many calls to CursorStack::EndBusy\n"); } SetActive(); }

Cursor * CursorStack::GetActive (   )  [static]

Definition at line 482 of file csrstack.cpp. { if( Global->nNextFreeSlot <= 0 ) { ERROR3("Stack empty in CursorStack::SetActive!\n"); return NULL; } // If BusyCount > 0 show the busy cursor instead of the topmost one if( Global->BusyCount > 0 ) { return Cursor::Busy; } else { return Global->pcStack[Global->nNextFreeSlot - 1].pCursor; } }

BOOL CursorStack::GIsActive (  const Cursor *  pCursor  )  [static]

Definition at line 716 of file csrstack.cpp. { return Global->IsActive(pCursor); }

BOOL CursorStack::GIsValid (   )  [static]

Definition at line 691 of file csrstack.cpp. { return Global->IsValid(); }

Cursor * CursorStack::GPop (  INT32  cursorID  )  [static]

Definition at line 701 of file csrstack.cpp. { return Global->Pop(cursorID); }

INT32 CursorStack::GPush (  Cursor *  pCursor, BOOL  ActivateNow = TRUE )  [static]

Definition at line 696 of file csrstack.cpp. { return Global->Push( pCursor, ActivateNow ); }

void CursorStack::GSetActive (   )  [static]

Definition at line 711 of file csrstack.cpp. { Global->SetActive(); }

Cursor * CursorStack::GSetTop (  Cursor *  pCursor, INT32  cursorID )  [static]

Definition at line 706 of file csrstack.cpp. { return Global->SetTop(pCursor, cursorID); }

BOOL CursorStack::Init (  void   )  [static]

Initialises the cursor system, loading the standard OS-provided cursors, such as the arrow and the hour-glass, creating the application's cursor stack etc. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 12/11/93 Parameters: -  [INPUTS] -  [OUTPUTS] Returns: TRUE if initialisation was successful. Errors: - See also: CursorStack::DeInit; Cursor::Init Definition at line 141 of file csrstack.cpp. { Global = new CursorStack; if (!Global || !Global->IsValid() || !Cursor::Init()) { delete Global; Global = 0; return FALSE; } Global->Push(Cursor::Arrow); // This is about the only occurrence of Push // that can legitimately ignore the return value, since // this cursor should always be on the stack. Global->SetActive(); return TRUE; }

BOOL CursorStack::IsActive (  const Cursor *  pCursor  )  const [private]

Tests if a particular cursor is on the top of the stack, ie. is currently visible and active. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 12/11/93 Parameters: A  pointer to a (constant) Cursor object. [INPUTS] -  [OUTPUTS] Returns: TRUE if the top of the stack is the same as the parameter, FALSE if it isn't or if the stack is empty. Errors: - See also: - Definition at line 516 of file csrstack.cpp. { // return (nNextFreeSlot > 0) ? (pcStack[nNextFreeSlot - 1] == pCursor) : FALSE; // if BusyCount>0 that means the busy cursor is active, so check for that situation if (BusyCount > 0) { return (pCursor == Cursor::Busy); } else { if (nNextFreeSlot>0 && (pcStack[nNextFreeSlot - 1].pCursor == pCursor)) return TRUE; return FALSE; } }

BOOL CursorStack::IsValid (   )  const [private]

Tests if the object was successfully constructed, and is coherent. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/11/93 Parameters: -  [INPUTS] -  [OUTPUTS] Returns: TRUE if the stack was allocated OK. Errors: - See also: - Definition at line 258 of file csrstack.cpp. { return pcStack != 0 && (nNextFreeSlot >= 0 && nNextFreeSlot <= nSentinel); }

Cursor * CursorStack::Pop (  INT32  cursorID = 0  )  [private]

Removes a cursor from the stack. Because of the strange, asynchronous nature of Camelot, and the way cursors are seemingly added and removed from the stack at random, when popping a cursor from the stack, a unique ID is used to identify which cursor you actually want to remove. That one is removed, whether it's at the top of the stack or not. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com>/Jim Date: 11/11/93 Modified: 27/1/95 Parameters: Unique  ID of the cursor you want to pop from the stack [INPUTS] -  [OUTPUTS] Returns: A pointer to the Cursor object that was previously at the top of the stack. Returns NULL if the stack is empty or a cursor of that ID is not found Errors: Checks for stack underflow. Also, it now handles stack underflow, as well. Will ERROR in debug builds if the ID is not found in the stack. See also: CursorStack::Push; CursorStack::SetActive Definition at line 323 of file csrstack.cpp. { ERROR2IF(nNextFreeSlot <= 0,NULL, "Underflow in CursorStack::Pop!\n"); // For old code which doesn't pass the ID, we'll pop the top one off and hope if (cursorID == 0) { Cursor* pc = pcStack[--nNextFreeSlot].pCursor; return pc; } else { INT32 n=0; // Counter to go through the stack // Yes, I know this while loop could be more cleverly implemented, but I'm // sticking with easier to understand code, and letting the optimiser do // the hard work. // Find the ID on the stack and remove it, sealing the hole up while(n<nNextFreeSlot) { if (pcStack[n].UniqueID == cursorID) { Cursor* pc = pcStack[n].pCursor; // for return // Now, what's the best way of closing up the gap? INT32 m = n+1; // Point at the next item on stack while (m<nNextFreeSlot) // Don't copy anything if n is the last one { pcStack[n].pCursor = pcStack[m].pCursor; pcStack[n].UniqueID = pcStack[m].UniqueID; n++; m++; } // Now the gap has been closed, let's decrement the nextfree counter nNextFreeSlot--; if (nNextFreeSlot > 0) SetActive(); // Finally, return the pointer to the cursor we've just removed from the stack return pc; } n++; } // If we arrive here, there wasn't a valid cursor on the stack, so complain ERROR2(NULL,"Unique ID not found in cursor stack\n"); } }

INT32 CursorStack::Push (  Cursor *  pCursor, BOOL  ActivateNow = TRUE )  [private]

Pushes the parameter onto the stack, making it top-most and hence the Cursor which will become active when SetActive() is called (this is done automatically by default, or if you pass in ActivateNow == TRUE) The Unique ID returned will be required by calls to SetTop and Pop so that we don't have any problems with the wrong cursors being popped and deleted. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/11/93 Modified: 27/1/95 by Jim Parameters: pCursor  - A pointer to a Cursor object. [INPUTS] ActivateNow - if TRUE (the default), the cursor will be immediately activated (will become visible immediately). If FALSE, the cursor will not be displayed until the mouse pointer is moved over the appropriate window/area. (The latter form is used by tools so that there is no cursor-flicker when a tool is selected) -  [OUTPUTS] Returns: Unique ID which should be used to reference this cursor while it's in the stack Errors: Tests for stack overflow. See also: CursorStack::Pop; CursorStack::SetActive Definition at line 289 of file csrstack.cpp. { ENSURE(nNextFreeSlot < nSentinel, "Overflow in CursorStack::Push!\n"); INT32 retID = pcStack[nNextFreeSlot++].StoreNewCursor(pCursor); if (ActivateNow) SetActive(); return retID; }

void CursorStack::SetActive (  bool  fOnlyRendWnd = true  )  const [private]

Makes the Cursor object on the top of the stack the active cursor. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/11/93 Parameters: -  [INPUTS] -  [OUTPUTS] Returns: - Errors: Checks that the stack isn't empty. Returns if it is See also: Cursor::SetActive Definition at line 467 of file csrstack.cpp. { if (nNextFreeSlot <= 0) { ERROR3("Stack empty in CursorStack::SetActive!\n"); return; } // If BusyCount > 0 show the busy cursor instead of the topmost one if (BusyCount > 0) Cursor::Busy->SetActive(); else pcStack[nNextFreeSlot - 1].pCursor->SetActive( fOnlyRendWnd ); }

Cursor * CursorStack::SetTop (  Cursor *  pCursor, INT32  cursorID = 0 )  [private]

Replaces a cursor on the stack with a new Cursor object. Combines a pop and a push. Note that the function detects if the stack is empty and will skip the initial pop if it is. The unique ID is used to find which cursor is actually to be replaced. If the cursor passed to this function is the same as the one already occupying the slot, no switching is done, otherwise the top cursor on the stack will be switched on (not necessarily the one passed to this function). Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/11/93 Modified: 28/1/95 by Jim Parameters: pCursor  points to a Cursor object. [INPUTS] cursorID is the unique ID of the cursor that wants to be changed -  [OUTPUTS] Returns: A pointer to the Cursor object that was previously occupied by the cursor replaced or NULL if there wasn't one. Errors: - See also: CursorStack::Push; CursorStack::Pop Definition at line 401 of file csrstack.cpp. { // cursorID will be zero if unmodified code is used. if (cursorID == 0) { ERROR3("CursorStack::SetTop called without a valid cursorID. Please change the offending code.\n"); Cursor* pc; if (nNextFreeSlot > 0) { pc = pcStack[nNextFreeSlot - 1].pCursor; pcStack[nNextFreeSlot - 1].pCursor = pCursor; } else { pc = NULL; Push(pCursor); } SetActive(); return pc; } else { // This is the new case INT32 n=0; // Counter to go through the stack // Find the ID on the stack and replace it with the new cursor while(n<nNextFreeSlot) { if (pcStack[n].UniqueID == cursorID) { Cursor* pc = pcStack[n].pCursor; // for return if (pc == pCursor) return pc; // Don't try and set the cursor if it's the same // Replace this cursor with the new one pcStack[n].pCursor = pCursor; if (nNextFreeSlot > 0) SetActive(); // Finally, return the pointer to the cursor we've just removed from the stack return pc; } n++; } // Oh dear, we seem not to have found this cursorID on the stack. ERROR2(NULL,"cursorID not found on stack in SetTop.\n"); } }

void CursorStack::SmashBusy (   )

Turns off the busy cursor (without exceptions) for this cursor stack. Resets the Busy count to zero. Called by Progress.cpp's SmashBusyJob to ensure the cursor is off. Author: Jason_Williams (Xara Group Ltd) <camelotdev@xara.com> Date: 24/8/95 Parameters: -  [INPUTS] -  [OUTPUTS] Returns: - See also: CursorStack::BeginBusy; CursorStack::EndBusy Definition at line 605 of file csrstack.cpp. { if (BusyCount == 0) // Not showing a busy cursor, so return ASAP return; // Turn off the busy cursor BusyCount = 0; SetActive(); }

---

Friends And Related Function Documentation

void BeginBusyCursor (   )  [friend]

Tells the global cursor stack to display a busy cursor. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 16/11/93 Modified: 28/1/95 by Jim Parameters: -  [INPUTS] -  [OUTPUTS] Returns: - Errors: - See also: CursorStack::Push; CursorStack::SetActive; EndBusyCursor; SmashBusyCursor Definition at line 632 of file csrstack.cpp. { //CursorStack::Global->Push(Cursor::Busy); if (CursorStack::Global) CursorStack::Global->BeginBusy(); }

void EndBusyCursor (   )  [friend]

Tells the global cursor stack to stop displaying the busy cursor. If more than one call has been previously made to beginBusyCursor, the busy cursor isn't removed - a usage count is decremented. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 16/11/93 Modified: 28/1/95 by Jim Parameters: -  [INPUTS] -  [OUTPUTS] Returns: - Errors: ERROR3 failure if the cursor stack isn't displaying a busy cursor at all See also: CursorStack::Pop; CursorStack::SetActive; BeginBusyCursor; SmashBusyCursor Definition at line 658 of file csrstack.cpp. { if (CursorStack::Global) CursorStack::Global->EndBusy(); }

void SmashBusyCursor (   )  [friend]

Tells the global cursor stack to stop displaying the busy cursor, regardless of how many calls have been previously made to beginBusyCursor. Author: Jason_Williams (Xara Group Ltd) <camelotdev@xara.com> Date: 24/8/95 Parameters: -  [INPUTS] -  [OUTPUTS] Returns: - See also: BeginBusyCursor; EndBusyCursor Definition at line 681 of file csrstack.cpp. { if (CursorStack::Global) CursorStack::Global->SmashBusy(); }

---

Member Data Documentation

INT32 CursorStack::BusyCount [private]

Definition at line 193 of file csrstack.h.

CursorStack * CursorStack::Global [static, private]

Definition at line 187 of file csrstack.h.

INT32 CursorStack::nNextFreeSlot [private]

Definition at line 190 of file csrstack.h.

INT32 CursorStack::nSentinel [private]

Definition at line 191 of file csrstack.h.

CursorIdent* CursorStack::pcStack [private]

Definition at line 189 of file csrstack.h.

---

The documentation for this class was generated from the following files:

• Kernel/csrstack.h (r1785/r1646)
• Kernel/csrstack.cpp (r1785/r1646)

---