Cleanup the organization of widget modules and add documentation

Signed-off-by: Michael X. Grey <[email protected]>

rmf_site_editor/src/aabb.rs

@@ -17,10 +17,12 @@ use bevy::{
 use smallvec::SmallVec;
 
 /// Tracks which [`Entities`](Entity) have which meshes for entities whose [`Aabb`]s are managed by
-/// the [`calculate_bounds`] and [`update_bounds`] systems. This is needed because `update_bounds`
+/// the [`calculate_bounds`][1] and [`update_bounds`] systems. This is needed because `update_bounds`
 /// recomputes `Aabb`s for entities whose mesh has been mutated. These mutations are visible via
 /// [`AssetEvent<Mesh>`](AssetEvent) which tells us which mesh was changed but not which entities
 /// have that mesh.
+///
+/// [1]: bevy::render::view::calculate_bounds
 #[derive(Debug, Default, Clone, Resource)]
 pub struct EntityMeshMap {
     entities_with_mesh: HashMap<AssetId<Mesh>, SmallVec<[Entity; 1]>>,
@@ -76,8 +78,6 @@ pub fn register_bounds(
 /// Updates [`Aabb`]s for [`Entities`](Entity) with [`Mesh`]es. This includes `Entities` that have
 /// been assigned new `Mesh`es as well as `Entities` whose `Mesh` has been directly mutated.
 ///
-/// To opt out of bound calculation for an `Entity`, give it the [`NoAabbUpdate`] component.
-///
 /// NOTE: This system needs to remove entities from their collection in
 /// [`EntityMeshMap`] whenever a mesh handle is reassigned or an entity's mesh handle is
 /// removed. This may impact performance if meshes with many entities are frequently

rmf_site_editor/src/interaction/gizmo.rs

@@ -218,7 +218,7 @@ impl Default for GizmoState {
 }
 
 /// Instruction to move an entity to a new transform. This should be caught with
-/// an EventReader<MoveTo>.
+/// an `EventReader<MoveTo>`.
 #[derive(Debug, Clone, Copy, Event)]
 pub struct MoveTo {
     pub entity: Entity,

rmf_site_editor/src/interaction/mode.rs

@@ -101,8 +101,8 @@ pub struct BackoutParams<'w, 's> {
 ///    cannot expect users to know this or handle the cleanup correctly.
 ///
 /// User-defined systems should never
-/// use ResMut<InteractionMode>. Instead they should always use
-/// EventWriter<ChangeMode>.
+/// use `ResMut<InteractionMode>`. Instead they should always use
+/// `EventWriter<ChangeMode>`.
 //
 // TODO(MXG): We could enforce this by letting InteractionMode be public but
 // wrapping it in a newtype to store it in the resource. The inner type would

rmf_site_editor/src/lib.rs

@@ -186,7 +186,7 @@ impl Plugin for SiteEditor {
                 WorkcellEditorPlugin,
                 SitePlugin,
                 InteractionPlugin,
-                StandardUiLayout,
+                StandardUiPlugin::default(),
                 AnimationPlugin,
                 OccupancyPlugin,
                 WorkspacePlugin,

rmf_site_editor/src/widgets/console.rs

@@ -17,11 +17,10 @@
 
 use crate::{log::*, widgets::prelude::*};
 use bevy::prelude::*;
-use bevy_egui::{
-    egui::{self, CollapsingHeader, Color32, RichText},
-    EguiContexts,
-};
+use bevy_egui::egui::{self, CollapsingHeader, Color32, RichText};
 
+/// This widget provides a console that displays information, warning, and error
+/// messages.
 #[derive(Default)]
 pub struct ConsoleWidgetPlugin {}
 
@@ -34,15 +33,14 @@ impl Plugin for ConsoleWidgetPlugin {
 }
 
 fn console_widget(
-    In(_): In<Entity>,
+    In(input): In<PanelWidgetInput>,
     mut log_history: ResMut<LogHistory>,
-    mut egui_context: EguiContexts,
 ) {
     egui::TopBottomPanel::bottom("log_consolse")
         .resizable(true)
         .min_height(30.0)
         .max_height(300.0)
-        .show(egui_context.ctx_mut(), |ui| {
+        .show(&input.context, |ui| {
             ui.horizontal_wrapped(|ui| {
                 ui.spacing_mut().item_spacing.x = 0.5;
                 let status = log_history.top();

rmf_site_editor/src/widgets/creation.rs

@@ -18,28 +18,30 @@
 use crate::{
     inspector::{InspectAssetSourceComponent, InspectScaleComponent},
     interaction::{ChangeMode, SelectAnchor, SelectAnchor3D},
-    site::{DefaultFile, DrawingBundle, Recall},
+    site::{DefaultFile, DrawingBundle, Recall, AssetSource, RecallAssetSource, Scale},
     widgets::{prelude::*, AssetGalleryStatus},
-    AppState, CurrentWorkspace, PendingDrawing, PendingModel,
+    AppState, CurrentWorkspace,
 };
 use bevy::{ecs::system::SystemParam, prelude::*};
 use bevy_egui::egui::{CollapsingHeader, Ui};
 
 use rmf_site_format::{DrawingProperties, Geometry, Model, WorkcellModel};
 
+/// This widget provides a widget with buttons for creating new site elements.
 #[derive(Default)]
 pub struct CreationPlugin {}
 
 impl Plugin for CreationPlugin {
     fn build(&self, app: &mut App) {
-        app.init_resource::<PendingDrawing>()
+        app
+            .init_resource::<PendingDrawing>()
             .init_resource::<PendingModel>()
             .add_plugins(PropertiesTilePlugin::<Creation>::new());
     }
 }
 
 #[derive(SystemParam)]
-pub struct Creation<'w, 's> {
+struct Creation<'w, 's> {
     default_file: Query<'w, 's, &'static DefaultFile>,
     app_state: Res<'w, State<AppState>>,
     change_mode: EventWriter<'w, ChangeMode>,
@@ -259,3 +261,17 @@ impl<'w, 's> Creation<'w, 's> {
         });
     }
 }
+
+#[derive(Resource, Clone, Default)]
+struct PendingDrawing {
+    pub source: AssetSource,
+    pub recall_source: RecallAssetSource,
+}
+
+
+#[derive(Resource, Clone, Default)]
+struct PendingModel {
+    pub source: AssetSource,
+    pub recall_source: RecallAssetSource,
+    pub scale: Scale,
+}

rmf_site_editor/src/widgets/diagnostics.rs

@@ -25,12 +25,10 @@ use crate::{
     AppState, CurrentWorkspace, Icons, Issue, IssueDictionary, ValidateWorkspace,
 };
 use bevy::{ecs::system::SystemParam, prelude::*};
-use bevy_egui::{
-    egui::{self, Button, Checkbox, Grid, ImageButton, ScrollArea, Ui},
-    EguiContexts,
-};
+use bevy_egui::egui::{self, Button, Checkbox, Grid, ImageButton, ScrollArea, Ui};
 use std::collections::HashSet;
 
+/// Add a [`Diagnostics`] widget to your application.
 #[derive(Default)]
 pub struct DiagnosticsPlugin {}
 
@@ -48,23 +46,25 @@ impl Plugin for DiagnosticsPlugin {
 }
 
 fn diagnostics_panel(
-    In(panel): In<Entity>,
+    In(input): In<PanelWidgetInput>,
     world: &mut World,
-    egui_contexts: &mut SystemState<EguiContexts>,
 ) {
     if world.resource::<DiagnosticsDisplay>().show {
-        let ctx = egui_contexts.get_mut(world).ctx_mut().clone();
         egui::SidePanel::left("diagnsotics")
             .resizable(true)
             .min_width(320.0)
-            .show(&ctx, |ui| {
-                if let Err(err) = world.try_show(panel, ui) {
+            .show(&input.context, |ui| {
+                if let Err(err) = world.try_show(input.id, ui) {
                     error!("Unable to display diagnostics panel: {err:?}");
                 }
             });
     }
 }
 
+/// A widget that displays diagnostic information about the current site. This
+/// helps identify potential problems that you should consider addressing.
+///
+/// Use [`DiagnosticsPlugin`] to add this to your application.
 #[derive(SystemParam)]
 pub struct Diagnostics<'w, 's> {
     icons: Res<'w, Icons>,

rmf_site_editor/src/widgets/fuel_asset_browser.rs

@@ -21,12 +21,12 @@ use crate::{
     widgets::prelude::*,
 };
 use bevy::{ecs::system::SystemParam, prelude::*};
-use bevy_egui::{
-    egui::{self, Button, ComboBox, ImageSource, RichText, ScrollArea, Ui, Window},
-    EguiContexts,
+use bevy_egui::egui::{
+    self, Button, ComboBox, ImageSource, RichText, ScrollArea, Ui, Window,
 };
 use gz_fuel::FuelModel;
 
+/// Add a [`FuelAssetBrowser`] widget to your application.
 #[derive(Default)]
 pub struct FuelAssetBrowserPlugin {}
 
@@ -50,7 +50,7 @@ pub struct ShowAssetFilters {
     pub recall_private: Option<bool>,
 }
 
-/// Used to indicate whether to show or hide the left side panel with the asset gallery
+/// Used to indicate whether to show or hide the [`FuelAssetBrowser`].
 #[derive(Resource, Default)]
 pub struct AssetGalleryStatus {
     pub show: bool,
@@ -63,6 +63,13 @@ pub struct AssetGalleryStatus {
     pub show_api_window: bool,
 }
 
+/// A widget for browsing models that can be downloaded from fuel.
+///
+/// This is part of the [`StandardUiPlugin`][1]. If you are not using the
+/// `StandardUiLayout` then it is recommended that you use the
+/// [`FuelAssetBrowserPlugin`] to add this to the editor.
+///
+/// [1]: crate::widgets::StandardUiPlugin
 #[derive(SystemParam)]
 pub struct FuelAssetBrowser<'w, 's> {
     fuel_client: ResMut<'w, FuelClient>,
@@ -76,17 +83,15 @@ pub struct FuelAssetBrowser<'w, 's> {
 }
 
 fn fuel_asset_browser_panel(
-    In(panel): In<Entity>,
+    In(input): In<PanelWidgetInput>,
     world: &mut World,
-    egui_contexts: &mut SystemState<EguiContexts>,
 ) {
     if world.resource::<AssetGalleryStatus>().show {
-        let ctx = egui_contexts.get_mut(world).ctx_mut().clone();
         egui::SidePanel::left("asset_gallery")
             .resizable(true)
             .min_width(320.0)
-            .show(&ctx, |ui| {
-                if let Err(err) = world.try_show(panel, ui) {
+            .show(&input.context, |ui| {
+                if let Err(err) = world.try_show(input.id, ui) {
                     error!("Unable to display asset gallery: {err:?}");
                 }
             });

rmf_site_editor/src/widgets/icons.rs

@@ -16,9 +16,24 @@
 */
 
 use crate::{recency::RankAdjustment, site::LayerVisibility};
-use bevy::{ecs::system::SystemState, prelude::*};
+use bevy::{
+    asset::embedded_asset,
+    ecs::system::SystemState,
+    prelude::*
+};
 use bevy_egui::{egui::ImageSource, egui::TextureId, EguiContexts};
 
+/// Add a resource for the common icons of the application.
+#[derive(Default)]
+pub struct IconsPlugin {}
+
+impl Plugin for IconsPlugin {
+    fn build(&self, app: &mut App) {
+        add_widgets_icons(app);
+        app.init_resource::<Icons>();
+    }
+}
+
 struct IconBuilder(Handle<Image>);
 impl IconBuilder {
     pub fn new(name: &str, asset_server: &AssetServer) -> Self {
@@ -48,7 +63,7 @@ impl Icon {
     }
 }
 
-// TODO(MXG): Create a struct to manage bevy-egui image pairs
+/// A collection of icons used by the standard widgets.
 #[derive(Clone, Debug, Resource)]
 pub struct Icons {
     pub select: Icon,
@@ -156,3 +171,56 @@ impl Icons {
         }
     }
 }
+
+fn add_widgets_icons(app: &mut App) {
+    // Taken from https://github.com/bevyengine/bevy/issues/10377#issuecomment-1858797002
+    // TODO(luca) remove once we migrate to Bevy 0.13 that includes the fix
+    #[cfg(any(not(target_family = "windows"), target_env = "gnu"))]
+    {
+        embedded_asset!(app, "src/", "icons/add.png");
+        embedded_asset!(app, "src/", "icons/alignment.png");
+        embedded_asset!(app, "src/", "icons/alpha.png");
+        embedded_asset!(app, "src/", "icons/confirm.png");
+        embedded_asset!(app, "src/", "icons/down.png");
+        embedded_asset!(app, "src/", "icons/edit.png");
+        embedded_asset!(app, "src/", "icons/empty.png");
+        embedded_asset!(app, "src/", "icons/exit.png");
+        embedded_asset!(app, "src/", "icons/global.png");
+        embedded_asset!(app, "src/", "icons/hidden.png");
+        embedded_asset!(app, "src/", "icons/hide.png");
+        embedded_asset!(app, "src/", "icons/merge.png");
+        embedded_asset!(app, "src/", "icons/opaque.png");
+        embedded_asset!(app, "src/", "icons/reject.png");
+        embedded_asset!(app, "src/", "icons/search.png");
+        embedded_asset!(app, "src/", "icons/select.png");
+        embedded_asset!(app, "src/", "icons/selected.png");
+        embedded_asset!(app, "src/", "icons/to_bottom.png");
+        embedded_asset!(app, "src/", "icons/to_top.png");
+        embedded_asset!(app, "src/", "icons/trash.png");
+        embedded_asset!(app, "src/", "icons/up.png");
+    }
+    #[cfg(all(target_family = "windows", not(target_env = "gnu")))]
+    {
+        embedded_asset!(app, "src\\", "icons\\add.png");
+        embedded_asset!(app, "src\\", "icons\\alignment.png");
+        embedded_asset!(app, "src\\", "icons\\alpha.png");
+        embedded_asset!(app, "src\\", "icons\\confirm.png");
+        embedded_asset!(app, "src\\", "icons\\down.png");
+        embedded_asset!(app, "src\\", "icons\\edit.png");
+        embedded_asset!(app, "src\\", "icons\\empty.png");
+        embedded_asset!(app, "src\\", "icons\\exit.png");
+        embedded_asset!(app, "src\\", "icons\\global.png");
+        embedded_asset!(app, "src\\", "icons\\hidden.png");
+        embedded_asset!(app, "src\\", "icons\\hide.png");
+        embedded_asset!(app, "src\\", "icons\\merge.png");
+        embedded_asset!(app, "src\\", "icons\\opaque.png");
+        embedded_asset!(app, "src\\", "icons\\reject.png");
+        embedded_asset!(app, "src\\", "icons\\search.png");
+        embedded_asset!(app, "src\\", "icons\\select.png");
+        embedded_asset!(app, "src\\", "icons\\selected.png");
+        embedded_asset!(app, "src\\", "icons\\to_bottom.png");
+        embedded_asset!(app, "src\\", "icons\\to_top.png");
+        embedded_asset!(app, "src\\", "icons\\trash.png");
+        embedded_asset!(app, "src\\", "icons\\up.png");
+    }
+}

rmf_site_editor/src/widgets/inspector/inspect_texture.rs

@@ -33,7 +33,8 @@ pub struct InspectTexturePlugin {}
 
 impl Plugin for InspectTexturePlugin {
     fn build(&self, app: &mut App) {
-        app.init_resource::<SearchForTexture>()
+        app
+            .init_resource::<SearchForTexture>()
             .add_plugins(InspectionPlugin::<InspectTextureAffiliation>::new());
     }
 }