// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \page creator-modeling.html
    \previouspage creator-reference.html

    \ingroup creator-reference-editors

    \title Model Editor

    \brief Create Universal Modeling Language (UML) style models with
    structured and behavioral diagrams.

    Use the model editor to create Universal Modeling Language (UML)
    style models with structured and behavioral diagrams that offer different
    views to your system. However, the editor uses a variant of UML and has only
    a subset of properties for specifying the appearance of model elements.

    Structural diagrams represent the static aspect of the system and are
    therefore stable, whereas behavioral diagrams have both static and dynamic
    aspects.

    You can create the following types of structural diagrams:

    \list
        \li Package diagrams, which consist of packages and their relationships
            and visualize how the system is packaged.
        \li Class diagrams, which consists of classes, dependencies,
            inheritance, associations, aggregation, and composition, and
            show a system in an object-oriented way.
        \li Component diagrams, which represent a set of components and their
            relationships and show the implementation of a system.
        \li Deployment diagrams, which represent a set of software and hardware
            components and their relationships and visualize the deployment
            of a system.
    \endlist

    You can create the following types of behavioral diagrams:

    \list
        \li Use case diagrams, which consists of actors, use cases, and their
            relationships, and represent a particular functionality of a system.
        \li Activity diagrams, which visualize the flow from one activity to
            another.
        \li Sequence diagrams, which consist of instances and specify where the
            instances are activated and destroyed and where their lifeline ends.
    \endlist

    \section1 Editing Models

    You can create models that have several different structural or behavioral
    diagrams. Add elements to the diagrams and specify properties for them. Use
    standard model elements or add your own elements with custom icons.

    \image qtcreator-modeleditor.webp {Class diagram in the model editor}
    \caption A class diagram in the model editor.

    Add elements to diagrams in the following ways:

    \list
        \li Drag elements from the element tool bar (1) to the
            editor (2).
        \li Select tool bar buttons (3) to add elements to the element tree (4).
        \li Drag elements from the element tree to the editor to add them and
            all their relations to the diagram.
        \li Drag source files from the sidebar views to the editor
            to add C++ classes or components to diagrams.

    \endlist

    \section2 Grouping Elements

    To group elements, surround them with a \e boundary. When you move
    the boundary, all elements within it move together.

    Similarly, drag a \e swimlane to the diagram. When you move the swimlane, all
    elements right to the swimlane (for vertical swimlanes) or below it (for
    horizontal swimlanes) move together.

    To create a vertical swimlane, drop the swimlane icon on the top border of
    the diagram. To create a horizontal swimlane, drop the icon near the left
    border.

    Classes or other objects that you lay on packages move with the packages.
    To move individual elements and modify their properties (5), select them.

    Use \e multiselection to group elements temporarily.

    \section2 Aligning Elements

    To align elements in the editor, select several elements and right-click to
    open a context menu. Select actions in \uicontrol {Align Objects} menu
    to align elements horizontally or vertically or to adjust their width and
    height.

    \section2 Managing Elements

    Drag the mouse over elements to select them and apply actions such as
    changing their \e stereotype or color. A stereotype is a classifier for
    elements, such as \e entity, \e control, \e interface, or \e boundary. An
    entity is usually a class that is used to store data. For some stereotypes,
    a custom icon is defined. You can assign several comma-separated stereotypes
    to one element.

    To add related elements to a diagram, select an element in the editor, and
    then select \uicontrol {Add Related Elements} in the context menu.

    By default, when you select an element in a diagram, it is highlighted also
    in \uicontrol Structure view. To change this behavior so that selecting
    an element in \uicontrol Structure makes it highlighted also in the
    diagram, select \inlineimage icons/linkicon.png and then select
    \uicontrol {Synchronize Diagram with Structure}.
    To keep the selections in the diagram and \uicontrol Structure view
    synchronized, select \uicontrol {Keep Synchronized}.

    \section2 Linking from Element Names to Files

    To link to a file from the name of an element, select the file in
    \uicontrol {Linked file}.

    \section2 Zooming into Diagrams

    To zoom into diagrams:

    \list
        \li Select \uicontrol {Zoom In} toolbar button.
        \li Select \key Ctrl++.
        \li Select \key Ctrl and roll the mouse wheel up.
    \endlist

    To zoom out of diagrams:

    \list
        \li Select \uicontrol {Zoom Out}.
        \li Select \key Ctrl+-.
        \li Select \key Ctrl and roll the mouse wheel down.
    \endlist

    To reset the diagram size to 100%:

    \list
        \li Select \uicontrol {Reset Zoom}.
        \li Select \key Ctrl+0.
    \endlist

    \section2 Printing Diagrams

    To print diagrams, select \key Ctrl+C when no elements are selected in
    the editor to copy all elements to the clipboard by using 300 dpi. Then
    paste the diagram to an application that can print images.

    If you copy a selection of elements in the editor, only those elements and
    their relations will be copied to the clipboard as an image.

    \section2 Exporting Diagrams as Images

    To save diagrams as images, go to \uicontrol File, and then select
    \uicontrol {Export Diagram}. To save only the selected parts of a diagram,
    select \uicontrol {Export Selected Elements}.

    \section1 Adding Custom Elements

    The model editor has the following built-in element types: package,
    component, class, and item.

    To use custom icons for the built-in elements, select an image file in
    \uicontrol {Image} in element properties.

    \image qtcreator-model-editor-component-diagram.webp {Component properties}
    \caption The Image field in Component properties.

    \section2 Using Definition Files

    For package, component, and class elements, you can use definition files to
    specify custom icons.

    The color, size, and form of the icon are
    determined by a stereotype. If you attach the stereotype to an element, the
    element icon is replaced by the custom icon. For example, you can attach the
    entity and interface stereotypes to classes and the database stereotype to
    components.

    The use case and activity diagrams are examples of using the built-in
    \e item element type to add custom elements. The item element has the form
    of a simple rectangle. The use case illustrates how to use a custom icon for
    an item. The attached stereotype is called \e usecase but it is hidden.
    Therefore, if you drag the use case to the diagram, it is shown as a use
    case but no stereotype appears to be defined and you can attach an
    additional stereotype to the use case.

    Color and icons are attached to elements in use case and activity diagrams
    by using a simple definition file format. For example, the following code
    adds the \c UseCase custom element:

    \code
    Icon {
        id: UseCase
        title: "Use-Case"
        elements: item
        stereotype: 'usecase'
        display: icon
        width: 40
        height: 20
        baseColor: #5fb4f0
        Shape {
            Ellipse { x: 20, y: 10, radiusX: 20, radiusY: 10 }
        }
    }
    \endcode

    For more information about the available options, see \e standard.def
    in the \e share/qtcreator/modeleditor directory in the \QC installation
    directory. It describes also how to define custom relation types
    and templates for existing types (such as a composition relation that
    can be drawn between classes).

    Add your own definition file and save it with the file extension
    \e .def to add custom colors and icons for stereotypes, elements, or tool
    bars. Either store this file in the same directory as the
    \e standard.def file or select the root element of a model and apply your
    \e .def file to the property \uicontrol {Config path}.

    \sa {Create Models and Diagrams}{How To: Create Models and Diagrams},
    {Create files}, {Sidebar Views}
*/

/*!
    \page creator-how-to-create-models.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-models

    \title Create UML-style models

    Use wizards to create UML-style models and \e {scratch models}.

    To create models and edit them in the model editor:

    \list 1

        \li Go to \uicontrol File > \uicontrol {New File} > \uicontrol Modeling
            > \uicontrol Model, and then select \uicontrol Choose.

            The model file opens in the model editor.

        \li Drag model elements to the editor and select them to
            specify properties for them:

            \image qtcreator-modeleditor-packages.webp {Package diagram in the model editor}
            \caption A package diagram in the model editor.

        \list 1

            \li In \uicontrol Stereotypes, enter the stereotype to
                apply to the element or select a predefined stereotype
                from the list.

            \li In \uicontrol Name, give a name to the element.

            \li In \uicontrol {Linked file}, select a file to create a link to
                it from the element name.

            \li In \uicontrol Image, select an image to use as a custom icon for
                the element.

            \li Select \uicontrol {Auto sized} to reset the
                element to its default size after you changed the element
                size by dragging its borders.

            \li In \uicontrol Color, select the color of the element.

            \li In \uicontrol Role, select a \e role to make the model
                element color lighter, darker, or softer. You can also remove
                color and draw the element outline or flatten the element by
                removing gradients.

            \li Select \uicontrol Emphasized to draw the model
                element with a thicker line.

            \li In \uicontrol {Stereotype display}, select:

                \list

                    \li \uicontrol Smart to display the stereotype as a
                        \uicontrol Label, a \uicontrol Decoration, or an
                        \uicontrol Icon, depending on the properties of the
                        element. For example, if a class has the stereotype
                        \uicontrol interface, it is displayed as an icon until
                        it becomes displayed members, after which it is
                        displayed as a decoration.

                    \li \uicontrol None to suppress the displaying of the
                        stereotype.

                    \li \uicontrol Label to display the stereotype as a line of
                        text using the standard form above the element name
                        even if the stereotype defines a custom icon.

                    \li \uicontrol Decoration to show the standard form of the
                        element with the stereotype as a small icon placed top
                        right if the stereotype defines a custom icon.

                    \li \uicontrol Icon to display the element using the custom
                        icon.

                \endlist

        \endlist

        \li To create a relation between two elements, select the arrow icon
            next to an element and drag it to the end point of the relation.

        \li Select the relation to specify settings for it, according to its
            type: inheritance, association, or dependency. You can specify the
            following settings for dependency relations, which are available for
            all element types:

        \list 1

            \li In \uicontrol Stereotypes, select the
                \e stereotype to apply to the relation.

            \li In \uicontrol Name, give a name to the relation.

            \li In \uicontrol Direction, change the direction
                of the connection or make it bidirectional.

        \endlist

        \li To move the end of a relation to a different element, drag the
            end point over another element that accepts relations
            of that type. For example, only classes accept inheritances and
            associations.

        \li To create \e {sampling points} that divide a relation into two
            connected lines, select a relation and select \key Shift and click
            on the relation line.

            If possible, the end point of a relation is moved automatically
            to draw the line to the next sampling point either vertically or
            horizontally.

        \li To remove a sampling point, select \key Ctrl and click the sampling
            point.

        \li To group elements, drag a \uicontrol Boundary element to
            the editor and resize it to enclose the elements in the group.

    \endlist

    \section1 Create scratch models

    Use a scratch model to quickly put a temporary diagram together. The wizard
    creates the model file in a temporary folder without any input from you.
    Therefore, you can assign a \l{Keyboard Shortcuts}{keyboard shortcut} to the
    wizard and use it to create and open models with empty diagrams.

    To create a scratch model, go to \uicontrol File > \uicontrol {New File} >
    \uicontrol Modeling > \uicontrol {Scratch Model}, and then select
    \uicontrol Choose.

    \sa {Create Models and Diagrams}{How To: Create Models and Diagrams},
    {Model Editor}
*/

/*!
    \page creator-how-to-create-package-diagrams.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-models

    \title Create package diagrams

    Create UML-style models that contain \e {package diagrams}.
    They show packages and their relationships to visualize how the
    system is packaged.

    Add nested package elements to a package diagram. The depth of the
    elements in the diagram corresponds to the depth of the structured model.
    Elements stacked on other elements of the same type are automatically drawn
    in a darker shade of the selected color.

    \image qtcreator-modeleditor-packages.webp {Package diagram in the model editor}
    \caption A package diagram in the model editor.

    Right-click a package to open a context menu, and select
    \uicontrol {Create Diagram} to create a new package diagram within the
    model. Drag items from the element tree to the diagram.

    To update the include dependencies of the package, select
    \uicontrol {Update Include Dependencies}.

    \sa {Create Models and Diagrams}{How To: Create Models and Diagrams},
    {Model Editor}
*/

/*!
    \page creator-how-to-create-class-diagrams.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-models

    \title Create class diagrams

    Create UML-style models that contain \e {class diagrams}. They show
    classes, dependencies, inheritance, associations, aggregation, and
    composition to visualize a system in an object-oriented way.

    \image qtcreator-modeleditor-classes.webp {Class diagram in the model editor}
    \caption A class diagram in the model editor.

    To create class diagrams:

    \list 1

        \li To add C++ classes to class diagrams, drag files from
            \uicontrol Projects to the editor, and select
            \uicontrol {Add Class}.

        \li In addition to the common element properties, you can specify the
            following properties:

            \list

                \li In \uicontrol Template, specify the template to
                    use.

                \li In \uicontrol {Template display}, select the
                    display format for the template:

                    \list

                        \li \uicontrol Smart displays the template as
                            \uicontrol Box or \uicontrol {Angle brackets},
                            depending on the class properties.

                        \li \uicontrol Box displays the template in a small box
                            with a dotted border in the top right corner of the
                            class icon.

                        \li \uicontrol {Angle brackets} writes the template
                            in angle brackets behind the class name using the
                            C++ syntax.

                    \endlist

                \li In \uicontrol Members, specify members for the
                    class, as described in \l {Specify members}.

                \li Select \uicontrol {Clean Up} to format the contents of
                    \uicontrol Members depending on their visibility
                    (private, protected, public) and following the rules set for
                    whitespace, line breaks, and so on.

                \li Select \uicontrol {Show members} to show
                    the members in the diagram.

            \endlist

    \endlist

    To navigate from a class in a diagram to the source code, double-click the
    class in the editor or select \uicontrol {Show Definition} in the context
    menu.

    \section1 Add relations

    Elements in class diagrams can have the following types of relations:

    \list
        \li Aggregation
        \li Association
        \li Composition
        \li Dependency
        \li Inheritance
    \endlist

    The end points of association relations can have the following properties:

    \list
        \li Cardinality
        \li Navigable
        \li Role
        \li Relationship
    \endlist

    \section2 Create self-relations

    To create self-relations, start creating a new association and press
    \key Shift to create a new \e {sampling point} while dragging the
    association. Create another sampling point and drag the association
    to the same class.

    \section2 Add and delete points

    To add more points, select \key Shift and click a relation.

    To delete a point, select \key Ctrl and click a point.

    \section2 Specify members

    To specify members for the class, enter each member on a separate line
    using a C++ like syntax. For example, the following lines define the
    method \c m that is private, virtual, and constant:

    \code
        private:
        virtual int m(string a) const;
    \endcode

    You may group members:

    \code
        [Geometry]
        QPointF position;
        QSizeF size;
    \endcode

    You may add stereotypes to members:

    \code
    <<setter>> setPosition(const QPointF &pos);
    \endcode

    There are some limitations of the parser:

    \list

        \li Multi-line declarations work only if lines are wrapped
            within nested brackets:

            \code
                void setSize(int width,
                             int height);
            \endcode

        \li Preprocessor macros will not be translated. Some Qt
            keywords are recognized (for example Q_SLOT).

        \li Function pointer declarations are interpreted as methods.

        \li \c throw() and \c noexpect() specifiers are not ignored
            but will make the declaration a method.

    \endlist

    \sa {Create Models and Diagrams}{How To: Create Models and Diagrams},
    {Model Editor}
*/

/*!
    \page creator-how-to-create-component-diagrams.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-models

    \title Create component diagrams

    Create UML-style models that contain \e {component diagrams}.
    They represent a set of components and their relationships, and show the
    implementation of a system.

    Add source code components, such as libraries, databases, programs,
    and architectural layers to a component diagram.

    To add components to component diagrams:

    \list 1
        \li Drag source code from \uicontrol Projects to the editor.
        \li Select \uicontrol {Add Component}.
    \endlist

    \image qtcreator-model-editor-component-diagram.webp {Component diagram in the model editor}
    \caption A component diagram in the model editor.

    To navigate from a component in a diagram to the source code, double-click
    the component in the editor or select \uicontrol {Show Definition} in the
    context menu.

    \sa {Create Models and Diagrams}{How To: Create Models and Diagrams},
    {Model Editor}
*/
