Analysis of the ShowWindow() and ShowModal() functions of the Duilib form and some properties of the duilib control

Create function description preface

HWND CWindowWnd::Create(HWND hwndParent, LPCTSTR pstrName, DWORD dwStyle, DWORD dwExStyle, int x, int y, int cx, int cy, HMENU hMenu)
{
    
    
    if( GetSuperClassName() != NULL && !RegisterSuperclass() ) return NULL;
    if( GetSuperClassName() == NULL && !RegisterWindowClass() ) return NULL;
    m_hWnd = ::CreateWindowEx(dwExStyle, GetWindowClassName(), pstrName, dwStyle, x, y, cx, cy, hwndParent, hMenu, CPaintManagerUI::GetInstance(), this);
    ASSERT(m_hWnd!=NULL);
    return m_hWnd;
}

1. Form creation process

In the article "Reverse Analysis of Windows Message Mechanism", the Windows message mechanism and the creation process of the form are analyzed in detail. The article states that the creation of the Windows form is divided into three steps: declaring the WNDCLASS instance, registering the form, and creating the form . If you continue to subdivide, it can be divided into four steps: declare the WNDCLASS instance, register the form, create the form, and display the form.

The window registration function is RegisterClass() or RegisterClassEx() , the window creation is CreateWindow() or CreatewindowEx() function, and the window display is the ShowWindow() function.

This article focuses on the ShowWindow() function.

2. ShowWindow function

After CreateWindowEx creates a window, at this time, although the window has been created, it has not yet been displayed on the screen.

3. ShowWindow function

Function function: This function sets the display state of the specified window.

Function prototype: BOOL ShowWindow (HWND hWnd, int nCmdShow)

Where hWnd refers to the window handle; nCmdShow specifies how the window is displayed. If the program sending the application provides a STARTUPINFO structure, this parameter is ignored the first time the application calls ShowWindow . Otherwise, when the ShowWindow function is called for the first time , the value should be the nCmdShow parameter in the function WinMain . On subsequent calls, this parameter can be one of the following values:

int APIENTRY _tWinMain(_In_ HINSTANCE hInstance,
	_In_opt_ HINSTANCE hPrevInstance,
	_In_ LPTSTR    lpCmdLine,
	_In_ int       nCmdShow)

void ShowWindow(bool bShow = true, bool bTakeFocus = true);

void CWindowWnd::ShowWindow(bool bShow /*= true*/, bool bTakeFocus /*= false*/)
{
    
    
    ASSERT(::IsWindow(m_hWnd));
    if( !::IsWindow(m_hWnd) ) return;
    ::ShowWindow(m_hWnd, bShow ? (bTakeFocus ? SW_SHOWNORMAL : SW_SHOWNOACTIVATE) : SW_HIDE);
}

4. ShowModal() function

void ShowModal(HWND hWndParent = ::GetActiveWindow())

Function: Display the window modally, that is, the user cannot interact with other windows until the window is closed.

parameter:

• hWndParent: optional parameter, specify the handle of the parent window, the default is the handle of the current active window. If a parent window handle is specified, then this window will be the parent window of the modal dialog.

5. Some properties of the duilib control

5.1. Windows controls

Create	创建窗口
Close	关闭窗口
ShowWindow	显示或隐藏窗口
ShowModalFake	显示模态对话框（推荐）
CenterWindow	居中窗口，支持扩展屏幕
Init	窗口接收到 WM_CREATE 消息时会被调用，一般用于初始化
AttachDialog	绑定窗口的顶层容器
InitControls	初始化控件，在容器中添加控件时会被调用（用于对控件名称做缓存）
ReapObjects	回收控件
GetWindowResourcePath	获取窗口资源路径
SetWindowResourcePath	设置窗口资源路径
GetDefaultFontInfo	获取默认字体信息

5.2, Control control

接口名称	用途
GetParent	获取父容器指针
GetAncestor	根据名称获取祖先容器指针
GetName	获取控件名称，对应 xml 中 name 属性
GetUTF8Name	获取控件名称，对应 xml 中 name 属性
SetName	设置控件名称，内存中设置不会写入 xml 中
SetUTF8Name	设置控件名称，内存中设置不会写入 xml 中（UTF8 编码）
GetWindow	获取关联的窗口指针
SetWindow	设置容器所属窗口
Init	初始化函数
DoInit	由 Init 调用，功能与 Init 相同
IsVisible	判断是否可见
IsInternVisible	待补充
IsFloat	判断控件是否浮动，对应 xml 中 float 属性
SetFloat	设置控件是否浮动
GetFixedWidth	获取固定宽度，对应 xml 中 width 属性
SetFixedWidth	设置控件固定宽度
GetFixedHeight	获取固定高度
SetFixedHeight	设置固定高度
GetMinWidth	获取最小宽度
SetMinWidth	设置最小宽度
GetMaxWidth	获取最大宽度
SetMaxWidth	设置最大宽度
GetMinHeight	获取最小高度
SetMinHeight	设置最小高度
GetMaxHeight	获取最大高度
SetMaxHeight	设置最大高度
GetWidth	获取实际宽度
GetHeight	获取实际高度
GetHorAlignType	获取水平对齐方式
SetHorAlignType	设置水平对齐方式
GetVerAlignType	获取垂直对齐方式
SetVerAlignType	设置垂直对齐方式
IsReEstimateSize	待补充
SetReEstimateSize	待补充
EstimateSize	待补充
GetPos	获取控件位置
SetPos	设置控件位置
Arrange	进行布局
ArrangeAncestor	让父容器排列
IsArranged	判断是否已经排列过
Invalidate	重绘控件
GetPosWithScrollOffset	待补充
GetScrollOffset	待补充
ArrangeSelf	待补充
GetBkColor	获取背景颜色
SetBkColor	设置背景颜色
GetStateColor	获取某个状态下的字体颜色
SetStateColor	设置某个状态下的字体颜色
GetBkImage	获取背景图片位置
GetUTF8BkImage	获取 UTF8 格式的背景图片位置
SetBkImage	设置背景图片
SetUTF8BkImage	设置背景图片（UTF8 格式字符串）
GetStateImage	获取指定状态下的图片位置
SetStateImage	设置某个状态下的图片
GetForeStateImage	获取指定状态下的前景图片
SetForeStateImage	设置某个状态下前景图片
GetState	获取控件状态
SetState	设置控件状态
GetEstimateImage	获取控件图片指针
GetBorderSize	获取边框大小
SetBorderSize	设置边框大小
GetBorderColor	获取边框颜色
SetBorderColor	设置边框颜色
SetBorderSize	设置边框的大小
GetLeftBorderSize	获取左侧边框大小
SetLeftBorderSize	设置左侧边框大小
GetTopBorderSize	获取顶部边框大小
SetTopBorderSize	设置顶部边框大小
GetRightBorderSize	获取右侧边框大小
SetRightBorderSize	设置右侧边框大小
GetBottomBorderSize	获取下方边框大小
SetBottomBorderSize	设置下方边框大小
GetBorderRound	获取边框大小
SetBorderRound	设置边框大小
GetCursorType	获取鼠标指针类型
SetCursorType	设置当前鼠标指针类型
GetToolTipText	获取控件在鼠标悬浮状态下的提示文本
GetUTF8ToolTipText	获取控件在鼠标悬浮状态下的提示文本（UTF8 格式）
SetToolTipText	设置鼠标悬浮到控件显示的提示文本
SetUTF8ToolTipText	设置鼠标悬浮到控件显示的提示文本（UTF8 格式）
SetToolTipTextId	设置鼠标悬浮到控件显示的提示文本在语言文件中对应的文字
SetUTF8ToolTipTextId	设置鼠标悬浮到控件显示的提示文本在语言文件中对应的文字（UTF8 格式）
SetToolTipWidth	设置鼠标悬浮到控件上提示的文本单行最大宽度
GetToolTipWidth	获取鼠标悬浮到控件上提示的文本单行最大宽度
IsContextMenuUsed	控件是否响应右键菜单消息
SetContextMenuUsed	设置控件响应右键菜单消息
GetDataID	获取用户绑定到控件的数据字符串
GetUTF8DataID	获取用户绑定到控件的数据字符串（UTF8 格式）
SetDataID	绑定一个字符串数据到控件
SetUTF8DataID	绑定一个字符串数据到控件（UTF8 格式）
GetUserDataBase	获取用户绑定的自定义数据结构
SetUserDataBase	绑定自定义数据到控件，用户可继承 UserDataBase 来补充需要绑定的数据
SetVisible	设置控件是否可见
SetInternVisible	待补充
SetVisible_	待补充
IsEnabled	检查控件是否可用
SetEnabled	设置控件可用状态
IsMouseEnabled	检查控件是否响应鼠标事件
SetMouseEnabled	设置控件是否响应鼠标事件
IsKeyboardEnabled	检查控件是否响应键盘事件
SetKeyboardEnabled	设置控件是否响应键盘事件
IsFocused	检查控件是否具有焦点
SetFocus	让控件获取焦点
SetNoFocus	让控件设置永远获取不到焦点
GetControlFlags	返回控件的标识，用于判断是否可以响应 TAB 切换事件
IsMouseFocused	判断当前鼠标焦点是否在控件上
SetMouseFocused	设置是否将鼠标焦点到控件上
IsActivatable	判断控件当前是否是激活状态
Activate	待补充
FindControl	根据坐标查找指定控件
GetPos	获取控件位置
SetPos	设置控件位置
GetMargin	获取控件的外边距
SetMargin	设置控件的外边距
EstimateSize	计算控件大小
EstimateText	待补充
IsPointInWithScrollOffset	检查指定坐标是否在滚动条当前滚动位置的范围内
HasHotState	判断控件是否处于 HOT 状态
SetReceivePointerMsg	设置控件是否响应触控消息
IsReceivePointerMsg	判断控件是否响应触控消息
SetNeedButtonUpWhenKillFocus	设置控件失去焦点时是否发送鼠标弹起消息
IsNeedButtonUpWhenKillFocus	判断控件失去焦点时是否发送鼠标弹起消息
SetAttribute	设置控件指定属性
SetClass	设置控件的 class 全局属性
ApplyAttributeList	应用一套属性列表
OnApplyAttributeList	待补充
HandleMessageTemplate	控件统一的消息处理入口，将传统 Windows 消息转换为自定义格式的消息
HandleMessageTemplate	将转换后的消息派发到消息处理函数
GetImage	根据图片路径缓存图片信息
DrawImage	绘制图片
GetRenderContext	获取绘制上下文对象
ClearRenderContext	清理绘制上下文对象
AlphaPaint	待补充
Paint	绘制控件的入口函数
PaintChild	绘制控件子项入口函数
SetClip	设置是否对绘制范围做剪裁限制
IsClip	判断是否对绘制范围做剪裁限制
SetAlpha	设置控件透明度
GetAlpha	获取控件透明度
IsAlpha	检查控件是否有透明属性
SetHotAlpha	设置焦点状态透明度
GetHotAlpha	获取焦点状态透明度
GetRenderOffset	获取控件绘制偏移量
SetRenderOffset	设置控件绘制偏移量
SetRenderOffsetX	设置控件偏移的 X 坐标
SetRenderOffsetY	设置控件偏移的 Y 坐标
StartGifPlayForUI	播放 GIF
StopGifPlayForUI	停止播放 GIF
AttachGifPlayStop	监听 GIF 播放完成通知

6. The difference between ShowWindow() and ShowModal()

• ShowWindow() is used to display the window in a non-modal manner, the window will be displayed on the screen, and the user can interact with other windows, that is, multiple windows can be operated at the same time.
• ShowModal() is used to display a window modally, and the window will be displayed on the screen, but when the user interacts with the window, he cannot operate other windows at the same time until the modal window is closed.

When in use, according to the specific needs and interaction methods, select the appropriate function to display the window to achieve the desired user experience. If you want the window to be displayed non-modally and allow the user to interact with other windows, you can use ShowWindow() ; if you want the window to be displayed modally, blocking the user from interacting with other windows until the modal window is closed, you can use ShowModal() .

6.1, the difference between the non-mode mode and the mode mode in DuiLib

• Display method :
  • Non-modal mode: The window is displayed in a non-modal mode without blocking the user from interacting with other windows. Users can operate multiple windows at the same time, and can switch between windows freely.
  • Modal mode: The window is displayed modally, blocking the user's interaction with other windows. While the modal window is open, the user can only interact with the window and cannot operate other windows until the modal window is closed.
• User interaction :
  • Non-modal mode: The user can interact with other windows while the window is displayed. For example, when editing text content in an editing window, you can still click on other windows or perform other operations.
  • Modal mode: The user can only interact with the modal window and cannot switch to other windows while the modal window is open. This ensures that the user is focused on interacting with the modal window until the corresponding action is completed.
• Relationship between windows :
  • Non-modal mode: There is no direct parent-child relationship between windows, they are independent top-level windows that can exist on the screen at the same time.
  • Modal way: A modal window has a parent window, usually the window that opened it. When the modal window is opened, the parent window will be set to an inoperable state, and the parent window will be restored to the operable state only after the modal window is closed.
• Closing method :
  • Non-modal mode: A non-modal window can be closed by the close button or other operations.
  • Modal approach: Modal windows usually have OK or Cancel buttons through which the user must close the modal window.
    Summarize:

The non-modal mode is suitable for the situation where the user can operate multiple windows at the same time, without blocking the user's interaction with other windows.
The modal method is suitable for situations that require the user to focus on a specific task or operation, and it blocks the user's interaction with other windows until the modal window completes the task or closes.

Modeless mode (non-modal dialog box) and modal mode (modal dialog box) are two different ways of displaying windows, and they have some differences in terms of user interaction and application behavior.

• Non-modal mode (non-modal dialog box) :

  • Features: A window displayed in a modeless manner does not block the user from interacting with other windows.
  • User interaction: Users can operate multiple windows at the same time, including interacting with other application windows, without waiting for the window to close.
  • Application Behavior: Non-modal dialog boxes are usually used to display temporary information, options, or functions, and users can freely switch and operate between different windows.

• Modal way (modal dialog) :

  • Features: Modally displayed windows block the user from interacting with other windows.
  • User interaction: The user can only interact with the modal dialog box, and cannot interact with other windows until the modal dialog box is closed.
  • Application Behavior: Modal dialog boxes are usually used to display important information, must be confirmed by the user, or provide required items to ensure that the user cannot switch to other windows while processing the content of the dialog box until the dialog box is closed.

Summary:
Non-modal dialog boxes are suitable for scenarios where users can operate multiple windows at the same time, and are suitable for general information display and temporary functions.
Modal dialog boxes are suitable for situations that require the user to concentrate on processing, ensuring that the user cannot switch to other windows to prevent ignoring or missing important information.

6.2. Use MessageLoop() and ShowModal() in ShowWindow() mode without using MessageLoop()

• ShowWindow()：
  • ShowWindow() displays the window in a non-modal manner, that is, the user can interact with other windows while the window is displayed.
  • Generally, when using ShowWindow(), you need to add a message processing function in the main message loop to respond to window messages and handle window interactions and events.
  • The main message loop is usually an infinite loop that receives and dispatches messages until the program exits.
• ShowModal()：
  • ShowModal() displays the window modally, that is, the user cannot interact with other windows until the window is closed.
  • When using ShowModal(), there is no need to create a message loop separately. The ShowModal() method in DuiLib will start a modal message loop internally, and will not return to the place where ShowModal() was called until the modal dialog box is closed.
  • The call of ShowModal() will block the execution of the program until the modal dialog box is closed, and then continue to execute subsequent codes.

Example:

// 使用 ShowWindow()
CPaintManagerUI::SetInstance(hInstance);
CPaintManagerUI::SetCurrentPath(CPaintManagerUI::GetInstancePath());

CMainDlg *pFrame = new CMainDlg;
pFrame->Create(NULL, _T("DUIWnd"), UI_WNDSTYLE_FRAME, WS_EX_WINDOWEDGE);
pFrame->ShowWindow();
CPaintManagerUI::MessageLoop();

// 使用 ShowModal()
CMainDlg *pFrame = new CMainDlg;
pFrame->Create(NULL, _T("DUIWnd"), UI_WNDSTYLE_FRAME, WS_EX_WINDOWEDGE);
pFrame->ShowModal();

Summarize:

• ShowWindow() needs to create the main message loop by itself, and process window messages and events in it.
• ShowModal() internally starts the modal message loop, and does not need to create a separate message loop, which will block the execution of the program until the modal dialog box is closed.