1. setAttribute() 定義

在 Qt 中，setAttribute() 是 QWidget類的一個成員函數，用來設置控件或窗口的內部屬性（attribute）。
這些屬性控制着控件的行為、外觀或與操作系統的交互方式。

函數原型：

void QWidget::setAttribute(Qt::WidgetAttribute attribute, bool on = true);
  • attribute：要設置的屬性，類型是枚舉 Qt::WidgetAttribute。
  • on：是否啓用該屬性，默認 true 表示啓用，false 表示禁用。

2. 與 setWindowFlags() 的區別

很多初學者會混淆 setAttribute() 和 setWindowFlags()，這裏做個對比：

項目

setAttribute()

setWindowFlags()

作用範圍

窗口/控件的行為特性（如透明、銷燬策略、事件處理）

窗口的類型和外觀標誌（如無邊框、模態、是否有標題欄）

參數類型

Qt::WidgetAttribute 枚舉

Qt::WindowFlags 枚舉

使用場景

控制 Qt 內部渲染方式、事件處理邏輯

控制窗口在操作系統中的分類和外觀

是否影響平台窗口

部分屬性會影響（如 WA_NativeWindow）

直接影響（因為窗口標誌是操作系統窗口的一部分）

簡單來説：

  • setWindowFlags()
  • setAttribute()

3. 常用 Qt::WidgetAttribute 屬性

3.1 窗口生命週期相關

屬性

作用

示例

Qt::WA_DeleteOnClose

窗口調用 close() 時自動 delete this

w.setAttribute(Qt::WA_DeleteOnClose);

Qt::WA_QuitOnClose

關閉此窗口時退出應用（QApplication::quit()）

w.setAttribute(Qt::WA_QuitOnClose);

注意：

  • WA_DeleteOnClose 不要用於有父對象的窗口，否則父對象銷燬時會二次釋放導致崩潰。
  • WA_QuitOnClose 一般只用於主窗口。

3.2 背景與透明相關

屬性

作用

示例

Qt::WA_TranslucentBackground

背景透明（支持 RGBA 透明度）

w.setAttribute(Qt::WA_TranslucentBackground);

Qt::WA_NoSystemBackground

禁用系統背景繪製（控件背景透明，但不是真正的 RGBA 透明）

w.setAttribute(Qt::WA_NoSystemBackground);

Qt::WA_OpaquePaintEvent

告訴 Qt 此控件的 paintEvent 會繪製整個區域，無需擦除背景，提升性能

w.setAttribute(Qt::WA_OpaquePaintEvent);

注意：

  • WA_TranslucentBackground 通常要配合 setWindowFlags(Qt::FramelessWindowHint) 才能實現全窗口透明。
  • 在 Windows 上需要啓用 Aero 效果（Win7+），Linux 依賴窗口管理器支持。

3.3 事件處理相關

屬性

作用

示例

Qt::WA_TransparentForMouseEvents

忽略鼠標事件，事件會傳遞給下面的控件

w.setAttribute(Qt::WA_TransparentForMouseEvents);

Qt::WA_AlwaysShowToolTips

禁用狀態下也顯示 ToolTip

w.setAttribute(Qt::WA_AlwaysShowToolTips);

Qt::WA_ShowWithoutActivating

顯示窗口時不激活它（不搶焦點）

w.setAttribute(Qt::WA_ShowWithoutActivating);

3.4 平台相關屬性

屬性

作用

平台

Qt::WA_NativeWindow

強制創建原生窗口句柄（HWND / X11 Window）

所有平台

Qt::WA_MacAlwaysShowToolWindow

macOS：工具窗口始終顯示在 Dock 欄

macOS

Qt::WA_LinuxOwnershipWarning

Linux：顯示 X11 窗口所有權警告

Linux

4. 使用示例

#include <QApplication>
  #include <QWidget>
    #include <QPushButton>
      int main(int argc, char *argv[])
      {
      QApplication a(argc, argv);
      QWidget w;
      w.setWindowTitle("setAttribute 示例");
      w.resize(400, 300);
      // 無邊框
      w.setWindowFlags(Qt::FramelessWindowHint);
      // 背景透明
      w.setAttribute(Qt::WA_TranslucentBackground);
      // 關閉時銷燬窗口
      w.setAttribute(Qt::WA_DeleteOnClose);
      // 背景色半透明
      w.setStyleSheet("background-color: rgba(0, 100, 200, 150);");
      QPushButton *btn = new QPushButton("關閉", &w);
      btn->move(150, 120);
      QObject::connect(btn, &QPushButton::clicked, &w, &QWidget::close);
      w.show();
      return a.exec();
      }

運行效果：

  • 窗口無邊框
  • 背景半透明
  • 點擊按鈕關閉窗口並銷燬對象

5. 注意事項

  1. 設置時機
  • 有些屬性必須在 show() 之前設置才能生效，例如 WA_TranslucentBackground、WA_NativeWindow。
  • 如果在 show() 之後修改，可能需要調用 show() 或 update() 重新生效。
  1. 平台差異
  • 透明、置頂等效果在不同平台上表現可能不同，尤其是 Linux 桌面環境差異較大。
  1. 父子關係影響
  • 子窗口的某些屬性會繼承父窗口設置。
  • 有父對象的窗口，關閉時默認不會退出應用，除非設置了 WA_QuitOnClose。
  1. 性能影響
  • WA_TranslucentBackground 會增加 GPU 渲染開銷，可能導致窗口移動卡頓。

Qt 常用 setAttribute() 速查表

屬性名稱（Qt::WidgetAttribute）

核心作用

典型使用場景

注意事項

Qt::WA_TranslucentBackground

開啓窗口/控件的背景透明（支持 RGBA 透明度）

1. 製作異形窗口（如圓形、不規則圖標窗口）

2. 半透明彈窗/懸浮層

3. 自定義標題欄的窗口

1. 需配合無邊框：通常需先設置 setWindowFlags(Qt::FramelessWindowHint)，否則系統標題欄可能不透明

2. 平台依賴：

- Windows：需開啓 Aero 效果，Win7 及以上支持

- Linux：依賴窗口管理器（如 KWin 支持，Openbox 可能需額外配置）

3. 需在 show() 前設置才生效

Qt::WA_DeleteOnClose

窗口調用 close() 時，自動銷燬對象（等價於 delete this）

1. 臨時子窗口（如“關於”窗口、編輯彈窗）

2. 避免手動管理窗口內存，防止內存泄漏

1. 不要用於“有父對象的窗口”：若窗口已指定父控件（如 QMainWindow 的子窗口），父對象銷燬時會自動回收，重複 delete 會崩潰

2. 關閉後不可再訪問：窗口關閉後對象已釋放，後續操作會觸發野指針錯誤

Qt::WA_NoSystemBackground

禁用系統默認的背景繪製（控件背景變為“透明”，但非 RGBA 透明）

1. 自定義控件重繪（如 paintEvent 中手動繪製背景）

2. 避免系統背景與自定義繪製衝突導致閃爍

1. 需手動處理背景：若不主動繪製背景，控件會“透傳”父控件的背景

2. 區別於 WA_TranslucentBackground：此屬性僅關閉系統繪製，不支持 RGBA 透明度；後者是真正的背景透明

Qt::WA_QuitOnClose

關閉此窗口時，觸發應用退出（等價於 QApplication::quit()）

1. 主窗口（如 QMainWindow）：確保關閉主窗口時退出整個應用

2. 單窗口應用的唯一窗口

1. 僅生效於“頂層窗口”（無父對象的窗口）

2. 多窗口場景慎用：若設置給子窗口，關閉子窗口會直接退出應用，需避免

Qt::WA_ShowWithoutActivating

顯示窗口時，不搶奪焦點（窗口處於“非激活”狀態）

1. 懸浮提示窗口（如歌詞彈窗、桌面小工具）

2. 後台通知窗口：不打斷用户當前操作（如瀏覽器下載完成提示）

1. 需配合 setWindowFlags(Qt::WindowDoesNotAcceptFocus) 增強效果

2. 平台差異：macOS 下可能仍會短暫激活窗口，需額外處理（如 setWindowLevel(Qt::ToolTip)）

Qt::WA_TransparentForMouseEvents

窗口/控件忽略所有鼠標事件（事件會透傳給下層控件）

1. 純展示用的懸浮層（如視頻水印、固定提示文本）

2. 父控件上的“裝飾性控件”，不影響用户操作下層內容

1. 事件完全透傳：包括點擊、hover、拖拽等，控件自身無法響應鼠標事件

2. 子控件繼承：若父控件設置此屬性，所有子控件也會繼承該行為（除非子控件單獨取消）

Qt::WA_AlwaysShowToolTips

即使控件處於禁用狀態（setEnabled(false)），仍顯示 ToolTip

1. 禁用的按鈕/輸入框：需提示用户“為何禁用”（如“當前權限不足，無法編輯”）

2. 只讀控件的狀態説明

1. 需先設置 setToolTip() 內容，否則無效果

2. 不影響啓用狀態的控件：啓用的控件原本就會顯示 ToolTip，此屬性僅針對禁用場景

Qt::WA_MacAlwaysShowToolWindow

macOS 專屬：讓工具窗口（Qt::Tool 類型）始終顯示在 Dock 欄中

macOS 下的工具類窗口（如獨立的調色板、日誌窗口）：確保用户能通過 Dock 快速切換

1. 僅支持 macOS 平台，其他系統設置無效

2. 需配合 setWindowFlags(Qt::Tool) 使用，否則屬性不生效