Views
Gadgets Package API Reference Guide
Product Documentation:
Views Documentation Home
List of all members | Public Types | Public Member Functions | Static Public Member Functions
IlvDateField Class Reference

Gadget class. More...

#include <ilviews/gadgets/datfield.h>

Inheritance diagram for IlvDateField:
IlvTextField IlvGadget IlvSimpleGraphic IlvStylable IlvGraphic IlvValueInterface

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 IlvPoint &point, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
 Constructor. More...
 
 IlvDateField (IlvDisplay *display, const IlvRect &rect, 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 (IlUShort &day, IlUShort &month, IlUShort &year) const
 Returns the date stored in the date field. More...
 
IlBoolean getValue (struct tm *date) const
 Returns the date stored in the date field into a struct tm object. 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 (IlUShort day, IlUShort month, IlUShort year, IlBoolean redraw=IlFalse)
 Sets the date of the date field. More...
 
void setValue (struct tm *date, 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 (IlSymbol *callbackName)
 Adds a named Label Changed callback. More...
 
void addChangeCallback (IlSymbol *callbackName, IlAny arg)
 Adds a named Label Changed callback. More...
 
void addChangeCallback (IlvGraphicCallback callback)
 Adds a Label Changed callback. More...
 
void addChangeCallback (IlvGraphicCallback callback, IlAny arg)
 Adds a 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...
 
IlSymbolgetChangeCallbackName () 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 (IlSymbol *callbackName)
 Sets a named Label Changed callback. More...
 
void setChangeCallback (IlSymbol *callbackName, IlAny arg)
 Sets a named Label Changed callback. More...
 
void setChangeCallback (IlvGraphicCallback callback)
 Sets a Label Changed callback. More...
 
void setChangeCallback (IlvGraphicCallback callback, IlAny arg)
 Sets a 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 (IlFloat value, const char *format=0, IlBoolean redraw=IlFalse)
 Sets the text field label to a floating-point value. More...
 
void setValue (IlInt value, IlBoolean redraw=IlFalse)
 Sets the text field label to an integer 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\nAccessors provide a scriptable and uniform way to inspect and modify an object by using its base class methods <tt>IlvValueInterface::queryValue()</tt>, <tt>IlvValueInterface::queryValues()</tt>, <tt>IlvValueInterface::changeValue()</tt>, <tt>IlvValueInterface::changeValues()</tt>.\n\n\nThis class inherits the accessors of its superclass \c 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

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
displayThe connection to the display.
rectThe size and position of the date field.
thicknessThe thickness of the date field.
paletteThe 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
displayThe connection to the display.
pointThe position of the date field.
thicknessThe thickness of the date field.
paletteThe 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
characterThe 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
firstThe first element of the date.
middleThe middle element of the date.
lastThe last element of the date.
separatorThe 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 ( IlUShort day,
IlUShort month,
IlUShort year 
) const

Returns the date stored in the date field.

Parameters
dayThe returned day.
monthThe returned month.
yearThe 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.

◆ getValue() [2/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
dateThe 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

◆ 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
centuryThe 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
thresholdThe 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
firstThe first element of the date.
middleThe middle element of the date.
lastThe last element of the date.
separatorThe character used to separate each element of the date.
redrawA 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
formatStrA 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 ( 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
dayThe new day.
monthThe new month.
yearThe new year.
redrawA Boolean value specifying whether the date field should be redrawn.
See also
getValue(IlUShort&, IlUShort&, IlUShort&) const, setValue(struct tm*, IlBoolean).

◆ setValue() [2/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
dateThe new date.
redrawA Boolean value specifying whether the date field should be redrawn.
See also
getValue(struct tm*) const, setValue(IlUShort, IlUShort, IlUShort, IlBoolean), setFormat().

◆ 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.