| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <!-- Generated by javadoc (1.8.0_181) on Fri Sep 14 11:34:46 BST 2018 --> |
| <title>Overview (Editor Guarded Sections)</title> |
| <meta name="date" content="2018-09-14"> |
| <link rel="stylesheet" type="text/css" href="javadoc.css" title="Style"> |
| <script type="text/javascript" src="script.js"></script> |
| </head> |
| <body> |
| <script type="text/javascript"><!-- |
| try { |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="Overview (Editor Guarded Sections)"; |
| } |
| } |
| catch(err) { |
| } |
| //--> |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar.top"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.top.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li class="navBarCell1Rev">Overview</li> |
| <li>Package</li> |
| <li>Class</li> |
| <li>Use</li> |
| <li><a href="overview-tree.html">Tree</a></li> |
| <li><a href="deprecated-list.html">Deprecated</a></li> |
| <li><a href="index-files/index-1.html">Index</a></li> |
| <li><a href="help-doc.html">Help</a></li> |
| </ul> |
| <div class="aboutLanguage">org.netbeans.modules.editor.guards/1 1.35.1 </div> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li>Prev</li> |
| <li>Next</li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="index.html?overview-summary.html" target="_top">Frames</a></li> |
| <li><a href="overview-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_top"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <div class="header"> |
| <h1 class="title">Editor Guarded Sections<br/><span style='font-style:normal; font-size:medium; font-weight:normal; background-color:#ffffff;'><a href='http://wiki.netbeans.org/API_Stability#Official' target='_blank'>Official</a></span></h1> |
| </div> |
| <div class="header"> |
| <p>See: <a href="#overview.description">Description</a></p> |
| </div> |
| <div class="contentContainer"> |
| <table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Editor Guarded Sections table, listing packages, and an explanation"> |
| <caption><span>Editor Guarded Sections</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Package</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="org/netbeans/api/editor/guards/package-summary.html">org.netbeans.api.editor.guards</a></td> |
| <td class="colLast"> </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="org/netbeans/spi/editor/guards/package-summary.html">org.netbeans.spi.editor.guards</a></td> |
| <td class="colLast"> </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="org/netbeans/spi/editor/guards/support/package-summary.html">org.netbeans.spi.editor.guards.support</a></td> |
| <td class="colLast"> </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="contentContainer"><a name="overview.description"> |
| <!-- --> |
| </a> |
| <div class="block"><p> |
| |
| <p> |
| GuardedSectionsAPI |
| The Guarded Sections module is supposed to operate over the Swing's <a href="http://download.oracle.com/javase/8/docs/api/javax/swing/text/StyledDocument.html" shape="rect"><code>StyledDocument</code></a>. |
| 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 <a href="../org-netbeans-modules-editor-guards/org/netbeans/api/editor/guards/GuardedSectionManager.html" shape="rect"> |
| <code>GuardedSectionManager</code></a> is the best place where to start. |
| |
| </p> |
| |
| <p> |
| GuardedSectionsSPI |
| The module also allows to implement custom guarded section persistance in various content types like java, xml, ... |
| The easiest way is to subclass <a href="../org-netbeans-modules-editor-guards/org/netbeans/spi/editor/guards/support/AbstractGuardedSectionsProvider.html" shape="rect"> |
| <code>AbstractGuardedSectionsProvider</code></a>.<br>In order to bind guarded sections to your editor see <a href="../org-netbeans-modules-editor-guards/org/netbeans/spi/editor/guards/GuardedSectionsFactory.html" shape="rect"> |
| <code>GuardedSectionsFactory</code></a>. |
| |
| </p> |
| |
| </p> |
| <h3>What is New (see <a href="apichanges.html">all changes</a>)?</h3> |
| <ul> |
| |
| |
| <!--Search for dates that are later or equal to 1997-09-01 in |
| .--> |
| <!--Checking date 2016-2-17 with count of newer 0--><!--year ok--> |
| <li>Feb 17 '16 <a href="apichanges.html#protectRange">Allow to protect existing text</a> |
| <p> |
| Added method to create guarded block on top of existing text. |
| </p> |
| </li> |
| <!--Checking date 2014-5-21 with count of newer 1--><!--year ok--> |
| <li>May 21 '14 <a href="apichanges.html#DocumentGuards">DocumentGuards API</a> |
| <p> |
| |
| <p> |
| APIs exposed and actually used on GuardedDocument in <code>editor.lib</code> module is now declared in Editor Guarded Sections. |
| Clients may depend on Guarded Sections instead of on fading-away editor.lib module. |
| </p> |
| |
| <p> |
| Dependency on <code>openide.text</code> eliminated, new SPI <code>GuardedRegionMarker</code> |
| is added for Documents that are willing to style their contents according to guarded areas. |
| </p> |
| |
| </p> |
| </li> |
| <!--Checking date 2012-11-25 with count of newer 2--><!--year ok--> |
| <li>Nov 25 '12 <a href="apichanges.html#AbstractGuardedSectionsProvider-useReadersWritersOnSet">Ability run guarded readers/writers when the content of the guarded section's content is set</a> |
| <p> |
| |
| <p>When this option is set, setting the content of a GuardedSection will pass the data through the given |
| guarded writer and back through the given guarded reader, to ensure the result is the same |
| as if it would be read from the disk.</p> |
| |
| <p>Note that this new mode is not fully compatible with the original mode, e.g. all the set methods |
| of all the GuardedSection classes will throw IllegalStateException if invoked inside the write&read part.</p> |
| |
| </p> |
| </li> |
| <!--Checking date 2007-6-19 with count of newer 3--><!--year ok--> |
| <li>Jun 19 '07 <a href="apichanges.html#GuardedSectionsProvider-Charset">GuardedSectionsProvider supports Charset</a> |
| <p> |
| In order to use proper encoding by guards impl it is necessary to |
| change GuardedSectionsProvider to accept encoding rather as <code>java.nio.Charset</code> instance |
| than as a plain encoding name. |
| <ul> |
| |
| <li> |
| <code>Reader createGuardedReader(InputStream stream, String encoding) throws UnsupportedEncodingException</code> |
| replaced with |
| <code>Reader createGuardedReader(InputStream stream, Charset charset)</code> |
| </li> |
| |
| <li> |
| <code>Writer createGuardedWriter(OutputStream stream, String encoding) throws UnsupportedEncodingException</code> |
| replaced with |
| <code>Reader createGuardedReader(InputStream stream, Charset charset)</code> |
| </li> |
| |
| </ul> |
| |
| </p> |
| </li> |
| </ul> |
| <h3>Use Cases</h3> |
| <answer id="arch-usecases"> |
| |
| <p> |
| |
| <h5>Add new section</h5> |
| In order to add a new section after the existing section, which seems to be most frequent, use: |
| <pre xml:space="preserve"> |
| String sectionName = ...; |
| StyledDocument doc = ...; |
| GuardedSectionManager guards = GuardedSectionManager.getInstance(doc); |
| GuardedSection g = guards.findSimpleSection(sectionName); |
| guards.createSimpleSection("new_name", doc.createPosition(g.getEndPosition().getOffset() + 1)); |
| </pre> |
| |
| |
| <h5>Delete existing section</h5> |
| |
| <pre xml:space="preserve"> |
| StyledDocument doc = ...; |
| GuardedSectionManager guards = GuardedSectionManager.getInstance(doc); |
| GuardedSection g = guards.findSimpleSection("sectionName"); |
| g.deleteSection(); |
| </pre> |
| |
| |
| <h5>Plug guarded sections stuff into the editor</h5> |
| In case you want your <code>CloneableEditorSupport</code> to provide |
| guarded sections you should implement the <code>GuardedEditorSupport</code> |
| interface. |
| <pre xml:space="preserve"> |
| private final class MyGuardedEditor implements GuardedEditorSupport { |
| ... |
| } |
| </pre> |
| Further implement reading and writing of existing sections. |
| <pre xml:space="preserve"> |
| 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()); |
| } |
| } |
| </pre> |
| Your module should also require a proper implementation. In case of java |
| content add to your module manifest file: |
| <pre xml:space="preserve"> |
| OpenIDE-Module-Requires: org.netbeans.api.editor.guards.Java |
| </pre> |
| |
| |
| </p> |
| |
| </answer> |
| <h3>Exported Interfaces</h3> |
| |
| 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. <a href="architecture-summary.html">Read them all</a>... |
| |
| |
| <a name="group-java"> |
| <h5>Group of java interfaces</h5> |
| </a> |
| <table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%"> |
| <tr> |
| <td> |
| <table border="0" cellpadding="3" cellspacing="1" width="100%"> |
| <tr class="tablersh"> |
| <td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td> |
| </tr> |
| <tr class="tabler"> |
| <td>GuardedSectionsAPI</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Official">Official</a></td><td><a name="java-GuardedSectionsAPI"> |
| <p></p> |
| The Guarded Sections module is supposed to operate over the Swing's <a href="http://download.oracle.com/javase/8/docs/api/javax/swing/text/StyledDocument.html" shape="rect"><code>StyledDocument</code></a>. |
| 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 <a href="../org-netbeans-modules-editor-guards/org/netbeans/api/editor/guards/GuardedSectionManager.html" shape="rect"> |
| <code>GuardedSectionManager</code></a> is the best place where to start. |
| <p></p> |
| </a></td> |
| </tr> |
| <tr class="tabler"> |
| <td>GuardedSectionsSPI</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Official">Official</a></td><td><a name="java-GuardedSectionsSPI"> |
| <p></p> |
| The module also allows to implement custom guarded section persistance in various content types like java, xml, ... |
| The easiest way is to subclass <a href="../org-netbeans-modules-editor-guards/org/netbeans/spi/editor/guards/support/AbstractGuardedSectionsProvider.html" shape="rect"> |
| <code>AbstractGuardedSectionsProvider</code></a>.<br>In order to bind guarded sections to your editor see <a href="../org-netbeans-modules-editor-guards/org/netbeans/spi/editor/guards/GuardedSectionsFactory.html" shape="rect"> |
| <code>GuardedSectionsFactory</code></a>. |
| <p></p> |
| </a></td> |
| </tr> |
| </table> |
| </td> |
| </tr> |
| </table> |
| <p></p> |
| <a name="group-property"> |
| <h5>Group of property interfaces</h5> |
| </a> |
| <table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%"> |
| <tr> |
| <td> |
| <table border="0" cellpadding="3" cellspacing="1" width="100%"> |
| <tr class="tablersh"> |
| <td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td> |
| </tr> |
| <tr class="tabler"> |
| <td>org.netbeans.api.editor.guards.GuardedSectionManager</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Private">Private</a></td><td><a name="property-org.netbeans.api.editor.guards.GuardedSectionManager"> |
| <p></p> |
| The <code>GuardedSectionManager</code> instance is physically stored as a property of |
| the document with key <code>org.netbeans.api.editor.guards.GuardedSectionManager.class</code>. Modules should not depend on this. |
| <p></p> |
| </a></td> |
| </tr> |
| </table> |
| </td> |
| </tr> |
| </table> |
| <p></p> |
| <a name="group-lookup"> |
| <h5>Group of lookup interfaces</h5> |
| </a> |
| <table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%"> |
| <tr> |
| <td> |
| <table border="0" cellpadding="3" cellspacing="1" width="100%"> |
| <tr class="tablersh"> |
| <td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td> |
| </tr> |
| <tr class="tabler"> |
| <td>GuardedSectionsFactory</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Official">Official</a></td><td><a name="lookup-GuardedSectionsFactory"><a href="../org-netbeans-modules-editor-guards/org/netbeans/spi/editor/guards/GuardedSectionsFactory.html"> |
| .../guards/GuardedSectionsFactory.html</a> |
| <p></p> |
| <p></p> |
| Factories of custom providers that implements reading and writing guarded sections |
| should be registered under <code>Editors/<mime path></code> |
| in the module layer file. The first one is chosen for the given mime path. |
| <p></p> |
| </a></td> |
| </tr> |
| </table> |
| </td> |
| </tr> |
| </table> |
| <p></p> |
| <h3>Implementation Details</h3> |
| <h5>Where are the sources for the module?</h5> |
| |
| <p> |
| <p> |
| The sources for the module are in the |
| <a href="http://hg.netbeans.org/" shape="rect">NetBeans Mercurial repositories</a>. |
| </p> |
| </p> |
| |
| <h5>What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?</h5> |
| |
| <p> |
| 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: |
| </p> |
| |
| <pre xml:space="preserve"> |
| OpenIDE-Module-Requires: org.netbeans.api.editor.guards.Java |
| </pre> |
| |
| <p> |
| A module implementing the Guarded Sections SPI should provide a token in |
| the manifest file. Eg in case of java content add: |
| </p> |
| |
| <pre xml:space="preserve"> |
| OpenIDE-Module-Provides: org.netbeans.api.editor.guards.Java |
| </pre> |
| |
| <p> |
| Read more about the implementation in the <a href="architecture-summary.html">answers to |
| architecture questions</a>. |
| </p></div> |
| </div> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar.bottom"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.bottom.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li class="navBarCell1Rev">Overview</li> |
| <li>Package</li> |
| <li>Class</li> |
| <li>Use</li> |
| <li><a href="overview-tree.html">Tree</a></li> |
| <li><a href="deprecated-list.html">Deprecated</a></li> |
| <li><a href="index-files/index-1.html">Index</a></li> |
| <li><a href="help-doc.html">Help</a></li> |
| </ul> |
| <div class="aboutLanguage">org.netbeans.modules.editor.guards/1 1.35.1 </div> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li>Prev</li> |
| <li>Next</li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="index.html?overview-summary.html" target="_top">Frames</a></li> |
| <li><a href="overview-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_bottom"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| <p class="legalCopy"><small><span class="footnote">Built on September 14 2018. | Copyright © 2017-2018 Apache Software Foundation. All Rights Reserved.</span></small></p> |
| </body> |
| </html> |
