Skip to content

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.json
index 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.json
index 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.json
index 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.json
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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: &solidcraft
if 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_engine
if 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()));