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.