BkWin界面框架使用说明.doc

BkWin界面框架使用说明张晓晅2009/12/13一、 简单说明1. 使用XML定义界面窗口分为三部分：header、footer、body，至少应该包含一个部分，header的空白部分是可以拖动的，窗口resize时header和footer高度不变，body自适应BodyFooterHeader所有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实例 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位图资源IDmodenone：不透明mask：透明色alpha：alpha通道透明，需要32位RGBA位图maskcolor如果mode=mask，则指定透明色，默认FF00FF subwidth如果图片资源是ImageList，用这个参数指定ImageList中单个图片的宽度crbgFrame中间填充的背景颜色(十六进制RRGGBB格式)topFrame上界高度(px)leftFrame左界宽度(px)partall：整个frame（默认）top：不包含底部边框middle：只有垂直中部边框bottom：不包含头部边框left：不包含右边框center：只有水平中部边框right：不包含左边框v. imghorzex标签定义一个左右不变，中间一像素宽水平拉伸的frame样式skin属性：属性名：说明src位图资源IDmodenone：不透明mask：透明色alpha：alpha通道透明，需要32位RGBA位图（目前版本可能有bug，未实验）maskcolor如果mode=mask，则指定透明色，默认FF00FF subwidth如果图片资源是ImageList，用这个参数指定ImageList中单个图片的宽度leftFrame左界宽度(px)vi. imglist标签定义一个图片列表样式skin，一般用于img和imgbtn控件属性：属性名：说明src位图资源IDmodenone：不透明mask：透明色alpha：alpha通道透明，需要32位RGBA位图maskcolor如果mode=mask，则指定透明色，默认FF00FF subwidth如果图片资源是ImageList，用这个参数指定ImageList中单个图片的宽度2. style定义i. Xml实例Style用于定义控件的样式，包括使用的skin、文字对齐方式、字体、文字颜色、背景色、鼠标指针形状等流模式还可以指定边距、行间距、行内控件间距等等在应用程序开始时通过BkStyle:LoadStyles方法加载指定资源ID的Style定义xml，资源分类必须为“BKRES”ii. class标签定义一个样式属性：属性名：说明nameStyle的名字，用于控件的class属性skin指定使用的skin，如果指定了有效的skinname，crbg属性被忽略textmode文字对齐方式，即DrawText的最后一个参数，格式为十六进制不加“0x”crbg背景色，默认不填充背景crtext默认情况下文字颜色，默认为000000即黑色crhover鼠标移上去时的文字颜色，默认同crtextcrdisabled控件不可用时的文字颜色，默认CCCCCCfont字体，4位16进制数，默认宋体12点字(0000)，前两位为字号，正值增大，负值缩小，大字体设置下字号不会改变后两位01斜体、02下划线、04粗体，可叠加hoverfont鼠标移上去时的字体，格式同fontx-margin水平边距(流模式)y-margin垂直边距(流模式)margin边距(流模式)，设置这个值会同时修改x-margin和y-marginspacing行内控件间距(流模式)linespacing行距(流模式)cursor鼠标移上去时的鼠标指针样式arrow：普通指针（默认）hand：手型3. string定义i. Xml实例应用程序标题列1列2列3定义应用程序中用到的字符串在应用程序开始时通过BkString:Load方法加载指定资源ID的Style定义xml，资源分类必须为“BKRES”后加载的字符串表会覆盖先加载的表中相同ID的字符串，此特性可用于OEM订制4. 窗口框架i. 框架实例默认采用流式排版还是对话框式排版，是在调用时由使用哪种窗口类决定的，具体请见Classes节ii. layer标签定义一个窗口属性：属性名：说明title窗口标题文字，如果设置appwin=1，则显示在任务栏height窗口高度(px)width窗口宽度(px)appwin1对应WS_EX_APPWINDOWresize1对应WS_MAXIMIZEBOX | WS_MINIMIZEBOXnoborder1对应WS_POPUP | WS_SYSMENU以及WS_EX_TOOLWINDOW | WS_EX_TOPMOST0对应WS_OVERLAPPED | WS_SYSMENUiii. header/footer/body标签定义窗口的一部分属性：属性名：说明height高度(px)，body必须为full，header和footer可定义width宽度(px)，必须为full5. 控件i. 公用属性说明属性名：说明：class指定一个Style Nameid指定控件的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#%例：定义字符串表AppName定义窗口%str1% - 设置则指定位置会显示“AppName 设置”iii. text标签定义一个文字控件以指定字体、前景色和背景色在窗口绘制一段文本可以用于制作超链接iv. link标签就是text，在header中，text标签会被认为是空白位置可以拖动，使用link标签可以用来制作header上的超链接v. button标签按钮，其实跟text一样，只是一般会指定一个带skin的stylevi. img标签在窗口上显示图片属性：属性名：说明skin指定imglstsub指定当前显示的是imglst中的第几个图片，-1则表示全部vii. imgbtn标签图片按钮，使用4张图片的ImageList，如果确定不会被Disable，图片资源中可以只包含前三种状态，用来节省生成的程序大小属性只有skin，此控件会根据Hover/Pushdown/Disable状态切换Sub Imageviii. progress标签进度条控件，用于显示一个进度条属性：属性名：说明bgskin指定进度条背景skinposskin指定进度条进度skinmin最小值max最大值value现在的值showpercent是否在正中间用文字显示xx%，用crtext和crbg防止显示不清楚ix. realwnd标签用于控制一个真实窗口的显示、隐藏只有一个参数ctrlid，用于绑定对应DlgItemID的控件要绑定的真实窗口要指定BkWin窗口的View窗口为父窗口，比如在OnInitDialog时创建要绑定的窗口，父窗口参数必须为GetViewHWND()，而不能直接用m_hWndx. check标签复选钮目前不能选择皮肤，自动套用XP以上的Themexi. radio标签单选钮目前不能选择皮肤，自动套用XP以上的Theme属性：属性名：说明group分组名，同一组的单选钮最多同时只能被选中一个，全局唯一标识，不能重复xii. icon标签用于显示一个图标属性：属性名：说明src指定图标资源idoem是否oem图标1：是，用于加载IDI_INFORMATION等系统图标2：否，加载当前资源模块的图标size图标大小，16/32/48/64等等注意：由于Windows API一向的bug，如果某ICON资源同时包含16*16和32*32，则size指定16时，绘制的会是32*32缩小后的图标，所以16*16的图标需要单独放置一份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开始tabwidthtab标签的宽度tabskintab标签的Skin Nameframeskintabpage客户区的Skin Nametableft第一个tab标签和左边的间距tabspacingtab和tab之间的间距，负值则重叠frametoptabpage客户区的位置，负值则和标签区域有重叠xvii. tab标签暂时是div标签，所以tab内需要使用对话框式排版时要嵌套width和height必须是full属性：属性名：说明titletab标签标题onlydrawchild子控件只用于绘图，不响应鼠标消息三、 Classes1. CBkRichWinImpl实现一个使用BkWin排版的窗口。最简单的实例如下：class CTestDlg : public CBkRichWinImplpublic: CTestDlg() : CBkRichWinImpl(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) 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_SELCHANGEtabctrl切换页面时触发消息根据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编码)SetItemTextFormatText设置button、text的文字SetItemAttributeSetItemIntAttributeSetItemDWordAttributeSetItemColorAttribute设置控件的某个属性，属性名用utf-8编码(其实跟ansi一样)值可以是utf-8字符串，也可以试int、DWORD、COLORREFGetItemRect获得某个控件的区域，可以用来控制PopupMenu的位置GetItemCheckSetItemCheck返回/设置check或radio是否被选中IsItemVisibleSetItemVisible返回/设置控件是否可见IsItemEnableEnableItem返回/设置控件是否可用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模板，这时候窗口还没创建，必须设置为FALSEii. 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和IDCANCEL3. CBkRichViewImplBkWin的真正实现所在，可以在普通对话框中创建实例，也可以直接使用CBkRichWinImpl来创建整个对话框在普通对话框中使用时，在消息循环内加入一行MSG_BK_NOTIFY(#BK_RICH_VIEW_ID#)即可处理BkWin分发的消息#BK_RICH_VIEW_ID#为CBkRichViewImpl:Create时传入的DlgCtrlID，用于当对话框中包含多个BkRichView时区分主要方法和CBkRich