【Connect C++】what is the difference between the return value true and false of these DgnTool's Function?

管华明 said:

what is the difference between the return value true and false?

virtual bool _OnDataButton ( DgnButtonEventCR ev )

Called when a data point is entered.

The initial data point will populate the tool's ElementAgenda. _ProcessAgenda and _OnModifyComplete will be called immediately if tool returns false for NeedAcceptPoint, otherwise this will happen on the next data button. If the tool returns true for WantDynamics then BeginComplexDynamics will be called after elements have been identified.

virtual bool _OnResetButton ( DgnButtonEventCR ev )

Called when a reset is entered.

If SOURCE_Pick and no elements have been identified, the Auto-Locate reset to find the next element is called. If an element is identified, reset will cycle to the next element, if there is no next element _OnReinitialize is called. For SOURCE_Fence and SOURCE_Selection set _ExitTool is called.

Help doesn't mention the purpose of the return value.

Jon Summers said:

Help doesn't mention the purpose of the return value.

Hi Jon Summers,

In my MSCE SDK U12 "sdkhelp", Help topic: "DgnElementSetTool Struct Reference" > "Mouse Events"; clicking "More..."; I see information on the virtual bool return values as:

and

virtual bool _OnResetButton  ( DgnButtonEventCR  ev )
...
Returns
true if _ExitTool or OnReinitalize was called and tool object has been freed. 

Bob

Robert Hook said:

I see information on the virtual bool return values as: true if _ExitTool was called and tool object has been freed

Yes, but that's not actually helpful to someone who is unfamiliar with MicroStation's primitive command paradigm.  For example...

true if _ExitTool was called and tool object has been freed

Who calls _ExitTool?  The phrasing implies that that method was called by something else in the framework.  Or, is the user supposed to call _ExitTool?

When is the tool object freed?  Surely that happens when another primitive command has been started?  The tool is, I hope, held somewhere as a smart pointer and will be freed automatically.

If either of the above is true, how will the tool continue?  Should the programmer create a new instance of his DgnElementSetTool? If not, how does the programmer allow this tool to restart automatically as a user expects?

As Jan wrote, the best approach is to study the SDK examples, and do as the examples do.

Short answer: You can always return false from OnDataButton/OnResetButton because nothing checks the status.

/*---------------------------------------------------------------------------------**//**
* Called when a data point is entered.
* @param ev IN Current button event.
* @return Default is false. Sub-classes may ascribe special meaning to this status.
* @bsimethod
+---------------+---------------+---------------+---------------+---------------+------*/
virtual bool _OnDataButton (DgnButtonEventCR ev) = 0;
virtual bool _OnDataButtonUp (DgnButtonEventCR ev) {return false;}

The return value only has meaning to sub-classes of DgnTool and it's only of importance if you override these methods and call super.

DgnElementSetTool is a framework Jon. When you override _OnDataButton and call super it's trying to use the return status to communicate the current tool state.

By default DgnElementSetTool is setup to do the following (when not operating on a fence or selection set):

- First data button locates an element and start dynamics. The return status will be false to denote that the tool hasn't completed and is still the active tool.

- Second data button accepts the modification and the tool will have either exited or restarted according to the implementation of _OnRestartTool. The return status will be true to denote that the tool is no longer the active tool and you should immediately return without doing anything further because another tool instance is now active.

DgnElementSetTool tries to encapsulate a lot of common tool requirements to ensure standard tool behavior while still allowing a high degree of customization. OnDataButton is the most common event that advances the tool state, so the DgnElementSetTool implementation of OnDataButton has a lot to do and orchestrates calling many other virtual tool methods so that sub-classes can control what happens.

Short answer: You can always return false from OnDataButton/OnResetButton because nothing checks the status.

/*---------------------------------------------------------------------------------**//**
* Called when a data point is entered.
* @param ev IN Current button event.
* @return Default is false. Sub-classes may ascribe special meaning to this status.
* @bsimethod
+---------------+---------------+---------------+---------------+---------------+------*/
virtual bool _OnDataButton (DgnButtonEventCR ev) = 0;
virtual bool _OnDataButtonUp (DgnButtonEventCR ev) {return false;}

The return value only has meaning to sub-classes of DgnTool and it's only of importance if you override these methods and call super.

DgnElementSetTool is a framework Jon. When you override _OnDataButton and call super it's trying to use the return status to communicate the current tool state.

By default DgnElementSetTool is setup to do the following (when not operating on a fence or selection set):

- First data button locates an element and start dynamics. The return status will be false to denote that the tool hasn't completed and is still the active tool.

- Second data button accepts the modification and the tool will have either exited or restarted according to the implementation of _OnRestartTool. The return status will be true to denote that the tool is no longer the active tool and you should immediately return without doing anything further because another tool instance is now active.

DgnElementSetTool tries to encapsulate a lot of common tool requirements to ensure standard tool behavior while still allowing a high degree of customization. OnDataButton is the most common event that advances the tool state, so the DgnElementSetTool implementation of OnDataButton has a lot to do and orchestrates calling many other virtual tool methods so that sub-classes can control what happens.

Brien Bastings said:

You can always return false from OnDataButton/OnResetButton because nothing checks the status

That's the information that the OP is looking for.

The long answer informs the rest of us.  Thanks!