Crate winsafe[−][src]
Expand description
Win32 GUI and related APIs in safe, idiomatic Rust.
WinSafe has:
- high-level structs to build native Win32 GUI applications;
- low-level Win32 API constants, functions and structs related to GUI.
If you’re looking for a comprehensive Win32 coverage, take a look at winapi or windows crates, which are unsafe, but have everything.
Links:
- Crate – crates.io/crates/winsafe;
- GitHub – github.com/rodrigocfd/winsafe;
- examples – github.com/rodrigocfd/winsafe-examples.
Usage
Add the dependency in your Cargo.toml
:
[dependencies]
winsafe = "0.0.7"
The COM modules are disabled by default, and can be enabled when needed:
Module | Cargo.toml [dependencies] |
---|---|
Automation | winsafe = { version = "0.0.7", features = ["autom"] } |
DirectShow | winsafe = { version = "0.0.7", features = ["dshow"] } |
IDL | winsafe = { version = "0.0.7", features = ["idl"] } |
Shell | winsafe = { version = "0.0.7", features = ["shell"] } |
Modules overview
The Win32 bindings are divided into a few modules:
Module | Description |
---|---|
winsafe | The root of the crate has Win32 free functions and structs. |
winsafe::co | Types and values of Win32 constants. |
winsafe::msg | Window messages. |
winsafe::gui | High-level GUI wrappers. |
And the COM modules:
Module | Description |
---|---|
winsafe::autom | Win32 Automation COM interfaces. |
winsafe::dshow | Win32 DirectShow COM interfaces. |
winsafe::idl | Win32 IDL COM interfaces. |
winsafe::shell | Win32 Shell COM interfaces. |
The GUI API
WinSafe features idiomatic bindings for the Win32 API, but on top of that,
it features a set of high-level GUI structs, which scaffolds the boilerplate
needed to build native Win32 GUI applications, event-oriented. Unless you’re
doing something really specific, these high-level wrappers are highly
recommended – you’ll usually start with the
WindowMain
.
One of the greatest strenghts of the GUI API is supporting the use of resource files, which can be created with a WYSIWYG resource editor.
GUI structs can be found in module gui
.
Native function calls
The best way to understand the idea behind WinSafe bindings is comparing them to the correspondent C code.
For example, take the following C code:
HWND hwnd = GetDesktopWindow();
SetFocus(hwnd);
This is equivalent to:
use winsafe::HWND;
let hwnd = HWND::GetDesktopWindow();
hwnd.SetFocus();
Note how GetDesktopWindow
is a static
method of HWND
, and SetFocus
is
an instance method called directly upon hwnd
. All native handles (HWND
,
HDC
, HINSTANCE
, etc.) are structs,
thus:
- native Win32 functions that return a handle are static methods in WinSafe;
- native Win32 functions whose first parameter is a handle are instance methods.
Now this C code:
PostQuitMessage(0);
Is equivalent to:
use winsafe::PostQuitMessage;
PostQuitMessage(0);
Since PostQuitMessage
is a free function, it’s
simply at the root of the crate.
Native constants
All native Win32 constants can be found in the co
module.
They’re all typed, what means that different constant types cannot be
mixed (unless you explicitly say so).
Technically, each constant type is simply a newtype with a couple implementations, including those allowing bitflag operations. Also, all constant values can be converted to its underlying integer type.
The name of the constant type is often its prefix. For example, constants of
MessageBox
function, like MB_OKCANCEL
, belong
to a type called MB
.
For example, take the following C code:
let hwnd = GetDesktopWindow();
MessageBox(hwnd, "Hello, world", "My hello", MB_OKCANCEL | MB_ICONINFORMATION);
This is equivalent to:
use winsafe::{co::MB, HWND};
let hwnd = HWND::GetDesktopWindow();
hwnd.MessageBox("Hello, world", "Title", MB::OKCANCEL | MB::ICONINFORMATION)?;
The method MessageBox
, like all native
functions that can return errors, will return
WinResult
, which can contain an
ERROR
constant.
Native structs
WinSafe implements native Win32 structs in a very restricted way. First off,
fields which control the size of the struct – often named cbSize
– are
private and automatically set when the struct is instantiated.
Pointer fields are also private, and they can be set and retrieved only
through getter and setter methods. In particular, when setting a string
pointer field, you need to pass a reference to a WString
buffer, which will keep the actual string contents.
For example, the following C code:
WNDCLASSEX wcx = {0};
wcx.cbSize = sizeof(WNDCLASSEX);
wcx.lpszClassName = "MY_WINDOW";
if (RegisterClassEx(&wcx) == 0) {
DWORD err = GetLastError();
// handle error...
}
Is equivalent to:
use winsafe::{RegisterClassEx, WNDCLASSEX, WString};
let buf = WString::from_str("MY_WINDOW");
let mut wcx = WNDCLASSEX::default();
wcx.set_lpszClassName(&buf);
if let Err(err) = RegisterClassEx(&wcx) {
// handle error...
}
Note how you don’t need to call GetLastError
to
retrieve the error code: it’s returned by the method itself in the
WinResult
.
Text encoding
Windows natively uses Unicode UTF-16.
WinSafe uses Unicode UTF-16 internally but exposes idiomatic UTF-8,
performing conversions automatically when needed, so you don’t have to worry
about OsString
or any low-level conversion.
However, there are cases where a string conversion is still needed, like
when dealing with native Win32 structs. In such cases, you can use the
WString
struct, which is also capable of working as a
buffer to receive text from Win32 calls.
Modules
Automation COM interfaces, structs and constants.
Win32 constants and types of constants.
DirectShow COM interfaces, structs and constants.
High-level GUI abstractions for user windows and native controls. They can
be created programmatically or by loading resources from a .res
file.
These files can be created with a WYSIWYG
resource editor.
Parameters of window messages.
File path utilities.
Commonly imported traits.
Structs
ALTTABINFO
struct.
ATOM
returned by RegisterClassEx
.
The data of the AccelMenuCtrl
Ctrl
option.
BITMAPINFO
struct.
BITMAPINFOHEADER
struct.
BUTTON_IMAGELIST
struct.
BUTTON_SPLITINFO
struct.
CHOOSECOLOR
struct.
COMBOBOXINFO
struct.
CREATESTRUCT
struct.
A pointer to a COM virtual table.
DELETEITEMSTRUCT
struct.
DRAWITEMSTRUCT
struct.
Manages a memory-mapped file, which can be read/written through slices. It is closed automatically when the object goes out of scope.
GUITHREADINFO
struct.
Handle to an accelerator table.
Handle to a device context.
Handle to an internal drop structure.
Handle to a deferred window position.
Handle to a
file mapping.
Originally just a HANDLE
.
Address of a
mapped view.
Originally just an LPVOID
.
Handle to a
file search.
Originally just a HANDLE
.
Handle to a
global memory block.
Originally just a HANDLE
.
Handle to an image list.
Handle to a registry key.
Handle to a local memory block.
Handle to a display monitor.
Handle to an
anonymous pipe.
Originally just a HANDLE
.
Handle to a process list
snapshot.
Originally just a HANDLE
.
Handle to a resource
memory block.
Originally just an HGLOBAL
.
Handle to an tree view item.
Handle to an
updateable resource.
Originally just a HANDLE
.
IUnknown
COM interface over IUnknownVT
. It’s the base to all
COM interfaces.
IUnknown
virtual table, base to all COM virtual tables.
Keeps sections and key/value pairs of a .ini
file, also doing parsing and
serialization of the data.
A single key/value pair of an IniSection
of an
Ini
.
A single section of an Ini
.
LVFINDINFO
struct.
LVHITTESTINFO
struct.
LVITEMINDEX
struct.
MEMORYSTATUSEX
struct.
MENUBARINFO
struct.
MENUITEMINFO
struct.
MINMAXINFO
struct.
MONITORINFO
struct.
MSLLHOOKSTRUCT
struct.
NMBCDROPDOWN
struct.
NMBCHOTITEM
struct.
NMCUSTOMDRAW
struct.
NMDATETIMECHANGE
struct.
NMDATETIMEFORMAT
struct.
NMDATETIMESTRING
struct.
NMDAYSTATE
struct.
NMIPADDRESS
struct.
NMITEMACTIVATE
struct.
NMLISTVIEW
struct.
NMLVCACHEHINT
struct.
NMLVCUSTOMDRAW
struct.
NMLVDISPINFO
struct.
NMLVEMPTYMARKUP
struct.
NMLVFINDITEM
struct.
NMLVGETINFOTIP
struct.
NMLVKEYDOWN
struct.
NMLVSCROLL
struct.
NMSELCHANGE
struct.
NMTREEVIEW
struct.
NMTVASYNCDRAW
struct.
NMTVCUSTOMDRAW
stuct.
NMTVITEMCHANGE
struct.
NMVIEWCHANGE
struct.
NONCLIENTMETRICS
struct.
NOTIFYICONDATA
struct.
OSVERSIONINFOEX
struct.
OVERLAPPED
struct.
PAINTSTRUCT
struct.
PROCESSENTRY32
struct.
Retrieves data from an embedded resource, which can be read from an executable file or a DLL.
SCROLLINFO
struct.
SHFILEINFO
struct.
SHFILEOPSTRUCT
struct.
STARTUPINFO
struct.
STYLESTRUCT
struct.
SYSTEMTIME
struct.
SYSTEM_INFO
struct.
TASKDIALOGCONFIG
struct.
TBADDBITMAP
struct.
TEXTMETRIC
struct.
TITLEBARINFOEX
struct.
TRACKMOUSEEVENT
struct.
TVINSERTSTRUCT
struct.
VS_FIXEDFILEINFO
struct.
WIN32_FIND_DATA
struct.
WINDOWINFO
struct.
WINDOWPLACEMENT
struct.
WNDCLASSEX
struct.
Stores a Vec<u16>
buffer for a null-terminated
Unicode UTF-16
wide string natively used by Windows.
Enums
Variant parameters of a wm::Command
message.
Variant parameter used in window class functions:
Variant parameter for:
Variant parameter for:
Variant parameter for:
Variant parameter for:
String encodings that can be guessed by
WString::guess_encoding
.
Access types for File::open
and
FileMapped::open
.
Variant parameter for:
Variant parameter for:
Variant parameter for:
Variant parameter for:
Variant parameter for:
Variant parameter for:
Variant parameter for:
Variant parameter for:
Variant parameter for:
Variant parameter for:
Variant parameter for:
Variant parameter for:
Variant parameter for:
Variant parameter for:
Registry value types.
Variant parameter for:
Variant parameter for:
Variant parameter for:
Functions
AdjustWindowRectEx
function.
AttachThreadInput
function.
ChooseColor
function.
ClipCursor
function.
CloseClipboard
function.
CoCreateInstance
function.
CoInitializeEx
function. Returns some error codes as success status.
CoTaskMemFree
function.
CoUninitialize
function.
CommDlgExtendedError
function.
CommandLineToArgv
function.
DecryptFile
function.
DeleteFile
function.
DispatchMessage
function.
EmptyClipboard
function.
EncryptFile
function.
EncryptionDisable
function.
EnumWindows
function.
FileTimeToSystemTime
function.
GetAsyncKeyState
function.
GetBinaryType
function.
GetClipCursor
function.
GetCommandLine
function.
GetComputerName
function.
GetCurrentDirectory
function.
GetCurrentProcessId
function.
GetCurrentThreadId
function.
GetCursorPos
function.
GetDialogBaseUnits
function.
GetDoubleClickTime
function.
GetFileAttributes
function.
GetFileVersionInfo
function.
GetFirmwareType
function.
GetGUIThreadInfo
function.
GetLargePageMinimum
function.
GetLastError
function.
GetMessage
function.
GetMessagePos
function.
GetNativeSystemInfo
function.
GetQueueStatus
function.
GetStartupInfo
function.
GetSysColor
function.
GetSystemDirectory
function.
GetSystemInfo
function.
GetSystemMetrics
function.
GetSystemTime
function.
GetSystemTimes
function.
GetTempPath
function.
GetTickCount64
function.
GetUserName
function.
GlobalMemoryStatusEx
function.
Returns the high-order u32
of an u64
.
HRESULT_FROM_WIN32
function. Originally a macro.
InitCommonControls
function.
IsGUIThread
function.
IsNativeVhdBoot
function.
IsWindows7OrGreater
function.
IsWindows8OrGreater
function.
IsWindows10OrGreater
function.
IsWindowsServer
function.
IsWow64Message
function.
Returns the low-order u32
of an u64
.
Function that implements
MAKELONG
,
MAKEWPARAM
,
and
MAKELPARAM
macros.
MultiByteToWideChar
function.
OutputDebugString
function.
PeekMessage
function.
PostQuitMessage
function.
RegisterClassEx
function.
ReleaseCapture
function.
ReplaceFile
function.
SHAddToRecentDocs
function.
SHFileOperation
function.
SHGetFileInfo
function.
SetCaretBlinkTime
function.
SetCaretPos
function.
SetClipboardData
function.
SetCurrentDirectory
function.
SetCursorPos
function.
SetLastError
function.
SetProcessDPIAware
function.
Shell_NotifyIcon
function.
ShowCursor
function.
SoundSentry
function.
SystemTimeToFileTime
function.
TaskDialogIndirect
function.
TrackMouseEvent
function.
TranslateMessage
function.
UnregisterClass
function.
VarQueryValue
function.
VerSetConditionMask
function.
VerifyVersionInfo
function.
WaitMessage
function.
WideCharToMultiByte
function.
Type Definitions
Type alias to
CCHOOKPROC
callback function.
Type alias to
PFTASKDIALOGCALLBACK
calback function.
Type alias to
SUBCLASSPROC
callback function.