【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.

Well, I guess it does, but as the standalone information it's not very helpful. On the other hand, when merged with discussions about the mentioned methods (they have been discussed quite often) and analysis of SDK examples source code, it makes more sense.

管华明 said:

I don't know under what circumstances should return true, and what circumstances should return false

I haven not implemented many DgnTool classes yet, but I guess the return value is an information whether the function has been finished / reinitialized or the event is a part of longer continuous process. It can be seen from two different perspectives / can be used in two different ways:

As value returned when you call __super::OnDataButton method in your code. You can use returned value to check in what situation the method was called. Also from overriden method _super is often called as the last step to finish the process of last data point and the value returned by super is returned also by the code.

The second situation is when your code (in overriden method) explicitely returns TRUE or FALSE. In this situation, FALSE means the tool is running (e.g. there will be more data points, dynamics starts...), TRUE means the tools has been finished (e.g. based on the data point element was added to model and the tool has been restarted).

I recommend to search existing discussions and also to search examples delivered with SDK (usually when element is added, TRUE is returned, because it was the last step in the tool's workflow, otherwise FALSE)

I hope Brien Bastings will correct my explanation where it's not precise or is incorrect.

With regards,

  Jan

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.

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!