Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

[r14318]: notes / jEdit Architecture Document - The Docking Framework.html Maximize Restore History

Download this file

jEdit Architecture Document - The Docking Framework.html    82 lines (82 with data), 9.7 kB

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>jEdit Architecture Document - The Docking Framework</title></head>
<body><h1><a class="mozTocH1" name="mozTocId974439"></a>jEdit Architecture Document</h1><h2><a class="mozTocH2" name="mozTocId873227"></a>The Docking Framework (DockableWindowManager)</h2><ol id="mozToc"><!--mozToc h1 1 h2 2 h3 3 h4 4 h5 5 h6 6--><li><a href="#mozTocId974439">jEdit Architecture Document</a><ol><li><a href="#mozTocId873227">The Docking Framework (DockableWindowManager)</a><ol><li><a href="#mozTocId461306">Introduction</a></li><li><a href="#mozTocId486556">The roles of the docking framework</a></li><li><a href="#mozTocId843111">The docking framework interface</a></li><li><a href="#mozTocId856380">Providing an alternative docking framework</a></li></ol></li></ol></li></ol><h3><a class="mozTocH3" name="mozTocId461306"></a>Introduction</h3>Let's
begin by describing the various elements in a jEdit window. The names
in parentheses are the names of the classes implementing these elements.<br><ul><li>A jEdit window is called a <strong>view</strong> (View).</li><li>The area of the view where the text of a buffer is shown and edited is called a <strong>text area</strong> (JEditTextArea).</li><li>Each text area is wrapped by an <strong>edit pane</strong> (EditPane). An edit pane manages a set of buffers, and may optionally contain a <strong>buffer switcher</strong>,
which is a combo-box for selecting the buffer to be edited. When a
buffer is selected in the combo-box, the edit pane sets the text area
to edit the selected buffer.</li><li>Edit
panes can be split vertically or horizontally; there are buttons for
this on the tool bar. Splitting an edit pane causes its screen area to
be split between itself and the new edit pane, with a draggable
splitter separating them.The arrangement of split edit panes inside a view is called the <strong>split configuration</strong> of the view.</li><li>The edit panes inside a view are all children of a <strong>center panel</strong> container. Dockable windows are always placed around this center panel.</li><li>The
<strong>dockable window manager</strong> (DockableWindowManager)&nbsp;
is the part of the view that contains the
center panel, the dockable windows, the action bar (when visible) and
the search bar (when visible). Each view has its own instance of a
dockable window manager.</li><ul><li>Depending
on the option "Alternate tool bar placement", the tool bars can be
children of the dockable window manager, in which case they have and
same width as the edit center panel, or they can bechildren of the view, in which case they use the entire view width. <br></li></ul><li>The
view itself contains the window frame (title bar, system buttons for
close/minimize/maximize..., border), the menu bar, the status bar, the
dockable window manager, and optionally the tool bars (depending on the
option "Alternate tool bar placement").</li></ul>Did
I forget anything? If so, excuse me. In any case, the purpose is to
show the design of the docking framework, and the elements described
above are sufficient for that purpose.<br><h3><a class="mozTocH3" name="mozTocId486556"></a>The roles of the docking framework</h3>The
main role of the docking framework, as its name implies, is to provide
a common docking framework for all sorts of windows that can be used in
jEdit. The common framework enables each plugin-provided window (and
also several core windows) to be docked inside the view, or be undocked
(floating) outside the view. The docking framework saves the dockable
window layout (a.k.a. "perspective") to disk when jEdit exits, and
reloads it from disk when jEdit is restarted. The docking framework
supports "named perspectives" - saving and loading a dockable window
layout to and from the disk under a user-defined name.<h4>The built-in docking framework</h4>Historically, jEdit had a built-in docking
framework, which was quite simplistic compared to modern docking
frameworks, but perhaps advanced for the time it was designed. The
built-in docking framework was implemented by a non-extensible class,
named&nbsp;DockableWindowManager. With the introduction of a pluggable
docking framework, some refactoring was done in the code, and now
DockableWindowManager is an abstract class, which serves as a base
class for any docking framework, providing the windowing interface for
the core and the plugins. The built-in docking framework has been
refactored into a concrete&nbsp; implementation of the
DockableWindowManager, named DockableWindowManagerImpl. The built-in
docking framework provides the following features:<br><ul><li>Dockable
windows can be docked inside the view in any of four docking positions
around the center panel - top, bottom, right, left.</li><ul><li>The docking positions of the dockable windows are specified using properties, and are persistent in the jEdit properties file.</li><li>The docking positions can be changed from the GUI using:</li><ul><li>The "Docking" option pane in the "Global Options" dialog</li><li>The context menu available for each docking window.</li></ul></ul><li>Each docking position can have at most one dockable window visible at a time. </li><li>Multiple
dockable windows can be docked in the same position. Each docking
position contains a "button bar", with a button for each window docked
in it, named after the window. The buttons are used to show or hide
their respective windows.</li><li>Dockable windows can be "floated" - undocked from the view, have their own top-level window (JFrame).</li><li>Draggable splitters allow resizing the dockable windows on the expense of the center panel (and vice versa).</li><li>While the docking positions of each dockable window are
specified using properties, the docking layout is persistent in the
perspective.xml file - specifying the location of the splitters, the
name of the visible window in each position, and so on.</li><li>Predefined
actions exist for various docking operations, e.g. toggling or floating
each dockable window, closing docking positions, etc.<span style="font-weight: bold;"></span></li></ul>Since
the pluggable docking framework was introduced into jEdit&nbsp;when
jEdit was already very mature and had lots of plugins, the interface of
the abstract base class DockableWindowManager was derived from the
built-in docking framework, in order to eliminate the need in changing
the massive usage of this interface (backward-compatibility).<br><h4>The pluggable docking framework</h4>The
abstract base class DockableWindowManager defines the roles of the
docking framework. This includes all the roles that the built-in
docking framework used to have, and a few additional roles.<h3><a class="mozTocH3" name="mozTocId843111"></a>The docking framework interface</h3>Each view has its own instance of DockableWindowManager, which can be retrieved using:<br>&nbsp;&nbsp;&nbsp; view.getDockableWindowManager();<br>This
is also available for BeanShell code (e.g. in actions.xml) because
'view' is a predefined variable for BeanShell code in jEdit.<br>This section describes the public interface of the DockableWindowManager:<br><br>The docking framework (DockableWindowManager) provides API methods for:<br><ul><li>Showing/Hiding/Toggling dockable windows:<br>showDockableWindow(String name) / hideDockableWindow(String name) / toggleDockableWindow(String name)</li><li>Docking/Floating dockable windows</li><ul><li>This is done by means of setting the docking position properties and sending a PropertiesChanged edit bus message.<br>jEdit.setProperty(name + ".dock-position", DockableWindowManager.BOTTOM);<br>jEdit.propertiesChanged();</li></ul><li>Closing (hiding) a docking position<br>getLeftDockingArea().show(null)</li><li>Closing (removing) dockable windows</li><ul><li>Also done by means of setting the dock-position to "float", and sending a PropertiesChanged edit bus message.</li></ul><li>Retrieving the dockable window component by name<br>getDockableWindow(String name)<br>This
is used by many plugins to find their dockable instance that is docked
in a view and invoke methods in it. This method returns a JComponent,
which can be cast to the right type in order to call methods of that
dockable type (in both BeanShell and Java).</li><li>Getting/Setting dockable window titles</li><li>Checking if a dockable window is docked</li></ul><h3><a class="mozTocH3" name="mozTocId856380"></a>Providing an alternative docking framework</h3>Plugins can now provide their own implementation of a docking framework
for jEdit. The first plugin to provide a docking framework is
MyDoggyPlugin, which uses the modern docking framework named MyDoggy to
manage the dockable windows in jEdit.<br><br>To
provide an alternative docking framework, a plugin needs to create a
concrete class that inherits DockableWindowManager, and create a
"Provider" that creates objects of that concrete class whenever asked
to (one object is needed for each view). To introduce its docking
framework to jEdit, it defines a service like the following:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;SERVICE CLASS="org.gjt.sp.jedit.gui.DockingFrameworkProvider" NAME="MyDoggy"&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; new myDoggy.Provider()<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;/SERVICE&gt;<br>The
service introduces the docking framework provider class, which is an
implementation of the DockingFrameworkProvider interface.<br></body></html>