Public C++ API

This article is part of the Scripts series.

Public C++ API

Scribus's internal interfaces are in constant flux as code is improved and refactored. They're also sometimes complex, hard to use, and often underdocumented. Often performance takes priority over easy understanding for the new user, and some have a considerable amount of historical cruft.

For all these reasons, we would benefit signifiantly from providing a new public C++ API to Scribus's functionality. This would be a collection of wrappers around the core code that:

• Hide internal-only structure and complexity
• Abstracted some functionality into simpler, but perhaps slower, interfaces
• Handle ownership issues related to exposing the API to refcounting or GC'd languages with:
  • Handles or proxy objects for important internal objects
  • Factory functions rather than direct ctor use
• Hides direct use of pointers to structures behind indexes into structures, names, proxy objects, or other abstractions.
• Logically groups functionality, often consolidating a number of objects into one
  • Needs interfaces to:
    • Text system
    • Pages
    • PageItems
    • Document manipulation (sizes, export, page management)
    • Application-wide functions (open doc etc)
    • GUI (menus, toolbars, etc)
  • See current scripter for an outline of some of the needed functionality.
• Provides important hooks for extending the GUI (exposes menu manager, key toolbars, action manager, etc)
• Exposes signals that can be connected to when a script/plugin wants to be informed of important events

We need to start, I think, by (a) looking at how others have done it (especially KDE apps supporting Kross), and (b) writing down everything we want the plug-in API to enable people to do. The existing scripter will serve as the beginnings of a guide to what's needed.

Once we know what we want to initially expose, we collect functionality into logical groups or entities based on what it applies to or acts on (works on the entire app vs works on the document vs works on a text pageitem, etc). That gives the beginnings of the structure we'd need the API to have as far as users of it are concerned.

If done well, this public API may let us actually hide much of the current innards entirely from scripts and plug-ins. They should see only the wrapper API headers, and should need to link only to wrapper API symbols. We should be able to reduce the size of the exported symbol table (improving binary size and link times), more easily expose functionality to new languages like QtScript, make it easier to write highly functional plug-ins and scripts, etc. Handily, we could also provide a more _stable_ interface to plug-ins and scripts, so fewer core changes would require incompatible changes in scripts or plug-ins.