openkylin
/
ukui-notification
mirror of https://gitee.com/openkylin/ukui-notification.git
9
0
Fork 1
Code Issues Projects Releases Wiki Activity

feat(doc):Add qch docment for libukui-notification.

This commit is contained in:
iaom 2023-11-24 14:44:17 +08:00
parent a685245313
commit 9f84e6c9a7
10 changed files with 220 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -45,7 +45,7 @@ popup-notification.h 单条通知的所有信息
notification-global-settings.h 全局通知设置
application-settings.h 应用通知行为设置
applications-settings.h 应用通知行为设置
single-application-settings.h 单个应用的通知设置
#### 代码编译：

35
libukui-notification/CMakeLists.txt
View File

@ -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 $<INSTALL_INTERFACE:${HEADERS_INSTALL_DIR}>)
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"

38
libukui-notification/notification-client.h
View File

@ -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 &notification);
/**
* 通知被关闭时发送.
*/
void notificationClosed(uint id, UkuiNotification::NotificationCloseReason::CloseReason closeReason);
private:
NotificationClientPrivate *d = nullptr;

29
libukui-notification/notification-close-reason.h
View File

@ -23,20 +23,35 @@
#include <QObject>
#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)
};

3
libukui-notification/notification-settings/applications-settings.h
View File

@ -27,7 +27,8 @@ namespace UkuiNotification{
typedef QMap<QString, SingleApplicationSettings*> ApplicationsSettingsMap;
class ApplicationsSettingsPrivate;
/**
* SingleApplicationSettings 工厂
* @short 用于获取应用的设置.
* @author iaom
*/
class ApplicationsSettings : public QObject
{

4
libukui-notification/notification-settings/notification-global-settings.h
View File

@ -24,6 +24,10 @@
#include "settings-properties.h"
namespace UkuiNotification {
class NotificationGlobalSettingsPrivate;
/**
* @short 通知的全局设置.
* @author iaom
*/
class NotificationGlobalSettings : public QObject
{
Q_OBJECT

3
libukui-notification/notification-settings/single-application-settings.h
View File

@ -25,7 +25,8 @@
namespace UkuiNotification {
class SingleApplicationSettingsPrivate;
/**
* 一个应用的设置項
* @short 表示单个应用的设置通知设置.
* @author iaom
*/
class SingleApplicationSettings : public QObject
{

104
libukui-notification/popup-notification.h
View File

@ -32,32 +32,106 @@
namespace UkuiNotification {
class PopupNotificationPrivate;
typedef QList<QPair<QString, QString>> 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;

16
libukui-notification/utils.h
View File

@ -21,9 +21,25 @@
#define UKUI_NOTIFICATION_UTILS_H
#include <QString>
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);
}
}

1
test/CMakeLists.txt
View File

@ -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