001: /*******************************************************************************
002: * Copyright (c) 2005, 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.internal.layout;
011:
012: import java.util.List;
013:
014: import org.eclipse.swt.SWT;
015:
016: /**
017: * Allow programmatic access to the workbench window trim areas.
018: *
019: * <p>
020: * <b>Note:</b> This is highly experimental and will change between M4 and M5.
021: * For example, the current trim area IDs will be changes to Strings, amongst
022: * other things.
023: * </p>
024: *
025: * @since 3.2
026: */
027: public interface ITrimManager {
028:
029: /**
030: * Trim area location.
031: */
032: public static final int TOP = SWT.TOP;
033:
034: /**
035: * Trim area location.
036: */
037: public static final int BOTTOM = SWT.BOTTOM;
038:
039: /**
040: * Trim area location.
041: */
042: public static final int LEFT = SWT.LEFT;
043:
044: /**
045: * Trim area location.
046: */
047: public static final int RIGHT = SWT.RIGHT;
048:
049: /**
050: * Trim area location.
051: */
052: public static final int NONTRIM = SWT.DEFAULT;
053:
054: /**
055: * Adds the given control to the layout's trim. The same as calling
056: * addTrim(areaId, trim, null);
057: *
058: * @param trim
059: * new window trim to be added
060: * @param areaId
061: * the area ID
062: * @see #getAreaIds()
063: * @see #addTrim(int, IWindowTrim, IWindowTrim)
064: */
065: public void addTrim(int areaId, IWindowTrim trim);
066:
067: /**
068: * Adds the given control to the layout's trim. Note that this must be
069: * called for every trim control. If the given widget is already a trim
070: * widget, it will be moved to the new position. Specifying a position
071: * allows a new widget to be inserted between existing trim widgets.
072: *
073: * <p>
074: * For example, this method allows the caller to say "insert this new
075: * control as trim along the bottom of the layout, to the left of this
076: * existing control".
077: * </p>
078: *
079: * @param trim
080: * new window trim to be added
081: * @param areaId
082: * the area ID
083: * @param beforeMe
084: * trim to insert before, <code>null</code> to insert at the
085: * end
086: * @see #getAreaIds()
087: */
088: public void addTrim(int areaId, IWindowTrim trim,
089: IWindowTrim beforeMe);
090:
091: /**
092: * Removes the given window trim. Note that this has no effect if window
093: * trim is not our window trim.
094: *
095: * @param toRemove
096: * a piece of trim.
097: */
098: public void removeTrim(IWindowTrim toRemove);
099:
100: /**
101: * Return the window trim for a given id.
102: *
103: * @param id
104: * the id
105: * @return the window trim, or <code>null</code> if not found.
106: */
107: public IWindowTrim getTrim(String id);
108:
109: /**
110: * Return all of the IDs for the currently supported trim areas. This is
111: * <b>experimental</b> and will be changing.
112: *
113: * @return the list of IDs that can be used with area descriptions. We
114: * currently support SWT.TOP, SWT.BOTTOM, SWT.LEFT, and SWT.RIGHT.
115: * @since 3.2
116: */
117: public int[] getAreaIds();
118:
119: /**
120: * Return a copy of the IWindowTrim in an ordered array. This will not
121: * return <code>null</code>. This array can be used to shuffle items
122: * around in {@link #updateAreaTrim(int, List, boolean) }.
123: *
124: * @param areaId
125: * the trim area id
126: * @return the IWindowTrim array
127: * @since 3.2
128: * @see #getAreaIds()
129: */
130: public List getAreaTrim(int areaId);
131:
132: /**
133: * Update ID's area description with the new window trim ordering. This
134: * applies the IWindowTrim contains in the array to the trim area named
135: * "ID".
136: *
137: * @param id
138: * the trim area ID
139: * @param trim
140: * the trim array must not be <code>null</code>.
141: * @param removeExtra
142: * if <code>true</code> the any trim in the specified trim area
143: * that's not contained in the List is removed from the window
144: * trim (but not disposed()). If <code>false</code> then the
145: * extra trim is shuffled to the beginning of the trim area.
146: * @since 3.2
147: * @see #getAreaIds()
148: */
149: public void updateAreaTrim(int id, List trim, boolean removeExtra);
150:
151: /**
152: * This method returns an aggregate array of all trim items known to this
153: * TrimLayout.
154: *
155: * @return The List of all IWindowTrim elements
156: * @since 3.2
157: */
158: public List getAllTrim();
159:
160: /**
161: * Update the visibility of the trim controls. It updates any docking
162: * handles as well. It has no effect on visiblity if the window trim doesn't
163: * belong to this TrimLayout.
164: *
165: * @param trim
166: * the trim to update
167: * @param visible
168: * visible or not
169: * @since 3.2
170: */
171: public void setTrimVisible(IWindowTrim trim, boolean visible);
172:
173: /**
174: * Force the trim areas to layout to pick up changes
175: *
176: * @since 3.2
177: */
178: public void forceLayout();
179: }
|