wxWidgets/interface/scrolbar.h

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

/**
    @class wxScrollBar
    @wxheader{scrolbar.h}
    
    A wxScrollBar is a control that represents a horizontal or
    vertical scrollbar. It is distinct from the two scrollbars that some windows
    provide automatically, but the two types of scrollbar share the way
    events are received.
    
    @beginStyleTable
    @style{wxSB_HORIZONTAL}:
           Specifies a horizontal scrollbar.
    @style{wxSB_VERTICAL}:
           Specifies a vertical scrollbar.
    @endStyleTable
    
    @library{wxcore}
    @category{ctrl}
    @appearance{scrollbar.png}
    
    @seealso
    @ref overview_scrollingoverview "Scrolling overview", @ref
    overview_eventhandlingoverview "Event handling overview", wxScrolledWindow
*/
class wxScrollBar : public wxControl
{
public:
    //@{
    /**
        Constructor, creating and showing a scrollbar.
        
        @param parent 
        Parent window. Must be non-@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 wxScrollBar.
        
        @param validator 
        Window validator.
        
        @param name 
        Window name.
        
        @sa Create(), wxValidator
    */
    wxScrollBar();
        wxScrollBar(wxWindow* parent, wxWindowID id,
                    const wxPoint& pos = wxDefaultPosition,
                    const wxSize& size = wxDefaultSize,
                    long style = wxSB_HORIZONTAL,
                    const wxValidator& validator = wxDefaultValidator,
                    const wxString& name = "scrollBar");
    //@}

    /**
        Destructor, destroying the scrollbar.
    */
    ~wxScrollBar();

    /**
        Scrollbar creation function called by the scrollbar constructor.
        See wxScrollBar() for details.
    */
    bool Create(wxWindow* parent, wxWindowID id,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
                long style = wxSB_HORIZONTAL,
                const wxValidator& validator = wxDefaultValidator,
                const wxString& name = "scrollBar");

    /**
        Returns the page size of the scrollbar. This is the number of scroll units
        that will be scrolled when the user pages up or down. Often it is the
        same as the thumb size.
        
        @sa SetScrollbar()
    */
    int GetPageSize();

    /**
        Returns the length of the scrollbar.
        
        @sa SetScrollbar()
    */
    int GetRange();

    /**
        Returns the current position of the scrollbar thumb.
        
        @sa SetThumbPosition()
    */
    int GetThumbPosition();

    /**
        Returns the thumb or 'view' size.
        
        @sa SetScrollbar()
    */
    int GetThumbSize();

    /**
        Sets the scrollbar properties.
        
        @param position 
        The position of the scrollbar in scroll units.
        
        @param thumbSize 
        The size of the thumb, or visible portion of the scrollbar, in scroll units.
        
        @param range 
        The maximum position of the scrollbar.
        
        @param pageSize 
        The size of the page size in scroll units. This is the number of units
        the scrollbar will scroll when it is paged up or down. Often it is the same as
        the thumb size.
        
        @param refresh 
        @true to redraw the scrollbar, @false otherwise.
        
        @remarks Let's say you wish to display 50 lines of text, using the same
                   font. The window is sized so that you can only see 16
                   lines at a time.
    */
    virtual void SetScrollbar(int position, int thumbSize, int range,
                              int pageSize,
                              bool refresh = @true);

    /**
        Sets the position of the scrollbar.
        
        @param viewStart 
        The position of the scrollbar thumb.
        
        @sa GetThumbPosition()
    */
    void SetThumbPosition(int viewStart);
};