StyleKits are a much better way of integrating the generated code into your Xcode projects.
- Eliminate the need to tweak the generated code by hand before putting it into your Xcode project
- Allow you to adjust your PaintCode documents and then re-integrate the changes into your Xcode project in seconds
- Allow for really fast design prototyping
What is StyleKit?
In PaintCode, you can have multiple drawing canvases in a single document, and each of these canvases can generate a corresponding drawing method in the StyleKit class. When you call this method in your code, the contents of the canvas will be drawn.
By putting all your PaintCode drawings inside a single StyleKit class (which you then use in your code via the public interface of the class), we’ve made the code integration process much smoother. Whenever you change your drawings in PaintCode, simply re-export the StyleKit class (2 files) into your Xcode project. No need to modify the generated code by hand - in fact, you don’t even need to look at the generated code!
To create a StyleKit, click on the first "StyleKit" tab - it is located on the left side, under the window toolbar.
This is the StyleKit Catalog. It is a catalog of all things you wish to place into the generated StyleKit class. When you scroll the catalog all the way to the bottom, you'll find the drawing canvases. Each canvas placed into the StyleKit catalog will generate a special drawing method in the StyleKit class.
The StyleKit Catalog also contains colors, gradients, shadows and images.
Adding colors and other library items to StyleKit
To add a library item (such as color) to the StyleKit catalog, simply drag & drop it from the Library to the Catalog.
Alternatively, you can also click on the "Add Color" placeholder, and choose a color from the menu that appears. Gradients, shadows and images can all be added to the StyleKit catalog in similar ways.
After you add a library item to the StyleKit catalog, a class method with the same name is added to the generated code. By calling this StyleKit method in your code, you can easily access the library item.
Removing colors and other library items from StyleKit
To remove a color or other library item from the StyleKit catalog, simply click on the item in the catalog (selecting it) and press DELETE or BACKSPACE.
Alternatively, you can just drag & drop the library item outside of the catalog.Important: Removing library item from your StyleKit Catalog does NOT
remove the item from your Library. When you remove a library item from the Catalog, it only means that in the generated StyleKit code, there will be no public class method generated for accessing that library item.
Adding canvases to StyleKit
Adding canvases to StyleKit works a bit differently than adding library items such as colors. By default, all newly-created canvases are added to the StyleKit catalog.
However, you can easily remove and add them at will, and even change what exactly is generated for each canvas in the StyleKit class.
To add a canvas to the StyleKit catalog, you have to go to the canvas settings. These are available in the Inspector after you click on the name of the canvas in the workspace. Alternatively, you can click on the canvas in the Shapes & Groups browser - it is always the item at the very top. Note that to do this, you have to leave the StyleKit tab, and activate the tab on which the canvas is.
The "StyleKit" popup button specifies what code should be generated for the selected canvas.
By default, the drawing method is generated. However, you can also choose "Image Method", which will generate a method that returns an UIImage with the content of your canvas.
This UIImage is drawn by code when the method is called. In case of simple, non-parametric canvases (canvases that do not use any variables), the resulting UIImage is automatically cached by the StyleKit class. That means that you do not have to worry about performance when calling the method that returns UIImage - first call of the method actually draws and caches the image, but subsequent calls only return the cached image, which is very fast.
When using UIImage-generating methods, you often get the best of both worlds - your drawings are resolution-independent, you don't have to use raster images, but the performance is the same as if you were using PNG resources. Moreover, you can still easily use the many AppKit APIs that expect UIImages.
In the image above, we've chosen "Drawing & Image Method" option. This means that both the UIImage-generating method and the void-returning drawing method will be available as public class methods in the StyleKit class.
Exporting StyleKit class from PaintCode
To export StyleKit class from PaintCode, selected the StyleKit tab and click on the big blue Export button in the Inspector.
An export sheet will appear. You can also show the export sheet by pressing COMMAND + E. In the export sheet, make sure that the first tab (StyleKit) is selected and press the "Export" button. Then, select the folder to which you wish to export the StyleKit class. Usually, two files will be exported - the implementation file and the header file. If your PaintCode document uses some raster images, you can choose to export those, too.
Once the StyleKit has been exported, it is very easy to export it again - simply press COMMAND + R or select File ▸ Export Again from the main menu. However, after you quit PaintCode and launch it again, you'll have to provide the export folder once more.
Using StyleKit class in Xcode
We take Objective-C as an example language, but Swift works almost identically.
Using StyleKit in your Xcode project is really easy. First, add the exported StyleKit class (both .m and .h file) to your Xcode project. Then, import the StyleKit class to your source code using the import directive:
Alternatively, you can put the import directive to your pre-compiled header (the one with the .pch extension). This way, you'll be able to use the StyleKit in all your source files, without adding the import directive to each of them.
Finally, to actually use the StyleKit class, simply call one of its class methods, like this:
Typically, you can do this in an overriden drawRect: method of some UIView. See the StyleKit basics tutorial for more information. To access a StyleKit color, you can do this:
UIColor* color = YourStyleKitName.yourColor;
The other library items such as gradients and shadows behave in a similar fashion.
Note that when using StyleKit programatically, you never need to instantiate the StyleKit class - all methods for accessing your drawings and library items are class methods, which means you call these methods on the class, not on the instance of the class.
Also note that if your canvases use frames or variables, the class methods generated by them may take parameters, allowing you to draw parametric drawings easily.
In case of UIImage-generating canvases, more options become available in the canvas settings. For example, it is possible to specify the cap insets necessary for stretchable UIImages:
You can also specify the resizing behavior of the UIImage (specifically, whether the central area defined by the cap insets should be tiled or stretched).
It is also possible to set the UIImage rendering mode. Some iOS system controls such as UITabBarItem use UIImages to draw icons, but only use these UIImages as templates, on which they apply system-wide effects. This behavior can often be prevented by switching to the "Original" rendering mode.
Here's how the StyleKit with a single canvas that is set to generate both drawing method and image-generating method looks like:
Using UIImage-generating canvases in XIBs and Storyboards
In the code above, you can see that a canvas that is set to generate UIImage method also generates a special IBOutletCollection.
If you make an instance object of the StyleKit class in your XIBs or Storyboards, you can connect the IBOutletCollection that was generated by the canvas to other objects.
After adding the instance object to your XIB or Storyboard, don't forget to change its class to your StyleKit's class.
StyleKit will automatically call the "setImage:" method on the objects you add to the IBOutletCollection (we also call them targets), using the UIImage generated by the canvas as the parameter.
You can use this to visually assign the images you've drawn in PaintCode to objects in your interface via their "setImage:" method. In the canvas settings, it is also possible to specify that "setSelectedImage:" method should be used instead.
These IBOutletCollections are useful when you want to customize interface objects such as UITabBarItem visually.
And here's what the results of connecting IBOutletCollection of your canvas to UITabBarItem look like in the simulator:Note: To make this work with UITabBarItem, you must also set its identifier to "Custom" in Xcode's Interface Builder. Important: Note that all public StyleKit methods are class methods. This
means that you usually don't need to make an instance of StyleKit to use it. In fact, you only need to create an instance to use the IBOutletCollection functionality.
To access the StyleKit settings, click on the StyleKit tab below the toolbar. The settings will appear in the Inspector on the right. You can specify:
- name of the generated StyleKit class
- name of your project
- your name
- company name
This information is used to generate the comments at the top of each StyleKit file The StyleKit settings can be found in the Inspector when the StyleKit tab is active.