libcegui-mk2-dev 0.7.6-3.3 / usr / include / CEGUI / elements / CEGUIGridLayoutContainer.h

/***********************************************************************
    filename:   CEGUIGridLayoutContainer.h
    created:    01/8/2010
    author:     Martin Preisler

    purpose:    Interface to a vertical layout container
*************************************************************************/
/***************************************************************************
 *   Copyright (C) 2004 - 2010 Paul D Turner & The CEGUI Development Team
 *
 *   Permission is hereby granted, free of charge, to any person obtaining
 *   a copy of this software and associated documentation files (the
 *   "Software"), to deal in the Software without restriction, including
 *   without limitation the rights to use, copy, modify, merge, publish,
 *   distribute, sublicense, and/or sell copies of the Software, and to
 *   permit persons to whom the Software is furnished to do so, subject to
 *   the following conditions:
 *
 *   The above copyright notice and this permission notice shall be
 *   included in all copies or substantial portions of the Software.
 *
 *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 *   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 *   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 *   IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 *   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 *   OTHER DEALINGS IN THE SOFTWARE.
 ***************************************************************************/
#ifndef _CEGUIGridLayoutContainer_h_
#define _CEGUIGridLayoutContainer_h_

#include "CEGUILayoutContainer.h"
#include "../CEGUIWindowFactory.h"
#include "CEGUIGridLayoutContainerProperties.h"

#if defined(_MSC_VER)
#   pragma warning(push)
#   pragma warning(disable : 4251)
#endif

// Start of CEGUI namespace section
namespace CEGUI
{
/*!
\brief
    A Layout Container window layouting it's children into a grid
*/
class CEGUIEXPORT GridLayoutContainer : public LayoutContainer
{
public:
    /**
     * enumerates auto positioning methods for the grid - these allow you to
     * fill the grid without specifying gridX and gridY positions for each
     * addChildWindow.
     */
    enum AutoPositioning
    {
        //! no auto positioning!
        AP_Disabled,
        /**
         * Left to right positioning:
         * - 1 2 3
         * - 4 5 6
         */
        AP_LeftToRight,
        /**
         * Top to bottom positioning
         * - 1 3 5
         * - 2 4 6
         */
        AP_TopToBottom
    };

    /*************************************************************************
        Constants
    *************************************************************************/
    //! The unique typename of this widget
    static const String WidgetTypeName;

    /*************************************************************************
        Child Widget name suffix constants
    *************************************************************************/
    //! Widget name suffix for dummies.
    static const String DummyNameSuffix;

    /*************************************************************************
        Event name constants
    *************************************************************************/
    //! Namespace for global events
    static const String EventNamespace;

    //! fired when child windows get rearranged
    static const String EventChildWindowOrderChanged;

    /*************************************************************************
        Construction and Destruction
    *************************************************************************/
    /*!
    \brief
        Constructor for GUISheet windows.
    */
    GridLayoutContainer(const String& type, const String& name);

    /*!
    \brief
        Destructor for GUISheet windows.
    */
    virtual ~GridLayoutContainer(void);

    /*!
    \brief
        Sets grid's dimensions.
    */
    void setGridDimensions(size_t width, size_t height);

    /*!
    \brief
        Retrieves grid width, the amount of cells in one row
    */
    size_t getGridWidth() const;

    /*!
    \brief
        Retrieves grid height, the amount of rows in the grid
    */
    size_t getGridHeight() const;

    /*!
    \brief
        Sets new auto positioning method.

    \par
        The newly set auto positioning sequence will start over!
        Use setAutoPositioningIdx to set it's starting point
    */
    void setAutoPositioning(AutoPositioning positioning);

    /*!
    \brief
        Retrieves current auto positioning method.
    */
    AutoPositioning getAutoPositioning() const;

    /*!
    \brief
        Sets the next auto positioning "sequence position", this will be used
        next time when addChildWindow is called.
    */
    void setNextAutoPositioningIdx(size_t idx);

    /*!
    \brief
        Retrieves auto positioning "sequence position", this will be used next
        time when addChildWindow is called.
    */
    size_t getNextAutoPositioningIdx() const;

    /*!
    \brief
        Skips given number of cells in the auto positioning sequence
    */
    void autoPositioningSkipCells(size_t cells);

    /*!
    \brief
        Add the specified Window to specified grid position as a child of
        this Grid Layout Container.  If the Window \a window is already
        attached to a Window, it is detached before being added to this Window.

    \par
        If something is already in given grid cell, it gets removed!

    \par
        This disabled auto positioning from further usage! You need to call
        setAutoPositioning(..) to set it back to your desired value and use
        setAutoPositioningIdx(..) to set it's starting point back

    \see
        Window::addChildWindow
    */
    void addChildWindowToPosition(Window* window, size_t gridX, size_t gridY);

    /*!
    \brief
        Add the named Window to specified grid position as a child of
        this Grid Layout Container.  If the Window \a window is already
        attached to a Window, it is detached before being added to this Window.

    \par
        If something is already in given grid cell, it gets removed!

    \par
        This disabled auto positioning from further usage! You need to call
        setAutoPositioning(..) to set it back to your desired value and use
        setAutoPositioningIdx(..) to set it's starting point back

    \see
        Window::addChildWindow
    */
    void addChildWindowToPosition(const String& name, size_t gridX, size_t gridY);

    /*!
    \brief
        Retrieves child window that is currently at given grid position
    */
    Window* getChildWindowAtPosition(size_t gridX, size_t gridY);

    /*!
    \brief
        Removes the child window that is currently at given grid position

    \see
        Window::removeChildWindow
    */
    void removeChildWindowFromPosition(size_t gridX, size_t gridY);

    /*!
    \brief
        Swaps positions of 2 windows given by their index

    \par
        For advanced users only!
    */
    virtual void swapChildWindowPositions(size_t wnd1, size_t wnd2);

    /*!
    \brief
        Swaps positions of 2 windows given by grid positions
    */
    void swapChildWindowPositions(size_t gridX1, size_t gridY1,
                                  size_t gridX2, size_t gridY2);

    /*!
    \brief
        Swaps positions of given windows
    */
    void swapChildWindows(Window* wnd1, Window* wnd2);

    /*!
    \brief
        Swaps positions of given windows
    */
    void swapChildWindows(Window* wnd1, const String& wnd2);

    /*!
    \brief
        Swaps positions of given windows
    */
    void swapChildWindows(const String& wnd1, Window* wnd2);

    /*!
    \brief
        Moves given child window to given grid position
    */
    void moveChildWindowToPosition(Window* wnd, size_t gridX, size_t gridY);

    /*!
    \brief
        Moves named child window to given grid position
    */
    void moveChildWindowToPosition(const String& wnd,
                                   size_t gridX, size_t gridY);

    //! @copydoc LayoutContainer::layout
    virtual void layout();

protected:
    /*!
    \brief
        Handler called when children of this window gets rearranged in any way

    \param e
        WindowEventArgs object whose 'window' field is set this layout
        container.
    */
    virtual void onChildWindowOrderChanged(WindowEventArgs& e);

    //! converts from grid cell position to idx
    size_t mapFromGridToIdx(size_t gridX, size_t gridY,
                            size_t gridWidth, size_t gridHeight) const;
    //! converts from idx to grid cell position
    void mapFromIdxToGrid(size_t idx, size_t& gridX, size_t& gridY,
                          size_t gridWidth, size_t gridHeight) const;

    /** calculates grid cell offset
     * (relative to position of this layout container)
     */
    UVector2 getGridCellOffset(const std::vector<UDim>& colSizes,
                               const std::vector<UDim>& rowSizes,
                               size_t gridX, size_t gridY) const;
    //! calculates total grid size
    UVector2 getGridSize(const std::vector<UDim>& colSizes,
                         const std::vector<UDim>& rowSizes) const;

    //! translates auto positioning index to absolute grid index
    size_t translateAPToGridIdx(size_t APIdx) const;

    //! stores grid width - amount of columns
    size_t d_gridWidth;
    //! stores grid height - amount of rows
    size_t d_gridHeight;

    //! stores currently used auto positioning method
    AutoPositioning d_autoPositioning;
    /** stores next auto positioning index (will be used for next
     * added window if d_autoPositioning != AP_Disabled)
     */
    size_t d_nextAutoPositioningIdx;

    /** stores next used grid X position
     * (only used if d_autoPositioning == AP_Disabled)
     */
    size_t d_nextGridX;
    /** stores next used grid Y position
     * (only used if d_autoPositioning == AP_Disabled)
     */
    size_t d_nextGridY;

    /** stores next used dummy suffix index
     * (used to generate unique dummy names)
     */
    size_t d_nextDummyIdx;

    //! creates a dummy window
    Window* createDummy();
    //! checks whether given window is a dummy
    bool isDummy(Window* wnd) const;

    /// @copydoc Window::addChild_impl
    virtual void addChild_impl(Window* wnd);
    /// @copydoc Window::removeChild_impl
    virtual void removeChild_impl(Window* wnd);

    /*!
    \brief
        Return whether this window was inherited from the given class name at
        some point in the inheritance hierarchy.

    \param class_name
        The class name that is to be checked.

    \return
        true if this window was inherited from \a class_name. false if not.
    */
    virtual bool    testClassName_impl(const String& class_name) const
    {
        if (class_name == "GridLayoutContainer")  return true;

        return LayoutContainer::testClassName_impl(class_name);
    }

private:
    /*************************************************************************
        Properties for GridLayoutContainer class
    *************************************************************************/
    static GridLayoutContainerProperties::GridSize d_gridSizeProperty;
    static GridLayoutContainerProperties::AutoPositioning d_autoPositioningProperty;

    void addGridLayoutContainerProperties(void);
};

} // End of  CEGUI namespace section

#if defined(_MSC_VER)
#   pragma warning(pop)
#endif

#endif  // end of guard _CEGUIGridLayoutContainer_h_