Quartz Composer Diary

Primer 1

And Then There Was Light

Quartz Composer Icon

This series of primers are intended to give you an introduction to the world of QC. Brian Kernighan and Dennis Ritchie in their classic The C Programming Language wrote that the biggest hurdle in starting beginning learning a programming language is to write a program to print the 'Hello World' on the screen, the rest is relatively easy. This is because it requires mastering the mechanics of writing a program : writing it somewhere, running it and seeing where the output went.

On a similar sentiment, we have modelled these primers to give you an understanding of the developing in Quartz Composer, so that you would be independent to pursue your own ideas without waiting for our next posts to arrive. In this post as well as the ones to follow, we will be focusing on revealing the quirky user interface of Quartz Composer, because we believe that once you know your tool inside out, there would be less of a barrier between you and your ideas turning into a reality.

As a graphical analogy to the hello world program, in this series of primers, we have chosen to create a rudimentary window manager. In this first post of the series, we will see how to create a toggle button which would be used in the next post to spawn a window. Let's start by getting you introduced to building blocks of Quartz Composer.

The Tofu Noodles Interface

Quartz Composer consists of building blocks of color coded rounded rectangles which are known as patches. These patches communicate to each other through noodle-like bézier curves that come out of little holes on either side of these patches known as ports. The ports on the left side take in input, the patch processes these values and outputs them through the ports on the right. This distinction between the ports on the left and right is important, because it brings in a left to right progression of patches in the projects you build.

You can make a connection by dragging out a noodle from the output port on the right side of a patch and connecting it to the input patch on the left of another patch. This connection between two patches is an abstraction of how data flows from one port to the other. Also, instead of clicking and dragging out a noodle from a port, you can just click on it and a noodle will follow your cursor around. With this trailing noodle, you can click on the port of another patch and the connection will be made. This would be a good choice if the two patches that you want to connect are located far apart. To locate a far-off patch, you might use the Sketch/Photoshop trick of panning around: with the spacebar down, left click and drag towards your target on screen.

A Strange Loop

Without further ado, let's start learning more about Quartz Composer by getting started with our project. Create a new project by going to File > New From Template Something of an easter egg here is that, the view area of 'Choose Template' window is a QCView, which means that everything you see inside the window is completely made in Quartz Composer. The switching of screens, the spring effect when you scroll inside the window, everything. This also means that you can embed your Quartz Composer projects in your apps. We will be detailing more about this in future posts but we have included this bit of information here because we think this file will be a great resource to start your exploration of the Quartz Composer's workings since it illustrates the working of a handful of patches, has some workarounds and has a decent organisation. You can find this file inside the package contents of Quartz Composer. To access it, Cmd + Click on the Quartz Composer icon on the dock which takes you to where Quartz Composer is stored on your drive, right click on the Quartz Composer icon that appears in the Finder window and choose Show Package Contents. Drill down to Contents > Resources and you'll find Welcome.qtz. Once you feel comfortable with the ideas introduced in this series, we recommend you to take this file apart right away and start your journey towards prototyping UIs. Also, before you start fiddling, be sure to make a copy of the file so that you have backup in case something goes wrong.

Taking the Baby Steps

Now that you have got a peek of Quartz Composer's power, let's kick off by choosing the Basic Composition from the range of choices on the screen. It serves you with a Quartz Composer file with a clear patch. This patch ensures that it clears up the screen and presents you with a blank canvas to draw on. Before you proceed, make sure you have got the Viewer window with a black canvas. If you don't have it, bring it on screen by going to Window > Show Viewer. This viewer window is where all the action happens. The resulting computation of whatever you do on the patch editor window will be reflected in real time in the viewer window. If you are working with limited screen real estate, a resolution of 800×600 works well for this tutorial. If you have a bigger screen, having both width and height values as even numbers would do the job. At any point in this tutorial, you are free to go full screen in the viewer by pressing the icon in the toolbar. We recommend keeping the viewer window always open beside your editor window, because seeing the changes on the fly will spark off new ideas. This is one of the primary reasons we think Quartz Composer soars as an interface prototyping tool. These spin-off discoveries are what makes prototyping interactions in Quartz Composer worthwhile.

Bring in a billboard patch from the patch library. It can be located in the toolbar of the window with an icon of three books or accessed by pressing Cmd + Return. A Billboard patch is a customizable rectangular display area. In other words, it displays the image data it's fed which can be resized. Let's bring in an image to test this. Download this background image file on to your desktop and drag it into the editing area. We have used a resolution of 1440×900 for this image but you might have a different screen resolution than us. In that case, we have also provided the Toggle.sketch file to resize the background to your liking. It also includes all other resources such as the buttons that are required to complete this tutorial. Now, locate the background file you just downloaded and drag and drop it in to the editor window of Quartz Composer. As soon as you drop the image, you can see that it transforms to an image patch. Connect this image patch to the billboard patch.

Making a connection

Just as you make the connection you will notice that the image does not fill the entire canvas in the Viewer window. This is because a billboard patch in it's original condition is defaulted to auto height in it's settings. To access the settings of any patch, select the patch and press Cmd + Shift + I. This brings up the Inspector panel which lets you tinker with the various options of a particular patch. On the billboard patch, change the Dimensions Mode to Custom Size by clicking on the dropdown.Maintaining the selection on the patch, access the input parameters of the patch by pressing Cmd + I. They are so frequently use when composing, that the designers of Quartz Composer have made them available as a sidebar. It can be accessed by pressing Cmd + T. Among the parameters, locate the text fields labelled Width and Height. Change the values of both of these fields to 2. As you make this change, you will see the background image fill up the entire display area of the Viewer Window. You might, quite reasonably, be wondering what's going on in here. Turn out, Quartz Composer uses a coordinate system which spans a unit distance of 2 across both X and Y direction. Though seemingly a bit strange, this unit measure will work to our advantage once we come in terms to representing screen area as coordinates. Rest assured that it will be covered in detail in future posts. One other thing to adjust if you feel the colors are slightly off is to check the 'Disable Color Correction' under the image options in the settings panel of the Image Patch. This is essentially how you work with Quartz Composer. You connect two patches with the help of the noodles and then use the inspector panels to change specific options associated with them. In the next section we will create a click-able button.

Zeros and Ones

Before we proceed further, let us take a small detour to explain a fundamental concept. Quartz Composer, actually all of computing devices for that matter, uses two logic values of true and false for operation. These true and false values are denoted with the help of 0 and 1 respectively in Quartz Composer. As an illustration, consider you want to know when the left mouse button is down. Bring the patch in Quartz Composer called the Mouse on the editor window. It has got various ports on the right that outputs the state of your mouse. Notice the port called Left Button. If you hover over that port for a few seconds, a tooltip will pop up saying that the value is false. What this tells us is that the left mouse button of our mouse is not pressed. Let's see how Quartz Composer internally processes this value. Bring in an Image With String Patch from the library and also a Billboard. Bring up the Settings Panel and change the dimension mode to 'Real Size' this time. Connect the port called Left Mouse Button from the Mouse patch to the String port on the left side of the Image with String patch. Now drag a noodle from the Image port on the right of the Image with String patch to the image port on the billboard. When you make this connection successfully, you will see a string 0 appear in the middle of the canvas.

Set up for Mouse Click Detection

In Quartz Composer, all the patches in their vanilla condition have their output values defaulted to false. In our composition, the false value flows from the Mouse Patch over to the String port of the Image with String Patch. It then processes the false value as 0 and outputs it as an image 0 through the Image port. The Billboard receives this image and display it on the screen. You might have expected the text 'False' to appear on screen, but for efficiency of computation, Quartz Composer internally represents false value as 0.

Now try clicking anywhere inside the canvas of the view window. As soon as you make a click, you will see the value becoming 1 and quickly reverting to 0. You can also notice that the value stays as one, as long as you keep hold of the mouse and reverts to 0 as soon as you release it.

What happens in this case is that the mouse connected to your Mac tells Quartz Composer that the Left Mouse Button is down. The value of Left Button on the Mouse patch becomes true which is internally represented in Quartz Composer as 1 and this value flows through the patches to bring about the text '1' on screen. This interplay of 0s and 1s are what govern the program flow in Quartz Composer. If you don't have a background in programming or maths, it might seem a bit quirky to see these 0s and 1s but actually this representation is used since you can perform a branch of Mathematics called Boolean Algebra on these values which opens up a world of possibilities to explore. We are keeping a detailed discussion on this topic for future posts. At the moment, let us put this new gained knowledge into building a toggle switch.

Implementing a Switch

We are hoping that, by now, you are familiar with bringing in patches to the composition from the patch library. Our typical workflow is to press Cmd+Return which brings up the patch library, enter the first few letters of the word, which almost always pinpoints the patch and press the Return key. To adopt this workflow, turn off 'Keep Patch Library visible after inserting patch' in Preferences > Editor so that the Patch Library is dismissed as soon as you bring in a patch.

Remove the Image with String patch that we used to inspect Quartz Composers internal representation. Now here is where the fun stuff begins, conjure up the Patch Library and pull out a Multiplexer patch. The Multiplexer patch takes decisions based on the input you feed into it's Source Index. The Source Index port takes up the value and outputs the object at the corresponding location. Suppose you feed in a value of '4' into the source index port, the output value will be what was fed into Source#4. Let's exploit this property of multiplexer to create a toggling switch. Download this archive of two images of a toggling switch. Once you download them, drag and drop these image files on to the Quartz Composition. Connect the Off.png to Source #0 and On.png to Source #1. Now drag out a noodle from the Left Button of Mouse patch and connect it to the Source Index port. Make a connection from Image port of Multiplexer to the Image port of Billboard. We are all set, click anywhere inside the canvas of the viewer and you'll be able to see that the button gets turned on and off as you press the left button of your mouse.

Set up for understanding multiplexer

Set up for understanding the multiplexer.

If you put together what was said in the previous section with what was said about the Multiplexer patch, you will be able to figure out what is going on. The Mouse patch outputs the value of '0' and '1' accordingly as the mouse gets pressed and released. This value is taken up by the Virtual Multiplexer which gives out the image 'Off.png' at Source #0 on receiving value 0, that is, when the mouse is not pressed. The 'On.png' at Source #1 is given out by the Multiplexer whenever it receives value 1 which means the mouse was pressed. The Multiplexer outputs the image accordingly, which is then taken up by the billboard to display it on screen.

This gives us a press-able button. But this is not good enough. What we need is a toggle-able button. This can be accomplished with the help of… surprise! …the toggle patch. It toggles between two states. You can set these values in the Initial Value and Secondary Value ports of the patch. The factory-default toggle has them as 0 and 1 which would work great for us. Interpose the toggle patch between the Mouse and the Virtual Multiplexer. That is, unwire the connection from Left Button of the Mouse to the Multiplexer and connect it to the Input port of Toggle patch. Drag the output from the Toggle on to the Source Index of the Multiplexer patch.

Interposing toggle between multiplexer setup

Interposing toggle between multiplexer setup

Test the output on the viewer. Just what we were looking for. A button that gets toggled when we click any where on the canvas. Wait something feels wrong, doesn't it ? We click on the switch, not around it, to toggle it in the real world but what we have got here is a button that gets toggled regardless of wherever we click on the canvas. To mimic the real world interaction thereby aligning it with the mental model of the user, We need a button that gets toggled only when we press on it. Lets see how we can bring about that behaviour in the next section.

Targeting a Billboard with Interaction Patch

Letting Quartz Composer know of the interactions on screen can be achieved with the Interaction patch. Bring up an interaction patch on the editor window. As soon as you have it on screen, you might notice that it has got an output port beside the heading of the patch. This port is used to communicate between a patch that renders on screen. In our case, we have been using Billboard to render our images on screen. If you examine the Billboard patch, you will notice that it too has a hole near the heading, but to the left side. These two patches were made for each other. Drag from this port of the Interaction patch and connect it to port on button's Billboard patch.

Making a connection between interaction patch and billboard patch

What has happened now is that the interaction patch acknowledges that it would only output a value when the mouse interacts with billboard patch it is connected to. Notice that the interaction patch has a Mouse Down port. This would output a value of '1' when we click on the toggle button. Let's now drag the from this Mouse Down port to the Input value of the Toggle port. Now we have successfully created a button that gets toggled only when you click 'on' it. You are free to remove the Mouse patch as it is not used anymore. The ground is now set to use this interaction to create the window manager. Find out how in the next primer.


Now that you have completed the tutorial, we would like to leave you with an exercise for you to complete. Noticed the banner of this post ? There is a pressed state between the bulb glowing and turning off. Whenever a click is made on a button, instead of a straight toggle, the button gets depressed and then gets toggled. Remember that when a button gets pressed, not only it's position but also it's lighting and shadows are prone to change. Hence you will need some new images for the pressed states. We have bundled the requisite resources along with the Quartz Composer file of this tutorial into this bundle. Download it and see if you can bring in a pressed state in between the bulb on and off states. Only the patches and the logic that you have been taught in this primer are required to complete this exercise. Good luck!

Sketch Resource


If you are having any difficulty with the above material, please be sure to let us know. Any comments, critiques and corrections are always welcome and keep tuned for the next primer.

comments powered by Disqus