The answer to the following question shows this is possible:
Trying to get UIBinder to give me a span not a div
If you declare <g:HTMLPanel tag="span"> in the template, then the HTMLPanel will be a <span> element in the final result, instead of the default <div>.
The HTMLPanel has this constructor:
public HTMLPanel(String tag, String html)
which is probably called by this method, but how? If there is no tag attribute in the template, then the constructor used is probably this one:
public HTMLPanel(String html)
I understand that it is possible to annotate a Constructor with @UiConstructor to create a widget with parameters defined in the template, but how is it possible to change constructors depending on which attributes are defined?
And also, how is the String html filled automatically? Would there be some implicit definition of an html attribute as the content of the element? Or is this a nonstandard behavior of UIBinder just for HTMLPanel?
HTMLPanel has a dedicated HTMLPanelParser that processes the element from the ui.xml.
Element parsers are an internal part of UiBinder, you cannot add your own.
You have to declare a single @UiConstructor constructor and have the rest taken care of by setters, with some final validation possibly done in onAttach (similar to how Composite throws at attach-time when you forgot to call initWidget, and similarly for Widget and setElement).
In complex cases, and/or if you want to enforce the use of constructor arguments, then don't do anything special and have users of the widget use a @UiFactory or @UiField(provided = true). This is already the case for SuggestBox, ValueListBox or CellList for instance.
My personal preference goes to that last approach.