com.luciad.view.gxy.controller.touch

LuciadLightspeedClass TLcdGXYTouchNewController

java.lang.Object

com.luciad.view.gxy.controller.ALcdGXYController

com.luciad.view.gxy.controller.ALcdGXYChainableController

com.luciad.view.gxy.controller.touch.TLcdGXYTouchNewController

All Implemented Interfaces:

ILcdUndoableSource, ILcdAWTEventListener, ILcdStatusSource, ILcdGXYChainableController, ILcdGXYController, Serializable

public class TLcdGXYTouchNewController
extends ALcdGXYChainableController
implements ILcdUndoableSource

Controller to interactively create and initialize domain objects using touches or drag gestures. This controller needs a controller model that determines the following:

• the object to create;
• the initialization of the object through a series of edit steps;
• the comitting of the domain object to a model.

Typical use

To interactively create a new object, implement a controller model providing a target layer and an uninitialized new domain object, and configure a corresponding controller on the view:

 ALcdGXYNewControllerModel2 controllerModel = new ALcdGXYNewControllerModel2() {

 public ILcdGXYLayer getGXYLayer(Graphics aGraphics, MouseEvent aMouseEvent, ILcdGXYLayerSubsetList aSnappables, ILcdGXYContext aContext) {
 return myLayer;
 }

 public Object create(int aEditCount, Graphics aGraphics, MouseEvent aMouseEvent, ILcdGXYLayerSubsetList aSnappables, ILcdGXYContext aContext) {
 return new MyDomainObject();
 }
 };
 TLcdGXYTouchNewController controller = new TLcdGXYTouchNewController(controllerModel);
 view.setGXYController(controller);
 

Typically you also want user interface elements to indicate if creation should end (e.g. when creating a polyline). See samples.gxy.touch.editing.TouchNewController for an example of this.
This controller supports snapping if snapping candidates are configured.

Undo behavior

This controller supports undo operations while creating, as well as after the creation has been finalized. The methods canUndo() and canRedo() can be used to check whether an undo or redo operation is possible at any given time during the creation process. The methods doUndo() and doRedo() will respectively undo the last creation interaction or redo the last action that was undone. After creation has finished (the object is committed), all registered ILcdUndoableListeners are notified with an undoable that will remove the object from the layer.

Customizing the editing process

The methods shouldCommit, shouldEdit, and shouldUndo can be overridden to map mouse events to specific editing behaviour.
In addition, some actions can be called programmatically. The methods canUndo(), canRedo(), canCommit() and canCancel() indicate whether or not an undo, redo, commit or cancel action are possible at the moment. The methods doUndo(), doRedo(), doCommit() and doCancel() will execute the actions when possible.

See ALcdGXYNewControllerModel2 for a more detailed explanation of the interaction with the controller model.

Use in a controller chain

This controller implements ILcdGXYChainableController, which means it can choose to disregard received AWTEvents and pass them on to an other component. This controller will automatically pass on all events but instances of TLcdTouchEvent. Even so it will only use one touch at a time. A second touch while the first isn't lifted will be delegated.

This controller only handles TLcdTouchPoints which are not-consumed, and marks the TLcdTouchPoints it uses as consumed, similar to the ALcdGXYTouchChainableController

Since:

10.0

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
TLcdGXYTouchNewController(ALcdGXYNewControllerModel2 aNewControllerModel) Creates a new Controller with the specified new controller model.

Method Summary

Modifier and Type	Method and Description
void	addUndoableListener(ILcdUndoableListener aUndoableListener) Adds a listener to this source, so this listener is notified when something undoable has happened.
void	appendGXYController(ILcdGXYChainableController aEnd) This method will append the passed controller to the end of the chain.
boolean	canCancel() This method indicates whether or not it's possible to cancel the creation of the current object.
boolean	canCommit() This method indicates whether are not an object is ready to be committed.
boolean	canRedo() This method indicates whether or not an creation step can be redone.
boolean	canUndo() This method indicates whether or not an creation step can be undone.
void	doCancel() If canCancel() returns true, this method will cancel the creation of the current object.
void	doCommit() If canCommit() returns true, this method will commit the object currently under creation, and trigger the action to trigger after commit if it's available.
void	doRedo() When canRedo() returns true, this method will redo the last creation step that was undone.
void	doUndo() When canUndo() returns true, this method will undo the last creation step.
ILcdAction	getActionToTriggerAfterCommit() Returns the ILcdAction that will be will be triggered just after this controller component has created a new Object, initialized it and committed it to an ILcdModel.
int	getEditThreshold() This method returns the edit threshold currently used by this controller.
ILcdGXYLayer	getGXYLayer() Returns the layer visualizing the object that the controller is creating.
int	getMoveThreshold() Returns the threshold for move events.
ALcdGXYNewControllerModel2	getNewControllerModel() Returns the ALcdGXYNewControllerModel2 this controller delegates to.
ILcdGXYChainableController	getNextGXYController() Returns a reference to the controller that is located after this one in a chain, or null if this controller is the last element of the chain.
Object	getObject() Returns the object that the controller is creating.
ILcdGXYLayerSubsetList	getSnappables() Returns the Objects to snap to when initializing a new created Object, or null when snapping is disabled.
void	handleAWTEvent(AWTEvent aEvent) This is method is called when the target of the listener has a new AWTEvent available.
boolean	isUndoOnSecondTouch() This method indicates whether or not you can undo actions by touching the representation of the last point added in the current object.
void	paint(Graphics aGraphics) Enables the controller to give visual feedback on the current user interactions.
protected void	paintImpl(Graphics aGraphics) The specific implementation of paint for this controller.
void	removeUndoableListener(ILcdUndoableListener aUndoableListener) Removes the specified listener so it is no longer notified.
void	setActionToTriggerAfterCommit(ILcdAction aNewActionToTriggerAfterCommit) Sets the ILcdAction that will be triggered just after this controller component has created a new Object and committed it to an ILcdModel.
void	setEditThreshold(int aEditThreshold) Sets the edit threshold.
protected void	setGXYView(ILcdGXYView aGXYView) Sets the ILcdGXYView the controller is interacting with.
void	setMoveThreshold(int aMoveThreshold) Sets the threshold for move events.
void	setNewControllerModel(ALcdGXYNewControllerModel2 aControllerModel) Sets the ALcdGXYNewControllerModel2 to delegate to.
void	setNextGXYController(ILcdGXYChainableController aNext) This method sets the next controller in the chain for this controller.
void	setSnappables(ILcdGXYLayerSubsetList aSnappables) Sets the Objects to snap to when initializing a new created Object.
void	setUndoOnSecondTouch(boolean aUndoOnSecondTouch) A setter to activate of deactivate undo on second touch behaviour.
protected boolean	shouldCommit(Object aObject, int aEditCount, Graphics aGraphics, TLcdTouchPoint aTouchPoint, ILcdGXYLayerSubsetList aSnappables, ILcdGXYContext aContext) This method indicates that the object should be committed.
protected boolean	shouldEdit(Object aObject, int aEditCount, Graphics aGraphics, TLcdTouchPoint aTouchPoint, ILcdGXYLayerSubsetList aSnappables, ILcdGXYContext aContext) This method controls when a edit should take place ( placing a point ).
protected boolean	shouldUndo(Object aObject, int aEditCount, Graphics aGraphics, TLcdTouchPoint aTouchPoint, ILcdGXYLayerSubsetList aSnappables, ILcdGXYContext aContext) This method controls when you should undo instead of edit.
void	startInteraction(ILcdGXYView aGXYView) Sets up the controller to receive input through the view passed.
protected void	startInteractionImpl(ILcdGXYView aGXYView) The specific implementation of startInteraction for this controller.
void	terminateInteraction(ILcdGXYView aGXYView) Releases a few items.
protected void	terminateInteractionImpl(ILcdGXYView aGXYView) The specific implementation of terminateInteraction for this controller.

Methods inherited from class com.luciad.view.gxy.controller.ALcdGXYChainableController

addStatusListener, removeStatusListener

Methods inherited from class com.luciad.view.gxy.controller.ALcdGXYController

asGXYController, fireStatusEvent, getCursor, getGXYView, getIcon, getName, getShortDescription, isTraceOn, registerInstance, retrieveGXYViewXYWorldTransformation, setClassTraceOn, setCursor, setIcon, setName, setShortDescription, setTraceOn, viewRepaint

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.luciad.view.gxy.ILcdGXYController

getCursor, getIcon, getLayered, getName, getShortDescription, viewRepaint

Constructor Detail

TLcdGXYTouchNewController

public TLcdGXYTouchNewController(ALcdGXYNewControllerModel2 aNewControllerModel)

Creates a new Controller with the specified new controller model.

Parameters:

aNewControllerModel - The new controller model that will be used by this controller.

Method Detail

addUndoableListener

public void addUndoableListener(ILcdUndoableListener aUndoableListener)

Description copied from interface: ILcdUndoableSource

Adds a listener to this source, so this listener is notified when something undoable has happened.

Specified by:

addUndoableListener in interface ILcdUndoableSource

Parameters:

aUndoableListener - The listener to be notified when something undoable has happened.

removeUndoableListener

public void removeUndoableListener(ILcdUndoableListener aUndoableListener)

Description copied from interface: ILcdUndoableSource

Removes the specified listener so it is no longer notified.

Specified by:

removeUndoableListener in interface ILcdUndoableSource

Parameters:

aUndoableListener - The listener to remove.

handleAWTEvent

public void handleAWTEvent(AWTEvent aEvent)

Description copied from interface: ILcdAWTEventListener

This is method is called when the target of the listener has a new AWTEvent available.

Specified by:

handleAWTEvent in interface ILcdAWTEventListener

Parameters:

aEvent - The event to be handled.

setNewControllerModel

public void setNewControllerModel(ALcdGXYNewControllerModel2 aControllerModel)

Sets the ALcdGXYNewControllerModel2 to delegate to.

Parameters:

aControllerModel - the ALcdGXYNewControllerModel2 to delegate to.

See Also:

getNewControllerModel()

getNewControllerModel

public ALcdGXYNewControllerModel2 getNewControllerModel()

Returns the ALcdGXYNewControllerModel2 this controller delegates to.

Returns:

the ALcdGXYNewControllerModel2 this controller delegates to.

See Also:

setNewControllerModel(com.luciad.view.gxy.controller.ALcdGXYNewControllerModel2)

setMoveThreshold

public void setMoveThreshold(int aMoveThreshold)

Sets the threshold for move events.

A move event will only be handled if the move exceeds the threshold in either the x or y direction.

Parameters:

aMoveThreshold - the move threshold

See Also:

getMoveThreshold()

getMoveThreshold

public int getMoveThreshold()

Returns the threshold for move events.

Returns:

the threshold for move events

See Also:

setMoveThreshold(int)

setSnappables

public void setSnappables(ILcdGXYLayerSubsetList aSnappables)

Sets the Objects to snap to when initializing a new created Object.

When null, snapping is disabled.

Parameters:

aSnappables - the new value for the snappables property, or null to disable snapping

See Also:

getSnappables()

getSnappables

public ILcdGXYLayerSubsetList getSnappables()

Returns the Objects to snap to when initializing a new created Object, or null when snapping is disabled.

Returns:

the Objects to snap to when initializing a new created Object, or null when snapping is disabled

See Also:

setSnappables(com.luciad.view.gxy.ILcdGXYLayerSubsetList)

setActionToTriggerAfterCommit

public void setActionToTriggerAfterCommit(ILcdAction aNewActionToTriggerAfterCommit)

Sets the ILcdAction that will be triggered just after this controller component has created a new Object and committed it to an ILcdModel. It might be interesting for example to set an ILcdGXYController ( using a TLcdGXYSetControllerAction) that can edit the new Object, just after this one has been created and initialized. When no action is set, the new controller model will be requested for an object and a layer when creation has been finished or has been canceled.

Parameters:

aNewActionToTriggerAfterCommit - the ILcdAction to be triggered or null if no ILcdAction has to be triggered.

See Also:

TLcdGXYSetControllerAction, getActionToTriggerAfterCommit()

getActionToTriggerAfterCommit

public ILcdAction getActionToTriggerAfterCommit()

Returns the ILcdAction that will be will be triggered just after this controller component has created a new Object, initialized it and committed it to an ILcdModel.

Returns:

the ILcdAction to be triggered after creation of a new Object.

See Also:

setActionToTriggerAfterCommit(com.luciad.gui.ILcdAction)

getEditThreshold

public int getEditThreshold()

This method returns the edit threshold currently used by this controller.

Returns:

the edit threshold

See Also:

setEditThreshold(int)

setEditThreshold

public void setEditThreshold(int aEditThreshold)

Sets the edit threshold. This value controls when an edit will take place. The distance between an edit and a previous edit must be at larger than the value set here for the second edit to have effect.

Parameters:

aEditThreshold - the new edit threshold.

See Also:

getEditThreshold(), shouldCommit(java.lang.Object, int, java.awt.Graphics, com.luciad.input.touch.TLcdTouchPoint, com.luciad.view.gxy.ILcdGXYLayerSubsetList, com.luciad.view.gxy.ILcdGXYContext)

shouldEdit

protected boolean shouldEdit(Object aObject,
                             int aEditCount,
                             Graphics aGraphics,
                             TLcdTouchPoint aTouchPoint,
                             ILcdGXYLayerSubsetList aSnappables,
                             ILcdGXYContext aContext)

This method controls when a edit should take place ( placing a point ). It is called before a new point is added to the object under construction.

By default it returns true for the first edit operation, for clicks when the aContext.getDeltaX or aContext.getDeltaY is greater than the edit threshold, and also for drag operations that have not been preceded by clicks.

Parameters:

aObject - the object currently created.

aEditCount - the number of edits

aGraphics - the graphics the object is painted on

aTouchPoint - the touchPoint descriptor triggering this call

aSnappables - the snappables

aContext - the context @return a boolean indicating whether or not a point should be added to the object under construction.

Returns:

when true the new controller will edit ( add a point to the object under creation ).

shouldUndo

protected boolean shouldUndo(Object aObject,
                             int aEditCount,
                             Graphics aGraphics,
                             TLcdTouchPoint aTouchPoint,
                             ILcdGXYLayerSubsetList aSnappables,
                             ILcdGXYContext aContext)

This method controls when you should undo instead of edit. It is called when shouldEdit returns false.

By default it returns true when isUndoOnSecondTouch returns true and the aContext.getDeltaX and aContext.getDeltaY are smaller than the edit threshold.

Parameters:

aObject - the object currently created.

aEditCount - the number of previous edits

aGraphics - the graphics the object is painted on

aTouchPoint - touchPoint descriptor triggering this call

aSnappables - the snappables

aContext - the context @return a boolean indicating whether or not the last edit should be undone

Returns:

when true the controller will undo the last edit action.

shouldCommit

protected boolean shouldCommit(Object aObject,
                               int aEditCount,
                               Graphics aGraphics,
                               TLcdTouchPoint aTouchPoint,
                               ILcdGXYLayerSubsetList aSnappables,
                               ILcdGXYContext aContext)

This method indicates that the object should be committed. It is called after attempting to edit/undo. The default implementation uses the ALcdGXYNewControllerModel2.getCreationStatus(java.lang.Object, int, java.awt.Graphics, java.awt.event.MouseEvent, com.luciad.view.gxy.ILcdGXYLayerSubsetList, com.luciad.view.gxy.ILcdGXYContext) method and returns true in any of the following cases:

• the object is FINISHED and a drag operation is not ongoing
• the object is COMMITTABLE and the touch event is the end of a drag operation that has not been preceded by a click operation

Parameters:

aObject - the object currently created.

aEditCount - the number of previous edits

aGraphics - the graphics the object is painted on

aTouchPoint - touchPoint descriptor triggering this call

aSnappables - the snappables

aContext - the context @return a boolean indicating whether or not the last edit should be undone

Returns:

when true the controller will commit the current object.

startInteractionImpl

protected void startInteractionImpl(ILcdGXYView aGXYView)

Description copied from class: ALcdGXYChainableController

The specific implementation of startInteraction for this controller.

Overrides:

startInteractionImpl in class ALcdGXYChainableController

Parameters:

aGXYView - the view to start interaction with.

terminateInteractionImpl

protected void terminateInteractionImpl(ILcdGXYView aGXYView)

Description copied from class: ALcdGXYChainableController

The specific implementation of terminateInteraction for this controller.

Overrides:

terminateInteractionImpl in class ALcdGXYChainableController

Parameters:

aGXYView - the view to terminate interaction with.

paintImpl

protected void paintImpl(Graphics aGraphics)

Description copied from class: ALcdGXYChainableController

The specific implementation of paint for this controller.

Overrides:

paintImpl in class ALcdGXYChainableController

Parameters:

aGraphics - the graphics to be used for painting.

getNextGXYController

public ILcdGXYChainableController getNextGXYController()

Description copied from interface: ILcdGXYChainableController

Returns a reference to the controller that is located after this one in a chain, or null if this controller is the last element of the chain.

Specified by:

getNextGXYController in interface ILcdGXYChainableController

Overrides:

getNextGXYController in class ALcdGXYChainableController

Returns:

a reference to the next controller.

See Also:

ILcdGXYChainableController.setNextGXYController(ILcdGXYChainableController)

setNextGXYController

public void setNextGXYController(ILcdGXYChainableController aNext)

Description copied from interface: ILcdGXYChainableController

This method sets the next controller in the chain for this controller. You can set null if you want the chain to end. This method does not start or terminate any interaction. If you need to replace a controller while it's being used you are responsible for properly terminating and starting it yourself.

Specified by:

setNextGXYController in interface ILcdGXYChainableController

Overrides:

setNextGXYController in class ALcdGXYChainableController

Parameters:

aNext - the reference to the controller that will be the next element in the chain

See Also:

ILcdGXYChainableController.getNextGXYController()

appendGXYController

public void appendGXYController(ILcdGXYChainableController aEnd)

Description copied from interface: ILcdGXYChainableController

This method will append the passed controller to the end of the chain. The controller will be the stored as the next controller in the last element of the current chain.

Specified by:

appendGXYController in interface ILcdGXYChainableController

Overrides:

appendGXYController in class ALcdGXYChainableController

Parameters:

aEnd - the controller to be appended to the end of the chain.

startInteraction

public void startInteraction(ILcdGXYView aGXYView)

Description copied from class: ALcdGXYChainableController

Sets up the controller to receive input through the view passed.

All ILcdGXYView implementations that support interaction call this method when the controller has been made active with setGXYController on the view, so this method shouldn't normally be called directly. Note that most view implementations add the controller as listener if appropriate before calling this method.

Sets the cursor on the view and sets the view for which this controller is now active. Sends out a status event based on the short description.

This method also calls ALcdGXYChainableController.startInteraction(com.luciad.view.gxy.ILcdGXYView) on the next controller. Override ALcdGXYChainableController.startInteractionImpl(com.luciad.view.gxy.ILcdGXYView) if you want to add your own behavior to this controller.

Specified by:

startInteraction in interface ILcdGXYController

Overrides:

startInteraction in class ALcdGXYChainableController

Parameters:

aGXYView - the ILcdGXYView this ILcdGXYController will interact with.

See Also:

ALcdGXYChainableController.startInteractionImpl(com.luciad.view.gxy.ILcdGXYView)

terminateInteraction

public void terminateInteraction(ILcdGXYView aGXYView)

Description copied from class: ALcdGXYChainableController

Releases a few items. Can be redefined but this 'super' method should be called too.

This method also calls ALcdGXYChainableController.terminateInteraction(com.luciad.view.gxy.ILcdGXYView) on the next controller. Override ALcdGXYChainableController.terminateInteractionImpl(com.luciad.view.gxy.ILcdGXYView) if you want to add your own behavior to this controller.

Specified by:

terminateInteraction in interface ILcdGXYController

Overrides:

terminateInteraction in class ALcdGXYChainableController

Parameters:

aGXYView - the ILcdGXYView this ILcdGXYController interacted with.

See Also:

ALcdGXYChainableController.terminateInteractionImpl(com.luciad.view.gxy.ILcdGXYView)

paint

public void paint(Graphics aGraphics)

Description copied from class: ALcdGXYChainableController

Enables the controller to give visual feedback on the current user interactions. Note that the controller is responsible for repainting the view.

Empty implementation. Redefine this method to render on the Graphics on which the view is rendered.

This method also calls ALcdGXYChainableController.paint(java.awt.Graphics) on the next controller. Override ALcdGXYChainableController.paintImpl(java.awt.Graphics) if you want to add your own behavior to this controller.

Specified by:

paint in interface ILcdGXYController

Overrides:

paint in class ALcdGXYChainableController

Parameters:

aGraphics - the Graphics on which the view was rendered.

See Also:

ALcdGXYChainableController.paintImpl(java.awt.Graphics)

setGXYView

protected void setGXYView(ILcdGXYView aGXYView)

Description copied from class: ALcdGXYController

Sets the ILcdGXYView the controller is interacting with.

This method is called when ILcdGXYView.setGXYController is used to set an ILcdGXYController active on an ILcdGXYView.

Overrides:

setGXYView in class ALcdGXYController

Parameters:

aGXYView - the view the controller is interacting with

See Also:

ALcdGXYController.startInteraction(com.luciad.view.gxy.ILcdGXYView), ILcdGXYView.setGXYController(com.luciad.view.gxy.ILcdGXYController)

canCommit

public boolean canCommit()

This method indicates whether are not an object is ready to be committed. It will return true when the controller is interacting with a view, a creation process is ongoing and the creation status returned by the new controller model (ALcdGXYNewControllerModel2.getCreationStatus(java.lang.Object, int, java.awt.Graphics, java.awt.event.MouseEvent, com.luciad.view.gxy.ILcdGXYLayerSubsetList, com.luciad.view.gxy.ILcdGXYContext)) is equal to ALcdGXYNewControllerModel2.CreationStatus.COMMITTABLE.

Returns:

A boolean indicating whether are not the object under creation is ready to be committed.

doCommit

public void doCommit()

If canCommit() returns true, this method will commit the object currently under creation, and trigger the action to trigger after commit if it's available.

See Also:

setActionToTriggerAfterCommit(com.luciad.gui.ILcdAction)

canCancel

public boolean canCancel()

This method indicates whether or not it's possible to cancel the creation of the current object. It will return true when this controller is interacting with a view and when a creation process is ongoing.

Returns:

a boolean indicating if the creation of the current object can be cancelled.

doCancel

public void doCancel()

If canCancel() returns true, this method will cancel the creation of the current object.

See Also:

canCancel()

canUndo

public boolean canUndo()

This method indicates whether or not an creation step can be undone. It will return true when this controller is interacting with a view, when a creation process is in progress, and when an undoable is available, meaning there has to have been at least one creation interaction.

Returns:

a boolean indicating whether or not a undo operation is possible.

doUndo

public void doUndo()

When canUndo() returns true, this method will undo the last creation step.

canRedo

public boolean canRedo()

This method indicates whether or not an creation step can be redone. It will return true when this controller is interacting with a view, when a creation process is in progress, and when an redoable is available, meaning that at least one creation step has been undone.

Returns:

a boolean indicating whether or not a redo operation is possible.

doRedo

public void doRedo()

When canRedo() returns true, this method will redo the last creation step that was undone.

isUndoOnSecondTouch

public boolean isUndoOnSecondTouch()

This method indicates whether or not you can undo actions by touching the representation of the last point added in the current object.

Returns:

true when the undo on second touch behaviour is active, false otherwise.

See Also:

setUndoOnSecondTouch(boolean)

setUndoOnSecondTouch

public void setUndoOnSecondTouch(boolean aUndoOnSecondTouch)

A setter to activate of deactivate undo on second touch behaviour. When activated, you can undo actions by touching the representation of the last point added in the current object. The default value is false.

Parameters:

aUndoOnSecondTouch - the boolean indicating whether or not the undo on second touch behaviour should be activated.

See Also:

isUndoOnSecondTouch(), shouldUndo(java.lang.Object, int, java.awt.Graphics, com.luciad.input.touch.TLcdTouchPoint, com.luciad.view.gxy.ILcdGXYLayerSubsetList, com.luciad.view.gxy.ILcdGXYContext)

getObject

public Object getObject()

Returns the object that the controller is creating. Note that this object can be replaced during the creation, for example, when calling ALcdGXYNewControllerModel2.edit(java.lang.Object, int, java.awt.Graphics, java.awt.event.MouseEvent, com.luciad.view.gxy.ILcdGXYLayerSubsetList, com.luciad.view.gxy.ILcdGXYContext).

Returns:

the object that the controller is creating, or null if no object is being created

getGXYLayer

public ILcdGXYLayer getGXYLayer()

Returns the layer visualizing the object that the controller is creating.

Returns:

the layer visualizing the object that the controller is creating, or null if no object is being created