Компонент TUniEdit

Вернуться к оглавлению

Компонент представляется собой панель (наследник от TCustomPanel), на которой размещается редактирующий контрол с меткой.

Преимущества по сравнению с использованием обычных редактирующих компонент заключаются, прежде всего, в гибкости и упрощении поддержки ПО в течение цикла разработки: для изменения типа редактирующего элемента (например, при переходе от TEdit к TComboBox) нет необходимости удалять прежний компонент и создавать новый, достаточно сменить способ редактирования свойством EditKind.

Кроме того, наличие собственной панели (подложки) и собственной метки контрола значительно упрощает размещение множества редактирующих элементов на форме. Например, есть у стандартного TEdit такой недостаток, как отсутствие свойства Align, в TUniEdit оно устранено.

Данный набор компонентов используется в TFastListView в качестве редактирующих компонентов при редактировании ячеек.

Компонент разрабатывался для Delphi 5, но работает так же и в Delphi 6, и должен работать в Delphi 7. В более поздних версиях Delphi и его клонов не тестировался.

Подробное описание

Компонент предоставляет во вне модуля, помимо класса TUniEdit, так же и класс TUniSource, который может быть использован для получения данных из базы данных (по крайней мере, для этого он задумывался). Впрочем, эта функциональность практически почти никогда не требовалась. В отдельном модуле UniSource.pas имеется так же определение компонента TUniPic. По сути, это отдельный компонент, и он может использоваться самостоятельно, но был изготовлен специально для использования в TUniEdit и используется в нём для хранения и отображения пиктограммы, если она требуется (группа свойств PicXXXX). Кроме того, во время исполнения могут использоваться классы редактирующих контролов TEditAny, TEditPeriod, TEditNum и т.д. - отдельно от TUniEdit. Впрочем, самостоятельное их использование вряд ли имеет какие-то преимущества.

Преимущества использования TUniEdit для ввода даты по сравнению со стандартным TDateTimePicker (в режиме ввода Kind = ekEditDate):

• В случае, когда дата (свойства Value = DateTime) установлена в значение, численно меньшее 1 (т.е. 31 декабря 1899 года или меньше), в поле ввода отсутствует текст. Тем самым более явно для пользователя отображается отсутствие введенной даты;

• В случае, когда в пустом поле вызван календарь, по умолчанию устанавливается текущая дата, для восстановления значения в состояние "дата не присвоена" достаточно нажать клавишу Delete.

Первоначально компонент разрабатывался так, чтобы кнопки [...] и со стрелками (для ekEditPeriod) оказались визуально вписанными внутрь редактирующего элемента. Дело в том, что происходило это до того, как появился Windows XP с его темами и манифестом. В случае применения манифеста под темами XP внешний вид контролов TUniEdit оставался топорно-классическим, тем более что в качестве кнопок использоваться могли TBitBtn и TSpeedButton, несовместимые с манифестом тем XP. В новой версии эта проблема полностью устранена, в качестве кнопок используются наследники компонента TKnopka, полностью совместимые с манифестом, правда, вписывать их внутрь редактирующего элемента уже не получается. Если все еще есть необходимость использовать классический стиль и вписывание дополнительных кнопок как бы вовнутрь редактируемого поля, следует в проекте добавить символы INNER_BUTTONS и USE_STDBUTTONS. Дополнительное преимущество использования компонента TKnopka в качестве кнопок для стрелок - наличие свойство повторения срабатывания при удерживании кнопки в нажатом состоянии, позволяющее быстро перелистывать месяцы и годы в периоде, вместо того, чтобы делать это одиночными кликами.

 

TUniEdit

TUniSource

TUniPic

Свойства, события, методы класса TUniEdit, доступные в Инспекторе объектов и/или во время исполнения.

Хотя сам компонент TUniEdit произведён от TCustomPanel, его свойства, методы, события включают в себя свойства размещенного на нём редактирующего контрола. Чтобы не делегировать от редактирующего контрола все его свойства, существует свойство Control, через которое может быть получен (во время исполнения) собственно редактирующий контрол. Приводя его к соответствующему типу (например, TCombobox), можно получить доступ ко всем свойствам соответствующего контрола, при необходимости.

Синим цветом отмечены свойства, унаследованные от TCustomPanel и аналогичные свойствам стандартной панели TPanel,
а зелёным цветом отмечены свойства, принадлежащие редактирующему контролу. Обо всех таких свойствах подробную информацию можно найти в справке Delphi по соответствующим компонентам.

Публикуемые свойства (свойства, которые могут быть изменены Инспектором объектов в режиме дизайна формы).

Имя свойства	Тип	Начальное значение	Описание
Align	TAlign	alNone	Выравнивание контрола на родительском контроле на форме. В отличие от стандартных редактирующих контролов (TEdit, TCombobox, TCheckbox, TDateTimePicker), компонент TUniEdit может быть легко выровнен, что упрощает размещение большого числа редактирующих элементов на форме.
Anchors	TAnchors	[akLeft, akTop]
Autosize	Boolean	TRUE	Автоматическое вычисление размера контрола в зависимости от размеров редактирующего контрола, которые, в свою очередь, зависят от размера шрифта, взаимного размещения заголовка (Title) и редактирующего контрола (см. Layout), и от размера и местоположения используемой пиктограммы (если она используется).
BevelInner	TPanelBevel	bvNone
BevelOuter	TPanelBevel	bvNone
BevelWidth	Integer	1
BorderWidth	Integer	4	Ширина бордюра напрямую относится к размеру бордюра панели, являющейся предком компонента TUniEdit и использующейся как подложка для прочих содержащихся на ней визуальных компонентов (метки, пиктограммы и собственно редактирующего элемента). Задаёт взаимное расстояние между этими визуальными компонентами и расстояние от них до края контрола.
Checked	Boolean	FALSE	Данное свойство относится к редактирующему флажку TCheckbox, когда выбран режим редактирования Kind = ekCheck. Так же, данное свойство используется при режиме ekEditDate, когда предполагается использование флажка.
Color	TColor	clWindow	Цвет фона окна редактирующего элемента (не панели!).
ComboStyle	TComboBoxStyle	csDropDown	Только для режима Kind = ekCombo, задаёт стиль выпадающего списка. Допускается использование только стилей csDropDown и csDropDownList, прочие стили не тестировались! (Стиль csDropDownList следует выбрать, если требуется разрешить пользователю только выбирать один из элементов списка в качестве текущего, но запретить при этом редактировать содержимое с помощью клавиатуры - как обычно для TCombobox).
Constraints	TSizeConstraints
CurrencyCommaChar	Char	#0	Символ разделителя рублей и копеек при редактировании в режиме Kind = ekEditCurrency.
Cursor	TCursor	crDefault	Редактирующий контрол имеет свой собственный курсор. Обычно изменять его не требуется, поэтому такое свойство в TUniEdit не экспортируется (при необходимости используйте доступ к самому редактирующему контролу через свойство Control).
DateFormat	TDTDateFormat	dfShort	Формат даты для режима Kind = ekEditDate. Варианты см. в справке по стандартному компоненту TDateTimePicker.
DateTimeCheckbox	Boolean	FALSE	Используется в режиме Kind = ekEditDate, соответствует свойству TDateTimePicker.ShowCheckbox. В случае значения TRUE слева от поля редактирования размещается флажок, сброшенное состояние которого соответствует отсутствию какого-либо выбранного значения даты/времени. Существует более простой и наглядный способ визуального выбора состояния "дата не выбрана". Достаточно присвоить численное значение 0, соответствующее 31 декабря 1899 года, и в поле ввода даты текст не отображается. Программно проверить можно сравнив значение DateTime с единицей (если < 1, то дата не выбрана).
Digits	Integer	-1	Используется в режиме редактирования вещественных чисел Kind = ekEditFloat. Задаёт число десятичных знаков после вещественной запятой. В случае значения -1 число десятичных знаков не контролируется компонентом.
DroppedWidth	Integer	0	Используется в режиме комбо-списка Kind = ekCombo. Если не 0, то устанавливает ширину выпадающего списка в пикселях.
EllipsisButton	TEllipsisButton	ebNone	Задает наличие и тип дополнительной кнопки с многоточием на ней, размещаемой справа от редактирующего элемента. Для обработки нажатия этой кнопки имеется особое событие OnEllipsis. Возможные значения свойства EllipsisButton: ebNone - нет такой кнопки, ebNormal - обычная кнопка с возможностью фокусировки, ebSpeed - используется TSpeedButton, кнопка пользователю доступна только кликом мыши, и не фокусируется никаким способом, ebHidden - создаётся, но невидимый. Такой вариант может использоваться для выравнивания колонки из TUniEdit-контролов, выровненных свойством Align, в которой не все контролы имеют кнопку [...], в результате чего возникает рваный правый край. Автору известна проблема с обновлением внешнего вида TUniEdit в режиме дизайнера формы, особенно сильно проявляющаяся при включении/выключении этого свойства. Но он так ленив, что вместо того, чтобы разобраться и пофиксить проблему, предлагает обновить внешний вид контрола на разрабатываемой форме другими способами. Например, закрыть проект, и затем открыть его снова. Впрочем, от того, прорисована кнопка [...] во время разработки или нет, внешний вид контрола во время выполнения не зависит.
Enabled	Boolean	TRUE	Относится к редактирующему элементу, но влияет и на внешний вид надписи Title и всех дополнительных кнопок: в случае FALSE заголовок автоматически приобретает вид "недоступного". При этом становятся автоматически недоступны и все другие элементы, в том числе кнопка [...], при ее наличии.
ExitOnMaxLenExceed	Boolean	FALSE	При установке данного свойства в значение TRUE, при достижении максимального число символов при вводе значения, автоматически выполняется выход из контрола (с переходом к следующему контролу на форме в порядке табуляции).
FitAligned	Boolean	TRUE	По умолчанию, элементы на подложке размещаются так, чтобы занимать все свободное пространство (за исключением бордюра). Данное свойство может быть отключено (FALSE) для выровненного TUniEdit, в этом случае размеры редактирующего контрола далее не изменяются при изменении размеров самого TUniEdit. Для невыровненного контрола (Align = alNone) данное свойство игнорируется.
GrayReadOnly	Boolean	TRUE	По умолчанию, установка свойства ReadOnly = TRUE делает фон редактирующего элемента более тесным, как для режима Enabled = FALSE. Данное свойство предназначено для отключения  стандартного поведения (цвет фона сохраняется).
Height	Integer		Высота всего контрола, включая подложку и содержащиеся на ней визуальные элементы.
HelpContext	Integer	0
Hint	String		Текст всплывающей подсказки (работает на всех элементах контрола).
Items	TStrings		Данное свойство предназначено для редактора в режиме Kind = ekCombo, и позволяет на этапе дизайна формы задать первоначальный список элементов выпадающего списка. Во время исполнения, данное свойство так же доступно.
Kind	TEditKind	ekEdit	Задаёт тип редактирующего элемента. Возможные варианты: ekEdit - поле ввода текста, ekEditNum - поле ввода целого числа, ekEditFloat - поле ввода вещественного числа, ekEditCurrency - поле ввода денежных сумм, ekEditDate - поле ввода/выбора даты (и/или времени), ekEditPeriod - поле ввода/выбора периода, ekCombo - поле ввода/выбора элемента (выпадающего) списка, ekCheck - поле переключаемого флажка. Разумеется, данное свойство, как и все прочие, может быть изменено не только в Инспекторе объектов на этапе разработки, но и во время исполнения.
KindPeriod	TPeriodKind	pkMonth	Для режима Kind = ekPeriod, задаёт разновидность периода, который может быть выбран/отредактирован. Возможные варианты: pkMonth - месяц+год, pkDay - день+месяц+год, pkDecade - декада месяца (т.е. 1я, 2я или 3я часть месяца)+месяц+год, pkQuarter - квартал (I, II, III или IV)+год, pkYear - год, pkQuarterYear - целый год или квартал года+год (последний случай позволяет пользователю определить, имеется в виду весь год или только один квартал года, без дополнительных усилий со стороны программы).
Layout	TLabelPosition	lpLeft	Положение заголовка на подложке. Другое возможное значение: lpTop.
Left	Integer
ListField	String		Имя поля (результата запроса). Предназначено для автоматической загрузки значения из комонента TUniSource. Должно быть так же настроено свойство ListSource.
ListSource	TUniSource		Ссылка на компонент типа TUniSource, через который выполняется связь с таблицей базы данных или с результатами запроса для загрузки данных в поля для редактирования значений.
MaxLength	Integer	0	Максимальная длина редактируемой строки (Kind = ekEdit, ekCombo)
MaxValue	Double	0	Максимальное численное значение для режимов Kind = ekEditNum, ekEditFloat. Действует, если MaxValue <> 0 или MinValue <> 0.
MinValue	Double	0	Минимальное численное значение для режимов Kind = ekEditNum, ekEditFloat. Действует, если MaxValue <> 0 или MinValue <> 0.
OldComboWidth	Boolean	FALSE	Из-за несколько странного поведения стандартного комбо-списка, использующегося в режиме Kind = ekCombo, его размер устанавливается на пару пикселей шире, чтобы компенсировать кажущуюся невыровненность по правому краю (в сравнении с Kind=ekEdit, например). Данное свойство запрещает данную корректировку ширины, если она чем-то не устраивает. При использовании компонента TKnopka в качестве кнопок, которые более не "вписываются" (как бы) внутрь редактирующего элемента, данное свойство лучше не использовать.
PicAutoFit	Boolean	TRUE	В случае TRUE высота пиктограммы подбирается по размеру контрола, изображение при этом растягивается или сжимается.
PicAutoSize	Boolean	TRUE	Размер контейнера для пиктограммы выбирается от размера изображения. Данное свойство перекрывается свойством PicAutoFit, если то включено (TRUE).
PicCenterVertical	Boolean	TRUE	Если пиктограмма меньше того размера, в который ее вписывает контрол (по вертикали), то вместо растягивания ее размера в большую сторону картинка центрируется в контроле. Данный режим подходит для случая, когда само изображение в картинке (или его основная смысловая часть) расположена в центре своего прямоугольника, а по краям имеется много свободного пространства.
PicHeight	Integer		Высота пиктограммы, для программного управления при отключённых PicAutoFit и PicAutoSize.
PicImageIndex	Integer	0	Индекс иконки в списке PicImageList, когда назначен список.
PicImageList	TImageList		Список иконок, из которого берётся пиктограмма.
PicPicture	TPicture		Свойство для загрузки картинки напрямую, без использования PicImageList.
PicStretch	Boolean	TRUE	Растягивание изображения при несоответствии размера прямоугольника, занимаемого пиктограммой, и размером используемого изображения.
PicTransparent	Boolean	TRUE	При использовании PicPicture с растровым изображением типа TBitmap, использовать левый нижний пиксель в качестве цвета прозрачности.
PicWidth	Integer		Ширина пиктограммы, для программного управления при отключённых PicAutoFit и PicAutoSize.
ReadOnly	Boolean	FALSE	Только чтение - для редактирующего контрола в режимах ekEditXXXX, ekCombo, ekEditDate, ekEditPeriod.
StdImage	TStdImage		Выбор изображения из стандартных системных пиктограмм (иконок и битмапов). Работает, только если установлено свойство StdImgShowSize > 0. См. компонент TUniPic, который обеспечивает отрисовку.
StdImgShowSize	Integer	0	Значение > 0 включает изображение стандартной иконки, если не присвоены PicPicture и ImageList.
TabOrder	Integer		Порядок табуляции контрола (точнее, его панели подложки).
TabStop	Boolean	TRUE
Tag	Integer	0
Text	String		Содержимое редактирующего элемента во всех случаях. Для режиме Kind = ekCheck, это собственный заголовок флажка, расположенный справа от флажка.
Title	String		Заголовок, отображаемый рядом с редактирующим элементом (слева или сверху, в зависимости от значения Layout). Реализуется в виде метки.
TitleAlign	TAlignment	taLeftJustify	Выравнивание заголовка. В случае Layout = lpLeft имеет смысл, только если задан TitleWidth > 0 и больше ширины текста.
TitleWidth	Integer	0	Ширина поля заголовка. В случае 0 (значение по умолчанию) ширина подбирается по ширине заголовка (т.е. поведение эквивалентно такому, при котором для метки, представляющей заголовок, включено свойство Autosize=TRUE). Использование данного свойства позволяет аккуратно выровнять заголовки расположенных друг под другом TUniEdit- контролов.
Top	Integer
Value	Double	0	Числовое значение - для Kind = ekEditNum, ekEditFloat. Так же может использоваться для получения и присваивания значения во время исполнения для режимов Kind = ekEditDate, ekEditPeriod.
Visible	Boolean	TRUE
Width	Integer		Ширина подложки.

Публикуемые события (которые могут быть назначены или изменены Инспектором объектов в режиме дизайна формы).

Имя события	Параметры обработчика	Описание
OnChange	(Sender: TObject)	Вызывается, когда изменяется значение (Value, Text, Checked) редактирующего элемента.
OnCloseUp	(Sender: TObject)	Вызывается при скрытии выпадающего списка TCombobox-контрола (режим Kind = ekCombo)
OnDefaultDate	(Sender: TObject; var D: TDateTime)	Вызывается при выпадении календаря в режиме редактирования даты (ekEditDate), в случае, когда поле ввода было пустое (т.е. дата была 31 декабря 1899 г. или меньше, что считается "не присвоенным" состоянием и численно соответствует значениям меньше 1). Позволяет установить в качестве назначаемой даты, от которой начинается работа в календаре иную, нежели текущую дату.
OnDropDown	(Sender: TObject)	Вызывается при выпадении выпадающего списка TCombobox-контрола (режим Kind = ekCombo). Может использоваться программой для заполнения списка элементов непосредственно в момент выпадания).
OnEllipsis	(Sender: TObject)	Вызывается при нажатии на кнопку [...] (EllipsisButton = ebNormal или ebSpeed). Имеет смысл использовать эту кнопку для отображения расширенного диалога выбора значения, для которого проектируется отдельный диалог.
OnEnter	(Sender: TObject)	Вызывается при получении редактирующим контролом фокуса ввода.
OnKeyDown	(Sender: TObject; var Key: Word; Shift: TShiftState)	Позволяют обработать нажатия пользователем клавиш (редактирующий контрол - в фокусе ввода).
OnKeyPress	(Sender: TObject; var Key: Char)
OnKeyUp	(Sender: TObject; var Key: Char)
OnLeave	(Sender: TObject)	Вызывается при потере фокуса редактирующим контролом.
OnMouseDown	(Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer)	Позволяют обработать события мыши. Координаты заданы в клиентских координатах панели подложки, т.е. самого TUniEdit, а не лежащих на нём визуальных элементов.
OnMouseMove	(Sender: TObject; Shift: TShiftState; X, Y: Integer)
OnMouseUp	(Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer)
OnOutbound	( Sender: TObject; const OldText: String )	Вызывается при выходе значения за заданные границы MinValue и MaxValue. Старый текст, переданный в качестве параметра, может использоваться для восстановления прежнего значения.

Свойства и методы времени исполнения класса TUniEdit, доступные из программы (секция PUBLIC).

 Свойства класса TUniSource, доступные из Инспектора объектов (событий нет).

Компонент TUniSource разработан (на скорую руку), для того чтобы автоматизировать загрузку значений из TFastListView или из  и обратно по окончании редактирования. Использовался редко. Как позже выяснилось, TUniEdit хорош и без привлечения TUniSource. Редактирование полей базы данных напрямую редко когда требуется. Несколько чаще применимо редактирование строк таблицы TFastListView, хотя позже была добавлена возможность редактирование произвольных ячеек TFastListView, в результате и эта функциональность так же оказалась практически ненужной.
 

Имя свойства или декларация метода	Тип (свойства)	Описание
FastListView	TFastListView	Список типа TFastListView, из которого берутся и в который возвращаются отредактированные данные.
Name	String
Tag	Integer

 

Свойства и методы класса TUniSource, доступные во время выполнения.

Для компонента

Имя свойства или декларация метода	Тип (свойства)	Описание
LinkedUniEditCount	Integer	Количество контролов TUniEdit, присоединившихся к данному "источнику".
LinkedUniEditControls[ Idx: Integer ]	TUniEdit	Доступ к списку контролов, присоединившихся к данному "источнику".
FieldExists( const AFieldName: String )	:Boolean	Возвращает TRUE, если в исходном TFastListView есть колонка с таким именем поля или заголовком.
ListItemBeginEdit( LI: TFastListItem )		Инициирует начало редактирования содержимого строки LI таблицы TFastListView. До того, как начать редактирование, для всех присоединённых TUniEdit- контролов выполняется загрузка начальных значений данных из строки LI таблицы (вообще, списка, но поскольку он используется только в режиме lvsReport, выгляжит этот список именно как таблица).
ListItemEndEdit( LI: TFastListItem );		Завершает редактирование строки. Новые значения из всех TUniEdit записываются в строку (элемент) LI таблицы (списка) TFastListView.
function QueryInsert(const TableName: String; const MoreValues: Array of Variant; const MoreFields: String = ''; MoreParams: String = ''; const DoBefore: String = ''; const WhereConditions: String = ''): Integer		Позволяет сохранить содержимое всех прилинкованных TUniEdit в таблицу базы данных. Параметры MoreValues и MoreFields могут использоваться для того, чтобы одновременно записать в таблицу еще несколько полей, не редактировавшихся с помощью TUniEdit. Строка DoBefore - это часть запроса до самой вставки, строка WhereConditions присоединяется к формируемой строке справа (и обычно содержит какие-либо дополнительные условия). Возвращаемый результат - это числовой результат с индексом 0. Подразумевается, что WhereConditions содержит в качестве завершающего фрагмента запрос select @@IDENTITY или select @@ROWCOUNT. Если сформированный запрос не возвращает результат, возвращается значение -1. В случае, если результат NULL, возвращается 0.
function QueryInsert_Str(const TableName: String; const MoreValues: String = ''; const MoreFields: String = ''; const DoBefore: String = ''; const WhereConditions: String = ''; NeedIdentity: Boolean = TRUE): Integer		Аналогично предыдущему, но значения дополнительных полей сохраняются именно как строки (для чего могут быть использованы функции StrToSQL, DateToSQL и другие - из модуля UtilsUnit).
function QueryUpdate(const TableName: String; const MoreValues: array of Variant; MoreFields: String; MoreParams: String; const DoBefore, WhereConditions: String): Boolean;		Аналогично предыдущим функциям, но запись не добавляется в таблицу, а обновляется существующая.
function QueryUpdate_Str(const TableName: String; const MoreValues: array of Variant; MoreFields: String; MoreParams: String; const DoBefore, WhereConditions: String): Boolean;		То же, что и выше, но дополнительные поля передаются в виде строк.
AdjustRestrictions( UniSource: TUniSource; const TableName: String )		Данная глобальная процедура позволяет применить ограничения на размеры полей, на число знаков после десятичной запятой на основании описания типа данных в таблице в базе данных - для всех TUniEdit- контролов, прилинкованных к указанному TUniSource.

 

Свойства, события и методы класса TUniPic, доступные на этапе разработки (они так же доступны и во время исполнения).

TUniPic - это специальный компонент на базе TGraphicControl. По своим возможностям подобен стандартному TImage. Основное различие заключается в том, что пиктограмма может храниться не только в самом контроле, но и в заданном списке пиктограмм (TImageList), а так же выбираться из списка стандартных системных ресурсов по имени ресурса. Используется в компоненте TUniEdit для отображения пиктограммы контрола.

Синим цветом отмечены свойства, аналогичные таким же из подобного компонента TImage.