#include <WApplication>
Inherits Wt::WObject.
Inheritance diagram for Wt::WApplication:
Public Types | |
| typedef WApplication *(*) | ApplicationCreator (const WEnvironment &env) |
| 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) |
| 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. | |
| void | triggerUpdate () |
| Propagate server-initiated updates. | |
| UpdateLock | getUpdateLock () |
| Get the lock for manipulating application widgets outside the event loop. | |
| void | doJavaScript (const std::string javascript) |
| Execute some JavaScript code. | |
Static Public Member Functions | |
| static WApplication * | instance () |
| Get the application instance. | |
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. | |
Classes | |
| class | UpdateLock |
| Synchronisation lock for manipulating and updating the application and its widgets. 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& 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 WApplication*(*) Wt::WApplication::ApplicationCreator(const WEnvironment &env) |
| Wt::WApplication::~WApplication | ( | ) |
Destroys the WApplication.
This automatically destroys root(), and as a consequence the entire widget tree.
| void Wt::WApplication::doJavaScript | ( | const std::string | javascript | ) |
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.
| 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. 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! AJAX, however, is not required..
| const WEnvironment & Wt::WApplication::environment | ( | ) | const |
The environment for this application session.
This is the environment that was used when constructing the application.
| WApplication::UpdateLock Wt::WApplication::getUpdateLock | ( | ) |
Get the lock for manipulating application 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.
| WApplication * Wt::WApplication::instance | ( | ) | [static] |
Get the application instance.
This is the same as the global variable wApp.
| 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().
| 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.
| WMessageResourceBundle& Wt::WApplication::messageResourceBundle | ( | ) | [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::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::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.
| 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::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::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::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.
| 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 is currently only works when Ajax and JavaScript are enabled, and only for Firefox and Internet Explorer.
You also need to copy the dhtmlHistory.js and dhtmlHistory_blank.html files into your deployment directory. They are located in src/web/skeleton in the source distribution.
| void Wt::WApplication::setTitle | ( | const WString & | text | ) |
Set the application title.
Set the title that appears as the browser window title.
| 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.
| std::string Wt::WApplication::state | ( | const std::string | key | ) | const |
| 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.
| const WString& Wt::WApplication::title | ( | ) | const [inline] |
Get the application title.
Returns the currently set application title.
| 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.
| std::string Wt::WApplication::url | ( | ) | const |
Get the application URL.
Returns the (relative) URL for this application.
| void Wt::WApplication::useStyleSheet | ( | const std::string | uri | ) |
Emitted when a too large post was received.
The integer parameter is the request that was received in bytes.
| 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.
1.4.7