Navigation:  I Want To... > Basics > Create a desktop tool

Use Case

Relevant Architecture

Relevant Types

Sample Code

using System;

using ClearCanvas.Common;

using ClearCanvas.Common.Utilities;

using ClearCanvas.Desktop;

using ClearCanvas.Desktop.Actions;

using ClearCanvas.Desktop.Tools;

 

// ... (other using namespace statements here)

 

namespace MyPlugin.Basics

{

   [MenuAction("apply", "global-menus/MenuTools/MenuStandard/MenuMyDesktopTool", "Apply")]

   [ButtonAction("apply", "global-toolbars/ToolbarStandard/ToolbarMyDesktopTool", "Apply")]

   [Tooltip("apply", "TooltipMyDesktopTool")]

   [IconSet("apply", IconScheme.Colour, "Icons.MyToolSmall.png", "Icons.MyToolMedium.png", "Icons.MyToolLarge.png")]

   [EnabledStateObserver("apply", "Enabled", "EnabledChanged")]

   // ... (other action attributes here)

   [ExtensionOf(typeof (DesktopToolExtensionPoint))]

   public class MyDesktopTool : Tool<IDesktopToolContext>

   {

      private bool _enabled;

      private event EventHandler _enabledChanged;

 

      /// <summary>

      /// Default constructor.  A no-args constructor is required by the

      /// framework.  Do not remove.

      /// </summary>

      public MyDesktopTool()

      {

         _enabled = true;

      }

 

      /// <summary>

      /// Called by the framework to initialize this tool.

      /// </summary>

      public override void Initialize()

      {

         base.Initialize();

         // TODO: add any significant initialization code here rather than in the constructor

      }

 

      /// <summary>

      /// Called to determine whether this tool is enabled/disabled in the UI.

      /// </summary>

      public bool Enabled

      {

         get { return _enabled; }

         protected set

         {

            if (_enabled != value)

            {

               _enabled = value;

               EventsHelper.Fire(_enabledChanged, this, EventArgs.Empty);

            }

         }

      }

 

      /// <summary>

      /// Notifies that the Enabled state of this tool has changed.

      /// </summary>

      public event EventHandler EnabledChanged

      {

         add { _enabledChanged += value; }

         remove { _enabledChanged -= value; }

      }

 

      /// <summary>

      /// Called by the framework when the user clicks the "apply" menu item or toolbar button.

      /// </summary>

      public void Apply()

      {

         // Add code here to implement the functionality of the tool

      }

   }

}

Remarks

A desktop tool is the simplest type of tool you can create.  Typically, a desktop tool will always be visible on the toolbar and/or menu.  In the example above, when the toolbar button is clicked or menu item selected, the Apply() method is executed.  Note that the handling method doesn't have to be called Apply().  You specify the handling method name in the third parameter of the class level MenuAction  or ButtonAction attribute.  Similarly, the EnabledStateObserver attribute allows you to specify the name of the boolean property that indicates whether the tool is enabled (in this case, "Enabled"), and the name of the event that notifies the Framework that the property has changed (in this case, "EnabledChanged").

Using the Wizard

The ClearCanvas SDK provides some useful wizards to make common tasks a little easier.  One such task is creating a desktop tool.  To use the wizard to create a desktop tool:

Important Note: By default, the Framework will try to use the string resource (in the assembly's SR.resx file) to resolve the names of the individual components of menu and toolbar paths.  If a string resource is not available, then the literal will be used.  So for example, if the menu path component is MyTool, the framework will look for a string resource called MyTool and use whatever value has been assigned to MyTool as the actual menu item label.  If the MyTool string resource doesn't exist, the menu item will be literally labelled "MyTool".

Examples in Code Base