Page MenuHomePhabricator

UI Builders Format
Updated 1,076 Days AgoPublic

Brief

We want to define a common format for the tools dealing with applications widgets descriptions.
I've not fully switched to interfaces, so some points could be not relevant. Please correct.

Requirements

  • Supports Eolian properties, enums, bit-wise operations for enums,...
  • Easy to write by hands
  • Easy to parse

Format rules

  • Python-like format with 4-spaces indentation
  • Boolean properties which don't provide value are interpreted as true
  • [] brackets are used for parameter values: size=[100, 100]
  • # Comments support is needed
  • Comments are parsed as objects or object's property

Reserved words (constants)

  • true/false
  • expand, fill (or these will be taken from Eolian)
  • on - for callbacks

Objects format

Objects are nested.

box(id="page1")
    box
        image(size=[100, 3000], position = [4, 5])

Properties format

Properties must use Eolian names.

button(id="button_2", visible, part_text["part"] = "text")

Properties can be multiple: t.e. part_text for toggle.

check(id="toggle_1", visible, style="toggle", part_text["on"] = "ON", part_text["off"] = "OFF")

Content format

Nesting is used to describe content behaviour.
Packing functions should be marked with special flag (e.g. @ packer) in Eolian.
Parser should have additional info file to describe packing rules for the cases when no explicit packing command is used - such cases as window, box.

Examples:

#pack object into table
table(padding=[4,5])  
    pack[0,0,1,1]: image(id="contact_image1")

#pack object into Part Container
panes
    part["left"]: image(id="contact_image1")

# Pack into Window, Box
window(id="window 1")
    box(id="box_1")
        image(id="contact_image1")
        table(padding=[4,5])

Callbacks

Starts with keyword 'on'.
UI context will be passed as data into callback.

button(id="button_2", visible, part_text = "Button 2")
    # call "callback_name" func
    on("clicked", "callback_name")

Items

For Toolbar, Menu and other widgets.

toolbar(id = "toolbar", horizontal, shrink_mode = menu, select_mode = always, visible)
    item(icon = "edit_undo", label = "Undo", disabled)
    item(icon = "edit_redo", label = "Redo")
        on("clicked", "redo_cb")
    item(separator)
    separator

Resources

Resource files should be marked like this (to decide):

  • res("path/layout.edj")
  • "@ data/path/layout.edj"
  • @"path/layout.edj"

Example:

window
    layout(file=res("path/layout.edj"))
        part["a"]: button(icon = res("path/logo.png"))

Snippets

The idea is to define reusable object, which can be used later in code.

box(id="mybox")
    button(id="but1")
    image(id="img1")

window
    layout
        part["a"]: snippet("mybox1")
        part["b"]: snippet("mybox2")

But it looks useless if snippet can not be customized. So it can be used like this to define properties for each widget inside snippet

part["b"]: snippet.mybox (id="mybox1")
                      but1(text = "text")
                          on("clicked", "func_name")
                      img1(file = res("logo.png"))

When project is opened in Gui Builder:

  • if snippet is changed - all snippet instances will be changed
  • if one instance of snippet is changed(order or new widget added, not properties) - unwrapped code will be generated

Example:

window
    layout
        part["a"]: snippet("mybox1")
        part["b"]: box(id="mybox2")
                              button
                              Image
                              button

Issues/To discuss/To remember

  • Order matters for some properties. i.e. style = "toggle" converts Elm.Check into Toggle. Assigning text to parts "on"/"off" can be made only after style. This means that order matters. Some rule must exist(in UI builder) to generate current format, C, JS, or other in proper order. This also must be stated in docs for handwriting current file.

Next steps

  • Snippets - improve syntax
  • Add your own thoughts.

Format example

#version = 1

box(id="page1")
    image(size=[100, 3000], position = [4, 5])

window(id="window 1", visible)
    box(id="box_1", horizontal, size_hint_weight = [expand, expand], size_hint_align = [fill, fill])
    table(padding=[4,5])
      # this is meant to create a comment object
      # and this is part of the comment above
        pack[0,0,1,1]: image (id="contact_image1", size=[300, 400], position[10, 10], visible) # this is meant to do this
        pack[1,1,1,1]: image (id="contact_image2", path=res("image.jpg")) # this is a comment that is set in the eo object

   button(id="button_1", visible, part_text = "Button 1", disabled)
   # How to describe translatable text
   button(id="button_2", visible, part_text = _"Button 2")
   # How to describe text part
   button(id="button_2", visible, part_text["part"] = _"Button 2")
       on("clicked", "callback_name")
       # Erigo supports callbacks which can modify existing elements.
       on clicked(contact_image4.visible = true, contact_image4.size = [100, 100])
   toolbar(id = "toolbar", horizontal, shrink_mode = menu, select_mode = always, visible)
       item(icon = "edit_undo", label = "Undo")
       item(icon = "edit_redo", label = "Redo")
         on("clicked", "redo_cb")
       item(separator)
       separator

    naviframe
        item(label = "item1")
            part["prev"]: button(id="but_prev")
            part["next"]: button(id="but_next")
            part["content"]: image(id="img_content")
Last Author
yakov-g
Last Edited
Apr 12 2016, 4:43 AM
Projects
None
Subscribers
felipealmeida, JackDanielZ, jpeg and 8 others