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

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

interface/bitmap.h

@@ -6,6 +6,12 @@
 // 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}
@@ -50,35 +56,33 @@ public:
         @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.
 
-@todo why type is an int and not a wxBitmapType?
-
         @returns @true if the call succeeded, @false otherwise (the default).
     */
-    virtual bool Create(wxBitmap* bitmap, const void* data, int type,
+    virtual bool Create(wxBitmap* bitmap, const void* data, wxBitmapType type,
-                        int width, int height, int depth = -1);
+                        int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
 
     /**
         Gets the file extension associated with this handler.
     */
-    const wxString GetExtension() const;
+    const wxString& GetExtension() const;
 
     /**
         Gets the name of this handler.
     */
-    const wxString GetName() const;
+    const wxString& GetName() const;
 
     /**
         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
@@ -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
-            See wxBitmap::wxBitmap for values this can take.
+            See ::wxBitmapType for values this can take.
 
         @returns @true if the operation succeeded, @false otherwise.
 
-@todo why type is an int and not a wxBitmapType?
-
         @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.
@@ -108,17 +110,15 @@ public:
         @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.
 
-@todo why type is an int and not a wxBitmapType?
-
         @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);
 
     /**
@@ -140,12 +140,10 @@ public:
     /**
         Sets the handler type.
 
-@todo why type is an int and not a wxBitmapType?
-
         @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
-    Many wxBitmap functions take a @e type parameter, which is a value of
+    Many wxBitmap functions take a @e type parameter, which is a value of the
-    the ::wxBitmapType enumeration.
+    ::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,
@@ -199,7 +197,8 @@ public:
     */
     wxBitmap(const wxBitmap& bitmap);
 
-    /**
+
+    /*
         Creates a bitmap from the given @a data which is interpreted in
         platform-dependent manner.
 
@@ -216,12 +215,14 @@ public:
         @param depth
             Specifies the depth of the bitmap.
             If this is omitted, the display depth of the screen is used.
-
-@todo why type is an int and not a wxBitmapType?
-
-    */
     wxBitmap(const void* data, int type, int width, int height, int depth = -1);
 
+
+        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.
+    */
+
     /**
         Creates a bitmap from the given array @a bits.
         You should only use this function for monochrome bitmaps (depth 1) in
@@ -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.
-        Under other platforms, only monochrome bitmaps may be created using this constructor
+        Under other platforms, only monochrome bitmaps may be created using this
-        and wxImage should be used for creating colour bitmaps from static data.
+        constructor and wxImage should be used for creating colour bitmaps from
+        static data.
 
         @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.
-            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);
 
     /**
-        Creates a new bitmap. A depth of -1 indicates the depth of the current
+        Creates a new bitmap. A depth of ::wxBITMAP_SCREEN_DEPTH indicates the
-        screen or visual. Some platforms only support 1 for monochrome and -1 for
+        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+.
     */
-    wxBitmap(int width, int height, int depth = -1);
+    wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
 
     /**
         Creates a bitmap from XPM data.
@@ -270,15 +273,16 @@ public:
 
         @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
+        Creates this bitmap object from the given image.
-        display an image as you cannot draw an image directly on a window.
+        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
-        current system if depth is -1) which entails that a colour reduction has
+        current system if depth is ::wxBITMAP_SCREEN_DEPTH) which entails that a
-        to take place.
+        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,
@@ -295,8 +299,7 @@ public:
             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.
@@ -339,16 +342,15 @@ public:
     */
     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.
     */
-    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
@@ -366,11 +368,13 @@ public:
         @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);
 
+        NOTE: leave this undoc for the same reason of the relative ctor.
+    */
+
     /**
         Finds the handler with the given @a name.
 
@@ -405,8 +409,8 @@ public:
     static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
 
     /**
-        Gets the colour depth of the bitmap. A value of 1 indicates a
+        Gets the colour depth of the bitmap.
-        monochrome bitmap.
+        A value of 1 indicates a monochrome bitmap.
     */
     int GetDepth() const;
 
@@ -531,7 +535,7 @@ public:
         @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).

interface/bmpbuttn.h

@@ -11,29 +11,53 @@
     @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
+    It may be placed on a wxDialog or a wxPanel, or indeed almost any other window.
-    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
-           all provided bitmaps. WIN32 only.
+           all provided bitmaps. Has effect only under MS Windows.
     @style{wxBU_LEFT}:
-           Left-justifies the bitmap label. WIN32 only.
+           Left-justifies the bitmap label. Has effect only under MS Windows.
     @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}:
-           Right-justifies the bitmap label. WIN32 only.
+           Right-justifies the bitmap label. Has effect only under MS Windows.
     @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
 
+    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)}:
-           Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is
+           Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
-           clicked.
     @endEventTable
 
     @library{wxcore}
@@ -45,7 +69,11 @@
 class wxBitmapButton : public wxButton
 {
 public:
-    //@{
+    /**
+        Default ctor.
+    */
+    wxBitmapButton();
+
     /**
         Constructor, creating and showing a button.
 
@@ -58,8 +86,7 @@ public:
         @param pos
             Button position.
         @param size
-            Button size. If wxDefaultSize is specified then the button is
+            Button size. If wxDefaultSize is specified then the button is sized
-        sized
             appropriately for the bitmap.
         @param style
             Window style. See wxBitmapButton.
@@ -68,16 +95,13 @@ public:
         @param name
             Window name.
 
-        @remarks The bitmap parameter is normally the only bitmap you need to
+        @remarks The bitmap parameter is normally the only bitmap you need to provide,
-                 provide, and wxWidgets will draw the button correctly
+                 and wxWidgets will draw the button correctly in its different states.
-                 in its different states. If you want more control, call
+                 If you want more control, call any of the functions SetBitmapSelected(),
-                 any of the functions SetBitmapSelected(),
+                 SetBitmapFocus(), SetBitmapDisabled().
-                 SetBitmapFocus(),
-                 SetBitmapDisabled().
 
         @see Create(), wxValidator
     */
-    wxBitmapButton();
     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");
-    //@}
 
     /**
         Destructor, destroying the button.
@@ -93,8 +116,8 @@ public:
     ~wxBitmapButton();
 
     /**
-        Button creation function for two-step creation. For more details, see
+        Button creation function for two-step creation.
-        wxBitmapButton().
+        For more details, see wxBitmapButton().
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxBitmap& bitmap,
@@ -106,36 +129,36 @@ 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.
 
         @see SetBitmapDisabled()
     */
-    const wxBitmap GetBitmapDisabled();
+    const wxBitmap& GetBitmapDisabled() const;
-    const wxBitmap&  GetBitmapDisabled();
+    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.
 
         @see SetBitmapFocus()
     */
-    const wxBitmap GetBitmapFocus();
+    const wxBitmap& GetBitmapFocus() const;
-    const wxBitmap&  GetBitmapFocus();
+    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()
     */
-    const wxBitmap GetBitmapHover();
     const wxBitmap& GetBitmapHover();
+    wxBitmap&  GetBitmapHover();
     //@}
 
     //@{
@@ -146,8 +169,8 @@ public:
 
         @see SetBitmapLabel()
     */
-    const wxBitmap GetBitmapLabel();
     const wxBitmap& GetBitmapLabel();
+    wxBitmap&  GetBitmapLabel();
     //@}
 
     /**
@@ -157,7 +180,7 @@ public:
 
         @see SetBitmapSelected()
     */
-    wxBitmap GetBitmapSelected() const;
+    wxBitmap& GetBitmapSelected() const;
 
     /**
         Sets the bitmap for the disabled button appearance.
@@ -184,8 +207,9 @@ public:
     /**
         Sets the bitmap to be shown when the mouse is over the button.
 
-        @wxsince{2.7.0} and the hover bitmap is
+        @wxsince{2.7.0}
-        currently only supported in wxMSW.
+
+        The hover bitmap is currently only supported in wxMSW.
 
         @see GetBitmapHover()
     */

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.
 
+    @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
@@ -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
-           control or used for navigation between dialog controls). Windows
+           control or used for navigation between dialog controls).
-           only.
+           Windows only.
     @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)}:
-           Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text
+           Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text changes.
-           changes.
     @event{EVT_TEXT_ENTER(id, func)}:
            Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
            the combobox.
@@ -48,6 +56,11 @@
 class wxBitmapComboBox : public wxComboBox
 {
 public:
+    /**
+        Default ctor.
+    */
+    wxBitmapComboBox();
+
     //@{
     /**
         Constructor, creating and showing a combobox.
@@ -61,8 +74,7 @@ public:
         @param pos
             Window position.
         @param size
-            Window size. If wxDefaultSize is specified then the window is
+            Window size. If wxDefaultSize is specified then the window is sized
-        sized
             appropriately.
         @param n
             Number of strings with which to initialise the control.
@@ -77,7 +89,6 @@ public:
 
         @see Create(), wxValidator
     */
-    wxBitmapComboBox();
     wxBitmapComboBox(wxWindow* parent, wxWindowID id,
                      const wxString& value = "",
                      const wxPoint& pos = wxDefaultPosition,
@@ -102,13 +113,17 @@ public:
     */
     ~wxBitmapComboBox();
 
-    //@{
     /**
-        Adds the item to the end of the combo box, associating the given, typed or
+        Adds the item to the end of the combo box.
-        untyped, client data pointer with the item.
     */
     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,
@@ -149,14 +164,20 @@ public:
     */
     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.
-        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);

interface/brush.h

@@ -6,164 +6,140 @@
 // 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
-    the background of rectangles, ellipses, etc. It has a colour and a
+    the background of rectangles, ellipses, etc. It has a colour and a style.
-    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
-    ::Objects:, ::wxNullBrush, ::Pointers:, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH,
+    ::wxNullBrush, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH, ::wxWHITE_BRUSH,
-    ::wxWHITE_BRUSH, ::wxBLACK_BRUSH, ::wxGREY_BRUSH, ::wxMEDIUM_GREY_BRUSH, ::wxLIGHT_GREY_BRUSH, ::wxTRANSPARENT_BRUSH, ::wxCYAN_BRUSH, ::wxRED_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:
-    //@{
     /**
-        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 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
-            One of:
+            One of the ::wxBrushStyle enumeration values.
 
-        
+        @see wxColourDatabase
-        
+    */
-        
+    wxBrush(const wxString& colourName, wxBrushStyle style);
-        
+
-        
+    /**
-            wxTRANSPARENT
+        Constructs a stippled brush using a bitmap.
-        
+        The brush style will be set to wxBRUSHSTYLE_STIPPLE.
-        
-        
-        
-            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
     */
-    wxBrush();
-    wxBrush(const wxColour& colour, int style = wxSOLID);
-    wxBrush(const wxString& colourName, int style);
     wxBrush(const wxBitmap& stippleBitmap);
+
+    /**
+        Copy constructor, uses @ref overview_refcount "reference counting".
+    */
     wxBrush(const wxBrush& brush);
-    //@}
 
     /**
         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
-                 exits, the application should try to clean up all
+                 exits, the application should try to clean up all brushes itself.
-                 brushes itself. This is because wxWidgets cannot know
+                 This is because wxWidgets cannot know if a pointer to the brush
-                 if a pointer to the brush object is stored in an
+                 object is stored in an application data structure, and there is
-                 application data structure, and there is a risk of
+                 a risk of double deletion.
-                 double deletion.
     */
     ~wxBrush();
 
@@ -175,61 +151,19 @@ public:
     wxColour GetColour() const;
 
     /**
-        Gets a pointer to the stipple bitmap. If the brush does not have a wxSTIPPLE
+        Gets a pointer to the stipple bitmap. If the brush does not have a wxBRUSHSTYLE_STIPPLE
-        style,
+        style, this bitmap may be non-@NULL but uninitialised (i.e. wxBitmap:IsOk() returns @false).
-        this bitmap may be non-@NULL but uninitialised (@ref wxBitmap::isok
-        wxBitmap:IsOk returns @false).
 
         @see SetStipple()
     */
     wxBitmap* GetStipple() const;
 
     /**
-        Returns the brush style, one of:
+        Returns the brush style, one of the ::wxBrushStyle values.
-        
-        @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.
 
         @see SetStyle(), SetColour(), SetStipple()
     */
-    int GetStyle() const;
+    wxBrushStyle GetStyle() const;
 
     /**
         Returns @true if the style of the brush is any of hatched fills.
@@ -263,9 +197,9 @@ public:
         @param bitmap
             The bitmap to use for stippling.
 
-        @remarks The style will be set to wxSTIPPLE, unless the bitmap has a mask
+        @remarks The style will be set to wxBRUSHSTYLE_STIPPLE, unless the bitmap
-                 associated to it, in which case the style will be set
+                 has a mask associated to it, in which case the style will be set
-                 to wxSTIPPLE_MASK_OPAQUE.
+                 to wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE.
 
         @see wxBitmap
     */
@@ -275,209 +209,121 @@ public:
         Sets the brush style.
 
         @param style
-            One of:
+            One of the ::wxBrushStyle values.
-        
-        
-        
-        
-        
-        
-            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.
 
         @see GetStyle()
     */
-    void SetStyle(int style);
+    void SetStyle(wxBrushStyle style);
 
     /**
         Inequality operator.
-        See @ref overview_refcountequality "reference-counted object comparison" for
+        See @ref overview_refcount_equality for more info.
-        more info.
     */
     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.
-        See @ref overview_refcountequality "reference-counted object comparison" for
+        See @ref overview_refcount_equality for more info.
-        more info.
     */
     bool operator ==(const wxBrush& brush);
 };
 
-
 /**
-    FIXME
+    An empty brush.
-*/
-wxBrush Objects:
-;
-
-/**
-    FIXME
 */
 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;

interface/buffer.h

@@ -11,27 +11,31 @@
     @wxheader{buffer.h}
 
     A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized
-    blocks
+    blocks of memory. wxMemoryBuffer guarantees deletion of the memory block when
-    of memory. wxMemoryBuffer guarantees deletion of the memory block when the
+    the object is destroyed.
-    object
-    is destroyed.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{data}
 */
 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.
 
         @param size
-            size of new buffer.
+            size of the new buffer.
     */
-    wxMemoryBuffer(const wxMemoryBuffer& src);
     wxMemoryBuffer(size_t size);
-    //@}
 
     /**
         Append a single byte to the buffer.
@@ -44,8 +48,8 @@ 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
-        write data into the buffer, this new data will be appended to
+        write data into the buffer, this new data will be appended to the
-        the existing data.
+        existing data.
 
         @param sizeNeeded
             Amount of extra space required in the buffer for
@@ -81,8 +85,8 @@ public:
     void SetBufSize(size_t size);
 
     /**
-        Sets the length of the data stored in the buffer.  Mainly useful for truncating
+        Sets the length of the data stored in the buffer.
-        existing data.
+        Mainly useful for truncating existing data.
 
         @param size
             New length of the valid data in the buffer. This is

interface/busyinfo.h

@@ -19,14 +19,14 @@
     @code
         wxBusyInfo wait("Please wait, working...");
 
-        for (int i = 0; i  100000; i++)
+        for (int i = 0; i < 100000; i++)
         {
             DoACalculation();
         }
     @endcode
 
-    It works by creating a window in the constructor,
+    It works by creating a window in the constructor, and deleting it
-    and deleting it in the destructor.
+    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
@@ -37,7 +37,7 @@
 
         wxBusyInfo wait("Please wait, working...");
 
-        for (int i = 0; i  100000; i++)
+        for (int i = 0; i < 100000; i++)
         {
             DoACalculation();
 
@@ -47,20 +47,19 @@
     @endcode
 
     but take care to not cause undesirable reentrancies when doing it (see
-    wxApp::Yield for more details). The simplest way to do
+    wxApp::Yield for more details). The simplest way to do it is to use
-    it is to use wxWindowDisabler class as illustrated
+    wxWindowDisabler class as illustrated in the above example.
-    in the above example.
 
     @library{wxcore}
-    @category{FIXME}
+    @category{cmndlg}
 */
 class wxBusyInfo
 {
 public:
     /**
-        Constructs a busy info window as child of @a parent and displays @e msg
+        Constructs a busy info window as child of @a parent and displays @e msg in it.
-        in it.
+
-        @b NB: If @a parent is not @NULL you must ensure that it is not
+        @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);

interface/button.h

@@ -10,10 +10,11 @@
     @class wxButton
     @wxheader{button.h}
 
-    A button is a control that contains a text string,
+    A button is a control that contains a text string, and is one of the most
-    and is one of the most common elements of a GUI. It may be placed on a
+    common elements of a GUI.
-    @ref overview_wxdialog "dialog box" or panel(), or indeed
+
-    almost any other window.
+    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}:
@@ -33,8 +34,7 @@
 
     @beginEventTable
     @event{EVT_BUTTON(id, func)}:
-           Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is
+           Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
-           clicked.
     @endEventTable
 
     @library{wxcore}
@@ -46,14 +46,19 @@
 class wxButton : public wxControl
 {
 public:
-    //@{
+    /**
+        Default ctor.
+    */
+    wxButton();
+
     /**
         Constructor, creating and showing a button.
+
         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
+        @a 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
+        @ref page_stockitems "this list", a standard label will be used.
-        to
+
-        that, the button will be decorated with stock icons under GTK+ 2.
+        In addition to that, the button will be decorated with stock icons under GTK+ 2.
 
         @param parent
             Parent window. Must not be @NULL.
@@ -67,7 +72,7 @@ public:
             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
@@ -75,7 +80,6 @@ public:
 
         @see Create(), wxValidator
     */
-    wxButton();
     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");
-    //@}
 
     /**
         Destructor, destroying the button.
@@ -91,8 +94,8 @@ public:
     ~wxButton();
 
     /**
-        Button creation function for two-step creation. For more details, see
+        Button creation function for two-step creation.
-        wxButton().
+        For more details, see wxButton().
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& label = wxEmptyString,
@@ -112,22 +115,20 @@ public:
     /**
         Returns the string label for the button.
 
-        @returns The button's label.
-        
         @see SetLabel()
     */
     wxString GetLabel() const;
 
     /**
-        This sets the button to be the default item for the panel or dialog
+        This sets the button to be the default item for the panel or dialog box.
-        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.
-                  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();
 

interface/gdicmn.h

@@ -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}
@@ -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);
-    //@}
-};
-
 
 
 // ============================================================================

interface/pen.h

@@ -1,34 +1,164 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        pen.h
-// Purpose:     interface of wxPen
+// Purpose:     interface of wxPen* classes
 // 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
-    lines and painting the outline of rectangles, ellipses, etc. It has a
+    lines and painting the outline of rectangles, ellipses, etc.
-    colour, a width and a style.
+    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
-    ::Objects:, ::wxNullPen, ::Pointers:, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN,
+    ::wxNullPen, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN, ::wxBLACK_PEN,
-    ::wxBLACK_PEN, ::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN, ::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_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:
-    //@{
     /**
-        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.
@@ -42,162 +172,7 @@ public:
         @param pen
             A pointer or reference to a pen to copy.
         @param style
-            The style may be one of the following:
+            The style may be one of the ::wxPenStyle values.
-        
-        
-        
-        
-        
-        
-            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.
 
         @remarks Different versions of Windows and different versions of other
                  platforms support very different subsets of the styles
@@ -206,13 +181,7 @@ public:
 
         @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);
-    //@}
 
     /**
         Destructor.
@@ -234,7 +203,7 @@ public:
 
         @see SetCap()
     */
-    int GetCap() const;
+    wxPenCap GetCap() const;
 
     /**
         Returns a reference to the pen colour.
@@ -260,7 +229,7 @@ public:
 
         @see SetJoin()
     */
-    int GetJoin() const;
+    wxPenJoin GetJoin() const;
 
     /**
         Gets a pointer to the stipple bitmap.
@@ -274,7 +243,7 @@ public:
 
         @see wxPen(), SetStyle()
     */
-    int GetStyle() const;
+    wxPenStyle GetStyle() const;
 
     /**
         Returns the pen width.
@@ -295,7 +264,7 @@ public:
 
         @see GetCap()
     */
-    void SetCap(int capStyle);
+    void SetCap(wxPenCap capStyle);
 
     //@{
     /**
@@ -327,7 +296,7 @@ public:
 
         @see GetJoin()
     */
-    void SetJoin(int join_style);
+    void SetJoin(wxPenJoin join_style);
 
     /**
         Sets the bitmap for stippling.
@@ -341,7 +310,7 @@ public:
 
         @see wxPen()
     */
-    void SetStyle(int style);
+    void SetStyle(wxPenStyle style);
 
     /**
         Sets the pen width.
@@ -370,24 +339,11 @@ public:
     bool operator ==(const wxPen& pen);
 };
 
-
-/**
-    FIXME
-*/
-wxPen Objects:
-;
-
 /**
     FIXME
 */
 wxPen wxNullPen;
 
-/**
-    FIXME
-*/
-wxPen Pointers:
-;
-
 /**
     FIXME
 */
@@ -439,3 +395,71 @@ wxPen wxMEDIUM_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;
+