Debian Codegraph @

docs/log/Logger.zh_CN.dox

raw
1 /*!
2 @~chinese
3
4 @ingroup dlog
5 @file include/log/Logger.h
6
7 @class Dtk::Core::Logger Logger.h
8 @brief 非常简单但相当强大的组件,可用于记录你的应用程序活动。
9
10 @enum Dtk::Core::Logger::LogLevel
11 @brief 日志等级
12 @var Dtk::Core::Logger::LogLevel Dtk::Core::Logger::Trace
13 追踪级别,可用于大部分不需要的记录,用于内部代码追踪
14 @var Dtk::Core::Logger::LogLevel Dtk::Core::Logger::Debug
15 调试级别,用于软件的调试。
16 @var Dtk::Core::Logger::LogLevel Dtk::Core::Logger::Info
17 信息级别,可用于信息记录,这可能不仅对开发者有意义
18 @var Dtk::Core::Logger::LogLevel Dtk::Core::Logger::Warning
19 警告,可以用来记录你的应用程序检测到的一些非致命的警告
20 @var Dtk::Core::Logger::LogLevel Dtk::Core::Logger::Error
21 错误,可能是一个较大问题,导致你的程序工作出错,但不至于崩溃
22 @var Dtk::Core::Logger::LogLevel Dtk::Core::Logger::Fatal
23 致命错误,用于不可恢复的错误,在写入日志记录后立即崩溃应用程序(终止)
24
25 @fn Logger Dtk::Core::Logger::Logger()
26 @brief 构建Logger的实例。
27 @note 如果你只使用一个全局的logger实例,不需要手动使用这个构造函数,可以考虑使用logger宏来代替访问记录器实例
28
29 @fn Logger Dtk::Core::Logger::Logger(const QString &defaultCategory)
30 @brief 构建Logger的实例并设置Logger的默认类别
31 @note 如果你只使用一个全局的logger实例,不需要手动使用这个构造函数,
32 可以考虑使用logger宏来访问logger实例并调用setDefaultCategory方法
33 @sa Logger::Logger()
34 @sa Logger::setDefaultCategory()
35
36 @fn Logger Dtk::Core::Logger::~Logger()
37 @brief 析构函数
38 @note 你可能不需要直接使用这个函数。记录器的全局实例将在你的QCoreApplication执行结束后自动销毁
39
40 @fn static Logger* Dtk::Core::Logger::globalInstance()
41 @brief 返回Logger的全局对象
42 @note 在大多数情况下,你不应该直接使用这个函数。可以考虑使用 [logger](@ref logger) 宏来代替
43 @return Logger指针
44
45 @fn static QString Dtk::Core::Logger::levelToString(Logger::LogLevel level)
46 @brief 将LogLevel枚举值转换为其字符串表示
47 @sa Logger::LogLevel
48
49 @fn static LogLevel Dtk::Core::Logger::levelFromString(const QString &str)
50 @brief 将LogLevel字符串表示转换为枚举值
51 @note 字符串的比较是不分大小写的。如果提供的日志级别字符串不合法,则返回`Logger::Debug`的枚举值
52 @sa Logger::LogLevel
53 @sa Logger::levelToString()
54
55 @fn void Dtk::Core::Logger::registerAppender(AbstractAppender *appender)
56 @brief 注册appender来写入日志记录<br>
57 在写入日志的调用中(使用其中一个宏或`write()`函数),Logger遍历appender列表,并向每个appender写入日志记录。请查阅AbstractAppender文档以了解appenders的概念。
58 如果没有appender被添加到Logger中,它就会退回到记录到`std::cerr`流中。
59 @param[in] appender 要在Logger中注册的Appender
60 @note Logger对appender拥有所有权,它将在应用程序退出时删除它。因此,appender必须在堆上创建,以防止appender被重复销毁。
61 @sa Logger::registerCategoryAppender()
62 @sa Dtk::Core::AbstractAppender
63
64 @fn void Dtk::Core::Logger::registerCategoryAppender(const QString &category, AbstractAppender *appender)
65 @brief 注册appender,将日志记录写到特定的类别中<br>
66 @details 调用这个方法,你可以将一些appender与命名的类别联系起来。
67 在调用特定类别的日志写入时(直接调用带有类别参数的`write()`,写入默认类别,或使用特殊的`dCDebug()`、`dCWarning()`等宏),
68 Logger只将日志信息写入注册的类别appender列表中。<br>
69 你可以调用`logToGlobalInstance()`将所有类别的日志信息传递给全局的Logger实例Appender(使用`registerAppender()`注册)。
70 如果没有特定名称的类别应用程序被注册到记录器上,它就会退回到记录到`std::cerr` STL流中,这两种方法都有简单的警告信息。
71 @param[in] category 类别名称
72 @param[in] appender 要在Logger中注册的Appender
73 @note Logger对appender拥有所有权,它将在应用程序退出时删除它。根据这一点,appender必须在堆上创建,以防止appender被重复销毁。
74 @sa Logger::registerAppender()
75 @sa Logger::logToGlobalInstance()
76 @sa Logger::setDefaultCategory()
77
78 @fn void Dtk::Core::Logger::logToGlobalInstance(const QString &category, bool logToGlobal = false)
79 @brief 将一些日志类别与全局日志实例应用者联系起来。
80 如果logToGlobal设置为 "true",所有到指定类别的Logger的日志消息也将被写入全局日志实例appenders(使用`registerAppender()`注册)<br>
81 默认情况下,所有到特定类别的消息都只写到特定的类别应用者
82 (使用 `registerCategoryAppender()` 注册)
83 @param[in] category 类别名称
84 @param[in] logToGlobal 是否将日志写入全局日志appenders
85 @sa Logger::registerAppender()
86 @sa Logger::globalInstance()
87 @sa Logger::registerCategoryAppender()
88
89 @fn void Dtk::Core::Logger::setDefaultCategory(const QString &category);
90 QString defaultCategory()
91 @brief 设置默认的日志类别
92 所有到这个类别应用的日志信息也将被写入一般的日志实例应用(使用[registerAppender](@ref registerAppender)方法注册),反之亦然
93 特别是,任何对dDebug()宏的调用都将被视为类别日志
94 所以你不需要用dCDebug()宏来指定类别名称
95 要取消默认的类别,传递一个空字符串作为参数
96 @param[in] category 类别名称
97 @note "category "格式标记将被设置为所有这些消息的类别名称
98 @sa Dtk::Core::AbstractStringAppender::setFormat()
99 @sa Logger::defaultCategory()
100 @sa Logger::registerCategoryAppender()
101 @sa Logger::logToGlobalInstance()
102
103 @fn QString Dtk::Core::Logger::defaultCategory()
104 @brief 返回默认的日志类别名称
105 @sa Logger::setDefaultCategory()
106
107 @fn void Dtk::Core::Logger::write(const QDateTime &time, LogLevel level,
108 const char *file, int line,const char *func,
109 const char *category, const QString &msg)
110 @brief 写入日志记录。
111 将带有所提供参数的日志记录写给所有注册的应用
112 @param[in] time 时间戳
113 @param[in] level 日志记录等级
114 @param[in] file 目标文件名
115 @param[in] line 要输出的行数
116 @param[in] func 输出的函数名称
117 @param[in] category 日志类别
118 @param[in] msg 输出信息
119 @note 使用`Logger::Fatal`日志级别记录日志记录将导致调用STL `abort()`函数,
120 这将中断你的软件的运行并Core dump
121 @sa Logger::LogLevel
122 @sa Dtk::Core::AbstractAppender
123
124 @fn void Dtk::Core::Logger::write(LogLevel level, const char *file, int line,
125 const char *func, const char *category, const QString &msg)
126 @brief 这是为方便而提供的重载函数。它的行为与同名函数类似,此函数无需传入time参数
127 @note 这个函数使用了`QDateTime::currentDateTime()`用获得的当前时间戳
128 @sa Logger::write(const QDateTime &time, LogLevel level,
129 const char *file, int line,const char *func,
130 const char *category, const QString &msg)
131 @param[in] level 日志记录等级
132 @param[in] file 目标文件名
133 @param[in] line 要输出的行数
134 @param[in] func 输出的函数名称
135 @param[in] category 日志类别
136 @param[in] msg 输出信息
137
138 @fn QDebug Dtk::Core::Logger::write(LogLevel level, const char *file,
139 int line,const char *func, const char *category)
140 @brief 这是为方便而提供的重载函数。它的行为与同名函数类似,此函数无需传入message参数
141 @details 这个函数不接受任何日志信息作为参数。它返回的是可以使用流函数写入的`QDebug`对象<br>
142 例如,你可能想写:
143 @code
144 dDebug() << "This is the size" << size << "of the element" << elementName;
145 @endcode
146 而不是写为:
147 @code
148 dDebug(QString(QLatin1String("This is the size %1x%2 of the element %3")).arg(size.x()).arg(size.y()).arg(elementName));
149 @endcode
150 这样会更优雅一些<br>
151 请考虑阅读Qt参考文档,了解QDebug类的使用语法
152 @note 这个重载肯定是最好用的一个重载,但是代价是它会比其他的重载更为慢
153 @sa Logger::write(const QDateTime &time, LogLevel level,
154 const char *file, int line,const char *func,
155 const char *category, const QString &msg)
156 @param[in] level 日志记录等级
157 @param[in] file 目标文件名
158 @param[in] line 要输出的行数
159 @param[in] func 输出的函数名称
160 @param[in] category 日志类别
161
162 @fn void Dtk::Core::Logger:: writeAssert(const char *file, int line,
163 const char *func, const char *condition)
164 @brief 写入断言
165 @details 这个函数使用write()函数来写断言记录<br>
166 断言记录总是使用`Logger::Fatal`日志级别来写,这将导致程序的中止和核心转储(core dump)的生成(如果支持)
167 写入appenders的信息与传入参数相同,前缀为 `ASSERT:`
168 @param[in] file 目标文件名
169 @param[in] line 要输出的行数
170 @param[in] func 输出的函数名称
171 @note 不建议直接调用这个函数,你可以直接调用`LOG_ASSERT`宏,它将为这个函数提供所有需要的信息
172 @sa Logger::write(const QDateTime &time, LogLevel level,
173 const char *file, int line,const char *func,
174 const char *category, const QString &msg)
175
176 */