win_ctx/lib.rs
1//! A Rust library for managing Windows context menu entries.
2//!
3//! ## Installation
4//!
5//! ```sh
6//! cargo add win-ctx
7//! ```
8//!
9//! ## Features
10//!
11//! - Create and edit context menu entries and sub-entries
12//! - Toggle the pre-Windows 11 context menu
13//!
14//! ## Basic examples
15//!
16//! The following code creates a top-level context menu entry that appears on
17//! right-clicked folders and opens the target folder in the terminal.
18//!
19//! ```no_run
20//! use win_ctx::*;
21//!
22//! CtxEntry::new_with_options(
23//! "Open in terminal",
24//! &ActivationType::Folder,
25//! &EntryOptions {
26//! command: Some("cmd /s /k pushd \"%V\""),
27//! icon: Some("C:\\Windows\\System32\\cmd.exe"),
28//! position: None,
29//! separator: None,
30//! extended: false,
31//! }
32//! )?;
33//! ```
34//!
35//! The following code creates a context menu entry with child entries that each
36//! open the target folder in the selected program.
37//!
38//! To reduce line count, the more basic non-options functions can be used,
39//! and individual values are then set on the resulting entries.
40//!
41//! ```no_run
42//! use win_ctx::{CtxEntry, ActivationType};
43//!
44//! let mut parent = CtxEntry::new("Open directory in", &ActivationType::Background)?;
45//! parent.set_extended(true);
46//!
47//! let mut child_1 = parent.new_child("Terminal")?;
48//! child_1.set_command(Some("cmd /s /k pushd \"%V\""))?;
49//! child_1.set_icon(Some("C:\\Windows\\System32\\cmd.exe"))?;
50//!
51//! let mut child_2 = parent.new_child("Powershell")?;
52//! child_2.set_command(Some("powershell -noexit -command Set-Location -literalPath '%V'"))?;
53//! child_2.set_icon(Some("C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"))?;
54//! ```
55//!
56//! ## Errors
57//!
58//! It's possible that an entry's underlying registry key goes out of sync,
59//! so most `CtxEntry` functions verify this and return a [`std::io::Result`].
60//!
61//! Errors will have an [`ErrorKind`] of either:
62//! - `PermissionDenied` for insufficient privileges,
63//! - `InvalidValue` for invalid entry renames, or
64//! - `NotFound` for operations on missing keys and values.
65//!
66//! [`ErrorKind`]: https://doc.rust-lang.org/std/io/enum.ErrorKind.html
67//! [`std::io::Result`]: https://doc.rust-lang.org/std/io/type.Result.html
68
69pub use entry::*;
70pub use utils::toggle_classic_menu;
71
72mod entry;
73mod path;
74mod utils;