Interface ChildrenIdCardGetterInterface

The ChildrenIdCardGetterInterface interface is used to retrieve information about the children of a part instance (and not a geometric instance id), such as the metadata of the children parts, link, the list of children attached document, ....

The metadata documents and general information about the children can be retrieved by knowing the part instance id of the parent to retrieve. Such documents are usually requested after an idcard request.

The ChildrenIdCardGetterInterface interfaces are created through the createChildrenIdCardGetter method.

/** 
 * Sample to illustrate the use of an ChildrenIdCardGetterInterface from a `part instance id`, to get the brothers of a part instance.
 */
import {
    VisibilityContextInterface, IdCardGetterInterface, IdCardGetterInterfaceSignal, ChildrenIdCardGetterInterface,
    ChildrenIdCardGetterInterfaceSignal, PartInstanceInfoInterface, InfiniteEvent, ChildrenPartInstanceInfoInterface, DataSessionInterface,
} from 'generated/documentation/appinfiniteapi';
// the `part instances` are retrieved by a picking for example

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// the `part instance id` to get information from (get its brothers)
let lPartInstanceId : number;
// the current filtering context has been created previously
let lVisibilityContext : VisibilityContextInterface;

// what to do when the id card retrieval is over
let onIdCardReady : (pEvent, _pCallbackData) => void;

// what to do when the children id card retrieval is over
let onChildrenIdCardReady : (pEvent, _pCallbackData) => void;

// id card getter interface creation
const lIdCardGetterInterface : IdCardGetterInterface = lDataSession.createIdCardGetter();
// children id card getter interface creation
const lChildrenIdCardGetterInterface : ChildrenIdCardGetterInterface = lDataSession.createChildrenIdCardGetter();

// connect the IDCardReady signal to the handling of the metadata of the `part instance` and its genealogy 
lIdCardGetterInterface.addEventListener(IdCardGetterInterfaceSignal.IdCardReady, onIdCardReady);

// connect the GeometricInstanceConverterReady signal to the id card retrieval
lChildrenIdCardGetterInterface.addEventListener(ChildrenIdCardGetterInterfaceSignal.ChildrenIdCardReady, onChildrenIdCardReady);

// trigger the idcard retrieval
lIdCardGetterInterface.retrieveIdCard(lPartInstanceId, lVisibilityContext);

// onIdCardReady will be called when data is available
onIdCardReady = (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) : void =>
{
    if (lIdCardGetterInterface.getLastError().length !== 0) {
        // do nothing in case of error
        // perhaps some GUI code ?
        return;
    }
    const lPartInstanceInfos : Array<PartInstanceInfoInterface> | undefined = lIdCardGetterInterface.getPartInstanceInfos();
    if (!lPartInstanceInfos || lPartInstanceInfos.length !== 1)
    {
        // no data (isCancelled ?)
        return;
    }
    // we required only one `part instance`, as such, only one result should be retrieved
    // iterate over the instantiation chain, but take the first chain since one `part instance` retrieved
    const lCurrentChain : PartInstanceInfoInterface = lPartInstanceInfos[0];

    // number of items 
    const lNbAncestors : number = lCurrentChain.getAncestors().length;

    // the parent offset is the one before last
    const lParentOffset : number = lNbAncestors - 2;
    if (lParentOffset < 0)
    {
        console.log(lPartInstanceId + ' is a leaf instance, exiting');
        return;
    }
    const lParentInstanceId : number = lCurrentChain.getAncestors()[lParentOffset];
    lChildrenIdCardGetterInterface.retrieveChildrenIdCard(lParentInstanceId, lVisibilityContext);
}

// onChildrenIdCardReady will be called when data is available
onChildrenIdCardReady = (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) : void =>
{
    if (lChildrenIdCardGetterInterface.getLastError().length !== 0) {
        // do nothing in case of error
        // perhaps some GUI code ?
    }
    const lPartInstanceInfos : Array<ChildrenPartInstanceInfoInterface> | undefined = lChildrenIdCardGetterInterface.getPartInstanceInfos();
    if (!lPartInstanceInfos || lPartInstanceInfos.length !== 1)
    {
        // no data (isCancelled ?)
        return;
    }
    // we required only one `part instance`, as such, only one result should be retrieved
    // iterate over the instantiation chain, but take the first chain since one `part instance` retrieved
    const lChildren : ChildrenPartInstanceInfoInterface = lPartInstanceInfos[0];

    // number of children 
    // const lNbChildren : number = lChildren.getChildren().length;
    // we should have the part instance in the list of children
    const lIndexOfMe : number = lChildren.getChildren().indexOf(lPartInstanceId);
    if (lIndexOfMe < 0)
    {
        console.log('something really weird has happen, I am not in the list of children of my parent, am I the root ?');
        return;
    }

    // we get the `part` metadata of me (but should do something else even more interesting)
    const lPartMetadata : Object = lChildren.getChildrenIdCard().partmd[lIndexOfMe];
    // some fancy output
    console.log(JSON.stringify(lPartMetadata));
}

The metadata retrieval procedure is triggered through the retrieveChildrenIdCard methods. The result is not available right away, but the event ChildrenIdCardReady is triggered when the result of the ChildrenIdCardGetterInterface is available. The result is available through the [getPartInstanceInfos]] function.

Warning : there may be cases when the getPartInstanceInfos is not available such as when the ChildrenIdCardGetterInterface is updating, i.e. when isRunning returns true, or when the ChildrenIdCardGetterInterface has been cancelled, i.e. when isCancelled returns true.

An ChildrenIdCardGetterInterface may be interrupted (cancelled) when the ChildrenIdCardGetterInterface is updating and cancel is called. In such cases, the ChildrenIdCardCancelled signal is fired, and shortly after, ChildrenIdCardReady signal is fired, but getPartInstanceInfos will return undefined. Just call retrieveChildrenIdCard with another (or the same) part instance ids to trigger a new retrieval.

If you call multiple times retrieveChildrenIdCard before receiving the ChildrenIdCardReady, only one ChildrenIdCardReady will be sent with the content of the last call to retrieveChildrenIdCard.

The developer may process the results of an id card retrieval with the following code :

/** 
 * Sample to illustrate the use of an ChildrenIdCardGetterInterface with the parsing of
 * PartInstanceInfoInterface to display some information about a part instance.
 */
import {
    VisibilityContextInterface, ChildrenIdCardGetterInterface, ChildrenIdCardGetterInterfaceSignal,
    InfiniteEvent, ChildrenPartInstanceInfoInterface, PartInstanceInfoStatusFlag, DataSessionInterface
} from 'generated/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// created previously
let lVisibilityContext : VisibilityContextInterface;
// the `part instance id` to get
let lPartInstanceId : number;
// what to do when we have retrieved id card information ?
let onChildrenIdCardReady : (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) => void;

// create an ChildrenIdCardGetter
const lChildrenIdCardGetterInterface : ChildrenIdCardGetterInterface = lDataSession.createChildrenIdCardGetter();
// what to do when result is ready ?
lChildrenIdCardGetterInterface.addEventListener(ChildrenIdCardGetterInterfaceSignal.ChildrenIdCardReady, onChildrenIdCardReady);

// onChildrenIdCardReady will be called when data is available
onChildrenIdCardReady = (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) : void =>
{
    if (lChildrenIdCardGetterInterface.getLastError().length !== 0) {
        // do nothing in case of error
        // perhaps some GUI code ?
    }
    const lPartInstanceInfos : Array<ChildrenPartInstanceInfoInterface> | undefined = lChildrenIdCardGetterInterface.getPartInstanceInfos();
    if (!lPartInstanceInfos || lPartInstanceInfos.length !== 1)
    {
        // no data (isCancelled ?)
        return;
    }
    // we required only one `part instance`, as such, only one result should be retrieved
    // iterate over the instantiation chain, but take the first chain since one `part instance` retrieved
    const lCurrentChildren : ChildrenPartInstanceInfoInterface = lPartInstanceInfos[0];

    // number of items 
    const lNbChildren : number = lCurrentChildren.getChildren().length;
    if (lNbChildren <= 0)
    {
        console.log('this part instance is a leaf');
        return;
    }
    // take the last child
    const lChildInstanceOffset : number = lNbChildren - 1;
    // we get the `part` metadata of the last child of the `part instance`
    const lPartMetadata : Object = lCurrentChildren.getChildrenIdCard().partmd[lChildInstanceOffset];
    // some fancy output
    console.log(JSON.stringify(lPartMetadata));

    // get the flags in order to get information about the `part instance`
    const lFlags : number = lCurrentChildren.getChildrenStatusFlags()[lChildInstanceOffset];
    if ((lFlags & PartInstanceInfoStatusFlag.PI_Displayable) !== 0)
    {
        console.log('the last child of the part instance is displayable')
    }
}

// trigger the retrieval
lChildrenIdCardGetterInterface.retrieveChildrenIdCard(lPartInstanceId, lVisibilityContext);

/** 
 * Sample to illustrate the asynchronous use of an ChildrenIdCardGetterInterface with the parsing of
 * PartInstanceInfoInterface to display some information about a part instance.
 */
import {
    VisibilityContextInterface, ChildrenIdCardGetterInterface, AsyncChildrenPartInstanceInfoResult,
    ChildrenPartInstanceInfoInterface, PartInstanceInfoStatusFlag, AsyncResultReason, DataSessionInterface
} from 'generated/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// created previously
let lVisibilityContext : VisibilityContextInterface;
// the `part instance id` to get
let lPartInstanceId : number;

// create an ChildrenIdCardGetter
const lChildrenIdCardGetterInterface : ChildrenIdCardGetterInterface = lDataSession.createChildrenIdCardGetter();

const retrieveIdCard = async () : Promise<any> =>
{
    // trigger the retrieval
    const lResult : AsyncChildrenPartInstanceInfoResult = await lChildrenIdCardGetterInterface.asyncRetrieveChildrenIdCard(lPartInstanceId, lVisibilityContext);

    if (lResult.reason !== AsyncResultReason.ARR_Success || lResult.value === undefined)
    {
        // do nothing in case of error
        // perhaps some GUI code ?
        return;
    }
    const lPartInstanceInfos : Array<ChildrenPartInstanceInfoInterface> = lResult.value;
    // we required only one `part instance`, as such, only one result should be retrieved
    // iterate over the instantiation chain, but take the first chain since one `part instance` retrieved
    const lCurrentChildren : ChildrenPartInstanceInfoInterface = lPartInstanceInfos[0];

    // number of items 
    const lNbChildren : number = lCurrentChildren.getChildren().length;
    if (lNbChildren <= 0)
    {
        console.log('this part instance is a leaf');
        return;
    }
    // take the last child
    const lChildInstanceOffset : number = lNbChildren - 1;
    // we get the `part` metadata of the last child of the `part instance`
    const lPartMetadata : Object = lCurrentChildren.getChildrenIdCard().partmd[lChildInstanceOffset];
    // some fancy output
    console.log(JSON.stringify(lPartMetadata));

    // get the flags in order to get information about the `part instance`
    const lFlags : number = lCurrentChildren.getChildrenStatusFlags()[lChildInstanceOffset];
    if ((lFlags & PartInstanceInfoStatusFlag.PI_Displayable) !== 0)
    {
        console.log('the last child of the part instance is displayable')
    }
}

retrieveIdCard();

See

• ChildrenIdCardGetterInterfaceSignal
• ChildrenPartInstanceInfoInterface
• ObjectMetadataInterface