Customize Custom UI

A custom action can stop partway, ask the person a question in the command palette, and carry on with the answer. rex.ui.input asks for a line of text, and rex.ui.pick shows a list to choose from.

rex.action{
  name  = "new_branch",
  title = "Git: New Branch…",
  run   = function(ctx, args)
    local name, why = rex.ui.input{
      title       = "New branch",
      placeholder = "feature/…",
      value       = "feature/",
      confirm     = "Create branch",
    }
    if name == nil then return end

    -- Type the command at the focused terminal's prompt.
    rex.block.call("com.superlogical.terminal", "write", {
      data = "git switch -c " .. name .. "\r",
    })
  end,
}

rex.bind("alt+cmd+b", "new_branch")
New branch feature/
Create branch ↩

Run rex config reload, then press Option+Cmd+B. The command palette opens with a text field titled “New branch”. Press

Return and the action continues with what you typed.

The action waits for the answer without holding anything else up. Keys, other actions, and events keep working while the question is open, and the time the person takes doesn’t count toward the action’s time limit.

Asking for Text

rex.ui.input takes a table and returns the text the person submitted:

local name, why = rex.ui.input{ title = "Your name" }
Your name Ada Lovelace
Use “Ada Lovelace” ↩
FieldDescription
titleNames the question. Required.
placeholderThe hint shown while the field is empty.
valueThe text the field starts with, for the person to edit.
confirmThe label of the row that submits. Without it, the row reads Use "…" with the typed text.
timeoutHow many seconds to wait for an answer. Defaults to 300, and is at most 3600.

The text comes back exactly as typed, including any spaces around it. It may be empty, because a person can submit an empty field.

Asking for a Choice

rex.ui.pick shows a list and returns the id of the item the person chose. It takes the same fields as rex.ui.input, where placeholder and value apply to the field that filters the list, plus items:

local dir, why = rex.ui.pick{
  title       = "Open project",
  placeholder = "Filter projects",
  items = {
    { id = "/Users/me/Apps/rex", title = "rex",
      subtitle = "~/Apps/rex", icon = "folder" },
    { id = "/Users/me/Apps/rex-app", title = "rex-app",
      subtitle = "~/Apps/rex-app", icon = "folder" },
  },
}
if dir == nil then return end

rex.session.new_window{
  layout = rex.layout.block{
    flavor  = "com.superlogical.terminal.shell",
    options = { cwd = dir },
  },
}
Open project Filter projects
rex ~/Apps/rex
rex-app ~/Apps/rex-app

items is a list, in the order to show it, of at most 2,000 items. It may be empty. Each item is a table:

FieldDescription
idWhat rex.ui.pick returns for the item. Required, and unique within the list.
titleThe item’s main text. Defaults to id.
subtitleA second, quieter line.
iconOne of the icon names below.
detailShort text at the far end of the row, such as a file’s status.
selectedSet to true to start the item ticked. Only with multiple.

An item can also be a plain string, which is short for an item whose id and title are both that string:

rex.ui.pick{ title = "Pick a fruit", items = { "Apple", "Banana", "Cherry" } }

Icons

icon is one of these names. Each Rex app draws them in its own style.

document, folder, branch, terminal, code, server, database, package, globe, link, person, tag, clock, star, gear, plus

Any other name is ignored with a warning, and the item has no icon.

Choosing Several Items

With multiple = true, the person can tick any number of items, and the result is a list of ids in the order of items. It’s an empty list if they confirmed with nothing ticked. The palette shows how many are ticked next to the confirm label, and Cmd+Return confirms.

local files = rex.ui.pick{
  title       = "Stage files",
  placeholder = "Filter changed files",
  multiple    = true,
  confirm     = "Stage",
  items = {
    { id = "README.md", icon = "document", detail = "??", selected = true },
    { id = "docs/notes.md", title = "notes.md", subtitle = "docs",
      icon = "document", detail = "??" },
  },
}
-- files is a list such as { "README.md", "docs/notes.md" }
Stage files Filter changed files
README.md ??
notes.md docs ??

Accepting Typed Text

With allow_other = true, the person can answer with what they typed in the field instead of choosing an item. The result is then the table { text = "..." }, so it can’t be mistaken for an id. allow_other can’t be combined with multiple.

local fruit = rex.ui.pick{
  title       = "Favourite fruit",
  items       = { "Apple", "Banana", "Cherry" },
  allow_other = true,
}
if type(fruit) == "table" then fruit = fruit.text end

When There Is No Answer

When there’s no answer, both functions return nil, a reason, and sometimes a detail:

local name, why, detail = rex.ui.input{ title = "New branch" }
if name == nil then
  if why == "cancelled" then return end
  rex.log("warn", "new_branch: " .. why .. " " .. (detail or ""))
  return
end

The reason is always one of these words:

ReasonMeaning
cancelledThe person closed the prompt without answering.
timeoutNobody answered within the timeout.
no_clientNo Rex app was connected, or every app showing the prompt lost its connection.
unsupportedNo connected app can show prompts, usually because they’re older than the server.
busyEvery app that could show the prompt is already showing another one.
failedAnything else. detail is a sentence that says what.

detail is nil for every reason except failed. Its wording can change between versions of Rex, so check the reason, not the detail.

A mistake in the call itself, such as a missing title or two items with the same id, raises an error instead.

Which Apps Are Asked

Every Rex app connected to the server is asked, including on your other devices, as long as it’s new enough to show prompts and isn’t already showing one. The first answer wins, and the prompt closes on the other apps. Cancelling on any one of them cancels it everywhere.

This is the same when the action is run with rex do: the question appears in the connected apps, and rex do waits until someone answers. Use --timeout to limit how long it waits. See rex do.

Where You Can Ask

A prompt pauses the action that asked, so it only works where Rex can pause: inside an action’s run function, and functions it calls directly. It doesn’t work in:

  • a function bound directly to a key, as in rex.bind(key, function() ... end)
  • a handler registered with rex.on
  • the top level of the configuration file
  • a function called through pcall or xpcall
  • an action run by rex.invoke
  • a function that a library calls, such as a table.sort comparator

There, both functions return nil and failed without asking anyone, and the log gets a warning. To ask from a key, define an action and bind the key to its name.

Running Without a Person

An action can take the answer as an argument and only ask when it’s missing. Then a script or a CI job can run it with nobody there to answer:

rex.action{
  name  = "greet",
  title = "Greet",
  args  = { name = "string?" },
  run   = function(ctx, args)
    local name = args.name or rex.ui.input{ title = "Your name" }
    if name == nil then return end
    rex.log("info", "Hello, " .. name)
  end,
}
rex do greet name=Ada

Server API

Apps receive a prompt as the client_prompt_requested event and answer it with client.reply. Apps that were asked but didn’t answer get client_prompt_ended when the prompt closes. Prompts need control API revision 17. See Server API Methods.