home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / chart101.zip / README < prev    next >
Text File  |  1995-07-12  |  233KB  |  6,842 lines
  1.           
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.                       THE DEVELOPER'S BUSINESS GRAPHICS TOOLKIT
  17.                     for OS/2 Presentation Manager and Windows 3.0
  18.  
  19.                               (OS/2 32-bit mini-release)
  20.  
  21.  
  22.  
  23.  
  24.       THIS SOFTWARE IS COPYRIGHTED AND AS SUCH, ONLY THE CROSSLEY GROUP MAY
  25.       AUTHORIZE ITS DISTRIBUTION, USE WITHIN OTHER PRODUCTS, OR USE ON SYSTEMS
  26.       WHICH ARE DEEMED END USER SYSTEMS AND NOT DEVELOPMENT SYSTEMS.
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.    Copyright The Crossley Group, Inc. 1990, 1991, 1992, 1993, 1994, 1995
  54.  
  55.  
  56.  
  57.  
  58.                                   
  59.  
  60.  
  61.  
  62.  
  63.                       THE DEVELOPER'S BUSINESS GRAPHICS TOOLKIT
  64.                     for OS/2 Presentation Manager and Windows 3.0
  65.  
  66.                               (OS/2 32-bit mini-release)
  67.  
  68.  
  69.  
  70.         Description                                                 Page
  71.  
  72.         ════════════════════════════════════════════════════════    ═════
  73.  
  74.         Product Overview                                               1
  75.  
  76.         Sample Programming for OS/2 PM                                12
  77.  
  78.         API Technical Descriptions & Synopsis                         18
  79.  
  80.             ChartAnnotate ..........................................  18
  81.             ChartAnnotatePaint .....................................  20
  82.             ChartAnnotateRelease ...................................  21
  83.             ChartAnnotateDestroy ...................................  22
  84.             ChartClipboard .........................................  23
  85.             ChartCreate ............................................  24
  86.             ChartData ..............................................  28
  87.             ChartDataAppend ........................................  30
  88.             ChartDataUpdatePoint ...................................  31
  89.             ChartDataHighlight .....................................  33
  90.             ChartDestroy ...........................................  34
  91.             ChartGetData ...........................................  35
  92.             ChartGetDisplacement ...................................  36
  93.             ChartGetLastError ......................................  37
  94.             ChartGetValue ..........................................  38
  95.             ChartLegend ............................................  39
  96.             ChartOptions ...........................................  40
  97.             ChartOutputMetaFile ....................................  40
  98.             ChartPaint .............................................  41
  99.             ChartPrint .............................................  42
  100.             ChartQueryDimensions ...................................  44
  101.             ChartQueryExtendedError ................................  44
  102.             ChartQueryGroupColor ...................................  45
  103.             ChartQueryLocation .....................................  46
  104.             ChartQueryOptions ......................................  49
  105.             ChartQueryPointer ......................................  50
  106.             ChartQueryTextFontSize .................................  53
  107.             ChartQueryTextFontSizes ................................  53
  108.             ChartQueryType .........................................  53
  109.             ChartQueryVersion ......................................  53
  110.             ChartSendMsg ...........................................  54
  111.             ChartSendMsgVP .........................................  64
  112.  
  113.  
  114.  
  115.  
  116.                                  i
  117.  
  118.  
  119.  
  120.             ChartSendMsgPV .........................................  65
  121.             ChartSendMsgPP .........................................  66
  122.             ChartSetColor ..........................................  67
  123.             ChartSetColorTable .....................................  70
  124.             ChartSetCountryCode ....................................  71
  125.             ChartSetDimensions .....................................  73
  126.             ChartSetFont ...........................................  74
  127.             ChartSetFrame ..........................................  74
  128.             ChartSetGroupColor .....................................  75
  129.             ChartSetGroupCount .....................................  77
  130.             ChartSetGroupLineType ..................................  78
  131.             ChartSetGroupMarker ....................................  80
  132.             ChartSetGroupPattern ...................................  82
  133.             ChartSetGroupRGB .......................................  82
  134.             ChartSetGroupStyle .....................................  83
  135.             ChartSetLineType .......................................  85
  136.             ChartSetLineWidth ......................................  87
  137.             ChartSetMarker .........................................  88
  138.             ChartSetMaxXValue ......................................  88
  139.             ChartSetMaxYValue ......................................  88
  140.             ChartSetMaxZValue ......................................  88
  141.             ChartSetMinYValue ......................................  89
  142.             ChartSetMinZValue ......................................  89
  143.             ChartSetNormalDataScope ................................  89
  144.             ChartSetOptions ........................................  90
  145.             ChartSetPattern ........................................  90
  146.             ChartSetPointCount .....................................  91
  147.             ChartSetRect ...........................................  92
  148.             ChartSetRegions ........................................  94
  149.             ChartSetRGB ............................................  94
  150.             ChartSetSymbolGroup ....................................  94
  151.             ChartSetTableFormat ....................................  94
  152.             ChartSetTextFontSize ...................................  95
  153.             ChartSetTicks ..........................................  95
  154.             ChartSetTimeRange ......................................  95
  155.             ChartSetTimeReference ..................................  96
  156.             ChartSetType ...........................................  97
  157.             ChartSetWindow .........................................  99
  158.             ChartSetXTicks ......................................... 100
  159.             ChartSetXTicksFloat .................................... 102
  160.             ChartSetXTicksString ................................... 103
  161.             ChartSetXTicksStringBasic .............................. 105
  162.             ChartSetYTicksString ................................... 107
  163.             ChartSetZAxisGroup ..................................... 108
  164.             ChartText .............................................. 109
  165.             ChartTexts ............................................. 111
  166.             ChartVisible ........................................... 113
  167.  
  168.         Installation ............................................... 115
  169.  
  170.         Compiling and Linking you program  ......................... 115
  171.  
  172.         The Sample Program ......................................... 115
  173.  
  174.                                 ii
  175.  
  176.  
  177.  
  178.                 THE DEVELOPER'S BUSINESS GRAPHICS TOOLKIT
  179.               for OS/2 Presentation Manager and Windows 3.0
  180.  
  181.  
  182.  
  183.       The Developer's Business Graphics Toolkit is a toolkit to help
  184.       application developers integrate two- and three-dimensional business
  185.       graphics into their application programs.  This toolkit is provided FREE
  186.       to you to use and distribute on an as is basis.  As this is being
  187.       provided FREE, there is NO product support provided.  Further, the number
  188.       or data groups/series, the number of data points for each group/series
  189.       that can be displayed and the number of different chart types are the
  190.       only functional limitations placed on the mini-release of this software.
  191.       The maximum number of data groups/series is limited to three and the
  192.       maximum number of points for any group/series is four.  As a final point
  193.       not all of the APIs are documented in this electronic documentation
  194.       package.  A fully functional and documented toolkits are sold by The
  195.       Crossley Group, Inc.  (USA).  The company can be reached by telephone at
  196.       1-404-751-3704 or FAX 1-404-751-3704.  While this package you received
  197.       contains only support for 32-bit OS/2 development, other products are
  198.       available for 16-bit OS/2, 16-bit Windows and 32-bit NT and Windows 95
  199.       support.  The Crossley Group will answer questions you might have via
  200.       CompuServe 72103,2013 or Internet crossley@atlanta.com user id.
  201.  
  202.       THIS SOFTWARE IS COPYRIGHTED AND AS SUCH, ONLY THE CROSSLEY GROUP MAY
  203.       AUTHORIZE ITS DISTRIBUTION, USE WITHIN OTHER PRODUCTS, OR USE ON SYSTEMS
  204.       WHICH ARE DEEMED END USER SYSTEMS AND NOT DEVELOPMENT SYSTEMS.
  205.  
  206.       The heart of the toolkit is an intelligent graphics engine provided
  207.       as a Dynamic Link Library (DLL).  High level Application Programming
  208.       Interfaces (APIs) are issued to bridge to this DLL.  Business
  209.       graphics can be incorporated into new or existing applications with
  210.       minimal code supplied by the developer.  The high-level APIs
  211.       eliminate the need to learn GPI function calls.  This product was
  212.       designed to ensure end user appeal and ease of developer
  213.       implementation.
  214.  
  215.  
  216.       The Developer's Business Graphics Toolkit allows the developer to
  217.       select from many chart type presentations.  Many of the chart types
  218.       can be displayed in either two or three dimensions on the display.
  219.       Also, many of the chart types support a time-based or real time
  220.       implementation that will be describe later in more detail.
  221.  
  222.       The toolkit supports many languages and tools currently in use, as
  223.       well as IBM's National Language Support.  Languages currently
  224.       supported include English, French, German, Italian, Spanish, and
  225.       Swedish, Japanese, Fenish and Glasnost cyrillic.  Other languages
  226.       will be implemented based on customer requirements.
  227.  
  228.  
  229.  
  230.  
  231.  
  232.                                  1
  233.         
  234.  
  235.  
  236.       Charts types are specified through the use of symbolic notation.  The
  237.       following lists the chart type symbolic values and brief descriptions
  238.       for each chart type.
  239.  
  240.         
  241.           
  242.       ┌───────────────────────────┬──────────────────────────────────────────┐
  243.       │                           │                                          │
  244.       │     Symbolic Value        │          Chart Description               │
  245.       │                           │                                          │
  246.       ├───────────────────────────┼──────────────────────────────────────────┤
  247.       │                           │                                          │
  248.       │ CH_BAR                    │  Vertical bars                           │
  249.       │ CH_STACKED_BAR            │  Vertical stacked bars                   │
  250.       │ CH_COLUMN                 │  Vertical stacked bar summation          │
  251.       │ CH_LINE                   │  Line (supports line types)              │
  252.       │ CH_SMOOTH_LINE            │  Smooth line (solid lines only)          │
  253.       │ CH_SCATTER                │  Marker symbols                          │
  254.       │ CH_AREA                   │  Line charts with filled downward        │
  255.       │ CH_PIE                    │  Summarized groups                       │
  256.       │ CH_PER_BAR                │  Vertical bars in perspective view       │
  257.       │ CH_BAR_LINE               │  Vertical bars, last group is a line     │
  258.   *   │ CH_NUMERIC_TABLE          │  Spread sheet view of your data          │
  259.   *   │ CH_SYMBOL_TABLE           │  Marker symbols in a spread sheet        │
  260.       │ CH_SPIKE                  │  Marker symbols with a line downward     │
  261.       │ CH_SQUARE_WAVE            │  Engineering square wave                 │
  262.       │ CH_HISTOGRAM              │  Vertical bars groups together           │
  263.   *   │ CH_RANGE                  │  Stock charts (3-types)                  │
  264.       │ CH_HORIZONTAL_BAR         │  Horizontal bars                         │
  265.       │ CH_HORIZONTAL_STACKED_BAR │  Horizontal stacked bars                 │
  266.   *   │ CH_PLOT                   │  Drawing using plotter techniques        │
  267.   *   │ CH_OVERLAP_BAR            │  Vertical bars which overlap             │
  268.   *   │ CH_CONNECTED_SCATTER      │  Marker symbols with vertical connection │
  269.       │ CH_BAR_GOAL               │  Vertical bars, last group square wave   │ 
  270.   *   │ CH_X_PLOT                 │  Marker symbols with x-axis offsets      │
  271.   *   │ CH_MIXED                  │  Combinations - lines, hi/low, markers   │
  272.   *   │ CH_FLOAT_BAR              │  Vertical floating bars                  │
  273.   *   │ CH_FLOAT_STACKED_BAR      │  Vertical bars for a financial portfolio │
  274.   *   │ CH_MATRIX                 │  Marker symbols with x-axis scales       │
  275.       │ CH_STACKED_AREA           │  Area chart with groups/series stacked   │
  276.       │                           │                                          │
  277.       └───────────────────────────┴──────────────────────────────────────────┘
  278.  
  279.  
  280.  
  281.  
  282.   * AVAILABLE ONLY IN THE FULL PRODUCT
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.                                  2
  291.  
  292.  
  293.  
  294.       While there are over 25 different type of charts which can be 
  295.       displayed, not all charts are displayed or processing in the same 
  296.       manner.  Some charts can be displayed only in 2 dimensions, while
  297.       other charts are displayed in only 3 dimensions and finally a third
  298.       class of chart can be displayed in either 2 or 3 dimensions.
  299.  
  300.       As is true with the number of visual dimensions in which a chart
  301.       may be viewed, not all of the charts support real time or time based 
  302.       implementations.
  303.  
  304.       The following table describes the current implementation level of 
  305.       each of the different type of charts supported.
  306.  
  307.  
  308.           
  309.       ┌───────────────────────────┬────────────┬────────────┬────────────────┐
  310.       │                           │            │            │                │
  311.       │     Symbolic Value        │ Dimensions │ Time Based │ Real Time      │
  312.       │                           │            │            │                │
  313.       ├───────────────────────────┼────────────┼────────────┼────────────────┤
  314.       │                           │            │            │                │
  315.       │ CH_BAR                    │    2-3     │    YES     │    YES         │
  316.       │ CH_STACKED_BAR            │    2-3     │            │                │
  317.       │ CH_COLUMN                 │    2-3     │            │                │
  318.       │ CH_LINE                   │    2-3     │    YES     │    YES         │
  319.       │ CH_SMOOTH_LINE            │     2      │    YES     │    YES         │
  320.       │ CH_SCATTER                │     2      │    YES     │    YES         │
  321.       │ CH_AREA                   │    2-3     │    YES     │                │
  322.       │ CH_PIE                    │    2-3     │            │                │
  323.       │ CH_PER_BAR                │     3      │            │    YES         │
  324.       │ CH_BAR_LINE               │    2-3     │            │    YES         │
  325.       │ CH_NUMERIC_TABLE          │     2      │            │    YES         │
  326.       │ CH_SYMBOL_TABLE           │     2      │            │    YES         │
  327.       │ CH_SPIKE                  │     2      │            │    YES         │
  328.       │ CH_SQUARE_WAVE            │     2      │            │    YES         │
  329.       │ CH_HISTOGRAM              │    2-3     │            │                │
  330.       │ CH_RANGE                  │     2      │    YES     │                │
  331.       │ CH_HORIZONTAL_BAR         │    2-3     │            │                │
  332.       │ CH_HORIZONTAL_STACKED_BAR │    2-3     │            │                │
  333.       │ CH_PLOT                   │     2      │            │    YES         │
  334.       │ CH_OVERLAP_BAR            │    2-3     │            │                │
  335.       │ CH_CONNECTED_SCATTER      │     2      │    ONLY    │                │
  336.       │ CH_BAR_GOAL               │    2-3     │            │    YES         │
  337.       │ CH_X_PLOT                 │     2      │            │    YES         │
  338.       │ CH_MIXED                  │     2      │    YES     │                │
  339.       │ CH_FLOAT_BAR              │    2-3     │            │                │
  340.       │ CH_FLOAT_STACKED_BAR      │    2-3     │            │                │
  341.       │ CH_MATRIX                 │     2      │            │                │
  342.       │ CH_STACKED_AREA           │    2-3     │            │                │
  343.       │                           │            │            │                │
  344.       └───────────────────────────┴────────────┴────────────┴────────────────┘
  345.  
  346.  
  347.  
  348.                                  3
  349.  
  350.  
  351.  
  352.       For the application to display a chart the developer must provide a
  353.       window or portion of a window in which the chart will be shown.
  354.       The Developer's Business Graphics Toolkit DOES NOT create a window. 
  355.       It is the responsibility of the developer to create the appropriately
  356.       sized window for the chart and any application data space.  The 
  357.       window handle returned to the developer is a parameter for the 
  358.       Developer's Business Graphics Toolkit.  While the size and placement 
  359.       of the chart within the window will be discussed later, the business 
  360.       chart does not necessarily occupy an entire window.
  361.  
  362.       The toolkit DOES NOT respond to any messages associated with a 
  363.       window.  It is the responsibility of the developer to respond 
  364.       appropriately to these window messages.  For example, in processing a
  365.       WM_CREATE message and a WM_PAINT message, the developer can create 
  366.       and paint the business chart with The Developer's Business Graphics 
  367.       Toolkit.
  368.  
  369.       Charts can be shown in a complete window with other application data,
  370.       in scrollable windows, or in dialog boxes.  Creating a chart instance
  371.       is similar to creating a system window using the "ChartCreate" API.
  372.       The developer provides this API with a handle for the window and the
  373.       coordinates within the window to display the chart.  Defaults are
  374.       provided for the percentage of space allocated to headings, footings,
  375.       margins, and the central graphic area.  Developers, using their own
  376.       percentages, can dynamically change the amount of space assigned to
  377.       these areas to meet their specific goals.  The DLL automatically
  378.       handles all scaling of the text and graphic images.
  379.  
  380.       Using data arrays, the developer then provides data to the chart.
  381.       The chart supports a maximum of (in the full product)12 data arrays
  382.       (representing groups) and an unlimited number of data points per
  383.       array.  Data arrays supported include SHORT, USHORT, LONG, ULONG,
  384.       float and double data types.  Each data group requires a separate
  385.       request through the "ChartData" API.  The graphics engine retains the
  386.       specified data in system dynamic storage until the data is changed or
  387.       the chart is destroyed.  Besides specifying a pointer to the data
  388.       array, the developer can provide an ASCIIZ string that represents the
  389.       text legend for each data group.
  390.  
  391.       The "ChartSetXTicks" API provides automatic x-axis text values.  For
  392.       example, if the data to be presented reflects the last three months
  393.       of 1994, the developer can specify that the x-axis be displayed in
  394.       months, starting with the tenth month.  The chart shows the months of
  395.       October, November, and December.  If the developer provides more than
  396.       three data points, the chart continues with January as the fourth
  397.       month and follows through the next year as long as data is provided.
  398.       If the chart does not have enough width to accommodate the entire
  399.       spelling of the months, the DLL shifts into an abbreviation mode,
  400.       such as "Dec" or "D" for the month of December.  The x-axis text is
  401.       also provided for English, French, German, Italian, Spanish, and
  402.       Swedish languages.  When the DLL does not provide the type of text
  403.       required, the developer can provide a text array that can serve as an
  404.       extension to the graphics engine.
  405.  
  406.                                  4
  407.  
  408.  
  409.  
  410.       The developer can provide the chart heading, footing, left margin,
  411.       and right margin text to the chart using one request to the
  412.       "ChartSetTexts" API.  These also can be specified individually
  413.       through a "ChartSetText" request.  The developer issues a
  414.       ChartVisible API call to make the chart visible to the user.
  415.  
  416.       There is a "ChartSetRect" function call to support the user's ability
  417.       to resize a window.  This call informs the graphic chart that the
  418.       amount of real estate for the chart has changed.  The chart is then
  419.       redisplayed through the "ChartVisible" or "ChartSetType" function
  420.       request.  The "ChartSetType" API enables the developer to change the
  421.       current type of chart to another chart type.  The data, headings, and
  422.       other information have been retained by the DLL, no additional steps
  423.       are required.
  424.  
  425.  
  426.  
  427.  
  428.       Axis scaling
  429.       ═════════════
  430.  
  431.       The Y-axis and Z-axis (an axis opposite the y-axis) support manual or
  432.       automatic scaling for positive and negative data, including floating
  433.       point.  Automatic X-axis application-specific element support
  434.       includes:  general numbering (0 to n); calendar (days, weeks, months,
  435.       years); time (seconds, minutes, hours); military/international hours;
  436.       and accounting cycles (30, 60, 90, etc.).  Programmer defined ASCIIZ
  437.       string values and floating point values for the X-axis is also
  438.       supported.  Data is summarized automatically and percentages
  439.       displayed for pie and column charts.  The developer can specify chart
  440.       text, such as titles, footnotes, margins, and data legends.  Fonts
  441.       re-size automatically in the client chart areas.  Besides using the
  442.       standard sixteen colors, developers can specify any RGB color, of
  443.       which their display is capable, to enhance the graphic chart.
  444.  
  445.  
  446.       Coloring the chart
  447.       ══════════════════
  448.  
  449.       Each data group has a specific pair of colors assigned to it by
  450.       default.  For example, data group one is assigned red and dark red
  451.       (for the shadowing effects of 3-D charts).  The developer can change
  452.       these defaults to any of the standard sixteen colors or specify RGB
  453.       values to be associated with a data group.  Colors can also be
  454.       specified for all other portions of the chart.  This includes, but is
  455.       not limited to, the text, tick marks, chart background, and the
  456.       graphic background.
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.                                  5
  464.  
  465.  
  466.  
  467.       Calculations
  468.       ════════════
  469.  
  470.       Besides extensive automatic scaling facilities, the DLL will provide
  471.       automatic summations of data to display percentages for the column
  472.       and pie charts.  The developer does not have to perform these
  473.       summations or calculations.  For example, to change a bar chart to a
  474.       pie chart, the developer simply calls the "ChartSetType" function
  475.       call.  The data provided to the bar chart is recalculated,
  476.       summarized, and then displayed as a pie chart.  In support of the
  477.       stacked bar and column charts, the graphics engine will sort the data
  478.       by ascending magnitude if requested by the developer.  This sort,
  479.       performed in memory, requires no disk files or disk activity.
  480.  
  481.  
  482.       Text and legend(s) placement
  483.       ════════════════════════════
  484.  
  485.       The graphics engine centers and aligns all text within the chart
  486.       area.  It does this through internal font size balancing algorithms.
  487.       It is dependent upon the amount of graphic space available.  For
  488.       example, a chart consisting of four data groups or legends may show
  489.       the four legends placed side by side, or in two groups of two.  The
  490.       placement is based on such considerations as available chart width,
  491.       height, and the characters in the legend text.  The DLL will
  492.       sacrifice certain text when the window is too small for the smallest
  493.       system font.  The DLL's goal is to provide as much data as possible
  494.       in the space available.
  495.  
  496.  
  497.       Messages and When to Paint
  498.       ══════════════════════════
  499.  
  500.       The graphics engine, or DLL, does not post or send any messages to
  501.       the developer's application.  The developer must specify when to
  502.       repaint the graphic chart through the "ChartVisible", "ChartPaint" or
  503.       "ChartSetType" APIs.  The graphics engine does not create any windows
  504.       to accomplish its tasks.  It uses only GPI function calls to achieve
  505.       its goals.  The "ChartDestroy" API removes the chart instance.  The
  506.       application window belongs to the developer and the graphics engine
  507.       is merely a high-level support service.
  508.  
  509.  
  510.       Real Time Applications
  511.       ══════════════════════
  512.  
  513.       This section describes the concept of data display in real time
  514.       applications.  The "ChartDataAppend" API allows the developer to add
  515.       continuing data points to an existing chart.  The application
  516.       developer can add these data points to a data group without
  517.       repainting the graphic chart.  The chart is repainted when the Y-axis
  518.       maximum or minimum is exceeded.  The chart types supported by the
  519.       ChartDataAppend function are:  BAR, PERSPECTIVE BAR, SCATTER, LINE,
  520.       SMOOTH LINE and a few others.
  521.                                  6
  522.  
  523.  
  524.  
  525.       The "ChartDataAppend" function can overlay previously displayed data
  526.       bars.  The developer must be aware of the painting characteristics of
  527.       the bar chart and the perspective bar chart to prevent an overlay
  528.       error.
  529.  
  530.       The bar chart is painted from the left to the right on the X-axis.
  531.       The ChartDataAppend function parameters must be:  data group 1/ point
  532.       1; followed by data group 2/ point 1; followed by data group 3/point
  533.       1; etc.; followed by data group 1/ point 2; followed by data group 2/
  534.       point 2; followed by data group 3/ point 2; etc.
  535.  
  536.       The perspective bar chart is painted from the back (highest group
  537.       number) to the front (data group 1) of the chart.  The data group
  538.       points are painted from the left to the right.  The ChartDataAppend
  539.       function parameters must be:  data group 8/ point 1; followed by data
  540.       group 7/ point 1; followed by data group 6/ point 1; etc,; followed
  541.       by data group 8/ point 2; followed by data group 7/ point 2; followed
  542.       by data group 6/ point 2; etc.
  543.  
  544.       Two group data points must be received for the line to be painted on
  545.       a line chart and smooth line chart.
  546.  
  547.  
  548.       Tactile Feedback / Hot Spot
  549.       ═══════════════════════════
  550.  
  551.       This section describes the tactile feedback function of the API
  552.       "ChartQueryPointer".  This API allows the developer to pass certain x
  553.       and y coordinates to the graphics DLL for "hot spot" resolution.  The
  554.       application program can respond with a course of action when a
  555.       coordinate receives a mouse click.
  556.  
  557.       The developer supplies the CH_TOUCH parameter flag to either the
  558.       "ChartCreate" or "ChartSetOptions" function calls.  The chart will
  559.       record the "hot spot" coordinates in dynamic memory until the chart
  560.       is either repainted, destroyed, or the flag option is removed.
  561.  
  562.  
  563.       Range Charts
  564.       ════════════
  565.  
  566.       The graphics engine also supports a category of "range charts".  Three
  567.       range sub-type charts, high/low, candlestick and point & figure 
  568.       charts are supported.  The high/low and candlestick charts can be 
  569.       represented in time based form. 
  570.  
  571.       Range charts are normally used for daily tracking of stocks, 
  572.       commodities, bonds and other financial instruments.  However, it 
  573.       should be noted that these charts have applicability to industries 
  574.       such as medical, for blood pressures, or manufacturing for average 
  575.       process or production ranges.
  576.  
  577.  
  578.  
  579.                                  7
  580.  
  581.  
  582.  
  583.       High/low charts can be drawn with or without open and close. 
  584.       Candlestick charts require that the developer supply four data 
  585.       entries (low,high, open and close) for each data display symbol. 
  586.       Point & figure charts require only one data entry for each data 
  587.       display symbol.
  588.  
  589.       Display and algorithmic details for the range family of charts are 
  590.       outside the scope of this toolkit.  The developer is advised to 
  591.       consult available technical sources to further understand these chart
  592.       sub-types.
  593.  
  594.  
  595.       Time Based Charts
  596.       ═════════════════
  597.  
  598.       Time based charts provide true calendar base information to the user
  599.       across the x-axis of a chart.  Data points occurring during a 
  600.       specified time span are displayed in the appropriate time locations 
  601.       of the chart.  Data points in relation to tick marks are not equally
  602.       spaced as with other charts.
  603.  
  604.       After issuing the "ChartData" API, the time values corresponding to
  605.       these data points must be provided by the developer.  The time based 
  606.       entries need not be in time sequence.  The charting engine will 
  607.       determine the correct orientation for each data point individually. 
  608.       Passing the point/data timing information to the charting engine is 
  609.       accomplished using the "ChartSetTimeReference" API.
  610.  
  611.       The x-axis text normally generates two line of text.  Time based 
  612.       charts need additional free space in the right and frequently in the 
  613.       footing area.  With the implementation of CH_TIME_BASED flag, the 
  614.       charting engine defaults to the region settings used for a 
  615.       perspective bar chart, even if the application program never displays
  616.       such a chart.  Take note that, if the x-axis text does not appear 
  617.       during the display of the graphic, the developer should insure that 
  618.       an adequate graphic area is available.  This is done by making the 
  619.       total charting area larger than normally used for other charts.
  620.  
  621.  
  622.       The time span is determined by either the charting engine or the 
  623.       developer.  The developer can control the earliest and latest times 
  624.       expressed on the x-axis using the "ChartSetTimeRange" API.  This API
  625.       instructs the charting engine to display only those data points which
  626.       fall within the specified time range.  If this API is not used, the 
  627.       system will use the earliest and latest time values provided in the 
  628.       "ChartSetTimeReference" API to determine the extent of the x-axis
  629.       information.
  630.  
  631.       Time based graphic charts support time ranges from 90 seconds to 
  632.       7,000 years.
  633.  
  634.  
  635.  
  636.  
  637.                                  8
  638.  
  639.  
  640.  
  641.       Clipboard, MetaFile and Printing
  642.       ════════════════════════════════
  643.  
  644.       Business graphics charts can be sent to the system clipboard with the
  645.       "ChartClipboard" API.  Charts can also be saved to disk with the
  646.       "ChartOutputMetaFile" API.  At a subsequent point in time, the
  647.       metafile can be replayed, printed, or included into a document
  648.       through metafile support.  The "ChartPrint" API supports printing.
  649.       This API defaults to the system default printer.
  650.    
  651.  
  652.  
  653.       Chart Fonts
  654.       ═══════════
  655.  
  656.       For the text displayed on a chart, the Helvetica font is used.  The 
  657.       font size is dependent on the total chart percentage for a specified 
  658.       area.  The scaling is automatic and requires no input from the 
  659.       developer.  These are fixed default settings.
  660.  
  661.       Special mention should be made regarding the footing area for text 
  662.       ticks and data legends.  The presentation in this area depends on 
  663.       such factors as: the percentage of chart specified for the footing, 
  664.       the number of data group legends and the text string length.
  665.  
  666.       As an example, assume a chart is created reflecting data generated 
  667.       for five week days (Monday through Friday).  Changing any one of the 
  668.       factors mentioned above could result in the following displays for 
  669.       the x-axis text ticks.
  670.  
  671.  
  672.                              M T W T F
  673.  
  674.                                  or
  675.  
  676.                          Mon Tue Wed Thu Fri
  677.  
  678.                                  or
  679.  
  680.                Monday Tuesday Wednesday Thursday Friday
  681.  
  682.  
  683.       The following example assumes a chart is created reflecting five data
  684.       groups with data and a legend assigned to each.  Changing any one of 
  685.       the factors mentioned above could result in the following displays 
  686.       for the data legend.
  687.  
  688.       Legend 1       Legend 2       Legend 3       Legend 4       Legend 5
  689.  
  690.                                        or
  691.  
  692.                Legend 1             Legend 2                Legend 3
  693.                Legend 4             Legend 5
  694.  
  695.                                  9
  696.  
  697.  
  698.  
  699.       Video displayed text uses the system provided Helvetica raster fonts. 
  700.       Printed text or text placed into a metafile use vectored Helvetica 
  701.       fonts.  The "ChartSetFont" API provides the programmer with the
  702.       ability to change either the raster or vector fonts.
  703.  
  704.  
  705.       ChartRegions Defaults and Philosophy
  706.       ════════════════════════════════════
  707.  
  708.       This section describes the default settings used during the 
  709.       "ChartCreate" function call and the calculation philosophy to change
  710.       those regions using the "ChartSetRegions" function call.  The five
  711.       sub-areas of a client area chart are as follows:
  712.  
  713.  
  714.               ┌────────────┬───────────────────────┬────────────┐
  715.               │            │                       │            │
  716.               │            │     HEADING AREA      │            │
  717.               │            │                       │            │
  718.               ├────────────┼───────────────────────┼────────────┤
  719.               │            │                       │            │
  720.               │            │                       │            │
  721.               │   LEFT     │                       │   RIGHT    │
  722.               │  MARGIN    │     GRAPHIC AREA      │   MARGIN   │
  723.               │            │                       │            │
  724.               │            │                       │            │
  725.               │            │                       │            │
  726.               ├────────────┼───────────────────────┼────────────┤
  727.               │            │                       │            │
  728.               │            │    FOOTING AREA       │            │
  729.               │            │                       │            │
  730.               └────────────┴───────────────────────┴────────────┘
  731.  
  732.  
  733.       The heading, graphic and footing areas will be the initial focus of 
  734.       this section.  The left and right margins will be addressed later.
  735.  
  736.       The parameters of a chart are percentages of the total chart, not 
  737.       pixels or inches.  With the "ChartCreate" function call, these
  738.       parameters will generally default of heading=13%, graphic=67%, and
  739.       footing=20%.  For aesthetic balance and presentation style, the 
  740.       sub-area parameters can be changes with the "ChartSetRegions" 
  741.       function call.
  742.  
  743.       The percentages passed to the "ChartSetRegions" function are
  744.       validated for general reasonableness.  Sometimes, "ChartSetRegions"
  745.       may initiate a default setting.  It is not necessary, though
  746.       advisable to specify the parameters for all three sub-areas.  The
  747.       calculations for the unspecified sub-areas will be made by the
  748.       charting engine.  The "ChartSetRegions" function provides artificial
  749.       intelligence for minor miscalculations if the three specified
  750.       parameters total more or less than 100%.
  751.  
  752.  
  753.                                  10
  754.  
  755.  
  756.       The following chart shows the effect speechified parameters will have 
  757.       on the chart results. X, Y, and Z represent the specified parameters:
  758.  
  759.       ┌──────────────────────────────────────┐ ┌─────────────────────────────┐
  760.       │              AREA INPUT %            │ │       AREA RESULT %         │
  761.       ├────────┬─────────┬─────────┬─────────┤ ├─────────┬─────────┬─────────┤
  762.       │   if   │ GRAPHIC │ HEADING │ FOOTING │ │ GRAPHIC │ HEADING │ FOOTING │
  763.       ├────────┼─────────┼─────────┼─────────┤ ├─────────┼─────────┼─────────┤
  764.       │        │  X      │  NULL   │  NULL   │ │   90    │   5     │   5     │
  765.       │        │  NULL   │  X      │  NULL   │ │ 100-X-5 │   X     │   5     │
  766.       │        │  NULL   │  X>70   │  NULL   │ │   25    │   70    │   5     │
  767.       │        │  NULL   │  NULL   │  X      │ │ 100-X-5 │   5     │   X     │
  768.       │        │  NULL   │  NULL   │  X>70   │ │   25    │   5     │   70    │
  769.       │        │  X      │  NULL   │  Y      │ │   X-5   │   5     │   Y     │
  770.       │        │  X      │  Y      │  NULL   │ │   X-5   │   Y     │   5     │
  771.       │        │  X      │  Y      │  Z      │ │   X     │   Y     │   Z     │
  772.       │(X+Y)<70│  NULL   │  X      │  Y      │ │ 100-X-Y │   X     │   Y     │
  773.       │(X+Y)>70│  NULL   │  X      │  Y      │ │   67    │   13    │   20    │
  774.       └────────┴─────────┴─────────┴─────────┘ └─────────┴─────────┴─────────┘
  775.  
  776.       While the above may appear to be complex, the actual implementation 
  777.       is as easy as 1, 2, 3.
  778.  
  779.  
  780.       Left and Right Margins
  781.       ══════════════════════
  782.  
  783.       The amount of space allocated to the left and right margin depends on
  784.       the type of chart specified during the "ChartCreate" function call.
  785.       In a pie chart display, both the left and right margins default to 8
  786.       percent of the total chart width.  The perspective bar and the
  787.       bar/line charts default to 20 percent for both the left and right
  788.       margins.  Area chart margins default to 20 percent for the left
  789.       margin and 10 percent for the right.  The defaults for all other
  790.       chart types are left, 20 percent, and right, 5 percent.  The width of
  791.       the graphic area changes in relationship to the amount of space
  792.       allocated, by the developer, to the left and right margins.
  793.  
  794.  
  795.       Information Messages
  796.       ════════════════════
  797.  
  798.       Developer information messages, specifying invalid parameters passed
  799.       to APIs, is provided in the full product.  A system modal dialog box
  800.       is presented by the graphics DLL when an API encounters an error.
  801.       The dialog box identifies the API name and indicates the parameter in
  802.       error.    THIS FEATURE IS ONLY AVAILABLE WITH THE FULL FUNCTION
  803.       PRODUCT.  ─────────────────────────────────────────────────────
  804.       ───────
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.                                  11
  812.  
  813.  
  814.  
  815.       Assumptions about the developer
  816.       ═══════════════════════════════
  817.       
  818.       This toolkit assumes the developer has minimal C programming
  819.       experience and understands programming concepts.  The programmer
  820.       should have experienced creating a window and processing its
  821.       associated messages.  An experienced programmer can make the API
  822.       bridges to utilize this toolkit with languages other than C.
  823.  
  824.       OS/2 and Presentation Manager are registered trademarks of
  825.       International Business Machines Corporation.  They are cited here
  826.       solely for the purpose of identification.
  827.  
  828.       Windows 3.0 is a registered trademark of Microsoft Corporation.  It
  829.       is cited here solely for the purpose of identification.
  830.  
  831.       Language Support
  832.       ════════════════
  833.  
  834.       The toolkit supports many popular programming languages such as C,
  835.       C++, PASCAL, COBOL and many others.
  836.  
  837.  
  838.       Application Programming Interface
  839.       ═════════════════════════════════
  840.       The Developer's Business Graphics Toolkit consists of approximately
  841.       80 API function calls.  The application programmer typically will use
  842.       only six or seven to produce a graphic chart presentation.  The
  843.       remaining function calls are used to perform more exotic tasks.  The
  844.       APIs use C programming notation.  No messages are sent for the
  845.       application programmer to process.  The six API function calls used 
  846.       as a foundation for a business chart are as follows:
  847.  
  848.          ChartCreate          Establishes a chart "object"
  849.          ChartData            Provides the chart with data
  850.          ChartSetXTicks       Sets the chart time span
  851.          ChartTexts           Provides textual headings and margins
  852.          ChartPaint           Shows the chart to the user
  853.          ChartSetRect         Supports user window reseizing
  854.  
  855.  
  856.  
  857.  
  858.  
  859.       The following code segments illustrates how to create and display a
  860.       basic 3 dimension bar chart.
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.                                  12
  870.  
  871.  
  872.  
  873.   APPLICATION INITIALIZATION FOR PRESENTATION MANAGER
  874.   ═══════════════════════════════════════════════════
  875.  
  876.   Creating your main program window should follow normal Presentation
  877.   Manager conventions, such as identifying any window procedures.
  878.  
  879.   #define CHART_OS2_32
  880.   #include <CHART.H>                     /* Business graphics identifiers */
  881.  
  882.       MRESULT EXPENTRY MyWindowProc(HWND ,ULONG ,MPARAM ,MPARAM );
  883.  
  884.   Start your main program procedure, identify any required static program
  885.   area, and perform the normal Presentation Manager housekeeping chores.
  886.  
  887.  
  888.       static HAB   hab;                      // PM anchor block handle
  889.       static HWND  hwndFrame;                // Frame window handle
  890.       static HWND  hwndClient;               // Client area window handle
  891.  
  892.       int  main(void)
  893.       {
  894.          HMQ           hmq;                  // Message queue handle                
  895.          QMSG          qmsg;                 // Message from message queue          
  896.          ULONG         flCreate;             // Window creation control flags       
  897.          HWND          hwndGraphClient;      // Client area window handle           
  898.  
  899.  
  900.          hab = WinInitialize(0L);            // Initialize PM                       
  901.          hmq = WinCreateMsgQueue(hab, 0);    // Create a message queue              
  902.          WinRegisterClass(                   // Register window class               
  903.             hab,                             // Anchor block handle                 
  904.             "PrWindow",                      // Window class name                   
  905.             (PFNWP)MyWindowProc,             // Address of window procedure         
  906.             CS_SIZEREDRAW,                   // Class Style                         
  907.             0                                // No extra window words               
  908.             );
  909.       
  910.          flCreate = FCF_TITLEBAR|FCF_MENU|FCF_SIZEBORDER|FCF_MINMAX|FCF_SYSMENU|
  911.             FCF_TASKLIST|FCF_ICON|FCF_SHELLPOSITION|FCF_ACCELTABLE;
  912.       
  913.          hwndFrame = WinCreateStdWindow(HWND_DESKTOP, // Desktop window is parent 
  914.             WS_VISIBLE,                      // No frame styles                     
  915.             (PULONG)&flCreate,               // Frame control flag                  
  916.             "PrWindow",                      // Client window class name            
  917.             "",                              // No window text                      
  918.             0L,                              // No special class style              
  919.             0L,                              // Resource is in .EXE file            
  920.             ID_WINDOW,                       // Frame window identifier             
  921.             (PHWND)&hwndClient               // Client window handle                
  922.             );
  923.       
  924.       
  925.                                  13
  926.  
  927.    APPLICATION TERMINATION FOR PRESENTATION MANAGER
  928.    ════════════════════════════════════════════════
  929.  
  930.    The developer should perform the normal Presentation Manager message
  931.    queue processing and termination activities.
  932.  
  933.  
  934.          while (WinGetMsg(hab, (PQMSG)&qmsg, (HWND)NULL, 0, 0))
  935.             WinDispatchMsg(hab, (PQMSG)&qmsg);
  936.          WinDestroyWindow(hwndFrame);        // Tidy up...
  937.          WinDestroyMsgQueue(hmq);            // and
  938.          WinTerminate(hab);                  // terminate the application      
  939.       }
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.                                  14
  984.  
  985.  
  986.  
  987.   APPLICATION CHART CREATION
  988.   ══════════════════════════
  989.  
  990.    The next section of the application program processes the Presentation
  991.    Manager messages from the message queue.  The beginning of the window
  992.    procedure identifies any procedure variables and starts the initial message
  993.    processing.  The first window command to be addressed is the WM_CREATE
  994.    message.  Five steps are required for the processing of a create message:
  995.    obtaining the size of the client area, creating the business graphic chart
  996.    type (i.e. standard bar chart), specifying the x-axis data point text
  997.    identifiers, priming the bar chart with data, and providing a chart
  998.    heading/title text string and left/right margin text string.  Any of these
  999.    functions could be accomplished at other points in time in a typical
  1000.    application.
  1001.  
  1002.       MRESULT EXPENTRY MyWindowProc(HWND hwnd,ULONG msg,MPARAM mp1,MPARAM mp2)
  1003.  
  1004.       {
  1005.  
  1006.       HPS    hps;                            // Presentation Space handle
  1007.       USHORT command;                        // WM_COMMAND value for switch(?)
  1008.       RECTL ClientRctl;                      // Size of client window
  1009.       static HWND  hChart;                   // Chart window handle
  1010.       static USHORT errors                   // Business graphics errors
  1011.       static USHORT data1[] = {250, 900, 600};// Data group 1 points
  1012.       static USHORT data2[] = {500, 700, 458};// Data group 2 points
  1013.  
  1014.       switch (msg) {
  1015.           case WM_CREATE :
  1016.  
  1017.              //   Get the size of the client window (PM will return 0's
  1018.  
  1019.              WinQueryWindowRect(hwnd, &ClientRctl);
  1020.  
  1021.              //   Create the bar chart instance
  1022.  
  1023.              hchart = ChartCreate(hwnd,CH_BAR,CH_GRAPHIC_FRAME | CH_Y_GRID,
  1024.                    &ClientRctl,&errors,CH_DATA_USHORT,2,3,3);
  1025.  
  1026.              //   Set x-axis time text information
  1027.  
  1028.              ChartSetXticks(hChart,CH_WIDTH,CH_MONTHS, 6); //June start month
  1029.  
  1030.              //   Load the chart with some data
  1031.  
  1032.              ChartData(hChart,1,&data1,3,NULL,CH_DATA_USHORT,"Small parts");
  1033.              ChartData(hChart,2,&data2,3,NULL,CH_DATA_USHORT,"Large parts");
  1034.  
  1035.              //   Provide chart title and left margin text
  1036.  
  1037.              ChartTexts(hChart,"Widget Sales Department",NULL,"Quantity",NULL);
  1038.           break;
  1039.  
  1040.  
  1041.  
  1042.                                  15
  1043.  
  1044.  
  1045.  
  1046.   APPLICATION CHART PAINTING
  1047.   ══════════════════════════
  1048.  
  1049.   The next section of the application program is responsible for painting the
  1050.   chart on the user's display.  The four steps involved in this process follow.
  1051.   The processing of the WM_PAINT message includes validation of the client
  1052.   window via WinBeginPaint and WinEndPaint.  Second, the current client window
  1053.   location is queried, in the event of user resizing and initialization.  Then
  1054.   the new chart display coordinates, inside the client window, are passed to
  1055.   the chart instance.  Lastly, the chart is made visible to the enduser.  While
  1056.   the parameters of each Chart...  function calls are not discussed at this
  1057.   time, the purpose of this application sample is to show detailed business
  1058.   chart programming concepts and requirements.  Individual business chart
  1059.   function calls are provided in the next section of this documentation.
  1060.  
  1061.       case WM_PAINT :
  1062.  
  1063.              //  Revalidate and paint any portion of the developer's
  1064.                  application data
  1065.  
  1066.              hps = WinBeginPaint(hwnd, NULL, NULL);
  1067.  
  1068.                 //   Obtain current client window coordinates
  1069.    
  1070.                 WinQueryWindowRect(hwnd, &ClientRctl);
  1071.    
  1072.                 //   Notify chart instance of new chart display location
  1073.    
  1074.                 ChartSetRect(hChart, &ClientRctl);
  1075.    
  1076.                 //   Make the chart visible to the user
  1077.    
  1078.                 ChartPaint(hChart,hps);
  1079.              
  1080.              WinEndPaint(hps);
  1081.  
  1082.  
  1083.              break;                          //  End of WM_PAINT processing
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.                                  16
  1101.  
  1102.  
  1103.  
  1104.   APPLICATION CHART TERMINATION
  1105.   ═════════════════════════════
  1106.  
  1107.   The WM_COMMAND and WM_CLOSE are the last two commands required for this
  1108.   sample program.  The application program termination is assumed to be a
  1109.   result of the user pressing the F3 function key to terminate the application.
  1110.   As a result of this action, the application will post an internal message to
  1111.   dispose of the business chart instance and to terminate the application.
  1112.   Releasing the chart instance is not necessary, but good programming practice.
  1113.  
  1114.           case WM_COMMAND :                     // Process operator keys
  1115.              command = SHORT1FROM(mp1);
  1116.  
  1117.              switch (command) {
  1118.                  case IDM_EXIT :                // F3 key processing
  1119.                    WinPostMsg(hwnd, WM_CLOSE, 0L, 0L);
  1120.              break;
  1121.           default;
  1122.              return WinDefWindowProc(hwnd, msg, mp1, mp2);
  1123.       }                                         // End switch (mp1)
  1124.       break;                                    // End of WM_COMMAND processing
  1125.  
  1126.       case WM_CLOSE :
  1127.  
  1128.              //   Dispose of the chart instance
  1129.  
  1130.              ChartDestroy(hChart);
  1131.  
  1132.              WinPostMsg(hwnd, WM_QUIT, 0L, 0L);
  1133.              break;
  1134.  
  1135.       default :
  1136.              return WinDefWindowProd(hwnd, msg, mp1, mp2);
  1137.          }
  1138.              return FALSE;
  1139.       }                                           // End of MyWindowProc
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.                                  17
  1159.  
  1160.  
  1161.  
  1162.                          API TECHNICAL SYNOPSIS
  1163.  
  1164.  
  1165.  
  1166.   ChartAnnotate - Display application text string
  1167.   ═══════════════════════════════════════════════
  1168.  
  1169.   This interface enables the programmer to place text any where on top of the
  1170.   chart after the chart has been displayed.  The program can determine where
  1171.   the data is to be displayed through the use of the "ChartQueryLocation" API
  1172.   (i.e..  locate a horizontal bar on a chart).  Next, determine what size font
  1173.   will fit in the rectangle based on the text provided through the use of the
  1174.   "ChartQueryTextFontSizes" API.
  1175.  
  1176.   ┌───────────────────────────────────────────────────────────────────────────┐
  1177.   │                                                                           │
  1178.   │   hann = ChartAnnotate(hchart,        // Chart handle                     │
  1179.   │                        font,          // Font size 1 thru 5               │
  1180.   │                        rect,          // Pointer to output rectangle      │
  1181.   │                        color,         // CLR_??? value                    │
  1182.   │                        options,       // Centering options                │
  1183.   │                        string);       // Pointer to a text string         │
  1184.   │                                                                           │
  1185.   └───────────────────────────────────────────────────────────────────────────┘
  1186.  
  1187.   The "ChartAnnotate" function parameters are as follows:
  1188.  
  1189.   hann         This API will return a handle to the annotation upon successful
  1190.   (HWND)       completion as the annotation is maintained in an internal pool
  1191.                for the chart.  The programmer may specify as many annotations 
  1192.                as required by their application.  Individual annotations can be
  1193.                eliminated from the pool through the use of the
  1194.                "ChartAnnotateRelease" API discussed later.
  1195.  
  1196.   hchart       Specifies the handle returned by the "ChartCreate" function.
  1197.   (HWND)
  1198.  
  1199.   font         Specifies the size of the font to use in displaying the text
  1200.   (USHORT)     string on the chart. The font size must range between 1 and 5.
  1201.                A value of 1 represents the smallest font size.
  1202.  
  1203.   rect         Specifies a pointer to rectangle structure which contains the
  1204.   (PRECT)      rectangular location of where to place the text string on
  1205.                the chart.
  1206.  
  1207.   color        Specifies a CLR_??? color value to be used in displaying
  1208.   (LONG)       the text string.  (See the "ChartSetColor" API for a full list
  1209.                of the CLR_ values.)
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.                                  18
  1217.  
  1218.  
  1219.  
  1220.   options      Specifies how the text is to be placed within the rectangle
  1221.   (ULONG)      provided by the programmer. Use one of the following valid
  1222.                options.
  1223.  
  1224.                    CH_RIGHT_JUSTIFY
  1225.                    CH_LEFT_JUSTIFY
  1226.                    CH_CENTER_JUSTIFY
  1227.  
  1228.                For vertical text you must specify CH_VERTICAL_ANNOTATE.  To
  1229.                direct text to start at the bottom on the rectangle and proceed
  1230.                upward, specify also the CH_BOTTOM_JUSTIFY parameter which must
  1231.                be or-ed with CH_VERTICAL_ANNOTATE.
  1232.  
  1233.   string    Specifies a pointer to the text string to be displayed.
  1234.   (PCH)
  1235.  
  1236.  
  1237.   NOTE: As the window is resized by the user or application and the chart is
  1238.   redrawn, it is the programmers responsibility to release all previously
  1239.   defined annotations and recalculate the new output area size and call the
  1240.   "ChartAnnotate" function again.  All annotations can be release through the
  1241.   "ChartAnnotateDestroy" API discussed later.
  1242.  
  1243.   NOTE:  Any annotations which are encountered during the "ChartDestroy"
  1244.   function call will automatically be released by the charting toolkit.
  1245.  
  1246.   NOTE: The "ChartPrint" function will automatically recalculate the annotation
  1247.   locations prior to the chart being printed.
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.  
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.                                  19
  1275.  
  1276.  
  1277.   ChartAnnotatePaint - Display all annotations on the chart
  1278.   ═════════════════════════════════════════════════════════
  1279.  
  1280.   This function will paint all annotations currently held by the chart on
  1281.   the display or the printer.
  1282.  
  1283.   ┌───────────────────────────────────────────────────────────────────────────┐
  1284.   │                                                                           │
  1285.   │   ans =  ChartAnnotatePaint(hchart,       // Chart handle                 │
  1286.   │                             hps);         // Handle to presentation space │
  1287.   │                                                                           │
  1288.   └───────────────────────────────────────────────────────────────────────────┘
  1289.  
  1290.   The "ChartAnnotatePaint" function parameters are as follows:
  1291.  
  1292.   ans          Provides TRUE for a successful request or FALSE for an
  1293.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  1294.                the "error" code location specified in the "ChartCreate"
  1295.                function.
  1296.  
  1297.   hchart       Specifies the handle returned by the "ChartCreate" function.
  1298.   (HWND)
  1299.  
  1300.   hps          Specifies the handle of presentation space for the output 
  1301.   (HPS)        device being used.
  1302.  
  1303.  
  1304.   ┌───────────────────────────────────────────────────────────────────────────┐
  1305.   │                                                                           │
  1306.   │  Error codes     NONE                                                     │
  1307.   │                                                                           │
  1308.   └───────────────────────────────────────────────────────────────────────────┘
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.                                  20
  1333.  
  1334.  
  1335.  
  1336.   ChartAnnotateRelease - Release a specific annotation
  1337.   ════════════════════════════════════════════════════
  1338.  
  1339.   This function releases individual annotations for a chart based on the
  1340.   annotation handle provided.
  1341.  
  1342.   ┌───────────────────────────────────────────────────────────────────────────┐
  1343.   │                                                                           │
  1344.   │   ans =  ChartAnnotateRelease(hchart,     // Chart handle                 │
  1345.   │                               hann);      // Annotation to release        │
  1346.   │                                                                           │
  1347.   └───────────────────────────────────────────────────────────────────────────┘
  1348.  
  1349.   The "ChartAnnotateRelease" function parameters are as follows:
  1350.  
  1351.   ans          Provides TRUE for a successful request or FALSE for an
  1352.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  1353.                the "error" code location specified in the "ChartCreate"
  1354.                function.
  1355.  
  1356.   hchart       Specifies the handle returned by the "ChartCreate" function.
  1357.   (HWND)
  1358.  
  1359.   hann         Specifies the handle of an annotation element as created by the 
  1360.   (HWND)       "ChartAnnotate" function call.
  1361.  
  1362.  
  1363.   ┌───────────────────────────────────────────────────────────────────────────┐
  1364.   │                                                                           │
  1365.   │  Error codes     Chart_no_memory            3                             │
  1366.   │                  Chart_invalid_parameter    5                             │
  1367.   │                                                                           │
  1368.   └───────────────────────────────────────────────────────────────────────────┘
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.                                  21
  1391.  
  1392.  
  1393.  
  1394.   ChartAnnotateDestroy - Release all annotations
  1395.   ══════════════════════════════════════════════
  1396.  
  1397.   This function releases all current annotations for a chart.  In the event no
  1398.   annotations are currently defined, this interface will also return a TRUE
  1399.   indication.
  1400.  
  1401.  
  1402.   ┌───────────────────────────────────────────────────────────────────────────┐
  1403.   │                                                                           │
  1404.   │   ans =  ChartAnnotateDestroy(hchart);    // Chart handle                 │
  1405.   │                                                                           │
  1406.   └───────────────────────────────────────────────────────────────────────────┘
  1407.  
  1408.   The "ChartAnnotateDestroy" function parameters are as follows:
  1409.  
  1410.   ans          Provides TRUE for a successful request or FALSE for an
  1411.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  1412.                the "error" code location specified in the "ChartCreate"
  1413.                function.
  1414.  
  1415.   hchart       Specifies the handle returned by the "ChartCreate" function.
  1416.   (HWND)
  1417.  
  1418.  
  1419.   ┌───────────────────────────────────────────────────────────────────────────┐
  1420.   │                                                                           │
  1421.   │  Error codes     Chart_no_memory            3                             │
  1422.   │                                                                           │
  1423.   └───────────────────────────────────────────────────────────────────────────┘
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.                                  22
  1449.  
  1450.  
  1451.  
  1452.   ChartClipboard - Paste the current chart on clipboard
  1453.   ═════════════════════════════════════════════════════
  1454.  
  1455.   This function provides a means to paste the current chart as shown on the
  1456.   display to the system clipboard.  This function will replace anything
  1457.   currently being held by the clipboard.
  1458.  
  1459.  
  1460.   ┌───────────────────────────────────────────────────────────────────────────┐
  1461.   │                                                                           │
  1462.   │   ans =  ChartClipboard(hchart);          // Chart handle                 │
  1463.   │                                                                           │
  1464.   └───────────────────────────────────────────────────────────────────────────┘
  1465.  
  1466.   The "ChartClipboard" function parameters are as follows:
  1467.  
  1468.   ans          Provides TRUE for a successful request or FALSE for an
  1469.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  1470.                the "error" code location specified in the "ChartCreate"
  1471.                function.
  1472.  
  1473.   hchart       Specifies the handle returned by the "ChartCreate" function.
  1474.   (HWND)
  1475.  
  1476.  
  1477.   ┌───────────────────────────────────────────────────────────────────────────┐
  1478.   │                                                                           │
  1479.   │  Error codes     Chart_no_memory            3                             │
  1480.   │                  Chart_clipboard_not_open  38                             │
  1481.   │                                                                           │
  1482.   └───────────────────────────────────────────────────────────────────────────┘
  1483.  
  1484.  
  1485.   The following is an example of the call to this function.
  1486.  
  1487.  
  1488.   ┌───────────────────────────────────────────────────────────────────────────┐
  1489.   │                                                                           │
  1490.   │  static HWND     hChart;                 // Bar chart handle              │
  1491.   │                                                                           │
  1492.   │  if (!ChartClipboard(hChart)) {                                           │
  1493.   │          //                                                               │
  1494.   │          //      Error condition                                          │
  1495.   │          //                                                               │
  1496.   │  } else {                                                                 │
  1497.   │          //                                                               │
  1498.   │          //      Success                                                  │
  1499.   │          //                                                               │
  1500.   │  }                                                                        │
  1501.   │                                                                           │
  1502.   │                                                                           │
  1503.   └───────────────────────────────────────────────────────────────────────────┘
  1504.  
  1505.  
  1506.                                  23
  1507.  
  1508.  
  1509.  
  1510.   ChartCreate - Create a graphic chart
  1511.   ════════════════════════════════════
  1512.  
  1513.   "ChartCreate" will establish/create a "chart object".  To be displayed, the
  1514.   chart requires a window or part of a window. The handle of a window (i.e.
  1515.   client or dialog box control) must be passed to the "ChartCreate" function.
  1516.   Other parameters describe the general characteristics of the chart.  The
  1517.   ChartCreate function will return a handle for the chart created.  This
  1518.   handle will be passed to all chart functions that follow.
  1519.  
  1520.   NOTE: The creation process does not display the chart to the user.  The
  1521.   chart has no data associated at this point.  Once data is provided by the
  1522.   "ChartData" function, the chart can be made visible with either a
  1523.   "ChartVisible" or "ChartPaint" function request.
  1524.  
  1525.   ┌───────────────────────────────────────────────────────────────────────────┐
  1526.   │                                                                           │
  1527.   │   hchart =  ChartCreate(hwnd,         // Client window handle             │
  1528.   │                         chart_type,   // Type of chart requested          │
  1529.   │                         chart_flags,  // Chart control flags              │
  1530.   │                         &rectl,       // Rectangle position in client     │
  1531.   │                         &errors,      // Error recording location         │
  1532.   │                         data_type,    // Type of data                     │
  1533.   │                         groups,       // Number of data group sets        │
  1534.   │                         points,       // Number of data points            │
  1535.   │                         dimensions);  // Number of dimensions (2 or 3)    │
  1536.   │                                                                           │
  1537.   └───────────────────────────────────────────────────────────────────────────┘
  1538.  
  1539.   The "ChartCreate" function parameters are as follows:
  1540.  
  1541.   hchart       Contains the handle returned by "ChartCreate".  If an error
  1542.   (HWND)       occurs during the creation process, "hchart" is set to a zero
  1543.                value.  ERRORS will be set to a reason code.
  1544.  
  1545.   hwnd         Contains the handle of the client window in which the chart will 
  1546.   (HWND)       be displayed.
  1547.  
  1548.   chart_type   Describes the type of chart to be created.  The values
  1549.   (CHTYPE)     are described on page two of this document.  For
  1550.                example CH_BAR.  These values were described earlier in the 
  1551.                documentation on page 2.
  1552.  
  1553.   chart_flags  Describes additional controls placed on the chart being
  1554.   (ULONG)      created.  The following values can be or-ed together to
  1555.                provide combinations for the chart.
  1556.  
  1557.                CH_CONNECTED      Connects the points on a scatter chart
  1558.                                  with straight lines.  This parameter is not
  1559.                                  applicable to any other chart type.
  1560.  
  1561.  
  1562.  
  1563.  
  1564.                                  24
  1565.  
  1566.  
  1567.  
  1568.                CH_FLOAT_SCALE    Sets the y-axis and z-axis at the lowest data
  1569.                                  point value overriding the default value 0.
  1570.                                  The lowest data point value will be rounded
  1571.                                  down to insure readability.
  1572.  
  1573.                CH_FRAME          Places a visual frame around the entire chart
  1574.                                  area as described by "rectl" parameter.
  1575.  
  1576.                CH_GRAPHIC_FRAME  Places a visual frame around the graphic
  1577.                                  picture created.
  1578.  
  1579.                CH_MARKER         Places marker symbols on line and bar/line
  1580.                                  charts.  This parameter is not applicable to 
  1581.                                  any other chart type.  The marker symbol 
  1582.                                  defaults to the solid diamond shape,
  1583.                                  MARKSYM_SOLIDDIAMOND.
  1584.  
  1585.                CH_MINOR_GRID     Places a vertical grid line in the graphic
  1586.                                  chart area for minor x-ticks.  Applicable to
  1587.                                  time-based charts only.
  1588.  
  1589.                CH_NO_ZEROES      Specifies that a data value of zero will not
  1590.                                  be displayed.
  1591.  
  1592.                CH_SORT           Sort column or stacked bar charts based on
  1593.                                  magnitude.
  1594.  
  1595.                CH_TIME_BASED     Displays a chart in a time-based manner.  
  1596.                                  Each data point must be accompanied by a
  1597.                                  time value.
  1598.  
  1599.                CH_TOUCH          Record data point location to implement
  1600.                                  tactile feedback.  See "ChartQueryLocation"
  1601.                                  and "ChartQueryPointer" function requests.
  1602.  
  1603.                CH_X_GRID         Places vertical grid lines in the graphic
  1604.                                  chart area.  This parameter is not applicable
  1605.                                  to pie charts.
  1606.  
  1607.                CH_Y_GRID         Places horizontal grid lines in the graphic
  1608.                                  chart area.  This parameter is not applicable
  1609.                                  to pie charts.
  1610.  
  1611.                CH_Z_GRID         Places horizontal grid lines in the graphic
  1612.                                  chart area.  This parameter is not applicable
  1613.                                  to pie charts.
  1614.  
  1615.   rectl        Provides the pointer to a structure containing the bottom left
  1616.   (PRECTL)     and upper right coordinates within "hwnd".  This is the chart 
  1617.                location when it is visible.
  1618.  
  1619.   errors       Provides the pointer to a location in memory for any error 
  1620.   (PUSHORT)    condition codes resulting from "Chart..." function calls.
  1621.                THIS MEMORY LOCATION MUST BE SET ASIDE IN STATIC DATA STORAGE.
  1622.                                  25
  1623.  
  1624.  
  1625.  
  1626.   data_type    Describes the format of the values displayed along the y-axis.
  1627.   (USHORT)
  1628.  
  1629.                            Range of data supported
  1630.                            ───────────────────────
  1631.  
  1632.                CH_DATA_USHORT                0 to 65,536
  1633.                CH_DATA_SHORT           -32,768 to 32,768
  1634.                CH_DATA_ULONG                 0 to 4,294,967,296
  1635.                CH_DATA_LONG     -2,147,483,648 to 2,147,483,648
  1636.                CH_DATA_FLOAT             10-36 to 10+36
  1637.                CH_DATA_DOUBLE           10-308 TO 10+308
  1638.  
  1639.   groups       Specifies the number of data groups to be displayed.  This
  1640.   (USHORT)     must range between 1 and 12.  EXCEPTIONS: Numeric and Symbol
  1641.                tables.
  1642.  
  1643.   points       Specifies the maximum number of graphic symbols associated with
  1644.   (USHORT)     any one data group.  A graphic symbol may consist of one data
  1645.                point (i.e. bar in a bar chart) or multiple data points (i.e.
  1646.                high/low/open/close in a range chart).
  1647.  
  1648.   dimensions   Indicates the viewing dimensions of the graphic chart.  The 
  1649.   (USHORT)     must be either 2 or 3.  A NULL or zero value will default to 3
  1650.                (representing a 3D chart).  Smooth line and scatter charts will
  1651.                default to 2 dimensions.
  1652.  
  1653.   ┌───────────────────────────────────────────────────────────────────────────┐
  1654.   │                                                                           │
  1655.   │  Error codes     Chart_invalid_client       1                             │
  1656.   │                  Chart_no_memory            3                             │
  1657.   │                  Chart_invalid_data_type    7                             │
  1658.   │                  Chart_invalid_group        8                             │
  1659.   │                  Chart_no_data              9                             │
  1660.   │                  Chart_invalid_dimensions  10                             │
  1661.   │                  Chart_invalid_chart_type  15                             │
  1662.   │                  Chart_invalid_DLL         18                             │
  1663.   │                                                                           │
  1664.   └───────────────────────────────────────────────────────────────────────────┘
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.  
  1677.  
  1678.  
  1679.  
  1680.                                  26
  1681.  
  1682.  
  1683.  
  1684.   The following illustrates creating a standard 3-D bar chart with horizontal
  1685.   grid lines and a frame surrounding the entire chart area.  This sample
  1686.   assumes a small window is provided for placing a standard window frame around
  1687.   the chart.
  1688.  
  1689.  
  1690.   ┌───────────────────────────────────────────────────────────────────────────┐
  1691.   │                                                                           │
  1692.   │  static HWND     hWnd;                   // Client window handle          │
  1693.   │                                                                           │
  1694.   │  static HWND     hChart;                 // Bar chart handle              │
  1695.   │  static RECTL    Clientrctl;             // Area bar chart will occupy    │
  1696.   │                                                                           │
  1697.   │  static USHORT   usErrors;               // Error recording area          │
  1698.   │                                                                           │
  1699.   │  hChart = ChartCreate(hWnd,              // Client window handle          │
  1700.   │                       CH_BAR,            // Create a bar chart            │
  1701.   │                       CH_FRAME|          // Frame the entire chart        │
  1702.   │                       CH_Y_GRID,         // Horizontal grid lines         │
  1703.   │                       &Clientrctl,       // Client rectangle area         │
  1704.   │                       &usErrors,         // Error recording location      │
  1705.   │                       CH_DATA_SHORT,     // Unsigned short chart data     │
  1706.   │                       1,                 // Number of data groups         │
  1707.   │                       5,                 // Number of data points         │
  1708.   │                       3);                // 3-D chart presentation        │
  1709.   │                                                                           │
  1710.   └───────────────────────────────────────────────────────────────────────────┘
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738.                                  27
  1739.  
  1740.  
  1741.  
  1742.   ChartData - Provide a group with data and text legend
  1743.   ═════════════════════════════════════════════════════
  1744.  
  1745.   This function provides a chart group with data and a legend.
  1746.  
  1747.   ┌───────────────────────────────────────────────────────────────────────────┐
  1748.   │                                                                           │
  1749.   │   ans = ChartData(hchart,           // Chart handle                       │
  1750.   │                   group,            // Data group number                  │
  1751.   │                   &data,            // Location of data array             │
  1752.   │                   points,           // Number of data items to chart      │
  1753.   │                   delay_start,      // Delay data starting point          │
  1754.   │                   data_type,        // Type of data to chart              │
  1755.   │                   &legend);         // Legend for the group               │
  1756.   │                                                                           │
  1757.   └───────────────────────────────────────────────────────────────────────────┘
  1758.  
  1759.   The "ChartData" function parameters are as follows:
  1760.  
  1761.   ans          Provides TRUE for a successful request or FALSE for an
  1762.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  1763.                the "error" code location specified in the "ChartCreate"
  1764.                function.
  1765.  
  1766.   hchart       Specifies the handle returned by the "ChartCreate" function.
  1767.   (HWND)
  1768.  
  1769.   group        Specifies the number of the data group that will be displayed.
  1770.   (USHORT)     This number must range between 1 and 12.
  1771.  
  1772.   data         Pointer to an array of data points associated with the group.
  1773.   (PUSHORT)    This parameter should be "cast" to bypass compile warnings.
  1774.  
  1775.   points       Specifies the number of data points (or array elements)
  1776.   (USHORT)     associated with the data group being loaded.  All previously
  1777.                loaded data for the group will be nullified.  The value of zero
  1778.                will release any previously stored data points.
  1779.  
  1780.   delay_start  Delays the starting point for a data group.  For example, data
  1781.   (USHORT)     groups 1 and 3 have five data points each (Mon-Fri).  Data
  1782.                group 2 has three data points (Wed-Fri).  The value of 3
  1783.                specifies the starting point (Wed) for data group 3.
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.                                  28
  1797.  
  1798.  
  1799.  
  1800.   data_type    Describes the type of data associated with this data group
  1801.   (USHORT)     (i.e. long, float).  The type of data being provided in the
  1802.                application data array is specified by one of the following
  1803.                parameters.
  1804.  
  1805.                            Range of data supported
  1806.                            ───────────────────────
  1807.  
  1808.                CH_DATA_USHORT                0 to 65,536
  1809.                CH_DATA_SHORT           -32,768 to 32,768
  1810.                CH_DATA_ULONG                 0 to 4,294,967,296
  1811.                CH_DATA_LONG     -2,147,483,648 to 2,147,483,648
  1812.                CH_DATA_FLOAT             10-36 to 10+36
  1813.                CH_DATA_DOUBLE           10-308 TO 10+308
  1814.  
  1815.  
  1816.   legend       Specifies a pointer to a text string that represents the text
  1817.   (PCH)        legend for the group.  The previous text legend will be 
  1818.                replaced.  If a NULL value is provided, the prior legend is 
  1819.                released.
  1820.  
  1821.   ┌───────────────────────────────────────────────────────────────────────────┐
  1822.   │                                                                           │
  1823.   │  Error codes     Chart_invalid_data_type    7                             │
  1824.   │                  Chart_invalid_group        8                             │
  1825.   │                                                                           │
  1826.   └───────────────────────────────────────────────────────────────────────────┘
  1827.  
  1828.   The following illustrates providing data group 3 with 4 data points and a
  1829.   legend.
  1830.  
  1831.  
  1832.   ┌───────────────────────────────────────────────────────────────────────────┐
  1833.   │                                                                           │
  1834.   │  BOOL            fAns;                   // Successful call indicator     │
  1835.   │  static HWND     hChart;                 // Bar chart handle              │
  1836.   │                                                                           │
  1837.   │  static LONG     Data[] = {350,-425,155,500};                             │
  1838.   │                                                                           │
  1839.   │  fAns = ChartData(hChart,                // Chart handle                  │
  1840.   │                   3,                     // Data group number             │
  1841.   │                   (PSHORT) &Data,        // Location of data points       │
  1842.   │                   4,                     // Data point count              │
  1843.   │                   0,                     // Start at first location       │
  1844.   │                   CH_DATA_LONG,          // Type of numerical data        │
  1845.   │                   "Group No. 3");        // Text legend                   │
  1846.   │                                                                           │
  1847.   └───────────────────────────────────────────────────────────────────────────┘
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.                                  29
  1855.  
  1856.  
  1857.  
  1858.   ChartDataAppend - Append a data point to a group
  1859.   ═════════════════════════════════════════════════
  1860.  
  1861.   ChartDataAppend(hchart,group,type,&datapoint,visible);
  1862.  
  1863.   This function adds a data point to a group and updates the currently
  1864.   displayed chart.  This function is the foundation for real-time chart
  1865.   updates.
  1866.  
  1867.   This function is operational and is described only in the full function
  1868.   product.
  1869.  
  1870.  
  1871.  
  1872.  
  1873.  
  1874.  
  1875.  
  1876.  
  1877.  
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.                                  30
  1913.  
  1914.  
  1915.  
  1916.   ChartDataUpdatePoint - Replace a single bar on the chart
  1917.   ════════════════════════════════════════════════════════
  1918.  
  1919.  
  1920.   This function is used to replace the value of a data point for a specific
  1921.   data group.  This interface can also immediately show the change on the chart
  1922.   if the chart is a 2 dimension bar chart.
  1923.  
  1924.   This API requires that the CH_TOUCH option be specified during the
  1925.   "ChartCreate" API request.  Further, the API will not redraw any grid lines
  1926.   associated with any scale.
  1927.  
  1928.  
  1929.   ┌───────────────────────────────────────────────────────────────────────────┐
  1930.   │                                                                           │
  1931.   │   ans = ChartDataUpdatePoint(hchart,       // Chart handle                │
  1932.   │                              group,        // Data group number           │
  1933.   │                              point,        // Data point number           │
  1934.   │                              data_type,    // Type of data to chart       │
  1935.   │                              &data,        // Pointer to data             │
  1936.   │                              visible);     // Display indicator           │
  1937.   │                                                                           │
  1938.   └───────────────────────────────────────────────────────────────────────────┘
  1939.  
  1940.   The "ChartDataUpdatePoint" function parameters are as follows:
  1941.  
  1942.   ans          Provides TRUE for a successful request or FALSE for an
  1943.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  1944.                the "error" code location specified in the "ChartCreate"
  1945.                function.
  1946.  
  1947.   hchart       Specifies the handle returned by the "ChartCreate" function.
  1948.   (HWND)
  1949.  
  1950.   group        Specifies the number of the data group that will be displayed.
  1951.   (USHORT)     This number must range between 1 and 12.
  1952.  
  1953.   point        Specifies the data point number to update.
  1954.   (USHORT)
  1955.  
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.                                  31
  1971.  
  1972.  
  1973.  
  1974.   data_type    Describes the type of data associated with this data group
  1975.   (USHORT)     (i.e. long, float).  The type of data being provided in the
  1976.                application data array is specified by one of the following
  1977.                parameters.
  1978.  
  1979.                            Range of data supported
  1980.                            ───────────────────────
  1981.  
  1982.                CH_DATA_USHORT                0 to 65,536
  1983.                CH_DATA_SHORT           -32,768 to 32,768
  1984.                CH_DATA_ULONG                 0 to 4,294,967,296
  1985.                CH_DATA_LONG     -2,147,483,648 to 2,147,483,648
  1986.                CH_DATA_FLOAT             10-36 to 10+36
  1987.                CH_DATA_DOUBLE           10-308 TO 10+308
  1988.  
  1989.   data         Pointer to an array of data points associated with the group.
  1990.   (PUSHORT)    This parameter should be "cast" to bypass compile warnings.
  1991.  
  1992.  
  1993.   visible      This parameter is used to also update the display.  In order
  1994.   (BOOL)       to update the display the chart type must be CH_BAR and the
  1995.                number of dimensions must be two. TRUE will display the new bar.
  1996.                A FALSE specification will only update the data point retained 
  1997.                by the charting engine.
  1998.  
  1999.  
  2000.   ┌───────────────────────────────────────────────────────────────────────────┐
  2001.   │                                                                           │
  2002.   │  Error codes     Chart_no_memory            3                             │
  2003.   │                  Chart_datapoints_excess    6                             │
  2004.   │                  Chart_invalid_data_type    7                             │
  2005.   │                  Chart_invalid_group        8                             │
  2006.   │                  Chart_no_data              9                             │
  2007.   │                  Chart_invalid_dimensions  10                             │
  2008.   │                  Chart_invalid_chart_type  15                             │
  2009.   │                                                                           │
  2010.   └───────────────────────────────────────────────────────────────────────────┘
  2011.  
  2012.  
  2013.  
  2014.  
  2015.  
  2016.  
  2017.  
  2018.  
  2019.  
  2020.  
  2021.  
  2022.  
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.                                  32
  2029.  
  2030.  
  2031.  
  2032.   ChartDataHighlight - Highlight data point(s) for emphasis
  2033.   ═════════════════════════════════════════════════════════
  2034.  
  2035.   ChartDataHighlight(hchart,group,count,&highlight);
  2036.  
  2037.   This function sets the display characteristics for one or more data points
  2038.   within a data group.  This function is to provided distinction for
  2039.   specified data points.
  2040.  
  2041.   This function is operational and is described only in the full function
  2042.   product.
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.  
  2055.  
  2056.  
  2057.  
  2058.  
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.  
  2078.  
  2079.  
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.                                  33
  2087.  
  2088.  
  2089.  
  2090.   ChartDestroy - Discard current chart
  2091.   ════════════════════════════════════
  2092.  
  2093.  
  2094.   This function discards all resources held by the chart.  If the chart is
  2095.   currently visible, it will not be erased or removed from the Presentation
  2096.   Manager window.  To reuse the space occupied by the chart, invalidate the
  2097.   rectangle and repaint any area as required.
  2098.  
  2099.   NOTE: Following this request, the chart is no longer accessible by any chart
  2100.   function.
  2101.  
  2102.   ┌───────────────────────────────────────────────────────────────────────────┐
  2103.   │                                                                           │
  2104.   │   ans = ChartDestroy(hchart);       // Chart handle                       │
  2105.   │                                                                           │
  2106.   └───────────────────────────────────────────────────────────────────────────┘
  2107.  
  2108.   The "ChartData" function parameters are as follows:
  2109.  
  2110.   ans          Provides TRUE for a successful request or FALSE for an
  2111.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  2112.                the "error" code location specified in the "ChartCreate"
  2113.                function.
  2114.  
  2115.   hchart       Specifies the handle returned by the "ChartCreate" function.
  2116.   (HWND)
  2117.  
  2118.  
  2119.   ┌───────────────────────────────────────────────────────────────────────────┐
  2120.   │                                                                           │
  2121.   │  Error codes     Chart_memory_release      12                             │
  2122.   │                                                                           │
  2123.   └───────────────────────────────────────────────────────────────────────────┘
  2124.  
  2125.  
  2126.   The following illustrates destroying a chart.
  2127.  
  2128.  
  2129.   ┌───────────────────────────────────────────────────────────────────────────┐
  2130.   │                                                                           │
  2131.   │  BOOL            fAns;                   // Successful call indicator     │
  2132.   │  static HWND     hChart;                 // Bar chart handle              │
  2133.   │                                                                           │
  2134.   │  fAns = ChartDestroy(hChart);            // Chart handle                  │
  2135.   │                                                                           │
  2136.   └───────────────────────────────────────────────────────────────────────────┘
  2137.  
  2138.  
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.                                  34
  2145.  
  2146.  
  2147.   ChartGetData - Retrieve data points
  2148.   ═══════════════════════════════════
  2149.  
  2150.   count = ChartGetData(hchart,group,&asciiz,&float_array);
  2151.  
  2152.   This function retrieves all data points which were previously provided to
  2153.   a data group.
  2154.  
  2155.   This function is operational and is described only in the full function
  2156.   product.
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.  
  2184.  
  2185.  
  2186.  
  2187.  
  2188.  
  2189.  
  2190.  
  2191.  
  2192.  
  2193.  
  2194.  
  2195.  
  2196.  
  2197.  
  2198.  
  2199.  
  2200.  
  2201.  
  2202.                                  35
  2203.  
  2204.  
  2205.  
  2206.   ChartGetDisplacement - Query where data would be drawn
  2207.   ══════════════════════════════════════════════════════
  2208.  
  2209.  
  2210.   This function provides the developer with a means to determine where a data
  2211.   value would be located if it was drawn by the charting DLL.  The pixel
  2212.   location returned is based on the axis and group number provided by the
  2213.   developer.
  2214.  
  2215.  
  2216.   ┌───────────────────────────────────────────────────────────────────────────┐
  2217.   │                                                                           │
  2218.   │   ans = ChartGetDisplacement(hwnd,         // Chart handle                │
  2219.   │                              group,        // Data group number           │
  2220.   │                              axis,         // Inference axis              │
  2221.   │                              value,        // Value to locate             │
  2222.   │                              &pixelout);    // Pointer to result          │
  2223.   │                                                                           │
  2224.   └───────────────────────────────────────────────────────────────────────────┘
  2225.  
  2226.  
  2227.   The "ChartGetDisplacement" function parameters are as follows:
  2228.  
  2229.   ans          Provides TRUE for a successful request or FALSE for an
  2230.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  2231.                the "error" code location specified in the "ChartCreate"
  2232.                function.
  2233.  
  2234.   hchart       Specifies the handle returned by the "ChartCreate" function.
  2235.   (HWND)
  2236.  
  2237.   group        Specifies the number of the data group that will be displayed.
  2238.   (USHORT)     This number must range between 1 and 12.
  2239.  
  2240.   axis         Specifies which axis to use as a reference point.  This 
  2241.   (LONG)       parameter must be one of the following values.
  2242.  
  2243.                    CH_X_TICK
  2244.                    CH_Y_TICK
  2245.                    CH_Z_TICK
  2246.  
  2247.   value        The data point value to be used when calculating the returned
  2248.   (DOUBLE)     pixel location.
  2249.  
  2250.   pixel_out    Pointer to a location to receive either the x, y or z 
  2251.   (LPLONG)     pixel location.  The result is returned in a LONG data format.
  2252.  
  2253.  
  2254.   NOTE:  This API should only be called after a chart has been displayed.
  2255.  
  2256.  
  2257.  
  2258.  
  2259.  
  2260.                                  36
  2261.   
  2262.  
  2263.  
  2264.   ChartGetLastError - Retrieve the last error code value
  2265.   ══════════════════════════════════════════════════════
  2266.  
  2267.   error = ChartGetLastError(hchart);
  2268.  
  2269.   This function retrieves the last error code value provided by the
  2270.   charting APIs.
  2271.  
  2272.   This function is operational and is described only in the full function
  2273.   product.
  2274.  
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280.  
  2281.  
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.                                  37
  2319.  
  2320.  
  2321.  
  2322.   ChartGetValue - Return value based on x or y coordinate
  2323.   ═══════════════════════════════════════════════════════
  2324.  
  2325.   This function provides the developer with a means to support rubber-banding
  2326.   of data points currently on the display.  Given a vertical pixel location
  2327.   within the client area, this API will return an approximate data value as it
  2328.   relates to either the y-axis or z-axis.  A x-axis value is only available for
  2329.   the CH_MATRIX chart.
  2330.  
  2331.  
  2332.   ┌───────────────────────────────────────────────────────────────────────────┐
  2333.   │                                                                           │
  2334.   │   ans = ChartGetValue(hchart,       // Chart handle                       │
  2335.   │                       group,        // Data group number                  │
  2336.   │                       axis,         // Inference axis                     │
  2337.   │                       location,     // Pixel location                     │
  2338.   │                       &valueout);   // Pointer to result                  │
  2339.   │                                                                           │
  2340.   └───────────────────────────────────────────────────────────────────────────┘
  2341.  
  2342.  
  2343.   The "ChartGetValue" function parameters are as follows:
  2344.  
  2345.   ans          Provides TRUE for a successful request or FALSE for an
  2346.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  2347.                the "error" code location specified in the "ChartCreate"
  2348.                function.
  2349.  
  2350.   hchart       Specifies the handle returned by the "ChartCreate" function.
  2351.   (HWND)
  2352.  
  2353.   group        Specifies the number of the data group that will be displayed.
  2354.   (USHORT)     This number must range between 1 and 12.
  2355.  
  2356.   axis         Specifies which axis to use as a reference point.  This 
  2357.   (LONG)       parameter must be one of the following values.
  2358.  
  2359.                    CH_X_TICK
  2360.                    CH_Y_TICK
  2361.                    CH_Z_TICK
  2362.  
  2363.   location     Specifies the pixel location to use when calculating the value
  2364.   (LONG)       to data value to return to the application.
  2365.  
  2366.   valueout     Specifies a pointer to a storage location to receive the data
  2367.   (double *)   value which is calculated by the charting engine.
  2368.  
  2369.  
  2370.   NOTE:  This API should only be called after a chart has been displayed.
  2371.  
  2372.   NOTE:  If the location specified is either above or below the graphic area,
  2373.   then either the maximum or minimum scale value will be returned.
  2374.  
  2375.  
  2376.                                  38
  2377.  
  2378.  
  2379.  
  2380.   ChartLegend - Associate a data group with a text string (legend)
  2381.   ════════════════════════════════════════════════════════════════
  2382.  
  2383.   This function associates a text string with a data group.  The function
  2384.   also changes or releases a currently specified legend.
  2385.  
  2386.   ┌───────────────────────────────────────────────────────────────────────────┐
  2387.   │                                                                           │
  2388.   │   ans = ChartLegend(hchart,         // Chart handle                       │
  2389.   │                     group,          // Data group Number                  │
  2390.   │                     &legend);       // Legend for group                   │
  2391.   │                                                                           │
  2392.   └───────────────────────────────────────────────────────────────────────────┘
  2393.  
  2394.  
  2395.   The "ChartLegend" function parameters are as follows:
  2396.  
  2397.   ans          Provides TRUE for a successful request or FALSE for an
  2398.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  2399.                the "error" code location specified in the "ChartCreate"
  2400.                function.
  2401.  
  2402.   hchart       Specifies the handle returned by the "ChartCreate" function.
  2403.   (HWND)
  2404.  
  2405.   group        Specifies the number of the data group that will be displayed.
  2406.   (USHORT)     This number must range between 1 and 12.
  2407.  
  2408.   legend       Specifies the pointer to a text string that represents the text
  2409.   (PCH)        legend for the group.  The previous text legend will be 
  2410.                replaced.  If a NULL value is provided, the prior legend is 
  2411.                released.
  2412.  
  2413.   ┌───────────────────────────────────────────────────────────────────────────┐
  2414.   │                                                                           │
  2415.   │  Error codes     Chart_no_memory            3                             │
  2416.   │                  Chart_invalid_parameter    5                             │
  2417.   │                  Chart_invalid_group        8                             │
  2418.   │                                                                           │
  2419.   └───────────────────────────────────────────────────────────────────────────┘
  2420.  
  2421.   The following illustrates providing data group 3 with a legend.
  2422.  
  2423.   ┌───────────────────────────────────────────────────────────────────────────┐
  2424.   │                                                                           │
  2425.   │  BOOL            fAns;                   // Successful call indicator     │
  2426.   │  static HWND     hChart;                 // Bar chart handle              │
  2427.   │                                                                           │
  2428.   │  fAns = ChartDestroy(hChart,             // Chart handle                  │
  2429.   │                      3,                  // Data group number 3           │
  2430.   │                      "X-Small");         // Text legend for the group     │
  2431.   │                                                                           │
  2432.   └───────────────────────────────────────────────────────────────────────────┘
  2433.  
  2434.                                  39
  2435.  
  2436.  
  2437.   ChartOptions - Assign required control flags to "range" charts
  2438.   ══════════════════════════════════════════════════════════════
  2439.  
  2440.   ChartOptions(hchart,charttype,count,¶meters);
  2441.  
  2442.   This function assigns unique control flags to specific chart types.  This
  2443.   function is applicable to the High/Low chart, Candlestick chart, and Point
  2444.   & Figure chart only.  These charts are members of the "range chart" family.
  2445.   One to four items are required for each data point to describe the data 
  2446.   point objects.
  2447.  
  2448.   NOTE:  The following order should be observed when providing data values to
  2449.   the charts: low value, high value, open value (optional), close value
  2450.   (optional).
  2451.  
  2452.   NOTE:  See "ChartSetOptions: for global chart flags.
  2453.  
  2454.   This function is operational and is described only in the full function
  2455.   product.
  2456.  
  2457.  
  2458.  
  2459.  
  2460.  
  2461.  
  2462.  
  2463.  
  2464.  
  2465.  
  2466.   ChartOutputMetaFile - Place a chart on disk in MetaFile format
  2467.   ══════════════════════════════════════════════════════════════
  2468.  
  2469.   ChartOutputMetaFile(hchart,&file_name);
  2470.  
  2471.   This function places a chart on the disk in metafile format for printing
  2472.   or replay.
  2473.  
  2474.   This function is operational and is described only in the full function
  2475.   product.
  2476.  
  2477.  
  2478.  
  2479.  
  2480.  
  2481.  
  2482.  
  2483.  
  2484.  
  2485.  
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.                                  40
  2493.  
  2494.   
  2495.  
  2496.   ChartPaint - Display chart without total redraw
  2497.   ═══════════════════════════════════════════════
  2498.  
  2499.   The "ChartPaint" API can be used instead of the "ChartVisible" interface to
  2500.   reduce the drawing time of a chart.  This interface must be called only
  2501.   during the applications processing of the WM_PAINT message.  Specifically,
  2502.   the API must be called between the WinBeginPaint and WinEndPaint messages.
  2503.   This function will display the chart specified by the "ChartCreate" function
  2504.   containing data defined in the "ChartData" function.
  2505.  
  2506.  
  2507.   ┌───────────────────────────────────────────────────────────────────────────┐
  2508.   │                                                                           │
  2509.   │   ans = ChartPaint(hchart,               // Chart handle                  │
  2510.   │                    hpaint);              // Handle from BeginPaint        │
  2511.   │                                                                           │
  2512.   └───────────────────────────────────────────────────────────────────────────┘
  2513.  
  2514.  
  2515.   The "ChartPaint" function parameters are as follows:
  2516.  
  2517.   ans          Provides TRUE for a successful request or FALSE for an
  2518.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  2519.                the "error" code location specified in the "ChartCreate"
  2520.                function.
  2521.  
  2522.   hchart       Specifies the handle returned by the "ChartCreate" function.
  2523.   (HWND)
  2524.  
  2525.   hpaint       Specifies the handle returned by the "WinBeginPaint"
  2526.   (HWND)       system message.
  2527.  
  2528.  
  2529.   ┌───────────────────────────────────────────────────────────────────────────┐
  2530.   │                                                                           │
  2531.   │  Error codes     Chart_invalid_client            1                        │
  2532.   │                  Chart_not_defined               2                        │
  2533.   │                  Chart_no_memory                 3                        │
  2534.   │                  Chart_no_data                   9                        │
  2535.   │                  Chart_memory_release           12                        │
  2536.   │                                                                           │
  2537.   └───────────────────────────────────────────────────────────────────────────┘
  2538.  
  2539.  
  2540.  
  2541.  
  2542.  
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549.  
  2550.                                  41
  2551.  
  2552.  
  2553.  
  2554.   ChartPrint - Print a graphic chart
  2555.   ══════════════════════════════════
  2556.  
  2557.   This function sends a graphic chart to the default system printer.  This
  2558.   function requires the use of the system print manager.
  2559.  
  2560.   NOTE: Charts with a large number of data groups and/or data points may not 
  2561.   print properly.  The graphics engine will not print a chart on multiple 
  2562.   pages.  If a chart is so large that the graphics engine can not print text or
  2563.   data using the smallest font, that information will be sacrificed and will 
  2564.   not be printed.
  2565.  
  2566.   ┌───────────────────────────────────────────────────────────────────────────┐
  2567.   │                                                                           │
  2568.   │   ans =     ChartPrint(hchart,             // Chart handle                │
  2569.   │                        job_name,           // Text string for job name    │
  2570.   │                      &print_flags);        // Pointer to print            │
  2571.   │                                            //   control structure         │
  2572.   │                                                                           │
  2573.   └───────────────────────────────────────────────────────────────────────────┘
  2574.  
  2575.  
  2576.   The "ChartPrint" function parameters are as follows:
  2577.  
  2578.   ans          Provides TRUE for a successful request or FALSE for an
  2579.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  2580.                the "error" code location specified in the "ChartCreate"
  2581.                function.
  2582.  
  2583.   hchart       Specifies the handle returned by the "ChartCreate" function.
  2584.   (HWND)
  2585.  
  2586.   Job_name     Pointer to an ASCIIZ text string which contains the name of
  2587.   (PCH)        job or report.
  2588.  
  2589.  
  2590.  
  2591.  
  2592.  
  2593.  
  2594.  
  2595.  
  2596.  
  2597.  
  2598.  
  2599.  
  2600.  
  2601.  
  2602.  
  2603.  
  2604.  
  2605.  
  2606.  
  2607.  
  2608.  
  2609.                                  42
  2610.  
  2611.  
  2612.  
  2613.   print_flags  This parameter should contain the address of a CHARTPRINT data
  2614.   PCHARTPRINT  structure. The structure is as follows.
  2615.  
  2616.               LONG    cb;               // Length of structure
  2617.               ULONG   flags;            // Flags to be or-ed on
  2618.               PSZ     pAbortProc;       // Pointer to abort procedure "Windows"
  2619.               CHAR    szDeviceName[32]; // Reserved
  2620.  
  2621.                For OS/2, two flags have been defined to circumvent problems
  2622.                arising when printing charts in landscape mode.  OS/2 currently
  2623.                has a BUG when we request the width and height when a printer is
  2624.                placed into landscape mode.  These flags should provide some
  2625.                relief to the developer and end user.  The "CH_OPTIONS_DIALOG"
  2626.                key word tells the ChartPrint API to pop-up the job properties
  2627.                dialog box of the system for the end user.  At that point, the
  2628.                user should select the landscape radio button.  This will direct
  2629.                the print manager to place this job into landscape mode.  The
  2630.                "CH_LANDSCAPE" key word tells the ChartPrint API to use the
  2631.                systems page height as the actual page width and the systems
  2632.                page width as the actual page height.  We are hoping that OS/2
  2633.                resolves their BUG in the near future.
  2634.  
  2635.                The third field in the structure is used only for windows and if
  2636.                required, contains the address of an application program printer
  2637.                abort procedure as defined by the Windows system.
  2638.  
  2639.  
  2640.   ┌───────────────────────────────────────────────────────────────────────────┐
  2641.   │                                                                           │
  2642.   │  Error codes     Chart_invalid_parameter    5                             │
  2643.   │                                                                           │
  2644.   └───────────────────────────────────────────────────────────────────────────┘
  2645.  
  2646.  
  2647.   The following illustrates printing a chart.
  2648.  
  2649.  
  2650.   ┌───────────────────────────────────────────────────────────────────────────┐
  2651.   │                                                                           │
  2652.   │  BOOL            fAns;                   // Successful call indicator     │
  2653.   │  static HWND     hChart;                 // Bar chart handle              │
  2654.   │                                                                           │
  2655.   │  fAns = ChartPrint(hChart,               // Chart handle                  │
  2656.   │                    "My Report",          // Job Name                      │
  2657.   │                     0L);                 // No additional controls        │
  2658.   │                                                                           │
  2659.   └───────────────────────────────────────────────────────────────────────────┘
  2660.  
  2661.  
  2662.  
  2663.  
  2664.  
  2665.  
  2666.  
  2667.                                  43
  2668.  
  2669.  
  2670.  
  2671.   ChartQueryDimensions - Obtain visual dimensions of a chart
  2672.   ══════════════════════════════════════════════════════════
  2673.  
  2674.   ChartQueryDimensions(hchart,&dimensions);
  2675.  
  2676.   This function provides a number representing the current dimensional
  2677.   display associated with a chart.
  2678.  
  2679.   This function is operational and is described only in the full function
  2680.   product.
  2681.  
  2682.  
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.   ChartQueryExtendedError - Query the time value error for time based charts
  2698.   ══════════════════════════════════════════════════════════════════════════
  2699.  
  2700.   error_number = ChartQueryExtendedError(hchart);
  2701.  
  2702.   This function determines the time value in error after a "ChartTimeReference"
  2703.   call is made.
  2704.  
  2705.   This function is operational and is described only in the full function
  2706.   product.
  2707.  
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.  
  2714.  
  2715.  
  2716.  
  2717.  
  2718.  
  2719.  
  2720.  
  2721.  
  2722.  
  2723.  
  2724.  
  2725.                                  44
  2726.  
  2727.  
  2728.  
  2729.   ChartQueryGroupColor - Obtain color assigned to a data group
  2730.   ════════════════════════════════════════════════════════════
  2731.  
  2732.   This function enables the application program to obtain the color assigned to
  2733.   a specific data group.  The value returned will be a CLR_???  value.  The API
  2734.   would generally be used when applications need to drill down into more detail
  2735.   about a specific data group.  For example, when the user touches their mouse
  2736.   on a bar, the programmer can request the "ChartQueryPointer" API and the
  2737.   charting DLL will return the group number touched by the user.  With this
  2738.   group number, the application program can call the "ChartQueryGroupColor" API
  2739.   to obtain the current color assigned for the data group.  Next, the
  2740.   application can set data group number one to the color just obtained, assign
  2741.   more detail data to data group one, change the number for groups being
  2742.   displayed to one and show the chart.  This technique will maintain the visual
  2743.   color consistency for the end user.  To return all data groups back to their
  2744.   original colors reference the "ChartSendMsg" API with the
  2745.   CH_RESET_GROUP_COLORS parameter.
  2746.  
  2747.   NOTE: See "ChartSetGroupColor"
  2748.  
  2749.  
  2750.   ┌───────────────────────────────────────────────────────────────────────────┐
  2751.   │                                                                           │
  2752.   │   ans =  ChartQueryGroupColor(hchart,      // Chart handle                │
  2753.   │                               group,       // Group number                │
  2754.   │                               &color);     // Location to receive CLR_??? │
  2755.   │                                                                           │
  2756.   └───────────────────────────────────────────────────────────────────────────┘
  2757.  
  2758.  
  2759.   The "ChartQueryGroupColor" function parameters are as follows:
  2760.  
  2761.   ans          Provides TRUE for a successful request or FALSE for an
  2762.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  2763.                the "error" code location specified in the "ChartCreate"
  2764.                function.
  2765.  
  2766.   hchart       Specifies the handle returned by the "ChartCreate" function.
  2767.   (HWND)
  2768.  
  2769.   group        Specifies the data group number to be queried.  The value must 
  2770.   (USHORT)     range from 1 to 12.
  2771.  
  2772.   color        Specifies a pointer to a memory location which will receive the
  2773.   (LPLONG)     "LONG" color value.
  2774.  
  2775.  
  2776.   ┌───────────────────────────────────────────────────────────────────────────┐
  2777.   │                                                                           │
  2778.   │  Error codes     Chart_invalid_parameter  5                               │
  2779.   │                  Chart_invalid_group      8                               │
  2780.   │                                                                           │
  2781.   └───────────────────────────────────────────────────────────────────────────┘
  2782.  
  2783.                                  45
  2784.  
  2785.  
  2786.  
  2787.   ChartQueryLocation - Obtain specific coordinates in a chart
  2788.   ═══════════════════════════════════════════════════════════
  2789.  
  2790.   This function determines the location of a specific item displayed in a
  2791.   chart.  The application can then provide a note or information to the
  2792.   user in the proximity.
  2793.  
  2794.   This function requires the use of a data structure called "CHARTPOINTER". The
  2795.   "CHARTPOINTER" data structure consists of xLeft, xRight, yTop, and yBottom 
  2796.   elements providing the object coordinates.  
  2797.  
  2798.   To activate this function, the parameter CH_TOUCH must be specified in either
  2799.   the "ChartCreate" or "ChartSetOptions" function calls.  The coordinates are
  2800.   held in dynamic memory until the chart is redisplayed, destroyed, or the 
  2801.   CH_TOUCH option is removed.
  2802.  
  2803.  
  2804.   ┌───────────────────────────────────────────────────────────────────────────┐
  2805.   │                                                                           │
  2806.   │   ans = ChartQueryLocation(hchart,      // Chart handle                   │
  2807.   │                            &pointer);   // Pointer to a data structure    │
  2808.   │                                                                           │
  2809.   └───────────────────────────────────────────────────────────────────────────┘
  2810.  
  2811.  
  2812.   The "ChartQueryLocation" function parameters are as follows:
  2813.  
  2814.   ans          Provides TRUE for a successful request or FALSE for an
  2815.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  2816.                the "error" code location specified in the "ChartCreate"
  2817.                function.
  2818.  
  2819.   hchart       Specifies the handle returned by the "ChartCreate" function.
  2820.   (HWND)
  2821.  
  2822.   pointer          Specifies the address of a data structure.  The data
  2823.   (PCHARTPOINTER)  structure is returned with the control information being
  2824.                    requested.
  2825.  
  2826.                CHARTPOINTER is in the CHART.H include file.  The following
  2827.                describes the values returned:
  2828.  
  2829.                    typedef  struct _CHARTPOINTER {
  2830.                       BOOL    success;            // Success indicator
  2831.                       USHORT  type;               // Type of object
  2832.                       USHORT  group;              // Group number  
  2833.                       USHORT  point;              // Point number within group
  2834.                       float   value;              // Value if data point
  2835.                       LONG    xLeft;              // Location of the object
  2836.                       LONG    yBottom;            // Location of the object
  2837.                       LONG    xRight;             // Location of the object
  2838.                       LONG    yTop;               // Location of the object
  2839.                    } CHARTPOINTER;
  2840.  
  2841.                                  46
  2842.  
  2843.  
  2844.  
  2845.                success    A BOOL value is TRUE if the query is successful or 
  2846.                           FALSE if unsuccessful.
  2847.  
  2848.                type       A USHORT value reflects the location of the chart
  2849.                           being queried.  The following are values which can
  2850.                           be provided by the programmer to this function:
  2851.  
  2852.                              Symbolic                Location being queried
  2853.                              ───────────────         ──────────────────────
  2854.                              CH_LOC_LEGEND           Legend 
  2855.                              CH_LOC_POINT            Data point
  2856.                              CH_LOC_TITLE            Title
  2857.                              CH_LOC_LEFT_MARGIN      Left margin
  2858.                              CH_LOC_RIGHT_MARGIN     Right margin
  2859.                              CH_LOC_TOP_LEFT         Top Left corner
  2860.                              CH_LOC_TOP_RIGHT        Top Right corner
  2861.                              CH_LOC_BOTTOM_LEFT      Bottom Left corner
  2862.                              CH_LOC_BOTTOM_RIGHT     Bottom Right corner
  2863.                              CH_LOC_X_TICK           X tick string
  2864.                              CH_LOC_Y_TICK           Y tick area
  2865.                              CH_LOC_Z_TICK           Z tick area
  2866.                              CH_LOC_GRAPHIC          Graphic drawing area
  2867.  
  2868.  
  2869.                group      A USHORT value specifies the data group, legend, or 
  2870.                           point queried.  The number specified is 1 to 12.
  2871.  
  2872.                point      A USHORT value specifies the data point of a group
  2873.                           queried.
  2874.  
  2875.                value      Receives the value if a data group and point area
  2876.                           queried.
  2877.  
  2878.                xLeft       Receive the coordinates of the object being queried.
  2879.                yBottom
  2880.                xRight
  2881.                yTop
  2882.  
  2883.  
  2884.   ┌───────────────────────────────────────────────────────────────────────────┐
  2885.   │                                                                           │
  2886.   │  Error codes     Chart_invalid_parameter    5                             │
  2887.   │                  Chart_invalid_group        8                             │
  2888.   │                  Chart_no_data_available   22                             │
  2889.   │                                                                           │
  2890.   └───────────────────────────────────────────────────────────────────────────┘
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.                                  47
  2900.  
  2901.  
  2902.  
  2903.   The following illustrates locating the rectangular display coordinates of the
  2904.   4th data point for data group 2 on the chart that is currently visible.
  2905.  
  2906.  
  2907.   ┌───────────────────────────────────────────────────────────────────────────┐
  2908.   │                                                                           │
  2909.   │  BOOL            fAns;                   // Successful call indicator     │
  2910.   │  static HWND     hChart;                 // Bar chart handle              │
  2911.   │  CHARTPOINTER    location;               // Query structure               │
  2912.   │                                                                           │
  2913.   │                                                                           │
  2914.   │  location.type = CH_LOC_POINT;           // Find location of group & point│
  2915.   │  location.group = 2;                     // Data group 2                  │
  2916.   │  location.point = 4;                     // Data point 4                  │
  2917.   │                                                                           │
  2918.   │  fAns = ChartQueryLocation(hChart,       // Chart handle                  │
  2919.   │                            &location);   // Pointer to a data structure   │
  2920.   │                                                                           │
  2921.   │                                                                           │
  2922.   │                                                                           │
  2923.   │  if (fAns && location.success) {                                          │
  2924.   │                                                                           │
  2925.   │          //  Success                                                      │
  2926.   │                                                                           │
  2927.   │  } else {                                                                 │
  2928.   │                                                                           │
  2929.   │          //  Item not found                                               │
  2930.   │                                                                           │
  2931.   │  }                                                                        │
  2932.   │                                                                           │
  2933.   └───────────────────────────────────────────────────────────────────────────┘
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.  
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.                                  48
  2958.  
  2959.  
  2960.  
  2961.   ChartQueryOptions - Obtain current chart flags
  2962.   ══════════════════════════════════════════════
  2963.  
  2964.   ChartQueryOptions(hchart,&chart_flags);
  2965.  
  2966.   This function enables acquisition of the current setting for the chart
  2967.   control flags.
  2968.  
  2969.   This function is operational and is described only in the full function
  2970.   product.
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.  
  2978.  
  2979.  
  2980.  
  2981.  
  2982.  
  2983.  
  2984.  
  2985.  
  2986.  
  2987.  
  2988.  
  2989.  
  2990.  
  2991.  
  2992.  
  2993.  
  2994.  
  2995.  
  2996.  
  2997.  
  2998.  
  2999.  
  3000.  
  3001.  
  3002.  
  3003.  
  3004.  
  3005.  
  3006.  
  3007.  
  3008.  
  3009.  
  3010.  
  3011.  
  3012.  
  3013.  
  3014.  
  3015.                                  49
  3016.  
  3017.  
  3018.  
  3019.   ChartQueryPointer - Tactile feedback
  3020.   ════════════════════════════════════
  3021.  
  3022.   ChartQueryPointer(hchart,x,y,&pointer);
  3023.  
  3024.   This function enables the user to click on various chart locations and
  3025.   allow the developer's application program to respond to the pointing motion.
  3026.   The programmer can then pass various x and y coordinates to the graphics DLL
  3027.   for "hot spot" resolution.
  3028.  
  3029.   To activate this function, the parameter CH_TOUCH must be specified in either
  3030.   the "ChartCreate" or "ChartSetOptions" function calls.  The coordinates are 
  3031.   held in dynamic memory until the chart is redisplayed, destroyed, or the 
  3032.   CH_TOUCH option is removed.
  3033.  
  3034.  
  3035.   ┌───────────────────────────────────────────────────────────────────────────┐
  3036.   │                                                                           │
  3037.   │   ans = ChartQueryPointer(hchart,       // Chart handle                   │
  3038.   │                           x,            // X coordinate queried           │
  3039.   │                           y,            // Y coordinate queried           │
  3040.   │                           &pointer);    // Pointer to a data structure    │
  3041.   │                                                                           │
  3042.   └───────────────────────────────────────────────────────────────────────────┘
  3043.  
  3044.  
  3045.   The "ChartQueryPointer" function parameters are as follows:
  3046.  
  3047.   ans          Provides TRUE for a successful request or FALSE for an
  3048.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  3049.                the "error" code location specified in the "ChartCreate"
  3050.                function.
  3051.  
  3052.   hchart       Specifies the handle returned by the "ChartCreate" function.
  3053.   (HWND)
  3054.  
  3055.   x            Specifies the x coordinate queried.
  3056.   (LONG)
  3057.  
  3058.   y            Specifies the y coordinate queried.
  3059.   (LONG)
  3060.  
  3061.  
  3062.  
  3063.  
  3064.  
  3065.  
  3066.  
  3067.  
  3068.  
  3069.  
  3070.  
  3071.  
  3072.  
  3073.                                  50
  3074.  
  3075.  
  3076.  
  3077.   pointer          Specifies the address of a data structure.  The data
  3078.   (PCHARTPOINTER)  structure is returned with the control information being
  3079.                    requested.
  3080.  
  3081.                CHARTPOINTER is in the CHART.H include file.  The following
  3082.                describes the values returned:
  3083.  
  3084.                    typedef  struct _CHARTPOINTER {
  3085.                       BOOL    success;            // Success indicator
  3086.                       USHORT  type;               // Type of object
  3087.                       USHORT  group;              // Group number  
  3088.                       USHORT  point;              // Point number within group
  3089.                       float   value;              // Value if data point
  3090.                       LONG    xLeft;              // Location of the object
  3091.                       LONG    yBottom;            // Location of the object
  3092.                       LONG    xRight;             // Location of the object
  3093.                       LONG    yTop;               // Location of the object
  3094.                    } CHARTPOINTER;
  3095.  
  3096.                success    A BOOL value is TRUE if the query is successful or 
  3097.                           FALSE if unsuccessful.
  3098.  
  3099.                type       A USHORT value reflects the location of the chart
  3100.                           item represented by the x and y locations provided
  3101.                           by the programmer to this function:
  3102.  
  3103.                              Symbolic                Location represented
  3104.                              ───────────────         ──────────────────────
  3105.                              CH_LOC_LEGEND           Legend 
  3106.                              CH_LOC_POINT            Data point
  3107.                              CH_LOC_TITLE            Title
  3108.                              CH_LOC_LEFT_MARGIN      Left margin
  3109.                              CH_LOC_RIGHT_MARGIN     Right margin
  3110.                              CH_LOC_TOP_LEFT         Top Left corner
  3111.                              CH_LOC_TOP_RIGHT        Top Right corner
  3112.                              CH_LOC_BOTTOM_LEFT      Bottom Left corner
  3113.                              CH_LOC_BOTTOM_RIGHT     Bottom Right corner
  3114.                              CH_LOC_X_TICK           X tick string
  3115.                              CH_LOC_Y_TICK           Y tick area
  3116.                              CH_LOC_Z_TICK           Z tick area
  3117.                              CH_LOC_GRAPHIC          Graphic drawing area
  3118.  
  3119.  
  3120.                group      A USHORT value specifies the data group, legend, or 
  3121.                           point queried.  The number specified is 1 to 12.
  3122.  
  3123.                point      A USHORT value specifies the data point of a group
  3124.                           queried.
  3125.  
  3126.                value      Receives the value if a data group and point area
  3127.                           queried.
  3128.  
  3129.  
  3130.  
  3131.                                  51
  3132.  
  3133.  
  3134.  
  3135.                xLeft       Receive the coordinates of the object being queried.
  3136.                yBottom
  3137.                xRight
  3138.                yTop
  3139.  
  3140.  
  3141.   ┌───────────────────────────────────────────────────────────────────────────┐
  3142.   │                                                                           │
  3143.   │  Error codes     Chart_invalid_parameter    5                             │
  3144.   │                                                                           │
  3145.   └───────────────────────────────────────────────────────────────────────────┘
  3146.  
  3147.  
  3148.   The following illustrates acquiring the graphic characteristics of an 
  3149.   application specific coordinate.
  3150.  
  3151.  
  3152.   ┌───────────────────────────────────────────────────────────────────────────┐
  3153.   │                                                                           │
  3154.   │  BOOL            fAns;                   // Successful call indicator     │
  3155.   │  static HWND     hChart;                 // Bar chart handle              │
  3156.   │  CHARTPOINTER    location;               // Query structure               │
  3157.   │                                                                           │
  3158.   │                                                                           │
  3159.   │  fAns = ChartQueryPointer(hChart,        // Chart handle                  │
  3160.   │                           100L,          // X location                    │
  3161.   │                           200L,          // Y location                    │
  3162.   │                           &location);    // Pointer to a data structure   │
  3163.   │                                                                           │
  3164.   └───────────────────────────────────────────────────────────────────────────┘
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.  
  3176.  
  3177.  
  3178.  
  3179.  
  3180.  
  3181.  
  3182.  
  3183.  
  3184.  
  3185.  
  3186.  
  3187.  
  3188.  
  3189.                                  52
  3190.  
  3191.  
  3192.  
  3193.   ChartQueryTextFontSize - Query the automatic font size for a text string
  3194.   ════════════════════════════════════════════════════════════════════════
  3195.  
  3196.   ChartQueryTextFontSize(hchart,flags,text);
  3197.  
  3198.   This function returns the font size used to display a single chart text 
  3199.   element.  The last "ChartSetRect" call determines the size of the text area.
  3200.  
  3201.   This function is operational and is described only in the full function
  3202.   product.
  3203.  
  3204.  
  3205.  
  3206.   ChartQueryTextFontSizes - Query the automatic font size for text strings
  3207.   ════════════════════════════════════════════════════════════════════════
  3208.  
  3209.   ChartQueryTextFontSizes(hchart,device,count,direction,rect,strings,fonts);
  3210.  
  3211.   This function returns the font sizes used to display multiple text strings.
  3212.   The device (i.e. display), the number of strings to process, the display 
  3213.   directions, the logical rectangles and the associated text strings for each 
  3214.   of the text areas are required.
  3215.  
  3216.   This function is operational and is described only in the full function
  3217.   product.
  3218.  
  3219.  
  3220.  
  3221.   ChartQueryType - Determine type of chart
  3222.   ════════════════════════════════════════
  3223.  
  3224.   ChartQueryType(hchart,&chart_type);
  3225.  
  3226.   This function provides the current chart type representing a chart handle
  3227.   (i.e. bar chart, pie chart).
  3228.  
  3229.   This function is operational and is described only in the full function
  3230.   product.
  3231.  
  3232.  
  3233.  
  3234.   ChartQueryVersion - Obtain installed version number of charting DLL
  3235.   ═══════════════════════════════════════════════════════════════════
  3236.  
  3237.   ChartQueryVersion(&ver);
  3238.  
  3239.   This function obtains the version and modification level of the installed
  3240.   charting DLL.
  3241.  
  3242.   This function is operational and is described only in the full function
  3243.   product.
  3244.  
  3245.  
  3246.  
  3247.                                  53
  3248.  
  3249.  
  3250.  
  3251.   ChartSendMsg - Send operational flags to charts
  3252.   ═══════════════════════════════════════════════
  3253.  
  3254.   This function directs messages to a specific chart or to all charts for 
  3255.   operational characteristics.
  3256.  
  3257.   ┌───────────────────────────────────────────────────────────────────────────┐
  3258.   │                                                                           │
  3259.   │   ans = ChartSendMsg(hchart,            // Chart handle                   │
  3260.   │                      msg_id,            // Message identification         │
  3261.   │                      param1,            // Parameter 1                    │
  3262.   │                      param2);           // Parameter 2                    │
  3263.   │                                                                           │
  3264.   └───────────────────────────────────────────────────────────────────────────┘
  3265.  
  3266.   The "ChartSendMsg" function parameters are as follows:
  3267.  
  3268.   ans          Provides TRUE for a successful request or FALSE for an
  3269.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  3270.                the "error" code location specified in the "ChartCreate"
  3271.                function.
  3272.  
  3273.   hchart       Specifies the handle returned by the "ChartCreate" function.
  3274.   (HWND)
  3275.  
  3276.   msg_id       Specifies the function to be performed or the chart to direct
  3277.   (USHORT)     the message.
  3278.  
  3279.   param1       Specifies the first parameter of the message.
  3280.   (ULONG)
  3281.  
  3282.   param2       Specifies the second parameter of the message.
  3283.   (ULONG)
  3284.  
  3285.   The following describes the message identifiers and parameters which can be 
  3286.   send as part of the message.
  3287.  
  3288.  
  3289.   Note any time in the following examples that TRUE is specified, a FALSE being
  3290.   specified will reverse the desired request.
  3291.  
  3292.  
  3293.       Display marker symbols in the chart legend
  3294.       ──────────────────────────────────────────
  3295.  
  3296.       Directs system marker symbols to be used in the legend area overriding 
  3297.       the default.  If the last parameter is FALSE, the marker symbols will 
  3298.       return to the default state.
  3299.  
  3300.       ChartSendMsg(hChart,CH_MARKER_LEGENDS,0,TRUE);
  3301.  
  3302.  
  3303.  
  3304.  
  3305.                                  54
  3306.  
  3307.  
  3308.  
  3309.       Bypass erasing the client area on displaying a chart
  3310.       ────────────────────────────────────────────────────
  3311.  
  3312.       Directs that the client area of the chart not be painted.  If the last 
  3313.       parameter is FALSE, the client area will be painted (default) with 
  3314.       "ChartVisible" function call.
  3315.  
  3316.       ChartSendMsg(hChart,CH_BYPASS_CLIENT_ERASE,0,TRUE);
  3317.  
  3318.  
  3319.       Specify the width of grid lines
  3320.       ────────────────────────────────
  3321.  
  3322.       Specifies the width of the grid lines.  The third parameter, "grid: must 
  3323.       specify CH_X_GRID, CH_Y_GRID, CH_Z_GRID, or CH_MINOR_GRID.  The last 
  3324.       parameter "width", specifies the pixel width for the line.  The solid 
  3325.       line width can be from 1 to a maximum of 20.  One is is maximum line 
  3326.       width for all other line types.
  3327.  
  3328.       ChartSendMsg(hChart,CH_GRID_WIDTH,grid,width);
  3329.  
  3330.  
  3331.       Evenly distribute x-tick strings
  3332.       ────────────────────────────────
  3333.  
  3334.       Specifies that one or more x tick text strings are to be evenly 
  3335.       distributed across the x-axis.  This message reduces the need to have a 
  3336.       string for every data point.  This request is supported by only 2 
  3337.       dimension line, scatter and area charts.  The last parameter must be 
  3338.       stated as FALSE to disable the message.
  3339.  
  3340.       ChartSendMsg(hChart,CH_X-TICK_BALANCE,0,TRUE);
  3341.  
  3342.  
  3343.       Horizontally stagger the x-axis text
  3344.       ────────────────────────────────────
  3345.  
  3346.       Directs that the x-axis text information is horizontally staggered.  This
  3347.       techniques allows space for more or longer x tick strings.  The last 
  3348.       parameter must be stated FALSE to disable the message.
  3349.  
  3350.       ChartSendMsg(hChart,CH_X-TICK_BALANCE,0,TRUE);
  3351.  
  3352.          ───────┬─────────┬─────────┬─────────┬─────────┬─────────┬──────
  3353.                ABC       DEF       GHI       JKL       MNO       PQR
  3354.       Default
  3355.  
  3356.  
  3357.          ───────┬─────────┬─────────┬─────────┬─────────┬─────────┬──────
  3358.                ABC        │        GHI        │        MNO        │
  3359.                          DEF                 JKL                 PQR
  3360.       Multiline
  3361.  
  3362.  
  3363.                                    55
  3364.  
  3365.  
  3366.  
  3367.       Use the full chart width for legend display
  3368.       ───────────────────────────────────────────
  3369.  
  3370.       Directs that the legend text information use the entire chart width for 
  3371.       output area.  The last parameter must be stated as FALSE to disable the 
  3372.       message and return the legend display immediately below the graphic area.
  3373.  
  3374.       ChartSendMsg(hChart,CH_FULL_WIDTH_LEGENDS,0,TRUE);
  3375.  
  3376.  
  3377.       Set display frequency for Point & Figure charts
  3378.       ───────────────────────────────────────────────
  3379.  
  3380.       Specifies the frequency that symbols will be displayed on the Point & 
  3381.       Figure chart.  The default frequency of 1.0 is used if this message is 
  3382.       not sent.
  3383.  
  3384.       ChartSendMsg(hChart,CH_POINT_FIGURE_VALUE,0,(float)4.0);
  3385.  
  3386.  
  3387.       Set direction change value on Point & Figure charts
  3388.       ───────────────────────────────────────────────────
  3389.  
  3390.       Specifies the value indicating a major upward direction change.  This 
  3391.       float value is usually specified as three times the value provided in the
  3392.       CH_POINT_FIGURE_VALUE message immediately above.
  3393.  
  3394.       ChartSendMsg(hChart,CH_POINT_FIGURE_UP,0,(float)12.0);
  3395.  
  3396.       Bypass switch to bar/line chart with z-axis
  3397.       ───────────────────────────────────────────
  3398.  
  3399.       Normally the charting DLL will switch to the region settings of the
  3400.       CH_BAR_LINE chart if the current chart contains a z-axis.  This send
  3401.       message request will suspend the switching operation.  To disable this
  3402.       request and resume the use of normal scales, specify FALSE as the last
  3403.       parameter for this API request.
  3404.  
  3405.       ChartSendMsg(hChart,CH_BYPASS_Z_EXCHANGE,0,TRUE);
  3406.  
  3407.  
  3408.       Tighten up y and z-axis scales
  3409.       ──────────────────────────────
  3410.  
  3411.       This function causes both the y and z axis scales to reduce any excess
  3412.       tick marks that may be generated during automatic axis scale generation.
  3413.       This should generally only be used on 2 dimension charts.  To enable this
  3414.       function follow the example below.  To disable this request and resume
  3415.       the use of normal scales, specify FALSE as the last parameter for this
  3416.       API request.
  3417.  
  3418.       ChartSendMsg(hChart,CH_TIGHT_SCALES,0,TRUE);
  3419.  
  3420.  
  3421.                                  56
  3422.  
  3423.  
  3424.  
  3425.       Tie z-axis scale to highest data value on the y-axis
  3426.       ────────────────────────────────────────────────────
  3427.  
  3428.       This function caused the top of the z axis scale to be aligned with the
  3429.       highest data value of all items on the y axis scale.  This function would
  3430.       best be used when the programmer specifies a programmer specified z axis
  3431.       and an automatic y axis scale generation.  To enable this function follow
  3432.       the example below.  To disable this request and resume the use of normal
  3433.       scales, specify FALSE as the last parameter for this API request.
  3434.  
  3435.       ChartSendMsg(hChart,CH_ZAXIS_YDATA,0,TRUE);
  3436.  
  3437.  
  3438.       Draw straight line on Bar Goal chart
  3439.       ────────────────────────────────────
  3440.  
  3441.       This function causes the bar goal chart to draw a straight line instead
  3442.       of a square wave line for a data group which is represented by some type
  3443.       of line.  To enable this function follow the example below.  To disable
  3444.       this request and resume the use of a square wave line, specify FALSE as
  3445.       the last parameter for this API request.
  3446.  
  3447.       ChartSendMsg(hChart,CH_BAR_GOAL,CH_LINE,TRUE);
  3448.  
  3449.  
  3450.       Bypass drawing in graphic area
  3451.       ──────────────────────────────
  3452.  
  3453.       This function will cause the painting process for charts to bypass the
  3454.       drawing of items within the chart graphic area.  This function is
  3455.       currently only implemented for standard bar, line, horizontal bar, and
  3456.       perspective bar charts The charts can be either 2 or 3 dimensions.
  3457.  
  3458.       ChartSendMsg(hChart,CH_BYPASS_GRAPHIC_DRAW,0,TRUE);
  3459.  
  3460.  
  3461.       Bypass legend display
  3462.       ─────────────────────
  3463.  
  3464.       This will stop the group legends from being displayed.  However, if a
  3465.       footnote was provided by way of the ChartTexts or ChartText APIs, the
  3466.       footnote will be displayed if possible.
  3467.  
  3468.       ChartSendMsg(hChart,CH_BYPASS_LEGENDS,0,TRUE);
  3469.  
  3470.  
  3471.  
  3472.       Bypass x-axis text
  3473.       ──────────────────
  3474.  
  3475.       This will stop the text from being displayed on the x-axis for all charts
  3476.       which are not time based.
  3477.  
  3478.       ChartSendMsg(hChart,CH_BYPASS_X_AXIS_TEXT,0,TRUE);
  3479.                                  57
  3480.  
  3481.  
  3482.  
  3483.       Display currency symbols on y or z-axis
  3484.       ───────────────────────────────────────
  3485.  
  3486.       Based on the current system currency symbol, these messages can
  3487.       independently force the currency symbol to appear before each numerical
  3488.       value on either the y or z axis.
  3489.  
  3490.  
  3491.       ChartSendMsg(hChart,CH_Y_AXIS_CURRENCY,0,TRUE);
  3492.                      or
  3493.       ChartSendMsg(hChart,CH_Z_AXIS_CURRENCY,0,TRUE);
  3494.  
  3495.  
  3496.  
  3497.       Display percent symbols on y or z-axis
  3498.       ───────────────────────────────────────
  3499.  
  3500.       These messages can independently request that a percent symbol be placed
  3501.       after each number on either the y-axis or the z-axis.
  3502.  
  3503.  
  3504.       ChartSendMsg(hChart,CH_Y_AXIS_PERCENT_SIGN,0,TRUE);
  3505.                      or
  3506.       ChartSendMsg(hChart,CH_Z_AXIS_PERCENT_SIGN,0,TRUE);
  3507.  
  3508.  
  3509.  
  3510.       Bypass display of dates, days or hours
  3511.       ──────────────────────────────────────
  3512.  
  3513.       On time based charts the developer can bypass any or all of the dates,
  3514.       days or hour information which is normally displayed.
  3515.  
  3516.  
  3517.       ChartSendMsg(hChart,CH_BYPASS_HOURS,0,TRUE);
  3518.                      or
  3519.       ChartSendMsg(hChart,CH_BYPASS_DAYS,0,TRUE);
  3520.                      or
  3521.       ChartSendMsg(hChart,CH_BYPASS_DATES,0,TRUE);
  3522.  
  3523.  
  3524.  
  3525.  
  3526.  
  3527.  
  3528.  
  3529.  
  3530.  
  3531.  
  3532.  
  3533.  
  3534.  
  3535.  
  3536.  
  3537.                                    58
  3538.  
  3539.  
  3540.  
  3541.       Query y or z-axis for tick control information
  3542.       ──────────────────────────────────────────────
  3543.  
  3544.       Either before or after a chart with a y-axis and possibly a z-axis has
  3545.       been displayed, the developer can request information about either of the
  3546.       axis values and detailed characteristics.  As a result of this call, a
  3547.       CHARTTICKS data structure will be returned indicating such items as the
  3548.       low value, high value, number of tick marks and the increment value for
  3549.       the scale in question.
  3550.  
  3551.  
  3552.       CHARTTICKS charttick;           // Local data structure
  3553.  
  3554.       ChartSendMsg(hChart,CH_QUERY_AXIS,CH_X_TICK,&charttick);
  3555.                      or
  3556.       ChartSendMsg(hChart,CH_QUERY_AXIS,CH_Z_TICK,&charttick);
  3557.                      or
  3558.       ChartSendMsg(hChart,CH_QUERY_AXIS,CH_Z_TICK,&charttick);
  3559.  
  3560.  
  3561.       Note:  This API only supports the x-axis for the CH_MATRIX chart.
  3562.       Further, charts such as pie or numeric tables which do not have either a
  3563.       y-axis or z-axis will not provide any data to the programmer.
  3564.  
  3565.  
  3566.  
  3567.       Set interval for x-axis text display
  3568.       ────────────────────────────────────
  3569.  
  3570.       Under some circumstances it may be desirable to skip displaying text
  3571.       under every x-axis tick mark.  The following example skips every other
  3572.       x-axis ticks before displaying another stream of text.  The third
  3573.       parameter specifies the number of tick marks to skip.
  3574.  
  3575.  
  3576.       ChartSendMsg(hChart,CH_X_AXIS_TEXT_SKIP,2,TRUE)
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.  
  3595.                                  59
  3596.  
  3597.  
  3598.  
  3599.       Use programmers presentation space or device context
  3600.       ────────────────────────────────────────────────────
  3601.  
  3602.       Under some circumstances the application programmer may have created
  3603.       their own drawing area (OS/2 presentation space or Windows device
  3604.       context).  This frequently happens when the programmer may require a
  3605.       special title on a sheet of paper for a printer or requires multiple
  3606.       charts on a single printer page.  To accomplish this task the application
  3607.       must acquire the handle to the space form the system and then notify the
  3608.       chart toolkit of their intention.  Under normal circumstance the toolkit
  3609.       creates its own presentation space prior to drawing a chart.  The third
  3610.       parameter is used to specify the handle of the programmers presentation
  3611.       space.  The fourth parameter is used only for OS/2 programmers and if
  3612.       TRUE requests that vector fonts be used instead of raster fonts.  To
  3613.       disable the function the programmer should supply a value of zero in the
  3614.       third parameter and recall the ChartSendMsg API once again.
  3615.  
  3616.  
  3617.       ChartSendMsg(hChart,CH_HPS,hps,FALSE);
  3618.  
  3619.  
  3620.       Force CH_TOUCH on output
  3621.       ────────────────────────
  3622.  
  3623.       When a chart is printed the charting toolkit does not disturb the
  3624.       internal tables which indicate where items have been drawn on the
  3625.       terminal display.  However, if it is necessary to maintain annotation
  3626.       texts or other items where location, this call will force the charting
  3627.       toolkit to record its drawing locations for the graphic items.  After the
  3628.       locations have been changed, it is the responsibility of the programmer
  3629.       to refresh the locations for the display if the end user is to maintain
  3630.       tactile feedback capabilities.
  3631.  
  3632.  
  3633.       ChartSendMsg(hChart,CH_FORCE_TOUCH,0,TRUE);
  3634.  
  3635.  
  3636.       Display line symbols in legend area
  3637.       ───────────────────────────────────
  3638.  
  3639.       Used generally with black and white printers, this message directs the
  3640.       charting toolkit to use the type of line associated with a group line
  3641.       type in the legend area of the display.  These short little lines are
  3642.       used instead of the colored squares normally associated with a legend for
  3643.       a line chart.
  3644.  
  3645.  
  3646.       ChartSendMsg(hChart,CH_LINE_LEGENDS,0,TRUE);
  3647.  
  3648.  
  3649.  
  3650.  
  3651.  
  3652.  
  3653.                                  60
  3654.  
  3655.  
  3656.  
  3657.       Use full chart width for line and scatter charts
  3658.       ────────────────────────────────────────────────
  3659.  
  3660.       For regular 2 dimension line, smooth line and scatter charts, the entire
  3661.       graphic area is not normally used.  If this space is required for use by
  3662.       the application program send the following message.
  3663.  
  3664.  
  3665.       ChartSendMsg(hChart,CH_LINE_FULL_WIDTH,0,TRUE);
  3666.  
  3667.  
  3668.  
  3669.       Display x-axis text between line points
  3670.       ───────────────────────────────────────
  3671.  
  3672.       Used only for 2 dimension line charts, this message request will place
  3673.       x-axis text information between the line points.  Under normal
  3674.       circumstances, the text is placed at the end points of a line segment.
  3675.       This request must be made in in conjunction with the CH_LINE_FULL_WIDTH
  3676.       send message command (reference the prior documentation).
  3677.  
  3678.       ChartSendMsg(hChart,CH_X_AXIS_TEXT_CENTER,0,TRUE);
  3679.  
  3680.  
  3681.  
  3682.       Display fractions on the y-axis
  3683.       ───────────────────────────────
  3684.  
  3685.       This function enables the application to display fractional values on the
  3686.       y-axis.  A example of this would be to increment the y-axis by 32nds of a
  3687.       whole number.  To accomplish this task use the following message.
  3688.  
  3689.  
  3690.       ChartSendMsg(hChart,CH_Y_TICK,CH_FRACTION_32,TRUE);
  3691.  
  3692.  
  3693.       The third parameter can contain any of the following parameters.
  3694.  
  3695.               CH_FRACTION_4
  3696.               CH_FRACTION_8
  3697.               CH_FRACTION_16
  3698.               CH_FRACTION_32
  3699.  
  3700.       These will display fourths, eights, sixteenths or thirty-second's of a
  3701.       whole number.
  3702.  
  3703.       This function will be added to the z-axis in the future.
  3704.  
  3705.  
  3706.  
  3707.  
  3708.  
  3709.  
  3710.  
  3711.                                  61
  3712.  
  3713.  
  3714.  
  3715.       Bypass automatic use of decimals on y and z axis
  3716.       ────────────────────────────────────────────────
  3717.  
  3718.       As the charting toolkit sometimes encounters very small values in the
  3719.       data to be show, the toolkit sometimes increments numbers by .25 or .10
  3720.       for example.  To insure that round numbers are instead, send the
  3721.       following message.
  3722.  
  3723.  
  3724.       ChartSendMsg(hChart,CH_YZ_BYPASS_DECIMAL,0,TRUE);
  3725.  
  3726.  
  3727.       Reset all data groups to the default color settings
  3728.       ───────────────────────────────────────────────────
  3729.  
  3730.       This function enables the application program to return to the charting
  3731.       color defaults for all groups after the ChartSetGroupColor API was
  3732.       issued.
  3733.  
  3734.  
  3735.       ChartSendMsg(hChart,CH_RESET_GROUP_COLORS,0,0);
  3736.  
  3737.  
  3738.  
  3739.       Set new minimum or maximum value for CH_X_PLOT chart
  3740.       ────────────────────────────────────────────────────
  3741.  
  3742.       The third and fourth parameter are used to set respectively a new low and
  3743.       or a new high values for the scaling area of the x-axis.
  3744.  
  3745.       The default value of 9.0 for the x-axis of the CH_X_PLOT chart type can
  3746.       be increased or decreased by sending the following message.
  3747.  
  3748.  
  3749.  
  3750.       static double new_x = (double) 30.0;
  3751.  
  3752.       ChartSendMsg(hChart,CH_X_PLOT,0,&new_x);
  3753.  
  3754.  
  3755.  
  3756.       In the above example the the value of 30.0 will replace the default value
  3757.       of 9.0.
  3758.  
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.                                  62
  3770.  
  3771.  
  3772.  
  3773.       Query font size used to display an item
  3774.       ───────────────────────────────────────
  3775.  
  3776.       This message request will return the size font used to display a chart
  3777.       item.  If a value of 0 is returned, the item being queried was not
  3778.       displayed.  Otherwise, this value should be 1 thru 6.
  3779.  
  3780.  
  3781.  
  3782.       static int FONT_SIZE;           // Location to receive answer
  3783.  
  3784.       ChartSendMsg(hChart,CH_QUERY_FONT_USED,CH_X_TICK_TEXT,&FONT_SIZE);
  3785.  
  3786.  
  3787.       The third parameter specifies the chart item being queried and must be
  3788.       one of the following.
  3789.  
  3790.  
  3791.               CH_X_TICK_TEXT
  3792.               CH_TITLE
  3793.               CH_LEGEND
  3794.  
  3795.  
  3796.  
  3797.  
  3798.  
  3799.  
  3800.  
  3801.  
  3802.  
  3803.  
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.  
  3824.  
  3825.  
  3826.  
  3827.                                  63
  3828.  
  3829.  
  3830.  
  3831.   ChartSendMsgVP - Send operational flags to charts
  3832.   ═════════════════════════════════════════════════
  3833.  
  3834.   This function provides another entry mechanism into the "ChartSendMsg" API.
  3835.   This is made available to minimize casting problems associated with some C++
  3836.   compilers.  The prototype for the API is as follows.
  3837.  
  3838.  
  3839.   ┌───────────────────────────────────────────────────────────────────────────┐
  3840.   │                                                                           │
  3841.   │   ans = ChartSendMsgVP(hchart,            // Chart handle                 │
  3842.   │                        msg_id,            // Message identifier           │
  3843.   │                        param1,            // Parameter 1                  │
  3844.   │                        param2);           // Parameter 2                  │
  3845.   │                                                                           │
  3846.   └───────────────────────────────────────────────────────────────────────────┘
  3847.  
  3848.  
  3849.   The "ChartSendMsgVP" function parameters are as follows:
  3850.  
  3851.   ans          Provides TRUE for a successful request or FALSE for an
  3852.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  3853.                the "error" code location specified in the "ChartCreate"
  3854.                function.
  3855.  
  3856.   hchart       Specifies the handle returned by the "ChartCreate" function.
  3857.   (HWND)
  3858.  
  3859.   msg_id       Specifies the function to be performed or the chart to direct
  3860.   (USHORT)     the message.
  3861.  
  3862.   param1       Specifies the first parameter of the message.
  3863.   (ULONG)
  3864.  
  3865.   param2       Specifies the second parameter of the message as a pointer.
  3866.   (PCH)
  3867.  
  3868.  
  3869.  
  3870.  
  3871.  
  3872.  
  3873.  
  3874.  
  3875.  
  3876.  
  3877.  
  3878.  
  3879.  
  3880.  
  3881.  
  3882.  
  3883.  
  3884.  
  3885.                                  64
  3886.  
  3887.  
  3888.  
  3889.   ChartSendMsgPV - Send operational flags to charts
  3890.   ═════════════════════════════════════════════════
  3891.  
  3892.   This function provides another entry mechanism into the "ChartSendMsg" API.
  3893.   This is made available to minimize casting problems associated with some C++
  3894.   compilers.  The prototype for the API is as follows.
  3895.  
  3896.  
  3897.   ┌───────────────────────────────────────────────────────────────────────────┐
  3898.   │                                                                           │
  3899.   │   ans = ChartSendMsgPV(hchart,            // Chart handle                 │
  3900.   │                        msg_id,            // Message identifier           │
  3901.   │                        param1,            // Parameter 1                  │
  3902.   │                        param2);           // Parameter 2                  │
  3903.   │                                                                           │
  3904.   └───────────────────────────────────────────────────────────────────────────┘
  3905.  
  3906.  
  3907.   The "ChartSendMsgPV" function parameters are as follows:
  3908.  
  3909.   ans          Provides TRUE for a successful request or FALSE for an
  3910.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  3911.                the "error" code location specified in the "ChartCreate"
  3912.                function.
  3913.  
  3914.   hchart       Specifies the handle returned by the "ChartCreate" function.
  3915.   (HWND)
  3916.  
  3917.   msg_id       Specifies the function to be performed or the chart to direct
  3918.   (USHORT)     the message.
  3919.  
  3920.   param1       Specifies the first parameter of the message as a pointer.
  3921.   (PCH)
  3922.  
  3923.   param2       Specifies the second parameter of the message.
  3924.   (LONG)
  3925.  
  3926.  
  3927.  
  3928.  
  3929.  
  3930.  
  3931.  
  3932.  
  3933.  
  3934.  
  3935.  
  3936.  
  3937.  
  3938.  
  3939.  
  3940.  
  3941.  
  3942.  
  3943.                                  65
  3944.  
  3945.  
  3946.  
  3947.   ChartSendMsgPP - Send operational flags to charts
  3948.   ═════════════════════════════════════════════════
  3949.  
  3950.   This function provides another entry mechanism into the "ChartSendMsg" API.
  3951.   This is made available to minimize casting problems associated with some C++
  3952.   compilers.  The prototype for the API is as follows.
  3953.  
  3954.  
  3955.   ┌───────────────────────────────────────────────────────────────────────────┐
  3956.   │                                                                           │
  3957.   │   ans = ChartSendMsgPP(hchart,            // Chart handle                 │
  3958.   │                        msg_id,            // Message identifier           │
  3959.   │                        param1,            // Parameter 1                  │
  3960.   │                        param2);           // Parameter 2                  │
  3961.   │                                                                           │
  3962.   └───────────────────────────────────────────────────────────────────────────┘
  3963.  
  3964.  
  3965.   The "ChartSendMsgPP" function parameters are as follows:
  3966.  
  3967.   ans          Provides TRUE for a successful request or FALSE for an
  3968.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  3969.                the "error" code location specified in the "ChartCreate"
  3970.                function.
  3971.  
  3972.   hchart       Specifies the handle returned by the "ChartCreate" function.
  3973.   (HWND)
  3974.  
  3975.   msg_id       Specifies the function to be performed or the chart to direct
  3976.   (USHORT)     the message.
  3977.  
  3978.   param1       Specifies the first parameter of the message as a pointer.
  3979.   (PCH)
  3980.  
  3981.   param2       Specifies the second parameter of the message as a pointer.
  3982.   (PCH)
  3983.  
  3984.  
  3985.  
  3986.  
  3987.  
  3988.  
  3989.  
  3990.  
  3991.  
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.                                  66
  4002.  
  4003.  
  4004.  
  4005.   ChartSetColor - Set the basic color for a chart item
  4006.   ════════════════════════════════════════════════════
  4007.  
  4008.   ChartSetColor(hchart,chart_item,color);
  4009.  
  4010.   This function sets chart characteristics (i.e. title text, chart border,
  4011.   graphic background) to one of eighteen color values.  The default color for
  4012.   all text and lines is the system default (contrast to background).
  4013.  
  4014.   NOTE: See "ChartSetGroupColor", "ChartSetRGB", and "ChartSetGroupRGB"
  4015.  
  4016.  
  4017.   ┌───────────────────────────────────────────────────────────────────────────┐
  4018.   │                                                                           │
  4019.   │   ans = ChartSetColor(hchart,           // Chart handle                   │
  4020.   │                       chart_item,       // Chart characteristic           │
  4021.   │                       color);           // Color                          │
  4022.   │                                                                           │
  4023.   └───────────────────────────────────────────────────────────────────────────┘
  4024.  
  4025.  
  4026.   The "ChartSetColor" function parameters are as follows:
  4027.  
  4028.   ans          Provides TRUE for a successful request or FALSE for an
  4029.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  4030.                the "error" code location specified in the "ChartCreate"
  4031.                function.
  4032.  
  4033.   hchart       Specifies the handle returned by the "ChartCreate" function.
  4034.   (HWND)
  4035.  
  4036.   chart_item   Specifies the major component to be affected.  These parameters
  4037.   (ULONG)      may be or-ed together.
  4038.  
  4039.                CH_FRAME          Specifies the frame area for the entire chart
  4040.                                  rectangle.
  4041.  
  4042.                CH_GRAPHIC_FRAME  Specifies the frame for the graphic display of
  4043.                                  the data.
  4044.  
  4045.                CH_GRAPHIC_WALL   Specifies the shadow box wall frame for 3D
  4046.                                  charts.
  4047.  
  4048.                CH_CLIENT         Specifies the area inside CH_FRAME.  The
  4049.                                  CH_CLIENT area is painted before the
  4050.                                  CH_GRAPHIC area.
  4051.  
  4052.                CH_GRAPHIC        Specifies the background area of the graphic
  4053.                                  data display.
  4054.  
  4055.                CH_TITLE          Specifies the title or heading text.
  4056.  
  4057.                CH_FOOTING        Specifies the footing text.
  4058.  
  4059.                                  67
  4060.  
  4061.  
  4062.  
  4063.                CH_LEFT_MARGIN    Specifies the left margin text.
  4064.  
  4065.                CH_RIGHT_MARGIN   Specifies the right margin text.
  4066.  
  4067.                CH_LEGEND         Specifies the legend text.
  4068.  
  4069.                CH_X_TICK         Specifies the vertical ticks on the bottom
  4070.                                  of the CH_GRAPHIC area for charts.
  4071.  
  4072.                CH_Y_TICK         Specifies the horizontal ticks on the left 
  4073.                                  side of the CH_GRAPHIC area for charts.
  4074.  
  4075.                CH_Z_TICK         Specifies the horizontal ticks on the right
  4076.                                  side of the CH_GRAPHIC area for charts.
  4077.  
  4078.                CH_X_TICK_TEXT    Specifies x-axis scaling text.
  4079.  
  4080.                CH_Y_TICK_TEXT    Specifies y-axis scaling text.
  4081.  
  4082.                CH_Z_TICK_TEXT    Specifies z-axis scaling text.
  4083.  
  4084.                CH_X_GRID         Specifies the vertical grid lines for the
  4085.                                  x-axis.
  4086.  
  4087.                CH_Y_GRID         Specifies the horizontal grid lines for the 
  4088.                                  y-axis.                                    
  4089.  
  4090.                CH_Z_GRID         Specifies the horizontal grid lines for the 
  4091.                                  z-axis.
  4092.  
  4093.                CH_SCOPE          Specifies the area represented by the
  4094.                                  "ChartSetNormalDataScope" API.
  4095.  
  4096.                CH_MINOR_GRID     Specifies the minor grid lines for time-
  4097.                                  based charts.
  4098.  
  4099.  
  4100.  
  4101.  
  4102.  
  4103.  
  4104.  
  4105.  
  4106.  
  4107.  
  4108.  
  4109.  
  4110.  
  4111.  
  4112.  
  4113.  
  4114.  
  4115.  
  4116.  
  4117.                                  68
  4118.  
  4119.  
  4120.  
  4121.   color        Specifies one of the eighteen color values.
  4122.   (LONG)
  4123.  
  4124.                CLR_WHITE                        
  4125.                CLR_BLACK                        
  4126.                CLR_BACKGROUND                   
  4127.                CLR_NEUTRAL                      
  4128.        
  4129.                CLR_BLUE              CLR_DARKBLUE     
  4130.                CLR_RED               CLR_DARKRED      
  4131.                CLR_PINK              CLR_DARKPINK     
  4132.                CLR_GREEN             CLR_DARKGREEN    
  4133.                CLR_CYAN              CLR_DARKCYAN     
  4134.                CLR_YELLOW            CLR_BROWN        
  4135.                CLR_PALEGRAY          CLR_DARKGRAY
  4136.  
  4137.  
  4138.   ┌───────────────────────────────────────────────────────────────────────────┐
  4139.   │                                                                           │
  4140.   │  Error codes     Chart_not_defined        2                               │
  4141.   │                  Chart_invalid_color      4                               │
  4142.   │                  Chart_invalid_parameter  5                               │
  4143.   │                                                                           │
  4144.   └───────────────────────────────────────────────────────────────────────────┘
  4145.  
  4146.  
  4147.   The following illustrates setting the title and graphic area to the darkgray
  4148.   color.
  4149.  
  4150.  
  4151.   ┌───────────────────────────────────────────────────────────────────────────┐
  4152.   │                                                                           │
  4153.   │  BOOL            fAns;                   // Successful call indicator     │
  4154.   │  static HWND     hChart;                 // Bar chart handle              │
  4155.   │                                                                           │
  4156.   │                                                                           │
  4157.   │  fAns = ChartSetColor(hChart,            // Chart handle                  │
  4158.   │                       CH_GRAPHIC |       // Total graphic area            │
  4159.   │                       CH_TITLE,          // Chart title text              │
  4160.   │                       CLR_DARKGRAY);     // Basic color                   │
  4161.   │                                                                           │
  4162.   └───────────────────────────────────────────────────────────────────────────┘
  4163.  
  4164.  
  4165.  
  4166.  
  4167.  
  4168.  
  4169.  
  4170.  
  4171.  
  4172.  
  4173.  
  4174.  
  4175.                                  69
  4176.  
  4177.  
  4178.  
  4179.   ChartSetColorTable - Set the colors for the numeric and symbol tables
  4180.   ═════════════════════════════════════════════════════════════════════
  4181.  
  4182.   This function sets the color representation for the numeric and symbol 
  4183.   tables.  A data point is compared against a range_data array to determine the
  4184.   color of the data.  The comparison proceeds until a match is found (= or <) 
  4185.   or the end of the array is encountered.  If no match is found, the default 
  4186.   color will be used.  The values in the range_data can also determine the 
  4187.   characteristics or symbols to be displayed in a symbol chart.
  4188.    
  4189.   This function is operational and is described only in the full function
  4190.   product.
  4191.  
  4192.  
  4193.  
  4194.  
  4195.  
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.  
  4220.  
  4221.  
  4222.  
  4223.  
  4224.  
  4225.  
  4226.  
  4227.  
  4228.  
  4229.  
  4230.  
  4231.  
  4232.  
  4233.                                  70
  4234.  
  4235.  
  4236.  
  4237.   ChartSetCountryCode - Set language translation
  4238.   ══════════════════════════════════════════════
  4239.  
  4240.   This function enables the automatically generated text to be translated into 
  4241.   a language supported by the graphics DLL.  This function request will also
  4242.   provide for currency symbols and other selected items.
  4243.   
  4244.  
  4245.   ┌───────────────────────────────────────────────────────────────────────────┐
  4246.   │                                                                           │
  4247.   │   ans = ChartSetCountryCode(hChart,           // Chart handle             │
  4248.   │                             country);         // Country numeric value    │
  4249.   │                                                                           │
  4250.   └───────────────────────────────────────────────────────────────────────────┘
  4251.  
  4252.  
  4253.   The "ChartSetCountryCode" function parameters are as follows:
  4254.  
  4255.   ans          Provides TRUE for a successful request or FALSE for an
  4256.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  4257.                the "error" code location specified in the "ChartCreate"
  4258.                function.
  4259.  
  4260.   hchart       Specifies the handle returned by the "ChartCreate" function.
  4261.   (HWND)
  4262.  
  4263.   country      Specifies the numeric value of the country for the language
  4264.   (USHORT)     translation.  (Consult the operating system documentation for
  4265.                country numeric values.)
  4266.  
  4267.                 1    English      (Default)
  4268.                33    French
  4269.                34    Spanish
  4270.                39    Italian
  4271.                46    Swedish
  4272.                49    German
  4273.                81    Japanese Kanji
  4274.               358    Finish
  4275.              7000    Russia
  4276.  
  4277.   ┌───────────────────────────────────────────────────────────────────────────┐
  4278.   │                                                                           │
  4279.   │  Error codes     NONE                                                     │
  4280.   │                                                                           │
  4281.   │                  Retains current setting when unsupported value is given. │
  4282.   │                                                                           │
  4283.   └───────────────────────────────────────────────────────────────────────────┘
  4284.  
  4285.  
  4286.  
  4287.  
  4288.  
  4289.  
  4290.  
  4291.                                  71
  4292.  
  4293.  
  4294.  
  4295.   The following illustrates setting the German automatically generating text
  4296.   translation and NLS.
  4297.  
  4298.  
  4299.   ┌───────────────────────────────────────────────────────────────────────────┐
  4300.   │                                                                           │
  4301.   │  BOOL            fAns;                   // Successful call indicator     │
  4302.   │  static HWND     hChart;                 // Bar chart handle              │
  4303.   │                                                                           │
  4304.   │                                                                           │
  4305.   │  fAns = ChartSetColor(hChart,            // Chart handle                  │
  4306.   │                       49);               // German language value         │
  4307.   │                                                                           │
  4308.   └───────────────────────────────────────────────────────────────────────────┘
  4309.  
  4310.  
  4311.  
  4312.  
  4313.  
  4314.  
  4315.  
  4316.  
  4317.  
  4318.  
  4319.  
  4320.  
  4321.  
  4322.  
  4323.  
  4324.  
  4325.  
  4326.  
  4327.  
  4328.  
  4329.  
  4330.  
  4331.  
  4332.  
  4333.  
  4334.  
  4335.  
  4336.  
  4337.  
  4338.  
  4339.  
  4340.  
  4341.  
  4342.  
  4343.  
  4344.  
  4345.  
  4346.  
  4347.  
  4348.  
  4349.                                  72
  4350.  
  4351.  
  4352.  
  4353.   ChartSetDimensions - Set visual dimensions of a chart
  4354.   ═════════════════════════════════════════════════════
  4355.  
  4356.   ChartSetDimensions(hchart,dimensions);
  4357.  
  4358.   This function changes the visual appearance of the graphic to be
  4359.   displayed.  The result will be a two dimension (2D) or three dimension (3D)
  4360.   chart.
  4361.  
  4362.  
  4363.   ┌───────────────────────────────────────────────────────────────────────────┐
  4364.   │                                                                           │
  4365.   │   ans = ChartSetDimensions(hChart,             // Chart handle            │
  4366.   │                            dimensions);        // Chart dimensions        │
  4367.   │                                                                           │
  4368.   └───────────────────────────────────────────────────────────────────────────┘
  4369.  
  4370.  
  4371.   The "ChartSetDimensions" function parameters are as follows:
  4372.  
  4373.   ans          Provides TRUE for a successful request or FALSE for an
  4374.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  4375.                the "error" code location specified in the "ChartCreate"
  4376.                function.
  4377.  
  4378.   hchart       Specifies the handle returned by the "ChartCreate" function.
  4379.   (HWND)
  4380.  
  4381.   dimension    Specifies a value of 2 or 3 to indicate either a 2D or 3D chart
  4382.   (USHORT)     to be displayed.
  4383.  
  4384.  
  4385.   ┌───────────────────────────────────────────────────────────────────────────┐
  4386.   │                                                                           │
  4387.   │  Error codes     Chart_invalid_dimensions   10                            │
  4388.   │                                                                           │
  4389.   └───────────────────────────────────────────────────────────────────────────┘
  4390.  
  4391.  
  4392.   The following illustrates setting a chart for 2 dimensions.
  4393.  
  4394.  
  4395.   ┌───────────────────────────────────────────────────────────────────────────┐
  4396.   │                                                                           │
  4397.   │  BOOL            fAns;                   // Successful call indicator     │
  4398.   │  static HWND     hChart;                 // Bar chart handle              │
  4399.   │                                                                           │
  4400.   │                                                                           │
  4401.   │  fAns = ChartSetDimensions(hChart,       // Chart handle                  │
  4402.   │                            2);           // 2 dimensions                  │
  4403.   │                                                                           │
  4404.   └───────────────────────────────────────────────────────────────────────────┘
  4405.  
  4406.  
  4407.                                  73
  4408.  
  4409.  
  4410.  
  4411.   ChartSetFont - Change the font name and point size
  4412.   ══════════════════════════════════════════════════
  4413.  
  4414.   This function changes the name of the font used in the chart to be displayed,
  4415.   printed, directed to a metafile or sent to the clipboard.  The API is a 
  4416.   pointer to a data structure containing the control information for font 
  4417.   typefaces and point sizes.  The system supported typefaces are used with a 
  4418.   maximum of six point sizes.  The six point sizes must be specified with the 
  4419.   smallest point size first and proceeding in ascending order.
  4420.    
  4421.   This function is operational and is described only in the full function
  4422.   product.
  4423.  
  4424.  
  4425.  
  4426.  
  4427.  
  4428.  
  4429.  
  4430.  
  4431.  
  4432.  
  4433.  
  4434.   ChartSetFrame - Place a frame around entire chart area
  4435.   ══════════════════════════════════════════════════════
  4436.  
  4437.   ChartSetFrame(hchart,visible);
  4438.  
  4439.   This function paints or removes a border surrounding the entire chart. The
  4440.   ability to paint a frame or border is provided to isolate the chart from
  4441.   other application data elements present in a window.
  4442.  
  4443.   This function is operational and is described only in the full function
  4444.   product.
  4445.  
  4446.  
  4447.  
  4448.  
  4449.  
  4450.  
  4451.  
  4452.  
  4453.  
  4454.  
  4455.  
  4456.  
  4457.  
  4458.  
  4459.  
  4460.  
  4461.  
  4462.  
  4463.  
  4464.  
  4465.                                  74
  4466.  
  4467.  
  4468.  
  4469.   ChartSetGroupColor - Set the basic color for a data group
  4470.   ═════════════════════════════════════════════════════════
  4471.  
  4472.   This function sets a data group to one of eight basic colors and eight
  4473.   shades.  Both light and dark colors are used for foreground elements,
  4474.   with darker colors used for dimension shading.  2D charts, except line,
  4475.   smooth line and scatter charts, will be displayed in light colors.  The
  4476.   line, smooth line and scatter charts will be displayed in darker shades.
  4477.  
  4478.  
  4479.   ┌───────────────────────────────────────────────────────────────────────────┐
  4480.   │                                                                           │
  4481.   │   ans = ChartSetGroupColor(hchart,              // Chart handle           │
  4482.   │                            group,               // Group number           │
  4483.   │                            color);              // Group color            │
  4484.   │                                                                           │
  4485.   └───────────────────────────────────────────────────────────────────────────┘
  4486.  
  4487.  
  4488.   The "ChartSetGroupColor" function parameters are as follows:
  4489.  
  4490.   ans          Provides TRUE for a successful request or FALSE for an
  4491.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  4492.                the "error" code location specified in the "ChartCreate"
  4493.                function.
  4494.  
  4495.   hchart       Specifies the handle returned by the "ChartCreate" function.
  4496.   (HWND)
  4497.  
  4498.   group        Specifies the number of the data group that will be displayed.
  4499.   (USHORT)     This number must range between 1 and 12.
  4500.  
  4501.   color        Specifies one of the eight basic color values.
  4502.   (SHORT)
  4503.  
  4504.                   CLR_RED
  4505.                   CLR_GREEN 
  4506.                   CLR_BLUE
  4507.                   CLR_YELLOW
  4508.                   CLR_DARKGRAY
  4509.                   CLR_CYAN         
  4510.                   CLR_PINK         
  4511.                   CLR_PALEGRAY     
  4512.  
  4513.  
  4514.  
  4515.  
  4516.  
  4517.  
  4518.  
  4519.  
  4520.  
  4521.  
  4522.  
  4523.                                  75
  4524.  
  4525.  
  4526.  
  4527.   ┌───────────────────────────────────────────────────────────────────────────┐
  4528.   │                                                                           │
  4529.   │  Error codes     Chart_invalid_color      4                               │
  4530.   │                  Chart_invalid_group      8                               │
  4531.   │                                                                           │
  4532.   └───────────────────────────────────────────────────────────────────────────┘
  4533.  
  4534.  
  4535.   The following illustrates setting data group 2 to the cyan color.
  4536.  
  4537.  
  4538.   ┌───────────────────────────────────────────────────────────────────────────┐
  4539.   │                                                                           │
  4540.   │  BOOL            fAns;                   // Successful call indicator     │
  4541.   │  static HWND     hChart;                 // Bar chart handle              │
  4542.   │                                                                           │
  4543.   │                                                                           │
  4544.   │  fAns = ChartSetColor(hChart,            // Chart handle                  │
  4545.   │                       2,                 // Group number                  │
  4546.   │                       (SHORT)CLR_CYAN);  // Basic color                   │
  4547.   │                                                                           │
  4548.   └───────────────────────────────────────────────────────────────────────────┘
  4549.  
  4550.  
  4551.  
  4552.  
  4553.  
  4554.  
  4555.  
  4556.  
  4557.  
  4558.  
  4559.  
  4560.  
  4561.  
  4562.  
  4563.  
  4564.  
  4565.  
  4566.  
  4567.  
  4568.  
  4569.  
  4570.  
  4571.  
  4572.  
  4573.  
  4574.  
  4575.  
  4576.  
  4577.  
  4578.  
  4579.  
  4580.  
  4581.                                  76
  4582.  
  4583.  
  4584.  
  4585.   ChartSetGroupCount - Set number of data groups to display
  4586.   ═════════════════════════════════════════════════════════
  4587.  
  4588.   This function sets the number of data groups displayed in a chart.  This 
  4589.   function should be used after "ChartCreate" to change the number of data 
  4590.   groups specified.
  4591.  
  4592.  
  4593.   ┌───────────────────────────────────────────────────────────────────────────┐
  4594.   │                                                                           │
  4595.   │   ans = ChartSetGroupCount(hchart,          // Chart handle               │
  4596.   │                            groups);         // Data groups for chart      │
  4597.   │                                                                           │
  4598.   └───────────────────────────────────────────────────────────────────────────┘
  4599.  
  4600.  
  4601.   The "ChartSetGroupCount" function parameters are as follows:
  4602.  
  4603.   ans          Provides TRUE for a successful request or FALSE for an
  4604.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  4605.                the "error" code location specified in the "ChartCreate"
  4606.                function.
  4607.  
  4608.   hchart       Specifies the handle returned by the "ChartCreate" function.
  4609.   (HWND)
  4610.  
  4611.   groups       Specifies the number of the data group that will be displayed.
  4612.   (USHORT)     This number must range between 1 and 12.
  4613.  
  4614.  
  4615.   ┌───────────────────────────────────────────────────────────────────────────┐
  4616.   │                                                                           │
  4617.   │  Error codes     Chart_invalid_group      8                               │
  4618.   │                                                                           │
  4619.   └───────────────────────────────────────────────────────────────────────────┘
  4620.  
  4621.  
  4622.   The following illustrates changing an existing data group specification to 4 
  4623.   groups
  4624.  
  4625.  
  4626.   ┌───────────────────────────────────────────────────────────────────────────┐
  4627.   │                                                                           │
  4628.   │  BOOL            fAns;                   // Successful call indicator     │
  4629.   │  static HWND     hChart;                 // Bar chart handle              │
  4630.   │                                                                           │
  4631.   │                                                                           │
  4632.   │  fAns = ChartSetGroupCount(hChart,       // Chart handle                  │
  4633.   │                            4);           // 4 data groups                 │
  4634.   │                                                                           │
  4635.   └───────────────────────────────────────────────────────────────────────────┘
  4636.  
  4637.  
  4638.  
  4639.                                  77
  4640.  
  4641.  
  4642.  
  4643.   ChartSetGroupLineType - Set a data group lines to a pattern
  4644.   ═══════════════════════════════════════════════════════════
  4645.  
  4646.   ChartSetGroupLineType(hchart,group,pattern);
  4647.  
  4648.   This function sets the line pattern for a specific data group.  
  4649.  
  4650.  
  4651.   ┌───────────────────────────────────────────────────────────────────────────┐
  4652.   │                                                                           │
  4653.   │   ans = ChartSetGroupLineType(hchart,       // Chart handle               │
  4654.   │                               group,        // Data group number          │
  4655.   │                               pattern);     // Line pattern               │
  4656.   │                                                                           │
  4657.   └───────────────────────────────────────────────────────────────────────────┘
  4658.  
  4659.  
  4660.   The "ChartSetGroupLineType" function parameters are as follows:
  4661.  
  4662.   ans          Provides TRUE for a successful request or FALSE for an
  4663.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  4664.                the "error" code location specified in the "ChartCreate"
  4665.                function.
  4666.  
  4667.   hchart       Specifies the handle returned by the "ChartCreate" function.
  4668.   (HWND)
  4669.  
  4670.   groups       Specifies the number of the data group that will be displayed.
  4671.   (USHORT)     This number must range between 1 and 12.
  4672.  
  4673.   pattern      Specifies the line type attribute.
  4674.   (LONG)
  4675.  
  4676.                LINETYPE_DEFAULT       ────────────
  4677.                LINETYPE_DOT           ............
  4678.                LINETYPE_SHORTDASH     ------------
  4679.                LINETYPE_DASHDOT       -.-.-.-.-.-.
  4680.                LINETYPE_DOUBLEDOT     .. .. .. ..
  4681.                LINETYPE_LONGDASH      ── ── ── ──
  4682.                LINETYPE_DASHDOUBLEDOT -..-..-..-..
  4683.                LINETYPE_SOLID         ────────────
  4684.  
  4685.  
  4686.   ┌───────────────────────────────────────────────────────────────────────────┐
  4687.   │                                                                           │
  4688.   │  Error codes     Chart_invalid_group         8                            │
  4689.   │                  Chart_invalid_line_type    17                            │
  4690.   │                                                                           │
  4691.   └───────────────────────────────────────────────────────────────────────────┘
  4692.  
  4693.  
  4694.  
  4695.  
  4696.  
  4697.                                  78
  4698.  
  4699.  
  4700.  
  4701.   The following illustrates setting data group 2 to a line type of long dashes.
  4702.  
  4703.  
  4704.   ┌───────────────────────────────────────────────────────────────────────────┐
  4705.   │                                                                           │
  4706.   │  BOOL            fAns;                   // Successful call indicator     │
  4707.   │  static HWND     hChart;                 // Line chart handle             │
  4708.   │                                                                           │
  4709.   │                                                                           │
  4710.   │  fAns = ChartSetGroupLineType(hChart,          // Chart handle            │
  4711.   │                               2,               // Group 2                 │
  4712.   │                               LINETYPE_LONGDASH); // ── ── Long dash lines│
  4713.   │                                                                           │
  4714.   └───────────────────────────────────────────────────────────────────────────┘
  4715.  
  4716.  
  4717.  
  4718.  
  4719.  
  4720.  
  4721.  
  4722.  
  4723.  
  4724.  
  4725.  
  4726.  
  4727.  
  4728.  
  4729.  
  4730.  
  4731.  
  4732.  
  4733.  
  4734.  
  4735.  
  4736.  
  4737.  
  4738.  
  4739.  
  4740.  
  4741.  
  4742.  
  4743.  
  4744.  
  4745.  
  4746.  
  4747.  
  4748.  
  4749.  
  4750.  
  4751.  
  4752.  
  4753.  
  4754.  
  4755.                                  79
  4756.  
  4757.  
  4758.  
  4759.   ChartSetGroupMarker - Set scatter and line chart marker for group
  4760.   ═════════════════════════════════════════════════════════════════
  4761.  
  4762.  
  4763.   This function sets a marker symbol for a specific data group.  The
  4764.   default marker symbol for all data groups is a solid diamond.
  4765.  
  4766.  
  4767.   ┌───────────────────────────────────────────────────────────────────────────┐
  4768.   │                                                                           │
  4769.   │   ans = ChartSetGroupMarker(hchart,       // Chart handle                 │
  4770.   │                             group,        // Data group number            │
  4771.   │                             marker);      // Marker type                  │
  4772.   │                                                                           │
  4773.   └───────────────────────────────────────────────────────────────────────────┘
  4774.  
  4775.  
  4776.   The "ChartSetGroupMarker" function parameters are as follows:
  4777.  
  4778.   ans          Provides TRUE for a successful request or FALSE for an
  4779.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  4780.                the "error" code location specified in the "ChartCreate"
  4781.                function.
  4782.  
  4783.   hchart       Specifies the handle returned by the "ChartCreate" function.
  4784.   (HWND)
  4785.  
  4786.   group        Specifies the number of the data group that will be displayed.
  4787.   (USHORT)     This number must range between 1 and 12.
  4788.  
  4789.   marker       Specifies the marker symbol attribute.
  4790.   (LONG)
  4791.                MARKSYM_DEFAULT       
  4792.                MARKSYM_CROSS         
  4793.                MARKSYM_PLUS          
  4794.                MARKSYM_DIAMOND       
  4795.                MARKSYM_SQUARE        
  4796.                MARKSYM_SIXPOINTSTAR  
  4797.                MARKSYM_EIGHTPOINTSTAR
  4798.                MARKSYM_SOLIDDIAMOND  
  4799.                MARKSYM_SOLIDSQUARE   
  4800.                MARKSYM_DOT           
  4801.                MARKSYM_SMALLCIRCLE   
  4802.                MARKSYM_TRIANGLEUP       
  4803.                MARKSYM_TRIANGLEDOWN     
  4804.                MARKSYM_SOLIDTRIANGLEUP  
  4805.                MARKSYM_SOLIDTRIANGLEDOWN
  4806.                MARKSYM_LARGECIRCLE      
  4807.                MARKSYM_DOCUMENT         
  4808.                MARKSYM_NULL             
  4809.  
  4810.  
  4811.  
  4812.  
  4813.                                  80
  4814.  
  4815.  
  4816.  
  4817.   ┌───────────────────────────────────────────────────────────────────────────┐
  4818.   │                                                                           │
  4819.   │  Error codes     Chart_invalid_group         8                            │
  4820.   │                  Chart_invalid_marker       16                            │
  4821.   │                                                                           │
  4822.   └───────────────────────────────────────────────────────────────────────────┘
  4823.  
  4824.  
  4825.   The following illustrates setting data group two with a solid square marker
  4826.   type.
  4827.  
  4828.  
  4829.   ┌───────────────────────────────────────────────────────────────────────────┐
  4830.   │                                                                           │
  4831.   │  BOOL            fAns;                   // Successful call indicator     │
  4832.   │  static HWND     hChart;                 // Scatter chart handle          │
  4833.   │                                                                           │
  4834.   │                                                                           │
  4835.   │  fAns = ChartSetGroupMarker(hChart,               // Chart handle         │
  4836.   │                             2,                    // Group 2              │
  4837.   │                             MARKSYM_SOLIDSQUARE); // Solid square         │
  4838.   │                                                                           │
  4839.   └───────────────────────────────────────────────────────────────────────────┘
  4840.  
  4841.  
  4842.  
  4843.  
  4844.  
  4845.  
  4846.  
  4847.  
  4848.  
  4849.  
  4850.  
  4851.  
  4852.  
  4853.  
  4854.  
  4855.  
  4856.  
  4857.  
  4858.  
  4859.  
  4860.  
  4861.  
  4862.  
  4863.  
  4864.  
  4865.  
  4866.  
  4867.  
  4868.  
  4869.  
  4870.  
  4871.                                  81
  4872.  
  4873.  
  4874.  
  4875.   ChartSetGroupPattern - Assign a pattern for a group
  4876.   ═══════════════════════════════════════════════════
  4877.  
  4878.   ChartSetGroupPattern(hchart,group,pattern,overlay,color);
  4879.  
  4880.   This function specifies a data group to be displayed using a pattern
  4881.  
  4882.   This function is operational and is described only in the full function
  4883.   product.
  4884.  
  4885.  
  4886.  
  4887.  
  4888.  
  4889.  
  4890.  
  4891.  
  4892.  
  4893.  
  4894.  
  4895.  
  4896.  
  4897.  
  4898.  
  4899.  
  4900.   ChartSetGroupRGB - Set the RGB colors for a data group
  4901.   ══════════════════════════════════════════════════════
  4902.  
  4903.   ChartSetGroupRGB(hchart,group,rgb1,rgb2);
  4904.  
  4905.   This function sets a data group's RGB color values.
  4906.  
  4907.   This function is operational and is described only in the full function
  4908.   product.
  4909.  
  4910.  
  4911.  
  4912.  
  4913.  
  4914.  
  4915.  
  4916.  
  4917.  
  4918.  
  4919.  
  4920.  
  4921.  
  4922.  
  4923.  
  4924.  
  4925.  
  4926.  
  4927.  
  4928.  
  4929.                                  82
  4930.  
  4931.  
  4932.  
  4933.   ChartSetGroupStyle - Assign data group to chart style
  4934.   ═════════════════════════════════════════════════════
  4935.  
  4936.   This function is used in conjunction with either the CH_X_PLOT or CH_MIXED
  4937.   chart types.  Its function is to assign a specific data group to a specific
  4938.   graphic style.
  4939.  
  4940.  
  4941.   ┌───────────────────────────────────────────────────────────────────────────┐
  4942.   │                                                                           │
  4943.   │   ans = ChartSetGroupStyle(hchart,        // Chart handle                 │
  4944.   │                            group,         // Data group number            │
  4945.   │                            style,         // Group style                  │
  4946.   │                            options);      // Style options                │
  4947.   │                                                                           │
  4948.   └───────────────────────────────────────────────────────────────────────────┘
  4949.  
  4950.  
  4951.   The "ChartSetGroupStyle" function parameters are as follows:
  4952.  
  4953.   ans          Provides TRUE for a successful request or FALSE for an
  4954.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  4955.                the "error" code location specified in the "ChartCreate"
  4956.                function.
  4957.  
  4958.   hchart       Specifies the handle returned by the "ChartCreate" function.
  4959.   (HWND)
  4960.  
  4961.   group        Specifies the number of the data group that will be displayed.
  4962.   (USHORT)     This number must range between 1 and 12.
  4963.  
  4964.   style        Specifies the type of graphic style for the group being
  4965.   (USHORT)     assigned.  Valid assignments are as follows.
  4966.  
  4967.                     CH_SCATTER
  4968.                     CH_LINE
  4969.                     CH_SPIKE
  4970.                     CH_SQUARE_WAVE
  4971.                     CH_AREA
  4972.                     CH_RANGE
  4973.  
  4974.   options      Specifies options for the style parameter.  For the CH_SCATTER
  4975.   (ULONG)      style specification, this parameter specifies the type of marker
  4976.                symbol to be used.  For the CH_LINE style specification, this
  4977.                parameter specifies the type of line to be used (i.e. dots).
  4978.  
  4979.   NOTE:  This API can also be used with the CH_BAR_GOAL chart type.  The only
  4980.   style parameter which can be provided is CH_LINE.  This will enable the chart
  4981.   to have multiple lines.  To control the type of line displayed as either a
  4982.   stright line or a square wave (default) the ChartSendMsg API may be required.
  4983.  
  4984.  
  4985.  
  4986.  
  4987.                                  83
  4988.  
  4989.  
  4990.  
  4991.   ┌───────────────────────────────────────────────────────────────────────────┐
  4992.   │                                                                           │
  4993.   │  Error codes     Chart_invalid_chart_type   15                            │
  4994.   │                                                                           │
  4995.   └───────────────────────────────────────────────────────────────────────────┘
  4996.  
  4997.  
  4998.  
  4999.  
  5000.  
  5001.  
  5002.  
  5003.  
  5004.  
  5005.  
  5006.  
  5007.  
  5008.  
  5009.  
  5010.  
  5011.  
  5012.  
  5013.  
  5014.  
  5015.  
  5016.  
  5017.  
  5018.  
  5019.  
  5020.  
  5021.  
  5022.  
  5023.  
  5024.  
  5025.  
  5026.  
  5027.  
  5028.  
  5029.  
  5030.  
  5031.  
  5032.  
  5033.  
  5034.  
  5035.  
  5036.  
  5037.  
  5038.  
  5039.  
  5040.  
  5041.  
  5042.  
  5043.  
  5044.  
  5045.                                  84
  5046.  
  5047.  
  5048.  
  5049.   ChartSetLineType - Set chart lines for all groups to a pattern
  5050.   ══════════════════════════════════════════════════════════════
  5051.  
  5052.  
  5053.   This function sets the pattern for all data groups. The default line type is
  5054.   a solid line for all data groups.
  5055.  
  5056.   NOTE: See "ChartSetGroupLineType".
  5057.  
  5058.  
  5059.   ┌───────────────────────────────────────────────────────────────────────────┐
  5060.   │                                                                           │
  5061.   │   ans = ChartSetLineType(hchart,            // Chart handle               │
  5062.   │                          pattern);          // Line pattern               │
  5063.   │                                                                           │
  5064.   └───────────────────────────────────────────────────────────────────────────┘
  5065.  
  5066.  
  5067.   The "ChartSetLineType" function parameters are as follows:
  5068.  
  5069.   ans          Provides TRUE for a successful request or FALSE for an
  5070.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  5071.                the "error" code location specified in the "ChartCreate"
  5072.                function.
  5073.  
  5074.   hchart       Specifies the handle returned by the "ChartCreate" function.
  5075.   (HWND)
  5076.  
  5077.   pattern      Specifies the line type attribute.
  5078.   (LONG)
  5079.  
  5080.                LINETYPE_DEFAULT       ────────────
  5081.                LINETYPE_DOT           ............
  5082.                LINETYPE_SHORTDASH     ------------
  5083.                LINETYPE_DASHDOT       -.-.-.-.-.-.
  5084.                LINETYPE_DOUBLEDOT     .. .. .. ..
  5085.                LINETYPE_LONGDASH      ── ── ── ──
  5086.                LINETYPE_DASHDOUBLEDOT -..-..-..-..
  5087.                LINETYPE_SOLID         ────────────
  5088.  
  5089.  
  5090.   ┌───────────────────────────────────────────────────────────────────────────┐
  5091.   │                                                                           │
  5092.   │  Error codes     Chart_invalid_line_type    17                            │
  5093.   │                                                                           │
  5094.   └───────────────────────────────────────────────────────────────────────────┘
  5095.  
  5096.  
  5097.  
  5098.  
  5099.  
  5100.  
  5101.  
  5102.  
  5103.                                  85
  5104.  
  5105.  
  5106.  
  5107.   The following illustrates setting the line type to short dashes for all data 
  5108.   groups.
  5109.  
  5110.  
  5111.   ┌───────────────────────────────────────────────────────────────────────────┐
  5112.   │                                                                           │
  5113.   │  BOOL            fAns;                   // Successful call indicator     │
  5114.   │  static HWND     hChart;                 // Line chart handle             │
  5115.   │                                                                           │
  5116.   │                                                                           │
  5117.   │  fAns = ChartSetLineType(hChart,                // Chart handle           │
  5118.   │                          LINETYPE_SHORTDASH);   // - - - Short dash lines │
  5119.   │                                                                           │
  5120.   └───────────────────────────────────────────────────────────────────────────┘
  5121.  
  5122.  
  5123.  
  5124.  
  5125.  
  5126.  
  5127.  
  5128.  
  5129.  
  5130.  
  5131.  
  5132.  
  5133.  
  5134.  
  5135.  
  5136.  
  5137.  
  5138.  
  5139.  
  5140.  
  5141.  
  5142.  
  5143.  
  5144.  
  5145.  
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.  
  5153.  
  5154.  
  5155.  
  5156.  
  5157.  
  5158.  
  5159.  
  5160.  
  5161.                                  86
  5162.  
  5163.  
  5164.  
  5165.   ChartSetLineWidth - Set line chart width
  5166.   ════════════════════════════════════════
  5167.  
  5168.  
  5169.   This function sets the data group pixel line width for straight line and
  5170.   smooth line charts.  The default line width is 2 pixels.  (applicable to 2D 
  5171.   lines only);
  5172.  
  5173.  
  5174.   ┌───────────────────────────────────────────────────────────────────────────┐
  5175.   │                                                                           │
  5176.   │   ans = ChartSetLineWidth(hchart,           // Chart handle               │
  5177.   │                           width);           // Pixel line width           │
  5178.   │                                                                           │
  5179.   └───────────────────────────────────────────────────────────────────────────┘
  5180.  
  5181.  
  5182.   The "ChartSetLineWidth" function parameters are as follows:
  5183.  
  5184.   ans          Provides TRUE for a successful request or FALSE for an
  5185.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  5186.                the "error" code location specified in the "ChartCreate"
  5187.                function.
  5188.  
  5189.   hchart       Specifies the handle returned by the "ChartCreate" function.
  5190.   (HWND)
  5191.  
  5192.   width        Specifies the line width in pixels.  All values above 15 will 
  5193.   (LONG)       default to 15.
  5194.  
  5195.  
  5196.   ┌───────────────────────────────────────────────────────────────────────────┐
  5197.   │                                                                           │
  5198.   │  Error codes     NONE                                                     │
  5199.   │                                                                           │
  5200.   └───────────────────────────────────────────────────────────────────────────┘
  5201.  
  5202.  
  5203.   The following illustrates setting the line width to 3 pixels.
  5204.  
  5205.  
  5206.   ┌───────────────────────────────────────────────────────────────────────────┐
  5207.   │                                                                           │
  5208.   │  BOOL            fAns;                   // Successful call indicator     │
  5209.   │  static HWND     hChart;                 // Line chart handle             │
  5210.   │                                                                           │
  5211.   │                                                                           │
  5212.   │  fAns = ChartSetLineWidth(hChart,         // Chart handle                 │
  5213.   │                           3L);            // 3 pixels wide                │
  5214.   │                                                                           │
  5215.   └───────────────────────────────────────────────────────────────────────────┘
  5216.  
  5217.  
  5218.  
  5219.                                  87
  5220.  
  5221.  
  5222.  
  5223.   ChartSetMarker - Set scatter and line chart markers
  5224.   ═══════════════════════════════════════════════════
  5225.  
  5226.   ChartSetMarker(hchart,marker);
  5227.  
  5228.   This function sets a marker symbol for all of the data groups.
  5229.  
  5230.   NOTE: This will reset all previous group markers specified in the 
  5231.   "ChartSetGroupMarker" function.  MARKSYM_SOLIDDIAMOND is the default for all 
  5232.   data groups.
  5233.  
  5234.   NOTE: See "ChartSetGroupMarker" API.
  5235.  
  5236.   This function is operational and is described only in the full function
  5237.   product.
  5238.  
  5239.  
  5240.   ChartSetMaxXValue - Set maximum X-axis scale
  5241.   ════════════════════════════════════════════
  5242.  
  5243.   These APIs are provided to support the CH_MATRIX chart and are are similar in
  5244.   function to the ChartSetMaxYValue documented the programmers guide.  Please
  5245.   refer to the programmers guide for additional information.
  5246.  
  5247.   This function is operational and is described only in the full function
  5248.   product.
  5249.  
  5250.  
  5251.  
  5252.   ChartSetMaxYValue - Set maximum Y-axis scale
  5253.   ════════════════════════════════════════════
  5254.  
  5255.   ChartSetMaxYValue(hchart,value);
  5256.  
  5257.   This function forces a maximum value for the Y-axis, overriding the
  5258.   automatic scaling default in the ChartVisible function request.  This
  5259.   function is not applicable to pie charts.
  5260.  
  5261.   This function is operational and is described only in the full function
  5262.   product.
  5263.  
  5264.  
  5265.  
  5266.   ChartSetMaxZValue - Set maximum Z-axis scale
  5267.   ════════════════════════════════════════════
  5268.  
  5269.   ChartSetMaxZValue(hchart,value);
  5270.  
  5271.   This function forces a maximum value for the Z-axis, overriding the
  5272.   automatic scaling default in the ChartVisible function request.  This
  5273.   function is not applicable to pie charts.
  5274.  
  5275.   This function is operational and is described only in the full function
  5276.   product.
  5277.                                  88
  5278.  
  5279.  
  5280.  
  5281.   ChartSetMinYValue - Set minimum Y-axis scale
  5282.   ════════════════════════════════════════════
  5283.  
  5284.   ChartSetMaxYValue(hchart,value);
  5285.  
  5286.   This function forces a minimum value for the Y-axis, overriding the
  5287.   automatic scaling default in the ChartVisible function request.  This
  5288.   function is not applicable to pie charts.
  5289.  
  5290.   NOTE: The CH_FLOAT_SCALE parameter from either "ChartCreate" or
  5291.   "ChartSetOptions" API is required.
  5292.  
  5293.   This function is operational and is described only in the full function
  5294.   product.
  5295.  
  5296.  
  5297.   ChartSetMinZValue - Set minimum z-axis scale
  5298.   ════════════════════════════════════════════
  5299.  
  5300.   ChartSetMaxZValue(hchart,value);
  5301.  
  5302.   This function forces a minimum value for the Z-axis, overriding the
  5303.   automatic scaling default in the ChartVisible function request.  This
  5304.   function is not applicable to pie charts.
  5305.  
  5306.   NOTE: The CH_FLOAT_SCALE parameter from either "ChartCreate" or
  5307.   "ChartSetOptions" API is required.
  5308.  
  5309.   This function is operational and is described only in the full function
  5310.   product.
  5311.  
  5312.  
  5313.  
  5314.   ChartSetNormalDataScope
  5315.   ═══════════════════════
  5316.  
  5317.   ChartSetNormalDataScope(hchart,low,high);
  5318.  
  5319.   This function places a horizontal band in the graphic area prior to drawing 
  5320.   data points.  The normal or historical scope for the data is displayed within
  5321.   this visual band, thereby, causing data outside the scope to e distinct.  The
  5322.   height and placement of this band depends on the y-axis values and the 
  5323.   parameter values supplied to this function.  The "ChartSetColor" API assigns 
  5324.   the horizontal band color.  (Not applicable to perspective bar chart, 
  5325.   horizontal charts, or pie chart)
  5326.  
  5327.   Note: When the low and high parameters are zero, the normal data scope 
  5328.   function is turned off.
  5329.  
  5330.    This function is operational and is described only in the full function
  5331.    product.
  5332.  
  5333.  
  5334.  
  5335.                                  89
  5336.  
  5337.  
  5338.  
  5339.   ChartSetOptions - Set chart flags on or off
  5340.   ═══════════════════════════════════════════
  5341.  
  5342.   ChartSetOptions(hchart,chart_flags);
  5343.  
  5344.   This function resets the chart_flags assigned in the ChartCreate
  5345.   function.
  5346.  
  5347.   NOTE: Use the "ChartQueryOptions" function to obtain the current chart_flags 
  5348.   status.
  5349.  
  5350.   This function is operational and is described only in the full function
  5351.   product.
  5352.  
  5353.  
  5354.   
  5355.   ChartSetPattern - Assign a pattern for a chart item
  5356.   ═══════════════════════════════════════════════════
  5357.  
  5358.   ChartSetPattern(hchart,item,pattern,overlay,color);
  5359.  
  5360.   This function specifies a chart item to be displayed using a pattern.
  5361.    
  5362.   This function is operational and is described only in the full function
  5363.   product.
  5364.  
  5365.  
  5366.  
  5367.  
  5368.  
  5369.  
  5370.  
  5371.  
  5372.  
  5373.  
  5374.  
  5375.  
  5376.  
  5377.  
  5378.  
  5379.  
  5380.  
  5381.  
  5382.  
  5383.  
  5384.  
  5385.  
  5386.  
  5387.  
  5388.  
  5389.  
  5390.  
  5391.  
  5392.  
  5393.                                  90
  5394.  
  5395.  
  5396.  
  5397.   ChartSetPointCount - Set maximum number of data points per group
  5398.   ════════════════════════════════════════════════════════════════
  5399.  
  5400.  
  5401.   This function resets the number of data points per group to be displayed.
  5402.   The value can be less than the actual number of data points provided to the
  5403.   ChartData function.
  5404.  
  5405.  
  5406.   ┌───────────────────────────────────────────────────────────────────────────┐
  5407.   │                                                                           │
  5408.   │   ans = ChartSetPointCount(hchart,      // Chart handle                   │
  5409.   │                            points);     // Maximum points per group to    │
  5410.   │                                         //    display.                    │
  5411.   │                                                                           │
  5412.   └───────────────────────────────────────────────────────────────────────────┘
  5413.  
  5414.  
  5415.   The "ChartSetPointCount" function parameters are as follows:
  5416.  
  5417.   ans          Provides TRUE for a successful request or FALSE for an
  5418.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  5419.                the "error" code location specified in the "ChartCreate"
  5420.                function.
  5421.  
  5422.   hchart       Specifies the handle returned by the "ChartCreate" function.
  5423.   (HWND)
  5424.  
  5425.   points       Specifies the number of data points associated with any group.
  5426.   (USHORT)     
  5427.  
  5428.  
  5429.   ┌───────────────────────────────────────────────────────────────────────────┐
  5430.   │                                                                           │
  5431.   │  Error codes     Chart_no_data            9                               │
  5432.   │                                                                           │
  5433.   └───────────────────────────────────────────────────────────────────────────┘
  5434.  
  5435.  
  5436.   The following illustrates setting the maximum number of displayed points to
  5437.   three.
  5438.  
  5439.  
  5440.   ┌───────────────────────────────────────────────────────────────────────────┐
  5441.   │                                                                           │
  5442.   │  BOOL            fAns;                   // Successful call indicator     │
  5443.   │  static HWND     hChart;                 // Bar chart handle              │
  5444.   │                                                                           │
  5445.   │                                                                           │
  5446.   │  fAns = ChartSetPointCount(hChart,       // Chart handle                  │
  5447.   │                            3);           // 3 points for all groups       │
  5448.   │                                                                           │
  5449.   └───────────────────────────────────────────────────────────────────────────┘
  5450.  
  5451.                                  91
  5452.  
  5453.  
  5454.  
  5455.   ChartSetRect - Change the location of a chart
  5456.   ═════════════════════════════════════════════
  5457.  
  5458.  
  5459.   This function enables movement of a chart within a window area defined by
  5460.   the chart handle in the "ChartCreate" function.
  5461.  
  5462.   NOTE: This function should be followed by either a "ChartPaint" or 
  5463.   "ChartVisible" API request to show the chart on the display.
  5464.  
  5465.  
  5466.   ┌───────────────────────────────────────────────────────────────────────────┐
  5467.   │                                                                           │
  5468.   │   ans = ChartSetRect(hChart,            // Chart handle                   │
  5469.   │                      &rectl);           // Rectangle pointer              │
  5470.   │                                                                           │
  5471.   └───────────────────────────────────────────────────────────────────────────┘
  5472.  
  5473.  
  5474.   The "ChartSetRect" function parameters are as follows:
  5475.  
  5476.   ans          Provides TRUE for a successful request or FALSE for an
  5477.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  5478.                the "error" code location specified in the "ChartCreate"
  5479.                function.
  5480.  
  5481.   hchart       Specifies the handle returned by the "ChartCreate" function.
  5482.   (HWND)
  5483.  
  5484.   rectl        Provides a pointer to a structure containing the bottom left
  5485.   (PRECTL)     and upper right coordinates.  This is the chart location when it
  5486.                is made visible.
  5487.  
  5488.  
  5489.   ┌───────────────────────────────────────────────────────────────────────────┐
  5490.   │                                                                           │
  5491.   │  Error codes     NONE                                                     │
  5492.   │                                                                           │
  5493.   └───────────────────────────────────────────────────────────────────────────┘
  5494.  
  5495.  
  5496.  
  5497.  
  5498.  
  5499.  
  5500.  
  5501.  
  5502.  
  5503.  
  5504.  
  5505.  
  5506.  
  5507.  
  5508.  
  5509.                                  92
  5510.  
  5511.  
  5512.  
  5513.   The following illustrates changing a chart location.
  5514.  
  5515.  
  5516.   ┌───────────────────────────────────────────────────────────────────────────┐
  5517.   │                                                                           │
  5518.   │  BOOL            fAns;                   // Successful call indicator     │
  5519.   │  static HWND     hChart;                 // Bar chart handle              │
  5520.   │  RECTL           Rectl;                  // Rectangle coordinates         │
  5521.   │                                                                           │
  5522.   │  Rectl.xLeft   = 50;                                                      │
  5523.   │  Rectl.yBottom = 50;                                                      │
  5524.   │  Rectl.xRight  = 250;                                                     │
  5525.   │  Rectl.yTop    = 300;                                                     │
  5526.   │                                                                           │
  5527.   │  fAns = ChartSetRect(hChart,             // Chart handle                  │
  5528.   │                      &Rectl);            // New chart location            │
  5529.   │                                                                           │
  5530.   └───────────────────────────────────────────────────────────────────────────┘
  5531.  
  5532.  
  5533.  
  5534.  
  5535.  
  5536.  
  5537.  
  5538.  
  5539.  
  5540.  
  5541.  
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.  
  5549.  
  5550.  
  5551.  
  5552.  
  5553.  
  5554.  
  5555.  
  5556.  
  5557.  
  5558.  
  5559.  
  5560.  
  5561.  
  5562.  
  5563.  
  5564.  
  5565.  
  5566.  
  5567.                                  93
  5568.  
  5569.  
  5570.  
  5571.   ChartSetRegions - Reallocate the chart sub-areas
  5572.   ════════════════════════════════════════════════
  5573.  
  5574.   ChartSetRegions(hchart,graphic,heading,footing,left_margin,right_margin);
  5575.  
  5576.   This function changes a region default size.  The ChartCreate function
  5577.   subdivides the rectangular space allocated into five regions.  The
  5578.   default size of these regions can be changed for the purpose of aesthetic
  5579.   balancing and presentation style.
  5580.  
  5581.   This function is operational and is described only in the full function
  5582.   product.
  5583.  
  5584.  
  5585.  
  5586.   ChartSetRGB - Set the RGB color for a chart item
  5587.   ════════════════════════════════════════════════
  5588.  
  5589.   ChartSetRGB(hchart,chart_item,rgb);
  5590.  
  5591.   This function sets chart characteristics (i.e. title text, chart border,
  5592.   graphic background) to any available RGB color value.  The default color
  5593.   for all text and lines is the system default (contrast to background).
  5594.  
  5595.  
  5596.   This function is operational and is described only in the full function
  5597.   product.
  5598.  
  5599.  
  5600.   ChartSetSymbolGroup - Specify number of data points per column
  5601.   ══════════════════════════════════════════════════════════════
  5602.  
  5603.   ChartSetSymbolGroup(hchart,collect);
  5604.  
  5605.   This function specifies the number of data point symbols to be grouped 
  5606.   together within each column of the symbol table chart.
  5607.  
  5608.  
  5609.   This function is operational and is described only in the full function
  5610.   product.
  5611.  
  5612.  
  5613.   ChartSetTableFormat - Set characteristics of numeric and symbol tables
  5614.   ══════════════════════════════════════════════════════════════════════
  5615.  
  5616.   ChartSetTableFormat(hchart,title,legend_title,format,width,justify);
  5617.  
  5618.   This function provides the general characteristics of either the numeric 
  5619.   table or symbol table charts.
  5620.  
  5621.  
  5622.   This function is operational and is described only in the full function
  5623.   product.
  5624.  
  5625.                                  94
  5626.  
  5627.  
  5628.  
  5629.   ChartSetTextFontSize - Set font size for a chart text element
  5630.   ═════════════════════════════════════════════════════════════
  5631.  
  5632.   ChartSetTextFontSize(hchart,flags,size);
  5633.  
  5634.   This function specifies a font size for the display of a chart text element.
  5635.  
  5636.   NOTE: This function overrides automatic font sizing.
  5637.  
  5638.  
  5639.   This function is operational and is described only in the full function
  5640.   product.
  5641.  
  5642.  
  5643.   ChartSetTicks - Specify controls for the y-axis and z-axis
  5644.   ══════════════════════════════════════════════════════════
  5645.  
  5646.   ChartSetTicks(hchart,item,&ticks);
  5647.  
  5648.   This function disables the axis automatic scaling and specifies the controls 
  5649.   for the y-axis and z-axis tick elements.
  5650.  
  5651.  
  5652.   This function is operational and is described only in the full function
  5653.   product.
  5654.  
  5655.  
  5656.   ChartSetTimeRange - Set time range for time-based charts
  5657.   ════════════════════════════════════════════════════════
  5658.  
  5659.   ChartSetTimeRange(hchart,&start,&end);
  5660.  
  5661.   This function specifies a starting and ending time range for the data.  Data 
  5662.   points prior to and following the preset time range will not be displayed.
  5663.  
  5664.  
  5665.   This function is operational and is described only in the full function
  5666.   product.
  5667.  
  5668.  
  5669.  
  5670.  
  5671.  
  5672.  
  5673.  
  5674.  
  5675.  
  5676.  
  5677.  
  5678.  
  5679.  
  5680.  
  5681.  
  5682.  
  5683.                                  95
  5684.  
  5685.  
  5686.  
  5687.   ChartTimeReference - Set the data point time elements for time-based charts
  5688.   ═══════════════════════════════════════════════════════════════════════════
  5689.  
  5690.   ChartTimeReference(hchart,group,count,&array);
  5691.  
  5692.   This function provides the date and time element of each data point for the 
  5693.   chart.  To enable time based scatter, line, smooth line, spike, square wave, 
  5694.   high/low range, area and candlestick charts, set the CH_TIME_BASED flag in 
  5695.   either "ChartCreate" or "ChartSetOptions" APIs.
  5696.  
  5697.   NOTE: This flag requires all data points provided to "ChartData" be 
  5698.   accompanied by an associated time value. The "ChartData" API must be issued 
  5699.   prior to the "ChartTimeReference" API.
  5700.  
  5701.  
  5702.  
  5703.   This function is operational and is described only in the full function
  5704.   product.
  5705.  
  5706.  
  5707.  
  5708.  
  5709.  
  5710.  
  5711.  
  5712.  
  5713.  
  5714.  
  5715.  
  5716.  
  5717.  
  5718.  
  5719.  
  5720.  
  5721.  
  5722.  
  5723.  
  5724.  
  5725.  
  5726.  
  5727.  
  5728.  
  5729.  
  5730.  
  5731.  
  5732.  
  5733.  
  5734.  
  5735.  
  5736.  
  5737.  
  5738.  
  5739.  
  5740.  
  5741.                                  96
  5742.  
  5743.  
  5744.  
  5745.   ChartSetType - Change the chart from one type to another
  5746.   ════════════════════════════════════════════════════════
  5747.  
  5748.   ChartSetType(hchart,chart_type,visible);
  5749.  
  5750.   This function changes the current chart type from one form to another.  A
  5751.   bar chart can be changed to a line chart without redefining current data,
  5752.   legends or other properties.  At the time the function call is made, the 
  5753.   application may request the new chart to be made visible.
  5754.  
  5755.  
  5756.   ┌───────────────────────────────────────────────────────────────────────────┐
  5757.   │                                                                           │
  5758.   │   ans = ChartSetType(hchart,            // Chart handle                   │
  5759.   │                      chart_type,        // New chart type                 │
  5760.   │                      visible);          // Reshow indicator               │
  5761.   │                                                                           │
  5762.   └───────────────────────────────────────────────────────────────────────────┘
  5763.  
  5764.  
  5765.   The "ChartSetType" function parameters are as follows:
  5766.  
  5767.   ans          Provides TRUE for a successful request or FALSE for an
  5768.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  5769.                the "error" code location specified in the "ChartCreate"
  5770.                function.
  5771.  
  5772.   hchart       Specifies the handle returned by the "ChartCreate" function.
  5773.   (HWND)
  5774.  
  5775.   chart_type   Describes the current or new chart type.  The values that may
  5776.   (PCHTYPE)    be provided are as follows:
  5777.  
  5778.  
  5779.                CH_BAR                       CH_RANGE                     
  5780.                CH_STACKED_BAR               CH_HORIZONTAL_BAR            
  5781.                CH_COLUMN                    CH_HORIZONTAL_STACKED_BAR    
  5782.                CH_LINE                      CH_PLOT                      
  5783.                CH_SMOOTH_LINE               CH_OVERLAP_BAR               
  5784.                CH_SCATTER                   CH_CONNECTED_SCATTER         
  5785.                CH_AREA                      CH_BAR_GOAL                  
  5786.                CH_PIE                       CH_X_PLOT                    
  5787.                CH_PER_BAR                   CH_MIXED                     
  5788.                CH_BAR_LINE                  CH_FLOAT_BAR                 
  5789.                CH_NUMERIC_TABLE             CH_FLOAT_STACKED_BAR         
  5790.                CH_SYMBOL_TABLE              CH_MATRIX                    
  5791.                CH_SPIKE                     CH_STACKED_AREA              
  5792.                CH_SQUARE_WAVE            
  5793.                CH_HISTOGRAM              
  5794.  
  5795.  
  5796.  
  5797.  
  5798.  
  5799.                                  97
  5800.  
  5801.  
  5802.  
  5803.   visible      True indicates the chart will be painted or re-shown after the 
  5804.   (BOOL)       type change has been made (implied "ChartVisible" function).
  5805.                FALSE specifies the chart type is changing but will not be 
  5806.                redisplayed.
  5807.  
  5808.  
  5809.   ┌───────────────────────────────────────────────────────────────────────────┐
  5810.   │                                                                           │
  5811.   │  Error codes     Chart_invalid_client            1                        │
  5812.   │                  Chart_not_defined               2                        │
  5813.   │                  Chart_no_memory                 3                        │
  5814.   │                  Chart_no_data                   9                        │
  5815.   │                  Chart_memory_release           12                        │
  5816.   │                                                                           │
  5817.   └───────────────────────────────────────────────────────────────────────────┘
  5818.  
  5819.  
  5820.   The following illustrates changing bar chart to a 3D line chart and 
  5821.   displaying the change.
  5822.  
  5823.  
  5824.   ┌───────────────────────────────────────────────────────────────────────────┐
  5825.   │                                                                           │
  5826.   │  BOOL            fAns;                   // Successful call indicator     │
  5827.   │  static HWND     hChart;                 // Bar chart handle              │
  5828.   │                                                                           │
  5829.   │                                                                           │
  5830.   │  fAns = ChartSetDimensions(hChart,3);    // Set chart to 3D               │
  5831.   │                                                                           │
  5832.   │         ChartSetType(hChart,             // Chart handle                  │
  5833.   │                      CH_LINE,            // Set chart to line chart       │
  5834.   │                      TRUE);              // Display the line chart        │
  5835.   │                                                                           │
  5836.   └───────────────────────────────────────────────────────────────────────────┘
  5837.  
  5838.  
  5839.  
  5840.  
  5841.  
  5842.  
  5843.  
  5844.  
  5845.  
  5846.  
  5847.  
  5848.  
  5849.  
  5850.  
  5851.  
  5852.  
  5853.  
  5854.  
  5855.  
  5856.  
  5857.                                  98
  5858.  
  5859.  
  5860.  
  5861.   ChartSetWindow - Change the window handle
  5862.   ═════════════════════════════════════════
  5863.  
  5864.   ans = ChartSetWindow(hchart,new_hwnd);
  5865.  
  5866.   This function enables the developer to change the window handle for a
  5867.   chart after the chart creation.  This allows the data to be re-shown in
  5868.   different windows.
  5869.  
  5870.   This function is operational and is described only in the full function
  5871.   product.
  5872.  
  5873.  
  5874.  
  5875.  
  5876.  
  5877.  
  5878.  
  5879.  
  5880.  
  5881.  
  5882.  
  5883.  
  5884.  
  5885.  
  5886.  
  5887.  
  5888.  
  5889.  
  5890.  
  5891.  
  5892.  
  5893.  
  5894.  
  5895.  
  5896.  
  5897.  
  5898.  
  5899.  
  5900.  
  5901.  
  5902.  
  5903.  
  5904.  
  5905.  
  5906.  
  5907.  
  5908.  
  5909.  
  5910.  
  5911.  
  5912.  
  5913.  
  5914.  
  5915.                                  99
  5916.  
  5917.  
  5918.  
  5919.   ChartSetXTicks - Set x-axis tick text type
  5920.   ══════════════════════════════════════════
  5921.  
  5922.  
  5923.   This function sets the text type and display direction under the x-axis
  5924.   tick marks in all charts except pie charts.
  5925.  
  5926.   
  5927.   ┌───────────────────────────────────────────────────────────────────────────┐
  5928.   │                                                                           │
  5929.   │   ans = ChartSetXTicks(hchart,          // Chart handle                   │
  5930.   │                        direction,       // Text direction                 │
  5931.   │                        text_type,       // Type of tick text              │
  5932.   │                        index);          // Start text index               │
  5933.   │                                                                           │
  5934.   └───────────────────────────────────────────────────────────────────────────┘
  5935.  
  5936.  
  5937.   The "ChartSetXTicks" function parameters are as follows:
  5938.  
  5939.   ans          Provides TRUE for a successful request or FALSE for an
  5940.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  5941.                the "error" code location specified in the "ChartCreate"
  5942.                function.
  5943.  
  5944.   hchart       Specifies the handle returned by the "ChartCreate" function.
  5945.   (HWND)
  5946.  
  5947.   direction    Specifies the direction of display for the text tick marks.
  5948.   (USHORT)     CH_WIDTH is the only possible value for this parameter.
  5949.  
  5950.   text_type    Specifies a flag indicating the type of text to be placed under 
  5951.   (USHORT)     the tick mark.  A list of the text types follows:
  5952.  
  5953.                CH_BASIC        Basic numbering 1 - 60
  5954.                CH_MONTHS       Months of the year
  5955.                CH_WEEK_DAYS    5 day week (Mon. - Fri.)
  5956.                CH_DAYS         7 day week (Mon. - Sun.)
  5957.                CH_HOURS        24 hours (12AM - 11PM)
  5958.                CH_HOURS_24     Military time (0000 - 2300)
  5959.                CH_MINUTES      1 - 60 minutes
  5960.                CH_SECONDS      1 - 60 seconds
  5961.                CH_LEDGER       0 - 360 (i.e. 0, 30, 60, 90)
  5962.  
  5963.  
  5964.  
  5965.  
  5966.  
  5967.  
  5968.  
  5969.  
  5970.  
  5971.  
  5972.  
  5973.                                 100
  5974.  
  5975.  
  5976.  
  5977.   index        Specifies the "starting point in time" for the text set selected
  5978.   (USHORT)     in the text-type parameter.
  5979.  
  5980.                NOTE: If CH_MONTHS is selected for the text and the start 
  5981.                paramenter value is 5, the first month displayed will be "May." 
  5982.                If CH_MONTHS is selected for the text and the start parameter is
  5983.                14, the month displayed will be "February." (If the start value
  5984.                is greater than the number of string elements implied by the 
  5985.                text parameter, a calculation performs and makes the proper
  5986.                adjustments.)
  5987.  
  5988.  
  5989.   ┌───────────────────────────────────────────────────────────────────────────┐
  5990.   │                                                                           │
  5991.   │  Error codes     Chart_invalid_parameter         5                        │
  5992.   │                  Chart_invalid_tick_text        11                        │
  5993.   │                                                                           │
  5994.   └───────────────────────────────────────────────────────────────────────────┘
  5995.  
  5996.  
  5997.   The following illustrates setting the "months of the year" for a bar chart 
  5998.   beginning in February.
  5999.  
  6000.  
  6001.   ┌───────────────────────────────────────────────────────────────────────────┐
  6002.   │                                                                           │
  6003.   │  BOOL            fAns;                   // Successful call indicator     │
  6004.   │  static HWND     hChart;                 // Bar chart handle              │
  6005.   │                                                                           │
  6006.   │                                                                           │
  6007.   │  fAns = ChartSetXTicks(hChart,           // Set chart to 3D               │
  6008.   │                        CH_WIDTH,         // Text direction                │
  6009.   │                        CH_MONTHS,        // Type of tick text             │
  6010.   │                        2);               // Start with February           │
  6011.   │                                                                           │
  6012.   └───────────────────────────────────────────────────────────────────────────┘
  6013.  
  6014.  
  6015.  
  6016.  
  6017.  
  6018.  
  6019.  
  6020.  
  6021.  
  6022.  
  6023.  
  6024.  
  6025.  
  6026.  
  6027.  
  6028.  
  6029.  
  6030.  
  6031.                                 101
  6032.  
  6033.  
  6034.  
  6035.   ChartSetXTicksFloat - Set x-axis tick floating point value
  6036.   ══════════════════════════════════════════════════════════
  6037.  
  6038.   ans = ChartSetXTicksFloat(hchart,direction,start,increment,format);
  6039.  
  6040.   This function allows the programmer to set floating point values to the
  6041.   x-axis tick marks.
  6042.  
  6043.  
  6044.   This function is operational and is described only in the full function
  6045.   product.
  6046.  
  6047.  
  6048.  
  6049.  
  6050.  
  6051.  
  6052.  
  6053.  
  6054.  
  6055.  
  6056.  
  6057.  
  6058.  
  6059.  
  6060.  
  6061.  
  6062.  
  6063.  
  6064.  
  6065.  
  6066.  
  6067.  
  6068.  
  6069.  
  6070.  
  6071.  
  6072.  
  6073.  
  6074.  
  6075.  
  6076.  
  6077.  
  6078.  
  6079.  
  6080.  
  6081.  
  6082.  
  6083.  
  6084.  
  6085.  
  6086.  
  6087.  
  6088.  
  6089.                                 102
  6090.  
  6091.  
  6092.  
  6093.   ChartSetXTicksString - Set x-axis tick string values
  6094.   ════════════════════════════════════════════════════
  6095.  
  6096.  
  6097.   This function sets application generated ASCIIZ string values for the x-axis 
  6098.   tick marks. X-axis string values repeat if the number of data points provided
  6099.   to the chart exceed the number of string values provided.
  6100.  
  6101.   
  6102.   ┌───────────────────────────────────────────────────────────────────────────┐
  6103.   │                                                                           │
  6104.   │   ans = ChartSetXTicksString(hchart,          // Chart handle             │
  6105.   │                              direction,       // Text direction           │
  6106.   │                              array_count,     // Number of array items    │
  6107.   │                              &array_ptr);     // Pointer to asciiz text   │
  6108.   │                                               //   string array           │
  6109.   │                                                                           │
  6110.   └───────────────────────────────────────────────────────────────────────────┘
  6111.  
  6112.  
  6113.   The "ChartSetXTicksString" function parameters are as follows:
  6114.  
  6115.   ans          Provides TRUE for a successful request or FALSE for an
  6116.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  6117.                the "error" code location specified in the "ChartCreate"
  6118.                function.
  6119.  
  6120.   hchart       Specifies the handle returned by the "ChartCreate" function.
  6121.   (HWND)
  6122.  
  6123.   direction    Specifies the direction of display for the text tick marks.
  6124.   (USHORT)     CH_WIDTH is the only possible value for this parameter.
  6125.  
  6126.   array_count  Specifies the count of asciiz string elements.  A value of 0 
  6127.   (USHORT)     releases previous strings.
  6128.  
  6129.   array_ptr    Specifies the pointer to the asciiz string array.  The maximum
  6130.   (PCH)        length of any one string element can not exceed 50 characters.
  6131.  
  6132.  
  6133.  
  6134.   ┌───────────────────────────────────────────────────────────────────────────┐
  6135.   │                                                                           │
  6136.   │  Error codes     Chart_invalid_parameter         5                        │
  6137.   │                  Chart_no_memory                 3                        │
  6138.   │                                                                           │
  6139.   └───────────────────────────────────────────────────────────────────────────┘
  6140.  
  6141.  
  6142.  
  6143.  
  6144.  
  6145.  
  6146.  
  6147.                                 103
  6148.  
  6149.  
  6150.  
  6151.   The following illustrates placing "North", "South" and "East" under the 
  6152.   x-axis tick marks.
  6153.  
  6154.  
  6155.   ┌───────────────────────────────────────────────────────────────────────────┐
  6156.   │                                                                           │
  6157.   │  BOOL            fAns;                   // Successful call indicator     │
  6158.   │  static HWND     hChart;                 // Bar chart handle              │
  6159.   │                                                                           │
  6160.   │  static PCH aszAreas[3] = {"North","South","East"};                       │
  6161.   │                                                                           │
  6162.   │  fAns = ChartSetXTicksString(hChart,     // Chart handle                  │
  6163.   │                              CH_WIDTH,   // Text direction                │
  6164.   │                              3,          // Number of string elements     │
  6165.   │                              aszAreas);  // Pointer to string array       │
  6166.   │                                                                           │
  6167.   └───────────────────────────────────────────────────────────────────────────┘
  6168.  
  6169.  
  6170.  
  6171.  
  6172.  
  6173.  
  6174.  
  6175.  
  6176.  
  6177.  
  6178.  
  6179.  
  6180.  
  6181.  
  6182.  
  6183.  
  6184.  
  6185.  
  6186.  
  6187.  
  6188.  
  6189.  
  6190.  
  6191.  
  6192.  
  6193.  
  6194.  
  6195.  
  6196.  
  6197.  
  6198.  
  6199.  
  6200.  
  6201.  
  6202.  
  6203.  
  6204.  
  6205.                                 104
  6206.  
  6207.  
  6208.  
  6209.   ChartSetXTicksStringBasic - BASIC Language interface
  6210.   ════════════════════════════════════════════════════
  6211.  
  6212.   This API is provided for those programming languages which can not provide an
  6213.   array of asciiz strings due to their programming tools restrictions.  This
  6214.   API enables the programmer to send one long character string to the charting
  6215.   DLL and the DLL will parse the strings and perform the basic function of the
  6216.   "ChartSetXTicksString" API.  The separation between the strings is performed
  6217.   by the caret ^ symbol from the keyboard.
  6218.  
  6219.  
  6220.   ┌───────────────────────────────────────────────────────────────────────────┐
  6221.   │                                                                           │
  6222.   │   ans = ChartSetXTicksStringBasic(hchart,         // Chart handle         │
  6223.   │                                   direction,      // Text direction       │
  6224.   │                                   string);        // Pointer to asciiz    │
  6225.   │                                                   //   string             │
  6226.   │                                                                           │
  6227.   └───────────────────────────────────────────────────────────────────────────┘
  6228.  
  6229.  
  6230.   The "ChartSetXTicksStringBasic" function parameters are as follows:
  6231.  
  6232.   ans          Provides TRUE for a successful request or FALSE for an
  6233.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  6234.                the "error" code location specified in the "ChartCreate"
  6235.                function.
  6236.  
  6237.   hchart       Specifies the handle returned by the "ChartCreate" function.
  6238.   (HWND)
  6239.  
  6240.   direction    Specifies the direction of display for the text tick marks.
  6241.   (USHORT)     CH_WIDTH is the only possible value for this parameter.
  6242.  
  6243.   string       Specifies a pointer to an ASCIIZ string
  6244.   (PCH)  
  6245.  
  6246.  
  6247.   ┌───────────────────────────────────────────────────────────────────────────┐ 
  6248.   │                                                                           │ 
  6249.   │  Error codes     Chart_invalid_parameter         5                        │ 
  6250.   │                  Chart_no_memory                 3                        │ 
  6251.   │                                                                           │ 
  6252.   └───────────────────────────────────────────────────────────────────────────┘ 
  6253.  
  6254.  
  6255.  
  6256.  
  6257.  
  6258.  
  6259.  
  6260.  
  6261.  
  6262.  
  6263.                                 105
  6264.  
  6265.  
  6266.   The following illustrates placing "North", "South" and "East" under the 
  6267.   x-axis tick marks.
  6268.  
  6269.  
  6270.   ┌───────────────────────────────────────────────────────────────────────────┐
  6271.   │                                                                           │
  6272.   │  BOOL            fAns;                   // Successful call indicator     │
  6273.   │  static HWND     hChart;                 // Bar chart handle              │
  6274.   │                                                                           │
  6275.   │                                                                           │
  6276.   │  fAns = ChartSetXTicksString(hChart,            // Chart handle           │
  6277.   │                              CH_WIDTH,          // Text direction         │
  6278.   │                              "North^South^East");  // String to be parsed │
  6279.   │                                                                           │
  6280.   └───────────────────────────────────────────────────────────────────────────┘
  6281.  
  6282.  
  6283.  
  6284.  
  6285.  
  6286.  
  6287.  
  6288.  
  6289.  
  6290.  
  6291.  
  6292.  
  6293.  
  6294.  
  6295.  
  6296.  
  6297.  
  6298.  
  6299.  
  6300.  
  6301.  
  6302.  
  6303.  
  6304.  
  6305.  
  6306.  
  6307.  
  6308.  
  6309.  
  6310.  
  6311.  
  6312.  
  6313.  
  6314.  
  6315.  
  6316.  
  6317.  
  6318.  
  6319.  
  6320.  
  6321.                                 106
  6322.  
  6323.  
  6324.  
  6325.   ChartSetYTicksString - Set y-axis tick string values
  6326.   ════════════════════════════════════════════════════
  6327.  
  6328.  
  6329.   This function sets string values for the y-axis (i.e. power off, warm up, 
  6330.   off-line, and on-line).  This function is generally used only with square 
  6331.   wave chart.
  6332.  
  6333.   NOTE: a data point with a zero value will represent the first string and a 
  6334.   value of one will represent the second string.  No check is made to insure 
  6335.   the data does not exceed the number of strings specified.
  6336.  
  6337.  
  6338.  
  6339.   This function is operational and is described only in the full function
  6340.   product.
  6341.  
  6342.  
  6343.   
  6344.  
  6345.  
  6346.  
  6347.  
  6348.  
  6349.  
  6350.  
  6351.  
  6352.  
  6353.  
  6354.  
  6355.  
  6356.  
  6357.  
  6358.  
  6359.  
  6360.  
  6361.  
  6362.  
  6363.  
  6364.  
  6365.  
  6366.  
  6367.  
  6368.  
  6369.  
  6370.  
  6371.  
  6372.  
  6373.  
  6374.  
  6375.  
  6376.  
  6377.  
  6378.  
  6379.                                 107
  6380.  
  6381.  
  6382.  
  6383.   ChartSetZAxisGroup - Assign a data group to the z-axis
  6384.   ══════════════════════════════════════════════════════
  6385.  
  6386.   This function assigns a data group to the z-axis scale.  The charting engine 
  6387.   assumes that at least one data group is assigned to the y-axis at all times.
  6388.  
  6389.   NOTE: The z-axis ticks and tick text should be set to the same color as the 
  6390.   data group to insure the connection for interpretation.
  6391.    
  6392.   
  6393.   ┌───────────────────────────────────────────────────────────────────────────┐
  6394.   │                                                                           │
  6395.   │   ans = ChartSetZAxisGroup(hchart,       // Chart handle                  │
  6396.   │                            group,        // Data group number             │
  6397.   │                            assign);      // Assignment indicator          │
  6398.   │                                                                           │
  6399.   └───────────────────────────────────────────────────────────────────────────┘
  6400.  
  6401.  
  6402.   The "ChartSetZAxisGroup" function parameters are as follows:
  6403.  
  6404.   ans          Provides TRUE for a successful request or FALSE for an
  6405.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  6406.                the "error" code location specified in the "ChartCreate"
  6407.                function.
  6408.  
  6409.   hchart       Specifies the handle returned by the "ChartCreate" function.
  6410.   (HWND)
  6411.  
  6412.  
  6413.   group        Specifies the number to be assigned to the z-axis. This number
  6414.   (USHORT)     must range between 1 and 12.
  6415.  
  6416.   assign       TRUE indicates the group will be assigned to the z-axis.  FALSE
  6417.   (BOOL)       indicates the group will be assigned to the y-axis (system 
  6418.                default).
  6419.  
  6420.  
  6421.   ┌───────────────────────────────────────────────────────────────────────────┐
  6422.   │                                                                           │
  6423.   │  Error codes     Chart_invalid_group             8                        │
  6424.   │                                                                           │
  6425.   └───────────────────────────────────────────────────────────────────────────┘
  6426.  
  6427.  
  6428.  
  6429.  
  6430.  
  6431.  
  6432.  
  6433.  
  6434.  
  6435.  
  6436.  
  6437.                                 108
  6438.  
  6439.  
  6440.  
  6441.   ChartText - Specify chart text (i.e. heading, footing)
  6442.   ══════════════════════════════════════════════════════════════════════
  6443.  
  6444.  
  6445.   This function defines the text strings to be placed in the five chart
  6446.   areas.  The chart heading, footing, left margin, right margin, graphic
  6447.   text areas can be defined or removed.
  6448.  
  6449.   NOTE: if enough space is provided in the title and footing areas, inserting ~
  6450.   in the text string will initiate a new line.  A maximum of four (4) lines 
  6451.   area allowed.
  6452.  
  6453.  
  6454.    
  6455.   ┌───────────────────────────────────────────────────────────────────────────┐
  6456.   │                                                                           │
  6457.   │   ans = ChartText(hchart,                // Chart handle                  │
  6458.   │                   placement,             // Type of text to place         │
  6459.   │                   &string);              // Pointer to text string        │
  6460.   │                                                                           │
  6461.   └───────────────────────────────────────────────────────────────────────────┘
  6462.  
  6463.  
  6464.   The "ChartText" function parameters are as follows:
  6465.  
  6466.   ans          Provides TRUE for a successful request or FALSE for an
  6467.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  6468.                the "error" code location specified in the "ChartCreate"
  6469.                function.
  6470.  
  6471.   hchart       Specifies the handle returned by the "ChartCreate" function.
  6472.   (HWND)
  6473.  
  6474.   placement    Indicates the type of text.
  6475.   (ULONG))     
  6476.                CH_TITLE                Horizontal centering of title
  6477.                CH_FOOTING              Horizontal centering of footing
  6478.                CH_LEFT_MARGIN          Vertical centering of left margin
  6479.                CH_RIGHT_MARGIN         Vertical centering of right margin
  6480.  
  6481.   string       Points to an ASCIIZ string of data containing the chart text 
  6482.   (PCH)        defined to a specific area.  If a NULL is provided, any previous
  6483.                string is removed.
  6484.  
  6485.  
  6486.   ┌───────────────────────────────────────────────────────────────────────────┐
  6487.   │                                                                           │
  6488.   │  Error codes     Chart_no_memory                 3                        │
  6489.   │                  Chart_invalid_parameter         5                        │
  6490.   │                                                                           │
  6491.   └───────────────────────────────────────────────────────────────────────────┘
  6492.  
  6493.  
  6494.  
  6495.                                 109
  6496.  
  6497.  
  6498.  
  6499.   The following illustrates two methods of specifying a chart heading.
  6500.  
  6501.  
  6502.   ┌───────────────────────────────────────────────────────────────────────────┐
  6503.   │                                                                           │
  6504.   │  BOOL            fAns;                   // Successful call indicator     │
  6505.   │  static HWND     hChart;                 // Bar chart handle              │
  6506.   │                                                                           │
  6507.   │  static CHAR     aszTitle[14] = "Monthly Sales";                          │
  6508.   │                                                                           │
  6509.   │  fAns = ChartText(hChart,                // Chart handle                  │
  6510.   │                   CH_TITLE,              // Text placement area           │
  6511.   │                   &aszTitle);            // Pointer to text string        │
  6512.   │                                                                           │
  6513.   │  //  or                                                                   │
  6514.   │                                                                           │
  6515.   │  fAns = ChartText(hChart,                // Chart handle                  │
  6516.   │                   CH_TITLE,              // Text placement area           │
  6517.   │                   "Monthly Sales");      // Actual text string            │
  6518.   │                                                                           │
  6519.   └───────────────────────────────────────────────────────────────────────────┘
  6520.  
  6521.  
  6522.  
  6523.  
  6524.  
  6525.  
  6526.  
  6527.  
  6528.  
  6529.  
  6530.  
  6531.  
  6532.  
  6533.  
  6534.  
  6535.  
  6536.  
  6537.  
  6538.  
  6539.  
  6540.  
  6541.  
  6542.  
  6543.  
  6544.  
  6545.  
  6546.  
  6547.  
  6548.  
  6549.  
  6550.  
  6551.  
  6552.  
  6553.                                 110
  6554.  
  6555.  
  6556.  
  6557.   ChartTexts - Set all chart texts (i.e. heading, margins)
  6558.   ════════════════════════════════════════════════════════
  6559.  
  6560.  
  6561.   This function defines all of the text strings to be placed in the four
  6562.   chart areas using a single call interface.  The chart heading, footing,
  6563.   left margin, and right margin areas can be defined or removed in any
  6564.   combination.
  6565.  
  6566.   NOTE: if enough space is provided in the title and footing areas, inserting ~
  6567.   in the text string will initiate a new line.  A maximum of four (4) lines 
  6568.   area allowed.
  6569.  
  6570.  
  6571.   ┌───────────────────────────────────────────────────────────────────────────┐
  6572.   │                                                                           │
  6573.   │   ans = ChartTexts(hchart,               // Chart handle                  │
  6574.   │                    &heading,             // Heading string                │
  6575.   │                    &footing,             // Footing string                │
  6576.   │                    &left_margin,         // Left margin string            │
  6577.   │                    &right_margin);       // Right margin string           │
  6578.   │                                                                           │
  6579.   └───────────────────────────────────────────────────────────────────────────┘
  6580.  
  6581.  
  6582.   The "ChartTexts" function parameters are as follows:
  6583.  
  6584.   ans          Provides TRUE for a successful request or FALSE for an
  6585.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  6586.                the "error" code location specified in the "ChartCreate"
  6587.                function.
  6588.  
  6589.   hchart       Specifies the handle returned by the "ChartCreate" function.
  6590.   (HWND)
  6591.  
  6592.   heading      Points to an ASCIIZ string of data containing the chart text for
  6593.   (PCH)        the heading area.  If a NULL is provided, any previous string 
  6594.                will be removed.
  6595.  
  6596.   footing      Points to an ASCIIZ string of data containing the chart text for
  6597.   (PCH)        the footing area.  If a NULL is provided, any previous string
  6598.                will be removed.
  6599.  
  6600.   left_margin  Points to an ASCIIZ string of data containing the chart text for
  6601.   (PCH)        the left margin area.  If a NULL is provided, any previous 
  6602.                string will be removed.
  6603.  
  6604.   right_margin Points to an ASCIIZ string of data containing the chart text for
  6605.   (PCH)        the right margin area.  If a NULL is provided, any previous
  6606.                string will be removed.
  6607.  
  6608.  
  6609.  
  6610.  
  6611.                                 111
  6612.  
  6613.  
  6614.  
  6615.   ┌───────────────────────────────────────────────────────────────────────────┐
  6616.   │                                                                           │
  6617.   │  Error codes     Chart_no_memory                 3                        │
  6618.   │                                                                           │
  6619.   └───────────────────────────────────────────────────────────────────────────┘
  6620.  
  6621.  
  6622.  
  6623.   The following illustrates defining a heading and left margin.
  6624.  
  6625.  
  6626.   ┌───────────────────────────────────────────────────────────────────────────┐
  6627.   │                                                                           │
  6628.   │  BOOL            fAns;                   // Successful call indicator     │
  6629.   │  static HWND     hChart;                 // Bar chart handle              │
  6630.   │                                                                           │
  6631.   │  fAns = ChartText(hChart,                // Chart handle                  │
  6632.   │                   "Monthly Sales",       // Title                         │
  6633.   │                   NULL,                  // No footing                    │
  6634.   │                   "Actual",              // Left margin                   │
  6635.   │                   NULL);                 // No right margin               │
  6636.   │                                                                           │
  6637.   └───────────────────────────────────────────────────────────────────────────┘
  6638.  
  6639.  
  6640.  
  6641.  
  6642.  
  6643.  
  6644.  
  6645.  
  6646.  
  6647.  
  6648.  
  6649.  
  6650.  
  6651.  
  6652.  
  6653.  
  6654.  
  6655.  
  6656.  
  6657.  
  6658.  
  6659.  
  6660.  
  6661.  
  6662.  
  6663.  
  6664.  
  6665.  
  6666.  
  6667.  
  6668.  
  6669.                                 112
  6670.  
  6671.  
  6672.  
  6673.   ChartVisible - Draw the chart
  6674.   ═════════════════════════════
  6675.  
  6676.   ChartVisible(hchart);
  6677.  
  6678.   The "ChartVisible" function paints the chart specified by the "ChartCreate"
  6679.   function containing data defined in the "ChartData" function.
  6680.  
  6681.    See also: "ChartPaint"
  6682.  
  6683.  
  6684.   ┌───────────────────────────────────────────────────────────────────────────┐
  6685.   │                                                                           │
  6686.   │   ans = ChartVisible(hchart);            // Chart handle                  │
  6687.   │                                                                           │
  6688.   └───────────────────────────────────────────────────────────────────────────┘
  6689.  
  6690.  
  6691.   The "ChartVisible" function parameters are as follows:
  6692.  
  6693.   ans          Provides TRUE for a successful request or FALSE for an
  6694.   (BOOL)       unsuccessful request.  If a FALSE indicator is returned, check
  6695.                the "error" code location specified in the "ChartCreate"
  6696.                function.
  6697.  
  6698.   hchart       Specifies the handle returned by the "ChartCreate" function.
  6699.   (HWND)
  6700.  
  6701.  
  6702.   ┌───────────────────────────────────────────────────────────────────────────┐
  6703.   │                                                                           │
  6704.   │  Error codes     Chart_invalid_client            1                        │
  6705.   │                  Chart_not_defined               2                        │
  6706.   │                  Chart_no_memory                 3                        │
  6707.   │                  Chart_no_data                   9                        │
  6708.   │                  Chart_memory_release           12                        │
  6709.   │                                                                           │
  6710.   └───────────────────────────────────────────────────────────────────────────┘
  6711.  
  6712.  
  6713.  
  6714.  
  6715.  
  6716.  
  6717.  
  6718.  
  6719.  
  6720.  
  6721.  
  6722.  
  6723.  
  6724.  
  6725.  
  6726.  
  6727.                                 113
  6728.  
  6729.  
  6730.  
  6731.   The following illustrates making a chart visible.
  6732.  
  6733.  
  6734.   ┌───────────────────────────────────────────────────────────────────────────┐
  6735.   │                                                                           │
  6736.   │  BOOL            fAns;                   // Successful call indicator     │
  6737.   │  static HWND     hChart;                 // Bar chart handle              │
  6738.   │                                                                           │
  6739.   │  fAns = ChartVisible(hChart);            // Chart handle                  │
  6740.   │                                                                           │
  6741.   └───────────────────────────────────────────────────────────────────────────┘
  6742.  
  6743.  
  6744.  
  6745.  
  6746.  
  6747.  
  6748.  
  6749.  
  6750.  
  6751.  
  6752.  
  6753.  
  6754.  
  6755.  
  6756.  
  6757.  
  6758.  
  6759.  
  6760.  
  6761.  
  6762.  
  6763.  
  6764.  
  6765.  
  6766.  
  6767.  
  6768.  
  6769.  
  6770.  
  6771.  
  6772.  
  6773.  
  6774.  
  6775.  
  6776.  
  6777.  
  6778.  
  6779.  
  6780.  
  6781.  
  6782.  
  6783.                                 114
  6784.  
  6785.  
  6786.  
  6787.       Installation
  6788.       ════════════
  6789.  
  6790.       To use this mini-release on you system, you must copy the following files
  6791.       to directories which are customary on your development system.
  6792.  
  6793.           CHART32.DLL
  6794.           CHART32.LIB
  6795.           CHART.H
  6796.  
  6797.  
  6798.  
  6799.  
  6800.       Compiling and Linking you program
  6801.       ═════════════════════════════════
  6802.  
  6803.       The following statements are generally used with the IBM C/C++ tool set
  6804.       to compile and link an application program called "DEMO".
  6805.  
  6806.           icc /Kbcr /W1  /Gs /Gm /C  DEMO.C
  6807.           LINK386  /NOI  DEMO,DEMO,NUL,CHART32.LIB,DEMO.DEF;
  6808.           RC DEMO.RC
  6809.  
  6810.  
  6811.       The Sample Program
  6812.       ══════════════════
  6813.  
  6814.       Before the programmer begins programming, please review the sample 
  6815.       program "DEMO.C" for and example of how to create a 3-D bar chart.
  6816.  
  6817.  
  6818.  
  6819.  
  6820.  
  6821.  
  6822.  
  6823.  
  6824.  
  6825.  
  6826.  
  6827.  
  6828.  
  6829.  
  6830.  
  6831.  
  6832.  
  6833.  
  6834.  
  6835.  
  6836.  
  6837.  
  6838.  
  6839.  
  6840.  
  6841.                                 115
  6842.