TbtkScriptSelectionObject
''''''''''''''''''''''''''
.. pas:class:: TbtkScriptSelectionObject
Скриптовый класс реализует доступ к сущности **`Выборка`**.
Создание объекта этого класса приведет к созданию выборки без визуального отображения.
.. pas:method:: Controller(): TbtkScriptControllerObject
Возвращает объект класса :pas:class:`TbtkScriptControllerObject` по работе с GUI редактором выборки.
:rtype: TbtkScriptControllerObject
.. code-block:: delphi
:caption: Пример использования
If Assigned(Selection.Controller) then
begin
Selection.Controller.GroupsVisible := True;
Selection.Controller.GroupsAddField('sCaption');
Selection.Controller.GroupsAddField('sSystemName');
Selection.Controller.GroupsFullExpand;
end;
.. pas:attribute:: Form: TbtkScriptFormObject
Ссылка на объект формы данной выборки.
:rtype: TbtkScriptFormObject
.. pas:attribute:: OleContainer
Возвращает объект класса :pas:class:`TOleContainer`.
.. warning:: Не поддерживается в :term:`Application Server`
.. pas:attribute:: Id: String
Идентификатор выборки. Представляет собой, генерируемый клиентом,
уникальный идентификатор экземпляра выборки. Данный идентификатор
позволяет обращаться к конкретному экземпляру выборки, с помощью метода
``GetSelectionById``. Используется для организации взаимодействия между
различными экземплярами выборок.
:rtype: String
.. pas:method:: Change()
Вызов метода указывает форме, что данные на форме менялись, даже если
транзакция не была начата.
.. pas:method:: SetStyleControl(AttrName, StyleName: String)
Устанавливает для редактора атрибута *AttrName* стиль *StyleName*.
:param String AttrName:
Имя атрибута.
:param String StyleName:
Имя стиля.
.. pas:method:: GetStyleControl(AttrName: String): String
Возвращает имя стиля атрибута по имени атрибута *AttrName*.
:param String AttrName:
Имя атрибута.
:rtype: String
Настройка
......................................................................
.. pas:class::
.. pas:attribute:: DisplayName: String
Наименование выборки.
:rtype: String
.. pas:attribute:: Representation: String
Активное отображение выборки.
:rtype: String
.. pas:attribute:: EntityName: String
Системное имя выборки.
:rtype: String
.. pas:method:: GetHelpIndex(): Variant
Метод возвращает значение свойства **IDHELPNOTIONUNIT** выборки.
:rtype: Variant
.. pas:attribute:: Visible: Variant
Говорит о видимости фрейма, которому принадлежит выборка. Изменяя это
свойство вы будете изменять видимость фрейма.
:rtype: Variant
.. code-block:: delphi
:caption: Пример использования
//При обращении напрямую к объекту Selection не работает (Selection.Visible)
S:=FindSelectionEx('SEL_TST_DetailVisible',['Representation'],['Detail2']);
S.Visible:=not S.Visible;
.. pas:method:: GetPropertyValue(PropertyName: String): Variant
Возвращает значение свойства *PropertyName* выборки.
:param String PropertyName:
Имя свойства выборки.
:rtype: Variant
.. pas:method:: SetPropertyValue(PropertyName: String; PropertyValue: Variant)
Устанавливает значение *PropertyValue* свойству выборки *PropertyName*.
:param String PropertyName:
Имя свойства выборки.
:param Variant PropertyValue:
Значение свойства выборки.
.. versionchanged:: 1.26.0-ms17 Может устанавливать свойства фрейма. Имя свойства должно быть без префикса с именем фрейма.
.. pas:method:: GetAttributeVisible(AttrName: String): Boolean
Возвращает видимость атрибута *AttrName*.
:param String AttrName:
Видимость атрибута
:rtype: Boolean
.. pas:method:: SetAttributeVisible(AttrName: String; Flag: Boolean)
Устанавливает видимость атрибута.
Установка видимости атрибута не влияет на уже открытый датасет. Для
визуального изменения необходимо пересоздать фрейм, либо переоткрыть.
:param String AttrName:
Имя атрибута.
:param Boolean Flag:
Значение видимости атрибута.
.. pas:method:: SetAttributeProperty(AttributeName, PropertyName, PropertyValue: String)
Метод позволяет менять любое свойство атрибута выборки. Предполагается
использовать в операции ``OnLoadMeta`` для внесения изменений в метаданные
в процессе выполнения.
:param String AttributeName:
имя атрибута выборки
:param String PropertyName:
имя свойства
:param String PropertyValue:
новое значение свойство
.. code-block:: delphi
:caption: Пример использования
Selection.SetAttributeProperty('id', 'visible', '0');
.. pas:method:: ReloadAttrPresetMeta()
Метод перегружает метаданные сохраненных настроек выборки.
.. deprecated:: future
Поскольку пресеты выборки не используются, метод признан устаревшим.
Контекст/Параметры/Данные
......................................................................
.. pas:class::
.. pas:method:: ClientSetVar(Name: String; Value: Variant)
Процедура аналогично ``SetVar``, устанавливает значение атрибута
(параметра), но без вызова сеттера.
:param String Name:
Имя атрибута (параметра).
:param Variant Value:
Значение атрибута (параметра) *Name*.
.. pas:method:: SetVar(AttrName: String; Value: Variant)
Устанавливает значение атрибута (параметра).
:param String AttrName:
Имя атрибута.
:param Variant Value:
Значение атрибута.
.. seealso::
Подробнее о параметрах в :ref:`selection_params`
.. pas:method:: SetVarDesc(AttrName, Caption: String)
Задаёт заголовок атрибута.
.. attention::
Не рекомендуется использовать в циклах. Каждый вызов
может приводить к перестроению интерфейса.
Чтобы избежать потерь производительности следует использовать
:pas:func:`TbtkScriptSelectionObject.SetVarsDesc`.
:param String AttrName:
Имя атрибута.
:param String Caption:
Новое значение заголовка.
.. code-block:: delphi
:caption: Пример использования
Selection.SetVarDesc('Attr1', 'Атрибут1');
Selection.SetVarDesc('Attr2', 'Атрибут2|Банд-1|Супер-банд-1|Гига-банд-1');
Selection.SetVarDesc('Attr3', 'Атрибут3|Банд-2|Супер-банд-1|Гига-банд-1');
.. pas:method:: SetVarsDesc(AttrNames, Captions: Array)
Задаёт заголовки атрибутов.
.. note::
отличается от :pas:class:`TbtkScriptSelectionObject.SetVarDesc` тем, что принимает массивы имён и
значений и существенно снижает сопутствующие накладные расходы на
применение изменений в пользовательском интерфейсе.
:param Array AttrNames:
Массив имён атрибутов.
:param Array Captions:
Массив новых значений заголовков.
Каждое значение может содержать имена бандов вверх по иерархии,
разделённые символом "|".
.. pas:method:: VarExists(AttrName: String): Boolean
Проверяет существование атрибута(параметра) с заданным именем
AttrName.
:param String AttrName:
Имя атрибута(параметра).
:rtype: Boolean
.. pas:method:: GetSelfVar(VarName: String): Variant
Возвращает значение параметра выборки. В отличие от ``GetVar`` не смотрит
на выборку мастера , если не находит параметр *VarName* в текущей выборке.
С помощью данной ф-ии можно получить значения: атрибута выборки,
свойства фрейма, параметры добавленные с помощью ``AddVar``, свойства
фрейма, параметры добавленные при вызове ``CreateFormEx`` или ``DoLookUpEx``.
Если переменная не существует вернётся **null**.
:param String VarName:
Имя переменной.
:rtype: Variant
.. pas:method:: SelfVarExists(VarName: Variant): Boolean
Проверяет существование параметра выборки. В отличие от ``VarExists`` не
смотрит на выборку мастера, если не находит параметр *VarName* в текущей
выборке. С помощью данной ф-ии можно проверить существование: атрибута
выборки, свойства фрейма, параметры добавленные с помощью ``AddVar``,
свойства фрейма, параметры добавленные при вызове ``CreateFormEx`` или
``DoLookUpEx``.
:param Variant VarName:
Имя переменной.
:rtype: Boolean
.. pas:method:: GetVarDesc(AttrName: String): String
Получает описание атрибута *AttrName* (то, что отображается в заголовках
списка и т.п.)
:param String AttrName:
Имя атрибута.
:rtype: String
.. pas:method:: AddVar(Name: String; Value, Type: Variant; Persistence: TbtkPersistentType)
Добавляет параметр в выборку. Если параметр с таким именем уже
существуют, то изменяются тип данных, значение существующего параметра, и
значение свойства **Persistent**.
:param String Name:
Имя параметра.
:param Variant Value:
Значение параметра.
:param Variant Type:
Тип параметра.
:param TbtkPersistentType Persistence:
Указывает, является ли переменная "стойкой" (Persistent), и, если да, то
место, куда будет сохранено ее значение при закрытии выборки.
ptNone
по умолчанию. В этом случае, переменная не является "стойкой" (Persistent) будет удалена при закрытии выборки.
ptRegistry
Означает, что переменная является "стойкой", после
закрытии выборки ее значение будет сохранено в реестре приложения, а
при открытии выборки - восстановлено оттуда.
.. pas:method:: GetVar(AttrName: String): Variant
Возвращает значение атрибута (параметра) по имени атрибута *AttrName*.
:param String AttrName:
Имя атрибута.
:rtype: Variant
.. seealso::
Подробнее о параметрах в :ref:`selection_params`
.. pas:attribute:: LookUpParams: TbtkScriptLookUpParamsObject
Метод возвращает объект класса для доступа к locate параметрам выборки,
если выборка открывается через ``DoLookUp``.
:rtype: TbtkScriptLookUpParamsObject
.. pas:attribute:: CreateFormParams: TbtkScriptCreateFormParamsObj
Список параметров переданных в ``CreateFormEx`` при создание данного фрейма.
:rtype: TbtkScriptCreateFormParamsObj
.. code-block:: delphi
:caption: Пример использования
Result := '';
Count := Selection.CreateFormParams.Count;
Result := 'Количество параметров переданных при создание формы: ' + IntToStr(Count);
Result := Result + #13#10 + 'Параметры:' + #13#10;
for i := 0 to Count - 1 do
begin
Result := Result + '('+ IntToStr(i)+')' + 'Name:' + Selection.CreateFormParams.Names[i] + '; ' +
'Value:'+ VarToStr(Selection.CreateFormParams.Values[i]) + '; '+
'ValueByName:' + VarToStr(Selection.CreateFormParams.GetValueByName(Selection.CreateFormParams.Names[i])) + ';' + #13#10;
end;
ShowMessage(Result);
Blob, файлы
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class::
.. pas:method:: BlobOpen(FieldName, FileName: String; Wait: Boolean; Save: T3State): Boolean
Сохраняет данные из поля в файл и открывает для редактирования ассоциированным приложением.
После редактирования файла может сохранить данные обратно из файла в поле.
:param String FieldName:
Имя поля. Поле должно быть типа Blob.
:param String FileName:
Имя файла. В этот файл будет записано содержимое поля.
Возможные значения:
- Полный путь к файлу (например, *'C:\\Temp\\picture.jpg'*);
- Имя файла (например, *'picture.jpg'*) — в этом случае приложение попытается создать файл с
заданным именем и расширением во временном каталоге пользователя;
- Расширение файла (например, *'.jpg'*) — в этом случае приложение попытается создать файл с
уникальным именем и заданным расширением во временном каталоге пользователя.
:param Boolean Wait:
Ожидать завершение запущенного приложения перед дальнейшим выполнением скрипта.
:param T3State Save:
Сохранять содержимое файла обратно в поле после редактирования.
Имеет эффект только при **Wait** = **True**.
Возможные значения:
- stTrue — сохранять
- stFalse — не сохранять
- stUnknown — спросить у пользователя
:rtype: Boolean
:returns: Если файл был успешно сохранен в поле — **True**, в противном случае — **False**.
.. code-block:: delphi
:caption: Пример использования
fileName := GetVar('sCaption');
Selection.BlobOpen('blobFile', fileName, True, stTrue);
.. seealso::
:pas:meth:`TbtkScriptSelectionObject.BlobOpenEx`
:pas:meth:`TbtkScriptSelectionObject.BlobOpenEx2`
:ref:`work_with_files`
.. pas:method:: BlobOpenEx(FieldName, FileName: String; Selection: TbtkScriptSelectionObject; Operation: String; Mode: TbtkWatcherMode)
Сохраняет данные из поля в файл и открывает для редактирования ассоциированным приложением.
После редактирования файла вызывается операция.
Можно настроить режим определения окончания редактирования файла.
:param String FieldName:
Имя поля. Поле должно быть типа Blob.
:param String FileName:
Имя файла. В этот файл будет записано содержимое поля.
Возможные значения:
- Полный путь к файлу (например, *'C:\\Temp\\picture.jpg'*);
- Имя файла (например, *'picture.jpg'*) — в этом случае приложение попытается создать файл с
заданным именем и расширением во временном каталоге пользователя;
- Расширение файла (например, *'.jpg'*) — в этом случае приложение попытается создать файл с
уникальным именем и заданным расширением во временном каталоге пользователя.
:param TbtkScriptSelectionObject Selection:
Выборка с Callback-операцией.
:param String Operation:
Имя Callback-операции. Операция берётся из выборки **Selection** и вызывается только в случае,
если в результате редактирования изменился файл.
В операции доступны :ref:`параметры выборки `:
- EditedFileName: string — полное имя отредактированного файла
- FileChanged: boolean — был ли изменён документ
:param TbtkWatcherMode Mode:
Режим определения окончания редактирования файла.
.. note::
Если выборка **Selection** не задана, файл открывается в модальном режиме, его изменения не записываются.
Если выборка **Selection** задана, то файл открывается в немодальном режиме.
.. code-block:: delphi
:caption: Пример использования
path := InputBox('Введите путь к файлу', 'Файл:', '');
Selection.BlobOpenEx('blobFile', path, Selection, 'SendEmail', wmFile);
.. seealso::
:pas:meth:`TbtkScriptSelectionObject.BlobOpen`
:pas:meth:`TbtkScriptSelectionObject.BlobOpenEx2`
:ref:`work_with_files`
.. pas:method:: BlobOpenEx2(FieldName, Filename: String; Selection: TbtkScriptSelectionObject; Operation: String; Mode: TbtkWatcherMode; Modal, ExecOperOnClose: Boolean; ChoiseMode: TbtkFileChoiseMode)
Сохраняет данные из поля в файл и открывает для редактирования ассоциированным приложением, либо показывает диалог выбора приложения.
После редактирования файла вызывается операция.
Можно настроить режим определения окончания редактирования файла.
:param String FieldName:
Имя поля. Поле должно быть типа Blob.
:param String FileName:
Имя файла. В этот файл будет записано содержимое поля.
Возможные значения:
- Полный путь к файлу (например, *'C:\\Temp\\picture.jpg'*);
- Имя файла (например, *'picture.jpg'*) — в этом случае приложение попытается создать файл с
заданным именем и расширением во временном каталоге пользователя;
- Расширение файла (например, *'.jpg'*) — в этом случае приложение попытается создать файл с
уникальным именем и заданным расширением во временном каталоге пользователя.
:param TbtkScriptSelectionObject Selection:
Выборка с Callback-операцией.
:param String Operation:
Имя Callback-операции. Операция берётся из выборки **Selection** и вызывается в случае,
если в результате редактирования файл изменился, либо если параметр **ExecOperOnClose** = **True**.
В операции доступны :ref:`параметры выборки `:
- EditedFileName: string — полное имя отредактированного файла
- FileChanged: boolean — был ли изменён документ
:param TbtkWatcherMode Mode:
Режим определения окончания редактирования файла.
:param Boolean Modal:
Модальность открытия файла.
:param Boolean ExecOperOnClose:
Необязательный параметр.
Вызывать Callback-операцию независимо от того, изменился ли файл.
Значение по умолчанию: **False**.
:param TbtkFileChoiseMode ChoiseMode:
Необязательный параметр.
Режим выбора приложения для открытия файла.
Значение по умолчанию: **fcmByExtensionOrDialog**.
.. note::
Если при открытии используется режим открытия **wmFile**, то
могут возникать нюансы:
- Некоторые приложения занимают файл не сразу после вызова и нужно время
чтобы дать приложению открыться и занять файл. По умолчанию дается 15 секунд.
Если приложение заняло файл быстрее, чем за 15 секунд, то начинается отслеживание,
когда приложение освободит файл. Если же приложение не заняло файл, то через 15 секунд
будет вызвана операция-обработчик, извещающая о том, что работа с файлом завершена.
- Приложение может не занять файл, если открывает его в режиме только на чтение, так сделает,
например, MS Excel когда открывает потенциально опасный файл в защищенном режиме.
.. warning::
На ОС Windows 8+ метод может вызвать исключение *EbtkFileWatcherException*
в случае, если файл открыт средством просмотра документов (фотографий) в
модальном режиме или с CallBack-операцией. Шаблон обработки этого
исключения см. в примере ниже.
.. seealso::
:pas:meth:`TbtkScriptSelectionObject.BlobOpen`
:pas:meth:`TbtkScriptSelectionObject.BlobOpenEx`
:ref:`work_with_files`
.. code-block:: delphi
:caption: Пример использования
[out blobe]
begin select t.blobfile into :blob from btk_attach t where t.id = 2890001; end;
Selection.AddVar('blob', null, ftOraBlob);
ExecSQL('func');
try
Selection.BlobOpenEx2('blobe', GetTempFileName('','.doc'), Selection , '' ,wmAuto, true);
except
if not SameText(LastExceptionClassName, 'EbtkFileWatcherException') then
raise(LastExceptionMessage);
end;
Selection.SetVar('blobe', null); //Освободить память от блоба.
.. pas:method:: SaveToFile(FileName, FileText: String)
Вызывает диалог экспорта данных.
:param String FileName:
Имя файла.
:param String FileText:
Сохраняемый текст.
.. code-block:: delphi
:caption: Пример использования
[out sNotionReg]
begin
:sNotionReg := BTK_Loader.OutNotionToScriptText(:idNotion);
end;
begin
sRes := ExecSQLEx('save', 'idNotion; sNotionReg ', [ftInteger, ftString], [GetVar('id'), '']);
// возвращаемое значение sNotionReg находится в sRes[1].
// В sRes[0] находится передаваемый параметр idNotion.
SaveToFile('', sRes[1]);
end;
.. pas:method:: BlobToByteArray(byteArray: Variant): Variant
Переводит данные из массива байт в Blob. Необходимо для работы со
сторонними dll, например, с Ole-объектами.
:param Variant byteArray:
Данные в виде массива байт.
:rtype: Variant
.. code-block:: delphi
:caption: Пример использования
// метод LoadFromFileToBlob на самом деле возвращает AnsiString
blob := LoadFromFileToBlob('D:\...\blob.bmp');
byteArray := Selection.BlobToByteArray(blob);
// Выводим массив байтов
str := 'Размер = ' + IntToStr(Length(byteArray)) + #13#10 + 'Начинка = ';
for i := 0 to Length(byteArray)-1 do
begin
if (i mod 20 = 0) then
str := str + #13#10;
str := str + IntToStr(byteArray[i]) + ',';
end;
ShowMessage(str);
// Обратно в блоб
blob_revert := Selection.ByteArrayToBlob(byteArray);
// Записываем в клетку
Selection.SetVar('TestBlobAttr', blob_revert);
.. pas:method:: UploadFile(FieldName: String): String
Метод загружает файл с жёсткого диска пользователя в поле *FieldName*
типа :term:`Blob`. Возвращает полное имя загруженного файла. В случае отмены
действия возвращает пустую строку.
Выбор файла для загрузки выполняется с помощью диалогового окна
открытия файла.
:param String FieldName:
Имя поля.
:rtype: String
.. code-block:: delphi
:caption: Пример использования
fileName := Selection.UploadFile('blobFile');
if (fileName <> '') then
begin
Selection.SetVar('sCaption', ExtractFileName(fileName));
end;
Selection.DownloadFile('blobFile', GetVar('sCaption'));
.. pas:method:: DownloadFile(FieldName, FileName: String)
Метод сохраняет содержимое поля *FieldName* типа Blob, в файл на диске с
менем *FileName*. Возможны два случая поведения:
- если параметр *FileName* содержит полный путь к файлу, сохранение
происходит автоматически
- если *FileName* не задан, или равен пустой строке, или содержит
краткое имя файла, открывается диалог сохранения файла с возможностью
выбора директории и имени нового файла.
:param String FieldName:
Имя поля.
:param String FileName:
Имя файла.
.. code-block:: delphi
:caption: Пример использования
fileName := Selection.UploadFile('blobFile');
if (fileName <> '') then
begin
Selection.SetVar('sCaption', ExtractFileName(fileName));
end;
Selection.DownloadFile('blobFile', GetVar('sCaption'));
.. pas:method:: LoadFieldFromFile(FieldName, FileName: String)
Загружает данные из файла *FileName* в поле *FieldName* выборки.
:param String FieldName:
Имя поля.
:param String FileName:
Имя файла.
.. note::
* Для загрузки файлов из файловой системы пользователя необходим установленный :ref:`плагин Gs3-browser-cmd `.
Если плагин не установлен:
- Если перед вызовом `LoadFieldFromFile` вызывался `AskFileNameForOpen` или `AskFileNamesForOpen` и указано выбранное имя файла,
то загружается ранее выбранный файл.
- В иных случаях откроется диалоговое окно для выбора файла, а загрузка будет выполнена через UploadManager.
* Для поддержки операций Drag-and-drop и Ctrl+V с файлами:
- При указании полного пути к файлу во временном каталоге на сервере, будет использован указанный файл.
.. seealso::
* :pas:meth:`LoadTextFromFile`
* :pas:meth:`LoadFromFileToBlob`
* :pas:meth:`LoadFromFile`
.. pas:method:: SaveFieldToFile(FieldName, FileName: String)
Выгружает данные из поля *FieldName* выборки в файл *FileName*.
:param String FieldName:
Имя поля выборки.
:param String FileName:
Имя файла.
.. note::
* Сохранение в файловой системе пользователя происходит только при наличии установленного :term:`плагина <Плагин>`. Если плагин отсутствует - произойдет сохранение файла через загрузчик бразуера.
.. seealso::
* :pas:meth:`SaveToFile`
* :pas:meth:`SaveTextToFile`
* :pas:meth:`SaveBlobToFile`
.. pas:method:: ByteArrayToBlob(): String
Конвертирует массив байт в блоб.
:rtype: String
.. code-block:: delphi
:caption: Пример использования
// метод LoadFromFileToBlob на самом деле возвращает AnsiString
blob := LoadFromFileToBlob('D:\...\blob.bmp');
byteArray := Selection.BlobToByteArray(blob);
// Выводим массив байтов
str := 'Размер = ' + IntToStr(Length(byteArray)) + #13#10 + 'Начинка = ';
for i := 0 to Length(byteArray)-1 do
begin
if (i mod 20 = 0) then
str := str + #13#10;
str := str + IntToStr(byteArray[i]) + ',';
end;
ShowMessage(str);
// Обратно в блоб
blob_revert := Selection.ByteArrayToBlob(byteArray);
// Записываем в клетку
Selection.SetVar('TestBlobAttr', blob_revert);
.. pas:method:: CreateLobLocator(): TbtkScriptOraLobLocator
Создаёт объект локатора привязанный к сессии данной выборки.
:rtype: TbtkScriptOraLobLocator
.. seealso::
:ref:`lob_locator`
.. warning:: Не реализовано
Утилиты
......................................................................
.. pas:class::
.. pas:method:: ExportToAccess(FileName, TableName: String; Overwrite: Boolean)
Метод экспортирует выборку в таблицу базы данных Access. Если файл базы
данных *FileName* не существует, то база данных будет создана с указанным
именем.
:param String FileName:
Имя файла базы данных Access.
:param String TableName:
Имя таблицы в которую надо выполнить экспорт. Таблица будет создана если
не существует. Если таблица уже существует в базе данных, то если флаг
*Overwrite* равен **False** будет возбуждено исключение. Если же *Overwrite*
равен **True** то таблица будет пересоздана.
:param Boolean Overwrite:
Параметр определяет действие которое будет выполнено если экспорт
происходит в уже существующую таблицу БД.
True
таблица будет пересоздана
False
будет возбуждено исключение.
.. pas:method:: ApplySelectionPreset(Name: String)
Заполняет значения текущей строки выборки значениями указанной
сохраненной настройки
:param String Name:
Системное имя сохраненной настройки выборки
.. warning:: Не реализовано
Мастер-деталь
......................................................................
.. pas:class::
.. pas:method:: RefreshDep(ParamName: String)
Обновляет все детали зависимые от указанного параметра выборки.
:param String ParamName:
Имя параметра.
.. pas:method:: LockRefreshDep(): TbtkScriptUnlockable
Блокирует реакцию на изменение :term:`параметров GST<Параметр GST>` и
выполнение :term:`CWA` выборки (и каждой её детали).
:rtype: TbtkScriptUnlockable
:returns: Объект описывающий установленную блокировку.
Блокировок может быть установлено несколько. Выборка будет считаться разблокированной
когда будут сняты все блокировки на неё установленные. Возвращаемый
:pas:class:`TbtkScriptUnlockable` соответствует единственной блокировке, установленной
вернувшим его вызовом ``LockRefreshDep``.
Пропущенные в результате блокировок :term:`CWA` будут выполнены при разблокировке выборки.
.. code-block:: pascal
{$IF DesktopVer >= 5.5.0.4045}
depLock := Selection.LockRefreshDep;
try
SetVar('ID', 100500);
finally
depLock.Unlock;
end;
{$Else}
Selection.LockRefreshDep;
try
SetVar('ID', 100500);
finally
Selection.UnlockRefreshDep;
end;
{$EndIf}
.. pas:method:: UnLockRefreshDep()
Снимает блокировку реакции выборки на изменение :term:`параметров GST<Параметр GST>`,
установленную методом :pas:func:`LockRefreshDep`.
.. warning::
Метод работает парно с :pas:func:`LockRefreshDep`, и только в рамках одной операции.
- Если возникает необходимость блокировать в одной операции, а разблокировать
в другой - в первую очередь, следует переосмыслить подход, т.к. он заведомо не даёт
гарантированного результата и рискует привести к недетерминированности реализованных
алгоритмов.
- Если описанная необходимость всё же остаётся - следует использовать `новый` подход, с
использованием :pas:class:`объекта блокировки ` - его можно
передать в другую операцию, и там уже разблокировать.
.. deprecated:: Global 5.5.0.4045
Вместо данного метода следует использовать :pas:func:`TbtkScriptUnlockable.Unlock`,
объекта возвращаемого методом :pas:func:`LockRefreshDep`.
Метод ``UnLockRefreshDep`` неявно обращается к
:pas:class:`объекту блокировки `, созданному для данной выборки
в течение времени выполнения текущей операции. Из чего следует, что блокировка и
разблокировка должны выполняться в рамках одной операции (прим.: и с использованием
конструкции ``try/finally``).
.. pas:method:: AddDependency(ParamName: String)
Метод позволяет добавить зависимость детальной выборки от *ParamName* -
атрибута мастер-выборки. При изменении указанного атрибута мастер
выборки, будет выполнено обновление детальной выборки. Данный метод
позволяет связать деталь и мастер, даже если в ``GetSQLText`` детальной
выборки нет внешнего ключа и если нельзя использовать "Super$" префикс
из-за ограничения на длину имени параметра в 30 символов.
:param String ParamName:
Имя атрибута мастера.
.. code-block:: delphi
:caption: Пример использования
Selection.AddDependency('Super$Super$Super$id');
.. pas:method:: RefreshDetails()
Метод обновляет активные(открытые) детали находящиеся на одной форме с
мастером(мастер-выборкой), при этом мастер не обновляется. Выборки табов также не обновляются.
.. pas:attribute:: IgnoreParamChange: Boolean
Не обновлять выборку при изменении super$ параметров.
:rtype: Boolean
.. seealso:: Свойство выборки :btk:selprop:`IgnoreParamChange`.
.. pas:attribute:: Master: TbtkScriptSelectionObject
Мастер-выборка для текущей выборки.
:rtype: TbtkScriptSelectionObject
.. code-block:: delphi
:caption: Пример использования
Sel := Selection;
M := Sel.Master;
.. pas:method:: CWADetails()
Метод выполняет операцию ``CheckWorkability`` у всех детальных выборок на
текущей форме
Операции
......................................................................
Настройки
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class::
.. pas:attribute:: Operations
Дальше можно писать операцию
.. pas:method:: SetOperationImageIndex(OpName: String; ImageIndex: Integer)
Устанавливает операции с именем *OpName* иконку с номером *ImageIndex*.
:param String OpName:
Имя операции.
:param Integer ImageIndex:
Номер иконки.
.. pas:attribute:: OperationOptions: TbtkScriptOperationOptionsObject
Свойство предоставляющее доступ к опциям операций выборки.
:rtype: TbtkScriptOperationOptionsObject
.. pas:method:: SetCustomDisable(OpName: String; Flag: Boolean)
Метод запрещает или разрешает действие по его имени.
.. deprecated:: Global 5.0.0
Следует использовать :pas:meth:`TbtkScriptOperationOptionsObject.SetCustomDisabled`.
:param String OpName:
Имя действия.
:param Boolean Flag:
Значение активности операции.
.. pas:method:: SetAdmDisable(AdmActionName: String; Flag: Boolean)
Метод запрещает или разрешает операции по системному имени
сопоставленного администрирующего действия.
:param String AdmActionName:
Название административного действия (otInsertItem, otDeleteItem и др.).
:param Boolean Flag:
Флаг - разрешить или запретить действие *AdmActionName*.
.. pas:method:: SetCustomInactive(OpName: String; Flag: Boolean)
Метод предназначен для управления видимостью пользовательской операции. Т.е. после вызова ``Selection.SetCustomInactive('MyOperation', true);`` операция исчезнет с панели управления и из меню.
:param String OpName:
Имя операции.
:param Boolean Flag:
Значение активности операции.
.. note::
Для сохранения обратной совместимости реализовано следующее поведение: при вызове ``SetCustomInactive`` с флагом ``False``, если операция изначально пришла из метаданных неактивной (со значением свойства "Флаг активности операции" равным ``False``), то она активируется. Такое поведение актуально только для неархивного режима загрузки метаданных, т.к. в архивном режиме неактивные операции не высылаются на клиент.
.. attention::
Существует ограничение на использование данного метода: метод нельзя
использовать в операциях, которые выполняются вследствие нажатия на
кнопку панели управления. Ограничение актуально для случая, когда метод активирует изначально неактивную операцию.
.. deprecated:: Global 5.5.0
Следует использовать :pas:meth:`TbtkScriptOperationOptionsObject.SetCustomInactive`.
Другое
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class::
.. pas:method:: Operation(): TbtkScriptOperationObject
Текущая выполняемая операция.
:rtype: TbtkScriptOperationObject
.. pas:method:: FindOperation(OpName: String): TbtkScriptOperationObject
Возвращает операцию по *OpName*, если операция не найдена, то возвращает
**nil**.
:param String OpName:
Системное имя операции.
:rtype: TbtkScriptOperationObject
.. pas:method:: OperationByName(OpName: String): TbtkScriptOperationObject
Возвращает операцию по имени *OpName*, если таковая не существует, то
генерируется исключение
:param String OpName:
Имя операции.
:rtype: TbtkScriptOperationObject
.. pas:method:: ExecOperationText(Text: String; Arguments: Array; MarkType: TbtkOperationTextMarkupType)
Метод позволяет выполнить динамически сформированный текст операции. При
вызове метода будет создана и выполнена временная операция с текстом,
переданным через параметр *Text*. По сути метод аналогичен методу
``ExecOpScript``, в который передаётся имя операции.
:param String Text:
Текст операции, который необходимо выполнить.
:param Array Arguments:
Параметры скрипта.
:param TbtkOperationTextMarkupType MarkType:
Тип разметки скрипта. По-умолчанию otmtAutoDetect.
.. code-block:: delphi
:caption: Пример использования
OpText := '' + #13#10 +
'ShowMessage(''Сообщение из метода ExecOperationText'');' + #13#10 +
'';
Selection.ExecOperationText(OpText);
.. pas:method:: ExecOpScript(OpName: String)
Выполняет операцию *OpName* выборки.
:param String OpName:
Имя операции в текущей выборки.
.. pas:method:: ExecOpScript(OpName: String, Args: Array)
Выполняет операцию *OpName* выборки.
:param String OpName:
Имя операции в текущей выборки.
:param Array Args:
Аргументы вызываемой операции
.. pas:method:: AsyncExecOperationText(Text: String; MarkType: TbtkOperationTextMarkupType)
Метод позволяет асинхронно выполнить динамически сформированный текст
операции. При вызове метода будет создана и выполнена временная операция
с текстом, который был передан *Text*.
:param String Text:
Текст операции, который необходимо выполнить.
:param TbtkOperationTextMarkupType MarkType:
Тип разметки скрипта. По-умолчанию otmtAutoDetect.
.. code-block:: delphi
:caption: Пример использования
var
s: string;
begin
s := '' + #13#10 +
'ShowMessage(''Сообщение из операции #AsyncExectSQLOprtnTxt''); ' + #13#10 +
'';
selection.AsyncExecOperationText(s);
end;
.. pas:method:: AsyncExecOpScript(OperationName: String)
Асинхронный вызов операции. "Асинхронный" в данном случае не означает
что операция начнёт выполняться параллельно - операция будет выполнена
по факту завершения выполнения всех выполняющихся на данный момент
операций; более корректно считать такое выполнение "Отложенным". Метод
позволяет выполнить действия вне текущего контекста работы, это
позволяет гарантировать что они никаким образом не повлияют на текущее
выполнение.
:param String OperationName:
Имя операции.
.. code-block:: delphi
:caption: Пример использования
S := Selection.Master; //находим выборку-список
S.PriorRecord;
if {здесь определяем, что нужно будет сменить карточку} then
begin
S.AddVar('UseActiveForm', 1, ftInteger); //имя переменной может быть любым
S.AsyncExecOpScript('CardEdit'); // операция открытия карточки запускается асинхронно
end
else
Selection.Refresh;
// В выборке-списке в операции открытия карточки пишется:
// CreateFormEx(...['UseActiveForm'],[GetVar(UseActiveForm)]);
// AddVar('UseActiveForm', 0);
.. pas:method:: UpdateMultiplicatingOperations(OpNames: array of string)
Обновляет клонируемые операции.
:param OpNames:
Необязательный параметр.
Массив имен клонируемых операций, которые нужно обновить.
Если не задан, будут обновлены все клонируемые операции.
:type OpNames: array of string
.. code-block:: delphi
:caption: Пример использования
Selection.UpdateMultiplicatingOperations(['clnOper1', 'clnOper2']);
S := Application.MainSelection;
if Assigned(S) then
S.UpdateMultiplicatingOperations;
.. pas:method:: GetEditButtonName(): String
На нажатие на кнопку вызывается сеттер атрибута с типом *etEditButton*.
Внутри сеттера с помощью метода ``Selection.GetEditButtonName`` можно получить строку с системным именем нажатой кнопки.
:rtype: String
.. pas:method:: UserActionType(): TbtkUserActionType
Метод позволяет определить, куда попадёт фокус ввода после выполнения
сеттера.
:rtype: TbtkUserActionType
.. warning:: Не реализовано
.. pas:method:: SetterExecType(): Variant
Метод позволяет определить в результате, какого действия был вызван
сеттер Вызывать метод можно только внутри сеттера. Поскольку результат,
возвращаемый функцией, актуален только внутри выполняемого сеттера. После
вставки таблицы (массового обновления) происходит выполнение операции,
указанной в свойстве фрейма: *OnAfterBulkUpdate* – «Операция, выполняемая
после массового обновления»
:rtype: Variant
.. code-block:: delphi
:caption: Пример использования
case Selection.SetterExecType of
etUnknown: ShowMessage('Непонятно откуда');
etEditBtn: ShowMessage('Кнопка EditBtn');
etClearBtn: ShowMessage('Кнопка ClearBtn');
etManual: ShowMessage('Ручной ввод');
etSetVar: ShowMessage('SetVar');
etExecOp: ShowMessage('Операция');
etBulkUpdate: ShowMessage('Вставка из буфера обмена');
end;
Selection.ExecOpScript('#SetIDUniFilterRefClass1');
SQL
......................................................................
.. pas:class::
.. pas:method:: ExecSQL(BlockName: String)
Метод выполняет PL/SQL-блок *BlockName*, объявленный в текущей операции.
:param String BlockName:
Имя блока
.. code-block:: delphi
:caption: Пример использования
[Out cost]
begin
select price into :cost
from table
where code = :id;
end;
ExecSQL('GetCost');
value := GetVar('Cost');
ShowMessage(IntToStr(Value * 10));
.. note::
Если в PL\SQL блоке используется параметр, который отсутствует в выборке,
то он считается пустым параметром типа 'ftString' размером 4000 символов (максимум varchar2).
.. attention::
При использовании входящих параметров типа 'ftString' под них в базе выделяется память размером с длину строки. Соответственно, если в PL\SQL блоке в такой параметр попробовать записать строку большей длины,
чем было в значении параметра изначально, то вылетит ошибка "ORA-06502: PL/SQL: numeric or value error: character string buffer too small".
Если в значении такого параметра изначально пустая строка (либо 'null'), то под него выделится память на 4000 символов (максимум varchar2).
.. pas:method:: ExecSQLEx(BlockName, ParamNames: String; ParamTypes, ParamValues: Array): Array
Метод выполняет PL/SQL-блок *BlockName*, объявленный в текущей операции,
с возможностью передавать в SQL-блок дополнительные, не участвующие в
контексте выборки параметры, а также возвращать их. Имена входящих
параметров задаются в *ParamNames* через точку с запятой. В тексте
SQL-запроса можно использовать не только передаваемые в *ParamNames*
параметры, но и использовать параметры, имеющиеся в выборке. В случае
совпадения имен параметров, будет использоваться параметр, переданный в
вызове ``ExecSQLEx``. Возвращает массив значений параметров, указанных в
*ParamNames*, в том порядке, в котором они перечислены в *ParamNames*. Если
возвращаемый параметр участвует в секции *[OUT]* sql-запроса, то будет
возвращено его новое значение. Если не участвует, то будет возвращено то
значение, которое передавалось в *ParamValues*. Если входящих параметров
нет, то можно передавать ``ParamNames = ''`` и ``ParamValues = []``. Количество
параметров должно совпадать с количеством типов и с количеством
значений. Все параметры являются входящими и могут являться
возвращаемыми.
:param String BlockName:
Имя PL\\SQLsql-блока.
:param String ParamNames:
Имена входящих параметров, разделенные точкой с запятой.
:param Array ParamTypes:
Массив типов параметров в формате: ``[тип1, тип2, …]`` Доступные константы
типов параметров:
- :pas:class:`~TFieldType.ftString`
- :pas:class:`~TFieldType.ftInteger`
- :pas:class:`~TFieldType.ftFloat`
- :pas:class:`~TFieldType.ftDateTime`
- :pas:class:`~TFieldType.ftOraBlob`
- :pas:class:`~TFieldType.ftOraClob`
- :pas:class:`~TFieldType.ftWideString`
- :pas:class:`~TFieldType.ftWideMemo`
:param Array ParamValues:
Массив значений параметров в формате: ``[значение1, значение2]``.
:rtype: Array
.. code-block:: delphi
:caption: Пример использования
[out sNotionReg]
begin
:sNotionReg := BTK_Loader.OutNotionToScriptText(:idNotion);
end;
begin
sRes := ExecSQLEx('save', 'idNotion; sNotionReg ',
[ftInteger, ftString], [GetVar('id'), '']);
// возвращаемое значение sNotionReg находится в sRes[1].
// В sRes[0] находится передаваемый параметр idNotion.
SaveToFile('', sRes[1]);
end;
.. pas:method:: ExecSQLWithProgress(BlockName, Caption, Message, EventName: String; FinalValue: Integer): Variant
Методы позволяют выполнять SQL-блоки, которые посылают по Pipe каналу
сообщения о процессе выполнения. Методы открывают модальное окно с
полосой прогресса, которое слушает Pipe канал с заданным именем, и
запускаю выполнение SQL-блока. Сообщения, приходящие с сервера должны
содержать число в диапазоне *[0 .. FinalValue]*. По приходу
сообщения с числом равным или больше *FinalValue*, диалог будет
закрыт. Если ``FinalValue = 0`` , то диалог будет закрыт при
получении первого сообщения.
:param String BlockName:
Имя SQL-блока.
:param String Caption:
Текст заголовка окна.
:param String Message:
Сообщение.
:param String EventName:
Имя Pipe-канала.
:param Integer FinalValue:
Финальное значение.
:rtype: Variant
.. code-block:: delphi
:caption: Пример использования
declare
i integer;
j integer;
begin
i := 1;
loop
dbms_pipe.pack_message(to_char(i));
j := dbms_pipe.send_message('TestEvent');
i := i + 1;
dbms_lock.sleep(1);
if i = 11 then
exit;
end if;
end loop;
end;
ExecSQLWithProgress('msg', 'Заголовок', 'Сообщение', 'TestEvent', 10);
.. warning:: Не реализовано
.. pas:method:: ExecSQLExWithProgress(BlockName: String; ParamNames, ParamTypes, ParamValues: Array; Caption, Message, EventName: String; FinalValue: Integer): Variant
Расширенный метод ``ExecSQLWithProgress``.
:param String BlockName:
Имя SQL-блока
:param Array ParamNames:
Имена входящих параметров, разделенные точкой с запятой.
:param Array ParamTypes:
Массив типов параметров в формате: ``[тип1, тип2, …]`` Доступные константы
типов параметров:
- ftString
- ftInteger
- ftFloat
- ftDateTime
- ftOraBlob
- ftOraClob
:param Array ParamValues:
Массив значений параметров в формате: ``[значение1, значение2]`` Количество
параметров должно совпадать с количеством типов и с количеством
значений. Все параметры являются входными и могут являться выходными.
:param String Caption:
Текст заголовка окна.
:param String Message:
Сообщение.
:param String EventName:
Имя Pipe-канала.
:param Integer FinalValue:
Финальное значение.
:rtype: Variant
.. code-block:: delphi
:caption: Пример использования
[OUT idpValue]
declare
i integer;
j integer;
begin
i := 1;
:idpValue := 'Возвращаемое значение';
loop
dbms_pipe.pack_message(to_char(i));
j := dbms_pipe.send_message('TestEvent');
i := i + 1; dbms_lock.sleep(1);
if i = 11 then
exit;
end if;
end loop;
end;
R := ExecSQLExWithProgress('msg', 'idpValue', [ftString], ['Входящее
значение'], 'Заголовок', 'Сообщение', 'TestEvent', 10 );
ShowMessage(R[0]);
.. warning:: Не реализовано
Фильтр
......................................................................
Настройки
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class::
.. pas:attribute:: ActiveFilterName: String
Имя активного фильтра выборки.
:rtype: String
.. code-block:: delphi
:caption: Пример использования
// При обращении напрямую к объекту Selection не работает
// (Selection.ActiveFilterName)
Sel := Selection;
ShowMessage(Sel. ActiveFilterName);
.. pas:method:: UniFilterMacros(): String
Метод возвращает условие универсального фильтра, подставляемое в
``GetSQLTest`` выборки
:rtype: String
.. pas:method:: UniFilterText(): String
Метод возвращает условие универсального фильтра в виде текста.
:rtype: String
параметры
**********************************************************************
.. pas:class::
.. pas:method:: GetFilterParamReadOnly(FltParamName: String): Boolean
Возвращает значение свойства **ReadOnly** параметра фильтра по имени
параметра *FltParamName*.
:param String FltParamName:
Имя параметра фильра.
:rtype: Boolean
.. pas:method:: SetFilterParamReadOnly(FltParamName: String; Flag: Boolean)
Устанавливает значение *Flag* свойству **ReadOnly** параметру фильтра
*FltParamName*.
:param String FltParamName:
Имя параметра фильтра.
:param Boolean Flag:
Флаг свойства *ReadOnly* параметра фильтра *FltParamName*.
.. pas:method:: GetFilterParamVisible(FltParamName: String): Boolean
Возвращает значение свойства **Visible** параметра фильтра по имени
параметра AFltParamName.
:param String FltParamName:
Имя параметра.
:rtype: Boolean
.. pas:method:: SetFilterParamVisible(FltParamName: String; Flag: Boolean)
Устанавливает значение *Flag* свойству видимости параметру фильтра
*FltParamName*.
:param String FltParamName:
Имя параметра фильтра.
:param Boolean Flag:
Флаг свойства видимости параметра фильтра *FltParamName*.
Другое
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class::
.. pas:attribute:: FilterChanged: Array
Установка этого свойства приводит к смене иконки на операциях ``GetSQLText``
и ``Filter``, что сигнализирует о том, что фильтр был изменён, и для его
применения необходимо обновить выборку.
:rtype: Array
.. pas:method:: ApplyFilter()
Метод применяет универсальный фильтр к выборке.
.. pas:method:: ApplyFilterImmediate()
Применяет фильтры к выборке, производя перезапрос данных. Метод не
зависит от флага **Загружать данные при открытии фрейма** в отличие от
``Selection.ApplyFilter``;
.. pas:method:: RestoreFilter()
Восстановление предыдущих значений параметров активного фильтра из
стека.
.. pas:method:: ResetFilterImmediate()
Сбрасывает все условия фильтрации и производя перезапрос данных. Метод
не зависит от флага **Загружать данные при открытии фрейма** в отличие от
``Selection.ResetFilter``
.. pas:method:: ResetFilter()
Сброс стандартного фильтра.
.. pas:method:: BuildUniFilter()
Метод вызывает окно фрейма универсального фильтра выборки.
.. warning:: Не реализовано
.. pas:method:: ResetUniFilter()
Сброс серверного универсального фильтра
.. pas:method:: ApplyFilterPreset(Name: String)
Применяет фильтр с указанной сохраненной настройкой
:param String Name:
Системное имя сохраненной настройки фильтра
.. warning:: Не реализовано
.. pas:method:: SaveFilterSetting(IDSetting: Variant)
Метод сохраняет значения параметров стандартного фильтра в настройку с
указанным идентификатором.
:param Variant IDSetting:
Идентификатор настройки
.. warning:: Не реализовано
.. pas:method:: LoadFilterSetting(IDSetting: Variant)
Метод загружает значения параметров стандартного фильтра из настройки с
указанным идентификатором.
:param Variant IDSetting:
Идентификатор настройки
.. warning:: Не реализовано
.. pas:method:: AddSelectedToFilter()
Метод добавляет выделенные записи списка в универсальный фильтр.
Вызывать метод необходимо до вызова метода ``Selection.ApplyFilter``
.. warning:: Не реализовано
Датасет
......................................................................
.. pas:class::
.. pas:method:: Insert()
Метод добавляет новую пустую запись в выборку и делает ее активной.
.. pas:method:: ClientInsert(FieldNames: String; FieldValues: Variant)
Процедура вставляет новую запись и устанавливает значение полей. При
вызове метода не вызывается паскаль операция ``InsertItem`` и не вызываются
сеттеры. Таким образом не происходит никаких действий на сервере. Для
вставки новой записи без установки значений можно передать параметры
``('', [])``.
:param String FieldNames:
Список имен полей через запятую.
:param Variant FieldValues:
Значения полей. Можно передать либо массивом, если несколько полей, либо
одиночным Variant, если одно поле. Можно передать **unassigned**, если не
хотим устанавливать значений полям.
.. code-block:: delphi
:caption: Пример использования
Selection.ClientInsert('id', 8599654000);
Selection.ClientInsert('id, sText, nNumber', [8599654000, 'Текст текст текст', 555]); // не работает в 4.30
.. pas:method:: Delete()
Удаляет текущую активную запись и переводить указатель на следующую.
.. pas:method:: ClientDelete()
Удаляет текущую запись. При этом не происходит никаких действий на
сервере.
.. pas:method:: Append()
Метод добавлять новую пустую запись в конец выборки.
.. pas:method:: ClientAppend(FieldNames: String; FieldValues: Variant)
Процедура вставляет новую запись в конец выборки и устанавливает значение полей. При
вызове метода не вызывается паскаль операция ``InsertItem`` и не вызываются
сеттеры. Таким образом не происходит никаких действий на сервере. Для
вставки новой записи без установки значений можно передать параметры
``('', [])``.
:param String FieldNames:
Список имен полей через запятую.
:param Variant FieldValues:
Значения полей. Можно передать либо массивом, если несколько полей, либо
одиночным Variant, если одно поле. Можно передать **unassigned**, если не
хотим устанавливать значений полям.
.. code-block:: delphi
:caption: Пример использования
Selection.ClientAppend('id', 8599654000);
Selection.ClientAppend('id, sText, nNumber', [8599654000, 'Текст текст
текст', 555]);
.. warning:: Не реализовано
.. pas:method:: Edit()
Включает режим редактирования активной записи. При этом определяется
текущее состояние выборки, если выборка пуста, то происходит вставка
записи, иначе редактирование.
.. code-block:: delphi
:caption: Пример использования
Selection.Edit;
SetVar('name', 'Новое значение');
Selection.Post;
ShowMessage(GetVar('name'));
.. pas:method:: Cancel()
Отменяет изменение активной записи, если еще не была зафиксирована
текущая транзакция в БД (не выполнен ``Commit``).
.. pas:method:: Post()
Фиксирует транзакцию в БД.
.. pas:method:: IsBrowseMode(): Boolean
Метод возвращает **True**, если выборка находиться в режиме просмотра
записей.
:rtype: Boolean
.. pas:method:: RefreshItem()
Выполняет операцию ``RefreshItem`` выборки (обновляет текущую запись)
.. pas:method:: Refresh()
Метод обновит данные в соответствии с *RefreshMode*. Если ``RefreshMode =
rmNormal``, при вызове ``Selection.Refresh`` будет выполнен перезапрос
данных, без закрытия выборки. Если же ``RefreshMode = rmCloseOpen``, при
вызове ``Selection.Refresh`` произойдёт переоткрытие выборки. По умолчанию,
``RefreshMode = rmNormal``. *rmCloseOpen* необходимо использовать в случае,
если вы используете динамический SQL и в результате перезапроса данных,
может измениться количество столбцов.
.. seealso::
:pas:meth:`TbtkScriptSelectionObject.RefreshAsync`
.. pas:method:: RefreshAsync()
Метод вызывает :pas:meth:`Refresh` в асинхронном режиме.
.. caution::
Если на момент выполнения метода выборка закрыта, метод не выполнится.
.. warning:: Не реализовано
.. pas:method:: IsEmpty(): Boolean
Метод возвращает **True**, если в открытой выборке нет записей.
:rtype: Boolean
.. pas:method:: DisableControls()
Метод временно блокирует отправку событий данных (значение выборки изменено, изменена запись выборки, изменена фокусировка записи и т.п.) компонентам, работающим с данными, таким как редакторы, табличные и древовидные представления, и т.п..
Рассылка сообщений включается обратным методом - :pas:class:`EnableControls`. Допускаются сколь угодно вложенные вызовы такой блокировки, т.е. вложенные методы (между парами вызовов :pas:class:`DisableControl`/:pas:class:`EnableControls`) так же могут вызывать блокировку рассылок событий данных.
.. warning::
Каждому вызову :pas:class:`DisableControl` обязан соответствовать, прекращающий его действие, :pas:class:`EnableControls`, в противном случае приложение продолжит функционировать неправильно.
.. code-block:: delphi
DisableControls;
try
Selection.SetFieldsReadOnly('val', False);
if Selection.Locate('id' , 5, []) then
Selection.SetVar('val', 123);
if Selection.Locate('id' , 9, []) then
Selection.SetVar('val', 123);
Selection.SetFieldsReadOnly('val', True);
finally
EnableControls;
end;
.. tip::
#. Метод следует использовать, если в коде производится большое количество операций с данными и их структурой. В этом случае приложение не будет реагировать на каждое изменение, а сделает это один раз при вызове :pas:class:`EnableControls`.
#. Следует учитывать, что вызов :pas:class:`EnableControls` приводит к полному перечитыванию всех данных выборки элементом управления. Если это большая выборка, то, например, табличное представление даст ощутимую просадку производительности на чтении.
#. Выбирать, использовать блокировку или нет, проще всего экспериментально, замеряя время выполнения кода. Т.к. множество операций над данными локальны, такие как установка значения поля, и не приводят к большим потерям производительности даже при последовательной обработке каждого из них.
.. pas:method:: EnableControls()
Метод обратный :pas:class:`DisableControls`.
Высылает событие "все данные изменились".
.. note::
Метод не делает ничего, если вызывается во вложенной паре `Enable`/`Disable` -`Controls`. Имеет эффект только при вызове последней разблокировки (фактически снимающей блокировку с рассылки).
Настройки
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Макросы
**********************************************************************
.. pas:class::
.. pas:method:: AddMacro(MacroName, MacroValue: String)
Создаёт в выборке макрос с именем *MacroName* и значением *MacroValue*.
Если макрос с именем *MacroName* существует, макросу будет установлено
значение *MacroValue*.
:param String MacroName:
Имя макроса.
:param String MacroValue:
Значение макроса.
.. code-block:: delphi
:caption: Пример использования
AddMacro('GSTMacro', '(4=4)');
AddMacro('GSTMacro2', '(5=5)');
.. pas:method:: GetMacro(MacroName: String): String
Возвращает значение макроса с именем *MacroName*.
:param String MacroName:
Имя макроса.
:rtype: String
.. pas:method:: IsMacroExists(MacroName.: Variant): Boolean
Проверяет существование макроса c именем *MacroName*.
:param Variant MacroName.:
Имя макроса.
:rtype: Boolean
.. pas:method:: SetMacro(MacroName, MacroValue: String): Variant
Устанавливает макросу с именем *MacroName* значение *MacroValue*. Если при
установке значения макроса выборка была открыта (``Selection.Active = True``),
то произойдёт её закрытие. Поэтому после установки макроса
необходимо открыть выборку самостоятельно.
:param String MacroName:
Имя макроса.
:param String MacroValue:
Текст макроса.
:rtype: Variant
Загрузка
**********************************************************************
.. pas:class::
.. pas:method:: SetRefreshMode(Value: TbtkSelectionRefreshMode)
Метод указывает выборке, каким образом необходимо производить
перезапрос данных при обновлении. Если ``RefreshMode = rmNormal``, при
вызове ``Selection.Refresh`` будет выполнен перезапрос данных, без
закрытия выборки. Если же ``RefreshMode = rmCloseOpen``, при вызове
``Selection.Refresh`` произойдёт переоткрытие выборки.
По умолчанию, ``RefreshMode = rmNormal``.
*rmCloseOpen* необходимо использовать в случае, если вы используете
динамический SQL и в результате перезапроса данных, может измениться
количество столбцов.
:param TbtkSelectionRefreshMode Value:
Определяет режим обновления. Может принимать значения:
- rmNormal
- rmCloseOpen.
.. pas:method:: GetRefreshMode(): TbtkSelectionRefreshMode
Функция возвращает значение свойства **RefreshMode** выборки.
:rtype: TbtkSelectionRefreshMode
.. pas:attribute:: AutoActivate: Boolean
Открывать выборку при создании фрейма.
:rtype: Boolean
.. pas:attribute:: ActivateMaster: Boolean
Свойство определяет надо ли при активации выборки открывать всех
мастер-выборок, если они закрыты.
true
активировать надо (по умолчанию)
false
открытие мастер-выборок выполняться не будет;
Свойство необходимо устанавливать до выполнения ``GetSQLText``.
:rtype: Boolean
.. pas:attribute:: AutoRefresh: Boolean
Включение/отключение автообновления. Автообновления производятся
согласно интервалу времени задаваемому в **AutoRefreshInterval**.
:rtype: Boolean
.. pas:attribute:: AutoRefreshInterval: Integer
Временной интервал, по истечении которого выборка будет обновлена.
Задаётся в секундах (не может быть меньше 5 секунд. Если будет указано
меньше, интервал будет равен 5 секунд)
:rtype: Integer
.. code-block:: delphi
:caption: Пример использования
Selection.AutoRefreshInterval := 10;
Selection.AutoRefresh := true;
// Для сброса таймера необходимо отключить автообновление и включить его заново
Selection.AutoRefresh := False;
Selection.AutoRefresh := True;
.. pas:attribute:: Active: Boolean
Активность выборки (открыта/закрыта).
:rtype: Boolean
.. code-block:: delphi
:caption: Пример использования
// При обращении напрямую к объекту Selection не работает
// (Selection.Active)
Sel := Selection;
ShowMessage(Sel.Active);
.. pas:attribute:: SQLText: String
SQL текст запроса выборки(Текст операции ``GetSqlText``).
:rtype: String
.. pas:attribute:: SortOrder: String
Свойство определяет порядок сортировки в выборке и содержит строку,
пригодную для подстановки в SQL запрос, в качестве условия сортировки.
В случае, если выборка частично прогружаемая, свойство будет содержать
значение макроса сортировки *SortOrder#*. В случае полностью
прогруженной выборки, сортировка производится клиентскими средствами,
и свойство будет содержать строку составленную с учётом клиентской
сортировки.
Изменяя свойство возможно изменять сортировку выборки.
:rtype: String
.. pas:attribute:: Partitioned: Boolean
Отвечает за режим прогрузки списка и датасета. Если свойство установлено
в **False**, то список будет полностью загружен на клиента. Если свойство
установлено в **True**, то записи будут прогружены частично.
:rtype: Boolean
.. pas:attribute:: RestoreFocusRecOnRefresh: Boolean
Свойство для выборок с частичной прогрузкой данных. Принцип его действия
следующий:
- если свойство установлено (по умолчанию), то при
обновлении выборки фокус вернется на выделенную ранее запись. Однако
если эта запись расположена далеко по порядку, то при открытии буду
прогружены все предшествующие ей данные. Это может сказаться на
производительности системы.
- если свойство сброшено, то при обновлении
выборки прогружается только первый блок данных, размер которого указан в
свойстве "Размер секции". Если ранее выделенная запись содержится в это
блоке, то фокус будет на нее возвращен. Иначе - установлен на первую
запись. Данное свойство реализовано в связи с необходимостью быстрой
работы выборок с группировкой, где при смене группы меняются условия
фильтрации данных. Получалось так, что выделенная запись оказывалась
расположенной глубоко по порядку, и выборка обновлялась долго.
:rtype: Boolean
.. code-block:: delphi
:caption: Пример использования
Selection.RestoreFocusRecOnRefresh := True
Поля
**********************************************************************
.. pas:class::
.. pas:method:: GetFieldNames(): String
Возвращает системные имена полей выборки разделённые запятыми.
:rtype: String
.. pas:method:: SetFieldsVisible(FieldNames: String; Visible: Boolean)
Метод делает видимыми/невидимыми поля/атрибуты, перечисленные в
параметре *FieldNames*. Если выборка активна, то будет выполняться
установка видимости полей, что приведет к немедленным визуальным
изменениям в фрейме, если выборка закрыта, то будет установлена
видимость атрибутов выборки, как при вызове метода ``SetAttrVisible``.
.. note::
Метод удаляет **все** редакторы полей, как
непосредственно самой выборки, так и её фильтра, в следствии чего его
нельзя использовать в операциях которые могут быть вызваны как результат
работы редактора, к примеру в сеттере. Если такая необходимость
существует - его следует выполнять асинхронно, т.е. отложить выполнение
до завершения всех текущих операций. см. метод :pas:class:`TbtkScriptSelectionObject.AsyncExecOpScript`
:param String FieldNames:
Системные имена атрибутов, разделённые запятой «,».
:param Boolean Visible:
Флаг видимости атрибутов.
.. pas:method:: SetFieldsDesc(FieldNames, Captions: String)
Метод изменяет наименования атрибутов, перечисленных в параметре
*FieldNames*.
:param String FieldNames:
Системные имена атрибутов, разделённые запятой «,».
:param String Captions:
Строка, содержащая новые наименования атрибутов разделённые запятой «,».
Если наименование содержит пробелы, оно должно быть заключено в двойные
кавычки. Например: ``"Имя один","Имя два"``
.. code-block:: delphi
:caption: Пример использования
Selection.SetFieldsDesc('sCaption,sSystemName', '"Новое
наименование","Новое системное имя"');
Selection.SetFieldsReadOnly('sCaption,sSystemName', '0,1');
.. pas:attribute:: FieldsCount: Integer
Количество полей (атрибутов) выборки.
:rtype: Integer
.. pas:method:: GetFieldCount(): Integer
Метод возвращает количество полей (атрибутов) выборки.
:rtype: Integer
.. pas:method:: SetFieldsReadOnly(FieldNames, ReadOnly: String)
Метод изменяет свойсво **ReadOnly** атрибутов, перечисленых в параметре
*FieldNames*.
:param String FieldNames:
Системные имена атрибутов, разделённые запятой «,».
:param String ReadOnly:
Строка, содержащая значения **0** и **1** (ноль и один) либо **True** и **False**,
разделённые запятой «,».
Количество значений должно соответствовать количеству имён полей
указанных в параметре *FieldNames*, либо содержать только одно значение
(общее для всех перечисленных полей).
.. code-block:: delphi
:caption: Пример использования
selection.SetFieldsReadOnly('fldName1,fldName2,fldName3', '0,0,1');
// отключит режим "Только для чтения" полям с именами "fldName1" и
// "fldName2", и включит этот режим для поля "fldName3".
selection.SetFieldsReadOnly(selection.GetFieldNames, True);
//включит режим "Только для чтения" всем полям выборки.
.. pas:method:: SetDisabled(ActName: Variant; Flag: Boolean)
Метод запрещает или разрешает стандартное действие в зависимости от
флага запрета.
.. warning ::
Использование метода может приводить к потенциальным ошибкам.
Реальное поведение метода отличается от закладывавшейся изначально в
него логики. Исторически сложилось так, что метод используется для
массового изменения значений свойств **"Только для чтения"** для всех полей
выборки, с последующим выборочным переключением этого свойства у
отдельных полей. Существовавшая в реализации метода ошибка позволяла
производить подобные действия. Исправление этой ошибки повлекло за собой
проблемы с огромным количеством написанного кода, в том числе
авто-генерируемого. В результате было решено изменить поведение метода
на ожидаемое, а корректную работу реализовать в новом методе
:pas:meth:`TbtkScriptOperationOptionsObject.SetStandardDisabled`.
:param Variant ActName:
Имя действия, может принимать следующие константы:
- dsoEdit
- dsoInsert
- dsoDelete
:param Boolean Flag:
Значение активности, запрещает или разрешает действие *ActName*.
.. code-block:: delphi
:caption: Пример использования
selection.SetDisabled(dsoInsert, False);
// разблокирует стандартную операцию "добавление новых записей"
selection.SetDisabled(dsoEdit, True);
// Внимание! должна блокировать стандартную операцию "редактирование", но для обеспечения совместимости
// устанавливает значение свойства "Только для чтения" всем полям выборки в
// значение "True"
.. deprecated:: Global 5.0.0
следует использовать:
- :pas:meth:`TbtkScriptOperationOptionsObject.SetStandardDisabled` для блокировки/разблокировки стандартных операций выборки;
- :pas:meth:`TbtkScriptSelectionObject.SetFieldsReadOnly` для изменения свойства **"Только для чтения"** указанным полям выборки.
.. pas:method:: FindField(FieldName: String): TbtkScriptFieldObject
Ищет поле по системному имени. Если атрибут не найден, возвращает **nil** (в
отличие от ``FieldByName``, который в этом случае возбуждает исключение)
:param String FieldName:
Системное имя поля.
:rtype: TbtkScriptFieldObject
.. code-block:: delphi
:caption: Пример использования
Fld := Selection.FindField('id');
If Assigned(Fld) then
Fld.Visible := false;
.. pas:method:: FieldByName(FieldName: String): TbtkScriptFieldObject
Возвращает поле типа :pas:class:`TbtkScriptFieldObject` по системному имени поля.
Если поле не найдено, дует возбуждена исключительная ситуация.
:param String FieldName:
Системное имя поля.
:rtype: TbtkScriptFieldObject
.. pas:method:: FieldByIndex(Index: Integer): TbtkScriptFieldObject
Возвращает поле типа :pas:class:`TbtkScriptFieldObject` по индексу *Index*.
Индексирование начинается с 0.
:param Integer Index:
Порядковый номер поля.
:rtype: TbtkScriptFieldObject
Навигация
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class::
.. pas:method:: Prior(): Boolean
Метод переводит активную запись на предыдущую, если такая имеется.
Результат - было ли фактическое перемещение.
:rtype: Boolean
.. pas:method:: Next(): Boolean
Метод переводит активную запись на следующую, если такая имеется.
Результат - было ли фактическое перемещение.
:rtype: Boolean
.. code-block:: delphi
:caption: Пример использования
while Selection.Next do
...
.. pas:method:: First()
Устанавливает первую запись выборки активной.
.. pas:method:: Last()
Метод делает последнюю запись выборки данных активной.
.. pas:method:: Eof(): Boolean
Метод возвращает **True** (**1**), если стоим на последней записи, и **False**, если
на любой другой.
:rtype: Boolean
.. pas:method:: Locate(KeyFields: String; KeyValues, Flag: Array): Boolean
Ищет запись, отвечающую указанным условиям (имя поля, значение поля), и
делает ее текущей. Возвращает **True** или **False** в зависимости от
результата.
.. attention::
Из-за того, что скриптер не понимает чисел больше *MaxInt*,
а идентификаторы в системе часто больше *MaxInt*, в качестве значения для
поиска по идентификатору следует использовать строковое представление
идентификатора.
:param String KeyFields:
Список названий полей. одной строкой через ';'
:param Array KeyValues:
Массив значений полей или значение, если поиск осуществляется по одному
полю
:param Array Flag:
Режим поиска. Может принимать значение :pas:class:`TbtkScriptLocateOption`
перечисления. Можно передать несколько значений.
:rtype: Boolean
.. code-block:: delphi
:caption: Пример использования
v := CreateArray(2);
v[0] := 91894001;
v[1] := 940593;
Selection.Locate('IDOperation;Nversion' , V, [loCaseInsensitive, loNext]);
Selection.Locate('ID;' , 100500, []);
Selection.Locate('ID;' , ['100500'], []);
Selection.Locate('ID;sCaption' , ['100500','xxxxY'], []);
.. pas:attribute:: RecNo: Integer
Номер текущей записи в выборке.
:rtype: Integer
.. pas:attribute:: RecordCount: Integer
Количество загруженных записей в выборке.
:rtype: Integer
Транспонирование
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class::
.. pas:method:: TransposeFieldByKey(Key: string; FieldName: string): TbtkScriptFieldObject
Возвращает поле транспонированного датасета по ключу.
:param string Key:
Значение ключа.
:param string FieldName:
Имя поля.
:rtype: TbtkScriptFieldObject
.. pas:method:: Merge(OperationName: String)
Добавляет в датасет данные, возвращаемые SQL операцией **OperationName**.
**OperationName** должна вернуть такой же набор полей, что и в датасете.
:param String OperationName:
Имя операции
.. warning:: Не реализовано
.. pas:method:: TransposeLocate(KeyFields, KeyValues: Array; Flag: Variant): Boolean
Ищет запись, отвечающую указанным условиям, и делает ее текущей.
Ключевым полем в транспонированной выборки является ключевое поле
выборки строк. Возвращает **True** или **False** в зависимости от результата.
:param Array KeyFields:
Список названий полей.
:param Array KeyValues:
Массив значений полей *KeyFields*.
:param Variant Flag:
Может принимать одно из следующих значений: [], [loCaseInsensitive],
[loPartialKey] или [loCaseInsensitive, loPartialKey].
loCaseInsensitive
регистронезависимый поиск
loPartialKey
поиск любого вхождения строки.
:rtype: Boolean
.. code-block:: delphi
:caption: Пример использования
Selection.TransposeLocate('n#row',3,[]);
.. pas:method:: Merge2(OperationName: String)
Добавляет в датасет данные, возвращаемые SQL операцией **OperationName**.
**OperationName** должна вернуть такой же набор полей, что и в датасете.
:param String OperationName:
Имя операции. Отличается от :pas:meth:`TbtkScriptSelectionObject.Merge` тем, что SQL текст выполняемый из
``OperationName`` вызывается в контексте выборки данный, а не мастер выборки
по отношению к выборке данных. Это влияет на подстановку значений
параметров.
.. warning:: Не реализовано
.. pas:method:: RefreshTranspose(DataRefresh, RowRefresh, AttrRefresh: Boolean)
Обновить транспонированный датасет.
:param Boolean DataRefresh:
Обновить выборку данных.
:param Boolean RowRefresh:
Обновить выборку строк.
:param Boolean AttrRefresh:
Обновить выборку атрибутов.
Вид
......................................................................
Фреймы
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class::
.. pas:method:: Chart(): TCustomChart
Метод возвращает объект класса :pas:class:`TCustomChart`.
:rtype: TCustomChart
.. code-block:: delphi
:caption: Пример использования
Chart.BottomAxis.Title.Caption := 'Нижняя ось';
Selection.Chart.BottomAxis.Title.Caption := 'Нижняя ось';
S := FindSelection('SEL_AnyName');
S.Chart.BottomAxis.Title.Caption := 'Нижняя ось';
.. warning:: Не реализовано
.. pas:method:: Diagram(): TbtkAdvDiagram
Возвращает объект для работы с Adv диаграммой.
:rtype: TbtkAdvDiagram
.. pas:method:: Scheduler(): TbtkScheduler
Возвращает объет "планировщик" для выборки.
:rtype: TbtkScheduler
.. warning:: Не реализовано
.. pas:method:: GetFrameDataAsString(): String
Метод возвращает данные фрейма расписания (Месяц, день, год).
:rtype: String
.. warning:: Не реализовано
.. pas:attribute:: Olap: TbtkScriptOLAPObject
Возвращает OLAP-интерфейс фрейма выборки
Атрибут только для чтения
:rtype: TbtkScriptOLAPObject
.. pas:method:: PivotGrid()
Свойство возвращает скриптовый объект Pivot-грида.
.. code-block:: delphi
:caption: Пример использования
stream := Selection.PivotGrid.SaveToBlob();
SaveBlobToFile('...\Saved_Settings.txt', stream);
stream := LoadFromFileToBlob('...\Saved_Settings.txt');
Selection.PivotGrid.LoadFromBlob(stream);
.. pas:method:: Gantt(): TbtkGantt
Возвращает объект для работы с диаграммой Гантта.
:rtype: TbtkGantt
.. pas:method:: TextView(): TbtkScriptTextViewObject
Возвращает объект, инкапсулирующий API доступа к фрейму
`TbtkLookUpTextViewFrame`.
:rtype: TbtkScriptTextViewObject
.. deprecated:: Global 5.4.0
Следует использовать :pas:meth:`Selection.Controller.Text `.
.. warning:: Не реализовано
.. pas:method:: Rte(): RichTextEditor
Возвращает объект для работы с редактором форматированного текста.
:rtype: RichTextEditor
.. warning:: В :term:`Global 1` не реализовано
.. versionadded:: 1.26.0-ms17
Дерево
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class::
.. pas:method:: GetNodeState(): Integer
Метод возвращает состояние текущего узла дерева.
0
Узел свернут
1
Узел раскрыт
\-1
Не найден текущий узел
:rtype: Integer
.. pas:method:: GetExpandedNodeIDS(): ArrayObject
Возвращает идентификаторы открытых узлов дерева.
:rtype: ArrayObject
.. code-block:: delphi
:caption: Пример использования
IDS := Selection.GetExpandedNodeIDS;
...
.. pas:method:: CollapseAllNodes()
Процедура сворачивает все узлы в дереве.
.. pas:method:: OpenAllNodes(Depth: Integer = -1; ExpandMode: TbtkNodeExpandMode = emExpandAndLoadNodes)
Метод раскрывает все узлы в дереве.
:param Integer Depth:
Глубина раскрытия узлов дерева.
\-1
Развернуть до максимальной глубины.
0
Свернуть все подузлы.
1..N
Развернуть узлы до указанного уровня глубины.
:param TbtkNodeExpandMode ExpandMode:
Параметр определяет как и какие узлы надо раскрывать.
.. pas:method:: OpenNode(NodeId: Float; Recursively: Boolean = False)
Метод раскрывает узел дерева с идентификатором *NodeId* (Применим только
для дерева)
:param Float NodeId:
Идентификатор узла дерева.
:param Boolean Recursively:
Параметр позволяет в значение **True** раскрыть все подузлы рекурсивно, то
есть будет развернут не только один *NodeId* узел, но и все его подузлы.
Если же передано значение **False**, то свернутые подузлы разворачиваться не будут.
.. pas:method:: CloseNode(NodeId: Float; Delete, Recursively: Boolean)
Метод сворачивает узел дерева с идентификатором *NodeID* (Применим только
для дерева).
:param Float NodeId:
Идентификатор узла.
:param Boolean Delete:
Параметр используется в курсорном дереве. Установка значение в **True**
позволяет удалить из памяти клиента (DataSet'а) сворачиваемые подузлы.
:param Boolean Recursively:
Параметр позволяет в значение **True** свернуть все подузлы рекурсивно, то
есть будет свернут не только один *NodeId* узел, но и все его подузлы.
Если же передано значение **False**, то подузлы сворачиваться не будут, и
при последующем открытии узла, сразу будут раскрыты и развернутые до
сворачивания подузлы.
.. code-block:: delphi
:caption: Пример для курсорного дерева, сворачивание с удалением узлов
Selection.CloseNode(GetVar('id'), True, False);
.. pas:method:: ChildNodesLoaded(NodeID: Variant): Boolean
Возвращает `True` если узел не содержит вложенных узлов либо его вложенные узлы загружены.
:param Variant NodeID:
Идентификатор узла. Если идентификатор не указан, метод вернет результат для
сфокусированного узла.
.. code-block:: delphi
:caption: Пример для фокусированного узла
loaded := Selection.ChildNodesLoaded;
.. code-block:: delphi
:caption: Пример для узла с указанным идентификатором
loaded := Selection.ChildNodesLoaded(id);
.. warning:: Не реализовано
Визуальная навигация
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Список/Дерево
**********************************************************************
.. pas:class::
.. pas:method:: VisibleRecordCount(): Integer
Возвращает количество видимых записей на экране.
Рекомендуется использовать вместо текущего метода новый
:pas:class:`TbtkScriptControllerObject.VisibleElementCount`.
:rtype: Integer
.. warning:: Не реализовано
.. pas:method:: SetEditButtonDisable(FieldName, ButtonName: String; Disable: Boolean)
Управление доступом для кнопок **Lookup#** и/или **Reset#**, влияет на свойство
**ReadOnly** поля выборки. То есть, запретив доступ к кнопке **Lookup#** и/или
**Reset#**, поле автоматически становится не редактируемым.
:param String FieldName:
Имя поля.
:param String ButtonName:
Имя кнопки: **Lookup#** или **Reset#**.
:param Boolean Disable:
Значение свойства **ReadOnly** для кнопки поля.
Другое
**********************************************************************
.. pas:class::
.. pas:method:: SetFocusedFieldByName(FieldName: String)
Метод позволяет осуществить переход курсора на другой столбец списка
(дерева) в пределах текущей строки, а также на элемент панели
фильтрации.
:param String FieldName:
Имя столбца (имя поля), на которое необходимо перейти.
.. pas:method:: GetFocusedFieldName (): String
Возвращает имя атрибута (параметра), на редакторе которого находится
фокус. Для списка (дерева) – это будет активный столбец; для карточки
(панели фильтров) – это атрибут (параметр), редактируемый активным
контролом. Если что-то не так, вернёт пустую строку.
:rtype: String
Список/Дерево
**********************************************************************
.. pas:class::
.. pas:method:: IsLastRecord(): Boolean
Метод возвращает **True**, если активная запись является последней в списке
или дереве, с учетом сортировки, фильтрации и группировки.
:rtype: Boolean
.. pas:method:: IsFirstRecord(): Boolean
Метод возвращает **True**, если активная запись является первой в списке или
дереве, с учетом сортировки, фильтрации и группировки.
:rtype: Boolean
.. pas:method:: LastRecord()
Метод делает последнюю запись в выборке активной в соответствие с ее
расположением в списке или дереве, с учетом сортировок и фильтрации.
.. pas:method:: FirstRecord()
Метод делает первую запись в выборке активной в соответствие с ее
расположением в списке или дереве, с учетом сортировок и фильтрации.
.. pas:method:: NextRecord(): Boolean
Метод переводит активную запись на следующую (если такая имеется) в
выборке в соответствие с ее расположением в списке или дереве, с
учетом сортировок и фильтрации. Результат - было ли фактическое
перемещение.
:rtype: Boolean
.. pas:method:: PriorRecord(): Boolean
Метод переводит активную запись на предыдущую (если такая имеется) в
выборке в соответствие с ее расположением в списке или дереве, с
учетом сортировок и фильтрации. Результат - было ли фактическое
перемещение.
:rtype: Boolean
.. pas:method:: ReportNext()
Метод аналогичен ``RecordNext``, но со следующим отличием: при вызове
``ReportNext`` будут пропускаться стоки-группировки, и переход будет
осуществляться исключительно по записям. Именно эти (``ReportNext``,
``ReportFirst``, ``ReportEOF``) методы необходимо использовать, например, при
подсчёте суммы какого-либо столбца выборки.
.. pas:method:: ReportEOF(): Variant
``ReportFirst``, ``ReportNext``, ``ReportEOF`` – позволяют передвигаться по записям
в selection в том порядке, в котором записи отображаются в гриде или
дереве, т.е. с учетом сортировки, фильтрации и группировки. Методы
аналогичны ``FirstRecord``, ``NextRecord`` и т.д., но со следующими отличиями:
При вызове ``FirstRecord`` будут раскрыты все группировки (узлы дерева). При
вызове ``ReportNext`` будут пропускаться стоки-группировки, и переход будет
осуществляться исключительно по записям. Именно эти методы необходимо
использовать, например, при подсчёте суммы какого-либо столбца выборки.
:rtype: Variant
.. pas:method:: ReportFirst()
Метод аналогичен методу ``RecordFirst``, но со следующем отличием: при
вызове ``FirstRecord`` будут раскрыты все группировки (узлы дерева). Именно
эти (``ReportNext``, ``ReportFirst``, ``ReportEOF``) методы необходимо использовать,
например, при подсчёте суммы какого-либо столбца выборки.
.. _TbtkScriptSelectionObject_Selection:
Выделение
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. seealso::
:ref:`Выделение в TbtkScriptControllerObject`
.. pas:class::
.. pas:method:: SelectedValue(FieldIndex, Index: Integer): Variant
Возвращает значение поля с индексом *FieldIndex* выделенной записи с
номером Index.
:param Integer FieldIndex:
Индекс поля.
:param Integer Index:
Номер записи.
:rtype: Variant
.. pas:method:: SelectedValueByName(FieldName: String; Index: Integer): Variant
Возвращает значение поля с именем *FieldName* выделенной записи с номером
*Index*.
:param String FieldName:
Системное имя поля.
:param Integer Index:
Номер записи.
:rtype: Variant
.. pas:method:: SelectedRecordsCount(): Integer
Метод возвращает количество выделенных записей в выборке в режиме
**MultiSelect**, если нет выделенных записей - вернёт **0**
:rtype: Integer
.. code-block:: delphi
:caption: Пример использования
count := Selection.SelectedRecordsCount;
ShowMessage('Выделено ' + count + ' строк');
.. pas:method:: MultiSelect(): Variant
Устанавливает возможность выбора нескольких записей в списке и дерева.
Если свойство равно **True**, то выбор нескольких записей разрешен.
:rtype: Variant
Серверная сессия
......................................................................
.. pas:class::
.. pas:method:: HasSession(): Boolean
Возвращает флаг наличия сессии у объекта **Selection**.
:rtype: Boolean
.. pas:method:: Commit()
Фиксирует транзакцию в БД.
.. pas:method:: Rollback()
Откат текущей транзакции.
.. pas:method:: SavePoint(SavePointName: String)
Создает точку сохранения с заданным именем
:param String SavePointName:
Имя точки сохранения.
.. code-block:: delphi
:caption: Пример использования
selection.savepoint('TestSavePoint');
.. pas:method:: RollBackToSavePoint(SavePointName: String)
Откатывает транзакцию к ранее созданной точке сохранения (если это возможно).
Для визуального обновления выборки после этого метода необходимо вызвать ``Refresh``.
.. attention::
Не безопасный! Необходимо предусмотреть возможность возникновения исключений.
Для безопасного отката используйте метод :pas:class:`TbtkScriptSelectinObject.SafeRollBackToSavePoint`.
:param String SavePointName:
Имя точки сохранения.
.. code-block:: delphi
:caption: Пример использования
selection.RollBackToSavePoint('TestSavePoint');
.. pas:method:: SafeRollBackToSavePoint(SavePointName: String)
Откатывает транзакцию к ранее созданной точке сохранения (если это
возможно). Для визуального обновления выборки после этого метода
необходимо вызвать ``Refresh``.
Безопасный. Возможные исключения подавляются при исполнении SQL-запроса.
:param String SavePointName:
Имя точки сохранения.
.. code-block:: delphi
:caption: Пример использования
selection.SafeRollBackToSavePoint('TestSavePoint');
Отчеты
......................................................................
.. pas:class::
.. pas:method:: CreateReport(ReportName: String; ReportVersionDate: TDateTime; Action: TReportViewMode; ShowWizard: Boolean; OpSelectionName: String; StyleFlag: TFormCreationFlags)
Процедура создает отчёт по его системному имени и дате, по которой
будет найдена актуальная версия шаблона.
:param String ReportName:
Системное имя отчёта.
:param TDateTime ReportVersionDate:
Дата, по которой будет найдена актуальная версия отчёта (если не задана,
берётся SysDate). Тип даты TDateType.
:param TReportViewMode Action:
Действие, которое необходимо произвести над отчётом после его создания.
Возможные значения: {rvmPrint, rvmShow, rvmSave, rvmDesign}
:param Boolean ShowWizard:
Флаг отображения мастера настройки отчётов (если указана главная выборка
мастера) {0,1}
:param String OpSelectionName:
Системное имя выборки, операции которой будут отображаться в главном
меню окна при модальном просмотре построенного отчёта. Если не указана,
подставляются выборки со стандартным набором команд ("Save as" и
"Print")
:param TFormCreationFlags StyleFlag:
Флаг модального или немодального открытия окна просмотра отчёта
{fcfModal, fcfMDI}. fcfMDI - работает только для отчетов на основе
FastReport 4й версии.
.. code-block:: delphi
:caption: Пример использования
Selection.CreateReport(GetVar('sSystemName'), null, rvmShow, 1, '', fcfModal);
.. pas:method:: CreateReportEx(ReportName: String; ReportVersionDate: TDateTime; Action: TReportViewMode; ShowWizard: Boolean; OpSelectionName: String; StyleFlag: TFormCreationFlags; ParamNames: Array; ParamValues: Array)
Процедура предназначена для создания отчёта по его системному имени и
дате, по которой будет найдена актуальная версия шаблона. Метод
представляет расширенную версию метода ``CreateReport``, но в отличие от
``CreateReport`` позволяет передать дополнительные параметры.
:param String ReportName:
Системное имя отчёта.
:param TDateTime ReportVersionDate:
Дата, по которой будет найдена актуальная версия отчёта (если не задана,
берётся SysDate).
:param TReportViewMode Action:
Действие, которое необходимо произвести над отчётом после его создания.
Возможные значения: {rvmPrint, rvmShow, rvmSave, rvmDesign}
:param Boolean ShowWizard:
Флаг отображения мастера настройки отчётов (если указана главная выборка
мастера) {0,1}
:param String OpSelectionName:
Системное имя выборки, операции которой будут отображаться в главном
меню окна при модальном просмотре построенного отчёта. Если не указана,
подставляются выборки со стандартным набором команд ("Save as" и
"Print")
:param TFormCreationFlags StyleFlag:
Флаг модального или немодального открытия окна просмотра отчёта
{fcfModal, fcfMDI}. fcfMDI - работает только для отчетов на основе
FastReport 4й версии.
:param Array ParamNames:
Массив имен параметров отчета.
Параметры:
- ReadOnlyPreview со значением 1 запрещает редактирование построенного
отчета из режима предпросмотра.
:param Array ParamValues:
Массив значений параметров *ParamNames* отчета.
.. pas:method:: CreateReports(ProfileName: String; ReportVersionDate: TDateTime; Action: TReportViewMode; ShowWizard: Boolean; OpSelectionName: String; StyleFlag: TFormCreationFlags)
Процедура создает все отчёты по системному имени профиля.
:param String ProfileName:
Системное имя отчёта.
:param TDateTime ReportVersionDate:
Дата, по которой будет найдена актуальная версия отчёта (если не задана,
берётся SysDate).
:param TReportViewMode Action:
Действие, которое необходимо произвести над отчётом после его создания.
Возможные значения: {rvmPrint, rvmShow, rvmSave, rvmDesign}
:param Boolean ShowWizard:
Флаг отображения мастера настройки отчётов (если указана главная выборка
мастера) {0,1}
:param String OpSelectionName:
Системное имя выборки, операции которой будут отображаться в главном
меню окна при модальном просмотре построенного отчёта. Если не указана,
подставляются выборки со стандартным набором команд ("Save as" и
"Print")
:param TFormCreationFlags StyleFlag:
Флаг модального или немодального открытия окна просмотра отчёта
{fcfModal, fcfMDI}. fcfMDI - работает только для отчетов на основе
FastReport 4й версии.
.. pas:method:: CreateReportsEx(ProfileName: String; ReportVersionDate: TDateTime; Action: TReportViewMode; ShowWizard: Boolean; OpSelectionName: String; StyleFlag: TFormCreationFlags; ParamNames, ParamValues: Variant)
Процедура создает все отчёты по системному имени профиля. Метод
обладает расширенной функциональностью, по сравнению с ``CreateReports``,
позволяя передать дополнительные параметры отчета.
:param String ProfileName:
Системное имя отчёта.
:param TDateTime ReportVersionDate:
Дата, по которой будет найдена актуальная версия отчёта (если не задана, берётся SysDate).
:param TReportViewMode Action:
Действие, которое необходимо произвести над отчётом после его создания.
:param Boolean ShowWizard:
Флаг отображения мастера настройки отчётов (если указана главная выборка
мастера).
:param String OpSelectionName:
Системное имя выборки, операции которой будут отображаться в главном
меню окна при модальном просмотре построенного отчёта.
:param TFormCreationFlags StyleFlag:
Флаг модального или немодального открытия окна просмотра отчёта. Немодальный работает только для отчетов на основе FastReport 4й версии.
:param Variant ParamNames:
Массив имён параметров, переданных в отчёт.
:param Variant ParamValues:
Массив значений параметров, переданных в отчёт.
.. pas:attribute:: PrintInfos: TbtkScriptFieldPrintInfo
Коллекция мета-данных по размножаемым атрибутам, которые можно заполнить
до вызова ``CreateReport``. Используется при выводе в **XLS** файл.
Коллекция создается перед вызовом ``AfterOpen`` операции выборки.
Разработчик должен сам заполнить структуру до вызова ``CreateReport``.
:rtype: TbtkScriptFieldPrintInfo
.. code-block:: delphi
:caption: Пример использования
Selection.ExecOpScript('#AfterOpen');
Selection.PrintInfos['sCaption'].Caption := 'КАПШЕН';
Selection.PrintInfos['nPrice[0]'].Caption := 'ПРАЙС 0';
Selection.PrintInfos['nPrice[1]'].Caption := 'ПРАЙС 1';
Selection.PrintInfos['nPrice[1]'].Style := 'Test_ForReadOnlyFld';
Selection.PrintInfos['nPrice[0]'].HorizGroup := 'Group1';
Selection.PrintInfos['nPrice[1]'].HorizGroup := 'Group1';
Selection.PrintInfos['nLevel'].HorizGroup := 'Group2';
Selection.PrintInfos['nCount'].HorizGroup := 'Group2';
Selection.PrintInfos['sCaption'].HorizGroup := 'Group2';
Selection.PrintInfos['nPrice[1]'].Order := 0;
Selection.PrintInfos['nPrice'].Order := 2;
Olap(Deprecated)
......................................................................
.. pas:class::
.. pas:method:: OpenOLAPDimension(DimensionName: String)
Метод раскрывает измерение с именем *DimensionName*. Если указанное
измерение находится на втором или более низком уровне, сначала будут
открыты измерения предки.
.. deprecated:: Global 5.0.0
Следует использовать :pas:meth:`Selection.OLAP.OpenDimension `.
:param String DimensionName:
Имя измерения. (Имя измерения совпадает с именем атрибута выборки. Если
измерение составное, его имя состоит из имён атрибутов выборки,
разделённых точкой с запятой с пробелом. Точное имя измерения можно
найти в дизайнере измерений OLAP-куба)
.. warning:: Не реализовано
.. pas:method:: ShowDimensionMapEditor()
Метод открывает редактор изменений OLAP-куба.
.. deprecated:: Global 5.0.0
Следует использовать :pas:meth:`Selection.OLAP.ShowDimensionMapEditor `.
.. warning:: Не реализовано
.. pas:method:: OpenOLAPColumnDimension(Level: Integer)
Метод раскрывает измерения с 1-го до *Level* уровня, расположенные в
области столбцов.
.. deprecated:: Global 5.0.0
Следует использовать :pas:meth:`Selection.OLAP.OpenColumnDimension `.
:param Integer Level:
Уровень измерения.
.. warning:: Не реализовано
.. pas:method:: LoadOLAPFrameSettings(ID: Variant): Boolean
Метод загружает и применяет сохранённую настройку для OLAP-фрейма с
идентификатором *ID*. В случае успешного выполнения возвращает *True*.
.. deprecated:: Global 5.0.0
Следует использовать :pas:meth:`Selection.OLAP.LoadFrameSettings `.
:param Variant ID:
Идентификатор настройки.
:rtype: Boolean
.. warning:: Не реализовано
.. pas:method:: SaveOLAPFrameSettings(ID: Variant): Variant
Метод сохраняет сохранённую настройку с идентификатором AID.
.. deprecated:: Global 5.0.0
Следует использовать :pas:meth:`Selection.OLAP.SaveFrameSettings `.
:param Variant ID:
Идентификатор настройки.
:rtype: Variant
.. warning:: Не реализовано
.. pas:method:: OpenOLAPAllDimensions()
Метод раскрывает все измерения в OLAP-списке.
.. deprecated:: Global 5.0.0
Следует использовать :pas:meth:`Selection.OLAP.OpenAllDimensions `.
.. warning:: Не реализовано
.. pas:method:: OpenOLAPRowDimension(Level: Integer)
Метод раскрывает измерения с 1-го до *Level* уровня, расположенные в
области строк.
.. deprecated:: Global 5.0.0
Следует использовать :pas:meth:`Selection.OLAP.OpenRowDimension `.
:param Integer Level:
Уровень измерения.
.. warning:: Не реализовано
Формы и выборки
......................................................................
.. pas:class::
.. pas:method:: CreateForm(FormName, EntityName: String; FormType: TFormCreationFlags): TModalResult
Метод создает и показывает форму.
Возвращает **mrOk** или **mrCancel** если ``FormType = fcfModal`` и **mrNone** если
``FormType = fcfMDI``
Если ``FormType = fcfModal``, то ожидает закрытия формы.
:param String FormName:
Имя формы
:param String EntityName:
Имя выборки которая будет показана на форме
:param TFormCreationFlags FormType:
Параметр определяет как будет показана форма (модально или как
MDI-child)
:rtype: TModalResult
.. code-block:: delphi
:caption: Пример использования
CreateForm('', 'SEL_RPT_Report.List', fcfMDI);
.. pas:method:: CreateFormEx(FormName, EntityName: String; FormType: TFormCreationFlags; PropNames, PropValues: Array): TModalResult
Метод создает и показывает форму.
Возвращает **mrOk** или **mrCancel** если ``FormType = fcfModal`` и **mrNone** если
``FormType = fcfMDI``
Если ``FormType = fcfModal``, то ожидает закрытия формы.
Отличается от ``CreateForm`` возможностью передавать дополнительные параметры.
Также имеется возможность передавать в выборку макросы в качестве
параметров.
Макрос передается в списке параметров. Имя макроса должно начинаться с
символа '**&**'.
:param String FormName:
Имя формы
:param String EntityName:
Имя выборки которая будет показана на форме
:param TFormCreationFlags FormType:
Параметр определяет как будет показана форма (модально или как
MDI-child)
:param Array PropNames:
Массив строк имен параметров формы.
:param Array PropValues:
Массив значений параметров PropNames формы.
:rtype: TModalResult
.. code-block:: delphi
:caption: Пример использования
CreateFormEx('', 'SEL_RPT_Report.List', fcfMDI, ['Representation',
'TabVisible','ExParam1'] ,['RoList', 0, 'Значение']);
CreateFormEx('', 'SEL_RPT_Report.List', fcfMDI, ['Representation',
'¯os','ExParam1'] ,['RoList', 'cSum < 100', 'Значение']);
.. pas:method:: CreatePanelEx(FrameName, EntityName: String; ParamNames, ParamValues: Array)
Показывает фрейм в виде панели на текущей форме. Передает фрейму
параметры.
:param String FrameName:
Имя фрейма
:param String EntityName:
Имя выборки, которой инициализируется внутренний Selection формы.
:param Array ParamNames:
Массив имен параметров.
:param Array ParamValues:
Массив значений параметров.
.. pas:method:: DoLookup(LookupControlClass, EntityName: String; LocateFieldNames, LocateFieldValues, ResultFieldNames: Array; MultiSelect: Boolean): TbtkLookupData
Отображает выборку в режиме выбора (в lookup-форме), возвращает
результат в виде набора записей :pas:class:`TbtkLookupData`.
:param String LookupControlClass:
Имя класса формы.
:param String EntityName:
Системное имя выборки (если пусто, то определяется вызываемой формой).
:param Array LocateFieldNames:
Массив имен атрибутов выборки по которым ищется запись для начального
позиционирования.
:param Array LocateFieldValues:
Вариантный массив значений для *LocateFieldNames*.
:param Array ResultFieldNames:
Массив имен атрибутов выборки, значения которых будут возвращены как
результат; В случае если необходимо вернуть значение атрибута из
детальной выборки, в качестве массивов имен атрибутов передаются имена
состоящие из: ``[имя выборки].[имя поля]``. Для доступа к выборке с
определенным отображением используется синтаксис: ``[имя выборки].[имя
отображения].[имя поля]``
:param Boolean MultiSelect:
Возможен ли выбор нескольких записей из выборки.
:rtype: TbtkLookupData
.. code-block:: delphi
:caption: Пример использования №1
R := DoLookup('TbtkLookupGridForm', 'maintree', ['id'], [2629000], ['id', 'sParentClass'], true);
if R.LookupResult = lrOk then
MessageDlg(VarToStr(R.Data(0, 1)) + '->' + R.Data(1, 1), mtWarning, 'mbYes', 0 );
.. code-block:: delphi
:caption: Пример использования №2: возврат значений из двух выборок.
S := DoLookup('', 'SELRO_CNT_ContractChoose',
['SELRO_CNT_ContractChoose.id', 'SELROCL_CNT_ObligationChoose.id'],
[GetVar('IDContract'), GetVar('IDObligation')],
['SELRO_CNT_ContractChoose.id', 'SELROCL_CNT_ObligationChoose.id'], false);
if s.LookupResult=lrOk then
begin
ShowMessage(s.SelectData('SELRO_CNT_ContractChoose').RecCount);
ShowMessage(s.SelectData('SELROCL_CNT_ObligationChoose').RecCount);
setvar('IDContract', s.SelectData('SELRO_CNT_ContractChoose').Data[0,1]);
setvar('IDObligation', s.SelectData('SELROCL_CNT_ObligationChoose').Data[0,1]);
execsql('set');
end;
Для доступа к вернувшимся значениям была использована структура: SelectData([имя выборки]).Data [AttrNo,RecNo]. Её использование
необходимо при явном указании имени поля ([имя выборки].[имя поля]), если поле указано неявно ([имя поля]), то вернувшиеся данные будут доступны непосредственно в свойстве “Data”, как это сделано в *примере №1*.
.. seealso::
* :pas:meth:`TbtkScriptSelectionObject.DoLookupEx`
* Алиас для краткого обращения :pas:meth:`DoLookup`
.. pas:method:: DoLookupEx(LookupControlClass, EntityName: String; LocateFieldNames, LocateFieldValues, ResultFieldNames: Array; MultiSelect: Boolean; PropNames, PropValues: Array): TbtkLookupData
Метод дополняет :pas:meth:`TbtkScriptSelectionObject.DoLookup` аргументами:
:param Array PropNames:
Массив имен свойств.
:param Array PropValues:
Массив значений свойств *PropNames*.
:rtype: TbtkLookupData
.. code-block:: delphi
:caption: Пример использования №1
R := DoLookupEx('TbtkLookupTreeForm','MainTree',
['id'],[Null],['id','sCaption'],true,
['IDRoot','fnID','fnIDParent','fnHasChild','fnText','fnImageIndex','ImageListname'],
[GetVar('id'),'id','IDParentClass','bHasChild','sCaption','ImageIndex','maintreeview']);
if (R.LookupResult = lrOk) then
begin
MessageDlg( VarToStr(R.Data(0,1))+'->'+R.Data(1,1), mtWarning, 'mbYes', 0 );
end;
.. code-block:: delphi
:caption: Пример использования №2: возврат значений из двух выборок.
begin
AnyAPI.SetIdContract(:id, :IDContract);
AnyAPI.SetIdContract(:id, :IDObligation);
end;
S := DoLookupEx('', 'SELRO_CNT_ContractChoose',
['SELRO_CNT_ContractChoose.id', 'SELROCL_CNT_ObligationChoose.id'],
[GetVar('IDContract'), GetVar('IDObligation')],
['SELRO_CNT_ContractChoose.id', 'SELROCL_CNT_ObligationChoose.id'], false,
['Caption'],
[GetFmtCaption('CONTRACTOBLFORCHOOSE', [GetVar('super$IDSettlerOut_HL'),GetVar('super$IDSettlerIn_HL')])]);
if s.LookupResult=lrOk then
begin
ShowMessage(s.SelectData('SELRO_CNT_ContractChoose').RecCount);
ShowMessage(s.SelectData('SELROCL_CNT_ObligationChoose').RecCount);
SetVar('IDContract', s.SelectData('SELRO_CNT_ContractChoose').Data[0,1]);
SetVar('IDObligation', s.SelectData('SELROCL_CNT_ObligationChoose').Data[0,1]);
ExecSql('set');
end;
Для доступа к вернувшимся значениям была использована структура: SelectData([имя выборки]).Data [AttrNo,RecNo]. Её использование необходимо при явном указании имени поля ([имя выборки].[имя поля]), если поле указано неявно ([имя поля]), то вернувшиеся данные будут доступны непосредственно в свойстве “Data”, как это сделано в *примере №1*.
.. seealso::
* :pas:meth:`TbtkScriptSelectionObject.DoLookup`
* Алиас для краткого обращения :pas:meth:`DoLookupEx`
.. pas:method:: FindFocusedSelection(RootForm: TbtkScriptFormObject): TbtkScriptSelectionObject
Метод возвращает фокусированную выборку.
Поиск ведется в пределах указанной формы. Если форма не
указана, то перебираются все выборки приложения.
.. attention::
Поиск ведется только по выборкам, имеющим контроллер.
Например, ``Application.MainSelection`` контроллера не имеет.
:param TbtkScriptFormObject RootForm:
Форма, по которой ведется поиск фокусированной выборки. Если не задана,
то перебираются все формы приложения.
:rtype: TbtkScriptSelectionObject
.. code-block:: delphi
:caption: Пример использования
sel := Selection.FindFocusedSelection;
if not VarIsNull(sel) then
begin
str := VarToStr(sel.EntityName) + '.' + VarToStr(sel.Representation);
ShowMessage(str);
end;
.. pas:method:: CreateSelectionsIterator(RootForm: TbtkScriptFormObject): TbtkSelectionsIterator
Метод создает объект перебора выборок
:pas:class:`TbtkSelectionsIterator`. Входной параметр - форма, в пределах которой
производится перебор. Если форма не задана, или указана главная форма
приложения, то перебор ведется по всем выборкам.
.. attention::
Поиск ведется только по выборкам, имеющим контроллер.
Например, ``Application.MainSelection`` контроллера не имеет.
:param TbtkScriptFormObject RootForm:
Форма, по которой ведется поиск фокусированной выборки. Если не задана,
то перебираются все формы приложения.
:rtype: TbtkSelectionsIterator
.. code-block:: delphi
:caption: Пример использования
form := Application.FindFormBySelection('SEL_TSG_FocusSelection_t18403');
iterator := Selection.CreateSelectionsIterator(form);
str := 'Все выборки приложения:' + #13#10;
repeat
sel := iterator.NextSelection;
if not VarIsNull(sel) then
str := str + VarToStr(sel.EntityName) + '.' +
VarToStr(sel.Representation) + #13#10;
until
VarIsNull(sel);
ShowMessage(str);
TReportViewMode
~~~~~~~~~~~~~~~~~
.. pas:class:: TReportViewMode
Перечисление.
Режим открытия отчетов
.. pas:attribute:: rvmDesign
Открыть отчет для изменения
.. pas:attribute:: rvmPrint
Открыть отчет для печати
.. pas:attribute:: rvmSave
Открыть отчет для сохранения
.. pas:attribute:: rvmShow
Открыть отчет для предпросмотра
TbtkWatcherMode
~~~~~~~~~~~~~~~~
.. pas:class:: TbtkWatcherMode
Перечисление
Режим открытия файла.
.. pas:attribute:: wmAuto
Авто-определение режима. В случае, если при вызове уже
запущен процесс приложения, которым следует открыть файл,
выбирается режим **wmProcess**, иначе режим **wmFile**.
.. pas:attribute:: wmFile
Считается, что файл редактируется, пока его нельзя открыть на редактирование.
Основан на том, что многие приложения при открытии занимают файл, не допуская
его редактирования другими приложениями.
Данный режим подходит не ко всем приложениям (например, приложение "Блокнот"
не запрещает другим приложениям редактировать файл).
.. pas:attribute:: wmProcess
Считается, что файл редактируется, пока работает процесс приложения, открывшего этот файл.
Как только процесс завершается, считается, что редактирование завершено.
Данный режим подходит не ко всем приложениям (например, приложение MS Word
для открытия нескольких файлов использует один и тот же процесс,
который завершается после закрытия всех открытых файлов).
Следует по возможности избегать использование данного режима.
TbtkUserActionType
~~~~~~~~~~~~~~~~~~~~
.. pas:class:: TbtkUserActionType
Перечисление
.. pas:attribute:: uaNextControl
Осуществится переход на следующий контрол (ячейку)
.. pas:attribute:: uaUnknown
Действие не известно
TbtkSelectionRefreshMode
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class:: TbtkSelectionRefreshMode
Перечисление
.. pas:attribute:: rmCloseOpen
.. pas:attribute:: rmNormal
TbtkScriptLocateOption
~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class:: TbtkScriptLocateOption
Перечисление
Параметры поиска записи для функции :pas:class:`TbtkScriptSelectionObject.Locate`
.. pas:attribute:: loCaseInsensitive
Поиск нечувствителен к регистру символов.
.. pas:attribute:: loPartialCompare
Опция похожа на :pas:attr:`TbtkScriptLocateOption.loPartialKey`, но поиск производится по произвольному вхождению подстроки в строку. То есть, при поиске слова "HAM" будет найдена строка "HAMM", "HAMMER" и "MR HAMMER".
Параметр неприменим к транспонированным датасетам.
.. pas:attribute:: loUp
Поиск производиться вверх по датасету от текущей записи к первой.
Параметр неприменим к транспонированным датасетам.
.. pas:attribute:: loNext
Поиск производиться вниз по датасету от текущей записи к последней.
Параметр неприменим к транспонированным датасетам.
.. pas:attribute:: loNearest
:pas:class:`TbtkScriptSelectionObject.Locate` перемещает курсор на заданную запись в датасете или на первую запись, значения которой больше, чем значения, указанные как ключевые. Для правильной работы этой опции датасет должен быть отсортирован по полям, в которых выполняется поиск. Если набор данных не отсортирован, курсор может быть установлен на строку, не связанную с условием поиска.
Параметр неприменим к транспонированным датасетам.
.. pas:attribute:: loPartialKey
Поиск ищет по частичному вхождению ключа поиска с начала. Например при поиске слова "HAM"
будет найдена строка со значением "HAMMER", но не "MR HAMMER".
TLocateOptions (Deprecated)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class:: TLocateOptions
Перечисление
Определяет значения параметров метода Locate выборки
.. pas:attribute:: loPartialKey
Искомая строка может быть частью ключевого значения.
Например: при поиске по строке "авто", будут найдены как "авто", так и "автомобиль"
Ключевое значение может включать искомую строку
.. pas:attribute:: loCaseInsensitive
Поиск по значению без учёта регистра.
TbtkScriptFieldObject
~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class:: TbtkScriptFieldObject
TbtkScriptFieldObject
.. pas:attribute:: FieldName: String
Имя поля (атрибута).
Атрибут только для чтения
:rtype: String
.. pas:attribute:: Visible: Integer
Свойство управляет видимостью атрибута. Также можно использовать методы
:pas:class:`TbtkScriptSelectionObject.SetFieldsVisible` или :pas:class:`TbtkScriptSelectionObject.SetAttributeVisible`.
:rtype: Integer
.. pas:attribute:: EditMask: String
Свойство управляет маской ввода.
:rtype: String
.. pas:attribute:: Mandatory: Integer
Выделяет редактор как обязательный для заполнения. Распространяется на
следующие типы редакторов: время, дата, дата-время, фиксированный
выпадающий список, выпадающий список по запросу, редактор в строке,
редактор с кнопкой, денежный редактор, редактор www. Установка свойства
в **True**, включает выделение редактора, как обязательного для заполнения.
:rtype: Integer
.. pas:attribute:: ColumnWidth: Integer
Свойство управляет шириной колонки атрибута (Поля) во фреймах с
таблицей (Grid) или дерева (Tree).
:rtype: Integer
.. pas:attribute:: ReadOnly: Integer
Свойство управляет доступностью редактирования атрибута.
:rtype: Integer
.. pas:attribute:: DataType: TFieldType
Тип данных.
Атрибут только для чтения
:rtype: TFieldType
.. code-block:: delphi
:caption: Пример использования
case Selection.FindField('bCheckInterval').DataType of
ftString: showmessage('String');
ftInteger, ftFloat: showmessage('Number');
ftDate, ftDateTime: showmessage('Date');
end;
TFieldType
~~~~~~~~~~~~~
.. pas:class:: TFieldType
Перечисление
Тип данных параметра PL/SQL скрипта.
.. pas:attribute:: ftSmallint
Поле 16-битных целых чисел
.. pas:attribute:: ftBoolean
Логическое поле
.. pas:attribute:: ftTime
Поле времени
.. pas:attribute:: ftOraClob
Поле CLOB данных в таблицах Oracle 8
.. pas:attribute:: ftTimeStamp
Поле даты и времени, доступное через dbExpress
.. pas:attribute:: ftBlob
Поле массивов двоичных данных
.. pas:attribute:: ftDateTime
Поле даты и времени
.. pas:attribute:: ftDate
Поле даты
.. pas:attribute:: ftCurrency
Денежное поле
.. pas:attribute:: ftFloat
Поле вещественных чисел
.. pas:attribute:: ftWord
Поле 16-битных целых положительных чисел
.. pas:attribute:: ftInteger
Поле 32-битных целых чисел
.. pas:attribute:: ftString
Поле символов или строк
.. pas:attribute:: ftWideString
Поле строк в кодировке Unicode
.. pas:attribute:: ftWideMemo
Поле CLOB данных в кодировке Unicode в таблицах Oracle
TbtkScriptFormObject
~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class:: TbtkScriptFormObject
TbtkScriptFormObject
.. pas:attribute:: Width: Integer
Ширина формы в пикселях, без учёта внешних границ окна.
.. warning:: Не реализовано
.. pas:attribute:: Height: Integer
Высота формы в пикселях, без учёта внешних границ окна и его заголовка.
.. warning:: Не реализовано
.. pas:attribute:: EvokedSelectionId: String
Идентификатор выборки создавшей форму
Атрибут только для чтения
:rtype: String
.. attention::
Если форма создана "не Lookup-ным" фреймом (то есть фреймом, не владеющим собственной выборкой, к примеру, :ref:`TbtkGridPanelFrame `),
то данное свойство вернет идентификатор мастера этого "не Lookup-ного" фрейма
.. warning:: Не реализовано
.. pas:method:: GetMainFrameSelection(): TbtkScriptSelectionObject
Возвращает выборку формы.
:rtype: TbtkScriptSelectionObject
.. code-block:: delphi
:caption: Пример использования
FormMDI := Application.GetActiveMDIWindow();
Selection := FormMDI.GetMainFrameSelection;
.. pas:method:: Close()
Метод закрывает окно. Вызов аналогичен нажатию на кнопку закрытия окна в
верхнем правом углу.
.. pas:method:: FindSelectionEx(EntityName: string; ParamNames, ParamValues: Variant): TbtkScriptSelectionObject
Ищет выборку на активной форме по системному имени выборки и отображению.
:param Variant EntityName:
Системное имя выборки.
:param Variant ParamNames:
Массив имён параметров. Может принимать следующие значения:
Representation
Отображение
FindChild
Поиск выборки только на текущем фрейме и компонентах расположенных на нем.
PrevSelection
Выборка, с фрейма которой начнётся поиск.
:param Variant ParamValues:
Массив значений параметров.
:rtype: TbtkScriptSelectionObject
.. pas:method:: FindSelection(EntityName: string): TbtkScriptSelectionObject
Ищет выборку на текущей форме по системному имени выборки.
:param string EntityName:
Имя выборки.
:rtype: TbtkScriptSelectionObject
.. pas:method:: BringToFront()
Метод делает немодальную :term:`форму<Форма>` активной, и передает ей фокус.
Если в приложении есть открытое модальное окно, форма не активируется.
.. seealso::
Подробнее про активацию :term:`встроенных форм<Встроенная форма>` в :ref:`builtin_activation_algorithms`
TbtkScriptCreateFormParamsObj
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class:: TbtkScriptCreateFormParamsObj
Класс обеспечивает доступ к параметрам переданным в ``CreateFormEx``.
.. pas:attribute:: Values
Массив значений параметров c доступом по индексу.
.. code-block:: delphi
:caption: Пример использования
Result := '';
Count := Selection.CreateFormParams.Count;
Result := 'Количество параметров переданных при создание формы: ' + IntToStr(Count);
Result := Result + #13#10 + 'Параметры:' + #13#10;
for i := 0 to Count - 1 do
begin
Result := Result + '('+ IntToStr(i)+')' + 'Name:' + Selection.CreateFormParams.Names[i] + '; ' +
'Value:'+ VarToStr(Selection.CreateFormParams.Values[i]) + '; '+
'ValueByName:' + VarToStr(Selection.CreateFormParams.GetValueByName(Selection.CreateFormParams.Names[i])) + ';' + #13#10;
end;
ShowMessage(Result);
.. pas:attribute:: Names
Массив имён параметров с доступом по индексу параметра в списке.
.. code-block:: delphi
:caption: Пример использования
Result := '';
Count := Selection.CreateFormParams.Count;
Result := 'Количество параметров переданных при создание формы: ' + IntToStr(Count);
Result := Result + #13#10 + 'Параметры:' + #13#10;
for i := 0 to Count - 1 do
begin
Result := Result + '('+ IntToStr(i)+')' + 'Name:' + Selection.CreateFormParams.Names[i] + '; ' +
'Value:'+ VarToStr(Selection.CreateFormParams.Values[i]) + '; '+
'ValueByName:' + VarToStr(Selection.CreateFormParams.GetValueByName(Selection.CreateFormParams.Names[i])) + ';' + #13#10;
end;
ShowMessage(Result);
.. pas:attribute:: Count
Количество переданных параметров.
.. code-block:: delphi
:caption: Пример использования
Result := '';
Count := Selection.CreateFormParams.Count;
Result := 'Количество параметров переданных при создание формы: ' + IntToStr(Count);
Result := Result + #13#10 + 'Параметры:' + #13#10;
for i := 0 to Count - 1 do
begin
Result := Result + '('+ IntToStr(i)+')' + 'Name:' + Selection.CreateFormParams.Names[i] + '; ' +
'Value:'+ VarToStr(Selection.CreateFormParams.Values[i]) + '; '+
'ValueByName:' + VarToStr(Selection.CreateFormParams.GetValueByName(Selection.CreateFormParams.Names[i])) + ';' + #13#10;
end;
ShowMessage(Result);
.. pas:method:: GetValueByName(Name: String): Variant
Функция возвращает значение параметра по имени.
:param String Name:
Имя параметра.
:rtype: Variant
.. code-block:: delphi
:caption: Пример использования
Result := '';
Count := Selection.CreateFormParams.Count;
Result := 'Количество параметров переданных при создание формы: ' + IntToStr(Count);
Result := Result + #13#10 + 'Параметры:' + #13#10;
for i := 0 to Count - 1 do
begin
Result := Result + '('+ IntToStr(i)+')' + 'Name:' + Selection.CreateFormParams.Names[i] + '; ' +
'Value:'+ VarToStr(Selection.CreateFormParams.Values[i]) + '; '+
'ValueByName:' + VarToStr(Selection.CreateFormParams.GetValueByName(Selection.CreateFormParams.Names[i])) + ';' + #13#10;
end;
ShowMessage(Result);
TbtkFormStyle
~~~~~~~~~~~~~~
.. pas:class:: TbtkFormStyle
Перечисление
Стиль формы
.. pas:attribute:: osLookUP
.. pas:attribute:: osModal
.. pas:attribute:: osNormal
TbtkPersistentType
~~~~~~~~~~~~~~~~~~~
.. pas:class:: TbtkPersistentType
Перечисление
Указывает место, куда сохраняются сериализованные стойкие (Persistent)
переменные. Если значение свойства **Persistent** отлично от **ptNone**,
переменная считается стойкой.
.. pas:attribute:: ptRegistry
Переменная является стойкой и сохраняет себя, и своё значение в реестре приложения при закрытии выборки.
.. pas:attribute:: ptNone
Переменная не является "стойкой" (не сохраняется при закрытии выборки).
T3State
~~~~~~~~~
.. pas:class:: T3State
Перечисление
.. pas:attribute:: stUnknown
.. pas:attribute:: stFalse
.. pas:attribute:: stTrue
TbtkNodeExpandMode
~~~~~~~~~~~~~~~~~~~~~
.. pas:class:: TbtkNodeExpandMode
Определяет условие и способ раскрытия узлов дерева.
Перечисление
.. pas:attribute:: emExpandAndLoadNodes
Раскрывать узлы и загружать, если еще не прогруженны.
.. pas:attribute:: emExpandOnlyLoadedNodes
Раскрывать только прогруженные узлы.
TbtkOperationTextMarkupType
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. pas:class:: TbtkOperationTextMarkupType
Перечисление.
Тип разметки текста скрипта.
.. pas:attribute:: otmtAutoDetect
Автоопределение. Проверяет наличие строки ``