# March 2022 Release (version 1.7.3)

Script Kit should auto-update or you can grab the downloads here: https://www.scriptkit.com/

## Widgets - `await widget()`

A widget is a detached UI window that can control and listen to a script.

<img width="374" alt="CleanShot 2022-03-01 at 12 43 13@2x" src="https://user-images.githubusercontent.com/36073/156237436-f42e8f33-2fbb-48bb-9408-94f1a45283a5.png">

[Open widget-hello-world in Script Kit](https://scriptkit.com/api/new?name=widget-hello-world&url=https://gist.githubusercontent.com/johnlindquist/ca174899643e86f416d301d9599bb4e8/raw/55d334c6dc412c0346a750348d8c0ffa2b8650ba/widget-hello-world.ts")

```js
// Name: Widget Hello World

import "@johnlindquist/kit"

let message = await arg("Hello what?")
await widget(`<h1 class="p-4 text-4xl">Hello ${message}</h1>`)

```

### Widget Events


[Open widget-events in Script Kit](https://scriptkit.com/api/new?name=widget-events&url=https://gist.githubusercontent.com/johnlindquist/1ce2972fdeed0773450f4dba3f3f2c00/raw/6834ccde194ea471f403df9366a7ac283cb853bb/widget-events.ts")

```js
// Name: Widget Events

import "@johnlindquist/kit"

let text = ""
let count = 0

let w = await widget(`
<div class="p-5">
    <h1>Widget Events</h1>
    <input autofocus type="text" class="border dark:bg-black"/>
    <button id="myButton" class="border px-2 py-1">+</button>
    <span>{{count}}</span>    
</div>
`)

w.onClick((event) => {
    if (event.targetId === "myButton") {
        w.setState({count: count++})
    }
})

w.onClose(async () => {
    await widget(`
<div class="p-5">
    <h1>You closed the other widget</h1>
    <p>${text}</p>
</div>
`)
})

w.onInput((event) => {
    text = event.value
})

w.onMoved(({ x, y}) => {
    // e.g., save position
})

w.onResized(({ width, height }) => {
    // e.g., save size
})
```

## Closing a Widget
There are 3 ways to close a widget:
1. Hit "escape" with the widget focused
2. End the process of the widget. Hit <kbd>cmd+p</kbd> with the main menu focused to see the running processes or `exit()` anywhere in the script.
3. Use a `ttl` (time to live) in the options when creating a widget

## "Always on Top" and Locking the Widget

[Open widget-always-on-top in Script Kit](https://scriptkit.com/api/new?name=widget-always-on-top&url=https://gist.githubusercontent.com/johnlindquist/bfd8ec67d9632867b0faf4e808381948/raw/90f766f21af8c88760409215e569baef9d8f0238/widget-always-on-top.ts")

```js
// Name: Widget Always on Top

import "@johnlindquist/kit"

await widget(`<h1 class="text-9xl">🇺🇦</h1>`, {
    alwaysOnTop: true,
    transparent: true
})

```

With a widget focused, press <kbd>cmd+l</kbd> to "Lock" the widget. This will disable any possible mouse interactions (including moving, resizing, etc) and allow you to click through the widget to any windows underneath.

To "Unlock":
1. three-fingered swipe up on OSX
2. focus the widget
3. hit <kbd>cmd+l</kbd>

You can now hit move, escape, etc the widget.

## Built-in Terminal - `await term()`

`term` is Script Kit's built-in terminal.

### From the Main Menu

Type <kbd>></kbd> into the main menu to open `term`

### From a Script

Use the `await term()` API to switch to the terminal.

[Open term-hello-world in Script Kit](https://scriptkit.com/api/new?name=term-hello-world&url=https://gist.githubusercontent.com/johnlindquist/10420bab68da357b572c1e703c2c5a43/raw/a287e443f1e57d4541f50feba28b86e1702ff515/term-hello-world.ts")

```js
// Name: Term Hello World

import "@johnlindquist/kit"

await term(`echo 'Hello World!'`)
```

> Note: If you want spawn a new Mac terminal, use `await terminal()`

### Pass Terminal Output to Script

If you end the terminal with <kbd>cmd+enter</kbd>, the script will continue and you can grab the latest text output from the terminal.

> 🐞: <kbd>ctrl+any key</kbd> will also end the terminal. This is a bug (it was only meant to be ctrl+c) which I'll fix soon. I'm also open to ideas for other shortcuts to "end" a terminal that aren't taken by vim/emacs/etc, because I know I'll be missing some.
> 🐞: `term` doesn't grab keyboard focus when opening. I'll get that fixed ASAP!

[Open term-returns in Script Kit](https://scriptkit.com/api/new?name=term-returns&url=https://gist.githubusercontent.com/johnlindquist/935445caef26d1c13f195533569cd0cc/raw/ca921b09480a3d7b5bf63e7a777011199e642fb9/term-returns.ts")

```js
// Name: Term Returns

import "@johnlindquist/kit"

let text = await term(`ls ~/.kit`)
await editor(text)
```

## Menubar - `menu()`

`menu` allows you to customize the menubar for Script Kit.

<img width="290" alt="CleanShot 2022-03-01 at 12 40 58@2x" src="https://user-images.githubusercontent.com/36073/156237149-c40843db-4dd2-4e35-9854-4a922e9cd1dd.png">

[Open menu-hello-world in Script Kit](https://scriptkit.com/api/new?name=menu-hello-world&url=https://gist.githubusercontent.com/johnlindquist/6aeb6a3f916bfc40e9acd6b9d4388b34/raw/21d8c70da05f08e454d81cb0ccebbbbc82b42f7d/menu-hello-world.ts")

```js
// Name: Menu Hello World

import "@johnlindquist/kit"

menu(`Hello 🌎`)
```

### Menu with Scripts

The second arg of menu can be an array of scripts you wish to present in a drop-down menu. This way, on left-click, you'll get a list of scripts to pick from from the menubar rather than opening the main Script Kit UI.

[Open menu-with-scripts in Script Kit](https://scriptkit.com/api/new?name=menu-with-scripts&url=https://gist.githubusercontent.com/johnlindquist/0e07e0a8bd4926be6d843ce49fbb4474/raw/4a111ceeae7725525fdcf8bf546105698a4ac4c9/menu-with-scripts.ts")

```js
// Name: Menu with Scripts

import "@johnlindquist/kit"

// An empty string means "Use default Script Kit icon"
menu(``, [
    "app-launcher"
])
```

## Built-in Editor Types

Script Kit's built-in editor now loads all of Script Kit's types! This was a huge undertaking that everyone just expects to work. You all know how that feels 😇

> 🐞: Please let me know if you see any missing. I noticed that I missed the types for `terminal` and `iterm` when putting this post together 🤦‍♂️.

## March Plans

I'm dedicating March to DOCUMENTATION!!! (and bug-fixes)... I have _a lot_ of script requests to follow-up on and work around the newsletter and other non-app stuff. I'm also moving this month, so y'all know how stressful that can be. So expect the April build to be extremely light feature-wise, but I will be set up in the new house ready to much more live-streaming and communication. Can't wait to share more! 🙂

## Questions?

I'm happy to help with any questions you may have!