SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Ribbon tooltips: a short written help for the main tools (#2758) (#3089)
rlartotedad8078ba99
diff --git a/assets/locales/en.json b/assets/locales/en.jsonindex b5d51025cd..73731f653b 100644--- a/assets/locales/en.json+++ b/assets/locales/en.json@@ -855,6 +855,12 @@"help.licences": "Licences","help.mit": "MIT licence","help.notice": "NOTICE",+ "help.solid.chamfer": "Cuts the selected edges with a flat bevel of the distance you set. Use it to break sharp edges or to ease the entry of a pin or screw.",+ "help.solid.extrude": "Pushes a sketch profile into 3D along a distance, adding or removing material. Use it to turn a flat outline into a block, a boss or a pocket.",+ "help.solid.fillet": "Rounds the selected edges with a smooth circular blend of the radius you set. Use it to soften sharp edges for strength, comfort or looks.",+ "help.solid.hole": "Drills a round hole of the diameter you set at a chosen point on a face. Use it for screw clearances, pins and other simple round openings.",+ "help.solid.revolve": "Spins a sketch profile around an axis to make a round solid. Use it for shafts, knobs, bowls and any part that is round about a centre line.",+ "help.solid.shell": "Hollows out a solid, leaving walls of the thickness you set, and can open the faces you pick. Use it for boxes, covers and other thin-walled parts.","help.third_party": "Third-party licences","home.documentation": "Documentation","home.in_this_browser": "in this browser",diff --git a/assets/locales/fr.json b/assets/locales/fr.jsonindex 325a6de422..10c1e6d393 100644--- a/assets/locales/fr.json+++ b/assets/locales/fr.json@@ -855,6 +855,12 @@"help.licences": "Licences","help.mit": "Licence MIT","help.notice": "NOTICE",+ "help.solid.chamfer": "Coupe les arêtes sélectionnées par un biseau plat de la distance indiquée. À utiliser pour casser des arêtes vives ou faciliter l'entrée d'une goupille ou d'une vis.",+ "help.solid.extrude": "Pousse le profil d'une esquisse en 3D sur une distance, en ajoutant ou en retirant de la matière. À utiliser pour transformer un contour plat en bloc, en bossage ou en poche.",+ "help.solid.fillet": "Arrondit les arêtes sélectionnées par un raccord circulaire lisse du rayon indiqué. À utiliser pour adoucir des arêtes vives par souci de solidité, de confort ou d'aspect.",+ "help.solid.hole": "Perce un trou rond du diamètre indiqué en un point choisi d'une face. À utiliser pour les passages de vis, les goupilles et autres ouvertures rondes simples.",+ "help.solid.revolve": "Fait tourner le profil d'une esquisse autour d'un axe pour obtenir un solide de révolution. À utiliser pour les arbres, boutons, bols et toute pièce ronde autour d'une ligne centrale.",+ "help.solid.shell": "Évide un solide en laissant des parois de l'épaisseur indiquée, et peut ouvrir les faces choisies. À utiliser pour les boîtes, couvercles et autres pièces à parois minces.","help.third_party": "Licences tierces","home.documentation": "Documentation","home.in_this_browser": "dans ce navigateur",diff --git a/assets/locales/ja.json b/assets/locales/ja.jsonindex 8efc6fb851..792efa23d4 100644--- a/assets/locales/ja.json+++ b/assets/locales/ja.json@@ -855,6 +855,12 @@"help.licences": "ライセンス","help.mit": "MITライセンス","help.notice": "NOTICE",+ "help.solid.chamfer": "選択した辺を、指定した距離で平らに斜めに削ります。鋭い角を落とすときや、ピンやねじを入れやすくするときに使います。",+ "help.solid.extrude": "スケッチの輪郭を指定した距離だけ立体方向に押し出し、材料を足したり削ったりします。平面の図形をブロック、突起、ポケットにするときに使います。",+ "help.solid.fillet": "選択した辺を、指定した半径のなめらかな円弧で丸めます。強度や持ちやすさ、見た目のために鋭い角を和らげるときに使います。",+ "help.solid.hole": "面上の指定した位置に、指定した直径の丸い穴をあけます。ねじのクリアランスやピン穴など、単純な丸い開口に使います。",+ "help.solid.revolve": "スケッチの輪郭を軸のまわりに回転させ、丸い立体を作ります。軸、つまみ、ボウルなど、中心線まわりに丸い部品に使います。",+ "help.solid.shell": "立体の中をくり抜き、指定した厚さの壁を残します。選んだ面を開口にすることもできます。箱、カバーなどの薄肉の部品に使います。","help.third_party": "サードパーティライセンス","home.documentation": "ドキュメント","home.in_this_browser": "このブラウザ内",diff --git a/assets/locales/zh.json b/assets/locales/zh.jsonindex 7a266d3b31..5276c629ca 100644--- a/assets/locales/zh.json+++ b/assets/locales/zh.json@@ -855,6 +855,12 @@"help.licences": "许可证","help.mit": "MIT 许可证","help.notice": "NOTICE",+ "help.solid.chamfer": "用指定的距离在所选边上切出一个平直的斜面。用于去除锐边,或使销钉、螺钉更容易插入。",+ "help.solid.extrude": "将草图轮廓按指定距离拉伸为三维形体,可以增加或去除材料。用于把平面轮廓变成方块、凸台或凹槽。",+ "help.solid.fillet": "用指定半径的平滑圆弧将所选的边倒圆。用于出于强度、手感或外观的考虑而柔化锐边。",+ "help.solid.hole": "在面上的指定位置钻出指定直径的圆孔。用于螺钉过孔、销孔等简单的圆形开口。",+ "help.solid.revolve": "将草图轮廓绕一条轴旋转,生成圆形的实体。用于轴、旋钮、碗等围绕中心线呈圆形的零件。",+ "help.solid.shell": "将实体掏空,留下指定厚度的壁,还可以打开所选的面。用于盒子、盖子等薄壁零件。","help.third_party": "第三方许可证","home.documentation": "文档","home.in_this_browser": "在此浏览器中",diff --git a/crates/ui-egui/src/command_help.rs b/crates/ui-egui/src/command_help.rsnew file mode 100644index 0000000000..464772e8ee--- /dev/null+++ b/crates/ui-egui/src/command_help.rs@@ -0,0 +1,110 @@+//! Written help for the ribbon tooltips (#2758): two short sentences per command, shown under the+//! tool name when the pointer rests on its button. The names stay as they are; the help is a+//! separate message `help.<command id>` in the catalogs, so a tool without help keeps its plain+//! tooltip. Text only for now; pictures and animations are a later step.++use crate::i18n;++/// The commands that have help text. Each one needs a `help.<id>` message in the catalogs.+pub const DOCUMENTED: &[&str] = &["solid.chamfer", "solid.extrude", "solid.fillet", "solid.hole", "solid.revolve", "solid.shell"];++/// The help for `command` in the current language, when it has any.+pub fn help(command: &str) -> Option<String> {+ if !DOCUMENTED.contains(&command) {+ return None;+ }+ let key = format!("help.{command}");+ let text = i18n::tr(&key);+ (text != key).then(|| text.to_owned())+}++/// Show `tip` (name, shortcut or the reason the tool is disabled) as the tooltip of `response`,+/// with the help of `command` below it when there is one.+pub fn tooltip(response: egui::Response, command: &str, tip: String) -> egui::Response {+ let help = help(command);+ response.on_hover_ui(move |ui| {+ ui.set_max_width(300.0);+ ui.label(tip);+ if let Some(help) = help {+ ui.add_space(2.0);+ ui.label(egui::RichText::new(help).weak());+ }+ })+}++/// The tooltip text of a panel drop-down row: the reason when the command is disabled (as before),+/// else its name and shortcut when it has help to show below, else nothing (no tooltip).+pub fn row_tip(command: &str, label: &str, shortcut: Option<&str>, disabled_reason: Option<&str>) -> Option<String> {+ match disabled_reason {+ Some(why) => Some(why.to_owned()),+ None => help(command).map(|_| format!("{label}{}", shortcut.map(|k| format!(" ({k})")).unwrap_or_default())),+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use std::collections::BTreeSet;++ fn catalog(source: &str) -> std::collections::BTreeMap<String, String> {+ serde_json::from_str(source).unwrap()+ }++ /// The `help.<command id>` messages; other `help.*` messages (About dialog texts) are not tool help.+ fn help_keys(source: &str) -> BTreeSet<String> {+ catalog(source)+ .into_keys()+ .filter(|k| k.starts_with("help.") && (k.starts_with("help.solid.") || DOCUMENTED.contains(&&k["help.".len()..])))+ .collect()+ }++ #[test]+ fn every_documented_id_is_a_real_command() {+ for id in DOCUMENTED {+ assert!(solidcraft_engine::find_command(id).is_some(), "{id} is not a command");+ }+ assert!(DOCUMENTED.is_sorted());+ }++ #[test]+ fn every_help_message_is_for_a_documented_command() {+ let english = help_keys(include_str!("../../../assets/locales/en.json"));+ let wanted: BTreeSet<String> = DOCUMENTED.iter().map(|id| format!("help.{id}")).collect();+ assert_eq!(english, wanted);+ for key in &english {+ let id = key.trim_start_matches("help.");+ assert!(solidcraft_engine::find_command(id).is_some(), "{key} names no command");+ }+ }++ #[test]+ fn the_help_texts_are_written_in_every_complete_language() {+ let english = catalog(include_str!("../../../assets/locales/en.json"));+ for source in [include_str!("../../../assets/locales/ja.json"), include_str!("../../../assets/locales/zh.json")] {+ let other = catalog(source);+ for (key, text) in english.iter().filter(|(k, _)| k.starts_with("help.")) {+ let translated = other.get(key).unwrap_or_else(|| panic!("{key} missing"));+ assert!(!translated.trim().is_empty());+ // The messages carry no placeholders; if one is added, both sides must agree.+ assert_eq!(text.matches('{').count(), translated.matches('{').count(), "{key}");+ }+ }+ }++ #[test]+ fn a_documented_command_has_help_and_others_do_not() {+ for id in DOCUMENTED {+ assert!(help(id).is_some_and(|text| !text.is_empty()), "{id}");+ }+ assert!(help("solid.pattern.rectangular").is_none());+ }++ #[test]+ fn a_drop_down_row_has_a_tip_only_for_a_reason_or_help() {+ assert_eq!(row_tip("solid.shell", "Shell", Some("S"), None).as_deref(), Some("Shell (S)"));+ assert_eq!(row_tip("solid.hole", "Hole", None, None).as_deref(), Some("Hole"));+ assert_eq!(row_tip("solid.hole", "Hole", None, Some("Select a face")).as_deref(), Some("Select a face"));+ assert_eq!(row_tip("solid.pattern.rectangular", "Pattern", None, None), None);+ assert_eq!(row_tip("solid.pattern.rectangular", "Pattern", None, Some("No body")).as_deref(), Some("No body"));+ }+}diff --git a/crates/ui-egui/src/lib.rs b/crates/ui-egui/src/lib.rsindex 4d502c72b7..dba709d221 100644--- a/crates/ui-egui/src/lib.rs+++ b/crates/ui-egui/src/lib.rs@@ -20,6 +20,7 @@ pub mod canvas;mod colour_tokens_tests;#[cfg(test)]mod colour_vision_tests;+pub mod command_help;pub mod context_menu;pub mod control;pub mod crash_ui;diff --git a/crates/ui-egui/src/toolbar.rs b/crates/ui-egui/src/toolbar.rsindex 4f043f0447..b49beef631 100644--- a/crates/ui-egui/src/toolbar.rs+++ b/crates/ui-egui/src/toolbar.rs@@ -1529,6 +1529,10 @@ fn ribbon_tooltip(app: &SolveApp, response: egui::Response, command: &solidcraftif let Some(description) = description {ui.add(egui::Label::new(description).wrap());}+ // The tool's own help, when it has one (#2758).+ if let Some(help) = crate::command_help::help(command.id) {+ ui.add(egui::Label::new(egui::RichText::new(help).color(t.text_dim)).wrap());+ }if let Some(reason) = disabled {ui.add(egui::Label::new(egui::RichText::new(reason).color(t.text_dim)).wrap());}@@ -1630,9 +1634,11 @@ fn dropdown_row(app: &SolveApp, ui: &mut egui::Ui, c: &'static solidcraft_engineif pin.on_hover_text(tip).clicked() {return RowAction::TogglePin;}- let resp = match &info.disabled_reason {- Some(why) if !info.enabled => resp.on_hover_text(why),- _ => resp,+ // A disabled row says why; a documented command also shows its help (#2758).+ let reason = info.disabled_reason.as_deref().filter(|_| !info.enabled);+ let resp = match crate::command_help::row_tip(c.id, &label, c.shortcut, reason) {+ Some(tip) => crate::command_help::tooltip(resp, c.id, tip),+ None => resp,};if resp.secondary_clicked() {return RowAction::Menu(resp.interact_pointer_pos().unwrap_or(rect.left_bottom()));