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 example
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//! extended: false,
30//! }
31//! )?;
32//! ```
33//!
34//! ## Advanced example
35//!
36//! The following code creates a context menu entry with child entries that each
37//! open the target folder in the selected program.
38//!
39//! To reduce line count, the more basic non-options functions can be used,
40//! and individual values are then set on the resulting entries.
41//!
42//! ```no_run
43//! use win_ctx::{CtxEntry, ActivationType};
44//!
45//! let mut parent = CtxEntry::new("Open directory in", &ActivationType::Background)?;
46//! parent.set_extended(true);
47//!
48//! let mut child_1 = parent.new_child("Terminal")?;
49//! child_1.set_command(Some("cmd /s /k pushd \"%V\""))?;
50//! child_1.set_icon(Some("C:\\Windows\\System32\\cmd.exe"))?;
51//!
52//! let mut child_2 = parent.new_child("Powershell")?;
53//! child_2.set_command(Some("powershell -noexit -command Set-Location -literalPath '%V'"))?;
54//! child_2.set_icon(Some("C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"))?;
55//! ```
56//!
57//! ## Errors
58//!
59//! Because this library manipulates the Windows registry, code must be executed
60//! as administrator or any other user with sufficient privileges.
61//!
62//! Errors will have an [`ErrorKind`] of either:
63//! - `PermissionDenied` for insufficient privileges, or
64//! - `NotFound` for operations on missing keys and values.
65//!
66//! [`ErrorKind`]: https://doc.rust-lang.org/std/io/enum.ErrorKind.html
67
68pub use entry::*;
69pub use utils::toggle_old_menu;
70
71mod entry;
72mod path;
73mod utils;