/*
 * ComponentAdapter.java
 *
 * Created on 2007年5月2日, 下午11:29
 *
 * To change this template, choose Tools | Template Manager
 * and open the template in the editor.
 */
package dyno.swing.designer.beans;

import dyno.swing.designer.properties.ValidationException;

import java.awt.Component;
import java.awt.Graphics;
import java.awt.Image;
import java.awt.Rectangle;
import java.awt.event.MouseEvent;

import java.beans.BeanInfo;
import java.util.ArrayList;

import javax.swing.JPopupMenu;


/**
 * 組件適配器接口，可看做是BeanInfo的擴展。
 * 主要目的是為具體組件提供特殊設(shè)計行為
 *
 * @author William Chen
 */
public interface ComponentAdapter {
    /**
     * 獲取該Component組件類型的BeanInfo
     * @return 獲取該組件對應(yīng)的beanInfo
     */
    BeanInfo getBeanInfo();


    Image getIcon(int iconKind);
    /**
     * 克隆一個該類型的組件。該方法主要用于復(fù)制、剪切和粘帖組件時使用。克隆原來的組件，要求
     * 克隆后的組件和原始組件具有相同的屬性。
     *
     * @param source源組件
     * @return 克隆組件
     */
    Component clone();

    /**
     * 在組件選擇面板上選擇了組件類型后，在設(shè)計界面上跟隨鼠標(biāo)移動用來代表當(dāng)前要添加組件的圖形
     * 一般使用組件自身的圖形代替。
     *
     * @param component 要添加的組件
     * @param g 當(dāng)前設(shè)計器的圖形上下文對象
     */
    void paintComponentMascot(Graphics g);


    /**
     * 當(dāng)鼠標(biāo)在設(shè)計界面上點擊時，調(diào)用鼠標(biāo)所在組件適配器的componentClick方法進(jìn)行處理。
     * 主要是用于解決JTabbedPane在設(shè)計狀態(tài)時能進(jìn)行面板的切換。
     *
     * @param e 當(dāng)前鼠標(biāo)事件
     *
     * @return 是否繼續(xù)處理該鼠標(biāo)事件，如果該鼠標(biāo)事件該預(yù)示這拖拽、選擇等行為的開始，應(yīng)該返回true，以便后面的事件處理繼續(xù)進(jìn)行
     */
    boolean componentClicked(MouseEvent e);

    /**
     * 當(dāng)鼠標(biāo)在此設(shè)計組件上右鍵點擊時，該方法根據(jù)上下文和組件類型提供彈出響應(yīng)的菜單
     *
     * @param 引發(fā)彈出菜單的鼠標(biāo)事件
     *
     * @return 彈出菜單
     */
    JPopupMenu getContextPopupMenu(MouseEvent e);

    /**
     * 為當(dāng)前組件創(chuàng)建描述屬性表的model, 分組返回
     * @return BeanPropertyModel
     */
    ArrayList<GroupModel> getBeanPropertyModel();

    /**
     * 為當(dāng)前組件創(chuàng)建事件描述表，分組返回
     */
    ArrayList<GroupModel> getEventPropertyModel();
    /**
     * 提供雙擊設(shè)計器的編輯器
     * @param bean 鼠標(biāo)雙擊的被設(shè)計組件
     * @param x
     * @param y 鼠標(biāo)坐標(biāo)在bean內(nèi)的位置
     * @return 被設(shè)計的編輯器
     */
    DesignerEditor getDesignerEditor(int x, int y);

    /**
     * 檢驗value對于bean來說是否有效
     * @param bean被編輯的組件
     * @param value新編輯的值
     * @throws 如果值不合法，拋出的異常，異常中包含錯誤消息
     */
    void validateBeanValue(Object value)
        throws ValidationException;

    /**
     * 更改bean的值
     * @param 需要更新的bean
     * @param 新的value
     */
    void setBeanValue(Object value);

    /**
     * 獲取當(dāng)前編輯的bean的值
     * @param bean 被編輯的bean
     * @return 當(dāng)前被編輯的bean的值
     */
    Object getBeanValue();

    /**
     * 獲取DesignerEditor的編輯放置的位置
     * @param bean 鼠標(biāo)雙擊的被設(shè)計組件
     * @param x
     * @param y 鼠標(biāo)坐標(biāo)在bean內(nèi)的位置
     * @return 編輯器應(yīng)該放置的位置，相對于bean的相對位置
     */
    Rectangle getEditorBounds(int x, int y);
    /**
     * 實例化組件的適配器后，在這兒進(jìn)行初始化
     */
    void initialize();    
}