Fork me on GitHub

Top Frame Plugin for MicroManager

TopFrame is a MicroManager plugin that provides an always-visible ‘top frame’ containing often-used controls and actions.  TopFrame is extensible – TopFrame-aware plugins can add action buttons to the toolbar, making them easily available.

Plugin: Download Link. Recommended Micro-Manager version 1.4.15

Download the TopFrame.jar file to Micro-Manager’s mmplugins folder.

Start TopFrame from the Micro-Manager Plugins menu.

TopFrame Features

Window Management

While performing acquisitions and image processing, it is no uncommon to accumulate numerous display windows on the desktop.  To make it easy to access commonly used windows, TopFrame allows you quickly bring selected frames to the top on the desktop.

  • Show Button

Pressing the ‘Show’ button makes MMStudioMainFrame as well as any other registered JFrames visible by bringing to ‘to-the-top’ in relation to other windows/frame open on the desktop.  (See ‘Adding a Frame to Show’ below.)

Camera Control

When TopFrame is started, it makes available several camera-related controls:

  • Live Toggle Button

This toggles (alternately turns on/off) the Live Mode for the camera.

  • Exposure Spinner

This is a spinner control for changing the exposure setting.  The increment of increase/decrease for the spinner changes based on the current value.  Hotkeys are also defined for increasing (F12) and decreasing (F11) the exposure.

Other Features

- Saves and restores its position and size on the desktop.

SomeAction button is an example of a TopFrame-aware plugin adding an action button.

Automatically Starting TopFrame

For convenience, TopFrame can be automatically started when Micro-Manager is started by adding this code to the BeanShell script that is automatically run (by default, MMStartup.bsh):

import org.micromanager.MMStudioMainFrame.PluginItem;
for (PluginItem plugin : gui.plugins_)
    if (plugin.className.equals("TopFramePlugin")) {

Making a Plugin TopFrame-Aware

A Micro-Manager plugin can be made TopFrame-Aware without having a direct dependency on TopFrame; this way, a plugin can be distributed and installed to Micro-Manager installation that may or may not haveTopFrame installed.

The trick is to use reflection to dynamically load a class and invoke a method.  Using this approach, the plugin can attempt to add its components to TopFrame and will not case an error if the TopFrame.jar is not available.  (It fails when it invokes loadClass(“TopFrame”), and the exception can simply be ignored; the printStackTrace can be removed after debugging.)  This approach is used in the following sections to enable another plugin to register an action or a frame to show withTopFrame.

Adding an Action Button

First, create an Action that invokes the functionality that you want the button to have.

Here is an example of how to create an Action:

public class SomeAction extends AbstractAction {   
    public SomeAction() {
        putValue(NAME, "SomeAction");
        putValue(ACTION_COMMAND_KEY, "someaction");
        try {
            putValue(SMALL_ICON, new javax.swing.ImageIcon(getClass().getResource("frameIcon.png")));
        } catch (Exception ex) {}
        putValue(SHORT_DESCRIPTION, "Perform some action");
        putValue(MNEMONIC_KEY, new Integer(KeyEvent.VK_I));
        putValue(ACCELERATOR_KEY, KeyStroke.getKeyStroke(KeyEvent.VK_I, KeyEvent.CTRL_DOWN_MASK, false));
    public void actionPerformed(ActionEvent ae) {
	// for example
        SwingUtilities.invokeLater(new Runnable() {
            public void run() {
               System.out.println("I have been invoked.");

The properties of the button are taken from the property values in the Action that is passed and are handled as follows:

  • ACTION_COMMAND_KEY is a unique string used as a hash key.
  • NAME becomes the label on the button.
  • SMALL_ICON is added to the button.
  • SHORT_DESCRIPTION becomes the tooltip for the button.
  • ACCELERATOR_KEY is added as a GlobalHotKey (see below)

  • Pass a KeyStroke, for example:
    KeyStroke.getKeyStroke(KeyEvent.VK_I, KeyEvent.CTRL_DOWN_MASK, false));
    (See docs for KeyStroke)

Now, add this method to your plugin and call it passing the Action:

private void registerActionWithTopFrame(Action action) {
  // call static TopFrame.addActionButton(Action action)
  try {
    ClassLoader l = Thread.currentThread().getContextClassLoader();
    Class cls = l.loadClass("TopFrame");
    Method mainMethod = cls.getDeclaredMethod("addActionButton", new Class[]{Action.class});
    mainMethod.invoke(null, new Object[]{action});
  } catch (Exception ex) {
    ex.printStackTrace();  // remove after debugging

TopFrame does not allow multiple copies of a button/action to be added.

Adding a Frame to ‘Show’

A plugin can add its window/frame to the set of frames that are brought to the top on the desktop when the ‘Show’ button is pressed.  To do this, do the following:

1. Add this method to the plugin:

private void registerFrameWithTopFrame(JFrame controlFrame_) {
  // call static TopFrame.addFrameToShow(JFrame frame)
  try {
    ClassLoader l = Thread.currentThread().getContextClassLoader();
    Class cls = l.loadClass("TopFrame");
    Method mainMethod = cls.getDeclaredMethod("addFrameToShow", new Class[]{JFrame.class});
    mainMethod.invoke(null, new Object[]{controlFrame_});
  } catch (Exception ex) {
    ex.printStackTrace();  // remove after debugging

2. Add a call to this method that passes the plugin’s frame as the parameter.


© OpenPolScope | All Rights Reserved | Contact
Last Page Update on April 08 2014 13:23