Workflow

Custom Devices

Custom Devices

Extend the library of simulated devices in Origami Studio by making your own device with custom dimensions, scale, frame and hand images.


Creating a New Device

  1. Download the custom device example
  2. Open the .origamidevice bundle by right-clicking and choosing Show Package Contents in the contextual menu
  3. Make adjustments to info.json file describing the device (see documentation below). Make sure to choose a unique key for every device you’re creating
  4. Replace or add .png images and reference them in the info.json file
  5. Double-click the bundle file to install it

Testing your Device

To test your custom device after installation:

  1. Switch to the device in Origami Studio
  2. Make any changes inside the .origamidevice bundle
  3. Double-click the .origamidevice bundle
  4. Origami Studio will immediately refresh the device

Example info.json

{
  "key" : "iPhone4",
  "displayName" : "iPhone 4",
  "platform" : "iOS",
  "type" : "phone",
  "screenScale" : 2,
  "screenSize" : [
    320,
    480
  ],
  "handsImageScale" : 0.5649999999999999,
  "handsImageOffset" : [
    2,
    45
  ],
  "handsImages" : [
    "iPhoneHands.png",
    "iPhoneHands2.png",
    "iPhoneHands3.png"
  ],
  "deviceInsets" : [
    130,
    28,
    130,
    28
  ],
  "deviceImages" : {
    "White" : "iPhone4-White.png",
    "Black" : "iPhone4-Black.png"
  },
  "shadowOffset" : [
    20,
    -5
  ],
  "defaultDeviceOrientation" : "Portrait",
  "supportsDeviceOrientationPortrait" : true,
  "supportsDeviceOrientationLandscapeLeft" : true,
  "supportsDeviceOrientationLandscapeRight" : true,
  "supportsDeviceOrientationPortraitUpsideDown" : true
}

info.json Documentation

Many of the properties of the device info.json file are exposed via the Device Info patch.

key

Type: String, Required

This is the most important item in the bundle. The key will be saved to designers’ compositions, so you can’t change it once it’s been picked. The key should be related to the commonly understood name for the device, but if there are multiple screen sizes or resolutions it must be unique to that combination. You shouldn’t include the device color in the key; that accounted for in the device images.

displayName

Type: String, Required

The display name shows in the Device picker menu in Studio. It can be changed after the fact since it’s not saved in compositions.

screenSize

Type: Array of 2 numbers, Required

The size of the device’s display in pt/dp. The size in pixels is screenSize multiplied by the screenScale.

This is exposed to compositions via the Device Info port “Screen Size”

screenScale

Type: Number, Required

How many pixels are in each point.

For example, an iOS Retina screen is typically a scale of 2.0. The iPhone 6 Plus has a scale of 3.0. Android devices have a range of scales from 0.75 to 4.0 corresponding to ldpi (0.75) mdpi (1.0), hdpi (1.5), xhdpi (2.0), xxhdpi (3.0) and xxxhdpi (4.0).

type

Type: String, Optional

The menu item in Device picker menu where this device is available. Available types are computer, phone, tablet, tv, watch, window, custom. Defaults to custom if not specified.

platform

Type: String, Optional

e.g. iOS, Android, AndroidWear, WindowsPhone, Windows, OSX, tvOS, or watchOS

mouseInput

Type: Boolean, Optional

Whether this device uses a Mouse or Trackpad for input

viewerWindowNative

Type: Boolean, Optional

Whether this device uses a native mac window to display when popped out into its own window. The screenSize is then able to be resized freely.

deviceInsets

Type: Array of 4 Numbers, Required

Describes the distance around the device. Influences how the shadow is drawn and the device is positioned relative to the containing view frame.

shadowOffset

Type: Array of 2 Numbers, Optional

If you want the builtin shadow, set this to something non-zero and you can position the shadow relative to the device.

deviceImages

Type: Dictionary of Strings to Strings

The keys in the dictionary describe colors the device is available in, the values are the names of the .png files within the bundle that will display the correct device frame within Origami Studio.

deviceImageOffset

Type: Array of 2 Numbers, Optional

How much to offset the device image from the screen

deviceImageScale

Type: Number, Required if deviceImages is used

How much to scale up or down the device image compared to the screen scale

handsImageOffset

Type: Array of 2 Numbers, Optional

How much to offset the hand image from the device image

handsImageScale

Type: Float, Optional

How much to scale the hands image compared to the screen

handsImages

Type: Array of Strings, Optional

Each entry here should refer to a hand image provided in the device bundle.

handsOnTop

Type: Boolean, Optional

Whether or not the hand is on top of the device. Useful for devices like iPad where the thumbs should be in front.

defaultDeviceOrientation

Type: String, Optional

The default device orientation to show the device in for the provided screen size and device images. For example, if the device is a TV or tablet in landscape orientation, the value should be LandscapeLeft or LandscapeRight. Available orientations are Portrait, LandscapeLeft, LandscapeRight, PortraitUpsideDown. Defaults to Portrait if not specified.

supportsDeviceOrientationPortrait,

supportsDeviceOrientationLandscapeLeft,

supportsDeviceOrientationLandscapeRight,

supportsDeviceOrientationPortraitUpsideDown

Type: Boolean, Optional

Interface orientations that the device supports when being rotated.