/*
 * Copyright (C) 2017 ~ 2018 Deepin Technology Co., Ltd.
 *
 * Author:     Gary Wang <wzc782970009@gmail.com>
 *
 * Maintainer: Gary Wang <wangzichong@deepin.com>
 *
 * 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.
 */

/*!
    \page crumb-zh.html
    \title Crumb Bar and Address Bar (zh)

    面包屑栏 和 地址栏

    \section1 结构关系

    面包屑新增的类共三个，即 \b{面包屑栏} DFMCrumbBar , \b{面包屑项} DFMCrumbItem 和 \b{地址栏}
    DFMAddressBar 。其中 \b{地址栏} 由 \b{面包屑栏} 管理， \b{面包屑栏} 由 DToolbar 管理，二
    者互相独立，而 \b{面包屑项} 则由 \b{面包屑栏} 管理。

    另外根据需求我们需要提供插件接口并实现预制插件支持现有的协议，新增插件接口类 DFMCrumbInterface
    和相应实现类（称为\e{面包屑栏控制器}，\e{CrumbController}）。插件类的注册和加载由 DFMCrumbManager
    管理，并且 \b{地址栏} 和 \b{面包屑栏} 分别持有自己独立的面包屑栏控制器。

    \section1 面包屑栏

        \section2 控件结构

        使用 `QHBoxLayout` 盛放栏内主要内容，共三项，左箭头、面包屑容器 和 右箭头。箭头默认隐藏，当面包屑容
        器宽度不足以完整显示面包屑容器内的项时据情况显示左右箭头。

        面包屑容器使用 QScrollArea 作为容器， QHBoxLayout 做为布局并将 \b{面包屑项} DFMCrumbItem 至于其中。

        由于面包屑栏也负责管理地址栏 DFMAddressBar 的状态，故除了面包屑栏状态外还负责地址栏的显示隐藏和状态的管理。

        \section2 相关类

        详细文档请见 \l DFMCrumbBar 。

    \section1 面包屑项

        \section2 控件结构

        使用 QPushButton 作为面包屑项，接受点击和 Drop 事件。每个项均可设置文字和/或图标。点击时将跳转到项所指的
        Url ， Drop 时复制文件到所指 Url 。

        \section2 相关类

        为了方便新增一个简单的纯数据类（于 DFMCrumbInterface ，其构造函数此处省略）：

        class CrumbData {
            DUrl url;
            QString iconName;
            QString displayText;
            QString iconKey = "icon";
        };

        详细文档请见 \l DFMCrumbItem 。

    \section1 地址栏

        \section2 控件结构

        使用 `QLineEdit` ，状态由面包屑栏管理。

        搜索栏应维护一个候选列表用于其接管的候选词列表控件（使用 `QStringListModel`）。用户输入时应检查候选词
        列表并更新候选列表控件状态，补全状态。应响应 Tab 键补全。

        \section2 相关类

        详细文档请见 \l DFMAddressBar 。

    \section1 面包屑插件

    面包屑插件的任务为为（额外的）协议提供分割路径的功能。

    加载面包屑通过如下固定的 IID 识别区分插件：

    \code
    #define DFMCrumbFactoryInterface_iid "com.deepin.filemanager.DFMCrumbFactoryInterface_iid"
    \endcode

    加载插件时通过 Url 的 scheme 作为插件 key ，当存在多个插件注册同一个 key 时，使用最后一个注册的插件。

    - 插件的识别注册： DFMCrumbManager (单例)
    - 插件实例工厂： `DFMCrumbFactory`, 其 `create(key)` 返回新 DFMCrumbInterface 实例的指针。

    由于插件应该能够针对不同的 Url 的 scheme 使得面包屑栏做出不同的行为，故插件接口类持有一个 `DFMCrumbBar` 实例的指针用以访问面包屑栏。

        \section2 相关类

        详细文档请见 \l DFMCrumbManager ， \l DFMCrumbInterface 。

*/
