BCF Support GSoC Proposal

[pPodest]

Here the update I wanted to post for some time now. Since this is a longer post, explaining (mostly) all of the functionality currently implemented, it will be structured into

1. A description of what can be done, and how the data is presented
2. Showcasing in form of screenshot tutorial.

State of Development
If you check out the current state of the feature/gui branch in the repository you find the root directory with the following contents:

Code: Select all

./bcf-examples
./bcfplugin
  |- gui/
  |  |- comment-list/
  |  |- design/
  |  |- examples/
  |  |- plugin_delegate.py
  |  |- plugin_model.py
  |  |- plugin_panel.py
  |  |- plugin_view.py
./doc
./env
./README.md

In the above listing I intentionally didn't list all files and directories, just the most important ones for this post. To start the plugin, as a standalone Qt application start plugin_view.py. This file contains the design of the plugin. To launch the plugin in the task panel you would include plugin_panel.py using the FreeCAD python console, but this will be part of a future post.

As I mentioned before (sometime), I am adhering to the Model/View(/Delegate) paradigm of Qt. For the ones not fluent with this paradigm here a short summary:

With the Model/View paradigm a separation between the presentation of data to the user, and the representation of the data in memory is achieved. The part comprising the model handels the access to the custom data structure and compiles it to a usable form for the View part. The View arranges the Qt widgets in a way that is functional and queries the data to present the user from the accompanying model. The Delegates are (as to my understanding) a second link between the Model and the View. Its main purpose is to handle edit-events on the model. Thus Delegates are responsible for drawing editors into the view and submitting the edited data to the model. I also use it for the drawing the custom elements in the comments list.

For a more comprehensive overview about this topic please refer to Qt Model/View

With this in mind, the intention behind the plugin-*.py files is easy to understand:

• plugin-view.py: contains all views, including the main view tying everything together
• plugin-model.py: provides classes and functions that handle the access to the data model, read in by reader.py
• plugin-delegate.py: handles the editing of some custom views. Currently this file holds code handling the editing and drawing of comments.

After startup, the user is asked to open a BCF-File, which is actually the only option the user has at this stage. If one is selected, the internal data model gets populated, and the UI is set up. In the top left the title of the project is shown, beside a button to save it to file or open another file. Below the user is able to select one topic which triggers the population of the comment list.

The comment list is where the most magic happens at the moment. If you want to change the wording, or the author of a comment, double press on the corresponding item. You will be droped into a QLineEdit, filled with the current content and author. If you hover over a comment a Delete-Button is drawn at the right side, which will delete the comment beneath, if pressed. The positioning of this button is still a bit buggy, which is noticable if the window is resized often. A comment will be written in blue color if it holds a reference to a viewpoint, otherwise it is drawn with black color. In the future I want to implement a shortcut to apply the linked viewpoint. A new comment can be added by entering it in the QLineEdit below the comment list.

Here a note on the editing and adding of comments: I opted for a single QLineEdit (Textbox) for modifying and adding comments, for reasons of complexity. That is why you (or the user) have (has) to adhere to a particular format when modifying or adding. This format is checked by a QValidator object, and is indicated by the placeholder text of the QLineEdit. First and foremost is the comment itself, followed by a space, a double hyphen and a space again. At the end an e-Mail of the author is required. So long story short a comment looks like this:
some text comprising the comment -- author@email.com

Showcasing

This was about it from the description. Now to the screenshots. Following you will find a description of what to see in each picture. To recreate the screenshots (if you want), I used the file Issues_BIMcollab_Example*.bcf from the ./bcf-examples folder.

• screenshot01.png: shows the start up screen
• screenshot02.png: shows the open file dialog after pressing Open
• screenshot03.png: shows the plugin after a project was sucessfully opened (for big projects this takes a while, presumably because all error
  messages are still printed to stdout, I plan to write them to an error.log file in the future)
• screenshot04.png: shows a populated comment list, after one topic was selected (in the screenshot it was Topic Intersections check: column inside slab
• screenshot05.png: shows the delete button drawn over the first comment.
• screenshot06.png: shows the comment list after the delete button was pressed on the first comment.
• screenshot07.png: shows the now first comment after it was double pressed with the left mouse key. The content is dropped into a QLineEdit, in the afore mentioned format.
• screenshot08.png: shows the comment list after hello this -- is@a.text was entered in the Textbox (QLineEdit) below the comment list, and enter was pressed.

[pPodest]

And here the second set of screenshots. I could not include all eight.

[duncan.lithgow]

Looking good. Is the BCF file validated in some way? I heard recently from a BIMcollab reseller that BIMcollab BCF files are not a full implementation of BCF - I don't know if this is true. That information simply got me thinking that validation might be a good idea.

[pPodest]

Yes it gets validated, against the supplied schema files at least. The way I handle data that is not conform to the schema files, is that it is simply skipped during reading it in. xmlschema is quite nice for this kind of stuff.
Every validation error, reported by xmlschema, is currently also printed to stdout. The error messages reported by the library are quite exhaustive and tell the user exactly what is violating in the BCF file.

I also talked with one support representative of BIMCollab already about this topic, because I noticed that the example BCF file they provide on their webpage, does not strictly adhere to the specifications. The final say was something like:
"Vendors using BCF are allowed to define their own elements. These elements do not have to be supported by every BCF application, but applications not supporting such modifications should still enable the user to act on the remaining data."

[yorik]

Excellent, that looks bright!!

I liked the "add new comment" placeholder text - easy syntax. The comments display is pretty clear and elegant too. Perfect!

In my opinion, I find it hard to schedule time for writing a post when development is going good, because then I think “I will still implement this feature and then write the post”, which then does not happen.

I know that problem too No worries! Just don't forget writing is also an important part of the game.

About "fancy features" others can add to BCF, indeed with xml it's a common behaviour. Parse the tags, do something with what you know, ignore the rest. It is usually easy to extend later on if needed...

Can you make the comments word-wrapped? I'm pretty sure there should be a simple switch for that in Qt, both for the QListView and the QLineEdit delegate..

[pPodest]

Can you make the comments word-wrapped? I'm pretty sure there should be a simple switch for that in Qt, both for the QListView and the QLineEdit delegate..

That the comments aren't word wrapped itches me too. The reason I didn't include it right away was the calculation of the size of the resulting text, which has to be reported by CommentDelegate to the view. Back when I implemented it, I thought that I had to implement the whole wrapping algorithm myself, which becomes hardcore if different screen resolutions and DPIs have to be considered. This problem could be solved, I think, by using QFontMetricsF.boundingRect(), or other functions of QFontMetrics. I will look into it right after I finished the SnapshotBar, which I am currently working on!

[pPodest]

I want to give a short update here too, at least every second day, of my working days.
So today I finished the SnapshotBar, it has now an acceptable state to be shown. The snapshot bar shows three snapshots, with some spacing in between them. A double click on one picture/snapshot results in it opening in full resolution in a separate window.
Then I started working on the word wrapping part, yorik suggested. But it is a bit hard, as it turned out. I ran into two main problems:

1. The function QFontMetric.boundingRect() somehow breaks the comment into two lines when in fact there is still much whitespace left, right of the comment. This results in an unintentionally big offset to the separation line between the comment and the author/date line.
2. When the plugin is started in a way that all comments fit into one line and it then is resized the list items do not resize properly with the widget. This results in the paint function of the CommentDelegate class to draw one comment over the one beneath.

Following a short description of the screenshots attached.

• screenshot01.png shows the word wrapping in action with the issue 1 in in effect.
• screenshot02.png shows the window that opens when a snapshot is double clicked
• screenshot03.png shows the comment list when the widget can fit every comment in one line. Here the second issue is visible, but in the other direction. Instead of drawing over the comment beneath, the offset between two comments grows larger the fewer lines are needed for a comment.

[yorik]

Great!!!
Don't worry too much at this point about these little defects in Qt Widgets, specially with alignments and things like that... It's sometimes hard to get them right, but later on you find workarounds.

[pPodest]

Ya, well I fixed it ^^
As it turned out I didn't use the abstract classes properly. I forgot to send the sizeHintChanged event. This was the main culprit.
I uploaded a short video showing how the comments are now resized with the whole plugin https://nextcloud.podest.co.at/index.ph ... 8jAH6msyaS.

I want to tell you in advance that this weekend, starting from Friday (2019-07-19) at noon till Sunday, I will not do any development work. This weekend I am attending a hiking trip. But tomorrow moring, I will still be putting in some valuable hours.

[yorik]

Excellent, you're quickly becoming a pyside wizard
Have fun!

BTW next week there is a new GSOC evaluation, I think your work is fully up to date and going well, nothing special to do, but if you could write a small wrap-up, that would be great!