blob: e8dbf6d87e51be26293f10d159c5b050a67bd360 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of QtLogger
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page index.html
\title QLogger Reference
\brief The Qt Logging API provides the application developer a categorized logging mechanism.
\section1 Introduction
The Qt Logging API provides the application developer a categorized logging mechanism.
\section1 Overview
The logging is designed to provide a flexible logging mechanism in an efficent manner.
\section1 Features
1. Enable or disable logging without recompiling your project.
Logging can be activated by providing a logging rules file or providing a QByteArray that contains the
\l {logging_rules} {rules}.
2. Logging with categories
Developer can create their own logging categories.
Every category can be turned on or off for logging during runtime.
Each category contains a subset of "debug", "warning" and "critical" subcategories.
In the initialization logging will be performed for all "warning" and "critical" subcategories.
\section1 How to Use
\section2 Add QLogger to Your Project
First you need to add the QLogger library dependency to your application:
LIBS += -lQtLogger
or use
QT+= logger
In your application you need to include the QLogger header:
#include <QtLogger/QtLogger>
Note: qDebug, qWarning and qCritical getting redefined in this header so make sure that the QLogger header gets included after qlogging.h.
\section2 Creating Logging Rules
\target logging_rules
As mentioned above logging rules are needed to control the behavior of the logging.
The logging rules containing basically the categories and a true/false value for each category:
Here is an example of some logging rules:
\table
\header
\row \li Nokia.driver.usb.debug = true
\row \li Nokia.driver.usb.warning = true
\row \li Nokia.driver.event = false
\endtable
Of course you could write Nokia.driver.usb = true, this will enable all subcategories (debug, warning and critical).
Vice versa with Nokia.driver.usb = false.
\section3 Wildcards
Wildcard (*) category definitions are possible as well. The order of the categories in your configuration is important. From top to bottom the category priority is low to high.
e.g:
\table
\header
\row \li Nokia*=false
\row \li *Nokia=true
\row \li *Nokia*=true
\endtable
All categories containing the word Nokia will be logged.
Willdcard "*" can only apply to the beginning or/and to the end of your configuration category entry.
The usage of qDebug(), qWarning() and qCrititcal results in the category "default".
e.g.
\table
\header \li Macro \li category
\row \li qDebug \li "default.debug"
\row \li qWarning \li "default.warning"
\row \li qCritical \li "default.critical"
\endtable
The logging rule file can be defined by using the environment variable QT_LOGGING_CONFIG.
The application developer can set the rule file by using:
qSetLoggingRulesFile(const QString &path)
or by defining a QByteArray containing the rules and call:
qSetLoggingRules(const QByteArray &configcontent)
If there is no configuration available logging will not be performed.
Note: QT_LOGGING_CONFIG will overwrite the qSetLoggingRulesFile and qSetLoggingRules calls.
\section2 Logging usage in your project
Qt provides a macro to create your logging Categories:
\snippet logger/main.cpp 1
In this example a logging category NOKIA_DRIVER_USB with a category string of "Nokia.driver.usb" and NOKIA_DRIVER_EVENT with a category string of "Nokia.driver.event" is created.
In you configuration file you could write:
\table
\header
\row \li Nokia.driver.usb = true
\row \li Nokia.driver.event = true
\row \li or even: Nokia.driver.* = true
\endtable
Next you need to tell Qt where the logging rules configuration file can be found.
\snippet logger/main.cpp 2
In this example the configuration file "mylogging.cfg" is in the current directory.
A category logging can be done by using the qCDebug(<category>), qCWarning(<category>) or the qCCritical(<category>) macro.
\snippet logger/main.cpp 3
\section1 Default settings
If there is no logging rules defined "debug" subcategories are disabled but "warning" and "critical" are enabled.
\section1 Functions
\section2
qSetLoggingRules(const QByteArray &rules)
Set the logging rules with the given \a rules byte array.
\section2
qSetLoggingRulesFile(const QString &path)
Set the config file with the given \a path which contains the logging rules for category logging.
The parameter \a path can contain only the file name.
In this case the standard path for configuration files QStandardPaths will be used.
*/
|
