/****************************************************************************

**

** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \example graphicsview/diagramscene

    \title Diagram Scene Example

    This example shows use of Qt's graphics framework. 

    \image diagramscene.png

    The Diagram Scene example is an application in which you can

    create a flowchart diagram. It is possible to add flowchart shapes

    and text and connect the shapes by arrows as shown in the image

    above.  The shapes, arrows, and text can be given different

    colors, and it is possible to change the font, style, and

    underline of the text.

    The Qt graphics view framework is designed to manage and

    display custom 2D graphics items. The main classes of the

    framework are QGraphicsItem, QGraphicsScene and QGraphicsView. The

    graphics scene manages the items and provides a surface for them.

    QGraphicsView is a widget that is used to render a scene on the

    screen. See the \l{The Graphics View Framework}{overview document}

    for a more detailed description of the framework. 

    In this example we show how to create such custom graphics

    scenes and items by implementing classes that inherit

    QGraphicsScene and QGraphicsItem. 

    In particular we show how to:

    \list

	\o Create custom graphics items.

	\o Handle mouse events and movement of items.

	\o Implement a graphics scene that can manage our custom items.

	\o Custom painting of items.

	\o Create a movable and editable text item.

    \endlist

    The example consists of the following classes:

    \list

	\o \c MainWindow creates the widgets and display

	   them in a QMainWindow. It also manages the interaction 

	   between the widgets and the graphics scene, view and 

	   items.

	\o \c DiagramItem inherits QGraphicsPolygonItem and

	   represents a flowchart shape. 

	\o \c TextDiagramItem inherits QGraphicsTextItem and

	   represents text items in the diagram. The class adds

	   support for moving the item with the mouse, which is not

	   supported by QGraphicsTextItem.

	\o \c Arrow inherits QGraphicsLineItem and is an arrow

	   that connect two DiagramItems. 

	\o \c DiagramScene inherits QGraphicsDiagramScene and

	   provides support for \c DiagramItem, \c Arrow and 

	   \c DiagramTextItem (In addition to the support already

	   handled by QGraphicsScene).

    \endlist

    \section1 MainWindow Class Definition

    \snippet examples/graphicsview/diagramscene/mainwindow.h 0

    The \c MainWindow class creates and lays out the widgets in a

    QMainWindow. The class forwards input from the widgets to the

    DiagramScene. It also updates its widgets when the diagram 

    scene's text item changes, or a diagram item or a diagram text item

    is inserted into the scene.

    The class also deletes items from the scene and handles the

    z-ordering, which decides the order in which items are drawn when

    they overlap each other.

    \section1 MainWindow Class Implementation

    We start with a look at the constructor:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 0

    In the constructor we call methods to create the widgets and

    layouts of the example before we create the diagram scene. 

    The toolbars must be created after the scene as they connect 

    to its signals. We then lay the widgets out in the window.

    We connect to the \c itemInserted() and \c textInserted() slots of

    the diagram scenes as we want to uncheck the buttons in the tool

    box when an item is inserted. When an item is selected in

    the scene we receive the \c itemSelected() signal. We use this to

    update the widgets that display font properties if the item

    selected is a \c DiagramTextItem.

    The \c createToolBox() function creates and lays out the widgets 

    of the \c toolBox QToolBox. We will not examine it with a

    high level of detail as it does not deal with graphics framework 

    specific functionality. Here is its implementation:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 21

    This part of the function sets up the tabbed widget item that

    contains the flowchart shapes. An exclusive QButtonGroup always 

    keeps one button checked; we want the group to allow all buttons

    to be unchecked.

    We still use a button group since we can associate user

    data, which we use to store the diagram type, with each button. 

    The \c createCellWidget() function sets up the buttons in the 

    tabbed widget item and is examined later.

    The buttons of the background tabbed widget item is set up in the

    same way, so we skip to the creation of the tool box:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 22

    We set the preferred size of the toolbox as its maximum. This

    way, more space is given to the graphics view. 

    Here is the \c createActions() function:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 23

    We show an example of the creation of an action. The

    functionality the actions trigger is discussed in the slots we

    connect the actions to. You can see the \l{Application

    Example}{application example} if you need a high-level

    introduction to actions.

    The is the \c createMenus() function:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 24

    We create the three menus' of the example.

    The \c createToolbars() function sets up the examples tool

    bars.  The three \l{QToolButton}s in the \c colorToolBar, the \c

    fontColorToolButton, \c fillColorToolButton, and \c

    lineColorToolButton, are interesting as we create icons for them

    by drawing on a QPixmap with a QPainter. We show how the \c

    fillColorToolButton is created. This button lets the user select a

    color for the diagram items.

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 25

    \dots

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 26

    We set the menu of the tool button with

    \l{QToolButton::}{setMenu()}. We need the \c fillAction QAction

    object to always be pointing to the selected action of the menu.

    The menu is created with the \c createColorMenu() function and, as

    we shall see later, contains one menu item for each color that the

    items can have.  When the user presses the button, which trigger

    the \l{QToolButton::}{clicked()} signal, we can set the color of

    the selected item to the color of \c fillAction. It is with \c

    createColorToolButtonIcon() we create the icon for the button.

    \dots

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 27

    Here is the \c createBackgroundCellWidget() function:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 28

    This function creates \l{QWidget}s containing a tool button

    and a label. The widgets created with this function are used for

    the background tabbed widget item in the tool box.

    Here is the \c createCellWidget() function:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 29

    This function returns a QWidget containing a QToolButton with

    an image of one of the \c DiagramItems, i.e., flowchart shapes.

    The image is created by the \c DiagramItem through the \c image()

    function.  The QButtonGroup class lets us attach a QVariant with

    each button; we store the diagram's type, i.e., the

    DiagramItem::DiagramType enum. We use the stored diagram type when

    we create new diagram items for the scene.  The widgets created

    with this function is used in the tool box.

    Here is the \c createColorMenu() function:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 30

    This function creates a color menu that is used as the

    drop-down menu for the tool buttons in the \c colorToolBar. We

    create an action for each color that we add to the menu. We fetch

    the actions data when we set the color of items, lines, and text.

    Here is the \c createColorToolButtonIcon() function:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 31

    This function is used to create the QIcon of the \c

    fillColorToolButton, \c fontColorToolButton, and \c

    lineColorToolButton. The \a imageFile string is either the text,

    flood-fill, or line symbol that is used for the buttons. Beneath

    the image we draw a filled rectangle using \a color.

    Here is the \c createColorIcon() function:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 32

    This function creates an icon with a filled rectangle in the 

    color of \a color. It is used for creating icons for the color

    menus in the \c fillColorToolButton, \c fontColorToolButton, and

    \c lineColorToolButton.

    Here is the \c backgroundButtonGroupClicked() slot:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 1

    In this function we set the QBrush that is used to draw the

    background of the diagramscene. The background can be a grid of

    squares of blue, gray, or white tiles, or no grid at all. We have

    \l{QPixmap}s of the tiles from png files that we create the brush

    with.

    When one of the buttons in the background tabbed widget item is

    clicked we change the brush; we find out which button it is by 

    checking its text. 

    Here is the implementation of \c buttonGroupClicked():

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 2

    This slot is called when a button in \c buttonGroup is checked.

    When a button is checked the user can click on the graphics view

    and a \c DiagramItem of the selected type will be inserted into

    the \c DiagramScene. We must loop through the buttons in the group

    to uncheck other buttons as only one button is allowed to be

    checked at a time.

    \c QButtonGroup assigns an id to each button. We have set the id

    of each button to the diagram type, as given by DiagramItem::DiagramType 

    that will be inserted into the scene when it is clicked. We can 

    then use the button id when we set the diagram type with 

    \c setItemType(). In the case of text we assigned an id that has a

    value that is not in the DiagramType enum.

    Here is the implementation of \c deleteItem():

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 3

    This slot deletes the selected item, if any, from the scene. If

    the item to be deleted is a \c DiagramItem, we also need to delete

    arrows connected to it; we don't want arrows in the scene that

    aren't connected to items in both ends.

    This is the implementation of pointerGroupClicked():

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 4

    The \c pointerTypeGroup decides whether the scene is in ItemMove

    or InsertLine mode. This button group is exclusive, i.e., only 

    one button is checked at any time. As with the \c buttonGroup above

    we have assigned an id to the buttons that matches values of the

    DiagramScene::Mode enum, so that we can use the id to set the

    correct mode.

    Here is the \c bringToFront() slot:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 5

    Several items may collide, i.e., overlap, with each other in

    the scene.  This slot is called when the user requests that an

    item should be placed on top of the items it collides with.

    \l{QGraphicsItem}{QGrapicsItems} have a z-value that decides the

    order in which items are stacked in the scene; you can think of it

    as the z-axis in a 3D coordinate system.  When items collide the

    items with higher z-values will be drawn on top of items with

    lower values. When we bring an item to the front we can loop

    through the items it collides with and set a z-value that is

    higher than all of them.

    Here is the \c sendToBack() slot:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 6

    This slot works in the same way as \c bringToFront() described

    above, but sets a z-value that is lower than items the item that

    should be send to the back collides with.

    This is the implementation of \c itemInserted():

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 7

    This slot is called from the \c DiagramScene when an item has been

    added to the scene. We set the mode of the scene back to the mode

    before the item was inserted, which is ItemMove or InsertText

    depending on which button is checked in the \c pointerTypeGroup. 

    We must also uncheck the button in the in the \c buttonGroup.

    Here is the implementation of \c textInserted():

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 8

    We simply set the mode of the scene back to the mode it had before

    the text was inserted.

    Here is the \c currentFontChanged() slot:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 9

    When the user requests a font change, by using one of the

    widgets in the \c fontToolBar, we create a new QFont object and

    set its properties to match the state of the widgets. This is done

    in \c handleFontChange(), so we simply call that slot.

    Here is the \c fontSizeChanged() slot:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 10

    When the user requests a font change, by using one of the

    widgets in the \c fontToolBar, we create a new QFont object and

    set its properties to match the state of the widgets. This is done

    in \c handleFontChange(), so we simply call that slot.

    Here is the implementation of \c sceneScaleChanged():

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 11

    The user can increase or decrease the scale, with the \c

    sceneScaleCombo, the scene is drawn in.

    It is not the scene itself that changes its scale, but only the

    view.  

    Here is the \c textColorChanged() slot:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 12

    This slot is called when an item in the drop-down menu of the \c

    fontColorToolButton is pressed. We need to change the icon on 

    the button to the color of the selected QAction. We keep a pointer

    to the selected action in \c textAction. It is in \c

    textButtonTriggered() we change the text color to the color of \c

    textAction, so we call that slot.

    Here is the \c itemColorChanged() implementation:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 13

    This slot handles requests for changing the color of \c

    DiagramItems in the same manner as \c textColorChanged() does for

    \c DiagramTextItems.

    Here is the implementation of \c lineColorChanged():

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 14

    This slot handles requests for changing the color of \c Arrows in

    the same manner that \c textColorChanged() does it for \c

    DiagramTextItems.

    Here is the \c textButtonTriggered() slot:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 15

    \c textAction points to the  QAction of the currently selected menu item

    in the \c fontColorToolButton's color drop-down menu. We have set

    the data of the action to the QColor the action represents, so we

    can simply fetch this when we set the color of text with \c

    setTextColor().

    Here is the \c fillButtonTriggered() slot:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 16

    \c fillAction points to the selected menu item in the drop-down

    menu of \c fillColorToolButton(). We can therefore use the data of

    this action when we set the item color with \c setItemColor().

    Here is the \c lineButtonTriggered() slot:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 17

    \c lineAction point to the selected item in the drop-down menu of

    \c lineColorToolButton. We use its data when we set the arrow 

    color with \c setLineColor().

    Here is the \c handleFontChange() function:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 18

    \c handleFontChange() is called when any of the widgets that show

    font properties changes. We create a new QFont object and set its

    properties based on the widgets. We then call the \c setFont()

    function of \c DiagramScene; it is the scene that set the font of

    the \c DiagramTextItems it manages.

    Here is the \c itemSelected() slot:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 19

    This slot is called when an item in the \c DiagramScene is

    selected. In the case of this example it is only text items that

    emit signals when they are selected, so we do not need to check

    what kind of graphics \a item is.

    We set the state of the widgets to match the properties of the

    font of the selected text item.

    This is the \c about() slot:

    \snippet examples/graphicsview/diagramscene/mainwindow.cpp 20

    This slot displays an about box for the example when the user

    selects the about menu item from the help menu.

    \section1 DiagramScene Class Definition

    The \c DiagramScene class inherits QGraphicsScene and adds

    functionality to handle \c DiagramItems, \c Arrows, and \c

    DiagramTextItems in addition to the items handled by its super

    class.

    \snippet examples/graphicsview/diagramscene/diagramscene.h 0

    In the \c DiagramScene a mouse click can give three different

    actions: the item under the mouse can be moved, an item may be

    inserted, or an arrow may be connected between to diagram items.

    Which action a mouse click has depends on the mode, given by the

    Mode enum, the scene is in. The mode is set with the \c setMode()

    function.

    The scene also sets the color of its items and the font of its

    text items.  The colors and font used by the scene can be set with

    the \c setLineColor(), \c setTextColor(), \c setItemColor() and \c

    setFont() functions. The type of \c DiagramItem, given by the

    DiagramItem::DiagramType function, to be created when an item is

    inserted is set with the \c setItemType() slot.

    The \c MainWindow and \c DiagramScene share responsibility for

    the examples functionality. \c MainWindow handles the following

    tasks: the deletion of items, text, and arrows; moving diagram

    items to the back and front; and setting the scale of the scene. 

    \section1 DiagramScene Class Implementation

    We start with the constructor:

    \snippet examples/graphicsview/diagramscene/diagramscene.cpp 0

    The scene uses \c myItemMenu to set the context menu when it

    creates \c DiagramItems. We set the default mode to \c

    DiagramScene::MoveItem as this gives the default behavior of

    QGraphicsScene.

    Here is the \c setLineColor() function:

    \snippet examples/graphicsview/diagramscene/diagramscene.cpp 1

    The \c isItemChange function returns true if an \c Arrow item is

    selected in the scene in which case we want to change its color.

    When the \c DiagramScene creates and adds new arrows to the scene

    it will also use the new \a color.

    Here is the \c setTextColor() function:

    \snippet examples/graphicsview/diagramscene/diagramscene.cpp 2

    This function sets the color of \c DiagramTextItems equal to the

    way \c setLineColor() sets the color of \c Arrows.

    Here is the \c setItemColor() function:

    \snippet examples/graphicsview/diagramscene/diagramscene.cpp 3

    This function sets the color the scene will use when creating 

    \c DiagramItems. It also changes the color of a selected \c

    DiagramItem.

    This is the implementation of \c setFont():

    \snippet examples/graphicsview/diagramscene/diagramscene.cpp 4

    Set the font to use for new and selected, if a text item is

    selected, \c DiagramTextItems.

    This is the implementation of \c editorLostFocus() slot:

    \snippet examples/graphicsview/diagramscene/diagramscene.cpp 5

    \c DiagramTextItems emit a signal when they loose focus, which is

    connected to this slot. We remove the item if it has no text.

    If not, we would leak memory and confuse the user as the items

    will be edited when pressed on by the mouse.

    The \c mousePressEvent() function handles mouse press event's

    different depending on which mode the \c DiagramScene is in. We