ISynchronizePageConfiguration


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.team.ui.synchronize;
12  
13  import org.eclipse.jface.operation.IRunnableContext;
14  import org.eclipse.jface.util.IPropertyChangeListener;
15  import org.eclipse.jface.viewers.ILabelDecorator;
16  import org.eclipse.team.core.synchronize.SyncInfoSet;
17  import org.eclipse.team.internal.ui.TeamUIPlugin;
18  import org.eclipse.ui.IWorkbenchActionConstants;
19  
20  /**
21   * Configures the model, actions and label decorations of an 
22   * {@link ISynchronizePage}. Clients can:
23   * <ul> 
24   * <li>set properties to affect the page contents and react to property changes
25   * <li>add and configure the actions available to the user (context menu,
26   * toolbar and view menu)
27   * </ul>
28   * <p>
29   * This interface is not intended to be implemented by clients.
30   * </p>
31   * @since 3.0
32   */
33  public interface ISynchronizePageConfiguration {
34      
35      /**
36       * Property constant for the <code>SyncInfoSet</code> that is being 
37       * displayed by the page. Some pages may not be displaying the 
38       * contents of a <code>SyncInfoSet</code> in which case the value
39       * associated with this property will be <code>null</code>.
40       */
41      public static final String   P_SYNC_INFO_SET = TeamUIPlugin.ID  + ".P_SYNC_INFO_SET"; //$NON-NLS-1$
42          
43      /**
44       * Property constant for the list of label decorators 
45       * (instance of <code>ILabelDecorator[]</code>) that will be 
46       * applied to the text and image from the label provider.
47       */
48      public static final String   P_LABEL_DECORATORS = TeamUIPlugin.ID  + ".P_LABEL_DECORATORS"; //$NON-NLS-1$
49  
50      /**
51       * Property constant that defines the groups in the toolbar 
52       * menu of the page. The value for this
53       * property should be a string array. If this property is
54       * set to <code>null</code>, the <code>DEFAULT_TOOLBAR_MENU</code>
55       * is used. Also, the groups mentioned in the <code>DEFAULT_TOOLBAR_MENU</code>
56       * can be removed but will always appear in the same order if 
57       * included.
58       */
59      public static final String   P_TOOLBAR_MENU = TeamUIPlugin.ID + ".P_TOOLBAR_MENU"; //$NON-NLS-1$
60  
61      /**
62       * The configuration property that defines
63       * the groups in the context menu of the page. The value for this
64       * property should be a string array.
65       */
66      public static final String   P_CONTEXT_MENU = TeamUIPlugin.ID + ".P_CONTEXT_MENU"; //$NON-NLS-1$
67      
68      /**
69       * Property constant that defines the groups in the dropdown view 
70       * menu of the page. The value for this
71       * property should be a string array. If this property is
72       * set to <code>null</code>, the <code>DEFAULT_VIEW_MENU</code>
73       * is used. Also, the groups mentioned in the <code>DEFAULT_VIEW_MENU</code>
74       * can be removed but will always appear in the same order if 
75       * included.
76       */
77      public static final String   P_VIEW_MENU = TeamUIPlugin.ID + ".P_VIEW_MENU"; //$NON-NLS-1$
78  
79      /**
80       * The configuration property that defines the filter id that
81       * determines which object contribution actions appear in the 
82       * context menu for the page. This defaults to the id of the
83       * participant but can be set to another id or <code>null</code>
84       * @since 3.1
85       */
86      public static final String   P_OBJECT_CONTRIBUTION_ID = TeamUIPlugin.ID +  ".P_OBJECT_CONTRIBUTION_ID"; //$NON-NLS-1$
87      
88      /**
89       * Property constant for the type of comparison used to create
90       * the <code>SyncInfo</code> in the P_SYNC_INFO_SET property.
91       * If the comparison type is <code>THREE_WAY</code> then
92       * modes selection applies.
93       */
94      public static final String   P_COMPARISON_TYPE = TeamUIPlugin.ID + ".P_COMPARISON_TYPE"; //$NON-NLS-1$
95      
96      /**
97       * Property constant for the mode used to filter the visible
98       * elements of the model. The value can be one of the mode integer
99       * constants.
100      */
101     public static final String   P_MODE = TeamUIPlugin.ID  + ".P_SYNCVIEWPAGE_MODE";   //$NON-NLS-1$
102     
103     /**
104      * Property constant which indicates which modes are to be available to the user.
105      * The value is to be an integer that combines one or more of the
106      * mode bit values.
107      * Either <code>null</code> or <code>0</code> can be used to indicate that
108      * mode filtering is not supported.
109      */
110     public static final String   P_SUPPORTED_MODES = TeamUIPlugin.ID  + ".P_SUPPORTED_MODES";  //$NON-NLS-1$
111     
112     /**
113      * Property constant for the id of the viewer to be used for this page.
114      * The viewer id corresponds to the viewer definition in the Common
115      * Navigator framework.
116      * 
117      * @since 3.2
118      */
119     public static final String   P_VIEWER_ID = TeamUIPlugin.ID + ".P_VIEWER_ID"; //$NON-NLS-1$
120     
121     /**
122      * Property constant for the description (String) of the page that appears
123      * as the description of the view when the page is active.
124      * 
125      * @since 3.2
126      */
127     public static final String   P_PAGE_DESCRIPTION = TeamUIPlugin.ID + ".P_PAGE_DESCRIPTION"; //$NON-NLS-1$
128     
129     /**
130      * The id of the synchronize group the determines where the synchronize 
131      * actions appear.
132      */
133     public static final String   SYNCHRONIZE_GROUP = "synchronize"; //$NON-NLS-1$
134 
135     /**
136      * The id of the navigate group that determines where the navigation
137      * actions appear
138      */
139     public static final String   NAVIGATE_GROUP = "navigate"; //$NON-NLS-1$
140     
141     /**
142      * The id of the sort group that determines where sort
143      * actions or submenus appear.
144      * @since 3.1
145      */
146     public final static String   SORT_GROUP = "sort"; //$NON-NLS-1$
147 
148     /**
149      * The id of the mode group that determines where the mode selection
150      * actions appear
151      */
152     public static final String   MODE_GROUP = "modes"; //$NON-NLS-1$
153 
154     /**
155      * The id of the file group that determines where the file
156      * actions appear. File actions include the open actions.
157      */
158     public static final String   FILE_GROUP = "file"; //$NON-NLS-1$
159 
160     /**
161      * The id of the edit group that determines where the edit
162      * actions appear (e.g. move and delete).
163      */
164     public static final String   EDIT_GROUP = "edit"; //$NON-NLS-1$
165 
166     /**
167      * The id of the preferences group that determines whether the preferences
168      * actions appear in the view dropdown.
169      */
170     public static final String   PREFERENCES_GROUP = "preferences"; //$NON-NLS-1$
171     
172     /**
173      * The id of the group that determines where workbench object contributions
174      * should appear. This group will only be used if there is an
175      * OBJECT_CONTRIBUTION_ID set in the configuration
176      * @since 3.1
177      */
178     public static final String   OBJECT_CONTRIBUTIONS_GROUP = IWorkbenchActionConstants.MB_ADDITIONS;
179     
180     /**
181      * The id of the layout group that determines whether the layout selection
182      * actions appear in the view dropdown or toolbar.
183      */
184     public static final String   LAYOUT_GROUP = "layout"; //$NON-NLS-1$
185 
186     /**
187      * These are the default groups used for the context menu of a page.
188      * Clients can remove, add and change the ordering for groups in
189      * the context menu.
190      */
191     public static final String  [] DEFAULT_CONTEXT_MENU = new String  [] { FILE_GROUP, EDIT_GROUP, SYNCHRONIZE_GROUP, NAVIGATE_GROUP, SORT_GROUP, OBJECT_CONTRIBUTIONS_GROUP};
192 
193     /**
194      * These are the default groups used for the toolbar of a page.
195      * These groups will always appear in this order in the toolbar.
196      * Clients can disable one or more of these groups by setting
197      * the <code>P_TOOLBAR_MENU</code> property to an array that
198      * contains a subset of these. Clients can also add groups 
199      * by adding new unique group ids to the array. Added groups 
200      * will appear in the order specified but after the default groups.
201      */
202     public static final String  [] DEFAULT_TOOLBAR_MENU = new String  [] { SYNCHRONIZE_GROUP, NAVIGATE_GROUP, MODE_GROUP, LAYOUT_GROUP };
203     
204     /**
205      * These are the default groups used for the dropdown view menu of a page.
206      * These groups will always appear in this order in the view menu.
207      * Clients can disable one or more of these groups by setting
208      * the <code>P_VIEW_MENU</code> property to an array that
209      * contains a subset of these. Clients can also add groups 
210      * by adding new unique group ids to the array. Added groups 
211      * will appear in the order specified but after the default groups.
212      */
213     public static final String  [] DEFAULT_VIEW_MENU = new String  [] { LAYOUT_GROUP, MODE_GROUP, SYNCHRONIZE_GROUP, PREFERENCES_GROUP };
214 
215     /**
216      * Comparison type constants
217      */
218     public final static String   TWO_WAY = "two-way"; //$NON-NLS-1$
219     public final static String   THREE_WAY = "three-way"; //$NON-NLS-1$
220     
221     /**
222      * Modes are direction filters for the view
223      */
224     public final static int INCOMING_MODE = 0x1;
225     public final static int OUTGOING_MODE = 0x2;
226     public final static int BOTH_MODE = 0x4;
227     public final static int CONFLICTING_MODE = 0x8;
228     public final static int ALL_MODES = INCOMING_MODE | OUTGOING_MODE | CONFLICTING_MODE | BOTH_MODE;
229 
230     /**
231      * Return the participant associated with this configuration.
232      * @return the participant
233      */
234     public abstract ISynchronizeParticipant getParticipant();
235     
236     /**
237      * Return the site which provides access to certain workbench
238      * services.
239      * @return the page site
240      */
241     public abstract ISynchronizePageSite getSite();
242     
243     /**
244      * Return the page created from and associated with this
245      * configuration.
246      * @return Returns the page for this configuration
247      */
248     public ISynchronizePage getPage();
249     
250     /**
251      * Set the page for this configuration. This method should only
252      * be called once by the {@link ISynchronizeParticipant} that created
253      * the page.
254      * @param page the configuration's page
255      */
256     public void setPage(ISynchronizePage page);
257 
258     /**
259      * Add a property change listener to the configuration.
260      * Registered listeners will receive notification when 
261      * any property changes.
262      * @param listener a property change listener
263      */
264     public abstract void addPropertyChangeListener(IPropertyChangeListener listener);
265 
266     /**
267      * Remove the registered change listener. Removing an unregistered listener
268      * has no effects.
269      * @param listener a property change listener
270      */
271     public abstract void removePropertyChangeListener(IPropertyChangeListener listener);
272 
273     /**
274      * Sets the property with the given name.
275      * If the new value differs from the old a <code>PropertyChangeEvent</code>
276      * is sent to registered listeners.
277      *
278      * @param key the name of the property to set
279      * @param newValue the new value of the property
280      */
281     public abstract void setProperty(String   key, Object   newValue);
282 
283     /**
284      * Returns the property with the given name, or <code>null</code>
285      * if no such property exists.
286      *
287      * @param key the name of the property to retrieve
288      * @return the property with the given name, or <code>null</code> if not found
289      */
290     public abstract Object   getProperty(String   key);
291 
292     /**
293      * Register the action group with the configuration. The
294      * registered action groups will have the opportunity to add
295      * actions to the action bars and context menu of the synchronize
296      * page created using the configuration.
297      * @param group a synchronize page action group
298      */
299     public abstract void addActionContribution(SynchronizePageActionGroup group);
300 
301     /**
302      * Remove a previously registered action group. Removing
303      * a group that is not registered has no effect.
304      * @param group a synchronize page action group
305      */
306     public abstract void removeActionContribution(SynchronizePageActionGroup group);
307     
308     /**
309      * Add a label decorator to the page configuration.
310      * @param decorator a label decorator
311      */
312     public void addLabelDecorator(ILabelDecorator decorator);
313     
314     /**
315      * Set the groups that are to be added to the menu identified
316      * by the menu property id.
317      * @param menuPropertyId the menu property id (one of <code>P_CONTEXT_MENU</code>,
318      * <code>P_VIEW_MENU</code> or <code>P_TOOLBAR_MENU</code>)
319      * @param groups a array of groups Ids
320      */
321     public void setMenuGroups(String   menuPropertyId, String  [] groups);
322     
323     /**
324      * Adds a menu group of the given id to the end of the menu groups list
325      * for the given menu property id.
326      * @param menuPropertyId the menu property id (one of <code>P_CONTEXT_MENU</code>,
327      * <code>P_VIEW_MENU</code> or <code>P_TOOLBAR_MENU</code>)
328      * @param groupId the id of the group to be added to the end of the menu
329      * group list
330      */
331     public void addMenuGroup(String   menuPropertyId, String   groupId);
332 
333     /**
334      * Returns whether the given group appears in the given menu
335      * @param menuPropertyId the property id that identifies the menu
336      * @param groupId the id of the group
337      * @return <code>true</code> if the group identified by the groupId appears
338      * in the menu identified by the menuPropertyId and <code>false</code>
339      * otherwise
340      */
341     public abstract boolean hasMenuGroup(String   menuPropertyId, String   groupId);
342     
343     /**
344      * Return the value of the P_MODE property of this configuration.
345      * @return the mode property value
346      */
347     int getMode();
348 
349     /**
350      * Set the P_MODE property of this configuration to the
351      * given mode flag (one of <code>INCOMING_MODE</code>,
352      * <code>OUTGOING_MODE</code>, <code>BOTH_MODE</code>
353      * or <code>CONFLICTING_MODE</code>).
354      * @param mode the mode value
355      */
356     void setMode(int mode);
357     
358     /**
359      * Return the value of the P_SUPPORTED_MODES property of this configuration.
360      * @return the supported modes property value
361      */
362     int getSupportedModes();
363     
364     /**
365      * Set the P_SUPPORTED_MODES property of this configuration to the
366      * ORed combination of one or more mode flags (<code>INCOMING_MODE</code>,
367      * <code>OUTGOING_MODE</code>, <code>BOTH_MODE</code>
368      * and <code>CONFLICTING_MODE</code>).
369      * @param modes the supported modes
370      */
371     void setSupportedModes(int modes);
372 
373     /**
374      * Return the set associated with the P_SYNC_INFO_SET property
375      * or <code>null</code> if the property is not set.
376      * @return the set associated with the P_SYNC_INFO_SET property
377      * or <code>null</code> if the property is not set
378      */
379     public abstract SyncInfoSet getSyncInfoSet();
380     
381     /**
382      * Return the comparison type used by the page's <code>SyncInfo</code>
383      * modes.
384      * @return comparison type (could be <code>TWO_WAY</code>, <code>THREE_WAY</code>
385      * or a custom type).
386      */
387     String   getComparisonType();
388     
389     /**
390      * Set the comparison type used by the page's <code>SyncInfo</code>
391      * modes. The default type is <code>THREE_WAY</code>.
392      * @param type the comparison type (could be <code>TWO_WAY</code>, <code>THREE_WAY</code>
393      * or a custom type).
394      */
395     void setComparisonType(String   type);
396     
397     /**
398      * Sets the runnable context that can be used by the page's
399      * actions to display progress.
400      * @param context a runnable context (or null)
401      */
402     void setRunnableContext(IRunnableContext context);
403     
404     /**
405      * Return the runnable context. If <code>null</code> is returned,
406      * actions can use their own method of progress feedback either
407      * using a background job or the progress service
408      * @return a runnable context (or <code>null</code>)
409      */
410     IRunnableContext getRunnableContext();
411 
412     /**
413      * Return the id of the viewer to which this configuration is 
414      * associated.
415      * @return the id of the viewer to which this configuration is 
416      * associated
417      * @since 3.2
418      */
419     String   getViewerId();
420 }
421
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags