TreeView DataWindow設計(二)
看過上一篇的簡單說明後，現在就進行實作了範例程式。
※TreeView DataWindow名稱過長，文中會使用TVDW(大寫)來代表其意義。
※DataWindow簡稱DW(大寫)
※DataStore簡稱DS(大寫)
(一)先來看看程式主畫面：
這個畫面的左半邊是展示用的資料，我這邊的展示設定是某家傳直銷的組織圖，因為這樣的組織圖很容易用來表現樹狀結構的特性，如果你不知道傳直銷組織的話，問一下親朋好友應該會有人解釋得很好(?)吧，傳直銷的組織特性就像是樹狀結構圖，基本上分為上線(通常是推薦人)以及下線(通常是所屬會員或是組織成員)；上線如同父節點(Parent)，下線如同子項目(Child)，所以如果能理解的話應該不難理解畫面左邊的列表意思。
現在的目的就是要如何把這樣的條列資料展現成樹狀組織圖，以供列表或是操作了。
主畫面的右半上方是TVDW的產生示範功能，右半下方則是TVDW本身了。
[產生]：用來產生TVDW的樹狀組織圖，資料來源則是依據主畫面左半邊的資料。
[停止]：由於資料多達300多筆，產生會消耗許多時間，如果想中途停止，只要按這個按鈕就好了。
[刪除]：當你選擇了某個項目節點後，按下此鈕，會將該項目連同下屬所有子項目一並全數刪除。
[預覽列印]：列印時的畫面預覽，用來檢視畫面是否超出紙張定義。
[內部資料檢視]：這算是特殊的功能了，上一篇有提到這個TVDW有個DS在儲存實際樹狀資料屬性，理論上使用者不需要也不可以直接檢視或修改該DS內容，這僅是提供程式設計師debug以及理論驗證的用途罷了。
[全部展開]：這個是以最基本的根項目(Root)為展開的動作，展開時各節點全部展開(註一)。
[全部收合]：這個是以最基本的根項目(Root)為收合的動作，收合時各節點全部收合(註一)。
[選擇子項全開]：以選擇的項目下屬項目節點全部展開，展開時各節點全部展開(註一)。
[選擇子項全收]：以選擇的項目下屬項目節點全部收合，收合時各節點全部收合(註一)。
[細部設定變更]：在TVDW產生時會依照某些特性設定值作為基本依據，如果需要更改某些特別屬性可以變更下列屬性質，以達所需要效果，其數值單位為PowerBuilder Unit，特別要注意的是屬性設定必須在TVDW"產生"畫面前進行設定，否則無效：
起始X、起始Y：這是初始項目的繪製起點座標，其它項目節點再進行繪置時將會受此座標值影響。
X間隔、Y間隔：可以決定項目與項目間的顯示距離，若字型放大時通常都需要調整，有時候也是因為版面需要才會進行調整。
項目寬、項目高：可調整的顯示項目寬與高，若字型變更或是項目邊框變更，則可能需要進行調整，另外需要注意的是，最底層項目的寬度不顯示的部份如果超過可列印頁面寬度時，儘管在預覽時，可能沒有跳頁，但實際列印時可能會產生跳頁的現象，此時就得進行調整。
字體：可調整項目文字字體大小，但須注意項目寬度、高度、間隔並不會自動調整。
項目邊框：可以改變項目顯示邊框形式，預設是無邊框。
允許編輯：此TVDW預設可以在項目上點及滑鼠兩次，可以編輯該項目文字(Label)內容，若是不希望使用者編輯可以將此屬性設定關閉(False)。
允許選擇反白：此TVDW在預設情況下使用者使用滑鼠單擊項目時會產生"選擇反白"，若是用於列印用途上時，不希望使用者點擊反白，可將此屬性設定關閉(False)。
(二)TVDW的操作Function：
(a)新增項目
@new id = of_AddItem(parent id , lebel text)
@new id = of_AddItem(Parent id , Label text , Properties string)
New id(Long)是新增項目成功後會回傳的編號，此編號在TVDW裡面是個唯一值。
Parent id(Long)是你要加入的父節點項目編號，若是要加在根節點(root)下，則設為0即可。
Label text(String)是項目顯示的文字。
Properties String(String)屬性描述字串，若不使用此字串則TVDW會依照預設屬性去新增項目，如果你想對某些項目使用特殊屬性，可以於新增該項目時使用屬性設定，底下簡單介紹屬性名稱與值的意義與用法，設定2個以上的屬性時屬性與屬性間使用"~t"做為區隔，屬性名稱與值使用"="做為區隔。
如：
*CollapseBmp項目收合時使用的圖片(僅BMP檔)。
*ExpandBmp項目展開時的圖片(僅BMP檔)。
**CollapseBmp與ExpandBmp若是只設定其中一個，則展開/收合都視為相同的圖片。
*Width項目寬度，當你有設定此屬性，"此項目"產生的寬度會以此為主，未設定則以預設為主。
*Height項目高度。
*FontColor項目文字顏色。
*FontBackColor項目底色。
*Event事件名稱，當使用者點擊此項目會觸發指定事件名稱的事件。
(b)刪除項目
@retcode = of_DeleteItem(id)
@retcode = of_DeleteItem(id , delete child)
retcode(Integer)是刪除項目回傳狀態1是成功，0是失敗，-1是錯誤。
id(Long)是要刪除的項目編號。
delete child(Boolean)是決定是否刪除下屬所有子項目與節點，如果不使用此參數，則視同為True(下屬子項目全數刪除)。
(c)收合項目
@of_Collapse(id)
@retcode = of_Collapse(id , Collapse All Child)
retcode(Integer)是收合項目回傳狀態1是成功，0是失敗，-1是錯誤。
id(Long)是要收合的項目編號。
Collapse All Child(Boolean)是決定是否收合下屬所有子項目與節點，如果不使用此參數，則視同為True(下屬子項目全數收合)。
(d)展開項目
@of_Expand(id)
@retcode = of_Expand(id , Expand All Child)
retcode(Integer)是展開項目回傳狀態1是成功，0是失敗，-1是錯誤。
id(Long)是要展開的項目編號。
Expand All Child(Boolean)是決定是否展開下屬所有子項目與節點，如果不使用此參數，則視同為False(只展開下屬1層級的子項目)。
(e)尋找項目
@id = of_FindItem(Label text , Start id)
id(Long)是找到的項目編號，若是找不到則會傳回0。
Label text(string)要尋找的項目內容文字，如果該標籤文字含有此文字，則代表找到。尋找文字的方式類似SQL語法的LIKE %S%。
Start id(Long)起始項目編號位置，如果為0，代表全部尋找，如果為某項目編號，則僅搜尋該項目下所有子項目為主。
(f)取得被選取的項目
@id = of_GetSelectItem()
id(Long)為傳回的項目編號，如果沒有項目被選取，則傳回0。
(g)取得父項目
@pid = of_GetItemParent(id)
pid(Long)為父項目的編號，若是失敗則傳回0，錯誤傳回-1。
id(Long)為尋找的項目編號。
(h)設定標題
此TVDW有個預設的標題可以設定
@of_SetTitle(Title text)
@of_SetTitle(Title text , Font size , Font face , Font color , Font Background color , Label transparent , Label x , Label y , Label width , Label Height)
Title text(String)標題文字內容。若是使用第一種用法，則所有屬性直皆為預設值。
Font size(Integer)字體大小。
Font Face(String)字型名稱。
Font color(Long)文字顏色。
Font Background color(Long)背景顏色。
Label transparent(Boolean)背景透明，當設定為透明(True)時，背景顏色會無效。
Label x(Long)標題標籤起始X座標(單位：powerbuilder unit)。
Label y(Long)標題標籤起始Y座標(單位：powerbuilder unit)。
Label width(Long)標題標籤寬度(單位：powerbuilder unit)。
Label Height(Long)標題標籤高度(單位：powerbuilder unit)。
(i)清除TVDW
@of_reset()
(j)檢視內部資料
@of_DataView(Show data)
Show data(Boolean)如果為true會開啟資料檢視視窗，Fasle則為關閉。
(k)取得項目標籤文字
@Label text = of_GetItemlabel(id)
Label text(String)取得的標籤文字內容。
id(Long)要取得標籤文字的項目編號。
(l)變更項目標籤文字
@retcode = of_SetItemLabel(id , Label text)
retcode(Integer)是變更項目標籤文字回傳狀態1是成功，0是失敗，-1是錯誤。
id(Long)要變更標籤文字的項目編號。
Label text(String)欲變更的標籤文字內容。
(m)取得項目附帶資料
@Data text = of_GetItemData(id)
Data text(String)取得項目的附帶資料。
id(Long)要取得附帶資料的項目編號。
(n)設定項目附帶資料
@retcode = of_SetItemData(id , Data text)
retcode(Integer)是設定項目附帶資料回傳狀態1是成功，0是失敗，-1是錯誤。
id(Long)要設定附帶資料的項目編號。
Label text(String)欲設定的附帶資料內容。
(三)TVDW的事件
雖然TVDW繼承自DataWindow物件，也擁有DataWindow的事件，但是由於使用方式特殊，因此請勿使用DataWindow原本的事件來攔截資料，因為攔截到的資料會有所錯誤。因此TVDW本身有定義好一部份事件以供設計者使用：
(a)ue_ItemClicked(x , y , row , id)滑鼠單擊事件(衍生自DW的Clicked事件)
x(Long)滑鼠X座標。
y(Long)滑鼠Y座標。
row(Long)資料運作DS的ROW位置。
id(Long)項目編號。
(b)ue_ItemDblClicked(x , y , row , id)滑鼠雙擊事件(衍生自DW的DoubleClicked事件)
x(Long)滑鼠X座標。
y(Long)滑鼠Y座標。
row(Long)資料運作DS的ROW位置。
id(Long)項目編號。
(c)retcode = ue_ItemChanging(id , Old Label , New Label)項目標籤變更事件
retcode(Integer)若是回傳非0值，則TVDW會拒絕項目標籤文字的變更。
id(Long)被變更標籤文字的項目編號
Old Label(String)舊的標籤文字資訊
New Label(String)新的標籤文字資訊，在此如果變更此變數內容，將會影響到變更的內容文字。
※TreeView DataWindow名稱過長，文中會使用TVDW(大寫)來代表其意義。
※DataWindow簡稱DW(大寫)
※DataStore簡稱DS(大寫)
(一)先來看看程式主畫面：
這個畫面的左半邊是展示用的資料，我這邊的展示設定是某家傳直銷的組織圖，因為這樣的組織圖很容易用來表現樹狀結構的特性，如果你不知道傳直銷組織的話，問一下親朋好友應該會有人解釋得很好(?)吧，傳直銷的組織特性就像是樹狀結構圖，基本上分為上線(通常是推薦人)以及下線(通常是所屬會員或是組織成員)；上線如同父節點(Parent)，下線如同子項目(Child)，所以如果能理解的話應該不難理解畫面左邊的列表意思。
現在的目的就是要如何把這樣的條列資料展現成樹狀組織圖，以供列表或是操作了。主畫面的右半上方是TVDW的產生示範功能，右半下方則是TVDW本身了。
[產生]：用來產生TVDW的樹狀組織圖，資料來源則是依據主畫面左半邊的資料。
[停止]：由於資料多達300多筆，產生會消耗許多時間，如果想中途停止，只要按這個按鈕就好了。
[刪除]：當你選擇了某個項目節點後，按下此鈕，會將該項目連同下屬所有子項目一並全數刪除。
[預覽列印]：列印時的畫面預覽，用來檢視畫面是否超出紙張定義。
[內部資料檢視]：這算是特殊的功能了，上一篇有提到這個TVDW有個DS在儲存實際樹狀資料屬性，理論上使用者不需要也不可以直接檢視或修改該DS內容，這僅是提供程式設計師debug以及理論驗證的用途罷了。
[全部展開]：這個是以最基本的根項目(Root)為展開的動作，展開時各節點全部展開(註一)。
[全部收合]：這個是以最基本的根項目(Root)為收合的動作，收合時各節點全部收合(註一)。
[選擇子項全開]：以選擇的項目下屬項目節點全部展開，展開時各節點全部展開(註一)。
[選擇子項全收]：以選擇的項目下屬項目節點全部收合，收合時各節點全部收合(註一)。
[細部設定變更]：在TVDW產生時會依照某些特性設定值作為基本依據，如果需要更改某些特別屬性可以變更下列屬性質，以達所需要效果，其數值單位為PowerBuilder Unit，特別要注意的是屬性設定必須在TVDW"產生"畫面前進行設定，否則無效：
起始X、起始Y：這是初始項目的繪製起點座標，其它項目節點再進行繪置時將會受此座標值影響。
X間隔、Y間隔：可以決定項目與項目間的顯示距離，若字型放大時通常都需要調整，有時候也是因為版面需要才會進行調整。
項目寬、項目高：可調整的顯示項目寬與高，若字型變更或是項目邊框變更，則可能需要進行調整，另外需要注意的是，最底層項目的寬度不顯示的部份如果超過可列印頁面寬度時，儘管在預覽時，可能沒有跳頁，但實際列印時可能會產生跳頁的現象，此時就得進行調整。
字體：可調整項目文字字體大小，但須注意項目寬度、高度、間隔並不會自動調整。項目邊框：可以改變項目顯示邊框形式，預設是無邊框。
允許編輯：此TVDW預設可以在項目上點及滑鼠兩次，可以編輯該項目文字(Label)內容，若是不希望使用者編輯可以將此屬性設定關閉(False)。
允許選擇反白：此TVDW在預設情況下使用者使用滑鼠單擊項目時會產生"選擇反白"，若是用於列印用途上時，不希望使用者點擊反白，可將此屬性設定關閉(False)。
※註一：若是一般的展開/收合(即是用滑鼠點擊項目節點前面的 +/-圖示)時，僅會對下屬1層進行展開/收合的動作，下屬第2層的展開/收合狀態會予以保留，若是使用全面展開/收合，則會將下屬所有層級項目屬性全部展開/收合。
(二)TVDW的操作Function：
(a)新增項目
@new id = of_AddItem(parent id , lebel text)
@new id = of_AddItem(Parent id , Label text , Properties string)
New id(Long)是新增項目成功後會回傳的編號，此編號在TVDW裡面是個唯一值。
Parent id(Long)是你要加入的父節點項目編號，若是要加在根節點(root)下，則設為0即可。
Label text(String)是項目顯示的文字。
Properties String(String)屬性描述字串，若不使用此字串則TVDW會依照預設屬性去新增項目，如果你想對某些項目使用特殊屬性，可以於新增該項目時使用屬性設定，底下簡單介紹屬性名稱與值的意義與用法，設定2個以上的屬性時屬性與屬性間使用"~t"做為區隔，屬性名稱與值使用"="做為區隔。
如：
ll_newid=of_additem(ll_pid,"鑽孔機","FontColor=12639424~tEvent=ue_tool~tExpandBmp=open.bmp")
*CollapseBmp項目收合時使用的圖片(僅BMP檔)。
*ExpandBmp項目展開時的圖片(僅BMP檔)。
**CollapseBmp與ExpandBmp若是只設定其中一個，則展開/收合都視為相同的圖片。
*Width項目寬度，當你有設定此屬性，"此項目"產生的寬度會以此為主，未設定則以預設為主。
*Height項目高度。
*FontColor項目文字顏色。
*FontBackColor項目底色。
*Event事件名稱，當使用者點擊此項目會觸發指定事件名稱的事件。
(b)刪除項目
@retcode = of_DeleteItem(id)
@retcode = of_DeleteItem(id , delete child)
retcode(Integer)是刪除項目回傳狀態1是成功，0是失敗，-1是錯誤。
id(Long)是要刪除的項目編號。
delete child(Boolean)是決定是否刪除下屬所有子項目與節點，如果不使用此參數，則視同為True(下屬子項目全數刪除)。
(c)收合項目
@of_Collapse(id)
@retcode = of_Collapse(id , Collapse All Child)
retcode(Integer)是收合項目回傳狀態1是成功，0是失敗，-1是錯誤。
id(Long)是要收合的項目編號。
Collapse All Child(Boolean)是決定是否收合下屬所有子項目與節點，如果不使用此參數，則視同為True(下屬子項目全數收合)。
(d)展開項目
@of_Expand(id)
@retcode = of_Expand(id , Expand All Child)
retcode(Integer)是展開項目回傳狀態1是成功，0是失敗，-1是錯誤。
id(Long)是要展開的項目編號。
Expand All Child(Boolean)是決定是否展開下屬所有子項目與節點，如果不使用此參數，則視同為False(只展開下屬1層級的子項目)。
(e)尋找項目
@id = of_FindItem(Label text , Start id)
id(Long)是找到的項目編號，若是找不到則會傳回0。
Label text(string)要尋找的項目內容文字，如果該標籤文字含有此文字，則代表找到。尋找文字的方式類似SQL語法的LIKE %S%。
Start id(Long)起始項目編號位置，如果為0，代表全部尋找，如果為某項目編號，則僅搜尋該項目下所有子項目為主。
(f)取得被選取的項目
@id = of_GetSelectItem()
id(Long)為傳回的項目編號，如果沒有項目被選取，則傳回0。
(g)取得父項目
@pid = of_GetItemParent(id)
pid(Long)為父項目的編號，若是失敗則傳回0，錯誤傳回-1。
id(Long)為尋找的項目編號。
(h)設定標題
此TVDW有個預設的標題可以設定
@of_SetTitle(Title text)
@of_SetTitle(Title text , Font size , Font face , Font color , Font Background color , Label transparent , Label x , Label y , Label width , Label Height)
Title text(String)標題文字內容。若是使用第一種用法，則所有屬性直皆為預設值。
Font size(Integer)字體大小。
Font Face(String)字型名稱。
Font color(Long)文字顏色。
Font Background color(Long)背景顏色。
Label transparent(Boolean)背景透明，當設定為透明(True)時，背景顏色會無效。
Label x(Long)標題標籤起始X座標(單位：powerbuilder unit)。
Label y(Long)標題標籤起始Y座標(單位：powerbuilder unit)。
Label width(Long)標題標籤寬度(單位：powerbuilder unit)。
Label Height(Long)標題標籤高度(單位：powerbuilder unit)。
(i)清除TVDW
@of_reset()
(j)檢視內部資料
@of_DataView(Show data)
Show data(Boolean)如果為true會開啟資料檢視視窗，Fasle則為關閉。
(k)取得項目標籤文字
@Label text = of_GetItemlabel(id)
Label text(String)取得的標籤文字內容。
id(Long)要取得標籤文字的項目編號。
(l)變更項目標籤文字
@retcode = of_SetItemLabel(id , Label text)
retcode(Integer)是變更項目標籤文字回傳狀態1是成功，0是失敗，-1是錯誤。
id(Long)要變更標籤文字的項目編號。
Label text(String)欲變更的標籤文字內容。
(m)取得項目附帶資料
@Data text = of_GetItemData(id)
Data text(String)取得項目的附帶資料。
id(Long)要取得附帶資料的項目編號。
(n)設定項目附帶資料
@retcode = of_SetItemData(id , Data text)
retcode(Integer)是設定項目附帶資料回傳狀態1是成功，0是失敗，-1是錯誤。
id(Long)要設定附帶資料的項目編號。
Label text(String)欲設定的附帶資料內容。
(三)TVDW的事件
雖然TVDW繼承自DataWindow物件，也擁有DataWindow的事件，但是由於使用方式特殊，因此請勿使用DataWindow原本的事件來攔截資料，因為攔截到的資料會有所錯誤。因此TVDW本身有定義好一部份事件以供設計者使用：
(a)ue_ItemClicked(x , y , row , id)滑鼠單擊事件(衍生自DW的Clicked事件)
x(Long)滑鼠X座標。
y(Long)滑鼠Y座標。
row(Long)資料運作DS的ROW位置。
id(Long)項目編號。
(b)ue_ItemDblClicked(x , y , row , id)滑鼠雙擊事件(衍生自DW的DoubleClicked事件)
x(Long)滑鼠X座標。
y(Long)滑鼠Y座標。
row(Long)資料運作DS的ROW位置。
id(Long)項目編號。
(c)retcode = ue_ItemChanging(id , Old Label , New Label)項目標籤變更事件
retcode(Integer)若是回傳非0值，則TVDW會拒絕項目標籤文字的變更。
id(Long)被變更標籤文字的項目編號
Old Label(String)舊的標籤文字資訊
New Label(String)新的標籤文字資訊，在此如果變更此變數內容，將會影響到變更的內容文字。
留言