Herbert Breunung avatar Herbert Breunung committed ccc6be2

cover most API internals

Comments (0)

Files changed (1)

lib/Kephra/Internals.pod

 
 If you want to touch the Kephra sources -
 this document explains where to find what and how does it all work together.
-In case you learn better by code - start at Kephra::API.
+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.
 
 
 
 
 =over 4
 
-* API - API for plugins, most cross module calls, central data structures
+=item * API - API for plugins, most cross module calls, central data structures
 
-* App - visuals
+=item * App - visuals
 
 =over 4
 
-* Bar - container widgets (menu bar, toolbar, tab bar, status bar, etc.)
+=item * Bar - container widgets (menu bar, toolbar, tab bar, status bar, etc.)
 
-* Editor - editor widget helper
+=item * Editor - editor widget helper
 
-* Panel - with sizer assembled visual units (snippet lib, io unit, etc.)
+=item * Panel - with sizer assembled visual units (snippet lib, io unit, etc.)
 
-* Part - functional units (main part, side panel, etc,)
+=item * Part - functional units (main part, side panel, etc,)
 
 =back
 
-* Config - data
+=item * Config - data
 
 =over 4
 
-* Default - built in fall back configs when certain files are in trouble
+=item * Default - built in fall back configs when certain files are in trouble
 
 =back
 
-* Document - document properties
+=item * Document - document properties
 
-* Edit - text manipulation functions
+=item * Edit - text manipulation functions
 
-* Files - all sorts of IO
+=item * Files - all sorts of IO
 
-* Plugins - namespace of users extentions
-
+=item * Plugins - namespace of users extentions
 
 =back
 
 
 =head2 MODULES
 
-=head3 Kephra
-
-contains just the init process:
-setting dirs, loading libs, finding configs, making worker fork, starting app
-
-=head4 Kephra::API
-
-interface to important internal functions all modules and plugins should use
-
-The modules in the Kephra::API::* namespace are services for a more sophisticated
-communication between the modules who do the real work.
-
-
-
-
-
-
-If you want to leave the recommended ways as proposed by the API and call
-functions or data directly (or even better you want to help to develope Kephra) ...
-here is an overview to the Kephra namespace organisation.
-
-Please note that the shorter the name is (shorter namespace chain),
-the more internal and general purpose the module is owning that name.
-For instance Kephra::File::Local serves as specialized subtask of Kephra::File.
-
-=head3 API
-
-The module Kephra::API is the best starting point to understand the inner workings.
-That's actually one design goal and purpose of this file, because it gives an
-overview to the most important functions and values and there origin. From there
-you can step to the other major interfaces that are included with C<use> in the
-first lines.
-
-But more vitally it decouples many cross module calls and allows to change things
-under the hood during smaller release cycles. As long as the first version number
-(see L<Versioning>) does not change, nothing will be renamed or removed from the API.
-
-=head3 Explained In Detail
-
-
-
-=head4 Kephra::API::Command
-
-Also sort of API but more complex. Contains every call the user is able to make.
-Needed to protocol each call for monitoring, macros and other introspection
-based functions. Also helps to make simple menu and toolbar definitions.
-They just need to be a list of CommandIDs.
-
-
-=head4 Kephra::API::DocumentStash
-
-Kephra::API::Event
-
-
-=head4 Kephra::API::KeyMap
-
-handles the mapping from key kommbo to the command it triggeres for any 
-App::Dialog and App::Part
-
-
-
-* Kephra::App
-
-module that handles boot and shutdown sequence
-namespace of all the Wx-GUI-related stuff, all visible parts
-Kephra::App::* contains the more lower level stuff and 
-Kephra::App::*::* the higher level components
-
-* Kephra::App::Dialog
-
-all dialogs are called from here
-
-* Kephra::App::Part
-
-namespace of the great visual sections of the app
-
-=head2 Kephra::App::Focus
-
-keeps track in which App::Part the Focus wanders to make save way back if needed
-
 =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
+
+
+=back
+
+
 * 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
-
-plugin namespace
 Kephra::API::Plugin is the base class for all plugins
 
-=back
+
 
 =head1 Glossary
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.