| 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 |
*/ |