選單技術

出處：https://www.amobbs.com/thread-5688720-1-1.html

說在前面的話

---

      從我第一次討論選單技術（2006年）到現在，已經十多年過去了。回想起來，當時還是大一新生，一個
親切的學姐找到我，請我幫她的畢業設計——凌陽聲控機器人小車做一個液晶選單，並許諾請我吃學校老區
最著名的新疆大盤雞。有小姐姐請客吃飯自然動力滿滿，我立馬熬了一個通宵好搞定了程式。老區的大盤雞
什麼味道 我連同學姐的臉一起已經忘得差不多了，好在這個選單程式卻倖存了下來，在之後的一年被我作為
湊字數的素材強行安插在 了[古董貼][交流]怎樣在點陣屏上繪圖——基於LCD12864的一百樓。

      現在再看當年的程式，真是恨不得找個地縫鑽進去——除了原理是勉強對的，其它細節真的是……一言難
盡——說好聽了叫青澀，說難聽了就是一坨屎……不好意思，我就是這麼直接。我摘抄一段，大家感受一下：



以下是吐槽，可以忽略……

    首先來說說這個結構體。

•         槽點1：  為毛不用typedef
•         槽點2：  為毛不用 stdint 裡面的標準型別？
•         槽點3：  為毛要浪費一個位元組來儲存  MenuCount？
•         槽點4：  函式指標  void (*Subs)()  為毛形參要省略 void ？
•         槽點5：  為什麼每一個選單項（MenuItem）都要包含一個指向父目錄的指標？
•         槽點6：  為什麼缺失了 專門的型別來描述選單？（這裡是直接用 MenuItem 的陣列裸體上陣直接表示一個menu）
•         槽點7：  NULL_MENU是什麼鬼？為什麼要浪費這個空間？
•         槽點8：  選單項處理函式的原型，為什麼返回值是void？難道不應該是一個狀態機麼？（返回 fsm_rt_t）
•         ...
•         槽點n： 沒有用匈牙利算不算……
  

    再來說說這個結構體的初始化:

•     槽點1： 為什麼不用typedef的型別？（好吧也許不算個槽點）
•     槽點2： 為什麼不用靜態賦值的方法初始化？（這裡用的是一個函式）
•     槽點3： 為什麼陣列的大小要直接用數字給定？（應該通過靜態初始化由編譯器來確定陣列的大小）
•     槽點4： 請大家無視“&Null”，這是我人生的汙點……
  

    從結論上看，一坨屎的資料結構是不可能寫出秀色可餐的演算法的，所以請大家無視選單的處理函式，我自
己也懶得吐槽了。

    讓我們拋開過去，重新審視下這個話題：
嵌入式系統中，如何使用C語言構建一個可維護性強的圖式選單。

---

【注】這裡的圖式選單說的是選單的資料結構是網狀的，使用圖論的方式來構建和維護

---

---

構建選單的資料結構

---

    設計一個服務的資料結構，不僅要考慮使用者的需求還要將目標環境的限制考慮在內。就選單服務來說，我
們不光希望選單的描述和維護簡便、能適應不同型別的GUI（文字的還是圖形化的），還要考慮嵌入式環境的
一些特點，比如對ROM和RAM的消耗要儘可能的小、嵌入式應用通常不會涉及到動態改變選單結構、選單服務
要能方便的進行裁剪和擴充套件等等。

    基於上述考慮，參考其它高階語言的常見選單結構，我們決定使用“選單容器”+"選單項"的二元結構來構建
選單的基本資料結構。簡單的說就是我們要定義兩個結構體，一個專門用來描述選單項，一個專門作為容器來
裝載選單項，並追加選單作為整體存在時所需的一些屬性。

    首先從選單項開始，容易得到：


    這裡我們看到，選單項的結構性主體由一個函式指標fnHandle和指向子目錄的指標ptChild構成。一般來說，
二者是互斥的：

• 當fnHandle不為NULL、指向對應的處理函式而ptChild為NULL時表示這是一個普通的選單項，當使用者選擇了
  這一選項時，對應的處理程式就會被執行。值得注意的是，這裡的fnHandler指向的是一個狀態機，這意味著
  選單引擎即有能力實現一個非阻塞的選單結構，也可以無視狀態機的返回，實現一個“一次性”的阻塞式選單
  處理程式。
  
• 當ptChild不為NULL、指向下一級選單而fnHandler為NULL時表示這是一個多級選單的入口。
• ptChild和fnHandler同時不為空的情況較為少見，一般為了滿足某些特殊的需求，需要定製特定的選單引擎
  來配合。
  

    選單項menu_item_t的剩下部分是和選單的顯示方式，或者說與選單的外觀效果高度相關的。根據需求的
不同，應該在這裡新增對應的成員變數，比如例子中的 pchTitle用以儲存選單文字、pchDescription用以儲存
選單的簡易提示資訊，可以在使用者懸停時以氣球或者statusbar的形式進行顯示。Windows選單一般都有一個
快捷熱鍵，如果我們的系統也希望增加這樣的功能，那麼chShortCutKey就是一個必不可少的部分，反之則是
多餘的；甚至很多時候，簡單的一個title就可以解決大部分問題。

    有些時候，我們希望用更為炫酷的方式來呈現選單，而此時選單的邏輯結構卻是和選單的顯示方式無關的，
因此，在menu_item_t里加入額外的顯示處理函式、字型、前景色、背景色、圖示等等的描述（或者指標）
都是必要的。此時，你會發現，基礎的menu_item_t更像是一個基類，而我們根據實際情況則需要繼承和派生
出符合我們自己的實現形式。為了適應這一設定，我們將menu_item_t拆分成兩個部分：

    基類部分 menu_item_t:

    以及一個滿足大部分應用情形的預設模板（派生類）：


為了讓模板的定義更為簡單，我們提供了以下的巨集進行輔助：

---

【注】如果你覺得巨集讓你頭暈，請忽略這部分，它對理解這個選單結構並沒有實質性的作用。

---

因此，前面的預設模板就可以用極為簡單的形式進行描述：



    你也可以參考這種形式通過這一系列巨集來定義自己的選單項模板。這裡就不再贅述。接下來，我們來看看
選單容器（menu_t）的結構：

• 非常直接的，menu_t結構體的前兩個成員就是體現其容器作用的ptItems和chCount。前者指向具體的選單
  項陣列，後者用以描述陣列中有效的選單項個數。
• ptParent用以指向當前選單的父選單。單一的指標限定了當前選單的扇入為1——也就是隻有唯一的一個父
  目錄——這對大部分應用來說不是什麼問題。如果要支援更為靈活的結構，解決方案並不是在這裡追加父目錄
  指標的數量，而是在這一資料結構外額外增加一個動態的單連結串列，用以記錄使用者開啟目錄的路徑，用以實現與
  手機瀏覽時常見的“返回之前頁面”類似的效果——在這種情況下，ptParent理論上也可以從結構體中刪除。
• 一般來說，簡單的應用傾向於給每一個選單都使用同樣的導航方式（根據按鍵處理選單選擇的方式）——
  也就是說唯一的一個選單引擎就夠了，然而在一些複雜的情況下，不同的選單可能有自己獨特的按鍵佈局和
  選單跳轉需要——比如前一個目錄是簡單的線性排列結構而後面一個目錄是平面的二維目錄結構，他們對按鍵
  的響應方式是不同的——在這種情況下，為每一個選單增加一個指向對應選單引擎的函式指標就非常有必要了。
  

    看過 menu_item_t 推演過程的朋友可能會有疑問了，menu_t 是否也有作為基類在需要的時候進行擴充套件的可
能呢？答案是肯定的。實際上，fnEngine 就可以被看作是擴充套件出來的。同樣的，如果GUI非常炫酷，我們需要
給不同的選單提供不同的背景色、背景圖片、前景色等等屬性時，我們也需要把 menu_t 當作是一個基類，並
根據自己的需要進行對應的擴充套件。這是一個舉一反三地過程，我很樂意把這一發揮空間留給大家，根據自己的
實際情況去擴充套件，這裡就不再贅述。

    總結下來，我們完成了選單最基礎的資料結構，並初步定義了一些巨集來簡化選單項模板的定義：

---

“選單的描述要優雅”

---

    有了選單的資料結構為基礎，我們就可以來考慮如何描述一個實際的選單，也就是底層上如何對一個選單資料
結構進行初始化的問題。基於 default_menu_item_t 一個可能的初始化形式是：



通過加入一些輔助巨集，我們可以讓這個初始化的選單的定義過程更簡單（只消耗ROM）：

---

【注】如果你覺得巨集讓你頭暈，請忽略這部分，它對理解這個選單結構並沒有實質性的作用。

---

從前面的巨集中，我們注意到無論是 def_menu 還是 end_def_menu 都預設的採用了 default_menu_item_t 作為菜
單項的模板，因此，前面初始化的例子就等效的可以簡化為：



    當我們要採用自己定義的選單項模板（而不是預設的 default_menu_item_t ）時，應該使用巨集 def_menu_ex，並
將自己定義的模板作為最後一個引數傳遞給該巨集。注意到 menu_item 巨集的最後一項是可變引數列表，因此無論你的
模板擴充套件了多少元素，都可以放心的使用 menu_item() 巨集進行初始化：



     使用上述方式構建的選單，會消耗多少SRAM呢？答案是0。觀察資料結構，我們會注意到，描述選單的結構體的
值在編譯時刻都是已知的——並且，這個並且至關重要——我們擴充套件的模板也不會引用（指標指向）或者包含任何在
執行時刻會發生變化的內容，因此完全可以將整個資料結構儲存在ROM中——在ARM體系架構下，簡單的const就可以
完成這一使命——如果你使用了不同的平臺，則應該根據自己的實際情況修改前述的巨集模板，使得最終產生的選單內容
被儲存在ROM中。

    下面我們來看一個2級選單的例子（更多級選單的情況請以此類推）：

---

“實際咋用”

---

定義好的menu資料結構怎麼引用呢？

需要用到變數的時候，用menu巨集，例如：


如果要extern給其它.c檔案使用怎麼辦呢？使用extern_menu巨集，例如：


     通過前面的內容，我們會很容易注意到，這個選單結構的靈活性還體現在選單的處理函式上，不僅每一個目錄可以單
獨指定處理引擎，每一個選單項也都可以通過狀態機的形式來處理具體的選單事件。拋開應用高度相關的選單項處理函式
不談，我們來重點看一看選單的引擎（以預設選單引擎為例）：

• 這是一個狀態機，意味著選單的處理可以是非阻塞的，這對喜歡酷炫特效以及需要在選單後面做小動作的應用來說非常
  關鍵。狀態機的模板參考我專門的帖子。在106樓的例子非常有參考價值，這裡就不具體展開了。
• 狀態機的傳入引數 ptThis 指向的是一個選單引擎的runtime控制塊，裡面存放的是關於選單當前狀態的各種資訊，容易
  想到：
  
  1. 
     
  2. typedef struct __menu_engine_cb menu_engine_cb_t;
     
  3. typedef fsm_rt_t menu_engine_t(menu_engine_cb_t *);
     
  4. 
     
  5. struct __menut {
     
  6.     menu_item_t        *ptItems;                        //!< menu item list
     
  7.     uint_fast8_t        chCount;                        //!< menu item count
     
  8.     menu_t             *ptParent;                       //!< parent menu;
     
  9.     menu_engine_t      *fnEngine;                       //!< engine for process current menu
     
  10. }; 
      
  11. 
      
  12. struct __menu_engine_cb {
      
  13.     const menu_t    *ptCurrentMenu;
      
  14.     uint_fast8_t    chCurrentItemIndex;
      
  15. };
      

  複製程式碼
  
  這裡，ptCurrentMenu是一個指向當前選單的指標，而chCurrentItemIndex儲存的就是當前使用者選中的選單項的陣列下標。
  僅靠這兩個變數，理論上再配合按鍵輸入，已經能夠實現一個簡單的選單引擎。實際上，考慮到目錄選單引擎是一個狀態
  機，因而將狀態機變數也放在menu_engine_cb_t中也是可行的，比如：
  
  1. 
     
  2. struct __menu_engine_cb {
     
  3.     uint_fast8_t tState;
     
  4.     const menu_t    *ptCurrentMenu;
     
  5.     uint_fast8_t    chCurrentItemIndex;
     
  6. };
     

  複製程式碼
  
  
  這裡給出一個簡化的引擎範例（虛擬碼）：
  
  1. 
     
  2. 
     
  3. #ifndef this
     
  4. #   define this        (*ptThis)
     
  5. #endif
     
  6. 
     
  7. typedef enum {
     
  8.     KEY_NULL = 0,
     
  9.     KEY_DOWN,
     
  10.     KEY_UP,
      
  11.     KEY_ENTER,
      
  12.     KEY_ESC,
      
  13. } key_t;
      
  14. 
      
  15. extern key_t get_key(void);
      
  16. 
      
  17. fsm_rt_t default_menu_engine(menu_engine_cb_t *ptThis)
      
  18. {
      
  19. #define DEFAULT_MENU_ENGINE_RESET_FSM() \
      
  20.     do { this.tState = START; } while(0)
      
  21. 
      
  22.     enum {
      
  23.         START = 0,
      
  24.         READ_KEY_EVENT, 
      
  25.         KEY_PROCESS, 
      
  26.         RUN_ITEM_HANDLER
      
  27.     };
      
  28.     key_t tKey;
      
  29.     menu_item_t *ptItem;
      
  30.     
      
  31.     switch(this.tState) {
      
  32.         case START:
      
  33.             this.tState++;
      
  34.         case READ_KEY_EVENT: 
      
  35.             tKey = get_key();
      
  36.             if (KEY_NULL == tKey) {
      
  37.                 break;
      
  38.             }
      
  39.             //this.tState = KEY_PROCESS;
      
  40.             
      
  41.         case KEY_PROCESS:
      
  42.             switch (tKey) {
      
  43.                 case KEY_DOWN:
      
  44.                     this.chCurrentItemIndex++;
      
  45.                     if (this.chCurrentItemIndex >= this.ptCurrentMenu->chCount) {
      
  46.                         this.chCurrentItemIndex = 0;
      
  47.                     }
      
  48.                     break;
      
  49.                 case KEY_UP:
      
  50.                     if (0 == this.chCurrentItemIndex) {
      
  51.                         this.chCurrentItemIndex = this.ptCurrentMenu->chCount - 1;
      
  52.                     }
      
  53.                     break;
      
  54.                 case KEY_ENTER: {
      
  55.                         ptItem = &(this.ptCurrentMenu->ptItems[this.chCurrentItemIndex]);
      
  56.                         if (NULL != ptItem->fnHandle) {
      
  57.                             this.tState = RUN_ITEM_HANDLER;
      
  58.                         } else if (NULL != ptItem->ptChild) {
      
  59.                             this.ptCurrentMenu = ptItem->ptChild;
      
  60.                             this.chCurrentItemIndex = 0;
      
  61.                             
      
  62.                             DEFAULT_MENU_ENGINE_RESET_FSM();
      
  63.                             return fsm_rt_cpl;
      
  64.                         }
      
  65.                     }
      
  66.                     break;
      
  67.                 case KEY_ESC:
      
  68.                 
      
  69.                     //! return to upper menu
      
  70.                     if (NULL != this.ptCurrentMenu->ptParent) {
      
  71.                         this.ptCurrentMenu = this.ptCurrentMenu->ptParent;
      
  72.                         this.chCurrentItemIndex = 0;
      
  73.                             
      
  74.                         DEFAULT_MENU_ENGINE_RESET_FSM();
      
  75.                         return fsm_rt_cpl;
      
  76.                     }
      
  77.                     break;
      
  78.                 default:
      
  79.                     break;
      
  80.             }
      
  81.             break;
      
  82.             
      
  83.         case RUN_ITEM_HANDLER:
      
  84.             ptItem = &(this.ptCurrentMenu->ptItems[this.chCurrentItemIndex]);
      
  85.             fsm_rt_t tFSM = ptItem->fnHandle(ptItem);
      
  86.             if (IS_FSM_ERR(tFSM)) {
      
  87.                 //! report error
      
  88.                 DEFAULT_MENU_ENGINE_RESET_FSM();
      
  89.                 return tFSM;
      
  90.             } else if (fsm_rt_cpl == tFSM) {
      
  91.                 DEFAULT_MENU_ENGINE_RESET_FSM();
      
  92.                 return fsm_rt_cpl;
      
  93.             }
      
  94.             break;
      
  95.     }
      
  96. 
      
  97.     return fsm_rt_on_going;
      
  98. }
      

  複製程式碼
  
  
  

最後我們還需要一個最頂層的任務，用來執行我們這個選單服務（這個頂層任務和具體用哪個引擎無關）：


“能玩出啥花兒不？”
    看的人多了，提問的人多了，再寫！
相關連結
        - [古董貼][交流]怎樣在點陣屏上繪圖——基於LCD12864
        - 最近讀傻孩子的選單程式，做了一個PPT，希望大家批評指正



打完收工！

<-----------------------------------------分割線----------------------------------------->

說說我的理解，不一定對，但是會給提供一個參考，希望大家踴躍留言。

選單就是一系列的介面的有機結合，你可以簡單認為是個樹形結構。至於這個樹形結構是怎麼

實現，陣列也好、連結串列也行。然後就是實現的問題，我們可以把內容和現實耦合在一起，就是

每屏都有自己的畫刷；也可以把畫刷剝離出來，但是寫成一個選單顯示引擎。再有就是選單的

索引驅動，怎麼設計。基於上面這篇論文，我們可以把選單的引擎獨立出來，它包括顯示驅動

（也可以是一個fnHandler，由每屏傳入，本論文沒有這麼做）+搜尋驅動（也可以是一個

fnHandler，由每屏傳入，本論文就是這麼設計的），在這裡我感覺可以這麼設計，就是使用者如果

傳入的是NULL指標，就呼叫系統的標準處理函式，如果傳入的不是NULL，就呼叫使用者的函式。

好了，到目前為止，我們提取了選單引擎。那麼選單如何設計內？我們知道一屏內容可能包含幾種

控制元件，每種控制元件都有自己的內容和屬性。於是就有了選單項和選單容器的概念，一個選單項就是一

個控制元件，容器可以認為是一屏，可以類比MFC。這裡需要為每個選單項新增一個type，這樣選單引

擎才能載入合適的驅動。