[wxWidgets.git] / interface / wx / valnum.h

/////////////////////////////////////////////////////////////////////////////
// Name:        wx/valnum.h
// Purpose:     Documentation of numeric validator classes.
// Author:      Vadim Zeitlin based on the submission of Fulvio Senore
// Created:     2010-11-06
// Copyright:   (c) 2010 wxWidgets team
//              (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

/**
    Bit masks used for numeric validator styles.

    A combination of these flags can be used when creating wxIntegerValidator
    and wxFloatingPointValidator objects and with their SetStyle() methods.

    @since 2.9.2
    @category{validator}
 */
enum wxNumValidatorStyle
{
    /**
        Indicates absence of any other flags.

        This value corresponds to the default behaviour.
     */
    wxNUM_VAL_DEFAULT = 0,

    /**
        Use thousands separators in the numbers.

        When this style is used, numbers are formatted using the thousands
        separators after validating the user entry (if the current locale uses
        the thousands separators character).
     */
    wxNUM_VAL_THOUSANDS_SEPARATOR = 1,

    /**
        Show a value of zero as an empty string.

        With this style a value of zero in the associated variable is
        translated to an empty string and an empty value of the control is
        translated to a value of zero.
     */
    wxNUM_VAL_ZERO_AS_BLANK = 2,

    /**
        Remove trailing zeroes from the fractional part of the number.

        This style can only be used with wxFloatingPointValidator and indicates
        that trailing zeroes should be removed from the control text when it is
        validated. By default, as many zeroes as needed to satisfy the
        precision used when creating the validator will be appended.

        For example, without this style a wxFloatingPointValidator with a
        precision 3 will show the value of 1.5 as "1.500" after validation.
        With this style, the value will be shown as just "1.5" (while a value
        of e.g. 1.567 will still be shown with all the three significant
        digits, of course).
     */
    wxNUM_VAL_NO_TRAILING_ZEROES

};

/**
    wxNumValidator is the common base class for numeric validator classes.

    This class is never used directly, but only as a base class for
    wxIntegerValidator and wxFloatingPointValidator.

    @tparam T
        Type of the values used with this validator.

    @category{validator}

    @since 2.9.2
 */
template <typename T>
class wxNumValidator : public wxValidator
{
public:
    /// Type of the values this validator is used with.
    typedef T ValueType;

    /**
        Sets the minimal value accepted by the validator.

        This value is inclusive, i.e. the value equal to @a min is accepted.
     */
    void SetMin(ValueType min);

    /**
        Sets the maximal value accepted by the validator.

        This value is inclusive, i.e. the value equal to @a max is accepted.
     */
    void SetMax(ValueType max);

    /**
        Sets both minimal and maximal values accepted by the validator.

        Calling this is equivalent to calling both SetMin() and SetMax().
     */
    void SetRange(ValueType min, ValueType max);


    /**
        Change the validator style.

        Can be used to change the style of the validator after its creation.
        The @a style parameter must be a combination of the values from
        wxNumValidatorStyle enum.
     */
    void SetStyle(int style);


    /**
        Override base class method to format the control contents.

        This method is called when the associated window is shown and it fills
        it with the contents of the associated variable, if any, formatted
        according to the validator style.

        It does nothing if there is no associated variable.
     */
    virtual bool TransferToWindow();

    /**
        Override base class method to validate the control contents.

        This method is called to check the correctness of user input and fill
        the associated variable with the controls numeric value. It returns
        false if it is not a number in the configured range or if the control
        contents is empty for a validator without wxNUM_VAL_ZERO_AS_BLANK
        style.

        It does nothing if there is no associated variable.
     */
    virtual bool TransferFromWindow();
};

/**
    Validator for text entries used for integer entry.

    This validator can be used with wxTextCtrl or wxComboBox (and potentially
    any other class implementing wxTextEntry interface) to check that only
    valid integer values can be entered into them.

    This is a template class which can be instantiated for all the integer types
    (i.e. @c short, @c int, @c long and <code>long long</code> if available) as
    well as their unsigned versions.

    By default this validator accepts any integer values in the range
    appropriate for its type, e.g. <code>INT_MIN..INT_MAX</code> for @c int or
    <code>0..USHRT_MAX</code> for <code>unsigned short</code>. This range can
    be restricted further by calling SetMin() and SetMax() or SetRange()
    methods inherited from the base class.

    When the validator displays integers with thousands separators, the
    character used for the separators (usually "." or ",") depends on the locale
    set with wxLocale (note that you shouldn't change locale with setlocale()
    as this can result in a mismatch between the thousands separator used by
    wxLocale and the one used by the run-time library).

    A simple example of using this class:
    @code
        class MyDialog : public wxDialog
        {
        public:
            MyDialog()
            {
                ...
                // Allow positive integers and display them with thousands
                // separators.
                wxIntegerValidator<unsigned long>
                    val(&m_value, wxNUM_VAL_THOUSANDS_SEPARATOR);

                // If the variable were of type "long" and not "unsigned long"
                // we would have needed to call val.SetMin(0) but as it is,
                // this is not needed.

                // Associate it with the text control:
                new wxTextCtrl(this, ..., val);
            }

        private:
            unsigned long m_value;
        };
    @endcode
    For more information, please see @ref overview_validator.

    @library{wxcore}
    @category{validator}

    @see @ref overview_validator, wxValidator, wxGenericValidator,
    wxTextValidator, wxMakeIntegerValidator()

    @since 2.9.2
*/
template <typename T>
class wxIntegerValidator : public wxNumValidator<T>
{
public:
    /// Type of the values this validator is used with.
    typedef T ValueType;

    /**
        Validator constructor.

        @param value
            A pointer to the variable associated with the validator. If non
            @NULL, this variable should have a lifetime equal to or longer than
            the validator lifetime (which is usually determined by the lifetime
            of the window).
        @param style
            A combination of wxNumValidatorStyle enum values with the exception
            of wxNUM_VAL_NO_TRAILING_ZEROES which can't be used here.
    */
    wxIntegerValidator(ValueType *value = NULL, int style = wxNUM_VAL_DEFAULT);
};

/**
    Creates a wxIntegerValidator object with automatic type deduction.

    This function can be used to create wxIntegerValidator object without
    explicitly specifying its type, e.g. write just:
    @code
        new wxTextCtrl(..., wxMakeIntegerValidator(&m_var));
    @endcode
    instead of more verbose
    @code
        new wxTextCtrl(..., wxIntegerValidator<unsigned long>(&m_var));
    @endcode

    @since 2.9.2
 */
template <typename T>
wxIntegerValidator<T>
wxMakeIntegerValidator(T *value, int style = wxNUM_VAL_DEFAULT);

/**
    Validator for text entries used for floating point numbers entry.

    This validator can be used with wxTextCtrl or wxComboBox (and potentially
    any other class implementing wxTextEntry interface) to check that only
    valid floating point values can be entered into them. Currently only fixed
    format is supported on input, i.e. scientific format with mantissa and
    exponent is not supported.

    This template class can be instantiated for either @c float or @c double,
    <code>long double</code> values are not currently supported.

    Similarly to wxIntegerValidator<>, the range for the accepted values is by
    default set appropriately for the type. Additionally, this validator allows
    to specify the maximum number of digits that can be entered after the
    decimal separator. By default this is also set appropriately for the type
    used, e.g. 6 for @c float and 15 for @c double on a typical IEEE-754-based
    implementation. As with the range, the precision can be restricted after
    the validator creation if necessary.

    When the validator displays numbers with decimal or thousands separators,
    the characters used for the separators (usually "." or ",") depend on the
    locale set with wxLocale (note that you shouldn't change locale with
    setlocale() as this can result in a mismatch between the separators used by
    wxLocale and the one used by the run-time library).

    A simple example of using this class:
    @code
        class MyDialog : public wxDialog
        {
        public:
            MyDialog()
            {
                ...
                // Allow floating point numbers from 0 to 100 with 2 decimal
                // digits only and handle empty string as 0 by default.
                wxFloatingPointValidator<float>
                    val(2, &m_value, wxNUM_VAL_ZERO_AS_BLANK);
                val.SetRange(0, 100);

                // Associate it with the text control:
                new wxTextCtrl(this, ..., val);
            }

        private:
            float m_value;
        };
    @endcode

    For more information, please see @ref overview_validator.

    @library{wxcore}
    @category{validator}

    @see @ref overview_validator, wxValidator, wxGenericValidator,
    wxTextValidator, wxMakeIntegerValidator()

    @since 2.9.2
*/
template <typename T>
class wxFloatingPointValidator : public wxNumValidator<T>
{
public:
    /// Type of the values this validator is used with.
    typedef T ValueType;

    /**
        Validator constructor.

        @param value
            A pointer to the variable associated with the validator. If non
            @NULL, this variable should have a lifetime equal to or longer than
            the validator lifetime (which is usually determined by the lifetime
            of the window).
        @param style
            A combination of wxNumValidatorStyle enum values.
        @param precision
            The number of decimal digits after the decimal separator to show
            and accept.
    */
    //@{
    wxFloatingPointValidator(ValueType *value = NULL,
                             int style = wxNUM_VAL_DEFAULT);
    wxFloatingPointValidator(int precision,
                             ValueType *value = NULL,
                             int style = wxNUM_VAL_DEFAULT);
    //@}


    /**
        Set precision.

        Precision is the number of digits shown (and accepted on input)
        after the decimal point. By default this is set to the maximal
        precision supported by the type handled by the validator in its
        constructor.
     */
    void SetPrecision(unsigned precision);
};

/**
    Creates a wxFloatingPointValidator object with automatic type deduction.

    Similarly to wxMakeIntegerValidator(), this function allows to avoid
    explicitly specifying the validator type.

    @since 2.9.2
 */
//@{
template <typename T>
inline wxFloatingPointValidator<T>
wxMakeFloatingPointValidator(T *value, int style = wxNUM_VAL_DEFAULT);

template <typename T>
inline wxFloatingPointValidator<T>
wxMakeFloatingPointValidator(int precision,
                             T *value, int style = wxNUM_VAL_DEFAULT);
//@}
Commit	Line	Data
a54cf371 VZ	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: wx/valnum.h
	3	// Purpose: Documentation of numeric validator classes.
	4	// Author: Vadim Zeitlin based on the submission of Fulvio Senore
	5	// Created: 2010-11-06
	6	// Copyright: (c) 2010 wxWidgets team
	7	// (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
3fdcd5d5	8	// Licence: wxWindows licence
a54cf371 VZ	9	/////////////////////////////////////////////////////////////////////////////
	10
	11	/**
	12	Bit masks used for numeric validator styles.
	13
	14	A combination of these flags can be used when creating wxIntegerValidator
	15	and wxFloatingPointValidator objects and with their SetStyle() methods.
	16
	17	@since 2.9.2
	18	@category{validator}
	19	*/
	20	enum wxNumValidatorStyle
	21	{
	22	/**
	23	Indicates absence of any other flags.
	24
	25	This value corresponds to the default behaviour.
	26	*/
	27	wxNUM_VAL_DEFAULT = 0,
	28
	29	/**
	30	Use thousands separators in the numbers.
	31
	32	When this style is used, numbers are formatted using the thousands
	33	separators after validating the user entry (if the current locale uses
	34	the thousands separators character).
	35	*/
	36	wxNUM_VAL_THOUSANDS_SEPARATOR = 1,
	37
	38	/**
	39	Show a value of zero as an empty string.
	40
	41	With this style a value of zero in the associated variable is
	42	translated to an empty string and an empty value of the control is
	43	translated to a value of zero.
	44	*/
	45	wxNUM_VAL_ZERO_AS_BLANK = 2,
	46
	47	/**
	48	Remove trailing zeroes from the fractional part of the number.
	49
	50	This style can only be used with wxFloatingPointValidator and indicates
	51	that trailing zeroes should be removed from the control text when it is
	52	validated. By default, as many zeroes as needed to satisfy the
	53	precision used when creating the validator will be appended.
	54
	55	For example, without this style a wxFloatingPointValidator with a
	56	precision 3 will show the value of 1.5 as "1.500" after validation.
	57	With this style, the value will be shown as just "1.5" (while a value
	58	of e.g. 1.567 will still be shown with all the three significant
	59	digits, of course).
	60	*/
	61	wxNUM_VAL_NO_TRAILING_ZEROES
	62
	63	};
	64
	65	/**
	66	wxNumValidator is the common base class for numeric validator classes.
	67
	68	This class is never used directly, but only as a base class for
	69	wxIntegerValidator and wxFloatingPointValidator.
	70
	71	@tparam T
	72	Type of the values used with this validator.
73
74	@category{validator}
75
76	@since 2.9.2
77	*/
78	template <typename T>
79	class wxNumValidator : public wxValidator
80	{
81	public:
82	/// Type of the values this validator is used with.
83	typedef T ValueType;
84
85	/**
86	Sets the minimal value accepted by the validator.
87
88	This value is inclusive, i.e. the value equal to @a min is accepted.
89	*/
90	void SetMin(ValueType min);
91
92	/**
93	Sets the maximal value accepted by the validator.
94
95	This value is inclusive, i.e. the value equal to @a max is accepted.
96	*/
97	void SetMax(ValueType max);
98
99	/**
100	Sets both minimal and maximal values accepted by the validator.
101
102	Calling this is equivalent to calling both SetMin() and SetMax().
103	*/
bf92c226	104	void SetRange(ValueType min, ValueType max);
a54cf371 VZ	105
	106
	107	/**
	108	Change the validator style.
	109
	110	Can be used to change the style of the validator after its creation.
	111	The @a style parameter must be a combination of the values from
	112	wxNumValidatorStyle enum.
	113	*/
	114	void SetStyle(int style);
	115
	116
	117	/**
	118	Override base class method to format the control contents.
	119
	120	This method is called when the associated window is shown and it fills
	121	it with the contents of the associated variable, if any, formatted
	122	according to the validator style.
	123
	124	It does nothing if there is no associated variable.
	125	*/
	126	virtual bool TransferToWindow();
	127
	128	/**
	129	Override base class method to validate the control contents.
	130
	131	This method is called to check the correctness of user input and fill
	132	the associated variable with the controls numeric value. It returns
	133	false if it is not a number in the configured range or if the control
	134	contents is empty for a validator without wxNUM_VAL_ZERO_AS_BLANK
	135	style.
	136
	137	It does nothing if there is no associated variable.
	138	*/
	139	virtual bool TransferFromWindow();
	140	};
	141
	142	/**
	143	Validator for text entries used for integer entry.
	144
	145	This validator can be used with wxTextCtrl or wxComboBox (and potentially
	146	any other class implementing wxTextEntry interface) to check that only
	147	valid integer values can be entered into them.
	148
	149	This is a template class which can be instantiated for all the integer types
	150	(i.e. @c short, @c int, @c long and <code>long long</code> if available) as
	151	well as their unsigned versions.
	152
	153	By default this validator accepts any integer values in the range
	154	appropriate for its type, e.g. <code>INT_MIN..INT_MAX</code> for @c int or
	155	<code>0..USHRT_MAX</code> for <code>unsigned short</code>. This range can
	156	be restricted further by calling SetMin() and SetMax() or SetRange()
	157	methods inherited from the base class.
	158
71f89d85 VZ	159	When the validator displays integers with thousands separators, the
	160	character used for the separators (usually "." or ",") depends on the locale
	161	set with wxLocale (note that you shouldn't change locale with setlocale()
	162	as this can result in a mismatch between the thousands separator used by
	163	wxLocale and the one used by the run-time library).
	164
a54cf371 VZ	165	A simple example of using this class:
	166	@code
	167	class MyDialog : public wxDialog
	168	{
	169	public:
	170	MyDialog()
	171	{
	172	...
	173	// Allow positive integers and display them with thousands
	174	// separators.
	175	wxIntegerValidator<unsigned long>
	176	val(&m_value, wxNUM_VAL_THOUSANDS_SEPARATOR);
	177
	178	// If the variable were of type "long" and not "unsigned long"
	179	// we would have needed to call val.SetMin(0) but as it is,
	180	// this is not needed.
	181
	182	// Associate it with the text control:
	183	new wxTextCtrl(this, ..., val);
	184	}
	185
	186	private:
	187	unsigned long m_value;
	188	};
	189	@endcode
	190	For more information, please see @ref overview_validator.
	191
	192	@library{wxcore}
	193	@category{validator}
	194
	195	@see @ref overview_validator, wxValidator, wxGenericValidator,
	196	wxTextValidator, wxMakeIntegerValidator()
	197
	198	@since 2.9.2
	199	*/
	200	template <typename T>
	201	class wxIntegerValidator : public wxNumValidator<T>
	202	{
	203	public:
	204	/// Type of the values this validator is used with.
	205	typedef T ValueType;
	206
	207	/**
	208	Validator constructor.
	209
	210	@param value
	211	A pointer to the variable associated with the validator. If non
	212	@NULL, this variable should have a lifetime equal to or longer than
	213	the validator lifetime (which is usually determined by the lifetime
	214	of the window).
	215	@param style
	216	A combination of wxNumValidatorStyle enum values with the exception
	217	of wxNUM_VAL_NO_TRAILING_ZEROES which can't be used here.
	218	*/
	219	wxIntegerValidator(ValueType *value = NULL, int style = wxNUM_VAL_DEFAULT);
	220	};
	221
	222	/**
	223	Creates a wxIntegerValidator object with automatic type deduction.
	224
	225	This function can be used to create wxIntegerValidator object without
	226	explicitly specifying its type, e.g. write just:
	227	@code
	228	new wxTextCtrl(..., wxMakeIntegerValidator(&m_var));
229	@endcode
230	instead of more verbose
231	@code
232	new wxTextCtrl(..., wxIntegerValidator<unsigned long>(&m_var));
233	@endcode
234
235	@since 2.9.2
236	*/
237	template <typename T>
238	wxIntegerValidator<T>
239	wxMakeIntegerValidator(T *value, int style = wxNUM_VAL_DEFAULT);
240
241	/**
242	Validator for text entries used for floating point numbers entry.
243
244	This validator can be used with wxTextCtrl or wxComboBox (and potentially
245	any other class implementing wxTextEntry interface) to check that only
246	valid floating point values can be entered into them. Currently only fixed
247	format is supported on input, i.e. scientific format with mantissa and
248	exponent is not supported.
249
250	This template class can be instantiated for either @c float or @c double,
251	<code>long double</code> values are not currently supported.
252
253	Similarly to wxIntegerValidator<>, the range for the accepted values is by
254	default set appropriately for the type. Additionally, this validator allows
255	to specify the maximum number of digits that can be entered after the
256	decimal separator. By default this is also set appropriately for the type
257	used, e.g. 6 for @c float and 15 for @c double on a typical IEEE-754-based
258	implementation. As with the range, the precision can be restricted after
259	the validator creation if necessary.
260
71f89d85 VZ	261	When the validator displays numbers with decimal or thousands separators,
	262	the characters used for the separators (usually "." or ",") depend on the
	263	locale set with wxLocale (note that you shouldn't change locale with
	264	setlocale() as this can result in a mismatch between the separators used by
	265	wxLocale and the one used by the run-time library).
	266
a54cf371 VZ	267	A simple example of using this class:
	268	@code
	269	class MyDialog : public wxDialog
	270	{
	271	public:
	272	MyDialog()
	273	{
	274	...
	275	// Allow floating point numbers from 0 to 100 with 2 decimal
	276	// digits only and handle empty string as 0 by default.
	277	wxFloatingPointValidator<float>
	278	val(2, &m_value, wxNUM_VAL_ZERO_AS_BLANK);
	279	val.SetRange(0, 100);
	280
	281	// Associate it with the text control:
	282	new wxTextCtrl(this, ..., val);
	283	}
	284
	285	private:
	286	float m_value;
	287	};
	288	@endcode
	289
	290	For more information, please see @ref overview_validator.
	291
	292	@library{wxcore}
	293	@category{validator}
	294
	295	@see @ref overview_validator, wxValidator, wxGenericValidator,
	296	wxTextValidator, wxMakeIntegerValidator()
	297
	298	@since 2.9.2
	299	*/
	300	template <typename T>
	301	class wxFloatingPointValidator : public wxNumValidator<T>
	302	{
	303	public:
	304	/// Type of the values this validator is used with.
	305	typedef T ValueType;
	306
	307	/**
	308	Validator constructor.
	309
	310	@param value
	311	A pointer to the variable associated with the validator. If non
	312	@NULL, this variable should have a lifetime equal to or longer than
	313	the validator lifetime (which is usually determined by the lifetime
	314	of the window).
	315	@param style
	316	A combination of wxNumValidatorStyle enum values.
	317	@param precision
	318	The number of decimal digits after the decimal separator to show
	319	and accept.
	320	*/
	321	//@{
	322	wxFloatingPointValidator(ValueType *value = NULL,
	323	int style = wxNUM_VAL_DEFAULT);
	324	wxFloatingPointValidator(int precision,
	325	ValueType *value = NULL,
	326	int style = wxNUM_VAL_DEFAULT);
	327	//@}
	328
	329
	330	/**
331	Set precision.
332
333	Precision is the number of digits shown (and accepted on input)
334	after the decimal point. By default this is set to the maximal
335	precision supported by the type handled by the validator in its
336	constructor.
337	*/
338	void SetPrecision(unsigned precision);
339	};
340
341	/**
342	Creates a wxFloatingPointValidator object with automatic type deduction.
343
344	Similarly to wxMakeIntegerValidator(), this function allows to avoid
345	explicitly specifying the validator type.
346
347	@since 2.9.2
348	*/
349	//@{
350	template <typename T>
351	inline wxFloatingPointValidator<T>
352	wxMakeFloatingPointValidator(T *value, int style = wxNUM_VAL_DEFAULT);
353
354	template <typename T>
355	inline wxFloatingPointValidator<T>
356	wxMakeFloatingPointValidator(int precision,
357	T *value, int style = wxNUM_VAL_DEFAULT);
358	//@}