The following paragraphs shall give you an introduction into the graphical user interface of the plugin. Starting point of this tutorial is the already opened plugin, that means right after you started the BCFPlugin.FCMacro from inside FreeCAD.

---

You are presented with a rather empty window:

The section containing the "Open"- and "Create" (further called "Project"-section) will be present through the lifetime of the plugin. However, only at the start of the plugin can a new project be created. If an existing file is opened the "Create" button is hidden. At every point in time, although, another project file can be opened. But beware: opening another project file without saving it beforehand does discard the current working state!.

You are presented with the file open dialog that already filters for ".bcf" and ".bcfzip" files.

When a file was selected, the plugin extracts the contents of the underlying zip file into a new directory in the system's temporary directory. After that the contents of the extracted files are read into the data model. After completion a list of all topics available in the project file is shown, as well as a button to add new topics. It looks like the following:

Per default no topic is opened and the plugin's UI looks rather empty. This is due to the fact that the most information is contained inside topics. So to select/open a topic double press on an entry of your choosing. This will result in the showing up of all other UI elements.

The section right below the topic list and also the project section is the comment-section. It is consists of two elements: a list of comments, and a line edit element that enables the user to add new comments.

A comment is shown in a customized, two-line list element. In the first line, the main line, shows the actual text of the comment. The second line contains the author of the latest change and the date of the latest change. If the comment was just created and no change has taken place since then, the original author and the date of creation will be shown.

The following screenshot shows a resized version of the plugin.

The above screenshot not only gives a good view of the comment elements but also shows a delete button on the right side of one comment. This delete button will show up over the comment the mouse is hovering over. A press of this button will delete the corresponding comment.

Note: The first comment is painted in blue! This means that linked to that comment is a viewpoint. Selecting such a comment will automatically also select the corresponding viewpoint in the viewpoints list (see below).

A comment can be easily added by utilization of the line edit field below the comments list (the second element in the comment-section). After you have hit enter, and did not make any future modification to the plugin's state, you are prompted for your E-Mail address. This will be filled into the Author field. But it also can be left empty.

Existing comments can be modified also. To do that double press, with the left mouse button, onto the desired comment. The comment text and the author are presented to you inside a drop-in text editor in the format described above. Now you can edit the comment. The E-Mail address you have or have not entered before is stored and now taken automatically as value for the ModifiedAuthor field. To submit the changes hit the [Enter] key. The drop-in text editor disappears and the updated comment will be shown.

The bottom-most group is called the "snapshot"-section, due to a lack of better names I took the name of the first element I added to this section. It, however, actually not only shows snapshots associated with the opened topic, but has the capability of displaying one of many widgets. The desired widget to show can be selected in the combo-box. Currently it is possible to open one of two widgets/views:

• Snapshot-List: This view/list displays at most three snapshots in a horizontal list. Snapshots are just plain screenshots of the BIM (Building Information Model) the BCF file was created for. With a double press on one snapshot it can be opened in a separate window in its full resolution.
• Viewpoints-List: The viewpoints list is a vertical list of all viewpoints associated with a topic. Viewpoints are just settings that describe how the BIM shall be displayed to make the issue with it more clear. Each viewpoint is accompanied by an icon if the viewpoint has an associated snapshot.

The screenshot below shows the viewpoints list:

The topic metrics window can be opened by clicking the details button in the upper right corner of the plugin. It becomes available as soon as some topic has been selected. What you are presented with is the following window:

The first list you see is a compilation of all the members of a topic that contain an integral value (e.g. only some text or a number etc.). Some values in the right column are greyed out, this is due to the fact that these values shall and cannot be edited by the user. These are set automatically by the plugin itself or are not up to modification. All other values can be edited in the same manner as comments. Just double clicking and entering the new value.

The second list, which is not shown in the above screenshot, contains a table with two columns displaying additional documents. The first column contains the description or name of the document, the second column contains the path to the document.

Names in the first column are displayed in blue if they are found on the local system, with the given path. A double click on these entries opens the file with the standard application of the system. If however the path of the document is more interesting it can be copied also with a double click.

The third list, which is empty in both above screenshots, contains only a list of topics that are related to the currently selected one.

Now that we know how to explore the contents of a BCF file it is time to start creating new BCF files! The option to create a new BCF file is only available right after the start of the plugin. It presents itself to us via the "Create" button right below the "Open" button. If pressed a new dialog window opens requesting a name for the new project:

After the name is submitted, a new temporary working directory is created for the new project. At the same time the plugin opens the project and displays its contents, as it would if an existing BCF file would have been opened. Since we just created the project, not really much is present right now.

The only action that can be done right now is to create a new topic. A click on the "Add-Topic" button opens the "New Topic" dialog window. The required fields are marked with '(*)'. Apart from the topic title, nothing is required, so it can be left empty.

If we submit the new topic we get back to the same view we had after creating the project, but now the list shows our new topic too! Now it can be used as any other topic.