Skip to content

Commit

Permalink
docs: update README.zh-cn.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@lc-soft
lc-soft committed May 4, 2024
1 parent af895de commit 9d441dc
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 198 deletions.
265 changes: 67 additions & 198 deletions README.zh-cn.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
</a>
<h3 align="center">LCUI</h3>
<p align="center">
C 的图形界面开发库，可借助 XML 和 CSS 构建简单的跨平台桌面应用
用于开发图形用户界面的 C 库
</p>
<p align="center">
<a href="https://github.com/lc-soft/LCUI/actions"><img alt="GitHub Actions" src="https://github.com/lc-soft/LCUI/workflows/C%2FC%2B%2B%20CI/badge.svg"></a>
Expand All @@ -23,252 +23,121 @@

- [目录](#%E7%9B%AE%E5%BD%95)
- [介绍](#%E4%BB%8B%E7%BB%8D)
- [主要特性](#%E4%B8%BB%E8%A6%81%E7%89%B9%E6%80%A7)
- [效果图](#%E6%95%88%E6%9E%9C%E5%9B%BE)
- [架构](#%E6%9E%B6%E6%9E%84)
- [设计参考](#%E8%AE%BE%E8%AE%A1%E5%8F%82%E8%80%83)
- [编译](#%E7%BC%96%E8%AF%91)
- [安装](#%E5%AE%89%E8%A3%85)
- [一图速览](#%E4%B8%80%E5%9B%BE%E9%80%9F%E8%A7%88)
- [架构](#%E6%9E%B6%E6%9E%84)
- [快速体验](#%E5%BF%AB%E9%80%9F%E4%BD%93%E9%AA%8C)
- [文档](#%E6%96%87%E6%A1%A3)
- [教程](#%E6%95%99%E7%A8%8B)
- [参考资料](#%E5%8F%82%E8%80%83%E8%B5%84%E6%96%99)
- [路线图](#%E8%B7%AF%E7%BA%BF%E5%9B%BE)
- [贡献](#%E8%B4%A1%E7%8C%AE)
- [经济支持](#%E7%BB%8F%E6%B5%8E%E6%94%AF%E6%8C%81)
- [常见问题](#%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98)
- [许可](#%E8%AE%B8%E5%8F%AF)

<!-- /TOC -->

## 介绍

LCUI 是一个用 C 语言编写的桌面端图形界面开发库。

### 主要特性

- **C 语言编写：** 适用于体积较小且主要使用 C 语言实现的应用程序，以及偏向使用 C 语言编写简单应用的开发者。
- **跨平台：** 支持 Windows 和 GNU/Linux 系统，可开发简单的 Windows 桌面应用和通用应用，以及 Linux 桌面应用。
- **XML + CSS：** 预置 XML 和 CSS 解析器，你可以使用 XML 和 CSS 来描述界面结构和样式。
- **与网页类似的开发体验：** 由于 LCUI 的布局、样式和渲染器等相关功能的设计和实现大都参考了 MDN 文档和一些 Web 前端流行的开发库，因此开发体验和界面效果会与网页有一些相似之处，如果你已经有用 HTML 和 CSS 编过网页的经验，那么会比较容易上手。
- **可缩放：** 支持全局缩放，支持使用基于屏幕密度的 sp 和 dp 单位表示界面元素的位置和大小。

### 效果图

<table>
<tbody>
<tr>
<td>
<a class="thumbnail" href="https://github.com/lc-soft/LCUI/blob/develop/test/helloworld.c">
<img src="https://lcui.org/static/images/showcase/screenshot-lcui-hello.png" alt="Hello App"/>
</a>
</td>
<td>
<a class="thumbnail" href="https://github.com/lc-soft/LC-Finder">
<img src="https://gitee.com/lc-soft/LC-Finder/raw/develop/screenshots/2.jpg" alt="LC Finder"/>
</a>
</td>
</tr>
<tr>
<td>
<a class="thumbnail" href="https://github.com/lc-ui/lcui-router-app">
<img src="https://gitee.com/lc-ui/lcui-router-app/raw/master/screenshot.gif" alt="LCUI Router App"/>
</a>
</td>
<td>
<a class="thumbnail" href="https://github.com/lc-ui/lc-design">
<img src="https://lcui.lc-soft.io/static/images/showcase/lc-design-example-preview.png" alt="LC Design"/>
</a>
</td>
</tr>
</tbody>
</table>
LCUI 是一个用 C 语言编写的用于构建图形用户界面的库，其功能设计和用法参考了 Web 领域内的一些流行的技术，例如：CSS、Flex 布局，对于有 Web 网页开发经验的人比较容易上手。

LC 源自作者名字首字母，设计之初的目的是为了方便作者开发一些小项目和积累开发经验，不过遗憾的是作者并没有因此在 C/C++ 高手众多的就业环境下获得足够竞争优势，被迫从事 Web 前端开发工作，也正是因为如此，LCUI 现在的发展方向偏向于融合 Web 前端领域的技术。

### 一图速览

你可以从下图了解 LCUI 应用程序的开发体验：

![preview](preview.png)

- **类 React 组件开发方式：** 用 TypeScript 语言编写界面配置文件，结合 TypeScript 的语言优势、JSX 语法特性和 LCUI React 库，你能够以简洁的代码描述界面结构、资源依赖、组件状态、数据绑定以及事件绑定。
- **多种样式编写方式：** [Tailwind CSS](https://tailwindcss.com/)、[CSS Modules](https://github.com/css-modules/css-modules)、[Sass](https://sass-lang.com/)、全局 CSS。
- **基于目录的路由定义方式：** 以文件目录的形式组织应用的各个页面，每个页面对应一个目录，目录的路径即是该页面的路由。借助内置的应用路由器，你可以轻松地实现页面之间的切换和导航，无需手动配置路由规则。
- **友好且现代的图标库：** 图标源自 [fluentui-system-icons](https://github.com/microsoft/fluentui-system-icons) 库，针对 LCUI 的特性做了部分定制，用法相似。
- **命令行开发工具：** 运行 `lcui build` 命令预处理 app 目录内的配置文件，然后生成相应的 C 源码和资源文件。

### 架构

LCUI 建立在各种库的基础之上，如下所示：

```text
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ LCUI Application ┃
┃ ┃
┃ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃
┃ ┃ LCUI 3 ┃ ┃
┃ ┏━┻━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┻━┓ ┃
┃ ┃ ui-server ┃ ui-widgets ┃ ui-builder ┃ ui-anchor ┃ ┃
┃ ┏━┻━━━━━━━━━━━┻━━━━━━━━━━━━┻━━━━━━━━━━━━┻━━━━━━━━━━━┻━┓ ┃
┃ ┃ platform ┃ ui ┃ worker ┃ timer ┃ cursor ┃ ┃
┣━━━━┻━━━━━━━━━━┻━━━━━━━━━━┻━━━━━━━━━━┻━━━━━━━━━┻━━━━━━━━━━┻━━━━┫
┃ thread ┃ yutil ┃ image ┃ css ┃ paint ┃ font ┃ text ┃
┗━━━━━━━━┻━━━━━━━━┻━━━━━━━━┻━━━━━━━━━┻━━━━━━━━┻━━━━━━━━┻━━━━━━━━┛
```
LCUI 建立在各种库的基础之上：

- [lib/yutil](./lib/yutil): 实用工具库，提供常用的数据结构和函数。
- [lib/pandagl](./lib/pandagl): PandaGL (Panda Graphics Library) 图形库，提供字体管理、文字排版、图片读写、图形处理和渲染能力。
- [lib/css](./lib/css): CSS 解析器和选择引擎，提供 CSS 解析和选择能力。
- [lib/font](./lib/font): 字体渲染库，提供字体文件加载和渲染能力。
- [lib/image](./lib/image): 图像文件操作库，提供 BMP、JPG、PNG 图像文件读取能力和 PNG 写能力。
- [lib/paint](./lib/paint): 图形绘制库，提供线段、矩形、圆形和阴影的绘制能力。
- [lib/platform](./lib/platform): 平台库，提供跨平台统一的系统相关 API，包括消息循环、窗口管理、输入法等。
- [lib/text](./lib/text): 文本排版库，提供文本排版能力。
- [lib/thread](./lib/thread): 线程库，提供跨平台的多线程能力。
- [lib/timer](./ui/timer): 定时器库，提供定时执行操作的能力。
- [lib/ui](./lib/ui): 图形界面核心库，提供 UI 组件管理、事件队列、样式计算、绘制等 UI 必要能力。
- [lib/ui-anchor](./lib/anchor): 锚点组件，提供类似于超链接的能力。
- [lib/ui-builder](./lib/anchor): 构建器，提供从 XML 文件内容创建 UI 的能力。
- [lib/timer](./ui/timer): 定时器库，提供定时执行任务的能力。
- [lib/ui](./lib/ui): UI 核心库，提供 UI 组件管理、事件队列、样式计算、绘制等 UI 必要能力。
- [lib/ui-xml](./lib/anchor): XML 解析库，提供从 XML 文件内容创建 UI 的能力。
- [lib/ui-cursor](./lib/ui-cursor): 光标，提供光标绘制能力。
- [lib/ui-server](./lib/ui-server): 服务器，提供将 UI 组件映射至系统窗口的能力。
- [lib/ui-widgets](./lib//ui/widgets): 组件库，提供文本、按钮、滚动条等一些基础的 UI 组件。
- [lib/ui-server](./lib/ui-server): UI 服务器，提供将 UI 组件映射至系统窗口的能力。
- [lib/ui-router](./lib/ui-router): 路由管理器，提供路由映射和导航能力。
- [lib/ui-widgets](./lib//ui/widgets): 预置的基础组件库，提供文本、按钮、滚动条等一些基础的 UI 组件。
- [lib/worker](./lib/worker): 工作线程库，提供简单的工作线程通信和管理能力。
- [lib/yutil](./lib/yutil): 实用工具库，提供链表、哈希表、红黑树、字符串等相关常用函数。

### 设计参考
## 快速体验

- [SDL](https://github.com/SDL-mirror/SDL/tree/master/src/video/x11) — x11 的驱动代码参考
- [FreeType](https://www.freetype.org/freetype2/docs/design/design-3.html#section-1) — 数据结构的命名风格参考
- [LevelDB](https://github.com/google/leveldb/blob/master/include/leveldb/c.h) — 函数命名风格参考
- [jQuery](https://jquery.com/) — 部件操作接口的命名风格参考
- [MDN](https://developer.mozilla.org/zh-CN/docs/Web/CSS) — CSS 标准参考
在开始前你需要在你的计算机上安装以下软件：

## 编译
- [Git](https://git-scm.com/download/)：版本管理工具，用于下载示例项目源码
- [XMake](https://xmake.io/#/zh-cn/?id=%e5%ae%89%e8%a3%85)：构建工具，用于构建项目
- [Node.js](https://nodejs.org/): JavaScript 运行环境，用于运行 LCUI 的命令行开发工具

先安装 [XMake](https://xmake.io/#/zh-cn/)，然后执行以下命令：
然后在命令行窗口中运行以下命令：

```bash
# 克隆代码库
git clone https://github.com/lc-soft/LCUI.git
```shell
# 安装 LCUI 命令行开发工具
npm install -g @lcui/cli

# 进入源码目录
cd LCUI

# 构建
xmake
# 创建 LCUI 应用程序项目
lcui create my-lcui-app
```

如果你想体验测试程序的运行效果的话：
之后按照命令输出的提示继续操作。

```bash
# 打包已构建的文件以供构建测试程序
xmake package
## 文档

# 进入测试程序目录
cd test
- [在线文档](https://lcui-dev.github.io/docs/next/guides/base/)
- [意见征集稿（RFC）](https://lcui-dev.github.io/docs/next/rfcs/)
- [更新日志](CHANGELOG.zh-cn.md)
- [贡献指南](.github/CONTRIBUTING.md)

# 编译测试程序
xmake -P .
### 教程

# 运行测试程序
xmake run -P . -w . helloworld
```
- [待办清单](https://lcui-dev.github.io/docs/next/tutorials/todolist)：学习 LCUI 的基本概念和用法，以及如何使用它构建界面，并实现状态管理、界面更新和交互。
- [渲染布料动画](https://lcui-dev.github.io/docs/next/tutorials/render-fabric)：参照现有的布料模拟程序的 JavaScript 源码，以 C 语言重新编写，并采用 cairo 图形库进行布料渲染，再运用 LCUI 实现布料动画的播放和交互。
- [浏览器](https://lcui-dev.github.io/docs/next/tutorials/browser)：参照网页浏览器，用 LCUI 实现与之类似的界面结构、布局、样式和多标签管理功能，并运用 LCUI 路由管理功能实现多标签页的状态管理和导航，以及一个简单的文件浏览页面。**（该教程已过时，欢迎参与更新）**

## 安装
### 参考资料

```bash
xmake install
LCUI 的部分功能设计参考了其它开源项目，你可以查看它们的文档以了解基本概念和用法。

# 或者安装到自定义目录下
xmake install -o /path/to/your/custom/installdir
```

## 文档

- 在线教程：[https://docs.lcui.lc-soft.io](https://docs.lcui.lc-soft.io)
- 更新日志：[CHANGELOG.zh-cn.md](CHANGELOG.zh-cn.md)
- [DirectXTK](https://github.com/Microsoft/DirectXTK/wiki/StepTimer)：步进定时器的源码参考。
- [Vue Router](https://router.vuejs.org/zh/guide/)：路由管理器的参考，[部分功能的实现](https://github.com/search?q=repo%3Alc-soft%2FLCUI+vuejs%2Fvue-router&type=code)还参考了 Vue Router 的源码。
- [Next.js](https://nextjs.org/docs/app/building-your-application/routing)：路由定义方式的参考。

## 路线图

此项目的开发计划分为主线和支线，主线中的开发任务主要由项目维护者负责推进，优先级较高，主要包括：

- LCUI 3.0 开发 ([#239](https://github.com/lc-soft/LCUI/issues/239))
- 完善文档
以下是未来可推进的事项：

其它的任务则归为支线，交给开源社区贡献者以及像你这样的开发者来推进。如需了解更多细节可查看 [issues](https://github.com/lc-soft/LCUI/issues) 和[项目](https://github.com/lc-soft/LCUI/projects)页面。
- 命令行工具
- `lcui build --watch`：持续监听文件变更并自动重新构建。
- `lcui dev-server`：与 webpack-dev-server 类似，将 LCUI 应用构建为网站以便开发者在浏览器中预览界面。
- 添加构建缓存，仅重新构建有更改的文件。
- React 组件库：参考一些 web 前端组件库（例如：[radix](https://www.radix-ui.com/)），用 TypeScript + React 开发一个适用于 LCUI 应用程序的组件库，复用 [LC Design](https://github.com/lcui-dev/lc-design) 组件库中的组件。
- 文档
- 教程
- 意见征集稿（RFC）

## 贡献

有很多方式可以为此项目的发展做贡献：

- 完善 lib 目录中各个库的自述文档，内容包括但不仅限于补充示例代码、相关功能讲解、运行效果图等
- [反馈问题](https://github.com/lc-soft/LCUI/issues)并在问题关闭时帮助我们验证它们是否已经修复
- 在源码中[搜索 FIXME 注释](https://github.com/lc-soft/LCUI/search?l=C&q=FIXME)，然后尝试解决它们
- 在源码中搜索 [FIXME 注释](https://github.com/lc-soft/LCUI/search?l=C&q=FIXME)和 [TODO 注释](https://github.com/lc-soft/LCUI/search?l=C&q=TODO)，然后尝试解决它们
- 在 [IssueHunt](https://issuehunt.io/r/lc-soft/LCUI) 上为感兴趣的 issue 设置悬赏，吸引其他开发者参与开发
- 审查[源代码的改动](https://github.com/lc-soft/LCUI/pulls)
- 修复已知问题

本项目采用了参与者公约定义的行为准则，该文档应用于许多开源社区，有关更多信息，请参阅[《行为准则》](CODE_OF_CONDUCT.zh-cn.md)。

## 经济支持

经济支持是最简单有效的支持方式，它能直接影响此项目的活跃度和贡献者数量，如果你看好此项目的发展前景，可以考虑在以下平台提供资金赞助：

- **爱发电:** https://afdian.net/@lc-soft
- **OpenCollective:** https://opencollective.com/LCUI

## 常见问题

1. **为什么开发它？**

- 探索和实验新的 GUI 开发方式
- 给职业生涯赚点加分项
- 找点存在感
- 打发时间

1. **这是一个浏览器内核吗？或者是像 Electron 这样的集成了浏览器环境的开发库？**

不是，你可以当成是一个应用了部分 Web 技术的传统 GUI 开发库。

1. **我为什么要用 LCUI，而不是 Electron？**

除了技术研究与交流，以及为开源社区发展做贡献外，你没有理由 LCUI。相较于功能完备的 Electron 而言，文件体积小和内存占用低并没有什么用，毕竟现在机器配置都很高，即便 APP 的界面卡到爆，占用上百 MB 的内存和近 1 GB 的存储空间，只要能正常运作就够了。

1. **假如我要用它的话，需要注意什么？**

建议你的项目满足以下条件：

- 界面结构简单，以静态内容为主，不需要动画、表格、渐变背景色等高级特性。
- 代码设计合理，核心功能代码与界面逻辑分离，即便在使用 LCUI 后发现不符合需求，也能轻松迁移至其它 GUI 库。

1. **适合哪些人使用？**

适合有 GUI 应用开发经验、熟悉 Web 前端开发技术、有意向参与开源项目的 C 开发者使用，最好是具备两年 C 开发经验和一年 web 前端开发经验。以时间来衡量上手门槛可能有点不妥，以下按照技术方向分别列出了一些主要条件，你可自行判断自己是否能够快速上手。

C：

- 熟悉 C 语言及编译相关工具链的配置，能解决编译问题
- 熟悉至少一种图形库和 GUI 库/框架，了解 GUI 应用程序的工作原理
- 熟悉多线程编程，能够解决线程安全、线程同步等问题
- 能熟练使用调试工具定位问题
- 有较多的开源项目源码阅读经验

Web 前端：

- 熟练掌握常见布局
- 熟悉 CSS 盒子模型和常用属性
- 有良好的 CSS 编码风格
- 了解前端工程化和相关开发工具

1. **我想要 ???? 功能，就像 ???? 里的那样。**

请先[新建 issue](https://github.com/lc-soft/LCUI/issues/new/choose)，按照已有的模板补全内容，我们建议你尽量将你的需求描述清楚，如果能提供开发思路、相关参考文档等内容那是最好的，例如：

```markdown
# 建议添加 xxx

（简介）xxx 是......
（特性）它能够......
（理由）对于 LCUI 它能解决 ...... 等问题
（实现思路）大致的实现方法是先这样......然后......再......最后......
（参考资料）具体可参考这些 ......
```

不推荐的写法：

```markdown
# 建议添加 xxx

如题，我觉得很有必要，请添加，谢谢。
```

1. **求添加 JavaScript/Python/Go/Rust/PHP/C#/Java 语言绑定**

已有官方支持的 [Trad](https://github.com/lc-soft/trad) 语言绑定，不考虑添加其它语言绑定。如果你实在需要的话可以自己动手设计，毕竟你比作者更懂这些语言的编程思想和设计哲学，也算是一个展现技术实力的好机会。

## 许可

LCUI 采用的开源许可证是 [MIT](http://opensource.org/licenses/MIT)。
[MIT](http://opensource.org/licenses/MIT)
Binary file added preview.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 9d441dc

Please sign in to comment.