/*!
@~chinese
@file dtitlebar.h
@ingroup window
@class Dtk::Widget::DTitlebar
@brief Dtitlebar是Dtk程序通用的标题栏组件，用于实现标题栏的高度定制化
@details

## DTitlebar 概述
Dtitlebar是Dtk程序通用的标题栏组件，用于实现标题栏的高度定制化。

当我们新建一个DMainWindow窗口，窗口则会自带一个 DTitlebar ，其包含默认的菜单，包括 主题切换、关于、退出等功能，如下图：

![dtitlebar_example1](/docs/images/dtitlebar_example1.png)

有时候我们开发一个应用，具有很多自己的功能，这些功能需要添加到标题栏中分门别类供用户选择，这是就需要自定义自己的DTitlebar。
下面通过一个简单的例子来创建自己的titlebar，添加自己的菜单

项目目录结构在同一目录下

## CMakeLists.txt

```cmake

cmake_minimum_required(VERSION 3.1.0) # 指定cmake最低版本

project(example1 VERSION 1.0.0 LANGUAGES CXX) # 指定项目名称, 版本, 语言 cxx就是c++

set(CMAKE_CXX_STANDARD 11) # 指定c++标准
set(CMAKE_CXX_STANDARD_REQUIRED ON) # 指定c++标准要求,至少为11以上
set(target example1) # 指定目标名称

set(CMAKE_AUTOMOC ON) # support qt moc # 支持qt moc
set(CMAKE_AUTORCC ON) # support qt resource file # 支持qt资源文件
set(CMAKE_AUTOUIC ON) # support qt ui file # 支持qt ui文件(非必须)

set(CMAKE_EXPORT_COMPILE_COMMANDS ON) # support clangd 支持 clangd

if (CMAKE_VERSION VERSION_LESS "3.7.0") # 如果cmake版本小于3.7.0
    set(CMAKE_INCLUDE_CURRENT_DIR ON) # 设置包含当前目录
endif()

find_package(Qt5 COMPONENTS Widgets REQUIRED) # 寻找Qt5组件Widgets
find_package(Qt5 COMPONENTS Gui  REQUIRED) # 寻找Qt5组件Gui
find_package(Dtk COMPONENTS Widget REQUIRED) # 寻找Dtk组件Widget
find_package(Dtk COMPONENTS Core REQUIRED) # 寻找Dtk组件Core
find_package(Dtk COMPONENTS Gui) # 寻找Dtk组件Gui

add_executable(example1     # 添加可执行文件
        main.cpp
)

target_link_libraries(example1 PRIVATE
    Qt5::Widgets
    Qt5::Gui
    dtkgui
    dtkcore
    dtkwidget
) # 链接库

```

## main.cpp

```cpp

#include <DApplication>
#include <DTitlebar>
#include <DMainWindow>
#include <DMenu>
#include <DStyle>
DWIDGET_USE_NAMESPACE //使用DTK widget命名空间


int main(int argc, char *argv[]){
    DApplication app(argc, argv);
    DMainWindow win;
    win.resize(400,250);

    DTitlebar *bar = win.titlebar(); //窗口会自带一个titlebar，直接调用
    DMenu *menu =  bar->menu()->addMenu("文件"); //新建一个文件菜单，并用一个 menu 指针来接收这个菜单并管理
    bar->menu()->addSeparator(); //添加一个分隔符
    menu->addAction("新建");  //menu菜单下添加可选项 “新建”
    menu->addAction("打开");
    menu->addAction("关闭");
    menu->setIcon(menu->style()->standardIcon(DStyle::SP_DirIcon)); //给文件菜单添加一个自带图标

    bar->setQuitMenuDisabled(true);  //设置退出菜单为不可用
    bar->setSwitchThemeMenuVisible(false); //设置主题更换菜单为不可见

    win.show();
    return app.exec();
}

```

以上代码运行效果如下图所示：

![dtitlebar_example2](/docs/images/dtitlebar_example2.png)

从代码中我们可以看出，对不需要的功能项进行了 setQuitMenuDisabled 和 setSwitchThemeMenuVisible 操作，对比图dtitlebar_example1和dtitlebar_example2
我们发现图dtitlebar_example2中主题切换菜单不见了，而退出选项还有，只是不能点击，它们适用于不同的场景，可以根据具体场景进行选择

有些情况下，例如安装重要组件时，中途退出可能导致很多麻烦，为了放置用户误操作，我们可能连关闭按钮都不希望用户点击，这时可以对窗口进行设置，使用如下代码：

```cpp

win.setWindowFlags(Qt::WindowMinimizeButtonHint | Qt::WindowMaximizeButtonHint);

```

以上代码是设置窗口titlebar上哪些按钮会显示，添加进去的会显示，不添加则不显示。上述代码添加了最小化最大化窗口按钮，没有添加窗口关闭按钮，所以窗口关闭按钮不显示，效果如下：

![dtitlebar_example3](/docs/images/dtitlebar_example3.png)

对菜单中的选项添加对应的连接和代码实现就能实现不同的功能响应了。

@fn Dtk::Widget::DTitlebar::DTitlebar(QWidget *parent)
@brief 构造函数，创建一个DTitlebar对象，包含默认的窗口按钮.
@param[in] parent 父控件指针

@fn QMenu Dtk::Widget::DTitlebar::menu()
@brief 获取和标题栏关联的应用查询菜单
@return 如该标题栏没有设置菜单，这里会返回空，但是如该使用 Dtk::Widget::DApplication ,
那么这里一般会自动创建一个程序菜单

@fn void Dtk::Widget::DTitlebar::setMenu(QMenu *menu)
@brief 设置自定义的程序菜单
@param[in] menu 需要被设置的菜单

@fn QWidget *Dtk::Widget::DTitlebar::customWidget() const
@brief 标题栏绑定的自定义控件,可以通过自定义控件来在标题栏上显示复杂的组合控件
@return 自定义控件
@param[in] Dtk::Widget::DTitlebar::setCustomWidget()

@fn void Dtk::Widget::DTitlebar::showMenu()
@brief 弹出应用程序菜单，设置标题栏上的自定义控件.
@param[in] w 需要显示的控件。
@param[in] fixCenterPos 是否需要自动修正控件位置，用于保持控件居中显示。

@fn void Dtk::Widget::DTitlebar::setFixedHeight(int h)
@brief 设置标题栏的高度，默认高度为 50。
@param[in] h 需要设置的高度

@fn void Dtk::Widget::DTitlebar::setBackgroundTransparent(bool transparent)
@brief 设置标题栏背景是否透明，当为透明时标题栏直接叠加在下层控件上.
@param[in] transparent 是否透明

@fn void Dtk::Widget::DTitlebar::setSeparatorVisible(bool visible)
@brief 设置菜单下面的分隔线是否可见，默认是可见的
@param[in] visible 是否可见

@fn void Dtk::Widget::DTitlebar::setTitle(const QString &title)
@brief 设置标题栏文本。
@param[in] title 待设置内容

@fn void Dtk::Widget::DTitlebar::setIcon(const QIcon &icon)
@brief 设置标题栏图标
@param[in] icon 待设置的图标

@fn int Dtk::Widget::DTitlebar::buttonAreaWidth() const
@brief 按钮区域大小，用于手动定位自定义控件时使用

@fn bool Dtk::Widget::DTitlebar::separatorVisible() const
@brief 分隔线是否可见

@fn bool Dtk::Widget::DTitlebar::autoHideOnFullscreen() const
@brief 全屏模式下标题栏是否自动隐藏

@fn void Dtk::Widget::DTitlebar::setAutoHideOnFullscreen(bool autohide)
@brief 设置全屏模式下是否需要自动隐藏标题栏
@param[in] autohide 是否自动隐藏

@fn void Dtk::Widget::DTitlebar::setEmbedMode(bool visible)
@brief 设置为嵌入模式，而不是替换系统标题栏，用于不支持dxcb的平台
@param[in] visible 为 true 时，替换系统标题栏，否则隐藏系统标题栏

@fn bool Dtk::Widget::DTitlebar::menuIsVisible() const
@brief 菜单按钮的可视化
@return true 菜单可见 false菜单不可见

@fn void Dtk::Widget::DTitlebar::setMenuVisible(bool visible)
@brief 设置菜单是否可见
@param[in] visible true 菜单可见 false菜单不可见

@fn void Dtk::Widget::DTitlebar::setMenuDisabled(bool disabled)
@brief 菜单是否被禁用
@return true 菜单被禁用 false 菜单没有被禁用

@fn bool Dtk::Widget::DTitlebar::quitMenuIsDisabled() const
@brief 退出菜单是否被禁用
@return true 退出菜单被禁用 false退出菜单没有被禁用

@fn void Dtk::Widget::DTitlebar::setQuitMenuDisabled(bool disabled)
@brief 设置退出菜单是否被禁用
@param[in] disabled true 退出菜单被禁用 false退出菜单没有被禁用

@fn void Dtk::Widget::DTitlebar::setQuitMenuVisible(bool visible)
@brief 设置退出菜单是否可见
@param[in] visible true 退出菜单可见 false退出菜单不可见

@fn bool Dtk::Widget::DTitlebar::switchThemeMenuIsVisible() const
@brief 设置主题切换菜单的可视化
@return true 切换主题菜单可见 false切换主题菜单不可见

@fn void Dtk::Widget::DTitlebar::setSwitchThemeMenuVisible(bool visible)
@brief 设置切换主题菜单是否可见
@param[in] visible true 切换主题菜单可见 false 切换主题菜单不可见

@fn void Dtk::Widget::DTitlebar::setDisableFlags(Qt::WindowFlags flags)
@brief 设置需要被禁用的按钮，仅仅是在界面上禁用按钮，还是可以通过事件等机制来调用对应接口
@param[in] flags 需要被禁用的按钮标志位

@fn Qt::WindowFlags Dtk::Widget::DTitlebar::disableFlags() const
@brief 当前被禁用的按钮标志位
@return 被禁用的窗口标志

*/
