revised b* headers; moved wxPenList and wxBrushList to the correct places; partially...

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52578 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/interface/bitmap.h b/interface/bitmap.h
index 01d43706b56d7b146472b9c240c24f7a4e760617..6c37d33628940124c361e443390122c419ff50ca 100644 (file)
--- a/interface/bitmap.h
+++ b/interface/bitmap.h
@@ -6,6 +6,12 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+
+/**
+    In wxBitmap and wxBitmapHandler context this value means: "use the screen depth".
+*/
+#define wxBITMAP_SCREEN_DEPTH       (-1)
+

 /**
     @class wxBitmapHandler
     @wxheader{bitmap.h}
 /**
     @class wxBitmapHandler
     @wxheader{bitmap.h}


@@ -50,35 +56,33 @@ public:
         @param height
             The height of the bitmap in pixels.
         @param depth
         @param height
             The height of the bitmap in pixels.
         @param depth

-            The depth of the bitmap in pixels. If this is -1, the screen depth is used.
+            The depth of the bitmap in pixels.
+            If this is ::wxBITMAP_SCREEN_DEPTH, the screen depth is used.

         @param data
             Data whose type depends on the value of type.
         @param type
             A bitmap type identifier - see ::wxBitmapType for a list
             of possible values.
 
         @param data
             Data whose type depends on the value of type.
         @param type
             A bitmap type identifier - see ::wxBitmapType for a list
             of possible values.
 

-@todo why type is an int and not a wxBitmapType?
-

         @returns @true if the call succeeded, @false otherwise (the default).
     */
         @returns @true if the call succeeded, @false otherwise (the default).
     */

-    virtual bool Create(wxBitmap* bitmap, const void* data, int type,
-                        int width, int height, int depth = -1);
+    virtual bool Create(wxBitmap* bitmap, const void* data, wxBitmapType type,
+                        int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);

 
     /**
         Gets the file extension associated with this handler.
     */
 
     /**
         Gets the file extension associated with this handler.
     */

-    const wxString GetExtension() const;
+    const wxString& GetExtension() const;

 
     /**
         Gets the name of this handler.
     */
 
     /**
         Gets the name of this handler.
     */

-    const wxString GetName() const;
+    const wxString& GetName() const;

 
     /**
         Gets the bitmap type associated with this handler.
 
     /**
         Gets the bitmap type associated with this handler.

-@todo why type is an int and not a wxBitmapType?

     */
     */

-    long GetType() const;
+    wxBitmapType GetType() const;

 
     /**
         Loads a bitmap from a file or resource, putting the resulting data into
 
     /**
         Loads a bitmap from a file or resource, putting the resulting data into


@@ -90,15 +94,13 @@ public:
             Either a filename or a Windows resource name.
             The meaning of name is determined by the type parameter.
         @param type
             Either a filename or a Windows resource name.
             The meaning of name is determined by the type parameter.
         @param type

-            See wxBitmap::wxBitmap for values this can take.
+            See ::wxBitmapType for values this can take.

 
         @returns @true if the operation succeeded, @false otherwise.
 
 
         @returns @true if the operation succeeded, @false otherwise.
 

-@todo why type is an int and not a wxBitmapType?
-

         @see wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile()
     */
         @see wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile()
     */

-    bool LoadFile(wxBitmap* bitmap, const wxString& name, long type);
+    bool LoadFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type);

 
     /**
         Saves a bitmap in the named file.
 
     /**
         Saves a bitmap in the named file.


@@ -108,17 +110,15 @@ public:
         @param name
             A filename. The meaning of name is determined by the type parameter.
         @param type
         @param name
             A filename. The meaning of name is determined by the type parameter.
         @param type

-            See wxBitmap::wxBitmap for values this can take.
+            See ::wxBitmapType for values this can take.

         @param palette
             An optional palette used for saving the bitmap.
 
         @returns @true if the operation succeeded, @false otherwise.
 
         @param palette
             An optional palette used for saving the bitmap.
 
         @returns @true if the operation succeeded, @false otherwise.
 

-@todo why type is an int and not a wxBitmapType?
-

         @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
     */
         @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
     */

-    bool SaveFile(wxBitmap* bitmap, const wxString& name, int type,
+    bool SaveFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type,

                   wxPalette* palette = NULL);
 
     /**
                   wxPalette* palette = NULL);
 
     /**


@@ -140,12 +140,10 @@ public:
     /**
         Sets the handler type.
 
     /**
         Sets the handler type.
 

-@todo why type is an int and not a wxBitmapType?
-

         @param type
             Handler type.
     */
         @param type
             Handler type.
     */

-    void SetType(long type);
+    void SetType(wxBitmapType type);

 };
 
 
 };
 
 


@@ -157,8 +155,8 @@ public:
     either monochrome or colour or colour with alpha channel support.
 
     @note
     either monochrome or colour or colour with alpha channel support.
 
     @note

-    Many wxBitmap functions take a @e type parameter, which is a value of
-    the ::wxBitmapType enumeration.
+    Many wxBitmap functions take a @e type parameter, which is a value of the
+    ::wxBitmapType enumeration.

     The validity of those values depends however on the platform where your program
     is running and from the wxWidgets configuration.
     If all possible wxWidgets settings are used, the Windows platform supports BMP file,
     The validity of those values depends however on the platform where your program
     is running and from the wxWidgets configuration.
     If all possible wxWidgets settings are used, the Windows platform supports BMP file,


@@ -199,7 +197,8 @@ public:
     */
     wxBitmap(const wxBitmap& bitmap);
 
     */
     wxBitmap(const wxBitmap& bitmap);
 

-    /**
+
+    /*

         Creates a bitmap from the given @a data which is interpreted in
         platform-dependent manner.
 
         Creates a bitmap from the given @a data which is interpreted in
         platform-dependent manner.
 


@@ -216,11 +215,13 @@ public:
         @param depth
             Specifies the depth of the bitmap.
             If this is omitted, the display depth of the screen is used.
         @param depth
             Specifies the depth of the bitmap.
             If this is omitted, the display depth of the screen is used.

+    wxBitmap(const void* data, int type, int width, int height, int depth = -1);

 
 

-@todo why type is an int and not a wxBitmapType?

 
 

+        NOTE: this ctor is not implemented by all port, is somewhat useless
+              without further description of the "data" supported formats and
+              uses 'int type' instead of wxBitmapType, so don't document it.

     */
     */

-    wxBitmap(const void* data, int type, int width, int height, int depth = -1);

 
     /**
         Creates a bitmap from the given array @a bits.
 
     /**
         Creates a bitmap from the given array @a bits.


@@ -229,8 +230,9 @@ public:
 
         For other bit depths, the behaviour is platform dependent: under Windows,
         the data is passed without any changes to the underlying CreateBitmap() API.
 
         For other bit depths, the behaviour is platform dependent: under Windows,
         the data is passed without any changes to the underlying CreateBitmap() API.

-        Under other platforms, only monochrome bitmaps may be created using this constructor
-        and wxImage should be used for creating colour bitmaps from static data.
+        Under other platforms, only monochrome bitmaps may be created using this
+        constructor and wxImage should be used for creating colour bitmaps from
+        static data.

 
         @param bits
             Specifies an array of pixel values.
 
         @param bits
             Specifies an array of pixel values.


@@ -240,18 +242,19 @@ public:
             Specifies the height of the bitmap.
         @param depth
             Specifies the depth of the bitmap.
             Specifies the height of the bitmap.
         @param depth
             Specifies the depth of the bitmap.

-            If this is omitted, the display depth of the screen is used.
+            If this is omitted, then a value of 1 (monochrome bitmap) is used.

     */
     wxBitmap(const char bits[], int width, int height, int depth = 1);
 
     /**
     */
     wxBitmap(const char bits[], int width, int height, int depth = 1);
 
     /**

-        Creates a new bitmap. A depth of -1 indicates the depth of the current
-        screen or visual. Some platforms only support 1 for monochrome and -1 for
+        Creates a new bitmap. A depth of ::wxBITMAP_SCREEN_DEPTH indicates the
+        depth of the current screen or visual.
+        Some platforms only support 1 for monochrome and ::wxBITMAP_SCREEN_DEPTH for

         the current colour setting.
 
         A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.
     */
         the current colour setting.
 
         A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.
     */

-    wxBitmap(int width, int height, int depth = -1);
+    wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);

 
     /**
         Creates a bitmap from XPM data.
 
     /**
         Creates a bitmap from XPM data.


@@ -270,15 +273,16 @@ public:
 
         @see LoadFile()
     */
 
         @see LoadFile()
     */

-    wxBitmap(const wxString& name, long type);
+    wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_XPM);

 
     /**
 
     /**

-        Creates bitmap object from the image. This has to be done to actually
-        display an image as you cannot draw an image directly on a window.
+        Creates this bitmap object from the given image.
+        This has to be done to actually display an image as you cannot draw an
+        image directly on a window.

 
         The resulting bitmap will use the provided colour depth (or that of the
 
         The resulting bitmap will use the provided colour depth (or that of the

-        current system if depth is -1) which entails that a colour reduction has
-        to take place.
+        current system if depth is ::wxBITMAP_SCREEN_DEPTH) which entails that a
+        colour reduction may take place.

 
         When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube
         created on program start-up to look up colors. This ensures a very fast conversion,
 
         When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube
         created on program start-up to look up colors. This ensures a very fast conversion,


@@ -295,8 +299,7 @@ public:
             Specifies the depth of the bitmap.
             If this is omitted, the display depth of the screen is used.
     */
             Specifies the depth of the bitmap.
             If this is omitted, the display depth of the screen is used.
     */

-    wxBitmap(const wxImage& img, int depth = -1);
-
+    wxBitmap(const wxImage& img, int depth = wxBITMAP_SCREEN_DEPTH);

 
     /**
         Destructor.
 
     /**
         Destructor.


@@ -339,16 +342,15 @@ public:
     */
     bool CopyFromIcon(const wxIcon& icon);
 
     */
     bool CopyFromIcon(const wxIcon& icon);
 

-

     /**
         Creates a fresh bitmap.
         If the final argument is omitted, the display depth of the screen is used.
 
         This overload works on all platforms.
     */
     /**
         Creates a fresh bitmap.
         If the final argument is omitted, the display depth of the screen is used.
 
         This overload works on all platforms.
     */

-    virtual bool Create(int width, int height, int depth = -1);
+    virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);

 
 

-    /**
+    /*

         Creates a bitmap from the given data, which can be of arbitrary type.
 
         @param data
         Creates a bitmap from the given data, which can be of arbitrary type.
 
         @param data


@@ -366,11 +368,13 @@ public:
         @returns @true if the call succeeded, @false otherwise.
 
         This overload depends on the @a type of data.
         @returns @true if the call succeeded, @false otherwise.
 
         This overload depends on the @a type of data.

-    */

 
     virtual bool Create(const void* data, int type, int width,
                         int height, int depth = -1);
 
 
     virtual bool Create(const void* data, int type, int width,
                         int height, int depth = -1);
 

+        NOTE: leave this undoc for the same reason of the relative ctor.
+    */
+

     /**
         Finds the handler with the given @a name.
 
     /**
         Finds the handler with the given @a name.
 


@@ -405,8 +409,8 @@ public:
     static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
 
     /**
     static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
 
     /**

-        Gets the colour depth of the bitmap. A value of 1 indicates a
-        monochrome bitmap.
+        Gets the colour depth of the bitmap.
+        A value of 1 indicates a monochrome bitmap.

     */
     int GetDepth() const;
 
     */
     int GetDepth() const;
 


@@ -531,7 +535,7 @@ public:
         @see LoadFile()
     */
     bool SaveFile(const wxString& name, wxBitmapType type,
         @see LoadFile()
     */
     bool SaveFile(const wxString& name, wxBitmapType type,

-                  wxPalette* palette = NULL);
+                  const wxPalette* palette = NULL);

 
     /**
         Sets the depth member (does not affect the bitmap data).
 
     /**
         Sets the depth member (does not affect the bitmap data).

diff --git a/interface/bmpbuttn.h b/interface/bmpbuttn.h
index 02503fedfa9bc99275dc13738853460c728a482c..58b5e32e1cae3aab52efb5542ee8ff0dfd8a78b9 100644 (file)
--- a/interface/bmpbuttn.h
+++ b/interface/bmpbuttn.h
@@ -11,29 +11,53 @@
     @wxheader{bmpbuttn.h}
 
     A bitmap button is a control that contains a bitmap.
     @wxheader{bmpbuttn.h}
 
     A bitmap button is a control that contains a bitmap.

-    It may be placed on a @ref overview_wxdialog "dialog box" or panel(), or indeed
-    almost any other window.
+    It may be placed on a wxDialog or a wxPanel, or indeed almost any other window.
+
+    @remarks
+    A bitmap button can be supplied with a single bitmap, and wxWidgets will draw
+    all button states using this bitmap. If the application needs more control,
+    additional bitmaps for the selected state, unpressed focused state, and greyed-out
+    state may be supplied.
+
+    @section wxbitmapbutton_states Button states
+    This class supports bitmaps for several different states:
+
+    @li @b normal: this is the bitmap shown in the default state, it must be always
+        valid while all the other bitmaps are optional and don't have to be set.
+    @li @b disabled: bitmap shown when the button is disabled.
+    @li @b selected: bitmap shown when the button is pushed (e.g. while the user
+        keeps the mouse button pressed on it)
+    @li @b focus: bitmap shown when the button has keyboard focus but is not pressed.
+    @li @b hover: bitmap shown when the mouse is over the button (but it is not pressed).
+        Notice that if hover bitmap is not specified but the current platform UI uses
+        hover images for the buttons (such as Windows XP or GTK+), then the focus bitmap
+        is used for hover state as well. This makes it possible to set focus bitmap only
+        to get reasonably good behaviour on all platforms.

 
     @beginStyleTable
     @style{wxBU_AUTODRAW}:
            If this is specified, the button will be drawn automatically using
            the label bitmap only, providing a 3D-look border. If this style is
            not specified, the button will be drawn without borders and using
 
     @beginStyleTable
     @style{wxBU_AUTODRAW}:
            If this is specified, the button will be drawn automatically using
            the label bitmap only, providing a 3D-look border. If this style is
            not specified, the button will be drawn without borders and using

-           all provided bitmaps. WIN32 only.
+           all provided bitmaps. Has effect only under MS Windows.

     @style{wxBU_LEFT}:
     @style{wxBU_LEFT}:

-           Left-justifies the bitmap label. WIN32 only.
+           Left-justifies the bitmap label. Has effect only under MS Windows.

     @style{wxBU_TOP}:
     @style{wxBU_TOP}:

-           Aligns the bitmap label to the top of the button. WIN32 only.
+           Aligns the bitmap label to the top of the button.
+           Has effect only under MS Windows.

     @style{wxBU_RIGHT}:
     @style{wxBU_RIGHT}:

-           Right-justifies the bitmap label. WIN32 only.
+           Right-justifies the bitmap label. Has effect only under MS Windows.

     @style{wxBU_BOTTOM}:
     @style{wxBU_BOTTOM}:

-           Aligns the bitmap label to the bottom of the button. WIN32 only.
+           Aligns the bitmap label to the bottom of the button.
+           Has effect only under MS Windows.

     @endStyleTable
 
     @endStyleTable
 

+    Note that the wxBU_EXACTFIT style supported by wxButton is not used by this
+    class as bitmap buttons don't have any minimal standard size by default.
+

     @beginEventTable
     @event{EVT_BUTTON(id, func)}:
     @beginEventTable
     @event{EVT_BUTTON(id, func)}:

-           Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is
-           clicked.
+           Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.

     @endEventTable
 
     @library{wxcore}
     @endEventTable
 
     @library{wxcore}


@@ -45,10 +69,14 @@
 class wxBitmapButton : public wxButton
 {
 public:
 class wxBitmapButton : public wxButton
 {
 public:

-    //@{
+    /**
+        Default ctor.
+    */
+    wxBitmapButton();
+

     /**
         Constructor, creating and showing a button.
     /**
         Constructor, creating and showing a button.

-        
+

         @param parent
             Parent window. Must not be @NULL.
         @param id
         @param parent
             Parent window. Must not be @NULL.
         @param id


@@ -58,8 +86,7 @@ public:
         @param pos
             Button position.
         @param size
         @param pos
             Button position.
         @param size

-            Button size. If wxDefaultSize is specified then the button is
-        sized
+            Button size. If wxDefaultSize is specified then the button is sized

             appropriately for the bitmap.
         @param style
             Window style. See wxBitmapButton.
             appropriately for the bitmap.
         @param style
             Window style. See wxBitmapButton.


@@ -67,17 +94,14 @@ public:
             Window validator.
         @param name
             Window name.
             Window validator.
         @param name
             Window name.

-        
-        @remarks The bitmap parameter is normally the only bitmap you need to
-                 provide, and wxWidgets will draw the button correctly
-                 in its different states. If you want more control, call
-                 any of the functions SetBitmapSelected(),
-                 SetBitmapFocus(),
-                 SetBitmapDisabled().
-        
+
+        @remarks The bitmap parameter is normally the only bitmap you need to provide,
+                 and wxWidgets will draw the button correctly in its different states.
+                 If you want more control, call any of the functions SetBitmapSelected(),
+                 SetBitmapFocus(), SetBitmapDisabled().
+

         @see Create(), wxValidator
     */
         @see Create(), wxValidator
     */

-    wxBitmapButton();

     wxBitmapButton(wxWindow* parent, wxWindowID id,
                    const wxBitmap& bitmap,
                    const wxPoint& pos = wxDefaultPosition,
     wxBitmapButton(wxWindow* parent, wxWindowID id,
                    const wxBitmap& bitmap,
                    const wxPoint& pos = wxDefaultPosition,


@@ -85,7 +109,6 @@ public:
                    long style = wxBU_AUTODRAW,
                    const wxValidator& validator = wxDefaultValidator,
                    const wxString& name = "button");
                    long style = wxBU_AUTODRAW,
                    const wxValidator& validator = wxDefaultValidator,
                    const wxString& name = "button");

-    //@}

 
     /**
         Destructor, destroying the button.
 
     /**
         Destructor, destroying the button.


@@ -93,8 +116,8 @@ public:
     ~wxBitmapButton();
 
     /**
     ~wxBitmapButton();
 
     /**

-        Button creation function for two-step creation. For more details, see
-        wxBitmapButton().
+        Button creation function for two-step creation.
+        For more details, see wxBitmapButton().

     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxBitmap& bitmap,
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxBitmap& bitmap,


@@ -106,65 +129,65 @@ public:
 
     //@{
     /**
 
     //@{
     /**

-        Returns the bitmap for the disabled state, may be invalid.
-        
+        Returns the bitmap for the disabled state, which may be invalid.
+

         @returns A reference to the disabled state bitmap.
         @returns A reference to the disabled state bitmap.

-        
+

         @see SetBitmapDisabled()
     */
         @see SetBitmapDisabled()
     */

-    const wxBitmap GetBitmapDisabled();
-    const wxBitmap&  GetBitmapDisabled();
+    const wxBitmap& GetBitmapDisabled() const;
+    wxBitmap& GetBitmapDisabled();

     //@}
 
     //@{
     /**
     //@}
 
     //@{
     /**

-        Returns the bitmap for the focused state, may be invalid.
-        
+        Returns the bitmap for the focused state, which may be invalid.
+

         @returns A reference to the focused state bitmap.
         @returns A reference to the focused state bitmap.

-        
+

         @see SetBitmapFocus()
     */
         @see SetBitmapFocus()
     */

-    const wxBitmap GetBitmapFocus();
-    const wxBitmap&  GetBitmapFocus();
+    const wxBitmap& GetBitmapFocus() const;
+    wxBitmap&  GetBitmapFocus();

     //@}
 
     //@{
     /**
     //@}
 
     //@{
     /**

-        Returns the bitmap used when the mouse is over the button, may be invalid.
-        
+        Returns the bitmap used when the mouse is over the button, which may be invalid.
+

         @see SetBitmapHover()
     */
         @see SetBitmapHover()
     */

-    const wxBitmap GetBitmapHover();
-    const wxBitmap&  GetBitmapHover();
+    const wxBitmap& GetBitmapHover();
+    wxBitmap&  GetBitmapHover();

     //@}
 
     //@{
     /**
         Returns the label bitmap (the one passed to the constructor), always valid.
     //@}
 
     //@{
     /**
         Returns the label bitmap (the one passed to the constructor), always valid.

-        
+

         @returns A reference to the button's label bitmap.
         @returns A reference to the button's label bitmap.

-        
+

         @see SetBitmapLabel()
     */
         @see SetBitmapLabel()
     */

-    const wxBitmap GetBitmapLabel();
-    const wxBitmap&  GetBitmapLabel();
+    const wxBitmap& GetBitmapLabel();
+    wxBitmap&  GetBitmapLabel();

     //@}
 
     /**
         Returns the bitmap for the selected state.
     //@}
 
     /**
         Returns the bitmap for the selected state.

-        
+

         @returns A reference to the selected state bitmap.
         @returns A reference to the selected state bitmap.

-        
+

         @see SetBitmapSelected()
     */
         @see SetBitmapSelected()
     */

-    wxBitmap GetBitmapSelected() const;
+    wxBitmap& GetBitmapSelected() const;

 
     /**
         Sets the bitmap for the disabled button appearance.
 
     /**
         Sets the bitmap for the disabled button appearance.

-        
+

         @param bitmap
             The bitmap to set.
         @param bitmap
             The bitmap to set.

-        
+

         @see GetBitmapDisabled(), SetBitmapLabel(),
              SetBitmapSelected(), SetBitmapFocus()
     */
         @see GetBitmapDisabled(), SetBitmapLabel(),
              SetBitmapSelected(), SetBitmapFocus()
     */


@@ -172,10 +195,10 @@ public:
 
     /**
         Sets the bitmap for the button appearance when it has the keyboard focus.
 
     /**
         Sets the bitmap for the button appearance when it has the keyboard focus.

-        
+

         @param bitmap
             The bitmap to set.
         @param bitmap
             The bitmap to set.

-        
+

         @see GetBitmapFocus(), SetBitmapLabel(),
              SetBitmapSelected(), SetBitmapDisabled()
     */
         @see GetBitmapFocus(), SetBitmapLabel(),
              SetBitmapSelected(), SetBitmapDisabled()
     */


@@ -183,30 +206,31 @@ public:
 
     /**
         Sets the bitmap to be shown when the mouse is over the button.
 
     /**
         Sets the bitmap to be shown when the mouse is over the button.

-        
-        @wxsince{2.7.0} and the hover bitmap is
-        currently only supported in wxMSW.
-        
+
+        @wxsince{2.7.0}
+
+        The hover bitmap is currently only supported in wxMSW.
+

         @see GetBitmapHover()
     */
     void SetBitmapHover(const wxBitmap& bitmap);
 
     /**
         Sets the bitmap label for the button.
         @see GetBitmapHover()
     */
     void SetBitmapHover(const wxBitmap& bitmap);
 
     /**
         Sets the bitmap label for the button.

-        
+

         @param bitmap
             The bitmap label to set.
         @param bitmap
             The bitmap label to set.

-        
+

         @remarks This is the bitmap used for the unselected state, and for all
                  other states if no other bitmaps are provided.
         @remarks This is the bitmap used for the unselected state, and for all
                  other states if no other bitmaps are provided.

-        
+

         @see GetBitmapLabel()
     */
     void SetBitmapLabel(const wxBitmap& bitmap);
 
     /**
         Sets the bitmap for the selected (depressed) button appearance.
         @see GetBitmapLabel()
     */
     void SetBitmapLabel(const wxBitmap& bitmap);
 
     /**
         Sets the bitmap for the selected (depressed) button appearance.

-        
+

         @param bitmap
             The bitmap to set.
     */
         @param bitmap
             The bitmap to set.
     */

diff --git a/interface/bmpcbox.h b/interface/bmpcbox.h
index 86aeb320654567b104bb00cb5d095308209fe243..0ac05f1ba41d10611c61fb377185c15863c260bd 100644 (file)
--- a/interface/bmpcbox.h
+++ b/interface/bmpcbox.h
@@ -14,6 +14,13 @@
     It currently only allows using bitmaps of one size, and resizes itself
     so that a bitmap can be shown next to the text field.
 
     It currently only allows using bitmaps of one size, and resizes itself
     so that a bitmap can be shown next to the text field.
 

+    @remarks
+    While wxBitmapComboBox contains the wxComboBox API, but it might not actually
+    be derived from that class. In fact, if the platform does not have a native
+    implementation, wxBitmapComboBox will inherit from wxOwnerDrawnComboBox.
+    You can determine if the implementation is generic by checking whether
+    @c wxGENERIC_BITMAPCOMBOBOX is defined.
+

     @beginStyleTable
     @style{wxCB_READONLY}:
            Creates a combobox without a text editor. On some platforms the
     @beginStyleTable
     @style{wxCB_READONLY}:
            Creates a combobox without a text editor. On some platforms the


@@ -23,17 +30,18 @@
     @style{wxTE_PROCESS_ENTER}:
            The control will generate the event wxEVT_COMMAND_TEXT_ENTER
            (otherwise pressing Enter key is either processed internally by the
     @style{wxTE_PROCESS_ENTER}:
            The control will generate the event wxEVT_COMMAND_TEXT_ENTER
            (otherwise pressing Enter key is either processed internally by the

-           control or used for navigation between dialog controls). Windows
-           only.
+           control or used for navigation between dialog controls).
+           Windows only.

     @endStyleTable
 
     @endStyleTable
 

+    @todo create wxCB_PROCESS_ENTER rather than reusing wxTE_PROCESS_ENTER!
+

     @beginEventTable
     @event{EVT_COMBOBOX(id, func)}:
            Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
            the list is selected.
     @event{EVT_TEXT(id, func)}:
     @beginEventTable
     @event{EVT_COMBOBOX(id, func)}:
            Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
            the list is selected.
     @event{EVT_TEXT(id, func)}:

-           Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text
-           changes.
+           Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text changes.

     @event{EVT_TEXT_ENTER(id, func)}:
            Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
            the combobox.
     @event{EVT_TEXT_ENTER(id, func)}:
            Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
            the combobox.


@@ -48,10 +56,15 @@
 class wxBitmapComboBox : public wxComboBox
 {
 public:
 class wxBitmapComboBox : public wxComboBox
 {
 public:

+    /**
+        Default ctor.
+    */
+    wxBitmapComboBox();
+

     //@{
     /**
         Constructor, creating and showing a combobox.
     //@{
     /**
         Constructor, creating and showing a combobox.

-        
+

         @param parent
             Parent window. Must not be @NULL.
         @param id
         @param parent
             Parent window. Must not be @NULL.
         @param id


@@ -61,8 +74,7 @@ public:
         @param pos
             Window position.
         @param size
         @param pos
             Window position.
         @param size

-            Window size. If wxDefaultSize is specified then the window is
-        sized
+            Window size. If wxDefaultSize is specified then the window is sized

             appropriately.
         @param n
             Number of strings with which to initialise the control.
             appropriately.
         @param n
             Number of strings with which to initialise the control.


@@ -74,10 +86,9 @@ public:
             Window validator.
         @param name
             Window name.
             Window validator.
         @param name
             Window name.

-        
+

         @see Create(), wxValidator
     */
         @see Create(), wxValidator
     */

-    wxBitmapComboBox();

     wxBitmapComboBox(wxWindow* parent, wxWindowID id,
                      const wxString& value = "",
                      const wxPoint& pos = wxDefaultPosition,
     wxBitmapComboBox(wxWindow* parent, wxWindowID id,
                      const wxString& value = "",
                      const wxPoint& pos = wxDefaultPosition,


@@ -102,13 +113,17 @@ public:
     */
     ~wxBitmapComboBox();
 
     */
     ~wxBitmapComboBox();
 

-    //@{

     /**
     /**

-        Adds the item to the end of the combo box, associating the given, typed or
-        untyped, client data pointer with the item.
+        Adds the item to the end of the combo box.

     */
     int Append(const wxString& item,
                const wxBitmap& bitmap = wxNullBitmap);
     */
     int Append(const wxString& item,
                const wxBitmap& bitmap = wxNullBitmap);

+
+    //@{
+    /**
+        Adds the item to the end of the combo box, associating the given, typed or
+        untyped, client data pointer @a clientData with the item.
+    */

     int Append(const wxString& item, const wxBitmap& bitmap,
                void* clientData);
     int Append(const wxString& item, const wxBitmap& bitmap,
     int Append(const wxString& item, const wxBitmap& bitmap,
                void* clientData);
     int Append(const wxString& item, const wxBitmap& bitmap,


@@ -149,14 +164,20 @@ public:
     */
     wxBitmap GetItemBitmap(unsigned int n) const;
 
     */
     wxBitmap GetItemBitmap(unsigned int n) const;
 

+    /**
+        Inserts the item into the list before @a pos.
+        Not valid for @c wxCB_SORT style, use Append() instead.
+    */
+    int Insert(const wxString& item, const wxBitmap& bitmap,
+               unsigned int pos);
+

     //@{
     /**
         Inserts the item into the list before pos, associating the given, typed or
         untyped, client data pointer with the item.
     //@{
     /**
         Inserts the item into the list before pos, associating the given, typed or
         untyped, client data pointer with the item.

-        Not valid for @c wxCB_SORT style, use Append instead.
+        Not valid for @c wxCB_SORT style, use Append() instead.

     */
     */

-    int Insert(const wxString& item, const wxBitmap& bitmap,
-               unsigned int pos);
+

     int Insert(const wxString& item, const wxBitmap& bitmap,
                unsigned int pos,
                void* clientData);
     int Insert(const wxString& item, const wxBitmap& bitmap,
                unsigned int pos,
                void* clientData);

diff --git a/interface/brush.h b/interface/brush.h
index d644b1e19b5bdfc1136be43b48797c356ae12b87..3b4e63d63d4424fae3234863608fcd0e5bb9e357 100644 (file)
--- a/interface/brush.h
+++ b/interface/brush.h
@@ -6,234 +6,168 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    The possible brush styles.
+*/
+enum wxBrushStyle
+{
+    wxBRUSHSTYLE_SOLID = wxSOLID,
+        /**< Solid. */
+
+    wxBRUSHSTYLE_TRANSPARENT = wxTRANSPARENT,
+        /**< Transparent (no fill). */
+
+    wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE = wxSTIPPLE_MASK_OPAQUE,
+        /**< @todo WHAT's THIS?? */
+
+    wxBRUSHSTYLE_STIPPLE_MASK = wxSTIPPLE_MASK,
+        /**< @todo WHAT's THIS?? */
+
+    wxBRUSHSTYLE_STIPPLE = wxSTIPPLE,
+        /**< Uses a bitmap as a stipple. */
+
+    wxBRUSHSTYLE_BDIAGONAL_HATCH = wxBDIAGONAL_HATCH,
+        /**< Backward diagonal hatch. */
+
+    wxBRUSHSTYLE_CROSSDIAG_HATCH = wxCROSSDIAG_HATCH,
+        /**< Cross-diagonal hatch. */
+
+    wxBRUSHSTYLE_FDIAGONAL_HATCH = wxFDIAGONAL_HATCH,
+        /**< Forward diagonal hatch. */
+
+    wxBRUSHSTYLE_CROSS_HATCH = wxCROSS_HATCH,
+        /**< Cross hatch. */
+
+    wxBRUSHSTYLE_HORIZONTAL_HATCH = wxHORIZONTAL_HATCH,
+        /**< Horizontal hatch. */
+
+    wxBRUSHSTYLE_VERTICAL_HATCH = wxVERTICAL_HATCH,
+        /**< Vertical hatch. */
+
+    wxBRUSHSTYLE_FIRST_HATCH = wxFIRST_HATCH,
+    wxBRUSHSTYLE_LAST_HATCH = wxLAST_HATCH,
+    wxBRUSHSTYLE_MAX
+};
+
+
+

 /**
     @class wxBrush
     @wxheader{brush.h}
 
     A brush is a drawing tool for filling in areas. It is used for painting
 /**
     @class wxBrush
     @wxheader{brush.h}
 
     A brush is a drawing tool for filling in areas. It is used for painting

-    the background of rectangles, ellipses, etc. It has a colour and a
-    style.
+    the background of rectangles, ellipses, etc. It has a colour and a style.
+
+    On a monochrome display, wxWidgets shows all brushes as white unless the
+    colour is really black.
+
+    Do not initialize objects on the stack before the program commences, since
+    other required structures may not have been set up yet. Instead, define
+    global pointers to objects and create them in wxApp::OnInit or when required.
+
+    An application may wish to create brushes with different characteristics
+    dynamically, and there is the consequent danger that a large number of
+    duplicate brushes will be created. Therefore an application may wish to
+    get a pointer to a brush by using the global list of brushes ::wxTheBrushList,
+    and calling the member function wxBrushList::FindOrCreateBrush().
+
+    This class uses reference counting and copy-on-write internally so that
+    assignments between two instances of this class are very cheap.
+    You can therefore use actual objects instead of pointers without efficiency problems.
+    If an instance of this class is changed it will create its own data internally
+    so that other instances, which previously shared the data using the reference
+    counting, are not affected.

 
     @library{wxcore}
     @category{gdi}
 
     @stdobjects
 
     @library{wxcore}
     @category{gdi}
 
     @stdobjects

-    ::Objects:, ::wxNullBrush, ::Pointers:, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH,
-    ::wxWHITE_BRUSH, ::wxBLACK_BRUSH, ::wxGREY_BRUSH, ::wxMEDIUM_GREY_BRUSH, ::wxLIGHT_GREY_BRUSH, ::wxTRANSPARENT_BRUSH, ::wxCYAN_BRUSH, ::wxRED_BRUSH,
+    ::wxNullBrush, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH, ::wxWHITE_BRUSH,
+    ::wxBLACK_BRUSH, ::wxGREY_BRUSH, ::wxMEDIUM_GREY_BRUSH, ::wxLIGHT_GREY_BRUSH,
+    ::wxTRANSPARENT_BRUSH, ::wxCYAN_BRUSH, ::wxRED_BRUSH

 
     @see wxBrushList, wxDC, wxDC::SetBrush
 */
 class wxBrush : public wxGDIObject
 {
 public:
 
     @see wxBrushList, wxDC, wxDC::SetBrush
 */
 class wxBrush : public wxGDIObject
 {
 public:

-    //@{

     /**
     /**

-        Copy constructor, uses @ref overview_trefcount "reference counting".
-        
+        Default constructor.
+        The brush will be uninitialised, and wxBrush:IsOk() will return @false.
+    */
+    wxBrush();
+
+    /**
+        Constructs a brush from a colour object and @a style.
+

         @param colour
             Colour object.
         @param colour
             Colour object.

+        @param style
+            One of the ::wxBrushStyle enumeration values.
+    */
+    wxBrush(const wxColour& colour, wxBrushStyle style = wxSOLID);
+
+    /**
+        Constructs a brush from a colour name and @a style.
+

         @param colourName
             Colour name. The name will be looked up in the colour database.
         @param style
         @param colourName
             Colour name. The name will be looked up in the colour database.
         @param style

-            One of:
-        
-        
-        
-        
-        
-        
-            wxTRANSPARENT
-        
-        
-        
-        
-            Transparent (no fill).
-        
-        
-        
-        
-        
-            wxSOLID
-        
-        
-        
-        
-            Solid.
-        
-        
-        
-        
-        
-            wxSTIPPLE
-        
-        
-        
-        
-            Uses a bitmap as a stipple.
-        
-        
-        
-        
-        
-            wxBDIAGONAL_HATCH
-        
-        
-        
-        
-            Backward diagonal hatch.
-        
-        
-        
-        
-        
-            wxCROSSDIAG_HATCH
-        
-        
-        
-        
-            Cross-diagonal hatch.
-        
-        
-        
-        
-        
-            wxFDIAGONAL_HATCH
-        
-        
-        
-        
-            Forward diagonal hatch.
-        
-        
-        
-        
-        
-            wxCROSS_HATCH
-        
-        
-        
-        
-            Cross hatch.
-        
-        
-        
-        
-        
-            wxHORIZONTAL_HATCH
-        
-        
-        
-        
-            Horizontal hatch.
-        
-        
-        
-        
-        
-            wxVERTICAL_HATCH
-        
-        
-        
-        
-            Vertical hatch.
-        @param brush
-            Pointer or reference to a brush to copy.
-        @param stippleBitmap
-            A bitmap to use for stippling.
-        
-        @remarks If a stipple brush is created, the brush style will be set to
-                 wxSTIPPLE.
-        
-        @see wxBrushList, wxColour, wxColourDatabase
+            One of the ::wxBrushStyle enumeration values.
+
+        @see wxColourDatabase
+    */
+    wxBrush(const wxString& colourName, wxBrushStyle style);
+
+    /**
+        Constructs a stippled brush using a bitmap.
+        The brush style will be set to wxBRUSHSTYLE_STIPPLE.

     */
     */

-    wxBrush();
-    wxBrush(const wxColour& colour, int style = wxSOLID);
-    wxBrush(const wxString& colourName, int style);

     wxBrush(const wxBitmap& stippleBitmap);
     wxBrush(const wxBitmap& stippleBitmap);

+
+    /**
+        Copy constructor, uses @ref overview_refcount "reference counting".
+    */

     wxBrush(const wxBrush& brush);
     wxBrush(const wxBrush& brush);

-    //@}

 
     /**
         Destructor.
 
     /**
         Destructor.

-        See @ref overview_refcountdestruct "reference-counted object destruction" for
-        more info.
-        
+
+        See @ref overview_refcount_destruct for more info.
+

         @remarks Although all remaining brushes are deleted when the application
         @remarks Although all remaining brushes are deleted when the application

-                 exits, the application should try to clean up all
-                 brushes itself. This is because wxWidgets cannot know
-                 if a pointer to the brush object is stored in an
-                 application data structure, and there is a risk of
-                 double deletion.
+                 exits, the application should try to clean up all brushes itself.
+                 This is because wxWidgets cannot know if a pointer to the brush
+                 object is stored in an application data structure, and there is
+                 a risk of double deletion.

     */
     ~wxBrush();
 
     /**
         Returns a reference to the brush colour.
     */
     ~wxBrush();
 
     /**
         Returns a reference to the brush colour.

-        
+

         @see SetColour()
     */
     wxColour GetColour() const;
 
     /**
         @see SetColour()
     */
     wxColour GetColour() const;
 
     /**

-        Gets a pointer to the stipple bitmap. If the brush does not have a wxSTIPPLE
-        style,
-        this bitmap may be non-@NULL but uninitialised (@ref wxBitmap::isok
-        wxBitmap:IsOk returns @false).
-        
+        Gets a pointer to the stipple bitmap. If the brush does not have a wxBRUSHSTYLE_STIPPLE
+        style, this bitmap may be non-@NULL but uninitialised (i.e. wxBitmap:IsOk() returns @false).
+

         @see SetStipple()
     */
     wxBitmap* GetStipple() const;
 
     /**
         @see SetStipple()
     */
     wxBitmap* GetStipple() const;
 
     /**

-        Returns the brush style, one of:
-        
-        @b wxTRANSPARENT
-        
-        Transparent (no fill).
-        
-        @b wxSOLID
-        
-        Solid.
-        
-        @b wxBDIAGONAL_HATCH
-        
-        Backward diagonal hatch.
-        
-        @b wxCROSSDIAG_HATCH
-        
-        Cross-diagonal hatch.
-        
-        @b wxFDIAGONAL_HATCH
-        
-        Forward diagonal hatch.
-        
-        @b wxCROSS_HATCH
-        
-        Cross hatch.
-        
-        @b wxHORIZONTAL_HATCH
-        
-        Horizontal hatch.
-        
-        @b wxVERTICAL_HATCH
-        
-        Vertical hatch.
-        
-        @b wxSTIPPLE
-        
-        Stippled using a bitmap.
-        
-        @b wxSTIPPLE_MASK_OPAQUE
-        
-        Stippled using a bitmap's mask.
-        
+        Returns the brush style, one of the ::wxBrushStyle values.
+

         @see SetStyle(), SetColour(), SetStipple()
     */
         @see SetStyle(), SetColour(), SetStipple()
     */

-    int GetStyle() const;
+    wxBrushStyle GetStyle() const;

 
     /**
         Returns @true if the style of the brush is any of hatched fills.
 
     /**
         Returns @true if the style of the brush is any of hatched fills.

-        
+

         @see GetStyle()
     */
     bool IsHatch() const;
         @see GetStyle()
     */
     bool IsHatch() const;


@@ -248,7 +182,7 @@ public:
     //@{
     /**
         Sets the brush colour using red, green and blue values.
     //@{
     /**
         Sets the brush colour using red, green and blue values.

-        
+

         @see GetColour()
     */
     void SetColour(wxColour& colour);
         @see GetColour()
     */
     void SetColour(wxColour& colour);


@@ -259,225 +193,137 @@ public:
 
     /**
         Sets the stipple bitmap.
 
     /**
         Sets the stipple bitmap.

-        
+

         @param bitmap
             The bitmap to use for stippling.
         @param bitmap
             The bitmap to use for stippling.

-        
-        @remarks The style will be set to wxSTIPPLE, unless the bitmap has a mask
-                 associated to it, in which case the style will be set
-                 to wxSTIPPLE_MASK_OPAQUE.
-        
+
+        @remarks The style will be set to wxBRUSHSTYLE_STIPPLE, unless the bitmap
+                 has a mask associated to it, in which case the style will be set
+                 to wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE.
+

         @see wxBitmap
     */
     void SetStipple(const wxBitmap& bitmap);
 
     /**
         Sets the brush style.
         @see wxBitmap
     */
     void SetStipple(const wxBitmap& bitmap);
 
     /**
         Sets the brush style.

-        
+

         @param style
         @param style

-            One of:
-        
-        
-        
-        
-        
-        
-            wxTRANSPARENT
-        
-        
-        
-        
-            Transparent (no fill).
-        
-        
-        
-        
-        
-            wxSOLID
-        
-        
-        
-        
-            Solid.
-        
-        
-        
-        
-        
-            wxBDIAGONAL_HATCH
-        
-        
-        
-        
-            Backward diagonal hatch.
-        
-        
-        
-        
-        
-            wxCROSSDIAG_HATCH
-        
-        
-        
-        
-            Cross-diagonal hatch.
-        
-        
-        
-        
-        
-            wxFDIAGONAL_HATCH
-        
-        
-        
-        
-            Forward diagonal hatch.
-        
-        
-        
-        
-        
-            wxCROSS_HATCH
-        
-        
-        
-        
-            Cross hatch.
-        
-        
-        
-        
-        
-            wxHORIZONTAL_HATCH
-        
-        
-        
-        
-            Horizontal hatch.
-        
-        
-        
-        
-        
-            wxVERTICAL_HATCH
-        
-        
-        
-        
-            Vertical hatch.
-        
-        
-        
-        
-        
-            wxSTIPPLE
-        
-        
-        
-        
-            Stippled using a bitmap.
-        
-        
-        
-        
-        
-            wxSTIPPLE_MASK_OPAQUE
-        
-        
-        
-        
-            Stippled using a bitmap's mask.
-        
+            One of the ::wxBrushStyle values.
+

         @see GetStyle()
     */
         @see GetStyle()
     */

-    void SetStyle(int style);
+    void SetStyle(wxBrushStyle style);

 
     /**
         Inequality operator.
 
     /**
         Inequality operator.

-        See @ref overview_refcountequality "reference-counted object comparison" for
-        more info.
+        See @ref overview_refcount_equality for more info.

     */
     bool operator !=(const wxBrush& brush);
 
     /**
     */
     bool operator !=(const wxBrush& brush);
 
     /**

-        Assignment operator, using @ref overview_trefcount "reference counting".
+        Assignment operator, using @ref overview_refcount "reference counting".

     */
     wxBrush operator =(const wxBrush& brush);
 
     /**
         Equality operator.
     */
     wxBrush operator =(const wxBrush& brush);
 
     /**
         Equality operator.

-        See @ref overview_refcountequality "reference-counted object comparison" for
-        more info.
+        See @ref overview_refcount_equality for more info.

     */
     bool operator ==(const wxBrush& brush);
 };
 
     */
     bool operator ==(const wxBrush& brush);
 };
 

-

 /**
 /**

-    FIXME
-*/
-wxBrush Objects:
-;
-
-/**
-    FIXME
+    An empty brush.

 */
 wxBrush wxNullBrush;
 
 /**
 */
 wxBrush wxNullBrush;
 
 /**

-    FIXME
+    Blue brush.

 */
 */

-wxBrush Pointers:
-;
+wxBrush* wxBLUE_BRUSH;

 
 /**
 
 /**

-    FIXME
+    Green brush.

 */
 */

-wxBrush wxBLUE_BRUSH;
+wxBrush* wxGREEN_BRUSH;

 
 /**
 
 /**

-    FIXME
+    White brush.

 */
 */

-wxBrush wxGREEN_BRUSH;
+wxBrush* wxWHITE_BRUSH;

 
 /**
 
 /**

-    FIXME
+    Black brush.

 */
 */

-wxBrush wxWHITE_BRUSH;
+wxBrush* wxBLACK_BRUSH;

 
 /**
 
 /**

-    FIXME
+    Grey brush.

 */
 */

-wxBrush wxBLACK_BRUSH;
+wxBrush* wxGREY_BRUSH;

 
 /**
 
 /**

-    FIXME
+    Medium grey brush.

 */
 */

-wxBrush wxGREY_BRUSH;
+wxBrush* wxMEDIUM_GREY_BRUSH;

 
 /**
 
 /**

-    FIXME
+    Light grey brush.

 */
 */

-wxBrush wxMEDIUM_GREY_BRUSH;
+wxBrush* wxLIGHT_GREY_BRUSH;

 
 /**
 
 /**

-    FIXME
+    Transparent brush.

 */
 */

-wxBrush wxLIGHT_GREY_BRUSH;
+wxBrush* wxTRANSPARENT_BRUSH;

 
 /**
 
 /**

-    FIXME
+    Cyan brush.

 */
 */

-wxBrush wxTRANSPARENT_BRUSH;
+wxBrush* wxCYAN_BRUSH;

 
 /**
 
 /**

-    FIXME
+    Red brush.

 */
 */

-wxBrush wxCYAN_BRUSH;
+wxBrush* wxRED_BRUSH;
+
+

 
 /**
 
 /**

-    FIXME
+    @class wxBrushList
+    @wxheader{gdicmn.h}
+
+    A brush list is a list containing all brushes which have been created.
+
+    @library{wxcore}
+    @category{gdi}
+
+    @see wxBrush

 */
 */

-wxBrush wxRED_BRUSH;
+class wxBrushList : public wxList
+{
+public:
+    /**
+        Constructor. The application should not construct its own brush list:
+        use the object pointer ::wxTheBrushList.
+    */
+    wxBrushList();

 
 

+    /**
+        Finds a brush with the specified attributes and returns it, else creates a new
+        brush, adds it to the brush list, and returns it.

 
 

+        @param colour
+            Colour object.
+        @param style
+            Brush style. See ::wxBrushStyle for a list of styles.
+    */
+    wxBrush* FindOrCreateBrush(const wxColour& colour,
+                               wxBrushStyle style = wxBRUSHSTYLE_SOLID);
+};
+
+/**
+    The global wxBrushList instance.
+*/
+wxBrushList* wxTheBrushList;

diff --git a/interface/buffer.h b/interface/buffer.h
index f46b11387db75a142d4c84a67518107d020e86d6..e8755cbd3d87712849eed27d61c7319f869c675d 100644 (file)
--- a/interface/buffer.h
+++ b/interface/buffer.h
@@ -11,31 +11,35 @@
     @wxheader{buffer.h}
 
     A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized
     @wxheader{buffer.h}
 
     A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized

-    blocks
-    of memory. wxMemoryBuffer guarantees deletion of the memory block when the
-    object
-    is destroyed.
+    blocks of memory. wxMemoryBuffer guarantees deletion of the memory block when
+    the object is destroyed.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{data}

 */
 class wxMemoryBuffer
 {
 public:
 */
 class wxMemoryBuffer
 {
 public:

-    //@{
+    /**
+        Copy constructor, refcounting is used for performance, but wxMemoryBuffer
+        is not a copy-on-write structure so changes made to one buffer effect all
+        copies made from it.
+
+        @see @ref overview_refcount
+    */
+    wxMemoryBuffer(const wxMemoryBuffer& src);
+

     /**
         Create a new buffer.
     /**
         Create a new buffer.

-        
+

         @param size
         @param size

-            size of new buffer.
+            size of the new buffer.

     */
     */

-    wxMemoryBuffer(const wxMemoryBuffer& src);

     wxMemoryBuffer(size_t size);
     wxMemoryBuffer(size_t size);

-    //@}

 
     /**
         Append a single byte to the buffer.
 
     /**
         Append a single byte to the buffer.

-        
+

         @param data
             New byte to append to the buffer.
     */
         @param data
             New byte to append to the buffer.
     */


@@ -44,9 +48,9 @@ public:
     /**
         Ensure that the buffer is big enough and return a pointer to the start
         of the empty space in the buffer. This pointer can be used to directly
     /**
         Ensure that the buffer is big enough and return a pointer to the start
         of the empty space in the buffer. This pointer can be used to directly

-        write data into the buffer, this new data will be appended to
-        the existing data.
-        
+        write data into the buffer, this new data will be appended to the
+        existing data.
+

         @param sizeNeeded
             Amount of extra space required in the buffer for
             the append operation
         @param sizeNeeded
             Amount of extra space required in the buffer for
             the append operation


@@ -81,9 +85,9 @@ public:
     void SetBufSize(size_t size);
 
     /**
     void SetBufSize(size_t size);
 
     /**

-        Sets the length of the data stored in the buffer.  Mainly useful for truncating
-        existing data.
-        
+        Sets the length of the data stored in the buffer.
+        Mainly useful for truncating existing data.
+

         @param size
             New length of the valid data in the buffer. This is
             distinct from the allocated size
         @param size
             New length of the valid data in the buffer. This is
             distinct from the allocated size


@@ -93,7 +97,7 @@ public:
     /**
         Update the length after completing a direct append, which
         you must have used GetAppendBuf() to initialise.
     /**
         Update the length after completing a direct append, which
         you must have used GetAppendBuf() to initialise.

-        
+

         @param sizeUsed
             This is the amount of new data that has been
             appended.
         @param sizeUsed
             This is the amount of new data that has been
             appended.


@@ -103,7 +107,7 @@ public:
     /**
         Update the buffer after completing a direct write, which
         you must have used GetWriteBuf() to initialise.
     /**
         Update the buffer after completing a direct write, which
         you must have used GetWriteBuf() to initialise.

-        
+

         @param sizeUsed
             The amount of data written in to buffer
             by the direct write
         @param sizeUsed
             The amount of data written in to buffer
             by the direct write

diff --git a/interface/busyinfo.h b/interface/busyinfo.h
index 4290bd6ce5270079536ba589af1654833a04779a..97eeee288eb6ca0d8016756bada6e1a22c65f789 100644 (file)
--- a/interface/busyinfo.h
+++ b/interface/busyinfo.h
@@ -17,27 +17,27 @@
     For example:
 
     @code
     For example:
 
     @code

-    wxBusyInfo wait("Please wait, working...");
+        wxBusyInfo wait("Please wait, working...");

 
 

-        for (int i = 0; i  100000; i++)
+        for (int i = 0; i < 100000; i++)

         {
             DoACalculation();
         }
     @endcode
 
         {
             DoACalculation();
         }
     @endcode
 

-    It works by creating a window in the constructor,
-    and deleting it in the destructor.
+    It works by creating a window in the constructor, and deleting it
+    in the destructor.

 
     You may also want to call wxTheApp-Yield() to refresh the window
     periodically (in case it had been obscured by other windows, for
     example) like this:
 
     @code
 
     You may also want to call wxTheApp-Yield() to refresh the window
     periodically (in case it had been obscured by other windows, for
     example) like this:
 
     @code

-    wxWindowDisabler disableAll;
+        wxWindowDisabler disableAll;

 
         wxBusyInfo wait("Please wait, working...");
 
 
         wxBusyInfo wait("Please wait, working...");
 

-        for (int i = 0; i  100000; i++)
+        for (int i = 0; i < 100000; i++)

         {
             DoACalculation();
 
         {
             DoACalculation();
 


@@ -47,21 +47,20 @@
     @endcode
 
     but take care to not cause undesirable reentrancies when doing it (see
     @endcode
 
     but take care to not cause undesirable reentrancies when doing it (see

-    wxApp::Yield for more details). The simplest way to do
-    it is to use wxWindowDisabler class as illustrated
-    in the above example.
+    wxApp::Yield for more details). The simplest way to do it is to use
+    wxWindowDisabler class as illustrated in the above example.

 
     @library{wxcore}
 
     @library{wxcore}

-    @category{FIXME}
+    @category{cmndlg}

 */
 class wxBusyInfo
 {
 public:
     /**
 */
 class wxBusyInfo
 {
 public:
     /**

-        Constructs a busy info window as child of @a parent and displays @e msg
-        in it.
-        @b NB: If @a parent is not @NULL you must ensure that it is not
-        closed while the busy info is shown.
+        Constructs a busy info window as child of @a parent and displays @e msg in it.
+
+        @note If @a parent is not @NULL you must ensure that it is not
+              closed while the busy info is shown.

     */
     wxBusyInfo(const wxString& msg, wxWindow* parent = NULL);
 
     */
     wxBusyInfo(const wxString& msg, wxWindow* parent = NULL);
 

diff --git a/interface/button.h b/interface/button.h
index 4bbb9134bac3313d3b525b0085a3e81eb5a49226..4a63ff78a3beb106a37e2f1d203faacab8a7d285 100644 (file)
--- a/interface/button.h
+++ b/interface/button.h
@@ -10,10 +10,11 @@
     @class wxButton
     @wxheader{button.h}
 
     @class wxButton
     @wxheader{button.h}
 

-    A button is a control that contains a text string,
-    and is one of the most common elements of a GUI. It may be placed on a
-    @ref overview_wxdialog "dialog box" or panel(), or indeed
-    almost any other window.
+    A button is a control that contains a text string, and is one of the most
+    common elements of a GUI.
+
+    It may be placed on a @ref wxDialog "dialog box" or on a @ref wxPanel panel,
+    or indeed on almost any other window.

 
     @beginStyleTable
     @style{wxBU_LEFT}:
 
     @beginStyleTable
     @style{wxBU_LEFT}:


@@ -33,8 +34,7 @@
 
     @beginEventTable
     @event{EVT_BUTTON(id, func)}:
 
     @beginEventTable
     @event{EVT_BUTTON(id, func)}:

-           Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is
-           clicked.
+           Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.

     @endEventTable
 
     @library{wxcore}
     @endEventTable
 
     @library{wxcore}


@@ -46,15 +46,20 @@
 class wxButton : public wxControl
 {
 public:
 class wxButton : public wxControl
 {
 public:

-    //@{
+    /**
+        Default ctor.
+    */
+    wxButton();
+

     /**
         Constructor, creating and showing a button.
     /**
         Constructor, creating and showing a button.

+

         The preferred way to create standard buttons is to use default value of
         The preferred way to create standard buttons is to use default value of

-        @e label. If no label is supplied and @a id is one of standard IDs from
-        @ref overview_stockitems "this list", standard label will be used. In addition
-        to
-        that, the button will be decorated with stock icons under GTK+ 2.
-        
+        @a label. If no label is supplied and @a id is one of standard IDs from
+        @ref page_stockitems "this list", a standard label will be used.
+
+        In addition to that, the button will be decorated with stock icons under GTK+ 2.
+

         @param parent
             Parent window. Must not be @NULL.
         @param id
         @param parent
             Parent window. Must not be @NULL.
         @param id


@@ -67,15 +72,14 @@ public:
             Button size. If the default size is specified then the button is sized
             appropriately for the text.
         @param style
             Button size. If the default size is specified then the button is sized
             appropriately for the text.
         @param style

-            Window style. See wxButton.
+            Window style. See wxButton class description.

         @param validator
             Window validator.
         @param name
             Window name.
         @param validator
             Window validator.
         @param name
             Window name.

-        
+

         @see Create(), wxValidator
     */
         @see Create(), wxValidator
     */

-    wxButton();

     wxButton(wxWindow* parent, wxWindowID id,
              const wxString& label = wxEmptyString,
              const wxPoint& pos = wxDefaultPosition,
     wxButton(wxWindow* parent, wxWindowID id,
              const wxString& label = wxEmptyString,
              const wxPoint& pos = wxDefaultPosition,


@@ -83,7 +87,6 @@ public:
              long style = 0,
              const wxValidator& validator = wxDefaultValidator,
              const wxString& name = "button");
              long style = 0,
              const wxValidator& validator = wxDefaultValidator,
              const wxString& name = "button");

-    //@}

 
     /**
         Destructor, destroying the button.
 
     /**
         Destructor, destroying the button.


@@ -91,8 +94,8 @@ public:
     ~wxButton();
 
     /**
     ~wxButton();
 
     /**

-        Button creation function for two-step creation. For more details, see
-        wxButton().
+        Button creation function for two-step creation.
+        For more details, see wxButton().

     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& label = wxEmptyString,
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& label = wxEmptyString,


@@ -111,29 +114,27 @@ public:
 
     /**
         Returns the string label for the button.
 
     /**
         Returns the string label for the button.

-        
-        @returns The button's label.
-        
+

         @see SetLabel()
     */
     wxString GetLabel() const;
 
     /**
         @see SetLabel()
     */
     wxString GetLabel() const;
 
     /**

-        This sets the button to be the default item for the panel or dialog
-        box.
-        
+        This sets the button to be the default item for the panel or dialog box.
+
+        As normal, pressing return causes the default button to be depressed when
+        the return key is pressed.
+
+        See also wxWindow::SetFocus() which sets the keyboard focus for windows
+        and text panel items, and wxTopLevelWindow::SetDefaultItem().
+

         @remarks Under Windows, only dialog box buttons respond to this function.
         @remarks Under Windows, only dialog box buttons respond to this function.

-                  As normal under Windows and Motif, pressing return
-                 causes the default button to be depressed when the
-                 return key is pressed. See also wxWindow::SetFocus
-                 which sets the keyboard focus for windows and text
-                 panel items, and wxTopLevelWindow::SetDefaultItem.

     */
     void SetDefault();
 
     /**
         Sets the string label for the button.
     */
     void SetDefault();
 
     /**
         Sets the string label for the button.

-        
+

         @param label
             The label to set.
     */
         @param label
             The label to set.
     */

diff --git a/interface/gdicmn.h b/interface/gdicmn.h
index 2160ab0be559ca526304fb015d830f6c9750dff7..ca488c38f737f42dba1f744b9cad2bd45c36a565 100644 (file)
--- a/interface/gdicmn.h
+++ b/interface/gdicmn.h
@@ -176,7 +176,7 @@ public:
         This method is the opposite from Inflate():
         Deflate(a, b) is equivalent to Inflate(-a, -b).
         Please refer to Inflate() for full description.
         This method is the opposite from Inflate():
         Deflate(a, b) is equivalent to Inflate(-a, -b).
         Please refer to Inflate() for full description.

-        
+

         @see Inflate()
     */
     void Deflate(wxCoord dx, wxCoord dy) const;
         @see Inflate()
     */
     void Deflate(wxCoord dx, wxCoord dy) const;


@@ -222,7 +222,7 @@ public:
 
     /**
         Gets the size.
 
     /**
         Gets the size.

-        
+

         @see SetSize()
     */
     wxSize GetSize() const;
         @see SetSize()
     */
     wxSize GetSize() const;


@@ -285,7 +285,7 @@ public:
                 independently. In the above example, the width is reduced by 20,
                 whereas the height is reduced by the full 30 (rather than also stopping
                 at 20, when the width reached zero).
                 independently. In the above example, the width is reduced by 20,
                 whereas the height is reduced by the full 30 (rather than also stopping
                 at 20, when the width reached zero).

-        
+

         @see Deflate()
     */
     void Inflate(wxCoord dx, wxCoord dy) const;
         @see Deflate()
     */
     void Inflate(wxCoord dx, wxCoord dy) const;


@@ -333,7 +333,7 @@ public:
 
     /**
         Sets the size.
 
     /**
         Sets the size.

-        
+

         @see GetSize()
     */
     void SetSize(const wxSize& s);
         @see GetSize()
     */
     void SetSize(const wxSize& s);


@@ -411,42 +411,6 @@ public:
 
 
 
 
 
 

-/**
-    @class wxBrushList
-    @wxheader{gdicmn.h}
-
-    A brush list is a list containing all brushes which have been created.
-
-    @library{wxcore}
-    @category{gdi}
-
-    @see wxBrush
-*/
-class wxBrushList : public wxList
-{
-public:
-    /**
-        Constructor. The application should not construct its own brush list:
-        use the object pointer @b wxTheBrushList.
-    */
-    wxBrushList();
-
-    /**
-        Finds a brush with the specified attributes and returns it, else creates a new
-        brush, adds it
-        to the brush list, and returns it.
-        
-        @param colour
-            Colour object.
-        @param style
-            Brush style. See wxBrush::SetStyle for a list of styles.
-    */
-    wxBrush* FindOrCreateBrush(const wxColour& colour,
-                               int style = wxSOLID);
-};
-
-
-

 /**
     @class wxPoint
     @wxheader{gdicmn.h}
 /**
     @class wxPoint
     @wxheader{gdicmn.h}


@@ -641,7 +605,7 @@ public:
              By @e size.x and @e size.y for the first overload
              By @a dx and @a dy for the second one
              By @a d and @a d for the third one
              By @e size.x and @e size.y for the first overload
              By @a dx and @a dy for the second one
              By @a d and @a d for the third one

-        
+

         @see IncBy()
     */
     void DecBy(const wxSize& size);
         @see IncBy()
     */
     void DecBy(const wxSize& size);


@@ -652,7 +616,7 @@ public:
     /**
         Decrements this object so that both of its dimensions are not greater than the
         corresponding dimensions of the @e size.
     /**
         Decrements this object so that both of its dimensions are not greater than the
         corresponding dimensions of the @e size.

-        
+

         @see IncTo()
     */
     void DecTo(const wxSize& size);
         @see IncTo()
     */
     void DecTo(const wxSize& size);


@@ -673,7 +637,7 @@ public:
              By @e size.x and @e size.y for the first overload
              By @a dx and @a dy for the second one
              By @a d and @a d for the third one
              By @e size.x and @e size.y for the first overload
              By @a dx and @a dy for the second one
              By @a d and @a d for the third one

-        
+

         @see DecBy()
     */
     void IncBy(const wxSize& size);
         @see DecBy()
     */
     void IncBy(const wxSize& size);


@@ -684,7 +648,7 @@ public:
     /**
         Increments this object so that both of its dimensions are not less than the
         corresponding dimensions of the @e size.
     /**
         Increments this object so that both of its dimensions are not less than the
         corresponding dimensions of the @e size.

-        
+

         @see DecTo()
     */
     void IncTo(const wxSize& size);
         @see DecTo()
     */
     void IncTo(const wxSize& size);


@@ -735,7 +699,7 @@ public:
         Combine this size object with another one replacing the default (i.e. equal
         to -1) components of this object with those of the other. It is typically
         used like this:
         Combine this size object with another one replacing the default (i.e. equal
         to -1) components of this object with those of the other. It is typically
         used like this:

-        
+

         @see IsFullySpecified()
     */
     void SetDefaults(const wxSize& sizeDefault);
         @see IsFullySpecified()
     */
     void SetDefaults(const wxSize& sizeDefault);


@@ -753,73 +717,6 @@ public:
 
 
 
 
 
 

-/**
-    @class wxPenList
-    @wxheader{gdicmn.h}
-
-    There is only one instance of this class: @b wxThePenList.  Use
-    this object to search for a previously created pen of the desired
-    type and create it if not already found. In some windowing systems,
-    the pen may be a scarce resource, so it can pay to reuse old
-    resources if possible. When an application finishes, all pens will
-    be deleted and their resources freed, eliminating the possibility of
-    'memory leaks'. However, it is best not to rely on this automatic
-    cleanup because it can lead to double deletion in some circumstances.
-
-    There are two mechanisms in recent versions of wxWidgets which make the
-    pen list less useful than it once was. Under Windows, scarce resources
-    are cleaned up internally if they are not being used. Also, a referencing
-    counting mechanism applied to all GDI objects means that some sharing
-    of underlying resources is possible. You don't have to keep track of pointers,
-    working out when it is safe delete a pen, because the referencing counting does
-    it for you. For example, you can set a pen in a device context, and then
-    immediately delete the pen you passed, because the pen is 'copied'.
-
-    So you may find it easier to ignore the pen list, and instead create
-    and copy pens as you see fit. If your Windows resource meter suggests
-    your application is using too many resources, you can resort to using
-    GDI lists to share objects explicitly.
-
-    The only compelling use for the pen list is for wxWidgets to keep
-    track of pens in order to clean them up on exit. It is also kept for
-    backward compatibility with earlier versions of wxWidgets.
-
-    @library{wxcore}
-    @category{gdi}
-
-    @see wxPen
-*/
-class wxPenList
-{
-public:
-    /**
-        Constructor. The application should not construct its own pen list:
-        use the object pointer @b wxThePenList.
-    */
-    wxPenList();
-
-    //@{
-    /**
-        Finds a pen with the specified attributes and returns it, else creates a new
-        pen, adds it
-        to the pen list, and returns it.
-        
-        @param colour
-            Colour object.
-        @param colourName
-            Colour name, which should be in the colour database.
-        @param width
-            Width of pen.
-        @param style
-            Pen style. See wxPen::wxPen for a list of styles.
-    */
-    wxPen* FindOrCreatePen(const wxColour& colour, int width,
-                           int style);
-    wxPen* FindOrCreatePen(const wxString& colourName, int width,
-                           int style);
-    //@}
-};
-

 
 
 // ============================================================================
 
 
 // ============================================================================

diff --git a/interface/pen.h b/interface/pen.h
index 9a9a2833ac41c1d4993b8fb4d286faeb37bf05b6..f39023aa0160aae09fd73fb887b6e1621e52aaf4 100644 (file)
--- a/interface/pen.h
+++ b/interface/pen.h
@@ -1,35 +1,165 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        pen.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        pen.h

-// Purpose:     interface of wxPen
+// Purpose:     interface of wxPen* classes

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    The possible styles for a wxPen.
+*/
+enum wxPenStyle
+{
+    wxPENSTYLE_SOLID,
+        /**< Solid style. */
+
+    wxPENSTYLE_DOT,
+        /**< Dotted style. */
+
+    wxPENSTYLE_LONG_DASH,
+        /**< Long dashed style. */
+
+    wxPENSTYLE_SHORT_DASH,
+        /**< Short dashed style. */
+
+    wxPENSTYLE_DOT_DASH,
+        /**< Dot and dash style. */
+
+    wxPENSTYLE_USER_DASH,
+        /**< Use the user dashes: see wxPen::SetDashes. */
+
+    wxPENSTYLE_TRANSPARENT,
+        /**< No pen is used. */
+
+    wxPENSTYLE_STIPPLE_MASK_OPAQUE,
+        /**< @todo WHAT's this? */
+
+    wxPENSTYLE_STIPPLE_MASK,
+        /**< @todo WHAT's this? */
+
+    wxPENSTYLE_STIPPLE,
+        /**< Use the stipple bitmap. */
+
+    wxPENSTYLE_BDIAGONAL_HATCH,
+        /**< Backward diagonal hatch. */
+
+    wxPENSTYLE_CROSSDIAG_HATCH,
+        /**< Cross-diagonal hatch. */
+
+    wxPENSTYLE_FDIAGONAL_HATCH,
+        /**< Forward diagonal hatch. */
+
+    wxPENSTYLE_CROSS_HATCH,
+        /**< Cross hatch. */
+
+    wxPENSTYLE_HORIZONTAL_HATCH,
+        /**< Horizontal hatch. */
+
+    wxPENSTYLE_VERTICAL_HATCH,
+        /**< Vertical hatch. */
+
+    wxPENSTYLE_FIRST_HATCH = wxPENSTYLE_BDIAGONAL_HATCH,
+    wxPENSTYLE_LAST_HATCH = wxPENSTYLE_VERTICAL_HATCH,
+    wxPENSTYLE_MAX
+};
+
+/**
+    The possible join values of a wxPen.
+
+    @todo use wxPENJOIN_ prefix
+*/
+enum wxPenJoin
+{
+    wxJOIN_INVALID = -1,
+
+    wxJOIN_BEVEL = 120,
+    wxJOIN_MITER,
+    wxJOIN_ROUND,
+};
+
+
+/**
+    The possible cap values of a wxPen.
+
+    @todo use wxPENCAP_ prefix
+*/
+enum wxPenCap
+{
+    wxCAP_INVALID = -1,
+
+    wxCAP_ROUND = 130,
+    wxCAP_PROJECTING,
+    wxCAP_BUTT
+};
+
+
+

 /**
     @class wxPen
     @wxheader{pen.h}
 
     A pen is a drawing tool for drawing outlines. It is used for drawing
 /**
     @class wxPen
     @wxheader{pen.h}
 
     A pen is a drawing tool for drawing outlines. It is used for drawing

-    lines and painting the outline of rectangles, ellipses, etc. It has a
-    colour, a width and a style.
+    lines and painting the outline of rectangles, ellipses, etc.
+    It has a colour, a width and a style.
+
+    On a monochrome display, wxWidgets shows all non-white pens as black.
+
+    Do not initialize objects on the stack before the program commences,
+    since other required structures may not have been set up yet.
+    Instead, define global pointers to objects and create them in wxApp::OnInit
+    or when required.
+
+    An application may wish to dynamically create pens with different characteristics,
+    and there is the consequent danger that a large number of duplicate pens will
+    be created. Therefore an application may wish to get a pointer to a pen by using
+    the global list of pens wxThePenList, and calling the member function
+    wxPenList::FindOrCreatePen().
+    See the entry for wxPenList.
+
+    This class uses reference counting and copy-on-write internally so that
+    assignments between two instances of this class are very cheap.
+    You can therefore use actual objects instead of pointers without efficiency problems.
+    If an instance of this class is changed it will create its own data internally
+    so that other instances, which previously shared the data using the reference
+    counting, are not affected.

 
     @library{wxcore}
     @category{gdi}
 
     @stdobjects
 
     @library{wxcore}
     @category{gdi}
 
     @stdobjects

-    ::Objects:, ::wxNullPen, ::Pointers:, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN,
-    ::wxBLACK_PEN, ::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN, ::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_PEN,
+    ::wxNullPen, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN, ::wxBLACK_PEN,
+    ::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN,
+    ::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_PEN

 
     @see wxPenList, wxDC, wxDC::SetPen
 */
 class wxPen : public wxGDIObject
 {
 public:
 
     @see wxPenList, wxDC, wxDC::SetPen
 */
 class wxPen : public wxGDIObject
 {
 public:

-    //@{

     /**
     /**

-        Copy constructor, uses @ref overview_trefcount "reference counting".
-        
+        Default constructor. The pen will be uninitialised, and wxPen:IsOk will return @false.
+    */
+    wxPen();
+
+    /**
+        Constructs a pen from a colour object, pen width and style.
+    */
+    wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxSOLID);
+
+    /**
+        Constructs a pen from a colour name, pen width and style.
+    */
+    wxPen(const wxString& colourName, int width, wxPenStyle style);
+
+    /**
+        Constructs a stippled pen from a stipple bitmap and a width.
+    */
+    wxPen(const wxBitmap& stipple, int width);
+
+    /**
+        Copy constructor, uses @ref overview_refcount "reference counting".
+

         @param colour
             A colour object.
         @param colourName
         @param colour
             A colour object.
         @param colourName


@@ -42,183 +172,22 @@ public:
         @param pen
             A pointer or reference to a pen to copy.
         @param style
         @param pen
             A pointer or reference to a pen to copy.
         @param style

-            The style may be one of the following:
-        
-        
-        
-        
-        
-        
-            wxSOLID
-        
-        
-        
-        
-            Solid style.
-        
-        
-        
-        
-        
-            wxTRANSPARENT
-        
-        
-        
-        
-            No pen is used.
-        
-        
-        
-        
-        
-            wxDOT
-        
-        
-        
-        
-            Dotted style.
-        
-        
-        
-        
-        
-            wxLONG_DASH
-        
-        
-        
-        
-            Long dashed style.
-        
-        
-        
-        
-        
-            wxSHORT_DASH
-        
-        
-        
-        
-            Short dashed style.
-        
-        
-        
-        
-        
-            wxDOT_DASH
-        
-        
-        
-        
-            Dot and dash style.
-        
-        
-        
-        
-        
-            wxSTIPPLE
-        
-        
-        
-        
-            Use the stipple bitmap.
-        
-        
-        
-        
-        
-            wxUSER_DASH
-        
-        
-        
-        
-            Use the user dashes: see SetDashes().
-        
-        
-        
-        
-        
-            wxBDIAGONAL_HATCH
-        
-        
-        
-        
-            Backward diagonal hatch.
-        
-        
-        
-        
-        
-            wxCROSSDIAG_HATCH
-        
-        
-        
-        
-            Cross-diagonal hatch.
-        
-        
-        
-        
-        
-            wxFDIAGONAL_HATCH
-        
-        
-        
-        
-            Forward diagonal hatch.
-        
-        
-        
-        
-        
-            wxCROSS_HATCH
-        
-        
-        
-        
-            Cross hatch.
-        
-        
-        
-        
-        
-            wxHORIZONTAL_HATCH
-        
-        
-        
-        
-            Horizontal hatch.
-        
-        
-        
-        
-        
-            wxVERTICAL_HATCH
-        
-        
-        
-        
-            Vertical hatch.
-        
+            The style may be one of the ::wxPenStyle values.
+

         @remarks Different versions of Windows and different versions of other
                  platforms support very different subsets of the styles
                  above - there is no similarity even between Windows95
                  and Windows98 - so handle with care.
         @remarks Different versions of Windows and different versions of other
                  platforms support very different subsets of the styles
                  above - there is no similarity even between Windows95
                  and Windows98 - so handle with care.

-        
+

         @see SetStyle(), SetColour(), SetWidth(), SetStipple()
     */
         @see SetStyle(), SetColour(), SetWidth(), SetStipple()
     */

-    wxPen();
-    wxPen(const wxColour& colour, int width = 1,
-          int style = wxSOLID);
-    wxPen(const wxString& colourName, int width, int style);
-    wxPen(const wxBitmap& stipple, int width);

     wxPen(const wxPen& pen);
     wxPen(const wxPen& pen);

-    //@}

 
     /**
         Destructor.
         See @ref overview_refcountdestruct "reference-counted object destruction" for
         more info.
 
     /**
         Destructor.
         See @ref overview_refcountdestruct "reference-counted object destruction" for
         more info.

-        
+

         @remarks Although all remaining pens are deleted when the application
                  exits, the application should try to clean up all pens
                  itself. This is because wxWidgets cannot know if a
         @remarks Although all remaining pens are deleted when the application
                  exits, the application should try to clean up all pens
                  itself. This is because wxWidgets cannot know if a


@@ -231,14 +200,14 @@ public:
         Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b
         wxCAP_PROJECTING and
         @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
         Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b
         wxCAP_PROJECTING and
         @b wxCAP_BUTT. The default is @b wxCAP_ROUND.

-        
+

         @see SetCap()
     */
         @see SetCap()
     */

-    int GetCap() const;
+    wxPenCap GetCap() const;

 
     /**
         Returns a reference to the pen colour.
 
     /**
         Returns a reference to the pen colour.

-        
+

         @see SetColour()
     */
     wxColour GetColour() const;
         @see SetColour()
     */
     wxColour GetColour() const;


@@ -248,7 +217,7 @@ public:
         @a dashes is a pointer to the internal array. Do not deallocate or store this
         pointer.
         The function returns the number of dashes associated with this pen.
         @a dashes is a pointer to the internal array. Do not deallocate or store this
         pointer.
         The function returns the number of dashes associated with this pen.

-        
+

         @see SetDashes()
     */
     int GetDashes(wxDash** dashes) const;
         @see SetDashes()
     */
     int GetDashes(wxDash** dashes) const;


@@ -257,28 +226,28 @@ public:
         Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b
         wxJOIN_ROUND and
         @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
         Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b
         wxJOIN_ROUND and
         @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.

-        
+

         @see SetJoin()
     */
         @see SetJoin()
     */

-    int GetJoin() const;
+    wxPenJoin GetJoin() const;

 
     /**
         Gets a pointer to the stipple bitmap.
 
     /**
         Gets a pointer to the stipple bitmap.

-        
+

         @see SetStipple()
     */
     wxBitmap* GetStipple() const;
 
     /**
         Returns the pen style.
         @see SetStipple()
     */
     wxBitmap* GetStipple() const;
 
     /**
         Returns the pen style.

-        
+

         @see wxPen(), SetStyle()
     */
         @see wxPen(), SetStyle()
     */

-    int GetStyle() const;
+    wxPenStyle GetStyle() const;

 
     /**
         Returns the pen width.
 
     /**
         Returns the pen width.

-        
+

         @see SetWidth()
     */
     int GetWidth() const;
         @see SetWidth()
     */
     int GetWidth() const;


@@ -292,15 +261,15 @@ public:
         Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING
         and
         @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
         Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING
         and
         @b wxCAP_BUTT. The default is @b wxCAP_ROUND.

-        
+

         @see GetCap()
     */
         @see GetCap()
     */

-    void SetCap(int capStyle);
+    void SetCap(wxPenCap capStyle);

 
     //@{
     /**
         The pen's colour is changed to the given colour.
 
     //@{
     /**
         The pen's colour is changed to the given colour.

-        
+

         @see GetColour()
     */
     void SetColour(wxColour& colour);
         @see GetColour()
     */
     void SetColour(wxColour& colour);


@@ -315,7 +284,7 @@ public:
         with the pen. The array is not deallocated by wxPen, but neither must it be
         deallocated by the calling application until the pen is deleted or this
         function is called with a @NULL array.
         with the pen. The array is not deallocated by wxPen, but neither must it be
         deallocated by the calling application until the pen is deleted or this
         function is called with a @NULL array.

-        
+

         @see GetDashes()
     */
     void SetDashes(int n, wxDash* dashes);
         @see GetDashes()
     */
     void SetDashes(int n, wxDash* dashes);


@@ -324,28 +293,28 @@ public:
         Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND
         and
         @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
         Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND
         and
         @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.

-        
+

         @see GetJoin()
     */
         @see GetJoin()
     */

-    void SetJoin(int join_style);
+    void SetJoin(wxPenJoin join_style);

 
     /**
         Sets the bitmap for stippling.
 
     /**
         Sets the bitmap for stippling.

-        
+

         @see GetStipple()
     */
     void SetStipple(wxBitmap* stipple);
 
     /**
         Set the pen style.
         @see GetStipple()
     */
     void SetStipple(wxBitmap* stipple);
 
     /**
         Set the pen style.

-        
+

         @see wxPen()
     */
         @see wxPen()
     */

-    void SetStyle(int style);
+    void SetStyle(wxPenStyle style);

 
     /**
         Sets the pen width.
 
     /**
         Sets the pen width.

-        
+

         @see GetWidth()
     */
     void SetWidth(int width);
         @see GetWidth()
     */
     void SetWidth(int width);


@@ -370,24 +339,11 @@ public:
     bool operator ==(const wxPen& pen);
 };
 
     bool operator ==(const wxPen& pen);
 };
 

-
-/**
-    FIXME
-*/
-wxPen Objects:
-;
-

 /**
     FIXME
 */
 wxPen wxNullPen;
 
 /**
     FIXME
 */
 wxPen wxNullPen;
 

-/**
-    FIXME
-*/
-wxPen Pointers:
-;
-

 /**
     FIXME
 */
 /**
     FIXME
 */


@@ -439,3 +395,71 @@ wxPen wxMEDIUM_GREY_PEN;
 wxPen wxLIGHT_GREY_PEN;
 
 
 wxPen wxLIGHT_GREY_PEN;
 
 

+
+/**
+    @class wxPenList
+    @wxheader{gdicmn.h}
+
+    There is only one instance of this class: ::wxThePenList.
+    Use this object to search for a previously created pen of the desired
+    type and create it if not already found. In some windowing systems,
+    the pen may be a scarce resource, so it can pay to reuse old
+    resources if possible. When an application finishes, all pens will
+    be deleted and their resources freed, eliminating the possibility of
+    'memory leaks'. However, it is best not to rely on this automatic
+    cleanup because it can lead to double deletion in some circumstances.
+
+    There are two mechanisms in recent versions of wxWidgets which make the
+    pen list less useful than it once was. Under Windows, scarce resources
+    are cleaned up internally if they are not being used. Also, a referencing
+    counting mechanism applied to all GDI objects means that some sharing
+    of underlying resources is possible. You don't have to keep track of pointers,
+    working out when it is safe delete a pen, because the referencing counting does
+    it for you. For example, you can set a pen in a device context, and then
+    immediately delete the pen you passed, because the pen is 'copied'.
+
+    So you may find it easier to ignore the pen list, and instead create
+    and copy pens as you see fit. If your Windows resource meter suggests
+    your application is using too many resources, you can resort to using
+    GDI lists to share objects explicitly.
+
+    The only compelling use for the pen list is for wxWidgets to keep
+    track of pens in order to clean them up on exit. It is also kept for
+    backward compatibility with earlier versions of wxWidgets.
+
+    @library{wxcore}
+    @category{gdi}
+
+    @stdobjects
+    ::wxThePenList
+
+    @see wxPen
+*/
+class wxPenList
+{
+public:
+    /**
+        Constructor. The application should not construct its own pen list:
+        use the object pointer ::wxThePenList.
+    */
+    wxPenList();
+
+    /**
+        Finds a pen with the specified attributes and returns it, else creates a
+        new pen, adds it to the pen list, and returns it.
+
+        @param colour
+            Colour object.
+        @param width
+            Width of pen.
+        @param style
+            Pen style. See ::wxPenStyle for a list of styles.
+    */
+    wxPen* FindOrCreatePen(const wxColour& colour, int width, wxPenStyle style);
+};
+
+/**
+    The global list of wxPen objects ready to be re-used (for better performances).
+*/
+wxPenList* wxThePenList;
+