Chapter 2: Setting up the Hilo Development Environment
The Hilo Browser application is a sample application written in C++. The application uses the Microsoft Windows 7 operating system application programming interface (API) through the Win32 and DirectX libraries. This article outlines how to set up a workstation for the development environment so that you can compile and run the Hilo Browser sample application. In subsequent articles, we’ll be walking through the code and explaining the rationale for the choice of technologies, the UI design, and the implementation of the application’s features.
Setting up the Developer Workstation
Windows 7 offers a wealth of Windows C/C++ API features for developers. The Hilo Browser application has been developed using Visual C++ 2010 Express. The minimum machine configuration needed to install Visual C++ 2010 Express is:
- 1.6 GHz or faster processor
- 1024 MB RAM (1.5 GB if running on a virtual machine)
- 3 GB of available hard-disk space
- 5400 RPM hard-disk drive
- DirectX 9-capable video card running at 1024 x 768 or higher display resolution
The Windows Ribbon will be used in subsequent Hilo applications. To write code for the Ribbon you must install the Windows Software Development Kit (SDK) for Windows 7. The SDK requires a minimum of 2.5 GB of free space, so this means that to install the software needed to compile all of the Hilo applications you need at least 5.5 GB of disk space. The installation of the SDK is covered in detail below.
Clearly a free development environment will have some restrictions, but perhaps surprisingly, the restrictions are not great. Visual Studio 2010 Express editions give the developer a functional development environment that can be used to create fully featured applications.
The features of the various Visual Studio editions are available on the MSDN website. Compared to the Professional edition, the main features that the Express edition lacks are that it only provides the 32-bit compiler, and it lacks the ActiveX Template Library (ATL) and Microsoft Foundation Classes (MFC) libraries. The C++ compiler is fully featured except that it does not provide profile guided optimizations. Furthermore, the Express edition does not supply all the tools provided with the Professional edition, but perhaps the one that you will miss early on is integrated resource editor—you will have to use external editors to edit bitmaps and icon files (Windows 7 Paint will do this).
Downloading Visual Studio from the MSDN Website
Visual C++ 2010 Express is available as a free download using the web download tool from the following address:
https://www.microsoft.com/express/Downloads/#2010-Visual-CPP
Once downloaded you should run the setup tool (Figure 1), agree to the license conditions, and select whether to download the optional components. Hilo does not require the optional components (Silverlight nor SQL Server 2010 Express) so deselecting these options will make the download and installation quicker (Figure 2).
Figure 1 The web download and installation application
.png "Ff742833.31ce9e89-ea71-434a-96f3-352847bce696(en-us,MSDN.10).png")
Figure 2 The download options
.png "Ff742833.2a73c709-c15b-4d12-92be-d3285d645917(en-us,MSDN.10).png")
Next you will be asked where to install the application (here you should use the defaults) and finally you will be shown a progress dialog (Figure 3) showing the components being downloaded and installed. As a guide, the minimum installation of Visual C++ will involve downloading 146 MB of data.
Figure 3 Downloading Visual C++ 2010 Express
.png "Ff742833.f5ed379d-8bf2-48ee-89df-4596f23b0015(en-us,MSDN.10).png")
Although the Hilo application does not use SQL Server, you will notice that Visual C++ 2010 will download and install SQL Server Compact edition. This is a separate product and it is used by Visual C++ 2010 to create the C++ program database (in previous versions of Visual Studio this was the .ncb file, which is used to store IntelliSense data for your code).
Registering Visual C++ Express Edition
Once Visual C++ 2010 Express has been installed you may run it for 30 days before the trial period expires. To use it beyond this time you need to register it. The registration option is on the Help menu (Figure 4).
Figure 4 Command to register Visual C++ 2010 Express
.png "Ff742833.8ef14a43-398c-49ce-a421-4ac75fc2dcef(en-us,MSDN.10).png")
The menu command gives the registration dialog shown in Figure 5.
Figure 5 Registering Visual C++ 2010 Express
.png "Ff742833.14421f98-9b82-4e21-bdca-bd6eb169efd5(en-us,MSDN.10).png")
When you click on the button marked Obtain a registration key online your browser will open the registration page on the Microsoft website. To obtain a registration key you must first log on using a Windows Live ID (which requires registering some minimal details) and then the website will return a registration key.
Figure 6 Obtaining a registration key
.png "Ff742833.487b8d97-f353-41b6-9900-5bd638c1a6ab(en-us,MSDN.10).png")
You should copy this key and paste it in the Registration Key box on the registration dialog (shown in Figure 5) and then click the Register Now button. Once you have registered the product the time restriction will be removed.
Using Help
One of the most important parts of a development environment is the help system. Visual C++ 2010 comes with two types of help documentation: local and online and these are configured through the Manage Help Settings item on the Help menu (Figure 7).
Figure 7 Managing the source of the help documentation
.png "Ff742833.e71c841e-31cf-469e-b52f-13699acdc8e8(en-us,MSDN.10).png")
The first time that you run this command you will be asked for the location of the local help system (Figure 8), accept the value suggested by clicking OK.
Figure 8 Starting the Help Library Manager
.png "Ff742833.612c534f-9a52-4137-9fe5-c8667d9891b9(en-us,MSDN.10).png")
Next you will see the actual Help Library Manager (Figure 9).
Figure 9 Running the Help Library Manager
.png "Ff742833.0440248a-46ee-4f5e-bc01-8d0814e2fe9b(en-us,MSDN.10).png")
Visual Studio 2010 help is browser based, but you have to choose whether the help data is locally installed, or web based. If you select the option to use the online help system then you can use help immediately. The advantage of the online system is that each page has a Community Content section that may contain helpful comments from members of the online community, and indeed, you can even add your own tips.
The local help system does not benefit from the community contributions, but since it is installed on your computer it means that you can use it even if you do not have a network connection. Before you can use local help you must install it. The help content is supplied as libraries of related APIs and to download and install this content you should use the Help Library Manager option Install content from online. When you select this option the manager will first search the web for available content and list the help topics in a table with an Add link in the Action column next to each help topic (Figure 10).
Figure 10 Installing documentation from online
.png "Ff742833.951bf177-0eac-446b-9b29-4207bc6c0fe5(en-us,MSDN.10).png")
The following help topics are relevant to Visual C++ Express:
- Visual Studio C++
- Visual Studio (All)
- Visual Studio Fundamentals
- Win32 and COM Development
When you have selected at least one topic you can click the Update button to download and install the documentation. This process may take a while (if you choose the libraries in the list above, about 1 GB will be downloaded) so now is definitely a good time to have a cup of coffee or two. Unfortunately the Manager does not warn you before the download starts how much disk space will be needed, so you should ensure that you have several gigabytes of free space to take into account the space needed for the final documentation and for the intermediate files. Once the Manager informs you that the documentation has been installed you can close the main Manager dialog by clicking Exit.
The first time that you use the locally installed help system Visual C++ 2010 will start the Help Library Agent. This is a simple HTTP server running on port 47873 on your computer. When you press F1 in Visual C++ 2010 to obtain help for a feature or a keyword the help system will determine the web page and create a URL to the appropriate file on port 47873 on the loopback address. The Help Library Agent will then locate the page within the compressed help files and return them to your registered browser.
Other than the community content section, there is no difference between the online and local help. Both help systems have a search box and show a tree view of the available help (to aid browsing).
Installing the Windows 7 SDK
There are two ways to install the Windows SDK for Windows 7 through the web tool or by downloading an ISO image of the DVD and then installing the SDK from the DVD. The DVD ISO image contains the entire SDK, but at install time you can choose which items you install. Both the web tool and the ISO image are available from the Microsoft download site.
The web tool is called winsdk_web.exe and is has an initial download size of 492 K. There are three ISO images available on the download site, for x86 32-bit, AMD64 64-bit and for Itanium 64-bit development. The Express edition of Visual C++ 2010 is only available in a 32-bit version, but you still must install the version of the SDK for the platform where you install Visual C++. The ISO files are approximately 1.5 GB in size.
Once you have burned the DVD you can start the installation by running the setup.exe file in the root folder of the DVD. Alternatively, you can run the web tool winsdk_web.exe. Both tools have the same user interface and start with an introduction page, Figure 11.
Figure 11 The Windows SDK installation program
.png "Ff742833.915150f8-f75b-42be-bc8f-1cf8e2c0b3c5(en-us,MSDN.10).png")
The following pages request that you accept the license agreement and then provide the location to install the SDK, accept the defaults. The next page lists the items that can be installed, Figure 12.
Figure 12 Installation options for the Windows 7 SDK
.png "Ff742833.98d954ae-e93a-4a2a-8cd5-341305d3253a(en-us,MSDN.10).png")
The tool indicates the disk space required for the selected options and, if you are using the web tool, you will also see an estimate of the amount of data that will be downloaded. A full install requires 4.5 GB of disk space and will download 2.5 GB of data. If you have sufficient disk space and installing from the DVD then you can simply install the entire SDK. If you have limited disk space or you are installing from the web then the absolute minimum you should install is the Win32 Development Tools from the Development Tools, Windows Development Tools section. The Win32 Development Tools will take up 42 MB of disk space.
Once you have selected the install options and clicked the Next button the setup program will download, decompress and install the items you selected, Figure 13.
Figure 13 Installing the SDK
.png "Ff742833.76b71a39-c294-415e-835f-12405cfbcecd(en-us,MSDN.10).png")
When the setup program has finished you must reboot the computer to complete the installation. You do not need to make any changes to your C++ projects since Visual C++ 2010 will automatically add the paths to the SDK tools to the search path it uses.
The SDK uses the Microsoft Document Explorer to display help, rather than the web browser based system used by Visual C++ 2010. The Microsoft Document Explorer is the help system used by previous versions of Visual C++, however, it is not integrated into the Visual C++ 2010 development environment.
Configuring Visual Studio
All of the settings of the Visual C++ 2010 Express environment can be changed. This allows you to configure the environment for your own preferences or to your employer’s coding standards. The main configurations are accessed through the Options menu item on the Tools menu. This dialog gives five categories of configuration options shown in the following table.
Category |
Description |
|---|---|
Environment |
General options for the integrated development environment, things like the fonts that will be used, keyboard short cuts, and startup options. |
Projects and Solutions |
Options for the general locations of solutions, how and when projects are built, and information about things like the extensions of C++ project files. |
Text Editor |
Options for the size of tabs and whether tab characters or spaces are used, and options about indenting code. |
Debugging |
General options for how the debugger works, whether Edit and Continue is allowed, and the location of symbol files. |
There are too many options to list here in detail, however, every developer is different and customizing the development environment to something that the developer is comfortable with is important, so we will list the common settings here.
Changing the Fonts
The Environment category has a subcategory called Fonts and Colors, Figure 14.
Figure 14 Configuration page used to change the code editor fonts
.png "Ff742833.d7fba720-609b-479f-bf43-eaa45d25d392(en-us,MSDN.10).png")
This page allows you to change the font used for individual tool windows, or several related windows within the design environment. Through this dialog you are able to choose a font size and font type that you are comfortable using. It is perhaps one of the most important configuration settings because you will spend most of your time reading text.
Changing the Keyboard Shortcuts
The Environment category has a subcategory called Keyboard, shown in Figure 15.
Figure 15 Configuration page used to change keyboard shortcuts
.png "Ff742833.0896ada5-0bdc-47bb-80a1-845bb9bbadbc(en-us,MSDN.10).png")
This page allows you to specify the keyboard shortcut keys that you can use to perform commands in the development environment. The commands mentioned in the list box are menu items. To change a command you click on the Press shortcut keys text box and press the appropriate key combination, the page will inform you if this key combination is already being used and allows you to choose to assign the key combination to the command.
If you typically use another development environment you may be used to different keyboard shortcuts than the defaults for Visual C++ 2010 Express. The ability to change the keyboard shortcuts means that you can get started to using Visual C++ immediately without having to learn new keyboard combinations.
Changing the Code Editor Settings
Code formatting is sometimes personal preferences, and sometimes a company policy, so it is important to know how to change them. Figure 1 shows the Text Editor category that you can use to change the tabs and indentation for C++ code.
Figure 16 Text editor tab options
.png "Ff742833.16e86c28-5ae9-4d4e-8bfc-69092ebb0015(en-us,MSDN.10).png")
Figure 17 The code editor Advanced options
.png "Ff742833.9da9fd7b-084d-4dc0-9573-8ebca02eb0b4(en-us,MSDN.10).png")
The Advanced options are about the database that will be created to enable code browsing, shown in Figure 17.
For example, the Rescan Solution Interval (by default 60 minutes) indicates how often the solution is rescanned to refresh the database. The browser database contains information about the classes and global functions in the project and this information is used by Class View, the navigation bar at the top of code windows and by the search menu items like Go To Definition, Go To Declaration and Find All References. The term database is used figuratively and literally because Visual C++ Express uses a SQL Server Compact database (with the extension sdf) to hold this code browser information.
Changing Other Settings
The Class View is a standard tool window in previous versions of Visual C++, however, when you start Visual C++ 2010 Express it will appear that this tool is no longer available. This is not the case, Class View is still supplied, but you have to use the environment in Expert mode. Figure 18 show the menu items that allow you to select Expert mode. On the Tools menu click the Settings submenu and then click Expert Settings to show Class View or Basic Settings to hide it.
Figure 18 Menu setting to select Expert mode
.png "Ff742833.ce054c95-fa44-4d9b-bead-7b3ff5431d42(en-us,MSDN.10).png")
In addition to exposing the Class View, selecting Expert Settings also enables other items, including the Property Manager, exposes menu items that allow you to enable the Extension Manager, and give you access to external tools like the MSIL Disassembler or Ildasm (for managed projects) and the Error Lookup utility. The Property Manager allows you to share project configurations between projects, while the Extension Manager gives you access to the installed extensions and allow you to browse the Microsoft online extensions gallery and download extensions.
Installing the Hilo Solution
The Hilo Browser solution is available as a ZIP archive from the MSDN Code gallery. On the Downloads page click the link for the code you wish to download and accept the license agreement. The ZIP file will then be downloaded to your hard disk. Once the download has completed, unzip the contents of the archive to a folder on your hard disk (for example, the Documents\My Documents\Visual Studio 2010\Projects library). Now browse the solution folder and double click on the Hilo.sln file to start Visual C++ 2010 Express and load the solution. For each project that is loaded you may see a security dialog, click OK to continue loading the project.
When the projects have been loaded, you will see at the bottom of the window the status message “Parsing included files.” This indicates that the environment is scanning the files in the solution and building the browsing database. When the scan has completed you can use the Class View and other tools like the Find All References context menu item.
To build the solution, click the Build menu and then click the Build Solution menu item. The results of the build operation will be shown in the Output tool window. If the installation of Visual C++ 2010 Express and the Hilo solution was successful then the solution should build without any errors or warnings. If you’re using Visual C++ 2010 Express, however, you will receive a warning about the x64 build because Visual C++ 2010 Express does not support 64 bit projects. You can safely ignore this warning.
To test the application, click the Debug menu and then click Start Without Debugging. The Hilo Browser application will start and show the contents of the Windows 7 Pictures library. You can now try out the application, spin the carousel to view the subfolders and touch (or with a mouse, click) on a folder to open it and view the images. Close the Hilo Browser when you have finished exploring its features.
Examining the Hilo Project
A Visual C++ 2010 project is made up of project files, resource files, and code files. The standard view in the Solution Explorer shows the code and resource files categorized as Header Files, Resource Files, and Source Files. Solution Explorer is shown in Figure 19. However, these Solution Explorer folders do not reflect the folders in the project disk folder, you can create any folders you like and move files between them without affecting where the file is saved.
Figure 19 Solution Explorer in Visual C++ 2010 Express
.png "Ff742833.47327044-9d55-4300-90d5-5f1101311175(en-us,MSDN.10).png")
The resource files are items like icon files and bitmaps and the resource compiler script file (.rc file). The Express edition of Visual C++ does not contain the resource editor, so to change the resources that will be bound to the executable file you must edit the resource script manually. To do this, right click on the resource script in the Solution Explorer, and click View Code. The other resources, like bitmaps and icons, must be edited with external tools, to do this double click on the item in the Solution Explorer and Visual C++ 2010 Express will launch the editor registered with Windows to open the file type.
On the disk, the Hilo Browser project is a subfolder of the solution folder and headers, source code files, and resource files are stored in this folder. The Browser project folder also has the project file, .vcxproj, a filters file, .vcxproj.filters and a user settings file, .vcxproj.user.
Visual C++ 2010 uses the MSBuild build tool. The .vcxproj file lists the targets in the build and the compiler and linker options used by the compilers. If you run the MSBuild utility from the command line in the project directory it will automatically load the .vcxproj file and build the targets specified in it.
The .vcxproj.filters file lists all the targets and the folder where they appear in the SolutionExplorer. This file is only used by the Solution Explorer and it is not used as part of the build. Similarly, the .vcxproj.user file contains user interface information for the current user.
When you open the solution for the first time in Visual C++ Express the environment will parse the source files and generate the code browser database, the .sdf file, and a folder called ipch which contains the IntelliSense pre-compiled header files that are used to provide IntelliSense information as the developer types code. This means that if you intend to distribute the solution, the absolute minimum collection of files that you should include are the code and resource files, the .sln file, and the project files .vcxproj and .vcxproj.filters, all the other files will be generated by Visual C++ if they do not exist.
Changing Project Options
The options in the .vcxproj file are edited using the property pages of the Solution Explorer. To do this, right click on the project entry in the Solution Explorer (make sure that you click on the project not the solution) and from the context menu click Properties. These property pages are categorized into pages for the tools, build events and debugging. The project property pages are shown in Figure 20.
Figure 20 Project configuration property pages
.png "Ff742833.40abd498-e5e2-4667-90ba-f2b34dd84b44(en-us,MSDN.10).png")
The four main tools used to build a project are in one of the following categories: C/C++ compiler, Linker, Manifest Tool, and Resources for the resource compiler. In all case you will have one or more property pages where you can change individual options, and a page called Command Line where you can type the command line switches for the options you want to use. The build tool values that you set through the project properties will be applied to all source files, if you wish to apply an option for just one file then you should use the property pages of that individual file.
In addition to the build tool options there are also property pages for build events and debugging, and a property page called VC++ Directories that allows you to provide additional search folders for the current project for the include folder, library folder and executable folders.
Debugging the Solution
Debugging a solution with Visual C++ 2010 Express is very simple. The first action to ensure that the solution is built with debugging information, and to do this you must ensure that the Debug build option is selected on the Standard toolbar, Figure 21, and then rebuild the solution.
Figure 22 Selecting the Debug build option
.png "Ff742833.84ae908f-ff88-44cb-9f76-37811e3198e0(en-us,MSDN.10).png")
Setting a breakpoint is simple: click on the line where you wish to set a breakpoint and then through the Debug menu click Toggle Breakpoint. A red breakpoint glyph appears in the indicator margin on the left of the line, as shown in Figure 22. You can also toggle a breakpoint by clicking in the indicator margin.
Figure 22 Toggling a breakpoint in the code editor
.png "Ff742833.efe9d46f-9d81-48bc-97d6-87a826e483a9(en-us,MSDN.10).png")
Once you have set breakpoints you can start debugging by clicking the Start Debugging option on the Debug menu. When a breakpoint is reached the debugger will pause at that point, Figure 23, and display a yellow arrow glyph above the breakpoint.
Figure 23 Debugging the Hilo Browser
.png "Ff742833.4bc9d0bb-5463-4d48-b16e-2c1422cd37ee(en-us,MSDN.10).png")
In addition several new tool windows will appear. The Autos window shows the values of the variables on the current line of code, the Locals window shows all the variables in the current scope. If the variable is a pointer to an object instance then you can expand the entry to show the values of the object’s members. You may also change the value of a variable through one of these variable windows.
When the application runs under the debugger the Debug toolbar will show (the toolbar is shown at the top of Figure 23). This toolbar allows you to control the debugging. Using this toolbar you can run the application until the next breakpoint, stop the application or single step. If you choose to single step then you can choose to step into the function at the current execution point, or step over it as a single action, or indeed, you can step out of the current function as a single action.
Conclusion
Now that your development environment is set up and you have compiled and run the Hilo Browser application, we’re ready to start walking through the code in more detail. In the next article, we’ll discuss the technologies that were used to develop the Hilo Browser application.