Home

Welcome to the idiary wiki! This small documentation explains the basics of compiling, running and creating interactive books with the idiary framework. This documentation assumes that you are familiar with XCode, Objective-C and Cocos2D.

Compiling and running the example diary

Alice' diary

The source code is located under src and contains an XCode project file iDiary2.xcodeproj. Everything is ready to compile so you can start with the example diary Alice and play around with it.

Targets and schemes

For the example diary, a target named Alice was created. One needs a separate compile target for each diary/book application using this project. For each target there are two compile schemes in XCode: Release and Debug, respectively in this case Alice-Release and Alice-Debug. Use the first for distribution and the second one for testing.

Folder structure and naming conventions

The following gives an overview about the main folder structure. It is also reflected in the XCode project file groups.

_Documentation	- not much, yet. But everthing is in the wiki.
_Scripts		- contains the script for converting PSDs to code/sprites
src				- contains... the sources!
	iDiary2				- sources of the XCode project
		Audio			- Sound classes
		Ctrl			- Main controller classes
		libs			- Cocos2D, Box2D, etc.
		Model			- Data structure classes
		Pages			- Important! Pages for each diary/ebook
		Resources		- Important! Graphics, anim., videos for each diary/ebook
		Util			- Utility classes
		View			- Important! Classes for interactive objects on the pages (sprites, layers, etc.)
	iDiary2.xcodeproj	- XCode project file

The Pages and Resources folder

In the src/iDiary2/Pages folder, the implementations for each page of each diary/ebook are contained. The structure of the foldes and files is the following:

Pages/<DIARY_NAME>/Page_<DIARY_NAME>_<PAGE_NAME>.h/.mm

Important: Note that you should always use the file extension .mm for class implementations instead of .m because this causes XCode to compile the file as Objective-C++ file which is important because the code also includes C++-classes (for example from Box2D).

Also important: The class name should also be Page_<DIARY_NAME>_<PAGE_NAME>. See "Diary Definitions" and "Adding pages to a book" for more information.

In analogy to that, the resources for each page are located in the following folders:

Resources/PageContents/<DIARY_NAME>_<PAGE_NAME>/   - for page-specific content
Resources/PageContents/<DIARY_NAME>/               - for book-specific content

Diary definitions

Each book or diary has a special file diary defintion file which is a header file containing information about which pages are available in which order for a book/diary. The file is located at Ctrl/DiaryDefinitions/Diaries_<DIARY_NAME>.h. For our example Alice, it is included with the compiler flag -DDIARIES_HEADER=\"Diaries_Alice.h\" in the Other C++ Flags setting of the XCode project build settings. For our example, the header file contains the following code:

static NSArray *diaryAlice = [NSArray arrayWithObjects:
  @"Intro",            // 0
  @"Example2",         // 1
  ...
  @"Example8",         // 7
nil];

So this array basically defines the order of the pages of a book/diary. The classes that implement a diary page are automatically instantiated by using this information. So the first page that is rendered in this case must be implemented in the class Page_Alice_Intro (in file Page_Alice_Intro.h/.mm). See "Adding pages to a book" on how to implement such a PageLayer class.

Creating a new book

When you want to create another book from the same sources, you don't need to copy the whole project and restart from scratch. Just create a new compile target and its compile schemes plus the needed folder structure and a diary definition and there you go.

Creating a new compile target Bob and its schemes

At first, you should duplicate the existing target Alice and rename it to Bob. Also rename the Product name in the Build settings of the target. Then you can rename the default build scheme and add a Bob-Release scheme if you want.

Creating a new diary definition

Change the compiler flag -DDIARIES_HEADER=\"Diaries_Alice.h\" to use the file Diaries_Bob.h in the Other C++ Flags setting of the target's build settings. Duplicate the Diaries_Alice.h file and rename it to Diaries_Bob.h. Change the content of the file to:

// These Arrays define the pages
static NSArray *diaryBob = [NSArray arrayWithObjects:
    @"Intro",            // 0
    nil];
   
// This dictionary associates the diary-arrays with the persons
static NSDictionary *diaryPages = [NSDictionary dictionaryWithObjectsAndKeys:
    diaryBob, @"Bob",
    nil];

// These Arrays define meta data for diaries, such as the position of the diary in the startscreen, page offset, anim corner size
static NSArray *metaDataBob = [NSArray arrayWithObjects:
    [NSValue valueWithCGPoint:ccp(395, 768-417)],       // position of the diary in the startscreen
    [NSValue valueWithCGPoint:ccp(-1.5, 0)],            // page offset
    [NSValue valueWithCGSize:CGSizeMake(242, 200)],     // page corner animation size
    [NSValue valueWithCGPoint:ccp(-1, 1)],              // page corner offset
    [NSValue valueWithCGPoint:ccp(0, 0)],       // disclamer coordinates
    nil];

// This dictionary associates the diary-metadata-arrays with the persons    
static NSDictionary *diaryMetaData = [NSDictionary dictionaryWithObjectsAndKeys:
    metaDataAlice, @"Bob",
    nil];    

// global settings
static NSMutableDictionary *globalSettings = [NSMutableDictionary dictionaryWithObjectsAndKeys:
    [NSNumber numberWithBool:NO], @"controlElemShown",
    nil]; 

Now we have a diary definition that tells the system to load a class Page_Bob_Intro as the first page of Bob's diary. We will implement this class later.

Setting up the folder structure

Adding pages to a book

Generating page code and graphics from a Photoshop PSD file