Skip to content

README_zh.md

Latest commit

 

History

History
199 lines (175 loc) · 13.7 KB

README_zh.md

File metadata and controls

199 lines (175 loc) · 13.7 KB

php-libui

PHP 绑定 libui 的 C 库.

libui 一个轻量级的且可移植的GUI库，其使用了原生的GUI技术为每一个平台提高支持

必须

  • PHP >= 8.1
  • PHP FFI 扩展可用
  • libui 最新版本

A Simple Example

比较完整的例子 https://github.com/chopins/http-request 首先从 https://github.com/andlabs/libui/releases 下载 libui 动态库，或者检出代码自行编译，然后使用后面例子的方法加载

include '/src/UI.php';
$ui = new \UI\UI('/usr/lib64/libui.so'); //加载 libui 动态库
$ui->init();
$mainwin = $ui->newWindow("libui Control Gallery", 640, 480,1);
$ui->controlShow($mainwin);
$ui->main();

注意：访问libui C 函数时，函数名需去掉ui前缀，然后首字母小写

使用 UIBuild 创建UI

基本用法:

include '/src/UI.php';
$ui = new \UI\UI('/usr/lib64/libui.so');
$config = ['title' => 'test', 'width' => 600,'height' => 450];//UI 配置数组
$build = $ui->build($config);
$build->show();

构建配置数组结构

  • 配置文件现在支持XML结构，例子见tests/uibuild.xml
  • XML配置，事件属性名必须以on开头，值为callable,无需Event, 值支持$var,func_name,CLASS::method几种模式，不支持数组
  • 属性值支持php GLOBALS变量与常量，分别以$``@开头， 类似 $var @CONST
  • 构建配置数组第一层包含body menu 以及 window 属性；在配置数组中键为属性，值为属性值。 类似后面代码所展示的结构。
[
    'title' => 'window title name',
    'width' => 600,
    'menu' => [],
    'body'  => [
        'name' => 'box'
        'childs' => []
    ]
]

window 属性列表:

属性名 类型 描述 默认值
title string window title No Win Title
width int window width 800
height int window height 640
border int window border 0
margin int window margin 0
quit \UI\Event quit callback null
close \UI\Event close callback null
resize \UI\Event resize callback null

菜单数组 menu

这个数组中的每一个元素为一个菜单配置，结构类似：

[
    [
        'title' => 'File',
        'id'    => 'menu_id_1',
        'childs' => [
            ['title' => 'New File'],
            ['title' => 'Open File'],
        ]
    ],
    [
        'title' => 'Edit',
        'id'    => 'menu_id_1',
        'childs' => [
            ['title' => 'Undo'],
            ['title' => 'Copy'],
        ]
    ],
]

顶级菜单只有 title, id, childs 几个子键(属性), title值为菜单名,childs数组是子菜单即下拉菜单。如果childs的元素是字符串且等于hr将显示分割线 当前UI配置中的菜单只支持下面的属性:

属性 类型 描述 必须
title string menu title yes
type string menu type, value is text,quit,about,preferences or checkbox, default is text no
click \UI\Event click callback no
childs array child menu list no

body 数组

body数组的每一个元素为一个UI控件的配置，元素的widget子元素为控件名，attr子元数为配置。见examples/table.php。当前 Build UI 配置只支持入如下控件名，

  1. button, Button control,包含下面的属性:

    属性名 类型 描述 必须
    type string 控件类型，类似HTML的<button>标签的type属性，可能值如下:
    2. file, open file button
    1. save, save file button
    2. font, select font button
    3. color, select color button
    3. button, is default value    		 yes
    title string button label name yes
    chick \UI\Event when click callback, 当type为 file 或 save 时，选择文件后会被调用，并会将文件名传给回调函数 no
    change \UI\Event only when color and font available, select color or font be call no

  2. box 盒布局 ,the following attr:

    属性名 类型 描述 必须
    dir string layout direction, Specify one of h is horizontal and default value, v is vertical yes
    padded int padding value, default is 0 no
    child_fit bool Whether to automatically adapt no
    childs array sub control list no

  3. group 组布局, have title and margin, child attr

  4. label 文本标签控件, only has title attr

  5. hr 水平分割线, no attr

  6. vr 垂直分割线, no attr

  7. input 输入类控件, the following attr:

    属性名 类型 描述 必须
    type string 类似HTML的<input>标签的type属性，specify one of the following value:
    1. password password entry control
    2. search search entry control
    3. textarea multiline entry control
    4. radio radio
    5. select select
    6. checkbox checkbox
    7. text, is default value
    		 yes
    readonly bool no
    wrap bool only textarea is available, false is non wrapping textarea no
    option array radio and select available,element value is option title, key is natural order number no
    change \UI\Event exclude checkbox and radio no
    title string checkbox` available no
    click \UI\Event only radio and checkbox available no

  8. form 表单布局, has padded, childs attr, 添加的子控件具备label属性

  9. grid 网格布局, the following attr:

属性名 类型 描述 必须
padded int no
child_left int no
child_top int no
child_width int no
child_height int no
child_hexpand int no
child_halign int no
child_vexpand int no
child_valign int no
childs array no
  1. table 表格控件, table cell has change event has following sub key :
属性名 类型 描述 必须
th array every element of value is array, key is id, has the following attr:
1. editable, bool type, the column is whether editable
2. textColor
3. title
4. type, specify value of button, image, imgtext, progress, checkbox, checkboxtext, color, text		 yes
tbody array the table row value list, every element is one row value, when row of column is array has the following attr:
1. image type, has src width height
2. color type has r,g,b
3. rowBgcolor
4. change is array, every element is one row change callback list, column is callable		 yes
表格单元格变更回调函数签名如下:
  1. tab 可切换页控件, has page sub array, page array every element value is page child control and page control has title attr
  2. img 图片控件， has flowing attr:
属性 类型 描述 必须
src array is image paths list, every element value is image file path, key is natural order number yes
width int the image control width, default is src first element image width no
height int the image control heigth, default is src first element image width no

  1. datetime datetime control

    attr type description require
    type string specify one of value time,date,datetime yes
    change \UI\Event no
    id string no

  2. progress, has id attr

  3. 构建配置未支持控件使用UI\UI直接访问libui C 函数

  4. UI\Event, all event callback class, The signature of the callback is as follows:

/**
 * @param UI\Event $callable   The object instance of current event 
 * @param UI\Control $widget  The Control object of trigger widget
 * @param $data         passed data
 * 
 * */
function (UI\Event $callable) {}

Control common method:

  • show()
  • hide()
  • enable()
  • disbale()
  • destroy()
  • parent()
  • setParent($parent)
  • isVisible()
  • isEnabled()

specify control see class statement in control directory

UI method

see UI.php

UIBuild method

see UIBuild.php