GKCatalog Class Reference

Public Member Functions
	GKCatalog ()
uint	size (const GKType *) const
const QMap< uint, GKObject * > *	getObjectsByType (const GKType *type) const
QVector< GKObject * >	getObjectsByTypeWithSubTypes (const GKType *type) const
QVector< const QMap< uint, GKObject * > * >	getUsedSubTypesFromType (const GKType *) const
GKObject *	find (uint) const
GKObject *	findByName (const QString &, const GKType *=0, bool=false) const
End void	catalogObjectExternalId (GKObject *)
void	uncatalogObjectExternalId (GKObject *obj)
GKObject *	findObjectByExternalId (const QString &, const GKType *=0) const
QVector< GKObject * >	findObjectsByExternalId (const QString &byId, const GKType *type=NULL)
void	add (GKObject *)
bool	remove (GKObject *)
void	setStatusOfAllObjects (const GKObject::GKObjectStatus &)
void	removeDataValue (const GKColumn *)
void	clearDeathObjects ()
void	increaseTickByType (const GKType *)

Public Attributes
MethodCode	sipRes = sipCpp->find( *a0, a1, (Qt::CaseSensitivity)a2 )

Detailed Description

The catalog contains all the alive objects in the model. It organizes the objects by type and unique identifier. An unique instance of this class exists in every GKModel instance.

Objects are added to the catalog either through the New commands or the GKSystem::newObject method and they are removed when the object is deleted (in the GKObject destructor).

It is also possible to remove the object from the catalog without deleting it by calling the method GKCatalog::remove. If the developer wants to add the object again she can use the method GKCatalog::add.

It keeps a list of all the objects that have been removed from the catalog (dead objects). This list is accessible using the method GKCatalog::getDeathObjects.

When an object is added to the catalog it calls the object method GKObject::addedToCatalog and when the object is removed from the catalog it calls the object method GKObject::removedFromCatalog.

GKCatalog::getObjectsByType and GKCatalog::getUsedSubTypesFromType

The most used methods are GKCatalog::getObjectsByType and GKCatalog::getUsedSubTypesFromType to iterate over all the instances of one class (or a class hierarchy tree) and the GKCatalog::find method to locate an object by identifier or by name.

Use GKCatalog::getUsedSubTypesFromType when you want to get all the instances of a class and all its subclasses and use GKCatalog::getObjectsByType to access all the instances of only one class.

Usually the method to use will be GKCatalog::getUsedSubTypesFromType since it is possible that new types are added to the system and that the user uses these new types instead of the old ones. For example: an algorithm writes a report in a file for all the sections (instances of GKSection) in a network. Later on, another developer adds a new class as a subtype of GKSection (with some extra attributes) and creates new instances of these new class. The algorithm, if using the GKCatalog::getObjectsByType method, will not report the sections that are instances of the new class. On the other hand, if the GKCatalog::getUsedSubTypesFromType method is used, the report will include all the sections from both classes.

An example of the use of GKCatalog::getUsedSubTypesFromType in C++ follows (it iterates over all the instances of GKSection and GKSection derivates to generate a report):

void GKSectionReport::generate() const
{
    QFile                                                   file( reportPath );
    GKSection                                               *section;
    GKCatalogObjectsById::const_iterator                    iter;
    QVector<const GKCatalogObjectsById*>                    types;
    QVector<const GKCatalogObjectsById *>::const_iterator   iterTypes;
 
    types = getModel()->getCatalog().getUsedSubTypesFromType( getModel()->getType( "GKSection" ));
    if( file.open( QIODevice::ReadOnly ) ){
        QTextStream stream( &file );
 
        for( iterTypes = types.begin(); iterTypes != types.end(); iterTypes++ ){
            for( iter = (*iterTypes)->begin(); iter != (*iterTypes)->end(); iter++ ){
                section = dynamic_cast<GKSection*>( iter.value() );
                if( section  ){
                    stream << section->getId() << "\t" << section->getName()
                        << "\t" << section->getDataValueDouble( GKSection::speedAtt ) << "\n";
                }
            }
        }       
        file.close();   
    }
}

And example in Python that prints the ID of all the section follows:

from PyANGBasic import *
from PyANGKernel import *
 
model = GKSystem.getSystem().getActiveModel()
for types in model.getCatalog().getUsedSubTypesFromType( GKSystem.getSystem().getType( "GKSection" ) ):
    for key in types:
        section = types[key]
        print section.getId()   

Constructor & Destructor Documentation

GKCatalog()

GKCatalog::GKCatalog

(

)

Member Function Documentation

add()

void GKCatalog::add

(

GKObject *

)

Adds "obj" to the model catalog. Pointer is not adopted.

catalogObjectExternalId()

End void GKCatalog::catalogObjectExternalId

(

GKObject *

)

Catalogs this object by its external ID.

clearDeathObjects()

void GKCatalog::clearDeathObjects

(

)

Clears the dead objects map

find()

GKObject * GKCatalog::find

(

uint

)

const

Finds an object by id. If no object is found a None will be returned.

findByName()

GKObject * GKCatalog::findByName	(	const QString &	,
		const GKType *	= 0,
		bool	= false
	)		const

Finds an object by name (slow operation). If type is different than None it will just look into objects of type "type" and subclasses of type, otherwise it will look in all the objects. If caseSensitive is true the search will be case sensitive.

findObjectByExternalId()

GKObject * GKCatalog::findObjectByExternalId	(	const QString &	,
		const GKType *	= 0
	)		const

Finds an object by its external ID. If a type is specified the object of that type with that external ID will be returned. If no type is specified, the first object found with the specified externalID will be returned

findObjectsByExternalId()

QVector< GKObject * > GKCatalog::findObjectsByExternalId	(	const QString &	byId,
		const GKType *	type = NULL
	)

Finds objects with the same external ID. If more than one is present (which is not recommended) all of them will be returned.

getObjectsByType()

const QMap< uint, GKObject * > * GKCatalog::getObjectsByType

(

const GKType *

type

)

const

Returns the model catalog but only for type "type". This catalog contains then all the instances of type "type". Note that instances of a subtype of type will not be returned.

Note that this method can return a None pointer if no object of type "type" exists.

See also

getUsedSubTypesFromType

getObjectsByTypeWithSubTypes()

QVector< GKObject * > GKCatalog::getObjectsByTypeWithSubTypes

(

const GKType *

type

)

const

Returns the model catalog including all objects from type "type" and its subtypes.

See also

getUsedSubTypesFromType

getUsedSubTypesFromType()

QVector< const QMap< uint, GKObject * > * > GKCatalog::getUsedSubTypesFromType

(

const GKType *

)

const

Returns a collection of types (and all its object instances) that:

• are subtypes of "type" or are "type"
• contains any element in the catalog

This method is needed to perform operations in objects in the catalog that are subtypes of a type. Using getObjectsByType will return the instances of the type but not the instances of subtypes.

This method can be used to to know if there is any instance of "type" or one of its subtypes since it will only return types with instances. Example: to know if there are instances of GKPolyline:

if( getUsedSubTypesFromType( model->getType( "GKPolyline" ) ).size() > 0 ){
    // there are instances
}else{
    // no instances
}

increaseTickByType()

void GKCatalog::increaseTickByType

(

const GKType *

)

Increases the tick for all the objects of type "type" and subclasses of type found in the catalog

remove()

bool GKCatalog::remove

(

GKObject *

)

Removes "obj" from the model catalog. Returns true if the object was in the catalog (and, thus, has been removed). The object is not deleted, just removed from the catalog.

removeDataValue()

void GKCatalog::removeDataValue

(

const GKColumn *

)

Removes an external attribute value from all the objects that use it.

setStatusOfAllObjects()

void GKCatalog::setStatusOfAllObjects

(

const GKObject::GKObjectStatus &

)

Changes the status of all the objects. Used after loading or saving a model (All the objects will be marked as saved).

size()

uint GKCatalog::size

(

const GKType *

)

const

Returns the number of objects of type "type" (or subtypes of "type") in the catalog. If type is None then returns the total number of objects in the catalog.

uncatalogObjectExternalId()

void GKCatalog::uncatalogObjectExternalId

(

GKObject *

obj

)

Uncatalogs this object by its external ID.

Member Data Documentation

sipRes

MethodCode GKCatalog::sipRes = sipCpp->find( *a0, a1, (Qt::CaseSensitivity)a2 )