Word add-in - calculation reports in Word

The Struct4U Word add-in puts an XFrame2D calculation report straight into a Word document. You drop a saved model onto the Calculations pane, XFrame2D calculates it in the background, and the report is inserted at the cursor as a linked block. When the model changes later, the block can be brought up to date in place - the surrounding text, the page numbering, and any bookmarks or cross-references that point at the report block all stay as they were.

The add-in is shared by the whole Struct4U family. Besides XFrame2D models (.xfr2) it accepts XBeam2D (.xbe2), XConstruct (.xcst) and XFEM4U (.xfem, and the older .xfr3) models, so one Word document can hold reports from several programs.

The short video below shows an XFrame2D model being inserted into Word.

Requirements

Microsoft Word for Windows (the desktop version; Word on the web and Word for Mac cannot load it).
XFrame2D 2027.8 or later. The /report batch mode the add-in drives arrived in 2027.8. An older XFrame2D is refused with a message naming the version needed, rather than being started and left to time out.
A valid XFrame2D licence. The calculation is a normal XFrame2D run and is licensed as one.
.NET Framework 4.8 and the Visual Studio 2010 Tools for Office Runtime. The XFrame2D installer adds the Office runtime if it is missing. .NET Framework 4.8 is part of Windows 10 version 1903 and later; on an older version of Windows the installer stops and asks you to install it first.

Installation

The add-in is part of the XFrame2D installation, as the Word Add-in feature. It is installed into a shared folder, C:\Program Files (x86)\Struct4u\Word Add-in, rather than into the XFrame2D program folder: XBeam2D, XConstruct and XFEM4U install the very same files there. Windows keeps one copy however many Struct4U programs you install, and removes it when you uninstall the last of them.

Word loads it for every user on the machine, under the name Struct4U Calculations. You can see it in Word under File > Options > Add-ins.

The Struct4U tab in Word

After installation Word has an extra ribbon tab, Struct4U, with two buttons:

Calculations - shows or hides the Calculations pane. The pane is hidden every time Word starts, so this is how you open it.
Info - the add-in version, and the four Struct4U calculation programs, each marked as installed or not and as able to produce reports or not. This is the quickest way to check whether your XFrame2D is new enough.

The Calculations pane

The pane docks at the right-hand side of the Word window and holds three things:

The drop zone at the bottom - Drop your models here. Drag one or more models onto it to insert their reports.
The block list - one row per report block in the document, in document order, with the Model it came from and its State.
The toolbar - six buttons: Insert…, Edit, Delete, Unlink, Update and Update all. The buttons show icons only; hover over one to see what it does.

Inserting a report

Open or create the Word document and put the cursor where the report should go.
Open the Calculations pane with Struct4U > Calculations.
Drag the model file onto the drop zone, or use Insert… to pick it from a file dialog.

XFrame2D is started in the background, calculates the model and writes the report; the report is then inserted at the cursor. A progress dialog with a Cancel button is shown while this runs, so you can stop a calculation that is taking too long. Stopping changes nothing in the document.

Several models dropped at once become several blocks, inserted in the order you dropped them. The insertion point is always the cursor, not the place in the page where you let go of the mouse.

Only one calculation runs at a time. Starting another while one is busy is refused with A calculation is in progress. Wait for it to finish.

What is in the report

The report is exactly the DOCX output XFrame2D itself produces. It contains what the model's own output selection (the Output selection dialog) asks for, except the choice of load combinations: when combinations are reported, all of them are. The drawing size comes from the Output settings on the computer that runs the calculation.

The add-in does not ask what to include: it uses the output selection stored in the model. To change what a report contains, open the model in XFrame2D, change the output selection, save the model, and update the block.

Keeping reports up to date

Every block remembers which model it came from and a fingerprint of that model's contents. Whether a report is still current is decided by that fingerprint, never by a file date - a model can be saved without anything in it changing, and a model can change without its date being helpful.

The State column says where each block stands:

State	Meaning
Up to date	The report matches the model as it is now.
Out of date	The model has been changed since the report was inserted.
Model missing	The model file is no longer where the block recorded it.
Model locked	The model file is there but cannot be read - it is open elsewhere, or you have no access to it.
Needs attention	The block and its record no longer belong together. Almost always a report block that was copied and pasted inside Word: only the original can be updated, and the copy keeps the numbers it was pasted with.

There are three ways a block is brought up to date:

Update recalculates the selected block; Update all recalculates every out-of-date block in the document at once.
Opening the document - if it holds out-of-date reports, Word asks once, naming the file and the number of blocks: 1 calculation in hal.docx is out of date. Update it now? Answering No leaves the document exactly as it was. Nothing is ever refreshed silently: a report that has been checked and signed must not change under its author.
Editing the model - see below.

A refresh replaces the contents of the same block, so bookmarks and cross-references that point at the block survive it. If a refresh cannot finish, the existing report is left as it was rather than being blanked. When every block is updated, the pane says how many; otherwise a message names each failed block and the reason.

Editing, deleting and unlinking

Edit opens the selected block's model in XFrame2D. Close XFrame2D again and the block is recalculated if you changed the model, and left alone if you did not. Double-clicking a row, or pressing Enter on it, does the same.
Delete removes the block and its report from the document.
Unlink keeps the report but turns it into ordinary text. It is no longer listed in the pane and will never be updated again, and you are free to edit it.

An inserted report is protected: you cannot type inside it, because anything you typed would be thrown away by the next update. Use Unlink when you want to edit the text of a report by hand.

Language

The add-in follows Word's own interface language, not Windows'. A Dutch Word shows a Dutch add-in, an English Word an English one. It has nothing to do with the language XFrame2D itself is set to; the report inside the block comes from XFrame2D and follows XFrame2D's language setting.

Limitations

Blocks cannot be reordered from the pane. Move a report by removing the block and inserting it again at the new place.
Copying and pasting a report block inside Word produces a second block that cannot be updated. It is listed as Needs attention, named as a copy of the original. Insert the model a second time instead.
Word 97-2003 documents (.doc) cannot hold reports. Convert the document first (File > Info > Convert) or save it as .docx.
One calculation at a time, per Word session.
If one model takes more than ten minutes, the calculation is stopped: nothing from it is inserted, and blocks not yet recalculated keep their existing report.
Word for the web and Word for Mac are not supported.