long setLineDrawingMode(bool isSynchronous, int lenUnitEnum, int nSeg)
This method sets the state of the SDM such that two or more mouse clicks in a view draws a series of connected line segments, i.e. a "polyline". The user can also use click and drag to draw the line segments. There are two distinct approaches to using this method:
Preset number of segments
as determined by the argument nSeg. If nSeg is a positive integer, it determines the number of segments to be collected before the operation is considered complete. If nSeg is zero, the line-drawing operation is open ended. In this case, the operation does not complete until the client calls setNeutralMode. (Normally, the client will make this call in response to a user action on its own GUI.) The drawn polyline is temporary, i.e. once the operation is complete, the polyline is removed.
The client using isSynchronous = TRUE must test for completion of the operation via isSynchronousOpComplete (see Synchronous vs. Asynchronous Response). Note that in the open-ended approach, it does not make sense to begin the testing cycle until after the client has called setNeutralMode. After isSynchronousOpComplete returns TRUE, the client must call getXList and getYList to obtain the list of locations clicked. The client may also call getInitlPixelSize and getFinalPixelSize to obtain the pixel sizes at the time of the first and last mouse clicks, respectively. The client may also obtain the index of the view in which the user drew the polyline via getRespondingViewIndex, provided that there was only one view involved (see below).
The client using isSynchronous = FALSE, must have previously identified itself to the MouseModeAPI object via setReceiver, and exposed the method receiveLocList (see Synchronous vs. Asynchronous Response). When the operation is complete, the SDM will call the latter. Note that in the open-ended approach, receiveLocList will not be called until after the client has called setNeutralMode. When receiveLocList is called the list of locations clicked and the initial and final pixel sizes are always provided as arguments. The index of the view in which the user drew the polyline is also provided, if there was only one view involved (see below).
The argument lenUnitEnum is currently ignored.
During an open-ended operation only, the SDM supports:
The collection of single points, i.e. incomplete line segments.
Polylines that span views, i.e. a polyline that begins on one map and continues on another, or as many as desired.
Thus, if setNeutralMode is called after the user clicks just one location, that location will be available via getXList and getYList for the synchronous approach, or that location will be provided to receiveLocList for the asynchronous approach. If setNeturalMode is called after the user clicks in more than one view, the SDM automatically assembles the polyline fragments in the correct order and concatenates them for return by getXList and getYList, or to be sent to receiveLocList. If multiple views are involved, getRespondingViewIndex returns -1 or the respondingViewIndex (fifth) argument to receiveLocList will be -1.
Migration note for v2.5 developers: setLineDrawingMode in 2.5 with arg1=TRUE, corresponds to setLineDrawingMode in 3.2, when used isSynchronous=FALSE with nSeg=0; setLineDrawingMode in 2.5 with arg1=FALSE corresonds to setNeutralMode in 3.2.