Skip to content

Commit

Permalink
docs: update README
Browse files Browse the repository at this point in the history
  • Loading branch information
lc-soft committed Dec 25, 2024
1 parent cfa6051 commit ee68772
Show file tree
Hide file tree
Showing 2 changed files with 78 additions and 60 deletions.
95 changes: 53 additions & 42 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,16 +42,17 @@ LCUI is a library written in C for building graphical user interfaces. Its goal

**LC** originates from the initials of the author's name. The library was initially designed to help the author develop small projects and gain development experience. However, the author did not gain a competitive advantage in the job market, which is crowded with C/C++ experts, and thus had to work in web front-end development. As a result, LCUI now leans towards integrating technologies from the web front-end domain.

### Main Features
### Key Features

- **Cross-Platform:** Supports Windows and Linux.
- **Fully Custom-Drawn Components:** Components maintain a consistent appearance and behavior across multiple platforms.
- **Built-in CSS Engine:** Supports using CSS to define the style and layout of the user interface, making it easier to get started for those with web development experience.
- **Provides Modern Development Tools:** The tools allow you to use the [TypeScript](https://lcui-dev.github.io/docs/guide/typescript) language with JSX syntax, the React library, and other web front-end technologies to write user interfaces.
- **Cross-platform:** Supports Windows and Linux.
- **Fully custom-drawn components:** Ensures consistent appearance and behavior of components across platforms.
- **DPI awareness:** Automatically scales the UI on high-resolution screens to maintain a clear display.
- **Built-in CSS engine:** Enables the use of CSS for defining UI styles and layouts, making it easier for developers with web development experience to get started.
- **Modern development tools:** Includes tools that allow you to build user interfaces using [TypeScript](https://lcui-dev.github.io/docs/guide/typescript) with JSX syntax, the React library, and other web frontend technologies.

### Overview of Features
### Development Experience Preview

You can learn about the development experience of LCUI applications from the following screenshot:
You can get an overview of the development experience for LCUI applications from the following image:

![preview](preview.png)

Expand All @@ -65,19 +66,18 @@ You can learn about the development experience of LCUI applications from the fol

Over time LCUI has been built up to be based on various libraries:

- [lib/yutil](./lib/yutil): Utility library providing common data structures and functions.
- [lib/pandagl](./lib/pandagl): PandaGL (Panda Graphics Library), offering font management, text layout, image I/O, graphics processing, and rendering capabilities.
- [lib/css](./lib/css): CSS parser and selector engine providing CSS parsing and selection capabilities.
- [lib/ptk](./lib/ptk): Platform Toolkit library offering cross-platform unified system-related APIs, including message loop, window management, input method, etc.
- [lib/thread](./lib/thread): Thread library providing cross-platform multithreading capabilities.
- [lib/timer](./ui/timer): Timer library providing the ability to execute tasks at regular intervals.
- [lib/ui](./lib/ui): UI core library providing essential UI capabilities such as UI component management, event queue, style computation, and drawing.
- [lib/ui-xml](./lib/anchor): XML parsing library providing the ability to create UI from XML file content.
- [lib/ui-cursor](./lib/ui-cursor): Cursor library offering cursor drawing capabilities.
- [lib/ui-server](./lib/ui-server): UI server providing the ability to map UI components to system windows.
- [lib/ui-router](./lib/ui-router): Router manager offering route mapping and navigation capabilities.
- [lib/ui-widgets](./lib//ui/widgets): Predefined basic component library providing basic UI components such as text, button, scrollbar, etc.
- [lib/worker](./lib/worker): Worker thread library providing simple worker thread communication and management capabilities.
- [lib/yutil](./lib/yutil): Utility library providing common data structures and functions.
- [lib/pandagl](./lib/pandagl): PandaGL (Panda Graphics Library), a graphics library offering font management, text layout, image processing, and rendering capabilities.
- [lib/css](./lib/css): CSS parser and selector engine, enabling CSS parsing and selection functionalities.
- [lib/ptk](./lib/ptk): Platform Toolkit library offering cross-platform unified system-related APIs, including message loops, window management, timers, worker threads, and input methods.
- [lib/thread](./lib/thread): Thread library offering cross-platform multithreading capabilities.
- [lib/ui](./lib/ui): Core UI library that manages UI components, event queues, style computation, drawing, and other essential UI functionalities.
- [lib/ui-xml](./lib/ui-xml): XML parsing library enabling the creation of UI components from XML file content.
- [lib/ui-cursor](./lib/ui-cursor): Cursor library providing cursor rendering capabilities.
- [lib/ui-server](./lib/ui-server): UI server that maps UI components to system windows.
- [lib/ui-router](./lib/ui-router): Router manager offering routing and navigation functionalities.
- [lib/ui-widgets](./lib/ui/widgets): Predefined basic component library offering essential UI components such as text, buttons, and scrollbars.
- [lib/worker](./lib/worker): Worker thread library providing simple communication and management for worker threads.

## Quick Start

Expand Down Expand Up @@ -122,21 +122,27 @@ Some features of LCUI and related projects are inspired by other open-source pro

## Roadmap

Here are the upcoming items:

- LCUI
- Improve API design.
- Enhance the CSS engine to support `inherit`, `!important`, and escape characters.
- Add [SDL](https://www.libsdl.org/) backend to replace the lib/ptk library.
- Adapt to other open-source graphics libraries for better rendering performance.
- Command-line Tools
- `lcui build --watch`: Continuously monitor file changes and automatically rebuild.
- `lcui dev-server`: Similar to webpack-dev-server, builds the LCUI application as a website for developers to preview interfaces in the browser.
- Add build cache to rebuild only files that have changed.
- React Component Library: Referencing some web frontend component libraries (e.g., [radix](https://www.radix-ui.com/), [shadcn/ui](https://ui.shadcn.com/)), develop a TypeScript + React component library suitable for LCUI applications, reusing components from the [LC Design](https://github.com/lcui-dev/lc-design) component library.
- Documentation
- Tutorials
- Request for Comments (RFC)
Below are the items for potential future development:

- **LCUI**
- Improve API design.
- Enhance the CSS engine to support `inherit` and `!important`.
- Add an [SDL](https://www.libsdl.org/) backend to replace the lib/ptk library.
- Adapt other open-source graphics libraries to achieve better rendering performance.
- Optimize memory usage.
- Improve performance.

- **Command-Line Tools**
- `lcui build --watch`: Continuously monitor file changes and automatically rebuild.
- `lcui dev-server`: Similar to webpack-dev-server, build LCUI applications as websites to allow developers to preview interfaces in the browser.
- Add build caching to rebuild only the modified files.

- **React Component Library**
Develop a component library for LCUI applications using TypeScript + React, inspired by some web frontend component libraries (e.g., [radix](https://www.radix-ui.com/), [shadcn/ui](https://ui.shadcn.com/)), and reuse components from the [LC Design](https://github.com/lcui-dev/lc-design) library.

- **Documentation**
- Tutorials
- Request for Comments (RFC)

## Contribution

Expand All @@ -152,20 +158,25 @@ Think LCUI is slow to update? there are many ways to [contribute](.github/CONTRI
LCUI has adopted the code of conduct defined by the Contributor Covenant. This document is used across many open source communities, and we think it articulates our values well. For more, see the [Code of Conduct](CODE_OF_CONDUCT.md).

## FAQ
**Is this a browser engine? Or a development library like Electron that integrates a browser environment?**

No, you can think of it as a traditional GUI development library that incorporates some web technologies.

**Is this a browser kernel? Or a development library like Electron that integrates the browser environment?**
**Why should I choose LCUI over other GUI libraries/frameworks?**

No, you can think of it as a traditional GUI development library that applied some Web technologies.
It's recommended to prioritize other GUI libraries/frameworks, as LCUI currently lacks:

**Since it supports the use of TypeScript language, why don't I use Electron?**
- **A rich set of built-in components:** You will need to build almost all the components in your interface from scratch, leading to higher development costs.
- **Efficient graphics rendering performance:** Interfaces with extensive and complex content may experience lag.
- **An animation system:** The lack of visual feedback affects the user interaction experience.

Yes, if you have web development experience and are willing to learn Electron, then Electron is obviously the best choice.
Given its current state, LCUI is best suited for fulfilling the author's personal needs or developing simple tools with minimal interface content and interactions.

Given LCUI's current capabilities, it is primarily suitable for meeting the author's personal needs and developing simple tools.
**Support development with TypeScript? If I know how to use it, why wouldn’t I just go with Electron?**

**Why should I choose LCUI over other GUI libraries/frameworks?**
Currently, TypeScript is primarily used to describe UI and resource dependencies, with only a few TypeScript features in use. You don’t need to study it in depth; in most cases, you can simply refer to example code for implementation.

We suggest that you prioritize other GUI libraries/frameworks.
If you have extensive web development experience and are willing to learn Electron, then Electron is clearly the better choice.

**How about CSS support?**

Expand Down
43 changes: 25 additions & 18 deletions README.zh-cn.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,11 @@ LCUI 是一个用 C 语言编写的用于构建图形用户界面的库。它的

- **跨平台:** 支持 Windows、Linux。
- **全自绘组件:** 组件在多个平台中都能保持一致的外观和行为。
- **DPI 感知:** 在高分辨率的屏幕内自动缩放界面以保持清晰的显示效果。
- **自带 CSS 引擎:** 支持使用 CSS 来定义用户界面的样式和布局,对于有网页开发经验的人比较容易上手。
- **提供现代化的开发工具:** 该工具允许你使用 [TypeScript](https://lcui-dev.github.io/docs/guide/typescript) 语言搭配 JSX 语法、 React 库以及其它 Web 前端技术来编写用户界面。

### 一图速览
### 开发体验预览

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

Expand All @@ -66,9 +67,8 @@ LCUI 建立在各种库的基础之上:
- [lib/yutil](./lib/yutil): 实用工具库,提供常用的数据结构和函数。
- [lib/pandagl](./lib/pandagl): PandaGL (Panda Graphics Library) 图形库,提供字体管理、文字排版、图片读写、图形处理和渲染能力。
- [lib/css](./lib/css): CSS 解析器和选择引擎,提供 CSS 解析和选择能力。
- [lib/ptk](./lib/ptk): 平台库(**P**ing **T**ai **K**u),提供跨平台统一的系统相关 API,包括消息循环、窗口管理、输入法等。
- [lib/ptk](./lib/ptk): 平台库(**P**ing **T**ai **K**u),提供跨平台统一的系统相关 API,包括消息循环、窗口管理、定时器、工作线程、输入法等。
- [lib/thread](./lib/thread): 线程库,提供跨平台的多线程能力。
- [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): 光标,提供光标绘制能力。
Expand All @@ -81,9 +81,9 @@ LCUI 建立在各种库的基础之上:

在开始前你需要在你的计算机上安装以下软件:

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

然后在命令行窗口中运行以下命令:

Expand Down Expand Up @@ -124,9 +124,11 @@ LCUI 及相关项目的部分功能设计参考了其它开源项目,你可以

- LCUI
- 改进 API 设计。
- 改进 CSS 引擎,增加支持 `inherit``!important`、转义字符
- 改进 CSS 引擎,增加支持 `inherit``!important`
- 添加 [SDL](https://www.libsdl.org/) 后端,代替 lib/ptk 库。
- 适配其它开源图形库,以获得更好的渲染性能。
- 优化内存占用。
- 优化性能。
- 命令行工具
- `lcui build --watch`:持续监听文件变更并自动重新构建。
- `lcui dev-server`:与 webpack-dev-server 类似,将 LCUI 应用构建为网站以便开发者在浏览器中预览界面。
Expand All @@ -140,12 +142,11 @@ LCUI 及相关项目的部分功能设计参考了其它开源项目,你可以

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

- 完善 lib 目录中各个库的自述文档,内容包括但不仅限于补充示例代码、相关功能讲解、运行效果图等
- [反馈问题](https://github.com/lc-soft/LCUI/issues)并在问题关闭时帮助我们验证它们是否已经修复
- 在源码中搜索 [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)
- 修复已知问题
- 完善 lib 目录中各个库的自述文档,内容包括但不仅限于补充示例代码、相关功能讲解、运行效果图等。
- [反馈问题](https://github.com/lc-soft/LCUI/issues)并在问题关闭时帮助我们验证它们是否已经修复。
- 在源码中搜索 [FIXME 注释](https://github.com/lc-soft/LCUI/search?l=C&q=FIXME)[TODO 注释](https://github.com/lc-soft/LCUI/search?l=C&q=TODO),然后尝试解决它们。
- 审查[源代码的改动](https://github.com/lc-soft/LCUI/pulls)
- 修复已知问题。

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

Expand All @@ -155,15 +156,21 @@ LCUI 及相关项目的部分功能设计参考了其它开源项目,你可以

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

**都用上 TypeScript 语言了,那我为什么不直接用 Electron**
**相比其它 GUI 库/框架,我为什么选择 LCUI**

是的,如果你有 web 开发经验且愿意学习 Electron,显然 Electron 是最合适的选择。
建议优先考虑其它 GUI 库/框架,因为 LCUI 目前缺少:

以 LCUI 现有的条件,除了满足作者的个人需求外,也就只适用于开发一些简单的小工具。
- **丰富的预置组件:** 你需要从零开始实现界面中几乎所有的组件,开发成本较高。
- **高效的图形渲染性能:** 界面内容较多且较大时,可能会出现卡顿。
- **动画系统:** 界面没有动效反馈,影响交互体验。

**相比其它 GUI 库/框架,我为什么选择 LCUI?**
以 LCUI 现有的条件,除了满足作者的个人需求外,也就只适用于开发一些界面内容和交互都很简单的小工具。

**都用上 TypeScript 语言了,那我为什么不直接用 Electron?**

目前,TypeScript 语言主要用于描述界面和资源依赖,用到的 TypeScript 特性较少,并不需要你深入学习并它,大多数情况下你只需要参考示例代码进行编写。

建议优先考虑其它 GUI 库/框架
如果你有较丰富的 web 开发经验且愿意学习 Electron,显然 Electron 是最合适的选择

**建议添加 MacOS、Android 系统支持!**

Expand Down

0 comments on commit ee68772

Please sign in to comment.