| <html> |
| <!-- |
| |
| NO NO NO NO NO! |
| |
| |
| AUTOMATICALLY GENERATED FROM APICHANGES.XML, DO NOT EDIT |
| |
| SEE CHANGEME/apichanges.xml |
| |
| --> |
| |
| <head> |
| <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| |
| <title>Change History for the Progress API</title> |
| |
| <link rel="stylesheet" href="prose.css" type="text/css"> |
| |
| </head> |
| |
| <body> |
| |
| |
| <p class="overviewlink"> |
| <a href="overview-summary.html" shape="rect">Overview</a> |
| </p> |
| |
| |
| <h1>Introduction</h1> |
| |
| |
| <p>This document lists changes made to the Palette API/SPI.</p> |
| |
| <!-- The actual lists of changes, as summaries and details: --> |
| |
| |
| <hr> |
| <h1> |
| <a name="list-all-apis">Index of APIs</a> |
| </h1> |
| <ul> |
| <li> |
| <a href="#palette_api">Palette API</a> |
| </li> |
| </ul> |
| <h1> |
| <a name="incompat-by-date">Incompatible changes by date</a> |
| </h1> |
| <p>Fuller descriptions of all changes can be found below (follow links).</p> |
| <p>Not all deprecations are listed here, assuming that the deprecated |
| APIs continue to essentially work. For a full deprecation list, please |
| consult the |
| <a href="deprecated-list.html">Javadoc</a>.</p> |
| <ul></ul> |
| <h1> |
| <a name="all-by-date">All changes by date</a> |
| </h1> |
| <ul> |
| <li>(Dec 10 '13) <a href="#issue-227345">Introduced <code>PaletteItemRegistration</code> and <code>PaletteItemRegistrations</code></a> |
| </li> |
| <li>(Apr 1 '12) <a href="#issue-200636">Deprecating ModuleInstall</a> |
| </li> |
| <li>(Nov 8 '11) <a href="#disable-palette-window">Allow to turn the auto-show of palette window on/off.</a> |
| </li> |
| <li>(Oct 21 '09) <a href="#default-visible">Make palette hidden by default for selected document types.</a> |
| </li> |
| <li>(May 5 '08) <a href="#support-text-dnd">Allowing user dropping text into the palette to create new custom code clips.</a> |
| </li> |
| <li>(Feb 22 '08) <a href="#per-document-visibility">Palette visibility is defined per document-type.</a> |
| </li> |
| <li>(Jun 12 '07) <a href="#custom-reset">Palette providers may need to define their own action that |
| resets the palette to its default state.</a> |
| </li> |
| <li>(Feb 27 '07) <a href="#mime-type-associations">Allow associating palette content with document mime type.</a> |
| </li> |
| <li>(Jan 30 '07) <a href="#display-name">Allow display name and tooltip to be defined directly in item's XML</a> |
| </li> |
| <li>(Jan 27 '07) <a href="#custom-refresh">Palette providers need to be notified when the palette content is being refreshed.</a> |
| </li> |
| <li>(Oct 16 '06) <a href="#help_ctx">Added helpId attribute</a> |
| </li> |
| <li>(Jun 6 '06) <a href="#api_stabilization.palette">The Common Palette API has been stabilized.</a> |
| </li> |
| <li>(Sep 13 '05) <a href="#draganddrop_support">Added support for default drag and drop operations</a> |
| </li> |
| <li>(Aug 10 '05) <a href="#client-support">Palette client support released</a> |
| </li> |
| <li>(Aug 9 '05) <a href="#version-1.2">Added a new optional attribute that can specify the width of items in the palette.</a> |
| </li> |
| <li>(Aug 8 '05) <a href="#version-1.1">Removing unnecessary exceptions from PaletteFactory</a> |
| </li> |
| <li>(Jul 21 '05) <a href="#version-1.0">Initial version released</a> |
| </li> |
| </ul> |
| <h1> |
| <a name="all-by-version">Changes by version</a> |
| </h1> |
| <p> |
| These API specification versions may be used to indicate that a module |
| requires a certain API feature in order to function. For example, if you |
| see here a feature you need which is labelled <samp>1.20</samp>, your |
| manifest should contain in its main attributes the line: |
| </p> |
| <pre>OpenIDE-Module-Module-Dependencies: org.netbeans.spi.palette > 1.20</pre> |
| <ul> |
| <li> |
| (1.40) <a href="#issue-227345">Introduced <code>PaletteItemRegistration</code> and <code>PaletteItemRegistrations</code></a> |
| </li> |
| <li> |
| (1.31) <a href="#issue-200636">Deprecating ModuleInstall</a> |
| </li> |
| <li> |
| (1.29) <a href="#disable-palette-window">Allow to turn the auto-show of palette window on/off.</a> |
| </li> |
| <li> |
| (1.20) <a href="#default-visible">Make palette hidden by default for selected document types.</a> |
| </li> |
| <li> |
| (1.14) <a href="#support-text-dnd">Allowing user dropping text into the palette to create new custom code clips.</a> |
| </li> |
| <li> |
| (1.13) <a href="#per-document-visibility">Palette visibility is defined per document-type.</a> |
| </li> |
| <li> |
| (1.11) <a href="#custom-reset">Palette providers may need to define their own action that |
| resets the palette to its default state.</a> |
| </li> |
| <li> |
| (1.10) <a href="#mime-type-associations">Allow associating palette content with document mime type.</a> |
| </li> |
| <li> |
| (1.9) <a href="#custom-refresh">Palette providers need to be notified when the palette content is being refreshed.</a> |
| </li> |
| <li> |
| (1.8) <a href="#display-name">Allow display name and tooltip to be defined directly in item's XML</a> |
| </li> |
| <li> |
| (1.7) <a href="#help_ctx">Added helpId attribute</a> |
| </li> |
| <li> |
| (1.6) <a href="#api_stabilization.palette">The Common Palette API has been stabilized.</a> |
| </li> |
| <li> |
| (1.4) <a href="#draganddrop_support">Added support for default drag and drop operations</a> |
| </li> |
| <li> |
| (1.3) <a href="#client-support">Palette client support released</a> |
| </li> |
| <li> |
| (1.2) <a href="#version-1.2">Added a new optional attribute that can specify the width of items in the palette.</a> |
| </li> |
| <li> |
| (1.1) <a href="#version-1.1">Removing unnecessary exceptions from PaletteFactory</a> |
| </li> |
| <li> |
| (1.0) <a href="#version-1.0">Initial version released</a> |
| </li> |
| </ul> |
| <h1> |
| <a name="all-by-class">Changes by affected class</a> |
| </h1> |
| <h2> |
| <a name="org.netbeans.spi.palette.DragAndDropHandler"><code><span style="color:gray">org.netbeans.spi.palette.</span>DragAndDropHandler</code></a> |
| </h2><ul><li>(May 5 '08) <a href="#support-text-dnd">Allowing user dropping text into the palette to create new custom code clips.</a> |
| </li></ul><h2> |
| <a name="org.netbeans.spi.palette.PaletteActions"><code><span style="color:gray">org.netbeans.spi.palette.</span>PaletteActions</code></a> |
| </h2><ul><li>(Jun 12 '07) <a href="#custom-reset">Palette providers may need to define their own action that |
| resets the palette to its default state.</a> |
| </li> |
| <li>(Jan 27 '07) <a href="#custom-refresh">Palette providers need to be notified when the palette content is being refreshed.</a> |
| </li></ul><h2> |
| <a name="org.netbeans.spi.palette.PaletteItemRegistration"><code><span style="color:gray">org.netbeans.spi.palette.</span>PaletteItemRegistration</code></a> |
| </h2><ul><li>(Dec 10 '13) <a href="#issue-227345">Introduced <code>PaletteItemRegistration</code> and <code>PaletteItemRegistrations</code></a> |
| </li></ul><h2> |
| <a name="org.netbeans.spi.palette.PaletteItemRegistrations"><code><span style="color:gray">org.netbeans.spi.palette.</span>PaletteItemRegistrations</code></a> |
| </h2><ul><li>(Dec 10 '13) <a href="#issue-227345">Introduced <code>PaletteItemRegistration</code> and <code>PaletteItemRegistrations</code></a> |
| </li></ul><h2> |
| <a name="org.netbeans.spi.palette.PaletteModule"><code><span style="color:gray">org.netbeans.spi.palette.</span>PaletteModule</code></a> |
| </h2><ul><li>(Apr 1 '12) <a href="#issue-200636">Deprecating ModuleInstall</a> |
| </li></ul><hr> |
| <h1> |
| <a name="details-by-api">Details of all changes by API and date</a> |
| </h1> |
| <hr style="width:50%"> |
| <h2> |
| <a name="palette_api">Palette API</a> |
| </h2> |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --> |
| <h3> |
| <a name="issue-227345">Introduced <code>PaletteItemRegistration</code> and <code>PaletteItemRegistrations</code></a> |
| </h3> |
| <em>Dec 10 '13; API spec. version: 1.40; affected top-level classes: <a href="./org/netbeans/spi/palette/PaletteItemRegistration.html"><code>PaletteItemRegistration</code></a> <a href="./org/netbeans/spi/palette/PaletteItemRegistrations.html"><code>PaletteItemRegistrations</code></a>; made by: skygo; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=227345"> |
| #227345</a></em> |
| <br> |
| |
| <p> |
| Introduced a new annotation for registering palette items. |
| </p> |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --> |
| <h3> |
| <a name="issue-200636">Deprecating ModuleInstall</a> |
| </h3> |
| <em>Apr 1 '12; API spec. version: 1.31; affected top-level classes: <a href="./org/netbeans/spi/palette/PaletteModule.html"><code>PaletteModule</code></a>; made by: jtulach; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=200636"> |
| #200636</a></em> |
| <br>Deprecating <a href="org/netbeans/spi/palette/PaletteModule.html" shape="rect"> |
| PaletteModule</a> - it should not |
| be part of the API to begin with. Now it is registered with |
| <a href="../org-openide-windows/org/openide/windows/OnShowing.html" shape="rect">OnShowing</a> |
| annotation and thus implements <code>Runnable</code>. |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --><h3> |
| <a name="disable-palette-window">Allow to turn the auto-show of palette window on/off.</a> |
| </h3> |
| <em>Nov 8 '11; API spec. version: 1.29; made by: saubrecht; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=204786"> |
| #204786</a></em> |
| <br> |
| |
| <p> |
| A new branding token <code>Palette.Window.Enabled</code> in |
| <code>org.netbeans.spi.palette</code> package allows to turn the automatic display of palette |
| window on/off. When the property value is <code>false</code> then |
| the palette window will not show when an editor with palette |
| content is activated. The user must open/close the palette window |
| manually. The default value is <code>true</code> which means |
| the palette window will auto-show/hide when active editor changes. |
| Note: The palette window is part of <code>commonpalette</code> TopComponent group |
| which the form designer opens when activated. So to turn the palette |
| window off completely it is necessary to remove its reference |
| from that group. |
| </p> |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --> |
| <h3> |
| <a name="default-visible">Make palette hidden by default for selected document types.</a> |
| </h3> |
| <em>Oct 21 '09; API spec. version: 1.20; made by: saubrecht; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=170718"> |
| #170718</a></em> |
| <br> |
| |
| <p> |
| A new boolean attribute can be set on palette's root node or |
| on palette's root folder in XML layer to hide the palette window |
| by default when a document the palette is associated with is activated. |
| User then must open the palette window manually for the first time. |
| The attribute's name is "paletteDefaultVisible" and the default |
| value is "true". |
| </p> |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --> |
| <h3> |
| <a name="support-text-dnd">Allowing user dropping text into the palette to create new custom code clips.</a> |
| </h3> |
| <em>May 5 '08; API spec. version: 1.14; affected top-level classes: <a href="./org/netbeans/spi/palette/DragAndDropHandler.html"><code>DragAndDropHandler</code></a>; made by: saubrecht; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=93002"> |
| #93002</a></em> |
| <br> |
| |
| <p> |
| If the Common Palette is associated with a text editor then it's desired to allow |
| users dragging and dropping text into the palette to create new custom code clips that |
| can be dropped into editor later on. |
| </p> |
| |
| <p> |
| That can be achieved simply by subclassing the default DragAndDropHandler class |
| which manages all DragAndDrop-related operations in the Common Palette and turning |
| the text dnd support in superclasses's constructor on. The default implementation |
| pops up a dialog window when some text is dropped into the palette where user enters |
| code clip name and tooltip and optionally selects appropriate icons. |
| </p> |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --> |
| <h3> |
| <a name="per-document-visibility">Palette visibility is defined per document-type.</a> |
| </h3> |
| <em>Feb 22 '08; API spec. version: 1.13; made by: saubrecht; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=62964"> |
| #62964</a></em> |
| <br> |
| |
| <p> |
| Now it's possible to close the palette window while e.g. editing an HTML file |
| and the palette will still show up when designing a form. |
| </p> |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --> |
| <h3> |
| <a name="custom-reset">Palette providers may need to define their own action that |
| resets the palette to its default state.</a> |
| </h3> |
| <em>Jun 12 '07; API spec. version: 1.11; affected top-level classes: <a href="./org/netbeans/spi/palette/PaletteActions.html"><code>PaletteActions</code></a>; made by: saubrecht; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=105561"> |
| #105561</a></em> |
| <br> |
| |
| <p> |
| Now it's possible to provide an action that will be invoked when user chose 'Reset' |
| in palette's popup menu or in Palette Manager window. |
| </p> |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --> |
| <h3> |
| <a name="mime-type-associations">Allow associating palette content with document mime type.</a> |
| </h3> |
| <em>Feb 27 '07; API spec. version: 1.10; made by: saubrecht; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=90213"> |
| #90213</a></em> |
| <br> |
| |
| <p> |
| The previous version of palette API mandated that editor TopComponent had to insert a |
| PaletteController instance into its Lookup if it wants to associate the palette with it. |
| Now it is possible to associate the palette also with an existing |
| editor without the need to change its implementation, e.g. to add code snippets |
| palette to java source editor. |
| </p> |
| |
| <p> |
| If the mime type of active editor window has an associated instance of PaletteController |
| in the XML layer system then palette window opens and displays the specified palette contents. |
| The PaletteController from TopComponent's Lookup takes precedens over the PaletteController |
| found from mime type lookup in the XML layer (if any) for backwards compatibility. |
| </p> |
| |
| <p>The new API is fully backwards compatible and there are no implications for existing |
| palette providers.</p> |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --> |
| <h3> |
| <a name="display-name">Allow display name and tooltip to be defined directly in item's XML</a> |
| </h3> |
| <em>Jan 30 '07; API spec. version: 1.8; made by: saubrecht; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=90212"> |
| #90212</a></em> |
| <br> |
| |
| <p> |
| Now it's possible to specify item's display name and tooltip directly in item's |
| XML definition (instead of providing bundle name and keys). It's needed for items |
| created at runtime, for example code snippets highlighted in the editor and dropped |
| to the palette. |
| </p> |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --> |
| <h3> |
| <a name="custom-refresh">Palette providers need to be notified when the palette content is being refreshed.</a> |
| </h3> |
| <em>Jan 27 '07; API spec. version: 1.9; affected top-level classes: <a href="./org/netbeans/spi/palette/PaletteActions.html"><code>PaletteActions</code></a>; made by: saubrecht; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=88400"> |
| #88400</a></em> |
| <br> |
| |
| <p> |
| Now it's possible to provide an action that will be invoked as part of palette's 'refresh' logic. |
| </p> |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --> |
| <h3> |
| <a name="help_ctx">Added helpId attribute</a> |
| </h3> |
| <em>Oct 16 '06; API spec. version: 1.7; made by: saubrecht; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=77387"> |
| #77387</a></em> |
| <br> |
| |
| <p> |
| Now it's possible to add <em>helpId</em> attribute to palette's root, categories and items |
| that will be used to create appropriate HelpCtx. The attribute can be specified |
| in XML layer as a folder (palette's root and categories) or file attribute |
| (palette items) or it can be provided directly by appropriate Nodes. |
| </p> |
| |
| <p> |
| When F1 key is pressed in palette's window then first the selected item is asked |
| for HelpCtx id. If no item is selected or it does not provide specific help id then |
| selected category is checked for help id. If the category does not provide any help id |
| either then palette's root is asked for help id. If the root does not define any then |
| the default help id <em>CommonPalette</em> will be used. |
| </p> |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --> |
| <h3> |
| <a name="api_stabilization.palette">The Common Palette API has been stabilized.</a> |
| </h3> |
| <em>Jun 6 '06; API spec. version: 1.6; made by: saubrecht; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=77387"> |
| #77387</a></em> |
| <br> |
| |
| <p> |
| To indicate that this is now considered a stable API, the major release version was |
| incremented to 1 from 0. |
| </p> |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --> |
| <h3> |
| <a name="draganddrop_support">Added support for default drag and drop operations</a> |
| </h3> |
| <em>Sep 13 '05; API spec. version: 1.4; made by: saubrecht</em> |
| <br> |
| The abstract class DragAndDropHandler now provides default implementation |
| for all drag and drop operations. The only method that needs to be overridden |
| is <code>void customize( ExTransferable t, Lookup item )</code> to provide |
| custom data flavors for items dragged from the palette to editor.<br> |
| There are also new methods (and their default implementations) in this class |
| that handle reordering of categories and reordering of items (i.e. drag and drop |
| operations withing the palette window). |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --><h3> |
| <a name="client-support">Palette client support released</a> |
| </h3> |
| <em>Aug 10 '05; API spec. version: 1.3; made by: lkotouc</em> |
| <br> |
| The first release of the Palette client support. It involves namely DTD describing item definition file format |
| and some implementation addons regarding definition file parsing and custom implementation class loading. |
| |
| The palette item implementor can either directly provide the item body |
| or her own item class implementing <code>org.openide.text.ActiveEditorDrop</code> interface. |
| |
| Lookup that holds object(s) representing the selected item then associates |
| custom item class instance with the <code>org.openide.text.ActiveEditorDrop.class</code> key and |
| the body with <code>java.lang.String</code> key. |
| <!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --><h3> |
| <a name="version-1.2">Added a new optional attribute that can specify the width of items in the palette.</a> |
| </h3> |
| <em>Aug 9 '05; API spec. version: 1.2; made by: saubrecht</em> |
| <br>There's a new attribute "itemWidth" that can be set for palette's root node |
| (or for palette's root folder in the layer). This attribute defines the width in pixels |
| for all items in the palette thus forcing the same number of columns for all categories. |
| If the attribute is omitted or its value is "-1" then the item widths will be calculated |
| dynamically. The attribute is read-only.<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --><h3> |
| <a name="version-1.1">Removing unnecessary exceptions from PaletteFactory</a> |
| </h3> |
| <em>Aug 8 '05; API spec. version: 1.1; made by: saubrecht</em> |
| <br>Removed IOException from the signature of methods in PaletteFactory that accept Node as an argument.<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --><h3> |
| <a name="version-1.0">Initial version released</a> |
| </h3> |
| <em>Jul 21 '05; API spec. version: 1.0; made by: saubrecht</em> |
| <br>The first initial release of the Palette API. |
| |
| <hr> |
| <p><span class="footnote">Built on September 14 2018. | Copyright © 2017-2018 Apache Software Foundation. All Rights Reserved.</span></p> |
| |
| |
| </body> |
| |
| </html> |
