added interface headers with latest discussed changes

[wxWidgets.git] / interface / spinbutt.h

/////////////////////////////////////////////////////////////////////////////
// Name:        spinbutt.h
// Purpose:     documentation for wxSpinEvent class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxSpinEvent
    @wxheader{spinbutt.h}
    
    This event class is used for the events generated by 
    wxSpinButton and wxSpinCtrl.
    
    @library{wxcore}
    @category{events}
    
    @seealso
    wxSpinButton and wxSpinCtrl
*/
class wxSpinEvent : public wxNotifyEvent
{
public:
    /**
        The constructor is not normally used by the user code.
    */
    wxSpinEvent(wxEventType commandType = wxEVT_@NULL, int id = 0);

    /**
        Retrieve the current spin button or control value.
    */
    int GetPosition();

    /**
        Set the value associated with the event.
    */
    void SetPosition(int pos);
};


/**
    @class wxSpinButton
    @wxheader{spinbutt.h}
    
    A wxSpinButton has two small up and down (or left and right) arrow buttons. It
    is often used next to a text control for increment and decrementing a value.
    Portable programs should try to use wxSpinCtrl instead
    as wxSpinButton is not implemented for all platforms but wxSpinCtrl is as it
    degenerates to a simple wxTextCtrl on such platforms.
    
    @b NB: the range supported by this control (and wxSpinCtrl) depends on the
    platform but is at least @c -0x8000 to @c 0x7fff. Under GTK and
    Win32 with sufficiently new version of @c comctrl32.dll (at least 4.71 is
    required, 5.80 is recommended) the full 32 bit range is supported.
    
    @beginStyleTable
    @style{wxSP_HORIZONTAL}:
           Specifies a horizontal spin button (note that this style is not
           supported in wxGTK).
    @style{wxSP_VERTICAL}:
           Specifies a vertical spin button.
    @style{wxSP_ARROW_KEYS}:
           The user can use arrow keys to change the value.
    @style{wxSP_WRAP}:
           The value wraps at the minimum and maximum.
    @endStyleTable
    
    @library{wxcore}
    @category{ctrl}
    @appearance{spinbutton.png}
    
    @seealso
    wxSpinCtrl
*/
class wxSpinButton : public wxControl
{
public:
    //@{
    /**
        Constructor, creating and showing a spin button.
        
        @param parent 
        Parent window. Must not be @NULL.
        
        @param id 
        Window identifier. The value wxID_ANY indicates a default value.
        
        @param pos 
        Window position. If wxDefaultPosition is specified then a default position
        is chosen.
        
        @param size 
        Window size. If wxDefaultSize is specified then a default size is
        chosen.
        
        @param style 
        Window style. See wxSpinButton.
        
        @param name 
        Window name.
        
        @sa Create()
    */
    wxSpinButton();
        wxSpinButton(wxWindow* parent, wxWindowID id,
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     long style = wxSP_HORIZONTAL,
                     const wxString& name = "spinButton");
    //@}

    /**
        Destructor, destroys the spin button control.
    */
    ~wxSpinButton();

    /**
        Scrollbar creation function called by the spin button constructor.
        See wxSpinButton() for details.
    */
    bool Create(wxWindow* parent, wxWindowID id,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
                long style = wxSP_HORIZONTAL,
                const wxString& name = "spinButton");

    /**
        Returns the maximum permissible value.
        
        @sa SetRange()
    */
    int GetMax();

    /**
        Returns the minimum permissible value.
        
        @sa SetRange()
    */
    int GetMin();

    /**
        Returns the current spin button value.
        
        @sa SetValue()
    */
    int GetValue();

    /**
        Sets the range of the spin button.
        
        @param min 
        The minimum value for the spin button.
        
        @param max 
        The maximum value for the spin button.
        
        @sa GetMin(), GetMax()
    */
    void SetRange(int min, int max);

    /**
        Sets the value of the spin button.
        
        @param value 
        The value for the spin button.
    */
    void SetValue(int value);
};