Функция CreateWindowExA (winuser.h)

Статья
08/27/2023

Создает перекрывающееся, всплывающее или дочернее окно с расширенным стилем окна; В противном случае эта функция идентична функции 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 . Атом должен быть в нижнем порядке в слове 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, после создания окна диспетчер окон вызывает ShowWindow с флагом SW_SHOW . Если параметр y является другим значением, диспетчер окон вызывает ShowWindow с этим значением в качестве параметра nCmdShow .

[in] nWidth

Тип: int

Ширина окна в единицах устройства. Для перекрывающихся окон nWidth — это ширина окна в координатах экрана или CW_USEDEFAULT. Если nWidthCW_USEDEFAULT, система выбирает ширину и высоту окна по умолчанию; ширина по умолчанию простирается от начальных координат X до правого края экрана; Высота по умолчанию простирается от начальной координаты Y до верхней части области значка. CW_USEDEFAULT допустимо только для перекрывающихся окон; Если для всплывающего или дочернего окна указано CW_USEDEFAULT, то для параметров nWidth и nHeight устанавливается значение 0.

[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 ), на которое указывает параметр lParamWM_CREATE сообщения. Это сообщение отправляется в созданное окно этой функцией перед возвратом.

Если приложение вызывает CreateWindow для создания клиентского окна MDI, lpParam должен указывать на структуру CLIENTCREATESTRUCT . Если окно клиента MDI вызывает CreateWindow для создания дочернего окна MDI, lpParam должен указывать на структуру MDICREATESTRUCT . Если дополнительные данные не требуются, lpParam может иметь значение NULL.

Возвращаемое значение

Тип: HWND

Если функция выполняется успешно, возвращаемое значение является дескриптором для нового окна.

Если функция завершается сбоем, возвращается значение NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Эта функция обычно завершается сбоем по одной из следующих причин:

недопустимое значение параметра
системный класс зарегистрирован другим модулем
Установлен обработчик WH_CBT и возвращает код сбоя.
Если один из элементов управления в шаблоне диалогового окна не зарегистрирован или его оконная процедура завершается сбоем WM_CREATE или WM_NCCREATE

Если созданное окно является дочерним, его позиция по умолчанию находится в нижней части 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 , см. в разделе Статические стили элементов управления.

Значение WS_EX_NOACTIVATEдля dwExStyle предотвращает активацию переднего плана системой. Чтобы предотвратить активацию очереди, когда пользователь щелкает окно, необходимо соответствующим образом обработать WM_MOUSEACTIVATE сообщение. Чтобы перевести окно на передний план или активировать его программным способом, используйте SetForegroundWindow или SetActiveWindow. Если вернуть значение FALSEв WM_NCACTIVATE , окно не потеряет активацию очереди. Однако возвращаемое значение игнорируется во время активации.

Если WS_EX_COMPOSITED задано, все потомки окна получают порядок рисования снизу вверх с помощью двойной буферизации. Порядок рисования снизу вверх позволяет окну-потомку иметь эффекты прозрачности (альфа) и прозрачности (цветовая клавиша), но только в том случае, если в окне-потомке также задан бит 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 в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll
Набор API	ext-ms-win-ntuser-window-l1-1-0 (представлено в Windows 8)