Chapter 8:
Special Features


 

This chapter describes special charting features in the PGSDK:

 

ADVANCED 3D RENDERING

 

 

Initializing Advanced 3D

 

 

Registering a Window for Drawing

 

 

Registering an Off-Screen Bitmap for Drawing

 

 

Advanced 3D Drawing

 

 

Blitting Off-Screen Bitmaps

 

 

Advanced 3D Attributes

 

VISUALIZE FEATURES

 

USER-INTERFACE DIALOGS

 

 

3D Viewing Angles Dialog

 

 

Chart Options Dialog

 

 

Choose a Chart Type Dialog

 

 

Data Analyzer Dialog

 

 

Drop Shadow Dialog

 

 

Fill Gradients Dialog

 

 

Fill Pattern Dialog

 

 

Fill Pictures Dialog

 

 

Fill Textures Dialog

 

 

Formatting Dialog

 

 

Grids & Scales Dialog

 

 

Lighting Preset Dialog

 

 

Model Preset Dialog

 

 

Series Options Dialog

 

 

Titles Dialog

 

IMPORT/EXPORT JAVA SCRIPT FILES

 

ANNOTATIONS

 

 

Creating Annotations

 

 

Allocate a PolyHandle

 

 

Add Points to PolyHandle

 

 

Close PolyHandle

 

 

Create and Remove Annotation Items

 

 

Other Useful API Functions for Annotations

 

SPECIAL SUPPORT FOR UNIX/LINUX PLATFORMS

 

IMAGE EXPORT FUNCTIONS

ADVANCED 3D RENDERING

 

Advanced 3D Rendering is an alternate form of drawing that is optionally done when a client calls DrawTheGraph(). Instead of platform-specific API calls (for example to the Windows GDI or Macintosh Toolbox), Advanced 3D uses the OpenGL graphics library to display complex 3D versions of charts with dynamic lighting, z-buffering, 3D text, true texture-mapping and other visual enhancements. In addition, OpenGL takes advantage of any available 3D hardware acceleration if the proper drivers are installed.

 

 

In order to use Advanced 3D Rendering on a given platform, the latest version of Silicon Graphics, Inc's OpenGL drivers (DLLs on Windows) must be installed. Links to versions for all available platforms can be found on the OpenGL web page at http://www.opengl.org.

 

In order to used Advanced 3D Rendering and Advanced 3D attributes, a few minor modifications are required beyond the basic chart-drawing procedure described in Chapter 3. The following paragraphs describe:

 

1.

how to initialize Advanced 3D to draw into your window,

 

2.

how to initialize Advanced 3D to draw into an off-screen bitmap,

 

3.

how to perform Advanced 3D drawing, and

 

4.

how to blit an off-screen bitmap into your window or port.

 

These examples demonstrate the Windows interfaces.

Initializing Advanced 3D

 

Advanced 3D Rendering can be set to render into an existing window or port or to render into an off-screen bitmap for subsequent copying to the screen. The engine must be initialized when the application is launched according to which method you want to use.

 

1.

Registering a Window for Drawing: Your application must register a window that will be used for Advanced 3D drawing.

 

2.

Registering an Off-Screen Bitmap for Drawing: Your application must allocate and register an off-screen bitmap that will be used for Advanced 3D drawing.

Registering a Window for Drawing

 

If you want Advanced 3D drawing to take place directly in an existing window, you must register it at application startup using the OGL_RegisterPort() function. The INT32 value returned is the OpenGL reference and must be stored by the client and passed in the preparations to draw to the window.

 

INT32 lOGLRef;

 

In a "standard" Windows application, this should be done when the WM_CREATE message is sent in the window proc of the window you want to draw into:

 

case WM_CREATE:
     hDC = GetDC(hWnd);
     lOGLRef = OGL_RegisterPort(-1L, hDC);
     break;

 

In an MFC application, it should be done in the OnCreate handler for the view you want to draw into:

 

int CChartView::OnCreate(
LPCREATESTRUCT lpCreateStruct)
{
     if (CView::OnCreate(lpCreateStruct) == -1)
          return -1;
     HDC hDC = ::GetDC(m_hWnd);
     lOGLRef = OGL_RegisterPort(-1L, hDC);
     return 0;
}

 

Each time OGL_RegisterPort() is called, there will be a noticeable delay as the OpenGL context is created and the font objects are tessellated.

Registering an Off-Screen Bitmap for Drawing

 

Smoother updates and more versatile drawing can be achieved by using more memory for an off-screen buffer. If you want Advanced 3D drawing to use an off-screen bitmap, you must initialize it at application startup. Allocate the off-screen buffer using OGL_InitOffscreen() with the width and height of the maximum size you want to render. Register the off-screen buffer using OGL_RegisterOffscreenPort(). The INT32 value returned is the OpenGL reference for the off-screen buffer and must be stored by the client and passed in the preparations to draw to the buffer.

 

INT32 lOGLRef;

 

In a "standard" Windows application, this should be done when the WM_CREATE message is sent in the window proc of the window you would be doing your drawing in, if you weren't drawing off-screen:

 

case WM_CREATE:
hDC = GetDC(hWnd);
OGL_InitOffscreen(TRUE, hDC, 1280, 960);
lOGLRef = OGL_RegisterOffscreenPort();
break;

 

In an MFC application, it should be done in the OnCreate handler for the view you would be doing your drawing in, if you weren't drawing off-screen:

 

int CChartView::OnCreate(LPCREATESTRUCT lpCreateStruct)
{
     if (CView::OnCreate(lpCreateStruct) == -1)
          return -1;
     HDC hDC = ::GetDC(m_hWnd);
     OGL_InitOffscreen(TRUE, hDC, 1280, 960);
     lOGLRef = OGL_RegisterOffscreenPort();
     return 0;
}

 

OGL_InitOffscreen() and OGL_RegisterOffscreenPort() can be called repeatedly, but they will only allocate the first time. On subsequent calls, OGL_RegisterOffscreenPort() will return the reference that was initially created. Because the OpenGL context is only created the first time, the delay incurred by tessellating fonts will only be seen once.

Advanced 3D Drawing

 

Advanced 3D Rendering requires a few lines of code bracketing the usual graph drawing calls. The biggest modification is a loop that allows DrawTheGraph() to be called repeatedly a certain number of times. This allows some complex effects to be drawn, which require multiple passes. The procedure within your paint function should work as follows:

 

1.

Call OGL_BeginFirstPass(). Tell the engine that you are about to begin the first draw pass.

 

2.

Call DESetDrawProcs() as normal. If the chart to be rendered is a 2D3D, you must pass DE_PROCS_ADVANCED_3D as the index.

 

3.

Call DrawBegin() as normal

 

4.

Call OGL_DrawBegin() with the reference obtained when the port was registered, plus the Draw Environment and the Graph. Save the BOOLEAN16 return value.

 

5.

Call DrawTheGraph() as usual.

 

6.

Call OGL_DrawEnd() with the reference obtained when the port was registered, plus the Draw Environment and the Graph.

 

7.

If the saved return value from the last call to OGL_DrawBegin() is TRUE, go back to step 4 and repeat the graph drawing.

 

8.

Call DrawEnd() as normal.

 

9.

Call OGL_BlitOffscreen() to copy the chart to the application's window if the chart was rendered to an off-screen bitmap.

 

Note that if you are rendering to an off-screen bitmap and the chart has been drawn successfully once, you only need to run the engines when some attribute or element of the chart has been changed or when the window is resized. If there have been no changes, your paint code can skip directly to step 9.

 

In a "standard" Windows application, this should be done when the WM_PAINT message is sent in the window proc of the window you want to display a chart in:

 

case WM_PAINT:
//
// assume the local variables here
// are defined at the top
// of the WndProc function
//
hdc = BeginPaint(hWnd, &ps);
OGL_GetChartStatus(pGraph, &bDoAdv3D, NULL,&bIs2D3D);
OGL_BeginFirstPass();
do_pass:
if(bDoAdv3D)
{
     if(bIs2D3D)
     DESetDrawProcs(pDE, DE_PROCS_ADVANCED_3D);
     else DESetDrawProcs(pDE, DE_PROCS_NORMAL);
     DrawBegin(pDE);
     bDoAnotherPass = OGL_DrawBegin(lOGLRef,
          pDE, pGraph);

     }
else
     {
          DESetDrawProcs(pDE, DE_PROCS_NORMAL);
          DrawBegin(m_pDE);
     }
          DrawTheGraph(pDE, pGraph, TRUE, TRUE,FALSE);
if(bDoAdv3D)
{
     OGL_DrawEnd(lOGLRef, pDE, pGraph);
     if(bDoAnotherPass)goto do_pass;
     OGL_BlitOffscreen(hdc NULL);
}
DrawEnd(m_pDE);
EndPaint(hWnd, &ps);
break;

 

In an MFC application, it should be done in the OnDraw handler for the view you would like to draw a chart in:

 

void CChartView::OnDraw(CDC* pDC)
{
     BOOLEAN16 bDoAdv3D;
     BOOLEAN16 bDoAdv3DTitles;
     BOOLEAN16 bIs2D3D;
     INT16 bDoAnotherPass;
     OGL_GetChartStatus(
          pGraph, &bDoAdv3D, NULL, &bIs2D3D);
     OGL_BeginFirstPass();
do_pass:
if(bDoAdv3D)
{
     if(bIs2D3D)
          DESetDrawProcs(m_pDE,DE_PROCS_ADVANCED_3D);
     else
          DESetDrawProcs(m_pDE, DE_PROCS_NORMAL);
     DrawBegin(m_pDE);
     bDoAnotherPass = OGL_DrawBegin(lOGLRef,
          m_pDE, m_pGraph);
}
else
{
     DESetDrawProcs(m_pDE, DE_PROCS_NORMAL);
     DrawBegin(m_pDE);
}

 

DrawTheGraph(m_pDE, m_pGraph,TRUE,TRUE,FALSE);
if(bDoAdv3D)
{
     OGL_DrawEnd(lOGLRef, m_pDE, m_pGraph);
     if(bDoAnotherPass)goto do_pass;
     OGL_BlitOffscreen(pDC->GetSafeHdc(), NULL);
}
DrawEnd(m_pDE);
return;
}

 

Note that in the two examples above it is assumed that an off-screen buffer has been registered for drawing. If that is not the case, the OGL_BlitOffscreen() call should be omitted.

Blitting Off-Screen Bitmaps

 

After you finish drawing the chart into a registered off-screen bitmap, you must call OGL_BlitOffscreen() to make it appear on your destination DC. There are two ways to use OGL_BlitOffscreen().

 

1.

If you have just finished running the graphing engines by calling DrawTheGraph(), the Advanced 3D Rendering code already knows the bounds of the destination rectangle that was set up before calling DrawBegin(). By calling OGL_BlitOffscreen() with NULL as the second parameter, you tell it to use the destination rectangle in the Draw Environment as the destination for the blit.

 

 

OGL_BlitOffscreen(hDC, NULL);

 

2.

If, however, you have not just run the graphing engines, the information in the Draw Environment may be out of date. In this case, you need to pass the pointer to a destination rectangle as the second parameter to OGL_BlitOffscreen(). The rectangle's bounds should be in the device coordinates of the DC that you pass as the first parameter.

 

 

OGL_BlitOffscreen(hDC, &rcDestBlit);

Advanced 3D Attributes

 

Advanced 3D attributes use the OpenGL libraries developed by Sun and currently supported by Microsoft. OpenGL drivers must be present on the target client in order to image graphs using the advanced attributes. The Advanced 3D attributes are:

 

A3D_ADV_2DDEPTH_DATA: Defines the depth of the data layer in Open GL units.

 

A3D_ADV_2DDEPTH_FRAME: Defines the depth of the frame in Open GL units.

 

A3D_ADV_2DDEPTH_LEGEND: Defines the depth of legend markers in Open GL units.

 

A3D_ADV_2DFRAMEFOOT: Frame is given a shelf on which risers rest.

 

A3D_ADV_2DFRAMEMARGIN: Expands frame and legend bounds.

 

A3D_ADV_2DVIEWER_DIST: Defines the distance from the viewer to 2D3D.

 

A3D_ADV_2DVIEWER_X: Defines the X-location of the viewer.

 

A3D_ADV_2DVIEWER_Y: Defines the Y-location of the viewer.

 

A3D_ADV_ANTIALIAS: Enables/Disables anti-alias

 

A3D_ADV_BGRADIOSITY: Defines radiant color from the background.

 

A3D_ADV_CHARTLIGHT_1/2/3: Defines information about the first, second, and third light to illuminate the chart.

 

A3D_ADV_DEFAULT_MATERIAL: Defines default global material for objects.

 

A3D_ADV_DOADV_CHART: Enables/Disables use of advanced rendering for the chart.

 

A3D_ADV_DOADV_TITLES: Enables/Disables use of advanced rendering for titles.

 

A3D_ADV_FOV: Defines the camera's field-of-view in degrees.

 

A3D_ADV_HIFI_OBJECTS: Substitutes OpenGL objects for Three |D| Graphics objects.

 

A3D_ADV_LABEL_MATERIAL: Defines the material used for chart labels.

 

A3D_ADV_LIGHTAMBIENT: Defines ambient light falling on the scene.

 

A3D_ADV_LOFT_SHAPE: Defines a marker shape to loft risers out of.

 

A3D_ADV_LOFT_TWIST: Defines the amount of twist for lofted risers.

 

A3D_ADV_MATAMBIENT: Defines the amount of ambient light reflecting on a chart.

 

A3D_ADV_MATGLOW: Defines the amount of color glow from the default.

 

A3D_ADV_PIE_LABELSFACE: Defines how much pie labels are turned to face the viewer.

 

A3D_ADV_PIE_TINTLABELS: Defines how much labels are tinted with the pie slice color.

 

A3D_ADV_ROUNDING: Defines the amount of rounding to apply.

 

A3D_ADV_TITLELIGHT: Defines information about light that illuminates the titles

VISUALIZE FEATURES

 

Visualize features are used to make 3D graphs more "visible". The visualize features can be used to make any series, group, or individual riser glow, suppressed (with optional rescaling), or transparent. The following attributes support the visualize features:

 

A3D_GLOW_RISER: Applies glow to a series, group, or riser.

 

A3D_RESCALE_ON_SUPPRESS: Rescales the entire graph after suppression.

 

A3D_SUPPRESS_RISER: Suppresses a series of risers.

 

 

 

A3D_SUPPRESS_RISER: Suppresses a group of risers.

 

 

 

A3D_SUPPRESS_RISER: Suppresses an individual riser.

 

 

 

A3D_TRANS_RISER: Makes a series of risers transparent.

 

 

 

A3D_TRANS_RISER: Makes a group of risers transparent.

 

 

 

A3D_TRANS_RISER: Makes an individual riser transparent.

 

 

 

See the PGSDK Attributes Guide for a description of these attributes.

USER-INTERFACE DIALOGS

 

PGSDK API functions can be used to access and display Amigo 2000 user-interface dialogs. These dialogs provide extensive chart editing capabilities to your application's user interface with a single API call. Use the following functions to initialize the use of the Amigo dialogs and to define the path where the help file for these dialogs resides.

 

InitAmigoDialog(); Dialog resource initialization.

 

SetHelpFilePath(); Set the path where the help file for the dialog's Help button can be accessed.

 

These API functions are defined in the AmigoDialogAPI.H header file.

3D Viewing Angles Dialog

 

The Prompt3DViewAnglePresetDialog() function shows the 3D Viewing Angles dialog.

 

Chart Options Dialog

 

The PromptChartOptionsDialog() function shows the Chart Options dialog.

Choose a Chart Type Dialog

 

The PromptChartTypesDialog() function shows the Choose a Chart... dialog and lets the user select a different chart type.

Data Analyzer Dialog

 

The PromptDataAnalyzerDialog() function shows the Data Analyzer dialog. The charting engine will suggest different charts types that are appropriate for the data that defines the chart.

Drop Shadow Dialog

The PromptDropShadowDialog() function shows the drop shadow dialog and allows the user to apply a drop shadow to a text object.

 

Fill Gradients Dialog

 

The PromptFillGradientsDialog() function shows the gradient selection dialog and allows the user to apply a gradient to an area object.

 

Fill Pattern Dialog

 

The PromptFillPatternDialog() function shows the pattern selection dialog and allows the user to apply a gradient to an area object.

 

Fill Pictures Dialog

 

The PromptFillPicturesDialog() function shows the picture selection dialog and allows the user to apply a picture to an area object.

 

Fill Textures Dialog

 

The PromptFillTexturesDialog() function shows the texture selection dialog and allows the user to apply a texture to an area object.

 

Formatting Dialog

 

The PromptFormattingDialog() function shows the formatting dialog and allows the user to format area, line and text objects.

Grids & Scales Dialog

 

The PromptGridScaleDialog() function shows the Grids & Scales dialog and allows the user to format chart axes.

Lighting Preset Dialog

 

When advanced charts are being used, the PromptLightingPresetDialog() function shows the lighting selection dialog and allows the user to apply a special lighting to the chart.

 

Model Preset Dialog

 

The PromptModelPresetDialog() function shows the model selection dialog and allows the user to model to riser objects.

 

Series Options Dialog

 

The PromptSeriesOptionsDialog() function shows the series options dialog and allows the user to format and apply options to a particular series in a chart.

Titles Dialog

 

The PromptTitleDialog() function shows the titles dialog and allows the user to define and show/hide chart titles.

 

IMPORT/EXPORT JAVA SCRIPT FILES

 

Based on special customer orders, PGSDK can support import from and export to Java Script Files that are compatible with Three |D| Graphics Perspective for Java Product. The API functions are:

 

ReadJAVAScriptChartFile(); to read a Java script file created by Perspective for Java into a PGSDK chart.

 

WriteJAVAScriptChartFile(); to write a PGSDK chart to a Java script file that is compatible with Perspective for Java.

 

For a ReadJAVAScriptChartFile() operation, the following JavaScript commands are translated:

 

>

setAutofit

 

>

setAxisAssignment

 

>

setBorderColor

 

>

setColorMode

 

>

setData, setDataRange

 

>

setDataTextDisplay, setDataTextFormat, & setDataTextPosition

 

>

setDepthAngle, setDepthRadius

 

>

setDisplay

 

>

setDisplay3DFloor, setDisplay3DLeftWall, & setDisplay3DRightWall

 

>

setDisplayBarAsPictograph

 

>

setDualAxisLineDisplay

 

>

setFillColor

 

>

setFontName, setFontSizeVC, setFontStyle

 

>

setFootnoteDisplay, setFootnoteString

 

>

setFrameDisplay

 

>

setGraphType

 

>

setGroupLabel

 

>

setGrid3DFloorDisplayX, setGrid3DFloorDisplayZ

 

>

setGrid3DLeftWallDisplayY, setGrid3DLeftWallDisplayZ

 

>

setGrid3DRightWallDisplayX, setGrid3DRightWallDisplayY

 

>

setGrid3DRiserDisplayX, setGrid3DRiserDisplayY, setGrid3DRiserDisplayZ

 

>

setGroupLabelArray

 

>

setLegendAutomatic, setLegendDisplay, setLegendRect

 

>

setLineWidth

 

>

setMarkerShape, setMarkerSize

 

>

setO1AxisLineDisplay, setO1AxisSide, setO1LabelAutofit, setO1LabelDisplay, setO1LabelStagger, setO1MajorGridDisplay, setO1MinorGridDisplay

 

>

setO2LabelAutofit, setO2LabelDisplay

 

>

setPieDepth, setPieFeelerTextDisplay, setPieRingSize, setPieRingTotalDisplay, setPieRingTotalFormat, setPieRotate, setPieSliceDelete, setPiesPerRow, setPieTilt

 

>

setQuadrantLineCountX, setQuadrantLineCountY, setQuadrantLineValueX, setQuadrantLineValueY

 

>

setRect

 

>

setReverseSeries

 

>

setRiser3DThicknessY, setRiserBarGroupSpacing, setRiserWidth

 

>

setScaleFromZero

 

>

setSeriesAreRows, setSeriesLabel, setSeriesLabelArray

 

>

setSquareMarkers

 

>

setStockCloseTicksDisplay, setStockOpenTicksDisplay

 

>

setSubtitleDisplay, setSubtitleString

 

>

setTextString, setTextRotation

 

>

setTitleDisplay, setTitleString

 

>

setTransparentBorderColor, setTransparentFillColor

 

>

setX1AxisDescending, setX1AxisLineDisplay, setX1AxisSide, setX1LabelAutofit, setX1LabelDisplay, setX1LabelFormat, setX1LabelStagger, setX1LogScale, setX1MajorGridDisplay, setX1MajorGridStepAuto, setX1MajorGridStyle, setX1MinorGridDisplay, setX1MinorGridStepAuto, setX1MinorGridStyle, setX1MustIncludeZero, setX1OffScaleDisplay, setX1ScaleMax, setX1ScaleMaxAuto, setX1ScaleMin, setX1ScaleMinAuto, setX1TitleDisplay, setX1TitleString, setX1ZeroLineDisplay

 

>

setY1AxisDescending, setY1AxisLineDisplay, setY1AxisSide, setY1LabelAutofit, setY1LabelDisplay, setY1LabelFormat, setY1LabelStagger, setY1LogScale, setY1MajorGridDisplay, setY1MajorGridStepAuto, setY1MajorGridStyle, setY1MinorGridDisplay, setY1MinorGridStepAuto, setY1MinorGridStyle, setY1MustIncludeZero, setY1OffScaleDisplay, setY1ScaleMax, setY1ScaleMaxAuto, setY1ScaleMin, setY1ScaleMinAuto, setY1TitleDisplay, setY1TitleString, setY1ZeroLineDisplay

 

>

setY2AxisDescending, setY2AxisLineDisplay, setY2AxisSide, setY2LabelAutofit, setY2LabelDisplay, setY2LabelFormat, setY2LabelStagger, setY2LogScale, setY2MajorGridDisplay, setY2MajorGridStepAuto, setY2MajorGridStyle, setY2MinorGridDisplay, setY2MinorGridStepAuto, setY2MinorGridStyle, setY2MustIncludeZero, setY2OffScaleDisplay, setY2ScaleMax, setY2ScaleMaxAuto, setY2ScaleMin, setY2ScaleMinAuto, setY2TitleDisplay, setY2TitleString

 

The following JavaScript data objects are translated by ReadJAVAScriptChartFile():

 

>

getChartBackground

 

>

getCubeFloor, getCubeLeftWall, getCubeRightWall

 

>

getDataText, getFootnote, getFrame, getGroup

 

>

getLegendArea, getLegendLine, getLegendMarker, getLegendText

 

>

getO1MajorGrid, getO2MajorGrid, getO1Label, getO2Axis

 

>

getPieLabel

 

>

getQuadrantLine

 

>

getSeries

 

>

getSubtitle, getTitle

 

>

getX1Title, getY1Axis, getY1Label, getY1MajorGrid, getY1Title

 

>

getY2Label, getY2Title

 

For a WriteJAVAScriptChartFile() operation you can write a PGSDK chart look or the chart look and data to a Java script file that is compatible with Perspective for Java. You can also write the file in HTML format. See the PGSDK-to-JavaScript Cross-Reference in Appendix C for a complete list of PGSDK objects, attributes, and API functions that can be translated to Java script.

ANNOTATIONS

 

Annotation functions can be used to draw rectangles, rounded rectangles, ellipses, polygons, lines, arrows, free hand lines, and text boxes in a chart.

Creating Annotations

 

Although the editing of annotation attributes is functionally identical to the editing of graph attributes, the creation of these objects is different. Creation of annotations requires the following steps:

 

1.

Allocate a PolyHandle

 

2.

Add points to the PolyHandle

 

3.

Close the PolyHandle

 

4.

Use CreateAnode() to create annotation objects.

Allocate a PolyHandle

 

Use AllocPolyHandle() to allocate a PolyHandle and get a pointer to the PolyHandle.

 

PolyHandle PUBLIC AllocPolyHandle(void);

 

void PUBLIC FreePolyHandle(PolyHandle hPoly);

Add Points to PolyHandle

 

Use AddPolyPoint() to add points to the polygon.

 

INT16 PUBLIC AddPolyPoint(
     // Polyhandle from AllocPolyHandle()
     PolyHandle FAR * hPoly,
     /* x,y coordinates of point */
     INT16 x, INT16 y,
     /* first point flag */
     int isFirstPoint
);

Close PolyHandle

 

When all points have been added, use ClosePolyHandle() to close the PolyHandle.

 

void PUBLIC ClosePolyHandle(PolyHandle FAR * hPoly);

Create and Remove Annotation Items

This function calls the annotation engine to create an annotation node of the specified type (aType).

 

INT16
CreateAnode (
     GraphPtr pGraph,
     INT16 aType,
     Rect FAR * bounds,
     MEMHDL hText,
     _PolyHandle hPoly,
     WedgeInfoPtr pWedge,
     Point startPt,
     Point endPt
);

 

The Remove() function can be used to remove a selected annotation item or all annotation items.

 

int
Remove (
GraphPtr pGraph,
SelListPtr pSelList,
BOOLEAN16 all
);

Other Useful API Functions for Annotations

 

Use the following API functions to:

 

1.

Lock a PolyHandle

 

2.

Query the number of points

 

3.

Query the bounds of a polygon

 

4.

Duplicate a polygon

 

PolyPtr PUBLIC LockPolyHandle(PolyHandle hPoly);
void PUBLIC UnlockPolyHandle(PolyHandle hPoly);
INT16 PUBLIC GetPolyPointCount(PolyHandle hPoly);
INT16 PUBLIC GetPolyPtrPointCount(PolyPtr pPoly);
void PUBLIC GetPolyBounds(PolyHandle hPoly,
     Rect FAR * pRect);
void PUBLIC GetPolyPtrBounds(PolyPtr pPoly,
     Rect FAR * pRect);
BOOLEAN PUBLIC ClonePolyHandle(PolyHandle FAR * phPoly);

 

 

SPECIAL SUPPORT FOR UNIX/LINUX PLATFORMS

 

The Headless-Server version of the PGSDK is a build that runs on UNIX/LINUX platforms. This version does its own internal rendering of the chart and generates various bitmap forms (GIF, BMP, PNG) using functions such as ExportGIF(), ExportGIFToMemory, ExportPNG(), etc.

 

This version is designed for developers who want to use PGSDK in a web-server ennvironment. It runs on the most popular UNIX platforms (AIX, HP-UX, SOLARIS, LINUX/Intel).

 

In basic usage:

 

1.

Design a chart template using the Windows Editor (Amigo).

 

2.

Move the template to a UNIX server.

 

3.

Write a CGI applet that links to the UNIX vesion (headless server) of the PGSDK. This applet calls the standard PGSDK functions: InitTDGLIB(), AllocGraphPtr(), Load_TIFFGraph(), SetGraphDataInfo(), etc.

 

When it is time to output the graph, your application cannot call any of the draw environment functions (such as DESetDestRect, AllocDrawEnv()) or the DrawBegin() or DrawTheGraph() functions. Instead, the graph pointer must be passed to an export call (such as ExportPNG()). The Export...() function can output the picture to disk or directly to memory. If the output is memory, the chart is typically spooled directly upstream to a web browser.

 

Since their is normally no draw environment pointer (pDE) to query (and no device context handle (hDC) to provide access to system functions), this special version of PGSDK does its own internal processing with these specialized versions of PlaceDefaultElements() and DryRunTheGraph() that work in a headless-server environment:

 

HS_PlaceDefaultElements() - Identical to PlaceDefaultElements(), but designed for use in Headless server version of PGSDK. This function does "auto-layout" of the chart so that nothing overlaps and everything has nice default sizes and positions. The most common usage is in scenarios where customers are spooling out dozens (or hundeds) of charts with different size data sets. If we were to use just a regular template, invariably some of the charts would look BAD - labels too small, legend too big, etc... This function adjusts on the fly for that by adjusting each chart to the data it contains.

 

HS_DryRunTheGraph() - This function is identical to PlaceDefaultElements() but it is designed for use in the Headless-Server version of PGSDK. This function does automatic layout of the chart so that chart objects do not overlap and everything has nice default sizes and positions. The most common usage is in scenarios where many (dozens or hundreds) of charts with different data sets are being spooled. If only a regular template is used, invariably some of the charts will look bad - labels too small, legend too big, etc. This function adjusts for this condition, on-the-fly, by adjusting each chart to the data each chart contains.

IMAGE EXPORT FUNCTIONS

 

PGSDK provides the following functions to export the chart image in various image formats to memory or a file.

 

ExportBMP(); Exports a chart as a Windows BMP image to a specified file.

 

ExportBMPtoRamFile(); Exports a chart as a Windows BMP image to a specified RAM file (memory).

 

ExportGIF(); Exports a chart as a GIF image to a specified file.

 

ExportGIFtoMemory(); Exports a chart as a GIF image to memory.

 

ExportPNG(); Exports a chart as a PNG image to a file.

 

ExportPNGToMemory(); Exports a chart as a PNG image to memory.