Adds an AttachEvent handler.

@param handler the handler @return the handler registration

HandlerRegistration addAttachHandler(AttachEventHandler handler) {
 return addHandler(handler, AttachEvent.TYPE);
}

For <a href= "http://code.google.com/p/google-web-toolkit/wiki/UnderstandingMemoryLeaks"

browsers which do not leak</a>, adds a native event handler to the widget.

Note that, unlike the {@link #addDomHandler(EventHandler, com.google.gwt.event.dom.client.DomEvent.Type)} implementation, there is no need to attach the widget to the DOM in order to cause the event handlers to be attached.

@param <H> the type of handler to add @param type the event key @param handler the handler @return {@link HandlerRegistration} used to remove the handler

HandlerRegistration addBitlessDomHandler(EventHandler handler, DomEventType type) {
 assert (handler != null);; // : "handler must not be null";
 assert (type != null); // : "type must not be null";
 sinkBitlessEvent(type.eventName);
 return ensureHandlers().addHandler(type, handler);
}

Adds a native event handler to the widget and sinks the corresponding native event. If you do not want to sink the native event, use the generic addHandler method instead.

@param <H> the type of handler to add @param type the event key @param handler the handler @return {@link HandlerRegistration} used to remove the handler

HandlerRegistration addDomHandler(EventHandler handler, DomEventType type) {
 assert (handler != null); // : "handler must not be null";
 assert (type != null); // : "type must not be null";
 int typeInt = IEvent.getTypeInt(type.eventName);
 if (typeInt == -1) {
   sinkBitlessEvent(type.eventName);
 } else {
   sinkEvents(typeInt);
 }
 return ensureHandlers().addHandler(type, handler);
}

Adds this handler to the widget.

@param <H> the type of handler to add @param type the event type @param handler the handler @return {@link HandlerRegistration} used to remove the handler

HandlerRegistration addHandler(EventHandler handler, EventType<EventHandler> type) {
 return ensureHandlers().addHandler(type, handler);
}

Adds a dependent style name by specifying the style name's suffix. The actual form of the style name that is added is:

getStylePrimaryName() + '-' + styleSuffix

@param styleSuffix the suffix of the dependent style to be added. @see #setStylePrimaryName(String) @see #removeStyleDependentName(String) @see #setStyleDependentName(String, boolean) @see #addStyleName(String)

void addStyleDependentName(String styleSuffix) {
 setStyleDependentName(styleSuffix, true);
}

Adds a secondary or dependent style name to this object. A secondary style name is an additional style name that is, in HTML/CSS terms, included as a space-separated token in the value of the CSS <code>class</code> attribute for this object's root element.

The most important use for this method is to add a special kind of secondary style name called a dependent style name. To add a dependent style name, use {@link #addStyleDependentName(String)}, which will prefix the 'style' argument with the result of {@link #k()} (followed by a '-'). For example, suppose the primary style name is gwt-TextBox. If the following method is called as obj.setReadOnly(true):

public void setReadOnly(boolean readOnly) {
  isReadOnlyMode = readOnly;
  // Create a dependent style name.
  String readOnlyStyle = "readonly";
  if (readOnly) {
addStyleDependentName(readOnlyStyle);

  } else {
removeStyleDependentName(readOnlyStyle);

  }
}</pre>

then both of the CSS style rules below will be applied:
// This rule is based on the primary style name and is always active.
.gwt-TextBox {
  font-size: 12pt;
}
// This rule is based on a dependent style name that is only active
// when the widget has called addStyleName(getStylePrimaryName() +
// "-readonly").
.gwt-TextBox-readonly {
  background-color: lightgrey;
  border: none;
}</pre>

The code can also be simplified with
{@link #setStyleDependentName(String, boolean)}:
public void setReadOnly(boolean readOnly) {
  isReadOnlyMode = readOnly;
  setStyleDependentName("readonly", readOnly);
}

Dependent style names are powerful because they are automatically updated
whenever the primary style name changes. Continuing with the example above,
if the primary style name changed due to the following call:
setStylePrimaryName("my-TextThingy");

then the object would be re-associated with following style rules, removing
those that were shown above.
.my-TextThingy {
  font-size: 20pt;
}
.my-TextThingy-readonly {
  background-color: red;
  border: 2px solid yellow;
}</pre>

Secondary style names that are not dependent style names are not
automatically updated when the primary style name changes.

@param style the secondary style name to be added
@see UIObject
@see #removeStyleName(String)
void addStyleName(String style) {
 setStyleName(style, true);
}

Returns the Widget aspect of the receiver.

Widget asWidget() {
 return this;
}

Clears all of the object's style names and sets it to the given style. You should normally use {@link #setStylePrimaryName(String)} unless you wish to explicitly remove all existing styles.

@param style the new style name @see #setStylePrimaryName(String)

void clearAndSetStyleName(String style) {
 setElementStyleName(getStyleElement(), style);
}

Creates the SimpleEventBus used by this Widget. You can override this method to create a custom EventBus.

@return the EventBus you want to use.

EventBus createEventBus() {
 return new SimpleEventBus();
}

Fires an event on a child widget. Used to delegate the handling of an event from one widget to another.

@param event the event @param target fire the event on the given target

void delegateEvent(Widget target, DwtEvent event) {
 target.fireEvent(event);
}

If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call {@link #onAttach()} for each of its child widgets.

@see #onAttach()

void doAttachChildren() {
}

If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call {@link #onDetach()} for each of its child widgets.

@see #onDetach()

void doDetachChildren() {
}

Ensures the existence of the event bus.

@return the EventBus.

EventBus ensureHandlers() {
 return _eventBus == null ? _eventBus = createEventBus() : _eventBus;
}

Intended to be used to pull the value out of a CSS length. If the value is "auto" or "inherit", 0 will be returned.

@param s The CSS length string to extract @return The leading numeric portion of <code>s</code>, or 0 if "auto" or

    "inherit" are passed in.

double extractLengthValue(String s) {
 if (s == "auto" || s == "inherit" || s == "") {
   return 0.0;
 } else {
   // numberRegex divides the string into a leading numeric portion
   // followed by an arbitrary portion.
   if(numberRegex.hasMatch(s)) {
     // Extract the leading numeric portion of string
     s = numberRegex.firstMatch(s)[0];
   }
   return double.parse(s);
 }
}

Fires the given event to the handlers listening to the event's type.

Any exceptions thrown by handlers will be bundled into a UmbrellaException and then re-thrown after all handlers have completed. An exception thrown by a handler will not prevent other handlers from executing.

@param event the event

void fireEvent(DwtEvent event) {
//    if (_eventBus != null) {
//      _eventBus.fireEvent(event);
//    }
 if (_eventBus != null) {
   // If it not live we should revive it.
   if (!event.isLive()) {
     event.revive();
   }
   Object oldSource = event.getSource();
   event.overrideSource(getElement());
   try {

     // May throw an UmbrellaException.
     _eventBus.fireEventFromSource(event, getElement());
   } on UmbrellaException catch (e) {
     throw new UmbrellaException(e.causes);
   } finally {
     if (oldSource == null) {
       // This was my event, so I should kill it now that I'm done.
       event.kill();
     } else {
       // Restoring the source for the next handler to use.
       event.overrideSource(oldSource);
     }
   }
 }
}

Gets the object's absolute left position in pixels, as measured from the browser window's client area.

@return the object's absolute left position

int getAbsoluteLeft() {
 return Dom.getAbsoluteLeft(getElement());
}

Gets the object's absolute top position in pixels, as measured from the browser window's client area.

@return the object's absolute top position

int getAbsoluteTop() {
 return Dom.getAbsoluteTop(getElement());
}

Gets this object's browser element.

dart_html.Element getElement() {
 assert (_element != null); // : MISSING_ELEMENT_ERROR;
 return _element;
}

Return EventBus.

EventBus getEventBus() {
 return _eventBus;
}

Gets the panel-defined layout data associated with this widget.

@return the widget's layout data @see #setLayoutData

Object getLayoutData() {
 return _layoutData;
}

Gets the object's offset height in pixels. This is the total height of the object, including decorations such as border and padding, but not margin.

@return the object's offset height

int getOffsetHeight() {
 return getElement().offset.height; // Dom.getElementPropertyInt(getElement(), "offsetHeight");
}

Gets the object's offset width in pixels. This is the total width of the object, including decorations such as border and padding, but not margin.

@return the object's offset width

int getOffsetWidth() {
 return getElement().offset.width; // Dom.getElementPropertyInt(getElement(), "offsetWidth");
}

Gets this widget's parent panel.

@return the widget's parent panel

Widget getParent() {
 return _parent;
}

Template method that returns the element to which style names will be applied. By default it returns the root element, but this method may be overridden to apply styles to a child element.

@return the element to which style names will be applied

dart_html.Element getStyleElement() {
 return getElement();
}

Gets all of the object's style names, as a space-separated list. If you wish to retrieve only the primary style name, call {@link #getStylePrimaryName()}.

@return the objects's space-separated style names @see #getStylePrimaryName()

String getStyleName() {
 return getElementStyleName(getStyleElement());
}

Gets the primary style name associated with the object.

@return the object's primary style name @see #setStyleName(String) @see #addStyleName(String) @see #removeStyleName(String)

String getStylePrimaryName() {
 return getElementStylePrimaryName(getStyleElement());
}

Provides subclasses access to the topmost widget that defines this composite.

@return the widget

Widget getWidget() {
 return _widget;
}

Sets the widget to be wrapped by the composite. The wrapped widget must be set before calling any {@link Widget} methods on this object, or adding it to a panel. This method may only be called once for a given composite.

@param widget the widget to be wrapped

void initWidget(Widget widget) {
 // Validate. Make sure the widget is not being set twice.
 if (this._widget != null) {
   throw new Exception("Composite.initWidget() may only be called once.");
 }

 if (widget is IsRenderable) {
   // In case the Widget being wrapped is an IsRenderable, we save that fact.
   this._renderable = widget as IsRenderable;
 }

 // Detach the new child.
 widget.removeFromParent();

 // Use the contained widget's element as the composite's element,
 // effectively merging them within the DOM.
 dart_html.Element elem = widget.getElement();
 setElement(elem);

//    if (PotentialElement.isPotential(elem)) {
//      PotentialElement.as(elem).setResolver(this);
//    }

 // Logical attach.
 this._widget = widget;

 // Adopt.
 widget.setParent(this);
}

Returns whether or not the receiver is attached to the {@link com.google.gwt.dom.client.Document Document}'s {@link com.google.gwt.dom.client.BodyElement BodyElement}.

@return true if attached, false otherwise

bool isAttached() {
 if (_widget != null) {
   return _widget.isAttached();
 }
 return false;
}

Has this widget ever been attached?

@return true if this widget ever been attached to the DOM, false otherwise

bool isOrWasAttached() {
 return eventsToSink == -1;
}

This method is called when a widget is attached to the browser's document. To receive notification after a Widget has been added to the document, override the {@link #onLoad} method or use {@link #addAttachHandler}.

It is strongly recommended that you override {@link #onLoad()} or {@link #doAttachChildren()} instead of this method to avoid inconsistencies between logical and physical attachment states.

Subclasses that override this method must call super.onAttach() to ensure that the Widget has been attached to its underlying Element.

@throws IllegalStateException if this widget is already attached @see #onLoad() @see #doAttachChildren()

void onAttach() {
 if (!isOrWasAttached()) {
   _widget.sinkEvents(eventsToSink);
   eventsToSink = -1;
 }

 _widget.onAttach();

 // Clobber the widget's call to setEventListener(), causing all events to
 // be routed to this composite, which will delegate back to the widget by
 // default (note: it's not necessary to clear this in onDetach(), because
 // the widget's onDetach will do so).
 Dom.setEventListener(getElement(), this);

 // Call onLoad() directly, because we're not calling super.onAttach().
 onLoad();
 AttachEvent.fire(this, true);
}

Fired whenever a browser event is received.

@param event the event received

TODO

void onBrowserEvent(dart_html.Event event) {
 // Fire any handler added to the composite itself.
 super.onBrowserEvent(event);

 // Delegate events to the widget.
 _widget.onBrowserEvent(event);
}

This method is called when a widget is detached from the browser's document. To receive notification before a Widget is removed from the document, override the {@link #onUnload} method or use {@link #addAttachHandler}.

It is strongly recommended that you override {@link #onUnload()} or {@link #doDetachChildren()} instead of this method to avoid inconsistencies between logical and physical attachment states.

Subclasses that override this method must call super.onDetach() to ensure that the Widget has been detached from the underlying Element. Failure to do so will result in application memory leaks due to circular references between DOM Elements and JavaScript objects.

@throws IllegalStateException if this widget is already detached @see #onUnload() @see #doDetachChildren()

void onDetach() {
 try {
   onUnload();
   AttachEvent.fire(this, false);
 } finally {
   // We don't want an exception in user code to keep us from calling the
   // super implementation (or event listeners won't get cleaned up and
   // the attached flag will be wrong).
   _widget.onDetach();
 }
}

This method is called immediately after a widget becomes attached to the browser's document.

void onLoad() {
}

This method is called immediately before a widget will be detached from the browser's document.

void onUnload() {
}

Removes this widget from its parent widget, if one exists.

If it has no parent, this method does nothing. If it is a "root" widget (meaning it's been added to the detach list via {@link RootPanel#detachOnWindowClose(Widget)}), it will be removed from the detached immediately. This makes it possible for Composites and Panels to adopt root widgets.

@throws IllegalStateException if this widget's parent does not support

      removal (e.g. {@link Composite})

void removeFromParent() {
 if (_parent == null) {
   // If the widget had no parent, check to see if it was in the detach list
   // and remove it if necessary.
   if (RootPanel.isInDetachList(this)) {
     RootPanel.detachNow(this);
   }
 } else if (_parent is HasWidgets) {
   (_parent as HasWidgets).remove(this);
 } else if (_parent != null) {
   throw new Exception("This widget's parent does not implement HasWidgets");
 }
}

Removes a dependent style name by specifying the style name's suffix.

@param styleSuffix the suffix of the dependent style to be removed @see #setStylePrimaryName(Element, String) @see #addStyleDependentName(String) @see #setStyleDependentName(String, boolean)

void removeStyleDependentName(String styleSuffix) {
 setStyleDependentName(styleSuffix, false);
}

Removes a style name. This method is typically used to remove secondary style names, but it can be used to remove primary stylenames as well. That use is not recommended.

@param style the secondary style name to be removed @see #addStyleName(String) @see #setStyleName(String, boolean)

void removeStyleName(String style) {
 setStyleName(style, false);
}

Replaces this object's browser element.

This method exists only to support a specific use-case in Image, and should not be used by other classes.

@param elem the object's new element

void replaceElement(dart_html.Element elem) {
 if (isAttached()) {
   // Remove old event listener to avoid leaking. onDetach will not do this
   // for us, because it is only called when the widget itself is detached
   // from the document.
   Dom.setEventListener(getElement(), null);
 }

 super.replaceElement(elem);

 if (isAttached()) {
   // Hook the event listener back up on the new element. onAttach will not
   // do this for us, because it is only called when the widget itself is
   // attached to the document.
   Dom.setEventListener(getElement(), this);
 }
}

Sets this object's browser element. UIObject subclasses must call this method before attempting to call any other methods, and it may only be called once.

@param elem the object's element

void setElement(dart_html.Element elem) {
 assert (_element == null);
 this._element = elem;
}

Sets the object's height. This height does not include decorations such as border, margin, and padding.

@param height the object's new height, in CSS units (e.g. "10px", "1em")

void setHeight(String height) {
 // This exists to deal with an inconsistency in IE's implementation where
 // it won't accept negative numbers in length measurements
 assert (extractLengthValue(height.trim().toLowerCase()) >= 0); // : "CSS heights should not be negative";
 Dom.setStyleAttribute(getElement(), "height", height);
}

Sets the panel-defined layout data associated with this widget. Only the panel that currently contains a widget should ever set this value. It serves as a place to store layout bookkeeping data associated with a widget.

@param layoutData the widget's layout data

void setLayoutData(Object value) {
 this._layoutData = value;
}

Sets this widget's parent. This method should only be called by {@link Panel} and {@link Composite}.

@param parent the widget's new parent @throws IllegalStateException if <code>parent</code> is non-null and the

      widget already has a parent

void setParent(Widget parent) {
 Widget oldParent = this._parent;
 if (parent == null) {
   try {
     if (oldParent != null && oldParent.isAttached()) {
       onDetach();
       assert (!isAttached()); // : "Failure of " + this.getClass().getName() + " to call super.onDetach()";
     }
   } finally {
     // Put this in a finally in case onDetach throws an exception.
     this._parent = null;
   }
 } else {
   if (oldParent != null) {
     throw new Exception("Cannot set a new parent without first clearing the old parent");
   }
   this._parent = parent;
   if (parent.isAttached()) {
     onAttach();
     assert (isAttached()); // : "Failure of " + this.getClass().getName() + " to call super.onAttach()";
   }
 }
}

Sets the object's size, in pixels, not including decorations such as border, margin, and padding.

@param width the object's new width, in pixels @param height the object's new height, in pixels

void setPixelSize(int width, int height) {
 if (width >= 0) {
   setWidth(width.toString() + "px");
 }
 if (height >= 0) {
   setHeight(height.toString() + "px");
 }
}

Sets the object's size. This size does not include decorations such as border, margin, and padding.

@param width the object's new width, in CSS units (e.g. "10px", "1em") @param height the object's new height, in CSS units (e.g. "10px", "1em")

void setSize(String width, String height) {
 setWidth(width);
 setHeight(height);
}

Adds or removes a dependent style name by specifying the style name's suffix. The actual form of the style name that is added is:

getStylePrimaryName() + '-' + styleSuffix

@param styleSuffix the suffix of the dependent style to be added or removed @param add <code>true</code> to add the given style, <code>false</code> to

     remove it

@see #setStylePrimaryName(Element, String) @see #addStyleDependentName(String) @see #setStyleName(String, boolean) @see #removeStyleDependentName(String)

void setStyleDependentName(String styleSuffix, bool add) {
 setStyleName(getStylePrimaryName() + '-' + styleSuffix, add);
}

Adds or removes a style name. This method is typically used to remove secondary style names, but it can be used to remove primary stylenames as well. That use is not recommended.

@param style the style name to be added or removed @param add <code>true</code> to add the given style, <code>false</code> to

     remove it

@see #addStyleName(String) @see #removeStyleName(String)

void setStyleName(String style, bool add) {
 manageElementStyleName(getStyleElement(), style, add);
}

Sets the object's primary style name and updates all dependent style names.

@param style the new primary style name @see #addStyleName(String) @see #removeStyleName(String)

void setStylePrimaryName(String style) {
 setElementStylePrimaryName(getStyleElement(), style);
}

Sets the object's width. This width does not include decorations such as border, margin, and padding.

@param width the object's new width, in CSS units (e.g. "10px", "1em")

void setWidth(String width) {
 // This exists to deal with an inconsistency in IE's implementation where
 // it won't accept negative numbers in length measurements
 assert (extractLengthValue(width.trim().toLowerCase()) >= 0); // : "CSS widths should not be negative";
 Dom.setStyleAttribute(getElement(), "width", width);
}

Sinks a named event. Note that only {@link Widget widgets} may actually receive events, but can receive events from all objects contained within them.

@param eventTypeName name of the event to sink on this element @see com.google.gwt.user.client.Event

void sinkBitlessEvent(String eventTypeName) {
 Dom.sinkBitlessEvent(getElement(), eventTypeName);
}

Overridden to defer the call to super.sinkEvents until the first time this widget is attached to the dom, as a performance enhancement. Subclasses wishing to customize sinkEvents can preserve this deferred sink behavior by putting their implementation behind a check of <code>isOrWasAttached()</code>:

{@literal @}Override
public void sinkEvents(int eventBitsToAdd) {
  if (isOrWasAttached()) {
    /{@literal *} customized sink code goes here {@literal *}/
  } else {
    super.sinkEvents(eventBitsToAdd);
 }
} 

void sinkEvents(int eventBitsToAdd) {
 if (isOrWasAttached()) {
   super.sinkEvents(eventsToSink);
 } else {
   eventsToSink |= eventBitsToAdd;
 }
}

This method is overridden so that any object can be viewed in the debugger as an HTML snippet.

@return a string representation of the object

String toString() {
 if (_element == null) {
   return "(null handle)";
 }
 return getElement().toString();
}

Removes a set of events from this object's event list.

@param eventBitsToRemove a bitfield representing the set of events to be

     removed from this element's event set

@see #sinkEvents @see com.google.gwt.user.client.Event

void unsinkEvents(int eventBitsToRemove) {
 Dom.sinkEvents(getElement(), Dom.getEventsSunk(getElement()) & (~eventBitsToRemove));
}