No changes, just merge some strings in wxSVGFileDC.

[wxWidgets.git] / interface / wx / button.h

diff --git a/interface/wx/button.h b/interface/wx/button.h
index fa2882bc245c39f7bca7b8daca7a8e1b3c7ddc14..697fc73f6ccdb02eb0e247b026ffddcec4eee5c0 100644 (file)
--- a/interface/wx/button.h
+++ b/interface/wx/button.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxButton
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxButton
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -17,34 +17,53 @@
 
     @beginStyleTable
     @style{wxBU_LEFT}
 
     @beginStyleTable
     @style{wxBU_LEFT}

-           Left-justifies the label. Windows and GTK+ only.
+        Left-justifies the label. Windows and GTK+ only.

     @style{wxBU_TOP}
     @style{wxBU_TOP}

-           Aligns the label to the top of the button. Windows and GTK+ only.
+        Aligns the label to the top of the button. Windows and GTK+ only.

     @style{wxBU_RIGHT}
     @style{wxBU_RIGHT}

-           Right-justifies the bitmap label. Windows and GTK+ only.
+        Right-justifies the bitmap label. Windows and GTK+ only.

     @style{wxBU_BOTTOM}
     @style{wxBU_BOTTOM}

-           Aligns the label to the bottom of the button. Windows and GTK+ only.
+        Aligns the label to the bottom of the button. Windows and GTK+ only.

     @style{wxBU_EXACTFIT}
     @style{wxBU_EXACTFIT}

-           Creates the button as small as possible instead of making it of the
-           standard size (which is the default behaviour ).
+        Creates the button as small as possible instead of making it of the
+        standard size (which is the default behaviour ).
+    @style{wxBU_NOTEXT}
+        Disables the display of the text label in the button even if it has one
+        or its id is one of the standard stock ids with an associated label:
+        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}
     @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
 
     @endStyleTable
 

+    By default, i.e. if none of the alignment styles are specified, the label
+    is centered both horizontally and vertically. If the button has both a
+    label and a bitmap, the alignment styles above specify the location of the
+    rectangle combining both the label and the bitmap and the bitmap position
+    set with wxButton::SetBitmapPosition() defines the relative position of the
+    bitmap with respect to the label (however currently non-default alignment
+    combinations are not implemented on all platforms).
+

     @beginEventEmissionTable{wxCommandEvent}
     @event{EVT_BUTTON(id, func)}
     @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
 
 
     @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
     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
     @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


@@ -59,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
         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.
 
 
     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}
     @library{wxcore}
     @category{ctrl}
     @appearance{button.png}


@@ -83,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
 
         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.
 
 
         In addition to that, the button will be decorated with stock icons under GTK+ 2.
 


@@ -127,6 +163,19 @@ public:
                 const wxValidator& validator = wxDefaultValidator,
                 const wxString& name = wxButtonNameStr);
 
                 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.
 
     /**
         Return the bitmap shown by the button.
 


@@ -190,6 +239,15 @@ public:
     */
     wxBitmap GetBitmapPressed() const;
 
     */
     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
     /**
         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


@@ -204,6 +262,19 @@ public:
     */
     wxString GetLabel() const;
 
     */
     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.
 
     /**
         Sets the bitmap to display in the button.