windows_win/raw/
message.rs

1//! Provides functions to handle windows messages.
2
3use core::{mem, ptr};
4
5use crate::sys::*;
6use crate::utils::{self, Result};
7
8///Retrieves a message from the calling thread's message queue. A blocking call.
9///
10///# Parameters:
11///
12///* ```window``` - A handle to the window whose messages are to be retrieved. The window must belong to the current thread.
13///* ```range_low``` - Integer value of the lowest message to retrieve.
14///* ```range_high``` - Integer value of the highest message to retrieve.
15///
16///# Return
17///
18///* ```Ok``` - Successfully retrieved message..
19///* ```Err``` - Impossible to retrieve message.
20pub fn get(window: Option<HWND>, range_low: Option<UINT>, range_high: Option<UINT>) -> Result<MSG> {
21    let mut msg: MSG = unsafe { mem::zeroed() };
22
23    let result = unsafe { GetMessageW(&mut msg as LPMSG,
24                                      window.unwrap_or(ptr::null_mut()),
25                                      range_low.unwrap_or(0),
26                                      range_high.unwrap_or(0)) };
27
28    if result < 0 {
29        Err(utils::get_last_error())
30    }
31    else {
32        Ok(msg)
33    }
34}
35
36///Retrieves a message from the calling thread's message queue.
37///
38///A non-blocking version of [get()](fn.get.html).
39///
40///If no message presents in queue then returns None.
41///
42///# Parameters:
43///
44///* ```window``` - A handle to the window whose messages are to be retrieved. The window must belong to the current thread.
45///* ```range_low``` - Integer value of the lowest message to retrieve.
46///* ```range_high``` - Integer value of the highest message to retrieve.
47///* ```handle_type``` - Determines how retrieved message is handled. See [details](https://msdn.microsoft.com/en-us/library/windows/desktop/ms644943(v=vs.85).aspx)
48///
49///# Return
50///
51///* ```Ok``` - Successfully retrieved message..
52///* ```Err``` - Impossible to retrieve message.
53pub fn peek(window: Option<HWND>, range_low: Option<UINT>, range_high: Option<UINT>, handle_type: Option<UINT>) -> Result<Option<MSG>> {
54    let mut msg: MSG = unsafe { mem::zeroed() };
55
56    let result = unsafe { PeekMessageW(&mut msg as LPMSG,
57                                       window.unwrap_or(ptr::null_mut()),
58                                       range_low.unwrap_or(0),
59                                       range_high.unwrap_or(0),
60                                       handle_type.unwrap_or(0)) };
61
62    if result < 0 {
63        Err(utils::get_last_error())
64    }
65    else if result == 0 {
66        Ok(None)
67    }
68    else {
69        Ok(Some(msg))
70    }
71}
72
73#[inline]
74///Translates virtual-key messages into character messages.
75///
76///The character messages are posted to the calling thread's message queue.
77///
78///# Parameters:
79///
80///* ```msg``` - Pointer to message retrieved by [get()](fn.get.html) or [peek()](fn.peek.html).
81///
82///# Return
83///
84///* ```true``` - Translation happened.
85///* ```false``` - Otherwise.
86pub fn translate(msg: LPMSG) -> bool {
87    unsafe {
88        TranslateMessage(msg) != 0
89    }
90}
91
92#[inline]
93///Dispatches a message to a window procedure.
94///
95///# Parameters:
96///
97///* ```msg``` - Pointer to message retrieved by [get()](fn.get.html) or [peek](fn.peek.html).
98///
99///# Return:
100///
101///Integer value whose meaning depends on dispatched messaged. Can be ignored.
102pub fn dispatch(msg: LPMSG) -> LRESULT {
103    unsafe {
104        DispatchMessageW(msg)
105    }
106}
windows_win/raw/message.rs

windows_win/raw/
message.rs
