19 个版本
0.6.4 | 2022 年 2 月 21 日 |
---|---|
0.5.1 | 2020 年 1 月 30 日 |
0.4.0 | 2019 年 12 月 9 日 |
0.3.2 | 2019 年 11 月 2 日 |
0.1.5 | 2019 年 7 月 13 日 |
#613 在 命令行界面
每月 31 次下载
在 ncursesw-win 中使用
1MB
20K SLoC
ncursesw
这是一个围绕 NCurses TUI 库 的胖包装器,其目的是使原生库功能安全使用,但是请注意,原生库中存在一些函数,在某些情况下可能导致未定义的行为,这些函数已实现并可调用,但已被标记为 已弃用 并附有适当的说明。
实际上,在这个库中暴露了三层 NCurses 函数,包括由 bindgen 生成的原始 extern "C"
函数,这些函数在 ncursesw::shims::bindings
中可用。
在此之上的一层,主要是不安全,但通过断言在一定程度上保护了调用代码(一些函数还会有轻微的 Rust 包装(例如返回原始指针的函数),但整体上按照
bindgen 层的方式留出),这些可以在
ncursesw::shims::{ncurses, npanels, nmouse, nmenu, nform}
中找到,您可以将此层视为 NCurses 库的等价于 -sys crate。
最后但同样重要的是,在 ncursesw 和
ncursesw::{panels, mouse, menu, form}
中存在安全的(在 NCurses 本身的限制内)函数,它们保留了原始的 NCurses 名称,但已被 Rust 化。
还有一个配套的 crate,即 ncursesw-win,它作为此 crate 的包装器,封装了 NCurses 使用的原始指针,并提供了一个更高层次的功能。
需求
目前这个 crate 只在 64 位 Linux(Linux Mint 19.1)上进行了测试,所以应该适用于 Debian 64 位 Linux 的版本,但这尚未得到证实。
推荐和本地库支持
我建议使用此 crate 的 0.6
及以上版本,因为在这个点上,crates API 已经基本稳定。此外,从 0.6.2
开始,本地的 NCurses 库(目前是 v6.3 补丁 20211021
)是本地编译并静态链接到这个 crate 中的,因此没有依赖通过发行版/操作系统安装的 NCurses 的版本(ABI 或其他)。
包含
[dependencies]
ncursesw = "0.6"
或者使用最新的 git 版本
[dependencies]
ncursesw = { git = "https://github.com/narfit66/ncursesw-rs" }
构建
如上所述,这个 crate 只在 Debian 基础的 x86_64 Linux 上进行了测试。
当这个 crate 使用所有必需的功能(宽字符和扩展颜色支持)以及菜单、表单和面板库进行构建时,NCurses 库是本地编译并静态链接的。
编译好的 crate 将会在 target
目录下构建。
cargo build
功能
默认情况下,这个crate将被编译,以便以下NCurses函数在终端尺寸改变时将KEY_RESIZE
事件传递回客户端代码,作为KeyBinding::ResizeEvent
。在客户端代码的Cargo.toml
中的以下设置将导致此crate被编译,以便将它们作为NCurseswError::KeyResize
错误类型传递回。
[features]
key_resize_as_error = ["ncursesw/key_resize_as_error"]
如何使用
extern crate ncursesw;
use ncursesw::*;
此crate遵循与C语言使用NCurses时相同的原理,它支持标准的ASCII函数(如果不在v6.1.20180127之前,add
类型函数似乎在NCurses中默认支持Unicode字符),带有属性的ASCII字符(chtype),宽字符(
wchar_t/
wint_t
)和带有属性的复杂字符(cchar_t
)。
颜色对和属性(属性)在两个模块中处理。normal
模块处理NCurses内部定义的标准ansi
颜色对,作为short_t/i16
,而extend
模块用于扩展颜色对,这些颜色对在NCurses内部定义为i32
。因为normal
颜色对实际上是NCurses中的一个属性,所以这两个模块也实现了自己的Attribute
和Attributes
类型。
使用属性和颜色对
use ncursesw::normal::*; // for 'ansi' color pairs and attributes...
use ncursesw::extend::*; // or for 'extended' color pairs and attributes.
使用面板函数
use ncursesw::panels::*;
使用鼠标函数
use ncursesw::mouse::*;
使用菜单函数
use ncursesw::menu::*;
使用表单函数
use ncursesw::form::*;
要使用宽字符(UTF-8),需要在初始化NCurses库之前调用setlocale()
,在示例中使用了gettext-rs crate来完成此目的。
自 NCurses v6.1 版本起,所有功能都得到了支持,包括 ANSI 8 位(正常)颜色和颜色对,扩展颜色和颜色对,字符和字符串(带有属性/颜色渲染),宽字符(UTF-8)和字符串,复杂字符和字符串,软标签,分割线,面板,鼠标,菜单,表单和屏幕功能。我建议您查看 NCurses 维护者 Thomas E. Dickey 的在线文档在线文档,以及面板,鼠标,菜单,表单和屏幕文档。如果您有机会,可以阅读 Dan Gookin 的《NCurses 编程指南》一书,虽然我猜测是 Dan Gookin 编写的,但这本书是了解如何使用此库的好入门书。在这两种情况下,您都需要具备基本的 'C' 语言知识。
或者,您可以查看 crate ncursesw-win,该 crate 的目的是将此 crate 封装起来,不暴露 NCurses 库的原始指针,并将它们封装在正式的结构中。
文档
有关此 crate 的文档可在此处找到这里。
许可证
根据 MIT 许可证授权,请参阅LICENSE
依赖项
~0.5–3MB
~58K SLoC