diff --git a/examples/corelib/tools/CMakeLists.txt b/examples/corelib/tools/CMakeLists.txt index 0ec145da297..39623d5ba3f 100644 --- a/examples/corelib/tools/CMakeLists.txt +++ b/examples/corelib/tools/CMakeLists.txt @@ -5,5 +5,3 @@ if(NOT TARGET Qt6::Widgets) return() endif() qt_internal_add_example(contiguouscache) -qt_internal_add_example(customtype) -qt_internal_add_example(customtypesending) diff --git a/examples/corelib/tools/customtype/CMakeLists.txt b/examples/corelib/tools/customtype/CMakeLists.txt deleted file mode 100644 index 21c9003f560..00000000000 --- a/examples/corelib/tools/customtype/CMakeLists.txt +++ /dev/null @@ -1,37 +0,0 @@ -# Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: BSD-3-Clause - -cmake_minimum_required(VERSION 3.16) -project(customtype LANGUAGES CXX) - -if(NOT DEFINED INSTALL_EXAMPLESDIR) - set(INSTALL_EXAMPLESDIR "examples") -endif() - -set(INSTALL_EXAMPLEDIR "${INSTALL_EXAMPLESDIR}/corelib/tools/customtype") - -find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets) - -qt_standard_project_setup() - -qt_add_executable(customtype - main.cpp - message.cpp message.h -) - -set_target_properties(customtype PROPERTIES - WIN32_EXECUTABLE TRUE - MACOSX_BUNDLE TRUE -) - -target_link_libraries(customtype PRIVATE - Qt6::Core - Qt6::Gui - Qt6::Widgets -) - -install(TARGETS customtype - RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}" - BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}" - LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}" -) diff --git a/examples/corelib/tools/customtype/customtype.pro b/examples/corelib/tools/customtype/customtype.pro deleted file mode 100644 index 0e0fe9b1a5a..00000000000 --- a/examples/corelib/tools/customtype/customtype.pro +++ /dev/null @@ -1,8 +0,0 @@ -HEADERS = message.h -SOURCES = main.cpp \ - message.cpp -QT += widgets - -# install -target.path = $$[QT_INSTALL_EXAMPLES]/corelib/tools/customtype -INSTALLS += target diff --git a/examples/corelib/tools/customtypesending/CMakeLists.txt b/examples/corelib/tools/customtypesending/CMakeLists.txt deleted file mode 100644 index a993d811607..00000000000 --- a/examples/corelib/tools/customtypesending/CMakeLists.txt +++ /dev/null @@ -1,38 +0,0 @@ -# Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: BSD-3-Clause - -cmake_minimum_required(VERSION 3.16) -project(customtypesending LANGUAGES CXX) - -if(NOT DEFINED INSTALL_EXAMPLESDIR) - set(INSTALL_EXAMPLESDIR "examples") -endif() - -set(INSTALL_EXAMPLEDIR "${INSTALL_EXAMPLESDIR}/corelib/tools/customtypesending") - -find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets) - -qt_standard_project_setup() - -qt_add_executable(customtypesending - main.cpp - message.cpp message.h - window.cpp window.h -) - -set_target_properties(customtypesending PROPERTIES - WIN32_EXECUTABLE TRUE - MACOSX_BUNDLE TRUE -) - -target_link_libraries(customtypesending PRIVATE - Qt6::Core - Qt6::Gui - Qt6::Widgets -) - -install(TARGETS customtypesending - RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}" - BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}" - LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}" -) diff --git a/examples/corelib/tools/doc/src/customtype.qdoc b/examples/corelib/tools/doc/src/customtype.qdoc deleted file mode 100644 index 63c30d62081..00000000000 --- a/examples/corelib/tools/doc/src/customtype.qdoc +++ /dev/null @@ -1,111 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - \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. -*/ diff --git a/examples/corelib/tools/tools.pro b/examples/corelib/tools/tools.pro index 6fb4a1214fc..618628d2742 100644 --- a/examples/corelib/tools/tools.pro +++ b/examples/corelib/tools/tools.pro @@ -1,6 +1,4 @@ requires(qtHaveModule(widgets)) TEMPLATE = subdirs -SUBDIRS = contiguouscache \ - customtype \ - customtypesending +SUBDIRS = contiguouscache diff --git a/src/corelib/doc/snippets/customtype/customtypeexample.cpp b/src/corelib/doc/snippets/customtype/customtypeexample.cpp new file mode 100644 index 00000000000..afa2c4b2688 --- /dev/null +++ b/src/corelib/doc/snippets/customtype/customtypeexample.cpp @@ -0,0 +1,90 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#include +#include +#include + +//message.h + +//! [custom type definition] +class Message +{ +public: + Message() = default; + ~Message() = default; + Message(const Message &) = default; + Message &operator=(const Message &) = default; + + Message(const QString &body, const QStringList &headers); + + QStringView body() const; + QStringList headers() const; + +private: + QString m_body; + QStringList m_headers; +}; +//! [custom type definition] + +//! [custom type meta-type declaration] +Q_DECLARE_METATYPE(Message); +//! [custom type meta-type declaration] + +//! [custom type streaming operator declaration] +QDebug operator<<(QDebug dbg, const Message &message); +//! [custom type streaming operator declaration] + +// message.cpp + +//! [custom type streaming operator] +QDebug operator<<(QDebug dbg, const Message &message) +{ + const QList pieces = message.body().split(u"\r\n", Qt::SkipEmptyParts); + if (pieces.isEmpty()) + dbg.nospace() << "Message()"; + else if (pieces.size() == 1) + dbg.nospace() << "Message(" << pieces.first() << ")"; + else + dbg.nospace() << "Message(" << pieces.first() << " ...)"; + return dbg; +} +//! [custom type streaming operator] + +//! [getter functions] +QStringView Message::body() const +{ + return m_body; +} + +QStringList Message::headers() const +{ + return m_headers; +} +//! [getter functions] + +//main.cpp + +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + QStringList headers; + headers << "Subject: Hello World" + << "From: address@example.com"; + QString body = "This is a test.\r\n"; + //! [printing a custom type] + Message message(body, headers); + qDebug() << "Original:" << message; + //! [printing a custom type] + //! [storing a custom value] + QVariant stored; + stored.setValue(message); + //! [storing a custom value] + qDebug() << "Stored:" << stored; + //! [retrieving a custom value] + Message retrieved = qvariant_cast(stored); + qDebug() << "Retrieved:" << retrieved; + retrieved = qvariant_cast(stored); + qDebug() << "Retrieved:" << retrieved; + //! [retrieving a custom value] + return 0; +} diff --git a/src/corelib/doc/src/custom-types.qdoc b/src/corelib/doc/src/custom-types.qdoc index 53885e51363..d9da3d65e53 100644 --- a/src/corelib/doc/src/custom-types.qdoc +++ b/src/corelib/doc/src/custom-types.qdoc @@ -37,7 +37,7 @@ The following \c Message class definition includes these members: - \snippet tools/customtype/message.h custom type definition + \snippet customtype/customtypeexample.cpp custom type definition The class also provides a constructor for normal use and two public member functions that are used to obtain the private data. @@ -53,11 +53,14 @@ to this class, we invoke the Q_DECLARE_METATYPE() macro on the class in the header file where it is defined: - \snippet tools/customtype/message.h custom type meta-type declaration + \snippet customtype/customtypeexample.cpp custom type meta-type declaration This now makes it possible for \c Message values to be stored in QVariant objects - and retrieved later. See the \l{Custom Type Example} for code that demonstrates - this. + and retrieved later: + + \snippet customtype/customtypeexample.cpp storing a custom value + \dots + \snippet customtype/customtypeexample.cpp retrieving a custom value The Q_DECLARE_METATYPE() macro also makes it possible for these values to be used as arguments to signals, but \e{only in direct signal-slot connections}. @@ -107,18 +110,17 @@ It is often quite useful to make a custom type printable for debugging purposes, as in the following code: - \snippet tools/customtype/main.cpp printing a custom type + \snippet customtype/customtypeexample.cpp printing a custom type This is achieved by creating a streaming operator for the type, which is often defined in the header file for that type: - \snippet tools/customtype/message.h custom type streaming operator + \snippet customtype/customtypeexample.cpp custom type streaming operator declaration - The implementation for the \c Message type in the \l{Custom Type Example} - goes to some effort to make the printable representation as readable as - possible: + The implementation for the \c Message type here goes to some effort to make the + printable representation as readable as possible: - \snippet tools/customtype/message.cpp custom type streaming operator + \snippet customtype/customtypeexample.cpp custom type streaming operator The output sent to the debug stream can, of course, be made as simple or as complicated as you like. Note that the value returned by this function is @@ -131,8 +133,8 @@ The Q_DECLARE_METATYPE() macro and qRegisterMetaType() function documentation contain more detailed information about their uses and limitations. - The \l{Custom Type Example}{Custom Type} and \l{Queued Custom Type} examples - show how to implement a custom type with the features outlined in this document. + The \l{Queued Custom Type} example shows how to implement a custom type with + the features outlined in this document. The \l{Debugging Techniques} document provides an overview of the debugging mechanisms discussed above. diff --git a/src/corelib/io/qdebug.cpp b/src/corelib/io/qdebug.cpp index dd8661cccaa..5e3f82dddf2 100644 --- a/src/corelib/io/qdebug.cpp +++ b/src/corelib/io/qdebug.cpp @@ -942,7 +942,7 @@ QDebug &QDebug::resetFormat() QDebugStateSaver is typically used in the implementation of an operator<<() for debugging: - \snippet tools/customtype/message.cpp custom type streaming operator + \snippet customtype/customtypeexample.cpp custom type streaming operator \since 5.1 */ diff --git a/tests/manual/corelib/CMakeLists.txt b/tests/manual/corelib/CMakeLists.txt new file mode 100644 index 00000000000..cd0e6d36562 --- /dev/null +++ b/tests/manual/corelib/CMakeLists.txt @@ -0,0 +1,4 @@ +# Copyright (C) 2023 The Qt Company Ltd. +# SPDX-License-Identifier: BSD-3-Clause + +add_subdirectory(tools) diff --git a/tests/manual/corelib/tools/CMakeLists.txt b/tests/manual/corelib/tools/CMakeLists.txt new file mode 100644 index 00000000000..4300db88594 --- /dev/null +++ b/tests/manual/corelib/tools/CMakeLists.txt @@ -0,0 +1,12 @@ +# Copyright (C) 2023 The Qt Company Ltd. +# SPDX-License-Identifier: BSD-3-Clause + +add_subdirectory(customtype) +add_subdirectory(customtypesending) +# Needs conversion from qmake: +# add_subdirectory(qhash) +# add_subdirectory(qlist) +# add_subdirectory(qmap) +# add_subdirectory(qset) +# add_subdirectory(qvarlengtharray) +# add_subdirectory(qvector) diff --git a/tests/manual/corelib/tools/customtype/CMakeLists.txt b/tests/manual/corelib/tools/customtype/CMakeLists.txt new file mode 100644 index 00000000000..4cb1c024b3e --- /dev/null +++ b/tests/manual/corelib/tools/customtype/CMakeLists.txt @@ -0,0 +1,15 @@ +# Copyright (C) 2022 The Qt Company Ltd. +# SPDX-License-Identifier: BSD-3-Clause + +cmake_minimum_required(VERSION 3.16) + +qt_internal_add_manual_test(customtype + GUI + SOURCES + main.cpp + message.cpp message.h + LIBRARIES + Qt6::Core + Qt6::Gui + Qt6::Widgets +) diff --git a/tests/manual/corelib/tools/customtype/customtype.pro b/tests/manual/corelib/tools/customtype/customtype.pro new file mode 100644 index 00000000000..0a5a90f5415 --- /dev/null +++ b/tests/manual/corelib/tools/customtype/customtype.pro @@ -0,0 +1,7 @@ +HEADERS = message.h +SOURCES = main.cpp \ + message.cpp +QT += widgets +INCLUDEPATH += . +TARGET = customtype + diff --git a/examples/corelib/tools/customtype/main.cpp b/tests/manual/corelib/tools/customtype/main.cpp similarity index 100% rename from examples/corelib/tools/customtype/main.cpp rename to tests/manual/corelib/tools/customtype/main.cpp diff --git a/examples/corelib/tools/customtype/message.cpp b/tests/manual/corelib/tools/customtype/message.cpp similarity index 100% rename from examples/corelib/tools/customtype/message.cpp rename to tests/manual/corelib/tools/customtype/message.cpp diff --git a/examples/corelib/tools/customtype/message.h b/tests/manual/corelib/tools/customtype/message.h similarity index 100% rename from examples/corelib/tools/customtype/message.h rename to tests/manual/corelib/tools/customtype/message.h diff --git a/tests/manual/corelib/tools/customtypesending/CMakeLists.txt b/tests/manual/corelib/tools/customtypesending/CMakeLists.txt new file mode 100644 index 00000000000..c22d5e23c18 --- /dev/null +++ b/tests/manual/corelib/tools/customtypesending/CMakeLists.txt @@ -0,0 +1,16 @@ +# Copyright (C) 2022 The Qt Company Ltd. +# SPDX-License-Identifier: BSD-3-Clause + +cmake_minimum_required(VERSION 3.16) + +qt_internal_add_manual_test(customtypesending + GUI + SOURCES + main.cpp + message.cpp message.h + window.cpp window.h + LIBRARIES + Qt6::Core + Qt6::Gui + Qt6::Widgets +) diff --git a/examples/corelib/tools/customtypesending/customtypesending.pro b/tests/manual/corelib/tools/customtypesending/customtypesending.pro similarity index 57% rename from examples/corelib/tools/customtypesending/customtypesending.pro rename to tests/manual/corelib/tools/customtypesending/customtypesending.pro index da351ce828f..d316787f765 100644 --- a/examples/corelib/tools/customtypesending/customtypesending.pro +++ b/tests/manual/corelib/tools/customtypesending/customtypesending.pro @@ -4,7 +4,6 @@ SOURCES = main.cpp \ message.cpp \ window.cpp QT += widgets +INCLUDEPATH += . +TARGET = customtypesending -# install -target.path = $$[QT_INSTALL_EXAMPLES]/corelib/tools/customtypesending -INSTALLS += target diff --git a/examples/corelib/tools/customtypesending/main.cpp b/tests/manual/corelib/tools/customtypesending/main.cpp similarity index 100% rename from examples/corelib/tools/customtypesending/main.cpp rename to tests/manual/corelib/tools/customtypesending/main.cpp diff --git a/examples/corelib/tools/customtypesending/message.cpp b/tests/manual/corelib/tools/customtypesending/message.cpp similarity index 100% rename from examples/corelib/tools/customtypesending/message.cpp rename to tests/manual/corelib/tools/customtypesending/message.cpp diff --git a/examples/corelib/tools/customtypesending/message.h b/tests/manual/corelib/tools/customtypesending/message.h similarity index 100% rename from examples/corelib/tools/customtypesending/message.h rename to tests/manual/corelib/tools/customtypesending/message.h diff --git a/examples/corelib/tools/customtypesending/window.cpp b/tests/manual/corelib/tools/customtypesending/window.cpp similarity index 100% rename from examples/corelib/tools/customtypesending/window.cpp rename to tests/manual/corelib/tools/customtypesending/window.cpp diff --git a/examples/corelib/tools/customtypesending/window.h b/tests/manual/corelib/tools/customtypesending/window.h similarity index 100% rename from examples/corelib/tools/customtypesending/window.h rename to tests/manual/corelib/tools/customtypesending/window.h