Switch to: V10V9V8V7V6V5

VCursorController

Inherits from NSObjectController
Represents object VCursor
Declared in V4CC_VCursorController.h

Overview

VCursorController provides access to the VCursor class.

To get the content of a database you should specify a SQL query and parameters of the query.

In the Query field you can type an SQL query, which will define the content of a cursor.

Also you can set the following options for SQL query (according to Valentina enums ):

  • Location ( 'None', 'Client', 'Server' );
  • Lock Type ( 'None', 'No Lock', 'Read Only', 'Read Write' );
  • Direction ( 'None', 'Forward Only', 'Random' );

Connections

In this section basic VCursorController connections are described. They should simplify data displaying and data managing using GUI.

Bindings

VCursorController provides two types of bindings:

  1. Binding to the records of cursor ( to Fields);
  2. Binding to the VCursorController properties.

For example, if you want to show a record in the name field of VCursor in TExtField, all you should do - is bind this field with VCursorController. For example:

If you want to bind to the field with compounded name, for example - “First Name”. You should set name with an underline instead blank - “First_Name.” This should be done because we can't type name with blanks in the binding field.

Except cursor's fields, VCursorController provides bindings to the next properties:

Binding Properties
canDoNextRecord returns YES if You can go to the next record, otherwise NO.
canDoPrevRecord returns YES if You can go to the previous record, otherwise NO.
canDoFirstRecord returns YES if You can go to the first record, otherwise NO.
canDoLastRecord returns YES if You can go to the last record, otherwise NO.
canModifyRecords returns YES if You can modify first record, otherwise NO.
countRecords returns count of records in the VCursor
currentRecord returns index of current record and provides 'go to' possibility

Actions

VCursorController provides access to the 'record methods' of the VCursor class, using Outlets technology.

For example, if you want that when you click button, the cursor will pass to the next record. All you should do - is connect nextRecord action of VCursorController with button.

VCursorController provides Actions:

Action Result
firstRecord moves cursor to the first record
lastRecord moves cursor to the last record
nextRecord moves cursor to the next record
prevRecord moves cursor to the previous record
goToRecord moves cursor to the set record
addRecord adds a new record in the cursor
dropRecord droops current record
deleteRecord deletes current record
deleteAllRecords deletes all records
updateRecord updates current record
updateAllRecords updates all records
newRecord creates a new record
flushDatabase saves changes in database

Outlets

VCursorController uses outlets, for providing data sources for VCursor class and for displaying cursor's content in TableView:

Outlet Function
databaseController provides data source for cursor from VDatabase
tableView shows cursor in table

Tasks

Please familiarise with tasks of all controllers before programming your application. Some tasks may be invoked and executed by high-level's objects. And you should not invoke them directly.

Construction Methods

Init Cursor Controller

Properties

Class Methods

Init Methods

-(id)initWithQuery:(NSString*)inQuery;
-(id)initWithQuery:(NSString*)inQuery cursorLocation:(EVCursorLocation)inCursorLocation;
-(id)initWithQuery:(NSString*)inQuery cursorLocation:(EVCursorLocation)inCursorLocation lockType:(EVLockType)inLockType;
-(id)initWithQuery:(NSString*)inQuery cursorLocation:(EVCursorLocation)inCursorLocation lockType:(EVLockType)inLockType direction:(EVCursorDirection)inDirection;
- (id)initWithQuery:(NSString*)inQuery cursorLocation:(EVCursorLocation)inCursorLocation lockType:(EVLockType)inLockType direction:(EVCursorDirection)inDirection binds:(NSArray*)inBinds;

This group of methods initializes property for SQL select query:

  • inQuery - a string which represents SQL query;
  • inCursorLocation - cursor location flag, can be Client or Server according to EVCursorLocation enum ;
  • inLockType - define rules for data change, can be No Locks, ReadOnly or kReadWrite, according to EVLockType enum;
  • inDirection - define direction of selection can be Forward Only or Random, according to EVCursorDirection;
  • inBinds - cursor binds.

To init properties - you can use one of the init methods in dependence of needed cursor type. (For more info look SQL Methods for VDatabase class).

initWithCursor:

Establishes VCursor instance for VCursorController

- (id)initWithCursor:(VCursor*)inCursor;

Return Value
VCursorController object.

Discussion
This method is helpful when you don't use VCLient(Local)Connection and VDatabaseConnection but you want to show cursor's content in GUI. You can represent VCursorController in a .nib file and in the program, connect them by reference outlet. Init the controller with a current method, and use bindings and outlets to represent cursor's content.

intiWithCursor:andTableView:

Establishes VCursor instance, an NSTableView object for VCursorController

- (id)intiWithCursor:(VCursor*)inCursor andTableView:(NSTableView*)inTableView;

Return Value
VCursorController object.

Discussion
This method is helpful when you don't use VCLient(Local)Connection and VDatabaseConnection but you want to show cursor's content in NSTableView in GUI. You can represent VCursorController in a .nib file and in the program, connect them by reference outlet. Init the controller with a current method, and display the cursor's content in the table.

dealloc

Releases VCursorController properties.

- (void)dealloc;

windowWillClose

Flush database when window where was represented VCursorController is closing.

- (void)windowWillClose:(NSNotification*)notification;

Discussion
You should not invoke this method. Its function is to guarantee to save cursor's changes in the database when you close the application window.

initCursorController

Initialize VCursor object. -(void)initCursorController;

Discussion
The task of this method is to fill your own VCursor object according to the given properties. It occurs in several steps (from top to down):

  1. initialization of VDatabaseController;
  2. VDatabaseController initializes own VLocalConnection, or VClientConnection;
  3. connection controller initialize own Valenina instance.
  4. when Valentina instants is inited - initialized VConnection object.
  5. when VConnection is inited - initialized VDatabase object;
  6. when VDatabase is inited - carried out SQL query;
  7. the result of a SQL query records in the VCursor object of VCursorController.

Let's take a look what methods are invoked* for this(from down to up):

-initConnection or -initConnection

-initDatabaseController

-makeSelectWithQuery:cursorLocation:lockType:direction:binds:

* - methods of initializes of properties for controllers are not considered.

So, if you use VCursorController you should not use above-listed methods for other controllers.

awakeFromNib

Automatically initializes VCursorController and references controllers in the runtime, when using IBPLugin.

-(void)awakeFromNib;

Simply invokes -initCursorController method.

cursor

Accessors for VCursor object, of the VCursorController.

- (VCursor*)cursor;
- (void)setCursor:(VCursor*)inCursor;

databaseController

Accessors for VDatabaseController object, of the VCursorController.

- (VDatabaseController*)databaseController; - (void)setDatabaseController:(VDatabaseController*)inDatabaseController;

query

Provides access to the SQL query string. Query - defines cursor' content.

- (NSString*)query;
- (void)setQuery:(NSString*)inQuery;

locationTypes

Used by IBPlugin to set the value of the pop-up button.

- (NSArray*)locationTypes;

Return Value

Array with strings: “Default” “Client” @“Server”.

currentLocationType

Accessors for currentLocationType property, of the VCursorController.

- (EVCursorLocation);
- (void)setCurrentLocationType:(int)inCurrentLocationType;

Discussion
Look EVCursorLocation enum for specify property value.

lockTypes

Used by IBPlugin to set the value of the pop-up button.

- (NSArray*)lockTypes;

Return Value

Array with strings: @“Default”, @“No Lock”, @“Read Only”, @“Read Write”.

currentLockType

Accessors for currentLocationType property, of the VCursorController.

- (EVLockType)currentLockType; - (void)setCurrentLockType:(int)inCurrentLockType;

Discussion
Look EVLockType enum for specify property value.

directionTypes

Used by IBPlugin to set the value of the pop-up button.

- (NSArray*)directionTypes;

Return Value

Array with strings: “Default”, “Forvard Only”, “Random”, .

currentDirection

Accessors for currentLocationType property, of the VCursorController.

- (EVCursorDirection)currentDirection;
- (void)setCurrentDirection:(int)inCurrentDirection;

Discussion
Look EVCursorDirection enum for specify property value.

cursorBinds

Unused in this version. Default Value - nil.

tableView

Accessors for NSTableView object, of the VCursorController.

- (NSTableView*)tableView; - (void)setTableView:(NSTableView*)inTableView;

Discussion
Use this method if you want to display cursor content in the table in your application.

Code example

- (VCursor*)getCursor
{
	VClientConnection*	clientConnection;
	VDatabaseController*	databaseController;
	VCursorController*	cursorController;
 
	clientConnection = [[VClientConnection alloc] initWithHost:@"localhost" 
							  userName:@"sa"
							  password:@"sa"];
 
	databaseController = [[VDatabaseController alloc] initClientDatabaseName:@"db1.vdb"];
	[databaseController setConnectionController:clientConnection];
	[databaseController initDatabaseController];
 
	cursorController = [[VCursorController alloc] initWithQuery:@"SELECT * FROM Person"];
	[cursorController setDatabaseController:databaseController];
 
	[cursorController awakeFromNib];
 
        return 	[cursorController cursor];
}