Switch to: V10V9V8V7V6V5

Lesson 1 - Using the VCursorController

Step 1: Create a New Project

Create a New Project

  1. Start Xcode.
  2. Select – Create a new Xcode project.
  3. Select – Application → Cocoa Application.
  4. Set the project name – Employees.
  5. Select location for a new project.

Add V4CC_x64 Framework

To use Valentina in your application, you should add the V4CC framework to the project:

  • Select the project file
  • Go to Build Phases, section Link Binary With Libraries.
  • Push Add button, and select V4CC_x64.Framework

The V4CC_x64.Framework should be included in the list of frameworks for the Base SDK of your application.

Step 2: Connect to Valentina

Geting Access to the Valentina API

To get access to the Valentina API you should import V4CC.h file to the application:

#import <V4CC_x64/V4CC.h>

Init Valentina

Before start using any Valentina methods you should initialize the Valentina engine. For this purpose create a new method in the application:

  • Open Employees folder in the project.
  • Select the AppDelegate.h file and add a new method to it:
- (void)   initValentina;
  • Add the implementation of this method ( AppDelegate.m file ):
- (void)initValentina
		[[Valentina instance] initWithCacheSize: 10 * 1024 * 1024];
	@catch( ... ) 
		NSRunCriticalAlertPanel( @"Valentina was not inited.",
				         @"Ok", NULL, NULL );

This method will initialize the Valentina engine with 10MB cache.

Add Shutdown Code

To properly finish the work with Valentina engine you should invoke the shutDown method for the Valentina instance. Perform this in the destructor of AppDelegate class to shut down the Valentina when the application is closed.

- (void) dealloc
	[[Valentina instance] shutDown];
	[super dealloc];


To be sure that the application can use Valentina angine we should invoke the initValentina method:

- (void) applicationDidFinishLaunching:(NSNotification *)aNotification 
	[self initValentina];

Build and run the application.

  • If the application is built successfuly – the framework was launched correctly.
  • If the application is running without errors – the Valentina engine was initialized correctly.

Step 3: Create Database

Now we should add the methods to work with database:

  • to create a new database
  • to open an existing database
  • to close the databases

Init Database

The access to the database will be provided by the appropriate variable:

VDatabase*	mpDatabase;

To open database add next method to the AppDelegate class.

- (void)initDatabase
	mpDatabase = [[VDatabase alloc] initWithStorageType:EVStorageType_kDefault];
	NSString* databasePath = [[NSBundle mainBundle] bundlePath]; 
	databasePath = [NSString stringWithFormat:@"%@/../%@", databasePath, @"Employees.vdb"];
		[mpDatabase open:databasePath];
	@catch( ... )
			[mpDatabase create:databasePath];		
		@catch ( ... ) 
			NSRunCriticalAlertPanel( @"Database was not inited.",
						 @"Ok", NULL, NULL );

If the database was already created, this method will open it. Otherwise a new database will be created.

Close Database

To be sure, that the database will be correctly closed we should finish the work with it properly. For this purpose add next code to the destructor:

if( mpDatabase )
     [mpDatabase close];
     [mpDatabase release];

Flush Data

To save changes in the database we should implement an appropriate method:

- (void)saveChanges:(id)sender
	[mpDatabase flush];

Step 4: Create Table

Let's create the table with three fields: FirstName, LastName, Mail, in the database. It will store the data processed by this application:

- (void)createTable
	if( [mpDatabase tableForName:@"Person"] )
		// Table Person is already exist. 
		VTable* tblPerson = [mpDatabase createTable:@"Person"];
		[tblPerson createStringField:	@"FirstName"	maxLength:20];
		[tblPerson createStringField:	@"LastName"	maxLength:25];
		[tblPerson createDateField:	@"Mail"         maxLength:100];

This code will create the empty table with three fields using Valentina API.

Step 5: Prepare Controller

To manage data we suggest to use the VCursorController class. It contains all needed actions to manage data, and supports cocoa bindings technology. Using VCursorController you can ADD DELETE APDATE data, or navigate records through, without writting any code.

At this step just add VCursorController to the AppDelegate class:

IBOutlet VCursorController* mpCursorController;

Step 6: Prepare User Interface

Open the MainMenu.nib file in Interface Builder. Add text fields, labels, buttons, and lines, like shown in the picture:

Step 7: Connect Views With Controller

Add Controller

Firs of all you should add the VCursorController to the nib file:

  • add the NSObjectController object to nib
  • open inspector for this object
  • open Identity. Type VCursorController in the field Class.

Connect Outlets

To bind VCursorController object in MainMenu.nib file to the mpCursorController (member of EmployeesAppDelegate class) you should do:

  • Select VCursorController object in nib file.
  • Go to the Connections tab in Inspector.
  • Drag New Reference Outlet to the AppDelegate object.
  • Select mpCursorController outlet in the connection panel.

Connect Bindings

Now you can bind text fields to the Valentina Cursor fields by name. For this:

  • Select first field where should be displayed the FirstName field.
  • Go to Bindings tab of Inspector.
  • Select Value panel.
  • Set Bind to Cursor Controller.
  • Type FirstName in Model Key Path field.


Repeat this steps to bind LastName and Mail text fields to the appropriate cursor fields.


Now we should connect the buttons to the appropriate actions of the VCursorController:

  • Select VCursorController object in nib file.
  • Go to the Connections tab in the Inspector. Here you can see the list of all needed actions for managing cursor's content.
  • Connect Actions to corresponding buttons:
Button Action
First firstRecord
Previous prevRecord
Next nextRecord
Last lastRecord
Delete deleteRecord
Update updateRecord
Add addRecord
New newRecord

As a result, the Connections tab of VCursorController may have next view:

At last you should connect the saveChanges action of the EmployeesAppDelegate object with Save button. Do the same as you connect actions of VCursor Controller.

Step 8: Get Cursor From Database

To fetch and manage data it is needed to initialize the VCursor:

- (void)initCursorController
	VCursor* cursor = [mpDatabase sqlSelect:@"Select * From Person" 
	[mpCursorController setContent:cursor];

Now you can manage database content through VCursorController.

Step 9: Completing Code of Application

Now we should gather all methods needed to connect to the database and manage data:

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification 
	[self initValentina];
	[self initDatabase];
	[self createTable];
	[self initCursorController];		

Step 10: Testing Application

Now you can build and run the application.

At first launch the database is empty, and of course the text fields will be empty too.

Add some records:

  • Push New button.
  • Fill text fields.
  • Push Add button.

You have added a new record into the cursor. Do this several times.

Now you can test navigate buttons - try to push “First” or “Next” buttons.

To save cursor content into database press the “Save” button.

If you launch Application again you'll see that the database is not empty. Now you can change old records, or add new ones.