sg-flex

A Flexbox node for Roku's SceneGraph.

• Install
  • With ropm
  • Manual install
• Usage
  • Directly in your XML
  • Or programatically
• API
• Current Limitations
• Running the test project
  • Option 1: Sideload the application
  • Option 2: Use VSCode
• Questions and suggestions
• Contributing

Install

With ropm

(tbd)

Manual install

Grab our latest release from our Releases page and copy the contents of the components and source folders into the root of the equivalent folders in your application. Remember to update the import scripts if you copy them anywhere else.

Usage

Directly in your XML

<SGFlex
    id="sgFlex"
    direction="row"
    justifyContent="spaceBetween"
    alignItems="center"
    width="1790"
    height="596"
    translation="[64, 101]"
>
    <Rectangle width="170" height="170" color="0xA90F0F">
        <Label text="0" />
    </Rectangle>
    <Rectangle width="170" height="170" color="0x2B9857">
        <Label text="1" />
    </Rectangle>
    <Rectangle width="170" height="170" color="0x2B4A98">
        <Label text="2" />
    </Rectangle>
</SGFlex>

Or programatically

m.sgFlex = CreateObject("roSGNode", "SGFlex")

' Consider that `flexify()` will be called for each of these assignments.
m.sgFlex.width = 1790
m.sgFlex.height = 596
m.sgFlex.direction = "row"
m.sgFlex.justifyContent = "spaceBetween"
m.sgFlex.alignItems = "center"

r1 = CreateObject("roSGNode", "Rectangle")
r1.width = 170
r1.height = 170

r2 = r1.clone()
r3 = r1.clone

m.sgFlex.appendChild(r1)
m.sgFlex.appendChild(r2)
m.sgFlex.appendChild(r3)

' Call flexify again due to limitation #1
m.sgFlex.callFunc("flexify")

API

• width and height: Dimensions of the flex container. If missing, they will be replaced by the accumulated width and height of the children.

• direction: The direction of the main axis.

  • row (default)
  • column

• justifyContent: The flex alignment of the main axis.

  • flexStart (default)
  • flexEnd
  • center
  • spaceBetween
  • spaceAround
  • spaceEvenly

• alignItems:

  • flexStart (default)
  • flexEnd
  • center

• flexifyOnce: A boolean value indicating if the SGFlex node should only call flexify() once. If true, the node will ignore all the function calls to flexify() except the first one.

• flexify(): Call this function every time you want to re calculate and apply the children alignments.

Current Limitations

• The SGFlex node is not reactive to changes to its children. To update the layout you need to call the flexify function.

• The SGFlex node assumes its children have their coordinate center at the top left. Otherwise they will not be properly aligned.

  • For example LayoutGroup nodes with values other than horizAlignment="left" and vertAlignment="top" will not be laid out properly. Same for Label nodes with values other than horizAlign="left" and vertAlign="top".
  • Consider replacing LayoutGroup nodes with SGFlex nodes to aleviate this.

• There are no flexbox-like capabilities for the children (e.g: order or alignSelf).

Running the test project

Option 1: Sideload the application

Grab the test-project.zip file from our latest release on the Releases page and sideload it into your Roku device following these instructions.

Option 2: Use VSCode

1. Make sure you have the BrightScript Language extension installed.

Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.

ext install RokuCommunity.brightscript

2. Clone this repository

git clone https://github.com/haystacknews/sg-flex.git

3. Install the project dependencies (preferibly with Node >=16.14.2 and NPM >=8.5.0)

npm install

3. Go to Run and Debug on the Activity Bar and Start debugging with the option Launch Test App.

The preLaunchTask might take a bit to load because it copies the file structure of the test project into a separate folder and runs ropm install every time.

Questions and suggestions

Hi! I'm Arturo Cuya, the main contributor of this project. If you have a question on how to use sg-flex or a suggesion on how to improve it, consider one of the following communication channels:

1. Create an issue explaining your question or asking for a feature; or
2. Ping me on the Roku Developers Slack

Contributing

todo: explain this nicely

• Remember to fork this repo and making a PR from yours into this instead of pulling this repo and doing modifications directly.

• Use this node environment

"engines": {
  "node": ">=16.14.2",
  "npm": ">=8.5.0"
},

• Use BrighterScript

• Switch between developing the component and the test project by changing the rootDir in bsconfig.json

• Testing is done with roca and brs, using a BrighterScript plugin located in bsconfig/plugins to disable features not supported by brs. Run the tests with npm run test