From cc4b516aa015dd90e005e79d31d83ba2b79967b2 Mon Sep 17 00:00:00 2001 From: Jason Harris Date: Thu, 15 Sep 2005 01:09:54 +0000 Subject: [PATCH] Added API documentation for ExtDate[Time]Edit svn path=/trunk/KDE/kdeedu/libkdeedu/; revision=460743 --- extdate/extdatetimeedit.h | 219 +++++++++++++++++++++++++++++++++++++- 1 file changed, 215 insertions(+), 4 deletions(-) diff --git a/extdate/extdatetimeedit.h b/extdate/extdatetimeedit.h index 98b8d3a..65875e7 100644 --- a/extdate/extdatetimeedit.h +++ b/extdate/extdatetimeedit.h @@ -42,6 +42,7 @@ *The range of allowable values is (arbitrarily) set at +/- 2e7, *corresponding approximately to years +/- 55,000. * + *@see ExtDateTimeEdit *@author Jason Harris *@version 1.0 */ @@ -58,35 +59,160 @@ class ExtDateEdit : public QSpinBox { Q_OBJECT public: +/** + *@short Default constructor. Creates an ExtDateEdit displaying the + *given date. + *@p d the date to display (default is current system time) + *@p parent pointer to the parent widget (default: 0) + */ ExtDateEdit( const ExtDate &d = ExtDate::currentDate(), QWidget *parent = 0 ); +/** + *@short Constructor. Creates an ExtDateEdit displaying the + *given date. + * + *Differs from the above function only in the data type of its argument. + *@p jd the date to display (given as an integer representing the Julian Day) + *@p parent pointer to the parent widget (default: 0) + */ ExtDateEdit( int jd, QWidget *parent = 0 ); +/** + *@short Default destructor. Empty. + */ ~ExtDateEdit(); +/** + *@short Modifies the display date by the given number of steps. + * + *Checks to see which date field (Day/Month/Year) is highlighted, + *and modifies the highlighted value by the given number of steps. + *@note Overloaded from QAbstractSpinBox. + *@see activeField() + *@p d the date to display (default is current system time) + *@p parent pointer to the parent widget (default: 0) + */ void stepBy( int steps ); + +/** + *@short Ensures that the text is a valid ExtDate. + * + *@note Overloaded from QAbstractSpinBox; called internally by + *the baseclass. + *@p input reference to the text to be validated + *(typically the text displayed in the spinbox) + *@p pos the position in the string at which to begin checking + *@return QValidator::Acceptable if the string is a valid ExtDate; + *otherwise return QValidator::Invalid + */ QValidator::State validate( QString &input, int &pos ); +/** + *@return the internal ExtDate value + *@see setDate() + */ ExtDate date() const { return m_Date; } - void setDate( const ExtDate &d ) { m_Date = d; } +/** + *@short set the internal ExtDate value, and display the new + *date in the spinbox. + * + *@p d reference to the new ExtDate + *@see date() + */ + void setDate( const ExtDate &d ) { m_Date = d; setValue( m_Date.jd() ); } +/** + *@return the currently-active Date field (Day=0; Month=1; Year=2) + *@see setActiveField() + */ int activeField() const { return ActiveField; } +/** + *@short set the currently-active Date field (Day=0; Month=1; Year=2) + *@note This function does not change highlighting in the GUI; + *to sync the highlighting with the value of ActiveField, use + *highlightActiveField(). + */ void setActiveField( int i ) { ActiveField = i; } +/** + *@short highlight the currently-active Date field in the spinbox + */ void highlightActiveField(); - QString simpleDateFormat(); + +/** + *@short create a keyPressEvent, as if the given key had been pressed. + *@p k the Qt key value for which a keyPressEvent is to be simulated + *@see edLineEdit::keyPressEvent() + *@note (why isn't this in edLineEdit?) + */ void invokeKey( Qt::Key k ); protected: +/** + *@short convert the spinbox internal value (a Julian Day integer) + *to a date string to be displayed in the spinbox + *@p v the internal JD value to be converted. + *@note Overloaded from QSpinBox. Called internally. + *@see valueFromText() + */ QString textFromValue( int v ) const; + +/** + *@short convert the string displayed in the spinbox to its + *internal representation (a Julian Day integer) + *@p text reference to the date string to be converted to a JD integer + *@note Overloaded from QSpinBox. Called internally. + *@see textFromValue() + */ int valueFromText( const QString &text ) const; +/** + *@short Highlight the active Date field (Day/Month/Year) when the + *spinbox gains input focus. + *@p e pointer to the QFocusEvent object + *@note Overloaded from QSpinBox. Calls QSpinBox::focusInEvent(), and + *highlights the active date field. + *@see highlightActiveField() + */ void focusInEvent( QFocusEvent *e ); +/** + *@short Advance the active date field forward or backward. + * + *Changes the "active date field" to the next or previous date field. + *If already at the first or last field, then + *QSpinBox::focusNextPrevChild() is called, which will move input + *focus to the next/previous widget. + *@note Overloaded from QWidget. Called internally when Tab/Shift+Tab + *or Left/Right arrows are pressed. + *@p next if true, advance to the next field or widget. Otherwise, + *advance to the previous field or widget. + */ bool focusNextPrevChild(bool next); private slots: +/** + *@short Simply calls highlightActiveField() + *@note connected to the valueChanged() Signal, to make sure + *that highlighting is persistent. + */ void slotRefreshHighlight(); private: +/** + *@short Convert the KDE date format for internal use. + * + *The KDE date format string (e.g., "%Y-%m-%d" does not reflect the + *number of characters in the date string. Specifically, while + *we use a restricted subset of KDE formats that guarantees two-digit + *Day and Month fields, the number of digits in the Year field depends + *on the date being displayed. This function simply converts the date + *format string to one that reflects the correct number of digits + *(e.g., "YYYY-MM-DD"). + * + *This function is used internally to properly highlight the active + *field, and to process mouse and key events correctly. + */ + QString simpleDateFormat(); + uchar ActiveField; // 0==day; 1==month; 2==year ExtDate m_Date; QString m_DateFormat; @@ -103,29 +229,114 @@ class ExtDateTimeEdit : public QWidget { Q_OBJECT public: - ExtDateTimeEdit( const ExtDateTime &dt = ExtDateTime::currentDateTime(), QWidget *p=0 ); +/** + *@short Default Constructor. Displays the given Date and Time. + *@p dt reference to an ExtDateTime whose date and time values are + *to be displayed (defaults to the system's current date and time) + *@p p pointer to the parent widget (default: 0) + */ + ExtDateTimeEdit( const ExtDateTime &dt = ExtDateTime::currentDateTime(), +QWidget *p=0 ); + +/** + *@short Default Constructor. Displays the given Date and Time. + * + *This is essentially identical to the above function, differing only in + *the type of its arguments. + *@p d reference to an ExtDate which is to be displayed in the date box + *@p t reference to a QTime which is to be displayed in the time box + *@p p pointer to the parent widget (default: 0) + */ ExtDateTimeEdit( const ExtDate &d, const QTime &t, QWidget *p=0 ); + +/** + *@short Default Destructor. Empty. + */ ~ExtDateTimeEdit(); +/** + *@return the internal ExtDate value + *@see setDate() + */ ExtDate date() const { return m_DateEdit->date(); } +/** + *@short set the internal ExtDate value, and display the new + *date in the date spinbox. + * + *@p d reference to the new ExtDate + *@see date() + */ void setDate( const ExtDate &d ) { m_DateEdit->setDate( d ); } + +/** + *@return the internal QTime value + *@see setTime() + */ QTime time() const { return m_TimeEdit->time(); } +/** + *@short set the internal QTime value, and display the new + *time in the time spinbox. + * + *@p t reference to the new QTime + *@see time() + */ void setTime( const QTime &t ) { m_TimeEdit->setTime( t ); } + +/** + *@return the ExtDateTime value displayed in the date and time boxes + *@see setDateTime() + */ ExtDateTime dateTime() const { return ExtDateTime( date(), time() ); } - void setDateTime( const ExtDateTime &dt ) { setDate( dt.date() ); setTime( dt.time() ); } +/** + *@short set the internal ExtDate and QTime values, and display the new + *values in their respective spinboxes. + * + *@p dt reference to the new ExtDateTime + *@see dateTime() + */ + void setDateTime( const ExtDateTime &dt ) { setDate( dt.date() ); setTime( +dt.time() ); } private: QTimeEdit *m_TimeEdit; ExtDateEdit *m_DateEdit; }; +/** + *@class edLineEdit + *@short A QLineEdit adapted for use by ExtDateEdit. + * + *This class simply provides custom keyboard and mouse event handlers + *needed for the ExtDateEdit widget. + *@author Jason Harris + *@version 1.0 + */ class edLineEdit : public QLineEdit { public: +/** + *@short Default constructor. + *@p parent pointer to the parent widget; defaults to 0 + */ edLineEdit( QWidget *parent=0 ); +/** + *@short Default destructor. Empty. + */ ~edLineEdit() {} protected: +/** + *@short Set the active date field based on where in the date + *string the mouse was clicked. + */ void mouseReleaseEvent( QMouseEvent * ); +/** + *@short Handle arrow-key press events. + * + *Up/Down arrows call ExtDateEdit::stepBy(); + *Left/Right arrows invoke a key press of Shift+Tab/Tab, + *which automatically calls + *ExtDateEdit::focusNextPrevChild() + */ void keyPressEvent( QKeyEvent *e ); private: -- 2.47.3