0.5.0 • Published 5 years ago

@ozgurgunes/sketch-plugin-ui v0.5.0

Weekly downloads
1
License
MIT
Repository
github
Last release
5 years ago

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

Typedefs

showMessage(text, status, document)

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

Kind: global function

ParamTypeDescription
textstringThe message to show.
status'error' | 'success'Puts an emoji before the command name (⚠️ or ✅).
documentDocumentThe document which the message will be shown in. Default is context.document

errorMessage(text, document)

Shows a message with error status.

Kind: global function

ParamTypeDescription
textstringThe message to show.
documentDocumentThe document which the message will be shown in. Default is context.document

successMessage(text, document)

Shows a message with success status.

Kind: global function

ParamTypeDescription
textstringThe message to show.
documentDocumentThe 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.

ParamTypeDescription
infostringThe message to show in dialog.
accessoryobjectAn AppKit view or control to place in dialog for user inputs.
buttonsArray.<string>Buttons to display in dialog for user actions. Default is ['OK']
messagestringTitle of dialog message. Default is context.command.name()
typenumberIndicates 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

ParamTypeDescription
documentDocumentThe 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.

ParamTypeDescription
textstringThe label text to display.
frameNSRectThe rectangle of the text field, specified in points in the coordinate space of the enclosing view. Default is NSMakeRect(0, 0, 240, 18)
sizenumberThe font size of the text. Default is NSFont.systemFontSize()
boldbooleanSpecifies 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.

ParamTypeDescription
initialstringDefault input text.
frameNSRectThe 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.

ParamTypeDescription
itemsArray.<string>Options to be listed in combo box.
frameNSRectThe 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.

ParamTypeDescription
itemsArray.<string>Options to be listed in pop up button.
frameNSRectThe 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.

ParamTypeDescription
optionsObjectProperties of the slider.
frameNSRectThe rectangle of the control, specified in points in the coordinate space of the enclosing view. Default is NSMakeRect(0, 0, 240, 25)

Properties

NameTypeDescription
options.minValuenumberMinimum selectable value of slider. Default is 1
options.maxValuenumberMaximum selectable value of slider. Default is 10
options.initialValuenumberInitial 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.

ParamTypeDescription
documentViewNSViewThe view the scroll view scrolls within its content view.
frameNSRectThe rectangle of the scroll view. Default is NSMakeRect(0, 0, 320, 120)
horizontalbooleanA Boolean that indicates whether the scroll view has a horizontal scroller. Default is false
verticalbooleanA 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.

ParamTypeDescription
itemsArray.<string>Options to be listed with checkboxes.
widthnumberWidth of the options. Default is 320

textList(items, width) ⇒ NSView

Returns a text list accesory.

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

ParamTypeDescription
itemsArray.<string>Options to be listed in scroll view.
widthnumberWidth of the list items. Default is 320

CheckboxList : Object

A dictionary of required components to get user selection.

Kind: global typedef
Properties

NameTypeDescription
optionsArray.<NSButton>List of checkboxes.
viewNSViewView of options.
getSelectionfunctionReturns indexes of selected options.