Taskbar ======= .. note:: With the release of OMERO 5.3.0, the OMERO.insight desktop client has entered **maintenance mode**, meaning it will only be updated if a major bug is discovered. Instead, the OME team will be focusing on developing the web clients. As a result, coding against this client is no longer recommended. The container provides a top-level window, the taskbar, to let users control some of the container's tasks like the connection to the remote service or quitting the application. The taskbar contains a menu bar and several toolbars. Agents can add their own entries to the menu bar and to the toolbars in order to trigger agent-specific actions, or can ignore the taskbar altogether. For example, agents that are UIs typically add an entry to the Window menu and to the Quick-launch toolbar (this should be done during the agent's linking phase) for top-level windows that the user can bring up. Some utility classes provide agents with functionality to link their top-level windows to the taskbar and to manage the display of those windows on screen. Structure and dynamics ---------------------- The following diagram shows the classes that provide the taskbar service and their relationships: .. figure:: /images/omeroinsight-taskbar-structure.png :align: center :alt: Taskbar structure Taskbar structure The following diagram shows how some utility classes that can be used to link windows to the ``TaskBar`` and to manage their display on screen: .. figure:: /images/omeroinsight-taskbar-utility.png :align: center :alt: Taskbar utility classes Taskbar utility classes The following diagram shows how the display state of a top window is managed by the ``TopWindowManager``: .. figure:: /images/omeroinsight-taskbar-window-management.png :align: center :alt: Taskbar window management Taskbar window management How to ------ Agents can use the taskbar directly to add entries to the various menus and toolbars. After retrieving the ``TaskBar`` from the ``Registry``, the ``addXXX`` and ``removeXXX`` are available to do the job. Agents can add entries to any of the menus within the menu bar -- ``File, Connect, Tasks, Window, Help``. Two toolbars, ``Tasks`` and ``Quick-Launch``, are also provided for agents to plug in their buttons. Buttons in the Tasks toolbar are usually shortcuts to entries in the Tasks menu. Similarly, buttons in the Quick-Launch toolbar are usually shortcuts to entries in the Window menu. However, some utility classes provide agents with built-in functionality to link their top-level windows to the taskbar and to manage the display of those windows on screen. The ``TopWindow`` class extends ``JFrame`` to provide the base functionality for windows that are to be linked to the ``TaskBar`` by means of one quick-launch button and a menu entry in the ``Window`` menu. The constructor of this class automatically adds a button to the ``Quick-Launch`` toolbar and an entry in the ``Window`` menu -- subclasses use the ``configureXXX`` methods to specify icons, names, and tool tips. These are display-trigger buttons that cause the window to be shown on screen. This class uses the ``TopWindowManager`` to control mouse clicks on these buttons as well as to manage the display state of the window -- how this display state is managed is specified by the ``TopWindowManager`` state machine, which is represented in one of the previous diagrams. Here is an example of a window that inherits from ``TopWindow``: :: class MainWindow extends TopWindow { //Member fields omitted. //Specifies names, icons, and tool tips for the quick-launch button and the //window menu entry in the taskbar. private void configureDisplayButtons() { configureQuickLaunchBtn(icons.getIcon("agent.png"), "Display the main window."); configureWinMenuEntry("Example Agent", icons.getIcon("agent.png")); } //Builds and lays out this window. private void buildGUI() { /* Omitted. */ } //Creates a new instance. MainWindow(Registry config) { //We have to specify the title of the window to the superclass //constructor and pass a reference to the TaskBar, which we get //from the Registry. super("Example Agent", config.getTaskBar()); configureDisplayButtons(); buildGUI(); } } The ``TopWindowGroup`` class links a group of windows to the ``TaskBar`` and manages their display on screen. Rather than adding a quick-launch button in the ``Quick-Launch`` toolbar and an entry in the window menu for each window in the group, the constructor of this class adds a drop-down button (a button that triggers the display of a popup menu) to the ``Quick-Launch`` toolbar and a sub-menu to the ``Window`` menu. These menus contain an entry for each window in the group and are populated/depopulated via the ``add/remove`` methods. All those menu entries are display-trigger buttons that cause the corresponding window to be shown on screen. This class uses the ``TopWindowManager`` to control mouse clicks on these buttons as well as to manage the display state of each window in the group. The following ``UIManager`` class provides an example of how to use the ``TopWindowGroup`` class. This example class creates and controls an instance of ``MainWindow`` (which we have already seen in the previous example) as well as ``AuxiliaryWindow`` instances. This latter class is just a window which contains two buttons and its code is omitted. ``UIManager`` delegates to the ``TopWindowGroup`` class the linkage of ``AuxiliaryWindow``'s to the ``TaskBar`` as well as the management of their display state. Follows the code: :: class UIManager { //Inherits from TopWindow, so it is automatically linked to the TaskBar. //Contains a button that we listen to. When a mouse click occurs we call //createAuxWin(). private MainWindow mainWindow; //Manages all the AuxiliaryWindow's that we have created and not destroyed yet. private TopWindowGroup auxWinGroup; //Counts how many {@link AuxiliaryWindow}'s that we have created so far. private int auxWinCount; //Cached reference to access the icons. private IconFactory icons; //Creates a new instance. UIManager(Registry config) { auxWinCount = 0; icons = (IconFactory) config.lookup("/resources/icons/MyFactory"); mainWindow = new MainWindow(config); //The MainWindow contains a button (not shown in the previous example) //which we listen to in order to trigger the creation of new //AuxiliaryWindow’s. mainWindow.openAuxiliary.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent ae) { createAuxWin(); } }); //We now create the window group. The text we pass will be displayed by //the sub-menu within the Window menu along with the icon, which will also //be the icon displayed by the drop-down button in the Quick-Launch //toolbar. auxWinGroup = new TopWindowGroup("Aux Win", icons.getIcon("edu_languages.png"), config.getTaskBar()); } //Creates an AuxiliaryWindow and adds it to the auxWinGroup. //Every AuxiliaryWindow contains two buttons, one labeled "Close" and the other //"Dispose". We listen to mouse clicks on these buttons in order to hide the //window when the "Close" button is clicked and to remove the window (and dispose //of it) from the auxWinGroup when the "Dispose" button is clicked. private void createAuxWin() { String title = "Aux Window "+(++auxWinCount); final AuxiliaryWindow aw = new AuxiliaryWindow(title); //Attach listeners and specify actions. aw.close.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent ae) {aw.setVisible(false);} }); aw.dispose.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent e) { //Remove from group and dispose. auxWinGroup.remove(aw, true); } }); //Add to the group. An entry will be added both to the Window sub-menu //and to the popup menu triggered by the drop-down button in the //Quick-Launch toolbar. We set the display text of those entries to be //the same as the window's title, but we don't specify any icon. auxWinGroup.add(aw, title, null); //Bring the window up. aw.open(); } //Releases all UI resources currently in use and returns them to the OS. void disposeUI() { mainWindow.dispose(); auxWinGroup.removeAll(true); //Empty group and dispose of all windows. } }