DockableWindowManager (jEdit API Documentation)
Date: 2015-02-03

org.gjt.sp.jedit.gui

## Class DockableWindowManager

- java.lang.Object
- - java.awt.Component
  - - java.awt.Container
    - - javax.swing.JComponent
      - - javax.swing.JPanel
        - - org.gjt.sp.jedit.gui.DockableWindowManager

- All Implemented Interfaces:
    java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible
  Direct Known Subclasses:
    DockableWindowManagerImpl

      public abstract class DockableWindowManager
      extends javax.swing.JPanel

  Keeps track of all dockable windows for a single View, and provides an API for getting/showing/hiding them.

  Each `View` has an instance of this class.

  dockables.xml:

  Dockable window definitions are read from `dockables.xml` files contained inside plugin JARs. A dockable definition file has the following form:

      <?xml version="1.0"?>
      <!DOCTYPE DOCKABLES SYSTEM "dockables.dtd">
      <DOCKABLES>
          <DOCKABLE NAME="dockableName" MOVABLE="TRUE|FALSE">
              // Code to create the dockable
          </DOCKABLE>
      </DOCKABLES>

  The MOVABLE attribute specifies the behavior when the docking position of the dockable window is changed. If MOVABLE is TRUE, the existing instance of the dockable window is moved to the new docking position, and if the dockable window implements the DockableWindow interface (see `DockableWindow`), it is also notified about the change in docking position before it is moved. If MOVABLE is FALSE, the BeanShell code is invoked to get the instance of the dockable window to put in the new docking position. Typically, the BeanShell code returns a new instance of the dockable window, and the state of the existing instance is not preserved after the change. It is therefore recommended to set MOVABLE to TRUE for all dockables in order to make them preserve their state when they are moved. For backward compatibility reasons, this attribute is set to FALSE by default.

  More than one `<DOCKABLE>` tag may be present. The code that creates the dockable can reference any BeanShell built-in variable (see `BeanShell`), along with a variable `position` whose value is one of `FLOATING`, `TOP`, `LEFT`, `BOTTOM`, and `RIGHT`.

  The following properties must be defined for each dockable window:

  - `dockableName.title` - the string to show on the dockable button.
  - `dockableName.label` - The string to use for generating menu items and action names.
  - `dockableName.longtitle` - (optional) the string to use in the dockable's floating window title (when it is floating). If not specified, the `dockableName.title` property is used.
  A number of actions are automatically created for each dockable window:
  - `dockableName` - opens the dockable window.
  - `dockableName-toggle` - toggles the dockable window's visibility.
  - `dockableName-float` - opens the dockable window in a new floating window.
  Note that only the first action needs a `label` property, the rest have automatically-generated labels.

  Implementation details:

  When an instance of this class is initialized by the `View` class, it iterates through the list of registered dockable windows (from jEdit itself, and any loaded plugins) and examines options supplied by the user in the Global Options dialog box. Any plugins designated for one of the four docking positions are displayed.

  To create an instance of a dockable window, the `DockableWindowManager` finds and executes the BeanShell code extracted from the appropriate `dockables.xml` file. This code will typically consist of a call to the constructor of the dockable window component. The result of the BeanShell expression, typically a newly constructed component, is placed in a window managed by this class.

  Since:
    jEdit 2.6pre3
  See Also:
    `View.getDockableWindowManager()`, Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `DockableWindowManager.DockingArea`
    `static class` | `DockableWindowManager.DockingLayout` Objects of DockingLayout class describe which dockables are docked where, which ones are floating, and their sizes/positions for saving/loading perspectives.

    - ### Nested classes/interfaces inherited from class javax.swing.JPanel

      `javax.swing.JPanel.AccessibleJPanel`

    - ### Nested classes/interfaces inherited from class javax.swing.JComponent

      `javax.swing.JComponent.AccessibleJComponent`

    - ### Nested classes/interfaces inherited from class java.awt.Container

      `java.awt.Container.AccessibleAWTContainer`

    - ### Nested classes/interfaces inherited from class java.awt.Component

      `java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `BOTTOM` Bottom position.
    `protected DockableWindowFactory` | `factory`
    `static java.lang.String` | `FLOATING` Floating position.
    `static java.lang.String` | `LEFT` Left position.
    `static java.lang.String` | `RIGHT` Right position.
    `static java.lang.String` | `TOP` Top position.
    `protected View` | `view`
    `protected java.util.Map<java.lang.String,javax.swing.JComponent>` | `windows`

    - ### Fields inherited from class javax.swing.JComponent

      `accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW`

    - ### Fields inherited from class java.awt.Component

      `BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT`

    - ### Fields inherited from interface java.awt.image.ImageObserver

      `ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DockableWindowManager(View view, DockableWindowFactory instance, View.ViewConfig config)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDockableWindow(java.lang.String name)` Opens the specified dockable window.
    `protected void` | `applyAlternateLayout(boolean alternateLayout)`
    `void` | `applyDockingLayout(DockableWindowManager.DockingLayout docking)`
    `void` | `close()`
    `abstract void` | `closeCurrentArea()`
    `java.awt.event.KeyListener` | `closeListener(java.lang.String dockableName)` The actionEvent "close-docking-area" by default only works on dockable windows that have no special keyboard handling.
    `protected javax.swing.JComponent` | `createDockable(java.lang.String name)`
    `abstract void` | `disposeDockableWindow(java.lang.String name)` Completely dispose of a dockable - called when a plugin is unloaded, to remove all references to the its dockables.
    `protected void` | `dockableLoaded(java.lang.String dockableName, java.lang.String position)`
    `void` | `dockableTitleChanged(java.lang.String dockable, java.lang.String newTitle)`
    `protected void` | `dockingPositionChanged(java.lang.String dockableName, java.lang.String oldPosition, java.lang.String newPosition)`
    `abstract javax.swing.JComponent` | `floatDockableWindow(java.lang.String name)`
    `protected void` | `focusDockable(java.lang.String name)`
    `protected boolean` | `getAlternateLayoutProp()`
    `abstract DockableWindowManager.DockingArea` | `getBottomDockingArea()`
    `javax.swing.JComponent` | `getDockable(java.lang.String name)`
    `protected java.lang.String` | `getDockablePosition(java.lang.String name)`
    `java.lang.String` | `getDockableTitle(java.lang.String name)` Returns the title of the specified dockable window.
    `javax.swing.JComponent` | `getDockableWindow(java.lang.String name)` Returns the specified dockable window.
    `static java.lang.String` | `getDockableWindowPluginName(java.lang.String name)`
    `abstract DockableWindowManager.DockingLayout` | `getDockingLayout(View.ViewConfig config)`
    `abstract DockableWindowManager.DockingArea` | `getLeftDockingArea()`
    `protected java.lang.String` | `getLongTitlePropertyName(java.lang.String dockableName)`
    `static java.lang.String[]` | `getRegisteredDockableWindows()`
    `abstract DockableWindowManager.DockingArea` | `getRightDockingArea()`
    `abstract DockableWindowManager.DockingArea` | `getTopDockingArea()`
    `View` | `getView()` Returns this dockable window manager's view.
    `void` | `handleDockableWindowUpdate(DockableWindowUpdate msg)`
    `void` | `handlePluginUpdate(PluginUpdate pmsg)`
    `void` | `handlePropertiesChanged(PropertiesChanged msg)`
    `abstract void` | `hideDockableWindow(java.lang.String name)`
    `void` | `init()`
    `abstract boolean` | `isDockableWindowDocked(java.lang.String name)`
    `abstract boolean` | `isDockableWindowVisible(java.lang.String name)`
    `java.lang.String` | `longTitle(java.lang.String name)`
    `protected void` | `propertiesChanged()`
    `void` | `removeDockableWindow(java.lang.String name)` Hides the specified dockable window.
    `void` | `setDockableTitle(java.lang.String dockable, java.lang.String title)` Changes the .longtitle property of a dockable window, which corresponds to the title shown when it is floating (not docked).
    `void` | `setDockingLayout(DockableWindowManager.DockingLayout docking)`
    `abstract void` | `setMainPanel(javax.swing.JPanel panel)`
    `java.lang.String` | `shortTitle(java.lang.String name)`
    `abstract void` | `showDockableWindow(java.lang.String name)`
    `void` | `toggleDockableWindow(java.lang.String name)` Toggles the visibility of the specified dockable window.
    `void` | `toggleDockAreas()` Hides all visible dock areas, or shows them again, if the last time it was a hide.
    `boolean` | `willToggleHide()`

    - ### Methods inherited from class javax.swing.JPanel

      `getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI`

    - ### Methods inherited from class javax.swing.JComponent

      `addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update`

    - ### Methods inherited from class java.awt.Container

      `add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree`

    - ### Methods inherited from class java.awt.Component

      `action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### FLOATING

          public static final java.lang.String FLOATING

      Floating position.
      Since:
        jEdit 2.6pre3
      See Also:
        Constant Field Values

    - #### TOP

          public static final java.lang.String TOP

      Top position.
      Since:
        jEdit 2.6pre3
      See Also:
        Constant Field Values

    - #### LEFT

          public static final java.lang.String LEFT

      Left position.
      Since:
        jEdit 2.6pre3
      See Also:
        Constant Field Values

    - #### BOTTOM

          public static final java.lang.String BOTTOM

      Bottom position.
      Since:
        jEdit 2.6pre3
      See Also:
        Constant Field Values

    - #### RIGHT

          public static final java.lang.String RIGHT

      Right position.
      Since:
        jEdit 2.6pre3
      See Also:
        Constant Field Values

    - #### view

          protected View view

    - #### factory

          protected DockableWindowFactory factory

    - #### windows

          protected java.util.Map<java.lang.String,javax.swing.JComponent> windows

  - ### Constructor Detail

    - #### DockableWindowManager

          public DockableWindowManager(View view,
                               DockableWindowFactory instance,
                               View.ViewConfig config)

  - ### Method Detail

    - #### setMainPanel

          public abstract void setMainPanel(javax.swing.JPanel panel)

    - #### showDockableWindow

          public abstract void showDockableWindow(java.lang.String name)

    - #### hideDockableWindow

          public abstract void hideDockableWindow(java.lang.String name)

    - #### disposeDockableWindow

          public abstract void disposeDockableWindow(java.lang.String name)

      Completely dispose of a dockable - called when a plugin is unloaded, to remove all references to the its dockables.

    - #### floatDockableWindow

          public abstract javax.swing.JComponent floatDockableWindow(java.lang.String name)

    - #### isDockableWindowDocked

          public abstract boolean isDockableWindowDocked(java.lang.String name)

    - #### isDockableWindowVisible

          public abstract boolean isDockableWindowVisible(java.lang.String name)

    - #### closeCurrentArea

          public abstract void closeCurrentArea()

    - #### getDockingLayout

          public abstract DockableWindowManager.DockingLayout getDockingLayout(View.ViewConfig config)

    - #### getLeftDockingArea

          public abstract DockableWindowManager.DockingArea getLeftDockingArea()

    - #### getRightDockingArea

          public abstract DockableWindowManager.DockingArea getRightDockingArea()

    - #### getTopDockingArea

          public abstract DockableWindowManager.DockingArea getTopDockingArea()

    - #### getBottomDockingArea

          public abstract DockableWindowManager.DockingArea getBottomDockingArea()

    - #### init

          public void init()

    - #### close

          public void close()

    - #### applyDockingLayout

          public void applyDockingLayout(DockableWindowManager.DockingLayout docking)

    - #### addDockableWindow

          public void addDockableWindow(java.lang.String name)

      Opens the specified dockable window. As of jEdit 4.0pre1, has the same effect as calling showDockableWindow().
      Parameters:
        `name` - The dockable window name
      Since:
        jEdit 2.6pre3

    - #### removeDockableWindow

          public void removeDockableWindow(java.lang.String name)

      Hides the specified dockable window. As of jEdit 4.2pre1, has the same effect as calling hideDockableWindow().
      Parameters:
        `name` - The dockable window name
      Since:
        jEdit 4.2pre1

    - #### toggleDockableWindow

          public void toggleDockableWindow(java.lang.String name)

      Toggles the visibility of the specified dockable window.
      Parameters:
        `name` - The dockable window name

    - #### getDockableWindow

          public javax.swing.JComponent getDockableWindow(java.lang.String name)

      Returns the specified dockable window. Note that this method will return null if the dockable has not been added yet. Make sure you call `addDockableWindow(String)` first.
      Parameters:
        `name` - The name of the dockable window
      Since:
        jEdit 4.1pre2

    - #### toggleDockAreas

          public void toggleDockAreas()

      Hides all visible dock areas, or shows them again, if the last time it was a hide.
      Since:
        jEdit 4.3pre16

    - #### willToggleHide

          public boolean willToggleHide()

      Returns:
        true if the next invocation of "toggle docked areas" will hide the dockables. false otherwise.

    - #### dockableTitleChanged

          public void dockableTitleChanged(java.lang.String dockable,
                                  java.lang.String newTitle)

    - #### closeListener

          public java.awt.event.KeyListener closeListener(java.lang.String dockableName)

      The actionEvent "close-docking-area" by default only works on dockable windows that have no special keyboard handling. If you have dockable widgets with input widgets and/or other fancy keyboard handling, those components may not respond to close docking area. You can add key listeners to each keyboard-handling component in your dockable that usually has keyboard focus. This function creates and returns a key listener which does exactly that. It is also used by FloatingWindowContainer when creating new floating windows.
      Parameters:
        `dockableName` - the name of your dockable
      Returns:
        a KeyListener you can add to that plugin's component.
      Since:
        jEdit 4.3pre6

    - #### getView

          public View getView()

      Returns this dockable window manager's view.
      Since:
        jEdit 4.0pre2

    - #### getDockable

          public javax.swing.JComponent getDockable(java.lang.String name)

      Since:
        jEdit 4.3pre2

    - #### getDockableTitle

          public java.lang.String getDockableTitle(java.lang.String name)

      Returns the title of the specified dockable window.
      Parameters:
        `name` - The name of the dockable window.
      Since:
        jEdit 4.1pre5

    - #### setDockableTitle

          public void setDockableTitle(java.lang.String dockable,
                              java.lang.String title)

      Changes the .longtitle property of a dockable window, which corresponds to the title shown when it is floating (not docked). Fires a change event that makes sure all floating dockables change their title.
      Parameters:
        `dockable` - the name of the dockable, as specified in the dockables.xml
        `title` - the new .longtitle you want to see above it.
      Since:
        4.3pre5

    - #### getRegisteredDockableWindows

          public static java.lang.String[] getRegisteredDockableWindows()

    - #### getDockableWindowPluginName

          public static java.lang.String getDockableWindowPluginName(java.lang.String name)

    - #### setDockingLayout

          public void setDockingLayout(DockableWindowManager.DockingLayout docking)

    - #### handleDockableWindowUpdate

          public void handleDockableWindowUpdate(DockableWindowUpdate msg)

    - #### handlePropertiesChanged

          public void handlePropertiesChanged(PropertiesChanged msg)

    - #### handlePluginUpdate

          public void handlePluginUpdate(PluginUpdate pmsg)

    - #### longTitle

          public java.lang.String longTitle(java.lang.String name)

    - #### shortTitle

          public java.lang.String shortTitle(java.lang.String name)

    - #### applyAlternateLayout

          protected void applyAlternateLayout(boolean alternateLayout)

    - #### dockableLoaded

          protected void dockableLoaded(java.lang.String dockableName,
                            java.lang.String position)

    - #### dockingPositionChanged

          protected void dockingPositionChanged(java.lang.String dockableName,
                                    java.lang.String oldPosition,
                                    java.lang.String newPosition)

    - #### getAlternateLayoutProp

          protected boolean getAlternateLayoutProp()

    - #### propertiesChanged

          protected void propertiesChanged()

    - #### createDockable

          protected javax.swing.JComponent createDockable(java.lang.String name)

    - #### getDockablePosition

          protected java.lang.String getDockablePosition(java.lang.String name)

    - #### focusDockable

          protected void focusDockable(java.lang.String name)

    - #### getLongTitlePropertyName

          protected java.lang.String getLongTitlePropertyName(java.lang.String dockableName)