// This may look like C code, but it's really -*- C++ -*-
/*
 * Copyright (C) 2005 Koen Deforche, Kessel-Lo, Belgium.
 *
 * See the LICENSE file for terms of use.
 */
#ifndef WTEXT_H_
#define WTEXT_H_

#include <WInteractWidget>
#include <WString>

namespace Wt {

/*! \class WText WText WText
 *  \brief A Widget that displays text.
 *
 * WText is an \link WWidget::setInline(bool) inline \endlink widget.
 *
 * The text is set through a WString, which may either hold a literal
 * text, or localized text which is looked up in locale dependent
 * XML files.
 *
 * Use setFormatting() to configure the formatting of the text. The
 * default formatting is WText::XHMTLFormatting, which allows any
 * XHMTL formatting to be included in the text (except for script
 * code) and this formatting is used in rendering the text. Script
 * code is stripped away not only to enforce use of %Wt's event
 * handling, but also to avoid security risks exposed by JavaScript
 * such as <a
 * href="http://en.wikipedia.org/wiki/Cross_site_scriptingCross-Site">
 * Cross-Site Scripting</a>. The WText::PlainFormatting format will
 * display the text literally (escaping any HTML special characters).
 * Finally, XHTMLUnsafeFormatting will not be stripped off any
 * potentially dangerous code. Use if it if you're sure that a user
 * cannot interfere with the text set.
 *
 * \sa WApplication::setLocale()
 * \sa WApplication::messageResourceBundle()
 * \sa WApplication::characterEncoding()
 */
class WT_API WText : public WInteractWidget
{
public:
  /*! \brief Formatting for the text.
   */
  enum Formatting { XHTMLFormatting, //!< Format as XHTML markup'ed text
		    XHTMLUnsafeFormatting,  //!< Format as XHTML markup'ed text that does not get stripped
		    PlainFormatting  //!< Format as plain text.
  };

  /*! \brief Construct a WText widget with empty text
   */
  WText(WContainerWidget *parent = 0);

  /*! \brief Construct a WText widget with a given text.
   *
   * The text message is rendered using WText::XHTMLFormatting.
   */
  WText(const WString& text, WContainerWidget *parent = 0);

  /*! \brief Get the text.
   */
  const WString& text() const { return text_; }

  /*! \brief Change the text.
   */
  void setText(const WString& text);

  /*! \brief Set the formatting.
   */
  void setFormatting(Formatting formatting);

  /*! \brief Get the formatting.
   */
  Formatting formatting() const { return formatting_; }

  virtual void refresh();

  WLength hintedWidth() const;

private:
  WString      text_;
  Formatting   formatting_;

  bool         textChanged_;

  std::string  formattedText() const;

protected:
  virtual void        updateDom(DomElement& element, bool all);
  virtual DomElement *createDomElement();
  virtual void        getDomChanges(std::vector<DomElement *>& changes);
};

}

#endif // WTEXT_H_
