lc-soft/lcui

C library for building user interfaces

LCUI

The C library for build user interfaces

Table of contents

• Table of contents
• Introduction
  • Main Features
  • Overview of Features
  • Architecture
• Quick Start
• Documentation
  • Tutorials
  • References
• Roadmap
• Contribution
• FAQ
• License

Introduction

中文版说明文档

LCUI is a library written in C for building graphical user interfaces. Its goal is to explore and practice new ways of developing user interfaces, characterized by its small size, ease of use, and provision of convenient development tools to help developers quickly create desktop applications with graphical user interfaces.

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

• 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 language with JSX syntax, the React library, and other web front-end technologies to write user interfaces.

Overview of Features

You can learn about the development experience of LCUI applications from the following screenshot:

• Component Development in React-like Style: Writing UI configuration files using TypeScript. With the combined advantages of TypeScript, JSX syntax, and the LCUI React library, you can succinctly describe interface structure, resource dependencies, component states, data binding, and event binding.
• Various Stylesheet Writing Methods: Tailwind CSS, CSS Modules, Sass, and global CSS.
• File-system based router: Organize application pages in directory form, with each page corresponding to a directory. The path of the directory serves as the route for that page. With the built-in application router, you can easily implement page switching and navigation without manual route configuration.
• User-friendly and Modern Icon Library: Icons are sourced from the fluentui-system-icons library, with partial customization to fit LCUI's characteristics, offering similar usage patterns.
• Command-line Development Tool: Run the lcui build command to preprocess configuration files within the app directory, then generate corresponding C source code and resource files.

Architecture

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

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

Quick Start

Before you begin, you need to install the following software on your computer:

• Git: Version control tool used to download the source code of the example project.
• XMake: Build tool used to build the project.
• Node.js: JavaScript runtime environment used to run the LCUI command-line development tool.

Then, run the following commands in a command-line window:

# Install the LCUI command-line development tool
npm install -g @lcui/cli

# Create an LCUI application project
lcui create my-lcui-app

Follow the prompts provided by the commands afterward.

Documentation

• Online Documentation
• Request for Comments (RFC)
• Changelog
• Contribution Guidelines

Tutorials

• Todo List: Learn the basic concepts and usage of LCUI, as well as how to use it to build interfaces and implement state management, interface updates, and interactions.
• Rendering Fabric Animation: Rewrite the existing fabric simulation program's JavaScript source code in C language, and use the cairo graphics library for fabric rendering. Then, apply LCUI to implement fabric animation playback and interaction.
• Browser: Referencing a web browser, use LCUI to implement similar interface structure, layout, style, and multi-tab management features. Utilize LCUI's routing management functionality to implement multi-tab page state management and navigation, as well as a simple file browsing page. (This tutorial is outdated, contributions to update it are welcome)

References

Some features of LCUI and related projects are inspired by other open-source projects. You can refer to their documentation to understand the basic concepts and usage.

• DirectXTK: Source code reference for the step timer.
• Vue Router: Reference for the router manager. Some functionalities also reference the source code of Vue Router.
• Next.js: Reference for route definition methods.

Roadmap

Here are the upcoming items:

• LCUI
  • Improve API design.
  • Enhance the CSS engine to support inherit, !important, and escape characters.
  • Add SDL backend to replace the lib/platform 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, shadcn/ui), develop a TypeScript + React component library suitable for LCUI applications, reusing components from the LC Design component library.
• Documentation
  • Tutorials
  • Request for Comments (RFC)

Contribution

Think LCUI is slow to update? there are many ways to contribute to LCUI.

• Submit bugs and help us verify fixes as they are checked in.
• Share some interesting ideas related to GUI development in the issues page.
• Search for FIXME comments in the source code and try to fix them.
• Fund the issues that interest you on IssueHunt to attract other developers to contribute.
• Review the source code changes.
• Contribute bug fixes.

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.

FAQ

Is this a browser kernel? Or a development library like Electron that integrates the browser environment?

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

Since it supports the use of TypeScript language, why don't I use Electron?

Yes, if you have web development experience and are willing to learn Electron, then Electron is obviously the best choice.

Given LCUI's current capabilities, it is primarily suitable for meeting the author's personal needs and developing simple tools.

Why should I choose LCUI over other GUI libraries/frameworks?

We suggest that you prioritize other GUI libraries/frameworks.

How about CSS support?

The following is a list of supported CSS features. Checked is supported (But does not mean full support). Unlisted properties are not supported by default.

CSS feature coverage

• at rules
  • @font-face
  • @keyframes
  • @media
• keywords
  • !important
• selectors
  • *
  • type
  • #id
  • .class
  • :hover
  • :focus
  • :active
  • :first-child
  • :last-child
  • [attr="value"]
  • :not()
  • :nth-child()
  • parent > child
  • a ~ b
  • ::after
  • ::before
  • ...
• units
  • px
  • dp
  • sp
  • pt
  • %
  • rem
  • vh
  • vw
• properties
  • top, right, bottom, left
  • width, height
  • visibility
  • display
    • none
    • inline-block
    • block
    • flex
    • inline-flex
    • inline
    • grid
    • table
    • table-cell
    • table-row
    • table-column
    • ...
  • position
    • static
    • relative
    • absolute
    • fixed
  • box-sizing
    • border-box
    • content-box
  • border
  • border-radius
  • background-color
  • background-image
  • background-position
  • background-cover
  • background
  • pointer-events
  • font-face
  • font-family
  • font-size
  • font-style
  • flex
  • flex-shrink
  • flex-grow
  • flex-basis
  • flex-wrap
  • flex-direction
  • justify-content
    • flex-start
    • center
    • flex-end
  • align-items
    • flex-start
    • center
    • flex-end
    • stretch
  • float
  • transition
  • transform
  • ...

License

The LCUI Project is released under the MIT License.

lcui's Issues

#define ⇒ enum?

Would you like to replace more defines for constant values by enumerations to stress their relationships?

• FILE_ERROR_…
• MAX_…

完善圆角边框功能

修改之前的圆角边框绘制代码以使其能够正常绘制。

定时器任务在 X11 的事件循环中有时会丢失

貌似定时器要出问题，所有定时器都会出现问题。

16-bit color screen graphics output problem

Graphical output in 16-bit color screen is not normal

部件样式刷新问题

在改变样式后会消失，当再次改变样式时才会显示出来。

改进部件的排序

当部件数量达到上万级别的时候排序操作会非常耗时，在当前版本中，每个部件都会排序一次，排序算法为插入排序，一万个部件会排序一万次，而每次排序都要遍历一次部件列表，总计遍历一亿次。

LCUI 应用程序启动后有时会出现异常

当前定位到的异常代码主要在 xml 解析和任务销毁上：


这些问题在 Release 版本中会出现，而在 Debug 版本中几乎不会出现。

部件初始位置的计算问题

部件在初次显示时的位置有问题，在更新一次样式后才会恢复正常位置。

编译不了

github中的代码编译不了，代码不全？第一个错误是LCUI_ScreenInfo没定义，搜索了所有文件都没有该定义

使用 border: 1px solid transparent 设置透明边框时会没有效果

在解析 border 属性值时，由于边框色是 transparent，被判定为无效的颜色，导致整个 border 属性值无效。

Protect against spurious wakeups

I have seen that no loop is used around a call of the function "LCUICond_Wait".
Would you like to reuse anything from my message on the topic "spurious wakeup"?

Possible name clash

According to ISO C11 7.31.6, macros that begin with LC_ and an uppercase letter may be used by the implementation. Though they are not explicitly reserved by ISO C(e.g. as identifiers containing double underscores), there are risks.
Furthermore, POSIX.1-2013 explicitly states that the names with prefix LC_[A-Z] are reserved once the header <locale.h> is included. That means if the client code uses both <locale.h> and LCUI, it could never be conforming to POSIX.

Copying permission statement at the beginning of the files

Some files like LCUI_Font.h and LCUI_Input.h have redundant "\n" at the end of lines of copying permission statement. What is worse, they use horizontal tab to align, so the "\n" are often unaligned when the text editor configuration varies.
In some files like LCUI_InputMethod.h it is just missing.

在 X11 模式下，按键事件有时会使事件循环卡住

XkbKeycodeToKeysym() 函数一直处于阻塞状态，没有返回结果。

Improve bitmap scaling quality

The currently used image scaling algorithm is nearest neighbor interpolation, and the scaled image is jagged and needs improvement.

需更改链表的遍历方式

当前是直接使用 LinkedList_ForEach() 宏来遍历链表的，但在 VisualStudio 中会把它当成函数定义，导致它所在的函数无法被索引。

部件样式的更新有延迟现象

正常情况下，在修改几个部件的样式后应该会在一两帧内得到应用，然而实际测试发现有时会需要近1秒的时间才应用新样式，能感到明显的延迟现象。

在 linux 环境下使用定时器，会间断性的出现延迟问题

设置 20 ms 间隔循环调用的定时器，使用过程中会间断性的出现延迟问题，延迟时间 300ms 到 1000ms 不等。

在 X11 窗口中，鼠标坐标有时会出现偏移

与 LCUI 内部实际鼠标坐标不一致。

CSS样式匹配和阴影绘制有问题

本应作用于外面大框的样式居然能作用到子级部件上，阴影样式被取消后，阴影并未被抹除干净。

定时器操作有时会出现死锁，导致UI线程卡住

UI 线程和定时器线程都卡在上锁操作上。

靠近边缘的部件无法正常绘制阴影

阴影会被绘制成黑色透明色块。

textview 不支持透明色

使用 rgba(255,255,255,0.4) 这类值时，textview 上绘制的文本颜色并没有变化，但设置成 #fff 这类颜色时又有效果。

Add mouse wheel support for linux

MFC dependency in .rc file

There is #include "afxres.h" in LCUI.rc, which fails to build in VS without MFC installed. Is it intended?

reserved identifier violation

I would like to point out that an identifier like "__LCUI_WIDGET_EVENT_H__" does not fit to the expected naming convention of the C++ language standard.
Would you like to adjust your selection for unique names?

Improve input method support for windows [$20]

Problem

• The top left of the screen will display an input box.
• The candidate box is positioned at the top left of the screen.

Expected effect

• No additional controls will be displayed.
• The candidate box should be positioned at the text caret, like this:

---

IssueHunt Summary

1354092549 has been rewarded.

Backers (Total: $20.00)

• lc-soft ($20.00)

Submitted pull Requests

• #175 fix #36

---

Tips

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on IssueHunt to raise funds.

---

IssueHunt has been backed by the following sponsors. Become a sponsor

x64转换警告

使用VC++ x64编译出现大量warning C4267：

warning C4267: “=”: 从“size_t”转换到“int”，可能丢失数据
warning C4267: “return”: 从“size_t”转换到“int”，可能丢失数据
warning C4267: “=”: 从“size_t”转换到“unsigned int”，可能丢失数据
warning C4267: “=”: 从“size_t”转换到“int”，可能丢失数据
warning C4267: “初始化”: 从“size_t”转换到“int”，可能丢失数据
warning C4267: “函数”: 从“size_t”转换到“int”，可能丢失数据
warning C4267: “=”: 从“size_t”转换到“uint_t”，可能丢失数据

虽然x64看来没有被正式支持，不过还是暴露出一些可移植性问题。

linux 的控制台模式下，屏幕上无任何图形输出

需为 dirent.c 中的函数补充 linux 环境下实现

program received signal SIGTTOU, Stoped(tty output).

程序不能在设备上正常运行，因收到SIGTTOU信号导致程序终止，具体如下图所示：

需要解决此问题。

有没有考虑过做脚本语言绑定？

恩，就是不知道你的学习机的速度能不能跑脚本……介绍一下Lua：

编译以后总大小140K左右，占运行内存大概400K左右，速度上，大概比C慢50倍左右。

如果你的学习机跑的是linux，可以将你的LCUI编译为Lua的一个so库，在Lua中载入，可以支持所有功能。

脚本语言优势：

1. 快速开发：可以很快实现一个Demo，修改代码十分容易
2. 编写简单：代码量比C/C++等静态语言少，写起来快
3. 原型设计：很快能设计最终产品的一个原型
4. 效率评估：脚本语言比C慢，很容易显示出效率瓶颈的位置，可以在该位置用C优化
5. 架构评估：可以根据绑定时遇到的问题，判断架构本身是否良好。

恩，有兴趣可以去看看：www.lua.org

已设置背景图的部件在局部刷新时，没有绘制背景图

Complete build options for Pthread API

Would you like to add the configuration script "AX_PTHREAD" to your build specification?

Some memory leak bugs

需减少样式表的内存占用

一张样式表的固定内存占用大约为1000字节，而通常实际数据只占其中的一小部分，有些浪费，可考虑改用 Dict 结构存储。

需为部件类型添加原型继承功能，以方便实现部件的功能扩展

自定义的字体有时会无法正常加载，显示为空白

如下图所示：

默认字体能正常显示，而新引入的字体却无法显示。

Error occurs when building LCUI on GNU/Linux

I'm trying to build LCUI on my Fedora box but make fails, here is the error message in short:

catch_screen.c: In function 'catch_screen':
catch_screen.c:79:3: error: incompatible type for argument 1 of 'LCUIScreen_CatchGraph'
   LCUIScreen_CatchGraph( area, &graph );

and here is the full ouput

➜  LCUI git:(master) ✗ ./configure
...
Build with tslib support ........... : yes
Build with libpng support .......... : yes
Build with libjpeg support ......... : yes
Build with libiconv support ........ : no
Build with font-engine support ..... : none
Build with thread support .......... : pthread
Build with video support ........... : framebuffer

➜  LCUI git:(master) ✗ make
Making all in src
make[1]: Entering directory `/home/xcy/workspace/LCUI/src'
Making all in bmp
make[2]: Entering directory `/home/xcy/workspace/LCUI/src/bmp'
  CC       bmp.lo
  CC       jpeg.lo
  CC       png.lo
png.c: In function 'Graph_WritePNG':
png.c:124:29: warning: variable 'pos' set but not used [-Wunused-but-set-variable]
         int x, y, row_size, pos;
                             ^
  CC       load_image.lo
  CCLD     libbmp.la
make[2]: Leaving directory `/home/xcy/workspace/LCUI/src/bmp'
Making all in misc
make[2]: Entering directory `/home/xcy/workspace/LCUI/src/misc'
  CC       catch_screen.lo
catch_screen.c: In function 'catch_screen':
catch_screen.c:79:3: error: incompatible type for argument 1 of 'LCUIScreen_CatchGraph'
   LCUIScreen_CatchGraph( area, &graph );
   ^
In file included from catch_screen.c:46:0:
/home/xcy/workspace/LCUI/include/LCUI/LCUI_Display.h:82:14: note: expected 'struct LCUI_Graph *' but argument is of type 'LCUI_Rect'
 LCUI_API int LCUIScreen_CatchGraph( LCUI_Graph *graph, LCUI_Rect rect );
              ^
catch_screen.c:79:3: error: incompatible type for argument 2 of 'LCUIScreen_CatchGraph'
   LCUIScreen_CatchGraph( area, &graph );
   ^
In file included from catch_screen.c:46:0:
/home/xcy/workspace/LCUI/include/LCUI/LCUI_Display.h:82:14: note: expected 'LCUI_Rect' but argument is of type 'struct LCUI_Graph *'
 LCUI_API int LCUIScreen_CatchGraph( LCUI_Graph *graph, LCUI_Rect rect );
              ^
make[2]: *** [catch_screen.lo] Error 1
make[2]: Leaving directory `/home/xcy/workspace/LCUI/src/misc'
make[1]: *** [all-recursive] Error 1
make[1]: Leaving directory `/home/xcy/workspace/LCUI/src'
make: *** [all-recursive] Error 1

➜  LCUI git:(master) ✗ uname -a                  
Linux fedora 3.14.7-200.fc20.x86_64 #1 SMP Wed Jun 11 22:38:05 UTC 2014 x86_64 x86_64 x86_64 GNU/Linux

If you want to know more details please let me know.

windows 窗口内容时有时无，而且还会出现各种异常。

test.

部件数量达到1000个以上时会使界面越来越卡，直到卡死为止

这是 LCFinder 的测试结果，向部件里追加子部件时的速度感觉很慢，按理来说1000多个部件应该在几毫秒以内追加完才对，然而过了几十秒都没追加完。。。

x11 window title encoding bug

需为部件补充缺省样式

当部件添加新样式类然后删除该样式类时，部件已计算的样式依然是拥有样式类时的样式，因为移除样式类后，部件样式表里的一些样式属性已经失效，而计算样式时会忽略这些无效的样式属性，导致部分样式在计算后并未刷新。

malloc(): memory corruption (fast): 0x00007f5efe9e1710

#include <LCUI_Build.h>
#include LC_LCUI_H
#include LC_WIDGET_H 
#include LC_WINDOW_H
#include LC_BUTTON_H

static void
destroy( LCUI_Widget *widget, LCUI_WidgetEvent *unused )
{
    LCUI_MainLoop_Quit(NULL);
}

int main(void) 
{
    LCUI_Widget *window, *button;

    setenv( "LCUI_FONTFILE", "/home/zhuzx/NetBeansProjects/CGUI/fonts/simfang.ttf", FALSE );
    LCUI_Init();
    window  = Widget_New("window");
    button  = Widget_New("button");

    /* 设定窗口标题的文本 */
    Window_SetTitleText(window, "测试按钮"); 
    /* 改变窗口的尺寸 */
    Widget_Resize( window, Size(320, 240) );
    /* 将窗口客户区作为按钮的容器添加进去 */
    Window_ClientArea_Add( window, button );
    /* 居中显示按钮 */
    Widget_SetAlign( button, ALIGN_MIDDLE_CENTER, Pos(0, 0) );
    /* 禁用部件的自动尺寸调整 */
    Widget_SetAutoSize( button, FALSE, 0 );
    /* 自定义按钮的尺寸 */
    Widget_Resize( button, Size(180, 70) );

    /* 设定按钮上显示的文本内容，和label部件的用法一样,支持样式标签 */
    Button_Text( button, 
        "<size=30px><color=255,0,0>彩</color>"
        "<color=0,255，0>色</color>"
        "<color=0,0,255>的</color>"
        "<color=255,255,0>按</color>"
        "<color=255,255,255>钮</color></size>");

    /* 显示部件 */
    Widget_Show( button );
    Widget_Show( window ); 
    Widget_Event_Connect( Window_GetCloseButton(window), EVENT_CLICKED, destroy );
    return LCUI_Main(); /* 进入主循环 */
}

在载入包含多风格的字体文件时，默认不会选择 Regular 风格的字体

在 Ubuntu 系统下，NotoSansCJK.ttc 字体包含了 Thin、Regular、Bold、Italic、Bold Italic 等风格，然而载入字体文件时只默认选择了 Thin 风格，没选择 Regular 风格。

[gui] Add linear-gradient() for background-image

参考 css 的 linear-gradient()，只需实现最基本的从左至右、从上到下的颜色渐变绘制。

触屏的问题

如题，在LCUI初始化时检测触摸屏并启用触摸屏支持后，程序出现段错误后终止。

[css] Add @media queries to support responsive layout

An error occured when compiling a LCUI's sample on CentOS

I successfully compiled and installed LCUI library on CentOS 6.4 x86_64 (in the Oracle VirtualBox), but an error occured when compiling the "helloworld" sample (./test/helloworld.c).

LCUI version is the latest release: 0.15.

[root@bogon test]# gcc helloworld.c -l LCUI
/usr/local/lib/libLCUI.so: undefined reference to `clock_gettime'
collect2: ld 返回 1

GCC VERSION: 4.4.7

Thank you for the LCUI project and I wonder if you can help me.

当存在多个同级部件时绘制会有问题