Calligra/Libs/KoAbstraction

Introduction

KoAbstraction is a library utilizing facade design pattern in order to simplify implementation of custom graphical interfaces for various applications.

Status: experimental, in development for 2.4.

Strategically, it's a showcase of #1 KOffice's advantage: portability and flexibility of the core, unmatched independence of the GUI. So far in my opinion we have not encouraged 3rd-parties to use this strength very consequently. It's much easier to expose this strength than first competing in area of features with mature competitors. --jstaniek

This is follow up of KOffice core re-usability request raised for the first time at Akademy 2005, and just recently discussed in Essen 2010 Sprint.

Implementation provided for review at http://git.reviewboard.kde.org/r/100304/

Applications

Most important possible applications of this tool are:

• Proof of concept koffice app in "100 lines of code or so", for Techbase
  • Status: planning
• Standalone KOffice viewer widget (can be used in Designer!)
  • Status: planning
• Proof of concept koffice app for QML (hot topic!) when the APIs support non-QWidget mode
  • Status: planning
• Proof of concept even higher-level Qt-only API abstracting KOffice core
• Avoiding creating general-purpose code directly in any current and future use of KOffice core by third parties, assuming that there is a will to collaborate
  • Status: Validated, currently it's avoiding creation of general-purpose code directly in FreOffice, what is part of [1] patch
  • Rationale: previous it was hard not to keep the 3rd-party UI implementation outside of koffice/ source code tree because implementation of the UI may depend on KOffice internals or unstable API; maintaining that within the facade API simplifies a number of tasks
  • Other possible ports: port of the Kids Office
• Refreshed KPart, to make it behave in a more modern way
  • Status: planning, let's note down our future needs for integration with Okular
• Integration with plasma (non-QWidget target)
  • Status: planning

All the above is not limited to mobile technologies, and heavily validates quality of the code base and design.

See Also

Technologies utilizing similar concepts: WebKit, Plasma, KDE libs, and Qt itself

Refactoring

Started Jstaniek 20:47, 5 February 2011 (UTC)

Status: finished, applied.

Background

The KoAbstraction API version 1 (Calligra master from early 2011) requires include .moc file generated in the library by outside code (e.g. in the f-office app) and using typedef to workaround impossibility of multiple inheritance from QObject-based classes. This is considered as a hack if not fragile and unclear. Also it was requested by the FreOffice developers to fix problems with their custom builds on maemo.

The Goal

Refactor the KoAbstraction lib so the API is more natural and has more OOD.

See also: Mani has also addressed a need for custom maemo builds: http://git.reviewboard.kde.org/r/100462/ ; this is not needed now.

The development happens on branch tools-koabstraction_refactoring1-staniek

Changes

• KoAbstractApplication:
  • renamed to *KoAbstractApplicationWindow
  • KoAbstractApplicationWindow is now a thin interface to inherit by the main application window, e.g. main window of FreOffice.
  • KoAbstractApplicationWindow no longer inherits QObject.
• KoAbstractAppliactionController:
  • KoAbstractAppliactionController is now separate controller inheriting QObject, owned by the KoAbstractApplication-derived class. It contains signals and slots, and should be inherited to customize behaviour and implement abstract interfaces.
  • currentPageChanged() renamed to handleCurrentPageChanged() since it's a placeholder for implementing reaction on page changing
  • documentPageSetupChanged renamed to handleDocumentPageSetupChanged()
  • controller() renamed to canvasController() to avoid silly controller()->controller() expressions
  • controllerWidget() renamed to canvasControllerWidget()
  • doOpenDocument() renamed to openScheduledDocument()
  • removeSheet() renamed to removeCurrentSheet()
  • more setter methods changed to slots
  • thisObject() removed, now 'this' is enough
  • mainWindow() pure virtual added, returns the QWidget of the main window

TODOs

• Move lots of variables from object attributes to stack, this includes QDialog, announce this change to the devs (students?) pointing out the original implementation was not valid
• A lot of functionality that stays in f-office for now, including code for formatting. It's is planned for the KoAbstraction.
• Identify methods that would have better not be pure virtual. But note: providing empty methods instead of pure virtuals makes the usage more error prone for developers. The solution could be to group the API into several aspects: viewer/editor and kword/kpresenter/kspread. Then developers can pick their "taste" for their implementation.
• Document selector with live document preview with kinetic scrolling; like on iWork for iPad but more universal
• Document zoom for touch devices
  • Optimized multi-touch zoom for documents
  • Single-tap zoom feature for documents, for devices lacking multi-touch (which N900 also is)
• Shape scaling and rotationg for touch devices
  • Multi-touch scaling and rotation for shapes
  • Single-tap scaling and rotation for shapes