Gedit New Mdi Internals

Documentation of gedit's new_mdi codebase.

This is a draft

Introduction

TODO... in the meantime read more about the goals of the new_mdi development branch in the Gedit/NewMdi page

File Map

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.

Toplevel dir:

• 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)

• po/: translations

• 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-view.[ch]: a subclass of GtkSourceView (which in turns subclasses GtkTextView) which takes care of displaying a document

  • 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

• dialogs:
  • 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)

  • gedit-tooltips.[ch]: like GtkTooltips, but allows bold messages in the tip

  • gedit-message-area.[ch]: a widget used to show a message (error, waring, etc), similar to GtkMessageDialog, but instead of beeing a standalone dialog it can be packed into a notebook tab or any other container.

• 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)