diff --git a/README-zh.md b/README-zh.md index 454baad..2299f86 100644 --- a/README-zh.md +++ b/README-zh.md @@ -247,6 +247,8 @@ CusConfig是核心库的全局配置,主要包括字体、颜色等,所有组件 ## 使用核心库TaoQuick +详细的使用方法，可以阅读 [入门指南](入门指南.md) + ### qmake用法 使用核心库，只需要在项目中导入'.pri'文件，并将qml路径加入到QmlEngine即可。 @@ -307,6 +309,9 @@ debug模式都以本地文件的方式使用，release模型则以qrc资源文 ### cmake用法 +详细的使用方法，可以阅读 [入门指南](入门指南.md) + + TaoQuick 0.5.0以后的版本，增加了cmake支持。 原理和qmake一样，只不过换成了cmake的语法规则。 diff --git a/doc/cmake1.png b/doc/cmake1.png new file mode 100644 index 0000000..181adf6 Binary files /dev/null and b/doc/cmake1.png differ diff --git a/doc/cmake2.png b/doc/cmake2.png new file mode 100644 index 0000000..920315a Binary files /dev/null and b/doc/cmake2.png differ diff --git a/doc/cmake3.png b/doc/cmake3.png new file mode 100644 index 0000000..3a57c69 Binary files /dev/null and b/doc/cmake3.png differ diff --git a/doc/cmake4.png b/doc/cmake4.png new file mode 100644 index 0000000..c773cc0 Binary files /dev/null and b/doc/cmake4.png differ diff --git a/doc/cmake5.png b/doc/cmake5.png new file mode 100644 index 0000000..51a0172 Binary files /dev/null and b/doc/cmake5.png differ diff --git a/doc/cmake6.png b/doc/cmake6.png new file mode 100644 index 0000000..5c6760d Binary files /dev/null and b/doc/cmake6.png differ diff --git a/doc/start1.png b/doc/start1.png new file mode 100644 index 0000000..60a3fbb Binary files /dev/null and b/doc/start1.png differ diff --git a/doc/start2.png b/doc/start2.png new file mode 100644 index 0000000..8fc00df Binary files /dev/null and b/doc/start2.png differ diff --git a/doc/start3.png b/doc/start3.png new file mode 100644 index 0000000..6d46e71 Binary files /dev/null and b/doc/start3.png differ diff --git a/doc/start4.png b/doc/start4.png new file mode 100644 index 0000000..f9a160c Binary files /dev/null and b/doc/start4.png differ diff --git a/doc/start5.png b/doc/start5.png new file mode 100644 index 0000000..b8f057f Binary files /dev/null and b/doc/start5.png differ diff --git a/examples/HelloTaoQuick1/HelloTaoQuick1.pro b/examples/HelloTaoQuick1/HelloTaoQuick1.pro new file mode 100644 index 0000000..f7cfddf --- /dev/null +++ b/examples/HelloTaoQuick1/HelloTaoQuick1.pro @@ -0,0 +1,9 @@ +TEMPLATE = app + +QT += gui quick qml quickcontrols2 + +SOURCES += main.cpp + +RESOURCES += Res.qrc + +include(../../src/TaoQuick/TaoQuick.pri) \ No newline at end of file diff --git a/examples/HelloTaoQuick1/Res.qrc b/examples/HelloTaoQuick1/Res.qrc new file mode 100644 index 0000000..8ed9b51 --- /dev/null +++ b/examples/HelloTaoQuick1/Res.qrc @@ -0,0 +1,5 @@ + + + main.qml + + \ No newline at end of file diff --git a/examples/HelloTaoQuick1/main.cpp b/examples/HelloTaoQuick1/main.cpp new file mode 100644 index 0000000..af3f831 --- /dev/null +++ b/examples/HelloTaoQuick1/main.cpp @@ -0,0 +1,16 @@ +#include +#include +#include +#include +int main(int argc, char **argv) +{ + QGuiApplication app(argc, argv); + QQuickView view; + view.engine()->addImportPath(TaoQuickImportPath); + view.rootContext()->setContextProperty("taoQuickImagePath", TaoQuickImagePath); + + view.setSource(QUrl("qrc:/main.qml")); + view.show(); + + return app.exec(); +} \ No newline at end of file diff --git a/examples/HelloTaoQuick1/main.qml b/examples/HelloTaoQuick1/main.qml new file mode 100644 index 0000000..c223a75 --- /dev/null +++ b/examples/HelloTaoQuick1/main.qml @@ -0,0 +1,21 @@ +import QtQml 2.0 +import QtQuick 2.9 + +import QtQuick.Controls 2.0 + +import TaoQuick 1.0 + +Rectangle { + color: "lightblue" + width: 640 + height: 480 + CusButton_Blue { + width: 120 + height: 36 + anchors.centerIn: parent + text: "Hello" + onClicked: { + console.log("hello TaoQuick") + } + } +} diff --git a/examples/HelloTaoQuick2/CMakeLists.txt b/examples/HelloTaoQuick2/CMakeLists.txt new file mode 100644 index 0000000..12ee2e7 --- /dev/null +++ b/examples/HelloTaoQuick2/CMakeLists.txt @@ -0,0 +1,35 @@ +cmake_minimum_required(VERSION 3.14) + +project(HelloTaoQuick2 LANGUAGES CXX) + +set(CMAKE_INCLUDE_CURRENT_DIR ON) + +set(CMAKE_AUTOUIC ON) +set(CMAKE_AUTOMOC ON) +set(CMAKE_AUTORCC ON) + +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED ON) + +include(taoQuick.cmake) + +find_package(QT NAMES Qt6 Qt5 COMPONENTS Core Quick REQUIRED) +find_package(Qt${QT_VERSION_MAJOR} COMPONENTS Core Quick REQUIRED) + +if(ANDROID) + add_library(HelloTaoQuick2 SHARED + main.cpp + qml.qrc + ) +else() + add_executable(HelloTaoQuick2 + main.cpp + qml.qrc + ${TaoQuickRes} + ) +endif() + +target_compile_definitions(HelloTaoQuick2 + PRIVATE $<$,$>:QT_QML_DEBUG>) +target_link_libraries(HelloTaoQuick2 + PRIVATE Qt${QT_VERSION_MAJOR}::Core Qt${QT_VERSION_MAJOR}::Quick) diff --git a/examples/HelloTaoQuick2/main.cpp b/examples/HelloTaoQuick2/main.cpp new file mode 100644 index 0000000..b79b20c --- /dev/null +++ b/examples/HelloTaoQuick2/main.cpp @@ -0,0 +1,22 @@ +#include +#include +#include +int main(int argc, char *argv[]) +{ + QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); + + QGuiApplication app(argc, argv); + + QQmlApplicationEngine engine; + engine.addImportPath(TaoQuickImportPath); + engine.rootContext()->setContextProperty("taoQuickImagePath", TaoQuickImagePath); + const QUrl url(QStringLiteral("qrc:/main.qml")); + QObject::connect(&engine, &QQmlApplicationEngine::objectCreated, + &app, [url](QObject *obj, const QUrl &objUrl) { + if (!obj && url == objUrl) + QCoreApplication::exit(-1); + }, Qt::QueuedConnection); + engine.load(url); + + return app.exec(); +} diff --git a/examples/HelloTaoQuick2/main.qml b/examples/HelloTaoQuick2/main.qml new file mode 100644 index 0000000..60fe69e --- /dev/null +++ b/examples/HelloTaoQuick2/main.qml @@ -0,0 +1,19 @@ +import QtQuick 2.12 +import QtQuick.Window 2.12 +import QtQuick 2.9 +import TaoQuick 1.0 +Window { + width: 640 + height: 480 + visible: true + title: qsTr("Hello World") + CusButton_Blue { + width: 120 + height: 36 + anchors.centerIn: parent + text: "Hello" + onClicked: { + console.log("hello TaoQuick") + } + } +} diff --git a/examples/HelloTaoQuick2/qml.qrc b/examples/HelloTaoQuick2/qml.qrc new file mode 100644 index 0000000..5f6483a --- /dev/null +++ b/examples/HelloTaoQuick2/qml.qrc @@ -0,0 +1,5 @@ + + + main.qml + + diff --git a/examples/HelloTaoQuick2/taoQuick.cmake b/examples/HelloTaoQuick2/taoQuick.cmake new file mode 100644 index 0000000..14e1948 --- /dev/null +++ b/examples/HelloTaoQuick2/taoQuick.cmake @@ -0,0 +1,19 @@ +set(TaoQuickPath ${CMAKE_SOURCE_DIR}/../../src/TaoQuick/imports) + +if (CMAKE_BUILD_TYPE MATCHES "Release") + set(TaoQuickRes ${TaoQuickPath}/TaoQuick/TaoQuick.qrc CACHE STRING "tao quick res path") + set(TaoQuickImportPath "qrc:///" CACHE STRING "tao quick import path") + set(TaoQuickImagePath "qrc:/TaoQuick/Images/" CACHE STRING "tao quick image path") + +else() + set(TaoQuickImportPath "file:///${TaoQuickPath}" CACHE STRING "tao quick import path") + set(TaoQuickImagePath "file:///${TaoQuickPath}/TaoQuick/Images/" CACHE STRING "tao quick image path") +endif() +add_compile_definitions(TaoQuickImportPath="${TaoQuickImportPath}") +add_compile_definitions(TaoQuickImagePath="${TaoQuickImagePath}") + +add_compile_definitions(QML_IMPORT_PATH="${TaoQuickPath}") +add_compile_definitions(QML2_IMPORT_PATH="${TaoQuickPath}") +add_compile_definitions(QML_DESIGNER_IMPORT_PATH="${TaoQuickPath}") + + diff --git a/入门指南.md b/入门指南.md new file mode 100644 index 0000000..3f0e99d --- /dev/null +++ b/入门指南.md @@ -0,0 +1,543 @@ +# 入门指南 + +## qmake 使用TaoQuick + +### 1. 创建Qml工程 + + +使用QtCreator创建一个简易的Qml工程，或者使用已有的工程。 + +这里示例创建一个HelloTaoQuick1 工程，内容如下： + +![](doc/start1.png) + +pro文件包含基本的Qml工程配置 + +```pro +TEMPLATE = app + +QT += gui quick qml quickcontrols2 + +SOURCES += main.cpp + +RESOURCES += Res.qrc +``` + +qrc资源文件中, 仅添加main.qml + +```xml + + + main.qml + + +``` + +### 2. 拷贝TaoQuick核心库 + +将TaoQuick核心库文件夹拷贝过来，路径是TaoQuick项目的 src/TaoQuick + +(pro文件不支持绝对路径，所以拷贝一下，使用相对路径) + +![](doc/start2.png) + +如图所示，HelloTaoQuick1 项目文件夹下，多了一个TaoQuick文件夹，内含 TaoQuick.pri文件和imports文件夹。 + +### 3. 导入核心库 + +在项目的pro文件中，增加一行include指令，包含相对工程路径下的TaoQuick.pri文件即可 + +(pro文件不支持绝对路径，使用相对路径) + +```pro +TEMPLATE = app + +QT += gui quick qml quickcontrols2 + +SOURCES += main.cpp + +RESOURCES += Res.qrc + +include(TaoQuick/TaoQuick.pri) +``` + +此pri文件提供了两个宏定义: + +TaoQuickImportPath 指向TaoQuick核心库的qmldir文件所在路径， + +需要将此路径添加到Qml引擎导入路径中(添加方法在下一步)，Qml才能识别TaoQuick库； + +TaoQuickImagePath 指向TaoQuick核心库的图片资源路径。 + +### 4. 增加导入路径 + +#### 4.1 两种不同Qml工程的说明 +对于一般的Qml工程，最简单的main.cpp内容，可以有两种使用方式， + +使用QQuickView： + +```C++ +#include +#include +int main(int argc, char **argv) +{ + QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); + + QGuiApplication app(argc, argv); + QQuickView view; + view.setSource(QUrl("qrc:/main.qml")); + view.show(); + + return app.exec(); +} +``` + +或者使用QQmlApplicationEngine: + +```C++ +#include +#include + +int main(int argc, char *argv[]) +{ + QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); + + QGuiApplication app(argc, argv); + + QQmlApplicationEngine engine; + const QUrl url(QStringLiteral("qrc:/main.qml")); + QObject::connect(&engine, &QQmlApplicationEngine::objectCreated, + &app, [url](QObject *obj, const QUrl &objUrl) { + if (!obj && url == objUrl) + QCoreApplication::exit(-1); + }, Qt::QueuedConnection); + engine.load(url); + + return app.exec(); +} + +``` +两种用法本质是一样的，细微区别是：QQuickView本身就是一个主窗口，main.qml顶层元素不能再是Window或者Window的子类；QQmlEngine本身不包含主窗口，main.qml顶层元素必须是Window或者Window的子类。 + +#### 4.2 设置路径 + +我们需要在QmlEngine加载source之前，增加importPath，并把imagePath设置为上下文。 + +如果主窗口是由QQuickView加载的，则： + +```C++ + view.engine()->addImportPath(TaoQuickImportPath); + view.rootContext()->setContextProperty("taoQuickImagePath", TaoQuickImagePath); +``` + +如果主窗口是由QQmlEngine加载的，则: + +```C++ + engine.addImportPath(TaoQuickImportPath); + engine.rootContext()->setContextProperty("taoQuickImagePath", TaoQuickImagePath); +``` + +完整的代码如下: + +QQuickView版本 +```C++ +#include +#include +#include +#include +int main(int argc, char **argv) +{ + QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); + + QGuiApplication app(argc, argv); + QQuickView view; + + view.engine()->addImportPath(TaoQuickImportPath); + view.rootContext()->setContextProperty("taoQuickImagePath", TaoQuickImagePath); + //setSource 之前，要设置好路径 + view.setSource(QUrl("qrc:/main.qml")); + view.show(); + + return app.exec(); +} +``` +QQmlApplicationEngine版本: + +```C++ +#include +#include +#include +int main(int argc, char *argv[]) +{ + QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); + + QGuiApplication app(argc, argv); + + QQmlApplicationEngine engine; + engine.addImportPath(TaoQuickImportPath); + engine.rootContext()->setContextProperty("taoQuickImagePath", TaoQuickImagePath); + + const QUrl url(QStringLiteral("qrc:/main.qml")); + QObject::connect(&engine, &QQmlApplicationEngine::objectCreated, + &app, [url](QObject *obj, const QUrl &objUrl) { + if (!obj && url == objUrl) + QCoreApplication::exit(-1); + }, Qt::QueuedConnection); + + //load 之前，设置好路径 + engine.load(url); + + return app.exec(); +} +``` +### 5. 使用TaoQuick组件 + +一个简单的main.qml,内容如下： + +QQuickView版本 +```qml +import QtQml 2.0 +import QtQuick 2.9 + + +Rectangle { + color: "lightblue" + width: 640 + height: 480 +} + +``` +Engine版本 +```qml +import QtQuick 2.12 +import QtQuick.Window 2.12 + +Window { + width: 640 + height: 480 + visible: true + title: qsTr("Hello World") +} + +``` + +接下来增加一行import,导入TaoQuick + +```qml +import TaoQuick 1.0 +import QtQml 2.0 +import QtQuick 2.9 + +Rectangle { + color: "lightblue" + width: 640 + height: 480 +} + +``` +导入过后，按一下Ctrl + S，保存一下。 + +只要路径正确，QtCreator就可以识别到TaoQuick库，可以直接使用TaoQuick库中的组件。 + +这里示例，使用蓝色按钮组件: +```qml +... + CusButton_Blue { + width: 120 + height: 36 + anchors.centerIn: parent + text: "Hello" + onClicked: { + console.log("hello TaoQuick") + } + } +... +``` +TaoQuick库已经做好了QtCreator的语法高亮和Qml代码跳转 + +![](doc/start3.png) + +当然也可以切换到Design模式，以拖拽、属性编辑的方式，创建、编辑组件 + +![](doc/start4.png) + +### 6. 运行效果 + + 最后，运行起来看看效果吧 + +![](doc/start5.png) + +## cmake 使用TaoQuick + +### 1.创建工程 + +使用QtCreator创建一个简易的Qml工程，或者使用已有的工程。 + +这里示例创建一个HelloTaoQuick2 工程，内容如下： + +![](doc/cmake1.png) + +其中工程文件，CMakeLists.txt内容如下： + +```cmake +cmake_minimum_required(VERSION 3.14) + +project(HelloTaoQuick2 LANGUAGES CXX) + +set(CMAKE_INCLUDE_CURRENT_DIR ON) + +set(CMAKE_AUTOUIC ON) +set(CMAKE_AUTOMOC ON) +set(CMAKE_AUTORCC ON) + +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED ON) + +find_package(QT NAMES Qt6 Qt5 COMPONENTS Core Quick REQUIRED) +find_package(Qt${QT_VERSION_MAJOR} COMPONENTS Core Quick REQUIRED) + +if(ANDROID) + add_library(HelloTaoQuick2 SHARED + main.cpp + qml.qrc + ) +else() + add_executable(HelloTaoQuick2 + main.cpp + qml.qrc + ) +endif() + +target_compile_definitions(HelloTaoQuick2 + PRIVATE $<$,$>:QT_QML_DEBUG>) +target_link_libraries(HelloTaoQuick2 + PRIVATE Qt${QT_VERSION_MAJOR}::Core Qt${QT_VERSION_MAJOR}::Quick) + +``` + +### 2. 拷贝TaoQuick核心库 + +将TaoQuick核心库文件夹拷贝过来，路径是TaoQuick项目的 src/TaoQuick + +![](doc/cmake2.png) + +如图所示，HelloTaoQuick2 项目文件夹下，多了一个TaoQuick文件夹，内含 TaoQuick.pri文件和imports文件夹。 + +### 3. 导入核心库 + +将TaoQuick项目路径中cmake/taoQuick.cmake文件拷贝到HelloTaoQuick2项目路径下 + +![](doc/cmake3.png) + +将taoQuick.cmake文件中第一行，路径修改为当前路径下的TaoQuick/imports文件夹 + +![](doc/cmake4.png) + +在项目的CMakeLists.txt文件中，导入taoQuick.cmake文件 + +![](doc/cmake5.png) + + +在项目的add_executable指令中，增加一项TaoQuickRes + +![](doc/cmake6.png) + + +说明一下吧，taoQuick.cmake文件提供了两个宏定义: + +TaoQuickImportPath 指向TaoQuick核心库的qmldir文件所在路径， + +需要将此路径添加到Qml引擎导入路径中(添加方法在下一步)，Qml才能识别TaoQuick库； + +TaoQuickImagePath 指向TaoQuick核心库的图片资源路径。 + +TaoQuickRes 只在Release模式时，指向TaoQuick的资源文件所在路径。 + +### 4. 增加导入路径 + +#### 4.1 两种不同Qml工程的说明 +对于一般的Qml工程，最简单的main.cpp内容，可以有两种使用方式， + +使用QQuickView： + +```C++ +#include +#include +int main(int argc, char **argv) +{ + QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); + + QGuiApplication app(argc, argv); + QQuickView view; + view.setSource(QUrl("qrc:/main.qml")); + view.show(); + + return app.exec(); +} +``` + +或者使用QQmlApplicationEngine: + +```C++ +#include +#include + +int main(int argc, char *argv[]) +{ + QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); + + QGuiApplication app(argc, argv); + + QQmlApplicationEngine engine; + const QUrl url(QStringLiteral("qrc:/main.qml")); + QObject::connect(&engine, &QQmlApplicationEngine::objectCreated, + &app, [url](QObject *obj, const QUrl &objUrl) { + if (!obj && url == objUrl) + QCoreApplication::exit(-1); + }, Qt::QueuedConnection); + engine.load(url); + + return app.exec(); +} + +``` +两种用法本质是一样的，细微区别是：QQuickView本身就是一个主窗口，main.qml顶层元素不能再是Window或者Window的子类；QQmlEngine本身不包含主窗口，main.qml顶层元素必须是Window或者Window的子类。 + +#### 4.2 设置路径 + +我们需要在QmlEngine加载source之前，增加importPath，并把imagePath设置为上下文。 + +如果主窗口是由QQuickView加载的，则： + +```C++ + view.engine()->addImportPath(TaoQuickImportPath); + view.rootContext()->setContextProperty("taoQuickImagePath", TaoQuickImagePath); +``` + +如果主窗口是由QQmlEngine加载的，则: + +```C++ + engine.addImportPath(TaoQuickImportPath); + engine.rootContext()->setContextProperty("taoQuickImagePath", TaoQuickImagePath); +``` + +完整的代码如下: + +QQuickView版本 +```C++ +#include +#include +#include +#include +int main(int argc, char **argv) +{ + QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); + + QGuiApplication app(argc, argv); + QQuickView view; + + view.engine()->addImportPath(TaoQuickImportPath); + view.rootContext()->setContextProperty("taoQuickImagePath", TaoQuickImagePath); + //setSource 之前，要设置好路径 + view.setSource(QUrl("qrc:/main.qml")); + view.show(); + + return app.exec(); +} +``` +QQmlApplicationEngine版本: + +```C++ +#include +#include +#include +int main(int argc, char *argv[]) +{ + QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); + + QGuiApplication app(argc, argv); + + QQmlApplicationEngine engine; + engine.addImportPath(TaoQuickImportPath); + engine.rootContext()->setContextProperty("taoQuickImagePath", TaoQuickImagePath); + + const QUrl url(QStringLiteral("qrc:/main.qml")); + QObject::connect(&engine, &QQmlApplicationEngine::objectCreated, + &app, [url](QObject *obj, const QUrl &objUrl) { + if (!obj && url == objUrl) + QCoreApplication::exit(-1); + }, Qt::QueuedConnection); + + //load 之前，设置好路径 + engine.load(url); + + return app.exec(); +} +``` +### 5. 使用TaoQuick组件 + +一个简单的main.qml,内容如下： + +QQuickView版本 +```qml +import QtQml 2.0 +import QtQuick 2.9 + + +Rectangle { + color: "lightblue" + width: 640 + height: 480 +} + +``` +Engine版本 +```qml +import QtQuick 2.12 +import QtQuick.Window 2.12 + +Window { + width: 640 + height: 480 + visible: true + title: qsTr("Hello World") +} + +``` + +接下来增加一行import,导入TaoQuick + +```qml +import TaoQuick 1.0 +import QtQml 2.0 +import QtQuick 2.9 + +Rectangle { + color: "lightblue" + width: 640 + height: 480 +} + +``` +导入过后，就可以直接使用TaoQuick库中的组件。 + +这里示例，使用蓝色按钮组件: +```qml +... + CusButton_Blue { + width: 120 + height: 36 + anchors.centerIn: parent + text: "Hello" + onClicked: { + console.log("hello TaoQuick") + } + } +... +``` + +### 6. 运行效果 + + 最后，运行起来看看效果吧 + +![](doc/start5.png) \ No newline at end of file