RSFieldControl

Материал из RSB-Doc
Перейти к: навигация, поиск

Содержание

Общие сведения

RSFieldControl — это визуальный ActiveX элемент, предназначеный для отображения и редактирования значения поля. RSFieldControl может использоваться как с источником данных RSCOMObjectCtrl (RSCOMObject), так и независимо от него.

Настройка поля

В простейшем случае для настройки FieldControl’а необходимо связать его с источником данных:

FieldSettings.jpg

Отвязанные поля

FieldControl может работать в двух режимах:

Свойства, доступные только в дизайнере.

Настройка выпадающего списка.

В зависимости от типа поля выпадающий список может принимать различный вид или его вообще может не быть. Например, если тип поля — классификатор, то в выпадающем списке будут отображаться данные того объекта, на который ссылается поле. Если тип поля — перечислитель, то в выпадающем списке будут отображаться значения перечислителя. Существует возможность изменить вид выпадающего списка. Выбор значений может осуществляться как из источника данных произвольного объекта так и из перечислителя.

Тип источника данных

Наименование

Имя контрола источника данных имя объекта из списка объектов или имя перечислителя. Заполняется после выбора типа источника данных

Отображаемое поле

Заполняется при типе источника данных равном «объект на форме» или «список объектов». Указывает поле источника данных, которое будет отображаться в FieldControl’е после выбора значения из выпадающего списка

Значимое поле

Заполняется при типе источника данных равном «объект на форме» или «список объектов». Указывает поле источника данных, которое будет присваиваться FieldControl’у после выбора значения из выпадающего списка

Горячие клавиши

Обработать Shift+Enter

По умолчанию вызывается обработчик события OptionClick. Если значение равно True, то можно обработать через событие KeyDown.

Свойства, доступные на этапе выполнения

Управление внешним видом

BackColor

Цвет фона. Учитывается только для необязательных полей. Заполняется по следующей формуле: RED + GREEN*256 + BLUE*65536, где компоненты цвета могут принимать значения в диапазоне 0..255

ForeColor

Цвет текста. Заполняется аналогично свойству BackColor

Font

Шрифт текста

AlignText

Выравнивание текста:

Для типа FT_Bool:

Enabled

Признак доступности окна. Если данное свойство установленно в FALSE, то окно блокируется

ReadOnly

Если этот флаг установлен в TRUE, то пользователь не сможет изменить значение поля

Required

Если этот флаг установлен в TRUE, то поле будет считаться обязательным для заполнения. Это повлияет только на его внешний вид

DropList

Признак разрешения ввода данны прямо в поле (TRUE) или только выбор значения из выпадающего списка (FALSE)

ExtendedChoice

Признак наличия кнопки расширения. Вид кнопки зависит от типа поля. Для полей типа перечислитель или полей-классификаторов будет отображаться кнопка выпадающего списка ExtendedChoice.JPG, для числовых полей — кнопки увеличения/уменьшения значения ExtendedChoice1.JPG. Для полей остальных типов будет отображаться кнопка выпадающего списка, но без какой бы то ни было реакции. При нажатии этой кнопки всегда вызовается обработчик события RunClientChoice

ExtendedOption

Признак наличия в поле опциональной кнопки ExtendedOption.JPG. Обычно используется для вызова справочника и последующего присвоения выбранного значения полю. При нажатии этой кнопки всегда вызовается обработчик события OptionClick

ExtendedClear

Признак наличия в поле кнопки очистки значения ExtendedClear.JPG.

PasswordMode

Режим пароля. Если флаг установлен в TRUE, то символы отображаются звездочками. Действительно для типа данных FT_String.

Настройка данных

RsObjectName

Имя контрола источника данных, к которому привязано поле. См. раздел «Настройка поля».

FieldName

Имя поля источника данных. См. раздел «Настройка поля».

Field

Ссылка на поле источника данных. См. раздел «Настройка поля».

FieldType

Тип данных в поле. Для FieldControl’ов, привязанных к источнику данных, заполняется автоматически. Заполнять это поле вручную нужно только для отвязанных полей.

Format

Формат данных в поле.

Для строковых полей могут использоваться следующие символы:

Для числовых полей могут использоваться следующие команды через точку с запятой (;) формата <команда>:<символ>:

AutoSave

Если этот флаг установлен в TRUE, то при изменении значения в FieldCtrl оно автоматически присваивается полю источника данных, к которому привязано поле. Без специального разрешения это свойство запрещено использовать, так как раньше в этом не было необходимости

SaveState

Признак сохранения значения отвязанного поля между сеансами работы с формой. Значение сохраняется в Application Data. См. описание свойства LabelField.

DetachValue

Признак отвязанного поля. FieldControl может быть привязан к источнику данных не только с целью редактирования поля источника данных, но и с целью наследования свойств поля источника данных (тип, обязательность, максимальная длина строки и т. д.). В таком режиме изменения в FieldControl’е не приводят к изменению значения поля источника данных. В данное время пользоваться этип свойством нет необходимости — можно просто установить тип поля без привязки к источнику данных. См. раздел «Отвязанные поля»

CheckNull

Возможность задавать Null-значения для поля с типом FT_Bool

Настройка выпадающего списка

EnumValues

Позволяет изменить список значений выпадающего списка для полей-перечислителей. Свойство имеет строковый тип со следующим форматом: «ЗНАЧЕНИЕ_ПОЛЯ=ОТОБРАЖАЕМОЕ_ЗНАЧЕНИЕ;…» ЗНАЧЕНИЕ_ПОЛЯ может быть как числом, так и строкой. См. описание метода AddEnumValue

TypeClassifer

Вид выпадающего списка (для полей-классификаторов):

ConditionValue

Фильтр, ограничивающий область значений поля. При попытке изменения значения поля осуществляется проверка допустимости установки нового значения согласно фильтру.

ConditionFreeValue

Фильтр, ограничивающий выбор значений из выпадающего списка поля. Заполняется при типе источника данных равном «объект на форме» или «список объектов».

Работа с данными

Value

Значение поля.

StringValue

Значение поля в виде строки.

WindowText

Текст, отображаемый окном FieldControl’а. Без специального разрешения это свойство запрещено использовать, так как раньше в этом практически не было необходимости.

ValueId

ID текущей записи в объекте выпадающего списка. Без специального разрешения это свойство запрещено использовать, так как раньше в этом практически не было необходимости.

Classifier

Возвращает ссылку на источник данных выпадающего списка поля.

SaveStateValue

Сохраненное между сеансами работы значение поля. Активно только при SaveState == true и доступно только для чтения.

CharArrayValue

Значение поля в виде массива кодов символов строкого значения.

Разное

LabelField

В данный момент используется только как строка, являющаяся контекстом при сохранении значения поля. Одна и та же форма может вызываться из разных мест и для каждого такого места может потребоваться сохранение различного значения. Это свойство должно задаваться до первого обращения к полю. См. описание свойства SaveState

LabelFieldText

Текст метки поля. Используется для установки подписи к полям типа BOOL.

LabelFieldAutoSize

Автоматическая установка подходящего размера для полей типа BOOL

Методы

DataExchange(Direction)

Производит обмен данными между FieldControl’ом и полем источника данных. Метод принимает один параметр — направление. По умолчанию в данный метод передается значение TRUE (присвоить FieldControl’у значение поля источника данных). Данный метод может использоваться в следующем случае: есть FieldControl, настроенный на источник данных. Значения FieldControl’а и поля источника данных совпадают. Далее происходит вызов серверного метода и значения некоторых поле объекта изменяются. Путем вызова данного метода можно обновить любые поля экранной формы, значения которых могли измениться

SetFreeDs(Object, DisplayedFieldName, FieldName)

Настройка выпадающего списка на этапе выполнения. Через параметр Object передается источник данных, через параметр DisplayedFieldName — отображаемое поле, FieldName — значимое поле. Для сброса списка следует присвоить параметру Object значение nullObj. См. раздел «Настройка выпадающего списка».

GetFreeDs

Возвращает источник данных выпадающего списка.

Refresh

Обновляет объект выпадающего списка поля.

AddEnumValue(ValueID, DisplayedValue)

Добавляет новое значение в список значений выпадающего списка для полей-перечислителей. См. описание свойства EnumValues. Через параметр ValueID передается значение поля, через параметр DisplayedValue — отображаемое значение.

DropDown

Отображает выпадающий список поля. Без специального разрешения этот метод запрещено использовать, так как раньше в этом не было необходимости.

События

RunClientChoice(Sender, ControlTop, ControlRight, ControlBottom, bInternal)

Обработчик нажатия кнопки расширенния ExtendedChoice.JPG. Используется для оптимизации. Можно создать для поля объект выпадающего списка или наложить фильтр на этапе создания формы, а более правильно — сделать это по первой необходимости, то есть при попытке пользователя выбрать значение.

InnerChanged(Sender)

Обработчик любого изменения данных внутри поля. Без специального разрешения это событие запрещено использовать, так как раньше в этом практически не было необходимости.

OptionClick(Sender, @Val)

Обработчик нажатия на опциональную кнопку ExtendedOption.JPG.

ConfirmValueChange(Sender, newVal, oldVal, @doChange)

Запрос на изменение значения. Через параметр newVal передается новое значение поля, через oldVal — старое. Если новое значение установить невозможно, то следует выдать сообщение об ошибке и присвоить параметру doChange значение FALSE.

ValueChanged(Sender)

Обработчик изменения значения поля.

NotFindFieldValue(Sender)

Событие возникает, когда FieldControl не может найти введенное вручную значение в связанном объекте. Без специального разрешения это событие запрещено использовать, так как раньше в этом не было необходимости

KeyDown(Sender,KeyCode,Shift,Handled)

Обработчик нажатия клавиши. Через параметр KeyCode передается код нажатой клавиши, а через параметр Shift — состояние служебных клавиш Alt, Ctrl, Shift. Параметр Handled - возвращаемый и по умолчанию равен FASLE. Если Handled установить в TRUE, то стандартный обработчик клавиши контролом вызываться не будет.

KeyUp(Sender, KeyCode, Shift)

Обработчик отпускания клавиши. Через параметр KeyCode передается код нажатой клавиши, а через параметр Shift — состояние служебных клавиш Alt, Ctrl, Shift.

KeyPress(Sender, KeyCode)

Обработчик удерживания клавиши.

KillFocus(Sender)

Обработчик потери фокуса. Использовать данное событие запрещено — в RS-Forms есть событие OnExit.

SetFocus(Sender)

Обработчик установки фокуса. Использовать данное событие запрещено — в RS-Forms есть событие OnEnter.

Особенности

Сохранение и восстановление значения отвязанных полей

Как было указано ранее, сохранение значения работает при установленном свойстве SaveState. Обычно это делается в дизайнере. Далее алгоритм работы следующий: сразу после загрузки формы (после выхода из обработчика OnLoad) поле начнет отрисовываться и восстановит свое сохраненное значение. После этого будет вызван обработчик события ValueChanged. Если таких полей на форме несколько, то порядок вызова обработчиков будет произвольным. Если такое недопустимо, то есть возможность восстановить сохраненное значение внутри обработчика OnLoad. Для этого нужно обратиться к значению поля.

Примеры

Обработка события OptionClick

]
 // Выбор записи из справочника и подставление значения в поле
 macro fldSourcDocumentKind_OptionClick (Sender: Object, Val: @Variant)
   FieldValueFromReference (null, @Val, "Виды документов");
 end;

Обработка события ConfirmValueChange

]
 macro fldDocument_ConfirmValueChange (Sender: Object, newVal: Variant, oldVal: Variant, doChange: @Bool)
   doChange = GetTrueEx ("Смена документа приведет к потере данных. Продолжить?");
 end;
 
 macro fldDocument_ValueChanged (Sender: Object)
  // Очищаем определенные поля и подобъекты
 end;

Обработка события RunClientChoice

]
 macro fldRelationRule_RunClientChoice (Sender       : Object, 
                                        ControlLeft  : Integer, 
                                        ControlTop   : Integer, 
                                        ControlRight : Integer, 
                                        ControlBottom: Integer, 
                                        bInternal    : @Bool)
   // Устанавливаем фильтр на выпадающий список до его отображения
   fldRelationRule.Classifier.Run ("SetFilter", GetRelationRulesFilter(true), true);
 end;
 
 var m_bInited = false;
 macro fldDocument_RunClientChoice (Sender       : Object, 
                                    ControlLeft  : Integer, 
                                    ControlTop   : Integer, 
                                    ControlRight : Integer, 
                                    ControlBottom: Integer, 
                                    bInternal    : @Bool)
   if (m_bInited)
     // Выпадающий список уже инициализирован
     return;
   end;
 
   m_bInited = true;
 
   // fldDocument – поле с типом GUID
   // Настраиваем выпадающий список поля
   // Будет отображаться список объектов с назначением “документ”
 
   fldDocument.SetFreeDs (GetDocumentList, "Наименование", "GUID");
 end;
Личные инструменты
Пространства имён
Варианты
Действия
Навигация
Для разработки
Инструменты