Form.AddControl

InvokeEvent (Добавление нового элемента формы)
Объект: Форма Статус разработки: Реализована Тип: Функция Обращение к БД: Нет Исключения: Форма не визуальная или не загружена, невозможно превратить в строку, неверные параметры Визуальность: Да

• Начальная страница
• Общее описание
• Объекты
• Форма

Функция создает и помещает на форму новый визуальный элемент с указанными параметрами и событиями. Функция может использоваться для программного добавления произвольных элементов на формы (в т.ч. таблиц и OLE-объектов). Обычно вызывается в обработчике события OnOpen, но может быть вызвана в любой момент после инициализации формы. Функция может вызываться как для формы, так и для страницы группы страниц.

Синтаксис

Form.AddControl(<Тип визуального элемента (INT)>,<Имя элемента (STRING)>,<Значение элемента>,<Якоря элемента (INT)>,<Координаты элемента (STRING)>,<Параметры элемента (LIST)>,<События элемента (LIST)>):<Созданный визуальный элемент (FORM)>

Аргументы

• <Тип визуального элемента (INT)> - Задает тип добавляемого элемента. Для списка возможных значений, используйте данную статью.
• <Имя элемента (STRING)> - (необязательный аргумент) Задает наименования элемента, требуемое, чтобы можно было обратиться к элементу программно.
• <Значение элемента> - (необязательный аргумент) Задает значение, тип и назначение которого будет зависеть от типа добавляемого визуального элемента. А именно:
  • _FORM_LABEL, _FORM_BUTTON, _FORM_CHECKBOX, _FORM_RADIOBUTTON, _FORM_GROUPBOX: аргумент задает заголовок элемента (т.е., является строкой).
  • _FORM_EDITBOX: аргумент задает значение поля для редактирования.
  • _FORM_COMBOBOX, _FORM_LISTBOX: аргумент должен быть списком и копируется в значение результирующего элемента.
  • _FORM_IMAGE: аргумент должен быть картинкой.
  • _FORM_PAGECONTROL: аргумент должен быть списком, каждый элемент которого добавит новую закладку в группу страниц. Наименования элементов будут представлены, как заголовки закладок, а значения, как их имена.
  • _FORM_BEVEL, _FORM_SPLITTER: значение аргумента будет проигнорировано.
  • _FORM_OLE: аргумент задает строковой идентификатор нового объекта OLE.
  • _FORM_MACRO: строковой аргумент задает путь к макросу (пользовательскому компоненту)
  • _FORM_TABLE: аргумент должен быть таблицей значений и копируется в значение результирующего элемента.
  • _FORM_SFTABLE: аргумент должен быть электронной таблицей значений, и копируется в значение результирующего элемента (исходная таблица не привязывается к экранному элементу).
  • _FORM_TREELIST: аргумент должен быть деревом значений и копируется в значение результирующего элемента.
  • _FORM_TRACKBAR: аргумент должен быть числом -- значением элемента.
  • _FORM_PROGRESSBAR: аргумент должен быть числом -- значением элемента.
• <Якоря элемента (INT)> - (необязательный аргумент) Задает числовое значение -- битовую маску якорей элемента (его привязки к краям формы). По-умолчанию используется значение 9 (1001b). Доступны следующие биты:
  • бит 0: привязка к верху формы.
  • бит 1: привязка к правой сторое формы.
  • бит 2: привязка к низу формы.
  • бит 3: привязка к левой стороне формы.
• <Координаты элемента (STRING)> - Аргумент задает строковое значение с координатами элемента (до их изменения при применении масштаба на форме). Аргумент имеет следующий вид: x1,y1,x2,y2 (т.е. левая координата, верхняя координата, правая координата и нижняя координата).
• <Параметры элемента (LIST)> - (необязательный аргумент) Список, задающий любые другие параметры элемента. Имена в списке задают наименование параметра, значения -- его значение. Возможны следующие имена параметров (для описания параметров см. к примеру, отдельные статьи по визуальным элементам в статье Редактор форм):
  • areFoldersSelectable, arePeriodicalsIncludedInQuery, HasNoFocus, ifLoadLineParts, ifNotInSettings, ifQFiltersAlwaysAllowed, ifSetChangeFlag, isChecked, isDBAutoUpdate, isDefault, isDefaultControl, isDisabled, isDisabledNoParent, isEditable, isHyperlink, isInEnterChain, isInvisible, isMoveable, isMultiLine, isMultiSelectAllowed, isNoCaptions, isNoGridLines, isNoLevels, isNoScrolling, isOutlined, isPassword, isProportional, isReadOnly, isShowGroups, isTristate, isWithCheckboxes, isWrapped, doLoadFully, ifResizeWithParentX, ifResizeWithParentY, NoDisable, isBeveled: Параметры флагов элементов. Значения должны быть числом 1 или 0.
  • Color: Цвет элемента (число).
  • OutlineColor: Цвет рамки картинки (число).
  • FontColor: Цвет шрифта элемента (число).
  • Font: Наименование шрифта элемента в формате записи шрифтов в системе.
  • DropDownCount: Количество строк на экране для полей со списком.
  • Folders: Режим отображения папок в таблице, привязанной к базе данных. Доступны следующие значения:
    • 0: Отображать в общей структуре.
    • 1: Отображать вверху списка.
    • 2: Не отображать.
    • 3: Отображать только папки.
  • isHorizontal: Флаг, использующийся для разделителя, указывает на то, является ли разделитель горизонтальным или вертикальным. Также используется для элементов выбора бегунком и индикатора выполнения.
  • InitialPage: Число, задает текущую страницу группы страниц с закладками.
  • EditorMode: Число, задает режим редактирования электронных таблиц. Доступны следующие режимы:
    • 0: Запретить редактирование.
    • 1: Редактируются только незащищенные ячейки (умолчание).
    • 2: Разрешить редактирование.
  • GroupName: Строка, наименование группы, к которой принадлежит переключатель (_FORM_RADIOBUTTON).
  • Hint: Строка, всплывающая подсказка элемента.
  • HotKey: Строка, задающая комбинацию быстрого вызова (см. Hotkey).
  • HAlign: Число, задающее горизонтальное выравнивание теста элемента. Может принимать следующие значения:
    • 0: Выравнивать текст к левому краю.
    • 1: Выравнивать текст к середине элемента.
    • 2: Выравнивать текст к правому краю.
  • VAlign: Число, задающее вертикальное выравнивание теста элемента. Может принимать следующие значения:
    • 0: Выравнивать текст к верхнему краю.
    • 1: Выравнивать текст к середине элемента.
    • 2: Выравнивать текст к нижнему краю.
  • Sizing: Число, режим поведения картинки. Может принимать следующие значения:
    • 0: Не изменять размер картинки.
    • 1: Уменьшать размер картинки, если она больше размера визуального элемента.
    • 2: Уменьшать или увеличивать размер картинки, если ее размер не совпадает с размером визуального элемента.
  • Shape: Число, задает форму объемного региона оформления. Доступны следующие значения:
    • 0: Горизонтальная линия.
    • 1: Вертикальная линия.
    • 2: Ящик.
    • 3: Рамка.
  • Style: Число, задает стиль объемного региона оформления. Доступны следующие значения:
    • 0: Вдавленный.
    • 1: Выпуклый.
  • MaxValue, MinValue: Числа максимального и минимального возможного значения элемента (к примеру для элементов выбора бегунком или индикатора выполнения)
  • SelectionStart, SelectionEnd: Числа начала и окончания выделения для элемента выбора бегунком
  • TrackbarMode: Число, задает режим отображения бегунка и выделения для элемента выбора бегунком. Доступны следующие значения:
    • 0: Без бегунка и диапазона выделения
    • 1: Отображать бегунок, но без диапазона выделения
    • 2: Без бегунка, отображать диапазон выделения
    • 3: Отображать бегунок и диапазон выделения
  • TicksMode: Число, задает режим отображения отметок для элемента выбора бегунком. Доступны следующие значения:
    • 0: Не отображать отметки
    • 1: Отметки снизу (справа)
    • 2: Отметки сверху (слева)
    • 3: Отметки с обеих сторон
  • OnChangeMode: Число, задает режим изменения положения бегунка пользователем для элемента выбора бегунком. Доступны следующие значения:
    • 0: Бегунок может изменяться как мышью (даже при движении с нажатой левой кнопкой мыши), так и клавиатурой, элемент принимает фокус (для изменений клавиатурой).
    • 1: Бегунок будет изменяться мышью только при отпускании левой кнопки мыши (не при движении); также может изменяться клавиатурой, элемент принимает фокус (для изменений клавиатурой).
    • 2: Бегунок может изменяться мышью (даже при движении с нажатой левой кнопкой мыши), однако не может изменяться клавиатурой, элемент не принимает фокус.
    • 3: Бегунок будет изменяться мышью только при отпускании левой кнопки мыши (не при движении); также не может изменяться клавиатурой, элемент не принимает фокус.
    • 4: Изменения бегунка мышью не будут изменять его значения; также не может изменяться клавиатурой, элемент не принимает фокус. Для полного запрета движения бегунка мышью, используйте свойство IsDisabled.
  • LineSize: Число, задает величину увеличения или уменьшения значения бегунка для элемента выбора бегунком при использовании стрелок на клавиатуре.
  • PageSize: Число, задает величину увеличения или уменьшения значения бегунка для элемента выбора бегунком при использовании кнопок PageUp / PageDown на клавиатуре.
  • LinesFrequency: Число, задает частоту (в точках) отображения отметок для элемента выбора бегунком.
  • PaperColor: Цвет окна элемента индикатора выполнения (число).
  • InkColor: Цвет заливки элемента индикатора выполнения (число).
  • Scale: Число, задает масштаб отображения электронной таблицы.
  • Picture: Число, номер картинки из библиотеки картинок, используемой на визуальном элементе (на кнопке)
  • Layer: Строка, задает имя слоя, которому принадлежит элемент.
  • Length: Число, задает максимальную длину текстового поля в символах.
  • Mask: Строка, задает маску редактирования текстового поля.
  • MaxWidth, MaxHeight: Число, задает максимальную ширину и высоту элемента соответственно (в пикселях).
  • InitialSortString: Строка, задает строку начальной сортировки для таблицы, привязанной к базе данных.
  • PartialLoadingModeColumns: Строка, задает наименования столбцов таблицы загрузки в режиме частичной загрузки объектов для таблицы, привязанной к базе данных.
  • AttachedButtons, EditorAttachedButtons: Таблица, задающая связанные элементы, используемые для элемента или для редактора списка соответственно. Таблица должна иметь как минимум столбец ID (идентификатор связанного элемента), но также могут использоваться значения столбцов Caption (заголовок кнопки), Hint (всплывающая подсказка кнопки), HotKey (быстрая комбинация вызова кнопки), Flags (битовая маска -- бит 0: использовать добавочную кнопку, бит 1: использовать разделитель).
• <События элемента (LIST)> - (необязательный аргумент) Список, задающий программный код событий элемента. Имена списка должны совпадать с именами добавляемых событий, а значения списка могут быть строками (события добавляются в виде текста) или объектом компилированной функции. Разрешается задавать исполняемый код следующих событий: OnGetCaption, OnClick, OnDoubleClick, OnGetRightClickMenu, OnRightClick, OnKeyPress, OnChecking, OnLeafChecking, OnChangeOrClick, OnDataChange, OnBeforeChange, OnAfterChange, OnBeforeResize, OnAfterResize, OnAfterNewElementCreated, OnBeforeElementSaved, OnAfterElementSaved, OnBeforeRefresh, OnAfterFilterChange, OnAfterSorting, OnBeforeEditLine, OnBeforeEditCell, OnAfterEditLine, OnAfterEditCell, OnBeforeEdit, OnAfterEdit, OnGetLine, OnGetVisualProperties, OnInitComboBox, OnEnter, OnExit, OnAttachedButtons, OnBeforeSelect, OnBeforeEditObject, OnGetCellVisualProperties, OnInitLine, OnBeforeLoadElements, OnShowLine, OnInitLeaf, OnGetFormNameForOperation, OnMoveToFolder, OnSaveLoadObject, OnSelectionChange. Для событий OLE-объектов используется запись ONOLE_<Имя события>. Описание событий можно найти в статье Визуальные события.

Возвращаемое значение

Функция возвращает объект нового созданного визуального элемента формы.

Примеры

//Добавление на форму визуального элемента списка значений

//Параметры элемента
спПараметры:=List.Create();
спПараметры["Font"]:="Default, 10";
спПараметры["IsNoGridLines"]:=1;

//Связанные элементы
тКнопки:=Tab.Create("ID,Caption,Hint,HotKey,Flags");
тКнопки.AddLine("ID,Caption",_ABB_ADDONE,"Добавить");
тКнопки.AddLine("ID",_ABB_DELALL);

спПараметры["AttachedButtons"]:=тКнопки;

//Начальные значения списка
спЗначение:=List.Create();
спЗначение.Add(1,"Элемент 1");
спЗначение.Add(2,"Элемент 2");
спЗначение.Add(3,"Элемент 3");

спСобытия:=List.Create();
спСобытия["OnAttachedButtons"]:="Сп:=Form.оНовыйСписок.Value;
|If Index=_ABB_DELALL Then
|  Сп.Clear();
|ElseIf Index=_ABB_ADDONE Then
|  Сп.Add(""Новое значение"");
|EndIf;
";

//Добавление элемента
Form.AddControl(_FORM_LISTBOX,"оНовыйСписок",спЗначение,15,"5,5,200,200",спПараметры,спСобытия);