A signal to relay JavaScript to C++ calls. More...

#include <Wt/WJavaScript>

Inheritance diagram for Wt::JSignal< A1, A2, A3, A4, A5, A6 >:

Public Member Functions
	JSignal (WObject *object, const std::string &name, bool collectSlotJavaScript=false)
	Construct a signal for the given object, and name. More...

	~JSignal ()
	Destructor.

const std::string &	name () const
	Returns the signal name.

const std::string	createCall (const std::string &arg1=std::string(), const std::string &arg2=std::string(), const std::string &arg3=std::string(), const std::string &arg4=std::string(), const std::string &arg5=std::string(), const std::string &arg6=std::string()) const
	Returns a JavaScript call that triggers the signal. More...

const std::string	createEventCall (const std::string &jsObject, const std::string &jsEvent, const std::string &arg1=std::string(), const std::string &arg2=std::string(), const std::string &arg3=std::string(), const std::string &arg4=std::string(), const std::string &arg5=std::string()) const
	Returns a JavaScript call that triggers the signal, passing the original event too. More...

virtual bool	isConnected () const
	Returns whether the signal is connected to at least one slot.

template<class F >
Wt::Signals::connection	connect (const F &function)
	Connect to a function. More...

template<class T , class V >
Wt::Signals::connection	connect (T target, void(V::method)())
	Connect a slot that takes no arguments. More...

template<class T , class V >
Wt::Signals::connection	connect (T target, void(V::method)(A1))
	Connect a slot that takes one argument. More...

template<class T , class V >
Wt::Signals::connection	connect (T target, void(V::method)(A1, A2))
	Connect a slot that takes two arguments. More...

template<class T , class V >
Wt::Signals::connection	connect (T target, void(V::method)(A1, A2, A3))
	Connect a slot that takes three arguments. More...

template<class T , class V >
Wt::Signals::connection	connect (T target, void(V::method)(A1, A2, A3, A4))
	Connect a slot that takes four arguments. More...

template<class T , class V >
Wt::Signals::connection	connect (T target, void(V::method)(A1, A2, A3, A4, A5))
	Connect a slot that takes five arguments. More...

template<class T , class V >
Wt::Signals::connection	connect (T target, void(V::method)(A1, A2, A3, A4, A5, A6))
	Connect a slot that takes six arguments. More...

void	connect (const std::string &function)
	Connects a JavaScript function. More...

void	connect (JSlot &slot)
	Connect a slot that is specified as JavaScript only. More...

void	emit (A1 a1=NoClass::none, A2 a2=NoClass::none, A3 a3=NoClass::none, A4 a4=NoClass::none, A5 a5=NoClass::none, A6 a6=NoClass::none)
	Emit the signal. More...

void	operator() (A1 a1=NoClass::none, A2 a2=NoClass::none, A3 a3=NoClass::none, A4 a4=NoClass::none, A5 a5=NoClass::none, A6 a6=NoClass::none)
	Emit the signal. More...

virtual Wt::Signals::connection	connect (WObject target, void(WObject::method)())
	Connects to a slot. More...

Public Member Functions inherited from Wt::EventSignalBase
const char *	name () const
	Returns the event name. More...

void	disconnect (JSlot &slot)
	Disconnects a JSlot.

void	preventDefaultAction (bool prevent=true)
	Prevents the default browser action. More...

bool	defaultActionPrevented () const
	Returns whether the default browser action is prevented. More...

void	preventPropagation (bool prevent=true)
	Prevents event propagation. More...

bool	propagationPrevented () const
	Returns whether event propagation is prevented. More...

Public Member Functions inherited from Wt::SignalBase
WObject *	sender () const
	Returns the sender. More...

template<class T , class V >
Wt::Signals::connection	connect (T target, void(V::method)())
	Connects to a slot. More...

Detailed Description

template<typename A1 = NoClass, typename A2 = NoClass, typename A3 = NoClass, typename A4 = NoClass, typename A5 = NoClass, typename A6 = NoClass>
class Wt::JSignal< A1, A2, A3, A4, A5, A6 >

A signal to relay JavaScript to C++ calls.

A JSignal, like an EventSignal, provides communicates events from JavaScript to C++ code. However, it not tied to a built-in event. Instead, it can be emitted from within custom JavaScript code using the JavaScript Wt.emit() function.

The signal is identified by a unique name within the scope of a WObject, or a unique global name (when declaring the signal in your WApplication).

The signal supports up to 6 arguments. Values for these arguments may be specified in the JavaScript Wt.emit() (or the deprecated global function WtSignalEmit()).

Example code:

class MyWidget : public WCompositeWidget
{
public:
  MyWidget()
    : doSome_(this, "doSome")
  {
    ...
  }
  JSignal<std::string, int>& doSome() { return doSome_; }
private:
  JSignal<std::string, int> doSome_;
  ...
};

The following JavaScript statement will emit the signal for a DOM element element that corresponds to a widget of class MyWidget:

Wt.emit(element, 'dosome', 'foo', 42);

The element can be a DOM element, or the object ID of a WObject, or the constant Wt which refers to the Wt::WApplication instance. The conversion between the JavaScript arguments (ax) and the C++ type Ax uses boost::lexical_cast<Ax>(ax).

You can use the methods createCall() to let the signal itself generate this JavaScript call for you:

doSome_.createCall("'foo'", "42");

The JavaScript generated by createCall() is possibly affected by every connect or disconnect to the signal. In practice, you will use JSignal internally within a widget and call createCall() only after you connected internal slots to signal.

It is also possible to propagate an original JavaScript event as a last argument, of type WMouseEvent, WKeyEvent or WTouchEvent. In that case, the second argument in Wt.emit() must be an object which indicates also the JavaScript event and event target.

Consider a signal declaration:

JSignal<std::string, int, WMouseEvent> doSome();

Then, the following would be a suitable JavaScript call:

Wt.emit(Wt, {name: 'dosome', event: event, eventObject: object}, 'foo', 42);

The method createEventCall() may be used this variation for the JavaScript method call.

Since the conversion from JavaScript to C++ uses boost::lexical_cast<T>(arg), you may provide support for custom types by implementing the c++ input stream operator std::istream& operator>> (std::istream&, T& t) for your type.

See also: WWidget::jsRef(), WObject::id()

Constructor & Destructor Documentation

template<typename A1 , typename A2 , typename A3 , typename A4 , typename A5 , typename A6 >

Wt::JSignal< A1, A2, A3, A4, A5, A6 >::JSignal	(	WObject *	object,
		const std::string &	name,
		bool	collectSlotJavaScript = `false`
	)

Construct a signal for the given object, and name.

The given name must be unique for all user signals specified for the object object. Ownership of the signal is not transferred to the object.

If collectSlotJavaScript is true, then javascript specified for connected slots (using JSlot) or learned by stateless slot learning, is collected to client-side JavaScript.

Use the utility methods createCall() or createEventCall() to create the appropriate JavaScript statements that invoke the signal, which take into account possible other client-side JavaScript handling associated with the signal.

See also: stateless slot learning

Member Function Documentation

template<typename A1 , typename A2 , typename A3 , typename A4 , typename A5 , typename A6 >

template<class F >

Wt::Signals::connection Wt::JSignal< A1, A2, A3, A4, A5, A6 >::connect ( const F & function )

Connect to a function.

This variant of the overloaded connect() method supports a template function object (which supports operator ()).

When the receiver function is an object method, the signal will automatically be disconnected when the object is deleted, as long as the object inherits from WObject (or Wt::Signals::trackable).

The function may leave 1 parameters unbound (e.g. using boost::bind placeholders _1) that may be bound to the event detail object passed by the signal.

template<typename A1 , typename A2 , typename A3 , typename A4 , typename A5 , typename A6 >

template<class T , class V >

Wt::Signals::connection Wt::JSignal< A1, A2, A3, A4, A5, A6 >::connect	(	T *	target,
		void(V::*)()	method
	)

Connect a slot that takes no arguments.

The slot is specified as a method of an object target of class T, which equals class V, or is a base class of class V. In addition, to check for stateless implementations, class T must be also be a descendant of WObject. Thus, the following statement must return a non-null pointer:

WObject *o = dynamic_cast<WObject *>(dynamic_cast<V *>(target));

If a stateless implementation is specified for the slot, then the visual behaviour will be learned in terms of JavaScript, and will be cached on the client side for instant feed-back, in addition running the slot on the server.

template<typename A1, typename A2 , typename A3 , typename A4 , typename A5 , typename A6 >

template<class T , class V >

Wt::Signals::connection Wt::JSignal< A1, A2, A3, A4, A5, A6 >::connect	(	T *	target,
		void(V::*)(A1)	method
	)

Connect a slot that takes one argument.

This is only possible for signals that take at least one argument.

See also: connect(T *target, void (V::*method)())

template<typename A1, typename A2, typename A3 , typename A4 , typename A5 , typename A6 >

template<class T , class V >

Wt::Signals::connection Wt::JSignal< A1, A2, A3, A4, A5, A6 >::connect	(	T *	target,
		void(V::*)(A1, A2)	method
	)

Connect a slot that takes two arguments.

This is only possible for signals that take at least two arguments.

See also: connect(T *target, void (V::*method)())

template<typename A1, typename A2, typename A3, typename A4 , typename A5 , typename A6 >

template<class T , class V >

Wt::Signals::connection Wt::JSignal< A1, A2, A3, A4, A5, A6 >::connect	(	T *	target,
		void(V::*)(A1, A2, A3)	method
	)

Connect a slot that takes three arguments.

This is only possible for signals that take at least three arguments.

See also: connect(T *target, void (V::*method)())

template<typename A1, typename A2, typename A3, typename A4, typename A5 , typename A6 >

template<class T , class V >

Wt::Signals::connection Wt::JSignal< A1, A2, A3, A4, A5, A6 >::connect	(	T *	target,
		void(V::*)(A1, A2, A3, A4)	method
	)

Connect a slot that takes four arguments.

This is only possible for signals that take at least four arguments.

See also: connect(T *target, void (V::*method)())

template<typename A1, typename A2, typename A3, typename A4, typename A5, typename A6 >

template<class T , class V >

Wt::Signals::connection Wt::JSignal< A1, A2, A3, A4, A5, A6 >::connect	(	T *	target,
		void(V::*)(A1, A2, A3, A4, A5)	method
	)

Connect a slot that takes five arguments.

This is only possible for signals that take at least five arguments.

See also: connect(T *target, void (V::*method)())

template<typename A1, typename A2, typename A3, typename A4, typename A5, typename A6>

template<class T , class V >

Wt::Signals::connection Wt::JSignal< A1, A2, A3, A4, A5, A6 >::connect	(	T *	target,
		void(V::*)(A1, A2, A3, A4, A5, A6)	method
	)

Connect a slot that takes six arguments.

This is only possible for signals that take at least six arguments.

See also: connect(T *target, void (V::*method)())

template<typename A1 , typename A2 , typename A3 , typename A4 , typename A5 , typename A6 >

void Wt::JSignal< A1, A2, A3, A4, A5, A6 >::connect ( const std::string & function )

Connects a JavaScript function.

This will provide a client-side connection between the event and a JavaScript function. The argument must be a JavaScript function which optionally accepts up to two arguments (object and event):

function(object, event) {
  ...
}

Unlike a JSlot, there is no automatic connection management: the connection cannot be removed. If you need automatic connection management, you should use connect(JSlot&) instead.

template<typename A1 , typename A2 , typename A3 , typename A4 , typename A5 , typename A6 >

void Wt::JSignal< A1, A2, A3, A4, A5, A6 >::connect ( JSlot & slot )

Connect a slot that is specified as JavaScript only.

This will provide a client-side connection between the event and some JavaScript code as implemented by the slot. Unlike other connects, this does not cause the event to propagated to the application, and thus the state changes induced by the slot are invisible to the server-side.

template<typename A1 , typename A2 , typename A3 , typename A4 , typename A5 , typename A6 >

Wt::Signals::connection Wt::JSignal< A1, A2, A3, A4, A5, A6 >::connect	(	WObject *	target,
		void(WObject::*)()	method
	)

virtual

Connects to a slot.

Every signal can be connected to a slot which does not take any arguments (and may thus ignore signal arguments).

Implements Wt::SignalBase.

template<typename A1 , typename A2 , typename A3 , typename A4 , typename A5 , typename A6 >

const std::string Wt::JSignal< A1, A2, A3, A4, A5, A6 >::createCall	(	const std::string &	arg1 = `std::string()`,
		const std::string &	arg2 = `std::string()`,
		const std::string &	arg3 = `std::string()`,
		const std::string &	arg4 = `std::string()`,
		const std::string &	arg5 = `std::string()`,
		const std::string &	arg6 = `std::string()`
	)		const

Returns a JavaScript call that triggers the signal.

This is:

Wt.emit([element], [name], arg1, ...);

When the signal was constructed with collectSlotJavaScript == true, the inline JavaScript from slots defined as JavaScript or from learned stateless slots, or directly connected to the signal, is included as well.

Note: The method only takes into account JavaScript from slot connections that have been connected so far, and any subsequent connections are ignored.

See also: createEventCall()

template<typename A1 , typename A2 , typename A3 , typename A4 , typename A5 , typename A6 >

const std::string Wt::JSignal< A1, A2, A3, A4, A5, A6 >::createEventCall	(	const std::string &	jsObject,
		const std::string &	jsEvent,
		const std::string &	arg1 = `std::string()`,
		const std::string &	arg2 = `std::string()`,
		const std::string &	arg3 = `std::string()`,
		const std::string &	arg4 = `std::string()`,
		const std::string &	arg5 = `std::string()`
	)		const

Returns a JavaScript call that triggers the signal, passing the original event too.

Similar to createCall(), the following JavaScript is returned:

Wt.emit([element], { name: [name], eventObject: [jsObject], event: [jsEvent]},

arg1, ...);

In addition to information identifying the signal (element and name) and the arguments, also information on the original JavaScript event is transferred. In this way, you can propagate the corresponding event class (WMouseEvent, WKeyEvent or WTouchEvent) as an additional last argument in the slot.

Note: The method only takes into account JavaScript from slot connections that have been connected so far, and any subsequent connections are ignored.

template<typename A1, typename A2, typename A3, typename A4, typename A5, typename A6>

void Wt::JSignal< A1, A2, A3, A4, A5, A6 >::emit	(	A1	a1 = `NoClass::none`,
		A2	a2 = `NoClass::none`,
		A3	a3 = `NoClass::none`,
		A4	a4 = `NoClass::none`,
		A5	a5 = `NoClass::none`,
		A6	a6 = `NoClass::none`
	)

Emit the signal.

The arguments must exactly match the arguments of the target function.

This will cause all connected slots to be triggered, with the given arguments.

template<typename A1, typename A2, typename A3, typename A4, typename A5, typename A6>

void Wt::JSignal< A1, A2, A3, A4, A5, A6 >::operator()	(	A1	a1 = `NoClass::none`,
		A2	a2 = `NoClass::none`,
		A3	a3 = `NoClass::none`,
		A4	a4 = `NoClass::none`,
		A5	a5 = `NoClass::none`,
		A6	a6 = `NoClass::none`
	)

Emit the signal.

This is equivalent to emit().

See also: emit

Public Member Functions

Detailed Description

template<typename A1 = NoClass, typename A2 = NoClass, typename A3 = NoClass, typename A4 = NoClass, typename A5 = NoClass, typename A6 = NoClass> class Wt::JSignal< A1, A2, A3, A4, A5, A6 >

Constructor & Destructor Documentation

Member Function Documentation

template<typename A1 = NoClass, typename A2 = NoClass, typename A3 = NoClass, typename A4 = NoClass, typename A5 = NoClass, typename A6 = NoClass>
class Wt::JSignal< A1, A2, A3, A4, A5, A6 >