tsc_PointField
The tsc_PointField is used for entering point names. Depending on the options specified, the field may be used for entering a new (non-existing) point name, for entering an existing name, or for selecting an existing point. In any case, Survey Core must have a currently open job; the best way to achieve this is to require a job in the tsc_UITask that is responsible for this form and field.
The tsc_PointField was added in version 1.70 of Survey Core, a part of Trimble Access 2011.10.
The screen-snap to the right shows a point field with the context menu displayed. All possible items in the menu are shown in the screen-snap, and whether a menu item is shown or not is controlled using properties on the point field. Note that the Map selections item is greyed out because there are no points currently selected in the map.
The default for the context menu is to show nothing and hide the button; if an item is required it must be turned on.
Constructors
tsc_PointField (x_Code identifier);
Constructs a point name field with a prompt obtained from identifier.
tsc_PointField (x_Code identifier, const char* initialName);
Constructs a point name field with the supplied prompt (identifier) and preloads the field with the supplied name.
Enumerations
enum tsc_PointExistence
This enumeration controls warning and error messages relating to whether the entered point name exists in the current job database. An error means that the field will not be accepted until the name is corrected.
tsc_PointExists_Any
Any point name may be entered, whether it exists or not. No errors or warnings are issued.
tsc_PointExists_ErrorIfNot
The point must exist - an error is shown if it does not.
tsc_PointExists_WarnIfNot
A warning message is shown if the point does not exist.
tsc_PointExists_WarnIfSo
A warning is shown if the point exists. The form may still be submitted.
tsc_PointExists_ErrorIfSo
The point must not exist - an error is shown if it does.
enum tsc_PointRequiredType
This enumeration is used to validate user input and filter point lists to only those points that may be converted to a particular coordinate type. If no required type is specified (by the RestrictType() method) then any coordinate type is allowed.
tsc_PointRequiredType_Any
The point selected may be any coordinate type.
tsc_PointRequiredType_WGS84
The point entered must be convertible to a WGS84 coordinate. Point lists will show only these points.
tsc_PointRequiredType_Grid
The point entered must be convertible to a Grid coordinate. Point lists will show only these points.
Public methods
tsc_String Value () const;
Returns the field value, which is the point name.
void Value (const char* pointName);
Sets the field value, which is the point name. If the point exists (and this is permitted) then the point associated with the field is set to the best point of the given name. This may result in the case of the letters in the field being altered to match the existing point name.
Note: If the Existence property has been set to tsc_PointExists_ErrorIfNot, the user is required to enter a point that exists. However, if the Value() method is used to populate the field with a non-existent point, no error will occur until the form is submitted, either with the enter key or button or by closing the form with a dialog result of tsc_DialogResult_Ok. The form can still be cancelled (using Esc etc) without error.
void NextUniqueValue (int stepSize = 1);
Attempts to increment the current point name by the specified step count, and populates the field with a point name that is unique (i.e. unused within the current job).
tsc_Point Point () const;
Returns the chosen point. The point returned will generally be the best point for the name in the field. If the field is empty or the point named in the field does not exist, then an empty point will be returned (the Exists() method returns false). In such a case, use the Value method to obtain the point name.
void Point (tsc_Point newPoint);
Sets the field to a specific existing point.
void Existence (existRequirements);
Controls whether the point must exist or not. The default is don't care. The option may specify either a warning or an error. If an error occurs (eg, tsc_PointExists_ErrorIfNot has been specified and the user has entered a point name that doesn't exist) then the form cannot be submitted until the name has been corrected. See the tsc_PointExistence enumeration above for more information. This property cannot be changed after the field has been displayed, through calling form.ShowDialog().
void RestrictType (tsc_PointRequiredType reqType);
Restricts the coordinate type of the points that may be selected, and is only applicable when used in conjunction with existing points. The default is to allow any coordinate type. A point is allowed if it is of the type specified, or is able to be converted to that type. This option is used to filter any list of points the user may request via the context menu. This property cannot be changed after the field has been displayed, through calling form.ShowDialog().
void AllowCheckshot (bool allow);
Check shot points are rarely used and are therefore normally not allowed in a point name field. Use this property to allow check-shots to be entered. This property cannot be changed after the form has been displayed.
void CopyCsvToDatabase (bool doCopy);
Often when a point is selected from a linked CSV file, it cannot be used because it does not exist in the current job database. By setting this property to true for the field, the CSV point will be automatically added to the job database when the field is accepted, if it is not already in the job.
void MenuIncludeList (bool include);
Includes the List item in the field context menu, which by default is not included. The List item allows the user to obtain a list of points and to select one.
void MenuIncludeFind (bool include);
Includes the Find item in the field context menu, which by default is not included. The Find item allows the user to enter a point name and Survey Core will increment the point name to the first subsequent unused point name. This option is not useful if the Existence property specifies that the point must exist (tsc_PointExists_ErrorIfNot).
void MenuIncludeMap (bool include);
Includes the Map selection item in the field context menu, which allows the user to select from a list of points currently selected in the map. By default the Map selection item is not displayed. If no items are currently selected in the map, the item will be greyed out.
void MenuIncludeKeyIn (bool include);
Includes the Key in menu item, which allows the user to key in a point. By default this item is not displayed.
void MenuIncludeMeasure (bool include);
Includes the Measure menu item which allows the user to measure a point. By default this item is not included. When this option is chosen, a new survey will be started if one is not already running.
Validating a point name
Sometimes it is useful to ensure that a point name follows some sort of naming scheme, or conforms to some other criteria. The sample below shows the essential parts of a form that will validate the name (in this case simply checking that it begins with a "p") and prevents the form being submitted until the name has been entered correctly.
class PointForm : public tsc_Form { tsc_PointField* pf; PointForm () { pf = new tsc_PointField (X_PointName, "P100"); this->Controls.Add(pf); } virtual bool OnFieldCompleted (tsc_Control& control) { if (control.GetIdentifier() == pf->GetIdentifier()) { if (!pf->Value().StartsWith ("p", Case_Insensitive)) { pf->DisplayWarningTip ("Name must start with a 'P'!"); } } return true; } virtual bool OnFormClosing(tsc_DialogResult result, bool modified, tsc_FormClosingPermission& permission) { if (result == tsc_DialogResult_Ok && !pf->Value().StartsWith ("p", Case_Insensitive)) { pf->DisplayWarningTip ("Point name doesn't start with a 'P'!"); permission = FormClosing_Deny; } return true; } };
