CreateWindowExA 函式 (winuser.h)

發行項
01/27/2024

建立具有擴充視窗樣式的重疊、彈出視窗或子視窗;否則，此函式與 CreateWindow 函式相同。如需建立視窗以及 CreateWindowEx 其他參數完整描述的詳細資訊，請參閱 CreateWindow。

語法

HWND CreateWindowExA(
  [in]           DWORD     dwExStyle,
  [in, optional] LPCSTR    lpClassName,
  [in, optional] LPCSTR    lpWindowName,
  [in]           DWORD     dwStyle,
  [in]           int       X,
  [in]           int       Y,
  [in]           int       nWidth,
  [in]           int       nHeight,
  [in, optional] HWND      hWndParent,
  [in, optional] HMENU     hMenu,
  [in, optional] HINSTANCE hInstance,
  [in, optional] LPVOID    lpParam
);

參數

[in] dwExStyle

類型： DWORD

正在建立之視窗的擴充視窗樣式。如需可能值的清單，請參閱擴充窗口樣式。

[in, optional] lpClassName

類型： LPCTSTR

Null 終止的字串或先前呼叫 RegisterClass 或 RegisterClassEx 函式所建立的類別 Atom。 Atom 必須以低順序的 lpClassName 字組表示;高序字必須是零。如果 lpClassName 是字串，它會指定視窗類別名稱。類別名稱可以是向 RegisterClass 或 RegisterClassEx 註冊的任何名稱，前提是註冊類別的模組也是建立窗口的模組。類別名稱也可以是任何預先定義的系統類別名稱。

[in, optional] lpWindowName

類型： LPCTSTR

視窗名稱。如果視窗樣式指定標題列， lpWindowName 指向的視窗標題會顯示在標題列中。使用 CreateWindow 建立控件時，例如按鈕、複選框和靜態控件，請使用 lpWindowName 來指定控件的文字。使用 SS_ICON 樣式建立靜態控件時，請使用 lpWindowName 來指定圖示名稱或標識符。若要指定標識碼，請使用語法 “#num”。

[in] dwStyle

類型： DWORD

正在建立之窗口的樣式。此參數可以是視窗樣式值的組合，加上一節中所指出的控件樣式。

[in] X

類型： int

視窗的初始水準位置。對於重疊或彈出視窗， x 參數是視窗左上角的初始 X 座標，以螢幕座標表示。針對子視窗， x 是相對於父視窗工作區左上角之視窗左上角的 X 座標。如果 x 設定為 CW_USEDEFAULT，系統會選取視窗左上角的預設位置，並忽略 y 參數。 CW_USEDEFAULT 僅適用於重疊視窗;如果已針對彈出視窗或子視窗指定， 則 x 和 y 參數會設定為零。

[in] Y

類型： int

視窗的初始垂直位置。對於重疊或彈出視窗， y 參數是視窗左上角的初始 Y 座標，以螢幕座標表示。針對子視窗， y 是子視窗左上角的初始 Y 座標，相對於父視窗工作區的左上角。對於清單框 y 是清單框工作區左上角相對於父視窗工作區左上角的初始 Y 座標。

如果使用 WS_VISIBLE 樣式位集建立重疊的視窗，且 x 參數設定為 CW_USEDEFAULT， 則 y 參數會決定視窗的顯示方式。如果 y 參數CW_USEDEFAULT，則視窗管理員會在建立窗口之後，使用 SW_SHOW 旗標呼叫 ShowWindow。如果 y 參數是一些其他值，則視窗管理員會以該值呼叫 ShowWindow ，並將該值作為 nCmdShow 參數。

[in] nWidth

類型： int

視窗的寬度，以裝置單位為單位。對於重疊的視窗， nWidth 是視窗的寬度、螢幕座標或 CW_USEDEFAULT。如果 nWidth是CW_USEDEFAULT，系統會選取視窗的預設寬度和高度;默認寬度會從初始 X 座標延伸至畫面右邊緣;預設高度會從初始 Y 座標延伸到圖示區域的頂端。 CW_USEDEFAULT 僅適用於重疊視窗;如果已為彈出視窗或子視窗指定CW_USEDEFAULT， 則 nWidth 和 nHeight 參數會設定為零。

[in] nHeight

類型： int

視窗的高度，以裝置單位為單位。對於重疊的視窗， nHeight 是視窗的高度，以螢幕座標表示。如果 nWidth 參數設定為 CW_USEDEFAULT，系統會忽略 nHeight。

[in, optional] hWndParent

類型： HWND

所建立視窗之父視窗或擁有者視窗的句柄。若要建立子視窗或擁有的視窗，請提供有效的視窗句柄。這個參數是彈出視窗的選擇性參數。

若要建立僅限訊息的視窗，請提供 HWND_MESSAGE 或現有僅限訊息視窗的句柄。

[in, optional] hMenu

類型： HMENU

功能表的句柄，或指定子視窗標識符，視視窗樣式而定。針對重疊或彈出視窗， hMenu 會識別要與視窗搭配使用的功能表;如果要使用類別功能表，它可以是 NULL 。針對子視窗， hMenu 會指定子視窗標識碼，這是對話框控件用來通知其父代事件的整數值。應用程式會決定子視窗識別碼;對於具有相同父視窗的所有子視窗而言，它必須是唯一的。

[in, optional] hInstance

類型： HINSTANCE

要與視窗相關聯之模組實例的句柄。

[in, optional] lpParam

類型： LPVOID

要透過 CREATESTRUCT 結構傳遞至視窗的值指標， (lpCreateParams 成員) WM_CREATE訊息的 lParam 參數所指向。此訊息會在傳回之前，由此函式傳送至建立的視窗。

如果應用程式呼叫 CreateWindow 來建立 MDI 用戶端視窗， lpParam 應該指向 CLIENTCREATESTRUCT 結構。如果 MDI 用戶端視窗呼叫 CreateWindow 來建立 MDI 子視窗， lpParam 應該指向 MDICREATESTRUCT 結構。如果不需要其他數據，lpParam 可能是 NULL。

傳回值

類型： HWND

如果函式成功，傳回值會是新視窗的句柄。

如果函式失敗，傳回值為 NULL。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

此函式通常會因為下列其中一個原因而失敗：

無效的參數值
系統類別是由不同的模塊註冊
已安裝 WH_CBT 勾點，並傳回失敗碼
如果未註冊對話框範本中的其中一個控件，或其視窗視窗程式 WM_CREATE 或 WM_NCCREATE

備註

CreateWindowEx 函式會將WM_NCCREATE、WM_NCCALCSIZE和WM_CREATE訊息傳送至所建立的視窗。

如果建立的視窗是子視窗，其預設位置會位於 Z 順序的底部。如果建立的視窗是最上層視窗，則其預設位置位於 Z 順序的頂端 (，但除非建立的視窗本身是最上層的視窗) 底下。

如需控制任務列是否顯示已建立視窗按鈕的資訊，請參閱管理任務列按鈕。

如需移除視窗的資訊，請參閱 DestroyWindow函式。

您可以在 lpClassName 參數中指定下列預先定義的控制項類別。請注意您可以在 dwStyle 參數中使用的對應控件樣式。

類別	意義
按鈕	指定小型矩形子視窗，代表使用者可以按下以開啟或關閉按鈕的按鈕。按鈕控制項可以單獨或群組使用，而且可以標示或顯示沒有文字。當使用者按鍵時，按鈕控制項通常會變更外觀。如需詳細資訊，請參閱按鈕。如需您可以在 dwStyle 參數中指定的按鈕樣式表格，請參閱按鈕樣式。
COMBOBOX	指定由清單框和類似編輯控制件的選取欄位所組成的控制件。使用此樣式時，應用程式應該隨時顯示清單框，或啟用下拉式清單框。如果顯示清單框，在選取字段中輸入字元會反白顯示符合輸入字元的第一個清單框專案。相反地，選取清單框中的項目會顯示選取欄位中選取的文字。如需詳細資訊，請參閱下拉式方塊。如需您可以在 dwStyle 參數中指定的下拉式方塊樣式數據表，請參閱下拉式方塊樣式。
編輯	指定矩形子視窗，用戶可以在其中輸入鍵盤中的文字。用戶選取控件，並藉由單擊控件或按 TAB 鍵移至它來提供鍵盤焦點。當使用者編輯控件顯示閃爍插入號時，可以輸入文字;使用滑鼠移動游標、選取要取代的字元，或放置插入字元的游標;或使用索引鍵來刪除字元。如需詳細資訊，請參閱編輯控件。如需您可以在 dwStyle 參數中指定的編輯控件樣式數據表，請參閱編輯控件樣式。
LISTBOX	指定字元字串的清單。每當應用程式必須顯示名稱清單，例如檔名，使用者可以從中選擇時，請指定此控件。用戶可以按下字串來選取字串。已醒目提示選取的字串，並將通知訊息傳遞至父視窗。如需詳細資訊，請參閱清單框。如需您可以在 dwStyle 參數中指定的清單框樣式數據表，請參閱清單框樣式。
MDICLIENT	指定 MDI 用戶端視窗。此視窗會接收控制 MDI 應用程式子視窗的訊息。建議的樣式位WS_CLIPCHILDREN和WS_CHILD。指定 WS_HSCROLL 和 WS_VSCROLL 樣式，以建立 MDI 用戶端視窗，讓使用者將 MDI 子視窗捲動到檢視中。如需詳細資訊，請參閱多個檔介面。
RichEdit	指定 Microsoft Rich Edit 1.0 控制件。此視窗可讓用戶檢視及編輯具有字元和段落格式的文字，並可包含內嵌元件物件模型 (COM) 物件。如需詳細資訊，請參閱 Rich Edit Controls。如需您可以在 dwStyle 參數中指定的豐富編輯控件樣式數據表，請參閱 Rich Edit 控制樣式。
RICHEDIT_CLASS	指定 Microsoft Rich Edit 2.0 控制件。此控制項可讓使用者檢視及編輯具有字元和段落格式的文字，並可包含內嵌 COM 物件。如需詳細資訊，請參閱 Rich Edit Controls。如需您可以在 dwStyle 參數中指定的豐富編輯控件樣式數據表，請參閱 Rich Edit 控制樣式。
SCROLLBAR	指定包含滾動盒的矩形，並在兩端都有方向箭號。每當使用者按兩下控制項時，滾動條就會將通知訊息傳送至其父視窗。父視窗負責視需要更新滾動盒的位置。如需詳細資訊，請參閱滾動條。如需您可以在 dwStyle 參數中指定的滾動條控件樣式數據表，請參閱滾動條控件樣式。
靜態	指定用來標記、方塊或分隔其他控件的簡單文字欄位、方塊或矩形。靜態控件不會接受任何輸入，而且不會提供任何輸出。如需詳細資訊，請參閱靜態控件。如需您可以在 dwStyle 參數中指定的靜態控件樣式數據表，請參閱靜態控件樣式。

dwExStyle的WS_EX_NOACTIVATE值可防止系統前景啟用。若要在使用者按兩下視窗時防止佇列啟用，您必須適當地處理 WM_MOUSEACTIVATE 訊息。若要將視窗帶入前景，或以程式設計方式啟用視窗，請使用 SetForegroundWindow 或 SetActiveWindow。將 FALSE 傳回 WM_NCACTIVATE 可防止視窗失去佇列啟用。不過，在啟用時會忽略傳回值。

設定 WS_EX_COMPOSITED 時，視窗的所有子系都會使用雙緩衝處理，以下至上繪製順序。從下至上繪製順序可讓子系視窗具有透明 (alpha) 和透明度， (色彩索引鍵) 效果，但只有在子代視窗也設定 WS_EX_TRANSPARENT 位時。雙緩衝可讓視窗及其子代繪製，而不會閃爍。

範例

下列範例程式代碼說明 如何使用 CreateWindowExA。

BOOL Create(
        PCWSTR lpWindowName,
        DWORD dwStyle,
        DWORD dwExStyle = 0,
        int x = CW_USEDEFAULT,
        int y = CW_USEDEFAULT,
        int nWidth = CW_USEDEFAULT,
        int nHeight = CW_USEDEFAULT,
        HWND hWndParent = 0,
        HMENU hMenu = 0
        )
    {
        WNDCLASS wc = {0};

        wc.lpfnWndProc   = DERIVED_TYPE::WindowProc;
        wc.hInstance     = GetModuleHandle(NULL);
        wc.lpszClassName = ClassName();

        RegisterClass(&wc);

        m_hwnd = CreateWindowEx(
            dwExStyle, ClassName(), lpWindowName, dwStyle, x, y,
            nWidth, nHeight, hWndParent, hMenu, GetModuleHandle(NULL), this
            );

        return (m_hwnd ? TRUE : FALSE);
    }

注意

winuser.h 標頭會將 CreateWindowEx 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winuser.h (包括 Windows.h)
程式庫	User32.lib
Dll	User32.dll
API 集合	ext-ms-win-ntuser-window-l1-1-0 (於 Windows 8)