Gocator API
GoTool.h
Go to the documentation of this file.
1 /**
2  * @file GoTool.h
3  * @brief Declares the base GoTool class.
4  *
5  * @internal
6  * Copyright (C) 2016-2025 by LMI Technologies Inc.
7  * Licensed under the MIT License.
8  * Redistributed files must retain the above copyright notice.
9  */
10 #ifndef GO_TOOL_H
11 #define GO_TOOL_H
12 
13 #include <GoSdk/GoSdkDef.h>
14 #include <GoSdk/Tools/GoMeasurements.h>
15 #include <GoSdk/Tools/GoMeasurement.h>
16 #include <GoSdk/Tools/GoFeatures.h>
17 #include <GoSdk/Tools/GoFeature.h>
18 
19 #include <kApi/Data/kXml.h>
20 
21 /**
22  * @class GoTool
23  * @extends kObject
24  * @ingroup GoSdk-Tools
25  * @brief Represents the base tool class.
26  */
27 typedef kObject GoTool;
28 
29 /**
30  * Returns the measurement count.
31  *
32  * @public @memberof GoTool
33  * @version Introduced in firmware 4.0.10.27
34  * @param tool GoTool object.
35  * @return The measurement count.
36  */
37 GoFx(kSize) GoTool_MeasurementCount(GoTool tool);
38 
39 /**
40  * Retrieves the measurement at the given index.
41  *
42  * @public @memberof GoTool
43  * @version Introduced in firmware 4.0.10.27
44  * @param tool GoTool object.
45  * @param index The index of the measurement.
46  * @return The measurement at the given index or kNULL if an invalid index is provided.
47  */
48 GoFx(GoMeasurement) GoTool_MeasurementAt(GoTool tool, kSize index);
49 
50 /**
51  * Returns the feature output count.
52  *
53  * @public @memberof GoTool
54  * @version Introduced in firmware 4.6.3.27
55  * @param tool GoTool object.
56  * @return The feature output count.
57  */
58 GoFx(kSize) GoTool_FeatureOutputCount(GoTool tool);
59 
60 /**
61  * Retrieves the feature output at the given index.
62  *
63  * @public @memberof GoTool
64  * @version Introduced in firmware 4.6.3.27
65  * @param tool GoTool object.
66  * @param index The index of the feature output.
67  * @return The feature output at the given index or kNULL if an invalid index is provided.
68  */
69 GoFx(GoFeature) GoTool_FeatureOutputAt(GoTool tool, kSize index);
70 
71 /**
72  * Sets the name of the tool.
73  *
74  * @public @memberof GoTool
75  * @version Introduced in firmware 4.0.10.27
76  * @param tool GoTool object.
77  * @param name The name to be set for the tool.
78  * @return Operation status.
79  */
80 GoFx(kStatus) GoTool_SetName(GoTool tool, const kChar* name);
81 
82 /**
83  * Retrieves the name of the tool.
84  *
85  * @public @memberof GoTool
86  * @version Introduced in firmware 4.0.10.27
87  * @param tool GoTool object.
88  * @param name Receives the name of the tool.
89  * @param capacity The maximum capacity of the name array.
90  * @return Operation status.
91  */
92 GoFx(kStatus) GoTool_Name(GoTool tool, kChar* name, kSize capacity);
93 
94 /**
95  * Retrieves the id of the instance of the tool.
96  *
97  * @public @memberof GoTool
98  * @version Introduced in firmware 5.1.1.28
99  * @param tool GoTool object.
100  * @return The instance id of the tool.
101  */
102 GoFx(k32s) GoTool_Id(GoTool tool);
103 
104 /**
105  * Retrieves the tool type enumeration value of the tool.
106  *
107  * @public @memberof GoTool
108  * @version Introduced in firmware 4.0.10.27
109  * @param tool GoTool object.
110  * @return The tool type enumeration value.
111  */
112 GoFx(GoToolType) GoTool_Type(GoTool tool);
113 
114 /**
115  * Retrieves the first found instance of a measurement for a given enumeration type.
116  *
117  * @public @memberof GoTool
118  * @version Introduced in firmware 4.0.10.27
119  * @param tool GoTool object.
120  * @param type A GoMeasurementType representing the measurement type to find in the given tool.
121  * @return A measurement object if one is found, otherwise kNULL.
122  */
123 GoFx(GoMeasurement) GoTool_FindMeasurementByType(GoTool tool, GoMeasurementType type);
124 
125 /**
126  * Retrieves the instance of a feature output for a given enumeration type.
127  *
128  * @public @memberof GoTool
129  * @version Introduced in firmware 4.6.3.27
130  * @param tool GoTool object.
131  * @param type A GoFeatureType representing the feature output type to find in the given tool.
132  * @return A feature object if one is found, otherwise kNULL. Returns the first found.
133  */
134 GoFx(GoFeature) GoTool_FindFeatureOutputByType(GoTool tool, GoFeatureType type);
135 
136 /**
137  * Adds the given measurement to the tool set.
138  *
139  * @public @memberof GoTool
140  * @version Introduced in firmware 4.8.2.76
141  * @param tool GoTool object.
142  * @param type The type of the measurement.
143  * @param isFilterable Indicates whether the measurement can be toggled and filtered;
144  * @param measurement A pointer to hold a reference to the created measurement (can be null).
145  * @return Operation status.
146  */
147 GoFx(kStatus) GoTool_AddMeasurement(GoTool tool, kType type, kBool isFilterable, GoMeasurement* measurement);
148 
149 /**
150  * [Deprecated]
151  *
152  * Adds the given custom measurement to the tool set.
153  *
154  * @deprecated
155  * @public @memberof GoTool
156  * @version Introduced in firmware 4.8.2.76
157  * @param tool GoTool object.
158  * @param type The type of the measurement.
159  * @param isFilterable Indicates whether the measurement can be toggled and filtered;
160  * @param measurement A pointer to hold a reference to the created measurement (can be null).
161  * @return Operation status.
162  */
163 GoFx(kStatus) GoTool_AddExtMeasurement(GoTool tool, kType type, kBool isFilterable, GoExtMeasurement* measurement);
164 
165 /**
166  * Removes a measurement at a given index.
167  *
168  * @public @memberof GoTool
169  * @version Introduced in firmware 4.8.2.76
170  * @param tool GoTool object.
171  * @param index The index of the measurement to remove.
172  * @return Operation status.
173  */
174 GoFx(kStatus) GoTool_RemoveMeasurement(GoTool tool, kSize index);
175 
176 /**
177  * Removes all measurements for the given tool.
178  *
179  * @public @memberof GoTool
180  * @version Introduced in firmware 4.8.2.76
181  * @param tool GoTool object.
182  * @return Operation status.
183  */
184 GoFx(kStatus) GoTool_ClearMeasurements(GoTool tool);
185 
186 /**
187  * Adds the given feature output to the tool set.
188  *
189  * @public @memberof GoTool
190  * @version Introduced in firmware 5.1.4.38
191  * @param tool GoTool object.
192  * @param type The type of the feature.
193  * @param featureOutput A pointer to hold a reference to the created feature output (can be null).
194  * @return Operation status.
195  */
196 GoFx(kStatus) GoTool_AddFeatureOutput(GoTool tool, kType type, GoFeature* featureOutput);
197 
198 /**
199  * Removes a feature output at a given index.
200  *
201  * @public @memberof GoTool
202  * @version Introduced in firmware 5.1.4.38
203  * @param tool GoTool object.
204  * @param index The index of the feature output to remove.
205  * @return Operation status.
206  */
207 GoFx(kStatus) GoTool_RemoveFeatureOutput(GoTool tool, kSize index);
208 
209 /**
210  * Removes all feature outputs for the given tool.
211  *
212  * @public @memberof GoTool
213  * @version Introduced in firmware 5.1.4.38
214  * @param tool GoTool object.
215  * @return Operation status.
216  */
217 GoFx(kStatus) GoTool_ClearFeatureOutputs(GoTool tool);
218 
219 /**
220  * Checks if the given tool is a GoExtTool or not. GoExtTool stands for "Gocator extensible tool".
221  * These types of tools require using APIs specifically for these tools in order to properly access information in this tool.
222  * For example, one would have to use "GoExtTool_XAnchor" rather than "GoSurfaceTool_XAnchor" to access the tool's X Anchor if the tool is a GoExtTool.
223  * Knowing if a given tool is a GoExtTool or not is not intuitive, so this function helps to determine it.
224  *
225  * @public @memberof GoTool
226  * @version Introduced in firmware 6.4.39.2
227  * @param tool GoTool object.
228  * @return kTRUE if the given tool is a GoExtTool or a subclass of it. kFALSE if it's a different kind of tool.
229  */
230 GoFx(kBool) GoTool_IsGoExtTool(GoTool tool);
231 
232 #include <GoSdk/Tools/GoTool.x.h>
233 
234 #endif
GoToolType
Lists all tool types.
GoTool::GoTool_FindMeasurementByType
GoMeasurement GoTool_FindMeasurementByType(GoTool tool, GoMeasurementType type)
Retrieves the first found instance of a measurement for a given enumeration type. ...
GoMeasurement
Represents the base class for a tool measurement or script output.
GoTool::GoTool_Id
k32s GoTool_Id(GoTool tool)
Retrieves the id of the instance of the tool.
GoTool::GoTool_RemoveMeasurement
kStatus GoTool_RemoveMeasurement(GoTool tool, kSize index)
Removes a measurement at a given index.
GoMeasurement.h
Declares the GoMeasurement class.
GoTool::GoTool_RemoveFeatureOutput
kStatus GoTool_RemoveFeatureOutput(GoTool tool, kSize index)
Removes a feature output at a given index.
GoMeasurementType
Lists all measurement types.
GoTool::GoTool_ClearMeasurements
kStatus GoTool_ClearMeasurements(GoTool tool)
Removes all measurements for the given tool.
GoTool::GoTool_FeatureOutputAt
GoFeature GoTool_FeatureOutputAt(GoTool tool, kSize index)
Retrieves the feature output at the given index.
GoFeatureType
Lists all feature types.
GoTool::GoTool_FindFeatureOutputByType
GoFeature GoTool_FindFeatureOutputByType(GoTool tool, GoFeatureType type)
Retrieves the instance of a feature output for a given enumeration type.
GoTool::GoTool_SetName
kStatus GoTool_SetName(GoTool tool, const kChar *name)
Sets the name of the tool.
GoSdkDef.h
Essential SDK declarations.
GoTool::GoTool_AddFeatureOutput
kStatus GoTool_AddFeatureOutput(GoTool tool, kType type, GoFeature *featureOutput)
Adds the given feature output to the tool set.
GoTool::GoTool_MeasurementAt
GoMeasurement GoTool_MeasurementAt(GoTool tool, kSize index)
Retrieves the measurement at the given index.
GoFeature.h
Declares the GoFeature class.
GoTool::GoTool_Name
kStatus GoTool_Name(GoTool tool, kChar *name, kSize capacity)
Retrieves the name of the tool.
GoMeasurements.h
Declares the GoMeasurement classes.
GoTool
Represents the base tool class.
GoTool::GoTool_Type
GoToolType GoTool_Type(GoTool tool)
Retrieves the tool type enumeration value of the tool.
GoTool::GoTool_AddMeasurement
kStatus GoTool_AddMeasurement(GoTool tool, kType type, kBool isFilterable, GoMeasurement *measurement)
Adds the given measurement to the tool set.
GoTool::GoTool_ClearFeatureOutputs
kStatus GoTool_ClearFeatureOutputs(GoTool tool)
Removes all feature outputs for the given tool.
GoFeature
Represents the base class for a tool Feature or script output.
GoTool::GoTool_IsGoExtTool
kBool GoTool_IsGoExtTool(GoTool tool)
Checks if the given tool is a GoExtTool or not.
GoTool::GoTool_MeasurementCount
kSize GoTool_MeasurementCount(GoTool tool)
Returns the measurement count.
GoFeatures.h
Declares the GoFeatures classes.
GoTool::GoTool_AddExtMeasurement
kStatus GoTool_AddExtMeasurement(GoTool tool, kType type, kBool isFilterable, GoExtMeasurement *measurement)
[Deprecated]
GoTool::GoTool_FeatureOutputCount
kSize GoTool_FeatureOutputCount(GoTool tool)
Returns the feature output count.