libwt-dev 3.3.0-1build1 / usr / include / Wt / WCssStyleSheet

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

#include <vector>
#include <set>
#include <string>

#include <Wt/WBreak>
#include <Wt/WCssDecorationStyle>

namespace Wt {

class WApplication;
class WCssStyleSheet;
class WCssTemplateWidget;

/*! \class WCssRule Wt/WCssStyleSheet Wt/WCssStyleSheet
 *  \brief Abstract rule in a CSS style sheet.
 *
 * A rule presents CSS style properties that are applied to a selected
 * set of elements.
 *
 * Use WCssTemplateRule if you would like to use a widget as a
 * template for specifying (<i>and</i> updating) a style rule, using
 * the widgets style properties, or WCssTextRule if you wish to
 * directly specify the CSS declarations.
 *
 * \sa WCssStyleSheet
 *
 * \ingroup style
 */
class WT_API WCssRule : public WObject
{
public:
  /*! \brief Destructor.
   */
  virtual ~WCssRule();

  /*! \brief Returns the selector.
   */
  const std::string& selector() const { return selector_; }

  /*! \brief Returns the style sheet to which this rule belongs.
   */
  WCssStyleSheet *sheet() const { return sheet_; }

  /*! \brief Indicates that the rule has changed and needs updating
   */
  void modified();

  /*! \brief Returns the declarations.
   *
   * This is a semi-colon separated list of CSS declarations.
   */
  virtual const std::string declarations() = 0;

  virtual bool updateDomElement(DomElement& cssRuleElement, bool all);

protected:
  /*! \brief Creates a new CSS rule with given selector.
   */
  WCssRule(const std::string& selector, WObject* parent = 0);

private:
  std::string  selector_;
  WCssStyleSheet *sheet_;

  friend class WCssStyleSheet;
};

/*! \class WCssTemplateRule Wt/WCssStyleSheet Wt/WCssStyleSheet
 *  \brief A CSS rule based on a template widget.
 *
 * This is a CSS rule whose CSS style properties are defined based on
 * properties of a template widget. When modifying the template
 * widget, these changes are reflected on the CSS rule and thus all
 * widgets that have this CSS rule.
 *
 * \if cpp
 * Usage example:
 * \code
 * Wt::WCssTemplateRule *styleRule = new Wt::WCssTemplateRule("#" + id() + " .item");
 * Wt::WApplication::instance()->styleSheet().addRule(styleRule);
 *
 * styleRule->templateWidget()->resize(100, WLength::Auto);
 * styleRule->templateWidget()->decorationStyle().setCursor(PointingHandCursor);
 * \endcode
 * \endif
 *
 * \sa Wt::WCssStyleSheet
 *
 * \ingroup style
 */
class WT_API WCssTemplateRule : public WCssRule
{
public:
  /*! \brief Creates a CSS rule with a given selector.
   *
   * The selector should be a valid CSS selector.
   *
   * \note If you want to update the rule, then the selector should be
   * unique and not contain commas, since this is not supported by
   * Microsoft Internet Explorer.
   */
  WCssTemplateRule(const std::string& selector, WObject* parent = 0);

  ~WCssTemplateRule();

  /*! \brief Returns the widget that is used as a template.
   *
   * Various properties of the widget are reflected in the CSS style:
   * - size and dimensions: WWidget::resize(), WWidget::setMinimumSize(),
   * and WWidget::setMaximumSize()
   * - its position: WWidget::setPositionScheme(), WWidget::setOffsets(),
   * WWidget::setFloatSide(), WWidget::setClearSides()
   * - visibility: WWidget::hide(), WWidget::show() and WWidget::setHidden()
   * - margins: WWidget::setMargin()
   * - line height: WWidget::setLineHeight()
   * - all decoration style properties: WWidget::decorationStyle()
   *
   * When modifying one of these properties of the returned widget, the
   * rule will be updated accordingly.
   */
  WWidget *templateWidget();

  const std::string declarations();

  bool updateDomElement(DomElement& cssRuleElement, bool all);

private:
  WCssTemplateWidget *widget_;
};

/*! \class WCssTextRule Wt/WCssStyleSheet Wt/WCssStyleSheet
 *  \brief A CSS rule specified directly using CSS declarations
 *
 * \if cpp
 * Usage example:
 * \code
 * Wt::WCssTextRule *styleRule = new Wt::WCssTextRule(".MyWidget .item", "width: 100px; cursor: pointer;");
 * Wt::WApplication::instance()->styleSheet().addRule(styleRule);
 * \endcode
 * \endif
 *
 * \sa WCssStyleSheet
 *
 * \ingroup style
 */
class WT_API WCssTextRule : public WCssRule
{
public:
  /*! \brief Creates a CSS rule with a given selector and declarations.
   */
  WCssTextRule(const std::string& selector, 
	       const WT_USTRING& declarations,
	       WObject* parent = 0);

  const std::string declarations();

private:
  WT_USTRING declarations_;
};

/*! \class WCssStyleSheet Wt/WCssStyleSheet Wt/WCssStyleSheet
 *  \brief A CSS style sheet.
 *
 * \if cpp
 * Usage example:
 * \code
 * Wt::WApplication::instance()->styleSheet().addRule(".MyWidget .item", "width: 100px; cursor: pointer;");
 * \endcode
 * \endif
 *
 * \sa WApplication::styleSheet()
 *
 * \ingroup style
 */
class WT_API WCssStyleSheet
{
public:
  /*! \brief Creates a new (internal) style sheet.
   */
  WCssStyleSheet();

  /*! \brief Creates a new (external) style sheet reference.
   */
  WCssStyleSheet(const WLink& link, const std::string& media = "all");

  /*! \brief Destroys a style sheet, and all rules in it.
   */
  ~WCssStyleSheet();

  const WLink& link() const { return link_; }
  const std::string& media() const { return media_; }

  /*! \brief Adds a CSS rule.
   *
   * Add a rule using the CSS selector \p selector, with CSS
   * declarations in \p declarations. These declarations must be a
   * list separated by semi-colons (;).
   *
   * Optionally, you may give a \p ruleName, which may later be
   * used to check if the rule was already defined.
   *
   * \sa isDefined()
   */
  WCssTextRule *addRule(const std::string& selector,
			const WT_USTRING& declarations,
			const std::string& ruleName = std::string());

#ifndef WT_TARGET_JAVA
  /* Interprets as UTF-8 */
  WCssTextRule *addRule(const std::string& selector,
			const std::string& declarations,
			const std::string& ruleName = std::string());

  /* Interprets as UTF-8 */
  WCssTextRule *addRule(const std::string& selector,
			const char *declarations,
			const std::string& ruleName = std::string());
#endif

  /*! \brief Adds a CSS rule.
   *
   * Add a rule using the CSS selector \p selector, with styles specified
   * in \p style.
   *
   * Optionally, you may give a \p ruleName, which may later be
   * used to check if the rule was already defined.
   *
   * \sa isDefined()
   */
  WCssTemplateRule *addRule(const std::string& selector,
			    const WCssDecorationStyle& style,
			    const std::string& ruleName = std::string());

  /*! \brief Adds a CSS rule.
   *
   * Optionally, you may give a \p ruleName, which may later be
   * used to check if the rule was already defined.
   *
   * \sa isDefined()
   */
  WCssRule *addRule(WCssRule *rule,
		    const std::string& ruleName = std::string());

  /*! \brief Returns if a rule was already defined in this style sheet.
   *
   * Returns whether a rule was added with the given \p ruleName.
   *
   * \sa addRule()
   */
  bool isDefined(const std::string& ruleName) const;

  /*! \brief Removes a rule.
   */
  void removeRule(WCssRule *rule);

  void ruleModified(WCssRule *rule);

  void cssText(WStringStream& out, bool all);

  void javaScriptUpdate(WApplication *app, WStringStream& js, bool all);

  void clear();

private:
  typedef std::vector<WCssRule *> RuleList;
  typedef std::set<WCssRule *> RuleSet;

  WLink link_;
  std::string media_;

  RuleList rules_;
  RuleList rulesAdded_;

  RuleSet rulesModified_;
  std::vector<std::string> rulesRemoved_;

  std::set<std::string> defined_;
};

}

#endif // WCSS_STYLE_SHEET_H_