#include <Wt/WApplication>
Public Types | |
enum | AjaxMethod { XMLHttpRequest, DynamicScriptTag } |
Enumeration that indicates the Ajax communication method. More... | |
typedef Wt::ApplicationCreator | ApplicationCreator |
Typedef for a function that creates WApplication objects. | |
Public Slots | |
void | quit () |
Quit the application. | |
Public Member Functions | |
WApplication (const WEnvironment &environment) | |
Construct a WApplication. | |
~WApplication () | |
Destructor. | |
const WEnvironment & | environment () const |
Returns the application environment. | |
WContainerWidget * | root () const |
Returns the root container. | |
WCssStyleSheet & | styleSheet () |
Returns a reference to the inline style sheet. | |
void | useStyleSheet (const std::string &uri, const std::string &dep=std::string()) |
Adds an external style sheet. | |
void | setTitle (const WString &text) |
Set the title. | |
const WString & | title () const |
Returns the title. | |
WLocalizedStrings * | localizedStrings () |
Returns the class that provides localized strings. | |
void | setLocalizedStrings (WLocalizedStrings *translator) |
Set the string translator. | |
WMessageResourceBundle & | messageResourceBundle () const |
Returns the message resource bundle. | |
void | setLocale (const std::string &locale) |
Changes the locale. | |
std::string | locale () const |
Returns the currently used locale. | |
virtual void | refresh () |
Refresh the application. | |
std::string | applicationName () const |
Returns the application name (deprecated). | |
std::string | url () const |
Returns a URL for the current session. | |
std::string | bookmarkUrl () const |
Returns a bookmarkable URL, including the internal path. | |
std::string | bookmarkUrl (const std::string &internalPath) const |
Returns a bookmarkable URL for a given internal path. | |
void | setInternalPath (const std::string &internalPath, bool emitChange=false) |
Change the internal path. | |
std::string | internalPath () const |
Returns the current internal path. | |
std::string | internalPathNextPart (const std::string &path) const |
Returns part of the current internal path. | |
bool | internalPathMatches (const std::string &path) const |
Checks if the internal path matches a given path. | |
void | redirect (const std::string &url) |
Redirects the application to another location. | |
std::string | sessionId () const |
Returns the unique identifier for the current session. | |
void | enableUpdates () |
Enable server-initiated updates. | |
bool | updatesEnabled () const |
Returns whether server-initiated updates are enabled. | |
void | triggerUpdate () |
Propagate server-initiated updates. | |
void | attachThread () |
Attach an auxiliary thread to this application. | |
UpdateLock | getUpdateLock () |
Grabs and returns the lock for manipulating widgets outside the event loop. | |
void | doJavaScript (const std::string &javascript, bool afterLoaded=true) |
Executes some JavaScript code. | |
bool | require (const std::string &uri, const std::string &symbol=std::string()) |
Load a JavaScript library. | |
void | processEvents () |
Process UI events. | |
void | setAjaxMethod (AjaxMethod method) |
Set the Ajax communication method. | |
AjaxMethod | ajaxMethod () const |
Returns the Ajax communication method. | |
virtual void | initialize () |
Initialize the application, post-construction. | |
virtual void | finalize () |
Finalize the application, pre-destruction. | |
void | setTwoPhaseRenderingThreshold (int size) |
Change the threshold for two-phase rendering. | |
void | setCookie (const std::string &name, const std::string &value, int maxAge, const std::string &domain="", const std::string &path="") |
Set a new cookie. | |
int | maximumRequestSize () const |
Returns the current maximum size of a request to the application. | |
WLogEntry | log (const std::string &type) const |
Add an entry to the application log. | |
void | setState (const std::string &key, const std::string &value) |
Checkpoints the current application state with a key/value pair (deprecated). | |
std::string | state (const std::string &key) const |
Returns the current application state value associated with a specific key (deprecated). | |
std::string | bookmarkUrl (const std::string &scope, const std::string &state) |
Returns a bookmarkable URL that captures the application state (deprecated). | |
Static Public Member Functions | |
static WApplication * | instance () |
Returns the current application instance. | |
static bool | readConfigurationProperty (const std::string &name, std::string &value) |
Read a configuration property. | |
Public Attributes | |
Signal< std::string > | internalPathChanged |
Signal which indicates that the user changes the internal path. | |
Signal< std::string, std::string > | stateChanged |
Signal which indicates a change in application state (deprecated). | |
Signal< int > | requestTooLarge |
Signal which indicates that too a large POST was received. | |
Protected Member Functions | |
virtual void | notify (const WEvent &e) |
Notify an event to the application. | |
virtual bool | isExposed (WWidget *w) const |
Returns whether a widget is exposed in the interface. | |
Related Functions | |
(Note that these are not member functions.) | |
typedef WApplication *(* | ApplicationCreator )(const WEnvironment &env) |
Typedef for a function that creates WApplication objects. | |
Classes | |
class | UpdateLock |
A synchronisation lock for manipulating and updating the application and its widgets outside of the event loop. More... |
For every new session, an instance of WApplication must be created, before creating widgets. For this purpose, the user passes a function that creates applications to WRun(). A general structure for starting a Wt Application could be:
WApplication *createApplication(const WEnvironment WEnvironment& env) { // // Optionally, check the environment and redirect to an error page. // bool valid = ...; if (!valid) { WApplication *app = new WApplication(env); app->redirect("error.html"); app->quit(); return app; } WApplication *app = new WApplication(env); // // Add widgets to app->root() and return the application object. // return app; }
Throughout the application, the instance is available through WApplication::instance() (or through wApp). The application may be quited either by calling quit(), or because of a timeout (when the user has closed the window, or crashed its computer or was eaten by a virus). 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:
typedef Wt::ApplicationCreator Wt::WApplication::ApplicationCreator |
Wt::WApplication::~WApplication | ( | ) |
Destructor.
The destructor deletes the root() container, and as a consequence the entire widget tree.
WApplication * Wt::WApplication::instance | ( | ) | [static] |
Returns the current application instance.
This is the same as the global variable wApp. In a multi-threaded server, it returns the thread-specific application instance (using thread-specific storage).
const WEnvironment & Wt::WApplication::environment | ( | ) | const |
Returns the application environment.
This is the environment that was used when constructing the application. The environment contains all settings that constrain the application from outside.
WContainerWidget* Wt::WApplication::root | ( | ) | const [inline] |
Returns the root container.
This is the top-level container for displaying widgets in the application. The user interface of your application is represented by the content of this container.
WCssStyleSheet& Wt::WApplication::styleSheet | ( | ) | [inline] |
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.
void Wt::WApplication::useStyleSheet | ( | const std::string & | uri, | |
const std::string & | dep = std::string() | |||
) |
Adds an external style sheet.
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.
If not empty, dep is a string that is used to make the stylesheet browser-dependent. This works only to differentiate between specific versions of Microsoft Internet Explorer versions versus other browsers. Values for dep are for example "gte IE 5" or "!IE 7".
The uri indicates a relative or absolute URL to the stylesheet.
void Wt::WApplication::setTitle | ( | const WString & | text | ) |
Set the title.
Set the title that appears as the browser window title.
The default title is "".
const WString& Wt::WApplication::title | ( | ) | const [inline] |
WLocalizedStrings* Wt::WApplication::localizedStrings | ( | ) | [inline] |
Returns the class that provides localized strings.
The default value is a WMessageResourceBundle, which uses XML files to resolve localized strings, but you can use a custom one using setLocalizedStrings().
void Wt::WApplication::setLocalizedStrings | ( | WLocalizedStrings * | translator | ) |
Set the string translator.
The string translator resolves localized strings in the current locale. The previous string translator is deleted, and ownership is transferred to the application.
WMessageResourceBundle & Wt::WApplication::messageResourceBundle | ( | ) | const |
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 stringTranslator() is a WMessageResourceBundle, and this method returns the stringTranslator upcasted as a message resource bundle.
void Wt::WApplication::setLocale | ( | const std::string & | locale | ) |
Changes the locale.
By passing a locale that is an empty string, the default locale is chosen. The locale is used by the string translator to resolve internationalized strings.
When the locale gets changed, refresh() is called, which will resolve the strings in the new locale.
The default locale is copied from the environment (WEnvironment::locale()), and is the locale that was configured by the user in his browser preferences.
std::string Wt::WApplication::locale | ( | ) | const [inline] |
void Wt::WApplication::refresh | ( | ) | [virtual] |
Refresh the application.
Causes the application to refresh its data, including messages from message-resource bundles. This done by propagating WWidget::refresh() through the widget hierarchy.
This method is also called in response to the user hitting the refresh (or reload) button.
std::string Wt::WApplication::applicationName | ( | ) | const |
Returns the application name (deprecated).
For example, for an application deployed at "/stuff/app.wt"
, When accessing the application using:
http://www.mydomain.com/stuff/app.wt
"app.wt"
, but when accessing the application using: http://www.mydomain.com/stuff/app.wt/file
"file"
.
std::string Wt::WApplication::url | ( | ) | 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
"/stuff/app.wt?wtd=AbCdEf"
, when using URL rewriting for session-tracking or "/stuff/app.wt?a=a"
when using cookies for session-tracking (see also 8.1 Session management (wt_config.xml) for configuring the session-tracking method). As in each case, a query is appended at the end of the URL, additional query parameters can be appended in the form of "¶m1=value¶m2=value"
.To obtain a URL that is suitable for bookmarking the current application state, to be used across sessions, use bookmarkUrl() instead.
std::string Wt::WApplication::bookmarkUrl | ( | ) | const |
Returns a bookmarkable URL, including the 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.
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 URL is relative and expanded into a full URL by the browser.
For example, for an application with current URL:
http://www.mydomain.com/stuff/app.wt#/project/internal/
"/project/external"
, this method would return:"app.wt/project/external/"
when JavaScript is available, or the agent is a web spider, or"app.wt/project/external/?wtd=AbCdEf"
when no JavaScript is available and URL rewriting is used for session-tracking (see also 8.1 Session management (wt_config.xml) for configuring the session-tracking method).When the application is deployed at a folder (ending with '/'), this style of URLs is not possible, and URLs are of the form:
"?_=/project/external/"
when JavaScript is available, or the agent is a web spider, or"?_=/project/external/&wtd=AbCdEf"
when no JavaScript is available and URL rewriting is used for session-tracking.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.
void Wt::WApplication::setInternalPath | ( | const std::string & | internalPath, | |
bool | emitChange = false | |||
) |
Change 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
"/project/z3cbc/details/"
is set, the two forms for the application URL are: http://www.mydomain.com/stuff/app.wt#/project/z3cbc/details/
http://www.mydomain.com/stuff/app.wt/project/z3cbc/details/
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 signal 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.
A url that includes the internal path may be obtained using bookmarkUrl().
The internalPath must start and end with a '/'.
std::string Wt::WApplication::internalPath | ( | ) | const |
Returns the current internal path.
When the application is just created, this is equal to WEnvironment::internalPath().
std::string Wt::WApplication::internalPathNextPart | ( | const std::string & | path | ) | const |
Returns 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 and end 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.
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). This may 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 and end with a '/'.
void Wt::WApplication::redirect | ( | const std::string & | url | ) |
Redirects the application to another location.
The client will be redirected to a new location. Use this in conjunction with quit() if you want to 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.
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.
void Wt::WApplication::enableUpdates | ( | ) |
Enable 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, or from socket events (using the WSocketNotifier). 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.
A call to this method starts a so-called "server push". Widgets may then be modified, created or deleted outside of the event loop (from another thread), and are subsequently propagated by calling triggerUpdate().
This works only if JavaScript is available on the client, and is not considered a production quality feature (there are some unwanted side effects that have to do with typical browser limitations, such as the maximum number of simultaneous open connections to a single web server)..
bool Wt::WApplication::updatesEnabled | ( | ) | const |
Returns whether server-initiated updates are enabled.
True if server-initiated updates were enabled by a previous call to enableUpdates().
void Wt::WApplication::triggerUpdate | ( | ) |
Propagate server-initiated updates.
Propagate changes made to the user interface outside of the main event loop. This is only possible after a call to enableUpdates(), and must be done while holding the UpdateLock (or from within a socket event, see WSocketNotifier).
void Wt::WApplication::attachThread | ( | ) |
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 getUpdateLock() 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 getUpdateLock() 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.
WApplication::UpdateLock Wt::WApplication::getUpdateLock | ( | ) |
Grabs and returns the lock for manipulating widgets outside the event loop.
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.
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.
bool Wt::WApplication::require | ( | const std::string & | uri, | |
const std::string & | symbol = std::string() | |||
) |
Load a JavaScript library.
Attempt to load a JavaScript library. When symbol is not empty, the library is only inserted in the page if the given symbol is not yet defined.
Returns true when the library was not yet loaded for this application.
JavaScript libraries may be loaded at any point in time. They will be loaded before evaluating the normal event handling code, but after javaScript that has been executed using doJavaScript(..., false).
void Wt::WApplication::processEvents | ( | ) |
Process UI events.
You may call this method during a long operation to:
This method starts a recursive event loop, blocking the current thread, and resumes when all events have been processed.
bool Wt::WApplication::readConfigurationProperty | ( | const std::string & | name, | |
std::string & | value | |||
) | [static] |
Read 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.
void Wt::WApplication::setAjaxMethod | ( | AjaxMethod | method | ) |
Set the Ajax communication method.
You may call this method only from your application constructor.
The default method depends on your application type. For plain applications, XMLHttpRequest is used, while for embedded widget sets, DynamicScriptTag is used. The latter is less efficient, but has the benefit to allow serving the application from a different server than the page that hosts the embedded widgets.
AjaxMethod Wt::WApplication::ajaxMethod | ( | ) | const [inline] |
void Wt::WApplication::initialize | ( | ) | [virtual] |
Initialize 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).
void Wt::WApplication::finalize | ( | ) | [virtual] |
Finalize 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).
void Wt::WApplication::setTwoPhaseRenderingThreshold | ( | int | size | ) |
Change the threshold for two-phase rendering.
This changes the threshold for the communication size (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. Setting it too large will increase the latency to render the visible changes, since first all changes need to be received in the browser.
The initial value is read from the configuration file, see 8.2 General application settings (wt_config.xml).
void Wt::WApplication::setCookie | ( | const std::string & | name, | |
const std::string & | value, | |||
int | maxAge, | |||
const std::string & | domain = "" , |
|||
const std::string & | path = "" | |||
) |
Set a new cookie.
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 current path on the current domain. To set a proper value for domain, see also RFC2109.
Use cookies to recognize the same user returning at some later time to your server or application.
int Wt::WApplication::maximumRequestSize | ( | ) | const |
Returns the current maximum size of a request to the application.
The maximum request size is configured in the configuration file, see 8.2 General application settings (wt_config.xml).
WLogEntry Wt::WApplication::log | ( | const std::string & | type | ) | const |
Add 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."
void Wt::WApplication::setState | ( | const std::string & | key, | |
const std::string & | value | |||
) |
Checkpoints the current application state with a key/value pair (deprecated).
.../key/value/...
Multiple key/value pairs can be combined in the URL in the order that they are (first) set. When changing an "earlier" (higher-level) key/value pair, "later" (lower-level) pairs are pruned from the URL (Warning! this does not completely reflect the old behaviour, since there keys were never pruned away, but it is more in the spirit of the hierarchical internal path nature).
An application object (such as a widget) that uses this deprecated system for internal application state works as follows:
std::string Wt::WApplication::state | ( | const std::string & | key | ) | const |
Returns the current application state value associated with a specific key (deprecated).
std::string Wt::WApplication::bookmarkUrl | ( | const std::string & | scope, | |
const std::string & | state | |||
) |
Returns a bookmarkable URL that captures the application state (deprecated).
void Wt::WApplication::quit | ( | ) | [slot] |
Quit the application.
The method returns immediately, and has as effect that the application will be terminated after the current event is completed.
The current widget tree (including any modifications still pending) is rendered, and the application is terminated.
You might want to make sure no more events can be received from the user, by not having anything clickable, for example by displaying only text. A better approach may be to also redirect() the user to another page.
void Wt::WApplication::notify | ( | const WEvent & | e | ) | [protected, virtual] |
Notify 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.
You will rarely want to reimplement this method, unless you wish to have a single point for exception handling. In that case, you should call the baseclass implementation WApplication::notify(), and surround it in your own try - catch block for those exceptions you wish to handle.
Any uncaught exception will terminate the application.
bool Wt::WApplication::isExposed | ( | WWidget * | w | ) | const [protected, virtual] |
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.
typedef WApplication*(* ApplicationCreator)(const WEnvironment &env) [related] |
Signal<std::string> Wt::WApplication::internalPathChanged |
Signal which indicates that the user changes the internal path.
This signal propagates changes to the internal path, which are usually triggered by the user using the browser back/forward buttons.
When the path changes, this signal is emitted for every prefix whose next path element has changed. The prefix is passed as the argument, and may be used by listening widgets to quickly determine if they need to respond to the path change. This also allows widgets to be created corresponding to each path element, and respond in their turn to further internal path changes.
For example, when the path would change from "/mail/inbox/unread/5"
to "/mail/addressbook/public/27"
, this signal would be emitted three times, in the following sequence:
prefix | internalPath() | internalPathNextPart(prefix) |
"/mail/" | "/mail/addressbook" | "addressbook" |
"/mail/addressbook/" | "/mail/addressbook/public" | "public" |
"/mail/addressbook/public/" | "/mail/addressbook/public/27" | "27" |
When the application starts with a non-empty internal path, a patch switch is simulated from "/" to the initial path, after the application has been created. Therefore you have two options to deal with the initial internal path on application start up:
Signal<std::string, std::string> Wt::WApplication::stateChanged |
Signal which indicates a change in application state (deprecated).
Signal which indicates that too a large POST was received.
The integer parameter is the request that was received in bytes.