tsc_JobMapAutopanEventArgs

An instance of this class is passed to the event handler tsc_JobMap::OnAutopan().  It contains information about the current state of the map (tsc_JobMapStateEventArgs), plus a bounding rectangle (often called a bounding box), and methods which control how the map's Autopan system responds to changes in position. 

Autopan is used to keep a point or area in view at all times.  Without a plugin, the map will keep the current position displayed on the map window, provided the Autopan option is turned on.  Autopan can also be paused automatically if the user manually pans away from the current position, and resumes when the user pans so that the current position is within the window again.

The map screen-snap to the right illustrates how the Autopan system operates when used by a plugin.  The red and green rectangles are never drawn, they are only shown here illustrate areas the plugin has defined.

The red outline illustrates a Leeway area within which the Bounding box (green) is allowed to move.  The OnAutopan() event handler is called regularly (typically once per second).  It must specify a leeway area and a bounding box each time it is called.  If any part of the bounding box (which is often simply a point) falls outside of the leeway area, then the map is panned and/or zoomed to provide the best fit possible of the bounding box within the leeway area. The leeway area is given as a simple percentage of the window size.  In the example it has been specified at 90%, which leaves a margin of 5% on each of the four sides.

The bounding box, which is shown in green in the picture, is contained in the base class of the event arguments (the class being described on this page) which is passed to the OnAutopan() event handler.  The bounding box contains four grid ordinates; North, East, South, and West.  When OnAutopan is called, the North and South values are initialized to the current grid position North value, and East and West are initialized to the current position East value, which amounts to a zero-size rectangle (ie, a point) at the current position.  The plugin may then modify the bounding box; upon return from OnAutopan the modified values are used to pan and zoom the map.

If there is no known current position, all bounding box values are initially set to double_Null.  The initial values need not be used; the bounding box may be calculated in any way desired.  If the current position is not required, call Clear() to set the bounding box to double_Null.  If the bounding box is null when OnAutopan returns, no zooming or panning will occur.  If it contains just a single point no zooming will occur, however the point will be panned to the center if it falls outside of the leeway area.

The easiest way to adjust the bounding box is to add points to it by calling Extend(). The bounding box will always be the smallest rectangle that encompasses all of the points added to it.  It is also possible to manipulate the four values directly, however we recommend using Extend so that null values are handled correctly.

Note that the automatic pausing of autopan can only occur if the bounding box contains a single point. 

In the example picture, the bounding box has been extended with points R1, R2, and R3.  It does extend outside the leeway area, and therefore a pan (and probably a zoom-in also) will occur.  The result will be the bounding box centered within the leeway area and sized as large as possible to fit within it.

In summary

• All the points in the bounding box are kept inside the leeway area.

• If the bounding box fits entirely in the leeway area, no panning occurs, although a zoom-in is possible.

• The smaller the leeway area, the more often the map will pan to keep moving points near the center.

• The smaller the bounding box, the tighter the map will zoom in.  If the bounding box is a point, no zooming will occur.

• By default (when the plugin does nothing) the map uses only the current position for autopan, and does no automatic zooming.

• The default leeway area is 100% of the screen.

• If zooming occurs, the scale will always be rounded off to i * 10j, where i and j are integers, except i may also be 1.5 or 2.5.

Public members

class tsc_JobMapAutopanEventArgs : public tsc_JobMapBounds

This class is subclassed from tsc_JobMapBounds, which contains the bounding box members.

tsc_JobMapStateEventArgs&  State;

Allows access to the current state of the map.

tsc_Grid CurrentPosition ();

Returns the current position derived from the current instrument, or possibly from the built-in GPS receiver if there is one and GPS Search is running.

void SetLeeway (int percentageOfWindow);

This method controls the map's sensitivity for panning and zooming. The parameter value is a percentage of the map window's width or height, and defines a "leeway area" inside which the bounding box is always kept. The leeway rectangle is centered in the window with a width and height given by percentageOfWindow.  Upon return from OnAutopan(), if any part of the bounding box (from the base class) falls outside the leeway area then the map is panned and/or zoomed so that it fits.

The larger the leeway, the closer objects in the bounding box may come to the edge of the map window before being panned or zoomed.  The default is 100%, and this value allows up to about half an object's icon to be off the screen before it is moved back into view.

Note: Avoid small values of leeway; they may affect performance with excessive map redraws, and also cause the map to be zoomed-out to an undesirable degree. Values > 70% are suggested.