Дмитро Медведенко

Розширення LIRA-FEM

Змінено 26.05.2026 | Створено 25.05.2026

LIRA-FEM дозволяє перетворювати у розрахункові схеми файли певних форматів, таких як .DXF або .IFC, а також змінювати розрахункові схеми за допомогою методів LIRA-FEM API.

Розширення LIRA-FEM, будучи частиною LIRA-FEM API, дозволяють зовнішнім програмам підключати свої команди до стрічки LIRA-FEM, свої розрахунки до будь-якого з етапів розрахунків LIRA-FEM, свої звіти до системи документування LIRA-FEM, включати свої дані до складу Lir-файлу та передавати їх у зовнішні застосунки з підтримкою редагування.

Ця стаття пояснює, як створювати розширення LIRA-FEM та користуватися переліченими вище можливостями розширень. Стаття побудована так, що простіші техніки описані вище, а складніші — нижче. Найпростіше розширення можна створити, користуючись лише відомостями з підрозділу «Швидкий старт». Наприкінці статті міститься довідник з підключення модулів розширень, написаних різними мовами програмування.

Зміст

Швидкий старт

Найпростіше розширення LIRA-FEM складається з виконуваного файлу та запису в реєстрі. Давайте створимо розширення, яке виводить на екран традиційне привітання на кшталт «Привіт, світ!» за кнопкою, що з'явиться на стрічці LIRA-FEM. Для цього створимо текстовий файл з функцією HelloLira мовою VBScript, як у лістингу нижче, і збережемо його за шляхом C:\Users\Public\Documents\Hello.vbs. 

Sub HelloLira
    MsgBox "Well, hello there, LIRA!"
End Sub

Тепер необхідно створити на стрічці LIRA-FEM кнопку, яка викликатиме цю функцію. Для цього необхідно внести до реєстру Windows кілька розділів та параметрів. Найпростіше це зробити, перерахувавши необхідні розділи з їхніми параметрами у файлі з розширенням *.reg, а потім виконати його. Створимо текстовий файл C:\Users\Public\Documents\Hello.reg з вмістом, як у лістингу нижче. 

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\LIRA EXTENSIONS\hli]
@="Script:VBS"
[HKEY_LOCAL_MACHINE\SOFTWARE\LIRA EXTENSIONS\hli\HelloLira]
@="C:\\Users\\Public\\Documents\\Hello.vbs"

Тепер необхідно виконати його. Для цього викличте вікно «Виконати» («Run») за допомогою комбінації клавіш Win+R, введіть у вікно, що з'явилося, шлях до файлу з розділами та параметрами реєстру C:\Users\Public\Documents\Hello.reg, та натисніть кнопку ОК.

Рис.1

Рис.1

Операційна система запитає підтвердження на виконання цієї дії — дозвольте його. Після цього редактор реєстру («Registry Editor») повторно запросить дозвіл на додавання до реєстру потрібних розділів та параметрів — дозвольте й це, натиснувши кнопку «Так» («Yes»).

Рис.2

Рис.2

І нарешті, редактор реєстру має показати вікно, в якому підтверджується внесення даних до реєстру. Це вікно можна просто закрити.

Рис.3

Рис.3

Тепер переконаємось, що кнопка додалася до стрічки LIRA-FEM. Запустимо LIRA-FEM. Якщо під час виконання дій вище вона вже була запущена, необхідно її перезапустити. Після запуску можна переконатися, що у стрічці LIRA-FEM з'явилася нова вкладка «Інструменти» («Tools»), а на ній з'явилася кнопка без піктограми, але з написом «HelloLira». З'явилося також меню «Інструменти hli» з пунктом «HelloLira».

Рис.4

Рис.4

Давайте натиснемо на кнопку «HelloLira», щоб переконатися, що вона справді викличе нашу функцію HelloLira. Після натискання на неї з'являється вікно, яке запитує дозвіл на завантаження до пам'яті виконуваного модуля, невідомого LIRA-FEM та без надійного цифрового підпису. Оскільки ми самі щойно написали цей виконуваний модуль, хвилюватися нема про що, і ми просто дозволяємо його роботу, вибравши опцію «Дозволити завантаження та виконання цього застосунку-розширення LIRA-FEM і більше не питати» («Allow this LIRA-FEM extension to load and run, and do not ask again») та натиснувши OK.

Рис.5

Рис.5

Після цього наша функція виконується, показавши віконце «Ну, привіт, ЛІРА!» («Well, hello there, LIRA!»)

Рис.6

Рис.6

Натиснемо у цьому віконці кнопку OK і запустимо нашу команду ще раз. Цього разу вікно із запитом дозволу на завантаження не з'являється, і віконце «Ну, привіт, ЛІРА!» («Well, hello there, LIRA!») викликається негайно.

Кнопка без піктограми на абсолютно порожній вкладці «Інструменти» («Tools») на перший погляд здається надміру аскетичною, але ж і зусиль на її створення ми витратили мінімум. Можливості розширень LIRA-FEM зі створення кнопок на стрічці жодним чином не поступаються можливостям самої програми LIRA-FEM, і підтвердженням цього може слугувати вкладка «Дерево» («Timber»), яка повністю побудована однойменним розширенням LIRA-FEM.

Рис.7

Рис.7

Нові вкладки, панелі та піктограми команд — все це можна додати до стрічки LIRA-FEM за допомогою відповідних функцій LIRA-FEM API або параметрів реєстру Windows. Детальний перелік останніх наведено наприкінці цього розділу довідкової системи.

У підрозділі «Швидкий старт» ми познайомилися з бліц-способом створення розширень LIRA-FEM, однак не завжди зручно задіювати функції розширень лише за натисканням кнопок на стрічці. Наступні підрозділи описують важливі подробиці та корисні можливості LIRA-FEM API для редагування розрахункової схеми.


Підтримувані мови програмування

Найпростіше розширення, яке ми створили у підрозділі «Швидкий старт», було написано інтерпретованою мовою VBScript. Щоб вказати програмі LIRA-FEM, інтерпретатор якої мови завантажувати, ми додали до реєстру параметр @="Script:VBS". Окрім інтерпретованої мови VBScript, LIRA-FEM підтримує такі інтерпретовані мови програмування для створення розширень: JScript та V8Script. Якщо VBScript і JScript — це добре відомі мови, вже давно вбудовані в операційну систему Microsoft Windows, то мова V8Script, або V8 JavaScript, — це відносно молода різновидність мови JavaScript, розроблена компанією Google. Якби ми написали наше розширення мовою JScript або V8, нам довелося б у файлі з розділами та параметрами реєстру написати замість @="Script:VBS" відповідно @="Script:JS" або @="Script:V8".

Окрім трьох інтерпретованих мов програмування, LIRA-FEM підтримує розширення, написані компільованими мовами програмування, що підтримують технологію COM (Component Object Model) або .NET, якими є практично всі сучасні мови програмування. Розширення, написані компільованою мовою програмування, можуть бути двох видів: виконуваний модуль *.EXE або динамічна бібліотека *.DLL. Для написання застосунків перевагу слід надавати динамічним бібліотекам, оскільки вони дозволяють викликати методи LIRA-FEM API без необхідності виконувати додатковий маршалінг параметрів. Якщо виклик одного методу LIRA-FEM API з виконуваного модуля *.EXE може зайняти кілька мілісекунд, то виклик того самого методу з динамічної бібліотеки *.DLL може зайняти наносекунди, тобто в мільйони разів швидше. Проте для реєстрації розширень у виконуваних модулях *.EXE передбачено параметр реєстру @="Exe:App". Динамічні бібліотеки *.DLL можуть бути скомпільовані в код .NET CLR (Common Language Runtime) з таких мов, як C# або VB.NET тощо, або в нативний код з таких мов, як C, C++ тощо. Параметри реєстру для реєстрації розширень *.DLL у LIRA-FEM залежать від обраної мови програмування. Для реєстрації бібліотеки класів, написаної мовою .NET CLR C# або VB.NET, передбачено параметр @="Dll:Net4", а для бібліотеки на нативному коді, написаної мовою С/С++ або іншими мовами, рядок реєстрації буде або @="Dll:stdcall", або @="Dll:cdecl" — залежно від угоди про виклики функцій розширення, що викликаються з LIRA-FEM. Угода про виклик stdcall є найпоширенішою, однак у С/С++ вимагає при оголошенні функції ключового слова __stdcall. Якщо ключове слово __stdcall відсутнє при оголошенні функцій, що викликаються з розширення програмою LIRA-FEM, то для реєстрації розширення слід внести до реєстру параметр @="Dll:cdecl".


Ідентифікатор розширення

У підрозділі «Швидкий старт» для того, щоб ідентифікувати наше бліц-розширення, ми додали до розділу реєстру Windows HKEY_LOCAL_MACHINE\SOFTWARE\LIRA EXTENSIONS параметр hli. Як видно, цей параметр складається з трьох букв латинського алфавіту. Це обмеження пов'язане з розширеннями файлів і буде детальніше пояснено у підрозділі «Вимоги до іменування файлів результатів» нижче.

Ідентифікатор розширення — трибуквений параметр, який може складатися лише з букв латинського алфавіту та цифр.

Для реєстрації розширення LIRA-FEM необхідно у розділі реєстру Windows HKEY_LOCAL_MACHINE\SOFTWARE\LIRA EXTENSIONS створити новий розділ з іменем — ідентифікатором розширення.

Як параметр за замовчуванням розділу реєстру — ідентифікатора розширення — слід вказати інструкцію щодо завантаження такого розширення, одне з таких рядкових значень:

  • Script:VBS – для розширення, написаного мовою VBScript.
  • Script:JS – для розширення, написаного мовою JScript.
  • Script:V8 – для розширення, написаного мовою V8 Java Script.
  • Dll:Net4 – для розширення, написаного у вигляді динамічної бібліотеки *.DLL, скомпільованої в код CLR мовами, що підтримують .NET Framework версії 4 (С#, VB.NET, managed C++ тощо).
  • Dll:stdcall – для розширення, написаного у вигляді динамічної бібліотеки *.DLL, скомпільованої в нативний код мовами, що підтримують роботу з COM-об'єктами (C/С++ тощо); функції мають угоду про виклик stdcall.
  • Dll:cdecl – для розширення, написаного у вигляді динамічної бібліотеки *.DLL, скомпільованої в нативний код мовами, що підтримують роботу з COM-об'єктами (C/С++ тощо); функції мають угоду про виклик cdecl.
  • Exe:App – для розширення, написаного у вигляді окремого виконуваного модуля .EXE.

Реєстрація функцій розширення для запуску з LIRA-FEM

У підрозділі «Швидкий старт» ми створили користувацьке розширення, яке складається з однієї функції, що запускається при натисканні відповідної кнопки на стрічці. Щоб вказати програмі, яку кнопку на стрічці створювати та яку функцію слід викликати при її натисканні, ми створили у розділі реєстру з іменем — ідентифікатором розширення HKEY_LOCAL_MACHINE\SOFTWARE\LIRA EXTENSIONS\hli підрозділ HelloLira.

Важливо, що ім'я підрозділу HelloLira збіглося з іменем функції у файлі C:\Users\Public\Documents\Hello.vbs, а шлях до цього файлу ми вказали для підрозділу як параметр за замовчуванням: 

[HKEY_LOCAL_MACHINE\SOFTWARE\LIRA EXTENSIONS\hli\HelloLira]
@="C:\\Users\\Public\\Documents\\Hello.vbs"

Так ми повідомили програмі LIRA-FEM, у якому файлі та з яким іменем шукати функцію. Оскільки ми не вказали, у який момент слід викликати функцію HelloLira, програма вчинила за замовчуванням, тобто розмістила кнопку з такою назвою на вкладці за замовчуванням, тобто на вкладці «Інструменти» («Tools»).

Виклик функції розширення API за натисканням кнопки на стрічці або вибором пункту меню — це лише один зі способів підключення функцій розширення до LIRA-FEM. Щоб вказати спосіб і момент виклику функції розширення, слід у розділі реєстру Windows з іменем функції створити рядковий параметр з іменем «CallAfter», значення якого може бути одним з таких:

  • Button – викликати функцію при натисканні кнопки на стрічці або при виборі відповідного їй пункту меню (параметр за замовчуванням).
  • AppStartup – викликати функцію після завантаження застосунку LIRA-FEM до створення або відкриття документа з розрахунковою схемою.
  • Analysis000 – викликати функцію перед запуском скінченно-елементного розрахунку.
  • AnalysisFEA – викликати функцію після виконання скінченно-елементного розрахунку (Finite Element Analysis).
  • AnalysisCLA – викликати функцію після виконання розрахунку Сполучень Навантажень і Впливів (Combinations of Load And Actions).
  • AnalysisDCF – викликати функцію після виконання розрахунку Розрахункових Сполучень Зусиль (Design Forces Combinations).
  • AnalysisUCF – викликати функцію після виконання розрахунку Уніфікації Розрахункових Сполучень Зусиль (Unified Forces Combinations).
  • AnalysisDCL – викликати функцію після виконання розрахунку Розрахункових Сполучень Навантажень (Design Load Combinations).
  • AnalysisLoF – викликати функцію після виконання розрахунку Навантажень на Фрагмент за завантаженнями (Loads of Fragment).
  • AnalysisPES – викликати функцію після виконання розрахунку головних і еквівалентних напружень (Principal and Equivalent Stresses).
  • AnalysisCRK – викликати функцію після розрахунку тріщин нелінійних задач (Cracks).
  • AnalysisDOs – викликати функцію після конструктивних розрахунків за варіантами конструювання (Design Options).
  • AnalysisCSV – викликати функцію після запису CSV-файлів з результатами розрахунку (Comma Separated Values).

Якщо жоден з перерахованих вище параметрів не вказано, то приймається параметр за замовчуванням, тобто параметр Button.

Може трапитися так, що одна функція розширення має бути викликана після виконання функції якогось іншого розширення на тому самому етапі виконання. Тоді важливо вказати не просто етап, а й послідовність виконання функцій розширення. Для цього після будь-якого значення від AppStartup до AnalysisCSV може бути вказано момент запуску у вигляді числа double після знака «+», наприклад: в одному розширенні можна вказати AnalysisFEA + 10.0, а в іншому AnalysisFEA + 20.0. Чим більше вказане число double, тим пізніше запускатиметься функція розширення, тобто одразу після скінченно-елементного розрахунку спочатку буде викликано функцію зі значенням AnalysisFEA + 10.0, а потім AnalysisFEA + 20.0.

Реєстрацію функцій розширення можна здійснювати не лише за допомогою ключів реєстру, а й за допомогою методів LIRA-FEM API, причому останній надає більше можливостей, однак у реєстрі Windows у будь-якому разі має бути зареєстрована принаймні одна функція розширення, щоб передати їй керування та таким чином дати розширенню можливість викликати методи LIRA-FEM API. Неважко припустити, що, як правило, це буде функція, вказана з параметром "CallAfter"="AppStartup".


Керування виглядом кнопки на стрічці

У своєму прикладі у підрозділі «Швидкий старт» ми створили кнопку, яка отримала ім'я за замовчуванням, розмістилася на вкладці стрічки LIRA-FEM за замовчуванням, а піктограми взагалі не мала. Все це легко налаштувати за допомогою відповідних параметрів розділу реєстру Windows з іменем — ідентифікатором розширення та з іменем функції розширення, що викликається; у нашому прикладі це розділи HKEY_LOCAL_MACHINE\SOFTWARE\LIRA EXTENSIONS\hli та HKEY_LOCAL_MACHINE\SOFTWARE\LIRA EXTENSIONS\hli\HelloLira.

У розділі реєстру з іменем — ідентифікатором розширення — допускаються рядкові параметри з такими іменами:

  • RibbonTab – ім'я нової вкладки стрічки LIRA-FEM для розміщення кнопок, що викликають функції розширення.
  • RibbonTabImageListSmall – шлях до файлу із зображеннями піктограм 16x16 для кнопок (або 24x24 у режимі «Великі значки на стрічці»).
  • RibbonTabImageListLarge – шлях до файлу із зображеннями піктограм 32x32 для кнопок (або 48x48 у режимі «Великі значки на стрічці»).

У розділі реєстру з іменем — іменем функції розширення — допускаються рядкові параметри з такими іменами:

  • Name – текст на кнопці
  • ToolTip – назва кнопки, відображається разом з описом кнопки у вікні підказки при наведенні курсора миші на кнопку стрічки.
  • Description – опис кнопки, відображається після назви кнопки у вікні підказки при наведенні курсора миші на кнопку стрічки.
  • RibbonImageSmall – номер, від 0, піктограми кнопки у файлі, вказаному в параметрі RibbonTabImageListSmall у розділі з ідентифікатором розширення, або шлях до файлу із зображенням піктограми 16x16 для кнопки (або 24x24 у режимі «Великі значки на стрічці»).
  • RibbonImageLarge – номер, від 0, піктограми кнопки у файлі, вказаному в параметрі RibbonTabImageListLarge у розділі з ідентифікатором розширення, або шлях до файлу із зображенням піктограми 32x32 для кнопки (або 48x48 у режимі «Великі значки на стрічці»).
  • RibbonAlwaysLarge – при зменшенні розміру вікна кнопка на стрічці не стає меншою за розміром; допустимі значення «1» або «0».
  • RibbonPanel – ім'я панелі, всередині якої розміщується кнопка, на вкладці стрічки.

Значення параметра RibbonTabImageListSmall, RibbonTabImageListLarge, RibbonImageSmall, RibbonImageLarge може містити шлях до зображення .PNG, .BMP або .ICO для однієї або кількох кнопок. Можна вказати або повний шлях до файлу зображення, що зберігається на диску, або повний шлях до зображення, що зберігається в ресурсах нативного застосунку або динамічної бібліотеки .EXE або .DLL. В останньому випадку після шляху до файлу .EXE або .DLL повинна слідувати коса риска та ідентифікатор зображення-ресурсу. Наприклад: C:\path\to\dll\file.dll/#1001 — ресурс має числовий ідентифікатор «1001». Ще приклад: C:\path\to\dll\file.dll/PNG1 — ресурс має рядковий ідентифікатор «PNG1». Можна вставити підказку-тип ресурсу, наприклад: C:\path\to\dll\file.dll/PNG/#1001 — ресурс типу зображення .PNG має числовий ідентифікатор, що дорівнює «1001». Ще приклад: C:\path\to\dll\file.dll/PNG/PNG1 — ресурс типу зображення .PNG має рядковий ідентифікатор «PNG1».

Замість /PNG/ можна вказати /BMP/ або /2/ для зображень типу .BMP або /ICO/ або /14/ для зображень типу .ICO. Якщо підказки немає, то завантажується .PNG, якщо він не знайдений — .BMP, якщо він не знайдений — .ICO.

RibbonTabImageListSmall, RibbonTabImageListLarge повинен містити горизонтальний спрайт із зображень розміром відповідно 16x16 і 32x32. Якщо увімкнено налаштування «Великі значки на стрічці», то горизонтальний спрайт повинен складатися із зображень відповідно 24x24 і 48x48. Якщо розміри зображень у спрайті інші, вони будуть масштабовані до потрібних.

RibbonImageSmall, RibbonImageLarge може містити не лише шлях до зображення відповідної кнопки, а й номер зображення у спрайті, відповідно, RibbonTabImageListSmall і RibbonTabImageListLarge, починаючи від 0. Якщо для всіх кнопок параметри RibbonImageSmall, RibbonImageLarge вказані у вигляді шляхів до відповідних зображень, то немає необхідності створювати спрайти кнопок і вказувати їх у параметрах RibbonTabImageListSmall, RibbonTabImageListLarge. І навпаки, немає необхідності створювати окреме зображення для кнопки, якщо воно вже є у спрайті. У цьому випадку достатньо просто вказати номер зображення у відповідному спрайті в параметрі RibbonImageSmall або RibbonImageLarge.


Виклик контекстної довідки

Якщо ви створюєте розширення, яким будуть користуватися не лише ви, а й інші люди, то швидше за все захочете додати до команд свого розширення також і команду для виклику довідки. Однієї команди для виклику довідки невеликого розширення зазвичай цілком достатньо. Але якщо у вас багато команд, і для кожної з них передбачено свій розділ довідкової системи, то логічніше скористатися так званою контекстною довідкою, тобто при натисканні клавіші F1 на клавіатурі викликати той розділ вашої довідкової системи, який відповідає кнопці, над якою в даний момент знаходиться курсор миші. Інший спосіб викликати контекстну довідку на команду стрічки — це натиснути комбінацію клавіш Shift+F1 і, після того як курсор миші перетвориться на стрілочку зі знаком питання, клацнути цим курсором на цікаву кнопку стрічки. LIRA-FEM має вбудовану контекстну довідку, яка так працює, і розширення LIRA-FEM також можуть підключитися до цієї довідки.

Для того, щоб контекстна довідка викликалася для вашої кнопки на стрічці, необхідно до параметрів розділу реєстру Windows з іменем команди розширення додати параметр «HelpCommand». Наприклад, таке значення параметра закріплює за кнопкою контекстну довідку у вигляді відкриття файлу PDF: "HelpCommand"="c:\Users\Public\Documents\ReadMe.pdf". А ось приклад з викликом довідки з Інтернету: "HelpCommand"="https://sites.google.com/view/help/home". І, нарешті, приклад виклику розділу з файлу формату .CHM — такого самого, який використовує LIRA-FEM для своєї довідкової системи: "HelpCommand"="HH.EXE C:\Program Files (x86)\LIRALAND\LIRA-FEM 2026\bin\x64\help\ru\LiraFEM.chm::/Explain/_LiraSaprApi.htm"


Візуалізація даних розширення за допомогою мозаїк

Припустимо, що ваше розширення зчитало щось із вихідних даних, а щось — з результатів розрахунку LIRA-FEM, виконало свій власний розрахунок і записало файл з результатами свого розрахунку. Тепер перед користувачем вашого розширення постало питання якісної оцінки результатів вашого розрахунку. Для якісної оцінки можна скористатися можливостями, які надають таблиці введення LIRA-FEM для побудови користувацьких мозаїк. Фактично це метод побудови мозаїки, яка на вузлах або елементах розрахункової схеми у вигляді мозаїки відображає довільні користувацькі значення.

Наприклад, наступна функція створює у вікні раніше відкритої розрахункової схеми мозаїку, розфарбовуючи її 1-й і 2-й елементи. 

 Sub CreateMosaic()
    ' Підключаємося до об’єкта LiraApplication і отримуємо активний документ із розрахунковою схемою
    Set LiraApp = CreateObject("LiraFEM.Application")
    Set Doc = LiraApp.ActiveDocument
    ' Створюємо таблицю мозаїки (46=kLiraTable_UserMosaicData)
    Params1 = Array("Element text mosaic" ,  11 , 1)
    Set Mosaic1 = Doc.AllTables.CreateNewItem ( 46 , (Params1) )
 
    ' Дані для мозаїки (масив 2D)
    Dim Data1(1,4)
    Data1(0,1) = 1 :  Data1(0,3) = "1.1 Червонмй колір" :  Data1(0,4) = "#ff4444"
    Data1(1,1) = 2 :  Data1(1,3) = "2.2 Зелений колір" :  Data1(1,4) = "#008800"
    ' Заповнюємо таблицю
    Mosaic1.SetContents(Data1)
    ' Впроваджуємо зміни
    Mosaic1.Apply(strErrs)
    'Прибираємо за собою — видаляємо щойно створену таблицю
    Doc.AllTables.Delete(Doc.AllTables.ItemCount-1)
End Sub

У наведеному вище прикладі кожному елементу призначається свій текст і свій колір. Щоб створилася мозаїка саме такого типу, у функцію CreateNewItem для створення нової таблиці введення передається масив параметрів. Перший параметр — це назва мозаїки, «Element text mosaic». Другий параметр — це тип вмісту таблиці: число 11 означає, що таблиця буде заповнена для кожного елемента числом і супутнім коментарем. Третій параметр 1 вмикає в таблиці стовпець з кольорами. Підтримуються такі типи вмісту таблиці для побудови мозаїк:

  • 0 — число в кожному вузлі для мозаїки на вузлах
  • 1 — число в кожному елементі для мозаїки на елементах
  • 2 — число в кожному розрахунковому перерізі елементів для мозаїки на елементах (лише для стержнів)
  • 3 — число в кожному розрахунковому перерізі елементів для епюр на елементах (лише для стержнів)
  • 4 — число в кожному елементі для ізополів (лише для пластин)
  • 10 — число і текст в кожному вузлі для мозаїки на вузлах
  • 11 — число і текст в кожному елементі для мозаїки на елементах

Тут слід зазначити, що замість мозаїки за розрахунковими перерізами стержнів можна побудувати епюру за розрахунковими перерізами, тип 3. А замість мозаїки на пластинах можна побудувати ізополя, тип 4.


Глибша інтеграція

Усю інформацію та приклади, які були наведені вище в цьому розділі, можна було відтворити будь-якою мовою програмування, зокрема інтерпретованими мовами сценаріїв на кшталт VBScript або JScript. У нижчевикладених підрозділах ми торкнемося можливостей, які недоступні з інтерпретованих мов.

Для початку ми опишемо, як реєструвати функції розширення та керувати виглядом кнопок не за допомогою параметрів реєстру Windows, як вже було описано у підрозділах вище, а за допомогою функцій LIRA-FEM API. Далі ми торкнемося більш просунутих можливостей, таких як реакція на зміну номера поточного завантаження або на запуск довільної команди з меню або стрічки інструментів LIRA-FEM, зберігання вихідних даних розширення всередині файлу розрахункової схеми та документування вихідних даних і результатів розрахунку розширення в системі «Книга звітів». Щоб продовжити читання цього розділу далі, вам знадобляться додаткові відомості з програмування, які неможливо навести в цій статті, а саме: знання, як створювати динамічні бібліотеки класів DLL та як реалізовувати попередньо визначені програмні інтерфейси.


Об'єкти та інтерфейси LIRA-FEM API для розширень

На наступній діаграмі жовтим кольором зображені об'єкти LIRA-FEM API, призначені для роботи з розширеннями. Білим кольором на діаграмі зображені інтерфейси, що реалізуються об'єктами на стороні розширення. 

LIRA-FEM                                                Розширення LIRA-FEM
Об'єкт застосунку
LiraApplication
  ¦
  ¦  Стрічка інструментів
  ¦--LiraRibbon
  ¦
  ¦  Розширення
  ¦--LiraExtensions
  ¦    ¦                                                Об'єкт розширення
  ¦    '--------------------------------------------<<--ILiraExtension
  ¦
  ¦  Документ, або розрахункова схема
  ¦--LiraDocument
  ¦    ¦
  ¦    ¦  Усі групи та таблиці введення
  ¦    '--LiraTables
  ¦       ILiraExtensionTables
  ¦         ¦
  ¦         ¦  Група таблиць введення документа
  ¦         ¦--LiraTableGroup
  ¦         ¦  ILiraExtensionTableGroup
  ¦         ¦    ¦    ¦                                  Об'єкт для керування
  ¦         ¦    ¦    ¦                                  групою таблиць введення розширення
  ¦         ¦    ¦    '------------------------------<<--ILiraExtensionTableGroupHelper
  ¦         ¦    ¦
  ¦         ¦    ¦  Таблиця введення документа
  ¦         ¦----'--LiraTable
  ¦         ¦    ¦
  ¦         ¦    ¦  Таблиця введення розширення
  ¦         ¦----'--LiraExtensionTable
  ¦         ¦          ¦                                  Об'єкт для керування
  ¦         ¦          ¦                                  таблицею введення розширення
  ¦         ¦          '------------------------------<<--ILiraExtensionTableHelper
  ¦         ¦
  ¦         ¦  Налаштування одиниць виміру
  '------------LiraMeasurementUnits
            '--ILiraExtensionMeasurementUnits

Об'єкти та програмні інтерфейси для роботи з розширеннями повторюють, хоча і з більшою свободою, ті самі варіанти використання, що й параметри розділів реєстру Windows, які були описані вище, а саме:

  • Поповнення стрічки інструментів застосунку функціями розширення;
  • Вбудовування функцій розширення до конвеєра розрахунку;

За допомогою програмних інтерфейсів стають доступними і додаткові варіанти використання розширень:

  • Збереження вихідних даних розширень разом з даними LIR-файлів;
  • Оновлення знімків екрана, що відображають мозаїки, побудовані розширенням;
  • Вбудовування таблиць результатів розрахунку розширень до системи документування;

Щоправда, є єдиний варіант використання, який неможливо реалізувати за допомогою методів програмних інтерфейсів і який реалізується лише за допомогою налаштування параметрів розділів реєстру Windows. Це — первинне завантаження розширення до адресного простору застосунку LIRA-FEM. Щоб розширення завантажилося, необхідно «прописати» його завантаження, як було описано вище у підрозділі «Реєстрація функцій розширення для запуску з LIRA-FEM», хоча б завантаження розширення на старті роботи застосунку CallAfter = AppStartup. Коли у розширення викликана функція, тобто коли воно отримало керування, розширення може налаштовувати стрічку інструментів, реєструвати інші свої функції та багато іншого, але «змусити» застосунок передати керування розширенню можна лише через реєстр.

З боку LIRA-FEM API для роботи розширень призначені об'єкти LiraRibbon, LiraExtensions, LiraTables, LiraTableGroup, LiraExtensionTable, LiraExtensionMeasurementUnits. Розглянемо методи цих об'єктів.

Об'єкт та його методи Опис, параметри
LiraRibbon Об'єкт для керування стрічкою інструментів
AddExtensionTab() Додає нову вкладку з іменем TabName. TabKey — це її скорочення з латинських букв або цифр. PathImagesSmall і PathImagesLarge — шляхи до файлів із зображеннями. Повертає номер доданої вкладки, починаючи з 0
AddExtensionTabImage() Додає нове зображення на вкладку з іменем TabName. ToLargeImages вказує, куди додати зображення: для малих або великих зображень вкладки. ImagePath — шлях до файлу зображення. Повертає номер доданого зображення від 0 або -1 у разі невдачі
GetExtensionTabCount() Повертає кількість вкладок, доданих на стрічку за допомогою методу AddExtensionTab()
GetExtensionTabData() Повертає дані i-ї вкладки: її ім'я, її ярлик, кількість зображень 16x16, 32x32
RemoveExtensionTab() Видаляє вкладку з іменем TabName
AddPanel() На вкладці з іменем TabName додається нова панель з іменем PanelName. PanelKey — це її скорочення з латинських букв або цифр. ImageSmall — індекс зображення вкладки. Повертає номер доданої панелі, починаючи з 0
GetPanelCount() Повертає кількість панелей на вкладці з іменем TabName
GetPanelData() Повертає дані i-ї панелі на вкладці з іменем TabName: її ім'я, її комбінацію клавіш, прапорці
RemovePanel() Видаляє панель з іменем PanelName на вкладці з іменем TabName
AddButton() На вкладці TabName та панелі PanelName додається нова кнопка ButtonName. При натисканні кнопки викликається функція з ExtensionID. Якщо ParentButton не дорівнює -1, нова кнопка є частиною її спливаючого меню. Повертає номер нової кнопки або -1 у разі збою
AddButtonSeparator() На вкладці TabName та панелі PanelName додає новий роздільник. Повертає його номер або -1 у разі збою
GetButtonCount() Повертає кількість кнопок або роздільників на вкладці з іменем TabName та панелі з іменем PanelName. Якщо ParentButton не дорівнює -1, повертає дані її спливаючого меню
GetButtonData() Повертає дані i-ї кнопки або роздільника на вкладці з іменем TabName та панелі з іменем PanelName: її ім'я, ID розширення, функція, батьківська кнопка, підказка, опис, комбінація клавіш, зображення та прапорці
SetButtonData() Встановлює дані i-ї кнопки на вкладці TabName та панелі PanelName: її ім'я, ідентифікатор розширення, функція, батьківська кнопка, підказка, опис, комбінація клавіш, зображення та прапорці. pImageSmall і pImageLarge — кількість зображень вкладок
RemoveButton() Видаляє i-ту кнопку на вкладці TabName та панелі PanelName
Update() Оновлює стрічку

Як видно з наведеної вище таблиці, всі методи об'єкта LiraRibbon створюють, змінюють або видаляють елементи стрічки інструментів: вкладки Tab, панелі Panel, кнопки Button або роздільники між кнопками ButtonSeparator. Тут слід зазначити, що розширення не можуть змінювати вкладки, які не належать до розширень. Перевагою створення кнопок стрічки через об'єкт LiraRibbon порівняно зі створенням тих самих кнопок з реєстру є, по-перше, динамічність — тобто розширення може змінювати кнопки під час виконання, і по-друге, мовна залежність, оскільки текст елементів стрічки може бути налаштований залежно від поточної мови інтерфейсу.  Ще функція AddButton може створювати кнопки у випадних списках.

Наступний об'єкт призначений виключно для реєстрації розширень та їхніх методів. За допомогою його методів, наприклад, одне розширення LIRA-FEM може завантажити інше розширення та зареєструвати команди розширення.

Об'єкт та його методи Опис, параметри
LiraExtensions Об'єкт для керування розширеннями та їхніми функціями
AddExtension() Додає розширення. ExtensionID повинен складатися з 3 латинських букв. Ім'я видно користувачу. Якщо Register не дорівнює 0, реєструє розширення в системному реєстрі. Повертає номер доданого розширення, починаючи з 0
GetExtensionCount() Повертає кількість доданих розширень
GetExtensionData() Повертає дані i-го розширення. i — це індекс розширення у списку розширень, що починається з нуля
RemoveExtension() Видаляє розширення з ExtensionID. Якщо UnRegister не дорівнює 0, скасовує реєстрацію розширення та всіх його функцій у системному реєстрі
AddExtensionFunction() Додає функцію для виклику з файлу за шляхом з розширенням ExtensionID. Якщо функція є методом, вона виглядатиме як 'MyNamespace.MyClass.MyMethod'. Ім'я та опис видно користувачу
GetExtensionFunctionCount() Повертає кількість доданих функцій розширення
GetExtensionFunctionData() Повертає дані по функції номер i. Див. AddExtensionFunction() для опису параметрів, що повертаються
RemoveExtensionFunction() Видаляє функцію розширення з ExtensionID. Також можна скасувати її реєстрацію в реєстрі Windows, якщо параметр UnRegister не дорівнює 0

Наступними об'єктами, призначеними для роботи з розширеннями, є об'єкти LiraTables, LiraTableGroup та LiraExtensionTable. Зверніть увагу, що на діаграмі об'єктів LIRA-FEM вище об'єкти LiraTables і LiraTableGroup, крім свого інтерфейсу за замовчуванням, підтримують спеціалізований інтерфейс для роботи з розширеннями. Це інтерфейс ILiraExtensionTables та ILiraExtensionTableGroup відповідно. Інтерфейси таблиць введення ILiraExtensionTables і ILiraExtensionTableGroup разом з об'єктом LiraExtensionTable дозволяють розширенням створювати власні групи таблиць введення та таблиці введення — і таким чином інтегрувати свої дані до даних документа з розрахунковою схемою LIRA-FEM. Оскільки більшість методів інтерфейсів ILiraExtensionTables, ILiraExtensionTableGroup, LiraExtensionTable повторюють методи об'єктів LiraTables, LiraTableGroup, LiraTable — розглянемо лише ті властивості та методи, що призначені для роботи безпосередньо з розширеннями.

Об'єкт та його методи Опис, параметри
ILiraExtensionTables, ILiraExtensionTableGroup Усі таблиці введення, зокрема таблиці, керовані розширеннями
Група таблиць введення, зокрема група, керована розширенням
AddTable() Додає нову таблицю, реалізовану за допомогою допоміжного об'єкта розширення LIRA-FEM, що підтримує інтерфейс ILiraExtensionTableHelper (він описаний у підрозділі нижче). Параметр ExtensionID повинен містити ідентифікатор розширення LIRA-FEM (3 латинські букви). Повертає нову таблицю.
AddTableGroup() Додає нову групу таблиць, реалізовану за допомогою допоміжного об'єкта розширення LIRA-FEM, що підтримує інтерфейс ILiraExtensionTableGroupHelper (він описаний у підрозділі нижче). Параметр ExtensionID повинен містити ідентифікатор розширення LIRA-FEM (3 латинські букви). Повертає нову групу таблиць.
FindTable() Повертає таблицю, раніше додану методом AddTable і керовану допоміжним об'єктом розширення з ID=HelperID. Параметр ExtensionID повинен містити ідентифікатор розширення LIRA-FEM (3 латинські букви). Повертає null, якщо таблицю не було додано.
FindTableGroup() Повертає групу таблиць, раніше додану методом AddTableGroup і керовану допоміжним об'єктом розширення з ID=HelperID. Параметр ExtensionID повинен містити ідентифікатор розширення LIRA-FEM (3 латинські букви). Повертає null, якщо групу таблиць не було додано.
GetGroupHelper() Повертає допоміжний об'єкт розширення, який фактично реалізує цю таблицю.
ILiraExtensionTable Таблиця введення, керована розширенням.
GetTableHelper() Повертає допоміжний об'єкт, який фактично реалізує цю таблицю.

Реалізація програмних інтерфейсів у розширенні LIRA-FEM

Розширення не зобов'язане реалізовувати всі інтерфейси, зображені з прозорим фоном на діаграмі в попередньому підрозділі. У наведеній нижче таблиці показано, у яких випадках слід реалізовувати ті або інші інтерфейси на стороні розширення.

Інтерфейс Слід реалізовувати, коли потрібно
ILiraExtension Керувати власними кнопками стрічки інструментів, зокрема доступністю команд, що належать розширенню
Отримувати сповіщення про зміну поточного завантаження, варіанта конструювання тощо
Отримувати сповіщення про виклик команд меню / стрічки інструментів
Оновлювати знімки екрана для документування за допомогою «Книги звітів»
Створювати екземпляри об'єктів, що реалізують інтерфейси ILiraExtensionTableGroupHelper та ILiraExtensionTableHelper
ILiraExtensionTableGroupHelper Налаштовувати параметри групи таблиць введення, що належать розширенню
ILiraExtensionTableHelper Редагувати дані розширення як таблицю введення
Зберігати дані розширення разом з даними документа у складі LIR-файлу
Створювати таблиці результатів для документування за допомогою «Книги звітів»

Далі ми розглянемо методи інтерфейсів, згаданих у вищенаведеній таблиці, акцентуючи увагу на найважливіших з них.


Створення екземпляра об'єкта розширення та його підключення до LIRA-FEM

Отже, ви дійшли висновку, що вашому розширенню потрібна тісніша інтеграція з користувацьким інтерфейсом застосунку. У такому разі ваші дії мають бути такими:

  1. Написати функцію, яка створює екземпляр об'єкта розширення, що підтримує інтерфейс ILiraExtension.
  2. Внести до реєстру Windows необхідні розділи та параметри, завдяки яким ця функція буде викликана у LIRA-FEM.

Як і коли створюється екземпляр об'єкта, що реалізує цей програмний інтерфейс?

Як уже було зазначено, для того щоб розширення могло бути завантажено до адресного простору застосунку LIRA-FEM, необхідно зареєструвати його в реєстрі. Рекомендується робити це за допомогою параметра реєстру Windows "CallAfter"="AppStartup", як було показано в підрозділі «Реєстрація функцій розширення для запуску з LIRA-FEM». Після того як ми внесли до реєстру Windows необхідні розділи та їхні параметри, під час завантаження застосунку LIRA-FEM буде викликана функція, вказана в розділі реєстру. Саме ця функція й повинна створити екземпляр об'єкта розширення та додати його до відповідного контейнера об'єктів LIRA-FEM під назвою LiraExtensions.

Наприклад, розширення Дерево могло б завантажитися до адресного простору LIRA-FEM таким чином. Під час встановлення воно реєструє в реєстрі Windows динамічну бібліотеку Wood.dll та її метод Startup:

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\LIRA EXTENSIONS\Wud]
@="Dll:Net4"
[HKEY_LOCAL_MACHINE\SOFTWARE\LIRA EXTENSIONS\Wud\Wood.WoodExtension.Startup]
@="c:\\Users\\Public\\Documents\\WoodExtension\\Wood.dll"
CallAfter="AppStartup"

І реалізує метод Startup у динамічній бібліотеці на платформі .NET Framework 4 мовою C#:

using LiraFEM;
using System.Collections.Generic;
using System.Runtime.InteropServices;
namespace Wood
{
  public class WoodExtension : ILiraExtension
  {
    // Конструктор має бути публічним і не містити параметрів
    public WoodExtension() { }
    // Повне ім'я цього методу, з урахуванням простору імен та імені класу, зареєстровано в реєстрі
    public void Startup()
    {
      // Наше головне завдання — підключити об’єкт розширення. Робимо це
      string strThisDllPath = System.Reflection.Assembly.GetExecutingAssembly().Location; // Шлях до файлу розширення DLL
      LiraApplication LiraApp = new LiraApplication();        // Отримуємо посилання на застосунок
      LiraExtensions LiraExts = LiraApp.Extensions;           // Отримуємо посилання на контейнер розширень
      LiraExts.AddExtension(                                  // Додаємо розширення до контейнера
        "Wud",                                                // ID розширення з 3-х латинських літер
        LiraExtensionLangEnum.kLiraExtensionLang_Dll_Net4,    // Технологія, на якій написано розширення
        "Timber structures design and analysis",              // Назва розширення (можна не вказувати) 
        LiraCompatibleVersionEnum.kLiraCompatibleVersion_Any, // Мінімальна версія програми, сумісна з розширенням 
        LiraCompatibleVersionEnum.kLiraCompatibleVersion_Any, // Максимальна версія програми, сумісна з розширенням 
        this);                                                // Посилання на розширення

Так розширення має завантажувати себе до контейнера розширень. Створення кнопок на стрічці, команди яких обробляються розширенням, можна виконати за допомогою реєстру Windows. Однак додавання кнопок можна виконати і програмно, як показано в прикладі нижче. У цьому прикладі ми додамо функцію, яка емулює розрахунок, і кнопку на стрічку інструментів, яка викликає цю функцію розрахунку. 

 // Продолжение метода Startup() 
      double fFunctionsOrder = 0;                             // Формальний параметр 
      LiraExts.AddExtensionFunction(                          // Посилання на розширення 
        "Wud",                                                // ID розширення з 3-х латинських літер
        "Wood.WoodExtension.DoAnalysis",                      // Повне ім'я методу з урахуванням простору імен та імені класу 
        strThisDllPath,                                       // Повний шлях до Wood.dll 
        LiraCallAfterEnum.kLiraCallAfter_Button,              // Метод викликається натисканням кнопки на стрічці 
        ref fFunctionsOrder,                                  // Порядок виклику методу (для кнопок на стрічці це не має значення) 
        "Timber analysis",                                    // Назва методу (можна не вказувати) 
        "Performs timber analysis",                           // Опис функції (можна не вказувати) 
        "wud");                                               // Розширення файлів результатів 
// Далі програмно додамо на панель інструментів вкладку та панель для кнопки, яка буде викликати цю функцію. 
      LiraRibbon Ribbon = LiraApp.Ribbon;                     // Отримуємо посилання на стрічку  
      Ribbon.AddExtensionTab("Wood");                         // Додамо на стрічку нову вкладку з назвою Wood 
      Ribbon.AddPanel("Wood", "Analysis");                    // Додамо на нову вкладку нову панель для кнопок із назвою Analysis 
      int iImgSmall = Ribbon.AddExtensionTabImage(            // Додамо піктограму для кнопки
        "Wood",                                               // Для якої закладки додається піктограма
        false,                                                // Це піктограма для великої кнопки?
        strThisDllPath + ".ICO");                             // Шлях до піктограми. Вона знаходиться поруч із Wood.dll у файлі Wood.dll.ico
      int iImgLarge = Ribbon.AddExtensionTabImage("Wood",true,strThisDllPath + ".ICO"); // те саме, для великої кнопки
// Додаємо саму кнопку на стрічку
      LiraCmdIdEnum eCmd = Ribbon.AddButton(
        "Wood",                                               // Назва нової вкладки стрічки 
        "Analysis",                                           // Назва нової панелі стрічки 
        -1,                                                   // Номер «батьківської» кнопки. Для звичайних кнопок — 1
        "Wud",                                                // ID розширення з 3-х латинських літер 
        "Wood.WoodExtension.DoAnalysis",                      // Повне ім'я методу з урахуванням простору імен та імені класу 
        "Timber analysis",                                    // Напис на кнопці 
        "Performs Timber Analysis",                           // Підказка для кнопки 
        "More description comes here",                        // Опис кнопки 
        "",                                                   // Клавіші швидкого доступу 
        iImgSmall,                                            // Номер зображення для маленької кнопки 
        iImgLarge);                                           // Номер зображення для великої кнопки 
      m_CmdId2Func[eCmd] = "Wood.WoodExtension.DoAnalysis";
  }
  Dictionary<LiraCmdIdEnum, string> m_CmdId2Func = new Dictionary<LiraCmdIdEnum, string>();
  public void DoAnalysis()
  {
    System.Windows.Forms.MessageBox.Show("Timber analysis performed!");
  }

Для повноти додамо до класу WoodExtension ще й методи, що реалізують інтерфейс ILiraExtension, щоправда без їхньої реалізації. Ці методи будуть описані в наступному підрозділі.

    string ILiraExtension.GetExtensionId() {return "Wud";}
    string ILiraExtension.GetExtensionName() {return "Timber design and analysis";}
    ILiraExtensionTableGroupItemHelper ILiraExtension.CreateTableHelper(ILiraExtensionTables Tables, int ExtensionHelperID) { return null;}
    void ILiraExtension.SetApplication(LiraApplication App){}
    void ILiraExtension.StateChanged(LiraDocument Doc, LiraCmdIdEnum Cmd, LiraViewCtlEnum Ctl){}
    int ILiraExtension.GetExtensionCmdState(LiraCmdIdEnum Cmd, out bool pEnabled){pEnabled = true;return 0;}
    bool ILiraExtension.CanExtensionDoAnalysis(){return false;}
    bool ILiraExtension.UpdateScreenshotScreen(string Src, string Dat, LiraTable DstTable){return false;}
    void ILiraExtension.DocumentClosing(LiraDocument Doc){}
    void ILiraExtension.HelpContext(string TabName, string PanelName, string Function, int HtmlHelpCommand, long hParentWnd){}
    void ILiraExtension.ApplicationClosing(){}
  }
}

Основний програмний інтерфейс розширення ILiraExtension

Методи інтерфейсу ILiraExtension описані в таблиці нижче.

Інтерфейс та його методи Опис
ILiraExtension Основний інтерфейс розширення для роботи в середовищі LIRA-FEM
CreateTableHelper() За запитом LIRA-FEM API створює та повертає об'єкт, що керує таблицею введення розширення ILiraExtensionTable або групою таблиць введення розширення ILiraExtensionTableGroup
GetExtensionId() Повертає трибуквений ідентифікатор розширення
GetExtensionName() Повертає ім'я розширення
SetApplication() Передає розширенню посилання на об'єкт LiraApplication
StateChanged() Передає розширенню інформацію про натискання будь-якої кнопки на стрічці або будь-якого вибраного пункту меню, а також про зміну поточного номера завантаження, варіанта конструювання тощо
GetExtensionCmdState() За запитом LIRA-FEM API повертає застосунку інформацію про доступність кнопки на стрічці, що належить розширенню
CanExtensionDoAnalysis() За запитом LIRA-FEM API повертає застосунку інформацію про те, чи може розширення виконати розрахунок. Це потрібно, наприклад, при наскрізному розрахунку або при налаштуванні параметрів розрахунку
UpdateScreenshotScreen() Викликається при оновленні копії екрана, створеної із зображенням даних розширення.
DocumentClosing() Викликається при закритті документа LIRA-FEM. Реалізація цього методу має звільнити всі посилання на об'єкти документа, які можуть утримуватися об'єктом розширення
HelpContext() Викликається, коли користувач відкриває довідку за командою розширення. Реалізація цього методу має відкрити відповідний розділ довідки розширення.
ApplicationClosing() Викликається при закритті застосунку LIRA-FEM. Реалізація цього методу має звільнити всі посилання на об'єкти застосунку, які можуть утримуватися об'єктом розширення

Більшість із 11 наведених у таблиці методів інтерфейсу ILiraExtension мають тривіальну реалізацію, тобто в більшості випадків ці методи можуть нічого не робити. Це стосується, наприклад, методів-сповіщень SetApplication(), StateChanged(), DocumentClosing(), ApplicationClosing(). Якщо розширення не відстежує натискання кнопок стрічки, не створених самим розширенням, якщо розширенню не важлива зміна поточного завантаження або варіанта конструювання, ці методи справді можна залишити порожніми. Ще 3 методи GetExtensionId(), GetExtensionName(), HelpContext() також мають вкрай просту реалізацію. Методи GetExtensionId() і GetExtensionName() — мають просто повернути два наперед визначені рядки, а метод HelpContext() — просто викликати розділ довідки, що відповідає імені переданої команди. Дещо складнішою буде реалізація методу CanExtensionDoAnalysis(). Цей метод має перевірити, чи достатньо у розширення даних для виконання розрахунку. Наприклад, розширення «Дерево» для реалізації цього методу переконується, що задані його таблиці введення вхідних даних.

Реалізація цього методу в «Дереві» могла б виглядати так: 

bool ILiraExtension.CanExtensionDoAnalysis()             // Чи можна виконувати розрахунок розширенню 
{                                                        // з ідентифікатором "Wud"?
  LiraApplication App      = new LiraApplication();      // Отримуємо посилання на застосунок LIRA-FEM
  LiraDocument Doc         = App.ActiveDocument;         // Откримуємо посилання на активний документ
  LiraTables  Ts           = Doc.AllTables;              // Отримуємо посилання на таблиці введення
  ILiraExtensionTables ETs = Ts as ILiraExtensionTables; // Приводимо його до інтерфейсу для роботи з розширеннями
  ILiraExtensionTable ET0  = ETs.FindTable(1, "Wud");    // Шукаємо таблицю з ідентифікатором 1 розширення "Wud"
  ILiraExtensionTable ET1  = ETs.FindTable(2, "Wud");    // Шукаємо таблицю з ідентифікатором 2 розширення "Wud"
  return ET0 != null && ET1 != null;                     // Якщо обидві таблиці знайдені значить можна виконувати розрахунок
}

У перших трьох рядках цієї функції розширення отримує посилання на контейнер усіх таблиць введення. Цей контейнер містить також і таблиці, що містять вхідні дані таблиць введення розширень (тому, як зберігаються вхідні дані розширень у складі LIR-файлу, присвячено окремий підрозділ нижче). Далі посилання на контейнер усіх таблиць введення приводиться до посилання на інтерфейс ILiraExtensionTables. Ми цілком могли б обійтися методами об'єкта LiraTables за замовчуванням, але його інтерфейс ILiraExtensionTables містить зручний метод FindTable(), яким ми і скористаємося в цьому випадку. Ми приводимо посилання на контейнер усіх таблиць введення до інтерфейсу ILiraExtensionTables і далі викликаємо його метод FindTable(), щоб знайти таблиці введення, що належать розширенню з ідентифікатором «Wud». Якщо знайдено таблиці введення з ідентифікаторами 1 і 2 цього розширення, то функція вважає, що даних для розрахунку достатньо.

Подібним чином має бути реалізований і метод розширення GetExtensionCmdState(), який відповідає застосунку на запит про те, чи доступна кнопка на стрічці, що належить розширенню. Припустимо, що на стрічці є кнопка, яка має показувати мозаїку вхідних даних розширення, розфарбовуючи в різні кольори елементи розрахункової схеми. Тоді реалізація методу GetExtensionCmdState() має перевірити, чи задані вже ці вхідні дані, і якщо ні — зробити кнопку недоступною для натискання. У розширення «Дерево» така реалізація могла б виглядати так: 

int ILiraExtension.GetExtensionCmdState(LiraCmdIdEnum eCmd, out bool pEnabled)
{
  pEnabled = false;
  string strFunctionName;
  if(m_CmdId2Func.TryGetValue(eCmd, out strFunctionName))
  {
    if(strFunctionName == "WudTblElsMosaic")
    {
      LiraApplication App = new LiraApplication();           // Отримуємо посилання на застосунок LIRA-FEM
      LiraDocument Doc = App.ActiveDocument;                 // Отримуємо посилання на активний документ
      ILiraTables Ts = Doc.AllTables;                        // Отримуємо посилання на таблиці введення
      ILiraExtensionTables ETs = Ts as ILiraExtensionTables; // Приводимо його до інтерфейсу для роботи з розширеннями
      ILiraExtensionTable ET0 = ETs.FindTable(0, "Wud");     // Шукаємо таблицю з ідентифікатором 0 розширення "Wud"
      pEnabled = (ET0 != null);                              // Якщо обидві таблиці знайдені значить можна виконувати розрахунок
    }
    else //if (strFunctionName == "...")
    {
         // інші перевірки
    }
  }
  return 0;
}

Наведений вище код методу GetExtensionCmdState() багато в чому подібний до реалізації методу CanExtensionDoAnalysis() з тією різницею, що спочатку за ідентифікатором команди eCmd отримується ім'я функції, пов'язаної з цією командою, а потім для цього імені виконується пошук відповідної таблиці введення. Поки залишимо осторонь значення, яке ця функція повертає, і повернемося до нього в підрозділі «Створення оновлюваних знімків екрана». Також залишимо поки осторонь реалізацію методів UpdateScreenshotScreen() і CreateTableHelper() — до них ми повернемося в наступних підрозділах. Через те що два методи інтерфейсу ми залишили без пояснень, підсумок щодо інтерфейсу ILiraExtension буде лише частковим. З того часткового опису, який вже отримав інтерфейс ILiraExtension, можна зробити висновок, що цей інтерфейс призначений для отримання сповіщень про події, що відбуваються в застосунку LIRA-FEM, — такі як закриття документа, закриття застосунку, виклик команди меню або стрічки, оновлення копії екрана для Книги звітів. Також цей інтерфейс може відповідати на запит застосунку про доступність кнопок на стрічці, що належать розширенню.


Вбудовування даних розширення в LIR-файли за допомогою інтерфейсу ILiraExtensionTableHelper

Не описаний у попередньому підрозділі метод інтерфейсу ILiraExtension.CreateTableHelper() якраз і призначений для того, щоб створити на стороні розширення об'єкт, що реалізує інтерфейс ILiraExtensionTableHelper, який здатний зберігати дані розширення разом з іншими даними розрахункової схеми всередині файлу з розширенням .LIR. Чи завжди потрібно реалізовувати такий об'єкт? Звісно, ні. По-перше, розширення може не мати жодних власних даних і користуватися лише даними документа LIRA-FEM. Якщо даних немає, то й інтерфейс для їх збереження не потрібен. По-друге, розширення може зберігати свої дані в окремому файлі, доручивши користувачу самостійно копіювати їх разом із LIR-файлом, якщо потрібно перенести задачу з одного комп'ютера на інший. Але якщо ви не потрапили ні в 1, ні в 2 випадок, то швидше за все ви захочете реалізувати інтерфейс ILiraExtensionTableHelper, щоб зберігати дані розширення всередині LIR-файлу.

Особливістю даних, які зберігаються в LIR-файлі за допомогою інтерфейсу ILiraExtensionTableHelper, є їх прозорість. Усі дані розширення, які підключаються до документа LIRA-FEM з розрахунковою схемою за допомогою інтерфейсу ILiraExtensionTableHelper, є або таблицями введення, або їх параметрами, і тому будь-який користувач LIRA-FEM може вільно їх переглядати. Методи інтерфейсу ILiraExtensionTableHelper та його батьківського інтерфейсу ILiraExtensionTableGroupItemHelper наведені в таблиці нижче.

Інтерфейс та його методи Опис
ILiraExtensionTableGroupItemHelper, Призначений для показу та редагування параметрів групи таблиць введення, що належать розширенню.
ILiraExtensionTableHelper Призначений для показу та редагування таблиці введення, що належить розширенню, а також її параметрів.
Спільні для двох інтерфейсів методи:
GetName() Повертає ім'я таблиці введення або групи таблиць введення для відображення як елемента дерева у вікні «Таблиці введення».
GetExtensionHelperID() Повертає унікальний ідентифікатор таблиці введення або групи таблиць введення, що належать розширенню. Це має бути число від 0 до 255.
GetParameterCount() Повертає кількість параметрів. Переглянути параметри можна у вікні «Параметри» таблиць введення
GetParameter() Повертає дані i-го параметра. Переглянути параметри можна у вікні «Параметри» таблиць введення
SetParameter() Встановлює значення i-го параметра таблиці введення або групи таблиць введення. Переглянути параметри можна у вікні «Параметри» таблиць введення.
EditParameter() Пропонує розширенню відкрити спливаюче вікно для редагування i-го параметра. Повертає true, якщо розширення підтвердило редагування, або false в іншому випадку.
GetParameterAllowedValues() Повертає масив варіантів, кожен з яких є допустимим значенням i-го параметра.
ILiraExtensionTableHelper Методи нижче є лише в інтерфейсі ILiraExtensionTableHelper:
GetColumnCount() Повертає кількість стовпців у підконтрольній таблиці.
GetColumn() Повертає дані i-го стовпця, а саме: його ім'я, спливаючу підказку, ширину у відсотках від ширини таблиці, тип даних, одиниці вимірювання та кількість знаків після коми для чисел з рухомою комою та чисел подвійної точності. pData — це комбінація прапорів LiraTableColumnEnum.
EditCell() Пропонує розширенню відредагувати вміст комірки підконтрольної таблиці у спливаючому вікні. Col і Row — це номери стовпця та рядка, що починаються з нуля. Параметр pCell містить вміст комірки, параметр pRow — вміст рядка з коміркою у вигляді масиву рядків. Розширення може змінювати параметри pCell або pRow.
GetCellAllowedValues() Повертає варіанти вмісту комірки (Row, Col) підконтрольної таблиці у вигляді масиву текстових рядків або варіантів. pDivider — це символ, що розділяє незалежну від мови частину тексту комірки від залежної від мови частини.
IsDataFromOutside Ця властивість має значення true, якщо дані підконтрольної таблиці не зберігаються ні в самій таблиці, ні в документі LIRA-FEM. У цьому випадку для її поповнення викликається метод RefillFromOutsideData, а при застосуванні даних викликається метод ApplyToOutsideData.
IsResult Чи є підконтрольна таблиця введення таблицею результатів. У таблиці результатів не можна викликати метод Apply().
RefillFromOutsideData() Викликається лише в тому випадку, якщо властивість IsDataFromOutside має значення true. Скасовує всі зміни, внесені до таблиці, та заповнює її вміст даними із зовнішнього джерела даних, визначеного розширенням Lira.
CanApply() Викликається лише в тому випадку, якщо властивість IsDataFromOutside має значення false. Перевіряє наявність помилок у підконтрольній таблиці. Повертає ненульове значення, якщо помилок не виявлено, або 0 в іншому випадку. pErrs отримує інформацію про помилки, якщо такі є. Формат помилок такий самий, як у методі LiraTable.Apply.
ApplyToOutsideData() Викликається лише в тому випадку, якщо властивість IsDataFromOutside має значення true. Перевіряє помилки та застосовує вміст таблиці. Скидає прапор IsModified таблиці. Повертає ненульове значення у разі успіху або 0 в іншому випадку. Формат pErrs такий самий, як у методі LiraTable.Apply.
FindInModel() Повертає pElementNumbers або pSelectedNodes (обидва значення починаються з 1), що відповідають рядкам (з нульовою індексацією) таблиці. Кожен параметр, крім Table, є масивом варіантів, кожен варіант містить значення типу long.
FindInTable() Повертає pRowNumbers (починаючи з 0) елементів таблиці, що відповідають ElementNumbers або NodeNumbers (обидва параметри починаються з 1). Кожен параметр, крім Table, є масивом варіантів, кожен варіант містить значення типу long.
CopyToAdaptCellValue() Викликається методом CopyTo, якщо 1 скінченний елемент (СЕ) у цільовому документі (ЦД) відповідає 2 або більше СЕ у вихідному документі (ВД). Параметр SrcCells є масивом варіантів, по одному для кожного СЕ у ВД. Необхідно повернути значення СЕ в ЦД. Усі значення знаходяться в стовпці Col.
DocumentClosing() Викликається перед закриттям документа, що містить підконтрольну таблицю.

Методи інтерфейсів ILiraExtensionTableGroupItemHelper та ILiraExtensionTableHelper дозволяють повністю контролювати відповідну групу таблиць введення або таблицю введення. Щоб створити власну групу таблиць введення або таблицю введення, розширення має скористатися відповідним методом інтерфейсу ILiraExtensionTableGroup. Наприклад, у відповідь на натиснуту на стрічці кнопку «Створити таблицю вхідних даних» розширення може виконати такий блок коду:

LiraApplication LiraApp = new LiraApplication();   // Отримуємо посилання на застосунок LIRA-FEM 
LiraDocument LiraDoc    = LiraApp.ActiveDocument;  // Отримуємо посилання на активний документ
LiraTables Tables       = LiraDoc.AllTables;       // Отримуємо посилання на контейнер усіх таблиць 
ILiraExtensionTableGroup ExtTables = Tables as ILiraExtensionTableGroup; // Перетворюємо посилання
 
// Створюємо об’єкт, що керує групою таблиць введення з нашого розширення Wood
ILiraExtensionTableGroupItemHelper GrpHelper = new WoodLiraExtensionTableGroupHelper(); 
 
// Створюємо групу таблиць введення, підконтрольну об’єкту GrpHelper
ILiraExtensionTableGroup WoodTableGroup = ExtTables.AddTableGroup(GrpHelper, "Wud");
 
// Створюємо об’єкт, який керує таблицею введення вихідних даних нашого розширення Wood
ILiraExtensionTableHelper TblHelper = new WoodLiraExtensionTableHelper(); 
 
// Створюємо таблицю введення, підконтрольну об’єкту TblHelper, у підконтрольній групі
ILiraExtensionTable WoodTable = WoodTableGroup.AddTable(TblHelper, "Wud");

Після того як було створено групу таблиць введення або таблицю введення, вона стає видимою у вікні «Таблиці введення» і починає зберігатися разом із розрахунковою схемою в LIR-файлі. Під час налаштування параметрів групи таблиць введення або таблиці введення, підконтрольної розширенню, викликаються методи інтерфейсу ILiraExtensionTableGroupItemHelper, а під час редагування таблиці введення, підконтрольної розширенню, викликаються методи інтерфейсу ILiraExtensionTableHelper. Таким чином, з точки зору користувача редагування даних розширення нічим не відрізняється від редагування даних розрахункової схеми за допомогою таблиць введення.

Дані розширення, збережені всередині LIR-файлу разом із підконтрольною розширенню таблицею введення або групою таблиць введення, при завантаженні необхідно знову пов'язати з розширенням. Для цього в інтерфейсі ILiraExtension і передбачений метод CreateTableHelper(). Метод ILiraExtension.CreateTableHelper() має повернути посилання на об'єкт-хелпер для таблиці або групи таблиць, підконтрольної розширенню за її ідентифікатором.

ILiraExtensionTableGroupItemHelper ILiraExtension.CreateTableHelper(ILiraExtensionTables ExtTables, long ExtensionHelperID)

Повернуте посилання пов'язується з таблицею або з групою таблиць введення і таким чином робить цю таблицю або групу таблиць знову підконтрольною розширенню після завантаження LIR-файлу.


Вимоги до найменування файлів результатів

Звісно, розширення може створювати файли з будь-якими іменами. Однак якщо ім'я файлу результатів буде цілком довільним, користувачу доведеться пам'ятати, який файл слід брати з собою, коли йому потрібно передати задачу з результатами на інший комп'ютер. З іншого боку, в LIRA-FEM є вбудована можливість створити ZIP-архів із вхідними даними задачі та результатами. Цей підрозділ містить дуже прості вимоги до того, в якій папці та під яким ім'ям слід зберігати файл із результатами розрахунку розширення, щоб вони потрапили до ZIP-архіву з іншими результатами розрахунку розрахункової схеми.

  • Створюйте двійкові файли результатів у папці Work, а текстові — у папці Result. Шлях до цих папок можна отримати за допомогою методу LiraApplication.GetFilePath(). Першим параметром цього методу є ідентифікатор папки; нас цікавлять папки з ідентифікаторами kLiraDirectory_Work і kLiraDirectory_Result.
  • Як ім'я файлу результатів використовуйте ім'я документа. Ім'я документа повертає властивість LiraDocument.Title.
  • Як розширення файлу результатів використовуйте трибуквений ідентифікатор розширення. Як вже було сказано, ідентифікатор розширення складається з трьох символів; допустимі значення символів — літери латинського алфавіту або цифри.

Розширення файлів може мати більше трьох символів, однак вікна на зразок «Відкрити файл» не розрізняють розширення файлів, у яких перші три символи однакові, тому обмеження довжини розширення файлу трьома символами буде розумним рішенням. Ідентифікатор розширення, яке породило такий файл у межах LIRA-FEM, є унікальним, тому використовувати його для розрізнення файлів результатів також виглядає розумно.


Документування таблиць результатів і таблиць вхідних даних

Якщо результатом розрахунку розширення є прямокутна таблиця, її можна включити до системи документування LIRA-FEM під назвою Книга звітів. Книга звітів дозволяє накопичувати знімки екрана, таблиці та текстові документи, оновлювати їх після перерахунків і верстати з них єдиний звіт у форматі .DOCX. Щоб ваша таблиця результатів могла бути включена до Книги звітів, необхідно спочатку зробити з неї таблицю введення, підконтрольну розширенню. Іншими словами, необхідно передбачити для таблиці результатів окремий об'єкт, який реалізує інтерфейс ILiraExtensionTableHelper, і після розрахунку додати цю таблицю до решти таблиць введення. 

LiraApplication LiraApp = new LiraApplication();   
LiraDocument LiraDoc    = LiraApp.ActiveDocument;  
LiraTables Tables       = LiraDoc.AllTables;       
ILiraExtensionTableGroup ExtTables = Tables as ILiraExtensionTableGroup; 
 
// Знаходимо раніше створену групу таблиць введення, яка підпорядковується нашому розширенню (нехай її ID = 0)
ILiraExtensionTableGroup WoodTableGroup = ExtTables.FindTableGroup(0, "Wud");
 
// Створюємо об’єкт, що керує таблицею введення результатів 
ILiraExtensionTableHelper ResultTblHelper = new WoodLiraExtensionResultTableHelper(); 
 
// Створюємо таблицю введення, підконтрольну об’єкту ResultTblHelper, у підконтрольній групі
ILiraExtensionTable WoodResultTable = WoodTableGroup.AddTable(ResultTblHelper, "Wud");

Таблиця введення результатів по суті не є таблицею введення, оскільки змінювати результати не можна. Кнопка «Застосувати» в такій таблиці нічого не робитиме. Властивість ILiraExtensionTableHelper.IsDataFromOutside має повертати значення true. Все, що можна зробити з такою таблицею, — це заново заповнити її за допомогою методу ILiraExtensionTableHelper.RefillFromOutsideData(), щоб оновити її дані. Будь-яку таблицю введення, у тому числі й таку, що містить результати, можна додати до Книги звітів. Програмно це можна зробити за допомогою методу LiraTable.AddToReportBook(). Таким чином, і таблиці введення вхідних даних, і таблиці введення результатів, підконтрольні розширенню, можна легко включити до Книги звітів і сверстати в єдиний із рештою результатів DOCX-файл.


Створення для Книги звітів оновлюваних знімків екрана

У підрозділі «Візуалізація даних розширення за допомогою мозаїк» ми показали, як можна програмно побудувати довільну мозаїку, розфарбувавши елементи розрахункової схеми в різні кольори. Побудовану таким чином мозаїку, ізополе або епюри можна додати до Книги звітів, щоб включити їх до загального звіту за задачею. Ні для побудови мозаїк, ні для включення їх до Книги звітів не потрібно було розробляти жодних об'єктів, що реалізують наперед визначені інтерфейси. Але все ж у мозаїк, доданих до Книги звітів, є проблема — вони не оновлювані, і якщо при черговому перерахунку задачі результати розрахунку вашого розширення змінилися, то відповідні мозаїки в Книзі звітів доведеться переробляти вручну.

Однак якщо ви реалізовуєте інтерфейс ILiraExtension у своєму об'єкті, ви можете реалізувати і його метод ILiraExtension.UpdateScreenshotScreen(). Цей метод якраз і призначений для перегенерації знімків екрана, вже доданих до Книги звітів. Щоправда, для цього треба знати один секрет: треба підписати свою мозаїку, щоб потім «впізнати» свій підпис і оновити мозаїку відповідно до нових даних.

Отже, підписуємо свою мозаїку. Для різноманітності зробимо це не мовою VBScript, як це було зроблено в розділі «Візуалізація даних розширення за допомогою мозаїк», а мовою C#.

void CreateMosaic(string strTableContentPostfix)
{
  // Підключаємося до об’єкта LiraApplication і отримуємо активний документ із розрахунковою схемою
  LiraApplication LiraApp = new LiraApplication();
  LiraDocument LiraDoc = LiraApp.ActiveDocument;
 
  // Створюємо таблицю мозаїки
  object Params1 = new object[] { "Element text mosaic", "11" + strTableContentPostfix, 1 };
  LiraTable Mosaic1 = LiraDoc.AllTables.CreateNewItem(LiraTableEnum.kLiraTable_UserMosaicData, Params1) as LiraTable;
 
  // Дані для мозаїки (масив 2D)
  object Data1 = new object[2,5]{{ "", 1, "", "1.1 Червоний колір", "#ff4444" },
                                 { "", 2, "", "2.2 Зелений колір", "#008800" }};
  // Заповнюємо таблицю
  Mosaic1.SetContents(Data1);
 
  // Впроваджуємо зміни
  string strErrs = "";
  Mosaic1.Apply(out strErrs);
 
  // Прибираємо за собою — видаляємо щойно створену таблицю
  // LiraDoc.AllTables.Delete(LiraDoc.AllTables.ItemCount - 1);
}

Якщо порівняти цю функцію на C# з її попередницею, написаною на VBScript, можна помітити, що у нової функції з'явився параметр strTableContentPostfix, який додається як постфікс до другого за рахунком параметра в масиві, що передається у функцію AllTables.CreateNewItem().

Якщо придивитися ще уважніше, то цей самий параметр у масиві змінив тип з int на string, що нормально, інакше ми б не змогли додати до нього суфікс. І, нарешті, останній рядок функції, що видаляв щойно створену таблицю введення з вхідними даними мозаїки, закоментований. До речі, залишати таблицю з вхідними даними мозаїки серед таблиць введення, що належать розширенню, — не така вже й погана ідея. Це дозволяє користувачу згодом відкрити цю таблицю введення та налаштувати її зображення на розрахунковій схемі. Саме так і робить розширення «Дерево» — залишає таблицю введення з мозаїкою, щоб користувач міг її за бажанням налаштувати.

Викличемо цю функцію у вже зареєстрованій функції розрахунку, передавши в неї «правильний» постфікс strTableContentSuffix.

public void DoAnalysis()
{
  System.Windows.Forms.MessageBox.Show("Timber analysis performed!");
  CreateMosaic(". Src=Wud:MyMosaicSign");
}

Далі натиснемо кнопку «Timber Analysis», відкриємо вікно Таблиць введення з новоствореною таблицею та подивимося на її параметри. Вікна застосунку виглядатимуть приблизно як на наступному рисунку.

Рис.8

Рис.8

Як видно, до другого за рахунком параметра таблиці введення потрапив наш «правильний» постфікс "Src=Wud:MyMosaicSign".

В описі цього параметра сказано, що постфікс цього параметра якраз і має містити підпис розширення, що його створило. Причому формат постфікса має бути таким:

. Src=Ім'я:Параметри
тут
. Src= — це ідентифікатор, що показує, що за ним ідуть дані розширення,
Ім'я: — це трибуквений ідентифікатор розширення, за яким слідує символ двокрапки — роздільник між ідентифікатором розширення та параметрами мозаїки,
Параметри — це, власне, і є підпис, який має розпізнати функція ILiraExtension.UpdateScreenshotScreen().

Під час оновлення знімка екрана застосунок LIRA-FEM розпізнає знімок екрана, виконаний за таблицею введення, що містить дані користувацької мозаїки, шукає її «підпис» і викликає у розширення з відповідним ідентифікатором метод ILiraExtension.UpdateScreenshotScreen(), передавши в цей метод підпис, тобто дані після ідентифікатора «. Src=». У нашому випадку у функцію  ILiraExtension.UpdateScreenshotScreen() потрапить параметр «Wud:MyMosaicSign». У відповідь розширення має розпізнати свій підпис, і якщо він розпізнаний — знову побудувати таку саму мозаїку за своїми поточними даними у вікні розрахункової моделі, використавши при цьому, звісно, ту саму таблицю введення для побудови користувацької мозаїки. Давайте реалізуємо таку функцію, замінивши червоний колір мозаїки на синій, щоб переконатися, що оновлення справді відбулося.

bool ILiraExtension.UpdateScreenshotScreen(string strSrc, string strDat, LiraTable DstTable)
{
  if(strSrc != "Wud:MyMosaicSign")
  {
    return false; // Цей підпис нам невідомий
  }
  if(DstTable == null) // Якщо таблиця введення для цієї мозаїки була видалена -
  {                    // створюємо її заново
    LiraApplication LiraApp = new LiraApplication(); // Підключаємося до об’єкта LiraApplication
    LiraDocument LiraDoc = LiraApp.ActiveDocument;   //  отримуємо активний документ із розрахунковою схемою
    object Params1 = new object[] { "Element text mosaic", "11. Src=" + strSrc, 1 }; // Параметри створення таблиці
    DstTable = LiraDoc.AllTables.CreateNewItem(LiraTableEnum.kLiraTable_UserMosaicData, Params1) as LiraTable;
  }
  object Data1 = new object[2, 5] {{ "", 1, "", "1.1 Синій колір",   "#0000ff" },  // Дані для мозаїки (масив 2D)
                                   { "", 2, "", "2.2 Зелений колір", "#008800" }};
  DstTable.SetContents(Data1);         // Заповнюємо таблицю
  DstTable.Apply(out string strErrs);  // Впроваджуємо зміни. 
  // Ми не видалятимемо таблицю, щоб користувач міг згодом змінити її вигляд у вікні розрахункової схеми на свій смак
  return true;    // оновлення пройшло успішно
}

Щоб перевірити, як спрацювала ця функція, додамо до Книги звітів знімок екрана, на якому зображена мозаїка, побудована з функції DoAnalysis() вище. Потім клацнемо на знімку правою кнопкою миші та виберемо команду «Оновити виділені елементи». Метод ILiraExtension.UpdateScreenshotScreen() відпрацює, і зелений колір на мозаїці та на знімку в Книзі звітів зміниться на синій:

Рис.9

Рис.9

Інші методи об'єктів LIRA-FEM API, призначені для розширень

З діаграми в підрозділі «Об'єкти та інтерфейси LIRA-FEM API для розширень» було видно, що для роботи з розширеннями LIRA з'явилися об'єкти LiraExtensions і LiraRibbon, які забезпечують підключення розширень, а інші об'єкти отримали додаткові програмні інтерфейси. Але й в основних об'єктах з'явилися нові функції, призначені для роботи з розширеннями. У цьому підрозділі ми прокоментуємо найважливіші з них.

Об'єкт та його методи Опис
LiraDocument Документ, що містить розрахункову схему
CurrentLoadCase Номер завантаження в режимі задання вхідних даних. Встановлює або повертає число, від 1, для поточного завантаження вхідних даних (або стадії монтажу, якщо застосовно)
CurrentDesignOption Номер варіанта конструювання. Встановлює або повертає число, від 1, що позначає поточний варіант конструювання
LiraApplication Застосунок
Extensions Повертає посилання на об'єкт LiraExtensions (див. розділ «Об'єкти та інтерфейси LIRA-FEM API для розширень»)
Ribbon Повертає посилання на об'єкт LiraRibbon (див. розділ «Об'єкти та інтерфейси LIRA-FEM API для розширень»)
GetFilePath() Дозволяє отримати шляхи до папок, які налаштовуються у вікні «Каталоги» LIRA-FEM
GetInterfaceLanguage() Повертає мову графічного інтерфейсу користувача LIRA-FEM
GetCmdState() Повертає стан елемента меню/панелі інструментів/стрічки (кнопки), що відповідає команді, заданій у параметрі Cmd. Параметр pEnabled повертає значення, що вказує, чи увімкнений елемент (кнопка). Параметр pSel повертає стан елемента: 0 — не вибрано (не відмічено, не натиснуто), 1 — вибрано (відмічено, натиснуто).
SetCmdState() Запускає команду з ідентифікатором, заданим у параметрі Cmd. На відміну від методу LiraApplication.StartCmd, цей метод не повертає керування до завершення виконання команди.
GetViewState() Призначений для визначення поточного завантаження, варіанта конструювання та інших поточних налаштувань, що відображаються в рядку статусу вікна LIRA-FEM. Повертає стан випадного списку, переданого в параметрі Ctrl. Параметр pEnabled повертає значення, що вказує, чи увімкнений список. Параметр pSel повертає номер вибраного елемента в списку (від 0 до -1 означає, що нічого не вибрано). Необов'язковий параметр pItems повертає текст усіх елементів списку у вигляді масиву рядків.
SetViewState() Призначений для зміни поточного завантаження, варіанта конструювання та інших поточних налаштувань, що відображаються в рядку статусу вікна LIRA-FEM. Встановлює новий вибраний елемент Sel випадного списку, переданого в параметрі Ctrl
GetViewStateTimePoints() Отримує масив точок інтегрування для перегляду результатів розрахунку задачі динаміки в часі. Повертає масив значень типу long (кроків інтегрування, починаючи з 1). Параметр TimeHistory вказує номер динаміки в часі, починаючи з 1, параметр pStep повертає крок у секундах, pPointCount — загальну кількість доступних часових точок.
SetViewStateTimePoints() Задає часові точки (кроки інтеграції) для перегляду результатів розрахунку задачі динаміки в часі. Параметр lTimeHistory вказує номер динаміки в часі, починаючи з 1, TimePoints — це масив, що містить кроки інтегрування (починаючи з 1), необхідні для перегляду.

Серед наведених вище методів хотілося б відзначити кілька з них, які можуть виявитися найбільш корисними.

По-перше, LiraApplication.SetCmdState() дозволяє запускати команди або перемикати режими роботи застосунку, причому цей новий метод очікує завершення команди, а не одразу повертає керування, на відміну від методу LiraApplication.StartCmd(), після виклику якого необхідно було очікувати невизначений час, поки метод LiraApplication.StartCmd() виконається.

По-друге, у метод LiraApplication.GetViewState() можна передати параметр Ctrl=kLiraViewCtl_MainWindow (kLiraViewCtl_MainWindow=2000) і дізнатися HANDLE цього вікна — він потрапляє в параметр pItems цього методу. Ще, передавши в цей метод параметр Ctrl=kLiraViewCtl_Plot (kLiraViewCtl_Plot=1000), можна дізнатися, чи увімкнена зараз якась мозаїка або епюри. Якщо наразі увімкнена мозаїка, побудована за допомогою таблиці введення користувацької мозаїки, то в параметрі pItems цього методу можна отримати її підпис. Можна також вимкнути показ мозаїки, викликавши метод LiraApplication.SetViewState() з параметром Ctrl=kLiraViewCtl_Plot і параметром Sel=0.

Маючи ці відомості, ми нарешті можемо дописати метод ILiraExtension.GetExtensionCmdState(), в якому значення, що повертається, завжди залишалося нульовим. Тепер ми можемо визначити, що активна наша мозаїка, і повернути ненульове значення, щоб її кнопка виявилася «натиснутою» на стрічці інструментів. 

 
public void Startup()
{
  ...
  //Добавим еще одну функцию и кнопку для построения мозаики
  LiraExts.AddExtensionFunction("Wud", "Wood.WoodExtension.DrawPlot", strThisDllPath, LiraCallAfterEnum.kLiraCallAfter_Button, ref fFunctionsOrder);
  eCmd = Ribbon.AddButton("Wood","Analysis",-1,"Wud","Wood.WoodExtension.DrawPlot","Mosaic");
  m_CmdId2Func[eCmd] = "Wood.WoodExtension.DrawPlot";
}
static Dictionary<LiraCmdIdEnum, string> m_CmdId2Func = new Dictionary<LiraCmdIdEnum, string>();
 
public void DoAnalysis() { System.Windows.Forms.MessageBox.Show("Timber analysis performed!"); }
public void DrawPlot()   { CreateMosaic(". Src=Wud:MyMosaicSign"); }
 
//Обновленная реализация метода ILiraExtension.GetExtensionCmdState()
int ILiraExtension.GetExtensionCmdState(LiraCmdIdEnum eCmd, out bool pEnabled)
{
  pEnabled = false;
  string strFunctionName;
  if(m_CmdId2Func.TryGetValue(eCmd, out strFunctionName))
  {
    LiraApplication App = new LiraApplication();             // Отримуємо посилання на додаток LIRA-FEM
    LiraDocument Doc = App.ActiveDocument;                   // Отримуємо посилання на активний документ
    if(strFunctionName == "Wood.WoodExtension.DoAnalysis")
    {
      ILiraTables Ts = Doc.AllTables;                        // Отримуємо посилання на таблиці введення
      ILiraExtensionTables ETs = Ts as ILiraExtensionTables; // Приводимо її до інтерфейсу для роботи з розширеннями
      ILiraExtensionTable ET0 = ETs.FindTable(0, "Wud");     // Шукаємо таблицю з ідентифікатором 0 розширення "Wud"
      pEnabled = (ET0 != null);                              // Якщо обидві таблиці знайдено, то можна виконувати розрахунок
    }
    else if(strFunctionName == "Wood.WoodExtension.DrawPlot")
    { 
      pEnabled = true;                                       // Нехай кнопка мозаїки завжди буде доступною
      bool bPlotEnabled = false;
      object pItems = null;
      if(App.GetViewState(LiraViewCtlEnum.kLiraViewCtl_Plot, out bPlotEnabled, ref pItems) != 0 && bPlotEnabled)
      { // Якась мозаїка увімкнена. Це наша?
        object[] Items = pItems as object[];
        if(Items != null && Items.Length > 0)
        {
          string strPlot = Items[0] as string;
          if(strPlot != null && strPlot.Contains(". Src=Wud:MyMosaicSign"))
          {// Так, це наша мозаїка. Натискаємо кнопку: 
            return 1;
          }
        }
      }
    }
    else //if (strFunctionName == "...")
    {
      // інші перевірки
    }
  }
  return 0;
}

Автономна робота розширення

З різних причин буває зручно зосередити увагу користувача на одному або кількох елементах розрахункової схеми. Для цього в LIRA-FEM вбудовані так звані локальні режими конструювання залізобетонних конструкцій ЛАРМ і металевих конструкцій СТК. У локальному режимі розрахунку металевих конструкцій СТК, наприклад, доступне трасування розрахунку, тобто розгортання чисел кінцевого результату у формули аж до вихідних зусиль і геометричних характеристик металевих профілів, тоді як у металевому розрахунку LIRA-FEM таке трасування недоступне. Локальний режим дозволяє винести з LIRA-FEM деякі функції, наприклад, ті що потребують суттєвого додаткового обчислювального часу.

LIRA-FEM API надає розробникам розширень можливість створювати подібні режими роботи свого розширення, причому автоматично переносить майже всі можливості редагування вхідних даних і створення результатів із застосунку LIRA-FEM у локальний режим. Не переносяться хіба що можливості побудови мозаїк на розрахунковій схемі, оскільки повної розрахункової схеми в локальному режимі немає. Прикладом локального режиму є застосунок Wood.exe — локальний режим розширення «Дерево».

Якщо ми відкриємо Wood.exe, ми побачимо інтерфейс, дуже схожий на інтерфейс вікна Таблиць введення.

Рис.10

Рис.10

У ньому такі самі таблиці введення розширення «Дерево», як і в LIRA-FEM, і при натисканні на три крапки в комірці відкриваються ті самі вікна для редагування вмісту комірки. Всі ці можливості автоматично надаються LIRA-FEM API, а саме спеціалізованим елементом керування LiraExtensionTablesControl class. Користувач цього елемента керування знайде в ньому реалізацію вже знайомих інтерфейсів LIRA-FEM API. Діаграма взаємодії об'єктів та інтерфейсів локального режиму роботи розширення показана нижче.

     LIRA-FEM API                                        Розширення LIRA-FEM
    Елемент керування                                                      
    LiraExtensionTablesControl     
      ¦  
      ¦  Всі групи та таблиці введення 
      '--LiraExtensionTables
         ILiraExtensionTables     
            ¦         ¦                                  Об'єкт для керування 
            ¦         ¦                                  таблицями введення розширення
            ¦         '------------------------------<<--ILiraExtensionTableGroupHelper 
            ¦
            ¦  Група таблиць введення документа 
            ¦--LiraExtensionTableGroup 
            ¦  ILiraExtensionTableGroup   
            ¦    ¦    ¦                                  Об'єкт для керування 
            ¦    ¦    ¦                                  групою таблиць введення розширення
            ¦    ¦    '------------------------------<<--ILiraExtensionTableGroupHelper   
            ¦    ¦   
            ¦    ¦  Таблиця введення документа 
            ¦----'--LiraExtensionTable  
            ¦    ¦                                  
            ¦    ¦  Таблиця введення розширення                                  
            ¦----'--LiraExtensionTable   
            ¦          ¦                                  Об'єкт для керування 
            ¦          ¦                                  таблицею введення розширення 
            ¦          '------------------------------<<--ILiraExtensionTableHelper  
            ¦                                           
            ¦  Налаштування одиниць вимірювання                                                 
            '--LiraExtensionMeasurementUnits 
               ILiraExtensionMeasurementUnits

Проаналізуємо відмінності локального режиму роботи від режиму роботи в складі LIRA-FEM. У локальному режимі роботи немає об'єктів LiraApplication і LiraDocument, місце останнього займає елемент керування LiraExtensionTablesControl class. У ньому міститься паралельна реалізація таблиць введення, у тому числі контейнера всіх таблиць введення ILiraExtensionTables. Усередині цього контейнера можна створювати таблиці введення та їх групи. Щоправда, об'єкти таблиць введення та їх груп у цій реалізації не підтримують інтерфейси [I]LiraTable і [I]LiraTableGroup, але розширення може користуватися їх версіями ILiraExtensionTable і ILiraExtensionTableGroup. Ці інтерфейси підтримуються і в режимі роботи в LIRA-FEM, тому в більшості випадків розширення може користуватися версіями програмних інтерфейсів *LiraExtensionTable* замість *LiraTable*. Тільки коли йдеться про взаємодію з розрахунковою схемою, розширення може запитувати інтерфейси *LiraTable*, а через них і об'єкти типу LiraDocument або LiraApplication.

В інших же випадках можливостей інтерфейсів *LiraExtensionTable* буде цілком достатньо. Одиниці вимірювання доступні лише у вигляді інтерфейсу ILiraExtensionMeasurementUnits, але знову-таки це не проблема, оскільки він підтримує всі методи інтерфейсу [I]LiraMeasurementUnits, а отже, розширення може використовувати ILiraExtensionMeasurementUnits завжди — як у режимі роботи в LIRA-FEM, так і в локальному режимі роботи.

Інтерфейс та його методи Опис
LiraExtensionTablesControl Основний інтерфейс розширення для роботи в середовищі LIRA-FEM
AllowEditTree Дозволяє користувачу видаляти або переміщати елементи в деревоподібному поданні цього елемента керування.
Tables Всі таблиці введення одного документа локального режиму роботи розширення

Корінною відмінністю локального режиму роботи розширення від режиму роботи в LIRA-FEM є відсутність у локальному режимі об'єкта ILiraExtension. Цей об'єкт ніколи не створюється, а замість нього застосунок має підтримувати об'єкт, що реалізує інтерфейс ILiraExtensionTablesHelper. Його єдине призначення по суті — створювати об'єкти ILiraExtensionTableGroupHelper і ILiraExtensionTableHelper при завантаженні документа локального режиму. Інтерфейс ILiraExtensionTablesHelper невеликий:

Інтерфейс та його методи Опис
ILiraExtensionTablesHelper Службовий інтерфейс, заміна ILiraExtension, який дозволяє завантажувати таблиці введення з файлів, що зберігаються на жорсткому диску
CreateTableHelper() За запитом LIRA-FEM API створює та повертає об'єкт, що керує таблицею введення розширення ILiraExtensionTable або групою таблиць введення розширення ILiraExtensionTableGroup
GetExtensionId() Повертає трибуквений ідентифікатор розширення
GetExtensionName() Повертає ім'я розширення
ExtensionDocumentClosing() Викликається при закритті автономного документа в автономному застосунку розширення. Потребує звільнення посилань на об'єкти в автономному документі.

Щоб створити локальний режим роботи розширення LIRA-FEM, необхідно створити застосунок .EXE і розмістити на його формі або діалоговій панелі елемент керування LiraExtensionTablesControl class. У Microsoft Visual Studio для цього слід клацнути правою кнопкою миші у вікні Toolbox, вибрати пункт контекстного меню Choose Items, потім увімкнути на закладці COM елемент керування LiraExtensionTablesControl class і натиснути OK.

Рис.11

Рис.11

Після розміщення елемента керування на формі він виглядатиме так:

Рис.12

Рис.12

Якщо вам не вдалося з першого разу розмістити цей елемент керування на формі, виконайте такі дії:

  • Переконайтеся, що властивість Platform Target вашого застосунку встановлена в значення x64, оскільки 32-розрядної версії цього елемента керування не існує.
  • Скомпілюйте застосунок.
  • Перезапустіть Visual Studio.
  • Знову спробуйте розмістити елемент керування.

Як видно після розміщення елемента керування на формі, він інкапсулює редагування таблиць введення. Вашому застосунку треба просто інстанціювати потрібні з них, як це робив об'єкт ILiraExtension. Мова елемента керування відповідає мові LIRA-FEM.

Збереження та завантаження даних здійснюється за допомогою методів ILiraExtensionTables.SaveToFile() і ILiraExtensionTables.LoadFromFile(). Завдяки тому, що метод ILiraExtensionTables.LoadFromFile() може читати дані, записані методом LiraTables.ExportToFile(), дуже легко виконати передачу даних із режиму роботи в LIRA-FEM у локальний режим роботи розширення. У розширенні «Дерево» для цього передбачена спеціальна команда «Локальний режим розрахунку елемента». При виклику цієї команди створюється кілька тимчасових таблиць, у яких розширення збирає дані виключно виділених на розрахунковій схемі елементів, потім виконує їх експорт за допомогою методу LiraTables.ExportToFile() і далі відкриває цей файл застосунком Wood.exe.

За замовчуванням у локальному режимі роботи розширення операції з таблицями введення, такі як перейменування, переміщення або копіювання таблиць у дереві за допомогою перетягування мишею або буфера обміну, вимкнені. Увімкнути їх можна у властивості AllowEditTree елемента керування LiraExtensionTablesControl class, розміщеного на формі. Усі експортовані з режиму LIRA-FEM у локальний режим таблиці, що не мають своєї реалізації інтерфейсу ILiraExtensionTableHelper, будуть відображатися в локальному режимі просто як текст і без можливості редагування комірок у відповідних діалогових панелях. У локальному режимі недоступне побудова мозаїк на розрахунковій схемі та документування за допомогою Книги звітів.

Елемент керування LiraExtensionTablesControl class встановлюється та видаляється разом із LIRA-FEM, однак для своєї роботи не потребує ліцензії LIRA-FEM.


Довідник з розділів і параметрів реєстру Windows, що стосуються розширень LIRA-FEM

Розділ Параметр Допустимі значення Коментарі Відповідний метод API
HKEY_LOCAL_MACHINE\Software\LIRA EXTENSIONS\ Розділ для реєстрації всіх розширень
Abc Лише латиниця та цифри Трибуквений ідентифікатор розширення LiraExtension.AddExtension()
(За замовчуванням) Script:VBS Розширення написане мовою VBScript те саме
Script:JS Розширення написане мовою JScript
Script:V8 Розширення написане мовою V8 Java Script
Dll:Net4 Розширення — це DLL на .NET Framework 4 (мова C# тощо)
Dll:stdcall Розширення — це native DLL з угодою про виклики _stdcall
Dll:cdecl Розширення — це native DLL з угодою про виклики _cdecl
Exe:App Розширення — це окремий застосунок EXE
Version 20AB - 20CD З якими версіями LIRA-FEM сумісне розширення, наприклад: "2026 - 2027". Якщо це значення не вказано, застосунок сумісний з усіма версіями LIRA-FEM, починаючи від 2026. те саме
Name Довільний текст Ім'я розширення те саме
RibbonTab Довільний текст Ім'я вкладки на стрічці інструментів, на якій розташовуватимуться кнопки для розширення LiraRibbon.AddExtensionTab()
RibbonTabImageListSmall Обмежені файловою системою ОС Шлях до горизонтального спрайту із зображеннями 16x16 або 24x24 (залежно від налаштування «Великі значки на стрічці») для кнопок розширення на стрічці інструментів те саме
RibbonTabImageListLarge Обмежені файловою системою ОС Шлях до горизонтального спрайту із зображеннями 32x32 або 48x48 (залежно від налаштування «Великі значки на стрічці») для кнопок розширення на стрічці інструментів те саме
Function Обмежені мовою програмування Ім'я функції або методу розширення з урахуванням простору імен і імені класу, якщо вони є LiraExtension.AddExtensionFunction()
(За замовчуванням) Обмежені файловою системою ОС Шлях до файлу VBS/JS або DLL/EXE, що містить функцію те саме
CallAfter Button Функція має бути викликана після натискання кнопки на стрічці те саме
AppStartup Функція має бути викликана безпосередньо після завантаження застосунку*
Analysis000 Функція має бути викликана перед скінченно-елементним (СЕ) розрахунком*
AnalysisFEA Функція має бути викликана безпосередньо після СЕ розрахунку*
AnalysisCLA Те саме, після розрахунку сполучень навантажень і впливів СНВ*
AnalysisDCF Те саме, після розрахунку розрахункових сполучень зусиль РСЗ*
AnalysisUCF Те саме, після розрахунку уніфікованих зусиль РСЗ*
AnalysisDCL Те саме, після розрахунку розрахункових сполучень навантажень РСН*
AnalysisLoF Те саме, після розрахунку навантажень на фрагмент*
AnalysisPES Те саме, після розрахунку головних і еквівалентних напружень*
AnalysisCRK Те саме, після розрахунку ширини розкриття тріщин після нелінійного розрахунку*
AnalysisDOs Те саме, після розрахунку варіантів конструювання (з/б, метал, цегла)*
AnalysisCSV Те саме, після створення CSV-файлів результатів (якщо замовлено)*
Name Довільний текст Підпис кнопки на стрічці** LiraRibbon.AddButton()
ToolTip Довільний текст Підказка кнопки на стрічці** те саме
Description Довільний текст Опис кнопки на стрічці** те саме
RibbonImageSmall Обмежені файловою системою ОС Номер від 0 у спрайті або шлях до зображення 16x16 або 24x24 (залежно від налаштування «Великі значки на стрічці»)** те саме
RibbonImageLarge Обмежені файловою системою ОС Номер від 0 у спрайті або шлях до зображення 32x32 або 48x48 (залежно від налаштування «Великі значки на стрічці»)** те саме
RibbonPanel Довільний текст Ім'я панелі на вкладці стрічки інструментів, на якій розташована кнопка LiraRibbon.AddPanel()
RibbonAlwaysLarge 1 або 0 Кнопка завжди велика** LiraRibbon.AddButton()
HelpCommand Обмежені файловою системою ОС Виклик довідки для цієї функції розширення**, наприклад: C:\Program Files (x86)\LIRALAND\LIRA-FEM 2026\bin\x64\help\ru\LiraFEM.chm ILiraExtension.HelpContext()
* Можна вказати порядок виклику у вигляді числа double після знака плюс «+», наприклад, Analysis000 + 123.456
** Лише для функцій з "CallAfter"="Button"

Технічні специфікації технології розширень LIRA-FEM

У цьому підрозділі перелічується, якими мовами можна писати та налагоджувати розширення LIRA-FEM.

Підтримувані мови програмування in-proc:

  • інтерпретовані мови — VBScript, JScript, V8 Java Script
  • native мови — будь-які, що підтримують COM (С++, С тощо)
  • мови .NET Framework 4 — будь-які (C#, managed C++, VB .NET тощо)

Підтримувані мови програмування out-proc:

  • будь-які, що підтримують COM (C, C++, C#, Python тощо)

Налагодження in-proc:

  • дозволено для інтерпретованих мов

Налагодження out-proc:

  • дозволено для будь-яких мов

Помилка в тексті? Виділіть її та натисніть Ctrl + Enter, щоб повідомити нам.

Дмитро Медведенко

Провідний інженер-програміст компанії «ЛІРА САПР».
Розробка програмних комплексів.

Інші публікації цього автора

Коментарі

Написати