diff --git a/rust/src/bindings.rs b/rust/src/bindings.rs index 2fa1a28c1..c8f35bb21 100644 --- a/rust/src/bindings.rs +++ b/rust/src/bindings.rs @@ -168,9 +168,6 @@ pub use ffi::{ ncdirect_render_image, ncdirect_rounded_box, ncdirect_stop, - ncdirect_styles_off, - ncdirect_styles_on, - ncdirect_styles_set, ncdirect_vline_interp, }; @@ -720,3 +717,10 @@ pub use ffi::{ sigprocmask, sigsuspend, }; + +// fade callback --------------------------------------------------------------- +// +// already wrapped: +// +// // types +// fadecb diff --git a/rust/src/box.rs b/rust/src/box.rs index 32e181c91..fa36f56b6 100644 --- a/rust/src/box.rs +++ b/rust/src/box.rs @@ -5,7 +5,8 @@ /// NcBoxMax is defined in the least significant byte, where bits [3, 0] are /// are a border mask, and bits [7, 4] are a gradient mask. /// -/// The drawing of the corners is defined in the second byte. +/// The drawing of the corners is defined in the second byte, +/// see [`NCBOXCORNER_MASK`]. /// /// ## Diagram /// diff --git a/rust/src/channel/mod.rs b/rust/src/channel/mod.rs index 773b9e828..2c757a82e 100644 --- a/rust/src/channel/mod.rs +++ b/rust/src/channel/mod.rs @@ -226,9 +226,6 @@ pub type NcRgb = u32; /// pub type NcColor = u8; -/// Context for a palette fade operation -pub type NcFadeCtx = crate::bindings::ffi::ncfadectx; - /// the [NcEgc][crate::NcEgc] which form the various levels of a given geometry. /// /// If the geometry is wide, things are arranged with the rightmost side diff --git a/rust/src/fade.rs b/rust/src/fade.rs new file mode 100644 index 000000000..63dcf42ec --- /dev/null +++ b/rust/src/fade.rs @@ -0,0 +1,50 @@ +//! `NcFadeCb` & `NcFadeCtx` + +// functions already exported by bindgen : 3 +// ------------------------------------------- +// (#) test: 0 +// (W) wrap: 3 / 0 +// ------------------------------------------- +//W ncfadectx_free +//W ncfadectx_iterations +//W ncfadectx_setup + +use std::ffi::c_void; + +use crate::{NcPlane, NcResult, NcTime, Notcurses}; + +/// Called for each fade iteration on the NcPlane. +/// +/// If anything but 0 is returned, the fading operation ceases immediately, +/// and that value is propagated out. +/// +/// The recommended absolute display time target is passed in 'tspec'. +pub type NcFadeCb = Option< + unsafe extern "C" fn(*mut Notcurses, *mut NcPlane, *const NcTime, *mut c_void) -> NcResult, +>; + +/// Context for a palette fade operation +pub type NcFadeCtx = crate::bindings::ffi::ncfadectx; + +impl NcFadeCtx { + /// NcFadeCtx constructor. + /// + /// Rather than the simple ncplane_fade{in/out}(), + /// ncfadectx_setup() can be paired with a loop over + /// ncplane_fade{in/out}_iteration() + ncfadectx_free(). + pub fn setup<'a>(plane: &'a mut NcPlane) -> &'a mut NcFadeCtx { + unsafe { &mut *crate::ncfadectx_setup(plane) } + } + + /// Releases the resources associated. + pub fn free(&mut self) { + unsafe { + crate::ncfadectx_free(self); + } + } + + /// Returns the number of iterations through which will fade. + pub fn iterations(&self) -> u32 { + unsafe { crate::ncfadectx_iterations(self) as u32 } + } +} diff --git a/rust/src/lib.rs b/rust/src/lib.rs index 2517fcc6b..ede16eaa5 100644 --- a/rust/src/lib.rs +++ b/rust/src/lib.rs @@ -118,6 +118,7 @@ mod channel; mod dimension; mod direct; mod error; +mod fade; mod file; mod input; mod key; @@ -139,6 +140,7 @@ pub use channel::*; pub use dimension::*; pub use direct::*; pub use error::*; +pub use fade::*; pub use file::*; pub use key::*; pub use keycodes::*; diff --git a/rust/src/macros.rs b/rust/src/macros.rs index 63d27f0fa..c7f304c96 100644 --- a/rust/src/macros.rs +++ b/rust/src/macros.rs @@ -11,7 +11,7 @@ macro_rules! sleep { } /// Renders the [Notcurses][crate::Notcurses] object, then sleeps for $ms -/// milliseconds and returns the result of [notcurses_render]. +/// milliseconds and returns the result of [notcurses_render][crate::notcurses_render]. #[macro_export] macro_rules! rsleep { ($nc:expr, $ms:expr) => {{ diff --git a/rust/src/notcurses/mod.rs b/rust/src/notcurses/mod.rs index e56f836e7..ad510dbd8 100644 --- a/rust/src/notcurses/mod.rs +++ b/rust/src/notcurses/mod.rs @@ -182,14 +182,14 @@ pub const NCLOGLEVEL_WARNING: NcLogLevel = crate::bindings::ffi::ncloglevel_e_NC /// - [NCALIGN_RIGHT] pub type NcAlign = crate::bindings::ffi::ncalign_e; -/// Left alignment within an [`NcPlane`] or terminal. +/// Left alignment within an [`NcPlane`][crate::NcPlane] or terminal. pub const NCALIGN_LEFT: NcAlign = crate::bindings::ffi::ncalign_e_NCALIGN_LEFT; -/// Right alignment within an [`NcPlane`] or terminal. +/// Right alignment within an [`NcPlane`][crate::NcPlane] or terminal. pub const NCALIGN_RIGHT: NcAlign = crate::bindings::ffi::ncalign_e_NCALIGN_RIGHT; -/// Center alignment within an [`NcPlane`] or terminal. +/// Center alignment within an [`NcPlane`][crate::NcPlane] or terminal. pub const NCALIGN_CENTER: NcAlign = crate::bindings::ffi::ncalign_e_NCALIGN_CENTER; -/// Do not align an [`NcPlane`] or terminal. +/// Do not align an [`NcPlane`][crate::NcPlane] or terminal. pub const NCALIGN_UNALIGNED: NcAlign = crate::bindings::ffi::ncalign_e_NCALIGN_UNALIGNED; diff --git a/rust/src/notcurses/reimplemented.rs b/rust/src/notcurses/reimplemented.rs index 7d9cc538e..b80846b10 100644 --- a/rust/src/notcurses/reimplemented.rs +++ b/rust/src/notcurses/reimplemented.rs @@ -25,7 +25,8 @@ use crate::{ /// Returns the offset into 'availcols' at which 'cols' ought be output given /// the requirements of 'align'. /// -/// Returns -[`NCRESULT_MAX`] if [NCALIGN_UNALIGNED] or invalid [NcAlign]. +/// Returns -[`NCRESULT_MAX`] if [NCALIGN_UNALIGNED][crate::NCALIGN_UNALIGNED] +/// or invalid [NcAlign]. #[inline] pub fn notcurses_align(availcols: NcDimension, align: NcAlign, cols: NcDimension) -> NcOffset { if align == NCALIGN_LEFT { diff --git a/rust/src/plane/methods.rs b/rust/src/plane/methods.rs index 523e391ff..336c5f082 100644 --- a/rust/src/plane/methods.rs +++ b/rust/src/plane/methods.rs @@ -4,8 +4,9 @@ use core::ptr::{null, null_mut}; use std::ffi::CStr; use crate::{ - cstring, NcAlign, NcBoxMask, NcCell, NcChannelPair, NcDimension, NcEgc, NcOffset, NcPlane, - NcPlaneOptions, NcResult, NcStyleMask, Notcurses, + cstring, NcAlign, NcAlphaBits, NcBoxMask, NcCell, NcChannel, NcChannelPair, NcColor, + NcDimension, NcEgc, NcFadeCb, NcOffset, NcPlane, NcPlaneOptions, NcResult, NcRgb, NcStyleMask, + NcTime, Notcurses, }; /// # `NcPlaneOptions` Constructors @@ -65,7 +66,7 @@ impl NcPlaneOptions { } } -/// # `NcPlane` constructors and destructors +/// # NcPlane constructors and destructors impl NcPlane { /// New NcPlane. /// @@ -125,7 +126,8 @@ impl NcPlane { } } - /// Destroys the NcPlane. + /// Destroys this NcPlane. + /// /// None of its contents will be visible after the next render call. /// It is an error to attempt to destroy the standard plane. pub fn destroy(&mut self) -> NcResult { @@ -133,180 +135,197 @@ impl NcPlane { } } -/// # `NcPlane` Methods +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: NcAlphaBits impl NcPlane { - // Cursor ------------------------------------------------------------------ + /// Gets the foreground [NcAlphaBits] from this NcPlane, shifted to LSBs. + #[inline] + pub fn fg_alpha(&self) -> NcAlphaBits { + crate::channels_fg_alpha(unsafe { crate::ncplane_channels(self) }) + } - /// Returns the current position of the cursor within this NcPlane. - /// - // NOTE: y and/or x may be NULL. - // maybe check for null and return Some() or None? - pub fn cursor_yx(&self) -> (NcDimension, NcDimension) { - let (mut y, mut x) = (0, 0); - unsafe { crate::ncplane_cursor_yx(self, &mut y, &mut x) }; - (y as NcDimension, x as NcDimension) + /// Gets the background [NcAlphaBits] for this NcPlane, shifted to LSBs. + #[inline] + pub fn bg_alpha(&self) -> NcAlphaBits { + crate::channels_bg_alpha(unsafe { crate::ncplane_channels(self) }) } - /// Returns the current row of the cursor within this NcPlane. - pub fn cursor_y(&self) -> NcDimension { - self.cursor_yx().0 + /// Sets the foreground [NcAlphaBits] from this NcPlane. + pub fn set_fg_alpha(&mut self, alpha: NcAlphaBits) -> NcResult { + unsafe { crate::ncplane_set_fg_alpha(self, alpha as i32) } } - /// Returns the current column of the cursor within this NcPlane. - pub fn cursor_x(&self) -> NcDimension { - self.cursor_yx().1 + /// Sets the background [NcAlphaBits] for this NcPlane. + pub fn set_bg_alpha(&mut self, alpha: NcAlphaBits) -> NcResult { + unsafe { crate::ncplane_set_bg_alpha(self, alpha as i32) } } +} - /// Moves the cursor to the specified position within the NcPlane. - /// - /// The cursor doesn't need to be visible. - /// - /// Parameters exceeding the plane's dimensions will result in an error, - /// and the cursor position will remain unchanged. - pub fn cursor_move_yx(&mut self, y: NcDimension, x: NcDimension) -> NcResult { - unsafe { crate::ncplane_cursor_move_yx(self, y as i32, x as i32) } +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: NcChannel +impl NcPlane { + /// Gets the current [NcChannelPair] from this NcPlane. + pub fn channels(&self) -> NcChannelPair { + unsafe { crate::ncplane_channels(self) } } - /// Moves the cursor the number of rows specified (forward or backwards). - /// - /// It will error if the target row exceeds the plane dimensions. - pub fn cursor_move_rows(&mut self, rows: NcOffset) -> NcResult { - let (y, x) = self.cursor_yx(); - self.cursor_move_yx((y as NcOffset + rows) as NcDimension, x) + /// Gets the foreground [NcChannel] from an [NcPlane]. + #[inline] + pub fn fchannel(&self) -> NcChannel { + crate::channels_fchannel(unsafe { crate::ncplane_channels(self) }) } - /// Moves the cursor the number of columns specified (forward or backwards). - /// - /// It will error if the target column exceeds the plane dimensions. - // TODO: maybe in this case it can improve - pub fn cursor_move_cols(&mut self, cols: NcOffset) -> NcResult { - let (y, x) = self.cursor_yx(); - self.cursor_move_yx(y, (x as NcOffset + cols) as NcDimension) + /// Gets the background [NcChannel] from an [NcPlane]. + #[inline] + pub fn bchannel(&self) -> NcChannel { + crate::channels_bchannel(unsafe { crate::ncplane_channels(self) }) } - /// Moves the cursor to 0, 0. - pub fn cursor_home(&mut self) { - unsafe { - crate::ncplane_home(self); - } + /// Sets the current [NcChannelPair] for this NcPlane. + pub fn set_channels(&mut self, channels: NcChannelPair) { + unsafe { crate::ncplane_set_channels(self, channels) } } - // Size & alignment -------------------------------------------------------- + /// Sets the current foreground [NcChannel] for this NcPlane. + /// Returns the updated [NcChannelPair]. + pub fn set_fchannel(&mut self, channel: NcChannel) -> NcChannelPair { + unsafe { crate::ncplane_set_fchannel(self, channel) } + } - /// Returns the column at which `cols` columns ought start in order to be - /// aligned according to `align` within this NcPlane. - /// Returns INT_MAX on invalid `align`. - pub fn align(&mut self, align: NcAlign, cols: NcDimension) -> NcResult { - crate::ncplane_align(self, align, cols) + /// Sets the current background [NcChannel] for this NcPlane. + /// Returns the updated [NcChannelPair]. + pub fn set_bchannel(&mut self, channel: NcChannel) -> NcChannelPair { + unsafe { crate::ncplane_set_bchannel(self, channel) } + } +} + +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: NcColor +impl NcPlane { + /// Gets the foreground [NcColor] RGB components from this NcPlane, + /// and returns the foreground [NcChannel]. + #[inline] + pub fn fg_rgb8(&self, red: &mut NcColor, green: &mut NcColor, blue: &mut NcColor) -> NcChannel { + crate::channels_fg_rgb8(unsafe { crate::ncplane_channels(self) }, red, green, blue) } - /// Return the dimensions of this NcPlane. + /// Gets the background [NcColor] RGB components from this NcPlane, + /// and returns the background [NcChannel]. + #[inline] + pub fn bg_rgb8(&self, red: &mut NcColor, green: &mut NcColor, blue: &mut NcColor) -> NcChannel { + crate::channels_bg_rgb8(unsafe { crate::ncplane_channels(self) }, red, green, blue) + } + + /// Sets the foreground [NcColor] RGB components for this NcPlane. /// - /// Unlike [ncplane_dim_yx][crate::ncplane_dim_yx] which uses `i32`, - /// this uses [u32]. - pub fn dim_yx(&self) -> (NcDimension, NcDimension) { - let (mut y, mut x) = (0, 0); - unsafe { crate::ncplane_dim_yx(self, &mut y, &mut x) }; - (y as NcDimension, x as NcDimension) + /// If the terminal does not support directly-specified 3x8b cells + /// (24-bit "TrueColor", indicated by the "RGB" terminfo capability), + /// the provided values will be interpreted in some lossy fashion. + /// + /// "HP-like" terminals require setting foreground and background at the same + /// time using "color pairs"; Notcurses will manage color pairs transparently. + pub fn set_fg_rgb8(&mut self, red: NcColor, green: NcColor, blue: NcColor) { + unsafe { + // Can't fail because of type enforcing. + let _ = crate::ncplane_set_fg_rgb8(self, red as i32, green as i32, blue as i32); + } } - /// Return the rows of this NcPlane. - pub fn dim_y(&self) -> NcDimension { - self.dim_yx().0 + /// Sets the background [NcColor] RGB components for this NcPlane. + /// + /// If the terminal does not support directly-specified 3x8b cells + /// (24-bit "TrueColor", indicated by the "RGB" terminfo capability), + /// the provided values will be interpreted in some lossy fashion. + /// + /// "HP-like" terminals require setting foreground and background at the same + /// time using "color pairs"; Notcurses will manage color pairs transparently. + pub fn set_bg_rgb8(&mut self, red: NcColor, green: NcColor, blue: NcColor) { + unsafe { + // Can't fail because of type enforcing. + let _ = crate::ncplane_set_bg_rgb8(self, red as i32, green as i32, blue as i32); + } } +} - /// Return the columns of this NcPlane. - pub fn dim_x(&self) -> NcDimension { - self.dim_yx().1 +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: NcRgb +impl NcPlane { + /// Gets the foreground [NcRgb] from this NcPlane, shifted to LSBs. + #[inline] + pub fn fg_rgb(&self) -> NcRgb { + crate::channels_fg_rgb(unsafe { crate::ncplane_channels(self) }) } - /// Return the rows of this NcPlane. - pub fn rows(&self) -> NcDimension { - self.dim_yx().0 + /// Gets the background [NcRgb] from this NcPlane, shifted to LSBs. + #[inline] + pub fn bg_rgb(&self) -> NcRgb { + crate::channels_bg_rgb(unsafe { crate::ncplane_channels(self) }) } - /// Return the cols of this NcPlane. - pub fn cols(&self) -> NcDimension { - self.dim_yx().1 + // default + + /// Is this NcPlane's foreground using the "default foreground color"? + #[inline] + pub fn fg_default_p(&self) -> bool { + crate::channels_fg_default_p(unsafe { crate::ncplane_channels(self) }) } - /// Sets the scrolling behaviour of the plane, and - /// returns true if scrolling was previously enabled, of false, if disabled. - /// - /// All planes are created with scrolling disabled. Attempting to print past - /// the end of a line will stop at the plane boundary, and indicate an error. - /// - /// On a plane 10 columns wide and two rows high, printing "0123456789" - /// at the origin should succeed, but printing "01234567890" will by default - /// fail at the eleventh character. In either case, the cursor will be left - /// at location 0x10; it must be moved before further printing can take place. I - pub fn set_scrolling(&mut self, scroll: bool) -> bool { - unsafe { crate::ncplane_set_scrolling(self, scroll) } + /// Is this NcPlane's background using the "default background color"? + #[inline] + pub fn bg_default_p(&self) -> bool { + crate::channels_bg_default_p(unsafe { crate::ncplane_channels(self) }) } +} - /// Resizes the NcPlane. - /// - /// The four parameters `keep_y`, `keep_x`, `keep_len_y`, and `keep_len_x` - /// defines a subset of the NcPlane to keep unchanged. This may be a section - /// of size 0. - /// - /// `keep_x` and `keep_y` are relative to the NcPlane. They must specify a - /// coordinate within the ncplane's totality. If either of `keep_len_y` or - /// `keep_len_x` is non-zero, both must be non-zero. - /// - /// `y_off` and `x_off` are relative to `keep_y` and `keep_x`, and place the - /// upper-left corner of the resized NcPlane. - /// - /// `y_len` and `x_len` are the dimensions of the NcPlane after resizing. - /// `y_len` must be greater than or equal to `keep_len_y`, - /// and `x_len` must be greater than or equal to `keeplenx`. +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: NcStyleMask +impl NcPlane { + /// Sets the given style throughout the specified region, keeping content + /// and channels unchanged. /// - /// It is an error to attempt to resize the standard plane. - pub fn resize( + /// Returns the number of cells set, or [NCRESULT_ERR][crate::NCRESULT_ERR] + /// on failure. + pub fn format( &mut self, - keep_y: NcDimension, - keep_x: NcDimension, - keep_len_y: NcDimension, - keep_len_x: NcDimension, - y_off: NcOffset, - x_off: NcOffset, - y_len: NcDimension, - x_len: NcDimension, + y_stop: NcDimension, + x_stop: NcDimension, + stylemask: NcStyleMask, ) -> NcResult { + unsafe { crate::ncplane_format(self, y_stop as i32, x_stop as i32, stylemask as u32) } + } + + /// Returns the current styling for this NcPlane. + pub fn styles(&self) -> NcStyleMask { unsafe { - crate::ncplane_resize( - self, - keep_y as i32, - keep_x as i32, - keep_len_y as i32, - keep_len_x as i32, - y_off as i32, - x_off as i32, - y_len as i32, - x_len as i32, - ) + crate::ncplane_styles(self) } } - /// Realigns this NcPlane against its parent, using the alignment specified - /// at creation time. Suitable for use as a `resizecb`. - pub fn resize_realign(&mut self) -> NcResult { - unsafe { crate::ncplane_resize_realign(self) } + /// Removes the specified styles from this NcPlane's existing spec. + pub fn off_styles(&mut self, stylemask: NcStyleMask) { + unsafe { + crate::ncplane_off_styles(self, stylemask as u32); + } } - /// Resizes the NcPlane, retaining what data we can (everything, unless we're - /// shrinking in some dimension). Keeps the origin where it is. - pub fn resize_simple(&mut self, y_len: NcDimension, x_len: NcDimension) -> NcResult { - crate::ncplane_resize_simple(self, y_len as u32, x_len as u32) + /// Adds the specified styles to this NcPlane's existing spec. + pub fn on_styles(&mut self, stylemask: NcStyleMask) { + unsafe { + crate::ncplane_on_styles(self, stylemask as u32); + } } - /// Returns the NcPlane's current resize callback. - pub fn resizecb(&self) -> Option NcResult> { - unsafe { crate::ncplane_resizecb(self) } + /// Adds the specified styles to this NcPlane's existing spec. + pub fn set_styles(&mut self, stylemask: NcStyleMask) { + unsafe { + crate::ncplane_set_styles(self, stylemask as u32); + } } +} - // Read ------------------------------------------------------------------- - +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: NcCell +impl NcPlane { /// Retrieves the current contents of the [NcCell] under the cursor, /// returning the [NcEgc] and writing out the [NcStyleMask] and the [NcChannelPair]. /// @@ -327,6 +346,7 @@ impl NcPlane { /// Retrieves the current contents of the [NcCell] under the cursor. /// /// This NcCell is invalidated if the associated NcPlane is destroyed. + #[inline] pub fn at_cursor_cell(&mut self, cell: &mut NcCell) -> NcResult { crate::ncplane_at_cursor_cell(self, cell) } @@ -337,12 +357,12 @@ impl NcPlane { /// This NcEgc must be freed by the caller. pub fn at_yx( &mut self, - y: i32, - x: i32, + y: NcDimension, + x: NcDimension, stylemask: &mut NcStyleMask, channels: &mut NcChannelPair, ) -> Option { - let egc = unsafe { crate::ncplane_at_yx(self, y, x, stylemask, channels) }; + let egc = unsafe { crate::ncplane_at_yx(self, y as i32, x as i32, stylemask, channels) }; if egc.is_null() { return None; } @@ -350,26 +370,33 @@ impl NcPlane { Some(egc) } + /// Retrieves the current contents of the specified [NcCell] into `cell`. + /// This cell is invalidated if the associated plane is destroyed. + #[inline] + pub fn ncplane_at_yx_cell( + &mut self, + y: NcDimension, + x: NcDimension, + cell: &mut NcCell, + ) -> NcResult { + crate::ncplane_at_yx_cell(self, y, x, cell) + } + /// Extracts this NcPlane's base [NcCell] into `cell`. /// - /// The reference is invalidated if the NcPlane is destroyed. + /// The reference is invalidated if this NcPlane is destroyed. pub fn base(&mut self, cell: &mut NcCell) -> NcResult { unsafe { crate::ncplane_base(self, cell) } } - /// Gets the current ChannelPair for this NcPlane. - pub fn channels(&self) -> NcChannelPair { - unsafe { crate::ncplane_channels(self) } - } - /// Creates a flat string from the NcEgc's of the selected region of the /// NcPlane. /// /// Starts at the plane's `beg_y` * `beg_x` coordinates (which must lie on /// the plane), continuing for `len_y` x `len_x` cells. /// - /// If either of `through_y` or `through_x` are true, then `len_y` or `len_x`, - /// will ignored respectively, and will go through the boundary of the plane. + /// If either `through_y` or `through_x` are true, then `len_y` or `len_x`, + /// will be respectively ignored, and will go through the boundary of the plane. pub fn contents( &self, beg_y: NcDimension, @@ -398,10 +425,12 @@ impl NcPlane { .into_owned() } } +} - // Write ------------------------------------------------------------------- - - /// Erases every NcCell in the NcPlane, resetting all attributes to normal, +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: writing +impl NcPlane { + /// Erases every NcCell in this NcPlane, resetting all attributes to normal, /// all colors to the default color, and all cells to undrawn. /// /// All cells associated with this NcPlane are invalidated, and must not be @@ -455,6 +484,7 @@ impl NcPlane { /// /// On error, a non-positive number is returned, indicating the number of /// columns which were written before the error. + #[inline] pub fn putstr(&mut self, string: &str) -> NcResult { crate::ncplane_putstr(self, string) } @@ -479,14 +509,22 @@ impl NcPlane { pub fn putstr_yx(&mut self, y: NcDimension, x: NcDimension, string: &str) -> NcResult { unsafe { crate::ncplane_putstr_yx(self, y as i32, x as i32, cstring![string]) } } +} - // Pile -------------------------------------------------------------------- - - // CHECK: - - /// Returns the bottommost NcPlane of the current pile. - pub fn bottom<'a>(&mut self) -> &'a mut NcPlane { - unsafe { &mut *crate::ncpile_bottom(self) } +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: NcPlane, pile & Notcurses context +impl NcPlane { + /// Duplicates this NcPlane. + /// + /// The new NcPlane will have the same geometry, the same rendering state, + /// and all the same duplicated content. + /// + /// The new plane will be immediately above the old one on the z axis, + /// and will be bound to the same parent. Bound planes are not duplicated; + /// the new plane is bound to the current parent, but has no bound planes. + // TODO: deal with the opaque field. + pub fn dup<'a>(&'a mut self) -> &'a mut NcPlane { + unsafe { &mut *crate::ncplane_dup(self, null_mut()) } } /// Returns the topmost NcPlane of the current pile. @@ -494,40 +532,25 @@ impl NcPlane { unsafe { &mut *crate::ncpile_top(self) } } - /// Makes the physical screen match the last rendered frame from the pile of - /// which this NcPlane is a part. - /// - /// This is a blocking call. Don't call this before the pile has been - /// rendered (doing so will likely result in a blank screen). - pub fn rasterize<'a>(&mut self) -> NcResult { - unsafe { crate::ncpile_rasterize(self) } + /// Returns the bottommost NcPlane of the current pile. + pub fn bottom<'a>(&mut self) -> &'a mut NcPlane { + unsafe { &mut *crate::ncpile_bottom(self) } } - /// Renders the pile of which this NcPlane is a part. - /// Rendering this pile again will blow away the render. - /// To actually write out the render, call ncpile_rasterize(). - pub fn render<'a>(&mut self) -> NcResult { - unsafe { crate::ncpile_render(self) } + /// Relocates this NcPlane at the top of the z-buffer. + pub fn move_top(&mut self) { + unsafe { + crate::ncplane_move_top(self); + } } - // Plane ------------------------------------------------------------------- - - // move_above - // move_below - // move_bottom - // move_top - - /// Duplicates this NcPlane. - /// The new plane will have the same geometry, will duplicate all content, - /// and will start with the same rendering state. - /// - /// The new plane will be immediately above the old one on the z axis, - /// and will be bound to the same parent. Bound planes are not duplicated; - /// the new plane is bound to the current parent, but has no bound planes. - // TODO: deal with the opaque field, currently giving a null_mut pointer. - pub fn dup<'a>(&'a mut self) -> &'a mut NcPlane { - unsafe { &mut *crate::ncplane_dup(self, null_mut()) } + /// Relocates this NcPlane at the bottom of the z-buffer. + pub fn move_bottom(&mut self) { + unsafe { + crate::ncplane_move_bottom(self); + } } + /// Moves this NcPlane relative to the standard plane, or the plane to /// which it is bound. /// @@ -555,7 +578,96 @@ impl NcPlane { Some(unsafe { &mut *plane }) } + /// Relocates this NcPlane above the `above` NcPlane, in the z-buffer. + /// + /// Returns [`NCRESULT_ERR`][crate::NCRESULT_ERR] if the current plane is + /// already in the desired location. Both planes must not be the same. + pub fn move_above(&mut self, above: &mut NcPlane) -> NcResult { + unsafe { crate::ncplane_move_above(self, above) } + } + + /// Relocates this NcPlane below the `below` NcPlane, in the z-buffer. + /// + /// Returns [`NCRESULT_ERR`][crate::NCRESULT_ERR] if the current plane is + /// already in the desired location. Both planes must not be the same. + pub fn move_below(&mut self, below: &mut NcPlane) -> NcResult { + unsafe { crate::ncplane_move_below(self, below) } + } + + /// Merges `source` down onto this NcPlane. + /// + /// Merging is independent of the position of both NcPlanes on the z-axis. + /// + /// It is an error to define a subregion of zero area, or that is not + /// entirely contained within `source`. + /// + /// It is an error to define a target origin such that the projected + /// subregion is not entirely contained within 'dst'. + /// + /// Behavior is undefined if both NcPlanes are equivalent. + pub fn mergedown( + &mut self, + source: &NcPlane, + source_y: NcDimension, + source_x: NcDimension, + len_y: NcDimension, + len_x: NcDimension, + target_y: NcDimension, + target_x: NcDimension, + ) -> NcResult { + unsafe { + crate::ncplane_mergedown( + source, + self, + source_y as i32, + source_x as i32, + len_y as i32, + len_x as i32, + target_y as i32, + target_x as i32, + ) + } + } + + /// Merges `source` down onto this NcPlane. + /// + /// If `source` does not intersect, this plane will not be changed, + /// but it is not an error. + /// + /// See [`mergedown`](type.NcPlane.html#method.mergedown) + /// for more information. + // + // TODO: maybe create a reversed method, and/or an associated function, + // for `mergedown` too. + pub fn mergedown_simple(&mut self, source: &NcPlane) -> NcResult { + unsafe { crate::ncplane_mergedown_simple(source, self) } + } + + /// Rotate the plane π/2 radians clockwise. + /// + /// This cannot be performed on arbitrary planes, because glyphs cannot be + /// arbitrarily rotated. + /// + /// The glyphs which can be rotated are limited: line-drawing characters, + /// spaces, half blocks, and full blocks. + /// + /// The plane must have an even number of columns. + /// + /// Use the ncvisual rotation for a more flexible approach. + pub fn rotate_cw(&mut self) -> NcResult { + unsafe { crate::ncplane_rotate_cw(self) } + } + + /// Rotate the plane π/2 radians counter-clockwise. + /// + /// See [`routate_cw`](type.NcPlane.html#method.rotate_cw) + /// for more information. + pub fn rotate_ccw(&mut self) -> NcResult { + unsafe { crate::ncplane_rotate_ccw(self) } + } + /// Gets the parent to which this NcPlane is bound, if any. + // // TODO: CHECK: what happens when it's bound to itself. // pub fn parent<'a>(&'a mut self) -> Option<&'a mut NcPlane> { pub fn parent<'a>(&'a mut self) -> &'a mut NcPlane { @@ -563,13 +675,52 @@ impl NcPlane { } /// Gets the parent to which this NcPlane is bound, if any. + // // TODO: CHECK: what happens when it's bound to itself. // pub fn parent<'a>(&'a mut self) -> Option<&'a mut NcPlane> { pub fn parent_const<'a>(&'a self) -> &'a NcPlane { unsafe { &*crate::ncplane_parent_const(self) } } - // Context ----------------------------------------------------------------- + /// Unbounds this NcPlane from its parent, makes it a bound child of + /// 'newparent', and returns itself. + /// + /// Any planes bound to this NcPlane are reparented to the previous parent. + /// + /// If this NcPlane is equal to `newparent`, then becomes the root of a new + /// pile, unless it is already the root of a pile, in which case this is a + /// no-op. + /// + /// The standard plane cannot be reparented. + pub fn reparent<'a>(&'a mut self, newparent: &'a mut NcPlane) -> &'a mut NcPlane { + unsafe { &mut *crate::ncplane_reparent(self, newparent) } + } + + /// Like [`reparent`](type.NcPlane.html#method.reparent), except any bound + /// planes comes along with this NcPlane to its new destination. + /// + /// Their z-order is maintained. + /// + // TODO:CHECK: If 'newparent' is an ancestor, NULL is returned & no changes're made. + pub fn reparent_family<'a>(&'a mut self, newparent: &'a mut NcPlane) -> &'a mut NcPlane { + unsafe { &mut *crate::ncplane_reparent_family(self, newparent) } + } + + /// Makes the physical screen match the last rendered frame from the pile of + /// which this NcPlane is a part. + /// + /// This is a blocking call. Don't call this before the pile has been + /// rendered (doing so will likely result in a blank screen). + pub fn rasterize<'a>(&mut self) -> NcResult { + unsafe { crate::ncpile_rasterize(self) } + } + + /// Renders the pile of which this NcPlane is a part. + /// Rendering this pile again will blow away the render. + /// To actually write out the render, call ncpile_rasterize(). + pub fn render<'a>(&mut self) -> NcResult { + unsafe { crate::ncpile_render(self) } + } /// Gets a mutable reference to the [Notcurses] context of this NcPlane. pub fn notcurses<'a>(&mut self) -> &'a mut Notcurses { @@ -580,9 +731,223 @@ impl NcPlane { pub fn notcurses_const<'a>(&mut self) -> &'a Notcurses { unsafe { &*crate::ncplane_notcurses_const(self) } } +} - // Box, perimeter----------------------------------------------------------- +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: cursor +impl NcPlane { + /// Returns the current position of the cursor within this NcPlane. + /// + // NOTE: y and/or x may be NULL. + // maybe check for null and return Some() or None? + pub fn cursor_yx(&self) -> (NcDimension, NcDimension) { + let (mut y, mut x) = (0, 0); + unsafe { crate::ncplane_cursor_yx(self, &mut y, &mut x) }; + (y as NcDimension, x as NcDimension) + } + + /// Returns the current row of the cursor within this NcPlane. + pub fn cursor_y(&self) -> NcDimension { + self.cursor_yx().0 + } + + /// Returns the current column of the cursor within this NcPlane. + pub fn cursor_x(&self) -> NcDimension { + self.cursor_yx().1 + } + /// Moves the cursor to the specified position within this NcPlane. + /// + /// The cursor doesn't need to be visible. + /// + /// Parameters exceeding the plane's dimensions will result in an error, + /// and the cursor position will remain unchanged. + pub fn cursor_move_yx(&mut self, y: NcDimension, x: NcDimension) -> NcResult { + unsafe { crate::ncplane_cursor_move_yx(self, y as i32, x as i32) } + } + + /// Moves the cursor the number of rows specified (forward or backwards). + /// + /// It will error if the target row exceeds the plane dimensions. + pub fn cursor_move_rows(&mut self, rows: NcOffset) -> NcResult { + let (y, x) = self.cursor_yx(); + self.cursor_move_yx((y as NcOffset + rows) as NcDimension, x) + } + + /// Moves the cursor the number of columns specified (forward or backwards). + /// + /// It will error if the target column exceeds the plane dimensions. + // TODO: maybe in this case it can improve + pub fn cursor_move_cols(&mut self, cols: NcOffset) -> NcResult { + let (y, x) = self.cursor_yx(); + self.cursor_move_yx(y, (x as NcOffset + cols) as NcDimension) + } + + /// Moves the cursor to 0, 0. + pub fn cursor_home(&mut self) { + unsafe { + crate::ncplane_home(self); + } + } +} + +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: size, position & alignment +impl NcPlane { + /// Returns the column at which `cols` columns ought start in order to be + /// aligned according to `align` within this NcPlane. + /// + /// Returns -[`NCRESULT_MAX`][crate::NCRESULT_MAX] if + /// [`NCALIGN_UNALIGNED`][crate::NCALIGN_UNALIGNED] or invalid [NcAlign]. + #[inline] + pub fn align(&mut self, align: NcAlign, cols: NcDimension) -> NcResult { + crate::ncplane_align(self, align, cols) + } + + /// + // TODO: doc. + pub fn center_abs(&self, y: &mut NcDimension, x: &mut NcDimension) { + unsafe { + crate::ncplane_center_abs(self, &mut (*y as i32), &mut (*x as i32)); + } + } + + /// Returns the dimensions of this NcPlane. + pub fn dim_yx(&self) -> (NcDimension, NcDimension) { + let (mut y, mut x) = (0, 0); + unsafe { crate::ncplane_dim_yx(self, &mut y, &mut x) }; + (y as NcDimension, x as NcDimension) + } + + /// Return the rows of this NcPlane. + #[inline] + pub fn dim_y(&self) -> NcDimension { + self.dim_yx().0 + } + + /// Return the columns of this NcPlane. + #[inline] + pub fn dim_x(&self) -> NcDimension { + self.dim_yx().1 + } + + /// Return the rows of this NcPlane. + /// + /// Alias of [dim_y](type.NcPlane.html#method.dim_y) + #[inline] + pub fn rows(&self) -> NcDimension { + self.dim_yx().0 + } + + /// Return the cols of this NcPlane. + /// + /// Alias of [dim_x](type.NcPlane.html#method.dim_x) + #[inline] + pub fn cols(&self) -> NcDimension { + self.dim_yx().1 + } + + /// Sets the scrolling behaviour of the plane, and + /// returns true if scrolling was previously enabled, of false, if disabled. + /// + /// All planes are created with scrolling disabled. Attempting to print past + /// the end of a line will stop at the plane boundary, and indicate an error. + /// + /// On a plane 10 columns wide and two rows high, printing "0123456789" + /// at the origin should succeed, but printing "01234567890" will by default + /// fail at the eleventh character. In either case, the cursor will be left + /// at location 0x10; it must be moved before further printing can take place. I + pub fn set_scrolling(&mut self, scroll: bool) -> bool { + unsafe { crate::ncplane_set_scrolling(self, scroll) } + } + + /// Resizes this NcPlane. + /// + /// The four parameters `keep_y`, `keep_x`, `keep_len_y`, and `keep_len_x` + /// defines a subset of this NcPlane to keep unchanged. This may be a section + /// of size 0. + /// + /// `keep_x` and `keep_y` are relative to this NcPlane. They must specify a + /// coordinate within the ncplane's totality. If either of `keep_len_y` or + /// `keep_len_x` is non-zero, both must be non-zero. + /// + /// `y_off` and `x_off` are relative to `keep_y` and `keep_x`, and place the + /// upper-left corner of the resized NcPlane. + /// + /// `y_len` and `x_len` are the dimensions of this NcPlane after resizing. + /// `y_len` must be greater than or equal to `keep_len_y`, + /// and `x_len` must be greater than or equal to `keeplenx`. + /// + /// It is an error to attempt to resize the standard plane. + pub fn resize( + &mut self, + keep_y: NcDimension, + keep_x: NcDimension, + keep_len_y: NcDimension, + keep_len_x: NcDimension, + y_off: NcOffset, + x_off: NcOffset, + y_len: NcDimension, + x_len: NcDimension, + ) -> NcResult { + unsafe { + crate::ncplane_resize( + self, + keep_y as i32, + keep_x as i32, + keep_len_y as i32, + keep_len_x as i32, + y_off as i32, + x_off as i32, + y_len as i32, + x_len as i32, + ) + } + } + + /// Realigns this NcPlane against its parent, using the alignment specified + /// at creation time. Suitable for use as a `resizecb`. + pub fn resize_realign(&mut self) -> NcResult { + unsafe { crate::ncplane_resize_realign(self) } + } + + /// Resizes this NcPlane, retaining what data we can (everything, unless we're + /// shrinking in some dimension). Keeps the origin where it is. + #[inline] + pub fn resize_simple(&mut self, y_len: NcDimension, x_len: NcDimension) -> NcResult { + crate::ncplane_resize_simple(self, y_len as u32, x_len as u32) + } + + /// Returns this NcPlane's current resize callback. + pub fn resizecb(&self) -> Option NcResult> { + unsafe { crate::ncplane_resizecb(self) } + } + + /// Gets the `y, x` origin of this NcPlane relative to the standard plane, + /// or the NcPlane to which it is bound. + // CHECK: negative offsets + pub fn yx(&self) -> (NcOffset, NcOffset) { + let (mut y, mut x) = (0, 0); + unsafe { crate::ncplane_yx(self, &mut y, &mut x) }; + (y as NcOffset, x as NcOffset) + } + + /// Gets the `x` origin of this NcPlane relative to the standard plane, + /// or the NcPlane to which it is bound. + pub fn x(&self) -> NcOffset { + unsafe { crate::ncplane_x(self) as NcOffset } + } + + /// Gets the `y` origin of this NcPlane relative to the standard plane, + /// or the NcPlane to which it is bound. + pub fn y(&self) -> NcOffset { + unsafe { crate::ncplane_y(self) as NcOffset } + } +} + +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: boxes & perimeters +impl NcPlane { /// Draws a box with its upper-left corner at the current cursor position, /// and its lower-right corner at `y_stop` * `x_stop`. /// @@ -630,6 +995,7 @@ impl NcPlane { /// The minimum box size is 2x2, and it cannot be drawn off-screen. /// /// See the [`box`](type.NcPlane.html#method.box) method for more information. + #[inline] pub fn box_sized( &mut self, ul: &NcCell, @@ -646,6 +1012,7 @@ impl NcPlane { } /// Draws the perimeter around this NcPlane. + #[inline] pub fn perimeter( &mut self, ul: &NcCell, @@ -660,6 +1027,7 @@ impl NcPlane { } /// + #[inline] pub fn perimeter_double( &mut self, stylemask: NcStyleMask, @@ -670,6 +1038,7 @@ impl NcPlane { } /// + #[inline] pub fn perimeter_rounded( &mut self, stylemask: NcStyleMask, @@ -679,3 +1048,62 @@ impl NcPlane { crate::ncplane_perimeter_rounded(self, stylemask, channels, boxmask) } } + +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: fading, gradients & greyscale +impl NcPlane { + /// Fades this NcPlane in, over the specified time, calling 'fader' at + /// each iteration. + /// + /// Usage: + /// 1. Load this NcPlane with the target cells without rendering. + /// 2. call this function. + /// + /// When it's done, the NcPlane will have reached the target levels, + /// starting from zeroes. + pub fn fadein(&mut self, time: &NcTime, fader: NcFadeCb) -> NcResult { + unsafe { crate::ncplane_fadein(self, time, fader, null_mut()) } + } + + /// Fades in through 'iter' iterations, + /// where 'iter' < 'ncfadectx_iterations(nctx)'. + pub fn fadein_iteration(&mut self, time: &NcTime, fader: NcFadeCb) -> NcResult { + unsafe { crate::ncplane_fadein(self, time, fader, null_mut()) } + } + + /// Fades this NcPlane out, over the specified time, calling 'fader' at + /// each iteration. + /// + /// Requires a terminal which supports truecolor, or at least palette + /// modification (if the terminal uses a palette, our ability to fade planes + /// is limited, and affected by the complexity of the rest of the screen). + pub fn fadeout(&mut self, time: &NcTime, fader: NcFadeCb) -> NcResult { + unsafe { crate::ncplane_fadeout(self, time, fader, null_mut()) } + } + + /// Fades out through 'iter' iterations, + /// where 'iter' < 'ncfadectx_iterations(nctx)'. + pub fn fadeout_iteration(&mut self, time: &NcTime, fader: NcFadeCb) -> NcResult { + unsafe { crate::ncplane_fadeout(self, time, fader, null_mut()) } + } + + /// Pulses this NcPlane in and out until the callback returns non-zero, + /// relying on the callback 'fader' to initiate rendering. + /// + /// `time` defines the half-period (i.e. the transition from black to full + /// brightness, or back again). + /// + /// Proper use involves preparing (but not rendering) the NcPlane, + /// then calling this method, which will fade in from black to the + /// specified colors. + pub fn pulse(&mut self, time: &NcTime, fader: NcFadeCb) -> NcResult { + unsafe { crate::ncplane_pulse(self, time, fader, null_mut()) } + } + + /// Converts this NcPlane's content to greyscale. + pub fn greyscale(&mut self) { + unsafe { + crate::ncplane_greyscale(self); + } + } +} diff --git a/rust/src/plane/mod.rs b/rust/src/plane/mod.rs index 5ed37b0ba..a775701c3 100644 --- a/rust/src/plane/mod.rs +++ b/rust/src/plane/mod.rs @@ -1,10 +1,10 @@ //! `NcPlane` -// functions already exported by bindgen : 105 +// functions already exported by bindgen : 102 // ------------------------------------------- // (X) wont: 4 // (#) test: 13 -// (W) wrap: 32 +// (W) wrap: 63 // ------------------------------------------- //W ncpile_bottom //W# ncpile_create @@ -17,7 +17,7 @@ //W ncplane_base //W ncplane_below //W ncplane_box -// ncplane_center_abs +//W ncplane_center_abs //W# ncplane_channels //W ncplane_contents //W ncplane_create @@ -27,33 +27,32 @@ //W# ncplane_dim_yx //W ncplane_dup //W# ncplane_erase -// ncplane_fadein -// ncplane_fadein_iteration -// ncplane_fadeout -// ncplane_fadeout_iteration -// ncplane_format +//W ncplane_fadein +//W ncplane_fadein_iteration +//W ncplane_fadeout +//W ncplane_fadeout_iteration +//W ncplane_format // ncplane_gradient -// ncplane_greyscale +//W ncplane_greyscale // ncplane_highgradient // ncplane_highgradient_sized // ncplane_hline_interp //W# ncplane_home -// ncplane_mergedown -// ncplane_mergedown_simple -// ncplane_move_above -// ncplane_move_below -// ncplane_move_bottom -// ncplane_move_top +//W ncplane_mergedown +//W ncplane_mergedown_simple +//W ncplane_move_above +//W ncplane_move_below +//W ncplane_move_bottom +//W ncplane_move_top //W ncplane_move_yx -// ncplane_new //W# ncplane_notcurses //W# ncplane_notcurses_const -// ncplane_off_styles -// ncplane_on_styles +//W ncplane_off_styles +//W ncplane_on_styles //W ncplane_parent //W ncplane_parent_const // ncplane_polyfill_yx -// ncplane_pulse +//W ncplane_pulse // ncplane_putchar_stained // ncplane_putc_yx // X ncplane_putegc_stained @@ -67,40 +66,37 @@ // X ncplane_putwegc_stained // X ncplane_putwstr_stained // ncplane_qrcode -// ncplane_reparent -// ncplane_reparent_family +//W ncplane_reparent +//W ncplane_reparent_family //W# ncplane_resize //W ncplane_resizecb //W ncplane_resize_realign // ncplane_rgba -// ncplane_rotate_ccw -// ncplane_rotate_cw +//W ncplane_rotate_ccw +//W ncplane_rotate_cw // ncplane_set_base // ncplane_set_base_cell -// # ncplane_set_bchannel -// ncplane_set_bg_alpha +//W# ncplane_set_bchannel +//W ncplane_set_bg_alpha // ncplane_set_bg_default // ncplane_set_bg_palindex // ncplane_set_bg_rgb -// ncplane_set_bg_rgb8 +//W ncplane_set_bg_rgb8 // ncplane_set_bg_rgb8_clipped -// # ncplane_set_channels -// # ncplane_set_fchannel -// ncplane_set_fg_alpha +//W# ncplane_set_channels +//W# ncplane_set_fchannel +//W ncplane_set_fg_alpha // ncplane_set_fg_default // ncplane_set_fg_palindex // ncplane_set_fg_rgb -// ncplane_set_fg_rgb8 +//W ncplane_set_fg_rgb8 // ncplane_set_fg_rgb8_clipped // ncplane_set_resizecb // ncplane_set_scrolling -// ncplane_set_styles +//W ncplane_set_styles // ncplane_set_userptr // ncplane_stain -// ncplane_styles -// ncplane_styles_off -// ncplane_styles_on -// ncplane_styles_set +//W ncplane_styles // ncplane_translate // ncplane_translate_abs // ncplane_userptr @@ -108,35 +104,35 @@ // ncplane_vprintf_aligned // ncplane_vprintf_stained // ncplane_vprintf_yx -// ncplane_x -// ncplane_y -// ncplane_yx +//W ncplane_x +//W ncplane_y +//W ncplane_yx // // functions manually reimplemented: 42 // ------------------------------------------ // (X) wont: 9 // (+) done: 34 / 0 -// (W) wrap: 5 +// (W) wrap: 20 // (#) test: 5 // ------------------------------------------ -// + ncplane_align +//W+ ncplane_align //W+ ncplane_at_cursor_cell -// + ncplane_at_yx_cell -// + ncplane_bchannel -// + ncplane_bg_alpha -// # ncplane_bg_default_p -// + ncplane_bg_rgb -// + ncplane_bg_rgb8 +//W+ ncplane_at_yx_cell +//W+ ncplane_bchannel +//W+ ncplane_bg_alpha +//W# ncplane_bg_default_p +//W+ ncplane_bg_rgb +//W+ ncplane_bg_rgb8 // + ncplane_box_sized //W# ncplane_dim_x //W# ncplane_dim_y // + ncplane_double_box // + ncplane_double_box_sized -// + ncplane_fchannel -// + ncplane_fg_alpha -// # ncplane_fg_default_p -// + ncplane_fg_rgb -// + ncplane_fg_rgb8 +//W+ ncplane_fchannel +//W+ ncplane_fg_alpha +//W# ncplane_fg_default_p +//W+ ncplane_fg_rgb +//W+ ncplane_fg_rgb8 // + ncplane_gradient_sized // u64|u32 https://github.com/dankamongmen/notcurses/issues/920 // + ncplane_hline //W+ ncplane_perimeter @@ -181,7 +177,7 @@ pub use reimplemented::*; /// `type in C: ncplane (struct)` /// /// -/// ## Piles +/// # Piles /// /// A single notcurses context is made up of one or more piles. /// @@ -211,6 +207,25 @@ pub use reimplemented::*; /// pile's z-axis. When ncplane_reparent_family() is used, all planes bound to /// the reparented plane are moved along with it. Their relative z-order is maintained. /// +/// +/// # Methods & Associated Functions +/// +/// - [Constructors & Destructors](#ncplane-constructors-and-destructors) +/// +/// Methods: +/// - [`NcAlphaBits`](#ncplane-methods-ncalphabits) +/// - [`NcChannel` & `NcChannelPair`](#ncplane-methods-ncchannel) +/// - [`NcColor`](#ncplane-methods-nccolor) +/// - [`NcRgb`](#ncplane-methods-ncrgb) +/// - [`NcStyleMask`](#ncplane-methods-ncstylemask) +/// - [`NcCell`](#ncplane-methods-nccell) +/// - [writing](#ncplane-methods-writing) +/// - [cursor](#ncplane-methods-cursor) +/// - [`NcPlane`, piles & `Notcurses` context](#ncplane-methods-ncplane-pile--notcurses-context) +/// - [boxes & perimeters](#ncplane-methods-boxes--perimeters) +/// - [Size, position & alignment](#ncplane-methods-size-position--alignment) +/// - [fading, gradients & greyscale](#ncplane-methods-fading-gradients--greyscale) +/// pub type NcPlane = crate::bindings::ffi::ncplane; /// Options struct for [`NcPlane`] diff --git a/rust/src/plane/reimplemented.rs b/rust/src/plane/reimplemented.rs index 97bdba529..7d617be62 100644 --- a/rust/src/plane/reimplemented.rs +++ b/rust/src/plane/reimplemented.rs @@ -11,8 +11,8 @@ use crate::{ ncplane_cursor_move_yx, ncplane_cursor_yx, ncplane_dim_yx, ncplane_gradient, ncplane_hline_interp, ncplane_putc_yx, ncplane_putnstr_yx, ncplane_putstr_yx, ncplane_resize, ncplane_styles, ncplane_vline_interp, ncplane_vprintf_yx, notcurses_align, NcAlign, - NcAlphaBits, NcBoxMask, NcCell, NcChannel, NcChannelPair, NcColor, NcDimension, NcOffset, - NcPlane, NcResult, NcRgb, NcStyleMask, NCRESULT_ERR, NCRESULT_OK, + NcAlphaBits, NcBoxMask, NcCell, NcChannel, NcChannelPair, NcColor, NcDimension, NcPlane, + NcResult, NcRgb, NcStyleMask, NCRESULT_ERR, NCRESULT_OK, }; // Alpha ----------------------------------------------------------------------- @@ -46,6 +46,7 @@ pub fn ncplane_bchannel(plane: &NcPlane) -> NcChannel { // NcColor --------------------------------------------------------------------- /// Gets the foreground [NcColor] RGB components from an [NcPlane]. +/// and returns the background [NcChannel]. #[inline] pub fn ncplane_fg_rgb8( plane: &NcPlane, @@ -56,7 +57,8 @@ pub fn ncplane_fg_rgb8( channels_fg_rgb8(unsafe { ncplane_channels(plane) }, red, green, blue) } -/// Gets the background [NcColor] RGB components from an [NcPlane]. +/// Gets the background [NcColor] RGB components from an [NcPlane], +/// and returns the background [NcChannel]. #[inline] pub fn ncplane_bg_rgb8( plane: &NcPlane, @@ -262,9 +264,10 @@ pub fn ncplane_resize_simple( /// Returns the column at which `cols` columns ought start in order to be aligned /// according to `align` within this NcPlane. /// -/// Returns -[`NCRESULT_MAX`] if [NCALIGN_UNALIGNED] or invalid [NcAlign]. +/// Returns -[`NCRESULT_MAX`][crate::NCRESULT_MAX] if +/// [NCALIGN_UNALIGNED][crate::NCALIGN_UNALIGNED] or invalid [NcAlign]. #[inline] -pub fn ncplane_align(plane: &NcPlane, align: NcAlign, cols: NcDimension) -> NcOffset { +pub fn ncplane_align(plane: &NcPlane, align: NcAlign, cols: NcDimension) -> NcResult { notcurses_align(ncplane_dim_x(plane), align, cols) }