/*****************************************************************************
* Module for Microchip Graphics Library
* Grid control
*****************************************************************************
* FileName: Grid.h
* Dependencies: none
* Processor: PIC24F, PIC24H, dsPIC, PIC32
* Compiler: MPLAB C30 V3.00, MPLAB C32
* Linker: MPLAB LINK30, MPLAB LINK32
* Company: Microchip Technology Incorporated
*
* Software License Agreement
*
* Copyright © 2008 Microchip Technology Inc. All rights reserved.
* Microchip licenses to you the right to use, modify, copy and distribute
* Software only when embedded on a Microchip microcontroller or digital
* signal controller, which is integrated into your product or third party
* product (pursuant to the sublicense terms in the accompanying license
* agreement).
*
* You should refer to the license agreement accompanying this Software
* for additional information regarding your rights and obligations.
*
* SOFTWARE AND DOCUMENTATION ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY
* KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY
* OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR
* PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR
* OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION,
* BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT
* DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL,
* INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA,
* COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY
* CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF),
* OR OTHER SIMILAR COSTS.
*
* Author Date Comment
*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Kim Otten 02/29/08 ...
* PAT 04/16/10 Added Grid Item as text.
*****************************************************************************/
#ifndef _GRID_H_
#define _GRID_H_
#include <Graphics\GOL.h>
//******************************************************************************
// Grid Object State Definitions
//******************************************************************************
#define GRID_FOCUSED 0x0001 // Bit for focused state
#define GRID_DISABLED 0x0002 // Bit for disabled state
#define GRID_SHOW_LINES 0x0004 // Display grid lines
#define GRID_SHOW_FOCUS 0x0008 // Highlight the focused cell.
#define GRID_SHOW_BORDER_ONLY 0x0010 // Draw only the outside border of the grid.
#define GRID_SHOW_SEPARATORS_ONLY 0x0020 // Draw only the lines between cells (like Tic-tac-toe)
#define GRID_DRAW_ITEMS 0x1000 // Bit to indicate that at least one item must be redrawn, but not the entire grid.
#define GRID_DRAW_ALL 0x4000 // Bit to indicate whole edit box must be redrawn
#define GRID_HIDE 0x8000 // Bit to remove object from screen
//******************************************************************************
// Grid Item State Definitions
//******************************************************************************
#define GRIDITEM_SELECTED 0x0001 // The cell is selected.
#define GRIDITEM_IS_TEXT 0x0000 // The grid item is a test string.
#define GRIDITEM_IS_BITMAP 0x0008 // The grid item is a bitmap.
#define GRIDITEM_TEXTRIGHT 0x0010 // Text in the cell is right aligned.
#define GRIDITEM_TEXTLEFT 0x0020 // Text in the cell is left aligned.
#define GRIDITEM_TEXTBOTTOM 0x0040 // Bit to indicate text is top aligned.
#define GRIDITEM_TEXTTOP 0x0080 // Bit to indicate text is bottom aligned.
#define GRIDITEM_DRAW 0x0100 // Draw this cell
#define GRID_TYPE_MASK (0x0C)
#define GRID_SUCCESS 0x0000 // Status of a successful GridSetCell() operation.
#define GRID_OUT_OF_BOUNDS 0x0001 // Status of an out of bounds cell GridSetCell() operation.
#define GRID_MAX_COLUMNS(rw, cw) ((rw - (GOL_EMBOSS_SIZE * 2) + 1) / (cw + 1))
#define GRID_MAX_ROWS(rh, ch) ((rh - (GOL_EMBOSS_SIZE * 2) + 1) / (ch + 1))
#define GRID_WIDTH(c, cw) ((GOL_EMBOSS_SIZE * 2) + (c * (cw + 1)) - 1)
#define GRID_HEIGHT(r, ch) ((GOL_EMBOSS_SIZE * 2) + (r * (ch + 1)) - 1)
/*********************************************************************
* Overview: Defines the grid item.
*
*********************************************************************/
typedef struct
{
void *data; // Indicates if the Grid Item is type GRIDITEM_IS_TEXT or GRIDITEM_IS_BITMAP
WORD status; // indicates the status of the Grid Item
} GRIDITEM;
/*********************************************************************
* Overview: Defines the parameters required for a grid Object.
* Clipping is not supported in grid object.
*
*********************************************************************/
typedef struct
{
OBJ_HEADER hdr; // Generic header for all Objects (see OBJ_HEADER).
SHORT numColumns; // Number of columns drawn for the Grid.
SHORT numRows; // Number of rows drawn for the Grid.
SHORT cellHeight; // The height of each cell in pixels.
SHORT cellWidth; // The width of each cell in pixels.
SHORT focusX; // The x position of the cell to be focused.
SHORT focusY; // The y position of the cell to be focused.
GRIDITEM *gridObjects; // The pointer to grid items
} GRID;
/*********************************************************************
* Function: GRID *GridCreate(WORD ID, SHORT left, SHORT top, SHORT right, SHORT bottom,
* WORD state, SHORT numColumns, SHORT numRows,
* SHORT cellWidth, SHORT cellHeight, GOL_SCHEME *pScheme)
*
* Overview: This function creates a GRID object with the parameters
* given. It automatically attaches the new object into a global
* linked list of objects and returns the address of the object.
*
* PreCondition: none
*
* Input: ID - Unique user defined ID for the object instance.
* left - Left most position of the Object.
* top - Top most position of the Object.
* right - Right most position of the Object.
* bottom - Bottom most position of the object.
* state - Sets the initial state of the object.
* numColumns - Sets the number of columns for the grid.
* numRows - Sets the number of rows for the grid.
* cellWidth - Sets the width of each cell of the grid.
* cellHeight - Sets the height of each cell of the grid.
* pScheme - Pointer to the style scheme used for the object.
* Set to NULL if default style scheme is used.
*
* Output: Returns the pointer to the object created.
*
* Side Effects: none
*
********************************************************************/
GRID *GridCreate
(
WORD ID,
SHORT left,
SHORT top,
SHORT right,
SHORT bottom,
WORD state,
SHORT numColumns,
SHORT numRows,
SHORT cellWidth,
SHORT cellHeight,
GOL_SCHEME *pScheme
);
/*********************************************************************
* Function: GridClearCellState(GRID *pGrid, SHORT column, SHORT row, WORD state)
*
* Overview: This function clears the state of the cell (or Grid Item) specified
* by the column and row.
*
* PreCondition: none
*
* Input: pGrid - Pointer to the object.
* column - column index of the cell
* row - row index of the cell
* atate - specifies the state to be cleared. See Grid Item State.
*
* Output: none.
*
* Side Effects: none
*
********************************************************************/
void GridClearCellState(GRID *pGrid, SHORT column, SHORT row, WORD state);
/*********************************************************************
* Function: WORD GridDraw(GRID *pGrid)
*
* Overview: This function renders the object on the screen using
* the current parameter settings. Location of the object
* is determined by the left, top, right and bottom parameters.
* The colors used are dependent on the state of the object.
* The font used is determined by the style scheme set.
*
* When rendering objects of the same type, each object must
* be rendered completely before the rendering of the next object
* is started. This is to avoid incomplete object rendering.
*
* PreCondition: Object must be created before this function is called.
*
* Input: pGb - Pointer to the object to be rendered.
*
* Output: Returns the status of the drawing
* - 1 - If the rendering was completed and
* - 0 - If the rendering is not yet finished.
* Next call to the function will resume the
* rendering on the pending drawing state.
*
* Side Effects: none
*
********************************************************************/
WORD GridDraw(GRID *pGrid);
/*********************************************************************
* Function: GridFreeItems(GRID *pGrid)
*
* Overview: This function removes all grid items for the given Grid
* and frees the memory used.
*
* PreCondition: Object must be created before this function is called.
*
* Input: pGrid - The pointer to the Grid object.
*
* Output: none.
*
* Side Effects: none
*
********************************************************************/
void GridFreeItems(GRID *pGrid);
/*********************************************************************
* Function: *GridGetCell(GRID *pGrid, SHORT column, SHORT row, WORD *cellType)
*
* Overview: This function removes all grid items for the given Grid
* and frees the memory used.
*
* PreCondition: Object must be created before this function is called.
*
* Input: pGrid - The pointer to the Grid object.
* column - the column index of the cell
* row - the row index of the cell
* cellType - pointer that will receive the type of grid item
* or cell (GRIDITEM_IS_TEXT or GRIDITEM_IS_BITMAP).
*
* Output: Returns a pointer to the grid item or cell data.
*
* Side Effects: none
*
********************************************************************/
void *GridGetCell(GRID *pGrid, SHORT column, SHORT row, WORD *cellType);
/*********************************************************************
* Macros: GridGetFocusX(pGrid)
*
* Overview: This macro returns the x position of the focused cell.
*
* PreCondition: none
*
* Input: pGrid - Pointer to the object.
*
* Output: Returns the x position of the focused cell.
*
* Side Effects: none
*
********************************************************************/
#define GridGetFocusX(pGrid) pGrid->focusX
/*********************************************************************
* Macros: GridGetFocusY(pGrid)
*
* Overview: This macro returns the y position of the focused cell.
*
* PreCondition: none
*
* Input: pGrid - Pointer to the object.
*
* Output: Returns the y position of the focused cell.
*
* Side Effects: none
*
********************************************************************/
#define GridGetFocusY(pGrid) pGrid->focusY
/*********************************************************************
* Function: GridMsgDefault(WORD translatedMsg, GRID *pGrid, GOL_MSG *pMsg)
*
* Overview: This function performs the actual state change
* based on the translated message given. The following state changes
* are supported:
* <TABLE>
* Translated Message Input Source Set/Clear State Bit Description
* ################## ############ ###### ###########
* GRID_MSG_TOUCHED Touch Screen none Grid will have no state change because of this event.
* GRID_MSG_ITEM_SELECTED Keyboard Set GRIDITEM_SELECTED, Grid Item selected will be redrawn.
* GRID_DRAW_ITEMS
* GRID_MSG_UP Keyboard Set GRIDITEM_DRAW, Grid Item above the currently focused item will be redrawn.
* GRID_DRAW_ITEMS
* GRID_MSG_DOWN Keyboard Set GRIDITEM_DRAW, Grid Item below the currently focused item will be redrawn.
* GRID_DRAW_ITEMS
* GRID_MSG_LEFT Keyboard Set GRIDITEM_DRAW, Grid Item to the left of the currently focused item will be redrawn.
* GRID_DRAW_ITEMS
* GRID_MSG_RIGHT Keyboard Set GRIDITEM_DRAW, Grid Item to the right of the currently focused item will be redrawn.
* GRID_DRAW_ITEMS
* </TABLE>
*
* PreCondition: none
*
* Input: translatedMsg - The translated message.
* pGrid - The pointer to the object whose state will be modified.
* pMsg - The pointer to the GOL message.
*
* Output: none
*
* Side Effects: none
*
********************************************************************/
void GridMsgDefault(WORD translatedMsg, GRID *pGrid, GOL_MSG *pMsg);
/*********************************************************************
* Function: GridTranslateMsg(GRID *pGrid, GOL_MSG *pMsg)
*
* Overview: This function evaluates the message from a user if the
* message will affect the object or not. The table below enumerates the translated
* messages for each event of the touch screen and keyboard inputs.
*
* <TABLE>
* Translated Message Input Source Set/Clear State Bit Description
* ################## ############ ####################### ##################################################################################################################################################################
* GRID_MSG_TOUCHED Touch Screen none If any touch events occurs and the x,y position falls in the face of the grid.
* GRID_MSG_ITEM_SELECTED Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the objects ID and parameter 2 passed matches SCAN_SPACE_PRESSED or SCAN_CR_PRESSED.
* GRID_MSG_UP Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the objects ID and parameter 2 passed matches SCAN_UP_PRESSED.
* GRID_MSG_DOWN Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the objects ID and parameter 2 passed matches SCAN_DOWN_PRESSED.
* GRID_MSG_LEFT Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the objects ID and parameter 2 passed matches SCAN_LEFT_PRESSED.
* GRID_MSG_RIGHT Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the objects ID and parameter 2 passed matches SCAN_RIGHT_PRESSED.
* OBJ_MSG_INVALID Any Any If the message did not affect the object.
* </TABLE>
*
* PreCondition: none
*
* Input: pGrid - The pointer to the object where the message will be
* evaluated to check if the message will affect the object.
* pMsg - Pointer to the message struct containing the message from
* the user interface.
*
* Output: Returns the translated message depending on the received GOL message:
* - GRID_MSG_TOUCHED - when the grid object is touched.
* - GRID_MSG_ITEM_SELECTED when key scan SCAN_SPACE_PRESSED or SCAN_CR_PRESSED are detected.
* - GRID_MSG_UP when key scan SCAN_UP_PRESSED is detected.
* - GRID_MSG_DOWN when key scan SCAN_DOWN_PRESSED is detected.
* - GRID_MSG_LEFT when key scan SCAN_LEFT_PRESSED is detected.
* - GRID_MSG_RIGHT when key scan SCAN_RIGHT_PRESSED is detected.
* - OBJ_MSG_INVALID Button is not affected
*
*
* Side Effects: none
*
********************************************************************/
WORD GridTranslateMsg(GRID *pCb, GOL_MSG *pMsg);
/*********************************************************************
* Function: WORD GridSetCell(GRID *pGrid, SHORT column, SHORT row, WORD state, void *data)
*
* Overview: This function sets the Grid Item state and data.
*
* PreCondition: Object must be created before this function is called.
*
* Input: pGrid - The pointer to the Grid object.
* column - the column index of the cell
* row - the row index of the cell
* state - sets the state of the Grid Item specified.
* data - pointer to the data used for the Grid Item.
*
* Output: Returns the status of the operation
* - GRID_SUCCESS - if the set succeeded
* - GRID_OUT_OF_BOUNDS - if the row and column given results in an out of bounds location.
*
* Side Effects: none
*
********************************************************************/
WORD GridSetCell(GRID *pGrid, SHORT column, SHORT row, WORD state, void *data);
/*********************************************************************
* Function: GridSetCellState(GRID *pGrid, SHORT column, SHORT row, WORD state)
*
* Overview: This function sets the state of the Grid Item or cell.
*
* PreCondition: Object must be created before this function is called.
*
* Input: pGrid - The pointer to the Grid object.
* column - the column index of the cell
* row - the row index of the cell
* state - sets the state of the Grid Item specified.
*
* Output: none.
*
* Side Effects: none
*
********************************************************************/
void GridSetCellState(GRID *pGrid, SHORT column, SHORT row, WORD state);
/*********************************************************************
* Function: GridSetFocus(GRID *pGrid, SHORT column, SHORT row)
*
* Overview: This function sets the focus of the specified Grid Item or cell.
*
* PreCondition: Object must be created before this function is called.
*
* Input: pGrid - The pointer to the Grid object.
* column - the column index of the cell
* row - the row index of the cell
*
* Output: none.
*
* Side Effects: none
*
********************************************************************/
void GridSetFocus(GRID *pGrid, SHORT column, SHORT row);
#endif
|