From 1c3a4fead2fdbd133b1635fe7ce5b79f365ef3c1 Mon Sep 17 00:00:00 2001 From: iaom Date: Fri, 24 Nov 2023 14:44:17 +0800 Subject: [PATCH] feat(doc):Add qch docment for libukui-notification. --- README.md | 2 +- libukui-notification/CMakeLists.txt | 35 ++++++ libukui-notification/notification-client.h | 38 ++++++- .../notification-close-reason.h | 29 +++-- .../applications-settings.h | 3 +- .../notification-global-settings.h | 4 + .../single-application-settings.h | 3 +- libukui-notification/popup-notification.h | 104 ++++++++++++++++++ libukui-notification/utils.h | 16 +++ test/CMakeLists.txt | 1 - 10 files changed, 220 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 5409b81..207c13d 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ popup-notification.h 单条通知的所有信息 notification-global-settings.h 全局通知设置 -application-settings.h 应用通知行为设置 +applications-settings.h 应用通知行为设置 single-application-settings.h 单个应用的通知设置 #### 代码编译： diff --git a/libukui-notification/CMakeLists.txt b/libukui-notification/CMakeLists.txt index 2ac6999..097fa3a 100644 --- a/libukui-notification/CMakeLists.txt +++ b/libukui-notification/CMakeLists.txt @@ -4,6 +4,14 @@ set(VERSION_MICRO 0) set(UKUI_NOTIFICATION_VERSION ${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_MICRO}) find_package(KF5WindowSystem) +include(FeatureSummary) + +find_package(ECM) +option(BUILD_QCH "Build API documentation in QCH format (for e.g. Qt Assistant, Qt Creator & KDevelop)" TRUE) +add_feature_info(QCH ${BUILD_QCH} "API documentation in QCH format (for e.g. Qt Assistant, Qt Creator & KDevelop)") +set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH}) +include(ECMAddQch) + find_package(PkgConfig REQUIRED) set(UKUI_NOTIFICATION_EXTERNAL_LIBS "") set(UKUI_NOTIFICATION_PC_PKGS ukui-search) @@ -16,6 +24,7 @@ foreach(PC_LIB IN ITEMS ${UKUI_NOTIFICATION_PC_PKGS}) list(APPEND UKUI_NOTIFICATION_EXTERNAL_LIBS ${${PC_LIB}_LIBRARIES}) endif() endforeach() + include_directories(notification-settings) set(ukui-notification_LIB_SRCS notification-client.cpp @@ -74,6 +83,32 @@ set(HEADERS_INSTALL_DIR /usr/include/ukui-notification) set(PC_INSTALL_DIR "/usr/lib/pkgconfig") target_include_directories(ukui-notification PUBLIC $) +if (BUILD_QCH) + set(QCH_INSTALL_DIR "/usr/share/qt5/doc/") + ecm_add_qch( + ukui-notification-qch + NAME ukui-notification + BASE_NAME ukui-notification + VERSION "${UKUI_NOTIFICATION_VERSION}" + ORG_DOMAIN org.ukui + SOURCES ${HEADERS} + MD_MAINPAGE "${CMAKE_SOURCE_DIR}/README.md" + LINK_QCHS + INCLUDE_DIRS ${CMAKE_CURRENT_BINARY_DIR} + TAGFILE_INSTALL_DESTINATION ${QCH_INSTALL_DIR} + QCH_INSTALL_DESTINATION ${QCH_INSTALL_DIR} + COMPONENT Devel + ) + ecm_install_qch_export( + TARGETS ukui-notification-qch + FILE ukui-notification-qch-targets.cmake + DESTINATION "${CMAKE_CONFIG_INSTALL_DIR}" + COMPONENT Devel + ) + set(PACKAGE_INCLUDE_QCHTARGETS "include(\"\${CMAKE_CURRENT_LIST_DIR}/ukui-notification-qch-targets.cmake\")") +endif() + + configure_package_config_file( "${CMAKE_CURRENT_SOURCE_DIR}/ukui-notification-config.cmake.in" "${CMAKE_CURRENT_BINARY_DIR}/ukui-notification-config.cmake" diff --git a/libukui-notification/notification-client.h b/libukui-notification/notification-client.h index f9f5f92..dc481b3 100644 --- a/libukui-notification/notification-client.h +++ b/libukui-notification/notification-client.h @@ -25,22 +25,52 @@ #include "notification-close-reason.h" namespace UkuiNotification { class NotificationClientPrivate; +/** + * @short 通知中心客户端接口. + * @author iaom + */ class UKUINOTIFICATION_EXPORT NotificationClient : public QObject { Q_OBJECT public: explicit NotificationClient(QObject *parent = nullptr); ~NotificationClient(); - /** - * 注册成为弹窗通知客户端 - * @return ture-成功 false 失败 - */ + /** + * @brief 客户端注册，注册后可监听通知发送&关闭信号或调用通知动作执行以及主动关闭通知的接口。 + * @return 是否成功操作 + * @retval 成功：true；失败：false + */ bool registerClient(); + /** + * @brief 注销当前客户端，注销后将不能再接收到新通知或通知关闭信号。 + * @return 是否成功操作 + * @retval 成功：true；失败：false + */ void unregisterClient(); + /** + * @brief 关闭一条通知 + * @param id：通知id + * @param reason：通知关闭原因 + * @return 是否成功操作 + * @retval 成功：true；失败：false + */ bool closeNotification(uint id, NotificationCloseReason::CloseReason reason); + /** + * @brief 执行动作 + * @param id： 通知id + * @param action_key： action的唯一标识 + * @return 是否成功操作 + * @retval 成功：true；失败：false + */ bool invokeAction(uint id, const QString &action_key); Q_SIGNALS: + /** + * 通知服务收到新通知时发送. + */ void newNotification(const UkuiNotification::PopupNotification ¬ification); + /** + * 通知被关闭时发送. + */ void notificationClosed(uint id, UkuiNotification::NotificationCloseReason::CloseReason closeReason); private: NotificationClientPrivate *d = nullptr; diff --git a/libukui-notification/notification-close-reason.h b/libukui-notification/notification-close-reason.h index 189731b..0bb2a0d 100644 --- a/libukui-notification/notification-close-reason.h +++ b/libukui-notification/notification-close-reason.h @@ -23,20 +23,35 @@ #include #include "ukui-notification_global.h" - namespace UkuiNotification { +/** + * @short 通知被关闭的原因. + * @author iaom + */ class UKUINOTIFICATION_EXPORT NotificationCloseReason { Q_GADGET public: /** - * The reason a notification was closed - */ + * The reason a notification was closed + */ enum CloseReason { - Expired = 1, // The notification expired(timed out). - DismissedByUser = 2, // The notification was dismissed by the user. - Revoked = 3, //< The notification was closed by sender by a call to CloseNotification. - Undefined = 4, //Undefined/reserved reasons. + /** + * 通知过期. + */ + Expired = 1, + /** + * 通知被用户关闭. + */ + DismissedByUser = 2, + /** + * 通知被发送者通过调用CloseNotification接口关闭 + */ + Revoked = 3, + /** + * 未定义/保留原因 + */ + Undefined = 4, }; Q_ENUM(CloseReason) }; diff --git a/libukui-notification/notification-settings/applications-settings.h b/libukui-notification/notification-settings/applications-settings.h index 578fef6..647b967 100644 --- a/libukui-notification/notification-settings/applications-settings.h +++ b/libukui-notification/notification-settings/applications-settings.h @@ -27,7 +27,8 @@ namespace UkuiNotification{ typedef QMap ApplicationsSettingsMap; class ApplicationsSettingsPrivate; /** - * SingleApplicationSettings 工厂 + * @short 用于获取应用的设置. + * @author iaom */ class ApplicationsSettings : public QObject { diff --git a/libukui-notification/notification-settings/notification-global-settings.h b/libukui-notification/notification-settings/notification-global-settings.h index 6981694..b333d7a 100644 --- a/libukui-notification/notification-settings/notification-global-settings.h +++ b/libukui-notification/notification-settings/notification-global-settings.h @@ -24,6 +24,10 @@ #include "settings-properties.h" namespace UkuiNotification { class NotificationGlobalSettingsPrivate; +/** + * @short 通知的全局设置. + * @author iaom + */ class NotificationGlobalSettings : public QObject { Q_OBJECT diff --git a/libukui-notification/notification-settings/single-application-settings.h b/libukui-notification/notification-settings/single-application-settings.h index 44662a0..94d53ee 100644 --- a/libukui-notification/notification-settings/single-application-settings.h +++ b/libukui-notification/notification-settings/single-application-settings.h @@ -25,7 +25,8 @@ namespace UkuiNotification { class SingleApplicationSettingsPrivate; /** - * 一个应用的设置項 + * @short 表示单个应用的设置通知设置. + * @author iaom */ class SingleApplicationSettings : public QObject { diff --git a/libukui-notification/popup-notification.h b/libukui-notification/popup-notification.h index de21d2a..44b0daa 100644 --- a/libukui-notification/popup-notification.h +++ b/libukui-notification/popup-notification.h @@ -32,32 +32,106 @@ namespace UkuiNotification { class PopupNotificationPrivate; typedef QList> ActionList; +/** + * @short 表示一条通知。 + * @author iaom + */ class UKUINOTIFICATION_EXPORT PopupNotification { friend class NotificationSettingsTest; Q_GADGET + /** + * 通知ID。 + */ Q_PROPERTY(uint id READ id) + /** + * 应用名称。 + */ Q_PROPERTY(QString applicationName READ applicationName WRITE setApplicationName) + /** + * 应用图标名。 + */ Q_PROPERTY(QString applicationIconName READ applicationIconName WRITE setApplicationIconName) + /** + * 通知摘要。 + */ Q_PROPERTY(QString summary READ summary WRITE setSummary) + /** + * 通知消息体。 + */ Q_PROPERTY(QString body READ body WRITE setBody) + /** + * 通知创建时间。 + */ Q_PROPERTY(QDateTime createdTime READ createdTime) + /** + * 是否有默认action,通常用于点击通知弹窗时执行。 + */ Q_PROPERTY(bool hasDefaultAction READ hasDefaultAction) + /** + * 通知action列表，表示通知包含的actions及执行动作信息，列表中两个为一组，偶数位（从0开始）表示一条action的唯一标识，奇数位表示要显示给用户的的内容。 + * 一般点击消息体产生的action为“default”，对应的内容无要求，一般不会显示给用户（但是需要在发送协议中和action拼成一组）。有额外需要用户操作的action则会在通知弹窗里以按钮形式展示。 + */ Q_PROPERTY(ActionList actions READ actions) + /** + * 通知超时失效时间（通知失效后会发送NotificationClosed信号，并且通知弹窗无法再继续操作）-1：系统默认；0 不会超时； >0 表示超时时间。 + */ Q_PROPERTY(int timeout READ timeout WRITE setTimeout) + /** + * 是否支持hints中的action-icon功能。 + */ Q_PROPERTY(bool enableActionIcons READ enableActionIcons) + /** + * 对应hints中的image-data字段。 + */ Q_PROPERTY(QImage image READ image) + /** + * 当加载image-data失败，或通过image-path加载image失败时（image-path不是URL）,icon会被设置为image-path数据。 + */ Q_PROPERTY(QString icon READ icon) + /** + * 当设置为true时，通知中心将不会在用户点击action按钮后自动移除消息。仅当用户关闭或被通知发送者关闭才会移除通知。 + */ Q_PROPERTY(bool resident READ resident) + /** + * 设置为true后，通知服务将通知视为临时的（不会一直存在）。 + */ Q_PROPERTY(bool transient READ transient) + /** + * 通知发送时播放的声音文件路径。 + */ Q_PROPERTY(QString soundFile READ soundFile) + /** + * 声音主题中的声音名称。 + */ Q_PROPERTY(QString soundName READ soundName) + /** + * 指定通知服务静音，通常用于通知发送者播放自己的声音。 + */ Q_PROPERTY(bool suppressSound READ suppressSound) + /** + * 当前通知的种类。 + */ Q_PROPERTY(QString category READ category) + /** + * 紧急程度。 + */ Q_PROPERTY(Urgency urgency READ urgency WRITE setUrgency) + /** + * 表示当前通知要显示在哪个DISPLAY上。 + */ Q_PROPERTY(QString display READ display) + /** + * 和action对应，依次表示每个action的状态(包括default action)。 + */ Q_PROPERTY(QStringList actionState READ actionState) + /** + * 设置为true后，通知将不会被折叠。 + */ Q_PROPERTY(bool noFold READ noFold) + /** + * 通知弹窗持续时间，超过此时间后被收纳进通知中心（单位秒）。-1：表示消息通知常驻,不会收纳进通知中心；0：表示通知将直接进入侧边栏通知中心，不会弹窗；>0: 表示通知弹窗持续时间。 + */ Q_PROPERTY(int popupTimeout READ popupTimeout) public: @@ -65,8 +139,17 @@ public: * The notification urgency. */ enum Urgency { + /** + * 低：不弹窗提醒，直接进入通知中心；重复应用通知会折叠。 + */ LowUrgency = 0, + /** + * 普通：弹窗默认6s后关闭，进入通知中心；重复应用通知会折叠。 + */ NormalUrgency = 1, + /** + * 重要：通知弹窗默认常驻，可点击关闭；通知不会折叠。 + */ CriticalUrgency = 2, }; Q_ENUM(Urgency) @@ -77,20 +160,41 @@ public: PopupNotification &operator=(PopupNotification &&other) Q_DECL_NOEXCEPT; ~PopupNotification(); + /** + * 通知ID。 + */ uint id() const; + /** + * 应用名称。 + */ QString applicationName() const; void setApplicationName(const QString &applicationName); + /** + * 应用图标名。 + */ QString applicationIconName() const; void setApplicationIconName(const QString &applicationIconName); + /** + * 通知摘要。 + */ QString summary() const; void setSummary(const QString &summary); + /** + * 通知消息体。 + */ QString body() const; void setBody(const QString &body); + /** + * 是否有默认action,通常用于点击通知弹窗时执行。 + */ bool hasDefaultAction() const; + /** + * 默认action的label名称。 + */ QString defaultActionLabel(); void setActions(const QStringList &actions); ActionList actions() const; diff --git a/libukui-notification/utils.h b/libukui-notification/utils.h index d248884..c9dd37e 100644 --- a/libukui-notification/utils.h +++ b/libukui-notification/utils.h @@ -21,9 +21,25 @@ #define UKUI_NOTIFICATION_UTILS_H #include namespace UkuiNotification { +/** + * @short 提供一些方便的接口. + * @author iaom + */ namespace Utils { + /** + * @brief 根据进程号@p pid 获取应用的desktop文件。 + * @return desktop文件全路径 + */ QString desktopEntryFromPid(uint pid); + /** + * @brief 根据进程号@p pid 获取应用所在的DISPLAY。 + * @return DISPLAY的值 + */ QString displayFromPid(uint pid); + /** + * @brief 根据desktop文件名（不带后缀）获取全路径。 + * @return desktop文件全路径 + */ QString desktopEntryFromName(const QString& desktopFileName); } } diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt index 4b54e32..e725368 100644 --- a/test/CMakeLists.txt +++ b/test/CMakeLists.txt @@ -4,7 +4,6 @@ set(notificationClientTest_SRCS main.cpp notification-settings-test.cpp notification-settings-test.h) include_directories(${CMAKE_SOURCE_DIR}/libukui-notification ${CMAKE_SOURCE_DIR}/libukui-notification/notification-settings) -message(${notificationClientTest_SRCS}, "123123") add_executable(ukui-notification-test ${notificationClientTest_SRCS}) target_link_libraries(ukui-notification-test PRIVATE