Simplify and Clarify Font Modification APIs (add_font and set_fonts)

[lalala-233]

Description

Currently, egui provides two APIs for modifying fonts:

1. add_font: Adds a new font to the existing font definitions.
2. set_fonts: Replaces the entire font definitions with a new set.

However, these APIs have a high degree of code overlap, and their usage is not clearly documented. Additionally, set_fonts has a performance overhead due to an expensive comparison check, and its behavior is not fully intuitive.

Problems

1. API Overlap:

   • Both add_font and set_fonts can be used to modify fonts, but their use cases and differences are not clearly explained in the documentation.
   • This can lead to confusion for users who are unsure which API to use.

2. Performance Overhead:

   • set_fonts performs an expensive comparison to check if the new font definitions are identical to the current ones. This is unnecessary in most cases, especially when the goal is to reset fonts or textures. As mentioned in Fix: ctx.set_fonts() Doesn't Apply Fonts with Same Name #5345.

egui/crates/egui/src/context.rs

Lines 1767 to 1771 in 4784136

	self.read(|ctx| {
	if let Some(current_fonts) = ctx.fonts.get(&pixels_per_point.into()) {
	// NOTE: this comparison is expensive since it checks TTF data for equality
	if current_fonts.lock().fonts.definitions() == &font_definitions {
	update_fonts = false; // no need to update

3. Documentation Issues:
   • The examples in the documentation do not clearly explain the differences between add_font and set_fonts.
   • Here are some confusing statements:

egui/examples/custom_font/src/main.rs

Lines 42 to 45 in 4784136

	// Demonstrates how to replace all fonts.
	fn replace_fonts(ctx: &egui::Context) {
	// Start with the default fonts (we will be adding to them rather than replacing them).
	let mut fonts = egui::FontDefinitions::default();

• The comment for set_fonts could be clearer

egui/crates/egui/src/context.rs

Lines 1759 to 1760 in 4784136

	/// This will overwrite the existing fonts.
	pub fn set_fonts(&self, font_definitions: FontDefinitions) {

• For example, state that it will replace the existing font definitions with the provided ones.

4. Code Overlap:
   • Both add_font and set_fonts share significant code overlap, particularly in font data insertion, font family definitions, and update logic. This duplication increases maintenance complexity and raises the risk of inconsistencies or subtle bugs.

egui/crates/egui/src/context.rs

Lines 1788 to 1808 in 4784136

	pub fn add_font(&self, new_font: FontInsert) {
	profiling::function_scope!();
	let pixels_per_point = self.pixels_per_point();
	let mut update_fonts = true;
	self.read(|ctx| {
	if let Some(current_fonts) = ctx.fonts.get(&pixels_per_point.into()) {
	if current_fonts
	.lock()
	.fonts
	.definitions()
	.font_data
	.contains_key(&new_font.name)
	{
	update_fonts = false; // no need to update
	}
	}
	});

egui/crates/egui/src/context.rs

Lines 1760 to 1774 in 4784136

	pub fn set_fonts(&self, font_definitions: FontDefinitions) {
	profiling::function_scope!();
	let pixels_per_point = self.pixels_per_point();
	let mut update_fonts = true;
	self.read(|ctx| {
	if let Some(current_fonts) = ctx.fonts.get(&pixels_per_point.into()) {
	// NOTE: this comparison is expensive since it checks TTF data for equality
	if current_fonts.lock().fonts.definitions() == &font_definitions {
	update_fonts = false; // no need to update
	}
	}
	});

---

This issue was translated by AI.