@ozgurgunes/sketch-plugin-ui v0.5.0
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
- 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. |