Represents an application instance for a single session. More...

#include <Wt/WApplication>

Inheritance diagram for Wt::WApplication:

Classes
class	UpdateLock
	A RAII lock for manipulating and updating the application and its widgets outside of the event loop. More...

Public Types
typedef Wt::ApplicationCreator	ApplicationCreator
	Typedef for a function that creates WApplication objects. More...

Public Types inherited from Wt::WObject
typedef void(WObject::*	Method) ()
	Typedef for a WObject method without arguments.

Public Member Functions
	WApplication (const WEnvironment &environment)
	Creates a new application instance. More...

	~WApplication ()
	Destructor. More...

const WEnvironment &	environment () const
	Returns the environment information. More...

WContainerWidget *	root () const
	Returns the root container. More...

WWidget *	findWidget (const std::string &name)
	Finds a widget by name. More...

void	setTitle (const WString &title)
	Sets the window title. More...

const WString &	title () const
	Returns the window title. More...

const WString &	closeMessage () const
	Returns the close message. More...

WLocalizedStrings *	localizedStrings ()
	Returns the resource object that provides localized strings. More...

void	setLocalizedStrings (WLocalizedStrings *stringResolver)
	Sets the resource object that provides localized strings. More...

WMessageResourceBundle &	messageResourceBundle ()
	Returns the message resource bundle. More...

void	setLocale (const WLocale &locale)
	Changes the locale. More...

const WLocale &	locale () const
	Returns the current locale. More...

virtual void	refresh ()
	Refreshes the application. More...

void	bindWidget (WWidget *widget, const std::string &domId)
	Binds a top-level widget for a WidgetSet deployment. More...

std::string	docRoot () const
	Returns the server document root. More...

void	setConnectionMonitor (const std::string &jsObject)
	Sets a client-side connection monitor. More...

std::string	sessionId () const
	Returns the unique identifier for the current session. More...

void	changeSessionId ()
	Changes the session id. More...

void	processEvents ()
	Processes UI events. More...

virtual void	waitForEvent ()
	Blocks the thread, waiting for an UI event. More...

void	setAjaxMethod (AjaxMethod method)
	Sets the Ajax communication method (deprecated). More...

AjaxMethod	ajaxMethod () const
	Returns the Ajax communication method (deprecated). More...

virtual void	initialize ()
	Initializes the application, post-construction. More...

virtual void	finalize ()
	Finalizes the application, pre-destruction. More...

void	setTwoPhaseRenderingThreshold (int size)
	Changes the threshold for two-phase rendering. More...

void	setCookie (const std::string &name, const std::string &value, int maxAge, const std::string &domain="", const std::string &path="", bool secure=false)
	Sets a new cookie. More...

void	removeCookie (const std::string &name, const std::string &domain="", const std::string &path="")
	Removes a cookie. More...

void	addMetaLink (const std::string &href, const std::string &rel, const std::string &media, const std::string &hreflang, const std::string &type, const std::string &sizes, bool disabled)
	Adds an HTML meta link. More...

void	removeMetaLink (const std::string &href)
	Removes the HTML meta link. More...

void	addMetaHeader (const std::string &name, const WString &content, const std::string &lang="")
	Adds a "name" HTML meta header. More...

void	addMetaHeader (MetaHeaderType type, const std::string &name, const WString &content, const std::string &lang="")
	Adds an HTML meta header. More...

WString	metaHeader (MetaHeaderType type, const std::string &name) const
	Returns a meta header value. More...

void	removeMetaHeader (MetaHeaderType type, const std::string &name="")
	Removes one or all meta headers. More...

WLogEntry	log (const std::string &type) const
	Adds an entry to the application log. More...

void	setLoadingIndicator (WLoadingIndicator *indicator)
	Sets the loading indicator. More...

WLoadingIndicator *	loadingIndicator () const
	Returns the loading indicator. More...

void	quit ()
	Quits the application. More...

void	quit (const WString &restartMessage)
	Quits the application. More...

bool	isQuited () const
	Returns whether the application has quit. (deprecated) More...

bool	hasQuit () const
	Returns whether the application has quit. More...

::int64_t	maximumRequestSize () const
	Returns the current maximum size of a request to the application. More...

Signal< ::int64_t > &	requestTooLarge ()
	Signal which indicates that too a large request was received. More...

void	setConfirmCloseMessage (const WString &message)
	Sets the message for the user to confirm closing of the application window/tab. More...

void	enableInternalPaths ()
	Sets the message for the user when the application was .

void	deferRendering ()
	Defers rendering of the current event response. More...

void	resumeRendering ()
	Resumes rendering of a deferred event response. More...

template<typename F >
boost::function< void()>	bind (const F &f)
	Protects a function against deletion of the target object. More...

std::string	encodeUntrustedUrl (const std::string &url) const
	Encodes an untrusted URL to prevent referer leaks. More...

void	pushExposedConstraint (WWidget *w)
	Pushes a (modal) widget onto the expose stack. More...

Style sheets and CSS
WCssStyleSheet &	styleSheet ()
	Returns a reference to the inline style sheet. More...

void	useStyleSheet (const WLink &link, const std::string &media="all")
	Adds an external style sheet. More...

void	useStyleSheet (const WLink &link, const std::string &condition, const std::string &media)
	Conditionally adds an external style sheet. More...

void	useStyleSheet (const WCssStyleSheet &styleSheet, const std::string &condition="")
	Adds an external stylesheet. More...

void	removeStyleSheet (const WLink &link)
	Removes an external stylesheet. More...

void	setTheme (const WTheme *theme)
	Sets the theme. More...

const WTheme *	theme () const
	Returns the theme.

void	setCssTheme (const std::string &name)
	Sets a CSS theme. More...

void	setLayoutDirection (LayoutDirection direction)
	Sets the layout direction. More...

LayoutDirection	layoutDirection () const
	Returns the layout direction. More...

void	setBodyClass (const std::string &styleClass)
	Sets a style class to the entire page <body>. More...

std::string	bodyClass () const
	Returns the style class set for the entire page <body>. More...

void	setHtmlClass (const std::string &styleClass)
	Sets a style class to the entire page <html>. More...

std::string	htmlClass () const
	Returns the style class set for the entire page <html>. More...

URLs and internal paths
std::string	url (const std::string &internalPath=std::string()) const
	Returns a URL for the current session. More...

virtual std::string	makeAbsoluteUrl (const std::string &url) const
	Makes an absolute URL. More...

std::string	resolveRelativeUrl (const std::string &url) const
	"Resolves" a relative URL taking into account internal paths. More...

std::string	bookmarkUrl () const
	Returns a bookmarkable URL for the current internal path. More...

std::string	bookmarkUrl (const std::string &internalPath) const
	Returns a bookmarkable URL for a given internal path. More...

void	setInternalPath (const std::string &path, bool emitChange=false)
	Changes the internal path. More...

void	setInternalPathDefaultValid (bool valid)
	Sets whether an internal path is valid by default. More...

bool	internalPathDefaultValid () const
	Returns whether an internal path is valid by default. More...

void	setInternalPathValid (bool valid)
	Sets whether the current internal path is valid. More...

bool	internalPathValid () const
	Returns whether the current internal path is valid. More...

std::string	internalPath () const
	Returns the current internal path. More...

std::string	internalPathNextPart (const std::string &path) const
	Returns a part of the current internal path. More...

std::string	internalSubPath (const std::string &path) const
	Returns a URL for the current session. More...

bool	internalPathMatches (const std::string &path) const
	Checks if the internal path matches a given path. More...

Signal< std::string > &	internalPathChanged ()
	Signal which indicates that the user changes the internal path. More...

Signal< std::string > &	internalPathInvalid ()
	Signal which indicates that an invalid internal path is navigated.

void	redirect (const std::string &url)
	Redirects the application to another location. More...

Manipulation outside the main event loop
void	enableUpdates (bool enabled=true)
	Enables server-initiated updates. More...

bool	updatesEnabled () const
	Returns whether server-initiated updates are enabled. More...

void	triggerUpdate ()
	Propagates server-initiated updates. More...

UpdateLock	getUpdateLock ()
	Grabs and returns the lock for manipulating widgets outside the event loop (deprecated). More...

void	attachThread (bool attach=true)
	Attach an auxiliary thread to this application. More...

Invoking JavaScript or including scripts
void	doJavaScript (const std::string &javascript, bool afterLoaded=true)
	Executes some JavaScript code. More...

void	addAutoJavaScript (const std::string &javascript)
	Adds JavaScript statements that should be run continuously. More...

void	declareJavaScriptFunction (const std::string &name, const std::string &function)
	Declares an application-wide JavaScript function. More...

bool	require (const std::string &url, const std::string &symbol=std::string())
	Loads a JavaScript library. More...

bool	requireJQuery (const std::string &url)
	Loads a custom JQuery library. More...

bool	customJQuery () const
	Returns whether a custom JQuery library is used. More...

void	setJavaScriptClass (const std::string &className)
	Sets the name of the application JavaScript class. More...

std::string	javaScriptClass ()
	Returns the name of the application JavaScript class. More...

Global keyboard and mouse events
EventSignal< WKeyEvent > &	globalKeyWentDown ()
	Event signal emitted when a keyboard key is pushed down. More...

EventSignal< WKeyEvent > &	globalKeyPressed ()
	Event signal emitted when a "character" was entered. More...

EventSignal< WKeyEvent > &	globalKeyWentUp ()
	Event signal emitted when a keyboard key is released. More...

EventSignal &	globalEnterPressed ()
	Event signal emitted when enter was pressed. More...

EventSignal &	globalEscapePressed ()
	Event signal emitted when escape was pressed. More...

Public Member Functions inherited from Wt::WObject
	WObject (WObject *parent=0)
	Create a WObject with a given parent object. More...

virtual	~WObject ()
	Destructor. More...

virtual const std::string	id () const
	Returns the (unique) identifier for this object. More...

virtual void	setObjectName (const std::string &name)
	Sets an object name. More...

virtual std::string	objectName () const
	Returns the object name. More...

void	resetLearnedSlots ()
	Resets learned stateless slot implementations. More...

template<class T >
void	resetLearnedSlot (void(T::*method)())
	Resets a learned stateless slot implementation. More...

template<class T >
WStatelessSlot *	implementStateless (void(T::*method)())
	Declares a slot to be stateless and learn client-side behaviour on first invocation. More...

template<class T >
WStatelessSlot *	implementStateless (void(T::method)(), void(T::undoMethod)())
	Declares a slot to be stateless and learn client-side behaviour in advance. More...

void	isNotStateless ()
	Marks the current function as not stateless. More...

template<class T >
WStatelessSlot *	implementJavaScript (void(T::*method)(), const std::string &jsCode)
	Provides a JavaScript implementation for a method. More...

void	addChild (WObject *child)
	Adds a child object. More...

virtual void	removeChild (WObject *child)
	Removes a child object. More...

const std::vector< WObject * > &	children () const
	Returns the children.

WObject *	parent () const
	Returns the parent object.

Static Public Member Functions
static WApplication *	instance ()
	Returns the current application instance. More...

static std::string	resourcesUrl ()
	Returns the URL at which the resources are deployed. More...

static std::string	relativeResourcesUrl ()
	Returns the URL at which the resources are deployed. More...

static std::string	appRoot ()
	Returns the appRoot special property. More...

static bool	readConfigurationProperty (const std::string &name, std::string &value)
	Reads a configuration property. More...

Protected Member Functions
virtual void	notify (const WEvent &e)
	Notifies an event to the application. More...

virtual bool	isExposed (WWidget *w) const
	Returns whether a widget is exposed in the interface. More...

virtual void	enableAjax ()
	Progresses to an Ajax-enabled user interface. More...

virtual void	unload ()
	Handles a browser unload event. More...

virtual void	handleJavaScriptError (const std::string &errorText)
	handleJavaScriptError print javaScript errors to log file. You may want to overwrite it to render error page for example. More...

Protected Member Functions inherited from Wt::WObject
virtual WStatelessSlot *	getStateless (Method method)
	On-demand stateless slot implementation. More...

Related Functions
(Note that these are not member functions.)
typedef boost::function< WApplication *(const WEnvironment &)>	ApplicationCreator
	Typedef for a function that creates WApplication objects. More...

Additional Inherited Members
Static Protected Member Functions inherited from Wt::WObject
static WObject *	sender ()
	Returns the sender of the current slot call. More...

Detailed Description

Represents an application instance for a single session.

Each user session of your application has a corresponding WApplication instance. You need to create a new instance and return it as the result of the callback function passed to WRun(). The instance is the main entry point to session information, and holds a reference to the root() of the widget tree.

The recipe for a Wt web application, which allocates new WApplication instances for every user visiting the application is thus:

WApplication *createApplication(const WEnvironment& env)
{
  //
  // Optionally, check the environment and redirect to an error page.
  //
  bool valid = ...;
  WApplication *app;
  if (!valid) {
    app = new WApplication(env);
    app->redirect("error.html");
    app->quit();
  } else {
    // usually you will specialize your application class
    app = new WApplication(env);
    //
    // Add widgets to app->root() and return the application object.
    //
  }
  return app;
}

Throughout the session, the instance is available through WApplication::instance() (or through #wApp). The application may be exited either using the method quit(), or because of a timeout after the user has closed the window, but not because the user does not interact: keep-alive messages in the background will keep the session around as long as the user has the page opened. In either case, the application object is deleted, allowing for cleanup of the entire widget tree, and any other resources.

The WApplication object provides access to session-wide settings, including:

circumstantial information through environment(), which gives details about the user, start-up arguments, and user agent capabilities.
the application title with setTitle().
inline and external style sheets using styleSheet() and useStyleSheet().
inline and external JavaScript using doJavaScript() and require().
the top-level widget in root(), representing the entire browser window, or multiple top-level widgets using bindWidget() when deployed in WidgetSet mode to manage a number of widgets within a 3rd party page.
definition of cookies using setCookie() to persist information across sessions, which may be read using WEnvironment::getCookie() in a future session.
management of the internal path (that enables browser history and bookmarks) using setInternalPath() and related methods.
support for server-initiated updates with enableUpdates()
localization information and message resources bundles using setLocale() and messageResourceBundle().

Member Typedef Documentation

typedef Wt::ApplicationCreator Wt::WApplication::ApplicationCreator

Typedef for a function that creates WApplication objects.

See also: WRun()

Member Enumeration Documentation

enum Wt::WApplication::AjaxMethod

Enumeration that indicates the method for dynamic (AJAX-alike) updates ((deprecated).

See also: setAjaxMethod()

Enumerator
XMLHttpRequest	Using the XMLHttpRequest object (real AJAX)
DynamicScriptTag	Using dynamic script tags (for cross-domain AJAX)

Constructor & Destructor Documentation

Wt::WApplication::WApplication ( const WEnvironment & environment )

Creates a new application instance.

The environment provides information on the initial request, user agent, and deployment-related information.

Wt::WApplication::~WApplication ( )

Destructor.

The destructor deletes the root() container, and as a consequence the entire widget tree.

Member Function Documentation

void Wt::WApplication::addAutoJavaScript ( const std::string & javascript )

Adds JavaScript statements that should be run continuously.

This is an internal method.

It is used by for example layout managers to adjust the layout whenever the DOM tree is manipulated.

See also: doJavaScript()

void Wt::WApplication::addMetaHeader	(	const std::string &	name,
		const WString &	content,
		const std::string &	lang = `""`
	)

Adds a "name" HTML meta header.

See also: addMetaHeader(MetaHeaderType, const std::string&, const WString&, const std::string&)

void Wt::WApplication::addMetaHeader	(	MetaHeaderType	type,
		const std::string &	name,
		const WString &	content,
		const std::string &	lang = `""`
	)

Adds an HTML meta header.

This method sets either a "name" meta headers, which configures a document property, or a "http-equiv" meta headers, which defines a HTTP headers (but these latter headers are being deprecated).

A meta header can however only be added in the following situations:

when a plain HTML session is used (including when the user agent is a bot), you can add meta headers at any time.
or, when progressive bootstrap is used, you can set meta headers for any type of session, from within the application constructor (which corresponds to the initial request).
but never for a Wt::WidgetSet mode application since then the application is hosted within a foreign HTML page.

These situations coincide with WEnvironment::ajax() returning false (see environment()). The reason that it other cases the HTML page has already been rendered, and will not be rerendered since all updates are done dynamically.

As an alternative, you can use the <meta-headers> configuration property in the configuration file, which will be applied in all circumstances.

See also: removeMetaHeader()

void Wt::WApplication::addMetaLink	(	const std::string &	href,
		const std::string &	rel,
		const std::string &	media,
		const std::string &	hreflang,
		const std::string &	type,
		const std::string &	sizes,
		bool	disabled
	)

Adds an HTML meta link.

When a link was previously set for the same href, its contents are replaced. When an empty string is used for the arguments media, hreflang, type or sizes, they will be ignored.

See also: removeMetaLink()

AjaxMethod Wt::WApplication::ajaxMethod ( ) const

Returns the Ajax communication method (deprecated).

See also: setAjaxMethod()

std::string Wt::WApplication::appRoot ( )

static

Returns the appRoot special property.

This returns the "appRoot" property, with a trailing slash added to the end if it was not yet present.

The property "appRoot" was introduced as a generalization of the working directory for the location of files that do not need to be served over http to the client, but are required by the program to run properly. Typically, these are message resource bundles (xml), CSV files, database files (e.g. SQLite files for Wt::Dbo), ...

Some connectors do not allow you to control what the current working directory (CWD) is set to (fcgi, isapi). Instead of referring to files assuming a sensible CWD, it is therefore better to refer to them relative to the application root.

The appRoot property is special in the sense that it can be set implicitly by the connector (see the connector documentation for more info). If it was not set by the connector, it can be set as a normal property in the configuration file (the default wt_config.xml describes how to set properties). If the property is not set at all, it is assumed that the appRoot is CWD and this function will return an empty string.

Usage example:

messageResourceBundle().use(appRoot() + "text");
messageResourceBundle().use(appRoot() + "charts");
Wt::Dbo::backend::Sqlite3 sqlite3_(appRoot() + "planner.db");

See also: WServer::appRoot(), docRoot()

void Wt::WApplication::attachThread ( bool attach = true )

Attach an auxiliary thread to this application.

In a multi-threaded environment, WApplication::instance() uses thread-local data to retrieve the application object that corresponds to the session currently being handled by the thread. This is set automatically by the library whenever an event is delivered to the application, or when you use the UpdateLock to modify the application from an auxiliary thread outside the normal event loop.

When you want to manipulate the widget tree inside the main event loop, but from within an auxiliary thread, then you cannot use the UpdateLock since this will create an immediate dead lock. Instead, you may attach the auxiliary thread to the application, by calling this method from the auxiliary thread, and in this way you can modify the application from within that thread without needing the update lock.

Calling attachThread() with attach = false, detaches the current thread.

template<typename F >

boost::function< void()> Wt::WApplication::bind ( const F & f )

Protects a function against deletion of the target object.

When posting an event using WServer::post(), it is convenient to bind an object method to be called. However, while WServer::post() guarantees that the application to which an event is posted is still alive, it may be that the targeted widget (or WObject in general) has been deleted.

This function wraps such an object method with a protection layer which guarantees that the method is only called when the targeted object is alive, in the same way as how a signal automatically disconnects slots from objects that are being deleted.

You typically will bind the function immediately within the event loop where you register the "callback", and pass this bound function to (typically an external thread) which calls post() later on. What you cannot do is bind the function only later on, since at that time the target object may already have been destroyed.

As with the signal/slot connection tracking mechanism, this requires that the object is a WObject.

void Wt::WApplication::bindWidget	(	WWidget *	widget,
		const std::string &	domId
	)

Binds a top-level widget for a WidgetSet deployment.

This method binds a widget to an existing element with DOM id domId on the page. The element type should correspond with the widget type (e.g. it should be a <div> for a WContainerWidget, or a <table> for a WTable).

See also: root(); Wt::WidgetSet

std::string Wt::WApplication::bodyClass ( ) const

Returns the style class set for the entire page <body>.

See also: setBodyClass()

std::string Wt::WApplication::bookmarkUrl ( ) const

Returns a bookmarkable URL for the current internal path.

Is equivalent to bookmarkUrl(internalPath()), see bookmarkUrl(const std::string&) const.

To obtain a URL that is refers to the current session of the application, use url() instead.

See also: url(), bookmarkUrl(const std::string&) const

std::string Wt::WApplication::bookmarkUrl ( const std::string & internalPath ) const

Returns a bookmarkable URL for a given internal path.

Returns the (relative) URL for this application that includes the internal path internalPath, usable across sessions.

The returned URL concatenates the internal path to the application base URL, and when no JavaScript is available and URL rewriting is used for session-tracking, a session Id is appended to reuse an existing session if available.

See also 10.1 Session management (wt_config.xml) for configuring the session-tracking method.

For the built-in httpd, when the application is deployed at a folder (ending with '/'), only an exact matching path is routed to the application (this can be changed since Wt 3.1.9, see 9.2 Built-in httpd ), making clean URLs impossible. Returned URLs then include a "?_=" encoding for the internal path.

You can use bookmarkUrl() as the destination for a WAnchor, and listen to a click event is attached to a slot that switches to the internal path internalPath (see WAnchor::setRefInternalPath()). In this way, an anchor can be used to switch between internal paths within an application regardless of the situation (browser with or without Ajax support, or a web spider bot), but still generates suitable URLs across sessions, which can be used for bookmarking, opening in a new window/tab, or indexing.

To obtain a URL that refers to the current session of the application, use url() instead.

See also: url(), bookmarkUrl()

Note: the internalPath should be UTF8 encoded (we may fix the API to use WString in the future).

void Wt::WApplication::changeSessionId ( )

Changes the session id.

To mitigate session ID fixation attacks, you should use this method to change the session ID to a new random value after a user has authenticated himself.

See also: sessionId()

const WString& Wt::WApplication::closeMessage ( ) const

Returns the close message.

See also: setConfirmCloseMessage()

bool Wt::WApplication::customJQuery ( ) const

Returns whether a custom JQuery library is used.

See also: requireJQuery(const std::string& url)

void Wt::WApplication::declareJavaScriptFunction	(	const std::string &	name,
		const std::string &	function
	)

Declares an application-wide JavaScript function.

The function is stored in WApplication::javaScriptClass().

The next code snippet declares and invokes function foo:

app->declareJavaScriptFunction("foo",
                               "function(id) { ... }");
...
std::string id("myId");
app->doJavaScript(app->javaScriptClass() + ".foo('" + id + "');");

void Wt::WApplication::deferRendering ( )

Defers rendering of the current event response.

This method defers the rendering of the current event response until resumeRendering() is called. This may be used if you do not want to actively block the current thread while waiting for an event which is needed to complete the current event response. Note that this effectively freezes the user interface, and thus you should only do this if you know that the event you are waiting for will arrive shortly, or there is really nothing more useful for the user to do than wait for the action to complete.

A typical use case is in conjunction with the Http::Client, to defer the rendering while waiting for the Http::Client to complete.

The function may be called multiple times and the number of deferral requests is counted. The current response is deferred until as many calls to resumeRendering() have been performed.

See also: resumeRendering()

std::string Wt::WApplication::docRoot ( ) const

Returns the server document root.

This returns the filesystem path that corresponds to the document root of the webserver.

Note: This does not work reliably for complex webserver configurations (e.g. using FastCGI with Apache and rewrite rules). See also the discussion here.

See also: appRoot()

void Wt::WApplication::doJavaScript	(	const std::string &	javascript,
		bool	afterLoaded = `true`
	)

Executes some JavaScript code.

This method may be used to call some custom javaScript code as part of an event response.

This function does not wait until the JavaScript is run, but returns immediately. The JavaScript will be run after the normal event handling, unless afterLoaded is set to false.

In most situations, it's more robust to use WWidget::doJavaScript() however.

See also: WWidget::doJavaScript(), declareJavaScriptFunction()

void Wt::WApplication::enableAjax ( )

protectedvirtual

Progresses to an Ajax-enabled user interface.

This method is called when the progressive bootstrap method is used, and support for AJAX has been detected. The default behavior will propagate the WWidget::enableAjax() method through the widget hierarchy.

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

See also: WWidget::enableAjax()

void Wt::WApplication::enableUpdates ( bool enabled = true )

Enables server-initiated updates.

By default, updates to the user interface are possible only at startup, during any event (in a slot), or at regular time points using WTimer. This is the normal Wt event loop.

In some cases, one may want to modify the user interface from a second thread, outside the event loop. While this may be worked around by the WTimer, in some cases, there are bandwidth and processing overheads associated which may be unnecessary, and which create a trade-off with time resolution of the updates.

When enabled is true, this enables "server push" (what is called 'comet' in AJAX terminology). Widgets may then be modified, created or deleted outside of the event loop (e.g. in response to execution of another thread), and these changes are propagated by calling triggerUpdate().

There are two ways for safely manipulating a session's UI, with respect to thread-safety and application life-time (the library can decide to terminate an application if it lost connectivity with the browser).

WServer::post()

The easiest and less error-prone solution is to post an event, represented by a function/method call, to a session using WServer::post().

The method is non-blocking: it returns immediately, avoiding dead-lock scenarios. The function is called from within a thread of the server's thread pool, and not if the session has been or is being terminated. The function is called in the context of the targeted application session, and with exclusive access to the session.

WApplication::UpdateLock

A more direct approach is to grab the application's update lock and manipulate the application's state directly from another thread.

At any time, the application may be deleted (e.g. because of a time out or because the user closes the application window). You should thus make sure you do no longer reference an application after it has been deleted. When Wt decides to delete an application, it first runs WApplication::finalize() and then invokes the destructor. While doing this, any other thread trying to grab the update lock will unblock, but the lock will return false. You should therefore always check whether the lock is valid.

An example of how to modify the widget tree outside the event loop and propagate changes is:

// You need to have a reference to the application whose state
// you are about to manipulate.
// You should prevent the application from being deleted somehow,
// before you could grab the application lock.
Wt::WApplication *app = ...;
{
  // Grab the application lock. It is a scoped lock.
  Wt::WApplication::UpdateLock lock(app);
  if (lock) {
    // We now have exclusive access to the application: we can safely modify the widget tree for example.
    app->root()->addWidget(new Wt::WText("Something happened!"));
    // Push the changes to the browser
    app->triggerUpdate();
  }
}

Note: This works only if JavaScript is available on the client.

See also: triggerUpdate()

std::string Wt::WApplication::encodeUntrustedUrl ( const std::string & url ) const

Encodes an untrusted URL to prevent referer leaks.

This encodes an URL so that in case the session ID is present in the current URL, this session ID does not leak to the refenced URL.

Wt will safely handle URLs in the API (in WImage and WAnchor) but you may want to use this function to encode URLs which you use in WTemplate texts.

const WEnvironment & Wt::WApplication::environment ( ) const

Returns the environment information.

This method returns the environment object that was used when constructing the application. The environment provides information on the initial request, user agent, and deployment-related information.

See also: url(), sessionId()

void Wt::WApplication::finalize ( )

virtual

Finalizes the application, pre-destruction.

This method is invoked by the Wt library before destruction of a new application. You may reimplement this method to do additional finalization that is not possible from the destructor (e.g. which uses virtual methods).

WWidget * Wt::WApplication::findWidget ( const std::string & name )

Finds a widget by name.

This finds a widget in the application's widget hierarchy. It does not only consider widgets in the root(), but also widgets that are placed outside this root, such as in dialogs, or other "roots" such as all the bound widgets in a widgetset application.

See also: WWidget::setObjectName(), WWidget::find()

WApplication::UpdateLock Wt::WApplication::getUpdateLock ( )

Grabs and returns the lock for manipulating widgets outside the event loop (deprecated).

You need to keep this lock in scope while manipulating widgets outside of the event loop. In normal cases, inside the Wt event loop, you do not need to care about it.

See also: enableUpdates(), triggerUpdate()

Deprecated:: Use the RAII-style UpdateLock(WApplication *) constructor instead.

EventSignal & Wt::WApplication::globalEnterPressed ( )

Event signal emitted when enter was pressed.