kwik user guide · 2014-05-15 · kwik 1.8 user guide revision 1.8 - dec. 15h, 2011 (thanks to...

KWIK 1.8 User Guide

Revision 1.8 - Dec. 15h , 2011 (thanks to Jordan Cohen)

Adobe Photoshop CS5 name and logo are properties of Adobe Systems. Ansca, the Ansca logo and Corona SDK are properties of Ansca, Inc. (c). Apple, iOS, iPhone, iPod and iPad, logo and names are properties of Apple. Android, logo and name, are properties of Google.

Table of Contents

What is Kwik? ............................................................................ 3 Things You Should Know and Follow .............................................. 3 Best Practices on using Kwik ........................................................... 3

Installing ..................................................................................... 6 Installing Corona and XCode ........................................................... 6 Installing Kwik .................................................................................. 6

Kwik Panel ................................................................................. 8 The tools in the Status Area ............................................................ 9 Customizing your Settings ............................................................. 10

Creating and Opening Projects ................................................ 13 Comic project options .............................................................. 15 Book Projects ........................................................................... 16

Project tools ................................................................................... 17 Page tools ...................................................................................... 19 Interaction tools ............................................................................. 23 Button actions ................................................................................ 26 Animation tools .............................................................................. 35 Widgets Tools ................................................................................ 46 Toolbox tools ................................................................................. 52

Previewing, Debugging and Building Projects ......................... 58 Debugging errors ........................................................................... 59 Building your projects .................................................................... 60

External Resources ................................................................. 61 People to follow on Twitter ............................................................. 61 Tutorials ......................................................................................... 61 Tools .............................................................................................. 61 Photoshop Performance ................................................................ 62

K W I K

3

What is Kwik?

Understanding the plugin before using it.

wik is a plugin for Adobe Photoshop CS5 and above that allows designers and illustrators to create comics and interactive books for iOS and Android devices, with animations, buttons, video and sound, directly from PSD files.

Things You Should Know and Follow

Before everything, if you have a Twitter account (if you do not have one yet we suggest you to create one – it’s free and simple!), follow us. Our profile is Kwiksher (not Kwik). To go direct from here: www.twitter.com/kwiksher.

If you prefer Facebook, follow us at www.facebook.com/kwiksher.

In both cases, you’ll be kept up to date on all new features or important announcements from us.

Don’t forget to visit (and subscribe) our YouTube channel: www.youtube.com/kwiksher. All video tutorials are available there.

Best Practices on using Kwik

Using Kwik is not difficult. However, due the relationship of the Kwik plugin with your Photoshop layers, follow these simple tips to avoid some common issues.

Kwik is very dependent on Photoshop layer naming. Wrong layer names can even block your preview process. Although Kwik tries to find and fixes potential issues, sometimes it simples cannot. To avoid these issues, use the following conventions (most are applicable to Book projects and many are valid for Comic projects as well):

1) Project name: Avoid long names for your projects and, DO NOT use characters like <> %,#;!. They conflict with XML convention. Keep naming simple!

2) Layer names: Before you start adding buttons and animations, follow the rules below. It is much easier to add interactivity with the final names than edit all of them afterwards. Basic rules:

Chapter

1

K

K W I K

4

- Avoid long names. All layer names become variables when exported, meaning they use more memory and are more difficult to read. Also, they are going to be shortening anyways, as Lua will not allow variable names with dozens of characters.

- Avoid having multiple layers with the same name. The second layer will overwrite the first one, and it will make the Lua code crazy. Kwik will provide an alert error if it finds layers with same name.

- As with Project names, when naming Layers, DO NOT use characters like <> %,#;!. These conflict with Lua language. Kwik removes these “strange” characters but, if they were used before in any button actions, it may generate errors during export.

- Do NOT name your layers as numbers. For example, a layer named 1, will generate an error. A layer named 01_Name will also generate an error. However, a layer named Name_01 will render without issues.

- Do not use Lua commands as names. For example, a layer named if will conflict with the command if. Some Lua commands are: if, end, local, transition, play. A full list of Lua commands is here. Kwik will generate an alert error if it finds layers with Lua commands as name.

3) Keep Layer Names Short: text layers names are originally created using the content of the text from the canvas. If you have a long paragraph, the layer name will be the entire content of the long paragraph! Long layer names cause problems in the generated code, so edit the layer names to make them shorter. (This is the most common problem we have seen from our users reporting issues.) And don’t forget all text, besides the ones used in the Sync feature, also exports as images!

4) Group layers: Kwik exports group layers as a single image. Use them to create more complex elements (for example, a multi-layered button with text, shadows, etc.), or for the creation of static elements. A common issue is to have all page elements in a group layer expecting they will render separately. If you have a group with several layers, try to flatten them whenever it is possible. It will make the export process much faster.

5) Create a background layer: Kwik must find at least one art layer in order to export. Whenever is possible, create it first. This is also used as the place for “page swipe” events – Kwik always uses the bottom layer of your PSD as background. If it cannot find it, an error occurs.

6) Universal projects: They are cool and expand your audience, right? Yes, but remember they duplicate image files, double your export time, add complexity to your code and, depending on the project, sometimes they just don’t make any sense! Can you really read a big paragraph on a 320×480 iPhone? If your audience is iPad users, do yourself a favor and create a project for iPad only.

7) Fireworks: Several designers like to start their project in Fireworks as it offers vector tools not available in Photoshop. When using PSD files created by Fireworks, please note that they do NOT come with the background layer (everything comes inside a group layer). As you read

K W I K

5

above, it will not work! To resolve this issue, if you are opening a PSD file from Fireworks, simply select all sub layers and move them outside the original folder they came in.

8) Button and Animation names: Although Kwik offers an auto-naming feature, try to enter your own names (follow the rules above). It will help you to quickly edit your actions from the project view. This is a time saver for project with several actions.

9) Export images only once: Whenever is possible, after renaming all the layers, export them (Preview button) before adding actions. You can do that by clicking the button Settings, then enabling the Export images checkbox. After the first export, disable the Export images checkbox. From now on, the Preview button will work much faster, exporting only the code (use it as much as need to tweak animations).

10) Don’t forget your icons and opening screen image: Kwik will help you to preview your project. However, your great comic or book will need the perfect icons (not the one we provide with Kwik’s logo) and a beautiful default screen (for iOS projects).

K W I K

6

Installing

Getting ready to create.

esides Adobe Photoshop, Kwik also requires Ansca Mobile’s Corona SDK installed in a Mac or PC. If you plan to develop applications for iOS, you will need a Mac computer (you cannot create apps for iOS on a PC) and a membership from the iOS Developer Program. For publishing Android apps on Google’s Marketplace, you will

need also a membership from Android’s Market. The same applies for Amazon Kindle Fire and Barnes & Noble Nook Color.

Using Kwik, as you will learn from the next pages, is the easiest part of creating your comic, ebook or application (app). However, becoming a member of Apple and/or Android’s developer programs, creating certificates, and publishing your app are not so simple tasks. Although this manual does not cover these tasks, it points you to several external sources that may help you, in the External Resources page.

Installing Corona and XCode

Before installing Kwik, certify that you have Corona (and in the case of running on a Mac, XCode either).

To install XCode on your Mac, go to http://developer.apple.com/devcenter/ios. The installation is free. However, to send your final app to the AppStore or test it on your device, you will need to pay the Program Membership.

In order to install Corona, simply go to http://www.anscamobile.com, click the Download button and follow the instructions. We suggest you to check the Docs, available at http://developer.anscamobile.com/resources/docs, as they provide lots of good tips and tricks on how to use and learn Corona.

You don’t need to install the Android SDK. Corona does it for you.

Installing Kwik

Kwik’s installation file is available at www.kwiksher.com, as well as inside the Tools folder, under the Corona’s SDK installation folder.

Chapter

2

B

K W I K

7

You will need the Adobe Extension Manager program to install Kwik. It is usually installed with your Photoshop or Creative Suite installation, also available at http://www.adobe.com/exchange/em_download. Please certify that you have the correct Extension (if you are using Photoshop CS5, the Adobe Extension Manager CS5 must be used, if you have Photoshop CS5.5, use the CS5.5 version of the product).

You can follow this video to see the installation http://youtu.be/ycgWi2xsGME

If you prefer to read:

1. Open Adobe Extension Manager

2. Click Install

3. Point to your kwik.mxp file (if you download it from our site, unzip the kwik.zip file first)

4. Accept the agreement and it is done.

Inside you Photoshop folder, you must be able to see:

- Kwik.mxp file

- A folder called Kwik created under Plugins/Panels folder

Now you are ready to use Kwik!

K W I K

8

Kwik Panel

Opening from the first time.

efore using Kwik, it is important to understand its interface. The Kwik Panel is divided in several areas, described below:

1) Category area (when in project mode)

2) Toolbox area

3) Project info area

4) Pages and Components area

5) Status area

Chapter

3

B

K W I K

9

All 5 areas change content when you have a project opened. Here is brief information on each area:

• Category: Shows the different features by category. For example, the Project category shows in the toolbox area all the features applicable to your entire project. For example, enabling or disabling Bookmarks.

• Toolbox: Shows all the tools related to the selected Category.

• Project Info: Displays information about the current project, like name, device and orientation mode. It also includes the Preview button, which export your project to Corona’s format, enabling it to be previewed in the Corona Simulator.

• Pages and Components: Displays two different tabs. The first one shows all the pages available in your project. The second one displays all the components available for the current page (for example, animations, buttons, etc).

• Status: Enables the access to Settings customization, quick access to Kwiksher’s website, and other features like deletion and project checking (more on that in the Status Area section).

The tools in the Status Area

When a project is opened, the Status Area shows 7 buttons. The first fours icons are related to Settings (see below), the Kwik logo checks for updates, the Bug icon is explained below, and the trash icon deletes pages and page elements.

Up to version 1.7, the Bug icon crosscheck layer names to avoid errors during export. Starting in version 1.8, it changes function during the Preview process, providing access to the external preview log file, enabling you to easily find why the process haven’t completed.

K W I K

10

Customizing your Settings

It is a nice practice to customize your preferences before starting your first project. To do so,

click the Settings button in the Status area. It will open the Settings window:

Tab General

The first tab contains the following information:

Corona Simulator Location: It must be informed to allow you to preview your project.

Project Folder Location: If you do not change it, all your projects will be created into your Documents/Kwik folder.

Show all alert messages: If selected, show all “non” critical alert messages.

Export images: If enabled, exports all project layers as separated images. It can be easily

access via button available in the Status area.

Check for updates when starting: Verifies if a new version exits in Kwiksher’s site, and alerts about it (it requires Internet connection to work).

Open only first project page document: If enabled, opens only the first page Photoshop document of each project.

K W I K

11

Tab Export

The second tab contains the following information:

Export only current page: When enabled, only the current page is exported during a Preview operation. It is a good practice to use this option enabled when you have several pages in your

project. This can be quickly accessed by the button in the Status area.

Export only pages_<num>.lua (do not export main.lua, director.lua, etc): If enabled, it does not create mandatory pages like main.lua, exporting only the page data. This can be

quickly accessed by the button in the Status area.

Export sample icons: If enabled, adds the default Kwik icons to the build project folder.

Close documents after export: If enabled, after exporting a page, the Preview process will close Photoshop page document. This is an important feature when you have large projects (Photoshop is not able to open more than 200 documents simultaneously) and need to export all pages at the same time.

New in v1.7 Export images and audios to separated folders: If enabled, images and audio files are going to be exported into folders images and audio, under the main project folder (build).

K W I K

12

Tab Registration

The third tab contains the registration information:

Product Registration Serial Number: When you buy Kwik, you will receive a serial number that needs to be pasted here. With this number, the plugin will be able to export all your project pages. Without this, only the first 2 pages are exported per project.

K W I K

13

Creating and Opening Projects

Starting right.

ou can create two different kinds of projects with Kwik: Comics and Books. It is important to understand the differences between each projects and when to use them.

DISCLAIMER ON COMIC PROJECTS

Comic projects uses the Corona Comics SDK “as is”. Meaning Kwik only provides the coordinates need by Corona’s code. Unfortunately the Comic SDK hasn’t been updated in a while and several issues have been reported about it (bad memory handling, etc). With all these know problems, our recommendation is to use this option only for prototype projects with just few pages.

Book projects are fully coded by Kwik, providing you a full set of interactions and animations. They can be created in both portrait and landscape orientation, and handle memory correctly when changing pages. Whenever it is possible, this is the correct project type to use.

In order to open a project, click the Open Project button

New in v1.7 If you want to quickly access the last project you were working on, click the Open

Last Project button

Chapter

4

Y

K W I K

14

In order to create your first project, click the New Project button

The following window will show up:

You need to enter the following information:

Title: is the name of your project (avoid long names)

Type: as explained above

Device: a list of devices will appear, with the first option being Universal, meaning Kwik will use iPad’s screen dimensions as start point, exporting also a low resolution version of each image for use in older iPhones. Check the Best Practices on Using Kwik page in the beginning of this guide to understand the issues with Universal projects.

Orientation: pretty explainable, portrait or landscape.

ATTENTION WHEN CREATING A PROJECT WITH A FILE OPENED

If you have a Photoshop file already opened when creating a project, Kwik will ask if you want to use it as first page. If you say so, the current file will be saved as another file and it will be resized to the correct screen size of your project. If you plan to use a large image as background, DO NOT import the current file, Place… it later on the created blank page.

K W I K

15

Comic project options The following options are available for Comic projects:

Creates a new page

Add a camera

Show/Hide cameras

Close current project and create a new one

Close current project and open a new one

As you can see, the Project Info was updated with the project data. Also, you see the page into the Page tab.

Understanding Cameras

For more information on the Corona Comic SDK, check this link https://developer.anscamobile.com/comics.

Cameras are simple rectangles that define an area to be zoomed for the Comic SDK. When you add a camera, Kwik auto creates a rectangle (using the rectangle tool). To change size, just resize the created rectangle.

The Show/Hide camera tool just enable/disable the layer visibility of all cameras.

Previewing your Comic project

When ready to preview your project, click the Preview button . Kwik will create all the need files and images to be compiled by the Corona Simulator. When finished, Kwik informs you the project is ready for previewing. Corona Simulator will launch and you will be able to interact with your creation.

K W I K

16

Book Projects

Kwik used in its full potential.

hen a Book project is opened, you have access to much more tools than in a Comic version. Below, 2 different ways to view your project data: the first image shows the pages info, while the second image shows the components of a page.

Notice this project has 3 pages

(Pages view)

See all page elements

(Components view)

Chapter

5

W

K W I K

17

New in 1.8: Now the panel shows a message with the current page opened, facilitating the user to easily remember in which page he/she is working.

To edit a page or its component, simple double-click it.

Another thing you may notice is the amount of Tools in the Category area.

Project tools

The Project category is represented by the icon , and contains the following tools:

Enable/Disable Bookmarks

Selecting this option opens the following window:

If enabled, user will return to the last page visited. If disable, users return always to the first page of your app.

Enable/Disable Page Swipe


If enabled, user will be able to switch pages swiping fingers (your last layer, the background, will be the responsible for tracking the swipe gesture. Avoid covering your background layer with big images; otherwise the swipe will never be completed). If disable, you will need to create buttons to change pages.

In-App Purchase Items

Attention: this feature is currently available only for iOS projects!

This button prepares the project for in-app purchase (IAP) configuration. Due the complexity of setting up an

K W I K

18

application for IAP, please read this blog posting first: http://kwiksher.com/blog/?p=195

Selecting this option opens the following window, which enables the entry of products for in-app purchasing:

Click the + button to enter more products:

In this window, inform exactly the same product id created in iTunes Connect, otherwise your app will not work. For the name, DO NOT enter names with spaces. As convention, use the last word of your product id as name.

New in v1.8

Multi-language settings

This button configures the languages to be used in the project. Due the complexity of setting up a multi-language application, please read this blog posting first: http://kwiksher.com/blog/?p=380

Selecting this button you get the following window:

K W I K

19

Click the add button (+) and you can set your language options:

Page tools

The Pages category is represented by the icon , and contains the following tools:

Add New Page


Although Kwik will create an auto name for your page, it is

K W I K

20

interesting to name it manually, as it makes easier to know the content of the page (specially in several pages project).

First checkbox is available when you have a current page opened. Enabling it means the content of the current page will be copied to the new one.

Copy content from checkbox allows you to copy not only the layers of the current page, as well as all elements (animations, buttons, etc) that exist there.

Add Audio


Location is the path for the audio file you are going to import to your project.

This is a short audio file checkbox, when checked tells Kwik to internally wait the audio be fully loaded in memory before playing it (this is best for short sound effects). Leaving it unchecked treats the audio as a stream (it starts to play promptly while loads the rest of the content in real time – this is best for narration and music audio files).

This is the page Read Me audio file, when checked informs Kwik that the audio file contains the narration of the page text content (this need to be checked if you plan to use this audio file as “Read to Me” option in your project).

Loop enables an audio being replayed forever of for an amount of time specified.

Delay informs when to start the audio file.

K W I K

21

Enable/Disable Page Swipe


If enabled, when in the current page, user will be able to switch pages swiping fingers (your last layer, the background, will be the responsible for tracking the swipe gesture. Avoid covering your background layer with big images; otherwise the swipe will never be completed). If disable, the current page will not enable page swipe with fingers and will need a button to move on to other pages. This is a nice feature for activities page, where user will interact with several objects and move to another page is not recommended.

In-App Purchase Only

Attention: this feature is currently available only for iOS projects!

This button protects a page, making it visible only if an IAP was completed. For example, you may set a page that will be accessible only after the purchase of a product from your app. Due the complexity of setting up an application for IAP, please read this blog posting first: http://kwiksher.com/blog/?p=195


Select the Product that unlock the page for visualization and the page for Re-direction, in the case the user tries to access the locked page without purchasing it.

K W I K

22

EDITING COMPONENTS

Please notice that many tools will add information into the Components tree, enabling you to review parameters later on. To do that, simply double-click the component you want to edit.

DELETING COMPONENTS AND PAGES

To delete a page or a component, select the appropriated tree in the Pages and Components area, and then select the element you want to delete. With the selection made, click the delete

icon , or just press DELETE key in your keyboard.

K W I K

23

Interaction tools

The Interaction category is represented by the icon , and contains the following tools:

Add Button

Buttons are the most basic interactivity tool. Users simple click them and something happens. Kwik provides several button actions, which can be chained to create complex results.

To create a button, select one layer of your Photoshop file, and then click the Add button (remember that the background layer, the bottom one, cannot be used as a button because it has already the swipe code attached to it).


K W I K

24

Like most components, a name will be required (Kwik always created a component name if you decide not to do so).

Normal/Mute is the current layer (remember that only one button can be attached to a layer).

Rollover/Unmute is the layer that will be shown when user clicks the button (it can be the same or another layer).

Action buttons are explained in the Buttons Actions section of this guide.

Actions grid shows all actions attached to the button. Double-clicking an action opens its own window for editing.

The trash button allows you to delete a particular action from the button. Simple select the action you do not want anymore and click the trash button.

The Multi-layer list allows you to associate the button with a preset group or create a new one.

Languages list saves the associated language to the button.

Drag Layer

Pick a layer you want to be “draggable”. Selecting this option opens the following window:

Optionally a draggable layer can execute an Action (more on that later on this guide), when dropped. If None is selected, nothing happens when user moves (drags) the layer to another position.

Spin Layer

Pick a layer you want to spin. Selecting this option opens the following window:

K W I K

25

Optionally a spin layer can execute an Action (more on that later on this guide), when dropped. If None is selected, nothing happens when user spins the layer to another position.

New in v1.8

Set Canvas

This option allows a layer to be used as a canvas for painting. When selected it shows the following window:

The Canvas Width and Height sets the size of the canvas (it automatically gets the size from the layer object).

Brush Size sets the start brush size.

Brush Color sets the start brush color.

ATTENTION:

Before to use this feature, you need to configure Flash Security Settings panel, allowing it to be executed with Kwik. When prompted to do so (if you missed the step or never got the prompt, click this link and

K W I K

26

follow the instructions below:

• In the Flash Security Settings panel, go to Global Security Settings tab;

• In the Always trust files in these locations: select Edit locations… then click Add location…

• Click the Browse for folder… button, then point it to your plugin folder:

o Windows: Program Files->Adobe->Adobe Photoshop->Plugins->Panel->Kwik

o Mac: Applications->Adobe->Adobe Photoshop->Plugins->Panel->Kwik

Confirm the action

New in v1.8

Enable Shake

Enables and associate an action to be run when the device is shaken. Clicking this option opens the following window:

Button actions

The following actions can be attached to a button:

Play Audio

Enables the button to play an audio.


K W I K

27

Simply pick a file to be imported. You can use .mp3, .wav, .caf and .aac for iOS projects. For Android projects you can use .mp3, .wav, and .ogg format.

Play Animation

Enables the button to play an animation previously made (only animations set with “Wait for Request” mode will be listed here).


Select the animation to play.

Go to Page

Enables the button to change pages when clicked.


Page Transition allows you to pick one of the several transitions available.

K W I K

28

New in v1.7 Wait x sec. before switch page allows you to wait a few seconds before changing pages. This is an interesting option if you want to finish an animation or play an audio before to move to another page.

Select Page points to the page that will be shown when user clicks the button. You can select a page by name or select NEXT (automatically moves to the next page) or PREVIOUS (automatically moves to the previous page). In the last two cases, Kwik will calculate the correct pages for you.

Show/Hide

Enables the button to hide and/or show layers when clicked.


Show/Hide checkbox defines what to do with the selected layer.

Toggle show/hide allows the button to switch between show and hide every time user clicks the button (if hidden, a layer is shown when the button is clicked, and vice-versa)

Duration specifies the total time until the layer fully appears (100% alpha).

Delay specifies the time before to start the process (if 0 sec, the layer appears/hides instantaneously).

Play Video

Enables the button to play a video when clicked.


K W I K

29

Location allows y to enter a url for an external video, or import a local .mov, .mp4, .m4v, and .3gp file. The following compression standards are acceptable:

• H.264 Baseline Profile Level 3.0 video, up to 640 x 480 at 30 fps. Note: B frames are not supported in the Baseline profile.

• MPEG-4 Part 2 video (Simple Profile)

Show controls, when enabled shows the play, stop and volume controls.

Warning: Video cannot be previewed in the Simulator. In order to check a video, use the Build option instead (in Corona Simulator).

Read to Me

Enables the button to move to the next page, and automatically play a narration audio file for the page.

No window is displayed for this action.

Play Read to Me

Enables the button to play a narration audio file for the page. Usually this button action is applied to text layers containing the page content. Doing that, when the text layer is clicked, it plays the narration for the user.


Go to URL

Enables the button to open a webpage, in the external browser, when clicked.


K W I K

30

Go to receive the URL users needed to be re-directed when the button is clicked.

Mute/Unmute

This is a special type of button action that cannot be associated with any other actions. It enables the button to toggle images (Rollover/Unmute button layer) and mute/unmute the device audio.


Record and Play Audio

Enables the button to record the user voice for the amount of time specified, than play the saved audio back.


Duration specifies the amount of time the recording session will take. While recording the user audio, the main screen will be dimmed, returning to full mode when the recording time stops. After that, the recorded audio will automatically be played.

Play Action

Enables the button to play a pre-save sequence of commands (action).


K W I K

31

Select the action to play.

Shuffle

Enables a button to play different actions (random or in sequence) every time the button is clicked. Selecting this option opens the following window:

Use the + (Add) button to select pre-made actions. The trash button removes actions from the list.

In the above example, the button will play the action “hideRed” when user clicks it for the first time. The second click will play “hidePurple”, and this sequence repeats every time users click the button.

The Play random checkbox, when checked, changes the behavior of the button. Every time user clicks the button, a random action from the list will be executed.

K W I K

32

Buy an Item (In-App Purchase)

Enables a button to buy a product, which needs to be selected via the following window:

The optional Hide button after purchase checkbox, when enabled, do not show the button in the case the product is already purchased.

Restore Purchased Items (In-App Purchase)

Enables a button to restore products previously bought.

Play Sync Audio and Text

Enables a button to start the sync of an audio and a text preset via the Toolbox feature Sync Audio and Text. When clicked, the following window opens for the selection of a prepared layer:

Due the particularities of setting up an text layer for syncing, please read this blog posting first: http://kwiksher.com/blog/?p=267

New in v1.8

Take a Screenshot of the current page

Takes a screenshot of the current window of the app and saves it in the Photo Library. When clicked opens the following window:

K W I K

33

The Play shutter audio checkbox plays a default audio when enabled.

Alert title and Alert message define the message to be shown after the screen capture.

New in v1.8

Set the Brush Size for a Canvas project

Sets the size and the alpha of a brush. When clicked opens the following window:

The Size sets the brush size.

Alpha sets the alpha (transparency) of the brush.

New in v1.8

Set the Brush Color for a Canvas project

Sets the color of a brush. When clicked opens the following window:

K W I K

34

The Color sets the brush color.

ATTENTION:

Before to use this feature, you need to configure Flash Security Settings panel, allowing it to be executed with Kwik. When prompted to do so (if you missed the step or never got the prompt, click this link and follow the instructions below:






Confirm the action

New in v1.8

Erase Canvas

Cleans the canvas (returns to original state).

New

Set Language

Set a language for the project.

K W I K

35

in v1.8

Animation tools

The Animation category is represented by the icon , and contains the following tools:

Linear

Linear animations moves a layer from its current position (point A) to a new position (point B).

Layers replaced by a Sprite Sheet or Movie Clip can also be animated by the Linear feature.


K W I K

36

Like most components, a name will be required (Kwik always created a component name if you decide not to do so). Different than a button, a layer can contain more than one animation associated with.

Layer info is the panel containing the start position of a layer. This is an important concept to understand. After creating an animation, you can move your layer to any other screen position, without the need of editing the animation again. However, if you need to change the end position (the place where the layer will be when the animation finishes), you will need to edit the animation again.

End Position is the panel containing the information of what will happen with the animation and where the layer will end. Although all components of this panel are optional, it is important to understand them:

• X (slider, + and – buttons, field) allows you to position the layer in the

K W I K

37

correct ending X axe point. Use the slider for large distances. The + and – are good for 1 pixel adjustment. If you know exactly the position you want, simply enter it in the field;

• Y (slider, + and – buttons, field) allows you to position the layer in the correct ending Y axe point. Use the slider for large distances. The + and – are good for 1 pixel adjustment. If you know exactly the position you want, simply enter it in the field;

• Return to start pos. after play when enabled returns the layer to its original position (start point) when the animation finishes;

• Easing displays a list of easing (velocity on start and ending) options. For examples of each option, click the Information button (it will redirect you to Flash site by Robert Penner);

• Information button shows examples of easing options to facilitate the selection of the best one for your need (it will redirect you to Flash site by Robert Penner);

• Pause when completed pauses a sprite sheet or movie clip replaced layer when the animation completes;

• Alpha sets the transparency level of the layer when the animation finishes. 100% means no transparency;

• Duration is the time of the moving the layer from its start to end point, in seconds;

• Starts define when the animation occurs. This is also an important concept to understand. If When page starts is selected, the animation will play automatically when the page loads. If Wait request is selected, the animation will never start, until an external event starts it. An external event can be a button, a timer, a drop, and an action request, for example.

• Delay specifies how long the page needs to wait before starting a “When page starts” animation. Zero means it will start promptly;

• Loop defines how many times the animation needs to be repeated;

• Reverse at ending when enabled plays the animation backwards. For example, supposing your animation shows the letters A, then B, then C, if Reverse at ending is active, the sequence will be A, B, C, B, A, and so on. If disabled, the sequence will be A, B, C, A, B, C.

• Rotate allows the layer to be rotated, according the degree number

K W I K

38

informed here. Notice that the rotation process starts when the animation begins, gradually rotating till the amount of degrees specified;

• Anchor Point allows the layer to be rotate with a different anchor point than Middle Center.

• Rotate Preview button allows you to preview the last position (full rotation) of your layer;

• Undo Rotate button allows you to return to the last position before the rotation;

• Scale W allows the layer to be scaled in X axe, according the percent number informed here. Notice that the scale process starts when the animation begins, gradually increasing or decreasing till the percentage specified;

• Scale Lock button when enable sets the same scale for both axes. When disable, each axe is treated separately;

• Scale Y allows the layer to be scaled in Y axe, according the percent number informed here. Notice that the scale process starts when the animation begins, gradually increasing or decreasing till the percentage specified;

Play Audio and/or Action is the panel containing optional information of what will happen with the animation ends. Options are:

• Play Audio allows you to select a valid audio file to play;

• Play Action allows you to select an action to play;

Path

Path animations move a layer along a path drawn using the Pen tool in Photoshop. The original position is the location of the first anchor of the path, not the current position of the layer.

Important Note

The direction of a path is defined by its first anchor. If you start a path from the left to the right of the screen, your animation will play left to right. If you start your path from the right to the left, the object will move along the path from right to left.

K W I K

39

Layers replaced by a Sprite Sheet or Movie Clip can also be animated by the Path feature.


A name will be required (Kwik always created a component name if you decide not to do so). Different than a button, a layer can contain more than one animation associated with.

Path Selection is the panel containing information about the path selection. It is important to understand them:

• Path lists all paths available in the current document;

• Duration is the time of the moving the layer from the start to end point of the path, in seconds;

K W I K

40

• Closed closes the path (ideal for circles);

• Return to start pos. after play when enabled returns the layer to its original position (start point) when the animation finishes;

• Easing displays a list of easing (velocity on start and ending) options. For examples of each option, click the Information button (it will redirect you to Flash site by Robert Penner);

• Information button shows examples of easing options to facilitate the selection of the best one for your need (it will redirect you to Flash site by Robert Penner);

• Pause when completed pauses a sprite sheet or movie clip replaced layer when the animation completes;

• Alpha sets the transparency level of the layer when the animation finishes. 100% means no transparency;

• Auto turn automatically calculates the angle of rotation for the layer, while it moves along the path. With this option enable, the Rotate angle will always be 0 (meaning any other value in the Rotate field will not be considered);

• Starts define when the animation occurs. This is also an important concept to understand. If When page starts is selected, the animation will play automatically when the page loads. If Wait request is selected, the animation will never start, until an external event starts it. An external event can be a button, a timer, a drop, and an action request, for example.

• Delay specifies how long the page needs to wait before starting a “When page starts” animation. Zero means it will start promptly;

• Loop defines how many times the animation needs to be repeated;

• Reverse at ending when enabled plays the animation backwards. For example, supposing your animation shows the letters A, then B, then C, if Reverse at ending is active, the sequence will be A, B, C, B, A, and so on. If disabled, the sequence will be A, B, C, A, B, C.

• Rotate allows the layer to be rotated, according the degree number informed here. This option only works if the (see above) Auto Turn checkbox is not enabled. Notice that the rotation process starts when the animation begins, gradually rotating till the amount of degrees specified;

• Anchor Point allows the layer to be rotating with a different anchor point

K W I K

41

than Middle Center.

• Rotate Preview button allows you to preview the last position (full rotation) of your layer;

• Undo Rotate button allows you to return to the last position before the rotation;

• Scale W allows the layer to be scaled in X axe, according the percent number informed here. Notice that the scale process starts when the animation begins, gradually increasing or decreasing till the percentage specified;

• Scale Lock button when enable sets the same scale for both axes. When disable, each axe is treated separately;

• Scale Y allows the layer to be scaled in Y axe, according the percent number informed here. Notice that the scale process starts when the animation begins, gradually increasing or decreasing till the percentage specified;

Play Audio and/or Action is the panel containing optional information of what will happen with the animation ends. Options are:

• Play Audio allows you to select a valid audio file to play;

• Play Action allows you to select an action to play;

Sprite Sheet

Sprite sheet is document containing several frames of illustration that, when played in sequence, creates movement. Below an example, available with Corona’s Jungle Scene project, under Corona/Sample Code/Sprites folder:

K W I K

42

In this example, all frames have the same dimension.

Another type of sprite sheet file uses frames with non-uniform sizes and positions. This second type of sprite sheet file is not compatible with Kwik.

CREATING SPRITE SHEETS

Several applications can create sprite sheets and they can be used with Kwik, if they can export same dimension frames. If you prefer, you can use the simple Sprite Sheet Exporter (available at File->Scripts) script provided and installed with Kwik. In order to learn how to use it, check the tutorial video at http://youtu.be/cLZ11A5_eFw

ATTENTION: SPRITE SHEETS IN YOUR LAYERS

When you attach a sprite sheet (see below), it replaces your current layer image with the selected sprite sheet frame. Another important concept to learn here: if your original layer illustration has a different size than the sprite frame you selected, it will render wrong. To guarantee a perfect match have your

K W I K

43

“dummy” layer content with the same dimensions of your sprite sheet frames.

Sprite Sheet window


Important Note

Sprite Sheet feature is not rendered as an animation anymore but just as a replacement of a layer. It means that previous projects with Sprite Sheets will need to be redone.

Sprite Sheet replacing layer is the panel containing the information about the sprite sheet attached to the selected layer:

• File is the pointer to the external sprite sheet file (a .png file should be used here to guarantee a better performance on the devices);

• Frame Width is the width size of frames into the external sprite sheet file (Kwik auto adds the current layer width into this field);

• Frame Height is the height size of frames into the external sprite sheet file (Kwik auto adds the current layer height into this field);

• Start Frame sets which frame in the sprite sheet will be the first one displayed;

• Frame Count informs the total number of frames of the animation (they

K W I K

44

need to be in sequence);

• Loop defines how many times the animation will be repeated;

• Length is the length of the animation in milliseconds, meaning how fast the frames will be played;

• Pause at frame 1 pauses the sprite sheet at frame 1;

ATTENTION: SPRITE SHEETS IN UNIVERSAL PROJECTS

Differently than regular layers, sprite sheet files are not optimized for multiple screen devices visualization. Corona does a pretty good job auto scaling them. However, it is always interesting to check if the final project renders well (if not, manually create a larger or smaller version of your sprite sheet file).

Movie Clip

Movie Clip animation requires a series of external files that, when played in sequence, creates movement.

ATTENTION: MOVIE CLIP IN YOUR LAYERS

When you attach a movie clip (see below), it replaces your current layer image with the selected external files. Another important concept to learn here: if your original layer illustration has a different size than the external file you selected, it will render wrong. To guarantee a perfect match have your “dummy” layer content with the same dimensions of your external files.

Movie Clip window


K W I K

45

Important Note

Movie Clip feature is not rendered as an animation anymore but just as a replacement of a layer. It means that previous projects with Movie Clip will need to be redone.

Movie Clip replacing layer is the panel containing the information about the movie clip files attached to the selected layer:

• First File is the pointer to one of the external movie clip files (a .png file should be used here to guarantee a better performance on the devices). When creating movie clip files for using with Kwik, name them following the convention name_1.pgn, name_2.png, and so on;

• Image Width is the width size of the external movie clip file (Kwik auto adds the current layer width into this field);

• Frame Height is the height size of the external movie clip file (Kwik auto adds the current layer width into this field);

• Nr. Images tells the total number of movie clip files (they will play in sequence);

• Loop defines how many times the animation will be repeated;

• Pause at frame 1 pauses the movie clip at frame 1;

K W I K

46

Widgets Tools

The Widgets category is represented by the icon , and contains the following tools:

Rotation

The Rotation widget is a pre-configured, less complex, window with parameters that allow an object to rotate.



Layer info is a panel containing the current layer info.

Rotate defines how the layer will be rotated, according the degree number informed here;

Duration is the time of the moving the layer from its start to end point, in seconds;

Delay specifies how long the page needs to wait before starting the rotation. Zero means it will start promptly;

Loop defines how many times the animation needs to be repeated;

Reverse at ending when enabled plays the animation backwards. For example, supposing your animation shows the letters A, then B, then C, if Reverse at ending is active, the sequence will be A, B, C, B, A, and so on. If disabled, the sequence will be A, B, C, A, B, C.

Starts define when the animation occurs. This is also an important

K W I K

47

concept to understand. If When page starts is selected, the animation will play automatically when the page loads. If Wait request is selected, the animation will never start, until an external event starts it. An external event can be a button, a timer, a drop, and an action request, for example.

Return to start pos. after play when enabled returns the layer to its original position (start point) when the animation finishes;

Pulse

The Pulse widget is a pre-configured, less complex, window with parameters that allow an object to pulse (scaling up and down).




Scale defines how the layer will be scaled, according the percentage number informed here;


Delay specifies how long the page needs to wait before starting the pulsing. Zero means it will start promptly;


K W I K

48


Starts define when the animation occurs. This is also an important concept to understand. If When page starts is selected, the animation will play automatically when the page loads. If Wait request is selected, the animation will never start, until an external event starts it. An external event can be a button, a timer, a drop, and an action request, for example.


Bounce

The Bounce widget is a pre-configured, less complex, window with parameters that allow an object to bounce (move up and down).




Distance defines how height the layer will be moved, according the number informed here;

Duration is the time of the moving the layer from its start to end

K W I K

49

point, in seconds;

Delay specifies how long the page needs to wait before starting the bouncing. Zero means it will start promptly;





Switch Images

The Switch Images widget is a pre-configured, less complex, window with parameters that allow an image replace another image (each image must be a different layer).


K W I K

50


Dissolve to is the layer that will replace the selected layer;

Duration is the time of the dissolving process between images, in seconds;

Delay specifies how long the page needs to wait before starting the transition process. Zero means it will start promptly;


New in v1.8

Blink

The Blink widget is a pre-configured, less complex, window with parameters that allow an object to simulate a blink movement (scale the Y axis to close to 0 than re-scale to the original height).


K W I K

51



Scale Y defines how scale down the layer will be, according the percentage number informed here;


Delay specifies how long the page needs to wait before starting the blinking. Zero means it will start promptly;





K W I K

52

Toolbox tools

The Toolbox category is represented by the icon , and contains the following tools:

Hide Layer

When selected, hides a layer.

No window is shown for this tool.

Actions

Actions are a sequence of commands that can be later trigger by external events like a button, the dropping of a layer or a timer, for example.



Action buttons are explained in the Buttons Actions section of this guide. Please notice that not all Button Actions are available for using as Actions.

K W I K

53

Actions grid shows all actions attached to the Action sequence. Double-clicking an action opens its own window for editing.

The trash button allows you to delete a particular command from the Action. Simple select the action you do not want anymore and click the trash button.

Timers

Timers can trigger action sequences in different times. They are interesting to use when something in your app needs to happen, independent of a manual event, like the button press.



Delay is the time that the timer will wait before to trigger the action.

Action is the action sequence that will be triggered.

Loop defines how many times a timer will be activated.

Shared Asset

This tool marks a layer to be exported only once, even if the same layer name is found in other pages from the same project. For example, if a project has 2 pages, and in both pages they have the same image in a layer named “butNext” for example, when pages are exported Kwik will create 2 files with the same content but different names (in this case p1_butNext.png and p2_butNext.pgn). To avoid this scenario,

K W I K

54

simply select the layer butNext in both pages and click Shared Asset. Doing that, Kwik will only export a file called kwkbutNext.pgn, which will be rendered in the 2 project pages.

There is not window for this tool.

Sync Audio and Text

Enables a text layer to be synced with an audio (when audio plays, words highlights according the audio position). Due the particularities of setting up an text layer for syncing, please read this blog posting first: http://kwiksher.com/blog/?p=267

Important: always test your project on the target devices when using this options. It will guarantee the positioning and font preview is corrected (Corona Simulator will always shows the text as local fonts are available on your desktop but maybe not on your device).

ATTENTION:

Before to use this feature, you need to configure Flash Security Settings panel, allowing it to be executed with Kwik. When prompted to do so (if you missed the step or never got the prompt, click this link and follow the instructions below:






• Confirm the action

K W I K

55

After selecting a text layer, when clicking the Sync Audio and Text button, the following window will appear:

When checked, Use native system font (do not import external font files) will use a native font from iOS and/or Android system. If disabled, during export you will need to locate the external font file to be imported into your project folder. Kwik will handle the process of importing the font to the build folder, as well as creating all external files needed;

Font options Padding sets the distance in pixels between words.

K W I K

56

Font options Offset sets the distance in pixels between lines.

When checked, the Use page Read Me audio file automatically syncs the text with a previously set Read Me audio type file. If unchecked, browse and set an audio file to be synced with the text.

Kwik reads the content of the text layer and set the words in the table under the Edit words to enter time codes. With the words imported, you will need to inform the start/end time of the word mention into the audio file. You can set it in two different ways:

• Manually double-clicking each word and entering the start and end time positioning;

• Import a text file with the contents (using the Import from Audacity button). When importing from Audacity, simply select the text file generated by Audacity, and the time codes will automatically be pre-populated;

ATTENTION

If you are using a different audio software than Audacity, check if it can export labels in the following text format (TAB is used between the entries):

0.000000 0.325079 This

This language reads right to left sets the text to be read from right to left (ideal for projects in Arabic and Japanese languages, for example).

Text highlighting color sets the color of the word highlight when the audio time code matches the one in the above table. In order to properly work, you must set the Flash Settings as mentioned above.

New in v1.8

Set language to a layer

Sets the language of the layer, to be used in multi-language projects. Due the particularities of setting up multi-language project, please read this blog posting first: http://kwiksher.com/blog/?p=364

After selecting a text layer, when clicking the Set language to a layer button, the following window will appear:

K W I K

57

The Multi-layer list allows you to associate a layer with a preset group or create a new one.

Languages list saves the associated language to the layer.

K W I K

58

Previewing, Debugging and

Building Projects

From design to a real app.

hen you hit the Preview button Kwik executes several functions to make your project compatible with Corona and ready to be viewed into Corona’s Simulator. They include cross-checking of layer names, export of layers into images, creation of mandatory files (main.lua, building.settings, etc), and the conversion of all

interactivity you added in your project into different pages per Photoshop files used. Depending of the size of your project, this process can take several minutes to finish.

ATTENTION: LOCKED LAYERS

Please notice that locked layers will not export and may cause the Preview process to stop.

In the background, Kwik will create a folder called Build into your project folder and place all necessary files there.

Usually, the export process concludes with the following message, informing your project is ready to be seen in Corona’s Simulator:

Clicking OK to the above message will open (if it is not opened yet) Corona Simulator (if it does not open, check your Settings to certify you have entered the path to the Simulator). In the Simulator, point to the created Build folder (on Windows, you need to point to the main.lua file inside the build folder), select the device to simulate and click OK.

Chapter

6

W

K W I K

59

If everything is fine, you will be able to play with your app in the Simulator.

Debugging errors

If, after a few minutes, the above message does not show, and Photoshop seems to be ready to work again, it means Kwik found an unexpected situation that didn’t allow it to finish the process.

This list shows the most common issues:

• There is a blank layer in your Photoshop file (simply remove it and try again);

• A layer was renamed or removed and there is a reference (from a button, for example) to it (in this case, an alert will appear asking you about the issue);

• Layers with same name exist (in this case, an alert will appear asking you about the issue);

• A text layer name contains non-accepted characters like symbols, etc;

Other times, you may receive the above message but, in the Simulator, nothing happens (a black screen only shows). If you are using a Mac, follow these suggestions:

• Close Corona Simulator;

• Go to your Applications folder, folder CoronaSDK and open the Corona Terminal application;

• Corona Terminal will open, together Corona Simulator;

On Windows machines the above instructions are not necessary as the Corona Simulator automatically starts the Corona Terminal application together.

Open your application again and check the Corona Terminal console. The console shows alerts and errors found in the current application. Below, an example showing 2 different errors:

• The audio file backAudio3.mp3 was not found;

• An error happened on the file page_1.lua, line 68

Although the screen seems scary, the only important error to notice (besides the warning message about the audio file) is the first one (in line 68). When an error is found, usually it triggers a sequence of errors related to the first one.

K W I K

60

It is not the intention of this User Guide to teach you how to fix Kwik exported pages, however, learning to read Corona Terminal messages will help you to understand potential errors, as well as it will facilitate your support requests to Kwiksher’s team. Instead of send an email saying “it is not working”, you can now copy the contents of the console, making easing the finding and fix of bugs.

Building your projects

DISCLAIMER

When you finish your project and are ready to preview it on your device, or even submit it to Apple’s AppStore or Android MarketPlace, you will need to follow Apple and Google rules. In both cases you will need to work on complicate processes of certificates creation. This User Guide does not teach you how to navigate on iOS and Android Developer Programs; however, the External Resources chapter provides some start points.

Considering the building process is done in Corona’s Simulator, the two links below are the best starting points for building projects:

iOS: http://developer.anscamobile.com/content/building-devices-iphoneipad

Android: http://developer.anscamobile.com/content/building-devices-android

For both platforms, don’t forget to create an appropriated icon for your app (otherwise Kwik’s icon will be used), and default screen(s) for iOS projects. As each platform has different icon requirements, follow the instructions from the above links as well.

K W I K

61

External Resources

Things everybody should know.

hen you built your app you thought every thing was done? Maybe not! The following resources are interesting to be at your hands. They include links and people to follow, tutorials and tools.

People to follow on Twitter

Technology changes everyday and it is nice to be updated. Start following:

@Ansca – developers of Corona

@Kwiksher – we, developers of Kwik

Also, check search for the following hashtags1:

#storyappchat – a great chat every Sunday night (9PM Eastern time) with authors, illustrators and story book developers;

#coronaSDK – if you are interested in finding more technical info, or even learn a little Lua (the language used by Corona);

Tutorials

We provide a series of tutorials at: www.youtube.com/kwiksher

Also, check our Learn page at www.kwiksher.com/learn.html

Tools

Although Kwik exports your layers as images directly from Photoshop, sometimes you may need to use better image optimization than the ones Photoshop provides (yes, there are better tools to export PNG files than Photoshop). This link shows some of them: http://www.webdesignbooth.com/12-really-useful-image-optimization-tools-for-web-designers/

1 Definition: The # symbol, called a hashtag, is used to mark keywords or topics in a Tweet. It was created organically by Twitter users as a way to categorize messages.

Chapter

7

W

62

Photoshop Performance

For performance improvement while using Photoshop, follow the best practices suggested by Adobe at http://kb2.adobe.com/cps/404/kb404439.html or http://blogs.adobe.com/crawlspace/2011/05/how-to-tune-photoshop-cs5-for-peak-performance.html

For those ones willing to change Kwik’s Lua code manually:

Sprite Sheet creation

If you use Flash to do your animations, it is interesting to check also Spriteloq, a very good Flash animation to sprite sheet file exporter. Although Kwik cannot process Spriteloq sheets yet, you may follow their instructions on how to add them to your project. www.loqheart.com

Visual Effects

Particle Candy is a really cool add-on to your arsenal. It brings a large number of effects (particles, fire, smoke, just to name a few) and can be used in storybook too (you can create your effects using custom illustrations). http://www.x-pressive.com/ParticleCandy_Corona/