More initial reviews of d* interface headers.

[wxWidgets.git] / interface / spinbutt.h

/////////////////////////////////////////////////////////////////////////////
// Name:        spinbutt.h
// Purpose:     interface of wxSpinEvent
// 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}

    @see 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() const;

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

    @note 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}

    @see 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.

        @see 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.

        @see SetRange()
    */
    int GetMax() const;

    /**
        Returns the minimum permissible value.

        @see SetRange()
    */
    int GetMin() const;

    /**
        Returns the current spin button value.

        @see SetValue()
    */
    int GetValue() const;

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

        @see 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);
};