001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.core.spi.multiview;
043:
044: import javax.swing.Action;
045: import javax.swing.JComponent;
046: import org.openide.awt.UndoRedo;
047: import org.openide.util.Lookup;
048:
049: /** View element for multi view, provides the UI components to the multiview component.
050: * Gets notified by the enclosing component about the changes in the lifecycle.
051: *
052: * @author Dafe Simonek, Milos Kleint
053: */
054: public interface MultiViewElement {
055:
056: /** Returns Swing visual representation of this multi view element. Should be relatively fast
057: * and always return the same component.
058: */
059: JComponent getVisualRepresentation();
060:
061: /**
062: * Returns the visual component with the multi view element's toolbar.Should be relatively fast as it's called
063: * everytime the current perspective is switched.
064: */
065: JComponent getToolbarRepresentation();
066:
067: /**
068: * Gets the actions which will appear in the popup menu of this component.
069: * <p>Subclasses are encouraged to use add the default TopComponent actions to
070: * the array of their own. These are accessible by calling MultiViewElementCallback.createDefaultActions()
071: *<pre>
072: * <code>
073: * public Action[] getActions() {
074: * Action[] retValue;
075: * // the multiviewObserver was passed to the element in setMultiViewCallback() method.
076: * if (multiViewObserver != null) {
077: * retValue = multiViewObserver.createDefaultActions();
078: * // add you own custom actions here..
079: * } else {
080: * // fallback..
081: * retValue = super.getActions();
082: * }
083: * return retValue;
084: * }
085: * </code>
086: *</pre>
087: * @return array of actions for this component
088: */
089: Action[] getActions();
090:
091: /**
092: * Lookup for the MultiViewElement. Will become part of the TopComponent's lookup.
093: * @return the lookup to use when the MultiViewElement is active.
094: */
095: Lookup getLookup();
096:
097: /** Called only when enclosing multi view top component was closed before and
098: * now is opened again for the first time. The intent is to
099: * provide subclasses information about multi view TopComponent's life cycle.
100: * Subclasses will usually perform initializing tasks here.
101: */
102: void componentOpened();
103:
104: /** Called only when multi view top component was closed. The intent is
105: * to provide subclasses information about TopComponent's life cycle.
106: * Subclasses will usually perform cleaning tasks here.
107: */
108: void componentClosed();
109:
110: /** Called when this MultiViewElement is about to be shown.
111: * That can happen when switching the current perspective/view or when the topcomonent itself is shown for the first time.
112: */
113: void componentShowing();
114:
115: /** Called when this MultiViewElement was hidden. This happens when other view replaces this one as the selected view or
116: * when the whole topcomponent gets hidden (eg. when user selects anothe topcomponent in the current mode).
117: */
118: void componentHidden();
119:
120: /** Called when this multi view element is activated.
121: * This happens when the parent window of this component gets focus
122: * (and this component is the preferred one in it), <em>or</em> when
123: * this component is selected in its window (and its window was already focused).
124: */
125: void componentActivated();
126:
127: /** Called when this multi view element is deactivated.
128: * This happens when the parent window of this component loses focus
129: * (and this component is the preferred one in the parent),
130: * <em>or</em> when this component loses preference in the parent window
131: * (and the parent window is focussed).
132: */
133: void componentDeactivated();
134:
135: /**
136: * UndoRedo support,
137: * Get the undo/redo support for this element.
138: *
139: * @return undoable edit for this component, null if not implemented.
140: */
141: UndoRedo getUndoRedo();
142:
143: /**
144: * Use the passed in callback instance for manipulating the enclosing multiview component, keep the instance around
145: * during lifecycle of the component if you want to automatically switch to this component etc.
146: * The enclosing window enviroment attaches the callback right after creating
147: * the element from the description.
148: * Same applies for deserialization of MultiViewTopComponent, thus MultiViewElement
149: * implementors shall not attempt to serialize the passed instance.
150: */
151: void setMultiViewCallback(MultiViewElementCallback callback);
152:
153: /**
154: * Element decides if it can be safely closed. The element shall just return a value
155: * (created by MultiViewFactory.createCloseState() factory method),
156: * not open any UI, that is a semantical difference from TopComponent.canClose().
157: * The CloseOperationHandler is the centralized place to show dialogs to the user.
158: * In cases when the element is consistent, just return CloseOperationState.STATE_OK.
159: */
160: CloseOperationState canCloseElement();
161:
162: }
|