WinSafe

WinSafe provides a safe, idiomatic Rust interface for the Windows API. It is divided into two main layers:

1. Low-level Win32 API: Provides direct access to constants, functions, structs, window messages, handles, and COM interfaces.
2. High-level GUI controls: Provides abstractions for building native applications, including custom windows/dialogs (main, modal, modeless, etc.) and native controls like buttons, combo boxes, list views, and progress bars.

WinSafe provides 5 types of windows that can host child controls. For most standard GUI applications, you should start by using WindowMain.

Available window types:

• WindowMain: The standard entry point for a GUI application.
• WindowModal: A window that requires user interaction before returning to the parent window.
• WindowModeless: A window that allows interaction with other windows while it is open.
• WindowMessageOnly: A window that does not have a visible interface but can receive messages.
• WindowControl: A custom, user-defined child control.

winsafe categorizes messages into two main types based on their capability:

1. Sendable Messages: All messages can be sent to a window. These implement the MsgSend trait. When you call SendMessage, you pass a struct representing the message.
2. Receivable Messages: Messages that can be handled (intercepted) by a window procedure implement the MsgSendRecv trait. This is useful when implementing custom window logic from scratch.

All messages are fundamentally based on the Wm struct, which contains the msg_id, wparam, and lparam fields.

To use WinSafe in your Rust project, add it to your Cargo.toml. You must explicitly enable the Cargo features corresponding to the Windows DLLs and libraries you need (e.g., user for User32.dll, gdi for Gdi32.dll).

Note that the gui feature is required to use the high-level GUI abstractions.

[dependencies]
winsafe = { version = "0.0.28", features = ["gui", "user"] }

To interact with Windows controls (like a ListView), you can send specific messages using the HWND::SendMessage method. In winsafe, messages are represented as structs that encapsulate the message ID and its parameters (WPARAM and LPARAM). The message struct also defines the return type of the operation via its RetType associated type.

For example, to delete an item from a ListView, you use the LvmDeleteItem struct.

use winsafe::{self as w, prelude::*, msg};

let hlistview: w::HWND; // initialized somewhere

hlistview.SendMessage(
    msg::LvmDeleteItem {
        index: 2,
    },
).expect("Failed to delete item 2.");

In winsafe, TreeView event methods (defined in GuiEventsTreeView) are not handled directly by the TreeView control itself, but are proxies to the GuiEventsParent of the parent window. The parent window is the entity actually responsible for receiving and dispatching child control events in the Win32 message loop.

When you call an event handler like tree.on().tvn_sel_changed(...), you are registering a callback that the parent window will execute when the specific notification is received from the TreeView control.

In winsafe, ListView notifications are exposed via the GuiEventsListView trait. These methods act as proxies to the GuiEventsParent of the parent window, as the parent window is responsible for handling child control events.

To use these event handlers, you should import the winsafe::prelude::* trait, which makes these methods available on your ListView instance via the .on() method.

Note: These event methods are only available when the gui Cargo feature is enabled.

use winsafe::prelude::*;

// Assuming 'list' is a gui::ListView instance
list.on().lvn_item_changed(|p: &NMLISTVIEW| -> AnyResult<()> {
    println!("Item changed: {}", p.iItem);
    Ok(())
});