Skip to content

图像控件 (SImageWnd)

Warning

The current page still doesn't have a translation for this language.

You can read it through google translate.

图像控件用于显示图片资源，支持多种图片格式，提供多种缩放和适应模式。它是展示图像内容的基础控件。

基本信息

  • 类名：SImageWnd
  • 控件标签：img
  • 基类：SWindow
  • 功能：提供图像显示功能

属性说明

自身属性

属性名 类型 默认值 说明
skin skin - 图片皮肤名称。注意 SImageWnd 用 ATTR_SKIN 覆盖了 SWindow 的 skin，指向独立的 m_pSkin，而不是背景皮肤
iconIndex int 0 皮肤中的子图（帧）索引，对应 SetIcon()/GetIcon()
keepAspect bool false 是否保持图片原始宽高比。为 true 时按等比缩放居中绘制，不会拉伸变形
fitImage bool false 是否让控件尺寸适应图片大小。MeasureContent() 返回皮肤尺寸，配合布局的 wrapContent 使用

SImageWnd 没有动画属性

SImageWnd 是静态图片控件，不支持 src、tile、stretch、fillType、rotate， 也没有 animate/frameInterval/autoStart/loop 等动画属性。 - 需要加载外部图片文件请用控件标签 icon（SIconWnd，属性 src）； - 需要播放多帧动画请用控件标签 animateimg（SAnimateImgWnd，属性 skin/speed/autoStart/repeat）。 alpha 属于 SWindow 的通用属性，见通用属性。

继承自 SWindow / SwndStyle / 布局参数的通用属性，见通用属性。

使用示例

基本图像显示

<img name="imgBasic" 
     pos="10,10,210,210" 
     skin="skin_image"/>

从皮肤中选取指定子图

<img name="imgIcon" 
     pos="220,10,320,110" 
     skin="skin_icons"
     iconIndex="0"/>

保持宽高比的图像

<img name="imgAspect" 
     pos="10,220,210,320" 
     skin="skin_image"
     keepAspect="1"/>

尺寸自适应图片

<img name="imgFit" 
     pos="220,220,420,320" 
     skin="skin_image"
     fitImage="1"
     keepAspect="1"/>

带透明度的图像

<img name="imgAlpha" 
     pos="10,330,210,430" 
     skin="skin_image"
     alpha="128"/>

图像操作

代码操作示例

void ImageOperations()
{
    SImageWnd *pImg = 
        FindChildByName2<SImageWnd>(L"imgDemo");
    if(pImg) {
        // 设置图片
        pImg->SetSkin(GETSKIN(L"new_skin", 
                             SKIN_IMG_FRAME));

        // 从文件加载
        pImg->SetImage(L"image.png");

        // 设置填充方式
        pImg->SetFillType(ImageFillType::Fit);

        // 设置旋转角度
        pImg->SetRotate(90);

        // 设置透明度
        pImg->SetAlpha(200);

        // 开始动画
        pImg->StartAnim();

        // 停止动画
        pImg->StopAnim();
    }
}

代码操作

// 查找图像控件
SImageWnd *pImage = FindChildByName2<SImageWnd>(L"imgBasic");

// 设置皮肤
pImage->SetAttribute(L"skin", L"skin_new_image");

// 设置子图索引
pImage->SetAttribute(L"iconIndex", L"1");

// 设置透明度
pImage->SetAttribute(L"alpha", L"200");

// 设置是否保持宽高比
pImage->SetAttribute(L"keepAspect", L"1");

// 设置控件尺寸自适应图片
pImage->SetAttribute(L"fitImage", L"1");

事件处理

图像控件支持以下事件：

事件名 EventID 说明
EVT_MOUSE_HOVER EventMouse::EventID 鼠标悬停事件
EVT_MOUSE_LEAVE EventMouse::EventID 鼠标离开事件
EVT_MOUSE_CLICK EventMouse::EventID 鼠标点击事件
EVT_SETFOCUS EventSetFocus::EventID 获得焦点事件
EVT_KILLFOCUS EventKillFocus::EventID 失去焦点事件 
// 事件处理示例
EVENT_MAP_BEGIN()
    EVENT_NAME_HANDLER(L"imgBasic", EventMouse::EventID, OnImageClick)
EVENT_MAP_END()

void OnImageClick(IEvtArgs *pEvt)
{
    EventMouse *pRealEvt = sobj_cast<EventMouse>(pEvt);
    if(pRealEvt->GetID() == EVT_MOUSE_CLICK)
    {
        // 处理图像点击
    }
}

样式定制

基本样式

<style>
    <class name="imgStyle"
           keepAspect="1"
           fitImage="1"
           alpha="255"/>
</style>

<img class="imgStyle"/>

动画样式

SImageWnd 不支持动画。需要播放多帧动画请使用 animateimg 控件：

<animateimg name="imgAnim"
            pos="10,10,210,210"
            skin="skin_anim"
            speed="50"
            autoStart="1"
            repeat="-1"/>

最佳实践

  1. 图像适应：根据显示需求选择 keepAspect 和 fitImage 属性
  2. 性能优化：尺寸固定时避免开启 fitImage，减少一次测量过程
  3. 视觉效果：通过 alpha 属性实现图像半透明效果（见通用属性）
  4. 图标使用：使用 iconIndex 属性从皮肤的子图中选择特定图标
  5. 皮肤管理：合理组织皮肤资源，便于维护和替换

常见问题

Q: 图像显示变形怎么办？

A: 设置 keepAspect 为 1 以保持图像原始宽高比。

Q: 图像显示不完整怎么办？

A: 检查控件尺寸是否足够；若希望控件跟随图片尺寸，可设置 fitImage 为 1。

Q: 图像透明度不生效怎么办？

A: 确保 alpha 属性值在 0-255 范围内，0 为完全透明，255 为完全不透明（见通用属性）。

相关控件