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);
}

void addIsWidget(IsWidget child) {
 this.add(Widget.asWidgetOrNull(child));
}

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);
}

Adds a new child widget to the panel, attaching its Element to the specified container Element.

@param child the child widget to be added @param container the element within which the child will be contained

void addWidget(Widget child, dart_html.Element container) {
 // Detach new child.
 child.removeFromParent();

 // Logical attach.
 getChildren().add(child);

 // Physical attach.
 //Dom.appendChild(container, child.getElement());
 container.append(child.getElement());

 // Adopt.
 adopt(child);
}

Adjusts beforeIndex to account for the possibility that the given widget is already a child of this panel.

@param child the widget that might be an existing child @param beforeIndex the index at which it will be added to this panel @return the modified index

int adjustIndex(Widget child, int beforeIndex) {
 checkIndexBoundsForInsertion(beforeIndex);

 // Check to see if this widget is already a direct child.
 if (child.getParent() == this) {
   // If the Widget's previous position was left of the desired new position
   // shift the desired position left to reflect the removal
   int idx = getWidgetIndex(child);
   if (idx < beforeIndex) {
     beforeIndex--;
   }
 }

 return beforeIndex;
}

Finalize the attachment of a Widget to this Panel. This method is the <b>last</b> step in adding or inserting a Widget into a Panel, and should be called after physical attachment in the DOM is complete. This Panel becomes the parent of the child Widget, and the child will now fire its {@link Widget#onAttach()} event if this Panel is currently attached.

@param child the widget to be adopted @see #add(Widget)

void adopt(Widget child) {
 assert (child.getParent() == null);
 child.setParent(this);
}

Returns the Widget aspect of the receiver.

Widget asWidget() {
 return this;
}

Checks that <code>index</code> is in the range [0, getWidgetCount()), which is the valid range on accessible indexes.

@param index the index being accessed

void checkIndexBoundsForAccess(int index) {
 if (index < 0 || index >= getWidgetCount()) {
   throw new Exception("Index Out Of Bounds Exception");
 }
}

Checks that <code>index</code> is in the range 0, getWidgetCount(), which is the valid range for indexes on an insertion.

@param index the index where insertion will occur

void checkIndexBoundsForInsertion(int index) {
 if (index < 0 || index > getWidgetCount()) {
   throw new Exception("Index Out Of Bounds Exception");
 }
}

Removes all child widgets.

void clear() {
 Iterator<Widget> it = iterator();
 while (it.moveNext()) {
   it.current.removeFromParent();
 }
}

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);
}

void doAttachChildren() {
 AttachDetachException.tryCommand(this.iterator(), AttachDetachException.attachCommand);
}

void doDetachChildren() {
 AttachDetachException.tryCommand(this.iterator(), AttachDetachException.detachCommand);
}

void doLogicalClear() {
 // TODO(jgw): When Layout work has landed, deprecate FlowPanel (the only
 // caller of this method in our code), and deprecate this method with an eye
 // to making it private down the road.

 // Only use one orphan command per panel to avoid object creation.
 if (_orphanCommand == null) {
   _orphanCommand = new OrpahExceptionCommand(this);
 }
 try {
   AttachDetachException.tryCommand(this.iterator(), _orphanCommand);
 } finally {
   _children = new WidgetCollection(this);
 }
}

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 the list of children contained in this panel.

@return a collection of child widgets

WidgetCollection getChildren() {
 return _children;
}

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());
}

Gets the child widget at the specified index.

@param index the child widget's index @return the child widget

Widget getWidgetAt(int index) {
 return getChildren().get(index);
}

Gets the number of child widgets in this panel.

@return the number of children

int getWidgetCount() {
 return getChildren().size();
}

Gets the index of the specified child widget.

@param child the widget to be found @return the widget's index, or <code>-1</code> if it is not a child of this

    panel

int getWidgetIndex(Widget child) {
 return getChildren().indexOf(child);
}

int getWidgetIndexIsWidget(IsWidget child) {
 return getWidgetIndex(Widget.asWidgetOrNull(child));
}

Insert a new child Widget into this Panel at a specified index, attaching its Element to the specified container Element. The child Element will either be attached to the container at the same index, or simply appended to the container, depending on the value of <code>domInsert</code>.

@param child the child Widget to be added @param container the Element within which <code>child</code> will be

     contained

@param beforeIndex the index before which <code>child</code> will be

     inserted

@param domInsert if <code>true</code>, insert <code>child</code> into

     <code>container</code> at <code>beforeIndex</code>; otherwise
     append <code>child</code> to the end of <code>container</code>.

void insert(Widget child, dart_html.Element container, int beforeIndex,
   bool domInsert) {

 if (container == null) {
   throw new Exception("container may not be null");
 }

 // Validate index; adjust if the widget is already a child of this panel.
 beforeIndex = adjustIndex(child, beforeIndex);

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

 // Logical attach.
 getChildren().insert(child, beforeIndex);

 // Physical attach.
 if (domInsert) {
   //DOM.insertChild(container, child.getElement(), beforeIndex);
   Dom.insertChild(container, child.getElement(), beforeIndex);
//      dart_html.Element refChild = container.nodes[beforeIndex];
//      if (refChild != null) {
//        container.insertBefore(child.getElement(), refChild);
//      } else {
//        container.append(child.getElement());
//      }
 } else {
   //DOM.appendChild(container, child.getElement());
   container.append(child.getElement());
 }

 // Adopt.
 adopt(child);
}

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() {
 return _attached;
}

Has this widget ever been attached?

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

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

Iterator<Widget> iterator() {
 return getChildren().iterator;
}

Fired whenever a browser event is received.

@param event the event received

TODO

void onBrowserEvent(dart_html.Event event) {
 switch (Dom.eventGetType(event)) {
   case IEvent.ONMOUSEOVER:
     // Only fire the mouse over event if it's coming from outside this
     // widget.
   case IEvent.ONMOUSEOUT:
     // Only fire the mouse over event if it's coming from outside this widget.
     // Only fire the mouse out event if it's leaving this widget.
     dart_html.Element related = (event as dart_html.MouseEvent).relatedTarget as dart_html.Element;
     if (related != null && Dom.isOrHasChild(getElement(), related)) {
       return;
     }
     break;
 }

 DomEvent.fireNativeEvent(event, this, this.getElement());
}

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() {
}

This method must be called as part of the remove method of any Panel. It ensures that the Widget's parent is cleared. This method should be called after verifying that the child Widget is an existing child of the Panel, but before physically removing the child Widget from the DOM. The child will now fire its {@link Widget#onDetach()} event if this Panel is currently attached.

Calls to {@link #orphan(Widget)} should be wrapped in a try/finally block to ensure that the widget is physically detached even if orphan throws an exception.

@param child the widget to be disowned @see #add(Widget)

void orphan(Widget child) {
 assert (child.getParent() == this);
 child.setParent(null);
}

Removes the widget at the specified index.

@param index the index of the widget to be removed @return <code>false</code> if the widget is not present

bool removeAt(int index) {
 return remove(getWidgetAt(index));
}

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");
 }
}

bool removeIsWidget(IsWidget child) {
 return remove(Widget.asWidgetOrNull(child));
}

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));
}