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 中使用

MIT 许可证

1MB
20K SLoC

ncursesw Crates.io 构建状态 MIT licensed 代码行数

这是一个围绕 NCurses TUI 库 的胖包装器,其目的是使原生库功能安全使用,但是请注意,原生库中存在一些函数,在某些情况下可能导致未定义的行为,这些函数已实现并可调用,但已被标记为 已弃用 并附有适当的说明。

实际上,在这个库中暴露了三层 NCurses 函数,包括由 bindgen 生成的原始 extern "C" 函数,这些函数在 ncursesw::shims::bindings 中可用。

在此之上的一层,主要是不安全,但通过断言在一定程度上保护了调用代码(一些函数还会有轻微的 Rust 包装(例如返回原始指针的函数),但整体上按照 bindgen 层的方式留出),这些可以在 ncursesw::shims::{ncurses, npanels, nmouse, nmenu, nform} 中找到,您可以将此层视为 NCurses 库的等价于 -sys crate。

最后但同样重要的是,在 ncurseswncursesw::{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中的一个属性,所以这两个模块也实现了自己的AttributeAttributes类型。

使用属性和颜色对

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