Wt  4.10.4
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions | List of all members
Wt::WApplication Class Reference

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

#include <Wt/WApplication.h>

Inheritance diagram for Wt::WApplication:
[legend]

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 WEnvironmentenvironment () const
 Returns the environment information. More...
 
WContainerWidgetroot () const
 Returns the root container. More...
 
WWidgetfindWidget (const std::string &name)
 Finds a widget by name. More...
 
void setTitle (const WString &title)
 Sets the window title. More...
 
const WStringtitle () const
 Returns the window title. More...
 
const WStringcloseMessage () const
 Returns the close message. More...
 
std::shared_ptr< WLocalizedStringslocalizedStrings ()
 Returns the resource object that provides localized strings. More...
 
void setLocalizedStrings (const std::shared_ptr< WLocalizedStrings > &stringResolver)
 Sets the resource object that provides localized strings. More...
 
WMessageResourceBundlemessageResourceBundle ()
 Returns the message resource bundle. More...
 
void setLocale (const WLocale &locale)
 Changes the locale. More...
 
const WLocalelocale () const
 Returns the current locale. More...
 
virtual void refresh ()
 Refreshes the application. More...
 
void bindWidget (std::unique_ptr< WWidget > widget, const std::string &domId)
 Binds a top-level widget for a EntryPointType::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...
 
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 Http::Cookie &cookie)
 Sets a new cookie. 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 Http::Cookie &cookie)
 Removes a 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 (std::unique_ptr< WLoadingIndicator > indicator)
 Sets the loading indicator. More...
 
WLoadingIndicatorloadingIndicator () const
 Returns the loading indicator. More...
 
void quit ()
 Quits the application. More...
 
void quit (const WString &restartMessage)
 Quits the application. 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 deferRendering ()
 Defers rendering of the current event response. More...
 
void resumeRendering ()
 Resumes rendering of a deferred event response. 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...
 
void suspend (std::chrono::seconds duration)
 Suspend the application. More...
 
Signalunsuspended ()
 Signal that is emitted when the application is no longer suspended. More...
 
Style sheets and CSS
WCssStyleSheetstyleSheet ()
 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 WLinkedCssStyleSheet &styleSheet, const std::string &condition="")
 Adds an external stylesheet. More...
 
void removeStyleSheet (const WLink &link)
 Removes an external stylesheet. More...
 
void setTheme (const std::shared_ptr< WTheme > &theme)
 Sets the theme. More...
 
std::shared_ptr< WThemetheme () 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...
 
void setHtmlAttribute (const std::string &name, const std::string &value)
 Sets an attribute for the entire page <html> element. More...
 
WString htmlAttribute (const std::string &name) const
 Returns the current <html> element attribute value of the specified name. More...
 
void setBodyAttribute (const std::string &name, const std::string &value)
 Sets an attribute for the entire page <body> element. More...
 
WString bodyAttribute (const std::string &name) const
 Returns the current <body> element attribute value of the specified name. 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
 
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...
 
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...
 
EventSignalglobalEnterPressed ()
 Event signal emitted when enter was pressed. More...
 
EventSignalglobalEscapePressed ()
 Event signal emitted when escape was pressed. More...
 
- Public Member Functions inherited from Wt::WObject
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. More...
 
std::unique_ptr< WObjectremoveChild (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. 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...
 
- Public Member Functions inherited from Wt::Core::observable
 observable () noexcept
 Default constructor.
 
virtual ~observable ()
 Destructor. More...
 
template<typename... Args, typename C >
auto bindSafe (void(C::*method)(Args...)) noexcept
 Protects a method call against object destruction. More...
 
template<typename... Args, typename C >
auto bindSafe (void(C::*method)(Args...) const) const noexcept
 Protects a const method call against object destruction. More...
 
template<typename Function >
auto bindSafe (const Function &function) noexcept
 Protects a function against object destruction. More...
 

Static Public Member Functions

static WApplicationinstance ()
 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 idleTimeout ()
 Idle timeout handler. 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 std::function< std::unique_ptr< WApplication >const WEnvironment &)> ApplicationCreator
 Typedef for a function that creates WApplication objects. 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:

std::unique_ptr<WApplication> createApplication(const WEnvironment& env)
{
//
// Optionally, check the environment and redirect to an error page.
//
bool valid = ...;
std::unique_ptr<WApplication> app;
if (!valid) {
app = std::make_unique<WApplication>(env);
app->redirect("error.html");
app->quit();
} else {
// usually you will specialize your application class
app = std::make_unique<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:

Member Typedef Documentation

◆ ApplicationCreator

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

Typedef for a function that creates WApplication objects.

See also
WRun()

Constructor & Destructor Documentation

◆ WApplication()

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.

◆ ~WApplication()

Wt::WApplication::~WApplication ( )

Destructor.

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

Member Function Documentation

◆ addAutoJavaScript()

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()

◆ addMetaHeader() [1/2]

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

◆ addMetaHeader() [2/2]

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::EntryPointType::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()

◆ addMetaLink()

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()

◆ appRoot()

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:

auto sqlite3_ = std::make_unique<Wt::Dbo::backend::Sqlite3>(appRoot() + "planner.db");
WMessageResourceBundle & messageResourceBundle()
Returns the message resource bundle.
Definition: WApplication.C:353
static std::string appRoot()
Returns the appRoot special property.
Definition: WApplication.C:502
void use(const std::string &path, bool loadInMemory=true)
Adds a (series) of message resource files to be used.
Definition: WMessageResourceBundle.C:18
See also
WServer::appRoot(), docRoot()

◆ attachThread()

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.

◆ bindWidget()

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

Binds a top-level widget for a EntryPointType::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::EntryPointType::WidgetSet

◆ bodyAttribute()

WString Wt::WApplication::bodyAttribute ( const std::string &  name) const

Returns the current <body> element attribute value of the specified name.

See also
setBodyAttribute(), htmlAttribute()

◆ bodyClass()

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

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

See also
setBodyClass()

◆ bookmarkUrl() [1/2]

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

◆ bookmarkUrl() [2/2]

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.1 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 CharEncoding::UTF8 encoded (we may fix the API to use WString in the future).

◆ changeSessionId()

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()

◆ closeMessage()

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

Returns the close message.

See also
setConfirmCloseMessage()

◆ customJQuery()

bool Wt::WApplication::customJQuery ( ) const

Returns whether a custom JQuery library is used.

See also
requireJQuery(const std::string& url)
Deprecated:
Wt no longer loads jQuery by default, making the use of requireJQuery() and thus customJQuery() obsolete.

◆ declareJavaScriptFunction()

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 + "');");
virtual const std::string id() const
Returns the (unique) identifier for this object.
Definition: WObject.C:64

◆ deferRendering()

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()

◆ docRoot()

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()

◆ doJavaScript()

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()

◆ enableAjax()

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()

◆ enableUpdates()

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.
if (lock) {
// We now have exclusive access to the application: we can safely modify the widget tree for example.
app->root()->addWidget(std::make_unique<Wt::WText>("Something happened!"));
// Push the changes to the browser
app->triggerUpdate();
}
}
A RAII lock for manipulating and updating the application and its widgets outside of the event loop.
Definition: WApplication.h:1340
Represents an application instance for a single session.
Definition: WApplication.h:211
WContainerWidget * root() const
Returns the root container.
Definition: WApplication.h:288
void triggerUpdate()
Propagates server-initiated updates.
Definition: WApplication.C:1508
virtual void addWidget(std::unique_ptr< WWidget > widget)
Adds a child widget to this container.
Definition: WContainerWidget.C:115
Note
This works only if JavaScript is available on the client.
See also
triggerUpdate()

◆ encodeUntrustedUrl()

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.

◆ environment()

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()

◆ finalize()

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).

◆ findWidget()

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()

◆ globalEnterPressed()

EventSignal & Wt::WApplication::globalEnterPressed ( )

Event signal emitted when enter was pressed.

The application receives key events when no widget currently has focus. Otherwise, key events are handled by the widget in focus, and its ancestors.

See also
See WInteractWidget::enterPressed()

◆ globalEscapePressed()

EventSignal & Wt::WApplication::globalEscapePressed ( )

Event signal emitted when escape was pressed.

The application receives key events when no widget currently has focus. Otherwise, key events are handled by the widget in focus, and its ancestors.

See also
See WInteractWidget::escapePressed()

◆ globalKeyPressed()

EventSignal< WKeyEvent > & Wt::WApplication::globalKeyPressed ( )

Event signal emitted when a "character" was entered.

The application receives key events when no widget currently has focus. Otherwise, key events are handled by the widget in focus, and its ancestors.

See also
See WInteractWidget::keyPressed()

◆ globalKeyWentDown()

EventSignal< WKeyEvent > & Wt::WApplication::globalKeyWentDown ( )

Event signal emitted when a keyboard key is pushed down.

The application receives key events when no widget currently has focus. Otherwise, key events are handled by the widget in focus, and its ancestors.

See also
See WInteractWidget::keyWentDown()

◆ globalKeyWentUp()

EventSignal< WKeyEvent > & Wt::WApplication::globalKeyWentUp ( )

Event signal emitted when a keyboard key is released.

The application receives key events when no widget currently has focus. Otherwise, key events are handled by the widget in focus, and its ancestors.

See also
See WInteractWidget::keyWentUp()

◆ handleJavaScriptError()

void Wt::WApplication::handleJavaScriptError ( const std::string &  errorText)
protectedvirtual

handleJavaScriptError print javaScript errors to log file. You may want to overwrite it to render error page for example.

Parameters
errorTextthe error will usually be in json format.

◆ hasQuit()

bool Wt::WApplication::hasQuit ( ) const

Returns whether the application has quit.

See also
quit()

◆ htmlAttribute()

WString Wt::WApplication::htmlAttribute ( const std::string &  name) const

Returns the current <html> element attribute value of the specified name.

See also
setHtmlAttribute(), bodyAttribute()

◆ htmlClass()

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

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

See also
setHtmlClass()

◆ idleTimeout()

void Wt::WApplication::idleTimeout ( )
protectedvirtual

Idle timeout handler.

If idle-timeout is set in the configuration, this method is called when the user seems idle for the number of seconds set in idle-timeout.

This feature can be useful in security sensitive applications to prevent unauthorized users from taking over the session of a user that has moved away from or left behind the device from which they are accessing the Wt application.

The default implementation logs that a timeout has occurred, and calls quit().

This method can be overridden to specify different timeout behaviour, e.g. to show a dialog that a user's session has expired, or that the session is about to expire.

Example for an expiration dialog:

class MyApplication : public Wt::WApplication {
public:
MyApplication(Wt::WEnvironment &env)
: WApplication(env)
{ }
protected:
virtual void idleTimeout() override
{
if (idleTimeoutDialog_)
return; // Prevent multiple dialogs
idleTimeoutDialog_ = addChild(std::make_unique<Wt::WDialog>("Idle timeout"));
idleTimeoutDialog_->contents()->addNew<Wt::WText>("This session will automatically quit in 1 minute, "
"press 'abort' to continue using the application");
auto btn = idleTimeoutDialog_->footer()->addNew<Wt::WPushButton>("abort");
btn->clicked().connect([this]{
removeChild(idleTimeoutDialog_.get());
});
auto timer = idleTimeoutDialog_->addChild(std::make_unique<Wt::WTimer>());
timer->setInterval(std::chrono::seconds{60});
timer->setSingleShot(true);
timer->timeout().connect([this]{
quit();
});
timer->start();
idleTimeoutDialog_->show();
}
private:
};
A safe smart pointer for an observable.
Definition: observing_ptr.hpp:44
virtual void idleTimeout()
Idle timeout handler.
Definition: WApplication.C:820
void quit()
Quits the application.
Definition: WApplication.C:769
A class that captures information on the application environment.
Definition: WEnvironment.h:129
EventSignal< WMouseEvent > & clicked()
Event signal emitted when the primary mouse button was clicked on this widget.
Definition: WInteractWidget.C:99
void addChild(std::unique_ptr< WObject > child)
Add a child WObject whose lifetime is determined by this WObject.
Definition: WObject.C:36
std::unique_ptr< WObject > removeChild(WObject *child)
Remove a child WObject, so its lifetime is no longer determined by this WObject.
Definition: WObject.C:41
A widget that represents a push button.
Definition: WPushButton.h:42
A widget that renders (XHTML) text.
Definition: WText.h:92
Note
The events currently counted as user activity are:
  • mousedown
  • mouseup
  • wheel
  • keydown
  • keyup
  • touchstart
  • touchend
  • pointerdown
  • pointerup

◆ initialize()

void Wt::WApplication::initialize ( )
virtual

Initializes the application, post-construction.

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

◆ instance()

WApplication * Wt::WApplication::instance ( )
static

Returns the current application instance.

This is the same as the global define #wApp. In a multi-threaded server, this method uses thread-specific storage to fetch the current session.

◆ internalPath()

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

Returns the current internal path.

When the application is just created, this is equal to WEnvironment::internalPath().

See also
setInternalPath(), internalPathNextPart(), internalPathMatches()
Note
the returned path is CharEncoding::UTF8 (we may fix the API to use WString in the future).

◆ internalPathChanged()

Signal< std::string > & Wt::WApplication::internalPathChanged ( )

Signal which indicates that the user changes the internal path.

This signal indicates a change to the internal path, which is usually triggered by the user using the browser back/forward buttons.

The argument contains the new internal path.

See also
setInternalPath()
Note
the internal path is CharEncoding::UTF8 encoded (we may fix the API to use WString in the future).

◆ internalPathDefaultValid()

bool Wt::WApplication::internalPathDefaultValid ( ) const

Returns whether an internal path is valid by default.

See also
setInternalPathDefaultValid()

◆ internalPathMatches()

bool Wt::WApplication::internalPathMatches ( const std::string &  path) const

Checks if the internal path matches a given path.

Returns whether the current internalPath() starts with path (or is equal to path). You will typically use this method within a slot conneted to the internalPathChanged() signal, to check that an internal path change affects the widget. It may also be useful before changing path using setInternalPath() if you do not intend to remove sub paths when the current internal path already matches path.

The path must start with a '/'.

See also
setInternalPath(), internalPath()
Note
the internal path is CharEncoding::UTF8 encoded (we may fix the API to use WString in the future).

◆ internalPathNextPart()

std::string Wt::WApplication::internalPathNextPart ( const std::string &  path) const

Returns a part of the current internal path.

This is a convenience method which returns the next folder in the internal path, after the given path.

For example, when the current internal path is "/project/z3cbc/details", this method returns "details" when called with "/project/z3cbc/" as path argument.

The path must start with a '/', and internalPathMatches() should evaluate to true for the given path. If not, an empty string is returned and an error message is logged.

See also
internalPath(), internalPathChanged()
Note
the internal path is CharEncoding::UTF8 encoded (we may fix the API to use WString in the future).

◆ internalPathValid()

bool Wt::WApplication::internalPathValid ( ) const

Returns whether the current internal path is valid.

See also
setInternalPathValid()

◆ isExposed()

bool Wt::WApplication::isExposed ( WWidget w) const
protectedvirtual

Returns whether a widget is exposed in the interface.

The default implementation simply returns true, unless a modal dialog is active, in which case it returns true only for widgets that are inside the dialog.

You may want to reimplement this method if you wish to disallow events from certain widgets even when they are inserted in the widget hierachy.

◆ javaScriptClass()

std::string Wt::WApplication::javaScriptClass ( )

Returns the name of the application JavaScript class.

This JavaScript class encapsulates all JavaScript methods specific to this application instance. The method is foreseen to allow multiple applications to run simultaneously on the same page in Wt::WidgtSet mode, without interfering.

◆ layoutDirection()

LayoutDirection Wt::WApplication::layoutDirection ( ) const

Returns the layout direction.

See also
setLayoutDirection()

◆ loadingIndicator()

WLoadingIndicator* Wt::WApplication::loadingIndicator ( ) const

Returns the loading indicator.

See also
setLoadingIndicator()

◆ locale()

const WLocale& Wt::WApplication::locale ( ) const

Returns the current locale.

See also
setLocale(const WLocale&)

◆ localizedStrings()

std::shared_ptr< WLocalizedStrings > Wt::WApplication::localizedStrings ( )

Returns the resource object that provides localized strings.

The default value is a WMessageResourceBundle instance, which uses XML files to resolve localized strings, but you can set a custom class using setLocalizedStrings().

WString::tr() is used to create localized strings, whose localized translation is looked up through this object, using a key.

See also
WString::tr(), messageResourceBundle()

◆ log()

WLogEntry Wt::WApplication::log ( const std::string &  type) const

Adds an entry to the application log.

Starts a new log entry of the given type in the Wt application log file. This method returns a stream-like object to which the message may be streamed.

A typical usage would be:

wApp->log("notice") << "User " << userName << " logged in successfully.";

This would create a log entry that looks like:

[2008-Jul-13 14:01:17.817348] 16879 [/app.wt Z2gCmSxIGjLHD73L] [notice] "User bart logged in successfully."
   * 
See also
10.2 General application settings (wt_config.xml)

◆ makeAbsoluteUrl()

std::string Wt::WApplication::makeAbsoluteUrl ( const std::string &  url) const
virtual

Makes an absolute URL.

Returns an absolute URL for a given (relative url) by including the schema, hostname, and deployment path.

If url is "", then the absolute base URL is returned. This is the absolute URL at which the application is deployed, up to the last '/'.

The default implementation is not complete: it does not handle relative URL path segments with '..'. It just handles the cases that are necessary for Wt.

This is not used in the library, except when a public URL is needed, e.g. for inclusion in an email.

You may want to reimplement this method when the application is hosted behind a reverse proxy or in general the public URL of the application cannot be guessed correctly by the application.

◆ maximumRequestSize()

int64_t Wt::WApplication::maximumRequestSize ( ) const

Returns the current maximum size of a request to the application.

The returned value is the maximum request size in bytes.

The maximum request size is configured in the configuration file, see 10.2 General application settings (wt_config.xml).

See also
requestTooLarge()

◆ messageResourceBundle()

WMessageResourceBundle & Wt::WApplication::messageResourceBundle ( )

Returns the message resource bundle.

The message resource bundle defines the list of external XML files that are used to lookup localized strings.

The default localizedStrings() is a WMessageResourceBundle object, and this method returns localizedStrings() downcasted to this type.

Exceptions
WExceptionwhen localizedStrings() is not a WMessageResourceBundle
See also
WString::tr(const char *key)

◆ metaHeader()

WString Wt::WApplication::metaHeader ( MetaHeaderType  type,
const std::string &  name 
) const

Returns a meta header value.

See also
addMetaHeader()

◆ notify()

void Wt::WApplication::notify ( const WEvent e)
protectedvirtual

Notifies an event to the application.

This method is called by the event loop for propagating an event to the application. It provides a single point of entry for events to the application, besides the application constructor.

You may want to reimplement this method for two reasons:

  • for having a single point for exception handling: while you may want to catch recoverable exceptions in a more appropriate place, general (usually fatal) exceptions may be caught here. You will probably want to catch the same exceptions in the application constructor in the same way.
  • you want to manage resource usage during requests. For example, at the end of request handling, you want to return a database session back to the pool. Since notify() is also used for rendering right after the application is created, this will also clean up resources after application construction.

In either case, you will need to call the base class implementation of notify(), as otherwise no events will be delivered to your application.

The following shows a generic template for reimplementhing this method for both managing request resources and generic exception handling.

MyApplication::notify(const WEvent& event)
{
// Grab resources for during request handling
try {
} catch (MyException& exception) {
// handle this exception in a central place
}
// Free resources used during request handling
}
virtual void notify(const WEvent &e)
Notifies an event to the application.
Definition: WApplication.C:1657

Note that any uncaught exception throw during event handling terminates the session.

◆ processEvents()

void Wt::WApplication::processEvents ( )

Processes UI events.

You may call this method during a long operation to:

  • propagate widget changes to the client.
  • process UI events.

This method starts a recursive event loop, blocking the current thread, and resumes when all pending user interface events have been processed.

Because a thread is blocked, this may affect your application scalability.

◆ pushExposedConstraint()

void Wt::WApplication::pushExposedConstraint ( WWidget w)

Pushes a (modal) widget onto the expose stack.

This defines a new context of widgets that are currently visible.

◆ quit() [1/2]

void Wt::WApplication::quit ( )

Quits the application.

This quits the application with a default restart message resolved as WString::tr("Wt.QuittedMessage").

See also
quit(const WString&)

◆ quit() [2/2]

void Wt::WApplication::quit ( const WString restartMessage)

Quits the application.

The method returns immediately, but has as effect that the application will be terminated after the current event is completed.

The current widget tree (including any modifications still pending and applied during the current event handling) will still be rendered, after which the application is terminated.

If the restart message is not empty, then the user will be offered to restart the application (using the provided message) when further interacting with the application.

See also
redirect()

◆ readConfigurationProperty()

bool Wt::WApplication::readConfigurationProperty ( const std::string &  name,
std::string &  value 
)
static

Reads a configuration property.

Tries to read a configured value for the property name. The method returns whether a value is defined for the property, and sets it to value.

See also
WServer::readConfigurationProperty()

◆ redirect()

void Wt::WApplication::redirect ( const std::string &  url)

Redirects the application to another location.

The client will be redirected to a new location identified by url. Use this in conjunction with quit() if you want the application to be terminated as well.

Calling redirect() does not imply quit() since it may be useful to switch between a non-secure and secure (SSL) transport connection.

◆ refresh()

void Wt::WApplication::refresh ( )
virtual

Refreshes the application.

This lets the application refresh its data, including strings from message resource bundles. This is done by propagating WWidget::refresh() through the widget hierarchy.

This method is also called when the user hits the refresh (or reload) button, if this can be caught within the current session.

The reload button may only be caught when Wt is configured so that reload should not spawn a new session. When URL rewriting is used for session tracking, this will cause an ugly session ID to be added to the URL. See 10.1 Session management (wt_config.xml) for configuring the reload behavior ("<reload-is-new-session>").

See also
WWidget::refresh()

◆ relativeResourcesUrl()

std::string Wt::WApplication::relativeResourcesUrl ( )
static

Returns the URL at which the resources are deployed.

This returns the value of the 'resources' property set in the configuration file, and may thus be a URL relative to the deployment path.

See also
resolveRelativeUrl()

◆ removeCookie() [1/2]

void Wt::WApplication::removeCookie ( const Http::Cookie cookie)

Removes a cookie.

The cookie will be removed if it has the same name, domain and path as the original cookie (RFC-6265, section 5.3.11).

See also
setCookie(const Http::Cookie&)

◆ removeCookie() [2/2]

void Wt::WApplication::removeCookie ( const std::string &  name,
const std::string &  domain = "",
const std::string &  path = "" 
)

Removes a cookie.

See also
setCookie()
Deprecated:
Use removeCookie(const Http::Cookie&) instead.

◆ removeMetaHeader()

void Wt::WApplication::removeMetaHeader ( MetaHeaderType  type,
const std::string &  name = "" 
)

Removes one or all meta headers.

Removes the meta header with given type and name (if it is present). If name is empty, all meta headers of the given type are removed.

See also
addMetaHeader()

◆ removeMetaLink()

void Wt::WApplication::removeMetaLink ( const std::string &  href)

Removes the HTML meta link.

See also
addMetaLink()

◆ removeStyleSheet()

void Wt::WApplication::removeStyleSheet ( const WLink link)

Removes an external stylesheet.

See also
styleSheet(), useStyleSheet(const std::string&, const std::string&)
WWidget::setStyleClass()

◆ requestTooLarge()

Signal< ::int64_t>& Wt::WApplication::requestTooLarge ( )

Signal which indicates that too a large request was received.

The integer parameter is the request size that was received in bytes.

◆ require()

bool Wt::WApplication::require ( const std::string &  url,
const std::string &  symbol = std::string() 
)

Loads a JavaScript library.

Loads a JavaScript library located at the URL url. Wt keeps track of libraries (with the same URL) that already have been loaded, and will load a library only once. In addition, you may provide a symbol which if already defined will also indicate that the library was already loaded (possibly outside of Wt when in EntryPointType::WidgetSet mode).

This method returns true only when the library is loaded for the first time.

JavaScript libraries may be loaded at any point in time. Any JavaScript code is deferred until the library is loaded, except for JavaScript that was defined to load before, passing false as second parameter to doJavaScript().

◆ requireJQuery()

bool Wt::WApplication::requireJQuery ( const std::string &  url)

Loads a custom JQuery library.

For Wt versions before 4.9.0, this function was used to load a different version of jQuery than the one included in Wt. Since Wt 4.9.0 however, Wt no longer relies on jQuery and does not load jQuery by default. If your application relies on jQuery, use require() instead.

Calling this function makes customJQuery() return true, and calls:

return require(url, "$");
std::string url(const std::string &internalPath=std::string()) const
Returns a URL for the current session.
Definition: WApplication.C:754
bool require(const std::string &url, const std::string &symbol=std::string())
Loads a JavaScript library.
Definition: WApplication.C:1677
Deprecated:
Wt no longer loads jQuery by default, making a separate requireJQuery() function unnecessary, use require() instead

◆ resolveRelativeUrl()

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

"Resolves" a relative URL taking into account internal paths.

This resolves the relative URL against the base path of the application, so that it will point to the correct path regardless of the current internal path, e.g. if the application is deployed at http://example.com/one and we're at the internal path /two/, so that the full URL is http://example.com/one/two/, the output of the input URL three will point to http://example.com/three, and not http://example.com/one/two/three.

If the given url is the empty string, the result will point to the base path of the application.

See the table below for more examples.

When you would want to use resolveRelativeUrl:

Using HTML5 History API or in a plain HTML session (without ugly internal paths), the internal path is present as a full part of the URL. This has a consequence that relative URLs, if not dealt with, would be resolved against the last 'folder' name of the internal path, rather than against the application deployment path (which is what you probably want).

When using a widgetset mode deployment, or when configuring a baseURL property in the configuration, this method will make an absolute URL so that the property is fetched from the right server.

Otherwise, this method will fixup a relative URL so that it resolves correctly against the base path of an application. This does not necessarily mean that the URL is resolved into an absolute URL. In fact, Wt will simply prepend a sequence of "../" path elements to correct for the internal path. When passed an absolute URL (i.e. starting with '/'), the url is returned unchanged.

For URLs passed to the Wt API (and of which the library knows it represents a URL) this method is called internally by the library. But it may be useful for URLs which are set e.g. inside a WTemplate.

Examples

Note that whether the deployment path and entry point ends with a slash is significant. Below are some examples with the deployment path in red and the internal path in blue.

Current full pathurl argumentResult points to
http://example.com/foo/bar/internal/path
Deployment path: /foo/bar (no slash at the end)
Internal path: /internal/path
(empty string)http://example.com/foo/bar
.http://example.com/foo/
./http://example.com/foo/
../http://example.com/
http://example.com/foo/bar/internal/path
Deployment path: /foo/bar/ (with slash at the end)
Internal path: /internal/path
Note that the slash between the deployment path and the internal path is shared
(empty string)http://example.com/foo/bar/
.http://example.com/foo/bar/
./http://example.com/foo/bar/
../http://example.com/foo/

◆ resourcesUrl()

std::string Wt::WApplication::resourcesUrl ( )
static

Returns the URL at which the resources are deployed.

Returns resolveRelativeUrl(relativeResourcesUrl())

◆ resumeRendering()

void Wt::WApplication::resumeRendering ( )

Resumes rendering of a deferred event response.

See also
deferRendering()

◆ root()

WContainerWidget* Wt::WApplication::root ( ) const

Returns the root container.

This is the top-level widget container of the application, and corresponds to entire browser window. The user interface of your application is represented by the content of this container.

The root() widget is only defined when the application manages the entire window. When deployed as a EntryPointType::WidgetSet application, there is no root() container, and 0 is returned. Instead, use bindWidget() to bind one or more root widgets to existing HTML <div> (or other) elements on the page.

◆ sessionId()

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

Returns the unique identifier for the current session.

The session id is a string that uniquely identifies the current session. Note that the actual contents has no particular meaning and client applications should in no way try to interpret its value.

◆ setBodyAttribute()

void Wt::WApplication::setBodyAttribute ( const std::string &  name,
const std::string &  value 
)

Sets an attribute for the entire page <body> element.

This allows you to set any of the global attributes (see: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes) on the <body> tag. As well as any tags specific to that tag (see: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body).

Note
If the value contains more complex JavaScript, make sure that " and ' are properly escaped. Otherwise you may encounter JavaScript errors.
See also
bodyAttribute(), setHtmlAttribute()

◆ setBodyClass()

void Wt::WApplication::setBodyClass ( const std::string &  styleClass)

Sets a style class to the entire page <body>.

See also
setHtmlClass()

◆ setConfirmCloseMessage()

void Wt::WApplication::setConfirmCloseMessage ( const WString message)

Sets the message for the user to confirm closing of the application window/tab.

If the message is empty, then the user may navigate away from the page without confirmation.

Otherwise the user will be prompted with a browser-specific dialog asking him to confirm leaving the page. This message is added to the page.

See also
unload()

◆ setConnectionMonitor()

void Wt::WApplication::setConnectionMonitor ( const std::string &  jsObject)

Sets a client-side connection monitor.

This can be used to be notified, in the browser, of changes in connection state between the browser and the server. The passed jsObject should be an object that has the following prototype:

{
onChange: function(type, oldValue, newValue) { ... }
}

The 'onChange' function will be called on an connection status change event. The following types are defined:

  • "connectionStatus": 0 = disconnected, 1 = connected
  • "websocket": true = websocket is used, false = websocket is not used

The current state is also stored in a 'status' object inside the connection monitor.

Example usage:

app.setConnectionMonitor("{ onChange: function(type, ov, nv) { console.log(type, ov, nv); } }");

◆ setCookie() [1/2]

void Wt::WApplication::setCookie ( const Http::Cookie cookie)

Sets a new cookie.

Use cookies to transfer information across different sessions (e.g. a user name). In a subsequent session you will be able to read this cookie using WEnvironment::getCookie(). You cannot use a cookie to store information in the current session.

For more information on how to configure cookies, see the Http::Cookie class.

Note
Wt provides session tracking automatically, and may be configured to use a cookie for this. You only need to use cookies yourself if you want to remember some information (like a logged in identity) across sessions.
See also
WEnvironment::supportsCookies(), WEnvironment::getCookie()

◆ setCookie() [2/2]

void Wt::WApplication::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.

Use cookies to transfer information across different sessions (e.g. a user name). In a subsequent session you will be able to read this cookie using WEnvironment::getCookie(). You cannot use a cookie to store information in the current session.

The name must be a valid cookie name (of type 'token': no special characters or separators, see RFC2616 page 16). The value may be anything. Specify the maximum age (in seconds) after which the client must discard the cookie. To delete a cookie, use a value of '0'.

By default the cookie only applies to the application deployment path (WEnvironment::deploymentPath()) in the current domain. To set a proper value for domain, see also RFC2109.

Note
Wt provides session tracking automatically, and may be configured to use a cookie for this. You only need to use cookies yourself if you want to remember some information (like a logged in identity) across sessions.
See also
WEnvironment::supportsCookies(), WEnvironment::getCookie()
Deprecated:
Use setCookie(const Http::Cookie&) instead.

◆ setCssTheme()

void Wt::WApplication::setCssTheme ( const std::string &  name)

Sets a CSS theme.

This sets a WCssTheme as theme.

The theme provides the look and feel of several built-in widgets, using CSS style rules. Rules for each CSS theme are defined in the resources/themes/name/ folder.

The default theme is "default". Setting an empty theme "" will result in a stub CSS theme that does not load any stylesheets.

◆ setHtmlAttribute()

void Wt::WApplication::setHtmlAttribute ( const std::string &  name,
const std::string &  value 
)

Sets an attribute for the entire page <html> element.

This allows you to set any of the global attributes (see: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes) on the <html> tag. As well as any tags specific to that tag (see: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/html).

Note
If the value contains more complex JavaScript, make sure that " and ' are properly escaped. Otherwise you may encounter JavaScript errors.
This can control the <html>'s class, dir, and lang as well, but this should generally be avoided, since the application manages that separately.
See also
htmlAttribute(), setBodyAttribute()

◆ setHtmlClass()

void Wt::WApplication::setHtmlClass ( const std::string &  styleClass)

Sets a style class to the entire page <html>.

See also
setBodyClass()

◆ setInternalPath()

void Wt::WApplication::setInternalPath ( const std::string &  path,
bool  emitChange = false 
)

Changes the internal path.

A Wt application may manage multiple virtual paths. The virtual path is appended to the application URL. Depending on the situation, the path is directly appended to the application URL or it is appended using a name anchor (#).

For example, for an application deployed at:

http://www.mydomain.com/stuff/app.wt

for which an internalPath "/project/z3cbc/details/" is set, the two forms for the application URL are:

  • in an AJAX session (HTML5):
    http://www.mydomain.com/stuff/app.wt/project/z3cbc/details/
  • in an AJAX session (HTML4):
    http://www.mydomain.com/stuff/app.wt#/project/z3cbc/details/
  • in a plain HTML session:
    http://www.mydomain.com/stuff/app.wt/project/z3cbc/details/

Note, since Wt 3.1.9, the actual form of the URL no longer affects relative URL resolution, since now Wt includes an HTML meta base tag which points to the deployment path, regardless of the current internal path. This does break deployments behind a reverse proxy which changes paths.

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.1 Built-in httpd ), making clean URLs impossible. Returned URLs then include a "?_=" encoding for the internal path:

http://www.mydomain.com/stuff/?_=/project/z3cbc/details/

When the internal path is changed, an entry is added to the browser history. When the user navigates back and forward through this history (using the browser back/forward buttons), an internalPathChanged() event is emitted. You should listen to this signal to switch the application to the corresponding state. When emitChange is true, this signal is also emitted by setting the path (but only if the path is actually changed).

A url that includes the internal path may be obtained using bookmarkUrl().

The internalPath must start with a '/'. In this way, you can still use normal anchors in your HTML. Internal path changes initiated in the browser to paths that do not start with a '/' are ignored.

The emitChange parameter determines whether calling this method causes the internalPathChanged() signal to be emitted.

See also
bookmarkUrl(), internalPath(), internalPathChanged()
Note
the path should be CharEncoding::UTF8 encoded (we may fix the API to use WString in the future).

◆ setInternalPathDefaultValid()

void Wt::WApplication::setInternalPathDefaultValid ( bool  valid)

Sets whether an internal path is valid by default.

This configures how you treat (invalid) internal paths. If an internal path is treated valid by default then you need to call setInternalPath(false) for an invalid path. If on the other hand you treat an internal path as invalid by default, then you need to call setInternalPath(true) for a valid path.

A user which opens an invalid internal path will receive a HTTP 404-Not Found response code (if sent an HTML response).

The default value is true.

◆ setInternalPathValid()

void Wt::WApplication::setInternalPathValid ( bool  valid)

Sets whether the current internal path is valid.

You can use this function in response to an internal path change event (or at application startup) to indicate whether the new (or initial) internal path is valid. This has only an effect on plain HTML sessions, or on the first response in an application deployed with progressive bootstrap settings, as this generates then a 404 Not-Found response.

See also
internalPathChanged(), setInternalPathDefaultValid()

◆ setJavaScriptClass()

void Wt::WApplication::setJavaScriptClass ( const std::string &  className)

Sets the name of the application JavaScript class.

This should be called right after construction of the application, and changing the JavaScript class is only supported for EntryPointType::WidgetSet mode applications. The className should be a valid JavaScript identifier, and should also be unique in a single page.

◆ setLayoutDirection()

void Wt::WApplication::setLayoutDirection ( LayoutDirection  direction)

Sets the layout direction.

The default direction is LayoutDirection::LeftToRight.

This sets the language text direction, which by itself sets the default text alignment and reverse the column orders of <table> elements.

In addition, Wt will take this setting into account in WTextEdit, WTableView and WTreeView (so that columns are reverted), and swap the behaviour of WWidget::setFloatSide() and WWidget::setOffsets() for LayoutDirection::RightToLeft languages. Note that CSS settings themselves are not affected by this setting, and thus for example "float: right" will move a box to the right, irrespective of the layout direction.

The library sets "Wt-ltr" or "Wt-rtl" as style classes for the document body. You may use this if to override certain style rules for a Right-to-Left document.

The only valid values are LayoutDirection::LeftToRight or LayoutDirection::RightToLeft.

For example:

body .sidebar { float: right; }
body.Wt-rtl .sidebar { float: left; }
Note
The layout direction can be set only at application startup and does not have the effect of rerendering the entire UI.

◆ setLoadingIndicator()

void Wt::WApplication::setLoadingIndicator ( std::unique_ptr< WLoadingIndicator indicator)

Sets the loading indicator.

The loading indicator is shown to indicate that a response from the server is pending or JavaScript is being evaluated.

The default loading indicator is a WDefaultLoadingIndicator.

◆ setLocale()

void Wt::WApplication::setLocale ( const WLocale locale)

Changes the locale.

The locale is used by the localized strings resource to resolve localized strings.

By passing an empty locale, the default locale is chosen.

When the locale is changed, refresh() is called, which will resolve the strings of the current user-interface in the new locale.

At construction, the locale is copied from the environment (WEnvironment::locale()), and this is the locale that was configured by the user in his browser preferences, and passed using an HTTP request header.

See also
localizedStrings(), WString::tr()

◆ setLocalizedStrings()

void Wt::WApplication::setLocalizedStrings ( const std::shared_ptr< WLocalizedStrings > &  stringResolver)

Sets the resource object that provides localized strings.

The translator resolves localized strings within the current application locale.

See also
localizedStrings(), WString::tr(const char *key)

◆ setTheme()

void Wt::WApplication::setTheme ( const std::shared_ptr< WTheme > &  theme)

Sets the theme.

The theme provides the look and feel of several built-in widgets, using CSS style rules. Rules for each theme are defined in the resources/themes/theme/ folder.

The default theme is "default" CSS theme.

◆ setTitle()

void Wt::WApplication::setTitle ( const WString title)

Sets the window title.

Sets the browser window title to title.

The default title is "".

See also
title()

◆ setTwoPhaseRenderingThreshold()

void Wt::WApplication::setTwoPhaseRenderingThreshold ( int  size)

Changes the threshold for two-phase rendering.

This changes the threshold for the size of a JavaScript response (in bytes) to render invisible changes in one go. If the bandwidth for rendering the invisible changes exceed the threshold, they will be fetched in a second communication, after the visible changes have been rendered.

The value is a trade-off: setting it smaller will always use two-phase rendering, increasing the total render time but reducing the latency for the visible changes. Setting it too large will increase the latency to render the visible changes, since first also all invisible changes need to be computed and received in the browser.

The initial value is read from the configuration file, see 10.2 General application settings (wt_config.xml).

◆ styleSheet()

WCssStyleSheet& Wt::WApplication::styleSheet ( )

Returns a reference to the inline style sheet.

Widgets may allow configuration of their look and feel through style classes. These may be defined in this inline stylesheet, or in external style sheets.

It is usually preferable to use external stylesheets (and consider more accessible). Still, the internal stylesheet has as benefit that style rules may be dynamically updated, and it is easier to manage logistically.

See also
useStyleSheet()
WWidget::setStyleClass()

◆ suspend()

void Wt::WApplication::suspend ( std::chrono::seconds  duration)

Suspend the application.

Keep this application alive for a certain amount of time, while allowing the user to navigate away from the page. This can be useful when using 3rd party login or payment providers. You can later return to the application with a url that includes the session ID as query parameter (see WApplication::url()).

◆ title()

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

Returns the window title.

See also
setTitle(const WString&)

◆ triggerUpdate()

void Wt::WApplication::triggerUpdate ( )

Propagates server-initiated updates.

When the lock to the application is released, changes will propagate to the user interface. This call only has an effect after updates have been enabled from within the normal event loop using enableUpdates().

This is typically used only outside of the main event loop, e.g. from another thread or from within a method posted to an application using WServer::post(), since changes always propagate within the event loop at the end of the event.

The update is not immediate, and thus changes that happen after this call will equally be pushed to the client.

See also
enableUpdates()

◆ unload()

void Wt::WApplication::unload ( )
protectedvirtual

Handles a browser unload event.

The browser unloads the application when the user navigates away or when he closes the window or tab.

When reload-is-new-session is set to true, then the default implementation of this method terminates this session by calling quit(), otherwise the session is scheduled to expire within seconds (since it may be a refresh).

You may want to reimplement this if you want to keep the application running until it times out.

Note
There is no guarantee that closing the browser tab sends the unload event. This is because it is at the web browser's discretion whether it still sends requests for a closed tab. It's also possible that there was no connection upon closing the tab. Sessions that don't receive the unload event will eventually time out according to the session-timeout set in wt_config.xml (this defaults to 10 minutes).

◆ unsuspended()

Signal& Wt::WApplication::unsuspended ( )

Signal that is emitted when the application is no longer suspended.

This can be used to apply changes which were difficult to do as a result of the application not being rendered. Eg. Wt uses this to trigger a login as a result of single sign-on.

◆ updatesEnabled()

bool Wt::WApplication::updatesEnabled ( ) const

Returns whether server-initiated updates are enabled.

See also
enableUpdates()

◆ url()

std::string Wt::WApplication::url ( const std::string &  internalPath = std::string()) const

Returns a URL for the current session.

Returns the (relative) URL for this application session (including the session ID if necessary). The URL includes the full application path, and is expanded by the browser into a full URL.

For example, for an application deployed at

http://www.mydomain.com/stuff/app.wt

this method might return "/stuff/app.wt?wtd=AbCdEf". Additional query parameters can be appended in the form of "&param1=value&param2=value".

To obtain a URL that is suitable for bookmarking the current application state, to be used across sessions, use bookmarkUrl() instead.

See also
redirect(), WEnvironment::hostName(), WEnvironment::urlScheme()
bookmarkUrl()

◆ useStyleSheet() [1/3]

void Wt::WApplication::useStyleSheet ( const WLink link,
const std::string &  condition,
const std::string &  media 
)

Conditionally adds an external style sheet.

This is an overloaded method for convenience, equivalent to:

useStyleSheet(Wt::WLinkedCssStyleSheet(link, media), condition)
void useStyleSheet(const WLink &link, const std::string &media="all")
Adds an external style sheet.
Definition: WApplication.C:618
An external CSS style sheet.
Definition: WLinkedCssStyleSheet.h:29

◆ useStyleSheet() [2/3]

void Wt::WApplication::useStyleSheet ( const WLink link,
const std::string &  media = "all" 
)

Adds an external style sheet.

The link is a link to a stylesheet.

The media indicates the CSS media to which this stylesheet applies. This may be a comma separated list of media. The default value is "all" indicating all media.

This is an overloaded method for convenience, equivalent to:

A CSS style sheet.
Definition: WCssStyleSheet.h:192

◆ useStyleSheet() [3/3]

void Wt::WApplication::useStyleSheet ( const WLinkedCssStyleSheet styleSheet,
const std::string &  condition = "" 
)

Adds an external stylesheet.

Widgets may allow configuration of their look and feel through style classes. These may be defined in an inline stylesheet, or in external style sheets.

External stylesheets are inserted after the internal style sheet, and can therefore override default styles set by widgets in the internal style sheet. External stylesheets must have valid link.

If not empty, condition is a string that is used to apply the stylesheet to specific versions of IE. Only a limited subset of the IE conditional comments syntax is supported (since these are in fact interpreted server-side instead of client-side). Examples are:

  • "IE gte 6": only for IE version 6 or later.
  • "!IE gte 6": only for IE versions prior to IE6.
  • "IE lte 7": only for IE versions prior to IE7.
See also
styleSheet(), useStyleSheet(const std::string&, const std::string&), removeStyleSheet(const WLink& link)
WWidget::setStyleClass()

◆ waitForEvent()

void Wt::WApplication::waitForEvent ( )
virtual

Blocks the thread, waiting for an UI event.

This function is used by functions like WDialog::exec() or WPopupMenu::exec(), to block the current thread waiting for a new event.

This requires that at least one additional thread is available to process incoming requests, and is not scalable when working with a fixed size thread pools.

Friends And Related Function Documentation

◆ ApplicationCreator

typedef std::function<std::unique_ptr<WApplication>const WEnvironment&)> ApplicationCreator
related

Typedef for a function that creates WApplication objects.

See also
WRun()