#include <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 () |
Exit the application. | |
Public Member Functions | |
WApplication (const WEnvironment &environment) | |
Construct a WApplication. | |
~WApplication () | |
Destroys the WApplication. | |
const WEnvironment & | environment () const |
The environment for this application session. | |
WCssStyleSheet & | styleSheet () |
Access the inline style sheet of this application. | |
void | useStyleSheet (const std::string &uri, const std::string &dep=std::string()) |
Add an external style sheet. | |
WContainerWidget * | root () const |
The root container of this application. | |
std::string | url () const |
Get the application Url. | |
void | setTitle (const WString &text) |
Set the application title. | |
const WString & | title () const |
Get the application title. | |
WMessageResourceBundle & | messageResourceBundle () |
Get the message resource bundle for this application. | |
void | setLocale (const std::string &locale) |
Set the current locale. | |
std::string | locale () const |
Get the currently used locale. | |
virtual void | refresh () |
Refresh the application. | |
int | maximumRequestSize () const |
Get the current maximum size of a request to the application. | |
void | redirect (const std::string &url) |
Redirect the application to another location. | |
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. | |
void | setState (const std::string &key, const std::string &value) |
Checkpoint the current application state with a key/value pair. | |
std::string | state (const std::string &key) const |
Get the current application state value associated with a specific key. | |
std::string | sessionId () const |
Unique identifier for the current session. | |
void | enableUpdates () |
Enable server-initiated updates. | |
bool | updatesEnabled () const |
Are server-initiated updates enabled ? | |
void | triggerUpdate () |
Propagate server-initiated updates. | |
UpdateLock | getUpdateLock () |
Get the lock for manipulating widgets outside the event loop. | |
void | doJavaScript (const std::string &javascript, bool afterLoaded=true) |
Execute 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 |
Get the Ajax communication method. | |
Static Public Member Functions | |
static WApplication * | instance () |
Get the application instance. | |
static bool | readConfigurationProperty (const std::string &name, std::string &value) |
Read a configuration property. | |
Public Attributes | |
Signal< std::string, std::string > | stateChanged |
Signal which is emitted when the application state changes because the user navigates through the browser history. | |
Signal< int > | requestTooLarge |
Emitted when a too large post was received. | |
Protected Member Functions | |
virtual void | notify (const WEvent &e) |
Notify an event to the application. | |
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 Wt::WApplication must be created, before creating widgets. For this purpose, the user passes a function that creates applications to Wt::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:
Wt::WApplication::~WApplication | ( | ) |
Destroys the WApplication.
This automatically destroys root(), and as a consequence the entire widget tree.
const WEnvironment & Wt::WApplication::environment | ( | ) | const |
The environment for this application session.
This is the environment that was used when constructing the application.
WCssStyleSheet& Wt::WApplication::styleSheet | ( | ) | [inline] |
Access the inline style sheet of this application.
WWidgets may allow configuration of their look and feel through style classes. These may be defined in this inline stylesheet. Currently, the stylesheet may only be defined before the application is started, subsequent changes will not be reflected in the application.
void Wt::WApplication::useStyleSheet | ( | const std::string & | uri, | |
const std::string & | dep = std::string() | |||
) |
Add an external style sheet.
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".
WContainerWidget* Wt::WApplication::root | ( | ) | const [inline] |
The root container of this application.
This is the top-level container for displaying widgets in the application.
std::string Wt::WApplication::url | ( | ) | const |
Get the application Url.
Returns the (relative) URL for this application, including session ID if needed (if using URL rewriting for session tracking).
void Wt::WApplication::setTitle | ( | const WString & | text | ) |
Set the application title.
Set the title that appears as the browser window title.
const WString& Wt::WApplication::title | ( | ) | const [inline] |
Get the application title.
Returns the currently set application title.
WApplication * Wt::WApplication::instance | ( | ) | [static] |
Get the application instance.
This is the same as the global variable wApp.
WMessageResourceBundle& Wt::WApplication::messageResourceBundle | ( | ) | [inline] |
void Wt::WApplication::setLocale | ( | const std::string & | locale | ) |
Set the current locale.
Specifying an empty locale assumes the default locale. A different value (such as e.g. "nl") will cause WString values to be resolved in the respect message resource files.
When the locale get changed, refresh() is called which will re-localize messages.
std::string Wt::WApplication::locale | ( | ) | const [inline] |
Get the currently used locale.
The default locale is copied from the environment, but may be changed using setLocale().
void Wt::WApplication::refresh | ( | ) | [virtual] |
Refresh the application.
This method is called in response to the user hitting the refresh (or reload) button, and causes the application to refresh its data, including messages from message-resource bundles.
int Wt::WApplication::maximumRequestSize | ( | ) | const |
Get the current maximum size of a request to the application.
The maximum request size may be configured in the configuration file.
void Wt::WApplication::redirect | ( | const std::string & | url | ) |
Redirect 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. redirect() does not imply quit(), since it may be useful to switch between a non-secure and secure (SSL) transport connection
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, which will only be rendered after all changes have been communicated.
The initial value is read from the configuration file.
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.
void Wt::WApplication::setState | ( | const std::string & | key, | |
const std::string & | value | |||
) |
Checkpoint the current application state with a key/value pair.
The user may browse through application states using the browser back and forward buttons, or bookmark a particular state of your application.
An application object (such as a widget) that wishes to generate history events, and respond to state changes, should:
For an example, see the WMenu implementation.
This feature currently only works when Ajax and JavaScript are enabled, and only for Firefox and Internet Explorer, and requires the following resource:
This file may be found in the resources/ folder of the Wt distribution.
The default value for resourcesURL is "resources/". This value may be overridden with any valid URL which points to the location where this file may be found, by configuring the resourcesURL property in your Wt configuration file.
std::string Wt::WApplication::state | ( | const std::string & | key | ) | const |
std::string Wt::WApplication::sessionId | ( | ) | const |
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 |
Are server-initiated updates 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).
WApplication::UpdateLock Wt::WApplication::getUpdateLock | ( | ) |
Get 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 | |||
) |
Execute 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 when the event handling is done.
bool Wt::WApplication::require | ( | const std::string & | uri, | |
const std::string & | symbol = std::string() | |||
) |
Load a JavaScript library.
Attempt to load a JavaScript library. The 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.
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::quit | ( | ) | [slot] |
Exit the application.
Signaling this slot will cause the application to end after the current event is completed.
By default, the current widget tree (including any modifications still pending) is rendered, and the application is terminated. A "-- Quited" is appended to the application title.
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 redirect the user to another page using redirect().
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.
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.
Signal<std::string, std::string> Wt::WApplication::stateChanged |
Signal which is emitted when the application state changes because the user navigates through the browser history.
An application object that wishes to react to state changes should listen to this signal.
Emitted when a too large post was received.
The integer parameter is the request that was received in bytes.