WIP of documenting the Dockable interface. Attempting to better learn…

… Writerside and its special feature set.

Writerside/m.tree

@@ -8,17 +8,18 @@
 
     <toc-element topic="starter-topic.md"/>
     <toc-element topic="User-Facing-Features.md"/>
-    <toc-element topic="Hello-World.md"/>
     <toc-element topic="Modern-Docking-API.md">
+        <toc-element topic="Dockable-Properties.md"/>
+        <toc-element topic="Hello-World.md"/>
+        <toc-element topic="Dockable-Interface.md"/>
+        <toc-element topic="Docking-Programatically.md"/>
+        <toc-element topic="Menu-Items.md"/>
         <toc-element topic="Customization-Points.md"/>
         <toc-element topic="Exceptions.md"/>
         <toc-element topic="Events.md"/>
         <toc-element topic="Working-With-Layouts.md"/>
-        <toc-element topic="Docking-Programatically.md"/>
-        <toc-element topic="Dockable-Interface.md"/>
         <toc-element topic="Persistence.md"/>
         <toc-element topic="Look-and-Feel.md"/>
-        <toc-element topic="Menu-Items.md"/>
     </toc-element>
     <toc-element topic="Modern-Docking-UI.md"/>
 </instance-profile>

Writerside/topics/Dockable-Interface.md

@@ -1,3 +1,84 @@
 # Dockable Interface
 
-Start typing here...
+The `Dockable` interface is required to be implemented by the application on any component it wishes to dock.
+Typically, this interface is implemented by a class that extends from `JPanel`.
+
+The `Dockable` interface has a minimum subset of methods that must be implemented by the application and a set of methods that are optional.
+These optional methods provide extra customization points for the application per dockable.
+
+<warning>
+The return values for the `Dockable` interface methods should be constant after the creation of the dockable component.
+Certain methods can be dynamic and the framework provides methods to update their values within the framework. Any method that doesn't specify such
+a method can lead to unexpected behavior if changed after the dockable component is created.
+
+Generally, if you wish to modify the return values after creating the dockable component, do so while the dockable is not docked. This can be checked with <b>Docking.isDocked</b>.
+</warning>
+
+## Mandatory Methods
+
+These two methods do not provide default implementations in the interface and must be implemented by the application.
+
+### getPersistentID
+
+`getPersistentID` provides a unique ID that the framework can use to refer to the dockable. This is the main piece of information that the application
+and the framework share in order to refer to specific dockables.
+
+### getTabText
+
+`getTabText` provides the text that should be displayed on a tab when this dockable is in a `JTabbedPane`.
+
+<note>If the text displayed on the tab ever changes, the application must call <b>Docking.updateTabText</b> with the dockables persistentID to force the framework to update the text. This should be done anytime the text is changed, just in case the dockable is displaying in a JTabbedPane</note>
+
+## Optional Methods
+
+All the following methods are provided to the application with a default. This means the application only needs to implement the methods
+if it wishes to change the default.
+
+### getType
+
+<!-- This one is a bit weird and complicated. It's really just a hack, and we should add something better. -->
+
+### getTabTooltip
+
+### getIcon
+
+Used by the framework to get the icon for the dockable to use in a `JTabbedPane` tab.
+
+### isFloatingAllowed
+
+Allows the application to specify whether a dockable can be dragged out of its current window and floated on its own as a new window.
+
+### isLimitedToRoot
+<procedure title="isLimitedToRoot" id="isLimitedToRoot">
+   <p>Before adding something, create it.</p>
+   <step>Do this.</step>
+   <step>Do that.</step>
+   <p>Default value is <code>false</code></p>
+</procedure>
+Allows the application to limit the dockable to the window it was initially docked in.
+
+### getStyle
+
+### getPinningStyle
+
+to be renamed
+
+### isClosable
+
+### isPinningAllowed
+
+### isMinMaxAllowed
+
+### isWrappableInScrollpane
+
+### getHasMoreOptions
+
+### getTabPosition
+
+### addMoreOptions
+
+### createHeaderUI
+
+### updateProperties
+
+<!-- todo: should updateProperties be mandatory? it'll probably be easy to forget if you start adding properties to dockables -->

Writerside/topics/Dockable-Properties.md

@@ -0,0 +1,3 @@
+# Dockable Properties
+
+Start typing here...

Writerside/topics/Persistence.md

@@ -1,3 +1,8 @@
 # Persistence
 
-Start typing here...
+defaults to off
+
+turn on with setPersist
+
+setPersistFile to customize what file the framework persists to
+

Writerside/topics/User-Facing-Features.md

@@ -1,5 +1,12 @@
 # User Facing Features
 
+Users of your application will interact with several UI components provided by Modern Docking.
+The framework is built around using Java Swing's `JTabbedPane` and `JSplitPane` to provide the docking layouts.
+The positioning of the applications dockable components within these `JTabbedPane`s and `JSplitPane`s is done by dragging the dockables.
+When the dockable is being dragged it will float about the window of the application and show Docking Handles and Docking Regions.
+Docking Handles allow the user to place the dockable precisely where they want it and Docking Regions provide extra visual feedback of this action.
+Docking Regions are also a quick way to "snap" dockables into place without needing to precisely drag to a Docking Handle.
+
 ## Using Docking Handles to Dock
 When dragging a dockable hovering over another dockable will display docking handles in the center of the dockable.
 These handles provide easy access to dock to the North, South, East and West regions.

Writerside/topics/starter-topic.md

@@ -1,8 +1,14 @@
-# About ModernDocking
+# Welcome to Modern Docking
+
+Welcome! This documentation explains both the user facing features of Modern Docking and it's API.
+
+Modern Docking provides a rich set of features to enhance any Java Swing User Interface.
+
 
 <!--Writerside adds this topic when you create a new documentation project.
 You can use it as a sandbox to play with Writerside features, and remove it from the TOC when you don't need it anymore.-->
 
+<!--
 ## Add new topics
 You can create empty topics, or choose a template for different types of content that contains some boilerplate structure to help you get started:
 
@@ -75,4 +81,6 @@ You can also always send an email to [writerside@jetbrains.com](mailto:writersid
         <a href="https://plugins.jetbrains.com/plugin/20158-writerside/docs/local-build.html">Build and publish</a>
         <a href="https://plugins.jetbrains.com/plugin/20158-writerside/docs/configure-search.html">Configure Search</a>
     </category>
-</seealso>
+</seealso>
+
+-->