|
Add a tool to the clipboard |
  
|
|
Add a tool to the clipboard |
|
Use Case
| • | You want to add a tool to the clipboard that will operate on the images contained and/or selected in the clipboard. |
| • | Applications include image printing and export, etc. |
Relevant Architecture
Relevant Types
| • | ClipboardToolExtensionPoint |
| • | ClipboardTool |
| • | IClipboardToolContext |
| • | IClipboardItem |
Sample Code
using ClearCanvas.Common;
using ClearCanvas.Desktop;
using ClearCanvas.Desktop.Actions;
using ClearCanvas.ImageViewer;
using ClearCanvas.ImageViewer.Clipboard;
// ... (other using namespace statements here)
namespace MyPlugin.Miscellaneous
{
[MenuAction("export", "clipboard-contextmenu/MenuExportToImage", "Export")]
[ButtonAction("export", "clipboard-toolbar/ToolbarExportToImage", "Export")]
[Tooltip("export", "TooltipExportToImage")]
[IconSet("export", IconScheme.Colour, "Icons.MyToolSmall.png", "Icons.MyToolMedium.png", "Icons.MyToolLarge.png")]
[EnabledStateObserver("export", "Enabled", "EnabledChanged")]
// ... (other action attributes here)
[ExtensionOf(typeof (ClipboardToolExtensionPoint))]
public class ExportToImageTool : ClipboardTool
{
public ExportToImageTool() {}
public override void Initialize()
{
this.Enabled = this.Context.SelectedClipboardItems.Count > 0;
base.Initialize();
}
public void Export()
{
foreach (IClipboardItem clipboardItem in this.Context.SelectedClipboardItems)
{
if (clipboardItem.Item is IPresentationImage)
{
// Export IPresentationImage
}
else if (clipboardItem.Item is IDisplaySet)
{
// Export IDisplaySet
}
}
}
}
}
Remarks
A very common use case is one where a user sets aside a few notable images from a study and wants do something with them, such as print them or export them. ClearCanvas Workstation provides a convenient mechanism for this: a clipboard. Users can send images or display sets to the clipboard, then perform some useful operation on them. Because the clipboard defines a ClipboardToolExtensionPoint, it is possible to add your own tools to the clipboard, as shown in the example above.
A few important notes:
| • | IClipboardItem.Item does not contain a reference to an existing IPresentationImage or IDisplaySet but rather a copy. This way, if the original IPresentationImage or IDisplaySet is changed (e.g., a new measurement is applied or the window/level is adjusted), it does not affect the clipboard's version, since that version should be a snapshot of the object when the user sent it to the clipboard. |
| • | The IClipboardToolContext exposes both ClipboardItems and SelectedClipboardItems, but clipboard tools should only operate on SelectedClipboardItems, unless explicitly stated (such as the "Delete All Clipboard Items" tool). |
| • | Before using an IClipboardItem on a different thread, be sure to call Lock(), so that the user cannot delete that IClipboardItem from the clipboard. When you're done with it, call Unlock(). (We added Lock/Unlock methods because it is not uncommon for operations on clipboard items to be asynchronous.) |
| • | When using IClipboardItem on a different thread, it is recommended that the IClipboardItem.Item (i.e. either an IPresentationImage or an IDisplaySet) be cloned so that the thread owns its own copy. Note however, that pixel data is still always shared. |
| • | Note the site portions of the toolbar and menu paths in the example above (i.e., "clipboard-toolbar" and "clipboard-contextmenu"). As usual, if you want to change the ordering of the tools on the clipboard toolbar or context menu, do so as you would with the main tool or menu bar. |
Examples in Code Base
| • | ClearCanvas.ImageViewer.Clipboard.ImageExport.ExportToImageTool |