Important must read: Splitting UI out of KoDocument

[C. Boemann]

As some of you may have noticed Bodewijn and I have spent the last 4 days 
extracting the UI out of KoDocument, and ported the applications to that 
change.

This is the branch: libs-kodocument_split_boud_and_boemann

Some background:  Calligra relies on KParts for embedding our applications 
into other applications. It used to be (before flake) that we also used it to 
embed a subdocuments (think a spreadsheet within a presentation) but we don't 
do that anymore (the idea was/is to use a shape for that).

And with that has gone the need for changing the UI depending of what 
(sub)document was active. This means we have the possiblity to remove the UI 
from the documents. In fact it is really good if we can separate it and the 
wish has come up at sprints over and over again. It's no good that 
applications have to carry our widget based UI around even if they don't use 
it (the QGraphicsView documents app on the N9 actually instantiates all our UI 
but just never shows it). The same thing happens in Calligra Active.

You can also see this splitting of the UI away from the KoDocument as the first 
step to being able to compile on Qt6 (not 5) where widgets might go away. And 
as a way to be more flexible in our architecture.

This is only a first step, but nevertheless an important one. It was done on my 
initiative, and as such is not for some secret costumer of KO. It was a 
regular community sprint, though KO graciously sponsored my flight and two 
working days.

What we have done is to create a new class KoPart that basically holds all the 
ui stuff that used to be in KoDocument. Right now the KoDocument still holds a 
pointer to that KoPart, but that is supposed to go away in further refactoring 
(not planned when) so please don't use that in new code. We have used it in a 
couple of places where we have ported the apps but at least for Flow, Stage, 
Words and mostly in Sheets I've done it the right way.

Which is to emit signals from the document and connect those to slots in the 
view or part. The connecting happens in the part (which now holds the 
createViewInstance() factory method.

Using signals and slots to communicate with KoDocument also ensures that we 
are compatible with qml in the future, if someone wants to make qml based ui 
without having to create adaptor classes.

Now the KoDocument is no longer a KPart, but just an ordinary QObject. We 
still subclass the KoDocument in all the applications and addtionally we also 
subclass the KoPart. So in the application factories where for example before 
we only created a FlowDocument, we now do:

part = new FlowPart(parentObject);
doc = new FlowDocument(part); // in the future it will just take a qobject
part->setDocumennt(doc); // let's the part know about the document it 
maintains

return part; // it used to return the document


We have tried our best to test but need the help of you all to do this right. 
Look for crashes, missing menus, templates, shape adding and removing that 
doen't work. These will be the most likely bugs.

We also ask you to look at the porting we have done, and see if we have done 
it right. It's mostly easy to part an app, but there may be side effects we 
don't know about. And especially the places where I've used signals I may have 
broken some things.

There is no pressure for you to make it even more independent. Each 
application may very well have other UI in their Document classes.

Another thing we have moved out of KoDocument is the startup dialog and file 
dialogs. This seems to works, but again please make sure we didn't miss 
anyting. We did a lot of work in 4 days, and now need you to check up on us.

Such a big branch has a tendency to bit rot quickly so please do your checking 
and reviewing quickly so we can merge within a week or so. If we don't hear 
from you we will assume you have tested and found no problems.

It's unlikely that there will be no problems, so I urge you to check. We will 
be at assistance and even do most fixes, but some things probably requires your 
inside knowledge of how your app works.

Next steps after merging: is to go over it one more time (probably during the 
evenings at akademy). and see if we can clean it up some more, but this was 
the big one. Another next step is to go through each app and make them more 
separated too. Good news is that the libs should no longer make that 
impossible. At least not regarding the documents.

The tools are not part of our current focus, but we are well aware that they 
pull in widgets too. More than that they require actions and those require 
widgets, so it's a big refactor too. Maybe some other sprint some other time.

Boemann