cornercorner
FeaturesPluginsDocs & SupportCommunityPartners

Editor XML Settings - User's View

Version: 0.4 DRAFT
Author: Martin Roskanin, Sun Microsystems/NetBeans
Abstract:
This document describes the storing of the editor settings to XML files, global structure and the placing of the files, DTDs of XML option files and simple examples. Versioning problem is also mentioned.
Document History: available in CVS
Contents:
1. Overview
2. The placing of editor settings XML files
3. The splitting of the current options
4. DTDs and examples of XML files
4.1 Fonts and Colors
4.2 Key Bindings
4.3 Abbreviations
4.4 Macros
4.5 Other Settings
5. Editor popup actions
6. Installation of other modules options
7. User interface
8. Versioning


1. Overview

At the present time all editor settings are serialized to stream during the closing of the IDE. The serialization brings a lot of problems. For example there is difficult handling with the different versions of the settings. The settings are stored in common IDE serialization file in human unreadable format and cannot be well accessed by others to change the option properties. And as it seems, the biggest problem is the performance gap, because of the initialization of all editor options during deserialization in the startup of the IDE. According to these disadvantages new solution of editor option storing should be created. The storing of the editor options to XML file satisfies all needs. Editor settings will be splitted to more parts, more precisely XML files and that's why the version controlling will be more comfortable. Big advantage of XML file is that options will be stored in human readable format. And we can avoid deserialization and startup options initialization performance gap.

2. The placing of editor settings XML files

Editor settings XML files should be stored in accessible place to provide the possibility of the modification of the settings to the other modules. For example the XML files will be accessed and modified by UI, especially because of the feature The UI Faces -- global UI Settings. The files will use XML layers structure and their place will be in the following folders: 
Default system
    - Editors
            - text
                - plain
                - html
                - x-java
                - x-propeties
                - x-jsp
                - ...
                - base
Each MIME type will contain specific XML option files. For example x-java MIME type will contain:
  1. Macros
  2. Abbreviations
  3. Popup
  4. fontsColors.xml
  5. abbreviations.xml
  6. macros.xml
  7. keybindings.xml
  8. properties.xml
Two folders - Macros and Abbreviations - will contain the additional (macro|abbreviation) related xml files and will provide support for extension of default macro|abbrevs file. Files in these folders will be read-only. All user changes will be saved to default macros.xml or abbreviations.xml file in his user layer. For example one can provide defined macros in his macro.xml and other can simply download and copy the file to Macros directory. This way users can share their macros or abbreviations. The structure of the particular XML files is described in the section DTDs


3. The splitting of the current options

The current options should be splitted to several minor parts, that will correspond with appropriate XML files. The proposed structure is following:

fontsColors.xml
  1. Colors and Fonts (default, line number, java keyword ... )
  2. Insertion point color
  3. Overwrite caret color
  4. Text limit line color
abbreviations.xml Abbreviations
macros.xml Macros
keybindings.xml Key Bindings
properties.xml
  1. Auto popup completion window
  2. Delay of completion window auto popup
  3. Line numbers
  4. Tab size
  5. Display text limit line
  6. Highlight caret row
  7. Highlight matching bracket
  8. Insertion point
  9. Insertion point blinking rate
  10. Italic insertion point
  11. Italic overwrite caret
  12. Line height correction
  13. Line number margin
  14. Margin
  15. Overwrite caret
  16. Scroll find insets
  17. Scroll jump insets
  18. Status bar caret delay
  19. Status bar visible
  20. Text limit character count



4. DTDs and examples of XML files

4.1. Fonts and colors

Element fontcolor will have attribute syntaxName that will be REQUIRED. Attributes foreColor and bgColor are declared as IMPLIED. So in the case they will be missing then foreColor/bgColor attributes will be treated as 'inherit' and missing font element as well.

fontsColors.xml
DTD XML example
<!ELEMENT fontscolors (fontcolor*, elementcolor*)>

<!ELEMENT fontcolor (font?)>
<!ATTLIST fontcolor
syntaxName CDATA #REQUIRED
foreColor CDATA #IMPLIED
bgColor CDATA #IMPLIED
>

<!ELEMENT font EMPTY>
<!ATTLIST font
name CDATA #IMPLIED
size CDATA #IMPLIED
style CDATA #IMPLIED>
>

<!ELEMENT elementcolor EMPTY>
<!ATTLIST elementcolor
name CDATA #REQUIRED
color CDATA #REQUIRED
>
 <fontscolors>
<fontcolor
syntaxName='Default'
foreColor='#000000'
bgColor='#FFFFFF'
>
<font
name='Monospaced'
size='12'
style='Plain'
/>
</fontcolor>

<elementcolor
name='insertion-point'
color='#000000'
/>

<elementcolor
name='overwrite-caret'
color='#000000'
/>

<elementcolor
name='text-limit'
color='#FFEBEB'
/>
</fontscolors>



4.2. Key Bindings

keybindings.xml
DTD XML example
<!ELEMENT bindings (bind*)>

<!ELEMENT bind EMPTY>
<!ATTLIST bind
key CDATA #REQUIRED
remove (true|false) "false"
actionName CDATA #IMPLIED
>
 <bindings>

<bind actionName='beep' key='CS-L$Q' />


<!-- deleted keybinding -->
<bind
key='CS-L'
remove='true'
/>
</bindings>



4.3. Abbreviations

abbreviations.xml
DTD XML example
<!ELEMENT abbrevs (abbrev*)>

<!ELEMENT abbrev (#PCDATA)>
<!ATTLIST abbrev
key CDATA #REQUIRED
remove (true|false) "false"
action CDATA #IMPLIED
>
 <abbrevs >
<!-- fire action using abbrevs-->
<abbrev
key='dbg'
action='abbrev-debug-line'
/>

<abbrev key='tds' >
Thread.dumpStack();
</abbrev>

<!-- deleting 'default' abbreviation -->
<abbrev
key='de'
remove='true'
/>
</abbrevs>



4.4. Macros

macros.xml
DTD XML example
<!ELEMENT macros (macro*)>

<!ELEMENT macro (#PCDATA)>
<!ATTLIST macro
name CDATA #REQUIRED
remove (true|false) "false"
>
 <macros >
<macro name='quote-word'>
caret-begin-word "\"" caret-end-word "\""
</macro>

<!-- deleting 'debug-var' macro -->
<macro
name='debug-var'
remove='true'
/>
</macros>



4.5. Other Settings

properties.xml
DTD XML example
<!ELEMENT properties (property*)>

<!ELEMENT property EMPTY>
<!ATTLIST property
name CDATA #REQUIRED
class CDATA #REQUIRED
value CDATA #REQUIRED
>
 <properties >
<property name='tab-size' class='java.lang.Integer' value='9' />
<property name='line-number-margin' class='java.awt.Insets' value='0,3,0,5' />

</properties>





5. Editor popup actions

(will be implemented in NetBeans 3.4)

There should be a directory Popup in each MIME-specific folder for registering the actions for MIME specific kit and global (default) Popup folder for registering the global actions, common for all kits, like Cut, Copy, Paste ...
For example for x-java the folder will look like Editors/text/x-java/Popup/ and global folder Editors/text/base/Popup/
Instances of the registered actions or registered editor action names could be used to construct the popup menu in the EditorKit. Actions can be sorted and arranged via folder attributes. In such way other modules could cooperate on construction of editor's menu.

Example of registration of the action:
(Actions will be displayed in the following order: goto-source/Separator/CompileAction) 

    <folder name="Editors">
      <folder name="text">
        <folder name="x-java">
          <folder name="Popup">

            <file name="goto-source"/>
            <attr name="goto-source/Separator1[javax-swing-JSeparator].instance" boolvalue="true"/>

            <file name="Separator1[javax-swing-JSeparator].instance"/>
            <attr name="Separator1[javax-swing-JSeparator].instance/org-openide-actions-CompileAction.instance"
                boolvalue="true"/>

            <file name="org-openide-actions-CompileAction.instance"/>

            .
            .
            .

          </file>
        </folder>
      </folder>
    </folder>



6. Installation of other modules options

Each module can install its option to Editor Settings via XML Layer. Initializing the option via ModuleInstall is deprecated.

All options instances are stored in content type folder in the file Settings.settings.

Installing the option via XML Layer:
(Example of editor's options installation) 

    <folder name="Editors">
        <folder name="text">
            <folder name="x-java">
                <file name="Settings.settings" url="JavaOptions.settings"/>
            </folder>
            <folder name="html">
                <file name="Settings.settings" url="HTMLOptions.settings"/>
            </folder>
            <folder name="plain">
                <file name="Settings.settings" url="PlainOptions.settings"/>
            </folder>
         </folder>
     </folder>
Example of HTMLOptions.settings: 
<?xml version="1.0"?>
<!DOCTYPE settings PUBLIC "-//NetBeans//DTD Session settings 1.0//EN" 
    "http://www.netbeans.org/dtds/sessionsettings-1_0.dtd">
<settings version="1.0">
    <module name="org.netbeans.modules.editor/2"/>
    <instanceof class="java.io.Externalizable"/>
    <instanceof class="org.openide.util.SharedClassObject"/>
    <instanceof class="java.beans.beancontext.BeanContextProxy"/>
    <instanceof class="java.io.Serializable"/>
    <instanceof class="org.openide.options.SystemOption"/>
    <instanceof class="org.netbeans.modules.editor.options.OptionSupport"/>
    <instanceof class="org.netbeans.modules.editor.options.BaseOptions"/>
    <instance class="org.netbeans.modules.editor.options.HTMLOptions"/>
</settings>
If your module use default maps for abbreviations, macros or keybindings you have to provide this default values in the Defaults folder for each editor. It is done via XML Layers too. The properties have to be saved in XML structure in accordance with appropriate DTD. You can find a utility for creating the proper XML file in the class org.netbeans.modules.editor.options.OptionUtilities - static methods:
  1. public static void printDefaultKeyBindings(List list, FileObject file)
  2. public static void printDefaultMacros(Map map, FileObject file)
  3. public static void printDefaultAbbrevs(Map map, FileObject file)


Example of installation of default values for java editor: 
    <folder name="Editors">
      <folder name="text">

        <folder name="x-java">
          <folder name="Defaults">
            <file name="abbreviations.xml" url="XMLs/DefaultAbbrevs.xml"/>
            <file name="macros.xml" url="XMLs/DefaultMacros.xml"/>
            <file name="keybindings.xml" url="XMLs/DefaultKeyBindings.xml"/>
          </folder>
        </folder>

        <folder name="base">
          <folder name="Defaults">
            <file name="keybindings.xml" 
                url="XMLs/DefaultGlobalKeyBindings.xml"/>
          </folder>
        </folder>

     </folder>
   </folder>
Note:
Make sure that the kitClass of your module implements the method public String getContentType()

Then you will need to remove deprecated option installation from ModuleInstall subClass of your module.


The editor XML options provides the storing of all known properties such as:
  1. abbreviations
  2. keybindings
  3. macros
  4. coloring
  5. other properties, expert properties
As for other and expert properties, only standard properties types are supported.

Namely:
  1. java.lang.Boolean
  2. java.lang.Integer
  3. java.lang.Float
  4. java.awt.Insets
  5. java.awt.Color
  6. java.lang.String
If your properties are other types, then you should to create your own XML processor. It should extend org.netbeans.modules.editor.options.MIMEProcessor. Please look at implementation of the other MIMEProcessors in org.netbeans.modules.editor.options package such as AbbrevsMIMEProcessor, FontsColorsMIMEProcessor, MacrosMIMEProcessor ... and their associated MIMEOptionFiles AbbrevsMIMEOptionFile, FontsColorsMIMEOptionFile, ...



7. User interface

User interface will remain the same as it is now as for basic editor settings. As for UI settings as fonts, colors or keybindings, they will be accessible from the UI Faces -- global UI Settings too. Edditor settings will be available in Tools/Options/Editor Settings folder.



8. Versioning

Versioning will use the advantages of the storing only diff-ed settings.



Companion
Projects: 		MySQL Database Server   GlassFish Community: an Open Source Application Server   Open Solaris  Open JDK: an Open SourceJDK   Mobile & Embedded Community     Sponsored by 
Sponsored by Sun Microsystems