Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Controls

Controls are the views you type into and move through.

ito.TextField(state)

A line you type into. state comes from ito.state and holds the text, so typing changes state.value and setting state.value changes the line.

ModifierEffect
:placeholder(text)Shows text dimmed while the line is empty.
:hidden()Draws the theme’s mask symbol for each character, for secrets.
:on_submit(handler)Calls handler(text) when you press Enter.
:focused()Asks for the keys when the field first shows.

Typed characters go in at the cursor. Left, Right, Home and End move the cursor, and Backspace and Delete erase. ito.TextField raises an error when state is not a state.

local ito = require("ito")

uji.command.add("branch", {
  desc = "create a branch",
  handler = function()
    local overlay
    overlay = uji.ui.overlay(function()
      local name = ito.state("")
      return ito.VStack({
        ito.Text("New branch"):bold(),
        ito.TextField(name):placeholder("feature/name"):focused():on_submit(function(text)
          overlay:close(text)
        end),
      }):padding({ horizontal = 1 }):border(ito.theme().borders.rounded)
    end)
    local branch = overlay:wait()
    if branch and branch ~= "" then
      uji.session.submit("Create the branch " .. branch .. " and switch to it.")
    end
  end,
})

ito.List(items, row)

Shows items, one row for each. ito calls row(item, index, selected) to build each row as a view, and only for the rows that fit. selected is true for the chosen row. The list scrolls to keep the chosen row in view.

ModifierEffect
:selection(state)Keeps the chosen index in a state, so you can read or set it. Without it, the list keeps the index itself.
:on_choose(handler)Calls handler(item, index) when you press Enter.
:focused()Asks for the keys when the list first shows.
:passive()Leaves the keys to the views around the list, which move it through :selection.
:footer(builder)Draws builder(first, last, total) under the rows while some items do not fit, where first and last are the rows in view.
:item_id(fn)Gives each item the id fn(item, index). A row’s state, the chosen row and the first row in view then follow their items when items are added, removed or moved. Without it they stay at their positions.

Up and Down move the choice by one row, Page Up and Page Down by a page, and Home and End go to the first and last rows. The mouse wheel over the list moves it too. ito.List raises an error unless items is a list and row is a function, and :item_id raises one when two items share an id.

local ito = require("ito")

local overlay
overlay = uji.ui.overlay(function()
  local styles = ito.theme().styles
  return ito.List(uji.session.list(), function(session, _, selected)
    local style = selected and styles.chosen or styles.text
    return ito.Lines({ { { session.title, style } } })
  end)
    :item_id(function(session)
      return session.id
    end)
    :focused()
    :on_choose(function(session)
      overlay:close(session)
    end)
    :footer(function(first, last, total)
      return ito.Text(first .. "-" .. last .. " of " .. total):dim()
    end)
    :border(ito.theme().borders.rounded)
    :title("Sessions")
end)

ito.ScrollView(child)

Shows child at its full height and scrolls it with the mouse wheel. :state(scroll) scrolls by an ito.ScrollState instead, so code of your own can move it too. :follow_end() keeps the bottom in view while the content grows, stops when you scroll up, and follows again once you scroll back to the bottom.

local ito = require("ito")

uji.fs.read("CHANGELOG.md", function(text)
  if not text then
    return
  end
  uji.ui.overlay(function()
    return ito.ScrollView(ito.Text(text)):border(ito.theme().borders.plain):title("CHANGELOG")
  end)
end)

ito.ScrollState(opts)

Holds where a scrolling view is. opts.follow starts it at the end. Pass it to ito.ScrollView(child):state(scroll) or ito.LazyVStack(...):state(scroll).

MemberMeaning
scroll:scroll(rows)Moves down by rows, or up when it is negative.
scroll:to_top()Goes to the top.
scroll:to_end()Goes to the end and follows it while the content grows.
scroll.followingWhether it is at the end and following it.
scroll.pageThe rows that show, for paging.
scroll.offsetThe first row that shows, counted from 0.
scroll.totalThe rows the content of an ito.ScrollView has.

page, offset and total are set when the scrolling view is laid out. A view that shows them, such as a “rows 1-10 of 40” line under it, reads them in an ito.SubcomposeLayout, which is built after the views above it are laid out.

ito.LazyVStack(items, row)

Shows items one under another and builds only the rows that show, so a list of thousands stays fast. row(item, index) gives the view of an item, and an ito.Group makes each of its children a row. Without a state it follows nothing and starts at the top.

ModifierMeaning
:item_id(id)Gives each item a lasting id, so its place and state follow it when items come and go. Two items with one id raise an error.
:state(scroll)The ito.ScrollState it scrolls by.
:footer(view)A view under the rows, right after the last one when they do not fill the room.
:more(load)Calls load when a move up reaches the first row, so the list can put the rows before it in items. The row you were on stays where it was.
local ito = require("ito")

local scroll = ito.ScrollState({ follow = true })

local Log = ito.view(function(props)
  return ito.LazyVStack(props.lines, function(line)
    return ito.Text(line.text)
  end)
    :item_id(function(line)
      return line.id
    end)
    :state(scroll)
end)

ito.Spinner()

Draws the frames of the theme’s symbols.spinner, one after another every limits.spinner_interval seconds, in the theme’s accent style.

ito.HStack({ ito.Spinner(), ito.Text(" indexing"):dim() })

Focus

Keys go to one control at a time. The control that has them keeps them while it is on the screen. When no control has them, the first one drawn with :focused() takes them, or else the first one drawn. A key the control does not use, such as Ctrl-C, goes on to uji’s keymap.

While a picker, prompt, approval or overlay is open, only the controls inside the one on top can take the keys. A control on the screen gets them back once it closes.