Wt::WApplication Class Reference

A class that represents an instance of a Wt Application, corresponding to a single session. More...

#include <Wt/WApplication>

Inheritance diagram for Wt::WApplication:

Inheritance graph
[legend]

List of all members.

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 WEnvironmentenvironment () const
 Returns the environment for this application session.
WCssStyleSheetstyleSheet ()
 Returns a reference to the inline style sheet.
void useStyleSheet (const std::string &uri, const std::string &dep=std::string())
 Add an external style sheet.
WContainerWidgetroot () const
 The root container of this application.
std::string url () const
 Returns the application url.
std::string bookmarkUrl () const
 Returns a bookmarkable URL that captures the application state.
const std::string & applicationName () const
 Get the name of the application.
void setTitle (const WString &text)
 Set the application title.
const WStringtitle () const
 Returns the application title.
WMessageResourceBundlemessageResourceBundle ()
 Returns 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.
void redirect (const std::string &url)
 Redirect the application to another location.
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
 Returns the current application state value associated with a specific key.
std::string bookmarkUrl (const std::string &scope, const std::string &state)
 Returns a bookmarkable URL that captures the application state.
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.
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)
 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
 Returns the Ajax communication method.
virtual void initialize ()
 Initialize your application, post-construction.
virtual void finalize ()
 Finalize your 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
 Get the current maximum size of a request to the application.
WLogEntry log (const std::string &type)
 Add an entry to the application log.

Static Public Member Functions

static WApplicationinstance ()
 Returns the current 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 indicates a change in application state, because the user navigates through the browser history.
Signal< int > requestTooLarge
 Signal which indicates that too 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...


Detailed Description

A class that represents an instance of a Wt Application, corresponding to a single session.

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:


Member Typedef Documentation

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

Typedef for a function that creates WApplication objects.

See also:
WRun()


Member Enumeration Documentation

enum Wt::WApplication::AjaxMethod

Enumeration that indicates the Ajax communication method.

See also:
setAjaxMethod()
Enumerator:
XMLHttpRequest  Use the XMLHttpRequest object (real AJAX).
DynamicScriptTag  Use dynamic script tags (for cross-domain AJAX).


Constructor & Destructor Documentation

Wt::WApplication::~WApplication (  ) 

Destroys the WApplication.

This automatically destroys root(), and as a consequence the entire widget tree.


Member Function Documentation

const WEnvironment & Wt::WApplication::environment (  )  const

Returns the environment for this application session.

This is the environment that was used when constructing the application. The environment contains all settings that constrain the application from outside.

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.

See also:
useStyleSheet()

void Wt::WApplication::useStyleSheet ( const std::string &  uri,
const std::string &  dep = std::string() 
)

Add an external 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.

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.

See also:
styleSheet()

WContainerWidget* Wt::WApplication::root (  )  const [inline]

The root container of this application.

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.

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

Returns the application url.

Returns the (relative) URL for this application instance (thus including the session ID if necessary). The URL includes the full application path, but excludes the protocol, host name and port number.

If you want to present URLs that are suitable for bookmarking the current application state, see bookmarkUrl().

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

applicationName(), bookmarkUrl()

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

Returns a bookmarkable URL that captures the application state.

Returns the (relative) URL for this application, excluding session ID, but including the encoded state for bookmarking. Tries to return a URL that is as short as possible (excluding protocol, host name, port, and application path).

See also:
url(), bookmarkUrl(const std::string&, const std::string&)

const std::string & Wt::WApplication::applicationName (  )  const

Get the name of the application.

Returns the name of the application in the application directory. This name is the file path of the url (without path and session ID).

You could use this if you have deployed the same application under two different names, and want to have a different behaviour for one versus the other.

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

Set the application title.

Set the title that appears as the browser window title.

The default title is "".

See also:
title()

const WString& Wt::WApplication::title (  )  const [inline]

Returns the application title.

See also:
setTitle(const WString&)

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 application-specific application instance.

WMessageResourceBundle& Wt::WApplication::messageResourceBundle (  )  [inline]

Returns the message resource bundle for this application.

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

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

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.

The defualt locale is copied from the environment (WEnvironment::locale()), and indicates the locale that was configured by the user in his browser preferences.

See also:
WMessageResourceBundle::use(), WString::tr()

std::string Wt::WApplication::locale (  )  const [inline]

Get the currently used locale.

See also:
setLocale(const std::string&)

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.

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.

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

You may also create URL's corresponding to particular states, and use them in WAnchor's so that the user may follow this anchor in a new window or tab to open a second session to your application that starts in that state.

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.

Changing application state is conveniently used together with a WAnchor. By using bookmarkUrl(), you can set the URL for the anchor so that it matches the application state that is set in the anchor's clicked<> signal handler. When the user follows the anchor to a new window or tab, it behaves as if the user uses the bookmarked URL, to spawn a new session.

With Ajax, this feature only works well 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.

See also:
state(), stateChanged, bookmarkUrl()

std::string Wt::WApplication::state ( const std::string &  key  )  const

Returns the current application state value associated with a specific key.

See also:
setState(), bookmarkUrl()

std::string Wt::WApplication::bookmarkUrl ( const std::string &  scope,
const std::string &  state 
)

Returns a bookmarkable URL that captures the application state.

Like bookmarkUrl(), this method returns the (relative) URL for this application, excluding session ID, but including the encoded state for bookmarking. This method however returns the URL when the state state would be set for the indicated scope. This is useful for generating URLs for anchors which a click event which generates that state.

See also:
url(), bookmarkUrl(), setState()

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

See also:
triggerUpdate()

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

See also:
enableUpdates(), getUpdateLock()

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.

See also:
enableUpdates(), triggerUpdate()

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 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]

Returns the Ajax communication method.

See also:
setAjaxMethod()

void Wt::WApplication::initialize (  )  [virtual]

Initialize your 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 your 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 7.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.

See also:
WEnvironment::supportsCookies()

int Wt::WApplication::maximumRequestSize (  )  const

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

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

See also:
requestTooLarge

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

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

See also:
7.2 General application settings (wt_config.xml)

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. 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 if they are inserted in the widget hierachy.


Friends And Related Function Documentation

typedef WApplication*(* ApplicationCreator)(const WEnvironment &env) [related]

Typedef for a function that creates WApplication objects.

See also:
WRun()


Member Data Documentation

Signal<std::string, std::string> Wt::WApplication::stateChanged

Signal which indicates a change in application state, because the user navigates through the browser history.

An application object that wishes to react to state changes should listen to this signal.

See also:
setState()

Signal<int> Wt::WApplication::requestTooLarge

Signal which indicates that too large POST was received.

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


Generated on Fri Jul 25 17:56:37 2008 for Wt by doxygen 1.5.3