001    package nl.cwi.sen1.gui.component;
002    
003    import javax.swing.Icon;
004    import javax.swing.JComponent;
005    
006    import nl.cwi.sen1.gui.CloseAbortedException;
007    
008    /** 
009     * The (visual) interface to a tab (window) that is hosted in a MetaStudio.
010     */
011    public interface StudioComponent {
012      /**
013       * The name is used to construct labels of tabs.
014       * @return the label of a tab.
015       */
016      public String getName();
017    
018      /**
019       * The name can be changed.
020       * @param name new name for this component.
021       */
022      public void setName(String name);
023    
024      /**
025       * The tooltip is used to show when hovering the mouse over tabs.
026       * @return the tooltip of a tab.
027       */
028      public String getTooltip();
029    
030      /**
031       * The tooltip can be changed.
032       * @param tooltip new tooltip for this component.
033       */
034      public void setTooltip(String tooltip);
035      
036      /**
037       * Tabs can be labelled with small icons too.
038       * @return an icon to be used by the Studio
039       */
040      public Icon getIcon();
041    
042      /**
043       * The bridge to Swing is made here. The returned JComponent
044       * will fill exactly one tab. Any JComponent will do.
045       */
046      public JComponent getViewComponent();
047    
048      /** 
049       * Register a listener (usually the plugin that this Component belongs
050       * to, and the MetaStudio).
051       * The studio and the plugin listen to important changes in the state 
052       * of a component. This may be used to implement window management, by
053       * the plugin, or by the Studio.
054       * @param l the listener to register.
055       */
056      public void addStudioComponentListener(StudioComponentListener l);
057    
058      /**
059       * Unregister a listener.
060       */
061      public void removeStudioComponentListener(StudioComponentListener l);
062    
063      /**
064       * Request to close the window. The controls on a tab window are implemented
065       * by the @see MetaStudio. If a user clicks the close icon on a tab, the
066       * component will be notified using this method. This gives the component
067       * the chance to save resources, or start save/cancel dialogs if necessary.
068       * @throws CloseAbortedException if the component can not be closed (for example when the user chooses to cancel.
069       */
070      public void requestClose() throws CloseAbortedException;
071    
072      /**
073       * Closes a component. This makes the component invisible immediately.
074       */
075      public void close();
076    
077      /**
078       * Receive the focus. When a component receives the focus, there is
079       * sometimes something to do, like reset or set the focus to a particular
080       * part of the component.
081       */
082      public void receiveFocus();
083    
084      /**
085       * The MetaStudio has a status bar at the bottom. When a component receives
086       * the focus, the status bar will show the returned JComponents from
087       * left to right in a certain part of the status bar.
088       * @return an array of JComponents to show in the status bar.
089       */ 
090      public JComponent[] getStatusBarComponents();
091    
092      /**
093       * Register a NameChangedListener. If a tab wants to change its name, it
094       * should notify all NameChangedListeners. The MetaStudio itself uses it
095       * to update the label on the tab.
096       */
097      public void addNameChangedListener(NameChangedListener l);
098    
099      /**
100       * Unregister a NameChangedListener.
101       */
102      public void removeNameChangedListener(NameChangedListener l);
103      
104      /**
105       * Register a TooltipChangedListener. If a tab wants to change its tooltip, it
106       * should notify all TooltipChangedListeners. The MetaStudio itself uses it
107       * to update the tooltip off the tab.
108       */
109      public void addTooltipChangedListener(TooltipChangedListener l);
110    
111      /**
112       * Unregister a TooltipChangedListener.
113       */
114      public void removeTooltipChangedListener(TooltipChangedListener l);
115      
116    }