CosmicBuffer is a public type but not not used or accessible in any public API (#17748)
# Objective Currently [CosmicBuffer](https://docs.rs/bevy/latest/bevy/text/struct.CosmicBuffer.html) is a public type with a public field that is not used or accessible in any public API. Since it is prominently shown in the docs it is the obvious place to start when trying to access `cosmic_string` features such as for mapping between screen coordinates and positions in the displayed text. The only place `CosmicBuffer` is currently used is as a field of `ComputedTextBlock`, where a comment explains why the field is private: /// Buffer for managing text layout and creating [`TextLayoutInfo`]. /// /// This is private because buffer contents are always refreshed from ECS state when writing glyphs to /// `TextLayoutInfo`. If you want to control the buffer contents manually or use the `cosmic-text` /// editor, then you need to not use `TextLayout` and instead manually implement the conversion to /// `TextLayoutInfo`. #[reflect(ignore)] pub(crate) buffer: CosmicBuffer, Unfortunately this comment does not appear in the docs, so a user looking for a way to access `CosmicBuffer` will not find it unless they check the source code. Also there does not seem to be any alternative way to map between screen coordinates and positions in the displayed text, which would be highly useful for things like text edit widgets or tool tips. The reasons given for making the field private only apply for mutable access, so non-mutable access would presumably be fine. ## Solution I added a getter to `ComputedTextBlock`, and added the explanation for why there is no mutable access in the comment: /// Accesses the underling buffer which can be used for `cosmic-text` APIs such as accessing layout information /// or calculating a cursor position. /// /// Mutable access not offered because changes would be overwritten during the automated layout calculation. /// If you want to control the buffer contents manually or use the `cosmic-text` /// editor, then you need to not use `TextLayout` and instead manually implement the conversion to /// `TextLayoutInfo`. pub fn get_buffer(&self) -> &CosmicBuffer { &self.buffer } ## Testing I tested that the getter could be used to map from screen coordinates to string positions by creating a rudimentary text edit widget and trying it out. ## Alternatives An alternative to making `CosmicBuffer` accessible would be to make the type private so that no one wastes time looking for a way of accessing it, and adding additional methods to `ComputedTextBlock` that make use of the buffer as implementation detail and offer access to currently inaccessible functionality. --------- Co-authored-by: Rob Parrett <robparrett@gmail.com>
This commit is contained in:
parent
4fe57767fc
commit
db0356517e
@ -86,6 +86,16 @@ impl ComputedTextBlock {
|
||||
pub fn needs_rerender(&self) -> bool {
|
||||
self.needs_rerender
|
||||
}
|
||||
/// Accesses the underlying buffer which can be used for `cosmic-text` APIs such as accessing layout information
|
||||
/// or calculating a cursor position.
|
||||
///
|
||||
/// Mutable access is not offered because changes would be overwritten during the automated layout calculation.
|
||||
/// If you want to control the buffer contents manually or use the `cosmic-text`
|
||||
/// editor, then you need to not use `TextLayout` and instead manually implement the conversion to
|
||||
/// `TextLayoutInfo`.
|
||||
pub fn buffer(&self) -> &CosmicBuffer {
|
||||
&self.buffer
|
||||
}
|
||||
}
|
||||
|
||||
impl Default for ComputedTextBlock {
|
||||
|
Loading…
Reference in New Issue
Block a user