Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
TCompositingLayer, MRemoteCaller
Inherited By:
None.
Purpose:
A cursor is a workspace sprite whose location is controlled by an input device, such as a mouse, trackball, pen, or data glove. A cursor is displayed on interactive display devices above all other graphics. A cursor allows the user to point to objects on the screen in order to select, edit, and control them. Currently, there can only be one cursor, known as the system cursor.
The TCursor class lets you specify which graphic is displayed for the system cursor. The TCursor class represents an alias to, or surrogate for, the system cursor. The cursor actually exists in the system before a particular application starts. In fact, the cursor is created by the controlling input device. Therefore, normal applications do not create cursors. Rather, they manipulate cursor surrogate objects, TCursors, that associate a particular graphic with the cursor and determine its visibility.
Both the member functions and the usage of TCursor will change in the future. Most applications will use a higher-level interface than TCursor to access the cursor. There will be some higher-level framework to associate cursor graphics with particular views and tools. When this framework is available, applications will rarely set the cursor graphic in response to cursor movement. Instead, the framework will change the cursor as it enters and exits views.
TCursor is derived from TCompositingLayer. As such, cursors can be ordered like other sprites. That is, you can specify that a cursor be in front of or behind another cursor or sprite.
Instantiation:
Allocate on the stack or heap.
Deriving Classes:
None.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
TCursor ()
Interface Category:
API.
Purpose:
Default constructor. This constructor creates an alias to the single system cursor.
Calling Context:
Called by the stream-in operators and all other clients.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual ~ TCursor ()
Interface Category:
API.
Purpose:
Destructor. Calling the destructor destroys your alias to a cursor, but does not necessarily destroy the cursor. If you delete your alias to the system cursor, for example, the system cursor still appears on the screen, and other threads can create aliases to control its appearance.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCursor::SetGraphic
virtual void SetGraphic (const MDrawable & graphic)
Interface Category:
API.
Purpose:
Sets the cursor's graphic. The graphic is positioned so that its origin (0,0) is aligned with the cursor's current location. You might have to translate your graphic appropriately before calling SetGraphic.
Calling Context:
Called by applications or frameworks to set the cursor's graphic.
Parameters:
- const MDrawable & graphic -The cursor's new graphic.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The graphic can be changed by other threads through their own TCursor objects, so don't assume that the cursor has the same graphic that you set earlier.
Member Function: TCursor::CopyGraphic
virtual MDrawable * CopyGraphic ()
Interface Category:
API.
Purpose:
Gets a copy of the cursor's current graphic.
Calling Context:
Called by applications or frameworks that need the cursor's current graphic.
Parameters:
Return Value:
Returns the cursor's current graphic.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The graphic can be changed by other threads through their own TCursor objects, so don't assume that the cursor has the same graphic that you set earlier.
Member Function: TCursor::GetLocation
virtual TGPoint GetLocation ()
Interface Category:
API.
Purpose:
Returns the cursor's current location in world coordinates.
Calling Context:
Called by applications and frameworks that need to know the current location of the cursor.
Parameters:
Return Value:
The current location of the cursor in world coordinates.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The cursor's location can change asynchronously at any time.
Member Function: TCursor::SetDefaultGraphic
virtual void SetDefaultGraphic ()
Interface Category:
API.
Purpose:
Restores the default arrow cursor. This function gives the client an efficient means to restore the arrow cursor. By using this function, the client does not have to duplicate the arrow polygon code, nor is it necessary to call CopyGraphic and SetGraphic before and after changing the cursor graphic.
Calling Context:
Called by applications or frameworks to set the default arrow cursor.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function saves CPU processing cycles, in addition to heap space and extra code.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.