| // |
| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you under the Apache License, Version 2.0 (the |
| // "License"); you may not use this file except in compliance |
| // with the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, |
| // software distributed under the License is distributed on an |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| // KIND, either express or implied. See the License for the |
| // specific language governing permissions and limitations |
| // under the License. |
| // |
| |
| = NetBeans プロパティーエディタチュートリアル |
| :jbake-type: platform_tutorial |
| :jbake-tags: tutorials |
| :jbake-status: published |
| :syntax: true |
| :source-highlighter: pygments |
| :toc: left |
| :toc-title: |
| :icons: font |
| :experimental: |
| :description: NetBeans プロパティーエディタチュートリアル - Apache NetBeans |
| :keywords: Apache NetBeans Platform, Platform Tutorials, NetBeans プロパティーエディタチュートリアル |
| |
| |
| |
| このチュートリアルでは、カスタムエディタやカスタムインプレイスエディタ (custom inplace editor) の提供など、 NetBeans でプロパティーエディタを使う方法について紹介します。特に以下の内容を扱います: |
| |
| * ノードごとに独自のプロパティーエディタを提供する |
| * カスタムエディタの作成 |
| * カスタムインプレイスエディタの作成 |
| * カスタムプロパティーエディタをグローバル登録する |
| |
| |
| == はじめに |
| |
| このチュートリアルは以下のチュートリアルの続きとして用意されており、サンプルコードはこれらのチュートリアルで作成したコードを基にしています: |
| |
| * link:nbm-selection-1_ja.html[NetBeans セレクション管理のチュートリアル I—TopComponent の Lookup を使う方法] |
| * link:nbm-selection-2_ja.html[NetBeans セレクション管理のチュートリアル II—ノードを使う方法] |
| * link:nbm-nodesapi2_ja.html[ノード API チュートリアル] |
| |
| もしもこれらのチュートリアルがまだお済みでないなら、先に済ませることをお勧めします。 |
| |
| サンプルをダウンロードするには link:http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=3146[ここ]をクリックしてください。 |
| |
| link:nbm-nodesapi2_ja.html[前回のチュートリアル]では、プロパティーシートに表示することができる `Property` を持つ`ノード`の作成方法を学びました。 |
| |
| |
| == カスタムプロパティーエディタ |
| |
| 標準のプロパティーエディタでは十分ではなかったり、標準のエディタが用意されていない型のプロパティーが必要になる時があるでしょう。NetBeans IDE には一般的な Swing の型に対するクラスが組み込まれていますが、標準のプロパティーエディタですべての需要がカバーできるというわけではありません。 |
| |
| これより前回のチュートリアルで中断したところ、つまり、 `APIObject` オブジェクトをラップする `MyNode` クラスが、 `index` という読み取り専用のプロパティーと、読み書き可能な `date` プロパティーを提供しているところから開始します。 |
| |
| |
| == プロパティーエディタの作成 |
| |
| プロパティーエディタ作成の基本はとてもシンプルです。JavaBeans API には、プロパティーエディタの基本をほとんどカバーする `PropertyEditorSupport` という基本クラスがあり、ほんの少しの手間で簡単なプロパティーエディタを作成することができます。 |
| |
| プロパティーエディタの役目は2つあります。プロパティーシートに表示する文字列から値にもしくは値から文字列へと変換することと、設定された値を検査することです。まず始めに、異なるフォーマットの日時を表示、入力できるプロパティーエディタを作成します。 |
| |
| |
| [start=1] |
| 1. `org.myorg.myeditor` パッケージを右クリックし、「新規」>「Java クラス」を選択します。ウィザードで、クラス名を `DatePropertyEditor` とします。 |
| |
| [start=2] |
| 1. コードエディタで、クラスのシグネチャを変更し、 `PropertyEditorSupport` を拡張するようにします: |
| |
| [source,java] |
| ---- |
| |
| |
| public class DatePropertyEditor extends PropertyEditorSupport { |
| |
| ---- |
| |
| |
| [start=3] |
| 1. `setAsText()` と `getAsText()` を以下のように実装します: |
| |
| [source,java] |
| ---- |
| |
| |
| public String getAsText() { |
| Date d = (Date) getValue(); |
| if (d == null) { |
| return "No Date Set"; |
| } |
| return new SimpleDateFormat("MM/dd/yy HH:mm:ss").format(d); |
| } |
| |
| public void setAsText(String s) { |
| try { |
| setValue (new SimpleDateFormat("MM/dd/yy HH:mm:ss").parse(s)); |
| } catch (ParseException pe) { |
| IllegalArgumentException iae = new IllegalArgumentException ("Could not parse date"); |
| throw iae; |
| } |
| } |
| |
| ---- |
| |
| |
| [start=4] |
| 1. `MyNode` をコードエディタで開きます。`dateProperty` の宣言部分を変更し、`Property` ではなく、 `PropertySupport.Reflection` の変数として宣言します。そして、 `PropertySupport.Reflection` 独自の関数を使っていきます: |
| |
| [source,java] |
| ---- |
| |
| |
| PropertySupport.Reflection dateProp = new PropertySupport.Reflection(obj, Date.class, "date"); |
| |
| ---- |
| |
| |
| [start=5] |
| 1. この行の後に、以下の1行を挿入してください: |
| |
| [source,java] |
| ---- |
| |
| |
| dateProp.setPropertyEditorClass(DatePropertyEditor.class); |
| |
| ---- |
| |
| |
| [start=6] |
| 1. モジュールスイートを実行し、「ファイル」>「Open Editor」をクリックしてエディタを開き、以下のように Date プロパティーのフォーマットが変わることを確認してください: |
| |
| |
| image::images/custom-editors_changed-date-60.png[] |
| |
| |
| == カスタムエディタの作成 |
| |
| 標準の `java.beans.PropertyEditor` とそのサブクラスのもう1つの特徴は、"カスタムエディタ" を作成することができるということです。これは通常、プロパティーシートの端にある "..." ボタンをクリックすると出てくるダイアログのことです。 |
| |
| このようなエディタの実装の詳細について説明することは、チュートリアルの本題からはそれるのですが、基本的には以下の通りです: |
| |
| |
| [start=1] |
| 1. `DatePropertyEditor` の以下の2つのメソッドを実装します: |
| |
| [source,java] |
| ---- |
| |
| |
| public Component getCustomEditor() { |
| return new JLabel ("I want to be a custom editor"); |
| } |
| |
| public boolean supportsCustomEditor() { |
| return true; |
| } |
| |
| ---- |
| |
| |
| [start=2] |
| 1. スイートを実行すると、今度は以下のように、"..." ボタンがプロパティーシートの端に表示されます: |
| |
| |
| image::images/custom-editors_custom-editor-60-1.png[] |
| |
| このボタンをクリックすると、 getCustomEditor() メソッドで作成した JLabel が表示されます: |
| |
| |
| image::images/custom-editors_custom-editor-60-2.png[] |
| |
| 実際に使用するには、JPanel を作成し、プロパティーを簡単に設定できるようにカレンダーや時計を追加します。話がそれるので、ここで実際のコードは紹介しません。 |
| |
| |
| [start=3] |
| 1. 続きへ進む前に、以上で追加した2つのメソッドを削除します。 |
| |
| |
| == カスタムインプレイスエディタの作成 |
| |
| 本当に便利な方法は、よりよい日時エディタをプロパティーシート自身に組み込むことです。NetBeans にはこのようなことをするための API があるのです。多少のコードは必要になりますが、そうするだけの価値はあります。 |
| |
| java.net の link:https://swingx.dev.java.net/[SwingLabs] プロジェクトに、 date picker component という便利なコンポーネントがあるので、これを単純にリユースすることにします。まず最初にしなくてはいけないことは、NetBeans に SwingX を組み込むことです。 |
| |
| |
| [start=1] |
| 1. link:http://swinglabs.org/downloads.jsp[SwingLabs のサイト]から、 `swingx.jar` をダウンロードします。(ライセンスの都合により、 NetBeans の CVS で管理することはできません。) |
| |
| [start=2] |
| 1. SelectionSuite を展開し、「モジュール」ノードを右クリックして、「新規ライブラリを追加」を選択します: |
| |
| |
| image::images/custom-editors_library-wrapper-60.png[] |
| |
| |
| [start=3] |
| 1. 先ほどダウンロードした `swingx.jar` を参照します。「次へ」をクリックします。 |
| |
| [start=4] |
| 1. もう一度「次へ」をクリックし、コード名ベースが ``org.jdesktop.swingx`` となっていることを確認して「完了」をクリックします。 |
| |
| [start=5] |
| 1. プロジェクトタブで、My Editor プロジェクトを右クリックし、「プロパティー」を選択します。 |
| |
| [start=6] |
| 1. 「ライブラリ」カテゴリの「依存関係を追加」をクリックし、 swingx のライブラリラッパーモジュールへの依存関係を追加します。 |
| |
| これで date picker を利用する準備が整いました。これより、NetBeans 固有のインタフェースをいくつか実装します: |
| |
| * ExPropertyEditor—プロパティーシートが環境変数 (`PropertyEnv`) を渡すことができるプロパティーエディタインタフェース。この環境変数により、エディタは編集中の `Property` オブジェクトなどにアクセスすることができる。 |
| * InplaceEditor.Factory—`InplaceEditor` を所有するオブジェクトのインタフェース |
| * InplaceEditor—プロパティーシート内にカスタムコンポーネントを表示するためのインタフェース |
| |
| `InplaceEditor.Factory` と `ExPropertyEditor` を `DatePropertyEditor` に直接実装し、 `InplaceEditor` をネストクラスとして作成します: |
| |
| |
| [start=1] |
| 1. `DatePropertyEditor` のシグネチャを以下のように変更します: |
| |
| [source,java] |
| ---- |
| |
| |
| public class DatePropertyEditor extends PropertyEditorSupport implements ExPropertyEditor, InplaceEditor.Factory { |
| |
| ---- |
| |
| |
| [start=2] |
| 1. これまでにもしたように、Ctrl-Shift-I キーを押してインポートを修正し、「すべての抽象メソッドの実装」を実行して必要な関数を追加します。 |
| |
| |
| [start=3] |
| 1. `DatePropertyEditor` に以下のメソッドを追加します: |
| |
| [source,java] |
| ---- |
| |
| |
| public void attachEnv(PropertyEnv env) { |
| env.registerInplaceEditorFactory(this); |
| } |
| |
| private InplaceEditor ed = null; |
| |
| public InplaceEditor getInplaceEditor() { |
| if (ed == null) { |
| ed = new Inplace(); |
| } |
| return ed; |
| } |
| |
| ---- |
| |
| |
| [start=4] |
| 1. 次に `InplaceEditor` を実装する必要があります。このクラスに、 swingx の `JXDatePicker` コンポーネントと、このコンポーネントに値を設定し、必要がなくなった際にリソースを解放する関数を追加します。多少のコードは必要になりますが、とても簡単です。`DatePropertyEditor` に `Inplace` という static なネストクラスを作成します: |
| |
| [source,java] |
| ---- |
| |
| |
| |
| private static class Inplace implements InplaceEditor { |
| |
| private final JXDatePicker picker = new JXDatePicker(); |
| private PropertyEditor editor = null; |
| |
| public void connect(PropertyEditor propertyEditor, PropertyEnv env) { |
| editor = propertyEditor; |
| reset(); |
| } |
| |
| public JComponent getComponent() { |
| return picker; |
| } |
| |
| public void clear() { |
| //avoid memory leaks: |
| editor = null; |
| model = null; |
| } |
| |
| public Object getValue() { |
| return picker.getDate(); |
| } |
| |
| public void setValue(Object object) { |
| picker.setDate ((Date) object); |
| } |
| |
| public boolean supportsTextEntry() { |
| return true; |
| } |
| |
| public void reset() { |
| Date d = (Date) editor.getValue(); |
| if (d != null) { |
| picker.setDate(d); |
| } |
| } |
| |
| public KeyStroke[] getKeyStrokes() { |
| return new KeyStroke[0]; |
| } |
| |
| public PropertyEditor getPropertyEditor() { |
| return editor; |
| } |
| |
| public PropertyModel getPropertyModel() { |
| return model; |
| } |
| |
| private PropertyModel model; |
| public void setPropertyModel(PropertyModel propertyModel) { |
| this.model = propertyModel; |
| } |
| |
| public boolean isKnownComponent(Component component) { |
| return component == picker || picker.isAncestorOf(component); |
| } |
| |
| public void addActionListener(ActionListener actionListener) { |
| //do nothing - not needed for this component |
| } |
| |
| public void removeActionListener(ActionListener actionListener) { |
| //do nothing - not needed for this component |
| } |
| } |
| |
| ---- |
| |
| |
| [start=5] |
| 1. まだインポートを修正していなければ、Ctrl-Shift-I キーを押してインポートを修正します。 |
| |
| |
| [start=6] |
| 1. モジュールスイートを実行し、「ファイル」>「Open Editor」をクリックしてエディタ (もはや大したエディタではありませんが) を開き、 `MyNode` のインスタンスを選択して、プロパティーシートの date プロパティーの値をクリックします。date picker のポップアップが表示され、ちゃんと動作することを確認してください: |
| |
| |
| image::images/custom-editors_custom-inplace-editor-60.png[] |
| |
| |
| == DatePropertyEditor をグローバル登録する |
| |
| プロパティーエディタを同じ型のすべてのプロパティーに対して使えるように登録しておくと便利な場合が多いでしょう。実際、 `DatePropertyEditor` は通常、 `java.util.Date` 型のどんなプロパティーにも有用です。このようなプロパティーエディタを登録すべきか決めるのに有用性が第1の要件ではありませんが、もしアプリケーションやモジュールが定期的に Date プロパティーを扱うのなら、登録したほうがよいでしょう。 |
| |
| それでは、 `java.util.Date` 型のすべてのプロパティーがプロパティーシートでエディタとして利用できるように `DatePropertyEditor` を登録する方法をご紹介します: |
| |
| |
| [start=1] |
| 1. My Editor プロジェクトを右クリックし、ポップアップメニューから 「プロパティー」を選択します。 |
| |
| |
| [start=2] |
| 1. 「プロジェクトプロパティー」ダイアログの「ライブラリ」カテゴリの「依存関係を追加」をクリックします。ここで追加しなくてはならないのは、モジュールシステム API への依存関係です。そうすれば `ModuleInstall` のサブクラスを作成し、スタートアップ時にいくつかのコードを実行することができるからです。ダイアログに `ModuleInstall` と入力します。ダイアログは自動的に「モジュールシステム API」を選択するはずです。Enter キーを押すか「了解」をクリックし、 My Editor モジュールにモジュールシステム API への依存関係を追加します。 |
| |
| |
| [start=3] |
| 1. My Editor プロジェクトの `org.myorg.myeditor` パッケージを右クリックし、「新規」>「その他」を選択します。「モジュールの開発」カテゴリの「モジュールインストーラ」を選択し、「次へ」をクリックします。「完了」をクリックします。すると `org.openide.modules.ModuleInstall` のサブクラスが作成されるでしょう。このクラスには、スタートアップ時に実行されるコードが含まれています。 |
| |
| |
| [start=4] |
| 1. スタートアップ時に実行される `restored()` メソッドを以下のように実装します: |
| |
| [source,java] |
| ---- |
| |
| |
| public void restored() { |
| PropertyEditorManager.registerEditor(Date.class, DatePropertyEditor.class); |
| } |
| |
| ---- |
| |
| ここでは、 `java.util.Date` 型のすべてのプロパティーの、システムを通じたデフォルトエディタとして、 `DatePropertyEditor` を登録しています。 |
| |
| |
| [start=5] |
| 1. Ctrl-Shift-I キーを押してインポートを修正します。 |
| |
| 本当に必要のある場合のみ `ModuleInstall` を使うということを忘れないでください。 <c1>ModuleInstall</c1> クラスは、スタートアップ時により多くのコードを実行することになるので、アプリケーションの起動を遅くしてしまいます。使わないですむなら使わないでください。もしどうしてもたくさんのプロパティーエディタを登録する必要があるなら、1つのモジュールに統合し、そこですべてのエディタを登録するのがよいでしょう。 |
| |
| 独自の型に対してプロパティーエディタを作成したい場合は、登録コードをそのクラスがロードされた時に実行される静的プロックなどに埋め込むなどするとよいでしょう。 |
| |
| |
| [source,java] |
| ---- |
| |
| |
| public class Foo { |
| static { |
| PropertyEditorManager.registerEditor(Foo.class, FooEditor.class); |
| } |
| //... |
| |
| ---- |
| |
| |
| [NOTE] |
| ==== |
| *要注意:* もし、プロパティーエディタが使用されるかどうか定かでないときは、 `PropertyEditorManager.setEditorSearchPath()` を使い、 `PropertyEditorManager.getEditorSearchPath()`で取得するパッケージの配列にあなたのパッケージを追加した方がよいかもしれません。上のコードは、 `FooEditor.class` をメモリにロードします。約1K は不必要なメモリを使用することになります。プロパティーエディタが1つや2つなら許されるでしょうが、それ以上ならプロパティーエディタを1つのパッケージにまとめ、各クラスに適当な名前をつけ、このパッケージを検索パスに登録したほうがよいでしょう。プロパティーエディタに関するより多くの情報については、 ` link:https://docs.oracle.com/javase/8/docs/api/java/beans/PropertyEditorManager.html[PropertyEditorManager]` の javadoc を参照してください。 |
| |
| ==== |
| |
| |
| == プロパティーパネルの使用 |
| |
| 詳細に取り扱わないにしても、プロパティーシートが `Node.Property` オブジェクトが役に立つ唯一の場所というわけではないということに言及しておいた方がよいでしょう。他にも `PropertyPanel` と呼ばれる便利な UI クラスが、 `org.openide.explorer.propertysheet` パッケージにあります。このクラスは、プロパティーシートのように、エディタ領域とカスタムエディタボタンと共に、1プロパティーを表示することができます。もしくは `somePropertyPanel.setPreferences(PropertyPanel.PREF_CUSTOM_EDITOR)` を呼べば、`Property` のカスタムエディタを表示することができます。プロパティーエディタがある設定/取得メソッドのペアを編集するのに適した UI コンポーネントを取得するために便利な方法として役に立ちます。 |
| |
| link:http://netbeans.apache.org/community/mailing-lists.html[ご意見をお寄せください] |
| |
| |
| |
| |
| |
| === この翻訳は、nora さんに提供していただきました。 |
| |
| |