deepin/uos 自研应用添加帮助手册

deepin/uos系统，为自己开发的应用添加帮助手册，支持全局快捷键F1 启动帮助手册显示应用介绍．

一 按F1启动帮助手册逻辑：

DTK封装了Qt::Key_F1快捷键，用户按F1时，判断此应用是不是存在帮助手册，如果存在即会调用deepin-manual的DBus接口com.deepin.Manual.Open，启动帮助手册应用，显示帮助文档；

DTK源码：

void DMainWindowPrivate::init()｛
    if (!help) {
        help = new QShortcut(QKeySequence(Qt::Key_F1), q);
        QObject::connect(help, &QShortcut::activated,
        q, [ = ]() {
            DApplication *dapp = qobject_cast<DApplication *>(qApp);
            if (dapp) {
                dapp->handleHelpAction();
            }
        });
    }
}

 该函数在用户点击窗口标题栏的帮助按钮时触发。
  默认实现为打开当前程序的帮助手册，子类可以重现实现此函数以覆盖其默认行为。
 */
void DApplication::handleHelpAction()
{
    D_D(DApplication);
    if (customHandler()) {
        d->appHandler->handleHelpAction();
        return;
    }
    if (!DApplicationPrivate::isUserManualExists()) {
        return;
    }
#ifdef Q_OS_LINUX
    QString appid = applicationName();

    // new interface use applicationName as id
    QDBusInterface manual("com.deepin.Manual.Open",
                          "/com/deepin/Manual/Open", 
                          "com.deepin.Manual.Open");
    QDBusReply<void> reply = manual.call("ShowManual", appid);
    if (reply.isValid())  {
        qDebug() << "call com.deepin.Manual.Open success";
        return;
    }
    qDebug() << "call com.deepin.Manual.Open failed" << reply.error();
    // fallback to old interface
    QProcess::startDetached("dman", QStringList() << appid);
#else
    qWarning() << "not support dman now";
#endif
}

判断应用是否有帮助手册主要是以下方法，满足以下两个条件，自己写的demo就可以按F1启动帮助手册啦．．．

bool DApplicationPrivate::isUserManualExists()
{
#ifdef Q_OS_LINUX
    auto loadManualFromLocalFile = [=]() -> bool {
        const QString appName = qApp->applicationName();
        //判断帮助手册应用是否存在
        bool dmanAppExists = QFile::exists("/usr/bin/dman");
        bool dmanDataExists = false;
        // search all subdirectories
        
        QString strManualPath = "/usr/share/deepin-manual";
        QDirIterator it(strManualPath, QDirIterator::Subdirectories);
        while (it.hasNext()) {
            QFileInfo file(it.next());
			//判断帮助文档是否存在
            if (file.isDir() && file.fileName().contains(appName, Qt::CaseInsensitive)) {

                dmanDataExists = true;
                break;
            }

            if (file.isDir())
                continue;
        }
        return  dmanAppExists && dmanDataExists;
    };

二 使用方法

1. 创建DTK项目

DWIDGET_USE_NAMESPACE
DCORE_USE_NAMESPACE
int main(int argc, char *argv[])
{
    DApplication a(argc, argv);
    mainwindow w;
    w.setMinimumSize(1000, 500);
    w.show();

    Dtk::Widget::moveToCenter(&w);

    return a.exec();
}

3. 设置应用名属性

//设置程序单例模式
    if (!a.setSingleInstance("dtk-看看")) {
        return 0;
    }
    a.setAttribute(Qt::AA_UseHighDpiPixmaps);
    //设置主题
    a.setTheme("light");
    a.setOrganizationName("deepin");
    //应用名称,此属性为帮助手册关键属性,应用名必须与/usr/share/deepin/deepin-manual目录中的保持一致
    a.setApplicationName("deepin-dtk-demo");
    a.setApplicationVersion("1.0");
    a.setProductIcon(QIcon(":/images/logo.svg"));
    a.setProductName("deepin-dtk-demo"); //关于
    a.setApplicationDescription("This is a dtk template application.");
    //不显示鸣谢链接
    a.setApplicationAcknowledgementVisible(false);
    //设置程序授权
    a.setApplicationLicense("GPLv3");
    // 设置终端日志和日志文件处理
    DLogManager::registerConsoleAppender();
    DLogManager::registerFileAppender();

    //主题记忆
    DApplicationSettings savetheme;

5. 创建帮助手册目录

cd  /usr/share/deepin-manual/manual-assets/application
mkdir deepin-dtk-demo

6. 帮助文档资源目录结构跟其它系统应用保持一致;