Gadget class. More...

#include <ilviews/gadgets/datfield.h>

Inheritance diagram for IlvDateField:

Public Types
enum	IlvDateFieldFormat { df_day, df_Day, df_month, df_Month, df_month_text, df_abbrev_month, df_year, df_Year }
	This enumeration defines values used to specify various date formats in a date field. These formats will be used to display the date and convert the date to a string. More...

Public Member Functions
	IlvDateField (IlvDisplay display, const IlvRect &rect, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette palette=0)
	Constructor. More...

	IlvDateField (IlvDisplay display, const IlvPoint &point, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette palette=0)
	Constructor. More...

virtual const char *	check (IlUShort ch)
	Is called by the interactor for each key down event that corresponds to a regular character. More...

void	getFormat (IlvDateFieldFormat &first, IlvDateFieldFormat &middle, IlvDateFieldFormat &last, char &separator) const
	Returns the format of the date field. More...

const char *	getFormatString () const
	Returns the date field format as a string. More...

IlBoolean	getValue (struct tm *date) const
	Returns the date stored in the date field into a `struct tm` object. More...

IlBoolean	getValue (IlUShort &day, IlUShort &month, IlUShort &year) const
	Returns the date stored in the date field. More...

IlBoolean	setFormat (IlvDateFieldFormat first, IlvDateFieldFormat middle, IlvDateFieldFormat last, char separator, IlBoolean redraw=IlFalse)
	Sets the format of the date field. More...

IlBoolean	setFormatString (const char *formatStr)
	Sets the format of the date field. More...

void	setValue (struct tm *date, IlBoolean redraw=IlFalse)
	Sets the date of the date field. More...

void	setValue (IlUShort day, IlUShort month, IlUShort year, IlBoolean redraw=IlFalse)
	Sets the date of the date field. More...

virtual void	validate ()
	Is called by the interactor when the user presses the Return or the Enter key. More...

Public Member Functions inherited from IlvTextField
	IlvTextField (IlvDisplay display, const char label, const IlvRect &rect, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
	Constructor. More...

	IlvTextField (IlvDisplay display, const IlvPoint &point, const char label, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
	Constructor. More...

void	addChangeCallback (IlvGraphicCallback callback)
	Adds a Label Changed callback. More...

void	addChangeCallback (IlSymbol *callbackName)
	Adds a named Label Changed callback. More...

void	addChangeCallback (IlvGraphicCallback callback, IlAny arg)
	Adds a Label Changed callback. More...

void	addChangeCallback (IlSymbol *callbackName, IlAny arg)
	Adds a named Label Changed callback. More...

void	ensureVisible (IlShort position, const IlvTransformer *t=0)
	Ensures that the character located at the specified position is visible. More...

IlvPosition	getAlignment () const
	Returns the alignment of the text field. More...

IlvGraphicCallback	getChangeCallback () const
	Returns a pointer to the first unnamed callback in the Label Changed callback list. More...

IlSymbol *	getChangeCallbackName () const
	Returns the name of the first named callback in the Label Changed callback list. More...

IlBoolean	getChangeFocusOnValidation () const
	Indicates whether the text field moves the keyboard focus to the next gadget once validated. More...

IlShort	getCursorPosition () const
	Returns the cursor position. More...

IlShort	getEndSelection () const
	Returns the index of the last selected character. More...

IlFloat	getFloatValue () const
	Converts the text field contents to a floating point value and returns the result of the conversion. More...

IlInt	getIntValue () const
	Converts the text field contents to an integer and returns the result of the conversion. More...

const char *	getLabel () const
	Returns the label displayed by the text field. More...

IlShort	getMaxChar () const
	Returns the maximum number of characters that the user can type in the text field. More...

virtual const char *	getMessage () const
	Returns the message displayed by this text field. More...

IlShort	getStartSelection () const
	Returns the index of the first selected character. More...

IlShort	getTextPosition () const
	Returns the index of the first visible character of the text field. More...

virtual IlBoolean	handleControl (IlUShort character)
	Is called by the interactor to handle control keys. More...

IlBoolean	isCursorShown () const
	Indicates whether the cursor is visible. More...

IlBoolean	isEditable () const
	Indicates whether the text field can be edited. More...

virtual void	labelChanged ()
	Is called by the interactor whenever the label of the text field changes. More...

IlShort	pointToPosition (const IlvPoint &point, const IlvTransformer *t=0) const
	Returns the index of the character located at the specified point. More...

virtual void	removeSelection ()
	Removes the selected label from the text field. More...

void	setAlignment (IlvPosition alignment)
	Sets the alignment of the text field. More...

void	setChangeCallback (IlvGraphicCallback callback)
	Sets a Label Changed callback. More...

void	setChangeCallback (IlSymbol *callbackName)
	Sets a named Label Changed callback. More...

void	setChangeCallback (IlvGraphicCallback callback, IlAny arg)
	Sets a Label Changed callback. More...

void	setChangeCallback (IlSymbol *callbackName, IlAny arg)
	Sets a named Label Changed callback. More...

void	setChangeFocusOnValidation (IlBoolean value)
	Specifies whether the text field should move the keyboard focus to the next gadget once validated. More...

void	setCursorPosition (IlShort position)
	Sets the cursor position. More...

void	setEditable (IlBoolean value)
	Specifies whether the text field can be edited. More...

void	setEndSelection (IlShort position)
	Sets the index of the last selected character. More...

virtual void	setLabel (const char *label, IlBoolean redraw=IlFalse)
	Sets the label of the text field. More...

void	setMaxChar (IlShort count)
	Sets the maximum number of characters that the user can type in the text field. More...

void	setSelection (IlShort start, IlShort end)
	Selects a portion of the text field content. More...

void	setStartSelection (IlShort position)
	Sets the index of the first selected character. More...

void	setTextPosition (IlShort position)
	Sets the index of the first visible character of the text field. More...

void	setValue (IlInt value, IlBoolean redraw=IlFalse)
	Sets the text field label to an integer value. More...

void	setValue (IlFloat value, const char *format=0, IlBoolean redraw=IlFalse)
	Sets the text field label to a floating-point value. More...

void	showCursor (IlBoolean value, IlBoolean redraw=IlFalse)
	Specifies whether the cursor should be visible. More...

Static Public Member Functions
static int	GetBaseCentury ()
	Returns the base century used by the class `IlvDateField`. More...

static int	GetCenturyThreshold ()
	Returns the century threshold set for the class `IlvDateField`. More...

static void	SetBaseCentury (int century)
	Sets the base century used by the class `IlvDateField`. More...

static void	SetCenturyThreshold (int threshold)
	Sets the century threshold used by the `IlvDateField` class. More...

Detailed Description

Gadget class.

Library: ilvadvgdt

IlvDateField defines a specialized text field gadget for editing a date.

- A Date Field -

See also: IlvNumberField, IlvPasswordField.

Accessors

Accessors provide a scriptable and uniform way to inspect and modify an object by using its base class methods IlvValueInterface::queryValue(), IlvValueInterface::queryValues(), IlvValueInterface::changeValue(), IlvValueInterface::changeValues(). This class inherits the accessors of its superclass IlvTextField and adds the following ones:

Name	Type	Equivalent methods
`value`	Time	`getValue(struct tm) const`, `setValue(struct tm, IlBoolean)`
`separator`	String	`getFormat()`, `setFormat()`
`format`	String	`getFormatString()`, `setFormatString()`

Member Enumeration Documentation

§ IlvDateFieldFormat

enum IlvDateField::IlvDateFieldFormat

This enumeration defines values used to specify various date formats in a date field. These formats will be used to display the date and convert the date to a string.

Alternatively, a string can specify a date format.

See also: getFormat(), setFormat(), getFormatString(), setFormatString()

Enumerator
df_day	Writes the day as a number with no leading zero.
df_Day	Writes the day as a number with a leading zero, if necessary.
df_month	Writes the month as a number with no leading zero.
df_Month	Writes the month as a number with a leading zero, if necessary.
df_month_text	Writes the month name. If the month names below appear in the language database, the corresponding name is taken from it. Otherwise, the character `&' is removed. Month names: `&January, &February, &March, &April, &May, &June, &July, &August, &September, &October, &November, &December`.
df_abbrev_month	Writes the abbreviated month name. If the abbreviated month names below appear in the language database, the corresponding name is taken from it. Otherwise, the abbreviated month name is taken with the character `&' removed. Abbreviated month names: `&january, &february, &march, &april, &may, &june, &july, &august, &september, &october, &november, &december.`
df_year	Writes the last two digits of the year.
df_Year	Writes the full year.

Constructor & Destructor Documentation

§ IlvDateField() [1/2]

IlvDateField::IlvDateField	(	IlvDisplay *	display,
		const IlvRect &	rect,
		IlUShort	thickness = `IlvDefaultGadgetThickness`,
		IlvPalette *	palette = `0`
	)

Constructor.

Initializes a new instance of the class IlvDatefield.

Parameters

display	The connection to the display.
rect	The size and position of the date field.
thickness	The thickness of the date field.
palette	The palette used by the date field.

§ IlvDateField() [2/2]

IlvDateField::IlvDateField	(	IlvDisplay *	display,
		const IlvPoint &	point,
		IlUShort	thickness = `IlvDefaultGadgetThickness`,
		IlvPalette *	palette = `0`
	)

Constructor.

Initializes a new instance of the class IlvDatefield. The height of the text field is computed using palette. Its width is 0, which means that you have to resize it.

Parameters

display	The connection to the display.
point	The position of the date field.
thickness	The thickness of the date field.
palette	The palette used by the date field.

Member Function Documentation

§ check()

virtual const char* IlvDateField::check ( IlUShort character )

virtual

Is called by the interactor for each key down event that corresponds to a regular character.

The default implementation inserts character in the text field (erasing the selection if there is one).

Parameters

character The ASCII code of the character.

Returns: The new label of the text field.

See also: setLabel().

Reimplemented from IlvTextField.

§ GetBaseCentury()

static int IlvDateField::GetBaseCentury ( )

static

Returns the base century used by the class IlvDateField.

This value is relevant only if the year format is df_year, that is, when the date is represented by two characters only. For details, see SetBaseCentury().

Returns: The base century used by the class IlvDateField.

See also: SetBaseCentury(), GetCenturyThreshold().

§ GetCenturyThreshold()

static int IlvDateField::GetCenturyThreshold ( )

static

Returns the century threshold set for the class IlvDateField.

The default value is 30. For details, see SetBaseCentury().

Returns: The century threshold set for the class IlvDateField.

See also: SetBaseCentury(), SetCenturyThreshold().

§ getFormat()

void IlvDateField::getFormat	(	IlvDateFieldFormat &	first,
		IlvDateFieldFormat &	middle,
		IlvDateFieldFormat &	last,
		char &	separator
	)		const

Returns the format of the date field.

A date is composed of three elements divided by separation characters.

Parameters

first	The first element of the date.
middle	The middle element of the date.
last	The last element of the date.
separator	The character used to separate each element of the date.

See also: setFormat(), IlvDateFieldFormat.

§ getFormatString()

const char* IlvDateField::getFormatString ( ) const

Returns the date field format as a string.

The method always uses the '/' character (slash) instead of the separator character set on the date field.

The correspondance between format string fields and IlvDateFieldFormat values is as follows:

d : IlvDateFieldFormat::df_day
dd : IlvDateFieldFormat::df_Day
m : IlvDateFieldFormat::df_month
mm : IlvDateFieldFormat::df_Month
MM : IlvDateFieldFormat::df_month_text
M : IlvDateFieldFormat::df_abbrev_month
yy : IlvDateFieldFormat::df_year
yyyy : IlvDateFieldFormat::df_Year

Some examples of date format strings: "dd/mm/yy", "MM/dd/yy", "yyyy/m/d", "M/d/yy", and so on.

Returns: The format of the date field, converted to a string. The returned string is stored in a temporary buffer. It must be copied by the caller, as the buffer may be modified or deleted any time after the call to this method.

See also: setFormatString(), IlvDateFieldFormat.

§ getValue() [1/2]

IlBoolean IlvDateField::getValue ( struct tm * date ) const

Returns the date stored in the date field into a struct tm object.

The type struct tm is defined in the system include file time.h.

Parameters

date	The returned date.

Returns: IlTrue if the field represents a valid date. Otherwise, it returns IlFalse.

See also: setValue(struct tm*, IlBoolean), getValue(IlUShort&, IlUShort&, IlUShort&) const

§ getValue() [2/2]

IlBoolean IlvDateField::getValue	(	IlUShort &	day,
		IlUShort &	month,
		IlUShort &	year
	)		const

Returns the date stored in the date field.

Parameters

day	The returned day.
month	The returned month.
year	The returned year.

Returns: IlTrue if the field represents a valid date. Otherwise, it returns IlFalse.

See also: setValue(IlUShort, IlUShort, IlUShort, IlBoolean), getValue(struct tm*) const.

§ SetBaseCentury()

static void IlvDateField::SetBaseCentury ( int century )

static

Sets the base century used by the class IlvDateField.

If you use a two-digit value for the year element of the date (df_year), the full year will be recomputed from this base century and a century threshold (see GetCenturyThreshold). The base century indicates the century to be used when a two-digit year is entered, and whether this value is less than a specified threshold. For compatibility reasons, the default value for the base century is 1900. The century threshold indicates the value under which the century number will be incremented. For compatibility reasons, the default value of the century threshold is 0. If you set the base century to 1900 and the century threshold to 30, a value of 10 for the year is converted to 2010, a value of 30 is converted to 1930, and a value of 50 is converted to 1950.

Parameters

century The new base century. The default value is 1900.

See also: GetBaseCentury(), SetCenturyThreshold().

§ SetCenturyThreshold()

static void IlvDateField::SetCenturyThreshold ( int threshold )

static

Sets the century threshold used by the IlvDateField class.

For details, see SetBaseCentury().

Parameters

threshold The new century threshold.

See also: SetBaseCentury(), GetCenturyThreshold().

§ setFormat()

IlBoolean IlvDateField::setFormat	(	IlvDateFieldFormat	first,
		IlvDateFieldFormat	middle,
		IlvDateFieldFormat	last,
		char	separator,
		IlBoolean	redraw = `IlFalse`
	)

Sets the format of the date field.

A date is composed of three elements divided by separation characters. This member function specifies which element represents the day, the month, or the year and which separator to use. The default value is: 12/31/1995 (df_Month, df_Day, df_Year, see below). The formats are defined by the enumeration type IlvDateFieldFormat. If you change the format when the field contains a value, this value is applied the new format. Note the following:

Only a single day, year, or month format can be passed to this member function. Otherwise, the function returns IlFalse and the format remains unchanged.

Parameters

first	The first element of the date.
middle	The middle element of the date.
last	The last element of the date.
separator	The character used to separate each element of the date.
redraw	A Boolean value specifying whether the date field should be redrawn.

See also: getFormat(), IlvDateFieldFormat.

§ setFormatString()

IlBoolean IlvDateField::setFormatString ( const char * formatStr )

Sets the format of the date field.

The syntax of the format string is the same as the one used by getFormatString(). The separator character must be '/' (slash). Its value is used to parse the string and identify the different fields.

If a date part (day, month or year) is specified more than once, the format is considered to be invalid.

Parameters

formatStr A character string containing the new format.

Returns: IlTrue if formatStr is valid and can applied to the date field, IlFalse otherwise.

See also: getFormatString(), IlvDateFieldFormat.

§ setValue() [1/2]

void IlvDateField::setValue	(	struct tm *	date,
		IlBoolean	redraw = `IlFalse`
	)

Sets the date of the date field.

The date is converted to a string using the date field format.

Parameters

date	The new date.
redraw	A Boolean value specifying whether the date field should be redrawn.

See also: getValue(struct tm*) const, setValue(IlUShort, IlUShort, IlUShort, IlBoolean), setFormat().

§ setValue() [2/2]

void IlvDateField::setValue	(	IlUShort	day,
		IlUShort	month,
		IlUShort	year,
		IlBoolean	redraw = `IlFalse`
	)

Sets the date of the date field.

The date is converted to a string using the date field format.

Parameters

day	The new day.
month	The new month.
year	The new year.
redraw	A Boolean value specifying whether the date field should be redrawn.

See also: getValue(IlUShort&, IlUShort&, IlUShort&) const, setValue(struct tm*, IlBoolean).

§ validate()

virtual void IlvDateField::validate ( )

virtual

Is called by the interactor when the user presses the Return or the Enter key.

The default implementation invokes the main callback of the text field. If the method IlvTextField::getChangeFocusOnValidation() returns IlTrue, the keyboard focus moves to the next gadget in the focus chain.

See also: getChangeFocusOnValidation(), IlvGraphicHolder::setFocus().

Reimplemented from IlvTextField.

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Accessors

Member Enumeration Documentation

§ IlvDateFieldFormat

Constructor & Destructor Documentation

§ IlvDateField() [1/2]

§ IlvDateField() [2/2]

Member Function Documentation

§ check()

§ GetBaseCentury()

§ GetCenturyThreshold()

§ getFormat()

§ getFormatString()

§ getValue() [1/2]

§ getValue() [2/2]

§ SetBaseCentury()

§ SetCenturyThreshold()

§ setFormat()

§ setFormatString()

§ setValue() [1/2]

§ setValue() [2/2]

§ validate()