Table of Contents
TGIS_LayerVector.Locate(TGIS_Point; Double) method
DK for Delphi | GisLayerVector.TGIS_LayerVector.Locate | Overloads | Constructors | Fields | Methods | Properties | Events
Locates the shape closest to a reference point within a specified precision distance. Uses spatial index for fast O(log n) lookup. Essential for interactive shape selection (mouse clicking).
Syntax
// Delphi public function Locate( const _ptg : TGIS_Point; const _prec : Double ) : TGIS_Shape; overload; virtual;
// C++ Builder public: virtual TGIS_Shape* Locate( TGIS_Point* const _ptg, const double _prec ) /* overload */;
Parameters
| Name | Type | Description |
|---|---|---|
| _ptg | TGIS_Point | Reference point for search. Coordinate space depends on context: if layer attached to Viewer, point is in viewer coordinates; else layer coordinates. Typically obtained from mouse position or calculated geometry. |
| _prec | Double | Maximum search distance (precision distance). Shapes outside this distance from _ptg are ignored. Distance same units as coordinate system. Special behavior: for points inside polygons, distance multiplied by 0.95 (preference for interior points); for points vs lines/polygons, point preference multiplier 0.9. |
Result
| Type | Description |
|---|---|
| TGIS_Shape | Shape closest to _ptg within _prec distance, or nil if no shape found. Returns only visible shapes (respects query/hidden settings). Returns first hit if multiple shapes equidistant (order undefined). |
Remarks
PURPOSE:Interactive shape selection for map-based UIs (mouse clicks, hover tooltips). Prioritizes topology: prefers interior points, prefers points over lines/polygons. Fast lookup via spatial index.
BEHAVIOR:Searches layer for closest shape to _ptg within _prec distance using R-Tree spatial index (O(log n) if indexed, O(n) if not). Applies special distance multipliers: 0.95× for points inside polygons (encourages interior selection), 0.9× for points (prefers point selection over lines). Respects query filter and hidden shapes (invisible shapes ignored). Returns first hit if ties exist.
USAGE:Map click handler:shape := layer.Locate (mouse_point, click_tolerance);Hover detection:hover := layer.Locate(current_pos, tolerance);With visibility filter:shape := layer.LocateEx(pt, prec, true);
CONSTRAINTS:Coordinate space context-dependent (viewer vs. layer). Precision must be positive (<=0 returns nil). Returns only visible shapes (query/hidden settings apply). Not thread-safe; synchronize access. Performance O(log n) with R-Tree, O(n) without. Distance calculation uses Euclidean metric (no geodetic). Viewer scale affects practical precision (click tolerance varies with zoom).
If locate is called upon active paint operations then result could be null. But Locate and paint process are using the same vector enumerator context.
It is recommended to check InPaint property before calling this Locate.