PyWinRT

https://pywinrt.readthedocs.io/en/latest/
Admin
The PyWinRT project provides access to Windows Runtime (WinRT) APIs in Python.
Tokens:10,050
Snippets:144
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize Windows App Runtime

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/winui3/index.rst.txt

Use the bootstrap module to initialize the Windows App runtime at the start of the application. The context manager ensures proper cleanup.

```python
from winui3.microsoft.windows.applicationmodel.dynamicdependency import bootstrap

# initialize Windows App runtime and prompt user if it is not installed
with bootstrap.initialize(options=bootstrap.InitializeOptions.ON_NO_MATCH_SHOW_UI):
    # your main entry point code here
    ...
```

--------------------------------

### get_window_id_from_window(int hwnd)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/winui3/microsoft/ui/interop.rst.txt

Gets the WindowId that corresponds to the specified hwnd, if the provided HWND is valid.

```APIDOC
## get_window_id_from_window(int hwnd)

### Description
Gets the WindowId that corresponds to the specified hwnd, if the provided HWND is valid.

### Parameters
- **hwnd** (int) - The handle of the window for which to get the WindowId.

### Returns
- **WindowId** (winui3.microsoft.ui.WindowId) - The identifier that corresponds to the specified hwnd.

### Raises
- **OSError** - if the OS call failed.
```

--------------------------------

### get_window_from_window_id(winui3.microsoft.ui.WindowId windowId)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/winui3/microsoft/ui/interop.rst.txt

Gets the window handle that corresponds to the specified windowId, if the provided windowId is valid and the system has an HWND that represents the window.

```APIDOC
## get_window_from_window_id(winui3.microsoft.ui.WindowId windowId)

### Description
Gets the window handle that corresponds to the specified windowId, if the provided windowId is valid and the system has an HWND that represents the window.

### Parameters
- **windowId** (winui3.microsoft.ui.WindowId) - The identifier for the window for which to get the HWND.

### Returns
- **int** - The handle of the window that corresponds to the specified windowId.

### Raises
- **OSError** - if the OS call failed.
```

--------------------------------

### Set expiration time using DateTime

Source: https://pywinrt.readthedocs.io/en/latest/_sources/types.rst.txt

Example of setting a WinRT property using a Python datetime object with UTC timezone.

```python
# set notification to expire 10 seconds from now
toaster.expiration_time = datetime.now(timezone.utc) + timedelta(seconds=10)
```

--------------------------------

### get_icon_from_icon_id

Source: https://pywinrt.readthedocs.io/en/latest/api/winui3/microsoft/ui/interop.html

Gets the icon handle that corresponds to the specified iconId.

```APIDOC
## get_icon_from_icon_id(iconId: winui3.microsoft.ui.IconId) -> int

### Description
Gets the icon handle that corresponds to the specified iconId, if the provided iconId is valid and the system has an HICON that represents the icon.

### Parameters
- **iconId** (winui3.microsoft.ui.IconId) - The identifier for the icon for which to get the HICON.

### Returns
- **int** - The handle of the icon that corresponds to the specified iconId.

### Raises
- **OSError** - if the OS call failed.
```

--------------------------------

### get_display_id_from_monitor(int hmonitor)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/winui3/microsoft/ui/interop.rst.txt

Gets the DisplayId that corresponds to the specified hmonitor, if the provided HMONITOR is valid.

```APIDOC
## get_display_id_from_monitor(int hmonitor)

### Description
Gets the DisplayId that corresponds to the specified hmonitor, if the provided HMONITOR is valid.

### Parameters
- **hmonitor** (int) - The handle of the display monitor for which to get the DisplayId.

### Returns
- **DisplayId** (winui3.microsoft.ui.DisplayId) - The identifier that corresponds to the specified hmonitor.

### Raises
- **OSError** - if the OS call failed.
```

--------------------------------

### get_icon_id_from_icon(int hicon)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/winui3/microsoft/ui/interop.rst.txt

Gets the IconId that corresponds to the specified hicon, if the provided HICON is valid.

```APIDOC
## get_icon_id_from_icon(int hicon)

### Description
Gets the IconId that corresponds to the specified hicon, if the provided HICON is valid.

### Parameters
- **hicon** (int) - The handle of the icon for which to get the IconId.

### Returns
- **IconId** (winui3.microsoft.ui.IconId) - The identifier that corresponds to the specified hicon.

### Raises
- **OSError** - if the OS call failed.
```

--------------------------------

### get_icon_from_icon_id(winui3.microsoft.ui.IconId iconId)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/winui3/microsoft/ui/interop.rst.txt

Gets the icon handle that corresponds to the specified iconId, if the provided iconId is valid and the system has an HICON that represents the icon.

```APIDOC
## get_icon_from_icon_id(winui3.microsoft.ui.IconId iconId)

### Description
Gets the icon handle that corresponds to the specified iconId, if the provided iconId is valid and the system has an HICON that represents the icon.

### Parameters
- **iconId** (winui3.microsoft.ui.IconId) - The identifier for the icon for which to get the HICON.

### Returns
- **int** - The handle of the icon that corresponds to the specified iconId.

### Raises
- **OSError** - if the OS call failed.
```

--------------------------------

### get_monitor_from_display_id(winui3.microsoft.ui.DisplayId displayId)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/winui3/microsoft/ui/interop.rst.txt

Gets the display monitor handle that corresponds to the specified displayId, if the provided displayId is valid and the system has an HMONITOR that represents the display monitor.

```APIDOC
## get_monitor_from_display_id(winui3.microsoft.ui.DisplayId displayId)

### Description
Gets the display monitor handle that corresponds to the specified displayId, if the provided displayId is valid and the system has an HMONITOR that represents the display monitor.

### Parameters
- **displayId** (winui3.microsoft.ui.DisplayId) - The identifier for the display monitor for which to get the HMONITOR.

### Returns
- **int** - The handle of the display monitor that corresponds to the specified displayId.

### Raises
- **OSError** - if the OS call failed.
```

--------------------------------

### create_desktop_window_target(compositor, hwnd_target, *, is_topmost=False)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/windows/ui/composition/interop.rst.txt

Creates a visual layer on a window to host Composition content.

```APIDOC
## create_desktop_window_target

### Description
Creates a visual layer on a window to host Composition content.

### Parameters
- **compositor** (winrt.windows.ui.composition.Compositor) - Required - The Compositor object that is used to create the DesktopWindowTarget.
- **hwnd_target** (int) - Required - The window handle (HWND) that the visual layer will be attached to.
- **is_topmost** (bool) - Optional - Specifies if the target is topmost.

### Returns
- **DesktopWindowTarget** (winrt.windows.ui.composition.DesktopWindowTarget) - The created DesktopWindowTarget.

### Exceptions
- **OSError** - Raised on failure.
```

--------------------------------

### initialize(version: str = RELEASE_VERSION, min_version: str = RUNTIME_VERSION, options: InitializeOptions = InitializeOptions.NONE) -> Shutdown

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/winui3/microsoft/windows/applicationmodel/dynamicdepedency/bootstrap.rst.txt

Initializes the Windows App SDK runtime and returns a context manager for automatic shutdown.

```APIDOC
## initialize(version, min_version, options)

### Description
Initializes the Windows App SDK runtime. Returns a context manager that will shutdown the Windows App SDK runtime when exited.

### Parameters
- **version** (str) - Optional - The Windows App SDK product release version to load (e.g., "1.5").
- **min_version** (str) - Optional - The minimum version of the Windows App SDK runtime to load.
- **options** (InitializeOptions) - Optional - Initialization option flags.

### Returns
- **Shutdown** - A context manager that handles runtime shutdown.

### Raises
- **OSError** - If the initialization fails.

### Example
```python
with initialize(options=InitializeOptions.ON_NO_MATCH_SHOW_UI):
    # main code here
    ...
```
```

--------------------------------

### Create WinRT Arrays

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/system.rst.txt

Demonstrates initializing arrays with specific types and sizes or initial values.

```python
from winrt.system import Array
from winrt.windows.foundation import Point

# array of 10 32-bit unsigned integers.
a1 = Array("I", 10)
# array of 3 points with initial values
a2 = Array(Point, [Point(1, 1), Point(2, 2), Point(3, 3)])
```

--------------------------------

### Initialize the Windows App SDK Runtime

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/winui3/microsoft/windows/applicationmodel/dynamicdepedency/bootstrap.rst.txt

Uses a context manager to initialize the runtime, ensuring it is shut down automatically when the block exits.

```python
with initialize(options=InitializeOptions.ON_NO_MATCH_SHOW_UI):
    # main code here
    ...
```

--------------------------------

### create_direct3d11_surface_from_dxgi_surface(dxgi_surface)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/windows/graphics/directx/direct3d11/interop.rst.txt

Creates a WinRT Direct3D 11 surface from a DXGI surface pointer.

```APIDOC
## create_direct3d11_surface_from_dxgi_surface(dxgi_surface)

### Description
Creates a WinRT Direct3D 11 surface from a DXGI surface.

### Parameters
- **dxgi_surface** (int) - Required - Pointer to an IDXGISurface to create the Direct3D 11 surface from.

### Returns
- **Direct3D11Surface** - A Direct3D 11 surface.

### Exceptions
- **OSError** - Raised on failure.
```

--------------------------------

### create_direct3d11_device_from_dxgi_device(dxgi_device)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/windows/graphics/directx/direct3d11/interop.rst.txt

Creates a WinRT Direct3D 11 device from a DXGI device pointer.

```APIDOC
## create_direct3d11_device_from_dxgi_device(dxgi_device)

### Description
Creates a WinRT Direct3D 11 device from a DXGI device.

### Parameters
- **dxgi_device** (int) - Required - Pointer to an IDXGIDevice to create the Direct3D 11 device from.

### Returns
- **Direct3D11Device** - A Direct3D 11 device.

### Exceptions
- **OSError** - Raised on failure.
```

--------------------------------

### Use IClosable as a context manager

Source: https://pywinrt.readthedocs.io/en/latest/_sources/types.rst.txt

Shows how to use types implementing IClosable with the 'with' statement to ensure deterministic resource cleanup.

```python
from winrt.windows.foundation import MemoryBuffer

with MemoryBuffer(256) as buf:
    ...
```

--------------------------------

### Importing WinRT namespaces

Source: https://pywinrt.readthedocs.io/en/latest/_sources/types.rst.txt

Demonstrates how to import specific members or entire modules from a WinRT namespace.

```python
# import members of a namespace
from winrt.windows.foundation import Uri
# or import the namespace module itself
import winrt.windows.foundation as wf
```

--------------------------------

### initialize_with_window(obj: Object, hwnd: int) -> None

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/runtime.interop.rst.txt

Provides an owner window to a Windows Runtime (WinRT) object used in a desktop application. This function is useful for objects that implement the IInitializeWithWindow interface.

```APIDOC
## initialize_with_window(obj: Object, hwnd: int) -> None

### Description
Provide an owner window to a Windows Runtime (WinRT) object used in a desktop application.

### Parameters
- **obj** (Object) - Required - A WinRT object that implements the IInitializeWithWindow interface.
- **hwnd** (int) - Required - The handle of the window to be used as the owner window.

### Version
Added in version 3.0
```

--------------------------------

### create_for_window(window)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/windows/graphics/capture/interop.rst.txt

Creates a graphics capture item targeting a specific window using its HWND handle.

```APIDOC
## create_for_window(window)

### Description
Targets a single window for the creation of a graphics capture item.

### Parameters
- **window** (int) - Required - The window handle (HWND) that represents the window to capture.

### Returns
- **GraphicsCaptureItem** - A graphics capture item.
```

--------------------------------

### Initialize WinRT object with a window handle

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/runtime.interop.rst.txt

Provides an owner window to a WinRT object that implements the IInitializeWithWindow interface.

```python
def initialize_with_window(obj: Object, hwnd: int) -> None: ...
```

--------------------------------

### create_for_monitor(monitor)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/windows/graphics/capture/interop.rst.txt

Creates a graphics capture item targeting a specific monitor using its HMONITOR handle.

```APIDOC
## create_for_monitor(monitor)

### Description
Targets a monitor for the creation of a graphics capture item.

### Parameters
- **monitor** (int) - Required - The monitor handle (HMONITOR) that represents the monitor to capture.

### Returns
- **GraphicsCaptureItem** - A graphics capture item.
```

--------------------------------

### Initialize NotificationData with a dictionary

Source: https://pywinrt.readthedocs.io/en/latest/_sources/types.rst.txt

Demonstrates passing a Python dictionary to a WinRT type that supports IIterable<IKeyValuePair<K, V>>.

```python
data = NotificationData({"my_key": "my_value"})
```

--------------------------------

### uninit_apartment() -> None

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/runtime.rst.txt

Uninitializes the WinRT runtime. This is not necessary on thread exit, but can be used to uninitialize and re-initialize a thread if needed.

```APIDOC
## uninit_apartment() -> None

### Description
Uninitializes the WinRT runtime. Not necessary on thread exit, but can be used to uninitialize and re-initialize a thread if needed.
```

--------------------------------

### init_apartment(apartment_type: ApartmentType) -> None

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/runtime.rst.txt

Initializes the WinRT runtime in the specified apartment type. This is necessary for single-threaded scenarios like UI threads or when re-initializing a thread with a different apartment type.

```APIDOC
## init_apartment(apartment_type: ApartmentType) -> None

### Description
Initializes the WinRT runtime in the specified apartment type. Calling this function is only necessary if you need a single threaded, e.g. for UI thread, or if you need to re-initalize the thread with a different apartment type.

### Parameters
- **apartment_type** (ApartmentType) - Required - The apartment type to initialize the runtime in.
```

--------------------------------

### Iterate over Map keys

Source: https://pywinrt.readthedocs.io/en/latest/_sources/types.rst.txt

Demonstrates the default iteration behavior for WinRT mapping types in Python.

```python
for key in map:
    print(key)
```

--------------------------------

### Iterate over Map items

Source: https://pywinrt.readthedocs.io/en/latest/_sources/types.rst.txt

Demonstrates how to access both keys and values when iterating over a WinRT mapping type.

```python
for key, value in map.items():
    print(key, value)
```

--------------------------------

### Use WinRT Array Sequence Protocol

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/system.rst.txt

Shows how to interact with WinRT Array objects using standard Python sequence operations.

```python
# get the number of elements in the array
size = len(a1)
# get the first element of the array
item = a1[0]
# get the last element of the array
item = a1[-1]
# iterate all items of the array
for item in a1: ...
# test for element in array
if item in a1: ...
```

--------------------------------

### Unbox a winrt.system.Object

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/system.rst.txt

Shorthand for retrieving the original value from a winrt.system.Object using IPropertyValue.

```python
from winrt.windows.foundation import IPropertyValue

value = obj.as_(IPropertyValue).get_xyz()
```

--------------------------------

### Unboxing Functions

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/system.rst.txt

Functions to unbox a winrt.system.Object back into its original Python type.

```APIDOC
## unbox_*(value)

### Description
Unboxes the given winrt.system.Object into the original value. This is a shorthand for calling the IPropertyValue interface methods.

### Parameters
- **value** (Object) - Required - The winrt.system.Object to unbox.

### Returns
- **Any** - The original value extracted from the object.
```

--------------------------------

### get_dxgi_device_from_object(device)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/windows/graphics/directx/direct3d11/interop.rst.txt

Retrieves the IDXGIDevice from a Direct3D object.

```APIDOC
## get_dxgi_device_from_object(device)

### Description
Retrieves the IDXGIDevice from a Direct3D object.

### Parameters
- **device** (Direct3D11Device) - Required - The WinRT object to retrieve the IDXGIDevice from.

### Returns
- **int** - Pointer to IDXGIDevice interface of the WinRT object.
```

--------------------------------

### Access Static WinRT Properties

Source: https://pywinrt.readthedocs.io/en/latest/_sources/types.rst.txt

Demonstrates accessing static properties via the type object rather than an instance.

```python
from winrt.windows.foundation import GuidHelper

empty_uuid = GuidHelper.empty
```

--------------------------------

### Box a value into a winrt.system.Object

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/system.rst.txt

Shorthand for creating a PropertyValue object from a given value.

```python
from winrt.windows.foundation import PropertyValue

obj = PropertyValue.create_xyz(value)
```

--------------------------------

### create_dispatcher_queue_controller(thread_type, apartment_type)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/windows/system/interop.rst.txt

Creates a DispatcherQueueController to manage the lifetime of a DispatcherQueue for running tasks in priority order.

```APIDOC
## create_dispatcher_queue_controller(thread_type=DispatcherQueueThreadType.CURRENT, apartment_type=DispatcherQueueThreadApartmentType.NONE)

### Description
Creates a DispatcherQueueController. Use the created DispatcherQueueController to create and manage the lifetime of a DispatcherQueue to run queued tasks in priority order on the dispatcher queue's thread.

### Parameters
- **thread_type** (DispatcherQueueThreadType) - Optional - Thread affinity for a new DispatcherQueueController.
- **apartment_type** (DispatcherQueueThreadApartmentType) - Optional - Specifies whether to initialize the COM apartment on the new thread as an application single-threaded apartment (ASTA) or a single-threaded apartment (STA).

### Returns
- **DispatcherQueueController** - The created dispatcher queue controller.

### Exceptions
- **OSError** - Raised on failure.
```

--------------------------------

### Modify and Unpack WinRT Structs

Source: https://pywinrt.readthedocs.io/en/latest/_sources/types.rst.txt

Demonstrates how to handle immutable WinRT structs using copy.replace and tuple unpacking.

```python
# window.position is a winrt.windows.graphics.PointInt32

# fails with AttributeError because Point is immutable
window.position.x = 200

# modifying
new = copy.replace(window.position, x=200)

# passing a tuple
window.move_and_resize((100, 100, 800, 600))

# unpacking
x, y = window.position.unpack()
```

--------------------------------

### get_for_window(hwnd)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/windows/media/interop.rst.txt

Retrieves the ISystemMediaTransportControls interface for a specified window handle.

```APIDOC
## get_for_window(hwnd)

### Description
Targets a single window for the creation of a graphics capture item and retrieves the corresponding ISystemMediaTransportControls interface.

### Parameters
- **hwnd** (int) - Required - The top-level app window (HWND) for which the ISystemMediaTransportControls interface is retrieved.

### Returns
- **winrt.windows.media.SystemMediaTransportControls** - The interface that corresponds to the specified appWindow.
```

--------------------------------

### Array(type, [initializer, ])

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/system.rst.txt

A wrapper around the WinRT System.Array type that implements the Python sequence protocol.

```APIDOC
## Array(type, [initializer, ])

### Description
Creates a wrapper around a WinRT array. This type supports the Python sequence protocol, allowing for indexing, length checks, and iteration.

### Parameters
- **type** (str or type) - Required - The type to use for elements of the array.
- **initializer** (int or iter or buffer) - Optional - An optional iterator of values to initialize the array, or an integer representing the size of an empty array.
```

--------------------------------

### Boxing Functions

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/system.rst.txt

Functions to box various primitive types into a winrt.system.Object.

```APIDOC
## box_*(value)

### Description
Boxes the given value into a winrt.system.Object. This is a shorthand for calling PropertyValue.create_xyz(value).

### Parameters
- **value** (bool | str | int | float | uuid.UUID | datetime.datetime | datetime.timedelta) - Required - The value to be boxed.

### Returns
- **Object** - The boxed representation of the input value.
```

--------------------------------

### get_dxgi_surface_from_object(surface)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/windows/graphics/directx/direct3d11/interop.rst.txt

Retrieves the IDXGISurface from a Direct3D object.

```APIDOC
## get_dxgi_surface_from_object(surface)

### Description
Retrieves the IDXGISurface from a Direct3D object.

### Parameters
- **surface** (Direct3D11Surface) - Required - The WinRT object to retrieve the IDXGISurface from.

### Returns
- **int** - Pointer to IDXGISurface interface of the WinRT object.
```

--------------------------------

### Access WinRT Properties

Source: https://pywinrt.readthedocs.io/en/latest/_sources/types.rst.txt

Shows standard property access for WinRT objects in Python.

```python
from winrt.windows.foundation import Uri

uri = Uri("https://example.com")
print(uri.scheme_name)
```

--------------------------------

### Object.as_(type)

Source: https://pywinrt.readthedocs.io/en/latest/_sources/api/system.rst.txt

Casts a WinRT wrapper object to a specified type.

```APIDOC
## Object.as_(type)

### Description
Casts the WinRT object to the specified type. This is used when a wrapper object is returned as a base type or interface type that needs to be converted.

### Parameters
- **type** (type) - Required - The type to cast the object to.

### Returns
- (Object) - The object cast to the specified type.
```

--------------------------------

### Await an asynchronous WinRT method

Source: https://pywinrt.readthedocs.io/en/latest/_sources/types.rst.txt

Use the await keyword to wait for the result of an asynchronous WinRT method within an asyncio context.

```python
thing = await winrt_obj.get_thing_async()
```

--------------------------------

### IAsyncAction/IAsyncOperation.wait()

Source: https://pywinrt.readthedocs.io/en/latest/_sources/types.rst.txt

Blocks the current thread until the operation completes or the specified timeout is reached.

```APIDOC
## IAsyncAction.wait() / IAsyncOperation.wait()

### Description
Blocks until the operation is complete or the timeout is reached. Returns the status of the operation.

### Parameters
- **timeout** (float) - Required - The timeout duration in seconds.

### Returns
- **AsyncStatus** - The status of the operation. Returns AsyncStatus.STARTED if a timeout occurs.

### Raises
- **RuntimeError** - If called from a single-threaded apartment (e.g., a GUI thread).
```

--------------------------------

### IAsyncAction/IAsyncOperation.get()

Source: https://pywinrt.readthedocs.io/en/latest/_sources/types.rst.txt

Blocks the current thread until the asynchronous operation completes. This method is available on all WinRT async types.

```APIDOC
## IAsyncAction.get() / IAsyncOperation.get()

### Description
Blocks the execution until the asynchronous operation is complete. Returns the result of the operation if applicable.

### Parameters
- **self** - The async object instance.

### Returns
- **TResult** (Any) - The result of the operation (if applicable).

### Raises
- **OSError** - If the operation failed or was canceled.
- **RuntimeError** - If called from a single-threaded apartment (e.g., a GUI thread).
```
Tokens:
Raw