Improve docs concerning custom fonts, themes and accessibility

Closes https://github.com/emilk/egui/pull/370
Closes https://github.com/emilk/egui/issues/372

egui/src/context.rs

@@ -415,7 +415,12 @@ impl Context {
         self.fonts().texture()
     }
 
-    /// Will become active at the start of the next frame.
+    /// Tell `egui` which fonts to use.
+    ///
+    /// The default `egui` fonts only support latin and cyrillic alphabets,
+    /// but you can call this to install additional fonts that support e.g. korean characters.
+    ///
+    /// The new fonts will become active at the start of the next frame.
     pub fn set_fonts(&self, font_definitions: FontDefinitions) {
         if let Some(current_fonts) = &self.fonts {
             // NOTE: this comparison is expensive since it checks TTF data for equality
@@ -434,6 +439,8 @@ impl Context {
 
     /// The [`Style`] used by all new windows, panels etc.
     ///
+    /// You can also use [`Ui::style_mut`] to change the style of a single [`Ui`].
+    ///
     /// Example:
     /// ```
     /// # let mut ctx = egui::CtxRef::default();

egui/src/data/input.rs

@@ -6,6 +6,9 @@ use crate::emath::*;
 ///
 /// Set the values that make sense, leave the rest at their `Default::default()`.
 ///
+/// You can check if `egui` is using the inputs using
+/// [`crate::Context::wants_pointer_input`] and [`crate::Context::wants_keyboard_input`].
+///
 /// All coordinates are in points (logical pixels) with origin (0, 0) in the top left corner.
 #[derive(Clone, Debug)]
 pub struct RawInput {

egui/src/input_state.rs

@@ -14,6 +14,9 @@ const MAX_CLICK_DIST: f32 = 6.0; // TODO: move to settings
 const MAX_CLICK_DELAY: f64 = 0.3; // TODO: move to settings
 
 /// Input state that egui updates each frame.
+///
+/// You can check if `egui` is using the inputs using
+/// [`crate::Context::wants_pointer_input`] and [`crate::Context::wants_keyboard_input`].
 #[derive(Clone, Debug)]
 pub struct InputState {
     /// The raw input we got this frame from the backend.

egui/src/style.rs

@@ -5,7 +5,12 @@
 use crate::{color::*, emath::*, Response};
 use epaint::{Shadow, Stroke, TextStyle};
 
-/// Specifies the look and feel of a [`Ui`].
+/// Specifies the look and feel of egui.
+///
+/// You can change the visuals of a [`Ui`] with [`Ui::style_mut`]
+/// and of everything with [`crate::Context::set_style`].
+///
+/// If you want to change fonts, use [`crate::Context::set_fonts`] instead.
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "persistence", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "persistence", serde(default))]
@@ -22,11 +27,16 @@ pub struct Style {
     /// * `Some(false)`: default off
     pub wrap: Option<bool>,
 
+    /// Sizes and distances between widgets
     pub spacing: Spacing,
+
+    /// How and when interaction happens.
     pub interaction: Interaction,
+
+    /// Colors etc.
     pub visuals: Visuals,
 
-    /// How many seconds a typical animation should last
+    /// How many seconds a typical animation should last.
     pub animation_time: f32,
 
     /// Options to help debug why egui behaves strangely.
@@ -58,6 +68,7 @@ impl Style {
     }
 }
 
+/// Controls the sizes and distances between widgets.
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "persistence", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "persistence", serde(default))]
@@ -119,6 +130,7 @@ impl Spacing {
     }
 }
 
+/// How and when interaction happens.
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "persistence", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "persistence", serde(default))]
@@ -133,6 +145,12 @@ pub struct Interaction {
     pub show_tooltips_only_when_still: bool,
 }
 
+/// Controls the visual style (colors etc) of egui.
+///
+/// You can change the visuals of a [`Ui`] with [`Ui::visuals_mut`]
+/// and of everything with [`crate::Context::set_visuals`].
+///
+/// If you want to change fonts, use [`crate::Context::set_fonts`] instead.
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "persistence", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "persistence", serde(default))]
@@ -224,6 +242,7 @@ pub struct Selection {
     pub stroke: Stroke,
 }
 
+/// The visuals of widgets for different states of interaction.
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "persistence", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "persistence", serde(default))]

egui/src/ui.rs

@@ -769,7 +769,26 @@ impl Ui {
         InnerResponse::new(ret, response)
     }
 
-    /// Convenience function to get a region to paint on
+    /// Convenience function to get a region to paint on.
+    ///
+    /// Note that egui uses screen coordinates for everything.
+    ///
+    /// ```
+    /// # use egui::*;
+    /// # let mut ui = &mut egui::Ui::__test();
+    /// # use std::f32::consts::TAU;
+    /// let size = Vec2::splat(16.0);
+    /// let (response, painter) = ui.allocate_painter(size, Sense::hover());
+    /// let rect = response.rect;
+    /// let c = rect.center();
+    /// let r = rect.width() / 2.0 - 1.0;
+    /// let color = Color32::from_gray(128);
+    /// let stroke = Stroke::new(1.0, color);
+    /// painter.circle_stroke(c, r, stroke);
+    /// painter.line_segment([c - vec2(0.0, r), c + vec2(0.0, r)], stroke);
+    /// painter.line_segment([c, c + r * Vec2::angled(TAU * 1.0 / 8.0)], stroke);
+    /// painter.line_segment([c, c + r * Vec2::angled(TAU * 3.0 / 8.0)], stroke);
+    /// ```
     pub fn allocate_painter(&mut self, desired_size: Vec2, sense: Sense) -> (Response, Painter) {
         let response = self.allocate_response(desired_size, sense);
         let clip_rect = self.clip_rect().intersect(response.rect); // Make sure we don't paint out of bounds