PyANGKernel.GKType

class GKType

Type information for an object

Details

A GKType hold information about the type of every object in the system (objects that inherit from GKObject and has been created with the 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 ( getSuperType , inherits , getSuperTypes , getBaseType ), about its attributes ( getColumns , containsColumn , addExternalColumn ) and its version (GKType::getVersion, GKType::setVersion).

<H2>Type Names</H2>

A type has two names, one internal accessible with getName and setName and one external accessible with getExternalName and 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).

<H2>Extensible Object Model</H2>

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 methods like addExternalColumn , addTemporaryColumn or addPythonFunctionColumn are used. These methods will add an attribute to a type (nothing happen if the attribute was already created).

<H2>Attribute Types</H2>

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).

<H3>Internal Attributes</H3>

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 addInternalColumn method and marking it as internal.

Then it will implement one (or several) methods to get the value of the attribute (as getDataValue or getDataValueInt ) and one method to set it ( 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.

<H3>External Attributes</H3>

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 temporal.

<h2>Creating attributes</h2>

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( GKModel * model, 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.

<h3>Keeping Attributes</h3> Attributes can be retrieved at any moment using its internal name and the GKSystem::getColumn method. But there is a faster way to access well known attribute: keep the ID of the attribute as an static attribute of the class (the attribute ID 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( GKModel * model,  GKType * type )
{
        GKColumn * col = type->addInternalColumn( "speedAtt", QObject::tr("Speed"), GKColumn::Int );
        Road::speedAtt = col->getId();
}

<H2>Artificial Types</H2>

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->addExternalColumn( "Hospital::numberOfBeds", tr( "number of beds" ), GKColumn::Int );

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

<H2>Type Version</H2>

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->addExternalColumn( "Hospital::numberOfBeds", tr( "number of beds" ), GKColumn::Int );
type->addInternalColumn( "Hospital::numberOfAmbulances", tr( "number of ambulances" ), GKColumn::Int );

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).

  1. In the restore operation: read only what is present …

    void Hospital::restore( GKDataStream & s )
{
        GKPolyline::restore( s );
        if( s.getTypeVersion( "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

Synopsis

Methods

Virtual methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

class GKTypeColumnSearchMode
__init__()
addExternalColumn(iname, aname, atype[, from=GKColumn.eDeveloper[, originDescription=std.string()[, dynamic=false[, precision=-1]]]])
Parameters:

  • iname – str

  • aname – str

  • atype – Type

  • from – Origin

  • originDescription – str

  • dynamic – bool

  • precision – int

Return type:

GKColumn

Add a column to this type with the specified name, with an automatically generated GKContents and type eExternal It is mandatory for columns of type _GKTimeSerie to have a valid GKTSDescription assigned before setting any values for a GKObject

addPythonFunctionColumn(contents, atype[, precision=-1])
Parameters:
Return type:

GKColumn

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

addPythonFunctionColumn(iname, aname, atype[, precision=-1])
Parameters:

  • iname – str

  • aname – str

  • atype – Type

  • precision – int

Return type:

GKColumn

addTemporaryColumn(contents, atype[, dynamic=false[, precision=-1]])
Parameters:

  • contents – GKContents

  • atype – Type

  • dynamic – bool

  • precision – int

Return type:

GKColumn

addTemporaryColumn(iname, contents, atype[, dynamic=false[, precision=-1]])
Parameters:

  • iname – str

  • contents – GKContents

  • atype – Type

  • dynamic – bool

  • precision – int

Return type:

GKColumn

Add a column to this type with the specified name, with an automatically generated GKContents and type eExternalTemporary ),

addTemporaryColumn(iname, aname, atype[, dynamic=false[, precision=-1]])
Parameters:

  • iname – str

  • aname – str

  • atype – Type

  • dynamic – bool

  • precision – int

Return type:

GKColumn

Add a column to this type with the specified name, with an automatically generated GKContents and type eExternalTemporary ),

containsColumn(col, columnSearchMode)
Parameters:
Return type:

bool

Returns true if this type contains the column “col”.

containsColumn(aname, columnSearchMode)
Parameters:
Return type:

bool

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

getBaseType()
Return type:

GKType

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 NULL is returned.

getColumn(contents[, columnSearchMode=GKType.GKTypeColumnSearchMode.eSearchThisAndParentTypes])
Parameters:
Return type:

GKColumn

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

getColumn(iname, columnSearchMode)
Parameters:
Return type:

GKColumn

Returns the column called (internal name) “iname” if this type contains it. It returns NULL otherwise.

getColumnByExternalName(aname, columnSearchMode)
Parameters:
Return type:

GKColumn

Returns the column called (external name) “aname” if this type contains it. It returns NULL otherwise.

getColumns(columnSearchMode[, sortedByName=true])
Parameters:
Return type:

.list of GKColumn

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.

getColumns(contents[, columnSearchMode=GKType.GKTypeColumnSearchMode.eSearchThisAndParentTypes])
Parameters:
Return type:

.list of GKColumn

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.

getDescription()
Return type:

str

A description for this type.

getExternalName()
Return type:

str

Type names in a more pleasant way (Section instead of GKSection …)

getModel()
Return type:

GKModel

Returns the model of this type

getName()
Return type:

str

Gets the unique type name.

getPluginName()
Return type:

str

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

getRealType()
Return type:

GKType

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

getStoreObjectsOnModel()
Return type:

bool

getSuperType()
Return type:

GKType

Returns the type from which “this” type inherits.

getSuperTypes()
Return type:

.list of GKType

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

getVersion()
Return type:

int

inherits(atype)
Parameters:

atype – GKType

Return type:

bool

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

isArtificial()
Return type:

bool

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

isInstanciable()
Return type:

bool

Can objects of this type be created? In C++: it is a pure virtual class?

removeColumn(aname)
Parameters:

aname – GKColumn

Removes a column from this type. No object that uses this column is modified. So never call this method. Use instead 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.

removeColumn(aname)
Parameters:

aname – str

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

Note that only external attributes can be removed.

setArtificial(value)
Parameters:

value – bool

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

See also

isArtificial()

setDescription(adescription)
Parameters:

adescription – str

A description for this type.

setExternalName(aname)
Parameters:

aname – str

Type names in a more pleasant way (Section instead of GKSection …)

setInstanciable(value)
Parameters:

value – bool

Can objects of this type be created? In C++: it is a pure virtual class?

See also

isInstanciable()

setModel(amodel)
Parameters:

amodel – GKModel

Sets the model in where this type resides

setName(aname)
Parameters:

aname – str

Sets the unique type name.

setPluginName(name)
Parameters:

name – str

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

setStoreObjectsOnModel(value)
Parameters:

value – bool

setSuperType(atype)
Parameters:

atype – GKType

Sets the type from which “this” type inherits.

setVersion(v)
Parameters:

v – int