All complex mouse modes provide information to the client, either synchronously or asynchronously, as controlled by a boolean argument isSyncronous. Synchronous response is simpler, in that the client need not expose an API. However, synchronous response is desirable only when a single response from the user is required. If it is desirable to maintain a mouse mode for an indefinite number of user operations, the asynchronous approach becomes more attractive.
To obtain information asynchronously, the client must:
Identify itself to the MouseModeAPI object, via setReceiver, and
Expose appropriate methods in its own API, as described under Client Services.
Call a method that sets a complex mouse mode, with isSynchronous = FALSE.
The appropriate client service will be called by the SDM each time the user completes the mouse operation prescribed by the method called in step 3, and provide the corresponding information. Thus, the client can conveniently process the results from a series of identical mouse operations. To end the series, i.e. prevent further operations resulting in calls to the client service, the client must call setNeutralMode, or set some other mouse mode.
To obtain information synchronously, the client must:
Call a method that sets a complex mouse mode, with isSynchronous = TRUE.
Call isSynchronousOpComplete at regular intervals, i.e. in a loop, until it returns TRUE.
Call setNeutralMode to prevent further operations
Call the appropriate MouseModeAPI selector(s) to obtain information.
It is possible to perform a series of identical mouse operations synchronously, by repeating steps 1 through 4 over and over. However, care must be taken. First, it is important to call setNeutralMode immediately after isSynchronousOpComplete returns TRUE, to prevent further mouse operations. Such operations would appear to the user to be processed correctly, because the SDM will remain in the mouse mode set by step 1 until setNeutralMode is called. But, once the user has completed the first operation, i.e. isSynchronousOpComplete returns TRUE, the client has no way to tell whether any further operations have completed. Thus, the correct strategy is to 1) set the mode, 2) wait until the user completes and operation, 3) prevent further operations, 4) obtain the information, 5) repeat if desired.
Below is a Visual C++ example that shows how to obtain a selected location from the user, synchronously.
!(m_mouseModeAPI->isSynchronousOpComplete()) && int cnt<30
if( cnt >= 30 )
CString x = m_mouseModeAPI->getX();
CString y = m_mouseModeAPI->getY();