Display Order

Functions used to iterate through the elements in the order the server application would draw them onto the display or manipulating this drawing order. More...

Functions
GSErrCode	ACAPI_DrawOrder_DrawOrderInit ()
	Initializes a loop on the current database to get the elements in the order specified by the BTF/STB system.
GSErrCode	ACAPI_DrawOrder_DrawOrderGetNext (API_ElemFilterFlags filterBits, API_Elem_Head *elemHead)
	Returns a reference to the next element of the current database in the order specified by the BTF/STB system.
GSErrCode	ACAPI_DrawOrder_DrawOrderTerm ()
	Signals the end of a draw order loop.
GSErrCode	ACAPI_DrawOrder_InitCreationOrderTable (API_ElemFilter *elemFilter)
	Initializes an internal table for fast access to the next element in creation order.
GSErrCode	ACAPI_DrawOrder_CreationOrderGetNext (API_Guid *guid)
	Returns the next element's GUID from the previously initialized creation order table.
GSErrCode	ACAPI_DrawOrder_DisposeCreationOrderTable ()
	Disposes of the previously allocated creation order table.

Detailed Description

Functions used to iterate through the elements in the order the server application would draw them onto the display or manipulating this drawing order.

Function Documentation

ACAPI_DrawOrder_CreationOrderGetNext()

GSErrCode ACAPI_DrawOrder_CreationOrderGetNext

(

API_Guid *

guid

)

Returns the next element's GUID from the previously initialized creation order table.

Parameters

guid	[in/out] On input, this is the GUID of the element for which the next in creation order is sought. On output, this is the GUID of the following element.

Returns

• NoError - The function completed successfully.
• APIERR_BADPARS - The guid parameter is nullptr.
• APIERR_GENERAL - The creation order table was not allocated beforehand.
• APIERR_NOMORE - The guid parameter is not in the table or it was the last element.

Remarks

This function retrieves the next element's GUID in creation order. Input a value of APINULLGuid to get the first element; an output value of APINULLGuid means the last element. The creation order table must be initialized beforehand with ACAPI_DrawOrder_InitCreationOrderTable.

Example

void PrintGuidsInCreationOrder ()
{
    if (ACAPI_DrawOrder_InitCreationOrderTable (nullptr) == NoError) {
        API_Guid guid = APINULLGuid;
        while ((ACAPI_DrawOrder_CreationOrderGetNext (&guid) == NoError) && (guid != GS::NULLGuid))
        {
            ACAPI_WriteReport (APIGuidToString (guid), false);
        }
        ACAPI_DrawOrder_DisposeCreationOrderTable ();
    }
 
    return;
}

ACAPI_DrawOrder_DisposeCreationOrderTable()

GSErrCode ACAPI_DrawOrder_DisposeCreationOrderTable

(

)

Disposes of the previously allocated creation order table.

Returns

• NoError - The function completed successfully.
• APIERR_GENERAL - The creation order table was not allocated beforehand.

Remarks

This function disposes of the creation order table allocated by ACAPI_DrawOrder_InitCreationOrderTable.

Example

void PrintGuidsInCreationOrder ()
{
    if (ACAPI_DrawOrder_InitCreationOrderTable (nullptr) == NoError) {
        API_Guid guid = APINULLGuid;
        while ((ACAPI_DrawOrder_CreationOrderGetNext (&guid) == NoError) && (guid != GS::NULLGuid))
        {
            ACAPI_WriteReport (APIGuidToString (guid), false);
        }
        ACAPI_DrawOrder_DisposeCreationOrderTable ();
    }
 
    return;
}

ACAPI_DrawOrder_DrawOrderGetNext()

GSErrCode ACAPI_DrawOrder_DrawOrderGetNext	(	API_ElemFilterFlags	filterBits,
		API_Elem_Head *	elemHead )

Returns a reference to the next element of the current database in the order specified by the BTF/STB system.

Parameters

filterBits	[in] Element filter attributes (pass as VALUE).
elemHead	[out] Element reference.

Returns

• NoError - The function completed successfully.
• APIERR_BADPARS - elemHead is nullptr.
• APIERR_NOMORE - No more elements in the list.

Remarks

This function retrieves the database elements in the order the server application would draw them onto the display. The loop should be initialized by the ACAPI_DrawOrder_DrawOrderInit function. Pass filter bits (AS A VALUE) to skip elements with specific properties, as shown in the example. See more details on this topic at ACAPI_Element_Filter.

Example

        API_Elem_Head   elem_head;
        GSErrCode       err;
        
        err = ACAPI_DrawOrder_DrawOrderInit ();
        while (err == NoError) {
            err = ACAPI_DrawOrder_DrawOrderGetNext (APIFilt_OnActFloor, &elem_head);
            if (err == NoError) {
                /* ... */
            }
        }
        if (err == APIERR_NOMORE)
            err = NoError;
 
err = ACAPI_DrawOrder_DrawOrderInit ();
while (err == NoError) {
    err = ACAPI_DrawOrder_DrawOrderGetNext (APIFilt_OnActFloor, &elem_head);
    if (err == NoError) {
        /* ... */
    }
}
if (err == APIERR_NOMORE)
    err = NoError;

ACAPI_DrawOrder_DrawOrderInit()

GSErrCode ACAPI_DrawOrder_DrawOrderInit

(

)

Initializes a loop on the current database to get the elements in the order specified by the BTF/STB system.

Returns

• NoError - The function completed successfully.

Remarks

This function sets up a loop to retrieve elements in the order the server application would draw them onto the display. Once the loop is initialized, the ACAPI_DrawOrder_DrawOrderGetNext function can be called repeatedly to get the element references in order. The function can be called at any time to reset the loop; it is not necessary to scan all the elements to restart the loop. The order of elements depends on the BTF/STB commands invoked by the user. The default ordering can also be imported when opening an external file, if the format provides information on this. Don't forget to call ACAPI_DrawOrder_DrawOrderTerm to allow the server application to free its cached data.

Example

    API_Elem_Head   elem_head;
    GSErrCode       err;
    
    err = ACAPI_DrawOrder_DrawOrderInit ();
    while (err == NoError) {
        err = ACAPI_DrawOrder_DrawOrderGetNext (APIFilt_OnActFloor, &elem_head);
        if (err == NoError) {
            /* ... */
        }
    }
    if (err == APIERR_NOMORE)
        err = NoError;

ACAPI_DrawOrder_DrawOrderTerm()

GSErrCode ACAPI_DrawOrder_DrawOrderTerm

(

)

Signals the end of a draw order loop.

Returns

• NoError - The function completed successfully.

Remarks

This function terminates a loop that retrieves elements in the order the server application would draw them onto the display. Once the loop is initialized with ACAPI_DrawOrder_DrawOrderInit, the ACAPI_DrawOrder_DrawOrderGetNext function can be called repeatedly to get the element references in order. You must call this function at the end of each loop so that the server application can free its cached data.

ACAPI_DrawOrder_InitCreationOrderTable()

GSErrCode ACAPI_DrawOrder_InitCreationOrderTable

(

API_ElemFilter *

elemFilter

)

Initializes an internal table for fast access to the next element in creation order.

Parameters

elemFilter

[in] Optional parameter; can be nullptr. Use this filter to exclude element types from the access table.

Returns

• NoError - The function completed successfully.
• APIERR_MEMFULL - The internal creation order table cannot be allocated.
• APIERR_NESTING - Internal access table initializations cannot be nested; you should dispose of the previously allocated table before initializing a new one.

Remarks

This function sets up an internal table that allows fast access to the next element in creation order (an ordering more or less equal to the unique ID ordering in previous versions).

Example

void PrintGuidsInCreationOrder ()
{
    if (ACAPI_DrawOrder_InitCreationOrderTable (nullptr) == NoError) {
        API_Guid guid = APINULLGuid;
        while ((ACAPI_DrawOrder_CreationOrderGetNext (&guid) == NoError) && (guid != GS::NULLGuid))
        {
            ACAPI_WriteReport (APIGuidToString (guid), false);
        }
        ACAPI_DrawOrder_DisposeCreationOrderTable ();
    }
 
    return;
}