?lang_form? ?lang_select? ?lang_submit? ?lang_endform?
{HEADER END}
{BLAME START}

library

?curdirlinks? -

Blame information for rev 32

Line No. Rev Author Line
1 32 kaklik /*****************************************************************************
2 * Module for Microchip Graphics Library
3 * GOL Layer
4 * Chart
5 *****************************************************************************
6 * FileName: Chart.h
7 * Dependencies: None
8 * Processor: PIC24F, PIC24H, dsPIC, PIC32
9 * Compiler: MPLAB C30 V3.00, MPLAB C32
10 * Linker: MPLAB LINK30, MPLAB LINK32
11 * Company: Microchip Technology Incorporated
12 *
13 * Software License Agreement
14 *
15 * Copyright © 2008 Microchip Technology Inc. All rights reserved.
16 * Microchip licenses to you the right to use, modify, copy and distribute
17 * Software only when embedded on a Microchip microcontroller or digital
18 * signal controller, which is integrated into your product or third party
19 * product (pursuant to the sublicense terms in the accompanying license
20 * agreement).
21 *
22 * You should refer to the license agreement accompanying this Software
23 * for additional information regarding your rights and obligations.
24 *
25 * SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY
26 * KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY
27 * OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR
28 * PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR
29 * OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION,
30 * BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT
31 * DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL,
32 * INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA,
33 * COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY
34 * CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF),
35 * OR OTHER SIMILAR COSTS.
36 *
37 * Author Date Comment
38 *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39 * Paolo A. Tamayo
40 * Anton Alkhimenok 4/8/08 ...
41 *****************************************************************************/
42 #ifndef _CHART_H
43 #define _CHART_H
44  
45 #include <Graphics\GOL.h>
46  
47 /*
48 Chart Terminologies
49  
50 Value Axis - This is the vertical range of a chart for normal bar charts and
51 horizontal range of the chart for horizontally drawn bar charts.
52 In most cases this axis will represent values ($ amounts), temperatures,
53 or other numeric data. Definition for Value Axis and Sample Axis
54 are flipped when chart is drawn horizontally.
55 Sample Axis - This is the horizontal range of a chart for normal bar charts and
56 vertical range of the chart for horizontally drawn bar charts.
57 In most cases this axis will represent categories, such as months,
58 sample segments, or other non-numeric data. Definition for Value Axis
59 and Sample Axis are flipped when chart is drawn horizontally.
60 Title - The text used to define the Title of the chart.
61 Data Points (or the sample points) These are the individual points where a value
62 is graphed, as a point on a line, a bar, or a pie slice.
63 Data Series - A complete series of data, distinguished by the same color and type of sample point.
64 Legend - Labels that indicate how each data series is displayed on the chart.
65 Each color represents a different data series. For pie charts with only one data
66 series shown, each color represent one sector or one one sample point.
67 Data Sample Range - The scale for the data sample axis. Example: months from
68 January to December. Internally, this range is represented by:
69 Numeric Sequence 1, 2, 3, ... and so on
70 Alphabet Sequence A, B, C, .. and so on.
71 Value Range - The scale for the value axis.
72 Example: range of numbers from the lowest to the highest to be charted.
73  
74 */
75  
76 /*********************************************************************
77 * Object States Definition:
78 *********************************************************************/
79 #define CH_DISABLED 0x0002 // Bit for disabled state.
80 #define CH_LEGEND 0x0001 // Bit to indicate that legend is to be shown. Usable only when seriesCount > 1.
81 #define CH_VALUE 0x0004 // Bit to indicate that the values of the bar chart data or pie chart
82  
83 // data are to be shown
84 #define CH_3D_ENABLE 0x0008 // Bit to indicate that bar charts are to be drawn with 3-D effect
85 #define CH_PIE 0x0100 // Bit to indicate the chart is type pie. If both PIE and BAR types
86  
87 // are set BAR type has higher priority.
88 #define CH_BAR 0x0200 // Bit to indicate the chart is type bar. If both PIE and BAR types
89  
90 // are set BAR type has higher priority.
91 #define CH_PERCENT 0x0010 // Bit to indicate that the pie chart will be drawn with percentage
92  
93 // values shown for the sample data. For bar chart, if CH_VALUE is set,
94 // it toggles the value shown to percentage.
95 #define CH_BAR_HOR 0x0240 // These bits (with CH_BAR bit set), sets the bar chart to
96  
97 // be drawn horizontally.
98 #define CH_DONUT 0x0140 // These bits (with CH_PIE bit set), sets the pie chart to
99  
100 // be drawn in a donut shape.
101 #define CH_NUMERIC 0x0080 // This bit is used only for bar charts. If this bit is set, it indicates that the
102  
103 // bar chart labels for variables are numeric. If this bit is not set, it indicates
104 // that the bar chart labels for variables are alphabets.
105 #define CH_DRAW_DATA 0x2000 // Bit to indicate data portion of the chart must be redrawn.
106 #define CH_DRAW 0x4000 // Bit to indicate chart must be redrawn.
107 #define CH_HIDE 0x8000 // Bit to indicate chart must be removed from screen.
108  
109 /*********************************************************************
110 * Data Series Show Flag Definitions:
111 *********************************************************************/
112 #define SHOW_DATA 1 // Macro used to set the data series show flag or indicate that the data series will be shown when the chart is drawn.
113 #define HIDE_DATA 0 // Macro used to reset the data series show flag or indicate that the data series will be not be shown when the chart is drawn.
114  
115 /* Internal Definitions - used to modify some specific rendering characteristics */
116 #define CH_MARGIN 2 // Margin from the edges.
117 #define CH_YGRIDCOUNT 6 // defines the number of grids to be drawn on the y-axis (includes the origin at y).
118 #define USE_HORZ_ASCENDING_ORDER // use ascending order when displaying variables on horizontal mode (bar chart only)
119 #define USE_PIE_ENABLE_LABEL // use labels: A:10%,30 where each sample is labeled A-Z followed by a colon.
120  
121 /*********************************************************************
122 * Overview: Defines a variable for the CHART object. It specifies
123 * the number of samples, pointer to the array of samples
124 * for the data series and pointer to the next data series.
125 * A member of this structure (show) is used as a flag to
126 * determine if the series is to be drawn or not. Together with
127 * the smplStart and smplEnd it will determine what kind of
128 * chart will be drawn.
129 *
130 *********************************************************************/
131 typedef struct
132 {
133 XCHAR *pSData; // Pointer to the data series name.
134 WORD samples; // Indicates the number of data samples (or data points) contained in the array specified by pData.
135 BYTE show; // The flag to indicate if the data series will be shown or not. If this flag is set to SHOW_DATA, the data series will be shown. If HIDE_DATA, the data series will not be shown.
136 WORD *pData; // Pointer to the array of data samples.
137 void *pNextData; // Pointer to the next data series. NULL if no other data series follows.
138 } DATASERIES;
139  
140 /*********************************************************************
141 * Overview: Defines the parameters for the CHART object.
142 *
143 *********************************************************************/
144 typedef struct
145 {
146 XCHAR *pTitle; // Pointer to the Title of the chart.
147 XCHAR *pSmplLabel; // Pointer to the bar chart sample axis label. Depending
148  
149 // if the bar chart is drawn vertically or horizontally, the
150 // location of the sample will be in the x-axis or y-axis.
151 XCHAR *pValLabel; // Pointer to the bar chart value axis label. Depending
152  
153 // if the bar chart is drawn vertically or horizontally, the
154 // location of the sample will be in the x-axis or y-axis.
155 SHORT seriesCount; // Number of data series that will be displayed when chart is drawn.
156 WORD smplStart; // Start point of data sample range to be displayed (minimum/default value = 1)
157 WORD smplEnd; // End point of data sample range to be displayed.
158 WORD valMax; // Maximum value of a sample that can be displayed.
159 WORD valMin; // Minimum value of a sample that can be displayed.
160 WORD perMax; // Maximum value of the percentage range that can be displayed.
161 WORD perMin; // Minimum value of the percentage range that can be displayed.
162 WORD *pColor; // Pointer to the color table used to draw the chart data.
163 void *pTitleFont; // Pointer to the font used for the title label of the chart.
164 void *pAxisLabelsFont; // Pointer to the font used for X and Y axis labels.
165 void *pGridLabelsFont; // Pointer to the font used for X and Y axis grid labels.
166 } CHARTPARAM;
167  
168 /*********************************************************************
169 * Overview: Defines the parameters required for a chart Object.
170 *
171 *********************************************************************/
172 typedef struct
173 {
174 OBJ_HEADER hdr; // Generic header for all Objects (see OBJ_HEADER).
175 CHARTPARAM prm; // Structure for the parameters of the chart.
176 DATASERIES *pChData; // Pointer to the first chart data series in the link list of data series.
177 } CHART;
178  
179 /*********************************************************************
180 * Data Color Table
181 * - The following macroses defines the default colors used when
182 * rendering chart data.
183 *********************************************************************/
184 #ifdef USE_PALETTE
185  
186 #include "PaletteColorDefines.h"
187  
188 #else
189  
190 #define CH_CLR0 BRIGHTBLUE // Bright Blue
191 #define CH_CLR1 BRIGHTRED // Bright Red
192 #define CH_CLR2 BRIGHTGREEN // Bright Green
193 #define CH_CLR3 BRIGHTYELLOW // Bright Yellow
194 #define CH_CLR4 RGB565CONVERT(0xFF, 0xBB, 0x4C) // Orange
195 #define CH_CLR5 BLUE // Blue
196 #define CH_CLR6 RED // Red
197 #define CH_CLR7 GREEN // Green
198 #define CH_CLR8 YELLOW // Yellow
199 #define CH_CLR9 RGB565CONVERT(255, 140, 0) // Dark Orange
200 #define CH_CLR10 LIGHTBLUE // Light Orange
201 #define CH_CLR11 LIGHTRED // Light Red
202 #define CH_CLR12 LIGHTGREEN // Light Green
203 #define CH_CLR13 RGB565CONVERT(255, 255, 150) // Light Yellow
204 #define CH_CLR14 RGB565CONVERT(255, 200, 0) // Light Orange
205 #define CH_CLR15 RGB565CONVERT(255, 215, 0) // Gold
206  
207 #endif
208  
209 SHORT ChSetDataSeries(CHART *pCh, WORD seriesNum, BYTE status);
210  
211 /*********************************************************************
212 * Function: CHART *ChCreate( WORD ID, SHORT left, SHORT top,
213 * SHORT right, SHORT bottom,
214 * WORD state, DATASERIES *pData,
215 * CHARTPARAM *pParam, GOL_SCHEME *pScheme)
216 *
217 * Overview: This function creates a CHART object with the parameters given.
218 * It automatically attaches the new object into a global linked list of
219 * objects and returns the address of the object.
220 *
221 * PreCondition: none
222 *
223 * Input: ID - Unique user defined ID for the object instance.
224 * left - Left most position of the object.
225 * top - Top most position of the object.
226 * right - Right most position of the object.
227 * bottom - Bottom most position of the object.
228 * state - Sets the initial state of the object.
229 * pData - Pointer to the data for the contents of the chart. NULL can
230 * be assigned initially when creating the object.
231 * pParam - Pointer to the chart parameters. NULL can be assigned initially
232 * when creating the object and the chart parameters can be
233 * populated using the API provided.
234 * pScheme - Pointer to the style scheme used. When set to NULL,
235 * the default style scheme will be used.
236 *
237 * Output: Returns the pointer to the object created.
238 *
239 * Example:
240 * <CODE>
241 *
242 * extern const FONT_FLASH GOLSmallFont;
243 * extern const FONT_FLASH GOLMediumFont;
244 *
245 * // Note that strings are declared as such to cover cases
246 * // where XCHAR type is declared as short (2 bytes).
247 * XCHAR ChTitle[] = {'E','x','a','m','p','l','e',0};
248 * XCHAR SampleName[] = {'C','a','t','e','g','o','r','y',0};
249 * XCHAR ValueName[] = {'#','H','i','t','s',0};
250 * XCHAR SeriesName[2] = {
251 * {'V','1',0},
252 * {'V','2',0},
253 * };
254 * V1Data[2] = { 50, 100};
255 * V2Data[2] = { 5, 10};
256 *
257 * GOL_SCHEME *pScheme;
258 * CHART *pChart;
259 * CHARTPARAM Contents;
260 * WORD state;
261 *
262 * pScheme = GOLCreateScheme();
263 * state = CH_BAR|CH_DRAW|CH_BAR_HOR; // Bar Chart to be drawn with horizontal orientation
264 *
265 *
266 * pChart = ChCreate(0x01, // ID
267 * 0, 0, // dimensions
268 * GetMaxX(),
269 * GetMaxY(),
270 * state, // state of the chart
271 * NULL, // data not initialized yet
272 * NULL, // no parameters yet
273 * pScheme); // style scheme used
274 *
275 * if (pMyChart == NULL) // check if chart was allocated memory
276 * return 0;
277 *
278 * ChSetTitleFont(pChart, (void*)&GOLMediumFont);
279 * ChSetTitle(pChart, ChTitle); // set the title
280 *
281 * // set the grid labels and axis labels font
282 * ChSetGridLabelFont(pChart, (void*)&GOLSmallFont);
283 * ChSetAxisLabelFont(pChart, (void*)&GOLSmallFont);
284 *
285 * // set the labels for the X and Y axis
286 * ChSetSampleLabel(pChart, (XCHAR*)SampleName);
287 * ChSetValueLabel(pChart, (XCHAR*)ValueName);
288 *
289 * ChAddDataSeries(pChart, 2, V1Data, (XCHAR*)SeriesName[0]);
290 * ChAddDataSeries(pChart, 2, V2Data, (XCHAR*)SeriesName[1]);
291 *
292 * // set the range of the sample values
293 * ChSetValueRange(pChart, 0, 100);
294 *
295 * // show all two samples to be displayed (start = 1, end = 2)
296 * ChSetSampleRange(pChart, 1, 2);
297 *
298 * GOLDraw(); // draw the chart
299 *
300 * </CODE>
301 *
302 * Side Effects: none
303 *
304 ********************************************************************/
305 CHART *ChCreate
306 (
307 WORD ID,
308 SHORT left,
309 SHORT top,
310 SHORT right,
311 SHORT bottom,
312 WORD state,
313 DATASERIES *pData,
314 CHARTPARAM *pParam,
315 GOL_SCHEME *pScheme
316 );
317  
318 /*********************************************************************
319 * Function: ChAddDataSeries(CHART *pCh, WORD nSamples, WORD *pData, XCHAR *pName)
320 *
321 * Overview: This function creates a DATASERIES object and
322 * populates the structure with the given parameters.
323 *
324 * PreCondition: none
325 *
326 * Input: pCh - Pointer to the chart object.
327 * nSamples - The number of samples or data points.
328 * pData - Pointer to the array of samples or data points.
329 * pName - Pointer to the string used to label the data series.
330 *
331 * Output: Returns the pointer to the data variable (DATASERIES) object created.
332 * If NULL is returned, the addition of the new object failed due to
333 * not enough memory for the object.
334 *
335 * Example: See ChCreate() example.
336 *
337 * Side Effects: Appends to the list of DATASERIES that the chart is operating on.
338 * By default, the show flag of the newly added data series is set to
339 * SHOW_DATA or enabled.
340 *
341 ********************************************************************/
342 DATASERIES *ChAddDataSeries(CHART *pCh, WORD nSamples, WORD *pData, XCHAR *pName);
343  
344 /*********************************************************************
345 * Function: ChRemoveDataSeries(CHART *pCh, WORD number)
346 *
347 * Overview: This function removes DATASERIES object from the list of
348 * DATASERIES objects and frees the memory used of that removed object.
349 * The position of the object to be removed is specified by the number
350 * parameter. If the list has only one member, it removes the member
351 * regardless of the number given.
352 *
353 * PreCondition: none
354 *
355 * Input: pCh - Pointer to the chart object.
356 * number - The position of the object to be removed in the list where
357 * the first object in the list is assigned a value of 1.
358 * If this parameter is set to zero, the whole list of
359 * DATA_SERIES is removed.
360 *
361 * Output: none.
362 *
363 *
364 * Example:
365 * <CODE>
366 *
367 * void ClearChartData(CHART *pCh) {
368 * if(pCh->pChData != NULL)
369 * // remove the all data series
370 * ChRemoveDataSeries(pCh, 0);
371 * }
372 * </CODE>
373 *
374 * Side Effects: none.
375 *
376 ********************************************************************/
377 void ChRemoveDataSeries(CHART *pCh, WORD number);
378  
379 /*********************************************************************
380 * Macros: SHORT ChShowSeries(CHART *pCh, WORD seriesNum)
381 *
382 * Overview: This macro sets the specified data series number
383 * show flag to be set to SHOW_DATA.
384 *
385 * PreCondition: none
386 *
387 * Input: pCh - Pointer to the chart object.
388 * seriesNum - The data series number that will be modified.
389 * If this number is zero, all the entries' flag in the
390 * list will be set to SHOW_DATA.
391 *
392 * Output: Returns the same passed number if successful otherwise
393 * -1 if unsuccesful.
394 *
395 * Example:
396 * <CODE>
397 * // from the example in ChCreate() we change the items to be shown when
398 * // GOLDraw() is called.
399 *
400 * // reset all data series to be HIDE_DATA
401 * ChHideSeries(pMyChart, 0);
402 * // set data series 1 (V1Data) to be shown
403 * ChShowSeries(pMyChart, 1);
404 * // draw the chart
405 * GOLDraw();
406 * .....
407 * </CODE> *
408 * Side Effects: none
409 *
410 ********************************************************************/
411 #define ChShowSeries(pCh, seriesNum) (ChSetDataSeries(pCh, seriesNum, SHOW_DATA))
412  
413 /*********************************************************************
414 * Macros: SHORT ChHideSeries(CHART *pCh, WORD seriesNum)
415 *
416 * Overview: This macro sets the specified data series number
417 * show flag to be set to HIDE_DATA.
418 *
419 * PreCondition: none
420 *
421 * Input: pCh - Pointer to the chart object.
422 * seriesNum - The data series number that will be modified.
423 * If this number is zero, all the entries' flag in the
424 * list will be set to HIDE_DATA.
425 *
426 * Output: Returns the same passed number if successful otherwise
427 * -1 if unsuccesful.
428 *
429 * Example: See ChShowSeries() example.
430 *
431 * Side Effects: none
432 *
433 ********************************************************************/
434 #define ChHideSeries(pCh, seriesNum) (ChSetDataSeries(pCh, seriesNum, HIDE_DATA))
435  
436 /*********************************************************************
437 * Macros: ChGetShowSeriesCount(pCh)
438 *
439 * Overview: This macro shows the number of data series that has
440 * its show flag set to SHOW_DATA
441 *
442 * PreCondition: none
443 *
444 * Input: pCh - Pointer to the object.
445 *
446 * Output: Returns the number of data series with its show flag set to
447 * SHOW_DATA.
448 *
449 * Side Effects: none
450 *
451 ********************************************************************/
452 #define ChGetShowSeriesCount(pCh) (pCh->prm.seriesCount)
453  
454 /*********************************************************************
455 * Macros: ChGetShowSeriesStatus(pDSeries)
456 *
457 * Overview: This macro returns the show ID status of the DATASERIES.
458 *
459 * PreCondition: none
460 *
461 * Input: pDSeries - Pointer to the data series(DATASERIES) that is
462 * being checked.
463 *
464 * Output: Returns the status of the show flag.
465 * 1 - (SHOW_DATA) means that the show status flag is set.
466 * 0 - (HIDE_DATA) means that the show status flag is not set.
467 *
468 * Side Effects: none
469 *
470 ********************************************************************/
471 #define ChGetShowSeriesStatus(pDSeries) (pDSeries->show)
472  
473 /*********************************************************************
474 * Macros: ChGetValueMax(pCh)
475 *
476 * Overview: This macro returns the current maximum value that will
477 * be drawn for bar charts.
478 *
479 * PreCondition: none
480 *
481 * Input: pCh - Pointer to the object.
482 *
483 * Output: Returns the maximum value set when bar charts are drawn.
484 *
485 * Side Effects: none
486 *
487 ********************************************************************/
488 #define ChGetValueMax(pCh) (pCh->prm.valMax)
489  
490 /*********************************************************************
491 * Macros: ChGetValueMin(pCh)
492 *
493 * Overview: This macro returns the current minimum value that will
494 * be drawn for bar charts.
495 *
496 * PreCondition: none
497 *
498 * Input: pCh - Pointer to the object.
499 *
500 * Output: Returns the minimum value set when bar charts are drawn.
501 *
502 * Side Effects: none
503 *
504 ********************************************************************/
505 #define ChGetValueMin(pCh) (pCh->prm.valMin)
506  
507 /*********************************************************************
508 * Function: ChSetValueRange(CHART *pCh, WORD min, WORD max)
509 *
510 * Overview: This function sets the minimum and maximum range of values
511 * that the bar chart will show.
512 * The criteria is that min <= max.
513 *
514 * PreCondition: none
515 *
516 * Input: pCh - Pointer to the chart object.
517 * min - Minimum value that will be displayed in the bar chart.
518 * max - Maximum value that will be displayed in the bar chart.
519 *
520 * Output: none.
521 *
522 * Side Effects: none.
523 *
524 ********************************************************************/
525 void ChSetValueRange(CHART *pCh, WORD min, WORD max);
526  
527 /*********************************************************************
528 * Function: ChGetValueRange(pCh)
529 *
530 * Overview: This macro gets the current range for bar charts.
531 * The value returned is calculated from the current (valMax - valMin) set.
532 * To get the minimum use ChGetValueMin() and to get the
533 * maximum use ChGetValueMax().
534 *
535 * PreCondition: none
536 *
537 * Input: pCh - Pointer to the chart object.
538 *
539 * Output: Value range computed from valMax-valMin.
540 *
541 * Side Effects: none.
542 *
543 ********************************************************************/
544 #define ChGetValueRange(pCh) (pCh->prm.valMax - pCh->prm.valMin)
545  
546 /*********************************************************************
547 * Macros: ChGetPercentMax(pCh)
548 *
549 * Overview: This macro returns the current maximum value of the percentage
550 * range that will be drawn for bar charts when CH_PERCENTAGE bit state
551 * is set.
552 *
553 * PreCondition: none
554 *
555 * Input: pCh - Pointer to the object.
556 *
557 * Output: Returns the maximum percentage value set when bar charts are drawn.
558 *
559 * Side Effects: none
560 *
561 ********************************************************************/
562 #define ChGetPercentMax(pCh) (pCh->prm.perMax)
563  
564 /*********************************************************************
565 * Macros: ChGetPercentMin(pCh)
566 *
567 * Overview: This macro returns the current minimum value of the percentage
568 * range that will be drawn for bar charts when CH_PERCENTAGE bit state
569 * is set.
570 *
571 * PreCondition: none
572 *
573 * Input: pCh - Pointer to the object.
574 *
575 * Output: Returns the minimum percentage value when bar charts are drawn.
576 *
577 * Side Effects: none
578 *
579 ********************************************************************/
580 #define ChGetPercentMin(pCh) (pCh->prm.perMin)
581  
582 /*********************************************************************
583 * Function: ChSetPercentRange(CHART *pCh, WORD min, WORD max)
584 *
585 * Overview: This function sets the minimum and maximum range of
586 * percentage that the bar chart will show.
587 * The criteria is that min <= max.
588 * This affects bar charts only and CH_PERCENTAGE bit state is set.
589 *
590 * PreCondition: none
591 *
592 * Input: pCh - Pointer to the chart object.
593 * min - Minimum percentage value that will be displayed in the bar chart.
594 * max - Maximum percentage value that will be displayed in the bar chart.
595 *
596 * Output: none.
597 *
598 * Side Effects: none.
599 *
600 ********************************************************************/
601 void ChSetPercentRange(CHART *pCh, WORD min, WORD max);
602  
603 /*********************************************************************
604 * Function: ChGetPercentRange(pCh)
605 *
606 * Overview: This macro gets the percentage range for bar charts.
607 * The value returned is calculated from percentage max - min.
608 * To get the minimum use ChGetPercentMin() and to get the
609 * maximum use ChGetPercentMax().
610 *
611 * PreCondition: none
612 *
613 * Input: pCh - Pointer to the chart object.
614 *
615 * Output: Percentage range computed from max-min.
616 *
617 * Side Effects: none.
618 *
619 ********************************************************************/
620 #define ChGetPercentRange(pCh) (pCh->prm.perMax - pCh->prm.perMin)
621  
622 /*********************************************************************
623 * Function: ChSetSampleRange(CHART *pCh, WORD start, WORD end)
624 *
625 * Overview: This function sets the sample start and sample end when
626 * drawing the chart. Together with the data series' SHOW_DATA
627 * flags the different way of displaying the chart data is achieved.
628 *
629 * <TABLE>
630 * Start & End Value The # of Data Series Flag Set Chart Description
631 * ################## ############################# ###########
632 * Start <= End 1 Show the data indicated by Start and End points of the DATASERIES with the flag set
633 * Start = End 1 Show the data indicated by Start or End points of the DATASERIES with the flag set
634 * Start, End = don't care > 1 Show the data indicated by Start point of the DATASERIES with the flag set. Each samples of all checked data series are grouped together according to sample number.
635 * </TABLE>
636 *
637 * PreCondition: none
638 *
639 * Input: pCh - Pointer to the chart object.
640 * start - Start point of the data samples to be displayed.
641 * end - End point of the data samples to be displayed.
642 *
643 * Output: none.
644 *
645 * Example: See ChCreate() example.
646 *
647 * Side Effects: none.
648 *
649 ********************************************************************/
650 void ChSetSampleRange(CHART *pCh, WORD start, WORD end);
651  
652 /*********************************************************************
653 * Function: ChGetSampleRange(pCh)
654 *
655 * Overview: This macro gets the sample range for pie or bar charts.
656 * The value returned is calculated from smplEnd - smplStart.
657 *
658 * PreCondition: none
659 *
660 * Input: pCh - Pointer to the chart object.
661 *
662 * Output: Sample range computed from smplEnd - smplStart.
663 *
664 * Side Effects: none.
665 *
666 ********************************************************************/
667 #define ChGetSampleRange(pCh) (ChGetSampleEnd(pCh) - ChGetSampleStart(pCh))
668  
669 /*********************************************************************
670 * Macros: ChGetSampleStart(pCh)
671 *
672 * Overview: This macro returns the sampling start value.
673 *
674 * PreCondition: none
675 *
676 * Input: pCh - Pointer to the object.
677 *
678 * Output: Returns the sample start point.
679 *
680 * Side Effects: none
681 *
682 ********************************************************************/
683 #define ChGetSampleStart(pCh) (((CHART *)pCh)->prm.smplStart)
684  
685 /*********************************************************************
686 * Macros: ChGetSampleEnd(pCh)
687 *
688 * Overview: This macro returns the sampling end value.
689 *
690 * PreCondition: none
691 *
692 * Input: pCh - Pointer to the object.
693 *
694 * Output: Returns the sample end point.
695 *
696 * Side Effects: none
697 *
698 ********************************************************************/
699 #define ChGetSampleEnd(pCh) ((CHART *)pCh)->prm.smplEnd
700  
701 /*********************************************************************
702 * Macros: ChSetTitle(pCh, pNewTitle)
703 *
704 * Overview: This macro sets the address of the current
705 * text string used for the title of the chart.
706 *
707 * PreCondition: none
708 *
709 * Input: pCh - Pointer to the object.
710 * pNewTitle - pointer to the string to be used as a title
711 * of the chart.
712 *
713 * Output: none.
714 *
715 * Example: See ChCreate() example.
716 *
717 * Side Effects: none
718 *
719 ********************************************************************/
720 #define ChSetTitle(pCh, pNewTitle) (((CHART *)pCh)->prm.pTitle = pNewTitle)
721  
722 /*********************************************************************
723 * Macros: ChGetTitle(pCh)
724 *
725 * Overview: This macro returns the address of the current
726 * text string used for the title of the chart.
727 *
728 * PreCondition: none
729 *
730 * Input: pCh - Pointer to the object.
731 *
732 * Output: Returns the pointer to the current title text used.
733 *
734 * Side Effects: none
735 *
736 ********************************************************************/
737 #define ChGetTitle(pCh) (((CHART *)pCh)->prm.pTitle)
738  
739 /*********************************************************************
740 * Macros: ChSetAxisLabelFont(pCh, pNewFont)
741 *
742 * Overview: This macro sets the location of the font used for
743 * the X and Y axis labels of the chart.
744 *
745 * PreCondition: none
746 *
747 * Input: pCh - Pointer to the object.
748 * pNewFont - Pointer to the font used.
749 *
750 * Output: none.
751 *
752 * Example: See ChCreate() example.
753 *
754 * Side Effects: none
755 *
756 ********************************************************************/
757 #define ChSetAxisLabelFont(pCh, pNewFont) (((CHART *)pCh)->prm.pAxisLabelsFont = pNewFont)
758  
759 /*********************************************************************
760 * Macros: ChGetAxisLabelFont(pCh)
761 *
762 * Overview: This macro returns the location of the font used for
763 * the X and Y axis labels of the chart.
764 *
765 * PreCondition: none
766 *
767 * Input: pCh - Pointer to the object.
768 *
769 * Output: Returns the address of the current font used for the title text.
770 *
771 * Side Effects: none
772 *
773 ********************************************************************/
774 #define ChGetAxisLabelFont(pCh) (((CHART *)pCh)->prm.pAxisLabelsFont)
775  
776 /*********************************************************************
777 * Macros: ChSetGridLabelFont(pCh, pNewFont)
778 *
779 * Overview: This macro sets the location of the font used for
780 * the X and Y axis grid labels of the chart.
781 *
782 * PreCondition: none
783 *
784 * Input: pCh - Pointer to the object.
785 * pNewFont - Pointer to the font used.
786 *
787 * Output: none.
788 *
789 * Example: See ChCreate() example.
790 *
791 * Side Effects: none
792 *
793 ********************************************************************/
794 #define ChSetGridLabelFont(pCh, pNewFont) (((CHART *)pCh)->prm.pGridLabelsFont = pNewFont)
795  
796 /*********************************************************************
797 * Macros: ChGetGridLabelFont(pCh)
798 *
799 * Overview: This macro returns the location of the font used for
800 * the X and Y axis grid labels of the chart.
801 *
802 * PreCondition: none
803 *
804 * Input: pCh - Pointer to the object.
805 *
806 * Output: Returns the address of the current font used for the title text.
807 *
808 * Side Effects: none
809 *
810 ********************************************************************/
811 #define ChGetGridLabelFont(pCh) (((CHART *)pCh)->prm.pGridLabelsFont)
812  
813 /*********************************************************************
814 * Macros: ChSetTitleFont(pCh, pNewFont)
815 *
816 * Overview: This macro sets the location of the font used for
817 * the title of the chart.
818 *
819 * PreCondition: none
820 *
821 * Input: pCh - Pointer to the object.
822 * pNewFont - Pointer to the font used.
823 *
824 * Output: none.
825 *
826 * Example: See ChCreate() example.
827 *
828 * Side Effects: none
829 *
830 ********************************************************************/
831 #define ChSetTitleFont(pCh, pNewFont) (((CHART *)pCh)->prm.pTitleFont = pNewFont)
832  
833 /*********************************************************************
834 * Macros: ChGetTitleFont(pCh)
835 *
836 * Overview: This macro returns the location of the font used for
837 * the title of the chart.
838 *
839 * PreCondition: none
840 *
841 * Input: pCh - Pointer to the object.
842 *
843 * Output: Returns the address of the current font used for the title text.
844 *
845 * Side Effects: none
846 *
847 ********************************************************************/
848 #define ChGetTitleFont(pCh) (((CHART *)pCh)->prm.pTitleFont)
849  
850 /*********************************************************************
851 * Macros: ChSetSampleLabel(pCh, pNewXLabel)
852 *
853 * Overview: This macro sets the address of the current
854 * text string used for the sample axis label of the bar chart.
855 *
856 * PreCondition: none
857 *
858 * Input: pCh - Pointer to the object.
859 * pNewXLabel - pointer to the string to be used as an sample
860 * axis label of the bar chart.
861 *
862 * Output: none.
863 *
864 * Example: See ChCreate() example.
865 *
866 * Side Effects: none
867 *
868 ********************************************************************/
869 #define ChSetSampleLabel(pCh, pNewXLabel) (((CHART *)pCh)->prm.pSmplLabel = pNewXLabel)
870  
871 /*********************************************************************
872 * Macros: ChGetSampleLabel(pCh)
873 *
874 * Overview: This macro returns the address of the current
875 * text string used for the sample axis label of the bar chart.
876 *
877 * PreCondition: none
878 *
879 * Input: pCh - Pointer to the object.
880 *
881 * Output: Returns the pointer to the current sample axis label text
882 * of the bar chart.
883 *
884 * Side Effects: none
885 *
886 ********************************************************************/
887 #define ChGetSampleLabel(pCh) (((CHART *)pCh)->prm.pSmplLabel)
888  
889 /*********************************************************************
890 * Macros: ChSetValueLabel(pCh, pNewYLabel)
891 *
892 * Overview: This macro sets the address of the current
893 * text string used for the value axis label of the bar chart.
894 *
895 * PreCondition: none
896 *
897 * Input: pCh - Pointer to the object.
898 * pNewYLabel - pointer to the string to be used as an value
899 * axis label of the bar chart.
900 *
901 * Output: none.
902 *
903 * Example: See ChCreate() example.
904 *
905 * Side Effects: none
906 *
907 ********************************************************************/
908 #define ChSetValueLabel(pCh, pNewValueLabel) (((CHART *)pCh)->prm.pValLabel = pNewValueLabel)
909  
910 /*********************************************************************
911 * Macros: ChGetValueLabel(pCh)
912 *
913 * Overview: This macro returns the address of the current
914 * text string used for the value axis label of the bar chart.
915 *
916 * PreCondition: none
917 *
918 * Input: pCh - Pointer to the object.
919 *
920 * Output: Returns the pointer to the current value axis label text
921 * of the bar chart.
922 *
923 * Side Effects: none
924 *
925 ********************************************************************/
926 #define ChGetValueLabel(pCh) (((CHART *)pCh)->prm.pValLabel)
927  
928 /*********************************************************************
929 * Macros: ChSetColorTable(pCh, pNewTable)
930 *
931 * Overview: This macro sets the color table used to draw the data
932 * in pie and bar charts.
933 *
934 * PreCondition: none
935 *
936 * Input: pCh - Pointer to the object.
937 * pNewTable - Pointer to the color table that will be used.
938 *
939 * Output: none.
940 *
941 * Side Effects: none
942 *
943 ********************************************************************/
944 #define ChSetColorTable(pCh, pNewTable) ((((CHART *)pCh)->prm.pColor) = pNewTable)
945  
946 /*********************************************************************
947 * Macros: ChGetColorTable(pCh)
948 *
949 * Overview: This macro returns the current color table used for
950 * the pie and bar charts.
951 *
952 * PreCondition: none
953 *
954 * Input: pCh - Pointer to the object.
955 *
956 * Output: Returns the address of the color table used.
957 *
958 * Side Effects: none
959 *
960 ********************************************************************/
961 #define ChGetColorTable(pCh) (((CHART *)pCh)->prm.pColor)
962  
963 /*********************************************************************
964 * Function: ChTranslateMsg(CHART *pCh, GOL_MSG *pMsg)
965 *
966 * Overview: This function evaluates the message from a user if the
967 * message will affect the object or not. The table below enumerates
968 * the translated messages for each event of the touch screen
969 * and keyboard inputs.
970 *
971 * <TABLE>
972 * Translated Message Input Source Events Description
973 * ################## ############ ###### ###########
974 * CH_MSG_SELECTED Touch Screen EVENT_PRESS, EVENT_RELEASE, EVENT_MOVE If events occurs and the x,y position falls in the area of the chart.
975 * OBJ_MSG_INVALID Any Any If the message did not affect the object.
976 * </TABLE>
977 *
978 * PreCondition: none
979 *
980 * Input: pCh - The pointer to the object where the message will be
981 * evaluated to check if the message will affect the object.
982 * pMsg - Pointer to the message struct containing the message from
983 * the user interface.
984 *
985 * Output: Returns the translated message depending on the received GOL message:
986 * - CH_MSG_SELECTED – Chart area is selected
987 * - OBJ_MSG_INVALID – Chart is not affected
988 *
989 * Output: none.
990 *
991 * Side Effects: none
992 *
993 ********************************************************************/
994 WORD ChTranslateMsg(CHART *pCh, GOL_MSG *pMsg);
995  
996 /*********************************************************************
997 * Function: ChDraw(CHART *pCh)
998 *
999 * Overview: This function renders the object on the screen using
1000 * the current parameter settings. Location of the object is
1001 * determined by the left, top, right and bottom parameters.
1002 * The colors used are dependent on the state of the object.
1003 * The font used is determined by the style scheme set.
1004 *
1005 * The colors of the bars of the bar chart or sectors of the
1006 * pie chart can be the default color table or user defined
1007 * color table set by ChSetColorTable() function.
1008 *
1009 * When rendering objects of the same type, each object
1010 * must be rendered completely before the rendering of the
1011 * next object is started. This is to avoid incomplete
1012 * object rendering.
1013 *
1014 * PreCondition: Object must be created before this function is called.
1015 *
1016 * Input: pCh - Pointer to the object to be rendered.
1017 *
1018 * Output: Returns the status of the drawing
1019 * - 1 - If the rendering was completed and
1020 * - 0 - If the rendering is not yet finished.
1021 * Next call to the function will resume the
1022 * rendering on the pending drawing state.
1023 *
1024 * Side Effects: none.
1025 *
1026 ********************************************************************/
1027 WORD ChDraw(CHART *pCh);
1028 #endif // _CHART_H
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3