hwnd 0.0.0-2024-01-05

Well documented, safe-leaning, sound, low-level API bindings to `HWND`-adjacent APIs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

use crate::{*, SW::ShowWindowCmd};
use winapi::um::winuser::*;



/// \[[learn.microsoft.com](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-showwindow)\]
/// ShowWindow
///
/// Sets `hwnd`'s show state.
///
/// ### Errors
/// *   [ERROR::INVALID_WINDOW_HANDLE]  If `hwnd` is an invalid handle.
///
/// ### Example
/// ```rust
/// # use hwnd::*;
/// # use winresult::*;
/// # use std::ptr::*;
/// # let desktop   = get_desktop_window();
/// # let vscode    = get_foreground_window();
/// #
/// # if is_zoomed(vscode) {
/// show_window(vscode, SW::MAXIMIZE).unwrap();
/// # }
///
/// assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(),        SW::HIDE).unwrap_err());
/// assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,           SW::HIDE).unwrap_err());
/// assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(!42usize as HWND,  SW::HIDE).unwrap_err());
/// #
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(), SW::SHOWNORMAL      ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(), SW::NORMAL          ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(), SW::SHOWMINIMIZED   ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(), SW::SHOWMAXIMIZED   ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(), SW::MAXIMIZE        ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(), SW::SHOWNOACTIVATE  ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(), SW::SHOW            ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(), SW::MINIMIZE        ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(), SW::SHOWMINNOACTIVE ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(), SW::SHOWNA          ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(), SW::RESTORE         ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(null_mut(), SW::SHOWDEFAULT     ).unwrap_err());
/// #
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,    SW::SHOWNORMAL      ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,    SW::NORMAL          ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,    SW::SHOWMINIMIZED   ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,    SW::SHOWMAXIMIZED   ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,    SW::MAXIMIZE        ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,    SW::SHOWNOACTIVATE  ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,    SW::SHOW            ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,    SW::MINIMIZE        ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,    SW::SHOWMINNOACTIVE ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,    SW::SHOWNA          ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,    SW::RESTORE         ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window(desktop,    SW::SHOWDEFAULT     ).unwrap_err());
/// ```
///
/// ### See Also
/// *   [show_window_async]
pub fn show_window(hwnd: impl TryInto<HWnd>, cmd: ShowWindowCmd) -> Result<(), Error> {
    fn_context!(show_window => ShowWindow);
    let hwnd = hwnd.try_into().map_err(|_| fn_param_error!(hwnd, ERROR::INVALID_WINDOW_HANDLE))?.into();
    fn_succeeded!(unsafe { ShowWindow(hwnd, cmd.into()) })
}

/// \[[learn.microsoft.com](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-showwindowasync)\]
/// ShowWindowAsync
///
/// Sets `hwnd`'s show state, without waiting for the operation to complete.
///
/// ### Errors
/// *   [ERROR::INVALID_WINDOW_HANDLE]  If `hwnd` is an invalid handle.
///
/// ### Example
/// ```rust
/// # use hwnd::*;
/// # use winresult::*;
/// # use std::ptr::*;
/// # let desktop   = get_desktop_window();
/// # let vscode    = get_foreground_window();
/// #
/// # if is_zoomed(vscode) {
/// show_window_async(vscode, SW::MAXIMIZE).unwrap();
/// # }
///
/// assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(),       SW::HIDE).unwrap_err());
/// assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,          SW::HIDE).unwrap_err());
/// assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(!42usize as HWND, SW::HIDE).unwrap_err());
/// #
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(), SW::SHOWNORMAL      ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(), SW::NORMAL          ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(), SW::SHOWMINIMIZED   ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(), SW::SHOWMAXIMIZED   ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(), SW::MAXIMIZE        ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(), SW::SHOWNOACTIVATE  ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(), SW::SHOW            ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(), SW::MINIMIZE        ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(), SW::SHOWMINNOACTIVE ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(), SW::SHOWNA          ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(), SW::RESTORE         ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(null_mut(), SW::SHOWDEFAULT     ).unwrap_err());
/// #
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,    SW::SHOWNORMAL      ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,    SW::NORMAL          ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,    SW::SHOWMINIMIZED   ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,    SW::SHOWMAXIMIZED   ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,    SW::MAXIMIZE        ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,    SW::SHOWNOACTIVATE  ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,    SW::SHOW            ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,    SW::MINIMIZE        ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,    SW::SHOWMINNOACTIVE ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,    SW::SHOWNA          ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,    SW::RESTORE         ).unwrap_err());
/// # assert_eq!(ERROR::INVALID_WINDOW_HANDLE, show_window_async(desktop,    SW::SHOWDEFAULT     ).unwrap_err());
/// ```
///
/// ### See Also
/// *   [show_window]
pub fn show_window_async(hwnd: impl TryInto<HWnd>, cmd: ShowWindowCmd) -> Result<(), Error> {
    fn_context!(show_window_async => ShowWindowAsync);
    let hwnd = hwnd.try_into().map_err(|_| fn_param_error!(hwnd, ERROR::INVALID_WINDOW_HANDLE))?.into();
    fn_succeeded!(unsafe { ShowWindowAsync(hwnd, cmd.into()) })
}