Release 1.0  Copyright ã1994 by Arcane Systems Ltd.  All Rights Reserved.

ThreadKit

Tutorial

Installation

This tutorial assumes that you have the full developer version of NEXTSTEP and ThreadKit installed on your local machine.

1.	Make sure you have NEXTSTEP Developer installed

	The application /NextDeveloper/Apps/InterfaceBuilder.app will exist if you have the developer package installed.
	
	See the documentation that accompanies NEXTSTEP developer for installation instructions.

2.	If you haven't done so already, install ThreadKit.pkg

	You can tell that ThreadKit has already been installed if the file /LocalDeveloper/Documentation/ThreadKit exists.
	
	You'll need to log in as root in order to install ThreadKit.  If you don't know the root password for the computer you're using, you'll need to have your system administrator install ThreadKit for you.

Creating a New ThreadKit Project

A few basic steps will be required every time you create a new application that will use ThreadKit.  These steps are as follows:

1.	Launch ProjectBuilder and create a new project
	
2.	Add the ThreadKit library to your project

	Double-click on the Libraries suitcase for your new project, and add the ThreadKit library /usr/local/lib/libThreadKit.a

	You'll need to include this library any time you create an application that uses the ThreadKit.  If you forget to include the library you'll get "ld: Undefined symbols" errors when you try to compile and link your application.

3.	Open your project's .nib file

	Open the .nib file for your new project by double clicking on the entry listed in the Interfaces suitcase.  Interface Builder will automatically be launched if it isn't already running.
	
4.	Introduce Interface Builder to the ThreadKit classes

	In the Workspace Manager, select the primary class definitions for ThreadKit by finding the directory /LocalDeveloper/Headers/threadkit and then select TKApplication.h and TKObject.h.  Drag the files onto the Classes suitcase in Interface Builder.
	
	You won't usually need to create subclasses of TKResource or TKThread, so you probably don't need to add their definitions to Interface Builder.
	
5.	Tell Interface Builder to use TKApplication instead of Application

	Select the Objects suitcase and then the File's Owner icon within Interface Builder.  Press Command-1 to display the inspector panel and select TKApplication in the class list.
	
	Without this step your ThreadKit application will behave in unexpected ways since application kit locking won't occur properly.  Your main .nib file's owner must be an instance of TKApplication or one of its subclasses.

A Simple Application

For your first ThreadKit application, we'll create a simple class that performs work in the background and displays results on screen.

1.	Create a subclass of Object named Counter

	Select the Classes suitcase in Interface Builder and scroll all the way to the left in the class browser.  Select the Object class and then pull down the Operations list and select Subclass.
	
	Press Command-1 to display the class inspector, type in the name "Counter" and press return.
	
2.	Create an outlet for the Counter class

	Select the Outlets radio button on the class inspector and enter the outlet name "text" into the entry field at the bottom of the inspector.  The outlet should be added to the list when you press return.

3.	Unparse the Counter class

	Pull down the Operations list and select Unparse.  This allows Interface Builder to create a class definition you'll use later to add custom code to the Counter class.
	
	A dialog box asking "Create .../Counter.[hm]?" will be displayed.  Press the Yes button to let Interface Builder create the files for you.
	
	Another dialog box, this time asking "Insert file Counter.[hm] in project?" will be displayed.  Press the Yes button so that this class will be automatically compiled for you later.

4.	Create two instances of Counter

	Pull down the Operations list and select Instantiate.  Select the Classes suitcase and do it again.  You should now have two objects named "Counter" and "Counter1"
	
5.	Create two text fields and connect the Counter instances to them

	Drag the display-only text field labelled "Title" from Interface Builder's palette to your application's window, labelled "My Window".  Hold down the control key, and drag a connection from the instance named "Counter" to the new text field.
	
	Press the Connect button in the inspector.
	
	Repeat the above for "Counter1", creating another text field and making another connection.
	
6.	Save the interface

	That's all the work you'll need to do in Interface Builder, so select Save from the Document menu and hide Interface Builder.
	
7.	Modify Counter.h

	Select the Headers suitcase in Project Builder and double-click on the file Counter.h.  Add the lines shown below in bold (or copy and paste the whole file if you'd rather):

#import <appkit/appkit.h>

@interface Counter:Object
{
    id	text;
}

- awakeFromNib ;
- startCounter ;

@end

	Save the changes and close the Counter.h window.

8.	Modify Counter.m

	Select the Classes suitcase in Project Builder and double-click on the file Counter.m.  Add the lines shown below in bold (or copy and paste the whole file if you'd rather):

#import "Counter.h"
#import <threadkit/threadkit.h>

@implementation Counter

- awakeFromNib
{
	[ [ TKThread alloc ] initFor: self
			perform: @selector ( startCounter ) ] ;
	return self ;
}

- startCounter
{
	int		counter;
	
	while ( 1 )
	{
		counter = 0 ;
		while ( counter <= 100 )
		{
			[ NXApp threadLock ] ;
			[ text setIntValue: counter ] ;
			[ NXApp threadUnlock ] ;
			counter++ ;
		}
		sleep ( 2 ) ;
	}
}

@end

	The method awakeFromNib is called automatically when your application creates the interface at runtime.  The code above creates a new thread and starts it by sending a message to itself to startCounter.
	
	The startCounter method counts from 0 to 100, locking the application kit and displaying the value at each step.  After counting to 100 it waits for two seconds and starts the process again.
	
	Save the changes and close the Counter.m window.

9.	Test the application
	
	Press the Run button in Project Builder.  A dialog box asking "Project is modified.  Save before building?"  will be displayed.  Press the Yes button and Project Builder will automatically compile and link your application.
	
	If you've done everything right the application should start and display two text fields counting independently from 0 to 100!