Applied patch #15286: documentation and col/rowspan demo by dghart

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

diff --git a/interface/wx/button.h b/interface/wx/button.h
index 60117d124b84afb39bae681cbc0f8e0705595c1b..7c91ca1dc390a286104381135bf670f62750e012 100644 (file)
--- a/interface/wx/button.h
+++ b/interface/wx/button.h
@@ -3,9 +3,10 @@
 // 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

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

+

 /**
     @class wxButton
 
 /**
     @class wxButton
 


@@ -15,34 +16,95 @@
     It may be placed on a @ref wxDialog "dialog box" or on a @ref wxPanel panel,
     or indeed on 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.
 

+    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).
+
+    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 (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
+        keeps the mouse button pressed on it)
+    @li @b focus: bitmap shown when the button has keyboard focus (but is not
+        pressed as in this case the button is in the pressed state)
+    @li @b current: bitmap shown when the mouse is over the button (but it is
+        not pressed although it may have focus). Notice that if current 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.
+
+    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. 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.
+

     @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 ).
+        By default, all buttons are made of at least the standard button size,
+        even if their contents is small enough to fit into a smaller size. This
+        is done for consistency as most platforms use buttons of the same size
+        in the native dialogs, but can be overridden by specifying this flag.
+        If it is given, the button will be made just big enough for its
+        contents. Notice that under MSW the button will still have at least the
+        standard height, even with this style, if it has a non-empty label.
+    @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/Cocoa 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/Carbon (these restrictions don't
+        exist in OSX/Cocoa however).

     @endStyleTable
 
     @endStyleTable
 

-    @beginEventTable{wxCommandEvent}
+    @beginEventEmissionTable{wxCommandEvent}

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

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

     @endEventTable
 
     @library{wxcore}
     @category{ctrl}
     @endEventTable
 
     @library{wxcore}
     @category{ctrl}

-    <!-- @appearance{button.png} -->
+    @appearance{button}

 
     @see wxBitmapButton
 */
 
     @see wxBitmapButton
 */

-class wxButton : public wxControl
+class wxButton : public wxAnyButton

 {
 public:
     /**
 {
 public:
     /**


@@ -55,14 +117,22 @@ 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.
 
         @param parent
             Parent window. Must not be @NULL.
         @param id
 
         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

-            Button identifier. A value of wxID_ANY indicates a default value.
+            Button identifier. A value of @c wxID_ANY indicates a default value.

         @param label
             Text to be displayed on the button.
         @param pos
         @param label
             Text to be displayed on the button.
         @param pos


@@ -87,11 +157,6 @@ public:
              const wxValidator& validator = wxDefaultValidator,
              const wxString& name = wxButtonNameStr);
 
              const wxValidator& validator = wxDefaultValidator,
              const wxString& name = wxButtonNameStr);
 

-    /**
-        Destructor, destroying the button.
-    */
-    virtual ~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().


@@ -104,6 +169,20 @@ 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;
+
+

     /**
         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


@@ -118,6 +197,20 @@ 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);
+
+

     /**
         This sets the button to be the default item in its top-level window
         (e.g. the panel or the dialog box containing it).
     /**
         This sets the button to be the default item in its top-level window
         (e.g. the panel or the dialog box containing it).


@@ -130,7 +223,7 @@ public:
 
         @remarks Under Windows, only dialog box buttons respond to this function.
 
 
         @remarks Under Windows, only dialog box buttons respond to this function.
 

-        @return the old default item (possibly NULL)
+        @return the old default item (possibly @NULL)

     */
     virtual wxWindow* SetDefault();
 
     */
     virtual wxWindow* SetDefault();