EnableDocking
EnableDocking是微软基础类库(MFC)中的一个成员函数,用于开启可停靠控件条在框架窗口中的停靠能力。同一名称的成员函数分别出现在框架窗口类(CFrameWnd)、控件条类(CControlBar)和窗格基类(CBasePane)中,调用方分别声明自己接受或希望停靠的边,两者匹配时停靠才会生效。它是MFC界面中工具栏、窗格随窗口布局调整的基础机制之一。
定义
EnableDocking是微软基础类库(MFC)提供的一个类成员函数,其作用是让可停靠的控件条能够附着在框架窗口的边缘。该函数并非单一实现,而是以同名成员函数的形式分布在多个类中:框架窗口类CFrameWnd用它声明窗口哪一侧可以作为停靠目标,CControlBar类用它声明控件条希望停靠到哪一侧,较新的CBasePane类同样以该名称开启窗格向主框架的停靠[1][2][3]。
各版本原型均形式为void EnableDocking(DWORD ...),参数是一个由样式位组成的双字值,指示允许停靠的方位[2][3]。CFrameWnd版本的声明位于头文件afxwin.h中,CBasePane版本则位于afxbasepane.h中[2][3]。
该函数的核心是一个方位掩码。可用的取值包括CBRS_ALIGN_TOP、CBRS_ALIGN_BOTTOM、CBRS_ALIGN_LEFT、CBRS_ALIGN_RIGHT,分别对应客户区的上、下、左、右,CBRS_ALIGN_ANY则是全部方位的组合[2][4]。当一次停靠存在多个可选边时,框架按照上、下、左、右的固定次序取用[1]。
在CBasePane的实现中,EnableDocking并不直接移动窗口,而是写入内部成员m_dwEnabledAlignment,框架在停靠发生时读取该标志作出判断;调用方可通过GetEnabledAlignment查询已启用的方位[3][4]。也就是说,该函数完成的是资格登记,真正的吸附动作由框架的停靠逻辑执行。
停靠成败取决于两端的方位集合是否有交集。若控件条所声明的边在框架窗口已启用的边中找不到对应项,控件条便无法停靠,只能以浮动形式存在[1][5]。文档还提到,控件条一旦进入浮动状态,便不再具备回落到框架窗口停靠的能力[6]。
在早期的MFC版本中,可停靠工具栏的搭建被归纳为3个固定步骤:先用CFrameWnd::EnableDocking开启框架窗口的停靠,再对每个工具栏调用CControlBar::EnableDocking,最后以CFrameWnd::DockControlBar完成附着;若任一步骤缺失,程序只显示普通的标准工具栏[5]。Visual Studio 6.0时期的示例程序DOCKTOOL即用于演示这套机制,浮动部分依赖迷你框架窗口类CMiniFrameWnd实现[5]。
Visual Studio 2008 的文档中,CFrameWnd::EnableDocking 的参数说明与头文件归属已经与后来的版本一致,说明该接口在较长时间内保持稳定[2]。Visual Studio 2010 一代引入了面向窗格体系的CBasePane::EnableDocking,把同一概念延伸到停靠窗格,并以m_dwEnabledAlignment与GetEnabledAlignment构成配套的查询接口[3]。
在后续的 MFC 文档中,与可停靠工具栏配套的还有CMFCToolBar等同名方法,其参数为dwAlignment,说明这一命名被多个界面类沿用[7]。
最常见的用途是让工具栏围绕主框架排列。应用程序向导生成带停靠工具栏的框架时,会同时写入开启窗口停靠、开启工具栏停靠和调用停靠三个环节的代码,开发者只需按需修改方位参数[1][6]。传入CBRS_ALIGN_ANY可让控件条在客户区任意一边停靠[2]。
在停靠窗格体系中,由CDockablePane派生的窗格创建后通常不能立即停靠,需先调用EnableDocking再调用DockPane,窗格才会显示并具备停靠行为[8]。
除初始化外,该函数也可在运行期调整布局时使用,但与DockControlBar、FloatControlBar等函数配合,前者负责登记方位,后者负责实际附着或分离[1]。若希望工具栏永久浮动,可以参数0调用,再调用FloatControlBar,控件条便始终无法停靠[1]。
该函数只登记方位,不负责完成停靠。仅调用EnableDocking而不调用DockControlBar,控件条不会自动附着到框架窗口[5]。两端方位不匹配时,函数调用虽然成功,控件条却仍无法停靠[1]。
控件条一旦浮动,就无法再停靠回框架窗口,这一单向特性限制了运行期布局的灵活度;如需恢复,通常要借助SaveBarState与LoadBarState一类的状态保存与读取函数[6][5]。
MFC 对可停靠工具栏的实现并不覆盖某些应用程序中的扩展能力,例如可自定义工具栏这类功能并未提供[1]。此外,在窗格体系中,隐藏或处于自动隐藏状态的控件在停靠相关操作上可能出现异常,需要在处理前先退出该状态[9]。
-
CFrameWnd —— MFC 的框架窗口类,其 EnableDocking 声明窗口接受停靠的方位。
-
CControlBar —— MFC 控件条基类,其 EnableDocking 声明控件条希望停靠的方位。
-
DockControlBar —— 与 EnableDocking 配套、实际执行停靠的框架窗口成员函数。
-
FloatControlBar —— 把控件条从框架窗口分离、转为浮动状态的函数。
-
微软基础类库 —— EnableDocking 所属的 C++ 类库。
-
停靠窗口 —— 可固定在主窗口边缘的工具窗口,与停靠机制直接相关。
参考资料
- 停靠和浮动工具栏 - 跳转至主内容 跳到 Ask Learn 聊天体验 [引用日期2026-10-29]
- CFrameWnd::EnableDocking [引用日期2026-10-29]
- CBasePane::EnableDocking [引用日期2026-10-29]
- [in] A pointer to another pane [引用日期2026-10-29]
- aa232548(v=vs [引用日期2026-10-29]
- 停駐和浮動工具列 [引用日期2026-10-29]
- CMFCToolBar::EnableDocking [引用日期2026-10-29]
- 停靠窗口 [引用日期2026-10-29]
- SetEnableDocking exception | WinForms | Tools | Syncfusion [引用日期2026-10-29]