java.beans
類別 EventHandler

java.lang.Object
  java.beans.EventHandler

所有已實作的介面：

InvocationHandler

public class EventHandler
extends Object
implements InvocationHandler

EventHandler 類別為動態產生事件偵聽器提供支持，這些偵聽器的方法執行一條涉及傳入事件物件和目標物件的簡單語句。

EventHandler 類別由交互工具（比如應用程序產生器）使用，這些工具允許開發人員在 bean 之間建立連接。通常是建立從使用者介面 bean（事件 source）到應用程序邏輯 bean（target）的連接。大多數這類別有效連接隔離了應用程序邏輯與使用者介面。例如，用於從 JCheckBox 到接受 boolean 值的方法之間連接的 EventHandler 可以處理複選框狀態的提取，以及處理將其直接傳遞給該方法，從而使該方法與使用者介面層隔離。

內部類別是處理來自使用者介面的事件的另一種更常見方法。EventHandler 類別只處理可能使用內部類別的事件的子集。不過，EventHandler 使用長期持久方案要比使用內部類別更有效。同樣，在同一介面被實作很多次的大型應用程序中，使用 EventHandler 可以減少應用程序的磁碟和記憶體佔用。

使用 EventHandler 創建偵聽器佔用記憶體如此之少的原因是，EventHandler 所依賴的 Proxy 類別共享了同一介面的實作。例如，如果使用 EventHandler 的 create 方法產生某個應用程序中的所有 ActionListener，則所有動作偵聽器都將是單個類別（由 Proxy 類別創建）的實例。通常，基於 Proxy 類別的偵聽器要求為每個偵聽器型別（介面）創建一個偵聽器類別，而使用內部類別方法時要求為每個偵聽器（實作介面的物件）創建一個類別。

通常不需要直接處理 EventHandler 實例。相反，可使用 EventHandler 的 create 方法之一創建實作給定偵聽器介面的物件。此偵聽器物件在後台使用一個 EventHandler 物件來封裝關於事件的資訊、發生事件時發送訊息的物件、要發送的訊息（方法）和方法的任意參數。以下部分給出了如何使用 create 方法創建偵聽器物件的範例。

使用 EventHandler 的範例

EventHandler 最簡單的使用方法是安裝一個偵聽器，不帶參數地在目標物件上調用某個方法。在以下範例中，將創建一個在 javax.swing.JFrame 實例上調用 toFront 方法的 ActionListener。

myButton.addActionListener(
    (ActionListener)EventHandler.create(ActionListener.class, frame, "toFront"));

當按下 myButton 時，將執行 frame.toFront() 語句。通過定義 ActionListener 介面的新實作並將其實例添加到按鈕中，使用者可以獲得同樣的效果，且具有額外的編譯時型別安全：

//Equivalent code using an inner class instead of EventHandler.
myButton.addActionListener(new ActionListener() {
    public void actionPerformed(ActionEvent e) {
        frame.toFront();
    }
});

EventHandler 的另一種最簡單用法是從偵聽器介面（通常是一個事件物件）中的方法的第一個參數中提取屬性值，並用其設置目標物件中的屬性值。在以下範例中，將創建一個 ActionListener，它將目標 (myButton) 物件的 nextFocusableComponent 屬性設置為事件的 "source" 屬性的值。

EventHandler.create(ActionListener.class, myButton, "nextFocusableComponent", "source")

這將對應於以下內部類別實作：

//Equivalent code using an inner class instead of EventHandler.
new ActionListener() {
    public void actionPerformed(ActionEvent e) {
        myButton.setNextFocusableComponent((Component)e.getSource()); 
    }
}

也可以創建一個只是將傳入事件物件傳遞給目標動作的 EventHandler。如果 EventHandler.create 中的第四個參數為空字元串，則事件的傳遞方式如下：

EventHandler.create(ActionListener.class, target, "doActionEvent", "")

這將對應於以下內部類別實作：

//Equivalent code using an inner class instead of EventHandler.
new ActionListener() {
    public void actionPerformed(ActionEvent e) {
        target.doActionEvent(e);
    }
}

EventHandler 最常見的用法可能是從事件物件的 source 中提取屬性值，並將此值設置為目標物件的屬性值。在以下範例中，將創建一個 ActionListener，它將目標物件的 "label" 屬性設置為事件源的 "text" 屬性的值（"source" 屬性的值）。

EventHandler.create(ActionListener.class, myButton, "label", "source.text")

這將對應於以下內部類別實作：

//Equivalent code using an inner class instead of EventHandler.
new ActionListener {
    public void actionPerformed(ActionEvent e) {
        myButton.setLabel(((JTextField)e.getSource()).getText()); 
    }
}

可以使用以 "." 字元分隔的任意數量的屬性前綴來“限定”事件屬性。採用出現在 "." 字元前面的“限定”名稱作為將應用於事件物件的屬性名稱，最左邊的最先應用。

例如，以下動作偵聽器

EventHandler.create(ActionListener.class, target, "a", "b.c.d")

可以寫成以下內部類別（假定所有屬性都有規範的獲取方法並返回適當的型別）：

//Equivalent code using an inner class instead of EventHandler.
new ActionListener {
    public void actionPerformed(ActionEvent e) {
        target.setA(e.getB().getC().isD()); 
    }
}

也可以使用以 "." 字元分隔的任意數量的屬性前綴來「限定」目標屬性。例如，以下動作偵聽器：

   EventHandler.create(ActionListener.class, target, "a.b", "c.d")
 

可以寫成以下內部類別（假定所有屬性都有規範的獲取方法並返回適當的型別）：

   //Equivalent code using an inner class instead of EventHandler.
   new ActionListener {
     public void actionPerformed(ActionEvent e) {
         target.getA().setB(e.getC().isD()); 
    }
}

由於 EventHandler 最終依賴反射來調用方法，所以建議不要以重載方法為目標。 例如，如果目標是類別 MyTarget 的一個實例，而 MyTarget 定義如下：

   public class MyTarget {
     public void doIt(String);
     public void doIt(Object);
   }
 

那麼方法 doIt 被重載。EventHandler 將基於源調用恰當的方法。如果源為 null，那麼兩個方法都可以，具體調用哪個方法是不確定的。因此，建議不要以重載方法為目標。

從以下版本開始：

1.4

另請參見：

Proxy, EventObject

建構子摘要

EventHandler(Object target, String action, String eventPropertyName, String listenerMethodName)
創建一個新的 EventHandler 物件；通常使用 create 方法之一，而不是直接調用此建構子。

方法摘要

static <T> T	create(Class<T> listenerInterface, Object target, String action) 創建 listenerInterface 的實作，在該實作中，偵聽器介面中的所有 方法都會將處理程序的 action 應用到 target。
static <T> T	create(Class<T> listenerInterface, Object target, String action, String eventPropertyName) 創建 listenerInterface 的實作，在該實作中，所有 方法都會將事件表達式的值 eventPropertyName 傳遞給語句中的最終方法 action，後者被應用於 target。
static <T> T	create(Class<T> listenerInterface, Object target, String action, String eventPropertyName, String listenerMethodName) 創建 listenerInterface 的實作，在該實作中，名為 listenerMethodName 的方法將事件表達式的值 eventPropertyName 傳遞給語句中的最終方法 action，後者被應用於 target。
String	getAction() 返回此事件處理程序將設置的目標的可寫屬性名稱，或者此事件處理程序將在目標上調用的方法名稱。
String	getEventPropertyName() 返回應該在應用於目標的動作中使用的事件屬性。
String	getListenerMethodName() 返回將觸發動作的屬性名稱。
Object	getTarget() 返回此事件處理程序將為其發送訊息的物件。
Object	invoke(Object proxy, Method method, Object[] arguments) 從事件中提取適當屬性值，並將其傳遞到與此 EventHandler 相關聯的動作。

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

建構子詳細資訊

EventHandler

public EventHandler(Object target,
                    String action,
                    String eventPropertyName,
                    String listenerMethodName)

創建一個新的 EventHandler 物件；通常使用 create 方法之一，而不是直接調用此建構子。有關 eventPropertyName 和 listenerMethodName 參數的完整描述，請參考 create 的一般形式。

參數：

target - 將執行動作的物件

action - 目標上屬性或方法的（可能受限定的）名稱

eventPropertyName - 傳入事件的可讀屬性的（可能受限定的）名稱

listenerMethodName - 應該觸發該動作的偵聽器介面中的方法名稱

另請參見：

EventHandler, create(Class, Object, String, String, String), getTarget(), getAction(), getEventPropertyName(), getListenerMethodName()

方法詳細資訊

getTarget

public Object getTarget()

返回此事件處理程序將為其發送訊息的物件。

返回：

此事件處理程序的目標

另請參見：

EventHandler(Object, String, String, String)

getAction

public String getAction()

返回此事件處理程序將設置的目標的可寫屬性名稱，或者此事件處理程序將在目標上調用的方法名稱。

返回：

此事件處理程序的動作

另請參見：

EventHandler(Object, String, String, String)

getEventPropertyName

public String getEventPropertyName()

返回應該在應用於目標的動作中使用的事件屬性。

返回：

事件屬性

另請參見：

EventHandler(Object, String, String, String)

getListenerMethodName

public String getListenerMethodName()

返回將觸發動作的屬性名稱。返回值為 null 表示偵聽器介面中的所有方法都將觸發該動作。

返回：

將觸發該動作的方法名稱

另請參見：

EventHandler(Object, String, String, String)

invoke

public Object invoke(Object proxy,
                     Method method,
                     Object[] arguments)

從事件中提取適當屬性值，並將其傳遞到與此 EventHandler 相關聯的動作。

指定者：

介面 InvocationHandler 中的 invoke

參數：

proxy - 代理物件

method - 偵聽器介面中的方法

arguments - 套件含傳入代理實例上方法調用的參數值的物件陣列，如果介面方法不使用參數，則為 null。基本型別的參數被包裹在適當基本外覆器類別（如 java.lang.Integer 或 java.lang.Boolean）的實例中。

返回：

對目標應用該操作的結果

另請參見：

EventHandler

create

public static <T> T create(Class<T> listenerInterface,
                           Object target,
                           String action)

創建 listenerInterface 的實作，在該實作中，偵聽器介面中的所有 方法都會將處理程序的 action 應用到 target。此方法是通過調用其他更常見的 create 方法實作來實作的，其中 eventPropertyName 和 listenerMethodName 都採用 null 值。有關 action 參數的完整描述，請參考 create 的一般形式。

要創建一個使用 dialog.show() 顯示 JDialog 的 ActionListener，使用者可以編寫以下程式碼：

EventHandler.create(ActionListener.class, dialog, "show")

參數：

listenerInterface - 要為其創建代理的偵聽器介面

target - 將執行動作的物件

action - 目標上的某個方法或（可能受限定的）屬性的名稱

返回：

實作 listenerInterface 的物件

拋出：

NullPointerException - 如果 listenerInterface 為 null

NullPointerException - 如果 target 為 null

NullPointerException - 如果 action 為 null

另請參見：

create(Class, Object, String, String)

create

public static <T> T create(Class<T> listenerInterface,
                           Object target,
                           String action,
                           String eventPropertyName)

創建 listenerInterface 的實作，在該實作中，所有 方法都會將事件表達式的值 eventPropertyName 傳遞給語句中的最終方法 action，後者被應用於 target。此方法是通過調用更常見的 create 方法實作來實作的，其中 listenerMethodName 採用 null 值。有關 action 和 eventPropertyName 參數的完整描述，請參考 create 的一般形式。

要創建一個將 JLabel 的文本設置為傳入事件 JTextField 源的文本值的 ActionListener，可以使用以下程式碼：

EventHandler.create(ActionListener.class, label, "text", "source.text");

這等同於以下程式碼：

//Equivalent code using an inner class instead of EventHandler.
new ActionListener() {
    public void actionPerformed(ActionEvent event) {
        label.setText(((JTextField)(event.getSource())).getText());
     }
};

參數：

listenerInterface - 要為其創建代理的偵聽器介面

target - 將執行動作的物件

action - 目標上的某個（可能受限定的）屬性或方法的名稱

eventPropertyName - 傳入事件的某個可讀屬性的（可能受限定的）名稱

返回：

實作 listenerInterface 的物件

拋出：

NullPointerException - 如果 listenerInterface 為 null

NullPointerException - 如果 target 為 null

NullPointerException - 如果 action 為 null

另請參見：

create(Class, Object, String, String, String)

create

public static <T> T create(Class<T> listenerInterface,
                           Object target,
                           String action,
                           String eventPropertyName,
                           String listenerMethodName)

創建 listenerInterface 的實作，在該實作中，名為 listenerMethodName 的方法將事件表達式的值 eventPropertyName 傳遞給語句中的最終方法 action，後者被應用於 target。其他所有偵聽器方法不執行任何操作。

eventPropertyName 字元串用來從傳遞給目標方法的傳入事件物件中提取值。一般情況下目標方法不帶任何參數，在這種情況下 eventPropertyName 應該使用 null 值。此外，如果希望傳入事件物件直接傳遞給目標方法，則應該使用空字元串。eventPropertyName 字元串的格式是一個方法或屬性序列，其中從傳入事件物件開始，每一個方法或屬性都應用於前一個方法所返回的值。語法如下：propertyName{.propertyName}* 其中 propertyName 與方法或屬性比對。例如，要從 MouseEvent 中提取 point 屬性，可以使用 "point" 或 "getPoint" 作為 eventPropertyName。要從具有 JLabel 源的 MouseEvent 中提取 "text" 屬性，可以使用以下值之一作為 eventPropertyName："source.text"、"getSource.text"、"getSource.getText" 或者 "source.getText"。如果無法找到某個方法，或者作為調用方法的過程中產生某個異常，則在指派時將拋出 RuntimeException。例如，如果傳入事件物件為 null，且 eventPropertyName 為非 null 或非空(null)，則將拋出 RuntimeException。

action 參數的格式與 eventPropertyName 參數相同，其中最後一個屬性名標識一個方法名或可寫屬性。

如果 listenerMethodName 為 null，則介面中的所有 方法都會觸發將在 target 上執行的 action。

例如，要創建一個 MouseListener，使其在每次按下鼠標按鍵時，都將目標物件的 origin 屬性設置為傳入 MouseEvent 的位置（即 mouseEvent.getPoint() 的值），則應編寫以下程式碼：

EventHandler.create(MouseListener.class, "mousePressed", target, "origin", "point");

這相當於編寫一個 MouseListener，其中除 mousePressed 以外的所有方法都是無操作：

//Equivalent code using an inner class instead of EventHandler.
new MouseAdapter() {
    public void mousePressed(MouseEvent e) {
        target.setOrigin(e.getPoint());
    }
}
 

參數：

listenerInterface - 要為其創建代理的偵聽器介面

target - 將執行動作的物件

action - 目標上的某個（可能受限制的）屬性或方法的名稱

eventPropertyName - 傳入事件的某個可讀屬性的（可能受限定的）名稱

listenerMethodName - 應觸發該動作的偵聽器介面中的方法名稱

返回：

實作 listenerInterface 的物件

拋出：

NullPointerException - 如果 listenerInterface 為 null

NullPointerException - 如果 target 為 null

NullPointerException - 如果 action 為 null

另請參見：

EventHandler