Wt::WWebWidget Class Reference

A base class for widgets with an HTML counterpart. More...

#include <Wt/WWebWidget>

Inheritance diagram for Wt::WWebWidget:

Inheritance graph
[legend]

List of all members.

Public Member Functions

 WWebWidget (WContainerWidget *parent=0)
 Construct a WebWidget with a given parent.
virtual void setPositionScheme (PositionScheme scheme)
 Sets the widget position scheme.
virtual PositionScheme positionScheme () const
 Returns the widget position scheme.
virtual void setOffsets (const WLength &offset, WFlags< Side > sides=All)
 Applies offsets to a widget.
virtual WLength offset (Side s) const
 Retrieves the offset of the widget.
virtual void resize (const WLength &width, const WLength &height)
 Resizes the widget.
virtual WLength width () const
 Returns the widget width.
virtual WLength height () const
 Returns the widget height.
virtual void setMinimumSize (const WLength &width, const WLength &height)
 Sets a minimum size.
virtual WLength minimumWidth () const
 Returns the minimum width.
virtual WLength minimumHeight () const
 Returns the minimum height.
virtual void setMaximumSize (const WLength &width, const WLength &height)
 Sets a maximum size.
virtual WLength maximumWidth () const
 Returns the maximum width.
virtual WLength maximumHeight () const
 Returns the maximum height.
virtual void setLineHeight (const WLength &height)
 Sets the line height for contained text.
virtual WLength lineHeight () const
 Returns the line height for contained text.
virtual void setFloatSide (Side s)
 Specify a side to which the WWidget must float.
virtual Side floatSide () const
 Returns the float side.
virtual void setClearSides (WFlags< Side > sides)
 Sets the sides that should be cleared of floats.
virtual WFlags< SideclearSides () const
 Returns the sides that should remain empty.
virtual void setMargin (const WLength &margin, WFlags< Side > sides=All)
 Sets margins around the widget.
virtual WLength margin (Side side) const
 Returns the margin set for that side.
virtual void setHidden (bool)
 Sets whether the widget must be hidden.
virtual bool isHidden () const
 Returns whether this widget is set hidden.
virtual void setPopup (bool)
 Let the widget overlay other sibling widgets.
virtual bool isPopup () const
 Returns whether this widget is overlayed.
virtual void setInline (bool)
 Sets whether this widget is displayed inline or as a block.
virtual bool isInline () const
 Returns whether this widget is displayed inline or as block.
virtual WCssDecorationStyledecorationStyle ()
 Returns the decoration style of this widget.
virtual void setStyleClass (const WString &styleClass)
 Sets a style class.
virtual WString styleClass () const
 Returns the style class.
virtual void setVerticalAlignment (AlignmentFlag alignment, const WLength &length=WLength())
 Sets the vertical alignment of this (inline) widget.
virtual AlignmentFlag verticalAlignment () const
 Returns the vertical alignment.
virtual WLength verticalAlignmentLength () const
 Returns the fixed vertical alignment that was set.
virtual void setToolTip (const WString &toolTip)
 Sets a tooltip.
virtual WString toolTip () const
 Returns the tooltip text.
virtual void refresh ()
 Refresh the widget.
virtual void setAttributeValue (const std::string &name, const WString &value)
 Sets an attribute value.
virtual WString attributeValue (const std::string &name) const
 Returns an attribute value.
virtual void load ()
 Load content just before the widget's content is rendered.
virtual bool loaded () const
 Returns if this widget has been loaded.
virtual void setId (const std::string &id)
 Sets the CSS Id.
virtual void setSelectable (bool selectable)
 Sets as selectable.
virtual const std::string id () const
 Returns the (unique) identifier for this object.
void setLoadLaterWhenInvisible (bool)
 Change the way the widget is loaded when invisible.
const std::vector< WWidget * > & children () const
 Returns contained widgets.

Static Public Member Functions

static WString escapeText (const WString &text, bool newlinesToo=false)
 Escape HTML control characters in the text, to display literally.
static std::string & escapeText (std::string &text, bool newlinestoo=false)
 Escape HTML control characters in the text, to display literally.
static bool removeScript (WString &text)
 Remove tags/attributes from text that are not passive.
static std::string jsStringLiteral (const std::string &v, char delimiter= '\'')
 Turn a UTF8 encoded string into a JavaScript string literal.

Protected Member Functions

virtual void enableAjax ()
 Progress to an Ajax-enabled widget.


Detailed Description

A base class for widgets with an HTML counterpart.

All descendants of WWebWidget implement a widget which corresponds almost one-on-one with an HTML element. These widgets provide most capabilities of these HTML elements, but rarely make no attempt to do anything more.

See also:
WCompositeWidget

Constructor & Destructor Documentation

WWebWidget::WWebWidget ( WContainerWidget parent = 0  ) 

Construct a WebWidget with a given parent.

See also:
WWidget::WWidget


Member Function Documentation

void WWebWidget::setPositionScheme ( PositionScheme  scheme  )  [virtual]

Sets the widget position scheme.

Establishes how the widget must be layed-out relative to its siblings. The default position scheme is Static.

This applies to CSS-based layout.

See also:
Wt::PositionScheme, positionScheme()

Implements Wt::WWidget.

PositionScheme WWebWidget::positionScheme (  )  const [virtual]

Returns the widget position scheme.

This applies to CSS-based layout.

See also:
Wt::PositionScheme, setPositionScheme(PositionScheme)

Implements Wt::WWidget.

void WWebWidget::setOffsets ( const WLength offset,
WFlags< Side sides = All 
) [virtual]

Applies offsets to a widget.

The argument sides may be a logical concatenation of Left, Right, Top, and Bottom.

This applies only to widgets that have a position scheme that is Relative, Absolute, or Fixed, and has a slightly different meaning for these three cases.

For a relatively positioned widget, an offset applies relative to the position the widget would have when layed-out using a Static position scheme. The widget may be shifted to the left or right by specifying an offset to the Left or Right). The widget may be shifted vertically, by specifying an offset for the Top or Bottom.

For an absolutely positioned widget, an offset specifies a distance of the corresponding side of the widget with respect to the corresponding side of the reference parent widget. Thus, setting all offsets to 0 result in a widget that spans the entire reference widget. The reference parent widget is the first ancestor widget that is a table cell, or a widget with a relative, absolute or fixed position scheme.

For an fixed positioned widget, an offset specifies a distance of the corresponding side of the widget with respect to the browser window, regardless of scrolling. Thus, setting all offsets to 0 result in a widget that spans the entire browser window.

This applies to CSS-based layout.

See also:
offset(Side) const

Implements Wt::WWidget.

WLength WWebWidget::offset ( Side  side  )  const [virtual]

Retrieves the offset of the widget.

This applies to CSS-based layout.

See also:
setOffsets(const WLength&, WFlags<Side>)

Implements Wt::WWidget.

void WWebWidget::resize ( const WLength width,
const WLength height 
) [virtual]

Resizes the widget.

Specify a new size for this widget, by specifying width and height. By default a widget has automatic width and height, see WLength::isAuto().

This applies to CSS-based layout.

See also:
width(), height()

Implements Wt::WWidget.

Reimplemented in Wt::Ext::TextEdit, Wt::WFlashObject, Wt::WPaintedWidget, and Wt::WTextEdit.

WLength WWebWidget::width (  )  const [virtual]

Returns the widget width.

Returns the width set for this widget. This is not a calculated width, based on layout, but the width as specified with resize(const WLength&, const WLength&).

This applies to CSS-based layout.

See also:
resize(const WLength&, const WLength&), height()

Implements Wt::WWidget.

WLength WWebWidget::height (  )  const [virtual]

Returns the widget height.

Returns the height set for this widget. This is not a calculated height, based on layout, but the height as specified previously with resize(const WLength& width, const WLength& height).

This applies to CSS-based layout.

See also:
resize(const WLength&, const WLength&), width()

Implements Wt::WWidget.

void WWebWidget::setMinimumSize ( const WLength width,
const WLength height 
) [virtual]

Sets a minimum size.

Specify a minimum size for this widget. When the widget is managed using a layout manager, these sizes are also taken into account.

See also:
resize(), minimumWidth(), minimumHeight()

Implements Wt::WWidget.

WLength WWebWidget::minimumWidth (  )  const [virtual]

Returns the minimum width.

Returns the minimum width set for this widget with setMinimumSize().

See also:
setMinimumSize(), minimumHeight()

Implements Wt::WWidget.

WLength WWebWidget::minimumHeight (  )  const [virtual]

Returns the minimum height.

Returns the minmum height set for this widget with setMinimumSize().

See also:
setMinimumSize(), minimumWidth()

Implements Wt::WWidget.

void WWebWidget::setMaximumSize ( const WLength width,
const WLength height 
) [virtual]

Sets a maximum size.

Specify a minimum size for this widget.

See also:
resize(), maximumWidth(), maximumHeight()

Implements Wt::WWidget.

WLength WWebWidget::maximumWidth (  )  const [virtual]

Returns the maximum width.

Returns the maximum width set for this widget with setMaximumSize().

See also:
setMaximumSize(), maximumHeight()

Implements Wt::WWidget.

WLength WWebWidget::maximumHeight (  )  const [virtual]

Returns the maximum height.

Returns the minmum height set for this widget with setMaximumSize().

See also:
setMaximumSize(), maximumWidth()

Implements Wt::WWidget.

WLength WWebWidget::lineHeight (  )  const [virtual]

Returns the line height for contained text.

sa setLineHeight()

Implements Wt::WWidget.

void WWebWidget::setFloatSide ( Side  s  )  [virtual]

Specify a side to which the WWidget must float.

This only applies to widgets with a Static positionScheme().

It specifies if the widget must be positioned on one of the sides of the parent widget, at the current line. A typical use is to position images within text. Valid values for Side or

None

, Left or Right .

This applies to CSS-based layout.

Implements Wt::WWidget.

Side WWebWidget::floatSide (  )  const [virtual]

Returns the float side.

See also:
setFloatSide(Side)

Implements Wt::WWidget.

void WWebWidget::setClearSides ( WFlags< Side sides  )  [virtual]

Sets the sides that should be cleared of floats.

This pushes the widget down until it is not surrounded by floats at the sides (which may be a logical OR of Left and Right.

This applies to CSS-based layout.

See also:
setFloatSide()

Implements Wt::WWidget.

WFlags< Side > WWebWidget::clearSides (  )  const [virtual]

Returns the sides that should remain empty.

See also:
setClearSides(WFlags<Side>)

Implements Wt::WWidget.

void WWebWidget::setMargin ( const WLength margin,
WFlags< Side sides = All 
) [virtual]

Sets margins around the widget.

Setting margin has the effect of adding a distance between the widget and surrounding widgets. The default margin (with an automatic length) is zero.

Use any combination of Left , Right , Bottom , or Top .

This applies to CSS-based layout.

See also:
margin();

Implements Wt::WWidget.

WLength WWebWidget::margin ( Side  side  )  const [virtual]

Returns the margin set for that side.

This applies to CSS-based layout.

See also:
setMargin();

Implements Wt::WWidget.

void WWebWidget::setHidden ( bool  hidden  )  [virtual]

Sets whether the widget must be hidden.

Hide or show the widget (including all its descendant widgets). setHidden(false) will show this widget and all child widgets that are not hidden.

See also:
hide(), show()

Implements Wt::WWidget.

Reimplemented in Wt::Ext::Dialog, Wt::Ext::MessageBox, Wt::Ext::Widget, and Wt::WFormWidget.

bool WWebWidget::isHidden (  )  const [virtual]

Returns whether this widget is set hidden.

A widget that is not hidden may still be not visible when one of its ancestor widgets are hidden.

See also:
setHidden()

Implements Wt::WWidget.

void WWebWidget::setPopup ( bool  popup  )  [virtual]

Let the widget overlay other sibling widgets.

A widget that isPopup() will be rendered on top of any other sibling widget contained within the same parent (including other popup widgets previously added to the container).

This will only have an effect when the widgetis either Absolute or Fixed positionScheme().

This applies to CSS-based layout.

Implements Wt::WWidget.

bool WWebWidget::isPopup (  )  const [virtual]

Returns whether this widget is overlayed.

This applies to CSS-based layout.

See also:
setPopup(bool)

Implements Wt::WWidget.

void WWebWidget::setInline ( bool  inlined  )  [virtual]

Sets whether this widget is displayed inline or as a block.

This option changes whether this widget must be rendered in-line with sibling widgets wrapping at the right edge of the parent container (like text), or whether this widget must be rendered as a rectangular block that stacks vertically with sibling widgets (unless a CSS float property is applied). Depending on the widget type, the default value is inline (such as for example for WText, or WPushButton), or block (such as for example for a WContainerWidget).

This applies to CSS-based layout.

Implements Wt::WWidget.

bool WWebWidget::isInline (  )  const [virtual]

Returns whether this widget is displayed inline or as block.

See also:
setInline(bool)

Implements Wt::WWidget.

WCssDecorationStyle & WWebWidget::decorationStyle (  )  [virtual]

Returns the decoration style of this widget.

This groups all decorative aspects of the widget, which do not affect the widget layout (except for the border properties which may behave like extra margin around the widget).

Implements Wt::WWidget.

void WWebWidget::setStyleClass ( const WString styleClass  )  [virtual]

Sets a style class.

The CSS style class works in conjunction with style sheet, and provides a flexible way to provide many widgets the same markup.

Setting an empty string removes the style class.

See also:
WApplication::styleSheet()

Implements Wt::WWidget.

WString WWebWidget::styleClass (  )  const [virtual]

Returns the style class.

See also:
setStyleClass()

Implements Wt::WWidget.

void WWebWidget::setVerticalAlignment ( AlignmentFlag  alignment,
const WLength length = WLength() 
) [virtual]

Sets the vertical alignment of this (inline) widget.

This only applies to inline widgets, and determines how to position itself on the current line, with respect to sibling inline widgets.

This applies to CSS-based layout.

Implements Wt::WWidget.

AlignmentFlag WWebWidget::verticalAlignment (  )  const [virtual]

Returns the vertical alignment.

This applies to CSS-based layout.

See also:
setVerticalAlignment()

Implements Wt::WWidget.

WLength WWebWidget::verticalAlignmentLength (  )  const [virtual]

Returns the fixed vertical alignment that was set.

This applies to CSS-based layout.

See also:
setVerticalAlignment()

Implements Wt::WWidget.

void WWebWidget::setToolTip ( const WString text  )  [virtual]

Sets a tooltip.

The tooltip is displayed when the cursor hovers over the widget.

Implements Wt::WWidget.

void WWebWidget::refresh (  )  [virtual]

Refresh the widget.

The refresh method is invoked when the locale is changed using WApplication::setLocale() or when the user hit the refresh button.

The widget must actualize its contents in response.

Implements Wt::WWidget.

Reimplemented in Wt::Ext::AbstractButton, Wt::Ext::ComboBox, Wt::Ext::FormField, Wt::Ext::MessageBox, Wt::Ext::Panel, Wt::Ext::TableView, Wt::Ext::TabWidget, Wt::WComboBox, Wt::WGroupBox, Wt::WPushButton, Wt::WText, and Wt::WViewWidget.

void WWebWidget::setAttributeValue ( const std::string &  name,
const WString value 
) [virtual]

Sets an attribute value.

Associate an extra attribute with this widget, with the given value. This is only useful when processing dom nodes associated with widgets in custom JavaScript code.

See also:
JSlot, WApplication::doJavaScript()

Implements Wt::WWidget.

WString WWebWidget::attributeValue ( const std::string &  name  )  const [virtual]

Returns an attribute value.

See also:
setAttributeValue()

Implements Wt::WWidget.

void WWebWidget::load (  )  [virtual]

Load content just before the widget's content is rendered.

As soon as a widget is inserted into the widget hierarchy, it is rendered. Visible widgets are rendered immediately, and invisible widgets in the back-ground. This method is called when the widget is directly or indirectly inserted into the widget tree.

The default implementation simply propagates the load signal to its children. You may want to override this method to load resource-intensive content only when the widget is loaded into the browser.

Implements Wt::WWidget.

Reimplemented in Wt::WTextEdit, and Wt::WViewWidget.

bool WWebWidget::loaded (  )  const [virtual]

Returns if this widget has been loaded.

See also:
load()

Implements Wt::WWidget.

void WWebWidget::setId ( const std::string &  id  )  [virtual]

Sets the CSS Id.

Sets a custom Id. Note that the Id must be unique across the whole widget tree, can only be set right after construction and cannot be changed.

See also:
WObject::id()

Implements Wt::WWidget.

void WWebWidget::setSelectable ( bool  selectable  )  [virtual]

Sets as selectable.

When a widget is made unselectable, a selection of text (or images) will not be visible (but may still be possible).

By default, the widget inherits this property from its parent, and this property propagates to all children. The top level container (WApplication::root()) selectable by default.

Implements Wt::WWidget.

const std::string WWebWidget::id (  )  const [virtual]

Returns the (unique) identifier for this object.

For a WWidget, this corresponds to the id of the DOM element that represents the widget. This is not entirely unique, since a composite widget shares the same id as its implementation.

By default, the id is auto-generated, unless a custom id is set for a widget using WWidget::setId(). The auto-generated id is created by concatenating objectName() with a unique number.

See also:
WWidget::jsRef()

Reimplemented from Wt::WObject.

void WWebWidget::setLoadLaterWhenInvisible ( bool  how  ) 

Change the way the widget is loaded when invisible.

By default, invisible widgets are loaded only after visible content. For tiny widgets this may lead to a performance loss, instead of the expected increase, because they require many more DOM manipulation to render, reducing the overall responsiveness of the application.

Therefore, this is disabled for some widgets like WImage, or empty WContainerWidgets.

Usually the default settings are fine, but you may want to change the behaviour.

See also:
WApplication::setTwoPhaseRenderingThreshold()

bool WWebWidget::removeScript ( WString text  )  [static]

Remove tags/attributes from text that are not passive.

This removes tags and attributes from XHTML-formatted text that do not simply display something but may trigger scripting, and could have been injected by a malicious user for Cross-Site Scripting (XSS).

This method is used by the library to sanitize XHTML-formatted text set in WText, but it may also be useful outside the library to sanitize user content when direcly using JavaScript.

Modifies the text if needed. When the text is not proper XML, returns false.

std::string WWebWidget::jsStringLiteral ( const std::string &  v,
char  delimiter = '\'' 
) [static]

Turn a UTF8 encoded string into a JavaScript string literal.

The delimiter may be a single or double quote.

const std::vector< WWidget * > & WWebWidget::children (  )  const

Returns contained widgets.

See also:
WContainerWidget::addWidget()

Reimplemented from Wt::WObject.

Reimplemented in Wt::Ext::Splitter.

void WWebWidget::enableAjax (  )  [protected, virtual]

Progress to an Ajax-enabled widget.

This method is called when the progressive bootstrap method is used, and support for AJAX has been detected. The default behavior will upgrade the widget's event handling to use AJAX instead of full page reloads, and propagate the call to its children.

You may want to reimplement this method if you want to make changes to widget when AJAX is enabled. You should always call the base implementation.

See also:
WApplication::enableAjax()

Implements Wt::WWidget.

Reimplemented in Wt::WAnchor, Wt::WFileUpload, and Wt::WPaintedWidget.


Generated on Tue Sep 1 17:51:17 2009 for Wt by doxygen 1.5.6