BkWin界面框架使用说明

袁鸿畴

2023-12-01

BkWin界面框架使用说明

一、简单说明

1. 使用XML定义界面

窗口分为三部分：header、footer、body，至少应该包含一个部分，header的空白部分是可以拖动的，窗口resize时header和footer高度不变，body自适应

Body

Footer

Header

所有xml格式采用utf-8编码，或使用ATL::CW2A类由Unicode字符串转换

2. 资源统一管理

提供了BkBmpPool、BkFontPool、BkString管理界面中用到的位图、字体、字符串资源，头文件放置在bkres目录下

BkBmpPool和BkFontPool一般情况下不需要调用

BkBmpPool会根据资源ID自动加载对应的位图资源，退出时一起释放

BkString需要加载xml资源

3. 实现了对话框模式和流模式

i. 对话框模式

使用pos属性定位，嵌套采用dlg标签

ii. 流模式

类似html的流式排版，在部分情况下会比较麻烦，除非需要，不建议使用

二、XML格式

1. skin定义

i. Xml实例

<skins>

</skins>

skin用于定义一些固定的图片绘制格式

所有skin均包含name属性，在style和若干控件中指定，下面就不描述了

在应用程序开始时通过BkSkin::LoadSkins方法加载指定资源ID的skin定义xml，资源分类必须为“BKRES”

skin包含Normal/Hover/Pushdown/Disable四种状态，当skin使用了ImageList时，ImageList中的图片必须按照此顺序水平排列

ii. skins标签

无属性，包含若干可能的皮肤格式

iii. button标签

定义一个很像vista按钮的样式，使用贴图就用不到了

iv. imgframe标签

定义一个四角不变，中间一像素宽（高）四向拉伸的frame样式skin

属性：

属性名：	说明
src	位图资源ID
mode	none：不透明 mask：透明色 alpha：alpha通道透明，需要32位RGBA位图
maskcolor	如果mode=mask，则指定透明色，默认FF00FF ■
subwidth	如果图片资源是ImageList，用这个参数指定ImageList中单个图片的宽度
crbg	Frame中间填充的背景颜色(十六进制RRGGBB格式)
top	Frame上界高度(px)
left	Frame左界宽度(px)
part	all：整个frame（默认） top：不包含底部边框 middle：只有垂直中部边框 bottom：不包含头部边框 left：不包含右边框 center：只有水平中部边框 right：不包含左边框

v. imghorzex标签

定义一个左右不变，中间一像素宽水平拉伸的frame样式skin

属性：

属性名：	说明
src	位图资源ID
mode	none：不透明 mask：透明色 alpha：alpha通道透明，需要32位RGBA位图（目前版本可能有bug，未实验）
maskcolor	如果mode=mask，则指定透明色，默认FF00FF ■
subwidth	如果图片资源是ImageList，用这个参数指定ImageList中单个图片的宽度
left	Frame左界宽度(px)

vi. imglist标签

定义一个图片列表样式skin，一般用于img和imgbtn控件

属性：

属性名：	说明
src	位图资源ID
mode	none：不透明 mask：透明色 alpha：alpha通道透明，需要32位RGBA位图
maskcolor	如果mode=mask，则指定透明色，默认FF00FF ■
subwidth	如果图片资源是ImageList，用这个参数指定ImageList中单个图片的宽度

2. style定义

i. Xml实例

<style>

</style>

Style用于定义控件的样式，包括使用的skin、文字对齐方式、字体、文字颜色、背景色、鼠标指针形状等

流模式还可以指定边距、行间距、行内控件间距等等

在应用程序开始时通过BkStyle::LoadStyles方法加载指定资源ID的Style定义xml，资源分类必须为“BKRES”

ii. class标签

定义一个样式

属性：

属性名：	说明
name	Style的名字，用于控件的class属性
skin	指定使用的skin，如果指定了有效的skinname，crbg属性被忽略
textmode	文字对齐方式，即DrawText的最后一个参数，格式为十六进制不加“0x”
crbg	背景色，默认不填充背景
crtext	默认情况下文字颜色，默认为000000即黑色
crhover	鼠标移上去时的文字颜色，默认同crtext
crdisabled	控件不可用时的文字颜色，默认CCCCCC
font	字体，4位16进制数，默认宋体12点字(0000)，前两位为字号，正值增大，负值缩小，大字体设置下字号不会改变后两位01斜体、02下划线、04粗体，可叠加
hoverfont	鼠标移上去时的字体，格式同font
x-margin	水平边距(流模式)
y-margin	垂直边距(流模式)
margin	边距(流模式)，设置这个值会同时修改x-margin和y-margin
spacing	行内控件间距(流模式)
linespacing	行距(流模式)
cursor	鼠标移上去时的鼠标指针样式 arrow：普通指针（默认） hand：手型

3. string定义

i. Xml实例

<sid=1>应用程序标题</s>

<sid=2>列1</s>

<sid=3>列2</s>

<sid=4>列3</s>

</string>

定义应用程序中用到的字符串

在应用程序开始时通过BkString::Load方法加载指定资源ID的Style定义xml，资源分类必须为“BKRES”

后加载的字符串表会覆盖先加载的表中相同ID的字符串，此特性可用于OEM订制

4. 窗口框架

i. 框架实例

<body>

</layer>

默认采用流式排版还是对话框式排版，是在调用时由使用哪种窗口类决定的，具体请见Classes节

ii. layer标签

定义一个窗口

属性：

属性名：	说明
title	窗口标题文字，如果设置appwin=1，则显示在任务栏
height	窗口高度(px)
width	窗口宽度(px)
appwin	1对应WS_EX_APPWINDOW
resize	1对应WS_MAXIMIZEBOX \| WS_MINIMIZEBOX
noborder	1对应WS_POPUP \| WS_SYSMENU以及WS_EX_TOOLWINDOW \| WS_EX_TOPMOST 0对应WS_OVERLAPPED \| WS_SYSMENU

iii. header/footer/body标签

定义窗口的一部分

属性：

属性名：	说明
height	高度(px)，body必须为full，header和footer可定义
width	宽度(px)，必须为full

5. 控件

i. 公用属性说明

属性名：	说明：
class	指定一个Style Name
id	指定控件的Command ID，用于消息响应和显示控制，在同一个窗口内必须唯一
href	指定一个链接或者应用程序，用shell的open操作打开，且不会再通知click消息
width	指定控件的宽度 0：自适应文字宽度（默认） full：流模式或对话框模式但未指定宽度时会延伸到右边框，对话框模式不建议使用
height	指定控件的高度 0：自适应文字高度（默认） full：流模式或对话框模式但未指定高度时会延伸到底边框，对话框模式不建议使用
pos	定义控件位置格式为”left,top,right,bottom”，四个数值用半角逗号分隔，正值为左（上）对齐，负值为右（下）对齐 right和bottom可省略，此时控件大小由width和height属性控制不建议流模式下使用
float	控件浮动，用于居中、居右、居下
align	水平对齐方式流模式下，如果float=1，此值生效 left：居左（默认） center：水平居中 right：居右
valign	垂直对齐方式流模式下，如果float=1，此值生效 top：居上（默认） middle：垂直居中 bottom：居下注：div标签也包含此属性，用于定义div内每行控件的垂直对齐模式，如果float=1，div的该属性用于控制div本身，如想控制内部控件垂直对齐模式，请再嵌套一个div并设置valign属性
show	默认是否显示

ii. 控件的InnerText可包含预定义字符串，用法为%str#strid#%

例：

定义字符串表

<sid=1>AppName</s>

</string>

定义窗口

…

…

则指定位置会显示“AppName – 设置”

iii. text标签

定义一个文字控件

以指定字体、前景色和背景色在窗口绘制一段文本

可以用于制作超链接

iv. link标签

就是text，在header中，text标签会被认为是空白位置可以拖动，使用link标签可以用来制作header上的超链接

v. button标签

按钮，其实跟text一样，只是一般会指定一个带skin的style

vi. img标签

在窗口上显示图片

属性：

属性名：	说明
skin	指定imglst
sub	指定当前显示的是imglst中的第几个图片，-1则表示全部

vii. imgbtn标签

图片按钮，使用4张图片的ImageList，如果确定不会被Disable，图片资源中可以只包含前三种状态，用来节省生成的程序大小

属性只有skin，此控件会根据Hover/Pushdown/Disable状态切换Sub Image

viii. progress标签

进度条控件，用于显示一个进度条

属性：

属性名：	说明
bgskin	指定进度条背景skin
posskin	指定进度条进度skin
min	最小值
max	最大值
value	现在的值
showpercent	是否在正中间用文字显示xx%，用crtext和crbg防止显示不清楚

ix. realwnd标签

用于控制一个真实窗口的显示、隐藏

只有一个参数ctrlid，用于绑定对应DlgItemID的控件

要绑定的真实窗口要指定BkWin窗口的View窗口为父窗口，比如在OnInitDialog时创建要绑定的窗口，父窗口参数必须为GetViewHWND()，而不能直接用m_hWnd

x. check标签

复选钮

目前不能选择皮肤，自动套用XP以上的Theme

xi. radio标签

单选钮

目前不能选择皮肤，自动套用XP以上的Theme

属性：

属性名：	说明
group	分组名，同一组的单选钮最多同时只能被选中一个，全局唯一标识，不能重复

xii. icon标签

用于显示一个图标

属性：

属性名：	说明
src	指定图标资源id
oem	是否oem图标 1：是，用于加载IDI_INFORMATION等系统图标 2：否，加载当前资源模块的图标
size	图标大小，16/32/48/64等等注意：由于WindowsAPI一向的bug，如果某ICON资源同时包含1616和3232，则size指定16时，绘制的会是3232缩小后的图标，所以1616的图标需要单独放置一份

xiii. spacing/br/hr标签

用于流模式下绘制空白、换行、直线，就不详细解释了

xiv. div标签

流模式容器，流模式下的header/footer/body其实就是div

也可以用于对话框模式下嵌套一个使用流模式排版的区域

属性：

属性名：	说明
onlydrawchild	子控件只用于绘图，不响应鼠标消息

xv. dlg标签

对话框模式容器，对话框模式下的header/footer/body其实就是dlg

也可以用于流模式下嵌套一个对话框模式排版的区域

属性名：	说明
onlydrawchild	子控件只用于绘图，不响应鼠标消息

xvi. tabctrl标签

显示一个tab控件，标签页的内容用tab标签表示

属性：

属性名：	说明
cursel	当前选中的tabpage，从0开始
tabwidth	tab标签的宽度
tabskin	tab标签的Skin Name
frameskin	tabpage客户区的Skin Name
tableft	第一个tab标签和左边的间距
tabspacing	tab和tab之间的间距，负值则重叠
frametop	tabpage客户区的位置，负值则和标签区域有重叠

xvii. tab标签

暂时是div标签，所以tab内需要使用对话框式排版时要嵌套<dlgpos=”0,0,-0,-0”></dlg>

width和height必须是full

属性：

属性名：	说明
title	tab标签标题
onlydrawchild	子控件只用于绘图，不响应鼠标消息

三、Classes

1. CBkRichWinImpl

实现一个使用BkWin排版的窗口。

最简单的实例如下：

class CTestDlg

: publicCBkRichWinImpl<CTestDlg>

{

public:

CTestDlg()

:CBkRichWinImpl<CTestDlg>(IDR_BK_TEST_DIALOG)

, m_dwPos(0)

{

}

public:

BK_NOTIFY_MAP(IDC_RICHVIEW_WIN)

BK_NOTIFY_ID_COMMAND(IDBK_BTN_CLOSE, OnBkBtnClose)

BK_NOTIFY_TAB_SELCHANGE(IDBK_TAB_MAIN, OnBkTabMainSelChange)

BK_NOTIFY_MAP_END()

BEGIN_MSG_MAP_EX(CTestDlg)

MSG_BK_NOTIFY(IDC_RICHVIEW_WIN)

CHAIN_MSG_MAP(CBkRichWinImpl<CTestDlg>)

END_MSG_MAP()

};

在实例中，CBkRichWinImpl的第一个模板参数必须和派生类相同，第二个模板参数使用默认表示使用对话框模式排版

构造函数可以指定窗口使用的模板资源ID，也可以在后面调用Load方法加载

BK_NOTIFY_MAP和BK_NOTIFY_MAP_END宏用于处理消息

IDC_RICHVIEW_WIN是CBkRichWinImpl中View的DlgCtrlID，直接使用CBkRichWinImpl的时候必须使用IDC_RICHVIEW_WIN

目前可以处理的消息包括：

i. BKNM_COMMAND

根据控件的id属性分发click消息

ii. BKNM_TAB_SELCHANGE

tabctrl切换页面时触发消息

根据tabctrl的id属性分发

iii. BKNM_MOUSEHOVER

鼠标移到窗口时触发消息

和BKNM_MOUSELEAVE主要可以用于pop窗口消失时间的处理

注意：这两个消息没有根据id属性分发

iv. BKNM_MOUSELEAVE

鼠标移出窗口触发消息

主要方法说明（具体参数见头文件定义）：

方法名：	说明
Load	加载指定资源ID的xml模板，资源必须为BKRES类型
GetViewHWND	获得BkRichView窗口句柄，用于创建realwnd标签控制的子窗口
SetPanelXml	重新设置某个div或dlg标签的内容，可以使用资源ID或xml字符串(utf-8编码)
SetItemText FormatText	设置button、text的文字
SetItemAttribute SetItemIntAttribute SetItemDWordAttribute SetItemColorAttribute	设置控件的某个属性，属性名用utf-8编码(其实跟ansi一样) 值可以是utf-8字符串，也可以试int、DWORD、COLORREF
GetItemRect	获得某个控件的区域，可以用来控制PopupMenu的位置
GetItemCheck SetItemCheck	返回/设置check或radio是否被选中
IsItemVisible SetItemVisible	返回/设置控件是否可见
IsItemEnable EnableItem	返回/设置控件是否可用
SetTabCurSel	设置tabctrl当前显示的页面id，从0开始
RecomposeItems	重新排版，主要用于流模式
Redraw	重绘窗口，不重新排版
SetWindowCaption	设置窗口标题，在Load之后Create之前调用，可以动态改变窗口标题，以前用于合作版本的，可以忽略
DontShowWindow	在OnInitDialog时调用，可以不显示窗口、不抢焦点，为包含界面的流程提供后台模式非常实用
Create	创建非模态窗口
DoModal	模态创建窗口并调用
EndDialog	关闭窗口，和MFC和WTL不同的是，非模态窗口也可以调用

大部分方法都包含uItemID和bRedraw参数

uItemID是需要获取/设置信息的控件的id属性

bRedraw用于设置是否立即重绘窗口，一般设置成TRUE就可以了

有三个地方比较特殊

i. Create或DoModal之前，如果已经Load了xml模板，这时候窗口还没创建，必须设置为FALSE

ii. OnInitDialog时，窗口虽然已经创建，但是还没有进行第一次绘制，所以画了也没用，为了节省时间，都设置成FALSE吧

iii. 连续大量控件设置操作，最好最后一次操作再使用TRUE，或者都用FALSE，最后RecomposeItems或Redraw

注意：Redraw时DC需要引用HBITMAP，因为做了资源收集，所以如果多个线程同时Select同一个HBITMAP，会导致绘图失败，所以涉及到界面的调用比如窗口创建、设置控件属性，最好都在同一个线程，不要直接在回调中使用上表中的方法

泡泡窗口如果必需要使用独立线程，尽量使用独立图片。以后可以考虑在HBITMAP上加锁

另外CBkRichWinImpl响应了回车和ESC键，可以和普通对话框一样处理OnOK和OnCancel，默认什么都不做

2. CBkSimpleRichDlg

构造传入一个Xml模板资源ID，以此模板创建一个对话框，DoModal后点击任何button或imgbtn均导致窗口消失并返回点击的按钮ID属性值，对于简单提示窗口很有效

OnOK和OnCancel也会分别返回IDOK和IDCANCEL

3. CBkRichViewImpl

BkWin的真正实现所在，可以在普通对话框中创建实例，也可以直接使用CBkRichWinImpl来创建整个对话框

在普通对话框中使用时，在消息循环内加入一行

MSG_BK_NOTIFY(#BK_RICH_VIEW_ID#)

即可处理BkWin分发的消息

#BK_RICH_VIEW_ID#为CBkRichViewImpl::Create时传入的DlgCtrlID，用于当对话框中包含多个BkRichView时区分

主要方法和CBkRichWinImpl类似

四、新的资源定义方式(091225新增)

新提供了一种定义资源的方式，使用步骤如下：

1. 添加bkres\bkres.rc到工程

2. 在公用头文件引用bkres\bkres.h

3. 在工程目录下新建bkwinres.rc2，以下面格式定义资源即可，会比使用VS资源编辑器的方式简单

#pragma once

// XML

DEFINE_XML(IDR_BK_SKIN_DEF, 100, "res\\def_skin.xml")

DEFINE_XML(IDR_BK_STYLE_DEF, 101, "res\\def_style.xml")

DEFINE_XML(IDR_BK_STRING_DEF, 102, "res\\def_string.xml")

DEFINE_XML(IDR_BK_MAIN_DIALOG, 103, "res\\dlg_main.xml")

// ICON

DEFINE_ICO(IDI_BEIKESAFE, 100, "res\\beikesafe.ico")

DEFINE_ICO(IDI_SMALL, 101, "res\\small.ico")

// BITMAP

DEFINE_BMP(IDB_BTN_NORMAL_BG, 100, "res\\btn_normal_bg.bmp")

DEFINE_BMP(IDB_BTN_SYS_CLOSE, 101, "res\\btn_sys_close.bmp")

// CONTROL ID

#defineIDC_BTN_SYS_CLOSE 60001

#defineIDC_BTN_SYS_MAX 60002

#defineIDC_BTN_SYS_MIN 60003

#defineIDC_BTN_FAST_SCAN 100

#defineIDC_BTN_FULL_SCAN 101

#defineIDC_BTN_CUSTOM_SCAN 102

// STRING ID

#defineIDS_APP_NAME 1

#defineIDS_EXAM_SCORE 2

BkWin界面框架使用说明

相关阅读

相关文章

相关问答

相关文档