Gedit New Mdi Internals
Documentation of gedit's new_mdi codebase.
This is a draft
TODO... in the meantime read more about the goals of the new_mdi development branch in the Gedit/NewMdi page
Here what I think is one of the most useful things for someone who wants to dive into a big codebase like the one of gedit: a list of which are the most importants source files in gedit with a description of what they do.
it contains the README, TODO etc, it also contains the configure.in script which is required for the build system (and no, if you are not familiar with them, don't get scared by autoconf, automake, etc... you can survive well without knowing them in the details )
data/: it contains some misc files like .desktop files and GConf schemas
gedit/: where the real sources live, more on this below
help/: user docs
pixmaps/: a little bit of artwork
plugins/: sources of the plugins shipped with gedit, each in its subdir (plugins sources are pretty straightforward so I won't go into details for now)
tools/: tools useful for developers, as on now it contains a script to generate a template for writing a plugin in C
lets now concentrate on the gedit/ subdir, which contains the sources of the application.
- entry point
gedit.c: this is the entry point of the program, where the main() function is defined. It takes care of parsing command line options, initializing various subsytems, etc. It also takes care of ensuring that only one instance of gedit is ever running on the system so that memory is shared across all the gedit windows and it's possible to drag a tab from a window to another; this is done by using a bacon-message-connection, in practice the first running instance of gedit acts as a simple server while subsequent invocations of gedit just connect to this server, ask it to create a new window and then exit.
- main classes (the key classes of gedit... these are strongly related to the 'UI elements' listed below, I'm putting in a separate item just to underline their importance):
gedit-app.[ch]: a class representing the application, there is only one instance of this class (singleton)
gedit-window.[ch], gedit-window-private.h, gedit-commands-*.[ch], gedit-ui.h, gedit-ui.xml: a class implementing a gedit window, it takes care of creating all the menus and toolbars and instanciates all the ui elements (notebook, statusbar etc). It has a 'state' reflecting the overall state of the tabs currently open in the window. gedit-window-private.h is in a separate header so that, despite being private, it is accessible from gedit-commands.c. gedit-commands.c implements the callbacks for all the ui actions, it's split in a separate file to make the codebase more manageable. gedit-ui.h and gedit-ui.xml respectively contains the defintion and the xml description of menus and toolbars.
gedit-document.[ch]: it's a class that extends GtkSourceBuffer (and thus GtkTextBuffer) and represents a text file loaded in gedit. Among other things it includes the code to load and to save a file. Note that gedit-document is a "non-GUI" (is this correct??) class, in the sense that it doesn't include anything that is displayed on screen.
gedit-document-loader.[ch] and gedit-document-saver.[ch]: two 'functors' (function objects) internally used by gedit document to load and save a file. They allow this operations to be done in an async manner and take care of hiding all the intricancies of handling remote files through gnome-vfs
- main UI elements (main widgets that form gedit's UI)
gedit-notebook.[ch], gedit-tab.[ch]: this two widgets take care of implementing gedit tabbed interface. They extend a simple GtkNotebook adding many features, as the ability to drag tabs around in the notebook and from a notebook to another. Each gedit-tab contains a GeditView and is caracterized by it's current state.
gedit-statusbar.[ch]: a simple GtkStatusbar subclass implementing our needs (e.g. the current line/col number)
gedit-panel, gedit-side-panel, gedit-bottom-panel: panel to implement side and bottom panes. These panes can hold multiple pages and plugins can add pages too.
- other classes/files:
gedit-encodings, gedit-convert: list supported encodings and utilities to convert between them.
gedit-languages-manager: supported syntax highlightimg languages.
gedit-session.[ch]: session management support. The session is serialized to an xml file and restored on login.
gedit-metadata-manager.[ch]: an utility object which takes care of 'remembering' some properties of opened documents (last searched word, selected highlighting, etc) acros different invocations.
gedit-prefs-manager.[ch], gedit-prefs-manager-app.[ch]: utility functions to retrieve configuration options out of gconf. They also take care of listening to GConf notifications.
gedit-recent: recent files data structure
gedit-utils.[ch]: misc utility functions
- gedit-file-chooser-dialog.[ch]: specialization of gtkfilechooser implementing some of the gedit's specific features
dialogs/*: this subdir contains sources for various dialogs that gedit shows (for instance the preference dialog etc). Each dialog is pretty much standalone and the sources should be fairly simple once you are familiar with gtk. Many of the dialogs make use of libglade to load the GUI from the corresponding .glade file.
- widgets (these are generic widgets, not specific to gedit)
- Plugin Support:
gedit-plugins-engine.[ch]: detect, load and manage available plugins
gedit-module.[ch]: support for shared objects (C plugins are shared objects)
gedit-plugin.[ch]: base classs for plugins
gedit-plugi-manager.[ch]: is a widget containing a list of the plugins, it's used in the prefs dialog.
cut & paste code
recent-files/*: libegg's recent files implementation
bacon-message-connection.[ch]: used to ensure a unique instance is running (currently works by wrapping a UNIX socket)
Design, implementation and UI principles
[In random order for now]
- All the code should be factored in Classes (GObjects) in a clean OO design. All apis available to plugins should be easily bindable to other languages.
- The running instance of gedit is a singleton to allow memory to be shared and windows to interact
Despite of the above, to the user all the windows should look independent: in particular a dialog should never be modal to the whole application, but just to its parent window. If possible modal dialogs should be avoided at all.
Operations in a tab inside a window should not affect other tabs in the same window (e.g. MessageAreas instead of dialogs)
GeditDocument and the realtive objects handling file loading/saving are independent from the GUI.
- File handling operations are handled asynchrously (well, some for the local files are sync for performance reason, but the api hides this detail)
The plugin system tries to expose a simple yet powerful api to extensions developers. Plugins should extend the GeditPlugin class and implements its methods. The plugin have full access to text manypulation since they can get the GeditDocument object which in turns is a GtkTextBuffer. The plugin system is easily bindable to other languages, in particular python.
- ... (more)