# Component
`Component` 基本上是 GXT widget 的共同祖先。
`Component` 有提供 `enable()`、`disable()` 也有 setter 形式的 `setEnable()`。 也就是說，有別於 GWT 只有某些 widget 才有 `setEnable()`， 所有的 GXT widget 都可以有 enable / disable 的狀態。 各式 container 的 `setEnable()` 會連小孩也一起呼叫 `setEnable()`。
## Container 系
（謎之聲：為什麼 `TabPanel` 不是... ＝＝?）
### Container
所有的 widget 都可以設定 `HasMargins` 的 layout data， 無論是加在哪一個 container 上都會有 margin 的效果。 這是因為 `Container.onInser()` 會特別檢查 `child.getLayoutData()` 是否為 `HasMargins` 並作處理。
### SimpleContainer
會自動讓小孩的大小跟自己的大小一樣
### BorderLayoutContainer
假設 `northLD` 的 size 設定為 100、split 設定為 true（北邊區域可以動態調整大小）， 調整北邊區域的大小會改變 `northLD.getSize()` 值。
### ContentPanel
在 ui.xml 當中作 `contentPanel.addButton()` 的方法：
```markup
```
原來一個 `` 只能塞一個 widget，我之前都誤會它了 \[炸]。
### Dialog
要知道使用者對 `Dialog` 做了什麼事情，是掛 `addDialogHideHandler()` 這個 handler。 從 `DialogHideEvent.getHideButton()` 可以知道是按下哪個 button。 不知道該說巧妙還是該說 WTF...... Orz
#### PredefinedButton 的 I18N ##\#
從 API 上來看，要改變 `PredefinedButton`（對應的 `TextButton`）的顯示字串， 就是透過 `setDialogMessages()` 設定 `DialogMessages`。 實際上，這個 API 根本有問題...... \[怒]，
以 `ConfirmMessageBox` 為例，流程大概是
```
constructor
setPredefinedButtons()
清空既有 button
createButtons()
getText()
讀 getDialogMessages() 設定對應字串
```
`setDialogMessages()` 純粹是 setter，沒有重設顯示字串， 所以 new 完 instance 再 `setDialogMessages()` 也沒意義。
最直白的 workaround 是
```
msgBox.getButton(PredefinedButton.OK).setText("OK 的啦");
```
但是被嫌棄這樣違背 API 設計 / OO 原則（阿就原本 API 設計爛阿幹 T\_\_T）， 所以找出第二種 workaround
```
msgBox.setDialogMessages(myDialogMessages);
msgBox.setPredefinedButton(PredefinedButton.YES, PredefinedButton.NO);
```
簡單地說，就是再次呼叫 `setPredefinedButtons()`、重新製造 button， 此時就會用 `myDialogMessages` 來設定顯示字串啦。
雖然這某種程度還是破壞了 `ConfirmMessageBox` 的封裝， 不過從程式碼當中可以清楚知道到底有哪些 button， 然後學理上 `myDialogMessages` 整個 project 只會有一份，好像也不錯啦。
### AccordionLayoutContainer
小孩只能是 `ContentPanel`，而且（應該說「所以」？） `ContentPanel` 還能塞 `AccordionLayoutAppearance` 來改變 `ContentPanel` 的外觀。
### HBox / VBox
做了 `setPack()`，會發現小孩的 layoutData 不管怎麼設定 flex 值， 都不會有預其中的大小變化，而是以小孩原本的大小呈現。 目前這是實驗結果，還沒追 source code \[死]。
### HorizontalLayoutContainer / VerticalLayoutContainer
`HorizontalLayoutData` 的 width 數值邏輯為 （`VerticalLayoutData` 的 height 比照辦理）：
* x > 1：小孩的寬度就是 x
* x = -1：小孩自己決定自己的寬度（容易錯，使用注意）
* x < -1：小孩的寬度是「爸爸的寬度加上 x」
換句話說，就是只留 -x 的寬度給兄弟姊妹
* 0 < x <= 1：小孩的寬度是「爸爸**剩下**的寬度乘上 x」。
舉實際的例子，假設一個 `HorizontalLayoutContainer` 的寬度是 1000， 底下有四個小孩、layoutData 的 width 設定值與實際計算完的寬度分別為：
* 100→100
* 0.5→(1000 - 100 - 200 - 600) \* 0.5 = 50
* -1（實際上是 200）→200
* -400→600
> **備註 ######**
>
> GXT API 文件上針對 `0 < x <= 1` 這段沒有說明仔細，導致跟實際結果有出入。 以上是追 source code 的結果，詳情可以參閱 `HorizontalLayoutContainer.doLayout()`， 因為 `0 < x <=1` 的需求，所以要兩次迴圈才有辦法決定（如果有小孩設定 -1 可能不只）。 第一次迴圈決定 `pw`，然後第二次迴圈才依照 `pw` 實際指定小孩的寬度。
## 輸入系
### ComboBox
label 必須是 unique 的， 這是因為 `ComboBox.getValue()` 會用當下的 `getText()` 去反找實際的 item instance， 所以如果有兩個 item 是 label 是一樣的， 會導致選第二個 item 後的 `getValue()` 還是得到第一個 item instance。 以 UI 面來說，這是沒有問題的──使用者本來就無法分辨他到底是選到哪一個...... Orz
`setTriggerAction(TriggerAction.ALL)` 可以在使用者再次要求下拉選單時顯示所有值。 像 `TimeField` 就非常需要... Orz
要注意 ComboBox 的顯示值（或著說 `LabelProvider.getLabel()` 的回傳值）不能是 `\n` 結尾。 顯示上是不會有問題、也會觸發 `SelectionEvent`， 但是在 onblur 的時候不會觸發 `ValueChangeEvent`、ComboBox 的值會消失。
如果 item 的值是 null，顯示時不會觸發 `LabelProvider.getLabel()`， 在 expand 時選單會多一個高度很詭異的空白行。
`setEditable(false)` 好像直接包含 `setSelectOnFocus()` 與 `setForceSelection()` 的功能， 此乃實驗結果，有待 trace code 證明 \[死]。 另外，如果搭配 `FieldLabel` 使用，居然點 `FieldLabel` 的 label 也會觸發 focus 效果， 這什麼黑魔法阿阿阿阿... Orz
如果 extend `ComboBox`，然後想要在裡頭用自己定義的 enum `PKG_NAME.Direction`， 在 Eclipse 當中會預設使用 `com.google.gwt.i18n.client.HasDirection.Direction` （還不用 import... WTF ＝＝"）。 目前唯一合理的解釋是 `ComboBox` 的祖先 `ValueBaseField` 有實作 `HasDirectionEstimator` 跟 `AutoDirectionHandler.Target`， 裡頭有 import `com.google.gwt.i18n.client.HasDirection.Direction`， 可是這還是不科學阿阿阿...... Orz
详细说明 `setTriggerAction()`、`setForceSelection()`、`setEditable()`、 `setSelectOnFocus()` 的作用和相互影响。
* setTriggerAction()是否显示全部下拉框中全部内容。 如果是 TriggerAction.QUERY，只能显示根据 ComboBox 内容筛选过后的内容。 如果是 TriggerAction.ALL，在输入的时候会筛选对应内容， 但是在按下下拉框按钮的时候会显示全部内容。 默认值：TriggerAction.QUERY
* setForceSelect()是否允许 ComboBox 中的值不在下拉框中。 如果是 true，ComboBox 输入的值不在下拉框中，lose focus 后会清空。 （如果使用setValue()设定一个不在下拉框的输入值不会清空） 默认值：false
* setEditable()是否允许 ComboBox 中直接输入值。 如果是 false，无法在 ComboBox 中直接输入值。 默认值：true
* setSelectOnFocus()是否在 focus 的时候出现反白的效果。 如果是 true，会在 focus 的时候选中 ComboBox 中的值，出现反白的效果 (只在鼠标点击的时候出现效果，松开后效果消失)，使用 Tab 键进入 ComboBox 不会出现这个效果。 默认值：false
* 打V表示符合描述。打X表示不符合描述。 （包括使用 setValue() 的情况）
| setTriggerAction() | setForceSelect() | setEditable() | setSelectOnFocus() | 下拉框只显示 ComboBox 筛选过内容 | 允许 ComboBox 中的值不在下拉框中 | 允许 ComboBox 中输入值 | 在 focus 的时候不出现反白的效果 |
| :-----------------: | :--------------: | :-----------: | :----------------: | :-------------------: | :-------------------: | :--------------: | :-----------------: |
| TriggerAction.QUERY | true | true | true | V | X | V | X |
| TriggerAction.QUERY | true | true | false | V | X | V | V |
| TriggerAction.QUERY | X | false | X | V | V | X | V |
| TriggerAction.QUERY | false | true | true | V | V | V | X |
| TriggerAction.QUERY | false | true | false | V | V | V | V |
| TriggerAction.ALL | true | true | true | X | X | V | X |
| TriggerAction.ALL | true | true | false | X | X | V | V |
| TriggerAction.ALL | X | false | X | X | V | X | V |
| TriggerAction.ALL | false | true | true | X | V | V | X |
| TriggerAction.ALL | false | true | false | X | V | V | V |
### DateField
#### 觸發 setValue() 的來源 ##\#
**DatePicker ####**
* 当 new 一个 `DateField` 时，就 new 了一个 `DateCell` 和一个 `DateTimePropertyEditor`；
* 当使用者点击画面上的 `DateCell` 时，会通过 `DateCell.onTriggerClick()` 呼叫 `DateCell.expand()`，在这里 new 了一个 `DatePicker`；
* 因为在 `DatePicker` 的 `Constructor` 中实现了 `sinkEvents()`，而且在 `onBrowserEvent()` 中实现了 `ONCLICK|ONMOUSEOVER` 等的具体操作，所以当画面上发生 ONCLICK Event 则会呼叫 `DatePicker.onClick(Event)`；
**按下 today #####**
* 使用者在出现的 date picker 上点击【today】时，作 `addSelectHandler()` 让 select event 发生时去呼叫 `selectToday()`，结果呼叫 `DatePicker.setValue(Date, boolean)`，设置 `value` 的值；
**點擊日曆上的日期 #####**
* 当使用者触发 ONCLICK Event 时，呼叫 `DatePicker.onClick(Event)`，若触发为当月的某一天则呼叫 `DatePicker.onDayClick(XElement)`；然后通过 `DatePicker.handleDateClick(XElement, String)` 呼叫 `DatePicker.setValue(Date, boolean)`，设置 `value` 的值；
**直接輸入字串 ####**
* 当 new 一个 `DateField` 时，就 new 了一个 `DateTimePropertyEditor` 和一个 `DateCell`；
* 当使用者在 text 中输入数据时，呼叫 `ValueBaseField.setValue(T)`，实际上是呼叫了 `CellComponent.setValue(C, boolean, boolean)`，在这里设置 `value` 的值；
* (确实没有找到回到 `DatePicker.setValue()` 的地方，但确实这里应该会做 `resetTime()`，我也没有找到在什么时候做 `resetTime()` 的，/(ㄒoㄒ)/\~\~)
**setValue() 的處理 ####**
* 在 `DatePicker.setValue(date, true)` 時會作 `this.value = new DateWrapper(date).resetTime()`，
`resetTime()` 的 source code 與結果有點對不起來。
就結果而言，會將指定日期的時間部份設定為零點零分零秒。
## 其他
### Grid
#### GridView ##\#
`GridView.setForceFit()`，如果設定 `true` 則 Grid 不會出現橫向 scroll bar； 沒有作 `setFixed(true)` 的 column 會依設定 width 為比例分配剩餘的寬度。
`GridView` 可以設定 `GridViewConfig`，藉此設定 row / column 的 style── 正確的說是加掛 style name。 實務上很吃 CSS 技能所以不好用，還有導致其他 style 亂掉的風險。 要處理 style 還是用 `ColumnConfig.setCell()`， 在自訂的 cell 裡頭設計比較容易且影響範圍可控。
可以透過 `GridView.getScroller()` 控制 `Grid` 的 scroll 狀態。 當 `refresh()` 結束之後不想強制 scroll 回左上角，就必須得靠這招。
**GroupingView ####**
如果希望資料初次載入後呈現 collapse 的樣子， 在操作完 store 之後對 view 作 `collapseAllGroups()` 是不正確的作法， 因為之後只要再對 view 作 `refresh()`， 原本沒有 expand 的 group 也會 expand。 正確作法是在 grid 初始時作 `GroupingView.setStartCollapsed(true)`。
#### AbstractGridEditing ##\#
`setEditableGrid()` 如果傳入 null 值是表示移除 edit 的效果， 因為一開始會作 `groupRegistration.removeHandler()`，然後在傳入值不為 null 才會掛相關 handler。 這在初始化設定（尤其搭配 ui.xml）時要特別注意 \[淚目]
使用者的編輯行為會透過 `GridEditing` 影響 `Grid` 的 `Store`， 實際作為是增加 `Change` 跟 `Record`。 目前看起來，`Store` 只有提供兩個對應的 method：`commitChanges()` 跟 `rejectChanges()` 來清空 `modifiedRecords`→才會讓畫面上的 dirty 樣子消失（應該是 `StoreUpdateEvent` 的結果）。 `commitChanges()` 跟 `rejectChanges()` 都會觸發 `StoreUpdateEvent`， 實驗結果：`rejectChanges()` 如果影響 n 個 item，就會炸 n 個 `StoreUpdateEvent`。
從 `Store.getModifiedRecords()` 可以得到有改變（dirty）的 item：
```java
for (Store.Record r : store.getModifiedRecords()) {
Foo fooInstance = r.getModel();
//此時 fooInstance 的內容為初始值，可以趁機作一些事情（？）
}
```
要讓 `fooInstance` 的內容變成現在的值，有幾種作法：
* `r.commit(boolean)`：單筆
* `store.commitChanges()`：整個 store
* 根據 `Record` / `Change` 來修改 `fooInstance` \[暈]
至於要發 RPC、萬一 RPC 失敗要能 rollback... 目前還沒有想法 \[死]
### LabelToolItem
`LabelToolItem` 轉換成 DOM 就只是一個 `div` 包一個字串，當然有掛一些 css（沒有特別的內容）， 除了 package name 很奇怪之外，基本上應該可以視為 GXT 版的 label。 （謎之聲：之前測試不知道是測試到哪裡去了... (艸 ）
### TabPanel
在 ui.xml 當中只能這樣寫
```markup
```
有點討厭，不過就算自己設計好像也沒辦法改變什麼 Orz
### Toggle
如果只是把 `HasValue` 加到 `Toggle` 當中、畫面也還沒進行任何操作， 畫面顯示是會正常的，但是 `toggle.getValue()` 會是 null。 所以 `toggle.add()` 完還是 `toggle.setValue()` 一下比較保險。
### DrawComponent
獨立出去紀錄在 [DrawComponent](https://gwt.dontcareabout.us/gxt/drawcomponent)。
## DnD
`new DragSource(dSource)` 會讓 `dSource` 變成可以 drag 的 widget， 實際上要看實作，像 `TreeDragSource` 就是讓 tree 的 item 變成可以 DnD。 `new DropTarget(dTarget)` 會讓 `dTarget` 變成可 drop 的對象。 在沒有特別的設定下（也就是 default group），任何的 `DropTarget` 都會接收任何 `DragSource` 的 DnD 行為。 反過來說，如果 `dSource.setGroup("5566")`，那麼 `dTarget` 必須也要是 5566 這個 group， 才有辦法接收源自於 `dSource` 的 DnD 行為。
如果 `parent`、`child` 這兩個 widget 都是 drop target（不考慮 group）， `parent` 跟 `child` 同時在畫面上、且 `parent` 包含 `child`， 則如果在 `child` 上作 drop 的動作，只會觸發 `child` 的 `DndDropHandler`、 而不會觸發 `parent` 的 `DndDropHandler`。