WGridLayout

// 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 WGRID_LAYOUT_H_
#define WGRID_LAYOUT_H_

#include <vector>
#include <Wt/WLayout>
#include <Wt/WLength>

namespace Wt {

  namespace Impl {

struct Grid {
  int horizontalSpacing_, verticalSpacing_;

  struct Row {
    int stretch_;

    Row(int stretch = 0);
  };

  struct Column {
    int stretch_;

    Column(int stretch = 0);
  };

  struct Item {
    WLayoutItem *item_;
    int rowSpan_;
    int colSpan_;
    int alignment_;

    Item(WLayoutItem *item = 0, int alignment = 0);
  };

  std::vector<Row>    rows_;
  std::vector<Column> columns_;
  std::vector<std::vector<Item> > items_; // [row][column]

  Grid();
  ~Grid();
};

  }

/*! \class WGridLayout Wt/WGridLayout Wt/WGridLayout
 *  \brief A layout manager which arranges widgets in a grid
 *
 * This is a layout class that arranges widgets in a grid, to span the
 * entire area of the parent container. Each grid location (row,
 * column) may contain one widget or nested layout. Horizontal and
 * vertical space are divided so that each column/row is given its
 * minimum size and the remaining space is dived according to stretch
 * factors among the columns/rows. The minimum width of a column/row
 * is based on the minimum dimensions of contained widgets or nested
 * layouts. The default minimum height and width may be overridden
 * using WWidget::setMinimumSize().
 *
 * Columns and rows are separated using a constant spacing, which
 * defaults to 6 pixels by default, and can be changed using
 * setHorizontalSpacing() and setVerticalSpacing(). In addition, when
 * this layout is a top-level layout (i.e. is not nested inside
 * another layout), a margin is set around the contents, which thus
 * replaces padding defined for the container. It is not allowed to
 * define padding for the container widget using its CSS 'padding'
 * property or the WContainerWidget::setPadding(). This margin also
 * defaults to 9 pixels, and can be changed using
 * setContentsMargins().
 *
 * For each column or row, a stretch factor may be defined, which
 * controls how remaining horizontal or vertical space is used. Each
 * column and row is stretched using the stretch factor to fill the
 * remaining space.
 *
 * \note This layout manager is applicable only to WContainerWidget
 * container widgets. You may use it within an Ext::Container
 * indirectly by first setting a WContainerWidget using a WFitLayout.
 *
 * \note When JavaScript support is not available, only Safari and
 * Firefox properly implement this layout. For other browsers, only
 * the horizontal layout is properly implemented, while vertically all
 * widgets use their minimum size.
 *
 * \note When set on a WContainerWidget, this layout manager accepts the
 *       following hints (see setLayoutHint()):
 *   <ul>
 *     <li>"table-layout" with possible values "auto" (default) or "fixed".<br/>
 *       Use "fixed" to prevent nested tables from overflowing the layout.
 *       In that case, you will need to specify a width (in CSS or otherwise)
 *       for at least one item in every column that has no stretch factor.</li>
 *  </ul>
 */
class WT_API WGridLayout : public WLayout
{
public:
  /*! \brief Create a new grid layout.
   *
   * The grid will grow dynamically as items are added.
   *
   * Use <i>parent</i>=0 to created a layout manager that can be
   * nested inside other layout managers.
   */
  WGridLayout(WWidget *parent = 0);

  virtual void addItem(WLayoutItem *item);
  virtual void removeItem(WLayoutItem *item);
  virtual WLayoutItem *itemAt(int index) const;
  virtual int count() const;

  /*! \brief Adds a layout item to the grid.
   *
   * Adds the <i>item</i> at (<i>row</i>, <i>column</i>). If an item
   * was already added to that location, it is replaced (but not
   * deleted).
   *
   * An item may span several more rows or columns, which is
   * controlled by <i>rowSpan</i> and <i>columnSpan</i>.
   *
   * The <i>alignment</i> specifies the vertical and horizontal
   * alignment of the item. The default value 0 indicates that the
   * item is stretched to fill the entire grid cell. The alignment can
   * be specified as a logical combination of a horizontal alignment
   * (Wt::AlignLeft, Wt::AlignCenter, or Wt::AlignRight) and a
   * vertical alignment (Wt::AlignTop, Wt::AlignMiddle, or
   * Wt::AlignBottom).
   *
   * \sa addLayout(WLayout *, int, int, int, int, int) 
   */
  void addItem(WLayoutItem *item, int row, int column,
	       int rowSpan = 1, int columnSpan = 1, int alignment = 0);

  /*! \brief Adds a nested layout item to the grid.
   *
   * Adds the <i>layout</i> at (<i>row</i>, <i>column</i>). If an item
   * was already added to that location, it is replaced (but not
   * deleted).
   *
   * The <i>alignment</i> specifies the vertical and horizontal
   * alignment of the item. The default value 0 indicates that the
   * item is stretched to fill the entire grid cell. The alignment can
   * be specified as a logical combination of a horizontal alignment
   * (Wt::AlignLeft, Wt::AlignCenter, or Wt::AlignRight) and a
   * vertical alignment (Wt::AlignTop, Wt::AlignMiddle, or
   * Wt::AlignBottom).
   *
   * \sa addLayout(WLayout *, int, int, int, int, int) 
   */
  void addLayout(WLayout *layout, int row, int column, int alignment = 0);

  /*! \brief Adds a nested layout item to the grid.
   *
   * Adds the <i>layout</i> at (<i>row</i>, <i>column</i>). If an item
   * was already added to that location, it is replaced (but not
   * deleted).
   *
   * An item may span several more rows or columns, which is
   * controlled by <i>rowSpan</i> and <i>columnSpan</i>.
   *
   * The <i>alignment</i> specifies the vertical and horizontal
   * alignment of the item. The default value 0 indicates that the
   * item is stretched to fill the entire grid cell. The alignment can
   * be specified as a logical combination of a horizontal alignment
   * (Wt::AlignLeft, Wt::AlignCenter, or Wt::AlignRight) and a
   * vertical alignment (Wt::AlignTop, Wt::AlignMiddle, or
   * Wt::AlignBottom).
   *
   * \sa addLayout(WLayout *, int, int, int) 
   */
  void addLayout(WLayout *layout, int row, int column,
		 int rowSpan, int columnSpan, int alignment = 0);

  /*! \brief Adds a widget to the grid.
   *
   * Adds the <i>widget</i> at (<i>row</i>, <i>column</i>). If an item
   * was already added to that location, it is replaced (but not
   * deleted).
   *
   * The <i>alignment</i> specifies the vertical and horizontal
   * alignment of the item. The default value 0 indicates that the
   * item is stretched to fill the entire grid cell. The alignment can
   * be specified as a logical combination of a horizontal alignment
   * (Wt::AlignLeft, Wt::AlignCenter, or Wt::AlignRight) and a
   * vertical alignment (Wt::AlignTop, Wt::AlignMiddle, or
   * Wt::AlignBottom).
   *
   * \sa addWidget(WWidget *, int, int, int, int, int) 
   */
  void addWidget(WWidget *widget, int row, int column, int alignment = 0);

  /*! \brief Adds a widget to the grid.
   *
   * Adds the <i>widget</i> at (<i>row</i>, <i>column</i>). If an item
   * was already added to that location, it is replaced (but not
   * deleted).
   *
   * The widget may span several more rows or columns, which is
   * controlled by <i>rowSpan</i> and <i>columnSpan</i>.
   *
   * The <i>alignment</i> specifies the vertical and horizontal
   * alignment of the item. The default value 0 indicates that the
   * item is stretched to fill the entire grid cell. The alignment can
   * be specified as a logical combination of a horizontal alignment
   * (Wt::AlignLeft, Wt::AlignCenter, or Wt::AlignRight) and a
   * vertical alignment (Wt::AlignTop, Wt::AlignMiddle, or
   * Wt::AlignBottom).
   *
   * \sa addWidget(WWidget *, int, int, int) 
   */
  void addWidget(WWidget *widget, int row, int column,
		 int rowSpan, int columnSpan, int alignment = 0);  

  /*! \brief Sets the horizontal spacing.
   *
   * The default horizontal spacing is 9 pixels.
   *
   * \sa setVerticalSpacing(int) 
   */
  void setHorizontalSpacing(int size);

  /*! \brief Returns the horizontal spacing.
   *
   * \sa setHorizontalSpacing(int) 
   */
  int horizontalSpacing() const { return grid_.horizontalSpacing_; }

  /*! \brief Sets the vertical spacing.
   *
   * The default vertical spacing is 9 pixels.
   *
   * \sa setHorizontalSpacing(int) 
   */
  void setVerticalSpacing(int size);

  /*! \brief Returns the vertical spacing.
   *
   * \sa setVerticalSpacing(int) 
   */
  int verticalSpacing() const { return grid_.verticalSpacing_; }

  /*! \brief Returns the column count.
   *
   * The grid dimensions change dynamically when adding contents to
   * the grid.
   *
   * \sa rowCount()
   */
  int columnCount() const;

  /*! \brief Returns the row count.
   *
   * The grid dimensions change dynamically when adding contents to
   * the grid.
   *
   * \sa columnCount()
   */
  int rowCount() const;

  /*! \brief Sets the column stretch.
   *
   * Sets the <i>stretch</i> factor for column <i>column</i>.
   *
   * \sa columnStretch()
   */
  void setColumnStretch(int column, int stretch);

  /*! \brief Returns the column stretch.
   *
   * \sa setColumnStretch(int, int)
   */
  int columnStretch(int column) const;

  /*! \brief Sets the row stretch.
   *
   * Sets the <i>stretch</i> factor for row <i>row</i>.
   *
   * \sa rowStretch()
   */
  void setRowStretch(int row, int stretch);

  /*! \brief Returns the column stretch.
   *
   * \sa setRowStretch(int, int)
   */
  int rowStretch(int row) const;

  Impl::Grid& grid() { return grid_; }

private:
  Impl::Grid grid_;

  void expand(int row, int column, int rowSpan, int columnSpan);
};

}

#endif // WGRID_LAYOUT_H_