don't style using Doxygen tags; use <span> tags and CSS instead

[wxWidgets.git] / interface / radiobox.h

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

/**
    @class wxRadioBox
    @wxheader{radiobox.h}

    A radio box item is used to select one of number of mutually exclusive
    choices.  It is displayed as a vertical column or horizontal row of
    labelled buttons.

    @beginStyleTable
    @style{wxRA_SPECIFY_ROWS}:
           The major dimension parameter refers to the maximum number of rows.
    @style{wxRA_SPECIFY_COLS}:
           The major dimension parameter refers to the maximum number of
           columns.
    @style{wxRA_USE_CHECKBOX}:
           Use of the checkbox controls instead of radio buttons (currently
           supported only on PalmOS)
    @endStyleTable

    @beginEventTable
    @event{EVT_RADIOBOX(id\, func)}:
           Process a wxEVT_COMMAND_RADIOBOX_SELECTED event, when a radiobutton
           is clicked.
    @endEventTable

    @library{wxcore}
    @category{ctrl}
    @appearance{radiobox.png}

    @seealso
    @ref overview_eventhandlingoverview "Event handling overview", wxRadioButton,
    wxCheckBox
*/
class wxRadioBox : public wxControlWithItems
{
public:
    //@{
    /**
        Constructor, creating and showing a radiobox.
        
        @param parent
        Parent window. Must not be @NULL.
        
        @param id
        Window identifier. The value wxID_ANY indicates a default value.
        
        @param label
        Label for the static box surrounding the radio buttons.
        
        @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 n
        Number of choices with which to initialize the radiobox.
        
        @param choices
        An array of choices with which to initialize the radiobox.
        
        @param majorDimension
        Specifies the maximum number of rows (if style contains wxRA_SPECIFY_ROWS) or
        columns (if style contains wxRA_SPECIFY_COLS) for a two-dimensional
        radiobox.
        
        @param style
        Window style. See wxRadioBox.
        
        @param validator
        Window validator.
        
        @param name
        Window name.
        
        @sa Create(), wxValidator
    */
    wxRadioBox();
    wxRadioBox(wxWindow* parent, wxWindowID id,
               const wxString& label,
               const wxPoint& point = wxDefaultPosition,
               const wxSize& size = wxDefaultSize,
               int n = 0,
               const wxString choices[] = @NULL,
               int majorDimension = 0,
               long style = wxRA_SPECIFY_COLS,
               const wxValidator& validator = wxDefaultValidator,
               const wxString& name = "radioBox");
    wxRadioBox(wxWindow* parent, wxWindowID id,
               const wxString& label,
               const wxPoint& point,
               const wxSize& size,
               const wxArrayString& choices,
               int majorDimension = 0,
               long style = wxRA_SPECIFY_COLS,
               const wxValidator& validator = wxDefaultValidator,
               const wxString& name = "radioBox");
    //@}

    /**
        Destructor, destroying the radiobox item.
    */
    ~wxRadioBox();

    //@{
    /**
        Creates the radiobox for two-step construction. See wxRadioBox()
        for further details.
    */
    bool Create(wxWindow* parent, wxWindowID id,
                const wxString& label,
                const wxPoint& point = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
                int n = 0,
                const wxString choices[] = @NULL,
                int majorDimension = 0,
                long style = wxRA_SPECIFY_COLS,
                const wxValidator& validator = wxDefaultValidator,
                const wxString& name = "radioBox");
    bool Create(wxWindow* parent, wxWindowID id,
                const wxString& label,
                const wxPoint& point,
                const wxSize& size,
                const wxArrayString& choices,
                int majorDimension = 0,
                long style = wxRA_SPECIFY_COLS,
                const wxValidator& validator = wxDefaultValidator,
                const wxString& name = "radioBox");
    //@}

    //@{
    /**
        Enables or disables an individual button in the radiobox.
        
        @param enable
        @true to enable, @false to disable.
        
        @param n
        The zero-based button to enable or disable.
        
        @sa wxWindow::Enable
    */
    virtual bool Enable(bool enable = @true);
    virtual bool Enable(unsigned int n, bool enable = @true);
    //@}

    /**
        Finds a button matching the given string, returning the position if found, or
        -1 if not found.
        
        @param string
        The string to find.
    */
    int FindString(const wxString& string);

    /**
        Returns the number of columns in the radiobox.
    */
    unsigned int GetColumnCount();

    /**
        Returns a radio box item under the point, a zero-based item index, or @c
        wxNOT_FOUND if no item is under the point.
        
        @param pt
        Point in client coordinates.
    */
    int GetItemFromPoint(const wxPoint pt);

    /**
        Returns the helptext associated with the specified @e item if any or @c
        wxEmptyString.
        
        @param item
        The zero-based item index.
        
        @sa SetItemHelpText()
    */
    wxString GetItemHelpText(unsigned int item);

    /**
        Returns the tooltip associated with the specified @e item if any or @NULL.
        
        @sa SetItemToolTip(), wxWindow::GetToolTip
    */
    wxToolTip * GetItemToolTip(unsigned int item);

    /**
        Returns the radiobox label.
        
        @param n
        The zero-based button index.
        
        @sa SetLabel()
    */
    wxString GetLabel();

    /**
        Returns the number of rows in the radiobox.
    */
    unsigned int GetRowCount();

    /**
        Returns the zero-based position of the selected button.
    */
    int GetSelection();

    /**
        Returns the label for the button at the given position.
        
        @param n
        The zero-based button position.
    */
    wxString GetString(unsigned int n);

    /**
        Returns the selected string.
    */
    wxString GetStringSelection();

    /**
        Returns @true if the item is enabled or @false if it was disabled using
        @ref enable() "Enable(n, @false)".
        
        @b Platform note: Currently only implemented in wxMSW, wxGTK and wxUniversal
        and always returns @true in the other ports.
        
        @param n
        The zero-based button position.
    */
    bool IsItemEnabled(unsigned int n);

    /**
        Returns @true if the item is currently shown or @false if it was hidden
        using
        @ref show() "Show(n, @false)".
        
        Note that this function returns @true for an item which hadn't been hidden
        even
        if the entire radiobox is not currently shown.
        
        @b Platform note: Currently only implemented in wxMSW, wxGTK and wxUniversal
        and always returns @true in the other ports.
        
        @param n
        The zero-based button position.
    */
    bool IsItemShown(unsigned int n);

    /**
        Sets the helptext for an item. Empty string erases any existing helptext.
        
        @param item
        The zero-based item index.
        
        @param helptext
        The help text to set for the item.
        
        @sa GetItemHelpText()
    */
    void SetItemHelpText(unsigned int item, const wxString& helptext);

    /**
        Sets the tooltip text for the specified item in the radio group.
        
        @b Platform note: Currently only implemented in wxMSW and wxGTK2 and does
        nothing in the other ports.
        
        @param item
        Index of the item the tooltip will be shown for.
        
        @param text
        Tooltip text for the item, the tooltip is removed if empty.
        
        @sa GetItemToolTip(), wxWindow::SetToolTip
    */
    void SetItemToolTip(unsigned int item, const wxString& text);

    /**
        Sets the radiobox label.
        
        @param label
        The label to set.
        
        @param n
        The zero-based button index.
    */
    void SetLabel(const wxString& label);

    /**
        Sets a button by passing the desired string position. This does not cause
        a wxEVT_COMMAND_RADIOBOX_SELECTED event to get emitted.
        
        @param n
        The zero-based button position.
    */
    void SetSelection(int n);

    /**
        Sets the selection to a button by passing the desired string. This does not
        cause
        a wxEVT_COMMAND_RADIOBOX_SELECTED event to get emitted.
        
        @param string
        The label of the button to select.
    */
    void SetStringSelection(const wxString& string);
};