1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: Defines the AutoCaptureMechanism class
4 // Author: Utensil Candel (UtensilCandel@@gmail.com)
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
8 #ifndef _AUTOCAPTURE_H_
9 #define _AUTOCAPTURE_H_
11 #include "wx/beforestd.h"
13 #include "wx/afterstd.h"
15 #include "wx/gdicmn.h"
18 class wxFlexGridSizer
;
23 GlobalAdjustFlags works with AutoCaptureMechanism's constructor, to
24 configure auto-adjustments of all controls.
26 They are used to make AutoCaptureMechanism more configurable and provide a
27 fallback to detect the bugs that the adjustments intended to avoid.
31 enum GlobalAdjustFlags
34 This is the default. All adjustments instructed in
35 AutoCaptureMechanism::RegisterControl() will be performed.
40 Disable region adjustment for all controls.
42 AJ_DisableRegionAdjust
= 1 << 0,
45 Enable region adjustment for all controls.
47 If AJ_DisableRegionAdjust and AJ_AlwaysRegionAdjust are both specified,
48 current implemetation will ignore AJ_DisableRegionAdjust.
50 AJ_AlwaysRegionAdjust
= 1 << 1,
53 Disable name adjustment for all controls.
55 AJ_DisableNameAdjust
= 1 << 2,
58 For all the "Drop-down Controls", e.g. wxChoice, do not prompt the user
59 about whether to capture their drop-down state, and always capture only
60 its non-drop-down state.
62 AJ_DisableDropdown
= 1 << 3
66 AdjustFlags works with AutoCaptureMechanism::RegisterControl() to specify
67 how to adjust the screenshot of the current control.
69 They are used to avoid bugs, look better or interact with user etc.
71 @see GlobalAdjustFlags
76 This is the default. Perform no adjustment for this control.
81 Perform region adjustment for this control.
83 On some platforms and for some controls, wxWindow::GetScreenRect() will
84 return a smaller or deflected region. In these cases, the screenshots
85 we get are incomplete. It's recommended for everyone to fix the
86 controls' code, yet this flag provides a workaround to get a guaranteed
87 correct region without using wxWindow::GetScreenRect().
89 This workaround ("label trick") is inspired by (or say stolen from)
92 AJ_RegionAdjust
= 1 << 0,
95 This flag provides a way to capture the drop-down state of "Drop-down
96 Controls", e.g. wxChoice.
98 For all the "Drop-down Controls", prompt the user about whether to
99 capture their drop-down state, if the user chooses YES, he should drop
100 down the control in about 3 seconds and wait util it's captured in that
103 AJ_Dropdown
= 1 << 1,
106 This flag is used internally by RegisterPageTurn(). Don't use it
107 directly unless you know what you are doing.
109 AJ_TurnPage
= 1 << 2,
112 This flag provides a functionality to union screenshots of different
113 modes/states of a control into one image. e.g. the single-line /
114 multi-line modes of a wxTextCtrl.
116 For a series of controls to be unioned, you should specify AJ_Union for
117 the first, and AJ_UnionEnd for the last. For the controls between them,
118 you can either specify AJ_Union or not.
120 The filename of the generated screenshot is the name of the first
121 control in the series.
132 @class AutoCaptureMechanism
134 AutoCaptureMechanism provides an easy-to-use and adjustable facility to
135 take the screenshots for all controls fully automatically and correctly. It
136 also provides an advanced feature to union screenshots of different
137 states/modes of a control.
139 @section tag_filename_convention Screenshot File Name Convention
141 All screenshots are generated as PNG files. For a control named wxName, its
142 screenshot file name would be "name.png", e.g. "button.png" for wxButton.
143 This is the protocol with the doxygen document of wxWidgets.
145 By default, screenshots are generated under the subdirectory "screenshots"
146 of current working directory. During updating or adding new screenshots,
147 first make sure screenshots are generated correctly, and then copy them to
148 the "docs/doxygen/images" folder directly.
150 @section tag_gui_assumption The Assumption of GUI
152 Unfortunately, this class have an assumption about the structure of GUI: It
153 must have the following top-down structure:
155 wxNotebook->wxPanel->wxSizer->wxControl
157 That means, in the wxNotebook associated with this class, controls that
158 needs to be taken screenshots are placed on different panels(for grouping)
159 and laid out by wxSizers.
161 @section tag_tutorial Tutorial
163 In the construction, you should associate a wxNotebook with this class, in
164 that wxNotebook, controls that needs to be captured are placed on different
165 panels(for grouping).
167 When you register controls, you should do it in order: Register the
168 controls on the first panel(using RegisterControl()), and then register a
169 page turn(using RegisterPageTurn()), so this class can turn a page of the
170 wxNotebook to present the second page. And then you register the controls
171 on the second panel, then a page turn, and so on.
173 When you are done, simply call CaptureAll(), then screenshots of all
174 controls will be automatically generated.
176 @section tag_autoadjust Make Use of Auto Adjustments
178 First take a look at the document of RegisterControl(), enum AdjustFlags
179 and GlobalAdjustFlags.
181 And then, ScreenshotFrame::OnCaptureAllControls() is a good example of
182 making use of auto adjustment. Taking a look at it will get you started.
184 @section tag_developer_note Notes for Developers
186 @subsection tag_cnc CaptureAll() and Capture()
188 The implementation of Auto Adjustments is in CaptureAll() and Capture(),
189 the code is short, quite readable and well commented, please read the codes
190 before any modification.
192 If you need the class to do something sepcial for you, consider introducing
193 a new flag and implement it in them. For an operation performed on multiple
194 controls, implemente its logic in CaptureAll(), otherwise in the private
197 @subsection tag_yield_issue wxYield Issues
199 Not quite a good habit, but this class made a lot of use of wxYield() /
200 wxYieldIfNeeded(). They are used to ensure the update of GUI (e.g. the
201 page turn of wxNotebook) is done before any further screenshot-taking, or
202 to do the timing(in Delay()). Without their use, there would be subtle
205 I've read documents about wxYield() and understand the down side of it
206 before using it. But I didn't find a better approach to do those things,
207 and I used them carefully. So please DO NOT remove any of these wxYield()s
208 unless you're sure that it won't cause problems on all of MS Windows
209 XP/Vista, Linux(Ubuntu/Fedora), Mac OS Tiger/Leopard. And please help me
210 to find a better approach, thank you :)
212 class AutoCaptureMechanism
219 The wxNotebook associated with this class. Please see
220 @ref tag_gui_assumption and @ref tag_tutorial.
222 It's one of or a combination of GlobalAdjustFlags, to disable /
223 enable some auto-adjustment for all controls.
225 It's the margin around every control in the sreenshots.
227 AutoCaptureMechanism(wxNotebook
*notebook
,
228 int flag
= AJ_NormalAll
,
231 ~AutoCaptureMechanism() { }
234 Register a control and perform specifid auto adjustments.
237 The pointer to the control to be taken a screenshot.
239 If you find out that the screenshot for this control was generated
240 under an incorrect file name, specify @a name. e.g. for wxButton,
241 "wxButton" or "button" are both OK.
243 If you end up with an a smaller or deflected screenshot, use
246 If you want to caputure the "drop-down" state of a "drop-down"
247 control, use AJ_Dropdown.
249 If you want to present different states of a control in one
250 screenshot, use AJ_Union and AJ_UnionEnd.
252 Please read the document of enum AdjustFlags, and notice that this
253 flag could be enabled / disabled by global flag GlobalAdjustFlags.
255 void RegisterControl(wxWindow
* ctrl
,
256 wxString name
= wxT(""),
257 int flag
= AJ_Normal
)
259 m_controlList
.push_back(Control(ctrl
, name
, flag
));
263 Register a control and perform specifid auto adjustments.
265 This calls RegisterControl(wxWindow* ctrl, wxString name, int flag)
266 with an empty name. This is useful when you only want to auto-adjust
267 something other than name adjustment.
269 void RegisterControl(wxWindow
* ctrl
, int flag
)
271 RegisterControl(ctrl
, wxT(""), flag
);
275 Register a page turn.
277 When you finished registering the controls on a panel, remember to
278 call it to turn the wxNotebook to the next panel.
280 void RegisterPageTurn()
282 m_controlList
.push_back(Control(0, wxT(""), AJ_TurnPage
));
286 Capture all registered controls of the associated wxNotebook.
294 Take a screenshot for the given region.
297 Bitmap to save the screenshot to.
299 Given rectangular region.
301 Only useful for Mac, for fixing a delay bug. It seems that it
302 didn't fix the bug, so it might be removed soon.
304 static bool Capture(wxBitmap
* bitmap
, wxRect rect
, int delay
= 0);
307 Take a screenshot for the given region.
309 @see Capture(wxBitmap*,wxRect,int)
311 static bool Capture(wxBitmap
* bitmap
,
312 int x
, int y
, int width
, int height
,
316 Save the screenshot as the name of @a fileName in the default
319 @a fileName should be without ".png".
321 static void Save(wxBitmap
* screenshot
, const wxString
& fileName
);
324 Set the default directory where the screenshots will be generated.
326 static void SetDefaultDirectory(const wxString
& dir
) { default_dir
= dir
; }
329 Get the default directory where the screenshots will be generated.
331 static wxString
GetDefaultDirectory() { return default_dir
; }
334 Get the absolute path of the default directory where the screenshots
337 static wxString
GetDefaultDirectoryAbsPath();
342 Internal Data Structures
344 They might go public in future to provide reuse of ControlList.
350 Control(wxWindow
* _ctrl
, wxString _name
, int _flag
)
351 : ctrl(_ctrl
), name(_name
), flag(_flag
) {}
358 typedef std::vector
<Control
> ControlList
;
363 They are only used to clearify the logic of some public functions and
364 it's nonsense to call them elsewhere.
368 Capture and auto adjust the control. Used by CaptureAll().
370 bool Capture(wxBitmap
* bitmap
, Control
& ctrl
);
373 Get the correct rectangular region that the control occupies. Used by
374 Capture(Control & ctrl).
376 If AJ_RegionAdjust is specified, it will use the "label trick" to
377 perform region auto adjustment.
379 The "label trick" is to reattach the control to a wxFlexGridSizer
380 m_grid, surround the control with labels and get the control's region
381 by label's positions. Just like this:
383 +---------+-----------+---------+
385 +---------+-----------+---------+
386 | label | ctrl | label |
387 +---------+-----------+---------+
389 +---------+-----------+---------+
391 So, there will be a side effect: the control is moved to a new
392 position. So after taking the screenshot, Capture(Control & ctrl)
393 should call PutBack(wxWindow * ctrl) to put it back.
395 If AJ_RegionAdjust isn't specified, it will simply call
396 wxWindow::GetScreenRect().
398 wxRect
GetRect(wxWindow
* ctrl
, int flag
);
401 Put the control back after the label trick used in GetRect(). Used by
402 Capture(Control & ctrl).
404 void PutBack(wxWindow
* ctrl
);
407 Union two screenshots in the vertical direction, and leave a gap
408 between the screenshots. Used by CaptureAll().
410 The gap is 20 pixels by default. Currently it isn't configurable.
412 static bool Union(wxBitmap
* top
, wxBitmap
* bottom
, wxBitmap
* result
);
415 Delay a few seconds without blocking GUI.
417 static void Delay(int seconds
);
422 ControlList m_controlList
;
424 wxNotebook
* m_notebook
;
430 wxFlexGridSizer
* m_grid
;
432 static wxString default_dir
;
435 #endif // _AUTOCAPTURE_H_