?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 * Meter
5 *****************************************************************************
6 * FileName: Meter.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 * PAT 11/12/07 Version 1.0 release
40 * Albert Z. 07/31/08 Added arc colors options
41 * PAT 08/20/08 Added accuracy option for displaying values
42 * PAT 01/18/10 Fixed MtrIncVal() and MtrDecVal() macros
43 *****************************************************************************/
44 #ifndef _METER_H
45 #define _METER_H
46  
47 #include <Graphics\GOL.h>
48  
49 // Compile time Options for Meter
50 #define METER_DISPLAY_VALUES_ENABLE // This enables the display of the values.
51  
52 // Displaying the values will have significant
53 // drawing time requirement.
54  
55 /*********************************************************************
56 * Object States Definition:
57 *********************************************************************/
58 #define MTR_DISABLED 0x0002 // Bit for disabled state.
59 #define MTR_RING 0x0004 // Bit for ring type, scales are drawn over the ring
60  
61 // default is only scales drawn.
62 #define MTR_ACCURACY 0x0008 // Sets the meter accuracy to one decimal places
63  
64 // when displaying the values. Application must multiply
65 // the minValue, maxValue and values passed to the widget
66 // by RESOLUTION.
67 #define MTR_DRAW_UPDATE 0x1000 // Bit to indicate an update only.
68 #define MTR_DRAW 0x4000 // Bit to indicate object must be redrawn.
69 #define MTR_HIDE 0x8000 // Bit to indicate object must be removed from screen.
70  
71 /*********************************************************************
72 * Used Constants
73 *********************************************************************/
74 #define RADIAN 1144 // Radian definition. Equivalent to sine(1) * 2^16.
75 #define PIIOVER2 102944 // The constant Pii divided by two (pii/2).
76  
77 // Meter types
78 #define MTR_WHOLE_TYPE 0
79 #define MTR_HALF_TYPE 1
80 #define MTR_QUARTER_TYPE 2
81  
82 /***************************************************************************
83 * Overview: This is a compile time setting to select the type if meter shape.
84 * There are three types:
85 * - MTR_WHOLE_TYPE - Meter drawn with 6 octants used.
86 * - MTR_HALF_TYPE - Meter drawn with semi circle shape.
87 * - MTR_QUARTER_TYPE - Meter drawn with quarter circle shape.
88 * Set only one value at a time. This is done to save code space.
89 * User can define the colors of the arcs for each type.
90 * MTR_WHOLE_TYPE will use all the arc colors (arcColor1 - arcColor6)
91 * MTR_HALF_TYPE will use arc colors (arcColor5, arcColor4, arcColor3, arcColor2)
92 * MTR_QUARTER_TYPE will use arc colors (arcColor3, arcColor2)
93 * Set the meter type in Meter.h file and arc colors using
94 * MtrSetScaleColors(pMtr, arc1, arc2, arc3, arc4, arc5, arc6) macro.
95 ***************************************************************************/
96 #define METER_TYPE MTR_WHOLE_TYPE
97  
98 //#define METER_TYPE MTR_HALF_TYPE // Meter drawn with semi circle shape.
99 //#define METER_TYPE MTR_QUARTER_TYPE // Meter drawn with quarter circle shape.
100 #define ARC1_DEGREE 180 // defines one arc1 limit (used for determining colors)
101 #define ARC2_DEGREE 135 // defines one arc2 limit (used for determining colors)
102 #define ARC3_DEGREE 90 // defines one arc3 limit (used for determining colors)
103 #define ARC4_DEGREE 45 // defines one arc4 limit (used for determining colors)
104 #define ARC5_DEGREE 0 // defines one arc5 limit (used for determining colors)
105  
106 // These selects the other parameters of the meter that are dependent on the shape.
107 #if (METER_TYPE == MTR_WHOLE_TYPE)
108 #define DEGREE_START - 45 // Defines the start angle to draw the meter.
109 #define DEGREE_END 225 // Defines the end angle to draw the meter.
110 #elif (METER_TYPE == MTR_HALF_TYPE)
111 #define DEGREE_START 0 // Defines the start angle to draw the meter.
112 #define DEGREE_END 180 // Defines the end angle to draw the meter.
113 #elif (METER_TYPE == MTR_QUARTER_TYPE)
114 #define DEGREE_START 0 // Defines the start angle to draw the meter.
115 #define DEGREE_END 90 // Defines the end angle to draw the meter.
116 #endif
117 #define SCALECHARCOUNT 4 // Defines how many characters will be allocated for the
118  
119 // scale labels. Use this define in accordance to
120 // the maxValue-minValue. Example: if maxValue-minValue = 500, SCALECHARCOUNT
121 // should be 3. if maxValue-minValue = 90, SCALECHARCOUNT = 2
122 // You must include the decimal point if this
123 // feature is enabled (see MTR_ACCURACY state bit).
124 #define DEGREECOUNT 9 // Defines how many degrees per scale, computed per octant
125  
126 // Example: for 5 division per octant 45/5 = 9.
127 // So every 9 degrees a scale is drawn
128 // for a 5 scale division per octant.
129 #define RESOLUTION 10 // Factor that the meter widget will divide minValue, maxValue
130  
131 // and current value. Used only when MTR_ACCURACY state bit is set.
132  
133 /*********************************************************************
134 * Overview: Defines the parameters required for a meter Object.
135 * Depending on the type selected the meter is drawn with
136 * the defined shape parameters and values set on the
137 * given fields.
138 *
139 *********************************************************************/
140 typedef struct
141 {
142 OBJ_HEADER hdr; // Generic header for all Objects (see OBJ_HEADER).
143 XCHAR *pText; // The text label of the meter.
144 SHORT value; // Current value of the meter.
145 SHORT minValue; // minimum value the meter can display
146 SHORT maxValue; // maximum value the meter can display (range is maxValue - minValue)
147 SHORT xCenter; // The x coordinate center position. This is computed automatically.
148 SHORT yCenter; // The y coordinate center position. This is computed automatically.
149 SHORT radius; // Radius of the meter, also defines the needle length.
150  
151 // This is computed automatically.
152 SHORT xPos; // The current x position of the needle. This is computed automatically.
153 SHORT yPos; // The current y position of the needle. This is computed automatically.
154 WORD arcColor6; // Arc 6 color parameter.
155 WORD arcColor5; // Arc 5 color parameter
156 WORD arcColor4; // Arc 4 color parameter
157 WORD arcColor3; // Arc 3 color parameter
158 WORD arcColor2; // Arc 2 color parameter
159 WORD arcColor1; // Arc 1 color parameter
160  
161 // The following three points define three fonts used in meter widget, they can be different from the scheme font.
162 // Note that the sizes of these fonts are not checked with the meter dimension. In cases where font sizes are
163 // larger than the meter dimension, some overlaps will occur.
164 void *pTitleFont; // Pointer to the font used in the title of the meter
165 void *pValueFont; // Pointer to the font used in the current reading (if displayed) of the meter
166 } METER;
167  
168 /*********************************************************************
169 * Function: METER *MtrCreate(WORD ID, SHORT left, SHORT top, SHORT right,
170 * SHORT bottom, WORD state, SHORT value,
171 * SHORT minValue, SHORT maxValue,
172 * XCHAR *pText, GOL_SCHEME *pScheme)
173 *
174 * Overview: This function creates a METER object with the parameters given.
175 * It automatically attaches the new object into a global linked list of
176 * objects and returns the address of the object.
177 *
178 * PreCondition: none
179 *
180 * Input: ID - Unique user defined ID for the object instance.
181 * left - Left most position of the object.
182 * top - Top most position of the object.
183 * right - Right most position of the object.
184 * bottom - Bottom most position of the object.
185 * state - Sets the initial state of the object.
186 * value - Initial value set to the meter.
187 * minValue - The minimum value the meter will display.
188 * maxValue - The maximum value the meter will display.
189 * pText - Pointer to the text label of the meter.
190 * pScheme - Pointer to the style scheme used.
191 *
192 * Output: Returns the pointer to the object created.
193 *
194 * Example:
195 * <CODE>
196 * #define ID_METER 101
197 *
198 * extern const FONT_FLASH GOLMediumFont; // medium font
199 * extern const FONT_FLASH GOLSmallFont; // small font
200 *
201 * GOL_SCHEME *pMeterScheme;
202 * METER *pMtr;
203 *
204 * pMeterScheme = GOLCreateScheme();
205 *
206 * pMtr = MtrCreate(
207 * ID_METER, // assign ID
208 * 30, 50, 150, 180, // set dimension
209 * MTR_DRAW|MTR_RING, // draw object after creation
210 * 0, // set initial value
211 * 0, 100, // set minimum and maximum value
212 * (void*)&GOLMediumFont, // set title font
213 * (void*)&GOLSmallFont, // set value font
214 * "Speed", // Text Label
215 * pMeterScheme); // style scheme
216 *
217 * // check if meter was created
218 * if (pMtr == NULL)
219 * return 0;
220 *
221 * // Change range colors: Normal values to WHITE
222 * // Critical values to BLUE
223 * // Danger values to RED
224 * // assume that WHITE, GREEN, YELLOW and RED have been defined.
225 * MtrSetScaleColors(pMtr, WHITE, WHITE, WHITE, GREEN, YELLOW, RED);
226 *
227 * // use GOLDraw() to draw the meter and all other objects you created
228 * while(!GOLDraw());
229 * // OR to draw the meter manually use this:
230 * //while(!MtrDraw(pMtr);
231 *
232 * </CODE>
233 *
234 * Side Effects: none
235 *
236 ********************************************************************/
237 METER *MtrCreate
238 (
239 WORD ID,
240 SHORT left,
241 SHORT top,
242 SHORT right,
243 SHORT bottom,
244 WORD state,
245 SHORT value,
246 SHORT minValue,
247 SHORT maxValue,
248 void *pTitleFont,
249 void *pValueFont,
250 XCHAR *pText,
251 GOL_SCHEME *pScheme
252 );
253  
254 /*********************************************************************
255 * Function: WORD MtrTranslateMsg(METER *pMtr, GOL_MSG *pMsg)
256 *
257 * Overview: This function evaluates the message from a user if the
258 * message will affect the object or not. The table below enumerates the translated
259 * messages for each event of the touch screen and keyboard inputs.
260 *
261 * <TABLE>
262 * Translated Message Input Source Events Description
263 * ################## ############ ###### ###########
264 * MTR_MSG_SET System EVENT_SET If event set occurs and the meter ID is sent in parameter 1.
265 * OBJ_MSG_INVALID Any Any If the message did not affect the object.
266 * </TABLE>
267 *
268 * PreCondition: none
269 *
270 * Input: pMtr - The pointer to the object where the message will be
271 * evaluated to check if the message will affect the object.
272 * pMsg - Pointer to the message struct containing the message from
273 * the user interface.
274 *
275 * Output: Returns the translated message depending on the received GOL message:
276 * - MTR_MSG_SET - Meter ID is given in parameter 1 for a TYPE_SYSTEM message.
277 * - OBJ_MSG_INVALID - Meter is not affected.
278 *
279 * Side Effects: none
280 *
281 ********************************************************************/
282 WORD MtrTranslateMsg(METER *pMtr, GOL_MSG *pMsg);
283  
284 /*********************************************************************
285 * Function: MtrMsgDefault(WORD translatedMsg, METER *pMtr, GOL_MSG* pMsg)
286 *
287 * Overview: This function performs the actual state change
288 * based on the translated message given. Meter value is set
289 * based on parameter 2 of the message given. The following state changes
290 * are supported:
291 * <TABLE>
292 * Translated Message Input Source Set/Clear State Bit Description
293 * ################## ############ ###### ###########
294 * MTR_MSG_SET System Set MTR_DRAW_UPDATE Meter will be redrawn to update the needle position and value displayed.
295 * </TABLE>
296 *
297 * PreCondition: none
298 *
299 * Input: translatedMsg - The translated message.
300 * pMtr - The pointer to the object whose state will be modified.
301 * pMsg - The pointer to the GOL message.
302 *
303 * Output: none
304 *
305 * Side Effects: none
306 *
307 ********************************************************************/
308 void MtrMsgDefault(WORD translatedMsg, METER *pMtr, GOL_MSG *pMsg);
309  
310 /*********************************************************************
311 * Macros: MtrGetVal(pMtr)
312 *
313 * Overview: This macro returns the current value of the meter.
314 * Value is always in the minValue-maxValue range inclusive.
315 *
316 * PreCondition: none
317 *
318 * Input: pMtr - Pointer to the object.
319 *
320 * Output: Returns current value of the meter.
321 *
322 * Side Effects: none
323 *
324 ********************************************************************/
325 #define MtrGetVal(pMtr) ((pMtr)->value)
326  
327 /*********************************************************************
328 * Function: MtrSetVal(METER *pMtr, SHORT newVal)
329 *
330 * Overview: This function sets the value of the meter to the passed
331 * newVal. newVal is checked to be in the minValue-maxValue
332 * range inclusive. If newVal is not in the range, minValue
333 * maxValue is assigned depending on the given newVal
334 * if less than minValue or above maxValue.
335 *
336 * PreCondition: none
337 *
338 * Input: pMtr - The pointer to the object.
339 * newVal - New value to be set for the Meter.
340 *
341 * Output: none
342 *
343 * Side Effects: none
344 *
345 ********************************************************************/
346 void MtrSetVal(METER *pMtr, SHORT newVal);
347  
348 /*********************************************************************
349 * Macros: MtrIncVal(pMtr, deltaValue)
350 *
351 * Overview: This macro is used to directly increment the value.
352 *
353 * PreCondition: none
354 *
355 * Input: pMtr - Pointer to the object.
356 * deltaValue - Number to be added to the current Meter value.
357 *
358 * Output: none
359 *
360 * Side Effects: none
361 *
362 ********************************************************************/
363 #define MtrIncVal(pMtr, deltaValue) MtrSetVal(pMtr, ((pMtr)->value + deltaValue))
364  
365 /*********************************************************************
366 * Macros: MtrDecVal(pMtr, deltaValue)
367 *
368 * Overview: This macro is used to directly decrement the value.
369 *
370 * PreCondition: none
371 *
372 * Input: pMtr - Pointer to the object.
373 * deltaValue - Number to be subtracted to the current Meter value.
374 *
375 * Output: none
376 *
377 * Side Effects: none
378 *
379 ********************************************************************/
380 #define MtrDecVal(pMtr, deltaValue) MtrSetVal(pMtr, ((pMtr)->value - deltaValue))
381  
382 /*********************************************************************
383 * Macros: MtrSetScaleColors(pMtr, arc1, arc2, arc3, arc4, arc5, arc6)
384 * { pMtr->arcColor6=arc6;
385 * pMtr->arcColor5=arc5;
386 * pMtr->arcColor4=arc4;
387 * pMtr->arcColor3=arc3;
388 * pMtr->arcColor2=arc2;
389 * pMtr->arcColor1=arc1; }
390 *
391 * Overview: Scale colors can be used to highlight values of the meter.
392 * User can set these colors to define the arc colors and scale colors.
393 * This also sets the color of the meter value when displayed. Limitation is that
394 * color settings are set to the following angles:
395 * Color Boundaries Type Whole Type Half Type Quarter
396 * Arc 6 225 to 180 not used not used
397 * Arc 5 179 to 135 179 to 135 not used
398 * Arc 4 134 to 90 134 to 90 not used
399 * Arc 3 89 to 45 89 to 45 89 to 45
400 * Arc 2 44 to 0 44 to 0 44 to 0
401 * Arc 1 -45 to -1 not used not used
402 * As the meter is drawn colors are changed depending on the
403 * angle of the scale and label being drawn.
404 *
405 * PreCondition: The object must be created (using MtrCreate()) before
406 * a call to this macro is performed.
407 *
408 * Input: pMtr - Pointer to the object.
409 * arc1 - color for arc 1.
410 * arc2 - color for arc 2.
411 * arc3 - color for arc 3.
412 * arc4 - color for arc 4.
413 * arc5 - color for arc 5.
414 * arc6 - color for arc 6.
415 *
416 * Output: none
417 *
418 * Side Effects: none
419 *
420 ********************************************************************/
421 #define MtrSetScaleColors(pMtr, arc1, arc2, arc3, arc4, arc5, arc6) \
422 { \
423 pMtr->arcColor6 = arc6; \
424 pMtr->arcColor5 = arc5; \
425 pMtr->arcColor4 = arc4; \
426 pMtr->arcColor3 = arc3; \
427 pMtr->arcColor2 = arc2; \
428 pMtr->arcColor1 = arc1; \
429 }
430  
431 /*********************************************************************
432 * Function: WORD MtrDraw(METER *pMtr)
433 *
434 * Overview: This function renders the object on the screen using
435 * the current parameter settings. Location of the object is
436 * determined by the left, top, right and bottom parameters.
437 * The colors used are dependent on the state of the object.
438 * The font used is determined by the style scheme set.
439 *
440 * Depending on the defined settings, value of the meter
441 * will displayed or hidden. Displaying the value will require
442 * a little bit more rendering time depending on the size
443 * of the meter and font used.
444 *
445 * When rendering objects of the same type, each object
446 * must be rendered completely before the rendering of the
447 * next object is started. This is to avoid incomplete
448 * object rendering.
449 *
450 * PreCondition: Object must be created before this function is called.
451 *
452 * Input: pMtr - Pointer to the object to be rendered.
453 *
454 * Output: Returns the status of the drawing
455 * - 1 - If the rendering was completed and
456 * - 0 - If the rendering is not yet finished.
457 * Next call to the function will resume the
458 * rendering on the pending drawing state.
459 *
460 * Example:
461 * See MtrCreate() example.
462 *
463 * Side Effects: none
464 *
465 ********************************************************************/
466 WORD MtrDraw(METER *pMtr);
467  
468 /*********************************************************************
469 * Macro: MtrSetTitleFont(pMtr, pNewFont) (((METER*)pMtr)->pTitleFont = pNewFont)
470 *
471 * Overview: This function sets the font of title.
472 *
473 * PreCondition: Font must be created before this function is called.
474 *
475 * Input: pMtr - Pointer to the object.
476 * pNewFont - Pointer to the new font used for the title.
477 *
478 * Output: N/A
479 *
480 * Side Effects: none
481 *
482 ********************************************************************/
483 #define MtrSetTitleFont(pMtr, pNewFont) (((METER *)pMtr)->pTitleFont = pNewFont)
484  
485 /*********************************************************************
486 * Macro: MtrSetValueFont(pMtr, pNewFont) (((METER*)pMtr)->pValueFont = pNewFont)
487 *
488 * Overview: This function sets the font of value.
489 *
490 * PreCondition: Font must be created before this function is called.
491 *
492 * Input: pMtr - Pointer to the object.
493 * pNewFont - Pointer to the new font used for the value.
494 *
495 * Output: N/A
496 *
497 * Side Effects: none
498 *
499 ********************************************************************/
500 #define MtrSetValueFont(pMtr, pNewFont) (((METER *)pMtr)->pValueFont = pNewFont)
501 #endif // _METER_H
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3