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 __ACENV_CALL	ACAPI_DrawOrder_DrawOrderInit ()
	Initializes a loop on the current database to get the elements in the order specified by the BTF/STB system.
GSErrCode __ACENV_CALL	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 __ACENV_CALL	ACAPI_DrawOrder_DrawOrderTerm ()
	Signals the end of a draw order loop.
GSErrCode __ACENV_CALL	ACAPI_DrawOrder_InitCreationOrderTable (API_ElemFilter *elemFilter)
	Initializes an internal table for fast access of the next element in creation order.
GSErrCode __ACENV_CALL	ACAPI_DrawOrder_CreationOrderGetNext (API_Guid *guid)
	Returns the next element's guid from the previously initialized creation order table.
GSErrCode __ACENV_CALL	ACAPI_DrawOrder_DisposeCreationOrderTable ()
	Disposes 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 __ACENV_CALL 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 following in creation order is sought. On output this is the guid of the following element.

Returns

• NoError - The function has completed with success.
• 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 elem.

Remarks

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

Example

See the example at APIDb_InitCreationOrderTableID
.

ACAPI_DrawOrder_DisposeCreationOrderTable()

GSErrCode __ACENV_CALL ACAPI_DrawOrder_DisposeCreationOrderTable

(

)

Disposes the previously allocated creation order table.

Returns

• NoError - The function has completed with success.
• APIERR_GENERAL - The creation order table was not allocated beforehand.

Remarks

This function is used to dispose the creation order table allocated by ACAPI_DrawOrder_InitCreationOrderTable.

Example

See the example at APIDb_InitCreationOrderTableID
.

ACAPI_DrawOrder_DrawOrderGetNext()

GSErrCode __ACENV_CALL 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 has completed with success.
• APIERR_BADPARS - elemHead is nullptr
• APIERR_NOMORE - no more element in the list

Remarks

This function is used to get 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_Database (APIDb_DrawOrderInitID, nullptr, nullptr);
while (err == NoError) {
    err = ACAPI_Database (APIDb_DrawOrderGetNextID, (void *) (Int32) APIFilt_OnActFloor, &elem_head);
    if (err == NoError) {
        /* ... */
    }
}
if (err == APIERR_NOMORE)
    err = NoError;

ACAPI_DrawOrder_DrawOrderInit()

GSErrCode __ACENV_CALL 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 has completed with success.

Remarks

This function is used to set up a loop to get element 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 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. Also the default ordering can be imported while opening an external file, which format give information on this issue. 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_Database (APIDb_DrawOrderInitID, nullptr, nullptr);
while (err == NoError) {
    err = ACAPI_Database (APIDb_DrawOrderGetNextID, (void *) (Int32) APIFilt_OnActFloor, &elem_head);
    if (err == NoError) {
        /* ... */
    }
}
if (err == APIERR_NOMORE)
    err = NoError;

ACAPI_DrawOrder_DrawOrderTerm()

GSErrCode __ACENV_CALL ACAPI_DrawOrder_DrawOrderTerm

(

)

Signals the end of a draw order loop.

Returns

• NoError - The function has completed with success.

Remarks

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

ACAPI_DrawOrder_InitCreationOrderTable()

GSErrCode __ACENV_CALL ACAPI_DrawOrder_InitCreationOrderTable

(

API_ElemFilter *

elemFilter

)

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

Parameters

elemFilter

[in] Optional parameter, can be nullptr. Use this filter to leave out element types from the access table.

Returns

• NoError - The function has completed with success.
• APIERR_MEMFULL - The internal creation order table cannot be allocated.
• APIERR_NESTING - Internal access table initializations cannot be nested, i.e. you should dispose the previously allocated table before initializing a new one.

Remarks

This function is used to set up an internal table which 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

static void  PrintGuidsInCreationOrder (void)
{
    if (ACAPI_Database (APIDb_InitCreationOrderTableID, nullptr, nullptr) == NoError) {
        API_Guid guid = APINULLGuid;
        while ((ACAPI_Database (APIDb_CreationOrderGetNextID, &guid, nullptr) == NoError) &&
               (guid != GS::NULLGuid))
        {
            ACAPI_WriteReport (APIGuid2GSGuid (guid).ToUniString ().ToCStr (), false);
        }
        ACAPI_Database (APIDb_DisposeCreationOrderTableID, nullptr, nullptr);
    }
 
    return;
}