001: /*******************************************************************************
002: * Copyright (c) 2001, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.views.properties.tabbed;
011:
012: import org.eclipse.jface.viewers.ISelection;
013: import org.eclipse.swt.widgets.Composite;
014: import org.eclipse.ui.IWorkbenchPart;
015:
016: /**
017: * Represents a section of properties for a given input.
018: * <p>
019: * The lifecycle of an ISection is as follows:
020: * <ul>
021: * <li><code>ISection.createControls()</code></li>
022: * <li><code>ISection.setInput()</code></li>
023: * <li><code>ISection.aboutToBeShown()</code></li>
024: * <li><code>ISection.refresh()</code></li>
025: * <li><code>ISection.aboutToBeHidden()</code></li>
026: * <li><code>ISection.dispose()</code></li>
027: * </ul>
028: * </p>
029: * <p>
030: * Implementors of this class should be aware that a section instance might be
031: * reused for different input objects (as long as they are valid section
032: * inputs). It means that <code>ISection.setInput</code> can be called at any
033: * time between <code>ISection.createControls</code> and
034: * <code>ISection.dispose</code>.
035: * </p>
036: * <p>
037: * When an input change event occurs, such as a tab selection or a workbench
038: * selection change, an ISection is sent:
039: * <ul>
040: * <li><code>ISection.setInput()</code></li>
041: * <li><code>ISection.refresh()</code></li>
042: * </ul>
043: * </p>
044: * <p>
045: * When an part activation event occurs, such as the contributor part activation
046: * event, an ISection is sent:
047: * <ul>
048: * <li><code>ISection.setInput()</code></li>
049: * <li><code>ISection.aboutToBeShown()</code></li>
050: * <li><code>ISection.refresh()</code></li>
051: * <li><code>ISection.setInput()</code></li>
052: * <li><code>ISection.refresh()</code></li>
053: * </ul>
054: * This is because both a tab selection event and an input selection event have
055: * occurred.
056: * </p>
057: * <p>
058: * This interface should not be extended or implemented. New section instances
059: * should be created using <code>AbstractPropertySection</code>.
060: * </p>
061: * @see org.eclipse.ui.views.properties.tabbed.TabbedPropertySheetPage
062: *
063: * @author Anthony Hunter
064: */
065: public interface ISection {
066:
067: /**
068: * Creates the controls for the section.
069: * <p>
070: * Clients should take advantage of the widget factory provided by the
071: * framework to achieve a common look between property sections.
072: * </p>
073: * @see org.eclipse.ui.views.properties.tabbed.TabbedPropertySheetPage#getWidgetFactory()
074: *
075: * @param parent
076: * the parent composite for the section.
077: * @param tabbedPropertySheetPage
078: * the tabbed property sheet page.
079: */
080: public abstract void createControls(Composite parent,
081: TabbedPropertySheetPage tabbedPropertySheetPage);
082:
083: /**
084: * Notifies the section that the workbench selection has changed.
085: * @param part The active workench part.
086: * @param selection The active selection in the workbench part.
087: */
088: public abstract void setInput(IWorkbenchPart part,
089: ISelection selection);
090:
091: /**
092: * Notifies the section that its controls are about to be shown. It is
093: * expected that sections enable domain related functions in this method,
094: * most commonly add listeners.
095: * <p>
096: * Since the controls are not visible, the section should wait for the
097: * refresh() before updating the section controls.
098: * </p>
099: */
100: public abstract void aboutToBeShown();
101:
102: /**
103: * Notifies the section that its controls are about to be hidden. It is
104: * expected that sections disable domain related functions in this method,
105: * most commonly remove listeners.
106: */
107: public abstract void aboutToBeHidden();
108:
109: /**
110: * Dispose this section.
111: */
112: public abstract void dispose();
113:
114: /**
115: * Returns the minimum height needed by this section. A return value of
116: * <code>SWT.DEFAULT</code> indicates that no minimum height is defined.
117: *
118: * @return the minimum height needed by this section.
119: */
120: public abstract int getMinimumHeight();
121:
122: /**
123: * Determine whether this section would like extra height space in case
124: * there is some left. Normally this is true when the section is the last to
125: * be displayed on a tab or is the only section on a tab.
126: * @return <code>true</code> if this section would like extra height space.
127: */
128: public abstract boolean shouldUseExtraSpace();
129:
130: /**
131: * Refresh the contents of the controls displayed in this section.
132: */
133: public abstract void refresh();
134: }
|