ArcGIS Explorer SDK Feedback via the User Forum
Programming with the E2API

Glossary Item Box

Custom Task Style Guide

This guide will help you design and develop custom tasks for ArcGIS Explorer. By referring to this guide in the design of your custom tasks, your custom tasks will have a look and feel which is consistent with other custom tasks and with the default ESRI tasks that are distributed with ArcGIS Explorer.

There are two sections to this guide; the Task Appearance section encourages you to build custom tasks that have a similar appearance to other ArcGIS Explorer tasks. The Task Behavior section encourages you to build custom tasks that have similar behavior as other tasks, the contents of both sections are listed below:

Task Appearance

Sizing and Spacing
Colors and Fonts
Common Controls and Control Placement
Working with Images

Task Behavior

Tab Order
Result Behavior
Result Icons
Sharing Results
Save Task State with the NMF
User Experience and Feedback

Task Appearance

  • Sizing and Spacing

    To ensure your custom task resizes as expected, form controls used in your custom task should be anchored to the containing control, using the Anchor property. For example, right aligned controls like the 'Find button' in the Find Place task, are anchored to the top, right of the containing UserControl. When the task is resized, as illustrated below, the Find button remains the same distance from the top and right edges of the UserControl.

  • Colors and Fonts

    The appearance of the ArcGIS Explorer application is formatted based on the HomeServer to which ArcGIS Explorer is connected. If ArcGIS Explorer is working with the default ESRI Home Server then tasks that are loaded in ArcGIS Explorer will be formatted according to the Windows theme color (Blue, Olive or Silver). If ArcGIS Explorer is connected to a custom Home Server, tasks will be formatted according to the fonts and colors specified in the skin file located on the custom Home Server. The ArcGIS Explorer API provides a useful SkinInfo class to help format your custom tasks so that they match the formatting of the application in which they are hosted.

    The following code snippet demonstrates using the SkinInfo class to format a command button.

    C# Copy Code
    public CustomTaskControl(CustomTaskUI taskUI)

       _taskUI = taskUI;

       //Set command button font to main font used in ArcGIS Explorer.
       SkinInfo sInfo = _taskUI.E2.SkinInfo;
       CommandButton1.Font = sInfo.GetSkinFont(esriE2SkinFont.MainFont);
       //Set command button back color to general background color used in ArcGIS Explorer.
       CommandButton1.BackColor = _taskUI.E2.SkinInfo.GetSkinColor(esriE2SkinColor.GeneralBackgroundColor);

    }
    Visual Basic Copy Code
    Friend Sub New (ByVal taskUI As CustomTaskUI)

        _taskUI = taskUI
      
        'Set command button font to main font used in ArcGIS Explorer.   
        Dim sInfo As SkinInfo = _taskUI.E2.SkinInfo
        Me.CommandButton1.Font = sInfo.GetSkinFont(esriE2SkinFont.MainFont)
        'Set command button back color to general background color used in ArcGIS Explorer.
        Me.CommandButton1.BackColor = _taskUI.E2.SkinInfo.GetSkinColor(esriE2SkinColor.GeneralBackgroundColor)
      
    End Sub

    If your custom task makes use of a message box or user form, the ArcGIS Explorer API provides some helpful methods to ensure your message box or user form is formatted in accordance with the fonts and colors used in ArcGIS Explorer. When developing custom tasks, instead of using the message box that ships with the .NET base class library, you are encouraged to use the E2.MessageBox method to display an ArcGIS Explorer message box. The ArcGIS Explorer message box is skinned according to the skin used by the instance of ArcGIS Explorer hosting your custom task, and is also thread safe.

    If your custom task makes use of a user form, you are encouraged to use the TaskUI.SetUIStyles method to ensure the user form is formatted the same way as the main custom task UserForm. The SetUIStyles method will format the font and backcolor of your user form, and any text or list boxes that the user form contains.

  • Common Controls and Control Placement

    Common to many custom tasks is a command button that when pressed executes your custom task. This control is usually placed in the bottom right of the UserControl, as illustrated below, with the Find Place tasks 'Find' button.

    Another common control is a LinkLabel that points to a html file documenting how to use your custom task. This control is usually placed in the bottom left of the UserControl, as illustrated below.

  • Working with Images

    The ImageSet class provides access, by name or index, to the set of images used as icons for tasks and results within ArcGIS Explorer. The ImageSet currently (version 440) provides access to 59 images. Using images that are already contained within the ImageSet, developers can add a familiar look and feel to their custom tasks, a small subset of the Images available in the ImageSet are displayed below.

    In addition to accessing default images, developers can store their own images in the ImageSet, as illustrated in the code snippet below. When adding images to the ImageSet ensure they have a unqiue name, a sensible approach is to prefix your Image name with your company name and product name, for example, MyCompany.MyProduct.MyImageName.

    C# Copy Code
    public CustomTaskControl(CustomTaskUI taskUI)

       _taskUI = taskUI;

       //Create Bitmap from Filepath.
       System.Drawing.Bitmap newImg = new System.Draw.Bitmap("YourImageFile.bmp");
       //Add Image to ImageSet.
       _taskUI.E2.ImageSet.AddImage("YourImageName", newImg);
       //Use Image from ImageSet when creating new Result
       Result newRes = new Result("YourImageName", "YourResultTitle");
    }
    Visual Basic Copy Code
    Friend Sub New (ByVal taskUI As CustomTaskUI)

        _taskUI = taskUI
      
       'Create Bitmap from Filepath.
       Dim newImg As System.Drawing.Bitmap = New System.Draw.Bitmap("YourImageFile.bmp");
       'Add Image to ImageSet.
       _taskUI.E2.ImageSet.AddImage("YourImageName", newImg);
       'Use Image from ImageSet when creating new Result
       Dim newRes As Result = New Result("YourImageName", "YourResultTitle");
      
    End Sub

    For more information on working with the ImageSet please see the Get Images Sample.

Task Behavior

  • Tab Order

    When designing custom tasks, careful attention should be given to the TabIndex associated with controls used in your custom task. The TabIndex allows custom task developers to specify the cycle order of form controls when a user presses the tab key to move to the next control. A sensible tab index order might be left to right, then top to bottom, as illustrated below.

    To process the task the user is expected to click the find button with the mouse cursor, or hit the Enter key. You are encouraged to replicate this behavior with your custom task, you can use the KeyUp or KeyDown events to listen for the Enter key, and process your task when it has been pressed, as illustrated in the code snippet below.

    C# Copy Code
    private void CustomTaskControl_KeyDown(object sender, KeyEventArgs e)

       //Check KeyCode.
        if (e.KeyCode == Keys.Enter)
        {
           _taskUI.E2.ProcessTask(yourTaskContext, esriE2TaskExecution.Show)
        }
    }
    Visual Basic Copy Code
    Private Sub CustomTaskControl_KeyDown(ByVal sender As System.Object, ByVal e As System.Windows.Forms.KeyEventArgs) Handles MyBase.KeyDown

       'Check KeyCode.
        If e.KeyCode = System.Windows.Forms.Keys.Enter Then
           _taskUI.E2.ProcessTask(yourTaskContext, esriE2TaskExecution.Show)
        End If
      
    End Sub
  • Result Behavior

    As a custom task developer it is important to recognize that the behavior of results generated by your custom task is unique to your custom task. There are several methods in the CustomTaskUI class that can be overridden allowing you to tailor the behavior of results generated by your custom task. For example, you can override GetMenu and DoMenuItem to add to the context menu displayed when a result of your custom task is right clicked with the mouse cursor in the Results panel.

    The following code snippet demonstrates adding an extra option to the context menu of a result.

    C# Copy Code
    public override MenuDef GetMenu(esriE2MenuType menuType, object menuArgs)

       //Check Menu Type.
        if (menuType == esriE2MenuType.ResultContextMenu);
        {
          //Create Menu and add a 'More Info' Item.
          _mainMenu = new MenuDef();
          _mainMenu.AddItem("ESRI.ArcGIS.E2API.Identify", "More Info", false, false, 10);
          _mainMenu.DefaultItem = 10;
        }

        return this._mainMenu;

    }

    public override void DoMenuItem(esriE2MenuType menuType, object menuArgs, int menuItemId)
    {
        // Perform the actual work of the context menu.
        // First, get the result information.
        ResultInfo resInfo = menuArgs as ResultInfo;
        switch (menuItemId)
        {
          case (10):
          {
            this.E2.MessageBox("Here is more Info", "More Info", esriE2MessageBoxType.Information);
            break;
          }
        }
    }
    Visual Basic Copy Code
    Public Overrides Function GetMenu(ByVal menuType As esriE2MenuType, ByVal menuArgs As Object) As MenuDef

        'Check Menu Type.
        If menuType = esriE2MenuType.ResultContextMenu Then

          If (Me._mainMenu Is Nothing) Then      
          'Create Menu and add a 'More Info' Item.
          _mainMenu = New MenuDef
          _mainMenu.AddItem("ESRI.ArcGIS.E2API.Identify", "More Info", False, False, 10)
          End If

        Return Me._mainMenu

        End If

    End Function

    Public Overrides Sub DoMenuItem(ByVal menuType As esriE2MenuType, ByVal menuArgs As Object, ByVal menuItemId As Integer)

        'Perform the actual work of the context menu.
        'First, get the result information.
        Dim resInfo As ResultInfo = menuArgs

          'Select statement incase we have more than one additonal menu item.
        Select Case menuItemId
          Case (10)
          Me.E2.MessageBox("Here is more Info", "More Info", esriE2MessageBoxType.Information)
          Exit Sub

        End Select

    End Sub

    The above code adds a 'More Info' item to the context menu which is displayed when a result is right-clicked in the Results panel. When the menu item is clicked a message box is displayed with more information.

    The DoAction method can also be overridden to determine how your result behaves when an action is undertaken on your result. Currently, this method is used to determine how ArcGIS Explorer responds when a result in the Results panel is double clicked with the mouse cursor, more actions may be added in subsequent releases.

  • Result Icons

    The Result class has an Image property that enables you to associate images with the results of a custom task. You are encouraged to use this functionality to match the top level result returned by a task, with the task that generated the result. For example, note in the illustration below how the parent result returned by the 'Get Driving Directions' task has the same image as the 'Get Driving Directions' task displayed in the Tasks panel.

  • Sharing Results

    The custom task framework has been designed to allow custom tasks to work together - not in isolation. Tasks are responsible for answering a question; they usually provide the answer as a type of result. The results of one task can act as input for another task. When developing your custom task you can determine which types of result you wish to accept as input for your custom task. This is done by adding code like that shown below which implements a 'send to' menu item. This code indicates to results of other tasks, if the result will be accepted as an input by your custom task.

    The following code creates a SendToMenu entry for your custom task in the context menu of a result created by another task, but only when the result has a point geometry.

    C# Copy Code
    public override MenuDef GetMenu(esriE2MenuType menuType, object menuArgs)

       //Check Menu Type.
        if (menuType == esriE2MenuType.ResultSendToMenu);
        {
          if(_sendToMenu == null)
          {
          //Create our Menu and add a single item.
          //allowing Results to be sent to this Task.
          _sendToMenu = new MenuDef();
          _sendToMenu.AddItem("ESRI.ArcGIS.E2API.FindPlace", "My Task", false, false, 20);
          }
         
          //The following code allows other tasks to send Result to this task.
          ResultInfo resInfo = menuArgs as ResultInfo;
          //If the Result has a Point Geometry return our menu def.
          PlaceResult chosenRes = resInfo.ChosenResult as PlaceResult;
          if ((chosenRes!= null) && (chosenRes.Geometry is Point))
          { return this._sendToMenu; }
          else
          { return null; }
        }
        else
        { return null; }

        return this._mainMenu;

    }

    public override void DoMenuItem(esriE2MenuType menuType, object menuArgs, int menuItemId)
    {
        // Perform the actual work of the Send To Menu.
        // First, get the result information.
        ResultInfo resInfo = menuArgs as ResultInfo;
        switch (menuItemId)
        {
          case (20):
          {
                //Set the Result as Input for the custom Task
                PlaceResult res = resInfo.ChosenResult as PlaceResult;
                if ((res != null) && (res.Geometry is Point))
                {
                _taskControl.InputResult = res;
                //Assumes an InputResult property exists in the taskControl to handle the Result
                }
            break;
          }
        }
    }
    Visual Basic Copy Code
    Public Overrides Function GetMenu(ByVal menuType As esriE2MenuType, ByVal menuArgs As Object) As MenuDef

        'Check Menu Type.
        If menuType = esriE2MenuType.ResultSendToMenu Then

          If (Me._mainMenu Is Nothing) Then      
          'Create our Menu and add a single item.
          'allowing Results to be sent to this Task.
          _sendToMenu = New MenuDef
          _sendToMenu.AddItem("ESRI.ArcGIS.E2API.FindPlace", "My Task", False, False, 20)
          End If

          'The following code allows other tasks to send Result to this task.
          Dim resInfo As ResultInfo = menuArgs
          'If the Result has a Point Geometry return our menu def.
          Dim chosenRes As PlaceResult = resInfo.ChosenResult
          If (Not resInfo.ChosenRes Is Nothing) AndAlso (TypeOf chosenRes.Geometry Is Point) Then
          Return Me._mainMenu
          End If

        End If

    End Function

    Public Overrides Sub DoMenuItem(ByVal menuType As esriE2MenuType, ByVal menuArgs As Object, ByVal menuItemId As Integer)

        'Perform the actual work of the context menu.
        'First, get the result information.
        Dim resInfo As ResultInfo = menuArgs

        'Select statement incase we have more than one additonal menu item.
        Select Case menuItemId
          Case (20)
                //Set the Result as Input for the custom Task
                PlaceResult res = resInfo.ChosenResult as PlaceResult;
                If ((Not res Is Nothing) && (TypeOf res.Geometry Is Point)) Then
                _taskControl.InputResult = res
                'Assumes an InputResult property exists in the taskControl to handle the Result
                End If
          Exit Sub

        End Select

    End Sub

    Notice in the illustration below, how the 'Send To' option on the context menu of a result created by the 'Create Note' task lets the user send the result to your custom task.


    If your custom task is designed to accept results from other tasks as input you should also design your TaskUI to support the drag and drop of Results. The ArcGIS Explorer API provides the XMLHelper class to assist you with this, for further information on building tasks with drag and drop functionality please see the Drag and Drop sample.

  • Save Task State with the NMF

    When ArcGIS Explorer saves a map document containing a custom task, the ParameterSet associated with the task context is saved to the map document as a PropertySet. When the map document is next opened the information contained within the PropertySet is deserialized into a ParameterSet that can be accessed from the TaskUI.

    The ParameterSet therefore provides a place to save default settings for a TaskUI when saved as part of a map. You are encouraged to use this functionality to persist the options selected in a custom task so thay can be re-initialized when the NMF is next opened.

    The following code snippet demonstrates how a custom task might set a parameter named 'foo' with a value 'bar'.

    C# Copy Code
    private void CustomTaskControl_Load(object sender, EventArgs e)

       //Create Task Context.
        TaskContext newTaskContext = new TaskContext();
        newTaskContext.TaskName = "MyCustomTask.CustomTask";
        newTaskContext.TaskUIName = _taskUI.Name;

       //Get Parameters.
        ParameterSet parameters = _taskUI.ParameterSet;
       //Set a Parameter
        parameters.SetParameter("TextBox1Value", TextBox1.Text);

        newTaskContext.UpdateParameters(parameters);
    }
    Visual Basic Copy Code
    Private Sub CustomTaskControl_Load(ByVal sender As System.Object, ByVal e As System.Windows.Forms.EventArgs) Handles MyBase.Load

       'Create Task Context.
        Dim newTaskContext As TaskContext = New TaskContext
        newTaskContext.TaskName = "MyCustomTask.CustomTask"
        newTaskContext.TaskUIName = _taskUI.Name

       'Get Parameters.
        Dim parameters As ParameterSet = _taskUI.ParameterSet
       'Set a Parameter
        parameters.SetParameter("TextBox1Value", TextBox1.Text)

        newTaskContext.UpdateParameters(parameters)

    End Sub

    When a map document containing a custom task is saved, the following XML is written to the NMF to indicate the presence of the custom task in the map. If the 'foo' parameter has been set as demonstrated in the code snippet above, the parameter is written as an element in the NMF, as illustrated below. Using this technique you can save the state of your custom task when it is saved as part of a map document, and when the custom task is next loaded as part of the saved map, the parameters written to the NMF will be accessible to the custom task.

  • User Experience and Feedback

    As a task moves through its lifecycle, its status changes. At any one time a custom task has a status equal to one of six values, as listed in the esriE2TaskStatus enumeration illustrated below. For a comprehensive introduction to the lifecycle of a custom task, please see the Task Lifecycle Diagram.

    The current task status is displayed in the ArcGIS Explorer Results panel when a custom task is pending execution, executing, or has been stopped.

    A custom task has default messages associated with each status value in the esriE2TaskStatus enumeration, as a custom task developer you have full control over this message and are encouraged to set the message associated with a task status to give appropriate user feedback. For example, the default status message when a task is executing is 'MyCustomTaskName-executing' as illustrated below:

    Using TaskContext.SetStatusMessage we can change the message associated with the Task executing status:

    C# Copy Code
    private void CustomTaskControl_Load(object sender, EventArgs e)

       //Create Task Context.
        TaskContext newTaskContext = new TaskContext();
        newTaskContext.TaskName = "MyCustomTask.CustomTask";
        newTaskContext.TaskUIName = _taskUI.Name;
       //Variable holding search term enetered in Textbox.
        string SearchTerm = textbox1.Text;

       //Set Status Message.
        newTaskContext.SetStatusMessage(esriE2TaskStatus.Executing, "Finding " + SearchTerm);
        _taskUI.E2.ProcessTask(newTaskContext, esriE2TaskExecution.Show)
    }
    Visual Basic Copy Code
    Private Sub CustomTaskControl_Load(ByVal sender As System.Object, ByVal e As System.Windows.Forms.EventArgs) Handles MyBase.Load

       'Create Task Context.
        Dim newTaskContext As TaskContext = New TaskContext
        newTaskContext.TaskName = "MyCustomTask.CustomTask"
        newTaskContext.TaskUIName = _taskUI.Name
       'Variable holding search term enetered in Textbox.
        Dim SearchTerm As String = Textbox1.Text;

       'Set Status Message.
        newTaskContext.SetStatusMessage(esriE2TaskStatus.Executing, "Finding " + SearchTerm)
        _taskUI.E2.ProcessTask(newTaskContext, esriE2TaskExecution.Show)

    End Sub

    Having set the status message with the above code, the following is displayed when the task executes:

Summary



ArcGIS Explorer has been designed with the intention of allowing different tasks, perhaps developed by different organisations, to work together. As a custom task developer you are encouraged to take note of the advice contained within this document when building custom tasks; insuring your custom tasks have a familar look and feel, and are intuitive to use.