JUCE supports the development of C++ applications for a range of target platforms. These include Microsoft Windows, Mac OS X, iOS, Linux, and Android. In general, this book covers the development of C++ applications using JUCE for Windows and Mac OS X, but it is relatively straightforward to apply this knowledge to build applications for the other supported target platforms.

In order to compile JUCE-based code for these platforms, typically an Integrated Development Environment (IDE) is required. To compile code for Windows, the Microsoft Visual Studio IDE is recommended (supported variants are Microsoft Visual Studio 2008, 2010, and 2012). Microsoft Visual Studio is available to download from http://www.microsoft.com/visualstudio (the free Express versions are sufficient for non-commercial development). To compile code for Mac OS X or iOS, the Xcode IDE is required. Generally, the latest public version of Xcode is recommended. This can be downloaded for free from the Mac App Store from within Mac OS X.

JUCE is provided as source code (rather than prebuilt libraries) divided into discrete but interconnected modules. The juce_core module is licensed under the Internet Systems Consortium (ISC) license, allowing it to be used freely in commercial and open source projects. All the other JUCE modules are dual licensed. For open source development, JUCE may be licensed under the terms of the GNU General Public License (Version 2 or later) or the Affero General Public License (Version 3). JUCE may also be used for closed-source, commercial projects using separate commercial licenses for a fee. More information on JUCE licensing is available at http://www.juce.com/documentation/commercial-licensing.

Unless there are very specific reasons for using a particular version of JUCE, it is recommended to use the current development version available from the project's GIT repository. This version is almost always kept stable and often includes useful new features and bug fixes. The source code is available for download, using any GIT client software, at git://github.com/julianstorer/JUCE.git or git://git.code.sf.net/p/juce/code. Alternatively, the code for the current development version may be downloaded as a ZIP file from https://github.com/julianstorer/JUCE/archive/master.zip.

You should keep the JUCE source code in its top-level juce directory, but you should move this directory to a sensible location on your system that suits your workflow. The juce directory has the following structure (directories are shown using a trailing /):

amalgamation/
docs/
extras/
juce_amalgamated.cpp
juce_amalgamated.h
juce_amalgamated.mm
juce.h
modules/
README.txt

Although all of these files are important, and the actual code for the JUCE library itself is located in the juce/modules directory, each module is contained within its own subdirectory. For example, the juce_core module mentioned previously is in the juce/modules/juce_core directory. The remainder of this chapter examines some important projects available in the juce/extras directory. This directory contains a range of useful projects, in particular the JUCE Demo and the Introjucer projects.

To give an overview of the features provided by JUCE, a demonstration project is included in the distribution. This is not only a good place to start, but is also a useful resource containing many examples of implementation details of classes throughout the library. This JUCE Demo project can be found in juce/extras/JuceDemo. The structure of this directory is typical of a JUCE project generated by the Introjucer application (which is covered later in the chapter).

To build and run the JUCE Demo application, open the appropriate IDE project file from the juce/extras/Builds directory.

Running the JUCE Demo application on Windows

On Windows, open the appropriate Microsoft Visual Studio Solution file. For example, using Microsoft Visual Studio 2010, this will be juce/extras/JuceDemo/Builds/VisualStudio2010/Juce Demo.sln (other project and solution file versions are also available for Microsoft Visual Studio 2008 and 2012).

Now, build and run the project by navigating to the menu item Debug | Start Debugging. You may be asked if you want to build the project first as shown in the following screenshot:

Click on Yes, and when this succeeds, the JUCE Demo application should appear.

The JUCE Demo application overview

The JUCE Demo application is divided into a series of demonstration pages, each illustrating a useful facet of the JUCE library. The following screenshot shows the Widgets demo (as it looks on Mac OS X). This is available by navigating to the menu item Demo | Widgets.

The Widgets demonstration shows many of the commonly needed Graphical User Interface (GUI) controls provided by JUCE for application development. In JUCE, these graphical elements are called components and this is the focus of Chapter 2, Building User Interfaces. There are a range of sliders, dials, buttons, text display, radio buttons, and other components, which are all customizable. There are other demonstrations available by default in the Demo menu, covering features such as Graphics Rendering, Fonts and Text, Multithreading, Treeviews, Table Components, Audio, Drag-and-drop, Interprocess comms, Web Browser, and Code Editor. There are additional demonstrations available on some platforms and when certain hardware and software is available. These are the QuickTime, DirectShow, OpenGL, and Camera Capture demonstrations.

Customizing the look and feel

By default, the JUCE Demo application uses JUCE's own window title bars, its own menu bar appearance, and its default look and feel. The title bars can be configured to use the native operating system appearance. The following screenshot shows the title bar of the JUCE Demo application as it appears on the Windows platform. Notice that even though the appearance of the buttons is the same as on Mac OS X, their positions should be more familiar to users on Windows.

By navigating to the menu item Look-and-feel | Use native window title bar, the title bar can use the standard appearance available on the operating system. The following screenshot shows the appearance of the native title bar on Mac OS X:

The default menu bar appearance, whereby the menu items appear within the application window below the title bar, should be familiar to Windows users. Of course, this is not the default location for application menus on the Mac OS X platform. Again, this can be specified as an option demonstrated in the JUCE Demo application by navigating to the menu item Look-and-feel | Use the native OSX menu bar. This moves the menu bar to the top of the screen, which will be more familiar to Mac OS X users. All of these options are customizable within JUCE-based code.

JUCE also provides a mechanism to customize the look and feel of many of the built-in components using its LookAndFeel class. This look and feel can apply to only some of the components of a particular type or globally across the application. JUCE itself, and the JUCE Demo application, come with two look and feel options: the default look and feel and the old, original (that is, "old school") look and feel. In the JUCE Demo application, this can be accessed via the Look-and-feel menu.

You should explore the JUCE Demo application before moving onto the next section, where you will build the Introjucer application that eases the management of multi-platform projects.

The Introjucer application is a JUCE-based application for creating and managing multi-platform JUCE projects. The Introjucer application is able to generate the Xcode projects for Mac OS X and iOS, the Microsoft Visual Studio projects (and solutions) for Windows projects, and the project files for all the other supported platforms (and other IDEs, such as the cross-platform IDE CodeBlocks). The Introjucer application performs a number of tasks that make managing such projects much easier, such as:

These are all helpful when setting up a project for the first time, but even more valuable when changes need to be made later in a project. Even changing the name of the product is relatively tedious if this needs to be done in several, separate projects. With the Introjucer application, most project settings can be set within the Introjucer project file itself. When saved, this will then modify the native IDE projects with any new settings. You should be aware that this would also override any changes made to the native IDE projects. Therefore, it is wise to make all the required changes within the Introjucer application.

In addition to this, the Introjucer application includes a GUI editor for arranging any GUI components. This reduces the amount of coding required for certain types of GUI development. This part of the Introjucer application generates the C++ code required to reconstruct the GUI when your application runs.

The Introjucer application is provided as source code; you will need to build it before it can be used. The source code is located in juce/extras/Introjucer. In a similar way to building the JUCE Demo application, there are various IDE projects available in juce/extras/Introjucer/Builds (understandably there are no Introjucer builds for iOS or Android). It is preferable to build the Introjucer application in its release configuration to take advantage of any code optimizations.

Building the Introjucer application on Windows

Open the appropriate solution file in juce/extras/Introjucer/Builds into Microsoft Visual Studio. Change the solution configuration to from Debug to Release as shown in the following screenshot:

Now you should build the Introjucer project by navigating to the menu item Build | Build Solution. After this succeeds, the Introjucer application will be available at juce/extras/Introjucer/Builds/VisualStudio2010/Release/Introjucer.exe (or similar, if you are using a different version of Microsoft Visual Studio). At this point you should add a shortcut to your Desktop or Start Menu, or whatever suits your typical workflow.

Examining the JUCE Demo Introjucer project

To illustrate the structure and functionality of an Introjucer project, let's examine the Introjucer project for the JUCE Demo application. Open the Introjucer application you have just built on your system. In the Introjucer application, navigate to the menu item File | Open… and navigate to open the JUCE Demo Introjucer project file (that is, juce/extras/JuceDemo/Juce Demo.jucer).

An Introjucer project uses a typical master-detail interface, as shown in the following screenshot. On the left, or the master section, there are either the Files or Config panels, which are selectable using either the on-screen tabs or via the View menu. On the right, or the detail section, there are the settings associated with the selected, specific item in the master section. With the project name selected in the Config panel in the master section, the global settings for the whole JUCE Demo project are shown in the detail section. The Config panel shows the hierarchy of the project's available target builds for the different native IDEs.

In addition to these sections in the hierarchy of the Config panel that are concerned with the native IDE targets, there is one item named Modules. As mentioned previously, the JUCE codebase is divided into loosely coupled modules. Each module generally encapsulates a specific range of functionality (for example, graphics, data structures, GUI, video). The following screenshot shows the available modules and the modules that are enabled or disabled for the JUCE Demo project.

Modules may be enabled or disabled for a particular project that is based on the functionality required for the final application. For example, a simple text-editing app may not need any video or audio functionality, and the modules related to that functionality could be disabled.

Each module also has its own settings and options. In many cases, these are where there might be the option to use native libraries for certain functionality (where performance on each platform may be a high priority) or whether the cross-platform JUCE code should be used for that functionality instead (where consistency across multiple platforms is a higher priority). Each module may have a dependency on one or more other modules, in which case it will be highlighted if it has missing dependencies (and selecting the module will explain which modules need to be enabled to resolve this). To illustrate this, try turning off the checkbox for the juce_core module. All the other modules depend on this juce_core module, which, as its name suggests, provides the core functionality of the JUCE library.

Each module has a copying mode (or Create local copy) option. With this turned on (or set to Copy the module into the project folder), the Introjucer application will copy the source code from the JUCE source tree into the project's local project hierarchy. With this option turned off, the native IDE will be instructed to refer to the JUCE source files directly in the JUCE source tree. Your preference here is a matter of taste and your individual circumstances.

The left-hand Files panel shows the hierarchy of all the source code that will be available in the native IDEs, and the binary files (for example, images, audio, XML, ZIP) that will be transformed into cross-platform source code (and included in the native IDE projects by the Introjucer application). The top-level file structure for the JUCE Demo project is shown in the following screenshot:

Selecting a file in the Files panel enables you to edit the file directly in the Introjucer application. It is currently more convenient to undertake the majority of the code editing in a native IDE that has features such as code completion, error checking, and so on.

Now that we are familiar with the Introjucer application, let's use it to create a project from scratch.

This section will guide you through creating a new Introjucer project, creating a native IDE project from this, and running your first JUCE application. First, close any open Introjucer projects by navigating to the menu item File | Close Project. Next, choose the menu item File | New Project…, and the Introjucer application will present its new project window. Using the Project Folder section of the window, navigate to where you would like to save the project (bearing in mind the project actually comprises a folder containing a hierarchy of code and possibly binary files). As shown in the following screenshot, name the project TestProject001 in the Project Name field, and select the Create a Main.cpp file and a basic window option from the Files to Auto-generate menu:

Finally, click on the Create… button and a familiar Introjucer project should be presented, similar to that shown in the following screenshot:

Initially, the Introjucer application creates only one target IDE platform for the user's current platform. Right-click (on Mac OS X, press control and click) on the project name in the Config panel. This presents a range of options for adding the target platforms to the project, as shown in the following screenshot:

Select the Files panel and notice that the Introjucer application created three files for this basic project:

It is recommended that you add any new files to the projects using this Introjucer project page. As discussed earlier, this ensures that any new files are added to all the projects for all the target platforms, rather than you having to manage this separately. In this example you will not be adding any files. Editing source files in the native IDE is not a problem even though these exact same files are used to compile on all the other platforms your project supports (that is, these files are not copied separately for each platform). You may need to be aware of some differences between compilers, but relying on the JUCE classes where possible (where this has already been taken into account) will help in this regard.

To open the project in your native IDE, first save the project by navigating to the menu item File | Save Project. Then, choose the appropriate option from the File menu to open the native project in the IDE. On Mac OS X, this menu item is Open in Xcode…, and on Windows it is Open in Visual Studio…. There is also a Menu option that combines these two operations, and a shortcut button for it at the bottom of the Config panel.

Once the project is loaded into your IDE, you should build and run the project as you did with the JUCE Demo project earlier. When this succeeds, you should be presented with a window as shown in the following screenshot:

The three source files added to the project by the Introjucer application can be seen in your native IDE. The following screenshot shows the project structure in Xcode on Mac OS X. This is similar in Microsoft Visual Studio.

Edit the MainComponent.cpp file (by single-clicking in Xcode or double-clicking in Microsoft Visual Studio). Examine the MainContentComponent::paint() function. This contains four function calls to draw into the Component object's Graphics context:

Experiment with changing some of these values, and build the application again.

JUCE is fully documented at the following URL:

http://www.juce.com/juce/api/

All the JUCE classes are documented using the Doxygen application (http://www.doxygen.org), which turns specially formatted code comments into readable documentation pages. For this reason, you can also read the comments from within the JUCE source code header files if you prefer. This is sometimes more convenient, depending on your IDE, because you can navigate to the documentation easily from within the code text editor. Throughout the remainder of this book, you will be directed to the documentation for the key classes being discussed.

JUCE is used by a number of commercial developers for applications and audio plugins in particular. Some examples include:

There are many others, some of which keep their use of JUCE a secret for commercial reasons.

This chapter has guided you through installing JUCE for your platform, and by this point you should have a good grasp of the structure of the source code tree. You should be familiar with the capabilities of JUCE through exploring the JUCE Demo project. The Introjucer application that you will have installed and used provides a basis for creating and managing projects using JUCE and the remaining chapters of this book. You will also know where to find the JUCE documentation via the JUCE website, or within the source code. In the next chapter, you will be exploring the Component class in more detail to create a range of user interfaces and to perform drawing operations.