]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/debugrpt.h
implement wxNativeFontInfo::SetFamily for wxGTK with the same logic used by wxMSW...
[wxWidgets.git] / interface / wx / debugrpt.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: debugrpt.h
1db8f1dc 3// Purpose: interface of wxDebugReport*
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxDebugReportPreview
7c913512 11
1db8f1dc
BP
12 This class presents the debug report to the user and allows him to veto
13 report entirely or remove some parts of it. Although not mandatory, using
14 this class is strongly recommended as data included in the debug report
15 might contain sensitive private information and the user should be notified
16 about it as well as having a possibility to examine the data which had been
17 gathered to check whether this is effectively the case and discard the
18 debug report if it is.
7c913512 19
23324ae1 20 wxDebugReportPreview is an abstract base class, currently the only concrete
1db8f1dc 21 class deriving from it is wxDebugReportPreviewStd.
7c913512 22
23324ae1
FM
23 @library{wxqa}
24 @category{debugging}
25*/
7c913512 26class wxDebugReportPreview
23324ae1
FM
27{
28public:
29 /**
1db8f1dc 30 Default constructor.
23324ae1
FM
31 */
32 wxDebugReportPreview();
33
34 /**
1db8f1dc 35 Destructor is trivial as well but should be virtual for a base class.
23324ae1 36 */
1db8f1dc 37 virtual ~wxDebugReportPreview();
23324ae1
FM
38
39 /**
1db8f1dc
BP
40 Present the report to the user and allow him to modify it by removing
41 some or all of the files and, potentially, adding some notes.
42
d29a9a8a 43 @return @true if the report should be processed or @false if the user
1db8f1dc
BP
44 chose to cancel report generation or removed all files from
45 it.
23324ae1 46 */
b91c4601 47 virtual bool Show(wxDebugReport& dbgrpt) const = 0;
23324ae1
FM
48};
49
50
e54c96f1 51
23324ae1
FM
52/**
53 @class wxDebugReportCompress
7c913512 54
1db8f1dc
BP
55 wxDebugReportCompress is a wxDebugReport which compresses all the files in
56 this debug report into a single ZIP file in its wxDebugReport::Process()
57 function.
7c913512 58
23324ae1
FM
59 @library{wxqa}
60 @category{debugging}
61*/
62class wxDebugReportCompress : public wxDebugReport
63{
64public:
65 /**
66 Default constructor does nothing special.
67 */
68 wxDebugReportCompress();
69
70 /**
1db8f1dc
BP
71 Returns the full path of the compressed file (empty if creation
72 failed).
23324ae1 73 */
b91c4601 74 const wxString& GetCompressedFileName() const;
23324ae1
FM
75};
76
77
e54c96f1 78
23324ae1
FM
79/**
80 @class wxDebugReport
7c913512 81
1db8f1dc
BP
82 wxDebugReport is used to generate a debug report, containing information
83 about the program current state. It is usually used from
84 wxApp::OnFatalException() as shown in the @ref page_samples_debugrpt.
7c913512 85
1db8f1dc
BP
86 A wxDebugReport object contains one or more files. A few of them can be
87 created by the class itself but more can be created from the outside and
88 then added to the report. Also note that several virtual functions may be
89 overridden to further customize the class behaviour.
7c913512 90
23324ae1 91 Once a report is fully assembled, it can simply be left in the temporary
1db8f1dc
BP
92 directory so that the user can email it to the developers (in which case
93 you should still use wxDebugReportCompress to compress it in a single file)
94 or uploaded to a Web server using wxDebugReportUpload (setting up the Web
95 server to accept uploads is your responsibility, of course). Other
96 handlers, for example for automatically emailing the report, can be defined
97 as well but are not currently included in wxWidgets.
98
99 A typical usage example:
100
101 @code
102 wxDebugReport report;
103 wxDebugReportPreviewStd preview;
104
105 report.AddCurrentContext(); // could also use AddAll()
106 report.AddCurrentDump(); // to do both at once
107
108 if ( preview.Show(report) )
109 report.Process();
110 @endcode
7c913512 111
23324ae1
FM
112 @library{wxqa}
113 @category{debugging}
114*/
7c913512 115class wxDebugReport
23324ae1
FM
116{
117public:
1db8f1dc
BP
118 /**
119 This enum is used for functions that report either the current state or
120 the state during the last (fatal) exception.
121 */
122 enum Context {
123 Context_Current,
124 Context_Exception
125 };
126
23324ae1
FM
127 /**
128 The constructor creates a temporary directory where the files that will
1db8f1dc 129 be included in the report are created. Use IsOk() to check for errors.
23324ae1
FM
130 */
131 wxDebugReport();
132
133 /**
134 The destructor normally destroys the temporary directory created in the
1db8f1dc
BP
135 constructor with all the files it contains. Call Reset() to prevent
136 this from happening.
23324ae1 137 */
adaaa686 138 virtual ~wxDebugReport();
23324ae1
FM
139
140 /**
141 Adds all available information to the report. Currently this includes a
1db8f1dc
BP
142 text (XML) file describing the process context and, under Win32, a
143 minidump file.
23324ae1
FM
144 */
145 void AddAll(Context context = Context_Exception);
146
147 /**
148 Add an XML file containing the current or exception context and the
149 stack trace.
150 */
adaaa686 151 virtual bool AddContext(Context ctx);
23324ae1
FM
152
153 /**
1db8f1dc 154 The same as calling AddContext(Context_Current).
23324ae1
FM
155 */
156 bool AddCurrentContext();
157
158 /**
1db8f1dc 159 The same as calling AddDump(Context_Current).
23324ae1
FM
160 */
161 bool AddCurrentDump();
162
163 /**
164 Adds the minidump file to the debug report.
1db8f1dc
BP
165
166 Minidumps are only available under recent Win32 versions
167 (@c dbghlp32.dll can be installed under older systems to make minidumps
168 available).
23324ae1 169 */
da1ed74c 170 virtual bool AddDump(Context ctx);
23324ae1
FM
171
172 /**
1db8f1dc 173 The same as calling AddContext(Context_Exception).
23324ae1
FM
174 */
175 bool AddExceptionContext();
176
177 /**
1db8f1dc 178 The same as calling AddDump(Context_Exception).
23324ae1
FM
179 */
180 bool AddExceptionDump();
181
182 /**
1db8f1dc
BP
183 Add another file to the report. If @a filename is an absolute path, it
184 is copied to a file in the debug report directory with the same name.
185 Otherwise the file should already exist in this directory
186 @a description only exists to be displayed to the user in the report
187 summary shown by wxDebugReportPreview.
188
189 @see GetDirectory(), AddText()
23324ae1 190 */
adaaa686 191 virtual void AddFile(const wxString& filename, const wxString& description);
23324ae1
FM
192
193 /**
1db8f1dc
BP
194 This is a convenient wrapper around AddFile(). It creates the file with
195 the given @a name and writes @a text to it, then adds the file to the
196 report. The @a filename shouldn't contain the path.
197
d29a9a8a 198 @return @true if file could be added successfully, @false if an IO
1db8f1dc 199 error occurred.
23324ae1
FM
200 */
201 bool AddText(const wxString& filename, const wxString& text,
202 const wxString& description);
203
23324ae1 204 /**
1db8f1dc
BP
205 This method should be used to construct the full name of the files
206 which you wish to add to the report using AddFile().
207
d29a9a8a 208 @return The name of the temporary directory used for the files in this
1db8f1dc 209 report.
23324ae1 210 */
b91c4601 211 const wxString& GetDirectory() const;
23324ae1
FM
212
213 /**
1db8f1dc
BP
214 Retrieves the name (relative to GetDirectory()) and the description of
215 the file with the given index. If @a n is greater than or equal to the
216 number of filse, @false is returned.
23324ae1 217 */
328f5751 218 bool GetFile(size_t n, wxString* name, wxString* desc) const;
23324ae1
FM
219
220 /**
221 Gets the current number files in this report.
222 */
328f5751 223 size_t GetFilesCount() const;
23324ae1
FM
224
225 /**
7c913512 226 Gets the name used as a base name for various files, by default
1db8f1dc 227 wxApp::GetAppName() is used.
23324ae1 228 */
adaaa686 229 virtual wxString GetReportName() const;
23324ae1
FM
230
231 /**
1db8f1dc
BP
232 Returns @true if the object was successfully initialized. If this
233 method returns @false the report can't be used.
23324ae1 234 */
328f5751 235 bool IsOk() const;
23324ae1
FM
236
237 /**
238 Processes this report: the base class simply notifies the user that the
239 report has been generated. This is usually not enough -- instead you
240 should override this method to do something more useful to you.
241 */
242 bool Process();
243
244 /**
1db8f1dc
BP
245 Removes the file from report: this is used by wxDebugReportPreview to
246 allow the user to remove files potentially containing private
247 information from the report.
23324ae1
FM
248 */
249 void RemoveFile(const wxString& name);
250
251 /**
1db8f1dc
BP
252 Resets the directory name we use. The object can't be used any more
253 after this as it becomes uninitialized and invalid.
23324ae1
FM
254 */
255 void Reset();
5e6e278d
FM
256
257protected:
258
259 /**
260 This function may be overridden to add arbitrary custom context to the
261 XML context file created by AddContext(). By default, it does nothing.
262 */
263 virtual void DoAddCustomContext(wxXmlNode* nodeRoot);
264
265 /**
266 This function may be overridden to modify the contents of the exception
267 tag in the XML context file.
268 */
269 virtual bool DoAddExceptionInfo(wxXmlNode* nodeContext);
270
271 /**
272 This function may be overridden to modify the contents of the modules
273 tag in the XML context file.
274 */
275 virtual bool DoAddLoadedModules(wxXmlNode* nodeModules);
276
277 /**
278 This function may be overridden to modify the contents of the system
279 tag in the XML context file.
280 */
281 virtual bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo);
23324ae1
FM
282};
283
284
e54c96f1 285
23324ae1
FM
286/**
287 @class wxDebugReportPreviewStd
7c913512 288
1db8f1dc
BP
289 wxDebugReportPreviewStd is a standard debug report preview window. It
290 displays a dialog allowing the user to examine the contents of a debug
291 report, remove files from and add notes to it.
7c913512 292
23324ae1
FM
293 @library{wxqa}
294 @category{debugging}
295*/
296class wxDebugReportPreviewStd : public wxDebugReportPreview
297{
298public:
299 /**
300 Trivial default constructor.
301 */
302 wxDebugReportPreviewStd();
303
304 /**
1db8f1dc
BP
305 Shows the dialog.
306
307 @see wxDebugReportPreview::Show()
23324ae1 308 */
328f5751 309 bool Show(wxDebugReport& dbgrpt) const;
23324ae1
FM
310};
311
312
e54c96f1 313
23324ae1
FM
314/**
315 @class wxDebugReportUpload
7c913512 316
1db8f1dc
BP
317 This class is used to upload a compressed file using HTTP POST request. As
318 this class derives from wxDebugReportCompress, before upload the report is
319 compressed in a single ZIP file.
7c913512 320
23324ae1
FM
321 @library{wxqa}
322 @category{debugging}
323*/
324class wxDebugReportUpload : public wxDebugReportCompress
325{
326public:
327 /**
1db8f1dc
BP
328 This class will upload the compressed file created by its base class to
329 an HTML multipart/form-data form at the specified address. The @a url
330 is the upload page address, @a input is the name of the @c "type=file"
331 control on the form used for the file name and @a action is the value
332 of the form action field. The report is uploaded using the @e curl
333 program which should be available, the @e curl parameter may be used to
334 specify the full path to it.
23324ae1
FM
335 */
336 wxDebugReportUpload(const wxString& url, const wxString& input,
1db8f1dc
BP
337 const wxString& action,
338 const wxString& curl = "curl");
23324ae1 339
5e6e278d 340protected:
23324ae1 341 /**
1db8f1dc
BP
342 This function may be overridden in a derived class to show the output
343 from curl: this may be an HTML page or anything else that the server
344 returned. Value returned by this function becomes the return value of
345 wxDebugReport::Process().
23324ae1 346 */
b91c4601 347 virtual bool OnServerReply(const wxArrayString& reply);
23324ae1 348};
e54c96f1 349