KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > google > gwt > user > client > History


1 /*
2  * Copyright 2007 Google Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5  * use this file except in compliance with the License. You may obtain a copy of
6  * the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13  * License for the specific language governing permissions and limitations under
14  * the License.
15  */

16 package com.google.gwt.user.client;
17
18 import com.google.gwt.core.client.GWT;
19 import com.google.gwt.core.client.GWT.UncaughtExceptionHandler;
20 import com.google.gwt.user.client.impl.HistoryImpl;
21
22 import java.util.ArrayList JavaDoc;
23 import java.util.Iterator JavaDoc;
24
25 /**
26  * This class allows you to interact with the browser's history stack. Each
27  * "item" on the stack is represented by a single string, referred to as a
28  * "token". You can create new history items (which have a token associated with
29  * them when they are created), and you can programmatically force the current
30  * history to move back or forward.
31  *
32  * <p>
33  * In order to receive notification of user-directed changes to the current
34  * history item, implement the
35  * {@link com.google.gwt.user.client.HistoryListener} interface and attach it
36  * via {@link #addHistoryListener}.
37  * </p>
38  *
39  * <p>
40  * <h3>Example</h3>
41  * {@example com.google.gwt.examples.HistoryExample}
42  * </p>
43  */

44 public class History {
45
46   private static ArrayList JavaDoc historyListeners = new ArrayList JavaDoc();
47   private static HistoryImpl impl;
48
49   static {
50     impl = (HistoryImpl) GWT.create(HistoryImpl.class);
51     if (!impl.init()) {
52       // Set impl to null as a flag to no-op future calls.
53
impl = null;
54
55       // Tell the user.
56
GWT.log(
57           "Unable to initialize the history subsystem; did you "
58               + "include the history frame in your host page? Try "
59               + "<iframe SRC=\"javascript:''\" id='__gwt_historyFrame' style='width:0;height:0;border:0'>"
60               + "</iframe>", null);
61     }
62   }
63
64   /**
65    * Adds a listener to be informed of changes to the browser's history stack.
66    *
67    * @param listener the listener to be added
68    */

69   public static void addHistoryListener(HistoryListener listener) {
70     historyListeners.add(listener);
71   }
72
73   /**
74    * Programmatic equivalent to the user pressing the browser's 'back' button.
75    */

76   public static native void back() /*-{
77     $wnd.history.back();
78   }-*/
;
79
80   /**
81    * Programmatic equivalent to the user pressing the browser's 'forward'
82    * button.
83    */

84   public static native void forward() /*-{
85     $wnd.history.forward();
86   }-*/
;
87
88   /**
89    * Gets the current history token. The listener will not receive an
90    * onHistoryChanged() event for the initial token; requiring that an
91    * application request the token explicitly on startup gives it an opportunity
92    * to run different initialization code in the presence or absence of an
93    * initial token.
94    *
95    * @return the initial token, or the empty string if none is present.
96    */

97   public static String JavaDoc getToken() {
98     return impl != null ? impl.getToken() : "";
99   }
100
101   /**
102    * Adds a new browser history entry. In hosted mode, the 'back' and 'forward'
103    * actions are accessible via the standard Alt-Left and Alt-Right keystrokes.
104    * Calling this method will cause {@link #onHistoryChanged} to be called as
105    * well.
106    *
107    * @param historyToken the token to associate with the new history item
108    */

109   public static void newItem(String JavaDoc historyToken) {
110     if (impl != null) {
111       impl.newItem(historyToken);
112     }
113   }
114
115   public static void onHistoryChanged(String JavaDoc historyToken) {
116     UncaughtExceptionHandler handler = GWT.getUncaughtExceptionHandler();
117     if (handler != null) {
118       fireHistoryChangedAndCatch(historyToken, handler);
119     } else {
120       fireHistoryChangedImpl(historyToken);
121     }
122   }
123
124   /**
125    * Removes a history listener.
126    *
127    * @param listener the listener to be removed
128    */

129   public static void removeHistoryListener(HistoryListener listener) {
130     historyListeners.remove(listener);
131   }
132
133   private static void fireHistoryChangedAndCatch(String JavaDoc historyToken,
134       UncaughtExceptionHandler handler) {
135     try {
136       fireHistoryChangedImpl(historyToken);
137     } catch (Throwable JavaDoc e) {
138       handler.onUncaughtException(e);
139     }
140   }
141
142   private static void fireHistoryChangedImpl(String JavaDoc historyToken) {
143     for (Iterator JavaDoc it = historyListeners.iterator(); it.hasNext();) {
144       HistoryListener listener = (HistoryListener) it.next();
145       listener.onHistoryChanged(historyToken);
146     }
147   }
148 }
149
Popular Tags