LoadIconMetric 函式 (commctrl.h)

  • 發行項

使用用戶端指定的系統計量載入指定的圖示資源。

語法

HRESULT LoadIconMetric(
  [in]  HINSTANCE hinst,
  [in]  PCWSTR    pszName,
  [in]  int       lims,
  [out] HICON     *phico
);

參數

[in] hinst

類型： HINSTANCE

DLL 或可執行檔 (.exe) 檔案的控制碼，其中包含要載入的圖示。 如需詳細資訊，請參閱 GetModuleHandle。

若要載入預先定義的圖示或獨立圖示檔案，請將此參數設定為 Null。

[in] pszName

類型： PCWSTR

Null 終止的 Unicode 緩衝區指標，其中包含要載入之圖示的位置資訊。 它會解譯如下：

如果 hinst 是 Null， pszName 可以指定兩件事之一。

  1. 獨立圖示的名稱 (.ico) 檔案。
  2. 要載入之預先定義圖示的識別碼。 這些識別碼可辨識：
    • IDI_APPLICATION
    • IDI_INFORMATION
    • IDI_ERROR
    • IDI_WARNING
    • IDI_SHIELD
    • IDI_QUESTION

      若要將這些常數傳遞至 LoadIconMetric 函式，請使用 MAKEINTRESOURCE 宏。 例如，若要載入IDI_ERROR圖示，請傳遞 MAKEINTRESOURCE(IDI_ERROR) 作為 pszName 參數，並將 Null 當做 hinst 參數傳遞。

如果 hinst 為非 Null， pszName 可以指定兩個專案之一。

  1. 如果要依名稱從模組載入圖示資源，圖示資源的名稱。
  2. 圖示序數，如果圖示資源是透過序數從模組載入。 這個序數必須使用 MAKEINTRESOURCE 宏進行封裝。

[in] lims

類型： int

所需的計量。 下列其中一個值：

值 意義
LIM_SMALL
 對應至 SM_CXSMICON，這是小型圖示的建議圖元寬度。
LIM_LARGE
 對應至SM_CXICON，這是圖示的預設圖元寬度。

[out] phico

類型： HICON*

當此函式傳回時，會包含已載入圖示控制碼的指標。

傳回值

類型： HRESULT

如果成功，則傳回S_OK，否則傳回錯誤，包括下列值。

傳回碼 描述
E_INVALIDARG
 pszName指向的緩衝區內容不符合任何預期的解譯。

備註

LoadIconMetric 類似于 LoadIcon，但具有指定圖示計量的功能。 當呼叫的應用程式想要確保高品質的圖示時，它會用來取代 LoadIcon 。 這特別適用于 (DPI) 情況的高點每英吋點數。

圖示會擷取或建立，如下所示。

  1. 如果在資源中找到完全相符的大小，則會使用該圖示。
  2. 如果找不到完全相符的大小，而且有較大的圖示可用，則會藉由將較大的版本相應縮小為所需的大小來建立新的圖示。
  3. 如果找不到完全相符的大小，而且沒有較大的圖示可用，則會藉由將較小的圖示調整為所需的大小來建立新的圖示。
此處會顯示 LoadIconMetric 和 LoadIcon的比較呼叫。 
NOTIFYICONDATA  nidIconData  = {0};
nidIconData.hIcon = LoadIcon(hInstance, MAKEINTRESOURCE(IDI_ICON));

// Or...

HRESULT hr = LoadIconMetric(hInstance, MAKEINTRESOURCE(IDI_ICON), LIM_SMALL, &nidIconData.hIcon);

應用程式負責在擷取的圖示上呼叫 DestroyIcon 。

規格需求

   
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平臺 Windows
標頭 commctrl.h
程式庫 Comctl32.lib
DLL Comctl32.dll