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 Member Functions

 WApplication (const WEnvironment &environment)
 Construct a WApplication.
 ~WApplication ()
 Destructor.
const WEnvironmentenvironment () const
 Returns the application environment.
WContainerWidgetroot () const
 Returns the root container.
WCssStyleSheetstyleSheet ()
 Returns a reference to the inline style sheet.
void useStyleSheet (const std::string &uri)
 Adds an external style sheet.
void useStyleSheet (const std::string &uri, const std::string &condition)
 Adds an external style sheet, conditional for IE.
void setTitle (const WString &title)
 Set the title.
const WStringtitle () const
 Returns the title.
WLocalizedStringslocalizedStrings ()
 Returns the object that provides localized strings.
void setLocalizedStrings (WLocalizedStrings *translator)
 Set the string translator.
WMessageResourceBundlemessageResourceBundle () 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.
void bindWidget (WWidget *widget, const std::string &domId)
 Bind 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, 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 &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 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)
 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 setLoadingIndicator (WLoadingIndicator *indicator)
 Set the loading indicator.
WLoadingIndicatorloadingIndicator () const
 Returns the loading indicator.
void quit ()
 Quit the application.
Signal< int > & requestTooLarge ()
 Signal which indicates that too a large POST was received.

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.

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.

Each user session of your application has a corresponding WApplication instance. This instance must be created, before creating widgets, and is returned as the result of the callback function passed to WRun(). The instance is the main entry point into information pertaining to a single session, 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 application, 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 (when the user has closed the window, or crashed its computer or was eaten by a virus -- 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:


Member Typedef Documentation

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

Typedef for a function that creates WApplication objects.

See also:
WRun()


Member Enumeration Documentation

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

Destructor.

The destructor deletes the root() container, and as a consequence the entire widget tree.


Member Function Documentation

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

Note:
The root() is only defined in normal application mode. For WidgetSet mode, there is no root() container, and 0 is returned. Instead, use bindWidget() to bind root widgets to existing HTML <div> elements on the page.

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  ) 

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

See also:
styleSheet(), useStyleSheet(const std::string&, const std::string&)

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

Adds an external style sheet, conditional for IE.

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

  • "IE gte 6": only for IE version 6 or later.
  • "!IE gte 6": only for IE versions prior to IE6.
  • "IE lte 7": only for IE versions prior to IE7.

The uri indicates a relative or absolute URL to the stylesheet.

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

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

Set the 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 title.

See also:
setTitle(const WString&)

WLocalizedStrings* Wt::WApplication::localizedStrings (  )  [inline]

Returns the 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().

See also:
WString::tr(), messageResourceBundle()

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.

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

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.

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

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.

See also:
localizedStrings(), WString::tr()

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

Returns the currently used locale.

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

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 when the user hits the refresh (or reload) button, in case the application is configured to not create a new session in response.

See also:
WWidget::refresh()

void Wt::WApplication::bindWidget ( WWidget widget,
const std::string &  domId 
)

Bind a top-level widget for a WidgetSet deployment.

This method binds a widget to an existing element 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).

See also:
root(), WidgetSet mode.

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 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 "&param1=value&param2=value".

To obtain a URL that is suitable for bookmarking the current application state, to be used across sessions, use bookmarkUrl() instead.

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

bookmarkUrl()

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.

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

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

See also:
url(), bookmarkUrl()

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:
  • in a browser with AJAX:
     http://www.mydomain.com/stuff/app.wt#/project/z3cbc/details/
    
  • or in other situations (no JavaScript):
     http://www.mydomain.com/stuff/app.wt/project/z3cbc/details/
    
    This has as major consequence that from the browser stand point, the application now serves many different URLs. As a consequence, relative URLs will break. Still, you can specify relative URLs within your application (in for example WAnchor::setRef() or WImage::setImageRef()) since Wt will transform them to absolute URLs when needed. But, this in turn may break deployments behind reverse proxies when the context paths differ. For the same reason, you will need to use absolute URLs in any XHTML or CSS you write manually.
    This type of URLs are only used when the your application is deployed at a location that does not end with a '/'. Otherwise, Wt will generate URLS like:
     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.

See also:
bookmarkUrl(), internalPath(), internalPathChanged()

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

Returns the current internal path.

When the application is just created, this is equal to WEnvironment::internalPath().

See also:
setInternalPath(), internalPathNextPart(), internalPathMatches()

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

See also:
internalPath(), internalPathChanged()

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 with a '/'.

See also:
setInternalPath(), internalPath()

Signal<std::string>& Wt::WApplication::internalPathChanged (  )  [inline]

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:

  • ignore the internal path when creating the application (perhaps even using setInternalPath("/")) and respond to the initial change. This simplifies the initialization of your application, at the potential cost of creating widgets that were not necessary.
  • use the value of internalPath() to setup the application directly in the state that corresponds to the internal path.

See also:
setInternalPath()

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 ( bool  enabled = true  ) 

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.

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

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();
 }

Note:
This works only if JavaScript is available on the client.
See also:
triggerUpdate()

bool Wt::WApplication::updatesEnabled (  )  const [inline]

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

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 
)

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:

  • Propagate widget changes to the client.
  • Process UI events.

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

AjaxMethod Wt::WApplication::ajaxMethod (  )  const [inline]

Returns the Ajax communication method.

See also:
setAjaxMethod()

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

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.

Note:
Wt provides session tracking automatically (and may be configured to use a cookie for this). You only need this method if you want to remember information across sessions.
See also:
WEnvironment::supportsCookies(), WEnvironment::getCookie()

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

See also:
requestTooLarge()

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

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

void Wt::WApplication::setLoadingIndicator ( WLoadingIndicator indicator  ) 

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

WLoadingIndicator* Wt::WApplication::loadingIndicator (  )  const [inline]

Returns the loading indicator.

See also:
setLoadingIndicator()

void Wt::WApplication::quit (  ) 

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

See also:
redirect()

Signal<int>& Wt::WApplication::requestTooLarge (  )  [inline]

Signal which indicates that too a large POST was received.

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

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 in a central place:

 MyApplication::notify(const WEvent& e)
 {
    try {
      WApplication::notify(e);
    } catch (MyException& exception) {
      // handle this exception in a central place
    }
 }

Any uncaught exception throw during event handling terminates the session.

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.


Friends And Related Function Documentation

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

Typedef for a function that creates WApplication objects.

See also:
WRun()


Generated on Mon Mar 9 08:27:50 2009 for Wt by doxygen 1.5.6