Sketch Plugin UI

Simple UI functions for Sketch plugins. Provides preset status messages and dialog windows with accessories and scroll views.

Installation

npm i @ozgurgunes/sketch-plugin-ui

Usage

Show a Simple Message with the Command Name

My Plugin Command: Hello Wold!

import { showMessage } from '@ozgurgunes/sketch-plugin-ui'

showMessage('Hello Wold!')

Show a Message with Check Mark Button Emoji

✅   My Plugin Command: It works!

import { successMessage } from '@ozgurgunes/sketch-plugin-ui'

successMessage('It works!')

Show a Message with Warning Emoji

⚠️   My Plugin Command: Something gone bad!

import { errorMessage } from '@ozgurgunes/sketch-plugin-ui'

errorMessage('Something gone bad!')

Show a Dialog

Plugin icon, command name as title and an "OK" button.

import { alert } from '@ozgurgunes/sketch-plugin-ui'

alert('Click OK to close this dialog.').runModal()

Show a Sheet

Attach alert as a sheet to given document.

import { alert } from '@ozgurgunes/sketch-plugin-ui'

alert('Click OK to close this dialog.').runSheet(context.document)

Get User Input

An autocomplete combo box, which user can pick an option or type new one.

import {
  comboBox,
  alert,
  errorMessage,
  successMessage,
} from "@ozgurgunes/sketch-plugin-ui"

var buttons = ["OK", "Cancel"]
var info = "Please type or pick something in the combo box."
var options = ["An option", "Another option"]
var accessory = comboBox(options)
var response = alert(info, buttons, accessory).runModal()
var result = accessory.stringValue()
if (response === 1000) {
  if (!result.length() > 0) {
    // User clicked "OK" without entering anything.
    errorMessage("You didn't enter anything.")
  } else {
    successMessage('You entered "' + result + '"')
  }
}

Get User Selection:

A scrollable checkbox list with an additional Select All button.

import {
  optionList,
  scrollView,
  alert,
  errorMessage,
  successMessage
} from '@ozgurgunes/sketch-plugin-ui'

var buttons = ['Select', 'Cancel', 'Select All']
var info = 'Please select options.'
var options = ['An option', 'Another option']
var list = optionList(options)
var accessory = scrollView(list.view)
var response = alert(info, buttons, accessory).runModal()

if (response === 1002) {
  // User clicked to "Select All".
  // Get a confirmation before selecting all.
  var message = 'Are you sure?'
  info = 'All options will be deleted!'
  buttons = ['Select All', 'Cancel']
  var confirmed = alert(info, buttons, null, message).runModal()
  if (confirmed === 1000) {
    // User is sure to select all.
    list.options.map(option => option.setState(true))
    successMessage('All ' + options.length + ' option selected.')
  }
}

if (response === 1000) {
  if (list.getSelection().length == 0) {
    // User clicked to "Select" button, without selecting any option.
    errorMessage('Nothing selected.')
  } else {
    successMessage(list.getSelection().length + ' options selected.')
  }
}

Functions

• showMessage(text, [status], [document])
• errorMessage(text, [document])
• successMessage(text, [document])
• alert(info, [accessory], [buttons], [message], [type]) ⇒ NSAlert
  • .runSheet([document])
• inputLabel(text, [frame], [size], [bold]) ⇒ NSTextField
• textField([initial], [frame]) ⇒ NSTextField
• comboBox(items, [frame]) ⇒ NSComboBox
• popUpButton(items, [frame]) ⇒ NSPopUpButton
• slider(options, [frame]) ⇒ NSSlider
• scrollView(documentView, [frame], [horizontal], [vertical]) ⇒ NSView
• optionList(items, [width]) ⇒ CheckboxList
• textList(items, [width]) ⇒ NSView

Typedefs

• CheckboxList : Object

showMessage(text, [status], [document])

Shows a temporary message at the bottom of the document. Message starts with the running command name.

Kind: global function

| Param | Type | Description | | --- | --- | --- | | text | string | The message to show. | | [status] | 'error' | 'success' | Puts an emoji before the command name (⚠️ or ✅). | | [document] | Document | The document which the message will be shown in. Default is context.document |

errorMessage(text, [document])

Shows a message with error status.

Kind: global function

| Param | Type | Description | | --- | --- | --- | | text | string | The message to show. | | [document] | Document | The document which the message will be shown in. Default is context.document |

successMessage(text, [document])

Shows a message with success status.

Kind: global function

| Param | Type | Description | | --- | --- | --- | | text | string | The message to show. | | [document] | Document | The document which the message will be shown in. Default is context.document |

alert(info, [accessory], [buttons], [message], [type]) ⇒ NSAlert

An alert with a combination of message, information text, buttons, and accessories.

Kind: global function
Returns: NSAlert - A preset NSAlert with a runSheet method attached.

| Param | Type | Description | | --- | --- | --- | | info | string | The message to show in dialog. | | [accessory] | object | An AppKit view or control to place in dialog for user inputs. | | [buttons] | Array.<string> | Buttons to display in dialog for user actions. Default is ['OK'] | | [message] | string | Title of dialog message. Default is context.command.name() | | [type] | number | Indicates the alert’s severity level. Default is 0 |

alert.runSheet([document])

Runs the alert modally as a sheet attached to the specified window.

Kind: static method of alert

| Param | Type | Description | | --- | --- | --- | | [document] | Document | The document which to display the sheet on window. Default is context.document |

inputLabel(text, [frame], [size], [bold]) ⇒ NSTextField

Simple text label for input fields.

Kind: global function
Returns: NSTextField - Uneditable text field to display.

| Param | Type | Description | | --- | --- | --- | | text | string | The label text to display. | | [frame] | NSRect | The rectangle of the text field, specified in points in the coordinate space of the enclosing view. Default is NSMakeRect(0, 0, 240, 18) | | [size] | number | The font size of the text. Default is NSFont.systemFontSize() | | [bold] | boolean | Specifies whether display the text bold. Default is false |

textField([initial], [frame]) ⇒ NSTextField

Returns a text input accessory.

Kind: global function
Returns: NSTextField - Text input with initial value.

| Param | Type | Description | | --- | --- | --- | | [initial] | string | Default input text. | | [frame] | NSRect | The rectangle of the control, specified in points in the coordinate space of the enclosing view. Default is NSMakeRect(0, 0, 240, 25) |

comboBox(items, [frame]) ⇒ NSComboBox

Returns an editable, autocomplete combo box accessory.

Kind: global function
Returns: NSComboBox - Combo box with options.

| Param | Type | Description | | --- | --- | --- | | items | Array.<string> | Options to be listed in combo box. | | [frame] | NSRect | The rectangle of the control, specified in points in the coordinate space of the enclosing view. Default is NSMakeRect(0, 0, 240, 25) |

popUpButton(items, [frame]) ⇒ NSPopUpButton

Returns a pop up button accessory.

Kind: global function
Returns: NSPopUpButton - Pop up button with options.

| Param | Type | Description | | --- | --- | --- | | items | Array.<string> | Options to be listed in pop up button. | | [frame] | NSRect | The rectangle of the control, specified in points in the coordinate space of the enclosing view. Default is NSMakeRect(0, 0, 240, 25) |

slider(options, [frame]) ⇒ NSSlider

Returns a slider accessory with tick marks for given range.

Kind: global function
Returns: NSSlider - Slider with given range.

| Param | Type | Description | | --- | --- | --- | | options | Object | Properties of the slider. | | [frame] | NSRect | The rectangle of the control, specified in points in the coordinate space of the enclosing view. Default is NSMakeRect(0, 0, 240, 25) |

Properties

| Name | Type | Description | | --- | --- | --- | | [options.minValue] | number | Minimum selectable value of slider. Default is 1 | | [options.maxValue] | number | Maximum selectable value of slider. Default is 10 | | [options.initialValue] | number | Initial selected value of slider. Default is 1 |

scrollView(documentView, [frame], [horizontal], [vertical]) ⇒ NSView

Returns a vertically scrollable accessory with given view.

Kind: global function
Returns: NSView - View with scrollable content.

| Param | Type | Description | | --- | --- | --- | | documentView | NSView | The view the scroll view scrolls within its content view. | | [frame] | NSRect | The rectangle of the scroll view. Default is NSMakeRect(0, 0, 320, 120) | | [horizontal] | boolean | A Boolean that indicates whether the scroll view has a horizontal scroller. Default is false | | [vertical] | boolean | A Boolean that indicates whether the scroll view has a vertical scroller. Default is true |

optionList(items, [width]) ⇒ CheckboxList

Returns a checkbox list accessory of options.

Kind: global function
Returns: CheckboxList - List of options.

| Param | Type | Description | | --- | --- | --- | | items | Array.<string> | Options to be listed with checkboxes. | | [width] | number | Width of the options. Default is 320 |

textList(items, [width]) ⇒ NSView

Returns a text list accesory.

Kind: global function
Returns: NSView - List of items.

| Param | Type | Description | | --- | --- | --- | | items | Array.<string> | Options to be listed in scroll view. | | [width] | number | Width of the list items. Default is 320 |

CheckboxList : Object

A dictionary of required components to get user selection.

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | options | Array.<NSButton> | List of checkboxes. | | view | NSView | View of options. | | getSelection | function | Returns indexes of selected options. |