Chapter 26:
Miscellaneous Functions
 

AllocDetListHandle(); Allocate a Detection List Handle

 

Categorize3DObject(); Is an object part of a graph cube, riser, or neither?

 

ChangeXanTextboxID(); Change Text Box ID

 

CheckDetList(); Check detection list in a draw environment

 

CreateMBCFontHandle(); Creates a font handle based on a existing logical font in the draw environment

 

EncompassLineThickness(); Expands the bounding rectangle of an item to include the thickness of its border or line

 

FindBoxForText(); Find a box for title, subtitle, or footnote text

 

FixupAxisTitleLocation(); Fix the axis title location

 

FreeDetListHandle(); Free Detection Node List Handle

 

GetAdvFormat(); Get an Advanced Format structure

 

GetDLLVersion(); Get DLL Version String

 

GetGroupHeaderPos(); Get Group Header Position

 

GetRiserBounds(); Get Riser Bounds

 

GetRiserSurface(); Get Riser Surface

 

GetScaleBoundaries(); Get Scale Boundaries

 

GetSeriesHeaderPos(); Get Series Header Position

 

GetTableChartCellDimensions(); Get Table Chart Cell Dimensions

 

InitAdvFormat(); Initialize AdvFormat data structure

 

IsObjectATextBox(); Is the object a text box?

 

MBCExists(); Multi-Byte Characters Exist?

 

PackDate(); Pack date in the AdvFormat structure

 

SetErrorCallBack(); Set Error Callback function

 

SetLineItemPoints(); Set Line Item Points

 

SetTableChartCellDimensions(); Set Table Chart Cell Dimensions

 

SetVisibilityMode(); Set Visibility Mode

 

StdFormat(); Format numerical values into a presentable string

 

SwapDetListHandle(); Swap Detection List Handle

 

UnPackDateTime(); Unpack Pack Date and Time in the AdvFormat structure

 

Update_ClearList(); Update Clear List

 

Update_GetFirstItem(); Update Get First Item

 

Update_GetInvalRect(); Update Get Invalid Rectangle

 

Update_GetNextItem(); Update Get Next Item

AllocDetListHandle()

 

This function allocates a detection list handle.

Syntax:

DetListHdl PUBLIC
AllocDetListHandle (
     void
);

Input:

None

Return:

DetListHdl: Detection list handle

Example:

// Create a new DetListHdl
// if one doesn't exist
phDetList = pDE->pDetListHead;
if (!*phDetList)
{
     *phDetList = AllocDetListHandle();
     if (! *phDetList)
          return E00_MEM_ERROR;
}

Also See:

FreeDetListHandle(), SwapDetListHandle(),

   

Categorize3DObject()

 

This function categorizes the object (nObjID) as part of the graph cube or a riser object.

Syntax:

INT16 PUBLIC
Categorize3DObject(
     INT16 nObjID
);

Input:

nObjID; An Object ID.

Return:

INT16;

 

NOT_AUTOSHADED (0) =

nObjID is not part of the graph cube or a riser object

 

CUBE_FACE (1) =

if nObjID is part of the graph cube (i.e., O3D_FLOOR1, O3D_FLOOR2, O3D_FLOOR3, O3D_LEFTWALL1, O3D_LEFTWALL2, etc.)

 

RISER_FACE (2) =

if nObjID is part of a riser object (i.e., O3D_RISERFACE1...9)

     

ChangeXanTextboxID()

 

This function finds the textbox with the given ID (oldID) and substitutes a new ID number (newID).

Syntax:

INT16 PUBLIC
ChangeXanTextboxID (
     GraphPtr pGraph,
     INT16 oldID,
     INT16 newID
);

Input:

pGraph: Pointer to a graph object created by AllocGraphPtr()

 

oldID: Existing text box ID

 

newID: the new ID to assign

Return:

INT16: TRUE/FALSE

 

TRUE

textbox ID was found and changed

 

FALSE

Unsuccessful

Example:

for (i = nBox; i < LOOK.nTCBoxes; i++)
{
     TCBOX[i] = TCBOX[i+1];
     if (IsAnnotBox (&TCBOX[i]))
#if WANT_ANNOTATION
     ChangeXanTextboxID (pGraph, i + 1, i);
#endif
     TCBOX[i].nBox = i;
}

Also See:

GetAnodeFromTextboxID(), IsObjectATextbox()

CheckDetList()

 

This function returns TRUE/FALSE identifying whether or not the detection list associated with the given draw environment (pDE) is valid.

Syntax:

BOOL PUBLIC
CheckDetList(
     DrawEnvPtr pDE
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

Return:

BOOL; TRUE/FALSE

 

TRUE

Detection list in pDE is valid

 

FALSE

Detection list in pDE is not valid

   

CreateMBCFontHandle()

 

This function creates a font handle based on an existing logical font in the draw environment. It only replaces the fontname, pitchandFamily, and charSet of the last logical font with those from the multi-byte character font.

Syntax:

HFONT
CreateMBCFontHandle(
     DrawEnvPtr pDE,
     FontInstPtr pFont

);

Input:

pDE; Pointer to a draw environment created by AllocDrawEnvPtr().

 

pFont; Pointer to a FontInstRec.

Return:

HFONT; Created font handle

Note:

This function allocates resources. Be sure to delete the Font when done.

Also See:

A_FONTNAME_MBC in the PGSDK Attributes Guide, MBCExists()

   

EncompassLineThickness()

 

This function expands the bounding rectangle (bounds) of an item to include the thickness of its border or line.

Syntax:

INT16 PUBLIC
EncompassLineThickness (
     SelItemPtr pItem,
     Rect *bounds
);

Input:

pItem: Pointer to an item in the selection list. See the SelItemRec in Appendix A.

 

bounds: Pointer to a rectangle structure where the new bounding rectangle of the object can be stored. See the Rect data structure in Appendix A.

Return:

INT16: TRUE/FALSE

 

TRUE=

Successful

 

FALSE=

pItem Invalid

Example:

/*
** get the new position and invalidate it
*/
EncompassLineThickness(pSelItem, &rcVirt);
rcDest = rcVirt;
vdRect(pDE, &rcDest);

   

FindBoxForText()

 

This function calculates a box that will fit around the chart Title, Subtitle or Footnote.

Syntax:

BOOLEAN16 PUBLIC FindBoxForText(
     DrawEnvPtr pDE,
     GraphPtr pGraph,
     INT16 nObjectID,
     LPSTR pText,
     BoxInstPtr pBounds
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pGraph; Pointer to a graph created by AllocGraphPtr().

 

nObjectID; The object ID of the chart footnote (O5D_LBLFOOTNOTE), title (O5D_LBLTITLE), or subtitle (O5D_LBLSUBTITLE).

 

pText; Pointer to the text string that defines the chart footnote, title, or subtitle.

 

pBounds; Pointer to a BoxInstRec where the calculated box can be stored.

Return:

BOOLEAN16; TRUE/FALSE

 

TRUE=

Success, pBounds contains the calculated BoxInstRec

 

FALSE=

Failed

   

FixupAxisTitleLocation()

 

This function adjusts the location of rotated axis titles so that any change to their string keeps them in the same position.

 

INT16 PUBLIC FixupAxisTitleLocation(
     DrawEnvPtr pDE,
     GraphPtr pGraph,
     INT16 nObjectID,
     char FAR *lpValue
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pGraph: A graph pointer allocated by AllocGraphPtr()

 

nObjectID; Object ID

 

lpValue; String Pointer

Return:

INT16; E00_OK

   

FreeDetListHandle

 

This function de-allocates storage for a chain of detection nodes identified by phDetList.

Syntax:

void PUBLIC
FreeDetListHandle (
     DetListHdl FAR * phDetList
);

Input:

phDetList: Pointer to a detection list handle

Return:

None

Example:

/* free any associated DetLists*/
FreeDetListHandle(
     &pGraph->Layer[BACKGROUND_LAYER].hDetList);
FreeDetListHandle(
     &pGraph->Layer[GRAPH_LAYER].hDetList);
FreeDetListHandle(
     &pGraph->Layer[ANNOTATION_LAYER].hDetList);

Also See:

FreeDetNode(), FreeAllDetNodes()

   

GetAdvFormat()

 

This function gets a pointer to an advanced format structure. It maps the format index (nFormat) to format parameters. This function is primarily used to map a standard numeric formatting code (e.g., set by A2D_FORMAT_Y1) to an Advanced Format Structure (e.g., set by A2D_FORMAT_Y1_ADV). For example, if nFormat is set to "14", the following entries will be initialized in the resulting AdvFormatStruct:

 

pAdvFormat->formatType = PercentFormat;

 

pAdvFormat->iDigits = 1;

Syntax:

void PUBLIC
GetAdvFormat(
     short nFormat,
     AdvFormatPtr pAdvFormat
);

Input:

nFormat; A standard numeric formatting code (0...54).

 

pAdvFormat; Pointer to the specified AdvFormatStruct.

Return:

void

   

GetDLLVersion()

 

This function gets the PGSDK DLL version string.:

Syntax:

BOOL PUBLIC
GetDLLVersion(
     TCHAR * szVersion
);

Input:

szVersion; Pointer to a character string where version string can be stored.

Return:

BOOL; TRUE/FALSE

 

True=

Version is valid

 

False=

Version is not valid

   

GetGroupHeaderPos()

 

This function sets pnRow and pnCol to the location of the group header at nGroupsAddress in the graph (G).

Syntax:

INT16 PUBLIC
GetGroupHeaderPos (
     GraphPtr G,
     INT16 nGroupsAddress,
     PINT16 pnRow,
     PINT16 pnCol
);

Input:

G: Graph Pointer

 

nGroupsAddress: Group address

 

pnRow: Set to SSI row address

 

pnCol: Set to SSI column address

Return:

INT16:

 

Value

Description

 

E00_OK =

Successful

 

EAC_EMPTYDATAFORMAT=

Failure

Also See:

GetGroupHeaderString()

   

GetRiserBounds()

 

This function sets pRect to the bounds of the nIndex riser in the draw environment (pDE). If the riser's visibility status is not visible, pRect is set to zero.:

Syntax:

INT16 PUBLIC
GetRiserBounds (
     DrawEnvPtr pDE,
     INT16 nIndex,
     RECT *pRect
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

nIndex: Index of riser

 

pRect: Pointer to a rectangle data structure where the bounds of the riser can be stored. See the Rect structure in Appendix A.

Return:

INT16: Zero

Also See:

CreateRisers(), GetRiserDetNodeLimit(), GetRiserSurface()

GetRiserSurface()

 

This function sets pnSuriface to the nRiserSurface entry in the visibility table for the nIndex riser in the drawn environment (pDE). pnSurface is set to zero if the riser is not visible in the draw environment.:

Syntax:

INT16 PUBLIC
GetRiserSurface (
     DrawEnvPtr pDE,
     INT16 nIndex,
     INT16 *pnSurface
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

nIndex: Index of riser

 

pnSurface: Pointer to an INT16 where the riser surface value will be stored on return.

Return:

INT16: Zero

Also See:

GetRiserBounds(), GetRiserDetNodeLimit()

   

GetScaleBoundaries()

 

This function gets the maximum and minimum scale values for each axis in a graph.:

Syntax:

void PUBLIC
GetScaleBoundaries(
     GraphPtr pGraph,
     REAL *pfXMin,
     REAL *pfXMax,
     REAL *pfYMin,
     REAL *pfYMax,
     REAL *pfZMin,
     REAL *pfZMax
);

Input:

pGraph: Graph Pointer

 

pfXMin; Pointer to place to store X-axis minimum value.

 

pfXMax; Pointer to place to store X-axis maximum value.

 

pfYMin; Pointer to place to store Y-axis minimum value.

 

pfYMax; Pointer to place to store Y-axis maximum value.

 

pfZMin; Pointer to place to store Z-axis minimum value.

 

pfZMax; Pointer to place to store Z-axis maximum value.

Return:

Void

   

GetSeriesHeaderPos()

 

This function sets pnRow and pnCol to the location of the series header (nSeriesAddress).

Syntax:

INT16 PUBLIC
GetSeriesHeaderPos (
     GraphPtr G,
     INT16 nSeriesAddress,
     PINT16 pnRow,
     PINT16 pnCol
);

Input:

G: Graph Pointer

 

nSeriesAddress: Series address

 

pnRow: Set to SSI row address

 

pnCol: Set to SSI column address

Return:

INT16: EAC_EMPTYDATAFORMAT or E00_OK

Also See:

GetSeriesHeaderString()

   

GetTableChartCellDimensions()

 

This function sets pnValue to the size of text at nRow/nCol in a table chart.:

Syntax:

INT16 PUBLIC
GetTableChartCellDimensions (
     GraphPtr pGraph,
     INT16 nRow,
     INT16 nCol,
     PINT16 pnValue
);

Input:

pGraph: A graph pointer allocated by AllocGraphPtr()

 

nRow: Row number

 

nCol: Column number

 

pnValue: Place to store cell dimensions

Return:

INT16: Zero

Also See:

SetTableChartCellDimensions()

   

InitAdvFormat

 

This API initializes the AdvFormatStruct structure to the user's current Locale settings. This data structure is used by the A2D_FORMAT_SDLINE_ADV, A2D_FORMAT_X_ADV, A2D_FORMAT_Y1_ADV, A2D_FORMAT_Y2_ADV, A2D_FORMATDTXT_X_ADV, A2D_FORMATDTXT_Y1_ADV, A2D_FORMATDTXT_Y2_ADV, API_FORMAT_DATATEXT_ADV, and API_FORMAT_RINGTEXT_ADV attributes to apply a custom format string to numbers in the chart. We recommend that this API be called before you apply your own settings.

Syntax:

void PUBLIC InitAdvFormat( AdvFormatPtr pAdvFormat );

Input:

pAdvFormat: Pointer to an advanced format structure. See the AdvFormatStruct in Appendix A.

Return:

None

Example:

AdvFormatStruct fmt;
// initialize the struct to current Locale
InitAdvFormat( &fmt );
// override Locale settings
fmt.iLZero = 0;
fmt.iDigits = 2;
fmt.iGrouping = 3;
fmt.iCurrDigits = 2;
fmt.iMonGrouping = 3;
fmt.formatType = CurrencyFormat;
SetGraphAttrSI (gpGraph,NULL, A2D_FORMAT_Y1_ADV, &fmt);

Also See:

A2D_FORMAT_SDLINE_ADV, A2D_FORMAT_X_ADV, A2D_FORMAT_Y1_ADV, A2D_FORMAT_Y2_ADV, A2D_FORMATDTXT_X_ADV, A2D_FORMATDTXT_Y1_ADV, A2D_FORMATDTXT_Y2_ADV, API_FORMAT_DATATEXT_ADV, API_FORMAT_RINGTEXT_ADV in the PGSDK Attributes Guide

IsObjectATextBox()

 

This function determines whether or not nObjID is a text box object (i.e., one of OTX_BOX_..., O5D_LBLTITLE, O5D_LBLSUBTITLE, O5D_LBLFOOTNOTE).

Syntax:

BOOLEAN16 PUBLIC
IsObjectATextBox (
     INT16 nObjID
);

Input:

nObjID: Object ID

Return:

BOOLEAN16: TRUE/FLASE

 

TRUE=

nObjID is a text box object

 

FALSE=

nObjID is not a text box object

Example:

nSelGeodes++;
nSelMovable++;
if(IsObjectATextBox(
     pCurr->nObjectID)) nSelTextBox++;
break;

Also See:

ChangeXanTextboxID(), GetAnodeFromTextboxID()

   

MBCExists()

 

This function checks if the input string (lpszText) contains multi-byte characters.

Syntax:

BOOLEAN16 PUBLIC
MBCExists(
     LPCSTR lpszText,
     int nLength
);

Input:

lpszText; Character String to check for multi-byte characters

 

nLength; Length of character string

Return:

BOOLEAN16; TRUE/FALSE

 

True =

String contains multi-byte characters

 

False=

String does not contain multi-byte characters

Also See:

A_FONTNAME_MBC in the PGSDK Attributes Guide, CreateMBCFontHandle()

   

PackDate()

 

This function packs respective date components into a single value.

Syntax:

double PUBLIC
PackDate(
     short nDay,
     short nMonth,
     short nYear,
     short nHour,
     short nMin,
     short nSec
);

Input:

nDay; Day value 1...31

 

nMonth; Month value 1...12

 

nYear; Year value 1...9999

 

nHour; Hours value 1...24

 

nMin; Minutes value 1...60

 

nSec; Seconds value 1...60

Return:

double; Packed date value ( nYear*10000000000.0 + nMonth*100000000.0 + nDay*1000000.0 + nHour*10000.0 + nMinute*100.0 + nSec )

Also See:

UnPackDateTime()

   

SetErrorCallBack()

 

This function registers an error-handling call-back routine within the application that will be called when an engine error occurs.

Syntax:

INT16 PUBLIC
SetErrorCallBack (
     LPFNErrorCallBack lpfnErrorCB
);

Input:

lpfnErrorCB: Identifies a user-defined function that the engine can call when an error occurs. This callback function has the following form:

 

typedef INT16 (*LPFNErrorCallBack) (
     void FAR *pContext,
     INT16 nErrorID,
     INT16 nErrorClass,
     INT32 lData,
     char FAR * pFile,
     INT16 nLine
);

 

pContext; Error context information (pGraph, pDE, etc.)

 

nErrorID; Error code (Exx_yyy)

 

nErrorClass; Error Class

 

lData; Additional information such as file name, etc.

 

pFile; Offending file name

 

nLine; Offending line number

Return:

INT16: E00_OK

SetLineItemPoints()

 

This function sets the virtual coordinates start (p0) and end (p1) points of a line or arrow annotation object (OAN_LINE or OAN_ARROW).

Syntax:

INT16 PUBLIC
SetLineItemPoints (
     SelItemPtr pItem,
     Point p0,
     Point p1,
     Rect *bounds
);

Input:

pItem; Pointer to a selection item record. See the SelItemRec in Appendix A.

 

p0; Start point

 

p1; End point

 

bounds; Place to store new bounding rectangle of object

Return:

INT16; 1/0

 

1=

Successful

 

0=

Unsuccessful

   

SetTableChartCellDimensions()

 

This function sets the cell dimension for nRow/nCol in a table chart to the cell dimensions specified in pnValue.

Syntax:

INT16 PUBLIC
SetTableChartCellDimensions (
     GraphPtr pGraph,
     INT16 nRow,
     INT16 nCol,
     PINT16 pnValue
);

Input:

pGraph: A graph pointer allocated by AllocGraphPtr()

 

nRow: Row number

 

nCol: Column number

 

pnValue: Cell dimensions

Return:

INT16: Zero

Also See:

GetTableChartCellDimensions()

   

SetVisibilityMode()

 

This function sets the visibility mode of a number of series and groups in the chart.

Syntax:

void PUBLIC
SetVisibilityMode (
     DrawEnvPtr pDE,
     INT16 nSeries,
     INT16 nGroups,
     BOOLEAN16 bVisibilityMode
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

nSeries: Number of visible series

 

nGroups: Number of visible groups

 

bVisilbilityMode: TRUE/FALSE

 

TRUE=

Make nSeries and nGroups visible

 

FALSE=

Make nSeries and nGroups not visible

Return:

None

Example:

short nSeries, nGroups;
graph.GetSGCount(TRUE, &nSeries, &nGroups );
CRect rcLocal(0,0,rcOffScreen.Width(),
     rcOffScreen.Height());
de.SetDestRect( rcLocal );
de.SetVisibilityMode( nSeries, nGroups, TRUE );

Also See:

GetSGCount(), SetDataRange()

   

StdFormat()

 

This function formats numeric values into a presentable string.

Syntax:

short PUBLIC
StdFormat(
     REAL value,
     AdvFormatPtr pFormat,
     short nFormat,
     _TCHAR *szFormattedString
);

Input:

value; Real number to be formatted

 

pFormat; Pointer to advanced formatting structure (if NoFormat, nFormat is used). See the AdvFormatStruct in Appendix A.

 

nFormat; Format index

 

szFormattedString; Pointer to a character string where the formatted number string (may be multi-byte) can be stored.

Return:

short; 0 if unsuccessful. Otherwise contains the length (bytes) of the formatted string in szFormattedString.

   

SwapDetListHandle()

 

This function is used to save a detection node list so that it can be restored later.

Syntax:

DetListHdl PUBLIC
SwapDetListHandle (
     GraphPtr pGraph,
     INT16 LayerID,
     DetListHdl hDetList
);

Input:

pGraph: Pointer to the graph object created by AllocGraphPtr()

 

LayerID: Graph layer.

 

Possible Values

Description

 

ANNOTATION_LAYER

Annotation Layer

 

GRAPH_LAYER

Graph Layer

 

BACKGROUND_LAYER

Background Layer

 

hDetList: Detection node list handle to be saved.

Return:

DetListHdl: Returned detection node list handle

UnPackDateTime()

 

This function unpacks a date value (dDate) into its respective components; nDay, nMonth, nYear, nHour, nMin, nSec. This function assumes the date value was previously packed by PackDate().

Syntax:

void PUBLIC
UnPackDateTime(
     short nDay,
     short nMonth,
     short nYear,
     short nHour,
     short nMin,
     short nSec,
     double dDate
);

Input:

nDay; Day value 1...31

 

nMonth; Month value 1...12

 

nYear; Year value 1...9999

 

nHour; Hours value 1...24

 

nMin; Minutes value 1...60

 

nSec; Seconds value 1...60

 

dDate; Date value that was previously packed by PackDate()

Also See:

PackDate()

   

Update_ClearList()

 

This function removes all update items from an update list. It is used for maintaining lists of invalidation regions.

Syntax:

INT16 PUBLIC
Update_ClearList (
     GraphPtr pGraph
);

Input:

pGraph: Pointer to the graph object created by AllocGraphPtr()

Return:

INT16

 

Possible Values

Description

 

E00_INVALID_NULL_ARG =

pGraph is invalid

 

E00_OK

No errors

Also See:

Update_GetFirstItem(), Update_GetNextItem(), Update_GetInvalRect()

Update_GetFirstItem()

 

This function returns a pointer to the first item in the update list. It is used for maintaining lists of invalidation regions.

Syntax:

UpdateItemPtr PUBLIC
Update_GetFirstItem (
     GraphPtr pGraph
);

Input:

pGraph: Pointer to the graph object created by AllocGraphPtr()

Return:

UpdateItemPtr:

 

Possible Values

Description

 

NULL =

No items in list

 

Non-Zero =

Pointer to Update Item

Example:

if (!pGraph)return E00_INVALID_NULL_ARG;
/* free each of the objects in the list */
for (pCurr=Update_GetFirstItem(pGraph);
     pCurr; pCurr=pNext)
{
     pNext = Update_GetNextItem(pCurr);
     FreePtr(pCurr);
}

Also See:

Update_ClearList(), Update_GetInvalRect(), Update_GetNextItem()

   

Update_GetInvalRect()

 

This function sets the rectangle at invalRect to the virtual coordinates of the item identified by pItem.

Syntax:

void PUBLIC
Update_GetInvalRect (
     UpdateItemPtr pItem,
     Rect *invalRect
);

Input:

pItem: Pointer to an item in an update list See the UpdateItemRec in Appendix A.

 

invalRect: Pointer to a rectangle data structure

Return:

None

Also See:

Update_ClearList(), Update_GetFirstItem(), Update_GetNextItem()

   

Update_GetNextItem()

 

This function returns a pointer to an update item that is the next item in the update list after pItem.

Syntax:

UpdateItemPtr PUBLIC
Update_GetNextItem (
     UpdateItemPtr pItem
);

Input:

pItem: Pointer to an item in an update list. See the UpdateItemRec in Appendix A.

Return:

UpdateItemPtr:

 

Possible Values

Description

 

NULL =

No items in list

 

Non-Zero =

Pointer to Update Item

Example:

if (!pGraph) return E00_INVALID_NULL_ARG;
/* free each of the objects in the list */
for (pCurr=Update_GetFirstItem(pGraph);
     pCurr; pCurr=pNext)
{
     pNext = Update_GetNextItem(pCurr);
     FreePtr(pCurr);
}

Also See:

Update_GetFirstItem()