1、mtk平臺mmi培訓資料(中文)2008-06-06 21:48本文詳細說明了如何建設一個自定義列表窗體模板。原理部分請參見MTK平臺(1)如何添加一個窗體模板。最終實現的是一個字典輸入界面。布局為：該模板不包含業務邏輯，僅提供頁面顯示和InputBox框輸入事件后的ListBox的Redraw事件的注冊，以及基本的輸入法設置、清空后的返回函數。一、添加用戶自定義列表模板的過程（一）在g_categories_controls_map中加入：,MMI_CATEGORY_CUSTOM_LIST,(U8*)custom_define_list,(s16*)coordinate_custom_lis

2、t,NULLconst U8 custom_define_list=    5,     DM_BASE_LAYER_START,    DM_SCR_BG,    DM_BASE_CONTROL_SET1,    DM_SINGLELINE_INPUTBOX1,    DM_LIST1;const S16 coordinate_custom_list=    DM_FULL_

3、SCREEN_COORDINATE_FLAG,    DM_CUSTOM_DEFINE_INPUTBOX,     /需要定義    DM_CUSTOM_DEFINE_LIST      /需要定義;（二）在dm_get_coordinates（）函數中加入：/設定列表位置和大小（不要忘記全局變量 MMI_custom_Listbox_x 等的定義）else if( *UICtrlAccessPtr_p = DM_CUSTOM_DEFINE_LI

4、ST )   dm_coordinate_info->s16X = MMI_custom_Listbox_x;      dm_coordinate_info->s16Y = MMI_custom_Listbox_y;      dm_coordinate_info->s16Width = MMI_custom_Listbox_width;   dm_coordinate_info->s16Height = MMI_custom_L

5、istbox_height;      dm_coordinate_info->Flags = DM_NO_FLAGS;UICtrlAccessPtr_p + ;/設定輸入框位置和大小else if( *UICtrlAccessPtr_p = DM_CUSTOM_DEFINE_INPUTBOX )   dm_coordinate_info->s16X = MMI_custom_inputbox_x ;       dm_coordinate_info-&

6、gt;s16Y = MMI_custom_inputbox_y;       dm_coordinate_info->s16Width = MMI_custom_inputbox_width ;  dm_coordinate_info->s16Height = MMI_custom_inputbox_height;    dm_coordinate_info->Flags = DM_SINGLE_LINE_INPUTBOX_SPECIFIC_HEIGHT; 

7、  UICtrlAccessPtr_p + ;（三）在Wgui_category.c中定義模板顯示函數void ShowCategoryCustomListScreen(        U8 *title,        U16 title_icon,        U16 left_softkey,      

8、60; U16 left_softkey_icon,        U16 right_softkey,        U16 right_softkey_icon,        S32 number_of_items,        U8 *list_of_items,    

9、;    U16 *list_of_icons,        S32 flags,        S32 highlighted_item,        U8 *history_buffer)    /*-*/    /* Local Variables   

10、60;                                            */    /*-*/  

11、  dm_data_struct dm_data;    S32 i;    U8 h_flag;    /*-*/    /* Code Body                           

12、;                           */    /*-*/    gdi_layer_lock_frame_buffer();    SetupCategoryKeyHandlers();    MM

13、I_title_string = (UI_string_type) title;    MMI_title_icon = (PU8) get_image(title_icon);   change_left_softkey(left_softkey, left_softkey_icon);    change_right_softkey(right_softkey, right_softkey_icon);/Create List     create_fixed_icont

14、ext_menuitems();    associate_fixed_icontext_list();    ShowListCategoryScreen(        (UI_string_type) title,        get_image(title_icon),        get_string(left_s

15、oftkey),        get_image(left_softkey_icon),        get_string(right_softkey),        get_image(right_softkey_icon),        number_of_items);   

16、 for (i = 0; i < number_of_items; i+)            add_fixed_icontext_item(UI_string_type) list_of_itemsi, wgui_get_list_menu_icon(i, list_of_iconsi);             h_flag = set_list_menu_category

17、_history(MMI_CATEGORY_CUSTOM_LIST, history_buffer);    if (h_flag)            fixed_list_goto_item_no_redraw(MMI_fixed_list_menu.highlighted_item);        else        

18、60;   fixed_list_goto_item_no_redraw(highlighted_item);    /Create Inputbox    memset(custom_single_input_buffer,0,100);    pfnUnicodeStrcpy(custom_single_input_buffer,L"Custom Category");    wgui_setup_singleline_inputb

19、ox(        0,        0,        240,        320,        custom_single_input_buffer,       

20、pfnUnicodeStrlen(custom_single_input_buffer),        MMI_CATEGORY_CUSTOM_LIST,        get_string(right_softkey),        get_image(right_softkey_icon),        IN

21、PUT_TYPE_ALPHANUMERIC_LOWERCASE| INPUT_TYPE_USE_ONLY_ENGLISH_MODES,        history_buffer,        0);    register_hide_multitap(wgui_hide_multitap);    gdi_layer_unlock_frame_buffer();  

22、0; ExitCategoryFunction = ExitCategoryCustomListScreen;    dm_setup_category_functions(dm_redraw_category_screen, dm_get_category_history, dm_get_category_history_size);    dm_data.s32ScrId = (S32) GetActiveScreenId();    dm_data.s32CatId = MMI_CATEGORY_C

23、USTOM_LIST;   /不要忘記該常量MMI_CATEGORY_CUSTOM_LIST的定義    dm_data.s32flags |= DM_CLEAR_SCREEN_BACKGROUND;    /dm_data.s32flags |= DM_SHOW_VKPAD;     dm_register_vkpad_callback(CustomList_virtual_keypad_callback);    dm_setup_

24、data(&dm_data);    dm_redraw_category_screen();   /* end of ShowCategory353Screen */void CustomList_virtual_keypad_callback(void)#if defined(_MMI_TOUCH_SCREEN_)    mmi_pen_editor_clear_and_show_virtual_keyboard_area();#endif   gui_show_transparen

25、t_image(0,200,GetImage(IMG_H_SELECT_LEFT),0);void ExitCategoryCustomListScreen()wgui_close_singleline_inputbox();（四）在singleline_inputbox_multitap_input（）函數中添加用戶處理key_0key_9的按鍵事件的函數：void (*singleline_inputbox_custom_input_callback) (void) = UI_dummy_function;void singleline_inputbox_multitap_input(UI

26、_character_type c)    /*-*/    /* Local Variables                                     

27、;           */    /*-*/    /*-*/    /* Code Body                          &

28、#160;                           */    /*-*/    if (MMI_singleline_inputbox.flags & UI_SINGLE_LINE_INPUT_BOX_PLUS_CHARACTER_HANDLING)

29、0;           if (MMI_singleline_inputbox.text0 = '+') &&            (MMI_singleline_inputbox.current_text_p = MMI_singleline_inputbox.text) &&     

30、0;      (MMI_singleline_inputbox.text_length >= (MMI_singleline_inputbox.available_length - ENCODING_LENGTH)                    return;        

31、0;       gui_single_line_input_box_insert_multitap_character(&MMI_singleline_inputbox, c);    redraw_singleline_inputbox();    singleline_inputbox_input_callback();    singleline_inputbox_custom_input_callback();（五）Wgui_Catego

32、ry.c中添加用戶事件定義接口/右鍵事件注冊void SetCategoryCustomListRightSoftkeyFunction(void (*f) (void)    wgui_singleline_inputbox_RSK_function = f;/key_0到key_9按下時的事件注冊extern void (*singleline_inputbox_custom_input_callback) (void);void SetCategoryCustomListNumKeyFunction(void (*f) (void)singleline_in

33、putbox_custom_input_callback = f ;/設置InputBox大小void SetCustomList_Inputbox_Size(S32 p_x , S32 p_y , S32 p_width , S32 p_height )MMI_custom_inputbox_x = p_x ;MMI_custom_inputbox_y = p_y ;MMI_custom_inputbox_width = p_width ;MMI_custom_inputbox_height = p_height ;/設置ListBox大小void SetCustomList_Listbox

34、_Size(S32 p_x , S32 p_y , S32 p_width , S32 p_height )MMI_custom_Listbox_x = p_x ;MMI_custom_Listbox_y = p_y ;MMI_custom_Listbox_width = p_width ;MMI_custom_Listbox_height = p_height ;二、自定義列表模板的使用方法1、 調用SetCustomList_Inputbox_Size 和 SetCustomList_Listbox_Size 設置列表框和輸入框的大小。2、 調用顯示窗體的接口 ShowCategoryCu

35、stomListScreen。3、 調用右鍵事件注冊函數，注冊文本框被清空后的事件（如返回等）SetCategoryCustomListRightSoftkeyFunction。4、 調用key_0至key_9的事件注冊函數，SetCategoryCustomListNumKeyFunction()。三、參數詳細說明 void SetCustomList_Inputbox_Size(S32 p_x , S32 p_y , S32 p_width , S32 p_height ) 與   void SetCustomList_Listbox_Size(S32 p_x , S3

36、2 p_y , S32 p_width , S32 p_height )p_x , p_y ：起始位置p_width , p_height : 大小。 void SetCategoryCustomListRightSoftkeyFunction(void (*f) (void)   void SetCategoryCustomListNumKeyFunction(void (*f) (void)   f(void) :函數地址。 void ShowCategoryCustomListScreen(     

37、;   U8 *title,       / 標題文本指針        U16 title_icon,      / 標題圖標ID        U16 left_softkey,     / 左鍵文本ID       

38、; U16 left_softkey_icon,    / 左鍵圖標ID        U16 right_softkey,     / 右鍵文本ID        U16 right_softkey_icon,    / 右鍵圖標ID        U8* custom_single_i

39、nput_buffer, / Input輸入Buffer        S32 number_of_items,    / 列表條目數        U8 *list_of_items,     / 列表項文本指針數組        U16 *list_of_icons,    

40、 / 列表項Icon        S32 highlighted_item,    / 當前高亮顯示的列表條目        U8 *history_buffer)     / 歷史記錄Buffer附：所需更改的文件wgui.cwgui_categories.cwgui_draw_manager.cwgui_inputs.cwgui.hwgui_categories_defs.hwgu

41、i_draw_manager.hCustCoordinate.c一、什么是History管理    對于我們上層用戶而言，經常接觸到的History管理是這樣的：    void EntryFunc()U8 *guiBuffer;     EntryNewScreen( Screen_ID , Exit_Func , Entry_Func , NULL );    guiBuffer = GetCurrGuiBuffer( SCR_ID_WORDMAIN_LIST

42、);   ShowCategroyXXScreen( Title_ID , , guiBuffer);    但是，無論是EntryNewScreen的調用，還是guiBuffer的傳入，我們都很少考慮過對這些指針和函數在GUI的管理起到了什么樣的作用。下面我們就要了解，以上的代碼與History管理之間存在的關系。        在MTK環境中，每當我們進入一個窗口，系統將先提取前一個窗口需保留的數據。這些數據包括：1.    窗口ID ；2.

43、    進入窗口時調用的函數和退出調用的函數 - Exit_Func 和 Entry_Func ；3.    組成窗體的控件的屬性(如，列表控件當前高亮顯示的條目、當前屏的首末條目等)。舉例說明這些數據在實際中是如何被使用的。假設存在AB兩個窗口，A窗口需要保留的數據為data_A。我們先從A窗口進入到B窗口。data_A將在B窗口調用EntryNewScreen()的時候，被壓入一個結構類似于棧的數據存儲區域；當從B調用GoBackHistory()返回A時，data_A從棧頂被彈出，然后A利用data_A將自身還原到其進入B之前的

44、狀態。這就是History管理的作用。簡言之，就是要保持窗口的外觀狀態。二、History管理的機制    現在，我們來了解一下前面所說的data_A的數據結構是什么樣的。typedef struct _history    U16 scrnID;      /(1)Screen ID (窗口號)    FuncPtr entryFuncPtr;   /(2)EntryNewScreen時要進入的 Entry_Func  &#

45、160; U8 inputBufferMAX_INPUT_BUFFER;         /(3)沒遇到過其使用，都是NULL。    U8 guiBufferMAX_GUI_BUFFER;         /(4)窗體中控件的一些需保存的信息的Buffer,通常/在使用時被轉化成各控件自定義的結構體如： list_menu_category_history。 history;  

46、60;     而存放data_A的類似于堆棧的數據區則以全局變量的形式定義在系統中：historyNode historyDataMAX_HISTORY; (MAX_HISTORY = 50):設當前窗口A所對應的數據是historyData EntryScreenNum 1 ，那么它是何時、是如何被賦值的？又是何時、如何被使用的？經過跟蹤調試，我們已經知道，在由窗口A進入到窗口B（調用EntryNewScreen）的時候，我們將data_A記錄到了historyNode 的結構體變量中。但是，在EntryNewScreen的時候傳入的，卻是

47、data_B，data_A是如何被記錄和使用的呢？我們摘選EntryNewScreen的子函數中所包含的較核心的代碼來說明這個問題。這三段代碼是按照現在的排放順序來執行的。第一段(history h 可理解為data_A)：    h.scrnID = scrnID;     / scrnID = currExitScrnID    h.entryFuncPtr = entryFuncPtr; / entryFuncPtr = currEntryFuncPtr   

48、 pfnUnicodeStrcpy(S8*) h.inputBuffer, (S8*) & nHistory);                                       / nHistory

49、= NULL ;        GetCategoryHistory(h.guiBuffer); /GetCategoryHistory是指向獲取/guiBuffer的函數的指針    AddHistory(h);      /數據入棧第二段：if(currExitFuncPtr)       /        (*c

50、urrExitFuncPtr) ();   /執行Exit_Func    第三段(記錄Screen_ID，Exit_Func和EntryFunc)：currExitScrnID = scrnID;    currExitFuncPtr = exitFuncPtr;    currEntryFuncPtr = entryFuncPtr;這樣，我們就可以看出，EntryNewScreen函數先將上次執行EntryNewScreen時所記錄的currExitScrnID, currEntr

51、yFuncPtr以history結構為載體記錄入棧；然后執行了記錄中的currExitFuncPtr；最后將本窗口的scrnID、exitFuncPtr、entryFuncPtr分別記錄入全局變量currExitScrnID、currExitFuncPtr和currEntryFuncPtr，留待下次調用EntryNewScreen時使用。下面有數據出入棧流程，有興趣的話可以跟蹤一下。以先后順序代表包含關系，如下：1.入棧(EntryNewScreen)：(1)U8 EntryNewScreen(U16 newscrnID, FuncPtr newExitHandler, FuncPtr new

52、EntryHandler, void *peerBuf)(2)static void ExecuteCurrExitHandler(void);(3)void ExecuteCurrExitHandler_Ext(void);(4)void GenericExitScreen( U16 scrnID , FuncPtr entryFuncPtr );(5)void AddHistoryReference(history *addHistory); /處理historyData(6)S16 increment();       

53、;  /更改棧指針2.出棧(GoBackHistory)：(1)void GoBackHistory(void);(2)static void ExecutePopHistory(void);        /處理historyData(3)static U8 decrement(void);                   

54、;    /更改棧指針現在我們已經知道了history 的三個結構體成員是如何記錄的了，最后來重點看一下history.guiBuffer是如何被記錄和使用的。三、GUI Buffer對控件屬性的記錄    由上2節我們知道,guiBuffer是窗體中某些控件的需保存的屬性的Buffer,通常在使用時被轉化成各控件自定義的結構體。如： list_menu_category_history。現在有幾個問題需要我們解答：1.    guiBuffer 指向的Buffer是如何被分配的？該塊數據是動態的還是靜態

55、的？2.    這塊 Buffer 是何時被寫入數據的？3.    如何釋放(動態分配時)或清空(固定地址時)該塊 Buffer ？讓我們逐一解答上面的三個問題，以清晰我們對guiBuffer的認識。1.    答：在void AddHistoryReference(history *addHistory)中，調用OslMalloc(MAX_GUI_BUFFER)動態申請了一塊內存，用來保存在 GenericExitScreen 中獲取的history.guiBuffer。參見出入棧流程2. &

56、#160;  如何釋放(動態分配時)或清空(固定地址時)該塊 Buffer ？答 ：在static void decrement (void)函數中，該buffer被釋放: OslMfree(historyDatacurrHistoryIndex.guiBuffer);。參見出入棧流程3.    答 ： 只要一個窗體模板有需要保存狀態的控件，它們都調用了這個函數dm_setup_category_functions()。函數定義如下：void dm_setup_category_functions(    

57、0;   FuncPtr redraw_function,        U8 *(*get_history_function) (U8 *buffer),        S32(*get_history_size_function) (void)/指向窗體重畫函數的函數指針    RedrawCategoryFunction = redraw_function;/指向獲取窗體guiBuffer的函數指針&

58、#160;   GetCategoryHistory = get_history_function;/指向獲取窗體guiBuffer大小的函數指針    GetCategoryHistorySize = get_history_size_function;在只有一個控件的狀態需要保存的窗體中，會這樣傳參給這個函數：dm_setup_category_functions(dm_redraw_category_screen, dm_get_category_history, dm_get_category_history_size);Generic

59、ExitScreen()函數中，將使用 GetCategoryHistory()獲取某個控件的GuiBuffer參見出入棧流程。如果按照上面的設置，GetCategoryHistory指向了dm_get_category_history這個函數。看看這個函數做了什么：control_set_ptr = dm_search_control_set(U16) p_dm_data->s32CatId, &coordinate_set_p); /獲取窗體模板內的控件類型數組control_set_ptru8NoOfUICtrls = control_set_ptr0; /獲取數組內變量個

60、數，即控件的個數/*根據控件類型，獲取控件的guiBuffer.值得注意的是，1.這里的histroy_Buffer的名稱起的不好，應該起名為guiBuffer，不應混淆視聽；2.最終history_buffer 將指向模板中定義的最后一個控件的guiBuffer*/   for (u8CtrlCt = 1; u8CtrlCt <= u8NoOfUICtrls; u8CtrlCt+)switch (control_set_ptru8CtrlCt)    case DM_CIRCULAR_MENU1:   &#

61、160;      get_circular_menu_category_history(U16) p_dm_data->s32CatId, history_buffer);       break;        case DM_LIST1:            get_list_menu_category_histo

62、ry(U16) p_dm_data->s32CatId, history_buffer);        break;        case DM_DYNAMIC_LIST1:             get_list_menu_category_history(U16) p_dm_data->s32CatId, history_buffer)

63、;         break;          case DM_ASYNCDYNAMIC_LIST1:              get_list_menu_category_history(U16) p_dm_data->s32CatId, history_buffer);   

64、;      break;            /./.而在模版顯示函數(ShowCategroyXXScreen)中,則根據 guibuffer 的情況設置控件的屬性。如果 guibuffer 不為空，則說明該模板的顯示函數是在GoBackHistory()的時候被調用的,而不是進入新窗口時被調用的。那么控件必然有一些保留的屬性需要被還原。以6號窗口的List為例。在ShowCategory6Screen()中，調用下面的函數來恢復List設

65、置：h_flag = set_list_menu_category_history(MMI_CATEGORY6_ID, history_buffer);這樣guiBuffer的Get和Set就統一起來了。現在，我們已經知道了guiBuffer 所起到的作用。但是，如果一個窗體模板內有兩個或兩個以上需要記錄狀態的控件，又該怎么辦呢？ps:該死的字數限制，只能把剩下的放到MTK平臺(3)History管理下了。四、靈活使用guiBuffer在我們自己設計窗體模板時，經常會出現一個窗體中有多個控件的情況。但是，如果一個窗體中有兩個控件、卻依然調用dm_get_category_history()獲取

66、控件的GuiBuffer的話，就會出現問題。比如，我們在制作CustomList窗體時，初期使用了這樣的代碼：(1)模板中的組件設置：const U8 custom_define_list=     5,     DM_BASE_LAYER_START,     DM_SCR_BG,     DM_BASE_CONTROL_SET1,     DM_SINGLELINE_INPUTBOX1,

67、60;  /單行輸入控件     DM_LIST1        /列表控件;    (2)窗體顯示函數 ShowCategoryCustomListScreen 部分源碼:void ShowCategoryCustomListScreen(.,U8 * guiBuffer) /.     /根據 MMI_CATEGORY_CUSTOM_LIST 的 guiBuffer,為全局結構體變量

68、 /MMI_fixed_list_menu賦值.h_flag = set_list_menu_category_history(MMI_CATEGORY_CUSTOM_LIST, guiBuffer);/而后利用MMI_fixed_list_menu,設置list的屬性if (h_flag)fixed_list_goto_item_no_redraw(MMI_fixed_list_menu.highlighted_item);else   fixed_list_goto_item_no_redraw(highlighted_item); /. /再設置單

69、行輸入框的屬性wgui_setup_singleline_inputbox(   0,   0,   240,   320,   custom_single_input_buffer,   50,   MMI_CATEGORY_CUSTOM_LIST,   get_string(right_softkey),   get_image(right_softkey_icon),   INPUT_TYP

70、E_ALPHANUMERIC_LOWERCASE| INPUT_TYPE_USE_ONLY_ENGLISH_MODES,   guiBuffer,   0);/其中 wgui_setup_singleline_inputbox 函數中調用了 /set_singleline_inputbox_category_history()來解析guiBuffer/.dm_setup_category_functions(dm_redraw_category_screen, dm_get_category_history, dm_get_category_histor

71、y_size);/.             繼續使用前3節的假設。窗口A使用了 CustomList 窗體模板。 從A 進入到B 時，EntryNewScreen函數調用了我們設置的獲取guiBuffer函數dm_get_category_history ，它先保存了A中InputBox的屬性，再保存A中List的屬性 此時它將把輸入框的屬性覆蓋掉。當從B窗口返回到A窗口時,ShowCategoryCustomListScreen()函數先把history_buffer傳給了 set

72、_list_menu_category_history , 由于guiBuffer中存儲的是List的數據,因此在交付fixed_list_goto_item_no_redraw 進行設置屬性的時候,不會出現問題。但 wgui_setup_singleline_inputbox()就會因為guiBuffer中存儲的不是輸入框存儲的數據而出現錯誤。因此,權宜之計是,將更改傳給wgui_setup_singleline_inputbox的入參:    wgui_setup_singleline_inputbox(   0,  

73、0,   240,   320,   custom_single_input_buffer,   50,   MMI_CATEGORY_CUSTOM_LIST,   get_string(right_softkey),   get_image(right_softkey_icon),   INPUT_TYPE_ALPHANUMERIC_LOWERCASE | INPUT_TYPE_USE_ONLY_ENGLISH_MODES, 

74、;  NULL,   0);     這樣,雖然死機 bug 避免了,但是特定情況下 InputBox 需要保存的屬性,將全部丟失掉.因此,更加合適的做法是,提取 dm_setup_category_functions()中使用的函數接口:get_singleline_inputbox_category_history get_list_menu_category_history    這樣可以分別獲取 inputbox 和 list 的屬性,然后將得到的兩個屬性的數據連續存放在一塊動

75、態分配的Buffer中.如200號窗口的GetCategroyHistory函數所示:U8 *GetCategory200History(U8 *history_buffer)S32 s;     get_list_menu_category_history(MMI_CATEGORY200_ID, history_buffer);s = sizeof(list_menu_category_history);s = (s + 3) / 4;s *= 4;get_singleline_inputbox_category_history(MMI_CA

76、TEGORY200_ID, (U8*) (history_buffer + s), MMI_current_input_type);return (history_buffer);     要注意的問題是,系統為guiBuffer分配空間時,依據的是 MAX_GUI_BUFFER,而不是 dm_setup_category_functions()所指定的獲取guiBuffer大小的函數GetCategoryHistorySize.而且系統中從未使用過該函數指針所指向的函數。奇怪的是 所有窗體模板的制作者都兢兢業業地制作了這個獲取guiBuffer大小的函數。在200號窗口里,獲取guiBuffer大小的函數如下:S32 GetCategory200HistorySize(void)return (sizeof(list_menu_category_history) + 3) / 4) * 4 + sizeof(singleline_inputbox_category_history);如果怕出錯且不怕麻煩的話，也可以未雨綢繆的寫一個這樣的函數，但恐怕多半是用不上的。最后的任務就是在顯示窗體時分別獲取各控件的guiBuf