Win32 API 日本語リファレンス
ホーム › UI.Shell › IDesktopWallpaper

IDesktopWallpaper

COM
📘 Microsoft Learn (日本語) · English
IIDb92b56a9-8b55-4e14-9a89-0199bbb6f93b継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

デスクトップの壁紙を管理するためのメソッドを提供します。(IDesktopWallpaper)

メソッド 16

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT SetWallpaper(LPWSTR monitorID, LPWSTR wallpaper)

デスクトップの壁紙を設定します。

monitorIDLPWSTRinモニターの ID。この値は GetMonitorDevicePathAt を通じて取得できます。この値を NULL に設定すると、すべてのモニターに壁紙画像を設定します。
wallpaperLPWSTRin壁紙画像ファイルのフルパス。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 4 HRESULT GetWallpaper(LPWSTR monitorID, LPWSTR* wallpaper)

現在のデスクトップの壁紙を取得します。

monitorIDLPWSTRin

モニターの ID。この値は GetMonitorDevicePathAt を通じて取得できます。

この値は NULL に設定できます。その場合、システムのすべてのモニターに単一の壁紙画像が表示されているときは、メソッドは正常に返ります。この値を NULL に設定した状態で、モニターごとに異なる壁紙を表示している場合やスライドショーが実行中の場合、メソッドは S_FALSE を返し、wallpaper パラメーターには空の文字列を返します。

wallpaperLPWSTR*out

バッファーへのポインターのアドレス。このメソッドが正常に返ると、壁紙画像ファイルへのパスを受け取ります。この画像は、monitorID パラメーターで指定したモニターだけでなく、システムのすべてのモニターに現在表示されている可能性があることに注意してください。

壁紙画像が表示されていない場合、またはモニターが単色を表示している場合、この文字列は空になります。メソッドが失敗した場合も文字列は空になります。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 5 HRESULT GetMonitorDevicePathAt(DWORD monitorIndex, LPWSTR* monitorID)

システムのモニターの 1 つの一意な ID を取得します。

monitorIndexDWORDinモニターの番号。モニターの総数を確認するには GetMonitorDevicePathCount を呼び出します。
monitorIDLPWSTR*outバッファーのアドレスへのポインター。このメソッドが正常に返ると、モニターの ID を受け取ります。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は、次を含む HRESULT エラーコードを返します。

戻り値 説明
E_POINTER
 monitorID に NULL ポインターが指定されました。

解説(Remarks)

このメソッドは、現在切り離されているが画像が割り当てられているモニターに対しても呼び出すことができます。接続されているモニターと切り離されているモニターを区別するには、GetMonitorRECT を呼び出します。

vtbl 6 HRESULT GetMonitorDevicePathCount(DWORD* count)

システムに関連付けられているモニターの数を取得します。

countDWORD*out値へのポインター。このメソッドが正常に返ると、モニターの数を受け取ります。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は、次を含む HRESULT エラーコードを返します。

戻り値 説明
E_POINTER
 monitorID に NULL ポインターが指定されました。

解説(Remarks)

このメソッドで取得される数には、現在切り離されているが画像が割り当てられているモニターも含まれます。接続されているモニターと切り離されているモニターを区別するには、GetMonitorRECT を呼び出します。

vtbl 7 HRESULT GetMonitorRECT(LPWSTR monitorID, RECT* displayRect)

指定したモニターの表示矩形を取得します。

monitorIDLPWSTRin照会するモニターの ID。この値は GetMonitorDevicePathAt を通じて取得できます。
displayRectRECT*outRECT 構造体へのポインター。このメソッドが正常に返ると、monitorID で指定したモニターの表示矩形を、スクリーン座標で受け取ります。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は、次を含む HRESULT エラーコードを返します。

戻り値 説明
S_FALSE
 monitorID で指定したモニターは現在システムに接続されていません。
E_POINTER
 displayRect に NULL ポインターが指定されました。
E_INVALIDARG
 monitorID に指定された ID が見つかりません。
vtbl 8 HRESULT SetBackgroundColor(COLORREF color)

画像が表示されていないとき、またはデスクトップ背景が無効化されているときにデスクトップに表示される色を設定します。この色は、デスクトップの壁紙が画面全体を埋めない場合の縁取りとしても使用されます。

colorCOLORREFin背景の RGB カラー値を指定する COLORREF 値。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 9 HRESULT GetBackgroundColor(COLORREF* color)

画像が表示されていないとき、またはデスクトップ背景が無効化されているときにデスクトップに表示される色を取得します。この色は、デスクトップの壁紙が画面全体を埋めない場合の縁取りとしても使用されます。

colorCOLORREF*outCOLORREF 値へのポインター。このメソッドが正常に返ると、RGB カラー値を受け取ります。このメソッドが失敗した場合、この値は 0 に設定されます。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 10 HRESULT SetPosition(DESKTOP_WALLPAPER_POSITION position)

デスクトップの壁紙画像の表示オプションを設定し、画像を中央揃え、並べて表示、または引き伸ばしのいずれで表示するかを指定します。

positionDESKTOP_WALLPAPER_POSITIONin画像をシステムのモニターにどのように表示するかを指定する DESKTOP_WALLPAPER_POSITION 列挙値のいずれか。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は、次を含む HRESULT エラーコードを返します。

戻り値 説明
S_FALSE
 デスクトップの壁紙はすでに position で要求されたとおりに表示されています。
vtbl 11 HRESULT GetPosition(DESKTOP_WALLPAPER_POSITION* position)

デスクトップの背景画像の現在の表示値を取得します。

positionDESKTOP_WALLPAPER_POSITION*out値へのポインター。このメソッドが正常に返ると、画像がシステムのモニターにどのように表示されているかを指定する DESKTOP_WALLPAPER_POSITION 列挙値のいずれかを受け取ります。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は、次を含む HRESULT エラーコードを返します。

戻り値 説明
E_POINTER
 position に NULL ポインターが指定されました。
vtbl 12 HRESULT SetSlideshow(IShellItemArray* items)

デスクトップの壁紙スライドショーに使用する画像を指定します。

itemsIShellItemArray*inスライドショー画像を含む IShellItemArray へのポインター。この配列には、同じコンテナーに格納された個々の項目(フォルダーに格納されたファイル)を含めることも、コンテナー自体である単一の項目(画像を含むフォルダー)を含めることもできます。これ以外の構成の配列を指定すると、このメソッドは失敗します。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 13 HRESULT GetSlideshow(IShellItemArray** items)

スライドショー画像が格納されているディレクトリへのパスを取得します。

itemsIShellItemArray**outIShellItemArray オブジェクトへのポインターのアドレス。このメソッドが正常に返ると、スライドショーを構成する項目を受け取ります。この配列には、同じコンテナーに格納された個々の項目を含めることも、コンテナー自体である単一の項目を含めることもできます。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は、次を含む HRESULT エラーコードを返します。

戻り値 説明
E_POINTER
 position に NULL ポインターが指定されました。
vtbl 14 HRESULT SetSlideshowOptions(DESKTOP_SLIDESHOW_OPTIONS options, DWORD slideshowTick)

シャッフルとタイミングに関するデスクトップ壁紙スライドショーの設定を行います。

optionsDESKTOP_SLIDESHOW_OPTIONSin

シャッフルを無効にする場合は 0 を、それ以外の場合は次の値を設定します。

DSO_SHUFFLEIMAGES (0x01)

シャッフルを有効にします。スライドショーをランダムな順序で進めます。

slideshowTickDWORDin画像を切り替える間隔(ミリ秒単位)。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 15 HRESULT GetSlideshowOptions(DESKTOP_SLIDESHOW_OPTIONS* options, DWORD* slideshowTick)

シャッフルとタイミングに関する現在のデスクトップ壁紙スライドショーの設定を取得します。

optionsDESKTOP_SLIDESHOW_OPTIONS*out

値へのポインター。このメソッドが正常に返ると、シャッフルが無効であることを示す 0、または次の値のいずれかを受け取ります。

DSO_SHUFFLEIMAGES (0x01)

シャッフルが有効です。画像はランダムな順序で表示されます。

slideshowTickDWORD*out値へのポインター。このメソッドが正常に返ると、画像を切り替える間隔(ミリ秒単位)を受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は、次を含む HRESULT エラーコードを返します。

戻り値 説明
E_POINTER
 いずれかのパラメーターに NULL ポインターが指定されました。
vtbl 16 HRESULT AdvanceSlideshow(LPWSTR monitorID, DESKTOP_SLIDESHOW_DIRECTION direction)

指定したモニターの壁紙をスライドショー内の次の画像に切り替えます。

monitorIDLPWSTRin壁紙画像を変更するモニターの ID。この ID は GetMonitorDevicePathAt メソッドを通じて取得できます。このパラメーターを NULL に設定すると、次に変更が予定されているモニターが使用されます。
directionDESKTOP_SLIDESHOW_DIRECTIONin

スライドショーを進める方向。次の DESKTOP_SLIDESHOW_DIRECTION 値のいずれか:

DSD_FORWARD (0)

スライドショーを前方に進めます。

DSD_BACKWARD (1)

スライドショーを後方に進めます。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 17 HRESULT GetStatus(DESKTOP_SLIDESHOW_STATE* state)

スライドショーの現在の状態を取得します。

stateDESKTOP_SLIDESHOW_STATE*out

DESKTOP_SLIDESHOW_STATE 値へのポインター。このメソッドが正常に返ると、次のフラグのうち 1 つ以上を受け取ります。

DSS_ENABLED (0x01)

スライドショーが有効です。

DSS_SLIDESHOW (0x02)

スライドショーが現在構成されています。

DSS_DISABLED_BY_REMOTE_SESSION (0x04)

リモートセッションによってスライドショーが一時的に無効化されています。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 18 HRESULT Enable(BOOL enable)

デスクトップの背景を有効または無効にします。

enableBOOLinデスクトップの背景を有効にする場合は TRUE、無効にする場合は FALSE。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は、次を含む HRESULT エラーコードを返します。

戻り値 説明
S_FALSE
 デスクトップの壁紙はすでにこの呼び出しで要求している状態になっています。
E_FILE_NOT_FOUND
 背景を有効にしたときに使用されるデスクトップの壁紙が、想定される場所に見つかりません。新しい壁紙を指定するには SetWallpaper を呼び出します。

解説(Remarks)

このメソッドは通常、パフォーマンス上の理由からデスクトップの背景を無効にするために呼び出されます。

デスクトップの背景が無効化されている場合、その代わりに単色が表示されます。特定の色を取得または設定するには、GetBackgroundColor および SetBackgroundColor メソッドを使用します。

注意 IDesktopWallpaper_SetWallpaper または IDesktopWallpaper_SetSlideshow メソッドを呼び出すと、このメソッドによって現在無効化されている場合でもデスクトップの背景が有効になります。
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IDesktopWallpaper "{B92B56A9-8B55-4E14-9A89-0199BBB6F93B}"
#usecom global IDesktopWallpaper IID_IDesktopWallpaper "{C2CF3110-460E-4FC1-B9D0-8A1C0C9CC4BD}"
#comfunc global IDesktopWallpaper_SetWallpaper               3 wstr,wstr
#comfunc global IDesktopWallpaper_GetWallpaper               4 wstr,var
#comfunc global IDesktopWallpaper_GetMonitorDevicePathAt     5 int,var
#comfunc global IDesktopWallpaper_GetMonitorDevicePathCount  6 var
#comfunc global IDesktopWallpaper_GetMonitorRECT             7 wstr,var
#comfunc global IDesktopWallpaper_SetBackgroundColor         8 int
#comfunc global IDesktopWallpaper_GetBackgroundColor         9 var
#comfunc global IDesktopWallpaper_SetPosition                10 int
#comfunc global IDesktopWallpaper_GetPosition                11 var
#comfunc global IDesktopWallpaper_SetSlideshow               12 sptr
#comfunc global IDesktopWallpaper_GetSlideshow               13 sptr
#comfunc global IDesktopWallpaper_SetSlideshowOptions        14 int,int
#comfunc global IDesktopWallpaper_GetSlideshowOptions        15 var,var
#comfunc global IDesktopWallpaper_AdvanceSlideshow           16 wstr,int
#comfunc global IDesktopWallpaper_GetStatus                  17 var
#comfunc global IDesktopWallpaper_Enable                     18 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。