X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a21175918ecedbae7d04a58acca5e90a6b59633d..c29c95fe24973b94fd724db767193171ca7c513d:/interface/wx/button.h

diff --git a/interface/wx/button.h b/interface/wx/button.h
index a36c8cacef..697fc73f6c 100644
--- a/interface/wx/button.h
+++ b/interface/wx/button.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxButton
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -33,7 +33,11 @@
         without using this style a button which is only supposed to show a
         bitmap but uses a standard id would display a label too.
     @style{wxBORDER_NONE}
-        Creates a flat button. Windows and GTK+ only.
+        Creates a button without border. This is currently implemented in MSW,
+        GTK2 and OSX/Carbon ports but in the latter only applies to buttons
+        with bitmaps and using bitmap of one of the standard sizes only, namely
+        128*128, 48*48, 24*24 or 16*16. In all the other cases wxBORDER_NONE is
+        ignored under OSX.
     @endStyleTable
 
     By default, i.e. if none of the alignment styles are specified, the label
@@ -46,18 +50,20 @@
 
     @beginEventEmissionTable{wxCommandEvent}
     @event{EVT_BUTTON(id, func)}
-           Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
+           Process a @c wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
     @endEventTable
 
 
-    Since version 2.9.1 wxButton supports showing both text and an image, see
+    Since version 2.9.1 wxButton supports showing both text and an image
+    (currently only when using wxMSW, wxGTK or wxOSX/Cocoa ports), see
     SetBitmap() and SetBitmapLabel(), SetBitmapDisabled() &c methods. In the
     previous wxWidgets versions this functionality was only available in (the
     now trivial) wxBitmapButton class which was only capable of showing an
     image without text.
 
     A button may have either a single image for all states or different images
-    for the following states:
+    for the following states (different images are not currently supported
+    under OS X where the normal image is used for all states):
     @li @b normal: the default state
     @li @b disabled: bitmap shown when the button is disabled.
     @li @b pressed: bitmap shown when the button is pushed (e.g. while the user
@@ -72,11 +78,20 @@
         get reasonably good behaviour on all platforms.
 
     All of the bitmaps must be of the same size and the normal bitmap must be
-    set first (to a valid bitmap), before setting any other ones.
+    set first (to a valid bitmap), before setting any other ones. Also, if the
+    size of the bitmaps is changed later, you need to change the size of the
+    normal bitmap before setting any other bitmaps with the new size (and you
+    do need to reset all of them as their original values can be lost when the
+    normal bitmap size changes).
 
     The position of the image inside the button be configured using
     SetBitmapPosition(). By default the image is on the left of the text.
 
+    Please also notice that GTK+ uses a global setting called @c
+    gtk-button-images to determine if the images should be shown in the buttons
+    at all. If it is off (which is the case in e.g. Gnome 2.28 by default), no
+    images will be shown, consistently with the native behaviour.
+
     @library{wxcore}
     @category{ctrl}
     @appearance{button.png}
@@ -96,7 +111,15 @@ public:
 
         The preferred way to create standard buttons is to use default value of
         @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.
+        @ref page_stockitems "this list", a standard label will be used. In
+        other words, if you use a predefined @c wxID_XXX constant, just omit
+        the label completely rather than specifying it. In particular, help
+        buttons (the ones with @a id of @c wxID_HELP) under Mac OS X can't
+        display any label at all and while wxButton will detect if the standard
+        "Help" label is used and ignore it, using any other label will prevent
+        the button from correctly appearing as a help button and so should be
+        avoided.
+
 
         In addition to that, the button will be decorated with stock icons under GTK+ 2.
 
@@ -140,6 +163,19 @@ public:
                 const wxValidator& validator = wxDefaultValidator,
                 const wxString& name = wxButtonNameStr);
 
+    /**
+        Returns @true if an authentication needed symbol is displayed on the
+        button.
+
+        @remarks This method always returns @false if the platform is not
+                 Windows Vista or newer.
+
+        @see SetAuthNeeded()
+
+        @since 2.9.1
+     */
+    bool GetAuthNeeded() const;
+
     /**
         Return the bitmap shown by the button.
 
@@ -203,6 +239,15 @@ public:
     */
     wxBitmap GetBitmapPressed() const;
 
+    /**
+        Get the margins between the bitmap and the text of the button.
+
+        @see SetBitmapMargins()
+
+        @since 2.9.1
+     */
+    wxSize GetBitmapMargins();
+
     /**
         Returns the default size for the buttons. It is advised to make all the dialog
         buttons of the same size and this function allows to retrieve the (platform and
@@ -217,6 +262,19 @@ public:
     */
     wxString GetLabel() const;
 
+    /**
+        Sets whether an authentication needed symbol should be displayed on the
+        button.
+
+        @remarks This method doesn't do anything if the platform is not Windows
+                 Vista or newer.
+
+        @see GetAuthNeeded()
+
+        @since 2.9.1
+     */
+    void SetAuthNeeded(bool needed = true);
+
     /**
         Sets the bitmap to display in the button.