Devel Manual:The New Library from the Programmer Point of View
From KLFWiki
TODO: this article needs some clean-up and restructuring, it was written too quickly.
Contents |
Intro
Very basically: KLFLibResourceEngine is the base class interface from which engines (eg. KLFLibDBEngine for SQLITE support, KLFLibLegacyEngine for legacy .klf support) will be derived.
To create a new engine, derive KLFLibResourceEngine and reimplement all the virtual functions to fit your needs, eg. entry(...) to provide library entries to the caller, resourceProperty() to provide information about resource properties, etc.
At the beginning, you may derive from KLFLibSimpleResourceEngine, which requires less work. In that class some functions are reimplemented to call the others, at the cost of some optimization... see API docs of that class.
Views
Resource engines that scrupulously follow the KLFLibResourceEngine API can be shown without problem in a KLFLibDefaultView (which can handle category trees, lists, and icon views). You can also derive your own class from KLFAbstractLibView to implement your own view (which can be about anything that displays to a screen). If your view makes full use of the KLFLibEngineResource API, then you can display any resource type; however you can also specialize and use your own API to communicate only with your special engine type, and refuse to display other engine types.
URLs
Internally, resource engine instances are identified using URLs. The scheme of the URL (eg. 'http' in regular URLs) defines the type of resource (eg. "klf+sqlite", "klf+legacy"). A given scheme is handled by a specific resource engine type, however it is possible for an engine implementation to support more than one scheme. Schemes are used to determine which factory to invoke when opening resources. The host, username/password, path and fragment(=anchor) of the URL may be used freely by the engine to identify the data source (for example, KLFLibDBEngine and KLFLibLegacyEngine leave host/user/pass/fragment empty and use path for the file path). There are some query items, however, that are standard, see docs for KLFLibResourceEngine (readonly, default sub-resource).
Factories
Engines are created in factories, which derive from KLFLibEngineFactory, which have to be instantiated once at the beginning of the program (built-in engines: main(), add-on engines: in the plugin's init function).
Views are also created in factories, in a very similar fashion.
Opening/Creating Resource Instances
To allow for the user to open your resource, you will need to specify a widget that is capable of prompting the user to select the resource data source. For example, you could rely on the "LocalFile" widget (that is internally created by the KLFLibBasicWidgetFactory), or you could write your own widget, and respective widget factory, to prompt the user to select the data source to open.
The APIs: Devel Manual:APIs. See especially classes KLFLib* in klfapp library.
