votorola.g.web.gwt

Class HistoryX

java.lang.Object

com.google.gwt.user.client.History

HistoryX

public final class HistoryX
extends History

An extended implementation of the URL history stacker with support for switches. Typical usage is by one of these two equivalent methods, each of which alters the fragment and therefore stacks a new URL in the browser history:

• history.setSwitchValue( "NAME", "VALUE" )
• switch.Switch.set(String)( "VALUE" )

Note: with Internet Explorer, manual modification of the history token from within the address bar goes unrecorded in the stack (IE 8). As a result, a subsequent press of the back button takes you farther back than expected.

See Also:

Coding basics, Making AJAX applications crawlable

Constructor Summary

Constructors

Constructor and Description
HistoryX(boolean _isFragmentShared, EventBus _bus) Constructs a permanent instance of HistoryX.

Method Summary

Methods

Modifier and Type	Method and Description
HandlerRegistration	addHandler(ValueChangeHandler<String> handler) Registers a handler to receive change events fired from this history stack.
HandlerRegistration	addPreviewHandler(ValueChangeHandler<String> handler) Registers a handler to receive change events fired from the preview source.
static HandlerRegistration	addValueChangeHandler(ValueChangeHandler<String> handler) Throws UnsupportedOperationException.
EventBus	bus() The bus through which events are fired.
String	clearSwitchValue(String name) Removes the switch from the history token and returns its value.
String	getSwitchValue(String name) Returns the value of a switch, or null if the switch has no value.
boolean	isFragmentShared() Answers whether the URL fragment of the browser window may be used for purposes other than storing the history token.
Object	previewSource() The source of all preview events.
void	replace() Schedules the construction of a new token to replace the current item in the browser's history stack, as opposed to adding a new one.
String	setSwitchValue(String name, String value) Sets the value of a switch and returns the old value.
Map<String,String>	switchMap() The map of switches in the current history token, indexed by switch name.

Methods inherited from class com.google.gwt.user.client.History

addHistoryListener, back, encodeHistoryToken, fireCurrentHistoryState, forward, getToken, newItem, newItem, onHistoryChanged, removeHistoryListener, replaceItem, replaceItem

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HistoryX

public HistoryX(boolean _isFragmentShared,
        EventBus _bus)

Constructs a permanent instance of HistoryX. Do not create and discard these on the fly; at present, they do not clean up after themselves.

See Also:

isFragmentShared(), bus()

Method Detail

addHandler

public HandlerRegistration addHandler(ValueChangeHandler<String> handler)

Registers a handler to receive change events fired from this history stack. The event dispatch for switch changes proceeds as follows:

1. A switch value is changed via setSwitchValue or clearSwitchValue.
2. A property change event with the name "switch-NAME" is immediately fired. [NOT YET IMPLIMENTED]
3. In the "finally" phase of the event dispatch loop, all switch values are compiled into a new token. If the new token differs from the old then it is added to this history stack as a new item, resulting in a new URL fragment on the document and a token change as described below.

And for token changes:

1. The document's URL fragment is changed either programatically, for example via newItem(token) or Window.Location, or manually via the address bar.
2. A change event is created and fired from the preview source.
3. The same change event is fired from this history stack. Handlers may retrieve switch values (which may or may not have changed) via getSwitchValue.

addPreviewHandler

public HandlerRegistration addPreviewHandler(ValueChangeHandler<String> handler)

Registers a handler to receive change events fired from the preview source.

See Also:

addHandler(ValueChangeHandler)

previewSource

public Object previewSource()

The source of all preview events.

See Also:

addPreviewHandler(ValueChangeHandler)

bus

public EventBus bus()

The bus through which events are fired.

getSwitchValue

public String getSwitchValue(String name)

Returns the value of a switch, or null if the switch has no value.

See Also:

Switch.get()

clearSwitchValue

public String clearSwitchValue(String name)

Removes the switch from the history token and returns its value.

See Also:

Switch.clear()

setSwitchValue

public String setSwitchValue(String name,
                    String value)

Sets the value of a switch and returns the old value. Setting an empty value has the same effect as clearing the switch.

See Also:

Switch.set(String)

isFragmentShared

public boolean isFragmentShared()

Answers whether the URL fragment of the browser window may be used for purposes other than storing the history token. For example, if the GWT application is embedded in a page that provides internal link targets (id attributes), then set this true in the constructor in order to suppress malformed switch alerts.

Returns:

true if the fragment is shared, false if it is used exclusively for the history token.

See Also:

votorola/a/web/gwt/gwt.js

replace

public void replace()

Schedules the construction of a new token to replace the current item in the browser's history stack, as opposed to adding a new one. The replacement will occur in the "finally" phase of the event dispatch loop, based on the switch values at that time, and a change event will then be fired. "All GWT state will be lost", as in a reload.

See Also:

Window.Location.replace(String)

switchMap

public Map<String,String> switchMap()

The map of switches in the current history token, indexed by switch name.

addValueChangeHandler

public static HandlerRegistration addValueChangeHandler(ValueChangeHandler<String> handler)

Throws UnsupportedOperationException.