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:
fschlee 2025-02-10 23:19:12 +01:00 committed by GitHub
parent 4fe57767fc
commit db0356517e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -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 {