完善文档

czyt1988 · Jan 24, 2024 · be34434 · be34434
1 parent 63b98d3
commit be34434
Show file tree

Hide file tree

Showing 6 changed files with 103 additions and 120 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -14,7 +14,7 @@ project(SARibbon VERSION ${SARIBBON_VERSION} LANGUAGES CXX)
 # option(BUILD_SHARED_LIBS "build the SARibbonBar in shared lib mode" ON)
 option(SARIBBON_BUILD_EXAMPLES "build the examples" ON)
 # frameless能提供windows的窗口特效，如边缘吸附，且对高分屏多屏幕的支持更好,默认开启
-option(SARIBBON_USE_FRAMELESS_LIB "use frameless lib" ON)
+option(SARIBBON_USE_FRAMELESS_LIB "Using the QWindowKit library as a frameless solution" OFF)
 
 # load Qt library, minimum version required is 5.8
 # cn:Qt库加载,最低版本要求为5.8

diff --git a/changlog.md b/changlog.md
@@ -23,9 +23,7 @@
 - `SARibbonMainWindow`支持非ribbon模式
 - 原`SAWindowButtonGroup`改名为`SARibbonSystemButtonGroupBar`，同时支持添加action
 
-【警告】编译过程会在当前目录下生成bin_qtx.x.x_Debug/Release_x64/86这样的文件夹，请确保有写入权限，否则会执行qmake或cmake过程报错
-
-
+【警告】编译过程会在当前目录下生成bin_qtx.x.x_[MSVC/GNU]_x[64/86]这样的文件夹，请确保有写入权限，否则执行qmake过程会报错
 
 由于接口函数有明显调整，因此版本变更为2.0
 

diff --git a/doc/how-to-build-cn.md b/doc/how-to-build-cn.md
@@ -18,7 +18,7 @@ git submodule update --init --recursive
 
 使用Qt Creator和使用visual studio构建和安装基本一样
 
-## 使用Qt Creator构建和安装
+## 使用Qt Creator构建和安装QWindowkit库
 
 使用qt creator编译`QWindowkit`库，直接用qt creator打开`src/SARibbonBar/3rdparty/CMakeLists.txt`文件
 
@@ -42,7 +42,7 @@ build步骤选择install
 
 此时完成`QWindowkit`库的编译和安装
 
-## 使用visual studio构建和安装
+## 使用visual studio构建和安装QWindowkit库
 
 使用visual studio编译`QWindowkit`库，用visual studio打开->CMake，选择`src/SARibbonBar/3rdparty/CMakeLists.txt`文件
 
@@ -62,17 +62,13 @@ build步骤选择install
 
 此时完成`QWindowkit`库的编译和安装
 
-# Cmake构建及使用SARibbon教程
+# 构建SARibbonBar库
 
-最近发现有许多使用visual studio（以下简称vs）咨询可以构建但无法引入的问题，为此，这里专门写此文针对此问题进行说明
+SARibbonBar库提供cmake和qmake两种方式构建，推荐使用cmake
 
-分两种方式，第一种使用cmake，个人推荐使用cmake对工程进行构建，毕竟能用到Ribbon的界面都算大型工程了
+## 基于CMake构建SARibbonBar库
 
-另外一种是直接通过visual studio建立的工程引入SARibbon
-
-# 基于cmake的构建和使用
-
-## vs下基于cmake的构建
+### vs下基于cmake的构建
 
 点击文件->打开->Cmake 选中CMakeLists.txt
 
@@ -94,7 +90,7 @@ build步骤选择install
 
 ![](./pic/build-cmake-install-dir.png)
 
-## qtcreator下基于cmake的构建
+### qtcreator下基于cmake的构建
 
 点击文件->打开文件或项目选中CMakeLists.txt，加载完成后形成如下的构建树
 
@@ -114,26 +110,69 @@ build步骤选择install
 
 使用SARibbon的所有内容都在这个文件夹下
 
-# 基于cmake引入SARibbonBar
+## 基于QMake构建SARibbonBar
+
+qmake构建SARibbonBar只需使用Qt Creator打开SARibbon.pro文件即可
+
+> 注意，如果使用Qt Creator打开SARibbon.pro文件过程报错，那么你的账户没有足够的写权限，因为qmake过程会在当前目录下执行mkdir等命令，没有足够权限，会报qmake错误
+
+# 使用SARibbonBar库
+
+## 基于cmake引入SARibbonBar库
 
-引用SARibbonBar和编译器无关，主要针对自己cmake文件的编写
+首先要通过cmake编译并执行安装，在自己的工程按照如下步骤执行：
 
-1、指定SARibbonBar的安装目录，把安装目录下的`lib/cmake/SARibbonBar`位置设置给`SARibbonBar_DIR`变量
+1. 指定SARibbonBar的安装目录，把安装目录下的`lib/cmake/SARibbonBar`位置设置给`SARibbonBar_DIR`变量
 
 ```cmake
-set(SARibbonBar_DIR "C:\src\Qt\SARibbon\bin_qt5.14.2_Debug_x64\lib\cmake\SARibbonBar")
+set(SARibbonBar_DIR "C:\src\Qt\SARibbon\bin_qt5.14.2_MSVC_x64\lib\cmake\SARibbonBar")
 ```
 
-2、使用find_package找到SARibbonBar的Config文件，这个函数实际上是调用`lib/cmake/SARibbonBar/SARibbonBarConfig.cmake`文件，这里会把需要include的路径、预定义的宏，和需要添加的库给指定好，此时`SARibbonBar_INCLUDE_DIR`就是SARibbonBar的include文件路径
+2. 使用find_package找到SARibbonBar的Config文件，这个函数实际上是调用`lib/cmake/SARibbonBar/SARibbonBarConfig.cmake`文件，这里会把需要include的路径、预定义的宏，和需要添加的库给指定好，此时`SARibbonBar_INCLUDE_DIR`就是SARibbonBar的include文件路径
 
 ```cmake
 find_package(SARibbonBar)
 ```
 
-3、最后调用`target_link_libraries`添加SARibbonBar库到自己的工程中,这里${myapp_target_name}是自己工程的target名字
+3. 最后调用`target_link_libraries`添加SARibbonBar库到自己的工程中,这里${myapp_target_name}是自己工程的target名字
 
 ```cmake
 target_link_libraries(${myapp_target_name} PUBLIC
     SARibbonBar
 )
-```
+```
+
+## 基于qmake引入SARibbonBar库
+
+qmake的编译过程会在SARibbon下生成`bin_qt{Qt version}_{MSVC/GNU}_x{32/64}`文件夹，库文件和dll文件都在此文件夹下，importSARibbonBarLib.pri会自动把这个文件夹下的库引用进来
+
+步骤如下：
+
+1. 先在你的工程中建立一个3rdparty文件夹，再把整个SARibbon文件夹拷贝过去
+
+> SARibbon内部已经有几个pri文件可以很方便的让你把工程引入到自己目录中，`./importSARibbonBarLib.pri`文件就是用于引入SARibbon库的
+
+2. 在自己的Qt工程pro文件中加入如下语句即可
+
+```shell
+include($$PWD/3rdparty/SARibbon/importSARibbonBarLib.pri)
+```
+
+此时你的工程目录结构大致如下：
+
+```
+|-[you-project-dir]
+|  |-you-project.pro
+|  |-[3rdparty]
+|     |-[SARibbon](直接把SARibbon完整复制过来)
+|        |-importSARibbonBarLib.pri
+|        |-SARibbonBar.pri
+|        |-common.pri
+|        |-[bin_qtx.x.x_{MSVC/GNU}_x{32/64}]
+|        |-[src]
+|        |   |-[SARibbonBar]
+```
+
+`importSARibbonBarLib.pri`、`SARibbonBar.pri`、`common.pri`这三个文件是引入工程的关键文件
+
+> Qt6.0版本后已经放弃qmake，建议使用cmake来管理工程
diff --git a/readme-cn.md b/readme-cn.md
@@ -108,8 +108,6 @@ MIT协议，欢迎大家使用并提出意见
 
 SARibbon提供qmake和cmake两种构建方式，同时提供了一个集成的SARibbon.h和SARibbon.cpp文件方便静态的嵌入到单一工程
 
-> qmake和cmake会根据qt版本选择是否加载frameless库，会根据不同的qt版本选择使用c++14还是C++17
-
 > SARibbon支持第三方无边框库[QWindowkit](https://github.com/stdware/qwindowkit)，同时也支持简单的无边框方案，如果你需要操作系统原生的窗口支持，如windows7以后的贴边处理，windows11的最大化按钮悬停的效果，建议开启[QWindowkit](https://github.com/stdware/qwindowkit)库，[QWindowkit](https://github.com/stdware/qwindowkit)库还能较好解决多屏幕移动问题
 
 如果你要依赖[QWindowkit](https://github.com/stdware/qwindowkit)库，需要先编译[QWindowkit](https://github.com/stdware/qwindowkit)库，[QWindowkit](https://github.com/stdware/qwindowkit)库作为SARibbon项目的submodules，如果在`git clone`时没有附带`--recursive`参数，需要执行`submodule update`命令:
@@ -118,13 +116,15 @@ SARibbon提供qmake和cmake两种构建方式，同时提供了一个集成的SA
 git submodule update --init --recursive
 ```
 
+> 用户指定使用[QWindowkit](https://github.com/stdware/qwindowkit)后，要求C++标准最低为C++17否则最低要求为c++14
+
 ## 编译为动态库
 
 具体构建过程，见文档：[SARibbon构建](./doc/how-to-build-cn.md)
 
 ## 直接引入工程（静态）
 
-SARibbon提供了合并好的`SARibbon.h`文件和`SARibbon.cpp`文件，只需要在自己的工程中引入这两个文件，同时把资源文件和第三方库文件引入就可以使用，无需编译为动态库或者静态库，可以参考StaticExample例子（位于`src/example/StaticExample`），静态嵌入将使用到`SARibbon.h`、`SARibbon.cpp`、`SARibbon.pri`、`SARibbonBar/resource.qrc`这4个文件，以及`SARibbonBar/3rdparty`,`SARibbonBar/resource`这两个文件夹：
+SARibbon提供了合并好的`SARibbon.h`文件和`SARibbon.cpp`文件，只需要在自己的工程中引入这两个文件，同时把资源文件和第三方库文件引入就可以使用，无需编译为动态库或者静态库，可以参考StaticExample例子（位于`src/example/StaticExample`），静态嵌入将使用到`SARibbon.h`、`SARibbon.cpp`、`SARibbon.pri`、`SARibbonBar/resource.qrc`这4个文件，以及`SARibbonBar/resource`这个文件夹：
 
 你的工程目录将如下所示：
 
@@ -138,14 +138,6 @@ SARibbon提供了合并好的`SARibbon.h`文件和`SARibbon.cpp`文件，只需
 |     |-resource.qrc
 |     |-resource(直接把SARibbonBar下的resource完整复制过来)
 |        |-resource files
-|     |-3rdparty(直接把SARibbonBar下的3rdparty完整复制过来)
-|        |-framelesshelper
-|           |-src
-|           |  |-src files
-|           |-include
-|           |  |-header files
-|           |-qmake
-|           |  |-pri files
 ```
 
 使用qmake编译，有如下步骤：
@@ -156,7 +148,7 @@ SARibbon提供了合并好的`SARibbon.h`文件和`SARibbon.cpp`文件，只需
 - 4. 把源码`src/SARibbonBar`下的`resource`文件夹和`3rdparty`文件夹拷贝到自己工程目录下的`SARibbonBar`文件夹中
 - 5. 在自己工程的pro文件中引入`SARibbon.pri`文件，如：`include($$PWD/SARibbon.pri)`
 
-使用cmake的话参考StaticExample例子的cmake编写方式
+使用cmake的话参考StaticExample（位于`src/example/StaticExample`）例子的cmake编写方式
 
 
 # 使用方法
@@ -177,7 +169,7 @@ SARibbon提供了合并好的`SARibbon.h`文件和`SARibbon.cpp`文件，只需
 include($$PWD/3rdparty/SARibbon/importSARibbonBarLib.pri)
 ```
 
-qmake的编译过程会在SARibbon下生成bin_qtx.x_xx文件夹，库文件和dll文件都在此文件夹下，importSARibbonBarLib.pri会自动把这个文件夹下的库引用进来
+qmake的编译过程会在SARibbon下生成`bin_qt{Qt version}_{MSVC/GNU}_x{32/64}`文件夹，库文件和dll文件都在此文件夹下，importSARibbonBarLib.pri会自动把这个文件夹下的库引用进来
 
 此时你的工程目录结构大致如下：
 
@@ -189,35 +181,17 @@ qmake的编译过程会在SARibbon下生成bin_qtx.x_xx文件夹，库文件和d
 |        |-importSARibbonBarLib.pri
 |        |-SARibbonBar.pri
 |        |-common.pri
-|        |-[bin_qtx.x.x_(release|debug)_(64|86)]
+|        |-[bin_qtx.x.x_{MSVC/GNU}_x{32/64}]
 |        |-[src]
 |        |   |-[SARibbonBar]
 ```
 
-
 ### cmake
 
 cmake在执行install后，会把必要的文件拷贝到安装目录下，cmake文件编写时可参考`src/example/MainWindowExample/CMakeLists.txt`
 
 具体见文档：[SARibbon构建](./doc/how-to-build-cn.md)
 
-### visual studio添加
-
-如果你的qt版本大于等于5.14，会使用第三方库frameless，此时使用vs的界面操作添加SARibbon需要注意以下几点：
-
-1、include路径有三个
-```
-src/SARibbonBar
-```
-
-2、预定义宏有一个：
-
-注意，预定义宏一定要和编译时配置一致，否则会导致拖动异常
-
-```
-SARIBBON_USE_3RDPARTY_FRAMELESSHELPER=1
-```
-
 ## 快速开始
 
 Ribbon是把菜单栏和工具栏合并了，并通过一个tab控件进行展示，Ribbon是无法简单的使用Tab+Toolbar替代的，涉及到很多细节问题，`SARibbon`在设计时参考了MFC Ribbon接口的命名风格，标签页称之为`Category`(种类)，每个`Category`下面有多个`pannel`（面板），面板下面管理着toolbutton，`pannel`有点类似传统的`Toolbar`，其层次结构如下图所示，这些命名参考了MFC的ribbon界面类
@@ -712,5 +686,4 @@ int main(int argc, char* argv[])
 
 # 其他
 
-
 > 感谢[FastCAE](http://www.fastcae.com/product.html)项目使用了本控件，并找到了许多bug和建议，FastCAE国产CAE软件集成开发平台，免费开源，是面向求解器开发者提供CAE软件界面与通用功能模块快速研发集成框架，[其开源仓库（github）:https://github.com/DISOGitHub/FastCAE](https://github.com/DISOGitHub/FastCAE)，[gitee:https://gitee.com/DISOGitee/FastCAE](https://gitee.com/DISOGitee/FastCAE)，[官网见:http://www.fastcae.com/product.html](http://www.fastcae.com/product.html)