qt-everywhere-src-5.14.1/qtbase/examples/corelib/tools/doc/src/customtype.qdoc

/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example tools/customtype
    \title Custom Type Example

    \brief The Custom Type example shows how to integrate a custom type into Qt's
    meta-object system.

    Contents:

    \tableofcontents

    \section1 Overview

    Qt provides a range of standard value types that are used to provide
    rich and meaningful APIs. These types are integrated with the meta-object
    system, enabling them to be stored in QVariant objects, written out in
    debugging information and sent between components in signal-slot
    communication.

    Custom types can also be integrated with the meta-object system as long as
    they are written to conform to some simple guidelines. In this example, we
    introduce a simple \c Message class, we describe how we make it work with
    QVariant, and we show how it can be extended to generate a printable
    representation of itself for use in debugging output.

    \section1 The Message Class Definition

    The \c Message class is a simple value class that contains two pieces
    of information (a QString and a QStringList), each of which can be read
    using trivial getter functions:

    \snippet tools/customtype/message.h custom type definition

    The default constructor, copy constructor and destructor are
    all required, and must be public, if the type is to be integrated into the
    meta-object system. Other than this, we are free to implement whatever we
    need to make the type do what we want, so we also include a constructor
    that lets us set the type's data members.

    To enable the type to be used with QVariant, we declare it using the
    Q_DECLARE_METATYPE() macro:

    \snippet tools/customtype/message.h custom type meta-type declaration

    We do not need to write any additional code to accompany this macro.

    To allow us to see a readable description of each \c Message object when it
    is sent to the debug output stream, we define a streaming operator:

    \snippet tools/customtype/message.h custom type streaming operator

    This facility is useful if you need to insert tracing statements in your
    code for debugging purposes.

    \section1 The Message Class Implementation

    The streaming operator is implemented in the following way:

    \snippet tools/customtype/message.cpp custom type streaming operator

    Here, we want to represent each value depending on how many lines are stored
    in the message body. We stream text to the QDebug object passed to the
    operator and return the QDebug object obtained from its maybeSpace() member
    function; this is described in more detail in the
    \l{Creating Custom Qt Types#Making the Type Printable}{Creating Custom Qt Types}
    document.

    We include the code for the getter functions for completeness:

    \snippet tools/customtype/message.cpp getter functions

    With the type fully defined, implemented, and integrated with the
    meta-object system, we can now use it.

    \section1 Using the Message

    In the example's \c{main()} function, we show how a \c Message object can
    be printed to the console by sending it to the debug stream:

    \snippet tools/customtype/main.cpp printing a custom type

    You can use the type with QVariant in exactly the same way as you would
    use standard Qt value types. Here's how to store a value using the
    QVariant::setValue() function:

    \snippet tools/customtype/main.cpp storing a custom value

    Alternatively, the QVariant::fromValue() function can be used if
    you are using a compiler without support for member template
    functions.

    The value can be retrieved using the QVariant::value() member template
    function:

    \snippet tools/customtype/main.cpp retrieving a custom value

    \section1 Further Reading

    The custom \c Message type can also be used with direct signal-slot
    connections.

    To register a custom type for use with queued signals and slots, such as
    those used in cross-thread communication, see the
    \l{Queued Custom Type Example}.

    More information on using custom types with Qt can be found in the
    \l{Creating Custom Qt Types} document.
*/