TSLEditor Class Reference

Detailed Description

Generic editing component for MapLink Geometry objects. This component should be attached to one drawing surface at a time, using the attach method. Events such as button presses should be passed to this from the application.

An instance of this class must be paired with an object derived from TSLEditorRequest. The methods of the request object are invoked by the TSLEditor component when information needs to be requested from or sent to the user.

NOTE : The editor may force redraw requests to the screen if an operation requests it.

Public Member Functions
	TSLEditor (TSLEditorRequest *handler)
bool	activate (const char *opname, void *data=NULL)
bool	activatePossible (const char *opname)
const char *	activeOperation ()
bool	addCustomHighlight (TSLCustomHighlight *customHighlight)
bool	addCustomFeedback (TSLCustomFeedback *customFeedback)
bool	addOperationAlias (const char *originalName, const char *aliasName)
bool	addUserOperation (TSLUserOperation *op, const char *name, TSLOperationType type)
bool	attach (TSLDrawingSurface *drawingSurface)
const TSLDrawingSurface *	attachedSurface () const
bool	backup ()
bool	backupPossible ()
bool	changed ()
void	changed (bool newValue)
bool	clearSelectList (bool feedback)
bool	constraint (TSLEditorConstraintType type, double parameter=0.0)
bool	cursorMovementConfig (TSLCursorMovementType type, bool constrain, const char *format)
bool	dataChanged ()
bool	deactivate ()
bool	descend ()
bool	deselect (TSLEntity *entity, bool feedback)
void	destroy ()
bool	dialogEntered (int button)
bool	done ()
bool	enableGlobalUndo (int numSlots)
bool	initialise (const char *configFileName, const char *configSectionName)
bool	locator (const TSLLocatorEvent &event)
int	numSelected ()
bool	query (const char *name, TSLVariant *val)
bool	querySelectedAttributes (TSLRenderingAttributes &attributes)
bool	redo ()
bool	redoPossible ()
bool	reset ()
bool	textEntered (const char *text, bool cancelled)
bool	select (TSLEntity *entity, bool clearSelectListFirst, bool feedback)
const TSLEntity *	selectedEntity (int n)
void	setDefaultOperation (const char *name)
bool	undo ()
bool	undoPossible ()
void	operator delete (void *self)
void *	operator new (size_t size, char *filename, int line)

Static Public Member Functions
static void *	operator new (size_t size)

Constructor & Destructor Documentation

TSLEditor()

TSLEditor::TSLEditor

(

TSLEditorRequest *

handler

)

The constructor for the TSLEditor class.

Parameters

handler

Pointer to TSLEditorRequest derived object. This is used when the Editor needs to make requests from the client application, such as entering some text or displaying a prompt. It is also used to inform the client application of specific events, such as a redraw or the selection list changing.

Member Function Documentation

activate()

bool TSLEditor::activate	(	const char *	opname,
		void *	data = NULL )

Activate a new operation.

This asks the editor to activate the specified operation. The operation is mapped by name, since overriding operations may intercept the operation methods.

Parameters

opname	This is the name of the operation to be activated by the editor.
data	A pointer to data required by the operation. This may be information is contained within the TSLSpecialised data object. The specific data required by each operation is specified in the operation class.

Returns

true on success, false otherwise.

activatePossible()

bool TSLEditor::activatePossible

(

const char *

opname

)

Ask whether it is possible to activate the specified operation.

This asks the editor to activate the specified operation. Some operations are dependent upon specific circumstances to work, for example the move/scale/rotate operations all rely on entities being selected.

Parameters

opname

This is the name of the operation to be queried for activation by the editor.

Returns

true if it is possible to activate the operation, false otherwise.

activeOperation()

const char * TSLEditor::activeOperation

(

)

This method queries the name of the current active operation

Returns the name of the currently active operation, NULL on error.

addCustomFeedback()

bool TSLEditor::addCustomFeedback

(

TSLCustomFeedback *

customFeedback

)

Add a new user-defined feedback manager to the editor.

The user-defined feedback manager is an instance of a class derived from the TSLCustomFeedback class. When the editor needs to perform any action on the entities that are in the edit layer, the user-defined instance is triggered.

Parameters

customFeedback

Pointer to user defined feedback manager to add to the editor. The editor assumes control of this instance and will delete it if replaced or the editor is deleted.

Returns

true if the custom feedback manager is successful added, false otherwise.

addCustomHighlight()

bool TSLEditor::addCustomHighlight

(

TSLCustomHighlight *

customHighlight

)

Add a new user-defined highlight manager to the editor.

The user-defined highlight manager is an instance of a class derived from the TSLCustomHighlight class. When the editor needs to perform any action on the highlight list, the user-defined instance is triggered.

Parameters

customHighlight

Pointer to user defined highlight manager to add to the editor. The editor assumes control of this instance and will delete it if replaced or the editor is deleted.

Returns

true if the custom highlight manager is successful added, false otherwise.

addOperationAlias()

bool TSLEditor::addOperationAlias	(	const char *	originalName,
		const char *	aliasName )

Create an operation by cloning an existing operation.

An operation alias will allow an existing operation to be invoked using a different name.

This is useful when combined with User Operations to provide multiple implementations of essentially the same operation. For example, an application may require several kinds of polyline to be drawn, each with a different feature code. The operation alias mechanism may be used to create different named operations which all perform the same original polyline functionality, with the advantage that overriding user-defined operations can modify the feature code after the polyline has been created.

Note that the current implementation at the time of the method call is used, regardless of subsequent operation additions. Thus, if the basic TSLPolyline Operation is added, the addOperationAlias called and a user-defined polyline operation added, then the alias would use the basic TSLPolylineOperation rather than the user-defined polyline operation. If the addOperationAlias call occurred after the user-defined polyline operation had been added, then that would be used as the basic of the alias.

Parameters

originalName	Name of original operation to clone.
aliasName	New name of the operation, used when activating.

Returns

true if the operation is successful aliased, false otherwise.

addUserOperation()

bool TSLEditor::addUserOperation	(	TSLUserOperation *	op,
		const char *	name,
		TSLOperationType	type )

Add a new user-defined operation to the editor.

The user-defined operation is an instance of a class derived from the TSLUser Operation class. When the editor receives an activation request for the named operation, it is activated.

A user-defined operation can override an existing operation by specifying the same name. For example, if the client application wished to override the "polygon" operation to perform some action after the polygon had been created, then it should add the normal polygon operation (TSLPolygon Operation::add( editor )), then add a user-defined operation of the same name - "polygon". The methods of the user-defined operation would then be called in place of the original operation methods. To invoke the original operation methods from within the user-defined operation methods, call the 'invokeOriginal' method of the TSLUserOperationRequest handler.

Note that this can be combined with an addOperationAlias call to provide multiple implementations of essentially the same operation. For example, an application may require several kinds of polyline to be drawn, each with a different feature code. The operation alias mechanism may be used to create different named operations which all perform the same original polyline functionality, with the advantage that overriding user-defined operations can modify the feature code after the polyline has been created.

Parameters

op	Pointer to user defined operation to add to the editor.
name	Name of the operation, used when activating.
type	Type of operation - primitive, manipulation or attribute.

Returns

true if the operation is successful added, false otherwise.

attach()

bool TSLEditor::attach

(

TSLDrawingSurface *

drawingSurface

)

Attach a drawing surface to the editor.

This method attaches a drawing surface to the editor. The drawing surface is responsible for the display of data in the window supplied by the user.

Parameters

drawingSurface

A pointer to the drawing surface to be attached to the editor.

Returns

true on success, false otherwise.

attachedSurface()

const TSLDrawingSurface * TSLEditor::attachedSurface

(

)

const

Queries the attached drawing surface.

Returns the attached drawing surface, if any.

backup()

bool TSLEditor::backup

(

)

Trigger the backup method of the current operation.

Returns true on success, false otherwise.

backupPossible()

bool TSLEditor::backupPossible

(

)

Ask whether backup is currently available for the current operation.

Returns true if it is possible to backup the current operation, false otherwise.

changed() [1/2]

bool TSLEditor::changed

(

)

Determine if any operations have changed the current data layer.

This flag queries the editor to determine if any operations have changed the current data layer.

Returns true if any operations have changed the current data layer, false otherwise.

changed() [2/2]

void TSLEditor::changed

(

bool

newValue

)

Set the editor changed flag.

This flag sets the editor's changed flag to determine if any operations have changed the current data layer. This gives control over the changed flag to the user application.

Parameters

newValue

The new state of the editor's changed flag.

clearSelectList()

bool TSLEditor::clearSelectList

(

bool

feedback

)

Clears the select list.

This asks the editor to clear the select list, optionally reporting the clear via the feedback mechanism.

Parameters

feedback

Flag to indicate whether the deselection should be reported via the feedback mechanism. If so, then the default operation name is used, as specified in the config file.

Returns

true if the entity is successfully deselected, false if it is not on the select list.

constraint()

bool TSLEditor::constraint	(	TSLEditorConstraintType	type,
		double	parameter = 0.0 )

Change the current constraint value.

This method allows the user application to change the current constraint.

Parameters

type	A TSLEditorConstraint value determining the new constraint type.
parameter	For angle constraints, this is the angle in degrees, anti-clockwise from the +ve X axis. For distance constraints, this is the distance in TMC units. For other constraints, this parameter is unused.

Returns

true on success.

cursorMovementConfig()

bool TSLEditor::cursorMovementConfig	(	TSLCursorMovementType	type,
		bool	constrain,
		const char *	format )

This method configures any cursor movement callback that may be required by the application.

When a cursor movement has been configured, the TSLEditorRequest::onCursor Movement method will be triggered. The default is none.

Parameters

type	The type of coordinate information required
constrain	Flag to indicate whether the cursor position should be constrained before performing the coordinate conversion.
format	Format string if the editor should construct a displayString. This should be a 'printf' style format string for two variables. The type of the variables are described in the documentation for TSLCursorMovementType. If no conversion is required, NULL should be passed to this parameter.

Returns

true on success, false otherwise.

dataChanged()

bool TSLEditor::dataChanged

(

)

Informs the editor that the current data layer has changed.

This informs the editor that the current editable data layer has changed in the current drawing Surface. This will cause the editor to reset back to the select operation, clear the select list and to request the current entity set from the data layer.

This method should be called after client application has changed the data in the data layer, such as after a 'loadData' call.

Returns true on success, false otherwise.

deactivate()

bool TSLEditor::deactivate

(

)

Deactivate the current operation.

This method asks the editor to deactivate the current operation and activate the default select operation.

Returns true if successful, false otherwise.

descend()

bool TSLEditor::descend

(

)

Increment the select depth.

This method asks the editor to increment the select depth. The select depth controls how far down into the entity hierarchy that a select operation will go.

The select depth is decremented by the done method when the select operation is active and the select list is clear.

Returns true on success, otherwise false.

deselect()

bool TSLEditor::deselect	(	TSLEntity *	entity,
		bool	feedback )

Deselect the specified entity.

This asks the editor to deselect the specified entity. Since this may alter the select list in the middle of an operation, a 'deactivate' is called internally first.

Parameters

entity	This is the entity to deselect. It must be on the select list.
feedback	Flag to indicate whether the deselection should be reported via the feedback mechanism. If so, then the default operation name is used, as specified in the config file.

Returns

true if the entity is successfully deselected, false if it is not on the select list.

destroy()

void TSLEditor::destroy

(

)

Destroy TSLEditor object.

This method should be called rather than deleting the object.

dialogEntered()

bool TSLEditor::dialogEntered

(

int

button

)

Dialog option selected by user.

This method is called by the client application when the user has selected one of the choices in a 'requestDialog' call. The user's choice is passed to the current operation for processing.

Parameters

button

The button selected by the user during the 'requestDialog' call. The index starts from 1.

Returns

true if successful, false otherwise.

done()

bool TSLEditor::done

(

)

Inform the editor of the completion of the current operation.

This informs the editor that the user has requested a completion of the current operation. This may be on a button press. The Right Button usually invokes this functionality automatically.

Returns true on success, false otherwise.

enableGlobalUndo()

bool TSLEditor::enableGlobalUndo

(

int

numSlots

)

Enable the global undo capability, with the specified number of undo slots. This capability allows for multiple undo slots, with 'redo' also available, at the expense of greater memory use.

Returns true if successful, false otherwise

initialise()

bool TSLEditor::initialise	(	const char *	configFileName,
		const char *	configSectionName )

Initialise the TSLEditor class.

This method initialises the class. It is separate from the constructor in order to avoid memory leaks if constructors fail.

configFileName: A pointer to a string containing the path of the configuration file.

configSectionName: A pointer to a string containing the name of the relevant section of the configuration file.

It will return true on successful initialisation, false otherwise.

locator()

bool TSLEditor::locator

(

const TSLLocatorEvent &

event

)

Inform the editor of a locator event.

This methods informs the editor that a locator event has occurred in the current drawing surface. The information concerning the event passed to the current operation in a TSLLocatorEvent for processing. Press, motion and release events should be passed to the editor.

NOTE : A Right Button locator event is automatically mapped to a 'done' method call.

Parameters

event

A reference to the TSLLocatorEvent object containing information about the event.

Returns

true if the locator event has been processed successfully, false otherwise.

numSelected()

int TSLEditor::numSelected

(

)

Query the number of entries in the current select list.

operator delete()

void TSLEditor::operator delete

(

void *

self

)

This custom deallocation operation is required to redirect the call to internal deallocation requests.

operator new() [1/2]

static void * TSLEditor::operator new ( size_t size )

static

This custom allocation operation is required to redirect the call to internal allocation requests.

operator new() [2/2]

void * TSLEditor::operator new	(	size_t	size,
		char *	filename,
		int	line )

When included in an MFC application in debug mode, the debug new expects this to be here. Override it and return the same as the normal one. The library must include it when compiled in release mode, since the user's application may be in debug mode.

query()

bool TSLEditor::query	(	const char *	name,
		TSLVariant *	val )

Query the data associated with the specified operation.

This method queries the named operation. The value queried is operation specific and is described in each operations documentation.

Parameters

name	A pointer to a string containing the name of the operation to be queried.
val	A pointer to a TSLVariant to be populated by the results of the query.

Returns

true on success, false otherwise.

querySelectedAttributes()

bool TSLEditor::querySelectedAttributes

(

TSLRenderingAttributes &

attributes

)

Query the attributes of the currently selected objects.

Populates the specified Rendering Attributes structure with the current values. Sets the value of an attribute to -1 if unused by any selected object or if there are multiple different values for the attribute.

Parameters

attributes

Storage for attributes.

Returns

true if structure populated, false if no objects are selected.

redo()

bool TSLEditor::redo

(

)

If global undo is enabled, then this is available.

Returns true on success, false otherwise.

redoPossible()

bool TSLEditor::redoPossible

(

)

Ask whether redo is currently available.

Returns true if it is possible to redo, false otherwise.

reset()

bool TSLEditor::reset

(

)

Reset to the default select operation.

This method resets the editor to the default select operation and clears the current select list.

Returns true on success, otherwise false.

select()

bool TSLEditor::select	(	TSLEntity *	entity,
		bool	clearSelectListFirst,
		bool	feedback )

Select the specified entity.

This asks the editor to select the specified entity. Since this may alter the select list in the middle of an operation, a 'deactivate' is called internally first. Optionally, the current selected items may be deselected.

Parameters

entity	This is the entity to select. It must be within the data layer that is attached to the editor, and at the current select depth.
clearSelectListFirst	This flag indicates that the select list should be cleared before selecting the specified entity.
feedback	Flag to indicate whether the modifications should be reported via the feedback mechanism. If so, then the default operation name is used, as specified in the config file.

Returns

true if the entity is successfully selected, false if it is not. An error will be placed onto the TSLErrorStack indicating why

selectedEntity()

const TSLEntity * TSLEditor::selectedEntity

(

int

n

)

Query the 'n'th selected entity. Note that this returns a read-only version of the entity. Any modifications should really take place via a custom operation. Under no circumstances should the entity be destroyed since the Editor and any active operation may be holding references to the entity.

Parameters

n	Index of selected entity to return.

Returns

NULL if the index is out of range, the entity otherwise.

setDefaultOperation()

void TSLEditor::setDefaultOperation

(

const char *

name

)

Sets the name of the default operation to be used.

The default operation is normally "select", although this can be configured in the .ini file. This method allows an application to override this. The default operation is used when the 'deactivate' method is called.

textEntered()

bool TSLEditor::textEntered	(	const char *	text,
		bool	cancelled )

Called when text is entered by user.

This method is called by the client application when a text string has been entered by the user. If the entry was cancelled by the user, then the 'cancelled' flag should be set. The entry is passed to the current operation for processing.

Parameters

text	Pointer to the string entered by the user.
cancelled	Flag set when text entry was cancelled by the user.

Returns

true if successful, false otherwise.

undo()

bool TSLEditor::undo

(

)

Trigger the undo method of the previous operation.

Returns true on success, false otherwise.

undoPossible()

bool TSLEditor::undoPossible

(

)

Ask whether undo is currently available.

Returns true if it is possible to undo, false otherwise.