GKType Class Reference

Public Types
enum	GKTypeColumnSearchMode { eSearchOnlyThisType , eSearchThisAndParentTypes }

Public Member Functions
	GKType ()
virtual void	setName (const QString &)
const QString &	getName () const
const QString &	getExternalName () const
void	setExternalName (const QString &)
const QString &	getDescription () const
void	setDescription (const QString &)
bool	isInstanciable () const
void	setInstanciable (bool)
bool	inherits (const GKType *) const
QVector< GKType * >	getSuperTypes () const
GKType *	getBaseType () const
GKType *	getSuperType () const
void	setSuperType (GKType *)
bool	isArtificial () const
void	setArtificial (bool)
const GKType *	getRealType () const
GKColumn *	addColumn (const QString &iname, const GKContents &contents, GKColumn::Type atype, GKColumn::GKColumnType astoreType=GKColumn::eExternalTemporary, bool dynamic=false)
GKColumn *	addColumn (const GKContents &contents, GKColumn::Type atype, GKColumn::GKColumnType astoreType=GKColumn::eExternalTemporary, bool dynamic=false)
GKColumn *	addColumn (const QString &iname, const QString &aname, GKColumn::Type atype, GKColumn::GKColumnType astoreType=GKColumn::eExternal, bool dynamic=false)
void	removeColumn (const QString &)
bool	containsColumn (const QString &aname, GKTypeColumnSearchMode columnSearchMode) const
bool	containsColumn (const GKColumn *col, GKTypeColumnSearchMode columnSearchMode) const
GKColumn *	getColumn (const QString &iname, GKTypeColumnSearchMode columnSearchMode) const
GKColumn *	getColumnByExternalName (const QString &aname, GKTypeColumnSearchMode columnSearchMode) const
const QVector< GKColumn * >	getColumns (GKTypeColumnSearchMode columnSearchMode, bool sortedByName=true) const
QVector< GKColumn * >	getColumns (const GKContents &contents, GKTypeColumnSearchMode columnSearchMode=eSearchThisAndParentTypes) const
GKColumn *	getColumn (const GKContents &contents, GKTypeColumnSearchMode columnSearchMode=eSearchThisAndParentTypes) const
void	postRestore ()
uint	getVersion () const
void	setVersion (uint)
const QString &	getPluginName () const
void	setPluginName (const QString &)
void	setStoreObjectsOnModel (bool)
bool	getStoreObjectsOnModel () const

Detailed Description

A GKType holds information about the type of every object in the system that derives from GKObject and that has been created using a new command or using the GKSystem::newObject method).

Every C++ class in the system has its own instance of GKType. Note, but, that is not needed to subclass GKType. All the relevant information is stored already on it. Just new instances of GKType are created and these instances are different in the name and the columns that they have.

A type has information about its super types (GKType::getSuperType, GKType::inherits, GKType::getSuperTypes, GKType::getBaseType), about its attributes (GKType::getColumns, GKType::containsColumn, GKType::addColumn) and its version (GKType::getVersion, GKType::setVersion).

Type Names

A type has two names, one internal accessible with GKType::getName and GKType::setName and one external accessible with GKType::getExternalName and GKType::setExternalName. Both names are set by the user when the type is created.

The internal name is a unique name among all the names for the types, is up to the user to guaranty that the name is unique.

The external name is the name of the type that will be presented to the user. It do not need to be unique and can change during the lifetime of the type (and can be translated).

Extensible Object Model

Keeping the type for each object is useful to discover the attributes that can be used in an object. In some programming languages (as Java) there are a mechanist to discover in run time the attributes of an object. In C++, but, there is no a standard way to do it. In order to by pass this limitation the Aimsun developer has to, explicitly, declare the attributes that she wants to make visible (the developer can make some or all or no one visible).

In order to declare an attribute for a particular type method GKType::addColumn is used. This method will add an attribute to a type (nothing happen if the attribute was already created).

Attribute Types

There are three types of attributes:

• internal (eInternal): exists in C++ and the user just make it accessible.
• external (eExternal): does not exist in C++. Aimsun Next will provide storage in memory and disk for it.
• external temporary (eExternalTemporal): does not exist in C++. Aimsun Next will provide storage in memory (it will not be saved in disk).

Internal Attributes

An internal attribute is the one that exists in the related C++ class. For example:

class Road : public GKPolyline
{
    int speed;
};

The C++ attribute speed from Road is only accessible to C++ code. In order to be discovered and used in run time the developer has to declare it using the addColumn method and marking it as internal.

Then it will implement one (or several) methods to get the value of the attribute (as GKObject::getDataValue or GKObject::getDataValueInt) and one method to set it (GKObject::setDataValue).

Aimsun Next will not store in disk automatically internal attributes. Is the developer (in GKObject::store and GKObject::restore) the responsible for this task.

External Attributes

An external attribute does not exist in C++. It is added in run time to the type and to all the instances of the objects of these type. Aimsun take care of storing it in memory. The developer do not need to write any method to get or set it. The only task to be performed by the developer is the declaration.

By default an external attribute is stored in disk with the rest of the object data. If an attribute do not need to be stored then it has to be declared as temporary.

Creating attributes

A new attribute can be created at any moment, the only restriction is that cannot be used before its creation. But, usually, the developer will create the attributes before creating any object, when the type is created. Aimsun supports the creation of attributes at this time via an special call to a C function.

When a type is registered in the system, the system will look for a C function called TYPE_NAMEInitType( GKType * type ). If the function is found it will be called and the argument will be the registered type. If is not found nothing happen (its optional). You can see this function as the constructor for the new type.

Keeping Attributes

Attributes can be rertieved at any moment using its internal name and the GKSystem::getColumn method. But there is a faster way to access well known attribute: keep a pointer of the attribute as an static attribute of the class (an attribute is unique for each type and only one is keep (and shared) among all the open models).

Example:

class Road : public GKPolyline
{
    int speed;
    static uint speedAtt;
};
... 
void RoadInitType( GKType * type )
{
    GKColumn * col = type->addColumn( "speedAtt", QObject::tr("Speed"), GKColumn::Int, GKColumn::eInternal );
    Road::speedAtt = col->getId();
}

Artificial Types

Not only is possible to add attributes in run time that do not have a C++ implementation (external attributes) but also to add new types in run time that do not have a C++ implementation. These types are called artificial. It is based in a real C++ type with some external attributes on it

It is useful to solve the following problem: Suppose that we need a new class called Hospital and we do not want to code a new C++ class. It has a shape and an attribute called "number of beds". One solution is use the C++ type GKPolygon (that will give us the shape) and add the attribute to it. In this case all the polygons will have this information, what is OK for the polygons that are hospitals but wrong for the rest of the polygons. And, another problem, we will not be able to filter information per type (find only hospitals or change the color of all the hospitals).

The solution is to create a new type in run time, mark it as artificial and set its real type as GKPolyline:

type = GKSystem::registerType( "Hospital", "GKPolyline" );
type->setArtificial( true );
type->setInstanciable( true );
type->addColumn( "Hospital::numberOfBeds", tr( "number of beds" ), GKColumn::Int, GKColumn::eExternal );

The type Hospital do not have any additional method, just the ones that comes from GKPolyline.

Type Version

Aimsun uses version information to restore old versions stored in files. It keep version number per model (in GKModel) and per type. Keeping type version allow us to add/remove/modify information stored in the instances of a type without marking all the document as a new version.

The version of the type is set when the type is registered in the system.

During the restore operation the developer can read the current version of the type using getVersion and the version used to store the information with GKDataStream::getTypeVersion. It will then decided what information has to be read from the data stream.

Example: we will add a new attribute to the Hospital class (number of ambulances). As we want to keep backward compatibility we will: a) Move up the version of the class:

type = GKSystem::registerType( "Hospital", "GKPolyline" );
type->setArtificial( true );
type->setInstanciable( true );
type->setVersion( 1001 ); // Old version was 1000
type->addColumn( "Hospital::numberOfBeds", tr( "number of beds" ), GKColumn::Int, GKColumn::eExternal );
type->addColumn( "Hospital::numberOfAmbulances", tr( "number of ambulances" ), GKColumn::Int, GKColumn::eInternal );

Note that we have add the attribute as an internal one. External attributes are read correctly without the need of a new version (we can add or remove external attributes without changing the version).

b) In the restore operation: read only what is present ...

void Hospital::restore( GKDataStream & s )
{
    GKPolyline::restore( s );
    if( s.getVersionType( "Hospital" ) > 1000 ){
        s >> numberOfAmbulances;
    }else{
         numberOfAmbulances = 0; // no data...
    }
}

Version starts at 1000 and is coded as follow: the last three digits are used to code the minor versions in this way: Mmmr, where M is the major version and is >= 1; mm is the minor version and is between [0,99] and r is the revision [0,9]. Examples: v4.1.1 -> 4011; v10.5.1 -> 10051; v15.12.7 -> 15127

See also

GKColumn, GKObject, GKModel, GKSystem, GKDataStream

Member Enumeration Documentation

GKTypeColumnSearchMode

enum GKType::GKTypeColumnSearchMode

Enumerator
eSearchOnlyThisType
eSearchThisAndParentTypes

Constructor & Destructor Documentation

GKType()

GKType::GKType

(

)

Member Function Documentation

addColumn() [1/3]

GKColumn * GKType::addColumn	(	const GKContents &	contents,
		GKColumn::Type	atype,
		GKColumn::GKColumnType	astoreType = GKColumn::eExternalTemporary,
		bool	dynamic = false
	)

Add a column to this type with the specified GKContents, with an automatically generated name.

addColumn() [2/3]

GKColumn * GKType::addColumn	(	const QString &	iname,
		const GKContents &	contents,
		GKColumn::Type	atype,
		GKColumn::GKColumnType	astoreType = GKColumn::eExternalTemporary,
		bool	dynamic = false
	)

Add a column to this type. If the column already exists, nothing happens.

addColumn() [3/3]

GKColumn * GKType::addColumn	(	const QString &	iname,
		const QString &	aname,
		GKColumn::Type	atype,
		GKColumn::GKColumnType	astoreType = GKColumn::eExternal,
		bool	dynamic = false
	)

Add a column to this type. If the column already exists nothing happen.

containsColumn() [1/2]

bool GKType::containsColumn	(	const GKColumn *	col,
		GKTypeColumnSearchMode	columnSearchMode
	)		const

Returns true if this type contains the column "col".

containsColumn() [2/2]

bool GKType::containsColumn	(	const QString &	aname,
		GKTypeColumnSearchMode	columnSearchMode
	)		const

Returns true if this type contains a column called (internal name) "aname".

getBaseType()

GKType * GKType::getBaseType

(

)

const

Returns the base type for this type, that is the type that start the hierarchy. If this type has no superType (it is already the start of the hierarchy) then None is returned.

getColumn() [1/2]

GKColumn * GKType::getColumn	(	const GKContents &	contents,
		GKTypeColumnSearchMode	columnSearchMode = eSearchThisAndParentTypes
	)		const

Same as getColumns( const GKContents&, GKTypeColumnSearchMode ) but returning the first matching column if there are any, None else.

getColumn() [2/2]

GKColumn * GKType::getColumn	(	const QString &	iname,
		GKTypeColumnSearchMode	columnSearchMode
	)		const

Returns the column called (internal name) "iname" if this type contains it. It returns None otherwise.

getColumnByExternalName()

GKColumn * GKType::getColumnByExternalName	(	const QString &	aname,
		GKTypeColumnSearchMode	columnSearchMode
	)		const

Returns the column called (external name) "aname" if this type contains it. It returns None otherwise.

getColumns() [1/2]

QVector< GKColumn * > GKType::getColumns	(	const GKContents &	contents,
		GKTypeColumnSearchMode	columnSearchMode = eSearchThisAndParentTypes
	)		const

Gets the columns that match the criteria, defined by minimum set of contents that must be contained in the column (the column may contain more).

If "columnSearchMode" is eSearchOnlyThisType only columns that pertains to this type will be returned.

getColumns() [2/2]

const QVector< GKColumn * > GKType::getColumns	(	GKTypeColumnSearchMode	columnSearchMode,
		bool	sortedByName = true
	)		const

Returns a list of all the columns in this type and in all the super types if "columnSearchMode" is eSearchThisAndParentTypes. If "columnSearchMode" is eSearchOnlyThisType only columns that pertains to this type will be returned.

If sortedByName is true, the default, columns will be sorted by their external name.

getDescription()

const QString & GKType::getDescription

(

)

const

getExternalName()

const QString & GKType::getExternalName

(

)

const

getName()

const QString & GKType::getName

(

)

const

Gets the unique type name.

getPluginName()

const QString & GKType::getPluginName

(

)

const

Returns the name of the plug-in in where this type was created.

getRealType()

const GKType * GKType::getRealType

(

)

const

If the object is artificial, get the real (C++) type. If the type is not returns "this".

getStoreObjectsOnModel()

bool GKType::getStoreObjectsOnModel

(

)

const

getSuperType()

GKType * GKType::getSuperType

(

)

const

Returns the type from which "this" type inherits.

getSuperTypes()

QVector< GKType * > GKType::getSuperTypes

(

)

const

Returns all the types in the type hierchy. From its super type to the root. This type is not included.

getVersion()

uint GKType::getVersion

(

)

const

inherits()

bool GKType::inherits

(

const GKType *

)

const

Returns true is this inherits from "atype" (that is: "atype" is a super type of this). If this == "atype" it will return true.

isArtificial()

bool GKType::isArtificial

(

)

const

An artificial type is a type that does not exist in the C++ hierarchy.

isInstanciable()

bool GKType::isInstanciable

(

)

const

postRestore()

void GKType::postRestore

(

)

Binds the superType. Called automatically by the system.

removeColumn()

void GKType::removeColumn

(

const QString &

)

Removes a column from this type. No object that uses this column is modified. So never call this method. Use instead GKModel::removeColumn that will: a) remove any reference to this column in the objects in the catalog b) will call GKType::removeColumn (this method)

Note that only external attributes can be removed.

setArtificial()

void GKType::setArtificial

(

bool

)

setDescription()

void GKType::setDescription

(

const QString &

)

setExternalName()

void GKType::setExternalName

(

const QString &

)

setInstanciable()

void GKType::setInstanciable

(

bool

)

setName()

virtual void GKType::setName ( const QString &  )

virtual

Sets the unique type name.

setPluginName()

void GKType::setPluginName

(

const QString &

)

Sets the name of the plug-in in where this type was created.

setStoreObjectsOnModel()

void GKType::setStoreObjectsOnModel

(

bool

)

setSuperType()

void GKType::setSuperType

(

GKType *

)

Sets the type from which "this" type inherits.

setVersion()

void GKType::setVersion

(

uint

)