1. Herbert Breunung
  2. Kephra


Kephra / lib / Kephra / Internals.pod

=head1 Kephra::Internals

If you want to touch the Kephra sources -
this document explains where to find what and how does it all work together.
The terminology is explained in the glossary at the end.
In case you learn better by looking at the good documented code - start at Kephra::API.


In each file is only one package with exactly the same name as the file.

With every directory you go deeper into the tree the modules will get more
specific. Thats why the directory "lib/Kephra" has only the most common
tools and libraries. Other dir:

=over 4

=item * API - API for plugins, most cross module calls, central data structures

=item * App - visuals

=over 4

=item * Bar - container widgets (menu bar, toolbar, tab bar, status bar, etc.)

=item * Editor - editor widget helper

=item * Panel - with sizer assembled visual units (snippet lib, io unit, etc.)

=item * Part - functional units (main part, side panel, etc,)


=item * Config - data

=over 4

=item * Default - built in fall back configs when certain files are in trouble


=item * Document - document properties

=item * Edit - text manipulation functions

=item * Files - all sorts of IO

=item * Plugins - namespace of users extentions


=head2 MODULES

=over 4

=item * Kephra

global vars like version number and the init process:
finding configs, setting dirs, forking to the worker, loading libs, starting app

=item * Kephra::API

- interface to most important functions all modules and plugins should use
- provides also simplified aliases to Kephra::API::* namespaces
- as long as the first version number (see L<Versioning>) does not change,
  no call will be renamed or removed

=item * Kephra::API::Command

Every function the user is able to trigger has an ID and gets called over this API.
In head of every module after package and use and vars are the definitions
which rgister these commands in this data structure.
Its for monitoring, triggers, macros and other introspection.
Also helps to make simple menu and toolbar definitions (are lists of CommandIDs).

=item * Kephra::API::DocumentStash

- Find docs by any attribute or categories.

=item * Kephra::API::Event

- trigger, freeze, thaw, add and remove events or calls attached to them
- covers also internal calls

=item * Kephra::API::GuiBuilder

- transformes wiki syntax => data structure => GUI and back

=item * Kephra::API::KeyMap

- managing the widgets mappings of key combo => CommandID

=item * Kephra::API::Macro

- record, play, store and load macros

=item * Kephra::API::Plugin

- load, reload and unsubscribe plugins

=item * Kephra::API::Sandrum

- vi like shortcut language for triggering commands

=item * Kephra::App

- root object of all GUI
- handles GUI related boot and shutdown sequence
- derived from Wx::App

=item * Kephra::App::Dialog

- all dialogs are called from here

=item * Kephra::App::Editor
=item * Kephra::App::Focus

- keeps track in which widget got to make save way back if needed

=item * Kephra::App::Menu
=item * Kephra::App::PaintBar
=item * Kephra::App::Panel
=item * Kephra::App::Sizer
=item * Kephra::App::Splitter
=item * Kephra::App::Toolbar
=item * Kephra::App::Util

- GUI utilities

=item * Kephra::App::Window

- main window

=item * Kephra::Config
=item * Kephra::Document
=item * Kephra::Edit
=item * Kephra::File
=item * Kephra::Help
=item * Kephra::Log
=item * Kephra::Worker


* Kephra::App::Panel
wrapper around Wx::Panel + Wx::BoxSizer, helps not to deal with with sizers
is a stepping stone to the GCL

* Kephra::App::Window
main frame/window and main layout of the app
holds all the Kephra::App::Part s and Bars

* Kephra::Config
Interface to most not document related internally held data.
We have a much broader understanding of configuration.
Even Icons and localisation belong to it.
Its all data which puts the app in the state it is.

* Kephra::Document
document properties, syntax modes

* Kephra::Edit
text processing

* Kephra::Plugin
Kephra::API::Plugin is the base class for all plugins

=head1 Glossary

=head2 App

everything visible and GUI (Wx) related

=head2 App::Part

visual area dedicated for one purpose, editor is the most prominent,
but ther are also FileBrowser, IOUnit and more

=head2 Editor

one widget for editing text

=head2 Edit

namespace for the actual editing operations

=head2 Panel

area to place widget on, can be under anything, even under each editor
a Kephra::App::Panel is a helper class that manages its sizer
(visibility and ordering of elements)

=head1 Document

=head2  Interdependency Of Core Modules

=head2  Modules vs Objects

=head2  Boot Stages

Just using the fact that when modules are loded (after the fork)
there main code (outside the sub) is run. At this time we create the
basic command list and the definition which module gets which part of
the global config (actual loading happens later).

=head2  Worker Fork