PyANGKernel.GKObject¶

class GKObject¶

Main class, almost all the objects derivate from this class.

Details

The main class in the GKernel module. It offers: - A user-defined name - A description (allows the documentation of this object) - Folders (unordered set of objects): see GKFolder - Extensible attributes: see GKType and GKColumn

<h2>Object creation</h2> A GKObject is created using the newObject call, either when a new object is required or when an object is restored from disk or copied (from the clipboard). When an object is created, it receives a type and a model and it’s stored in the catalog ( GKCatalog ). Avoid calling the new operator of a specific class to create an object since all these additional initializations will not be done (the exception to the rule is when the developer wants to create a temporary object and type, model or catalog presence are not required).

Object creation example:

GKModel *model;
...
GPolyline * polyline = (GKPolyline*)GKSystem::getSystem().newObject( "GKPolyline", model );

<h3>Object Factory</h3> The newObject method looks for a C function that creates the object (an object factory). This function, in order to be located, must be called in a specific way and explicitly exported in Windows platform (in the other platforms, symbols in a shared library are exported by default).

For example, if we add MyClass to the system, in order to create instances of it we will implement a C function which name will be MyClass followed by Factory:

extern "C" EXPORT_MACRO GKObject * MyClassFactory( GKModel * model, GKType * type );

The implementation of MyClassFactory will be:

GKObject * MyClassFactory( GKModel * model, GKType * type )
{
return new MyClass();
}

If the developer doesn’t provide an object factory with the correct name, signature and correctly exported, the method newObject will fail and no object will be created.

<h3>Exporting Symbols</h3> Classes and functions defined in the developer plug-in and used by Aimsun (object factories, editor factories, new classes,…) reside in a DLL in Windows or in a shared library in UNIX, Linux and MAC OS X. In Windows platform (due to Microsoft and Intel C++ compilers) these symbols must be explicitly exported, that is, marked as symbols that can be used by the application where the DLL is loaded. In the other platforms these symbols should be exported as well, but with other markings.

In order to export symbols they have to be marked with <tt>__declspec(dllexport)</tt> when the DLL is compiled and must be marked as <tt>__declspec(dllimport)</tt> when the symbol is included by an application that will use it. And, logically, in non Windows platforms no mark is needed at all.

The best way to deal with this requirement is to define a macro for Windows platform as follows:

#include <qglobal.h>

#ifdef _DLL_DEF
#define EXPORT_MACRO Q_DECL_EXPORT
#else
#define EXPORT_MACRO Q_DECL_IMPORT
#endif

This macro requires that, during compilation, the developer defines _DLL_DEF when compiling the DLL. If another DLL or application uses this DLL, then it will not define _DLL_DEF so, in this case, __declspec(dllimport) will be used.

It is recommendable for the name of the macro (EXPORT_MACRO in the example) to be unique among other DLLs. A good name can be, for example, PLUGIN_NAMEEXPORT, where PLUGIN_NAME is the name of the plug-in.

<h2>Identifiers</h2> An object has not only a type and a model but also a unique identifier (set when the object is created the first time via newObject ) and inmutable during all the object lifetime. Use the GKSystem::getId to get the identifier.

It supports also an external identifier using the GKObject::externalIdAtt attribute. This attribute is used to identify this object in an external system where using the unique identifier of this object is not convenient (either because the identifier is coded in a different way or because the identifier was already set and cannot be changed). Use the methods GKObject getExternalId and setExternalId .

<h2>Store and Restore</h2> Objects are stored in a file via the GKObject::store method. The developer must call the store method from the super class first and then add all new information to the data stream. See GKDataStream documentation for further details.

Objects are restored from a file using the GKObject::restore method. The developer must call the restore method from the super class first and, then, read any additional data. Note that versioning is supported. See GKType and GKDataStream for more information.

<h2>Generic Attribute Access (Extensible Object Model)</h2> Aimsun can access attributes from any object in a generic way using the getDataValue and setDataValue methods. These attributes have been declared during the GKType creation.

There is one way to store data in a generic way, using the setDataValue method, and several ways to get the data back: getDataValue , getDataValueInt , getDataValueBool , getDataValueDouble and getDataValueString .

The specific calls are much more efficient as the generic ones, because the user doesn’t need to convert the QVariant to the final type.

As a developer you need to rewrite these functions (the set and the get) only for internal attributes. When doing it, make sure that a call to the supertype method is done if the attribute is not in this type (because it may be in the super type).

For the get, only one function has to be written, either the generic one ( getDataValue ) or the specific one (depending on the attribute type).

An example follows (see also GKType ): If we have the following class:

class Road : public GKPolyline
{
int     speed;
};

Then we will write the set method:

void Road::setDataValue( const GKColumn * attr, const QVariant & v )
{
if( attr->getStoreType() == GKColumn::eInternal ){
        if( attr->getId() == speedAtt ){
        speed = v.toInt();
        }else{
        GKPolyline::setDataValue( attr, v );
        }
}else{
        GKPolyline::setDataValue( attr, v );
}
}

and the get method:

int Road::getDataValueInt( const GKColumn * attr, const GKContext & context ) const
{
int     res = 0;

if( attr->getStoreType() == GKColumn::eInternal ){
        if( attr->getId() == speedAtt ){
        res = speed;
        }else{
        res = GKPolyline::getDataValueInt( attr, context );
        }
}else{
        res = GKPolyline::getDataValueInt( attr, context );
}
return res;
}

or the genetic get method:

QVariant * Road::getDataValue( const GKColumn * attr, bool * deleteit )
{
QVariant        *res = nullptr;

*deleteit = false;
if( attr->getStoreType() == GKColumn::eInternal ){
        if( attr->getId() == speedAtt ){
        res = new QVariant( speed );
        *deleteit = true;
        }else{
        res = GKPolyline::getDataValue( attr, deleteit );
        }
}else{
        res = GKPolyline::getDataValue( attr, deleteit );
}
return res;
}

<h2>Folders</h2> Each GKObject can have a folder in where it can store any kind of data. This folder is called the root folder. This folder can store itself a collection of objects and folders (and so on).

<h2>Object Status</h2> An object changes its status during its lifetime. It goes from ‘new’ when created, to ‘saved’ when stored in disk (or restored from it), to ‘deleted’ when it’s deleted and ‘modified’ when it’s edited (in a dialog, in a command).

All the status changes are managed automatically by the system except the ‘modify’ one. The developer must mark the object as modified when it is modified (usually in the editor during the accept operation and in the command during the undo and redo).

If the object is not marked as modified when it’s modified, it will not be saved in a database (database store and restore will be supported in future Aimsun versions).

When an operation modifies an object, it is important to call increaseTick so that observers of this object are aware of a change.

<h2>Delete commands</h2> When this object is deleted, the system will ask for a delete command using the method getDelCmd . This command will have the responsability for deleting the object and all the references to it (and undo this operation).

See also

GKType GKColumn GKModel GKFolder GKPreferences

Inherited by: GKViewModeStyle, GKViewMode, GKViewBookmark, GKViewBookmarkStatic, GKViewBookmarkDynamic, GKVehicleClass, GKUserClass, GKTripPurpose, GKTrigger, GKTransportationMode, GKTrafficDemandItem, GKTrafficState, GKODMatrix, GKCentroidVector, GKTrafficDemand, GKTrafficArrivals, GKStrategy, GKSimulationEvent, GKPolicy, GKTrafficCondition, GKScript, GKScenarioChange, GKTurningCooperationChange, GKTurningClosingChange, GKTurningBehaviouralParametersChange, GKSectionChange, GKSpeedChange, GKSectionIncident, GKPeriodicSectionIncident, GKSectionBehaviouralParametersChange, GKRoadPricing, GKParkAndRideChange, GKLaneClosingChange, GKForceTurning, GKDisableReservedLaneChange, GKDestinationChange, GKPeriodicCall, GKForceEnrouteAssignment, GKControlPlanChange, GKRoadType, GKReplication, GKExperimentResult, GKRealDataSet, GKPublicLineTimeTableSchedule, GKPublicLineTimeTable, GKPublicLinePlan, GKProblem, GKPathAssignmentPlan, GKPathAssignment, GKPTZonePlan, GKNetworkAttributesOverride, GKModel, GKModeChoiceClass, GKMobileAgent, GKVehicle, GKMasterControlPlan, GKLaneType, GKGroupingType, GKGeometryConfiguration, GKGeoObject, GKSectionObject, GKVMS, GKPedestrianCrossing, GKMetering, GKDetector, GKDetectorStation, GKBusStop, GKRoute, GKSubPath, GKPublicLine, GKODRoute, GKPolyline, GKPolygon, GKSuperNode, GKSimulationArea, GKProblemNet, GKPolygonWithHoles, GKPTZone, GKPTStation, GKGroup, GKExtrudedPolygon, GKCrosswalkArea, GKCentroid, GKImage3D, GKExtrudedPolyline, GKBezierCurve, GKTurning, GKSuperNodeTrajectory, GKSection, GKObjectConnection, GKCenConnection, GKLayer, GKDPoint, GKText, GKNode, GKImage, GKGeoImage, GKController, GKCircle, GKGenericScenario, GKScenario, GKGenericExperiment, GKExperiment, GKFunctionCost, GKFunctionComponent, GKFolder, GKDynamicTrafficSnapshot, GKControlPlanSignal, GKControlPlan, GKControlMetering, GKControlGreenMetering, GKControlGreenMeteringByLane, GKControlFlowMetering, GKControlFlowAlineaMetering, GKControlDelayMetering, GKControlJunction, GKCentroidConfiguration, GKAuthority

Synopsis¶

Methods¶

def __init__()
def cloneAsTemporary()
def createDataValueTS()
def findFolder()
def getCreateRootFolder()
def getExtendedId()
def getLock()
def getNameOrExtendedId()
def getParentFolders()
def getRootFolder()
def getStatus()
def getTick()
def getType()
def getUUID()
def isA()
def isDataValueNull()
def isDataValueZero()
def isExternal()
def isTemporary()
def newUUID()
def notifyStatusChange()
def __eq__()
def removeColumn()
def removeDataValue()
def renameFolder()
def resetColumn()
def setDescription()
def setExternal()
def setExternalId()
def setRootFolder()
def setTemporary()
def setTick()

Virtual methods¶

def addedToCatalog()
def canBeDeleted()
def canBeEdited()
def canBeModified()
def clearDataValueTS()
def clone()
def exists()
def getDelCmd()
def getDelConnectionCmd()
def hasAnyTSWithData()
def hasTSWithData()
def increaseTick()
def init()
def nonCommandObjectRemoved()
def preferencesChanged()
def removedFromCatalog()
def setAggregatedValueInTS()
def setDataValue()
def setDataValueDouble()
def setDataValueInTS()
def setDataValueObject()
def setId()
def setLock()
def setModel()
def setName()
def setStatus()
def setType()
def setUUID()

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 IdentifierFormFlag¶: When asking for the extended identifier ( getExtendedId ) of an object, the information to use to create it. It can be a combination of: - eIdentifierId: the identifier - eIdentifierName: the name - eIdentifierExternalId: the external ID - eIdentifierDescription: the description - eIdentifierTypeExternalName: the externalName of the type

class GKLockType¶: Lock types for this object.

class GKObjectStatus¶: See getStatus

__init__()¶

__init__(o)

Parameters:: o – GKObject

addedToCatalog()¶

Called by the catalog when this object is added to it.

canBeDeleted()¶

Return type:: bool

Return true is this object can be deleted. This function can be rewritten to support complex locks as objects locked because its container is locked.

canBeEdited()¶

Return type:: bool

Return true is this object can be modified. This function can be rewritten to support complex locks as objects locked because its container is locked.

canBeModified()¶

Return type:: bool

Return true is this object can be modified. This function can be rewritten to support complex locks as objects locked because its container is locked.

clearDataValueTS(attr)¶

Parameters:: attr – GKColumn

Clears an existing Time Series.

clone([addItToModel=true[, temporary=false]])¶

Parameters:

addItToModel – bool
temporary – bool

Return type:

GKObject

Returns this object copied in a new one. It will be added to the catalog by default unless the ‘addItTomodel’ is false. * If temporary is true, the object will be temporary.

cloneAsTemporary([addItToModel=true])¶

Parameters:: addItToModel – bool
Return type:: GKObject

Returns this object copied in a new temporary one. It will be added to the catalog by default unless the ‘addItTomodel’ is false.

createDataValueTS(attr, aDescription)¶

Parameters:

attr – GKColumn
aDescription – GKTSDescription

Return type:

GKTimeSerie

Creates a time series for the provided Column and returns it. Description is mandatory for creation. * If the time series already exists for that Column it just returns the existing one without alter it in any way.

exists(scenario)¶

Parameters:: scenario – GKGenericScenario
Return type:: bool

Returns true if this object exists in the scenario. An object can exists in several, all or just one scenario. * If scenario is 0 it will return always true. * Objects exists or not based on Geometry Configuration settings attached to the Scenario. * * Only geo objects are marked as existing or not directly. Non geo objects can be nonexistent based on contained * geo objects (for example a Signal Group exists if all the turnings exists).

findFolder(byName)¶

Parameters:: byName – str
Return type:: GKFolder

Finds a folder by its internal name among the different folders in this object.

See also

findFolder

getCreateRootFolder()¶

Return type:: GKFolder

Returns the root folder. If the root folder doesn’t exist it will create one.

getDelCmd()¶

Return type:: GKObjectDelCmd

Object will be deleted. The user must write a suitable GKObjectDelCmd subclass and return it in this method. The implementation in this class returns a GKObjectDelCmd as it is (it removes the object from the GKModel and delete it if needed after command destruction, removes the object from the GKGeoModel and removes connections to it).

getDelConnectionCmd(target)¶

Parameters:: target – GKObject
Return type:: GKObjectConnectionDelCmd

This object has connections to “target” and “target” will be removed. Create and return a delete command to handle undo and redo of the affected connections. If the object is deleted outside a command (no UNDO) then the model will call nonCommandObjectRemoved instead.

If this method returns a NULL it means that the delete is not possible and the command will not be done. If an object is connected to another but decides that no information is needed in the delete command then it has to return an empty GKObjectConnectionDelCmd instead of a NULL.