Fix a crash in wxExecute() in wxMSW too.

[wxWidgets.git] / utils / screenshotgen / src / autocapture.h

diff --git a/utils/screenshotgen/src/autocapture.h b/utils/screenshotgen/src/autocapture.h
index bb922a445c10d40cc99d09d87199e0149dac521d..36477c3a54c1642e972ca6c0c1b96a0ac46c37bd 100644 (file)
--- a/utils/screenshotgen/src/autocapture.h
+++ b/utils/screenshotgen/src/autocapture.h
@@ -21,11 +21,11 @@ class wxWindow;
 class wxNotebook;
 
 /**
 class wxNotebook;
 
 /**

-    GlobalAdjustFlags works with AutoCaptureMechanism's constructor, to disbale/enable
-    some auto-adjustment for all controls.
+    GlobalAdjustFlags works with AutoCaptureMechanism's constructor, to
+    configure auto-adjustments of all controls.

 
 

-    They are used to make AutoCaptureMechanism more configurable and provide a fallback
-    to detect the bugs that the adjustments intended to avoid.
+    They are used to make AutoCaptureMechanism more configurable and provide a
+    fallback to detect the bugs that the adjustments intended to avoid.

 
     @see AdjustFlags
 */
 
     @see AdjustFlags
 */


@@ -45,8 +45,8 @@ enum GlobalAdjustFlags
     /**
         Enable region adjustment for all controls.
 
     /**
         Enable region adjustment for all controls.
 

-        If AJ_DisableRegionAdjust and AJ_AlwaysRegionAdjust are both specified, current
-        implemetation will ignore AJ_DisableRegionAdjust.
+        If AJ_DisableRegionAdjust and AJ_AlwaysRegionAdjust are both specified,
+        current implemetation will ignore AJ_DisableRegionAdjust.

     */
     AJ_AlwaysRegionAdjust =  1 << 1,
 
     */
     AJ_AlwaysRegionAdjust =  1 << 1,
 


@@ -56,15 +56,16 @@ enum GlobalAdjustFlags
     AJ_DisableNameAdjust = 1 << 2,
 
     /**
     AJ_DisableNameAdjust = 1 << 2,
 
     /**

-        For all the "Drop-down Controls", e.g. wxChoice, do not prompt the user about whether
-        to capture their drop-down state, and always capture only its non-drop-down state.
+        For all the "Drop-down Controls", e.g. wxChoice, do not prompt the user
+        about whether to capture their drop-down state, and always capture only
+        its non-drop-down state.

     */
     AJ_DisableDropdown = 1 << 3
 };
 
 /**
     */
     AJ_DisableDropdown = 1 << 3
 };
 
 /**

-    AdjustFlags works with AutoCaptureMechanism::RegisterControl() to specify how to
-    adjust the screenshot of the current control.
+    AdjustFlags works with AutoCaptureMechanism::RegisterControl() to specify
+    how to adjust the screenshot of the current control.

 
     They are used to avoid bugs, look better or interact with user etc.
 
 
     They are used to avoid bugs, look better or interact with user etc.
 


@@ -80,40 +81,45 @@ enum AdjustFlags
     /**
         Perform region adjustment for this control.
 
     /**
         Perform region adjustment for this control.
 

-        On some platforms and for some controls, wxWindow::GetScreenRect() will return
-        a smaller or deflected region. In these cases, the screenshots we get are incomplete.
-        It's recommended for everyone to fix the controls' code, yet this flag provides a
-        workaround to get a guaranteed correct region without using wxWindow::GetScreenRect().
+        On some platforms and for some controls, wxWindow::GetScreenRect() will
+        return a smaller or deflected region. In these cases, the screenshots
+        we get are incomplete. It's recommended for everyone to fix the
+        controls' code, yet this flag provides a workaround to get a guaranteed
+        correct region without using wxWindow::GetScreenRect().

 
 

-        This workaround("label trick") is inspired by (or say stolen from) Auria's work.
+        This workaround ("label trick") is inspired by (or say stolen from)
+        Auria's work.

     */
     AJ_RegionAdjust = 1 << 0,
 
     /**
     */
     AJ_RegionAdjust = 1 << 0,
 
     /**

-        This flag provides a way to capture the drop-down state of "Drop-down Controls",
-        e.g. wxChoice.
+        This flag provides a way to capture the drop-down state of "Drop-down
+        Controls", e.g. wxChoice.

 
 

-        For all the "Drop-down Controls", prompt the user about whether to capture their
-        drop-down state, if the user chooses YES, he should drop down the control in about
-        3 seconds and wait util it's captured in that state.
+        For all the "Drop-down Controls", prompt the user about whether to
+        capture their drop-down state, if the user chooses YES, he should drop
+        down the control in about 3 seconds and wait util it's captured in that
+        state.

     */
     AJ_Dropdown = 1 << 1,
 
     /**
     */
     AJ_Dropdown = 1 << 1,
 
     /**

-        This flag is used internally by RegisterPageTurn(). Don't use it directly unless you
-        know what you are doing.
+        This flag is used internally by RegisterPageTurn(). Don't use it
+        directly unless you know what you are doing.

     */
     AJ_TurnPage = 1 << 2,
 
     /**
     */
     AJ_TurnPage = 1 << 2,
 
     /**

-        This flag provides a functionality to union screenshots of different modes/states of
-        a control into one image. e.g. the single-line/multi-line modes of a wxTextCtrl.
+        This flag provides a functionality to union screenshots of different
+        modes/states of a control into one image. e.g. the single-line /
+        multi-line modes of a wxTextCtrl.

 
 

-        For a series of controls to be unioned, you should specify AJ_Union for the first,
-        and AJ_UnionEnd for the last. For the controls between them, you can either specify
-        AJ_Union or not.
+        For a series of controls to be unioned, you should specify AJ_Union for
+        the first, and AJ_UnionEnd for the last. For the controls between them,
+        you can either specify AJ_Union or not.

 
 

-        The filename of the generated screenshot is the name of the first control in the series.
+        The filename of the generated screenshot is the name of the first
+        control in the series.

     */
     AJ_Union = 1 << 3,
 
     */
     AJ_Union = 1 << 3,
 


@@ -126,76 +132,83 @@ enum AdjustFlags
 /**
     @class AutoCaptureMechanism
 
 /**
     @class AutoCaptureMechanism
 

-    AutoCaptureMechanism provides an easy-to-use and adjustable facility to take the screenshots
-    for all controls fully automaticly and correctly. It also provides an advanced feature to
-    union screenshots of different states/modes of a control.
+    AutoCaptureMechanism provides an easy-to-use and adjustable facility to
+    take the screenshots for all controls fully automaticly and correctly. It
+    also provides an advanced feature to union screenshots of different
+    states/modes of a control.

 
     @section tag_filename_convention Screenshot File Name Convention
 
 
     @section tag_filename_convention Screenshot File Name Convention
 

-    All screenshots are generated as PNG files. For a control named wxName, its screenshot file
-    name would be "name.png", e.g. "button.png" for wxButton. This is the protocol with the
-    doxygen document of wxWidgets.
+    All screenshots are generated as PNG files. For a control named wxName, its
+    screenshot file name would be "name.png", e.g. "button.png" for wxButton.
+    This is the protocol with the doxygen document of wxWidgets.

 
 

-    By default, screenshots are generated under the subdirectory "screenshots" of current working
-    directory. During updating or adding new screenshots, first make sure screenshots are generated
-    correctly, and then copy them to the following subdirectory of docs/doxygen/images:
-
-    "wxmsw" for MS Windows, "wxgtk" for Linux and "wxmac" for Mac OS.
+    By default, screenshots are generated under the subdirectory "screenshots"
+    of current working directory. During updating or adding new screenshots,
+    first make sure screenshots are generated correctly, and then copy them to
+    the "docs/doxygen/images" folder directly.

 
     @section tag_gui_assumption The Assumption of GUI
 
 
     @section tag_gui_assumption The Assumption of GUI
 

-    Unfortunately, this class have an assumption about the structure of GUI:
-    It must have the follwoing top-down structure:
+    Unfortunately, this class have an assumption about the structure of GUI: It
+    must have the follwoing top-down structure:

 
     wxNotebook->wxPanel->wxSizer->wxControl
 
 
     wxNotebook->wxPanel->wxSizer->wxControl
 

-    That means, in the wxNotebook associated with this class, controls that needs to be
-    taken screenshots are placed on different panels(for grouping) and layed out by wxSizers.
+    That means, in the wxNotebook associated with this class, controls that
+    needs to be taken screenshots are placed on different panels(for grouping)
+    and layed out by wxSizers.

 
     @section tag_tutorial Tutorial
 
 
     @section tag_tutorial Tutorial
 

-    In the contruction, you should associate a wxNotebook with this class, in that wxNotebook,
-    controls that needs to be captured are placed on different panels(for grouping).
+    In the contruction, you should associate a wxNotebook with this class, in
+    that wxNotebook, controls that needs to be captured are placed on different
+    panels(for grouping).

 
 

-    When you register controls, you should do it in order: Register the controls on the first
-    panel(using RegisterControl()), and then register a page turn(using RegisterPageTurn()),
-    so this class can turn a page of the wxNotebook to present the second page. And then
-    you register the controls on the second panel, then a page turn, and so on.
+    When you register controls, you should do it in order: Register the
+    controls on the first panel(using RegisterControl()), and then register a
+    page turn(using RegisterPageTurn()), so this class can turn a page of the
+    wxNotebook to present the second page. And then you register the controls
+    on the second panel, then a page turn, and so on.

 
 

-    When you are done, simply call CaptureAll(), then screenshots of all controls will be
-    automaticly generated.
+    When you are done, simply call CaptureAll(), then screenshots of all
+    controls will be automaticly generated.

 
     @section tag_autoadjust Make Use of Auto Adjustments
 
 
     @section tag_autoadjust Make Use of Auto Adjustments
 

-    First take a look at the document of RegisterControl(), enum AdjustFlags and
-    GlobalAdjustFlags.
+    First take a look at the document of RegisterControl(), enum AdjustFlags
+    and GlobalAdjustFlags.

 
 

-    And then, ScreenshotFrame::OnCaptureAllControls() is a good example of making use of
-    auto adjustment. Taking a look at it will get you started.
+    And then, ScreenshotFrame::OnCaptureAllControls() is a good example of
+    making use of auto adjustment. Taking a look at it will get you started.

 
     @section tag_developer_note Notes for Developers
 
     @subsection tag_cnc CaptureAll() and Capture()
 
 
     @section tag_developer_note Notes for Developers
 
     @subsection tag_cnc CaptureAll() and Capture()
 

-    The implementation of Auto Adjustments is in CaptureAll() and Capture(), the code is
-    short, quite readable and well commented, please read the codes before any modification.
+    The implementation of Auto Adjustments is in CaptureAll() and Capture(),
+    the code is short, quite readable and well commented, please read the codes
+    before any modification.

 
 

-    If you need the class to do something sepcial for you, consider introducing a new flag
-    and implement it in them. For an operation performed on multiple controls, implemente
-    its logic in CaptureAll(), otherwise in the private member Capture().
+    If you need the class to do something sepcial for you, consider introducing
+    a new flag and implement it in them. For an operation performed on multiple
+    controls, implemente its logic in CaptureAll(), otherwise in the private
+    member Capture().

 
     @subsection tag_yield_issue wxYield Issues
 
 
     @subsection tag_yield_issue wxYield Issues
 

-    Not quite a good habit, but this class made a lot of use of wxYield()/wxYieldIfNeeded().
-    They are used to ensure the update of GUI(e.g. the page turn of wxNotebook) is done
-    before any further screenshot-taking, or to do the timing(in Delay()). Without their use,
-    there would be subtle bugs.
-
-    I've read documents about wxYield() and understand the down side of it before using it.
-    But I didn't find a better approach to do those things, and I used them carefully. So
-    please DO NOT remove any of these wxYield()s unless you're sure that it won't cause problems
-    on all of MS Windows XP/Vista, Linux(Ubuntu/Fedora), Mac OS Tiger/Leopard. And please
-    help me to find a better approach, thank you :)
+    Not quite a good habit, but this class made a lot of use of wxYield() /
+    wxYieldIfNeeded(). They are used to ensure the update of GUI (e.g. the
+    page turn of wxNotebook) is done before any further screenshot-taking, or
+    to do the timing(in Delay()). Without their use, there would be subtle
+    bugs.
+
+    I've read documents about wxYield() and understand the down side of it
+    before using it. But I didn't find a better approach to do those things,
+    and I used them carefully. So please DO NOT remove any of these wxYield()s
+    unless you're sure that it won't cause problems on all of MS Windows
+    XP/Vista, Linux(Ubuntu/Fedora), Mac OS Tiger/Leopard. And please help me
+    to find a better approach, thank you :)

 */
 class AutoCaptureMechanism
 {
 */
 class AutoCaptureMechanism
 {


@@ -204,15 +217,13 @@ public:
         Constructor.
 
         @param notebook
         Constructor.
 
         @param notebook

-        The wxNotebook associated with this class.Please see @ref tag_gui_assumption
-        and @ref tag_tutorial.
-
+            The wxNotebook associated with this class. Please see
+            @ref tag_gui_assumption and @ref tag_tutorial.

         @param flag
         @param flag

-        It's one of or a combination of GlobalAdjustFlags, to disbale/enable some auto-adjustment
-        for all controls.
-
+            It's one of or a combination of GlobalAdjustFlags, to disable /
+            enable some auto-adjustment for all controls.

         @param margin
         @param margin

-        It's the margin around every control in the sreenshots.
+            It's the margin around every control in the sreenshots.

     */
     AutoCaptureMechanism(wxNotebook *notebook,
                          int flag = AJ_NormalAll,
     */
     AutoCaptureMechanism(wxNotebook *notebook,
                          int flag = AJ_NormalAll,


@@ -224,25 +235,27 @@ public:
         Register a control and perform specifid auto adjustments.
 
         @param ctrl
         Register a control and perform specifid auto adjustments.
 
         @param ctrl

-        The pointer to the control to be taken a screenshot.
-
+            The pointer to the control to be taken a screenshot.

         @param name
         @param name

-        If you find out that the screenshot for this control was generated under an incorrect
-        file name, specify @a name. e.g. for wxButton, "wxButton" or "button" are both OK.
-
+            If you find out that the screenshot for this control was generated
+            under an incorrect file name, specify @a name. e.g. for wxButton,
+            "wxButton" or "button" are both OK.

         @param flag
         @param flag

+            If you end up with an a smaller or deflected screenshot, use
+            AJ_RegionAdjust.

 
 

-        If you end up with an a smaller or deflected screenshot, use AJ_RegionAdjust.
-
-        If you want to caputure the "drop-down" state of a "drop-down" control, use AJ_Dropdown.
+            If you want to caputure the "drop-down" state of a "drop-down"
+            control, use AJ_Dropdown.

 
 

-        If you want to present different states of a control in one screenshot, use AJ_Union
-        and AJ_UnionEnd.
+            If you want to present different states of a control in one
+            screenshot, use AJ_Union and AJ_UnionEnd.

 
 

-        Please read the document of enum AdjustFlags, and notice that this flag could be enabled/
-        disabled by global flag GlobalAdjustFlags.
+            Please read the document of enum AdjustFlags, and notice that this
+            flag could be enabled / disabled by global flag GlobalAdjustFlags.

     */
     */

-    void RegisterControl(wxWindow * ctrl, wxString name = wxT(""), int flag = AJ_Normal)
+    void RegisterControl(wxWindow* ctrl,
+                         wxString name = wxT(""),
+                         int flag = AJ_Normal)

     {
         m_controlList.push_back(Control(ctrl, name, flag));
     }
     {
         m_controlList.push_back(Control(ctrl, name, flag));
     }


@@ -250,11 +263,11 @@ public:
     /**
         Register a control and perform specifid auto adjustments.
 
     /**
         Register a control and perform specifid auto adjustments.
 

-        This is the same as RegisterControl(wxWindow * ctrl, wxString name, int flag),
-        But with it, you won't have to specify the name if you only want to auto-adjust something
-        other than name adjustment.
+        This calls RegisterControl(wxWindow* ctrl, wxString name, int flag)
+        with an empty name. This is useful when you only want to auto-adjust
+        something other than name adjustment.

     */
     */

-    void RegisterControl(wxWindow * ctrl, int flag)
+    void RegisterControl(wxWindow* ctrl, int flag)

     {
         RegisterControl(ctrl, wxT(""), flag);
     }
     {
         RegisterControl(ctrl, wxT(""), flag);
     }


@@ -262,8 +275,8 @@ public:
     /**
         Register a page turn.
 
     /**
         Register a page turn.
 

-        When you finished registering the controls on a panel, remember to call it to turn the
-        wxNotebook to the next panel.
+        When you finished registering the controls on a panel, remember to
+        call it to turn the wxNotebook to the next panel.

     */
     void RegisterPageTurn()
     {
     */
     void RegisterPageTurn()
     {


@@ -296,10 +309,13 @@ public:
 
         @see Capture(wxBitmap*,wxRect,int)
     */
 
         @see Capture(wxBitmap*,wxRect,int)
     */

-    static bool Capture(wxBitmap* bitmap, int x, int y, int width, int height, int delay = 0);
+    static bool Capture(wxBitmap* bitmap,
+                        int x, int y, int width, int height,
+                        int delay = 0);

 
     /**
 
     /**

-        Save the screenshot as the name of @a fileName in the default directory.
+        Save the screenshot as the name of @a fileName in the default
+        directory.

 
         @a fileName should be without ".png".
     */
 
         @a fileName should be without ".png".
     */


@@ -316,7 +332,8 @@ public:
     static wxString GetDefaultDirectory() { return default_dir; }
 
     /**
     static wxString GetDefaultDirectory() { return default_dir; }
 
     /**

-        Get the absolute path of the default directory where the screenshots will be generated.
+        Get the absolute path of the default directory where the screenshots
+        will be generated.

     */
     static wxString GetDefaultDirectoryAbsPath();
 
     */
     static wxString GetDefaultDirectoryAbsPath();
 


@@ -344,8 +361,8 @@ private:
     /*
         Internal Functions
 
     /*
         Internal Functions
 

-        They are only used to clearify the logic of some public functions and it's nonsense
-        to call them elsewhere.
+        They are only used to clearify the logic of some public functions and
+        it's nonsense to call them elsewhere.

     */
 
     /*
     */
 
     /*


@@ -357,12 +374,12 @@ private:
         Get the correct rectangular region that the control occupies. Used by
         Capture(Control & ctrl).
 
         Get the correct rectangular region that the control occupies. Used by
         Capture(Control & ctrl).
 

-        If AJ_RegionAdjust is specified, it will use the "label trick" to perform
-        region auto adjustment.
+        If AJ_RegionAdjust is specified, it will use the "label trick" to
+        perform region auto adjustment.

 
 

-        The "label trick" is to reattach the control to a wxFlexGridSizer m_grid,
-        surround the control with labels and get the control's region by label's positions.
-        Just like this:
+        The "label trick" is to reattach the control to a wxFlexGridSizer
+        m_grid, surround the control with labels and get the control's region
+        by label's positions. Just like this:

 
         +---------+-----------+---------+
         |    0    |   label   |    1    |
 
         +---------+-----------+---------+
         |    0    |   label   |    1    |


@@ -372,10 +389,12 @@ private:
         |    2    |   label   |    3    |
         +---------+-----------+---------+
 
         |    2    |   label   |    3    |
         +---------+-----------+---------+
 

-        So, there will be a side effect: the control is moved to a new position. So after taking the
-        screenshot, Capture(Control & ctrl) should call PutBack(wxWindow * ctrl) to put it back.
+        So, there will be a side effect: the control is moved to a new
+        position. So after taking the screenshot, Capture(Control & ctrl)
+        should call PutBack(wxWindow * ctrl) to put it back.

 
 

-        If AJ_RegionAdjust isn't specified, it will simply call wxWindow::GetScreenRect().
+        If AJ_RegionAdjust isn't specified, it will simply call
+        wxWindow::GetScreenRect().

     */
     wxRect GetRect(wxWindow* ctrl, int flag);
 
     */
     wxRect GetRect(wxWindow* ctrl, int flag);
 


@@ -386,8 +405,8 @@ private:
     void PutBack(wxWindow * ctrl);
 
     /*
     void PutBack(wxWindow * ctrl);
 
     /*

-        Union two screenshots in the vertical direction, and leave a gap between the
-        screenshots. Used by CaptureAll().
+        Union two screenshots in the vertical direction, and leave a gap
+        between the screenshots. Used by CaptureAll().

 
         The gap is 20 pixels by default. Currently it isn't configurable.
     */
 
         The gap is 20 pixels by default. Currently it isn't configurable.
     */


@@ -415,5 +434,3 @@ private:
 };
 
 #endif // _AUTOCAPTURE_H_
 };
 
 #endif // _AUTOCAPTURE_H_

-
-