API користувацького програмування
API користувацького програмування рушія візуалізації безпосередньо представлено об'єктами OpenSCADA, що формують користувацький інтерфейс, а саме "Сеансом" та "Віджетами-сторінками". Для користувача ці об'єкти надають набір функцій управління:
Об'єкт "Сеанс" ( this.ownerSess() )
- string user( ) — поточний користувач сеансу.
- int alrmQuietance( int quit_tmpl, string wpath = "", bool ret = false ) — стишує порушення wpath з шаблоном quit_tmpl. Якщо wpath це порожній рядок то здійснюється глобальне стишення. У рядку wpath, через символ ';', може бути перелічено адреси декількох віджетів. При встановлені ret здійснюється повернення стишення.
- int reqTm( ) — час останнього запиту у секундах від епохи 1.1.1970.
- string reqUser( ) — користувач останнього запиту.
- string reqLang( ) — мова останнього запиту.
- int userActTm( ) — час останньої дії користувача у секундах від епохи 1.1.1970.
- bool uiCmd( string cmd, string prm, string src ) — надсилає UI команду керування сторінками, як то: "open", "next", "prev"; детальніше дивиться у секції подій. Ця функція має бути пріоритетною для використання у керуванні сторінками перед прямим записом до атрибутів сторінок "pgOpen" та "pgOpenSrc", оскільки це єдиний метод коректної поводження з лінкованими сторінками.
- int period( bool isReal = false ) — отримання періоду опрацювання сеансу, isReal для реального періоду.
Об'єкт "Віджет" (this)
- TCntrNodeObj ownerSess( ) — об'єкт сеансу даного віджету.
- TCntrNodeObj ownerPage( ) — об'єкт батьківської сторінки даного віджету.
- TCntrNodeObj ownerWdg( bool base = false ) — об'єкт батьківського віджету даного віджету. При указанні base буде повернено й об'єкти сторінок.
- TCntrNodeObj wdgAdd( string wid, string wname, string parent ) — додає віджет wid з ім'ям wname на основі бібліотечного віджету parent.
//Додає новий віджет на основі віджету текстового примітиву
nw = this.wdgAdd("nw", "Новий віджет", "/wlb_originals/wdg_Text");
nw.attrSet("geomX", 50).attrSet("geomY", 50);
- bool wdgDel( string wid ) — видаляє віджет wid.
- TCntrNodeObj wdgAt( string wid, bool byPath = false ) — підключається до дочірнього або глобального віджету, за посередництвом шляху byPath. У випадку глобального підключення можна використати абсолютний або відносний шлях до віджету. Точкою відліку абсолютної адреси виступає об'єкт кореня модуля "VCAEngine", а значить, першим елементом абсолютної адреси є ідентифікатор сеансу, який опускається. Відносна адреса бере відлік від поточного віджету. Спеціальним елементом відносної адреси є елемент вищестоящого вузла "..".
- Array attrList() — перелік атрибутів віджету.
- bool attrPresent( string attr ) — перевіряє атрибут віджета attr на факт присутності.
- ElTp attr( string attr, bool fromSess = false ) — значення атрибуту віджету attr або з сеансу fromSess. Для відсутніх атрибутів повертає порожній рядок.
- TCntrNodeObj attrSet( string attr, ElTp vl, bool toSess = false ) — встановлює значення vl у атрибут віджету attr або сеанс, для toSess. Повертає поточний об'єкт, для конкатенації функцій встановлення.
- string link( string attr, bool prm = false ) — посилання атрибуту віджету attr. При встановленні prm запитує посилання групи атрибутів (параметр), представлене вказаним атрибутом.
- string linkSet( string attr, string vl, bool prm = false ) — встановлює посилання атрибуту віджету attr. При встановленні prm здійснює встановлення посилання групи атрибутів (параметр), представленого вказаним атрибутом.
//Встановлює посилання восьмого тренду параметром
this.linkSet("el8.name", "prm:/LogicLev/experiment/Pi", true);
- string {resource,mime}( string addr, string MIME = "" ) — ресурс об'єкту за адресою addr (пряме посилання на ресурс або атрибут віджету з цим посиланням) з типом MIME, з таблиці сеансу або джерела. Призначено для редагування ресурсу об'єкта та підставлення його у контексті сеансу, наприклад, зображень SVG.
- int {resourceSet,mimeSet}( string addr, string data, string MIME = "" ) — встановлює ресурс об'єкту у data з типом MIME за адресою addr.
- int messDebug( string mess ); int messInfo( string mess ); int messNote( string mess ); int messWarning( string mess ); int messErr( string mess ); int messCrit( string mess ); int messAlert( string mess ); int messEmerg( string mess ); — формує повідомлення програми mess з категорією — шлях до даного віджету.
- int calcPer( int set = EVAL ) — отримання, та встановлення за set не EVAL, щодо актуального періоду обчислення-опрацювання. Зарезервовано наступні спеціальні значення:
- 0 — якщо бажаєте періодичного опрацювання сеансу;
- -1 — якщо бажаєте використати період опрацювання батьківського віджету/сторінки/проєкту каскадно;
- -2 — для цілковитого вимкнення періодичного опрацювання.
- -3 — відсутній період часу сеансу, отримання проєктного.
Об'єкт "Віджет", примітиву "Документ" (this)
- string getArhDoc( int nDoc) — текст документу архіву на глибині nDoc (0-{aSize-1}).
Застаріле, але підтримуване, API представляється групою функцій безпосередньо у модулі рушія СВУ. Виклик цих функцій з процедури віджету може здійснюватися прямо за ідентифікатором, оскільки їх область імен визначається у контексті процедур віджетів.
Перелік віджетів (WdgList)
Опис: Повертає перелік віджетів, у контейнері віджетів, або дочірніх віджетів. Якщо встановлено pg, то повертається перелік сторінок проєктів та сеансу.
Параметри:
| Ідентифікатор | Ім'я | Тип | Режим | По замовчанню |
|---|---|---|---|---|
| list | Перелік | Рядок | Повернення | |
| addr | Адреса | Рядок | Вхід | |
| pg | Сторінки | Логічний | Вхід | 0 |
Присутність вузла (NodePresent)
Опис: Перевірка вузла на присутність, включаючи віджети, атрибути та інше.
Параметри:
| Ідентифікатор | Ім'я | Тип | Режим | По замовченню |
|---|---|---|---|---|
| rez | Результат | Логічний | Повернення | |
| addr | Адреса | Рядок | Вхід |
Перелік атрибутів (AttrList)
Опис: Повертає перелік атрибутів віджету. Якщо встановлено noUser тоді повертаються тільки атрибути не користувача.
Параметри:
| Ідентифікатор | Ім'я | Тип | Режим | По замовченню |
|---|---|---|---|---|
| list | Перелік | Рядок | Повернення | |
| addr | Адреса | Рядок | Вхід | |
| noUser | Без користувацьких | Логічний | Вхід | 1 |
Отримати атрибут (AttrGet)
Опис: Отримання значення атрибуту віджета. Запит може здійснюватися як указанням повної адреси атрибуту у addr, так і окремо: адресу віджету у addr та ідентифікатор атрибута у attr.
Параметри:
| Ідентифікатор | Ім'я | Тип | Режим | По замовченню |
|---|---|---|---|---|
| val | Значення | Рядок | Повернення | |
| addr | Адреса | Рядок | Вхід | |
| attr | Атрибут | Логічний | Вхід |
Встановити атрибут (AttrSet)
Опис: Встановлення значення атрибуту віджета. Встановлення може здійснюватися як указанням повної адреси атрибуту у addr, так і окремо: адресу віджету у addr та ідентифікатор атрибута у attr.
Параметри:
| Ідентифікатор | Ім'я | Тип | Режим | По замовченню |
|---|---|---|---|---|
| addr | Адреса | Рядок | Вхід | |
| val | Значення | Рядок | Вхід | |
| attr | Атрибут | Логічний | Вхід |
Користувач сеансу (SesUser)
Опис: Повертає користувача сеансу за шляхом віджета сеансу.
Параметри:
| Ідентифікатор | Ім'я | Тип | Режим | По замовченню |
|---|---|---|---|---|
| user | Користувач | Рядок | Повернення | |
| addr | Адреса | Рядок | Вхід |