tsc_JobPolylines

This class represents all polylines within a job.  A polyline is essentially a list of line and arc segments which, when connected together, form a single object. This list of line segments is known as the polyline's Parts.

Each line or arc segment is in turn defined by two or three points respectively. For a line, the two endpoints are used, and an arc is defined by the two endpoints plus a point anywhere on the arc between the endpoints. In some API calls, the start point of a part is omitted since it can be inferred from the previous part's end point.

Internally, Trimble Access supports two types of polyline:

• Live polylines, where the points that make up the parts are identified by a name or a tsc_Point object. Most polylines in new jobs are of this type. If a point that forms part of a polyline part changes position, then the polyline will also change to accommodate the new position.

• Legacy polylines, where the points that make up the parts of the polyline are defined as absolute grid coordinates, which will never move. This type of polyline is generally found in older Trimble Access jobs.

• Polylines can also be created when a feature code file is used with appropriately coded points to join them up into a polyline. These behave like Live polylines, only exist while the job is open, and are recreated every time the job is opened as the current job. They are also dependent on the feature code library currently loaded.

Member functions are provided to obtain lists of polylines (see class tsc_PolylineList) filtered in various ways.  A tsc_PolylineList also contains member functions to further filter the list down to the required set.

Other functions allow the addition of new polylines, deletion, utility functions to help with naming polylines, etc.

A reference to the tsc_JobPolylines is obtained from the Polylines() method in tsc_Database.  The reference remains valid until the job is closed.

See also

• tsc_PolylineObservation (An instance of a polyline in a job)

• tsc_PolylineList (A list of polyline observations)

• tsc_PolylineDefinition (The definition of one polyline)

• tsc_PolylineParts (A list of the parts - lines and arcs as grid coordinates)

• tsc_PolylinePointParts (A list of the parts - lines and arcs defined by point objects)

Case-sensitivity in polyline names

Names within Survey Core are case-sensitive, but to the outside world (i.e., the user) they are not.  To make this work, every name obtained from an external source, which also exists in the job, must be altered to the correct case before it is used internally, and Trimble Access normally takes care of this.  In practice there are only a small number of cases where this is necessary. 

Note that each entity type (Lines, Points, Arcs, Polylines) has its own namespace, so it is possible to have, for example, a polyline and a point of the same name but remain distinct entities.

The AdjustNameCase function may be used to change a name's case to that of any existing polyline:

tsc_String AdjustNameCase (const char* name);
Any name that the plugin obtains externally to SC (a file, a form field, etc) must be run through this function before use.  If the name does not case-insensitively exist in the current job, then no change is made to the name.  If a case-insensitive match already exists, the name is updated to the same case. The name, adjusted or not, is returned.  This function has a lower performance for names that do not exist in the database, or whose case is different from an existing name.

tsc_JobPolylines member functions

The Snapshot function obtains a snapshot of the job's polylines at the current time.  Use these for iterating through a list of polylines, when a copy is required for filtering or other modification, and any other time that arc information is required.  The list is in the sequence that the polylines were added to the database and includes deleted ones.

tsc_PolylineList  Snapshot();
Obtain a list of all polylines - live and legacy -  in the job. If other jobs are attached, they will also be scanned for legacy polylines and included in the list. Live polylines in attached jobs are omitted because they would be dependent on the attached job's position resolution, which is unavailable.

tsc_Polyline GetPolyline(const char* name);
This function returns a reference to the polyline of the name supplied.  The name must have the correct case - if it hasn't, then first fix it with the AdjustNameCase member of the tsc_JobPolylines class.  If no polyline  with the given name is found, the returned object will be empty, and its Exists() function will return false.

tsc_String NextUniqueName (const char* polylineName, int stepSize = 1);
Generates a unique polyline name. Supply a name containing a numeric segment, and a step size. A polyline name that is unique within the database will be generated by incrementing the numeric segment by the step size until a unique name is found.   Alphabetic characters may also be incremented when there is no suitable numeric part (e.g. POLY99 increments to POLZ00). When many names must be generated, it is more efficient to remember the output name from each call, and pass it back in when generating the next name. For example, passing POLY00 into a series of calls will generate POLY00, POLY01, POLY02, etc but passing in the previous name (POLY01 etc) generates the same sequence but quicker.

Note that a polyline name is only considered to be used when a polyline actually exists, so a simple series of calls to NextUniqueName will generate the same name every time if the polyline is not stored.

x_Code Append (class tsc_PolylineObservation& obs);
Appends a polyline to the database.  After calling an Append method, the added polyline will appear in lists produced by subsequent calls to Snapshot(). A return code of X_NULL indicates success, and any other value will hint at what's gone wrong.

x_Code Delete (tsc_Polyline& polyline);
Deletes a polyline from the job.  The polyline will still appear as an item in the list produced by a subsequent Snapshot() but will be marked as deleted. A return code of X_NULL indicates success.

x_Code UnDelete (tsc_Polyline& polyline);
Un-Deletes a previously-deleted polyline in the job. A return code of X_NULL indicates success.