Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Tidy up "platform-specifc" doc sections #2356

Merged
merged 3 commits into from
Jul 20, 2022
Merged

Tidy up "platform-specifc" doc sections #2356

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fc009d6
Tidy up "platform-specific" doc sections
maroider Jul 3, 2022
c155a8c
Unrelated grammatical fix
maroider Jul 3, 2022
1d628ae
Subjective improvements
maroider Jul 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 11 additions & 7 deletions src/event.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -277,17 +277,19 @@ pub enum WindowEvent<'a> {

/// The keyboard modifiers have changed.
///
/// Platform-specific behavior:
/// - **Web**: This API is currently unimplemented on the web. This isn't by design - it's an
/// ## Platform-specific
///
/// - **Web:** This API is currently unimplemented on the web. This isn't by design - it's an
/// issue, and it should get fixed - but it's the current state of the API.
ModifiersChanged(ModifiersState),

/// An event from input method.
/// An event from an input method.
///
/// **Note :** You have to explicitly enable this event using [`Window::set_ime_allowed`].
/// **Note:** You have to explicitly enable this event using [`Window::set_ime_allowed`].
///
/// Platform-specific behavior:
/// - **iOS / Android / Web :** Unsupported.
/// ## Platform-specific
///
/// - **iOS / Android / Web:** Unsupported.
Ime(Ime),

/// The cursor has moved on the window.
Expand Down Expand Up @@ -370,6 +372,8 @@ pub enum WindowEvent<'a> {
/// Applications might wish to react to this to change the theme of the content of the window
/// when the system changes the window theme.
///
/// ## Platform-specific
///
/// At the moment this is only supported on Windows.
ThemeChanged(Theme),

Expand All @@ -379,7 +383,7 @@ pub enum WindowEvent<'a> {
/// minimised, set invisible, or fully occluded by another window.
///
/// Platform-specific behavior:
/// - **iOS / Android / Web / Wayland / Windows :** Unsupported.
/// - **iOS / Android / Web / Wayland / Windows:** Unsupported.
Occluded(bool),
}

Expand Down
9 changes: 5 additions & 4 deletions src/event_loop.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,7 @@ pub enum ControlFlow {
/// whether or not new events are available to process.
///
/// ## Platform-specific
///
/// - **Web:** Events are queued and usually sent when `requestAnimationFrame` fires but sometimes
/// the events in the queue may be sent before the next `requestAnimationFrame` callback, for
/// example when the scaling of the page has changed. This should be treated as an implementation
Expand All @@ -171,8 +172,8 @@ pub enum ControlFlow {
///
/// ## Platform-specific
///
/// - **Android / iOS / WASM**: The supplied exit code is unused.
/// - **Unix**: On most Unix-like platforms, only the 8 least significant bits will be used,
/// - **Android / iOS / WASM:** The supplied exit code is unused.
/// - **Unix:** On most Unix-like platforms, only the 8 least significant bits will be used,
/// which can cause surprises with negative exit values (`-42` would end up as `214`). See
/// [`std::process::exit`].
///
Expand Down Expand Up @@ -264,7 +265,7 @@ impl<T> EventLoop<T> {
///
/// ## Platform-specific
///
/// - **X11 / Wayland**: The program terminates with exit code 1 if the display server
/// - **X11 / Wayland:** The program terminates with exit code 1 if the display server
/// disconnects.
///
/// [`ControlFlow`]: crate::event_loop::ControlFlow
Expand Down Expand Up @@ -321,7 +322,7 @@ impl<T> EventLoopWindowTarget<T> {
///
/// ## Platform-specific
///
/// - **Wayland / Windows / macOS / iOS / Android / Web**: Unsupported.
/// - **Wayland / Windows / macOS / iOS / Android / Web:** Unsupported.
///
/// [`DeviceEvent`]: crate::event::DeviceEvent
pub fn set_device_event_filter(&self, _filter: DeviceEventFilter) {
Expand Down
2 changes: 1 addition & 1 deletion src/platform/run_return.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ pub trait EventLoopExtRunReturn {
///
/// ## Platform-specific
///
/// - **Unix-alikes** (**X11** or **Wayland**): This function returns `1` upon disconnection from
/// - **X11 / Wayland:** This function returns `1` upon disconnection from
/// the display server.
fn run_return<F>(&mut self, event_handler: F) -> i32
where
Expand Down
33 changes: 17 additions & 16 deletions src/window.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,20 +203,20 @@ impl WindowBuilder {
///
/// ## Platform-specific
///
/// - **macOS**: The top left corner position of the window content, the
/// - **macOS:** The top left corner position of the window content, the
/// window's "inner" position. The window title bar will be placed above
/// it. The window will be positioned such that it fits on screen,
/// maintaining set `inner_size` if any.
/// If you need to precisely position the top left corner of the whole
/// window you have to use [`Window::set_outer_position`] after creating
/// the window.
/// - **Windows**: The top left corner position of the window title bar,
/// - **Windows:** The top left corner position of the window title bar,
/// the window's "outer" position.
/// There may be a small gap between this position and the window due to
/// the specifics of the Window Manager.
/// - **X11**: The top left corner of the window, the window's "outer"
/// - **X11:** The top left corner of the window, the window's "outer"
/// position.
/// - **Others**: Ignored.
/// - **Others:** Ignored.
#[inline]
pub fn with_position<P: Into<Position>>(mut self, position: P) -> Self {
self.window.position = Some(position.into());
Expand Down Expand Up @@ -333,8 +333,9 @@ impl WindowBuilder {
///
/// Possible causes of error include denied permission, incompatible system, and lack of memory.
///
/// Platform-specific behavior:
/// - **Web**: The window is created but not inserted into the web page automatically. Please
/// ## Platform-specific
///
/// - **Web:** The window is created but not inserted into the web page automatically. Please
/// see the web platform module for more information.
#[inline]
pub fn build<T: 'static>(
Expand All @@ -359,8 +360,9 @@ impl Window {
/// Error should be very rare and only occur in case of permission denied, incompatible system,
/// out of memory, etc.
///
/// Platform-specific behavior:
/// - **Web**: The window is created but not inserted into the web page automatically. Please
/// ## Platform-specific
///
/// - **Web:** The window is created but not inserted into the web page automatically. Please
/// see the web platform module for more information.
///
/// [`WindowBuilder::new().build(event_loop)`]: WindowBuilder::build
Expand Down Expand Up @@ -648,10 +650,7 @@ impl Window {
///
/// This only has an effect on desktop platforms.
///
/// Due to a bug in XFCE, this has no effect on Xfwm.
///
/// ## Platform-specific
///
/// - **X11:** Due to a bug in XFCE, this has no effect on Xfwm.
/// - **iOS / Android / Web:** Unsupported.
///
/// [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized
Expand Down Expand Up @@ -839,7 +838,7 @@ impl Window {
/// ## Platform-specific
///
/// - **macOS:** IME must be enabled to receive text-input where dead-key sequences are combined.
/// - ** iOS / Android / Web :** Unsupported.
/// - **iOS / Android / Web:** Unsupported.
///
/// [`Ime`]: crate::event::WindowEvent::Ime
/// [`KeyboardInput`]: crate::event::WindowEvent::KeyboardInput
Expand Down Expand Up @@ -873,7 +872,7 @@ impl Window {
///
/// ## Platform-specific
///
/// - **iOS / Android / Web :** Unsupported.
/// - **iOS / Android / Web:** Unsupported.
/// - **macOS:** `None` has no effect.
/// - **X11:** Requests for user attention must be manually cleared.
/// - **Wayland:** Requires `xdg_activation_v1` protocol, `None` has no effect.
Expand Down Expand Up @@ -1063,7 +1062,7 @@ pub enum CursorGrabMode {
/// ## Platform-specific
///
/// - **macOS:** Not implemented. Always returns [`ExternalError::NotSupported`] for now.
/// - ** iOS / Android / Web:** Always returns an [`ExternalError::NotSupported`].
/// - **iOS / Android / Web:** Always returns an [`ExternalError::NotSupported`].
Confined,

/// The cursor is locked inside the window area to the certain position.
Expand All @@ -1074,7 +1073,7 @@ pub enum CursorGrabMode {
/// ## Platform-specific
///
/// - **X11 / Windows:** Not implemented. Always returns [`ExternalError::NotSupported`] for now.
/// - ** iOS / Android:** Always returns an [`ExternalError::NotSupported`].
/// - **iOS / Android:** Always returns an [`ExternalError::NotSupported`].
Locked,
}

Expand Down Expand Up @@ -1167,10 +1166,12 @@ pub enum Theme {
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum UserAttentionType {
/// ## Platform-specific
///
/// - **macOS:** Bounces the dock icon until the application is in focus.
/// - **Windows:** Flashes both the window and the taskbar button until the application is in focus.
Critical,
/// ## Platform-specific
///
/// - **macOS:** Bounces the dock icon once.
/// - **Windows:** Flashes the taskbar button until the application is in focus.
Informational,
Expand Down