UI使用规范

文件命名规范

• json文件名 json中的namespace python文件名 三者需要一致
• 示例中为"myUIName"

​x
    myUIName.json
​
    "namespace" : "myUIName"
​
    myUIName.py
​

JSON规范

Json是UI界面的显示内容和绑定的集合，UI是一种树状的组织结构，界面和界面中的控件都是一个UI Node节点，后续的很多方法的调用也需要这个树状结构的路径来标识。

• 注：暂时Json只能通过手写来构筑界面，后续会开放相应的UI编辑器供开发者使用。

命名空间

命名空间是这个界面的名称，我们规定json文件名和namespace一致。

xxxxxxxxxx
    "namespace" : "myUIName"

Main Screen

main是这个界面名称，我们规定使用main，即一个json文件是一个界面。

controls中的内容是该界面下的树状节点，即子节点。

xxxxxxxxxx
    "main@common.base_screen" : {
        "controls" : [
        ]
    }

xxxxxxxxxx
my_namespace
|____main
     |test_image
     |test_panel
              |test_label

• 关于控件的适配问题，固定大小像素能在屏幕像素发生变化时保持形状大小不变，而百分比则能够保持与屏幕分辨率一致的比例，可能导致控件变形。

控件介绍

Label

Label 是文本框控件，用来显示文本信息，默认的字体是MC字体，如果有中文会变成中文字体格式，暂时不支持换字体，可以通过接口统一设置字体，如果需要设置后续有介绍。

xxxxxxxxxx
   "label" : {
      "anchor_from" : "top_left",
      "anchor_to" : "top_left",
      "auto_expand" : false,
      "color" : [ 1, 1, 0, 0.8],
      "font_size" : "large",
      "layer" : 5,
      "offset" : [ "0%+0px", "0%+0px" ],
      "shadow" : false,
      "size" : [ "83.80282%+0px", "100%+0px" ],
      "text" : "Hello World",
      "text_alignment" : "center",
      "type" : "label",
      "visible" : true
   },

Image

Iamge是在UI中的图片控件，可以动态设置控件的图片，该种控件的特点是会保持图片的形状进行拉伸，重复的变量不再重复解释。

xxxxxxxxxx
   "image" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "layer" : 1,
      "nineslice_size" : 0,
      "offset" : [ 0, 0 ],
      "size" : [ "20.000000%+0 px", "20.000000%+0px" ],
      "texture" : "textures/fish",
      "type" : "image",
      "uv" : [ 0, 0 ],
      "uv_size" : [ 16, 16 ],
      "visible" : true
   }

NineSliceImage

NineSliceImage是指九宫格图片空间，可以动态设置控件图片，该控件相比Image会随着拉伸改变九宫格的形状，该九宫格只显示切片后中心宫的内容。

xxxxxxxxxx
   "nine_slice_iamge" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "is_new_nine_slice" : true,
      "layer" : 1,
      "nine_slice_bottom" : 0,
      "nine_slice_left" : 0,
      "nine_slice_right" : 0,
      "nine_slice_top" : 0,
      "offset" : [ 0, 0 ],
      "size" : [ "20.000000%+0 px", "30.000000%+0px" ],
      "texture" : "textures/items/fish",
      "type" : "image",
      "visible" : true,
   }

Image Button

ImageButton 是指可以动态设置贴图的按钮，同时含有NineSliceImage和Label。按钮有三种状态，分别为default/hover/pressed，可以分别对应不同的贴图。

• 注 $符号表示定义变量
• controls表示控制的子节点，

xxxxxxxxxx
   "button@common.button" : {
      "$default_color" : [ 1, 1, 1 ],
      "$default_texture" : "textures/common/button/btn01",
      "$hover_texture" : "textures/common/button/btn02",
      "$pressed_texture" : "textures/common/button/btn03",
      "$labelText" : "hello",
      "$label_font_size" : "large",
      "$nine_slice_bottom" : 0,
      "$nine_slice_left" : 0,
      "$nine_slice_right" : 0,
      "$nine_slice_top" : 0,
      "$text_offset" : [ 0, 0 ],
      "anchor_from" : "center",
      "anchor_to" : "center",
      "is_handle_button_move_event": true, 
      "button_mappings": [], 
      "controls" : [
         {
            "default" : {
               "is_new_nine_slice" : true,
               "layer" : 2,
               "nine_slice_bottom" : "$nine_slice_bottom",
               "nine_slice_left" : "$nine_slice_left",
               "nine_slice_right" : "$nine_slice_right",
               "nine_slice_top" : "$nine_slice_top",
               "texture" : "$default_texture",
               "type" : "image"
            }
         },
         {
            "hover" : {
               "is_new_nine_slice" : true,
               "layer" : 2,
               "nine_slice_bottom" : "$nine_slice_bottom",
               "nine_slice_left" : "$nine_slice_left",
               "nine_slice_right" : "$nine_slice_right",
               "nine_slice_top" : "$nine_slice_top",
               "texture" : "$hover_texture",
               "type" : "image"
            }
         },
         {
            "pressed" : {
               "is_new_nine_slice" : true,
               "layer" : 2,
               "nine_slice_bottom" : "$nine_slice_bottom",
               "nine_slice_left" : "$nine_slice_left",
               "nine_slice_right" : "$nine_slice_right",
               "nine_slice_top" : "$nine_slice_top",
               "texture" : "$pressed_texture",
               "type" : "image"
            }
         },
         {
            "button_label" : {
               "color" : "$default_color",
               "font_size" : "$label_font_size",
               "layer" : 3,
               "max_size" : [ "100%", "100%" ],
               "offset" : "$text_offset",
               "shadow" : false,
               "text" : "$labelText",
               "type" : "label"
            }
         }
      ],
      "layer" : 1,
      "offset" : [ 0, 0 ],
      "size" : [ "15.000000%+0 px", "10.000000%+0px" ],
      "visible" : true
   }

Panel

panel为面板控件，主要是用来将控件进行分类和管理，类似文件夹。

xxxxxxxxxx
   "panel" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "layer" : 0,
      "offset" : [ 0, 0 ],
      "size" : [ "50.000000%+0 px", "50.000000%+0px" ],
      "type" : "panel",
      "visible" : true
   }

TextEditBox

TextEditBox是输入框控件，用来输入文字信息，可以获取输入内容，设置输入框内容，触发输入中和输入完成事件，设置最大输入值等。下面的示例展示了一个搜索框的信息。

xxxxxxxxxx
  "search_panel": {
   "type": "panel",
   "anchor_from" : "top_left",
   "anchor_to" : "top_left",
   "offset" : [ "7.21832%+0px", "50%+0px" ],
   "size" : [ "83.80282%+0px", "10.31250%+0px" ],
   "$text_edit_clipping_panel_size": [ "100% - 23px", "100%" ],
   "$text_edit_box_label_anchor_point": "left_middle",
   "controls": [
     {
       "search_text_box@common.text_edit_box": {
         "max_length": 3,
         "$text_box_name": "%test_screen.TextBox",
         "$text_edit_box_enabled_binding_type": "none",
         "$text_edit_box_content_binding_name": "#test_screen.ReturnTextString",
         "$place_holder_text": "#test_screen.ReturnHolderContent",
         "$text_edit_box_placeholder_content_binding_name": "#test_screen.ReturnHolderContent",
         "$enabled": true
       }
     },
     {
       "clear_button@common.close_button": {
         "anchor_from": "right_middle",
         "anchor_to": "right_middle",
         "visible": true,
         "layer": 2,
         "focus_enabled": true,
         "$close_button_offset": [ -2, 0 ],
         "button_mappings": [
           {
             "from_button_id": "button.menu_select",
             "to_button_id": "%test_screen.ClearButtonClick",
             "mapping_type": "pressed"
           },
           {
             "from_button_id": "button.menu_ok",
             "to_button_id": "%test_screen.ClearButtonClick",
             "mapping_type": "focused"
           }
         ]
       }
     },
     {
        "test_label@test_screen.test_label" : {}
     }
   ]
 }

• 注1

xxxxxxxxxx
class TestScreen(ScreenNode):
    def __init__(self, namespace, name, param):
        ScreenNode.__init__(self, namespace, name, param)
        self.text = ""
        self.holder = str("请输入姓名")
    
    @ViewBinder.binding(ViewBinder.BF_EditChanged | ViewBinder.BF_EditFinished)
    def TextBox(self, args):
        print "SearchTextBox  ", args
        self.text = args["Text"]
        return ViewRequest.Refresh
​
    @ViewBinder.binding(ViewBinder.BF_InteractButtonClick)
    def ClearButtonClick(self, args):
        self.text = ""
        return ViewRequest.Refresh
​
    @ViewBinder.binding(ViewBinder.BF_BindString)
    def ReturnTextString(self):
        return self.text
​
    @ViewBinder.binding(ViewBinder.BF_BindString)
    def ReturnHolderContent(self):
        return self.holder

• 注2

max_length 可以通过接口SetEditTextMaxLength，接口详细调用可见下文。

注意：输入框不允许在inputmode为0的情况下使用。

创建带输入框的UI时inputmode必须要为1，如：

clientApi.CreateUI("testMod", "testUI", {"inputMode":1})

PaperDoll

该控件可以用于在ui上显示骨骼模型

xxxxxxxxxx
"paper_doll0" : {
    "anchor_from" : "center",
    "anchor_to" : "center",
    "bindings" : [
     {
        "binding_type": "view",
        "source_control_name": "paper_doll0_skin_viewer_panel",
        "source_property_name": "#gesture_delta_source",
        "target_property_name": "#gesture_delta_source"
    },
     {
        "binding_type" : "view",
        "source_control_name" : "paper_doll0_skin_viewer_panel",
        "source_property_name" : "#gesture_mouse_delta_x",
        "target_property_name" : "#gesture_mouse_delta_x"
     }
    ],
    "controls" : [
     {
        "paper_doll0_skin_viewer_panel" : {
           "anchor_from" : "bottom_middle",
           "anchor_to" : "bottom_middle",
           "button_mappings" : [
              {
                 "button_up_right_of_first_refusal" : true,
                 "from_button_id" : "button.menu_select",
                 "mapping_type" : "pressed",
                 "to_button_id" : "button.turn_doll"
              }
           ],
           "gesture_tracking_button" : "button.turn_doll",
           "layer" : 3,
           "offset" : [ 0, 0 ],
           "size" : [ "100%+0px", "100%+0px" ],
           "type" : "input_panel",
           "visible" : true
        }
     }
    ],
    "property_bag":{
        "#skin_rotation": true,
        "#custom_rot_y": 90
    },
    "layer" : 1,
    "offset" : [ "0.00000%+0px", "1.66667%+0px" ],
    "renderer" : "paper_doll_renderer",
    "rotation" : "gesture_x",
    "modelname": "xuenv",
    "animation": "idle",
    "modelsize": 1.0,
    "size" : [ "19.37500%+0px", "50.27777%+0px" ],
    "type" : "custom",
    "visible" : true
}

ScrollView

该控件是可以滑动的窗口，需要有其他控件附属。

xxxxxxxxxx
   "first_scroll_panel@common.scrolling_panel" : {
      "$scroll_bar_right_padding_size" : [ 0, 3 ],
      "$scroll_box_mouse_image_control" : "common-classic.button_state_default",
      "$scroll_size" : [ 0, "100.000000%+0px" ],
      "$scroll_view_name" : "scroll_view",
      "$scrolling_content" : "test_screen.first_stack_grid",
      "$scrolling_pane_offset" : [ -3, 0 ],
      "$scrolling_pane_size" : [ "100.000000%+0 px", "100.000000%+0px" ],
      "$show_background" : false,
      "anchor_from" : "right_middle",
      "anchor_to" : "right_middle",
      "layer" : 2,
      "offset" : [ "-9.500000%+0 px", "3.000000%+0px" ],
      "size" : [ "37.67606%+0px", "66.87500%+0px" ],
      "visible" : true
   },

StackGrid

该控件可以依附在滚动条中，用来实现背包等功能。

xxxxxxxxxx
   "first_stack_grid" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "bindings" : [
         {
            "binding_condition" : "always",
            "binding_name" : "#first_stack_grid.item_count",
            "binding_name_override" : "#StackGridItemsCount"
         }
      ],
      "collection_name" : "hugo_first_scroll",
      "controls" : [
         {
            "first_stack@test_screen.first_stack" : {}
         }
      ],
      "item_count" : 8,
      "layer" : 0,
      "orientation" : "vertical",
      "property_bag" : {
         "#first_stack_grid.item_count" : 8
      },
      "size" : [ "100%", "default" ],
      "type" : "stack_grid",
      "visible" : true
   },

Grid

Grid组件类似于上面的StackGrid组件，属于网格型的排列。

xxxxxxxxxx
   "grid0" : {
      "anchor_from" : "center",
      "anchor_to" : "center",
      "bindings" : [
         {
            "binding_condition" : "always",
            "binding_name" : "#grid0.grid_dimension_binding",
            "binding_name_override" : "#GridItemsCount"
         }
      ],
      "collection_name" : "hugo_grid",
      "grid_dimension_binding" : "#grid0.grid_dimension_binding",
      "grid_dimensions" : [ 2, 2 ],
      "grid_item_template" : "test_screen.item_content0",
      "layer" : 1,
      "offset" : [ "0%+0px", "0%+0px" ],
      "size" : [ "35.73944%+0px", "33.75000%+0px" ],
      "type" : "grid",
      "visible" : true
   },

Python规范

必要的属性

xxxxxxxxxx
import client.extraClientApi as clientApi
ViewBinder = clientApi.GetViewBinderCls()
ViewRequest = clientApi.GetViewViewRequestCls()
ScreenNode = clientApi.GetScreenNodeCls()

UI界面初始化

xxxxxxxxxx
class TestScreen(ScreenNode):
    def __init__(self, namespace, name, param):
        ScreenNode.__init__(self, namespace, name, param)

ScreenNode是我们的UI节点基类，必须继承。

xxxxxxxxxx
# Bind Type
class ViewBinder(object):
    ButtonFilter = 0x10000000
    BF_ButtonClickUp    =   0 | ButtonFilter
    BF_ButtonClickDown  =   1 | ButtonFilter
    BF_ButtonClick      =   2 | ButtonFilter
    BF_ButtonClickCancel=   3
    BF_InteractButtonClick = 4
    BindFilter = 0x01000000
    BF_BindBool     = 5 | BindFilter
    BF_BindInt      = 6 | BindFilter
    BF_BindFloat    = 7 | BindFilter
    BF_BindString   = 8 | BindFilter
    BF_BindGridSize = 9 | BindFilter
    BF_BindColor    = 10 | BindFilter
    EditFilter = 0x00100000
    BF_EditChanged  = 11 | EditFilter
    BF_EditFinished = 12 | EditFilter
# Return Type
class ViewRequest(object):
    Nothing = 0
    Refresh = 1 << 0
    PointerHeldEventsRequest = 1 << 1
    PointerHeldEventsCancel = 1 << 2
    Exit = 1 << 3  
​

UI绑定和返回

UI的绑定分为binding单个绑定和binding_collection集合绑定，适合集合容器。

binding(bind_flag, binding_name = None)

bind_flag为上文中绑定类型，binding_name为绑定名称。

binding_name为脚本绑定变量，binding_name_override为引擎变量，json格式如下

xxxxxxxxxx
      "bindings" : [
         {
            "binding_condition" : "always",
            "binding_name" : "#scoreboard_grid.item_count",
            "binding_name_override" : "#StackGridItemsCount"
         }
      ]

对应的Python代码如下

xxxxxxxxxx
    @ViewBinder.binding(ViewBinder.BF_BindInt, "#scoreboard_grid.item_count")
    def OnStarkGridResize(self):
        return len(self.scoreBoardList)

binding_collection(bind_flag, collection_name, binding_name = None)

bind_flag为上文中的绑定类型，collection_name为集合名称，binding_name为绑定的变量名称。

集合的json如下：

xxxxxxxxxx
"collection_name" : "scoreboard_stackgrid"

在集合的子控件中，binding_collection_name为集合名，binding_condition为绑定条件，binding_name为绑定名称，binding_type为collection绑定，property_bag设置他的初始值，text为它的绑定值。

xxxxxxxxxx
   "label_score_board" : {
      "bindings" : [
         {
            "binding_collection_name" : "scoreboard_stackgrid",
            "binding_condition" : "always",
            "binding_name" : "#label_score_board.text",
            "binding_type" : "collection"
         }
      ],
      "offset" : [ "0%+0 px", "0%+0px" ],
      "property_bag" : {
         "#label_score_board.text" : "666666666666"
      },
      "text" : "#label_score_board.text",
      "text_alignment" : "left",
      "type" : "label",
      "visible" : true
   },

对应的Python代码如下，其中index表示在集合中的哪一元素。

xxxxxxxxxx
    @ViewBinder.binding_collection(ViewBinder.BF_BindString, "scoreboard_stackgrid", "#label_score_board.text")
    def OnRefreshScoreBoardLabel(self, index):
        return self.scoreBoardList[index] if len(self.scoreBoardList) > index else ""

调用规范

参数命名规范

@Mod.Binding(name = myModName, version = myModVersion)

假设设置Mod名称为"myModName"，示例：

xxxxxxxxxx
    @Mod.Binding(name = "myModName", version = "0.1")
    class MyModClass(object):
        def __init__(self):
            pass

注册UI界面

RegisterUI(myModName, key, clsPath, uiDef)

该函数用来，示例：

xxxxxxxxxx
    import client.extraClientApi as clientApi
    clientApi.RegisterUI("myModName", "myUIName", "myScripts.modClient.ui.myUIName.MyUIClass", "myUIName.main")

创建UI界面

CreateUI(myModName, key, paramDict=None)

xxxxxxxxxx
    import client.extraClientApi as clientApi
    clientApi.CreateUI("myModName", "myUIName", {"isHud" : 1})

获取UI界面

GetUI(myModName, key)

获取UI结点，该结点就是python类的实例，示例：

xxxxxxxxxx
    import client.extraClientApi as clientApi
    uiNode = clientApi.GetUI("myModName", "myUIName")

删除UI界面

uiNode.SetRemove()

xxxxxxxxxx
    import client.extraClientApi as clientApi
    uiNode = clientApi.GetUI("myModName", "myUIName")
    uiNode.SetRemove()

xxxxxxxxxx
从上面获取的UI结点删除界面，会调用node的Destroy()方法。

• 注意 单个json界面内的layer值应小于1000

生命周期函数

生命周期函数会被自动在以下情况下调用，重写函数可以完成一些逻辑。

下面是一些示例：

xxxxxxxxxx
    def Create(self):
        print "================ fpsui create "
        clientApi.HideHudGUI(False)
        comp = clientApi.CreateComponent(clientApi.GetLevelId(), "Minecraft", "operation")
        comp.all = True
        clientApi.NeedsUpdate(comp)
​
    def OnActive(self):
        print "================ fpsui OnActive "
        clientApi.HideHudGUI(False)
        comp = clientApi.CreateComponent(clientApi.GetLevelId(), "Minecraft", "operation")
        comp.all = True
        clientApi.NeedsUpdate(comp)
​
    def OnDeactive(self):
        print "================ fpsui OnDeactive "
        clientApi.HideHudGUI(True)
        comp = clientApi.CreateComponent(clientApi.GetLevelId(), "Minecraft", "operation")
        comp.all = False
        clientApi.NeedsUpdate(comp)
​
    def Destroy(self):
        print "================ fpsui Destroy "
        clientApi.HideHudGUI(False)
        comp = clientApi.CreateComponent(clientApi.GetLevelId(), "Minecraft", "operation")
        comp.all = True
        clientApi.NeedsUpdate(comp)