dockingmanager.java

定要上载质量高而定要上载质量高而定要上载质量高而定要上载质量高而定要上载质量高而

    }

    /**
     * Returns the "main" {@code DockingPort} within the application window
     * containing the specified {@code Component}. Just as desktop applications
     * will tend to have a "main" application window, perhaps surrounded with
     * satellite windows or dialogs, the "main" {@code DockingPort} within a
     * given window will be considered by the application developer to contain
     * the primary docking layout used by the enclosing window.
     * <p>
     * The {@code Component} parameter may or may not be a root window
     * container. If not, the ancestor window of {@code comp} is determined and
     * a set of docking ports encapsulated by a {@code RootDockingPortInfo}
     * instance is returned by a call to
     * {@code getRootDockingPortInfo(Component comp)}. The resolved
     * {@code RootDockingPortInfo} instance's main {@code DockingPort} is
     * returned via its method {@code getMainPort()}.
     * <p>
     * By default, the "main" {@code DockingPort} assigned to any
     * {@code RootDockingPortInfo} instance associated with a window will happen
     * to be the first root {@code DockingPort} detected for that window. In
     * essence, the default settings make this method identical to
     * {@code getRootDockingPort(Component comp)}. This, however, may be
     * altered by {@code RootDockingPortInfo's}
     * {@code setMainPort(String portId)} method based upon the needs of the
     * application developer. In contrast,
     * {@code getMainDockingPort(Component comp)} will always return the first
     * root {@code DockingPort} found within a window.
     * <p>
     * If {@code comp} is {@code null} or the root window cannot be resolved,
     * then this method returns a {@code null} reference. A {@code null}
     * reference is also returned if the root window does not contain any
     * {@code DockingPorts}.
     * 
     * @param comp
     *            the {@code Component} whose root window will be checked for a
     *            main {@code DockingPort}
     * @return the main {@code DockingPort} within the root window that contains
     *         {@code comp}
     * @see #getRootDockingPortInfo(Component)
     * @see #getRootDockingPort(Component)
     * @see DockingPortTracker#getRootDockingPortInfo(Component)
     * @see RootDockingPortInfo#getMainPort()
     * @see RootDockingPortInfo#setMainPort(String)
     */
    public static DockingPort getMainDockingPort(Component comp) {
        RootDockingPortInfo info = getRootDockingPortInfo(comp);
        return info == null ? null : info.getMainPort();
    }

    /**
     * Returns the first root {@code DockingPort} found within the application
     * window containing the specified {@code Component}. A "root"
     * {@code DockingPort} is a {@code DockingPort} embedded within a
     * window/frame/applet/dialog that is not nested within any other parent
     * {@code DockingPorts}. The {@code Component} parameter may or may not be
     * a root window container itself. If not, the root window containing
     * {@code comp} is resolved and the first root {@code DockingPort} found
     * within it is returned. This method defers actual processing to
     * {@code org.flexdock.docking.event.hierarchy.DockingPortTracker.findByWindow(Component comp)}.
     * <p>
     * If {@code comp} is {@code null} or the root window cannot be resolved,
     * then this method returns a {@code null} reference. A {@code null}
     * reference is also returned if the root window does not contain any
     * {@code DockingPorts}.
     * <p>
     * This method differs from {@code getMainDockingPort(Component comp)} in
     * that the "main" {@code DockingPort} for a given window is configurable by
     * the application developer, whereas this method will always return the
     * "first" {@code DockingPort} found within the window. However, if the
     * "main" {@code DockingPort} has not been manually configured by the
     * application developer, then this method and
     * {@code getMainDockingPort(Component comp)} will exhibit identical
     * behavior.
     * 
     * @param comp
     *            the {@code Component} whose root window will be checked for a
     *            root {@code DockingPort}
     * @return the first root {@code DockingPort} found within the root window
     *         that contains {@code comp}
     * @see #getMainDockingPort(Component)
     * @see DockingPortTracker#findByWindow(Component)
     * @see RootDockingPortInfo
     */
    public static DockingPort getRootDockingPort(Component comp) {
        return DockingPortTracker.findByWindow(comp);
    }

    /**
     * Returns the {@code RootDockingPortInfo} instance associated with the root
     * window containing the specified {@code Component}. The {@code Component}
     * parameter may or may not be a root window container itself. If not, the
     * root window containing {@code comp} is resolved and the
     * {@code RootDockingPortInfo} instance associated with the window is
     * returned. {@code RootDockingPortInfo} will contain information regarding
     * all of the "root" {@code DockingPorts} embedded within a root window
     * where a "root" {@code DockingPort} is any {@code DockingPort} embedded
     * within the window that does not have any other {@code DockingPort}
     * ancestors in it's container hierarchy.
     * <p>
     * If {@code comp} is {@code null} or the root window cannot be resolved,
     * then this method returns a {@code null} reference. A {@code null}
     * reference is also returned if the root window does not contain any
     * {@code DockingPorts}.
     * <p>
     * This method dispatches internally to
     * {@code org.flexdock.docking.event.hierarchy.DockingPortTracker.getRootDockingPortInfo(Component comp)}.
     * 
     * @param comp
     *            the {@code Component} whose root window will be checked for an
     *            associated {@code RootDockingPortInfo}.
     * @return the {@code RootDockingPortInfo} instance associated with the root
     *         window containing {@code comp}.
     * @see RootDockingPortInfo
     * @see DockingPortTracker#getRootDockingPortInfo(Component)
     */
    public static RootDockingPortInfo getRootDockingPortInfo(Component comp) {
        return DockingPortTracker.getRootDockingPortInfo(comp);
    }

    /**
     * Sends the application's current layout model to external storage. This
     * method defers processing to the currently installed
     * {@code org.flexdock.docking.state.LayoutManager} by invoking its
     * {@code store()} method. If there is no {@code LayoutManager} installed,
     * then this method returns {@code false}.
     * <p>
     * The layout model itself, along with storage mechanism, is abstract and
     * dependent upon the particular {@code LayoutManager} implementation. As
     * such, it may be possible that the {@code LayoutManager} is unable to
     * persist the current layout state for non-Exceptional reasons. This method
     * returns {@code true} if the layout model was successfully stored and
     * {@code false} if the layout model could not be stored under circumstances
     * that do not generate an {@code Exception} (for instance, if there is no
     * persistence implementation currently installed). If a problem occurs
     * during the persistence process, an {@code IOException} is thrown.
     * 
     * @return {@code true} if the current layout model was succesfully stored,
     *         {@code false} otherwise.
     * @throws IOException
     * @throws PersisterException
     * @see #getLayoutManager()
     * @see #setLayoutManager(LayoutManager)
     * @see LayoutManager#store()
     */
    public static boolean storeLayoutModel() throws IOException,
            PersistenceException {
        LayoutManager mgr = getLayoutManager();
        return mgr == null ? false : mgr.store();
    }

    /**
     * Loads a previously stored layout model into the currently installed
     * {@code LayoutManager}. This method defers processing to
     * {@code loadLayoutModel(boolean restore)} with an argument of
     * {@code false} to indicate that the stored data model should merely be
     * loaded into memory and the {@code LayoutManager} should not attempt to
     * subsequently restore the application view by synchronizing it against the
     * newly loaded data model.
     * <p>
     * The layout model itself, along with storage mechanism, is abstract and
     * dependent upon the particular {@code LayoutManager} implementation. As
     * such, it may be possible that the {@code LayoutManager} is unable to load
     * the previous layout state for non-Exceptional reasons. This method
     * returns {@code true} if the layout model was successfully loaded and
     * {@code false} if the layout model could not be loaded under circumstances
     * that do not generate an {@code Exception} (for instance, if there was no
     * previous layout model found in storage). If a problem occurs during the
     * loading process, an {@code IOException} is thrown.
     * 
     * @return {@code true} if the current layout model was succesfully loaded,
     *         {@code false} otherwise.
     * @throws IOException
     * @throws PersisterException
     * @see #loadLayoutModel(boolean)
     * @see LayoutManager#load()
     */
    public static boolean loadLayoutModel() throws IOException,
            PersistenceException {
        return loadLayoutModel(false);
    }

    /**
     * Loads a previously stored layout model into the currently installed
     * {@code LayoutManager} and attempts to synchronize the application view
     * with the newly loaded layout model if the {@code restore} parameter is
     * {@code true}. If there is no currently installed {@code LayoutManager},
     * then this method returns {@code false}. If the {@code restore} parameter
     * is {@code true}, then this method defers processing to
     * {@code restoreLayout(boolean loadFromStorage)} with an argument of
     * {@code true}. Otherwise, this method defers processing to the currently
     * installed {@code org.flexdock.docking.state.LayoutManager} by invoking
     * its {@code load()} method.
     * <p>
     * The layout model itself, along with storage mechanism, is abstract and
     * dependent upon the particular {@code LayoutManager} implementation. As
     * such, it may be possible that the {@code LayoutManager} is unable to load
     * the previous layout state for non-Exceptional reasons. This method
     * returns {@code true} if the layout model was successfully loaded and
     * {@code false} if the layout model could not be loaded under circumstances
     * that do not generate an {@code Exception} (for instance, if there was no
     * previous layout model found in storage). If a problem occurs during the
     * loading process, an {@code IOException} is thrown.
     * 
     * @return {@code true} if the current layout model was succesfully loaded,
     *         {@code false} otherwise.
     * @throws IOException
     * @throws PersisterException
     * @see #getLayoutManager()
     * @see #setLayoutManager(LayoutManager)
     * @see #restoreLayout(boolean)
     * @see LayoutManager#load()
     */
    public static boolean loadLayoutModel(boolean restore) throws IOException,
            PersistenceException {
        LayoutManager mgr = getLayoutManager();
        if (mgr == null)
            return false;

        return restore ? restoreLayout(true) : mgr.load();
    }

    /**
     * Synchronizes the application view with the current in-memory layout
     * model. This method defers processing to
     * {@code restoreLayout(boolean loadFromStorage)} with an argument of
     * {@code false}. This instructs the currently installed
     * {@code LayoutManager} to restore the application view to match the
     * current in-memory layout model without reloading from storage prior to
     * restoration. This method is useful for developers who choose to construct
     * a layout model programmatically and wish to "commit" it to the
     * application view, restoring their own in-memory layout model rather than
     * a model persisted in external storage.
     * <p>
     * If there is no {@code LayoutManager} currently installed, then this
     * method returns {@code false}.
     * 
     * @return {@code true} if the in-memory layout model was properly restored
     *         to the application view, {@code false} otherwise.
     * @throws PersisterException
     * @see #restoreLayout(boolean)
     * @see #getLayoutManager()
     * @see #setLayoutManager(LayoutManager)
     * @see LayoutManager#restore(boolean)
     */
    public static boolean restoreLayout() {
        try {
            return restoreLayout(false);
        } catch (IOException e) {
            // shouldn't happen since we're not intending to load from storage
            log.debug(e.getMessage(), e);
            return false;
        } catch (PersistenceException e) {
            // TODO Auto-generated catch block
            log.debug(e.getMessage(), e);
            return false;
        }
    }

    /**
     * Synchronizes the application view with the current in-memory layout
     * model. This method defers processing to the currently installed
     * {@code org.flexdock.docking.state.LayoutManager} by invoking its
     * {@code restore(boolean loadFromStorage)} method. If there is no
     * {@code LayoutManager} currently installed, then this method returns
     * {@code false}.
     * <p>
     * If the {@code loadFromStorage} parameter is {@code true}, then the
     * {@code LayoutManager} is instructed to load any persisted layout model
     * from external storage into memory before synchronizing the application
     * view. If a problem occurs while loading from exernal storage, this method
     * throws an {@code IOException}.
     * 
     * @param loadFromStorage
     *            instructs whether to load any layout model from external
     *            storage into memory before synchronizing the application view.
     * @return {@code true} if the in-memory layout model was properly restored
     *         to the application view, {@code false} otherwise.
     * @throws PersisterException
     * @see #getLayoutManager()
     * @see #setLayoutManager(LayoutManager)
     * @see LayoutManage