Represents an application instance for a single session. More...
#include <Wt/WApplication>
Classes | |
class | UpdateLock |
A synchronisation lock for manipulating and updating the application and its widgets outside of the event loop. More... | |
Public Types | |
enum | AjaxMethod { XMLHttpRequest, DynamicScriptTag } |
Enumeration that indicates the method for dynamic (AJAX-alike) updates. More... | |
typedef Wt::ApplicationCreator | ApplicationCreator |
Typedef for a function that creates WApplication objects. | |
Public Member Functions | |
WApplication (const WEnvironment &environment) | |
Creates a new application instance. | |
~WApplication () | |
Destructor. | |
const WEnvironment & | environment () const |
Returns the environment information. | |
WContainerWidget * | root () const |
Returns the root container. | |
WCssStyleSheet & | styleSheet () |
Returns a reference to the inline style sheet. | |
void | useStyleSheet (const std::string &url) |
Adds an external style sheet. | |
void | useStyleSheet (const std::string &url, const std::string &condition) |
Adds an external style sheet, conditional to specific Internet Explorer browser. | |
void | setCssTheme (const std::string &theme) |
Sets the theme. | |
std::string | cssTheme () const |
Returns the theme. | |
void | setTitle (const WString &title) |
Sets the window title. | |
const WString & | title () const |
Returns the window title. | |
WLocalizedStrings * | localizedStrings () |
Returns the resource object that provides localized strings. | |
void | setLocalizedStrings (WLocalizedStrings *stringResolver) |
Sets the resource object that provides localized strings. | |
WMessageResourceBundle & | messageResourceBundle () const |
Returns the message resource bundle. | |
void | setLocale (const std::string &locale) |
Changes the locale. | |
std::string | locale () const |
Returns the current locale. | |
virtual void | refresh () |
Refreshes the application. | |
void | bindWidget (WWidget *widget, const std::string &domId) |
Binds a top-level widget for a WidgetSet deployment. | |
std::string | url () const |
Returns a URL for the current session. | |
std::string | bookmarkUrl () const |
Returns a bookmarkable URL for the current internal path. | |
std::string | bookmarkUrl (const std::string &internalPath) const |
Returns a bookmarkable URL for a given internal path. | |
void | setInternalPath (const std::string &path, 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 a part of the current internal path. | |
bool | internalPathMatches (const std::string &path) const |
Checks if the internal path matches a given path. | |
Signal< std::string > & | internalPathChanged () |
Signal which indicates that the user changes the internal 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 (bool enabled=true) |
Enables server-initiated updates. | |
bool | updatesEnabled () const |
Returns whether server-initiated updates are enabled. | |
void | triggerUpdate () |
Propagates server-initiated updates. | |
UpdateLock | getUpdateLock () |
Grabs and returns the lock for manipulating widgets outside the event loop. | |
void | attachThread () |
Attach an auxiliary thread to this application. | |
void | doJavaScript (const std::string &javascript, bool afterLoaded=true) |
Executes some JavaScript code. | |
void | addAutoJavaScript (const std::string &javascript) |
Adds JavaScript statements that should be run continuously. | |
void | declareJavaScriptFunction (const std::string &name, const std::string &function) |
Declares an application-wide JavaScript function. | |
bool | require (const std::string &url, const std::string &symbol=std::string()) |
Loads a JavaScript library. | |
void | processEvents () |
Processes UI events. | |
void | setAjaxMethod (AjaxMethod method) |
Sets the Ajax communication method. | |
AjaxMethod | ajaxMethod () const |
Returns the Ajax communication method. | |
std::string | javaScriptClass () |
Returns the name of the application JavaScript class. | |
virtual void | initialize () |
Initializes the application, post-construction. | |
virtual void | finalize () |
Finalizes the application, pre-destruction. | |
void | setTwoPhaseRenderingThreshold (int size) |
Changes 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="") |
Sets a new cookie. | |
int | maximumRequestSize () const |
Returns the current maximum size of a request to the application. | |
WLogEntry | log (const std::string &type) const |
Adds an entry to the application log. | |
void | setLoadingIndicator (WLoadingIndicator *indicator) |
Sets the loading indicator. | |
WLoadingIndicator * | loadingIndicator () const |
Returns the loading indicator. | |
void | quit () |
Quits the application. | |
bool | isQuited () const |
Returns whether the application is quited. | |
Signal< int > & | requestTooLarge () |
Signal which indicates that too a large request was received. | |
void | setBodyClass (const std::string &styleClass) |
Sets a style class to the entire page <body>. | |
std::string | bodyClass () const |
Returns the style class set for the entire page <body>. | |
void | setHtmlClass (const std::string &styleClass) |
Sets a style class to the entire page <html>. | |
std::string | htmlClass () const |
Returns the style class set for the entire page <html>. | |
EventSignal< WKeyEvent > & | globalKeyWentDown () |
Event signal emitted when a keyboard key is pushed down. | |
EventSignal< WKeyEvent > & | globalKeyPressed () |
Event signal emitted when a "character" was entered. | |
EventSignal< WKeyEvent > & | globalKeyWentUp () |
Event signal emitted when a keyboard key is released. | |
EventSignal & | globalEnterPressed () |
Event signal emitted when enter was pressed. | |
EventSignal & | globalEscapePressed () |
Event signal emitted when escape was pressed. | |
Static Public Member Functions | |
static WApplication * | instance () |
Returns the current application instance. | |
static bool | readConfigurationProperty (const std::string &name, std::string &value) |
Reads a configuration property. | |
static std::string | resourcesUrl () |
Returns the URL at which the resources are deployed. | |
Protected Member Functions | |
virtual void | notify (const WEvent &e) |
Notifies an event to the application. | |
virtual bool | isExposed (WWidget *w) const |
Returns whether a widget is exposed in the interface. | |
virtual void | enableAjax () |
Progresses to an Ajax-enabled user interface. | |
Related Functions | |
(Note that these are not member functions.) | |
typedef WApplication *(* | ApplicationCreator )(const WEnvironment &env) |
Typedef for a function that creates WApplication objects. |
Represents an application instance for a single session.
Each user session of your application has a corresponding WApplication instance. You need to create a new instance and return it as the result of the callback function passed to WRun(). The instance is the main entry point to session information, and holds a reference to the root() of the widget tree.
The recipe for a Wt web application, which allocates new WApplication instances for every user visiting the application is thus:
WApplication *createApplication(const WEnvironment WEnvironment& env) { // // Optionally, check the environment and redirect to an error page. // bool valid = ...; WApplication *app; if (!valid) { app = new WApplication(env); app->redirect("error.html"); app->quit(); } else { // usually you will specialize your application class app = new WApplication(env); // // Add widgets to app->root() and return the application object. // } return app; }
Throughout the session, the instance is available through WApplication::instance() (or through wApp). The application may be quited 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:
typedef Wt::ApplicationCreator Wt::WApplication::ApplicationCreator |
Typedef for a function that creates WApplication objects.
Enumeration that indicates the method for dynamic (AJAX-alike) updates.
Wt::WApplication::WApplication | ( | const WEnvironment & | environment ) |
Creates a new application instance.
The environment
provides information on the initial request, user agent, and deployment-related information.
Wt::WApplication::~WApplication | ( | ) |
Destructor.
The destructor deletes the root() container, and as a consequence the entire widget tree.
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.
AjaxMethod Wt::WApplication::ajaxMethod | ( | ) | const [inline] |
Returns the Ajax communication method.
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.
void Wt::WApplication::bindWidget | ( | WWidget * | widget, |
const std::string & | domId | ||
) |
Binds a top-level widget for a WidgetSet deployment.
This method binds a widget
to an existing element with DOM id domId
on the page. The element type should correspond with the widget type (e.g. it should be a <div> for a WContainerWidget, or a <table> for a WTable).
std::string Wt::WApplication::bodyClass | ( | ) | const [inline] |
Returns the style class set for the entire page <body>.
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.
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/
when called with "/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 9.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.
std::string Wt::WApplication::cssTheme | ( | ) | const [inline] |
Returns the theme.
void Wt::WApplication::declareJavaScriptFunction | ( | const std::string & | name, |
const std::string & | function | ||
) |
Declares an application-wide JavaScript function.
This is an internal method.
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
.
void Wt::WApplication::enableAjax | ( | ) | [protected, virtual] |
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.
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().
Note that you need to grab the application's update lock to avoid concurrency problems, whenever you modify the application's state from another thread.
An example of how to modify the widget tree outside the event loop and propagate changes is:
// You need to have a reference to the application whose state // you are about to manipulate. // You should prevent the application from being deleted somehow, // before you could grab the application lock. Wt::WApplication *app = ...; { // Grab the application lock. It is a scoped lock. Wt::WApplication::UpdateLock lock = app->getUpdateLock(); // We now have exclusive access to the application: we can safely modify the widget tree for example. app->root()->addWidget(new Wt::WText("Something happened!")); // Push the changes to the browser app->triggerUpdate(); }
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.
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).
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.
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.
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.
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.
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.
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.
std::string Wt::WApplication::htmlClass | ( | ) | const [inline] |
Returns the style class set for the entire page <html>.
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).
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.
std::string Wt::WApplication::internalPath | ( | ) | const |
Returns the current internal path.
When the application is just created, this is equal to WEnvironment::internalPath().
Signal<std::string>& Wt::WApplication::internalPathChanged | ( | ) | [inline] |
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.
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 '/'.
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.
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.
bool Wt::WApplication::isQuited | ( | ) | const [inline] |
Returns whether the application is quited.
std::string Wt::WApplication::javaScriptClass | ( | ) | [inline] |
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 WidgtSet mode, without interfering.
WLoadingIndicator* Wt::WApplication::loadingIndicator | ( | ) | const [inline] |
Returns the loading indicator.
std::string Wt::WApplication::locale | ( | ) | const [inline] |
Returns the current locale.
WLocalizedStrings* Wt::WApplication::localizedStrings | ( | ) | [inline] |
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.
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."
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 9.2 General application settings (wt_config.xml).
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 localizedStrings() is a WMessageResourceBundle object, and this method returns localizedStrings() upcasted to this type.
void Wt::WApplication::notify | ( | const WEvent & | e ) | [protected, virtual] |
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:
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 { WApplication::notify(event); } catch (MyException& exception) { // handle this exception in a central place } // Free resources used during request handling }
Note that any uncaught exception throw during event handling terminates the session.
void Wt::WApplication::processEvents | ( | ) |
Processes 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 pending user interface events have been processed.
Because a thread is blocked, this may affect your application scalability.
void Wt::WApplication::quit | ( | ) |
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.
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. Even better is to redirect() the user to another, static, page in conjunction with quit().
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
.
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 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.
void Wt::WApplication::refresh | ( | ) | [virtual] |
Refreshes the application.
This lets the application to refresh its data, including strings from message-resource bundles. This 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 9.1 Session management (wt_config.xml) for configuring the reload behavior ("<reload-is-new-session>").
Signal<int>& Wt::WApplication::requestTooLarge | ( | ) | [inline] |
Signal which indicates that too a large request was received.
The integer parameter is the request size that was received in bytes.
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 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().
std::string Wt::WApplication::resourcesUrl | ( | ) | [static] |
Returns the URL at which the resources are deployed.
This returns the value of the 'resources' property set in the configuration file.
WContainerWidget* Wt::WApplication::root | ( | ) | const [inline] |
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 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.
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::setAjaxMethod | ( | AjaxMethod | method ) |
Sets the Ajax communication method.
You may change the communication method only from within the application constructor.
The default method depends on your application deployment type.
For plain applications, XMLHttpRequest is used, while for widget set applications, 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.
void Wt::WApplication::setBodyClass | ( | const std::string & | styleClass ) |
Sets a style class to the entire page <body>.
void Wt::WApplication::setCookie | ( | const std::string & | name, |
const std::string & | value, | ||
int | maxAge, | ||
const std::string & | domain = "" , |
||
const std::string & | path = "" |
||
) |
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 current path on the current domain. To set a proper value for domain, see also RFC2109.
void Wt::WApplication::setCssTheme | ( | const std::string & | 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". When setting "", the external style sheets related to the theme are not loaded.
void Wt::WApplication::setHtmlClass | ( | const std::string & | styleClass ) |
Sets a style class to the entire page <html>.
void Wt::WApplication::setInternalPath | ( | const std::string & | path, |
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
for which an internalPath
"/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() 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.
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.
void Wt::WApplication::setLoadingIndicator | ( | 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.
When setting a new loading indicator, the previous one is deleted.
void Wt::WApplication::setLocale | ( | const std::string & | 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.
The default 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.
void Wt::WApplication::setLocalizedStrings | ( | WLocalizedStrings * | stringResolver ) |
Sets the resource object that provides localized strings.
The translator
resolves localized strings within the current application locale.
The previous resource is deleted, and ownership of the new resource passes to the application.
void Wt::WApplication::setTitle | ( | const WString & | title ) |
Sets the window title.
Sets the browser window title to title
.
The default title is "".
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 9.2 General application settings (wt_config.xml).
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.
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.
const WString& Wt::WApplication::title | ( | ) | const [inline] |
Returns the window title.
void Wt::WApplication::triggerUpdate | ( | ) |
Propagates 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).
bool Wt::WApplication::updatesEnabled | ( | ) | const [inline] |
Returns whether server-initiated updates are enabled.
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
this method would return "/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 9.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.
void Wt::WApplication::useStyleSheet | ( | const std::string & | url, |
const std::string & | condition | ||
) |
Adds an external style sheet, conditional to specific Internet Explorer browser.
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:
The url
indicates a relative or absolute URL to the stylesheet.
void Wt::WApplication::useStyleSheet | ( | const std::string & | url ) |
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.
The url
indicates a relative or absolute URL to the stylesheet.
External stylesheets are inserted after the internal style sheet, and can therefore override default styles set by widgets in the internal style sheet.
typedef WApplication*(* ApplicationCreator)(const WEnvironment &env) [related] |
Typedef for a function that creates WApplication objects.