01: /*******************************************************************************
02: * Copyright (c) 2000, 2006 IBM Corporation and others.
03: * All rights reserved. This program and the accompanying materials
04: * are made available under the terms of the Eclipse Public License v1.0
05: * which accompanies this distribution, and is available at
06: * http://www.eclipse.org/legal/epl-v10.html
07: *
08: * Contributors:
09: * IBM Corporation - initial API and implementation
10: *******************************************************************************/package org.eclipse.ui;
11:
12: /**
13: * Represents the context marked for the user in the navigation history.
14: *
15: * Not intended to be implemented by clients. Clients should subclass NavigationLocation
16: * instead.
17: *
18: * @since 2.1
19: */
20: public interface INavigationLocation {
21:
22: /**
23: * Disposes of this location and frees any allocated resource.
24: */
25: public void dispose();
26:
27: /**
28: * Release any state kept by this location. Any relevant state should be
29: * saved by the previous call of saveState(IMemento). This object will
30: * not be used until restoreState is called again.
31: */
32: public void releaseState();
33:
34: /**
35: * Persists the state of this location into the <code>memento</code>
36: *
37: * @param memento the storage were the state should be saved into.
38: */
39: public void saveState(IMemento memento);
40:
41: /**
42: * Restore the state of this location from the <code>memento</code>
43: *
44: * @param memento the storage were the state was saved into.
45: */
46: public void restoreState(IMemento memento);
47:
48: /**
49: * Restore the context saved by this location.
50: */
51: public void restoreLocation();
52:
53: /**
54: * Merge the receiver into <code>currentLocation</code>. Return true if
55: * the two locations could be merged otherwise return false.
56: * <p>
57: * This message is sent to all locations before being added to the history;
58: * given the change to the new location to merge itself into the current
59: * location minimizing the number of entries in the navigation history.
60: * </p>
61: *
62: * @param currentLocation where the receiver should be merged into
63: * @return boolean true if the merge was possible
64: */
65: public boolean mergeInto(INavigationLocation currentLocation);
66:
67: /**
68: * Returns the input used for this location. Returns <code>null</code> if the
69: * receiver's state has been released.
70: *
71: * @return the input for this location
72: */
73: public Object getInput();
74:
75: /**
76: * Returns the display name for this location. This name is used in the
77: * navigation history list.
78: *
79: * @return the display name
80: */
81: public String getText();
82:
83: /**
84: * Sets the location's input.
85: * <p>
86: * Should not be called by clients.
87: * </p>
88: *
89: * @param input the editor input.
90: */
91: public void setInput(Object input);
92:
93: /**
94: * The message <code>update</code> is sent to the active location before
95: * another location becomes active.
96: */
97: public void update();
98: }
|