Skip navigation links
org.netbeans.modules.editor.guards/1 1.37.1

Editor Guarded Sections
Official

See: Description

Editor Guarded Sections 
Package Description
org.netbeans.api.editor.guards  
org.netbeans.spi.editor.guards  
org.netbeans.spi.editor.guards.support  

GuardedSectionsAPI The Guarded Sections module is supposed to operate over the Swing's StyledDocument. It allows clients to manipulate named guarded sections that prevents user to modify the content. So if you like to create, modify or delete guarded sections the GuardedSectionManager is the best place where to start.

GuardedSectionsSPI The module also allows to implement custom guarded section persistance in various content types like java, xml, ... The easiest way is to subclass AbstractGuardedSectionsProvider.
In order to bind guarded sections to your editor see GuardedSectionsFactory.

What is New (see all changes)?

Use Cases

Add new section
In order to add a new section after the existing section, which seems to be most frequent, use:
        String sectionName = ...;
        StyledDocument doc = ...;
        GuardedSectionManager guards = GuardedSectionManager.getInstance(doc);
        GuardedSection g = guards.findSimpleSection(sectionName);
        guards.createSimpleSection("new_name", doc.createPosition(g.getEndPosition().getOffset() + 1));
       
Delete existing section
        StyledDocument doc = ...;
        GuardedSectionManager guards = GuardedSectionManager.getInstance(doc);
        GuardedSection g = guards.findSimpleSection("sectionName");
        g.deleteSection();
       
Plug guarded sections stuff into the editor
In case you want your CloneableEditorSupport to provide guarded sections you should implement the GuardedEditorSupport interface.
        private final class MyGuardedEditor implements GuardedEditorSupport {
           ...
        }
       
Further implement reading and writing of existing sections.
        protected void loadFromStreamToKit(StyledDocument doc, InputStream stream, EditorKit kit) throws IOException, BadLocationException {
            if (guardedEditor == null) {
                guardedEditor = new MyGuardedEditor();
                // remember the provider
                String mimeType = ((CloneableEditorSupport.Env) this.env).getMimeType();
                guardedProvider = GuardedSectionsFactory.find(mimeType).create(guardedEditor);
            }

            // load content to kit
            if (guardedProvider != null) {
                guardedEditor.setDocument(doc);
                Charset cs = FileEncodingQuery.getEncoding(this.getDataObject().getPrimaryFile());
                Reader reader = guardedProvider.createGuardedReader(stream, cs);
                try {
                    kit.read(reader, doc, 0);
                } finally {
                    reader.close();
                }
            } else {
                kit.read(stream, doc, 0);
            }
        }

        protected void saveFromKitToStream(StyledDocument doc, EditorKit kit, OutputStream stream) throws IOException, BadLocationException {
            if (guardedProvider != null) {
                Charset cs = FileEncodingQuery.getEncoding(this.getDataObject().getPrimaryFile());
                Writer writer = guardedProvider.createGuardedWriter(stream, cs);
                try {
                    kit.write(writer, doc, 0, doc.getLength());
                } finally {
                    writer.close();
                }
            } else {
                kit.write(stream, doc, 0, doc.getLength());
            }
        }
       
Your module should also require a proper implementation. In case of java content add to your module manifest file:
        OpenIDE-Module-Requires: org.netbeans.api.editor.guards.Java
       

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...
Group of java interfaces
Interface NameIn/OutStabilitySpecified in What Document?
GuardedSectionsAPIExportedOfficial

The Guarded Sections module is supposed to operate over the Swing's
StyledDocument. It allows clients to manipulate named guarded sections that prevents user to modify the content. So if you like to create, modify or delete guarded sections the GuardedSectionManager is the best place where to start.

GuardedSectionsSPIExportedOfficial

The module also allows to implement custom guarded section persistance in various content types like java, xml, ... The easiest way is to subclass
AbstractGuardedSectionsProvider.
In order to bind guarded sections to your editor see GuardedSectionsFactory.

Group of property interfaces
Interface NameIn/OutStabilitySpecified in What Document?
org.netbeans.api.editor.guards.GuardedSectionManagerExportedPrivate

The GuardedSectionManager instance is physically stored as a property of the document with key org.netbeans.api.editor.guards.GuardedSectionManager.class. Modules should not depend on this.

Group of lookup interfaces
Interface NameIn/OutStabilitySpecified in What Document?
GuardedSectionsFactoryExportedOfficial .../guards/GuardedSectionsFactory.html

Factories of custom providers that implements reading and writing guarded sections should be registered under Editors/<mime path> in the module layer file. The first one is chosen for the given mime path.

Implementation Details

Where are the sources for the module?

The sources for the module are in the NetBeans Mercurial repositories.

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

A module using the Guarded Sections API should also require a proper implementation. Eg in case of java content add to your module manifest file:

        OpenIDE-Module-Requires: org.netbeans.api.editor.guards.Java
       

A module implementing the Guarded Sections SPI should provide a token in the manifest file. Eg in case of java content add:

        OpenIDE-Module-Provides: org.netbeans.api.editor.guards.Java
       

Read more about the implementation in the answers to architecture questions.

Skip navigation links
org.netbeans.modules.editor.guards/1 1.37.1