Chapter 25:
Headless-Server Functions for Unix Applications
 

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.

 

GloGetDefaultFontName(); Get TrueType default font name

 

GloGetDefaultFontPath(); Get TrueType default font path

 

gloSetBackgroundGIF(); Set unpainted background pixels to be a passed-in GIF file

 

GloSetDefaultFontName(); Set TrueType default font name

 

GloSetDefaultFontPath(); Set TrueType default font path

 

HS_DryRunTheGraph(); Headless-Server version of DryRunTheGraph()

 

HS_PlaceDefaultElements(); Headless-Server version of PlaceDefaultElements()

   

GloGetDefaultFontName()

 

This function and GloGetDefaultFontPath() are used to get TrueType default font parameters on UNIX machines.

Syntax:

LPCSTR PUBLIC
GloGetDefaultFontName();

Input:

None

Return:

LPCSTR; Pointer to a character string that defines the default font name.

Also See:

GloGetDefaultFontPath(), GloSetDefaultFontName(), GloSetDefaultFontPath()

   

GloGetDefaultFontPath()

 

This function and GloGetDefaultFontName() are used to get TrueType default font parameters on UNIX machines.

Syntax:

LPCSTR PUBLIC
GloGetDefaultFontPath();

Input:

None

Return:

LPCSTR; Pointer to a character string that defines the default font path.

Also See:

GloGetDefaultFontName(), GloSetDefaultFontName(), GloSetDefaultFontPath()

   

gloSetBackgroundGIF()

 

For the Headless-Server version of the PGSDK ONLY

 

This function sets unpainted background pixels to be a passed-in GIF file.

Syntax:

INT16 PUBLIC
gloSetBackgroundGIF(
     LPSTR szFile,
     INT16 nMode
);

Input:

szFile; Name of GIF file to be used. NULL = Free global background memory.

 

nMode; 0/1

 

Value

Description

 

0=

TILE this image on background

 

1=

STRETCH this image to fit background

Return:

INT16;

 

Value

Description

 

E00_OK

Success

 

E00_FILE_NOT_FOUND

Failed

   

GloSetDefaultFontName()

 

This function and GloSetDefaultFontPath() are used to set TrueType default font parameters on UNIX machines.

Syntax:

void PUBLIC GloSetDefaultFontName(
     char *pszDefaultFontName
);

Input:

pszDefaultFontName; Pointer to the default font name.

Return:

void

Example:

/* Choose a TrueType font to use as "default" */
/* if requested font does not exist on this server */
GloSetDefaultFontName("arialbd.ttf");
/* Set the path on this machine to look */
/* for TrueType (.ttf) fonts. */
GloSetDefaultFontPath("./");

Notes:

This function and GloSetDefaultFontPath() set TrueType font support defaults. To use TrueType fonts, you need the FREETYPE library. This library is available as shareware at www.freetype.org. If no TrueType fonts are found, PGSDK will default to internal bitmap fonts instead.

Also See:

GloGetDefaultFontName(), GloGetDefaultFontPath(),
GloSetDefaultFontPath()

   

GloSetDefaultFontPath()

 

This function and GloSetDefaultFontName() are used to set TrueType default font parameters on UNIX machines.

Syntax:

void PUBLIC GloSetDefaultFontPath(
     char *pszDefaultFontPath
);

Input:

pszDefaultFontPath; Pointer to the default font path.

Return:

void

Notes:

This function and GloSetDefaultFontName() set TrueType font support defaults. To use TrueType fonts, you need the FREETYPE library. This library is available as shareware at www.freetype.org. If no TrueType fonts are found, PGSDK will default to internal bitmap fonts instead.

Also See:

GloGetDefaultFontName(), GloGetDefaultFontPath(), GloSetDefaultFontName()

   

HS_DryRunTheGraph()

 

Headless-Server Wrapper for DryRunTheGraph()

 

This function does the work of DryRunTheGraph when the Headless-Server version of the library is being used. It allocates and returns a valid draw environment pointer (DrawEnvPtr) that can be used for Selection List and Detection Node (Detnode) functions that require such a parameter.

 

This function is identical to DryRunTheGraph. In the Headless-Server version of PGSDK, the application may need to detect risers. The actual detection is done via an HTML image map. This call generates an internal draw environment pointer (pDE) that developers who use this platform can query to figure out the bounds of objects they wish to make detectable/selectable.

Syntax:

DrawEnvPtr PUBLIC
HS_DryRunTheGraph(
     GraphPtr pGraph,
     INT16 wantGraph,
     INT16 wantBackground,
     INT16 wantAnnotation,
     UINT16 cxBounds,
     UINT16 cyBounds
);

Input:

pGraph: Pointer to a graph created by AllocGraphPtr()

 

wantGraph: 0/1

 

0=

Don't draw the graph layer

 

1=

Draw the graph layer

 

wantBackground: 0/1

 

0=

Don't draw the background layer

 

1=

Draw the background layer

 

wantAnnotation: 0/1

 

0=

Draw the annotation layer

 

1=

Don't draw the annotation layer

 

cxBounds/cyBounds; Defines the x/y coordinates of the chart (in pixels)

Return:

DrawEnvPtr; Pointer to an internal draw environment

Notes:

See Special Features in the PGSDK Programmer's Manual

Also See:

DryRunTheGraph(), HS_PlaceDefaultElements()

   

HS_PlaceDefaultElements()

 

Headless-Server Wrapper for PlaceDefaultElements()

 

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.

Syntax:

INT16 PUBLIC
HS_PlaceDefaultElements(
     GraphPtr pGraph,
     UINT32 nElement,
     INT16 nLegendPlacement,
     UINT16 cxBounds,
     UINT16 cyBounds
);

Input:

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

 

nElement; One or more of the following #defined element codes:

 

#define

value

Description

 

EFRAME

0x0001

Default Frame position

 

ETITLE

0x0002

Default Title position

 

ESUBTITLE

0x0004

Default SubTitle position

 

EFOOTNOTE

0x0008

Default Footnote position

 

EY1TITLE

0x0010

Default Y1-Axis title position

 

EY2TITLE

0x0020

Default Y2-Axis title position

 

EXTITLE

0x0040

Default X-Axis title position

 

EMOVABLELABELS

0x0080

Restore Movable labels to base positions

 

ELEGEND

0x0100

Recalculate size of Legend

 

EY1LABEL

0x0200

Recalculate Y1-Axis Labels to fit

 

EY2LABEL

0x0400

Recalculate Y2-Axis Labels to fit

 

EXLABEL

0x0800

Recalculate X-Axis Labels to fit

 

EDEFAULTLABELSIZE

0x1000

Resize label to 10-point while putting in its default location

 

EDATATEXT

0x2000

Recalculate data labels to fit

 

EMAXIMIZEFRAME

0x4000

When items are turned off, make frame use up empty space

 

EPIELABEL

0x8000

Fit pie labels on pie charts

 

ECLEARHILITES

0x10000

Clear ALL hilite information

 

E3DCUBE

0x20000

Reset 3D Cube to a default size & position

 

EDATAMARKERS

0x40000

Resize and adjust data markers

 

E3DDEFAULTCUBE

0x80000

Reset 3D Cube to a default size and position

 

nLegentPlacement; Selects the placement of the legend with a value from the LegendPlacementType enum:

 

LegendPlacementType enum

Description

 

LEGEND_PLACEMENT_RIGHT (0)

Keep legend placement on the right side of the chart

 

LEGEND_PLACEMENT_LEFT (1)

Keep legend placement on the left side of the chart

 

LEGEND_PLACEMENT_BOTTOM (2)

Keep legend placement on the at the bottom of the chart

 

LEGEND_PLACEMENT_AUTO (3)

Automatic

 

cxBounds/cyBounds; Defines the x/y coordinates of the chart (in pixels)

Notes:

In nLegendPlacement is set to LEGEND_PLACEMENT_AUTO, this function will determine the current placement of the legend and use LEGEND_PLACEMENT_RIGHT, LEGEND_PLACEMENT_LEFT, or LEGEND_PLACEMENT_BOTTOM to reposition the legend based on which position most closely matches the current legend placement.

Return:

INT16; E00_OK = Success. Any other E00_XXX error code = Error.

Example:

UINT32 uElement = EFRAME |EMAXIMIZEFRAME |ETITLE |
     ESUBTITLE | EFOOTNOTE|ELEGEND |EXTITLE |EXLABEL |
     EY1TITLE |EY2TITLE |EY1LABEL |EY2LABEL | EPIELABEL;
rect.top = 0;
rect.left = 0;
rect.bottom = 599;
rect.right = 799;
/* PGSDK: Call to "auto-magically" layout the chart */
/* so things look nice and don't overlap */
HS_PlaceDefaultElements(gpGraph, uElement,
     LEGEND_PLACEMENT_RIGHT,
     (UINT16)(rect.right+1),
     (UINT16)(rect.bottom+1));

Notes:

See Special Features in the PGSDK Programmer's Manual

Also See:

HS_DryRunTheGraph(), PlaceDefaultElements()