第十六章　功能表（二）

本章介紹快捷功能表與系統功能表。

與功能表相關 Win64 API

前一章已經介紹過幾個常用、與功能表有關的 Win64 API，例如 LoadMenu、SetMenu、CheckMenuItem、GetSubMenu。底下先介紹本章會用的 Win64 API，然後再介紹快捷功能表與系統功能表。

TrackPopupMenu API

TrackPopupMenu 函式會在指定位置顯示快捷功能表並追蹤使用者在功能表上的選擇，此快捷功能表可以出現在螢幕的任何位置。TrackPopupMenu 原型如下：

invoke  TrackPopupMenu,\
        hMenu,\         ; handle of shortcut menu
        uFlags,\        ; screen-position and mouse-button flags
        x,\             ; horizontal position, in screen coordinates
        y,\             ; vertical position, in screen coordinates
        nReserved,\     ; reserved, must be zero
        hWnd,\          ; handle of owner window
        prcRect         ; points to RECT that specifies no-dismissal area

底下是 TrackPopupMenu 參數的說明：

如果在 uFlags 參數中指定 TPM_RETURNCMD，則回傳值是使用者所選項目的選單識別碼；如果使用者在沒有做出選擇的情況下取消功能表（例如已顯示功能表後，卻以滑鼠左鍵點擊功能表外的區域），或發生錯誤，則回傳值為零。如果未在 uFlags 參數中指定 TPM_RETURNCMD，那麼如果 TrackPopupMenu 成功執行，則回傳值為非零；如果失敗，則傳回值為零。若要取得擴充錯誤訊息，請呼叫 GetLastError。

ClientToScreen API

ClientToScreen 將某一像素（也可稱為點）的工作區座標，轉變成螢幕座標（以工作區左上角為原點的座標稱工作區座標，以螢幕左上角為原點的座標稱為螢幕座標）。其原型如下：

invoke  ClientToScreen,\
        hWnd,\          ; window handle for source coordinates
        lpPoint         ; pointer to structure containing screen coordinates

上式中的 hWnd 指定要以哪一個視窗的工作區為原點。lpPoint 是 POINT 結構體的位址，該結構體內有要轉變的工作區座標。假如轉變成功，那麼 ClientToScreen 會將轉變後的螢幕座標，存回 lpPoint 所指位址的結構體內，同時回傳值為非零；如果失敗，回傳值為零。

GetSystemMenu API

GetSystemMenu 可以讓應用程式存取系統功能表，以供複製或修改。其原型如下：

invoke  GetSystemMenu,\
        hWnd,\          ; handle of window to own window menu
        bRevert	        ; reset flag

第一個參數，hWnd，是要存取系統功能表之視窗代碼。

第二個參數 bRevert 指定如何存取，可以是下列兩種數值其中之一：

  1. FALSE：GetSystemMenu 會傳回 hWnd 的系統功能表之功能表代碼，爾後應用程式可呼叫其他 Win64 API 修改系統功能表。
  2. TRUE：GetSystemMenu 會重設系統功能表為原來的預設狀態，並傳回 0。

AppendMenu API

AppendMenu 可以將一個分隔線、選項或彈出選項添加到指定的主功能表、子功能表、快捷功能表或系統功能表的尾端，也可以使用 AppendMenu 來指定選項的內容、外觀和行為。雖然 AppendMenu 已被 InsertMenuItem 所取代，但是如果不需要 InsertMenuItem 複雜的擴展功能，仍然可以使用 AppendMenu。AppendMenu 的原型是：

invoke  AppendMenu,\
        hMenu,\         ; handle to menu to be changed
        uFlags,\        ; menu-item flags
        uIDNewItem,\    ; menu-item identifier or handle of drop-down menu or submenu
        lpNewItem       ; menu-item content

底下是這些參數的說明：

如果 AppendMenu 成功執行，回傳值為非零；如果失敗，回傳值為零。

WM_SYSCOMMAND 訊息

當使用者點選系統功能表中的選項，或是點擊標題欄右側的最小化、最大化或關閉按鈕時，視窗就會收到 WM_SYSCOMMAND 訊息。

WM_SYSCOMMAND 中的 wParam 代表使用者所選擇的選項識別碼，這些都是由系統預先定義過的，這些選項識別碼亦可視為使用者對視窗發出的「指令」，指使其「工作」。常見的指令如下表：

系統定義的選項識別碼數值說明
SC_CLOSE0F060H使用者選擇系統選單的關閉選項或點擊標題欄右邊的關閉按鈕
SC_MAXIMIZE0F030H使用者選擇系統選單的最大化選項或點擊標題欄右邊的最大化按鈕
SC_MINIMIZE0F020H使用者選擇系統選單的最小化選項或點擊標題欄右邊的最小化按鈕

上面僅列出一小部分，其他的請參考 MSDN，這些選項識別碼的數值都大於或等於 0F000H。一般而言，視窗函式把 wParam 為 SC_CLOSE、SC_MAXIMIZE、SC_MINIMIZE……的 WM_SYSCOMMAND 訊息，交給 DefWindowProc API 處理。

lParam 存著滑鼠點選時的螢幕座標，0∼15 位元是 X 座標，16∼31 是 Y 座標。

快捷功能表

快捷功能表（shortcut menu）也叫快捷選單或突現式功能表（popup menu，也翻譯成突現式選單），是使用者於工作區任一處，按下滑鼠右鍵所出現的功能表。

資源描述檔中的快捷功能表

回憶前一章，主功能表位於視窗標題欄下方，其選項或彈出選項皆為橫向排列，但如果使用者點選彈出選項，顯示出來的子功能表中的選項，卻是縱向排列。換句話說，在資源描述檔中，MENU 區塊中的第一層功能表中的選項是橫向排列，而其他的子功能表中的選項是縱向排列。

按下滑鼠右鍵而顯示的快捷功能表中的選項，不論第幾層，其選項均為縱向排列。由於這樣的緣故，所以要在資源描述檔中，藉由 MENU 區塊定義快捷功能表，需要稍微變通。

所謂「變通」的意思是製作「虛假的」第一層功能表。其過程大致是先在資源描述檔中，MENU 區塊內建立只有一個彈出選項的第一層功能表。在彈出選項內是第二層功能表，它才是真正的快捷功能表所在。從第二層開始，就按原來快捷功能表的設計撰寫。

也就是說，第一層功能表只是佔了個位置，讓橫向排列的選項放在這兒，是「虛假的」，快捷功能表是從第二層開始，再配合「特殊的」載入方式就避免了第一層功能表橫向排列的問題了。所謂「特殊的」載入方式，見下面的「從資源中載入快捷功能表」。底下是用 MENU 區塊定義快捷功能表的格式：

┌─MenuID  MENU
│ BEGIN
│   ┌─POPUP text
│   │ BEGIN
│   │   ⁝
│   └─END
└─END

由上面可知，第一層功能表（以天空色括住）只有一個彈出選項，其名稱，text，可以是任意字串，其實是什麼字串並不重要，這是因為快捷功能表並不顯示 MENU 區塊中的第一層功能表。第二層功能表（以紅色括住）介於第二層的 BEGIN/END 之間，可以說是第一層的子功能表，位於「⁝」處，此處才是真正快捷功能表的內容。它可以是選項：

MENUITEM    text,ID,[option]
MENUITEM    SEPARATOR

或彈出選項：

POPUP   彈出功能表字串
BEGIN
    ⁝
END

此二者都在前一章敘述過了，此處不重複。

從資源中載入快捷功能表

在組合語言原始程式中，由資源載入快捷功能表，並不顯示第一層功能表，而是由第二層開始顯示，所以呼叫 TrackPopupMenu 顯示快捷功能表的第一個參數，是第二層功能表的功能表代碼。

換句話說，應先呼叫 LoadMenu 並取得資源描述檔 MENU 功能表代碼，此為第一層功能表的代碼。然後再以第一層功能表代碼及位置 0 為參數，呼叫 GetSubMenu 取得子功能表代碼，這個子功能表代碼其實就是第二層的功能表代碼，也是使用者以滑鼠點選工作區出現的快捷功能表代碼。這件事一般是在處理 WM_CREATE 訊息時完成，也可以在主程式中建立好視窗後、但尚未進入訊息迴圈前完成。

要顯示快捷功能表時，呼叫 TrackPopupMenu 的第一個參數就是這個第二層的功能表代碼。通常是使用者在工作區任一處，按下滑鼠右鍵才會出現快捷功能表，通常是在處理 WM_RBUTTONUP 或 WM_RBUTTONDOWN 呼叫 TrackPopupMenu。

快捷功能表的例子：DRAW3

下面的例子是將上一章所提到的主功能表範例，DRAW2，改寫成快捷功能表，改寫後的例子稱為 DRAW3。先來看看資源描述檔，DRAW3.RC，其內容與 DRAW2.RC 大致一樣，故只列出不同之處：

1
⁝ 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
⁝ 
#define IDM_QUIT        3000
    ⁝

DRAW3   MENU
{                       /* 第一層功能表 */
  POPUP "快捷功能表"
  {                     /* 第二層功能表 */
    MENUITEM "離開",IDM_QUIT
    POPUP    "檢視"
             {
               MENUITEM   "座標",IDM_XY,CHECKED
               MENUITEM   "畫筆顏色",IDM_COLOR,CHECKED
             }
    POPUP    "繪圖"
             {          /* 第三層功能表 */
               MENUITEM    "橢圓",IDM_ELLIPSE
               MENUITEM    "手繪圖",IDM_TRACE     /* 預設手繪圖 */
               MENUITEM    SEPARATOR
               MENUITEM    "黑",IDM_BLACK         /* 預設黑筆 */
               MENUITEM    "紅",IDM_RED
               MENUITEM    "綠",IDM_GREEN
               MENUITEM    "藍",IDM_BLUE
             }
    MENUITEM "幫助",IDM_HELP
  }
}

DRAW3   ICON   "DRAW2.ICO"   /* 圖示 */
    ⁝

再來看看原始程式 DRAW3.ASM 的內容，它與 DRAW2.ASM 大同小異，所以底下的內容，僅列出其中不同的地方。完整的檔案請到這裏下載（此壓縮檔包含本章的兩個例子）。

1
2
⁝ 
28
29
30
⁝ 
56
57
58
59
60
⁝ 
170
⁝ 
188
189
190
191
192
193
⁝ 
211
212
213
214
215
216
217
218
219
⁝ 
231
232
⁝ 
250
251
252
⁝ 
264
265
;DRAW3是將DRAW2的主功能表改成快捷功能表
OPTION CASEMAP:NONE
          ⁝
szClassName     DB      "DRAW3",0
szAppName       DB      "超簡單繪圖",0
szText          DB      "DRAW3僅能繪製橢圓與手繪圖",0dh,0ah,"，且不能存檔也不能編輯。",0
          ⁝
.CODE
;-----------------------------------------------------------------------------------------
WndProc PROC    hWnd:HWND, uMsg:UINT, wParam:WPARAM, lParam:LPARAM
        LOCAL   ps:PAINTSTRUCT,rect:RECT,buffer[64]:BYTE,tm:TEXTMETRIC,point:POINT
.switch uMsg
          ⁝
  .case WM_CREATE
          ⁝
        mov     hCursor[24],rax
    ;取得快捷功能表的功能表代碼，並存於hMenu中
        invoke  LoadMenu,hInstance,OFFSET szMenuName
        mov     hMenu,rax
        invoke  GetSubMenu,hMenu,0
        mov     hMenu,rax
          ⁝
  .case WM_RBUTTONUP
        mov     r8,r9
        shr     r9,10h          ;R9＝Y座標
        and     r8,0ffffh       ;R8＝X座標
        mov     point.y,r9d
        mov     point.x,r8d
        invoke  ClientToScreen,hWnd,ADDR point
        invoke  TrackPopupMenu,hMenu,TPM_RIGHTALIGN,point.x,point.y,0,hWnd,0

          ⁝
;-----------------------------------------------------------------------------------------
main    PROC
          ⁝
        invoke  RegisterClassEx,ADDR wc
        invoke  CreateWindowEx,0,ADDR szClassName,ADDR szAppName,WS_OVERLAPPEDWINDOW,\
                50,50,500,375,0,0,hInstance,0
          ⁝
;*****************************************************************************************
END     main

將 DRAW3.ASM、DRAW3.RC 放置於同一子目錄，組譯、連結的方式與 DRAW2 一模一樣，只有檔名不同而已，就不列出來了。

解說 DRAW3

首先看 DRAW3.RC 檔內有關於 MENU 區塊。你會發現，在最上層的功能表多加了一個名為「快捷功能表」的彈出選項（見第 18 行），其餘皆與 DRAW2.RC 中的 MENU 區塊一樣。原因很簡單前面也提過，就是避免顯示第一層的功能表，而由第二層開始顯示。

另外在 DRAW3.RC 中還有一點與 DRAW2.RC 不同。在 DRAW2.RC 中的幫助選項，為了讓幫助的字樣顯示在主功能表右邊，故其後有加上「HELP」。但是在 DRAW3.RC 中，這些選項都是鉛錘方向排列，故不須加上「HELP」，即使加上了，也毫無用處。

接下來看看如何從資源中載入快捷功能表。見 DRAW3.ASM 的第 189∼193 行，有兩步驟，都在處理 WM_CREATE 訊息中發生：①先呼叫 LoadMenu 得到第一層功能表的代碼。②然後再以此代碼以及位置 0 為參數，呼叫 GetSubMenu 得到第 0 個位置的子功能表之代碼，也是快捷功能表代碼。

最後來看看如何在原始程式中顯示快捷功能表。一般而言，當使用者在工作區按下滑鼠右鍵，才會顯示快捷功能表，因此在 DRAW3.ASM 就必須處理 WM_RBUTTONUP 或 WM_RBUTTONDOWN 兩則訊息的其中一則，一般是處理前者。見第 211∼218 行。

DRAW3.ASM 是呼叫 TrackPopupMenu 來顯示快捷功能表，但是 TrackPopupMenu 用來把快捷功能表顯示在哪兒的第三、四個參數，其座標是相對於螢幕左上角為原點；而 WM_RBUTTONUP 所提供位於 lParam 的座標，是相對於工作區左上角為原點。因此在呼叫 TrackPopupMenu 之前，必須先呼叫 ClientToScreen 將其轉換成螢幕座標。

再看 TrackPopupMenu 的第一個參數，hMenu。這是要顯示的快捷功能表代碼，前面提過，此功能表代碼其實是在資源描述檔 MENU 區塊、第一層功能表的第零個位置的子功能表代碼。第二個參數，TPM_RIGHTALIGN，會使得滑鼠游標在快捷功能表的右邊。第三、四個參數是由 ClientToScreen 轉換後的螢幕座標。第五個參數，hWnd，表示該視窗擁有此快捷功能表，也就是快捷功能表所發出的訊息，會發送到 hWnd 的視窗函式中，加以處理。

系統功能表

系統功能表（system menu）也稱為視窗功能表（window menu）或控制功能表（control menu），使用者可以用滑鼠左鍵點擊標題欄最左邊的圖示，或是用滑鼠右鍵點擊標題欄任一處，就會出現系統功能表。即使應用程式沒有建立任何功能表，Windows 作業系統也會自行提供預設的系統功能表。預設的系統功能表如下圖紅色框框住的部分，包含六個選項及一個分隔線。

應用程式也可以透過 GetSystemMenu 取得系統功能表代碼，然後透過呼叫 AppendMenu 等 Win64 API 對其添加選項或進行修改，如上圖紅色框以外的功能表區域都是應用程式新添的，事實上，上圖是本章的第二個例子，DRAW4，稍後再敘述，現在言歸正傳，繼續說明在系統功能表添加選項。

添加到系統功能表的選項，其選項識別碼就必須小於 0F000H，以免與系統功能表原來的選項衝突。當使用者點選添加的選項時，發出的不再是 WM_COMMAND，而是 WM_SYSCOMMAND 訊息，其 wParam 的 0∼15 位元是其選項識別碼。也就是說，應用程式必須在處理 WM_SYSCOMMAND 訊息時，以回應使用者點選的添加選項。

如果應用程式在系統功能表中添加了新的選項，當使用者點選系統功能表中的關閉、最大化、最小化、還原……等選項，系統仍然發出 wParam 為 SC_CLOSE、SC_MAXIMIZE、SC_MINIMIZE、SC_RESTORE……的 WM_SYSCOMMAND 訊息，大多數的情形還是交由 DefWindowProc 處理；當使用者點選新添加的選項，系統還是發出 WM_SYSCOMMAND 訊息，只是此時的 wParam 是小於 0F000H 的選項識別碼。

換句話說，若是在系統功能表中添加了選項，那麼必須在處理 WM_SYSCOMMAND 訊息的程式碼中，判斷哪些是系統功能表中原有的選項，它們由 DefWindowProc API 處理；哪些是新添加的選項，它們必須由 WM_SYSCOMMAND 訊息新增的程式碼來處理。

系統功能表例子：DRAW4

底下的例子，DRAW4，是把 DRAW2 的主功能表移到系統功能表裏，但是其中的「離開」選項和系統功能表原來的「關閉」具有一樣的功能因此刪除，只有把「檢視彈出選項」、「繪圖彈出選項」和「幫助選項」移到系統功能表。

DRAW4.ASM 及其解說

對系統功能表而言，DRAW4 要做的就是添加這三個選項，其功能幾乎一樣，所以 DRAW4.ASM 的內容與 DRAW2.ASM 大同小異，底下的 DRAW4.ASM 僅列出不同的部分。

1
2
⁝ 
10
⁝ 
26
27
28
29
30
31
32
⁝ 
42
43
⁝ 
139
140
141
142
143
144
145
⁝ 
173
⁝ 
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
⁝ 
250
251
252
⁝ 
264
265
;DRAW4是將DRAW2的主功能表大部分選項移至系統功能表
OPTION CASEMAP:NONE
          ⁝
IDM_XY          EQU     3001
          ⁝
szIconName      LABEL   BYTE
szClassName     DB      "DRAW4",0
szAppName       DB      "超簡單繪圖",0
szText          DB      "DRAW4僅能繪製橢圓與手繪圖",0dh,0ah,"，且不能存檔也不能編輯。",0
szViewMenu      DB      "檢視",0
szDrawMenu      DB      "繪圖",0
szHelpMenu      DB      "幫助",0
          ⁝
hDrawSubMenu    HMENU   ?       ;繪圖子功能表代碼
hSysMenu        HMENU   ?       ;系統功能表代碼
          ⁝

  .case WM_SYSCOMMAND
        mov     line_pen,0
        mov     ellips_pen,0
    .if r8w>=0f000h
        jmp     deflt
    .elseif r8w==IDM_HELP
          ⁝
  .case WM_CREATE
          ⁝
        mov     hCursor[24],rax
    ;由資源中載入功能表
        invoke  LoadMenu,hInstance,OFFSET szMenuName
        mov     hMenu,rax
    ;獲得檢視子功能表代碼及繪圖子功能表代碼，分別存於hViewSubMenu、hDrawSubMenu
        invoke  GetSubMenu,hMenu,0
        mov     hViewSubMenu,rax
        invoke  GetSubMenu,hMenu,1
        mov     hDrawSubMenu,rax
    ;將繪圖子功能表中的手繪圖選項和黑色選項前顯示圓點的勾選記號
        invoke  CheckMenuRadioItem,hDrawSubMenu,0,1,1,MF_BYPOSITION
        invoke  CheckMenuRadioItem,hDrawSubMenu,IDM_BLACK,IDM_BLUE,IDM_BLACK,MF_BYCOMMAND
    ;獲得系統功能表代碼，並存於hSysMenu
        invoke  GetSystemMenu,hWnd,0
        mov     hSysMenu,rax
    ;在系統功能表中依序加入分隔線、檢視子功能表、繪圖子功能表、幫助選項
        invoke  AppendMenu,hSysMenu,MF_SEPARATOR,0,0
        invoke  AppendMenu,hSysMenu,MF_POPUP,hViewSubMenu,OFFSET szViewMenu
        invoke  AppendMenu,hSysMenu,MF_POPUP,hDrawSubMenu,OFFSET szDrawMenu
        invoke  AppendMenu,hSysMenu,MF_STRING,IDM_HELP,OFFSET szHelpMenu
          ⁝
        invoke  RegisterClassEx,ADDR wc
        invoke  CreateWindowEx,0,ADDR szClassName,ADDR szAppName,WS_OVERLAPPEDWINDOW,\
                50,50,500,375,0,0,hInstance,0
          ⁝
;*****************************************************************************************
END     main

首先看 DRAW4.ASM 是如何將選項或子功能表加進到系統選單中，一般是在 WM_CREATE 訊息中處理，必須做三件事：①獲得要新加入系統功能表的子功能表代碼、②獲得系統功能表代碼、③呼叫 AppendMenu 將選項或子功能表加進系統功能表內。詳細的步驟說明如下：

①、見第 192∼199 行，呼叫 LoadMenu 自資源中載入功能表，再依據此功能表代碼及位置 0、1 分別呼叫 GetSubMenu 兩次，以獲得「檢視子功能表」、「繪圖子功能表」代碼，分別存於 hViewSubMenu、hDrawSubMenu 變數裏。順便將繪圖子功能表中的兩個選項，手繪圖及黑，前面標示「●」的記號。

②、見第 203∼205 行，呼叫 GetSystemMenu 獲得系統功能表的代碼，存於 hSysMenu 變數內。

③、見第 206∼210 行，呼叫四次 AppendMenu 在系統功能表中添加分隔線、子功能表及選項。當添加分隔線時，

因為在 WM_CREATE 訊息中修改了系統功能表，所以在 main 副程式中，呼叫 CreateWindowEx 時，第十個參數不需要設為功能表代碼，故設為零（第 251∼252 行）。

當使用者點選系統功能表中的任一選項，不論是原來的還是新加進的，都會發出 WM_SYSCOMMAND 訊息。為了使原來的選項仍能夠正常運作，必須交由 DefWindowProc 處理，所以在第 143 行，判斷 WM_SYSCOMMAND 的 wParam 是否大於或等於 0F000H，如果是，那麼就跳躍至 deflt 標記處，由 DefWindowProc 處理。如果不是，那就依序檢查選項識別碼，依據使用者點選不同選項，分別加以處理，這段程式與 DRAW2 一樣，所以沒列在上面。

DRAW4.RC 及其解說

底下是資源描述檔 DRAW4.RC 的內容，同樣也只列出與 DRAW2.RC 不同之處，事實上只有三處：①因為沒有離開選項，也就不需要「#define IDM_QUIT 3000」。②因為沒有離開選項，所以在 MENU 區塊刪除「MENUITEM "離開",IDM_QUIT」。③圖示名稱改成 DRAW4，見 DRAW4.RC 第 35 行。

1
⁝ 
15
16
17
⁝ 
33
34
35
⁝ 
#define IDM_XY          3001
   ⁝
DRAW4      MENU
{
  POPUP    "檢視"
   ⁝
}

DRAW4      ICON   "DRAW2.ICO"   /* 圖示 */
   ⁝

組譯與連結

組譯與連結的步驟，都和 DRAW2 相同，只是檔名不同，參考第十五章。另外，這一章的兩個例子並沒有列出完整的程式碼，如要對照 DRAW2 還原可能不易，於 Mega 放置 DRAW3、DRAW4 的完整原始碼，按此處下載。

註解

註一：有關 Windows API、TrackPopupMenu、TPM_NONOTIFY 的調查結果

註一是取自網路上的文章，原文請看ミルノのブログ，標題翻譯成中文，就是「有關 Windows API、TrackPopupMenu、TPM_NONOTIFY 的調查結果」。其內容大意如下：

在很多文獻中提到「在呼叫 TrackPopupMenu 時，若以 TPM_NONOTIFY 為參數，TrackPopupMenu 不會發送通知訊息」這從頭到尾都錯了。並不是翻譯上的錯誤，因為一開始就錯了。作者寫了個程式來研究 TPM_NONOTIFY 的行為，發現當指定 TPM_NONOTIFY 時，將不再發出以下訊息：

但也有可能作者所撰寫的程式沒偵測到，也還有其他訊息被抑制而未發出。

順便說一句，只需指定 TPM_RETURNCMD，傳送到父視窗的 WM_COMMAND 訊息被抑制。相反，即使指定了 TPM_NONOTIFY，WM_COMMAND 也會發生。因此，當使用TPM_RETURNCMD時，無需指定 TPM_NONOTIFY。