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 a36c8cacefddb9ea628d3ca54cdeec95a951b896..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,27 +16,6 @@
     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.
 

-    @beginStyleTable
-    @style{wxBU_LEFT}
-        Left-justifies the label. Windows and GTK+ only.
-    @style{wxBU_TOP}
-        Aligns the label to the top of the button. Windows and GTK+ only.
-    @style{wxBU_RIGHT}
-        Right-justifies the bitmap label. Windows and GTK+ only.
-    @style{wxBU_BOTTOM}
-        Aligns the label to the bottom of the button. Windows and GTK+ only.
-    @style{wxBU_EXACTFIT}
-        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}
-        Creates a flat button. Windows and GTK+ only.
-    @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
     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


@@ -44,20 +24,16 @@
     bitmap with respect to the label (however currently non-default alignment
     combinations are not implemented on all platforms).
 
     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)}
-           Process a 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
     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


@@ -72,18 +48,63 @@
         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.
+
+    @beginStyleTable
+    @style{wxBU_LEFT}
+        Left-justifies the label. Windows and GTK+ only.
+    @style{wxBU_TOP}
+        Aligns the label to the top of the button. Windows and GTK+ only.
+    @style{wxBU_RIGHT}
+        Right-justifies the bitmap label. Windows and GTK+ only.
+    @style{wxBU_BOTTOM}
+        Aligns the label to the bottom of the button. Windows and GTK+ only.
+    @style{wxBU_EXACTFIT}
+        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}
+        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
+
+    @beginEventEmissionTable{wxCommandEvent}
+    @event{EVT_BUTTON(id, func)}
+           Process a @c wxEVT_BUTTON event, when the button is clicked.
+    @endEventTable
+

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

-    @appearance{button.png}
+    @appearance{button}

 
     @see wxBitmapButton
 */
 
     @see wxBitmapButton
 */

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

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


@@ -96,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


@@ -141,67 +170,18 @@ public:
                 const wxString& name = wxButtonNameStr);
 
     /**
                 const wxString& name = wxButtonNameStr);
 
     /**

-        Return the bitmap shown by the button.
+        Returns @true if an authentication needed symbol is displayed on the
+        button.

 
 

-        The returned bitmap may be invalid only if the button doesn't show any
-        images.
+        @remarks This method always returns @false if the platform is not
+                 Windows Vista or newer.

 
 

-        @see SetBitmap()
+        @see SetAuthNeeded()

 
         @since 2.9.1
      */
 
         @since 2.9.1
      */

-    wxBitmap GetBitmap() const;
-
-    /**
-        Returns the bitmap used when the mouse is over the button, which may be
-        invalid.
-
-        @see SetBitmapCurrent()
-
-        @since 2.9.1 (available as wxBitmapButton::GetBitmapHover() in previous
-            versions)
-    */
-    wxBitmap GetBitmapCurrent() const;
-
-    /**
-        Returns the bitmap for the disabled state, which may be invalid.
-
-        @see SetBitmapDisabled()
+    bool GetAuthNeeded() const;

 
 

-        @since 2.9.1 (available in wxBitmapButton only in previous versions)
-    */
-    wxBitmap GetBitmapDisabled() const;
-
-    /**
-        Returns the bitmap for the focused state, which may be invalid.
-
-        @see SetBitmapFocus()
-
-        @since 2.9.1 (available in wxBitmapButton only in previous versions)
-    */
-    wxBitmap GetBitmapFocus() const;
-
-    /**
-        Returns the bitmap for the normal state.
-
-        This is exactly the same as GetBitmap() but uses a name
-        backwards-compatible with wxBitmapButton.
-
-        @see SetBitmap(), SetBitmapLabel()
-
-        @since 2.9.1 (available in wxBitmapButton only in previous versions)
-    */
-    wxBitmap GetBitmapLabel() const;
-
-    /**
-        Returns the bitmap for the pressed state, which may be invalid.
-
-        @see SetBitmapPressed()
-
-        @since 2.9.1 (available as wxBitmapButton::GetBitmapSelected() in
-            previous versions)
-    */
-    wxBitmap GetBitmapPressed() const;

 
     /**
         Returns the default size for the buttons. It is advised to make all the dialog
 
     /**
         Returns the default size for the buttons. It is advised to make all the dialog


@@ -218,107 +198,18 @@ public:
     wxString GetLabel() const;
 
     /**
     wxString GetLabel() const;
 
     /**

-        Sets the bitmap to display in the button.
-
-        The bitmap is displayed together with the button label. This method
-        sets up a single bitmap which is used in all button states, use
-        SetBitmapDisabled(), SetBitmapPressed(), SetBitmapCurrent() or
-        SetBitmapFocus() to change the individual images used in different
-        states.
-
-        @param bitmap
-            The bitmap to display in the button. May be invalid to remove any
-            currently displayed bitmap.
-        @param dir
-            The position of the bitmap inside the button. By default it is
-            positioned to the left of the text, near to the left button border.
-            Other possible values include wxRIGHT, wxTOP and wxBOTTOM.
-
-        @see SetBitmapPosition(), SetBitmapMargins()
-
-        @since 2.9.1
-     */
-    void SetBitmap(const wxBitmap& bitmap, wxDirection dir = wxLEFT);
-
-    /**
-        Sets the bitmap to be shown when the mouse is over the button.
-
-        @see GetBitmapCurrent()
-
-        @since 2.9.1 (available as wxBitmapButton::SetBitmapHover() in previous
-            versions)
-    */
-    void SetBitmapCurrent(const wxBitmap& bitmap);
-
-    /**
-        Sets the bitmap for the disabled button appearance.
-
-        @see GetBitmapDisabled(), SetBitmapLabel(),
-             SetBitmapPressed(), SetBitmapFocus()
-
-        @since 2.9.1 (available in wxBitmapButton only in previous versions)
-    */
-    void SetBitmapDisabled(const wxBitmap& bitmap);
-
-    /**
-        Sets the bitmap for the button appearance when it has the keyboard
-        focus.
-
-        @see GetBitmapFocus(), SetBitmapLabel(),
-             SetBitmapPressed(), SetBitmapDisabled()
-
-        @since 2.9.1 (available in wxBitmapButton only in previous versions)
-    */
-    void SetBitmapFocus(const wxBitmap& bitmap);
-
-    /**
-        Sets the bitmap label for the button.
-
-        @remarks This is the bitmap used for the unselected state, and for all
-                 other states if no other bitmaps are provided.
-
-        @see SetBitmap(), GetBitmapLabel()
-
-        @since 2.9.1 (available in wxBitmapButton only in previous versions)
-    */
-    void SetBitmapLabel(const wxBitmap& bitmap);
-
-    /**
-        Sets the bitmap for the selected (depressed) button appearance.
-
-        @since 2.9.1 (available as wxBitmapButton::SetBitmapSelected() in
-            previous versions)
-    */
-    void SetBitmapPressed(const wxBitmap& bitmap);
-
-    /**
-        Set the margins between the bitmap and the text of the button.
+        Sets whether an authentication needed symbol should be displayed on the
+        button.

 
 

-        This method is currently only implemented under MSW. If it is not
-        called, default margin is used around the bitmap.
+        @remarks This method doesn't do anything if the platform is not Windows
+                 Vista or newer.

 
 

-        @see SetBitmap(), SetBitmapPosition()
+        @see GetAuthNeeded()

 
         @since 2.9.1
      */
 
         @since 2.9.1
      */

-    //@{
-    void SetBitmapMargins(wxCoord x, wxCoord y);
-    void SetBitmapMargins(const wxSize& sz);
-    //@}
-
-    /**
-        Set the position at which the bitmap is displayed.
-
-        This method should only be called if the button does have an associated
-        bitmap.
+    void SetAuthNeeded(bool needed = true);

 
 

-        @since 2.9.1
-
-        @param dir
-            Direction in which the bitmap should be positioned, one of wxLEFT,
-            wxRIGHT, wxTOP or wxBOTTOM.
-     */
-    void SetBitmapPosition(wxDirection dir);

 
     /**
         This sets the button to be the default item in its top-level window
 
     /**
         This sets the button to be the default item in its top-level window


@@ -332,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();