Wt: Wt::WObject Class Reference

Wt 4.10.4

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Protected Member Functions | List of all members
Wt::WObject Class Reference
Signal/slot system

A base class for objects that participate in the signal/slot system. More...

`#include <Wt/WObject.h>`

Inheritance diagram for Wt::WObject:
[legend]

## Public Types
typedef void(WObject::*) | Method()
| Typedef for a WObject method without arguments.

## Public Member Functions
void | addChild (std::unique_ptr< WObject > child)
| Add a child WObject whose lifetime is determined by this WObject.
template<typename Child >
Child * | addChild (std::unique_ptr< Child > child)
| Add a child WObject, returning a raw pointer.
std::unique_ptr< WObject > | removeChild (WObject *child)
| Remove a child WObject, so its lifetime is no longer determined by this WObject.
template<typename Child >
std::unique_ptr< Child > | removeChild (Child *child)
| Remove a child WObject, so its lifetime is no longer determined by this WObject.
virtual const std::string | id () const
| Returns the (unique) identifier for this object.
virtual void | setObjectName (const std::string &name)
| Sets an object name.
virtual std::string | objectName () const
| Returns the object name.
void | resetLearnedSlots ()
| Resets learned stateless slot implementations.
template<class T >
void | resetLearnedSlot (void(T::*method)())
| Resets a learned stateless slot implementation.
template<class T >
WStatelessSlot * | implementStateless (void(T::*method)())
| Declares a slot to be stateless and learn client-side behaviour on first invocation.
template<class T >
WStatelessSlot * | implementStateless (void(T::*method)(), void(T::*undoMethod)())
| Declares a slot to be stateless and learn client-side behaviour in advance.
void | isNotStateless ()
| Marks the current function as not stateless.
template<class T >
WStatelessSlot * | implementJavaScript (void(T::*method)(), const std::string &jsCode)
| Provides a JavaScript implementation for a method.
Public Member Functions inherited from Wt::Core::observable
| observable () noexcept
| Default constructor.
virtual | ~observable ()
| Destructor.
template<typename... Args, typename C >
auto | bindSafe (void(C::*method)(Args...)) noexcept
| Protects a method call against object destruction.
template<typename... Args, typename C >
auto | bindSafe (void(C::*method)(Args...) const) const noexcept
| Protects a const method call against object destruction.
template<typename Function >
auto | bindSafe (const Function &function) noexcept
| Protects a function against object destruction.

## Protected Member Functions
virtual WStatelessSlot * | getStateless (Method method)
| On-demand stateless slot implementation.

## Detailed Description

A base class for objects that participate in the signal/slot system.

The main feature offered by WObject is automated object life-time tracking when involved in signal/slot connections. Connections between signals and slots of WObject instances implement a type-safe event callback system. For example, one can simply connect() the WInteractWidget::clicked() signal of a WPushButton to the WApplication::quit() method, to exit the application when the button is clicked:

std::unique_ptr<Wt::WInteractWidget> sender{new Wt::WText("Quit.")};
Wt::WApplication *app = Wt::WApplication::instance();
sender->clicked().connect(app, &Wt::WApplication::quit);
Wt::WApplication
Represents an application instance for a single session.
Definition WApplication.h:211
Wt::WApplication::quit
void quit()
Quits the application.
Wt::WApplication::instance
static WApplication * instance()
Returns the current application instance.
Wt::WText
A widget that renders (XHTML) text.
Definition WText.h:92

Wt's signals may also propagate arguments to slots. For example, the same clicked() signal provides event details in a WMouseEvent details class, and these details may be received in the slot:

class MyClass : public Wt::WContainerWidget
{
public:
MyClass()
{
Wt::WText *text = addWidget(std::make_unique<Wt::WText>("Click here"));
text->clicked().connect(this, &MyClass::handleClick);
...
}
private:
void handleClick(const Wt::WMouseEvent& event) {
if (event.modifiers().test(Wt::KeyboardModifier::Shift)) {
...
}
}
};
Wt::WContainerWidget
A widget that holds and manages child widgets.
Definition WContainerWidget.h:135
Wt::WContainerWidget::addWidget
virtual void addWidget(std::unique_ptr< WWidget > widget)
Adds a child widget to this container.
Wt::WFlags::test
bool test(EnumType flag) const
Returns whether a flag is set.
Definition WFlags.h:197
Wt::WInteractWidget::clicked
EventSignal< WMouseEvent > & clicked()
Event signal emitted when the primary mouse button was clicked on this widget.
Wt::WMouseEvent
A class providing details for a mouse event.
Definition WEvent.h:181
Wt::WMouseEvent::modifiers
WFlags< KeyboardModifier > modifiers() const
Returns keyboard modifiers.
Definition WEvent.h:203
Wt::KeyboardModifier::Shift
@ Shift
Shift key pressed.

As the example illustrates, slots are ordinary WObject methods.

In conjunction with EventSignal, WObject also facilitates learning of client-side event handling (in JavaScript) through invocation of the slot method. This is only possible when the slot behaviour is stateless, i.e. independent of any application state, and can be specified using the implementStateless() methods.

See also
  Signal, EventSignal

## Member Function Documentation

## ◆ addChild()

template<typename Child >

Child * Wt::WObject::addChild | ( | std::unique_ptr< Child > | child | ) |

Add a child WObject, returning a raw pointer.

This is implemented as:

Child *result = child.get();
addChild(std::unique_ptr<WObject>(std::move(child)));
return result;
Wt::WObject::addChild
void addChild(std::unique_ptr< WObject > child)
Add a child WObject whose lifetime is determined by this WObject.

## ◆ getStateless()

virtual WStatelessSlot * Wt::WObject::getStateless | ( | Method | method | ) |
| protectedvirtual

On-demand stateless slot implementation.

This method returns a stateless slot implementation for the given `method`. To avoid the cost of declaring methods to be stateless when they are not used, you may reimplement this method to provide a stateless implementation for a method only when the method is involved in a slot connection.

Use implementStateless() to provide a stateless implementation of the given `method`, or return the base class implementation otherwise.

Reimplemented in Wt::WAbstractToggleButton, Wt::WWebWidget, and Wt::WWidget.

## ◆ id()

virtual const std::string Wt::WObject::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().

See also
  WWidget::jsRef()

Reimplemented in Wt::WButtonGroup, Wt::WCompositeWidget, Wt::WTableColumn, Wt::WTableRow, and Wt::WWebWidget.

## ◆ implementJavaScript()

template<class T >

WStatelessSlot * Wt::WObject::implementJavaScript | ( | void(T::* | method )(),
|  | const std::string & | jsCode )

Provides a JavaScript implementation for a method.

This method sets the JavaScript implementation for a method. As a result, if JavaScript is available, the JavaScript version will be used on the client side and the visual effect of the C++ implementation will be ignored.

This is very similar to an auto-learned stateless slot, but here the learning is avoided by directly setting the JavaScript implementation.

The `jsCode` should be one or more valid JavaScript statements.

See also
  implementStateless(void (T::*method)())

## ◆ implementStateless() [1/2]

template<class T >

WStatelessSlot * Wt::WObject::implementStateless | ( | void(T::* | method )() | ) |

Declares a slot to be stateless and learn client-side behaviour on first invocation.

Indicate that the given slot is stateless, and meets the requirement that the slot's code does not depend on any state of the object, but performs the same visual effect regardless of any state, or at least until resetLearnedSlot() is called.

When this slot is connected to an EventSignal (such as those exposed by WInteractWidget and WFormWidget), the Wt library may decide to cache the visual effect of this slot in JavaScript code at client-side: this effect will be learned automatically at the first invocation. This has no consequences for the normal event handling, since the slot implementation is still executed in response to any event notification. Therefore, it is merely an optimization of the latency for the visual effect, but it does not change the behaviour of the application.

When for some reason the visual effect does change, one may use resetLearnedSlot() or resetLearnedSlots() to flush the existing cached visual effect, forcing the library to relearn it.

It is crucial that this function be applied first to a slot that is intended to be stateless before any EventSignal connects to that slot. Otherwise, the connecting EventSignal cannot find the stateless slot implementation for the intended slot, and the statement will have no effect for that connection.

See also
  resetLearnedSlot(), EventSignal

## ◆ implementStateless() [2/2]

template<class T >

WStatelessSlot * Wt::WObject::implementStateless | ( | void(T::* | method )(),
|  | void(T::* | undoMethod )() )

Declares a slot to be stateless and learn client-side behaviour in advance.

This method has the same effect as implementStateless(void (T::*method)()), but learns the visual effect of the slot before the first invocation of the event.

To learn the visual effect, the library will simulate the event and record the visual effect. To restore the application state, it will call the undoMethod which must restore the effect of method.

See also
  implementStateless(void (T::*method)())

## ◆ isNotStateless()

void Wt::WObject::isNotStateless | ( |  | ) |

Marks the current function as not stateless.

This may be useful if your current function is manipulating the UI in a way that is not stateless (i.e. does depend on some state), but which happens to be called from within a function that is marked stateless (such as WWidget::setHidden()). This will reject stateless slot pre-learning in this case, reverting to plain server-side dynamic UI updates.

## ◆ objectName()

virtual std::string Wt::WObject::objectName | ( |  | ) | const
| virtual

Returns the object name.

See also
  setObjectName()

Reimplemented in Wt::WCompositeWidget.

## ◆ removeChild()

template<typename Child >

std::unique_ptr< Child > Wt::WObject::removeChild | ( | Child * | child | ) |

Remove a child WObject, so its lifetime is no longer determined by this WObject.

This is an overload that automatically casts the returned value to a unique_ptr<Child> for convenience

This is implemented as:

return std::unique_ptr<Child>(static_cast<Child*>(removeChild(static_cast<WObject*>(child)).release()));
Wt::WObject
A base class for objects that participate in the signal/slot system.
Definition WObject.h:85
Wt::WObject::removeChild
std::unique_ptr< WObject > removeChild(WObject *child)
Remove a child WObject, so its lifetime is no longer determined by this WObject.

## ◆ resetLearnedSlot()

template<class T >

void Wt::WObject::resetLearnedSlot | ( | void(T::* | method )() | ) |

Resets a learned stateless slot implementation.

Clears the stateless implementation for the given slot that was declared to be implemented with a stateless implementation.

When something has changed that breaks the contract of a stateless slot to always have the same effect, you may call this method to force the application to discard the current implementation.

See also
  implementStateless()

## ◆ resetLearnedSlots()

void Wt::WObject::resetLearnedSlots | ( |  | ) |

Resets learned stateless slot implementations.

Clears the stateless implementation for all slots declared to be implemented with a stateless implementation.

See also
  resetLearnedSlot(), implementStateless()

## ◆ setObjectName()

virtual void Wt::WObject::setObjectName | ( | const std::string & | name | ) |
| virtual

Sets an object name.

The object name can be used to easily identify a type of object in the DOM, and does not need to be unique. It will usually reflect the widget type or role.

If a WWidget has an object name, the object name is reflected in the `data-object-name` attribute. You can use this to find widgets in JavaScript (e.g. for automated testing) using:

document.querySelector('*[data-object-name="yourObjectNameHere"]')

The default object name is empty (no object name).

Reimplemented in Wt::WCompositeWidget, and Wt::WWebWidget.