A base class for widgets with an HTML counterpart. More...
#include <Wt/WWebWidget>
Public Member Functions | |
WWebWidget (WContainerWidget *parent=0) | |
Construct a WebWidget with a given parent. | |
virtual void | setPositionScheme (PositionScheme scheme) |
Sets the CSS position scheme. | |
virtual PositionScheme | positionScheme () const |
Returns the CSS position scheme. | |
virtual void | setOffsets (const WLength &offset, WFlags< Side > sides=All) |
Sets CSS offsets for a non-statically positioned widget. | |
virtual WLength | offset (Side s) const |
Returns a CSS offset. | |
virtual void | resize (const WLength &width, const WLength &height) |
Resizes the widget. | |
virtual WLength | width () const |
Returns the width. | |
virtual WLength | height () const |
Returns the 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 CSS line height for contained text. | |
virtual WLength | lineHeight () const |
Returns the CSS line height for contained text. | |
virtual void | setFloatSide (Side s) |
Specifies a CSS float side. | |
virtual Side | floatSide () const |
Returns the CSS float side. | |
virtual void | setClearSides (WFlags< Side > sides) |
Sets the sides that should be cleared of floats. | |
virtual WFlags< Side > | clearSides () const |
Returns the sides that should remain empty. | |
virtual void | setMargin (const WLength &margin, WFlags< Side > sides=All) |
Sets CSS margins around the widget. | |
virtual WLength | margin (Side side) const |
Returns a CSS margin set. | |
virtual void | setHiddenKeepsGeometry (bool enabled) |
Sets whether the widget keeps its geometry when hidden. | |
virtual bool | hiddenKeepsGeometry () const |
Returns whether the widget keeps its geometry when hidden. | |
virtual void | setHidden (bool) |
Sets whether the widget is hidden. | |
virtual bool | isHidden () const |
Returns whether the widget is set hidden. | |
virtual bool | isVisible () const |
Returns whether the widget is visible. | |
virtual void | setDisabled (bool) |
Sets whether the widget is disabled. | |
virtual bool | isDisabled () const |
Returns whether the widget is set disabled. | |
virtual bool | isEnabled () const |
Returns whether the widget is enabled. | |
virtual void | setPopup (bool) |
Lets the widget overlay over other sibling widgets. | |
virtual bool | isPopup () const |
Returns whether the widget is overlayed. | |
virtual void | setInline (bool) |
Sets whether the widget is displayed inline or as a block. | |
virtual bool | isInline () const |
Returns whether the widget is displayed inline or as block. | |
virtual void | setDecorationStyle (const WCssDecorationStyle &style) |
Sets a CSS decoration style. | |
virtual WCssDecorationStyle & | decorationStyle () |
Returns the decoration style of this widget. | |
virtual void | setStyleClass (const WString &styleClass) |
Sets (one or more) CSS style classes. | |
virtual WString | styleClass () const |
Returns the CSS style class. | |
virtual void | setVerticalAlignment (AlignmentFlag alignment, const WLength &length=WLength()) |
Sets the vertical alignment. | |
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. | |
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 | setJavaScriptMember (const std::string &name, const std::string &value) |
Sets a JavaScript member. | |
virtual std::string | javaScriptMember (const std::string &name) const |
Returns the value of a JavaScript member. | |
virtual void | callJavaScriptMember (const std::string &name, const std::string &args) |
Calls a JavaScript member. | |
virtual void | load () |
Loads content just before the widget is used. | |
virtual bool | loaded () const |
Returns whether this widget has been loaded. | |
virtual void | setId (const std::string &id) |
Sets the CSS Id. | |
virtual WWidget * | find (const std::string &name) |
Finds a descendend widget by name. | |
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. | |
bool | isRendered () const |
Returns whether the widget is rendered. | |
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 | propagateSetEnabled (bool enabled) |
Propagates that a widget was enabled or disabled through children. | |
virtual void | enableAjax () |
Progresses to an Ajax-enabled widget. |
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.
WWebWidget::WWebWidget | ( | WContainerWidget * | parent = 0 ) |
Construct a WebWidget with a given parent.
WString WWebWidget::attributeValue | ( | const std::string & | name ) | const [virtual] |
void WWebWidget::callJavaScriptMember | ( | const std::string & | name, |
const std::string & | args | ||
) | [virtual] |
Calls a JavaScript member.
This calls a JavaScript member.
Implements Wt::WWidget.
const std::vector< WWidget * > & WWebWidget::children | ( | ) | const |
Returns contained widgets.
Reimplemented from Wt::WObject.
Reimplemented in Wt::Ext::Splitter.
WFlags< Side > WWebWidget::clearSides | ( | ) | const [virtual] |
Returns the sides that should remain empty.
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).
When a decoration style has not been previously set, it returns a default decoration style object.
Implements Wt::WWidget.
void WWebWidget::enableAjax | ( | ) | [protected, virtual] |
Progresses 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.
Implements Wt::WWidget.
Reimplemented in Wt::WAnchor, Wt::WFileUpload, Wt::WFormWidget, Wt::WPaintedWidget, and Wt::WTemplate.
WWidget * WWebWidget::find | ( | const std::string & | name ) | [virtual] |
Side WWebWidget::floatSide | ( | ) | const [virtual] |
WLength WWebWidget::height | ( | ) | const [virtual] |
Returns the 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.
Implements Wt::WWidget.
bool WWebWidget::hiddenKeepsGeometry | ( | ) | const [virtual] |
Returns whether the widget keeps its geometry when hidden.
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.
Reimplemented from Wt::WObject.
bool WWebWidget::isDisabled | ( | ) | const [virtual] |
Returns whether the widget is set disabled.
A widget that is not set disabled may still be disabled when one of its ancestor widgets is set disabled. Use isEnabled() to find out whether a widget is enabled.
Implements Wt::WWidget.
bool WWebWidget::isEnabled | ( | ) | const [virtual] |
Returns whether the widget is enabled.
A widget is enabled if it is not disabled, and none of its ancestors are disabled. This method returns whether the widget is rendered as enabled, while isDisabled() returns whether a widget has been explicitly disabled.
Note that a widget may be at the same time not enabled, and not disabled, in case one of its ancestors was disabled.
Implements Wt::WWidget.
Reimplemented in Wt::Ext::Component.
bool WWebWidget::isHidden | ( | ) | const [virtual] |
Returns whether the widget is set hidden.
A widget that is not hidden may still be not visible when one of its ancestor widgets is hidden. Use isVisible() to check the visibility of a widget.
Implements Wt::WWidget.
bool WWebWidget::isInline | ( | ) | const [virtual] |
Returns whether the widget is displayed inline or as block.
Implements Wt::WWidget.
bool WWebWidget::isPopup | ( | ) | const [virtual] |
Returns whether the widget is overlayed.
This applies to CSS-based layout.
Implements Wt::WWidget.
bool WWebWidget::isRendered | ( | ) | const |
bool WWebWidget::isVisible | ( | ) | const [virtual] |
Returns whether the widget is visible.
A widget is visible if it is not hidden, and none of its ancestors are hidden. This method returns the true visibility, while isHidden() returns whether a widget has been explicitly hidden.
Note that a widget may be at the same time not hidden, and not visible, in case one of its ancestors was hidden.
Implements Wt::WWidget.
std::string WWebWidget::javaScriptMember | ( | const std::string & | name ) | const [virtual] |
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.
WLength WWebWidget::lineHeight | ( | ) | const [virtual] |
void WWebWidget::load | ( | ) | [virtual] |
Loads content just before the widget is used.
When the widget is inserted in the widget hierarchy, this method is called. Widgets that get inserted in the widget hierarchy will be rendered. Visible widgets are rendered immediately, and invisible widgets in the back-ground (or not for a plain HTML session). 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 delay loading of resource-intensive contents.
Implements Wt::WWidget.
Reimplemented in Wt::WViewWidget.
bool WWebWidget::loaded | ( | ) | const [virtual] |
Returns a CSS margin set.
This applies to CSS-based layout.
Implements Wt::WWidget.
WLength WWebWidget::maximumHeight | ( | ) | const [virtual] |
Returns the maximum height.
Returns the minmum height set for this widget with setMaximumSize().
Implements Wt::WWidget.
WLength WWebWidget::maximumWidth | ( | ) | const [virtual] |
Returns the maximum width.
Returns the maximum width set for this widget with setMaximumSize().
Implements Wt::WWidget.
WLength WWebWidget::minimumHeight | ( | ) | const [virtual] |
Returns the minimum height.
Returns the minmum height set for this widget with setMinimumSize().
Implements Wt::WWidget.
WLength WWebWidget::minimumWidth | ( | ) | const [virtual] |
Returns the minimum width.
Returns the minimum width set for this widget with setMinimumSize().
Implements Wt::WWidget.
PositionScheme WWebWidget::positionScheme | ( | ) | const [virtual] |
void WWebWidget::propagateSetEnabled | ( | bool | enabled ) | [protected, virtual] |
Propagates that a widget was enabled or disabled through children.
When enabling or disabling a widget, you usually also want to disable contained children. This method is called by setDisabled() to propagate its state to all children.
You may want to reimplement this method if they wish to render differently when a widget is disabled. The default implementation will propagate the signal to all children.
Reimplemented in Wt::WFormWidget, Wt::WGroupBox, and Wt::WLabel.
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.
Reimplemented from 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::WTemplate, Wt::WText, and Wt::WViewWidget.
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
.
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, and only block widgets can be given a size reliably.
When inserted in a layout manager, the widget may be informed about its current size using setLayoutSizeAware(). If you have defined a "wtResize()" JavaScript method for the widget, then this method will also be called. operation.
Reimplemented from Wt::WWidget.
Reimplemented in Wt::Ext::TextEdit, Wt::WFlashObject, Wt::WPaintedWidget, and Wt::WTextEdit.
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.
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 combination of Left and Right.
This applies to CSS-based layout.
Implements Wt::WWidget.
void WWebWidget::setDecorationStyle | ( | const WCssDecorationStyle & | style ) | [virtual] |
Sets a CSS decoration style.
This copies the style over its current decorationStyle()
Implements Wt::WWidget.
void WWebWidget::setDisabled | ( | bool | disabled ) | [virtual] |
Sets whether the widget is disabled.
Enables or disables the widget (including all its descendant widgets). setDisabled(false) will enable this widget and all descendant widgets that are not disabled. A widget is only enabled if it and all its ancestors in the widget tree are disabled.
Implements Wt::WWidget.
void WWebWidget::setFloatSide | ( | Side | s ) | [virtual] |
Specifies a CSS float side.
This only applies to widgets with a Static positionScheme().
This lets the widget float to 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 orNone , Left or Right .
This applies to CSS-based layout.
Implements Wt::WWidget.
void WWebWidget::setHidden | ( | bool | hidden ) | [virtual] |
Sets whether the widget is hidden.
Hides or show the widget (including all its descendant widgets). setHidden(false) will show this widget and all descendant widgets that are not hidden. A widget is only visible if it and all its ancestors in the widget tree are visible, which may be checked using isVisible().
Implements Wt::WWidget.
Reimplemented in Wt::Ext::Dialog, Wt::Ext::MessageBox, Wt::Ext::Widget, and Wt::WFormWidget.
void WWebWidget::setHiddenKeepsGeometry | ( | bool | enabled ) | [virtual] |
Sets whether the widget keeps its geometry when hidden.
Normally, a widget that is hidden will no longer occupy space, causing a reflow of sibling widgets. Using this method you may change this behavior to keep an (open) space when hidden.
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. This is mostly useful for in tests using a test plan that manipulates DOM elements by Id.
By default, auto-generated id's are used.
Implements Wt::WWidget.
void WWebWidget::setInline | ( | bool | inlined ) | [virtual] |
Sets whether the 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.
void WWebWidget::setJavaScriptMember | ( | const std::string & | name, |
const std::string & | value | ||
) | [virtual] |
Sets a JavaScript member.
This binds a JavaScript member, which is set as a JavaScript property to the DOM object that implements this widget. The value may be any JavaScript expression, including a function.
Members that start with "wt" are reserved for internal use. You may define a member "wtResize(self, width, height)" method if your widget needs active layout management. If defined, this method will be used by layout managers and when doing resize() to set the size of the widget, instead of setting the CSS width and height properties.
Implements Wt::WWidget.
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.
Sets CSS 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.
Implements Wt::WWidget.
Sets a maximum size.
Specify a minimum size for this widget.
Implements Wt::WWidget.
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.
Implements Wt::WWidget.
Sets CSS offsets for a non-statically positioned widget.
The argument sides
may be a combination 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.
Implements Wt::WWidget.
void WWebWidget::setPopup | ( | bool | popup ) | [virtual] |
Lets the widget overlay over 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, and configures the z-index property.
Implements Wt::WWidget.
void WWebWidget::setPositionScheme | ( | PositionScheme | scheme ) | [virtual] |
Sets the CSS 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.
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.
void WWebWidget::setStyleClass | ( | const WString & | styleClass ) | [virtual] |
Sets (one or more) CSS style classes.
You may set one or more space separated style classes. 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(es).
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::setVerticalAlignment | ( | AlignmentFlag | alignment, |
const WLength & | length = WLength() |
||
) | [virtual] |
Sets the vertical alignment.
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.
WString WWebWidget::styleClass | ( | ) | const [virtual] |
AlignmentFlag WWebWidget::verticalAlignment | ( | ) | const [virtual] |
Returns the vertical alignment.
This applies to CSS-based layout.
Implements Wt::WWidget.
WLength WWebWidget::verticalAlignmentLength | ( | ) | const [virtual] |
Returns the fixed vertical alignment that was set.
This applies to CSS-based layout.
Implements Wt::WWidget.
WLength WWebWidget::width | ( | ) | const [virtual] |
Returns the 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.
Implements Wt::WWidget.