The draw environment functions are used to define the window, device context, destination rectangle, etc. where the graph(s) is(are) drawn. |
|
AllocDrawEnvPtr(); Allocate a Draw Environment Pointer | |
DEForceDetNodes(); Draw Environment Force Detection Nodes | |
DEGetDestRect(); Draw Environment Get Destination Rectangle | |
DEGetDrawProcs(); Draw Environment Get Drawing Procedures | |
DEGetGlobalFontInfo (); Draw Environment Get Global Font Information | |
DEGetMeasurements(); Draw Environment Get Measurements | |
DEGetPenMode(); Draw Environment Get Pen Mode | |
DEGetPortInfo(); Draw Environment Get Port Information | |
DEGetVirtRect(); Draw Environment Get Virtual Rectangle | |
DERegisterCallbacks(); Draw Environment Register Callback functions |
|
DESetActionProcs(); Draw Environment Set Action Procedures | |
DESetDestRect(); Draw Environment Set Destination Rectangle | |
DESetDrawProcs(); Draw Environment Set Drawing Procedures | |
DESetGlobalFontInfo(); Draw Environment Set Global Font Information | |
DESetMeasurements(); Draw Environment Set Measurements | |
DESetPenMode(); Draw Environment Set Pen Mode | |
DESetPortInfo(); Draw Environment Set Port Information | |
DESetVirtRect(); Draw Environment Set Virtual Rectangle | |
DrawBegin(); Draw Begin | |
DrawEnd(); Draw End | |
FreeDrawEnvPtr(); Free Draw Environment Pointer |
This function allocates a new Draw Environment Object, sets the default values of virtual/target rectangles, and initializes variables that support the drawing process. Platform specific information associated with drawing is also specified at this time. |
|||
Syntax: |
DrawEnvPtr PUBLIC |
||
Input: |
port: Platform-specific information of the GrafPort (Macintosh) or Device Context (Windows). |
||
nPortType: Set to a value from the DE_PORT_TYPES enum. Indicates the type of platform-specific information. The following table describes relationship between the two: |
|||
Mac port |
Windows port |
nPortType Setting |
|
NULL |
NULL |
DE_PORT_NULL (unknown) |
|
GrafPtr |
HDC |
DE_PORT_NORMAL (screen or off-screen) |
|
GrafPtr |
HDC |
DE_PORT_OFFSCREEN (off-screen bitmap) |
|
GrafPtr |
HDC (Metafile DC) |
DE_PORT_PICTURE (Metafile or PICT) |
|
GrafPtr |
DE_PORT_PIP |
||
GrafPtr |
HDC (Printer DC) |
DE_PORT_PRINTING (Printing Device) |
|
DE_PORT_COREL_WPG (Draw to Corel WPG using their GI library) |
|||
DE_PORT_ENHMETAFILE (For enhanced metafile, use clipping, but still draw when not visible) |
|||
DE_PORT_OPENGL (for proper processing of the 2D parts i.e., title text sfx, etc.of an OpenGL chart) |
|||
DE_PORT_GLPICTURE (for proper processing of the 2D parts i.e., title text sfx, etc.of an OpenGL chart) |
|||
DE_PORT_NULL is used when the port to be associated with the drawing environment is not known. This port information must be specified later with DESetPortInfo(). This is the standard case for Windows since the value of the DC could change for every WM_PAINT message. |
|||
Return: |
DrawEnvPtr: |
||
Non-Zero = a valid Draw Environment Pointer |
|||
NULL = Error, draw environment not created |
|||
Notes: |
This function must be called in the initialization code of any application that uses this library. See the PGSDK Programmer's Manual for more details. |
||
Also See: |
This function is used to force detection node generation in any port mode. When DESetPortInfo() or AllocDrawEnvPtr() selects DE_PORT_OFFSCREEN, DE_PORT_PRINTING, or DE_PORT_PICTURE mode, detection nodes are not generated. Use this function to force generation of detection nodes in one of these modes. |
|
Syntax: |
INT16 PUBLIC |
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
bMode: TRUE = Force Detection node Generation. |
|
Return: |
INT16: E00_OK |
Example: |
if ( m_bDoAdv3D ) |
Also See: |
This function gets the destination rectangle information from the draw environment data structure identified by pDE and stores it in the rectangle data structure pRect. This information is set by DESetDestRect(). |
|
Syntax: |
INT16 PUBLIC |
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
pBounds: Pointer to a rectangle (Rect) data structure |
|
Return: |
INT16: E00_OK |
Also See: |
|
This function sets the location at pIndex to the nDrawProcs entry in the draw environment (pDE) data structure. This entry indicates the index value of the current drawing procedures for the specified draw environment. This information is set by DESetDrawProcs(). |
|||
Syntax: |
INT16 PUBLIC |
||
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
||
pIndex: Pointer to an INT16 where the drawing procedures index can be stored. On return, it may contain one of the following from the StdDrawProcTypes enum: |
|||
StdDrawProcTypes |
Value |
Description |
|
DE_PROCS_DEFAULT |
0 |
Drawing and Detection |
|
DE_PROCS_DETECTION_ONLY |
1 |
Detection Only |
|
DE_PROCS_DRAWING_ONLY |
2 |
Drawing Only |
|
DE_PROCS_ADVANCED_3D |
3 |
Advanced 3D Rendering |
|
DE_PROCS_COREL_WPG |
4 |
Draw to Corel WPG (using their GI library) |
|
Return: |
INT16: E00_OK |
||
Also See: |
This function stores the font mode, scaling flag, and greeking size entries from the Draw Environment data structure (pDE) into the location identified by pGlobalFont. This information can be set by DESetGlobalFontInfo(). |
||
Syntax: |
INT16 PUBLIC |
|
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
|
pGlobalFont: Pointer to a global font data structure. See the GlobalFontClass data structure in Appendix A. |
||
Return: |
INT16 |
|
Value |
Description |
|
E00_OK |
No Errors |
|
E00_INVALID_STRUCT_SIZE |
The destination (pGlobalFont) was not the correct size to store the requested information. |
|
Also See: |
||
This function returns the horizontal and vertical size of the draw environment (pDE) in 1/1000-inch increments. The horizontal and vertical size values are stored in pnHorz and pnVert. These values can be set by DESetMeasurements(). |
|
Syntax: |
INT16 PUBLIC |
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
pnHorz: Place to store horizontal size. |
|
pnVert: Place to store vertical size. |
|
Return: |
INT16: E00_OK |
Also See: |
|
This function gets the pen mode information from the draw environment data structure (pDE) and stores it in the location specified by pPenMode. The pen mode information can be set by DESetPenMode(). |
|||
Syntax: |
INT16 PUBLIC |
||
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
||
pPenMode: Pointer to an INT16. The successful execution of this function will set this location to a value from the DE_PEN_MODES enum: |
|||
DE_PEN_MODES |
Value |
Description |
|
DE_PEN_NORMAL |
0 |
Normal drawing mode |
|
DE_PEN_XOR |
1 |
Exclusive-or drawing mode |
|
Return: |
INT16: E00_OK |
||
Example: |
INT16 myPenMode; |
||
Also See: |
This function gets platform-specific information about the port that is associated with the given draw environment. This information is set by DESetPortInfo(). The information is stored at the locations specified by pPort and pnPortType. |
|||
Syntax: |
INT16 PUBLIC |
||
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
||
pPort: Specifies a location where the platform-specific output port from the draw environment data structure will be stored. |
|||
pnPortType: Specifies a location where the platform-specific port type from the draw environment data structure will be stored. |
|||
Following the execution of this function, pPort and pnPortType will be set to one of the following values: |
|||
Mac |
Windows |
A value from the |
|
NULL |
NULL |
DE_PORT_NULL = unknown |
|
GrafPtr |
HDC |
DE_PORT_NORMAL = screen |
|
GrafPtr |
HDC |
DE_PORT_OFFSCREEN = offscreen bitmap |
|
GrafPtr |
HDC (Metafile DC) |
DE_PORT_PICTURE = Metafile or PICT |
|
DE_PORT_PIP |
|||
GrafPtr |
HDC (Printer DC) |
DE_PORT_PRINTING = printing device |
|
DE_PORT_COREL_WPG (Draw to Corel WPG using their GI library) |
|||
DE_PORT_ENHMETAFILE (For enhanced metafile, use clipping, but still draw when not visible) |
|||
DE_PORT_OPENGL (for proper processing of the 2D parts i.e., title text sfx, etc.of an OpenGL chart) |
|||
DE_PORT_GLPICTURE (for proper processing of the 2D parts i.e., title text sfx, etc.of an OpenGL chart) |
|||
DE_PORT_NULL indicates the port associated with the drawing environment is not known. It must be specified with the DESetPortInfo() function. This is the standard case for Windows since the value of the DC could change for every WM_PAINT message. |
|||
Return: |
INT16: E00_OK; |
||
Also See: |
AllocDrawEnvPtr() & DESetPortInfo() |
This function stores the virtual rectangle information from the draw environment data structure identified by pDE in the rectangle data structure pRect. |
|
Syntax: |
INT16 PUBLIC |
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
pRect: Pointer to a rectangle (Rect) data structure |
|
Return: |
INT16: E00_OK |
Example: |
/* Get current center of page */ |
Also See: |
This function registers three procedure addresses: |
||
1) |
The first address (pMaybeSwitchDE) identifies a procedure that can be given control from the application. |
|
2) |
The second address (pDoneWithSwitchedDE) identifies a procedure that returns control to the application when pMaybeSwitchDE is done. |
|
3) |
The third address (pDetNodeFilterProc) identifies a detection node filter procedure. This address can be set to NULL if it is not required. |
|
Syntax: |
INT16 PUBLIC DERegisterCallbacks ( |
|
INT16 (FAR *pDoneWithSwitchedDE)( |
||
INT16 (FAR *pDetNodeFilterProc) ( |
||
Input: |
pDE: Pointer to a Draw Environment created by AllocDrawEnvPtr() |
|
pMaybeSwitchDE: Address of procedure to be given control from the application. |
||
pDoneWithSwitchedDE: Address of procedure to return to when the switched procedure (pMaybeSwitchDE) is done. |
||
pDetNodeFilterProc: Address of a detection node filter procedure. May be set to NULL if this procedure is not required. |
||
lClientData: User-defined data |
||
Return: |
INT16: E00_OK |
|
Example: |
/* Register the Action Callback Procedures */ |
|
Also See: |
||
This function sets the drawing procedures for the draw environment (pDE) to the SDMM_draw procedures. |
|
Syntax: |
INT16 PUBLIC |
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
Return: |
INT16: E00_OK |
Example: |
/* Register the Action Callback Procedures */ |
Also See: |
|
This function sets the bounds of the destination rectangle to the specified rectangle (pRect). The destination rectangle is specified in device coordinates. The virtual rectangle is mapped into the device rectangle for all drawing calls. |
|
Syntax: |
INT16 PUBLIC |
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
pRect: Pointer to a rectangle (Rect) data structure where the virtual coordinates of the rectangle are stored. |
|
Return: |
INT16: E00_OK |
Example: |
/* Set Graph Rect to Entire Client Area */ |
Also See: |
This function sets the drawing procedures for the specified draw environment (pDE). Use DEGetDrawProcs() to determine which drawing procedures are currently being used. |
|||
Syntax: |
INT16 PUBLIC |
||
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
||
nIndex: Specify the new procedure index as one of the following: |
|||
StdDrawProcTypes |
Value |
Description |
|
DE_PROCS_DEFAULT |
0 |
Drawing and Detection |
|
DE_PROCS_DETECTION_ONLY |
1 |
Detection Only |
|
DE_PROCS_DRAWING_ONLY |
2 |
Drawing Only |
|
DE_PROCS_ADVANCED_3D |
3 |
Advanced 3D Rendering |
|
DE_PROCS_COREL_WPG |
4 |
||
Return: |
INT16 |
||
E00_OK = No Errors |
|||
E00_RANGE_ERR = Invalid value of nIndex |
|||
Example: |
/* Set standard draw to using |
||
Also See: |
|||
This function stores the font mode, scaling flag, and greeking size entries from the data structure identified by pGlobalFont into the Draw Environment's data structure (pDE). Use DEGetGlobalFontInfo() to determine the font information that is currently stored in the draw environment. |
||
Syntax: |
INT16 PUBLIC |
|
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
|
pGlobalFont: Pointer to a global font data structure. See the GlobalFontClass data structure in Appendix A. |
||
Return: |
INT16 |
|
E00_OK = |
No Errors |
|
E00_INVALID_STRUCT_SIZE = |
pGlobalFont points to an invalid data structure (i.e., wrong size). |
|
Example: |
GlobalFontClass myFontRec; |
|
Also See: |
||
This function sets the horizontal and vertical size of the draw environment (pDE) in 1/1000-inch increments. Use DEGetMeasurements() to determine the current size of the draw environment. |
|
Syntax: |
INT16 PUBLIC |
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
pnHorz: Horizontal measurements |
|
pnVert: Vertical measurements |
|
Return: |
INT16: Zero |
Also See: |
|
This function sets the pen mode information (at pPenType) into the draw environment identified by pDE. Use DEGetPenMode() to determine the drawing mode that is currently being used. |
||||
Syntax: |
INT16 PUBLIC |
|||
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
|||
nPenType: INT16 that is set to a value from the DE_PEN_MODES enum. |
||||
DE_PEN_MODES |
Value |
Description |
||
DE_PEN_NORMAL |
0 |
Normal drawing mode |
||
DE_PEN_XOR |
1 |
Exclusive-or drawing mode |
||
Return: |
INT16 |
|||
E00_OK = |
No Errors |
|||
E00_RANGE_ERROR = |
Invalid value in pPenMode |
|||
Also See: |
This function sets platform-specific information about the port associated with the given draw environment (pDE). Use DEGetPortInfo() to determine the port information that is currently set. |
||||
Syntax: |
INT16 PUBLIC |
|||
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
|||
port: Specifies a platform specific output port |
||||
nPortType: Specifies a platform-specific port type. It can be one of the following: |
||||
Mac |
Windows |
A value from the |
||
NULL |
NULL |
DE_PORT_NULL = unknown |
||
GrafPtr |
HDC |
DE_PORT_NORMAL = screen |
||
GrafPtr |
HDC |
DE_PORT_OFFSCREEN = offscreen bitmap |
||
GrafPtr |
HDC (Metafile DC) |
DE_PORT_PICTURE = Metafile or PICT |
||
DE_PORT_PIP |
||||
GrafPtr |
HDC (Printer DC) |
DE_PORT_PRINTING = printing device |
||
DE_PORT_COREL_WPG (Draw to Corel WPG using their GI library) |
||||
DE_PORT_ENHMETAFILE (For enhanced metafile, use clipping, but still draw when not visible) |
||||
DE_PORT_OPENGL (for proper processing of the 2D parts i.e., title text sfx, etc.of an OpenGL chart) |
||||
DE_PORT_GLPICTURE (for proper processing of the 2D parts i.e., title text sfx, etc.of an OpenGL chart) |
||||
Return: |
INT16 |
|||
E00_OK = |
Set operation successfully completed. |
|||
E00_RANGE_ERROR = |
Invalid nPortType |
|||
Notes: |
DE_PORT_NULL is used when the port to be associated with the drawing environment is not known at the time the drawing environment is created. It must be specified later with the DESetPortInfo() function. This is the standard case for Windows since the value of the DC could change for every WM_PAINT message. |
|||
Also See: |
This function sets the bounds of the virtual rectangle to the specified rectangle (pRect). The rectangle is specified in virtual coordinates. The virtual rectangle is mapped into the device rectangle for all drawing calls. Use DEGetVirRect() to determine the current bounds of the virtual rectangle. |
|
Syntax: |
INT16 PUBLIC |
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
pRect: Pointer to a rectangle (Rect) data structure |
|
Return: |
E00_OK |
Notes: |
The virtual rectangle is normally initialized when the drawing environment is allocated (AllocDrawEnvPtr) and is not changed after that. It is strongly recommended that you do NOT use this function. The default settings of |
Example: |
//Pointer to device rectangle to mask |
Also See: |
This function is used at the start of a series of standard drawing commands. The pDE parameter points to a valid drawing environment. |
|
Syntax: |
INT16 PUBLIC |
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
Return: |
E00_OK |
Notes: |
Calls to DrawBegin() and DrawEnd() must bracket all drawing commands. Also see the PGSDK Programmer's Manual (Graph Basics) for more information about this and other API functions that are essential elements in using the graphics library. |
Example: |
DrawBegin ( gpLeftDrawEnv );DrawTheGraph(gpLeftDrawEnv, gpLeftGraph,TRUE,TRUE,TRUE ); DrawEnd ( gpLeftDrawEnv ); |
Also See: |
DrawEnd() |
DrawEnd()
This function terminates the end of the current drawing session. It releases all memory previous allocated to the draw environment by AllocDrawEnvPtr(). All drawing calls must be bracketed between DrawBegin() and DrawEnd() functions. See Sample below. |
|
Syntax: |
INT16 PUBLIC |
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
Return: |
INT16: E00_OK |
Notes: |
Also see the PGSDK Programmer's Manual (Graph Basics) for more information about this and other API functions that are essential elements in using the graphics library. |
Example: |
DrawBegin ( gpLeftDrawEnv ); |
Also See: |
This function releases the memory used by the Draw Environment data structure. The memory used by this data structure was allocated by a previous call to AllocDrawEnvPtr(). |
||
Syntax: |
INT16 PUBLIC |
|
Input: |
pDE: Pointer to a draw environment created by AllocDrawEnvPtr() |
|
Return: |
INT16 |
|
Value |
Description |
|
E00_OK = |
Successful |
|
E00_INVALID_NULL_ARG = |
pDE is NULL |
|
Notes: |
Also see the PGSDK Programmer's Manual (Graph Basics) for more information about this and other API functions that are essential elements in using the graphics library. |
|
Example: |
/* Free Draw Environment Memory */ |
|
Also See: |
||