Identify features

An identify operation is a user-driven operation typically involving a single click on the map and the retrieval of information about any features hit by that clicked point from any layer in the map. This operation has the potential to retrieve a lot of information depending on the identify parameters specified. Use the IdentifyTask to search the layers in both local and online data for features that intersect an input geometry. Once the matching features are returned, you can display their geometries and attributes in your application.

Using the IdentifyTask with online data

To perform Identify operations on online data in your application you will need to pass the URL of an online service or layer. To find the URL, you can use the ArcGIS Services Directory. Set the map service so that the task will search by passing the service's URL to the IdentifyTask's constructor.

// Construct the layer  
EsriRuntimeQt::ArcGISDynamicMapServiceLayer* dynamicServiceLayer = new EsriRuntimeQt::ArcGISDynamicMapServiceLayer(
    "”, this);
QString theMapServerURL = dynamicServiceLayer->url();

Using the IdentifyTask with local data

To perform Identify operations on local data in your application you will need to consume the IdentifyTask programmatically by creating and initializing a new LocalMapService with the path to an ArcGIS map package.

// Construct Local Dynamic Layer using: sdk/samples/data/mpks/USCitiesStates.mpk
QString dataPath = pathSampleData + "mpks" + QDir::separator() + "USCitiesStates.mpk";
m_localMapService = EsriRuntimeQt::LocalMapService(dataPath);

// Connect the service's signals to slots for success and failure
connect(&m_localMapService, SIGNAL(serviceCreationSuccess(QString,QString)),
		this, SLOT(onServiceCreationSuccess(QString,QString)));
connect(&m_localMapService, SIGNAL(serviceCreationFailure(QString)),
		this, SLOT(onServiceCreationFailure(QString)));

// Start the local service

Add the code for the onServiceCreationSuccess

// Slot to connect to serviceCreationSuccess signal
void IdentifyTestApp::onServiceCreationSuccess(const QString& url, const QString& name)

   // Create the ArcGISDynamicMapServiceLayer using the LocalMapService's URL

   if ("USCitiesStates.mpk", Qt::CaseSensitive) == 0)
  	  m_dynamicServiceLayer = new EsriRuntimeQt::ArcGISDynamicMapServiceLayer(
		  	m_localMapService.urlMapService(), this);

Also add the code for onServiceCreationFailure

// Slot to connect to serviceCreationFailure signal
void IdentifyTestApp::onServiceCreationFailure(const QString& name)
  // Produce simple warning
  qWarning() << name + " failed to start";
  qWarning() << m_localMapService.error().what();

Instantiate the IdentifyTask

First, obtain the URL of the online or local map service containing the layers that will be used by the IdentifyTask. Next, instantiate the IdentifyTask class passing the map server's URL to the task's constructor.

// In the header, declare m_identifyTask as a member variable
EsriRuntimeQt::IdentifyTask* m_identifyTask;
. . .
// In the cpp file, instantiate the task
// Construct the IdentifyTask
m_identifyTask = new EsriRuntimeQt::IdentifyTask(theMapServerURL, this);
. . .

Specify the IdentifyParameters inputs

Before using Identify operations you will need to define the operation's input parameters. These parameters will vary depending on the operation. The IdentifyParameters object is used to specify the input for the IdentifyTask. You can customize your Identify operation by specifying Identify parameters such as layer IDs to narrow down the amount of data you see by filtering the layers you are interested in. The LayerMode parameter can also be set to search only the top-most or visible layers. By reducing the number of layers Identify works with, you can quickly focus on what is important to you. The setGeometry Identify parameter allows you to specify a geometry to perform an Identify on. This enables the flexibility of identify areas such as polygons, envelopes and polylines as well as points. The IdentifyParameters class defines how you want the IdentifyTask to operate. Specify the parameters on IdentifyParameters and then pass it into the constructor of the IdentifyTask. Here are some basic guidelines:

  • Identify operates by intersecting a geometry with the features in one or more layers. Provide the intersection geometry in the setGeometry property.
  • Control the distance (in pixels) from your geometry that the intersection will be performed using the setTolerance property.
  • Identify can be performed on any of the layers. You specify the layers, by id, that take part in the identify using the setLayers(const QList&) property. Alternatively, specify the visible layers, the top most layer or all layers.
// Construct and populate IdentifyParameters
EsriRuntimeQt::IdentifyParameters myIdentifyParams;

Execute the task asynchronously

Asynchronous execution of the IdentifyTask is performed using the execute method using the previously defined IdentifyParameters class as input. You also need to connect to the signals and slots you defined to receive a collection of IdentifyResults. If you execute the task asynchronously the application will remain responsive during the execution of the task. This is the recommended method of execution for most identify operations.

// Connect the task's completion signal to a slot and execute the task
connect (m_IdentifyTask, SIGNAL(identifyTaskComplete(const QList<EsriRuntimeQt::IdentifyResult*>&)),
		 this, SLOT(onIdentifyTaskComplete(const QList<EsriRuntimeQt::IdentifyResult*>&)));
// The task is now running asynchronously...
// ...

// Slot to connect to identifyTaskComplete signal
void IdentifyTestApp::onIdentifyTaskComplete(const QList<EsriRuntimeQt::IdentifyResult*>& identifyResults)
  // Get each result
  for (int i = 0; i < identifyResults.length(); i++)
	 EsriRuntimeQt::IdentifyResult* result = identifyResults[i];
	 // Do something with each result...

Execute the task synchronously

Synchronous execution of the IdentifyTask is performed using the executeAndWait method using the previously defined IdentifyParameters class as input. If you execute the task synchronously the application's UI will block while the operation is in progress. The results of the task will be returned to a set of IdentifyResults that can be examined by the application. This method of execution is only recommended if the identify is reliably rapid and the resultant IdentifyResults is small.

// Execute the task synchronously
QList<EsriRuntimeQt::IdentifyResult*> identifyResults = m_identifyTask->executeAndWait(myIdentifyParams);

// Get each result
for (int i = 0; i < identifyResults.length(); i++)
  EsriRuntimeQt::IdentifyResult* result = myResults[i];
  // Do something with each result...

Process the results

The results of the IdentifyTask are returned in a list of IdentifyResults. Each item in the array represents a feature containing one geometry and one or more attributes with their values. Once you have acquired the IdentifyResult collection all that remains is for you to process the contents.

for(int i = 0; i < identifyResults.length() ;i++)
    EsriRuntimeQt::IdentifyResult* result = identifyResults[i];
    QString displayFieldName = result->displayFieldName();
    QString displayFieldValue = result->attributes().value(displayFieldName).toString();
    QString layerName = result->layerName();
  // Do something with this information...

Sample code

To view any samples related to searching data, please launch the ArcGIS Runtime for Qt sample application and explore the interactive samples and their code in the Search section.