Calendar Control

Calendar Control, версия 2.5.
Автор Ал.В. Сариков.
Херсон, Украина, 2006 г.
E-mail: avix@ukrpost.net.
Сайт: http://avix.pp.ru.

Распространяется по лицензии BSD (см. файл LICENSE).

Наследован от: BControl
Объявлен в: CalendarControl.h
Библиотека: CalendarControl.a
Функции:  далее...


Контрол календаря (Calendar Control) позволяет работать с датами: вводить дату в поле ввода контрола или выбирать дату из календаря. Внешний вид раскрытого контрола (с интерфейсом BeOS) показан на рисунке.

Контрол работает с полной и краткой датой (год записывается полностью или только двумя последними цифами). В первом случае допустимыми являются даты от 1 января 0001 года до 31 декабря 9999 года. Во втором случае контрол принимает даты в пределах столетия, от 01 года столетия до 00 года или от 51 года столетия до 50 года следующего столетия (в зависимости от установленного в конструкторе флага начала столетия). Нумерация месяцев идет с 1 (январь).

Дата вводится в поле ввода как обычный текст (допускается ввод только цифр). Если дата введена некорректно (месяц больше 12, день больше 31 и т.д.), то она будет автоматически исправлена заменой всех неправильных значений на значения текущей системной даты.

Допускается выделение текста в поле ввода, копирование значения поля ввода или его части в Clipboard, удаление символов (вместо удаленного символа появляется 0). Вставка текста в поле ввода запрещена, т.к. это могло бы привести к некорректности даты в контроле.

Нажатие мышью на кнопку рядом с полем ввода даты (или нажатие на клавиатуре Ctrl+стрелка вниз) открывает календарь. Первоначально календарь содержит месяц и год, введенные в поле ввода. Введенный в поле ввода день на календаре заключается в синий прямоугольник.

Если месяц и год совпадают с месяцем и годом системной даты, то сегодняшний день пишется красным цветом.

Навигация по календарю осуществляется с помощью мыши или клавиатуры.

Нажатием мышью на стрелки (значки "<<" и ">>") возле месяца пользователь изменяет месяц. Нажатием на стрелки возле года - год.

Нажатие мышью на нижнюю строку с сегодняшней датой делает ее текущей в календаре (день, месяц, год). Окончательный выбор даты осуществляется нажатием мыши на нужном дне при установленном нужном годе и месяце. Выбранная дата помещается в поле ввода даты контрола.

При навигации с помощью клавиатуры используются клавиши-стрелки (перемещают по дням месяца либо увеличивают и уменьшают месяц и год, в зависимости от фокуса), клавиши Tab или Shift+Tab (изменяют фокус в окне), Enter или пробел (делают сегодняшнюю дату текущей или окончательно выбирают дату, в зависимости от фокуса), ESC или Ctrl+стрелка вверх (закрывают окно без выбора даты).

Снятие фокуса с календаря любым способом (нажатие мышью вне календаря, активизация другого окна какой-либо программы) приводит к его закрытию без помещения даты в поле ввода контрола.

История версий

Версия 1.0:

Версия 2.0:

Версия 2.1 (не была распространена):

Версия 2.5:


Конструктор и Деструктор


CalendarControl()

CalendarControl(BPoint p,
      const char *name,
      int day = 0,
      int month = 0,
      int year = 0,
      uint32 flags = CC_DD_MM_YYYY_FORMAT | CC_FULL_YEAR,
      uint32 look = CC_DOT_DIVIDER | CC_AUTO_INTERFACE)

Создает контрол календаря. Аргументы:

После создания контрола его следует присоединить к родителю (окну или BView) функцией AddChild() родителя.


~CalendarControl()

~CalendarControl()

Удаляет динамически созданные переменные класса.


Функции


GetDate()  см. SetDate()
GetFlags()  см. SetFlags()
GetLook()  см. SetLook()


GetYearRange()

void GetYearRange(int *first_year, int *last_year)

Возвращает в переменных first_year, last_year первый и последний годы, допустимые для использования в контроле (см. допустимые значения даты).


GetDate() , SetDate()

void GetDate(int *day, int *month, int *year)
void SetDate(int day = 0, int month = 0, int year = 0)
void SetDate(const char *tdate)

GetDate() возвращает дату, установленную в контроле. День, месяц, год даты записываются в переменные day, month, year.

SetDate() устанавливает дату в контроле согласно значениям параметров day, month, year либо строки tdate.

Во втором варианте функции SetDate() предполагается, что tdate - запись даты в текстовом виде с учетом флагов, установленных конструктором контрола и функцией SetFlags().

Если задаваемая для SetDate() дата некорректна, неверные день, месяц, год исправляются на значения текущей системной даты (при установленном флаге CC_SHORT_YEAR год отсчитывается в пределах допустимого столетия).

См. также: Text()


GetFlags() , SetFlags()

uint32 GetFlags(void)
void SetFlags(uint32 flags)

GetFlags() возвращает параметры даты как комбинацию констант формата даты, представления года (краткое или полное) и начала столетия.

Каждый из параметров в отдельности получается следующим способом:

if((GetFlags() & CC_MM_DD_YYYY_FORMAT) == CC_MM_DD_YYYY_FORMAT) // формат даты

if((GetFlags() & CC_SHORT_YEAR) == CC_SHORT_YEAR) // представление года

if((GetFlags() & CC_HALF_CENTURY) == CC_HALF_CENTURY) // начало столетия

Замечание: в приведенных выражениях вы не можете использовать константы CC_DD_MM_YYYY_FORMAT, CC_FULL_YEAR и CC_FULL_CENTURY после знака "&" (но можно после знака "=="), т.к. эти константы равны нулю и операция "&" даст в результате 0 вне зависимости от действительно установленных флагов.

SetFlags() устанавливает формат даты в контроле. Флаги представления года и начала столетия игнорируются.


GetLook() , SetLook()

uint32 GetLook(void)
void SetLook(uint32 look)

GetLook() возвращает параметры внешнего вида контрола как комбинацию разделителя элементов даты в контроле и флага интерфейса.

Каждый из параметров в отдельности получается следующим способом:

if((GetLook() & CC_ALL_DIVIDERS) == CC_DOT_DIVIDER) // разделители, после знака "==" ставится любой из разделителей

if((GetLook() & CC_ALL_INTERFACES) == CC_BEOS_INTERFACE) // интерфейсы, после знака "==" ставится любой из флагов интерфейса (см. замечание)

Замечание: возвращаемый флаг интерфейса принимает только значения CC_BEOS_INTERFACE и CC_ZETA_INTERFACE, т.е. флаг, определяющий внешний вид контрола в данный момент (даже если в конструкторе был задан CC_AUTO_INTERFACE). Информацию о допустимости использования флага CC_AUTO_INTERFACE (т.е. был ли задан соответствующий параметр при компиляции) можно получить, анализируя результат выполнения функции Version().

SetLook() устанавливает значение разделителя элементов даты в поле ввода даты контрола. Флаг интерфейса игнорируется.


Text()

const char *Text(void) const

Возвращает дату в контроле в виде текста, используя текущие формат, представление года и разделитель.


TextView()

BTextView *TextView(void) const

Возвращает указатель на объект BTextView, принадлежащий контролу, в котором происходит редактирование даты. Используйте этот результат только для чтения, иначе работа контрола может быть нарушена.


Version()

const char *Version(void)

Возвращает текстовую строку, описывающую версию и параметры компиляции библиотеки с контролом.


Константы


Форматы

Константа
CC_DD_MM_YYYY_FORMAT
CC_MM_DD_YYYY_FORMAT

Константы определяют формат даты в контроле (DD.MM.YYYY или MM.DD.YYYY).

См. также: SetFlags(), CalendarControl()


Представление года

Константа
CC_FULL_YEAR
CC_SHORT_YEAR

Константы задают число цифр в представлении года (DD.MM.YYYY или DD.MM.YY).

См. также: CalendarControl()


Начало столетия

Константа
CC_FULL_CENTURY
CC_HALF_CENTURY

Если год представлен двумя цифрами, то эти константы задают границы столетия, в пределах которого контрол принимает значения: либо с 01 года столетия до 00 года, либо с 51 года столетия до 50 года следующего столетия.

См. также: CalendarControl()


Разделители

Константа
CC_DOT_DIVIDER
CC_SLASH_DIVIDER
CC_MINUS_DIVIDER
CC_ALL_DIVIDERS

Первые три константы задают разделитель элементов даты (дня, месяца и года) в поле ввода даты контрола (DD.MM.YYYY, DD/MM/YYYY или DD-MM-YYYY).

CC_ALL_DIVIDERS используется для выделения разделителей из результата, возвращаемого функцией GetLook().

См. также: GetLook(), CalendarControl()


Интерфейс

Константа
CC_AUTO_INTERFACE
CC_BEOS_INTERFACE
CC_ZETA_INTERFACE
CC_ALL_INTERFACES

Первые три константы задают внешний вид (интерфейс) контрола (определяемый операционной системой, BeOS или Zeta). Интерфейс устанавливается при создании контрола, зависит также от параметров при компиляции (см. Compile.html).

CC_ALL_INTERFACES используется для выделения интерфейсов из результата, возвращаемого функцией GetLook().

См. также: GetLook(), CalendarControl()