Calligra/Libs/KoAbstraction

From KDE Community Wiki

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

Changelog:

  • 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


Later TODO:

  • move lots of variables from attributed to stack, this includes QDialog, announce this change to the devs (students?) pointing out the original implementation was not valid

TODOs

  • 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