MFC Grid manual

CGrid Class Reference

This class implements full featured thread-safe hierarchical list control. More...

#include <Dapfor/GUI/Grid.h>

List of all members.


Serialization

virtual void Serialize (CArchive &ar)
 Saves a state and settings to the archive and restores them from the archive.
static int GetSerializeVertion ()
 Gets current grid version that is used for compatibility with the archives made in the previous grid versions.

Public Member Functions

Adding, deleting, positioning, enumerating
HITEM Add (Common::CDataObject *pDO, HITEM hParent=GI_SCROLLABLE_ROOT, HITEM hInsertAfter=GI_LAST)
 Adds a data object to the grid.
bool Delete (HITEM hItem)
 Deletes an item from the grid.
int Delete (const Common::CDataObject *pDO)
 Deletes all lines corresponding to a given data object from the grid.
bool Delete (int nRow, ContextType contextType=ScrollableContext)
 Deletes a visible line from a given data context.
void DeleteAll (ContextType contextType=AllContexts)
 Deletes all data from a given context.
Handles GetHandles (const Common::CDataObject *pDO, bool visibleOnly, ContextType contextType=AllContexts) const
 Gets all handles corresponding to a given data object.
Handles GetHandles (ContextType contextType=AllContexts) const
 Get a copy of all handles inserted into the grid.
bool Attach (HITEM hItem, HITEM hParent, HITEM hInsertAfter=GI_LAST)
 This function enables attachment of a given hItem to the grid.
bool Detach (HITEM hItem)
 Detaches a handle inserted by Add() function from the grid.
bool Exists (HITEM hItem) const
 Checks whether a given handle is attached to the grid.
bool Exists (const Common::CDataObject *pDO) const
 Checks whether a given data object is inserted into the grid. One data object can be inserted multiple times into a single grid. For each insertion a unique handle is created. This handle enables unique definition of object position and status in the grid.
unsigned int GetRowCount (ContextType contextType=ScrollableContext) const
 Gets a number of visible grid lines (not filtered and not hidden by parents).
void ForEach (IForEach &functional, HITEM startFrom=GI_FIRST)
 Conducts a search and passes all found handles with data objects to the functional object.
void ForEachVisible (IForEach &functional, HITEM startFrom=GI_FIRST)
 Conducts a search and passes all found visible handles with data objects to the functional object.
bool MoveBefore (HITEM movingItem, HITEM parentPosition, HITEM position)
 Moves a given handle with all hierarchy to a position before the specified position for the specified parent.
bool MoveAfter (HITEM movingItem, HITEM parentPosition, HITEM position)
 Moves a given handle with all hierarchy to a position after the specified position for the specified parent.
Getting and setting formatted and non-formatted data
Common::CValue GetValue (HITEM hItem, Common::FID fid) const
 The function enables getting unformatted value of a data object corresponding to a 'fid'.
bool SetValue (HITEM hItem, Common::FID fid, const Common::CValue &value)
 Sets a new value for the data object.
TString GetFormattedStlString (HITEM hItem, Common::FID fid, const Common::CFormat *format=0) const
 Gets a formatted string from a data object by its field identifier.
bool SetFormattedStlString (HITEM hItem, Common::FID fid, const TString &str, const Common::CFormat *format=0)
 Sets a new value into the data object using a formatted string.
CString GetFormattedMfcString (HITEM hItem, Common::FID fid, const Common::CFormat *format=0) const
bool SetFormattedMfcString (HITEM hItem, Common::FID fid, const CString &str, const Common::CFormat *format=0)
Functions for working with hierarchy
bool IsExpanded (HITEM hItem) const
 Gets the value specifying whether the line is expanded.
Handles GetChildren (HITEM hItem, bool visibleOnly) const
 Gets handles of all children of a given parent.
bool HasChildren (HITEM hItem) const
 Gets the value specifying whether a given handle has at least one child.
int GetHierarchicalLevel (HITEM hItem) const
 Gets hierarchical level of a given line.
HITEM GetParent (HITEM hItem) const
 Gets the parent to which a line is attached.
void Expand (HITEM hItem, bool withChildren)
 Expands a line.
void Expand (const Common::CDataObject *pDO, bool withChildren)
 Expands the line, handle of which is associated with the data object.
void Collapse (HITEM hItem, bool withChildren)
 Collapses a line.
void Collapse (const Common::CDataObject *pDO, bool withChildren)
 Collapses the line, handle of which is associated with the data object.
void ShowAlwaysPlusMinus (bool show)
bool IsPlusMinusAlwaysVisible () const
Search for data objects and lines in the grid
int GetRow (HITEM hItem) const
 Gets an index of a visible grid line for a given handle.
int GetRow (const Common::CDataObject *pDO) const
 Searches for the grid line corresponding to the first encountered handle of a given data object.
ContextType GetContextType (HITEM hItem) const
 Gets grid context, where a given handle belongs.
ContextType GetContextType (const Common::CDataObject *pDO) const
 Gets grid context, where the first encountered handle corresponding to a given data object is inserted.
HITEM GetItem (int nRow, ContextType contextType=ScrollableContext) const
 Gets a line handle by its absolute location in grid context.
HITEM GetItem (const Common::CDataObject *pDO) const
 Gets the first encountered handle for a given data object.
HITEM GetItem (CPoint point) const
 Gets a handle of the grid line located within given x, y coordinates.
HITEM GetPreviousItem (HITEM hItem, bool jumpBetweenContexts=true) const
 Gets a handle of the first visible line before a given handle.
HITEM GetNextItem (HITEM hItem, bool jumpBetweenContexts=true) const
 Gets a handle of the next visible line after a given handle.
Common::CDataObjectGetDataObject (HITEM hItem)
 Gets the data object corresponding to a given handle.
const Common::CDataObjectGetDataObject (HITEM hItem) const
 Gets the data object corresponding to a given handle. Const version.
Common::CDataObjectGetDataObject (int nRow, ContextType contextType=ScrollableContext)
 Gets the data object corresponding to the line located in a given grid context and at a given position.
const Common::CDataObjectGetDataObject (int nRow, ContextType contextType=ScrollableContext) const
 Gets the data object corresponding to the line in a given grid context at a given position. Const version.
Visibility, placement and bounds
int GetFirstVisibleRow () const
 Gets the first visible line in scrollable context.
int GetLastVisibleRow (ContextType contextType=ScrollableContext) const
 Gets the last visible line in a given context.
void SetFirstVisibleRow (int nRow)
 Sets a given index as the first visible index in scrollable context.
void SetFirstVisibleItem (HITEM hItem)
 Sets a given handle as the first visible handle in scrollable context.
void SetFirstVisibleItem (const Common::CDataObject *pDO)
 Searches for the first encountered line in scrollable context for a given data object.
void EnsureVisible (int nRow)
 Makes a given line visible in scrollable context.
void EnsureVisible (HITEM hItem)
 Makes a given handle visible in scrollable context.
void EnsureVisible (const Common::CDataObject *pDO)
 Makes the handle corresponding to the data object visible in scrollable context.
bool IsVisible (HITEM hItem) const
 Checks whether a given handle is visible in the grid.
bool IsVisible (const Common::CDataObject *pDO) const
 Checks whether the first handle corresponding to the data object is visible in the grid.
bool IsInVisibleRect (HITEM hItem)
 Checks whether at least a part of a given line is visible in the client area of the grid.
bool IsInVisibleRect (const Common::CDataObject *pDO)
 Checks whether at least a part of the given line corresponding to the data object is visible in the client area of the grid.
bool IsInVisibleRect (int nRow, ContextType contextType)
 Checks whether at least a part of the line in a given grid context and at a given position is visible in client area of the grid.
CRect GetContextVisibleRect (ContextType contextType) const
 Gets the visible rectangle occupied by a given grid context with consideration of client area dimensions and scrolling.
CRect GetContextVirtualRect (ContextType contextType) const
 Gets the virtual rectangle occupied by a given grid context without consideration of client area dimensions and scrolling.
CRect GetLineVisibleRect (HITEM hItem) const
 Gets the visible rectangle occupied by the grid line corresponding to a given handle.
CRect GetLineVisibleRect (const Common::CDataObject *pDO) const
 Gets the visible rectangle occupied by grid line corresponding to the first found handle for a given data object.
CRect GetLineVirtualRect (HITEM hItem) const
 Calculates the virtual rectangle occupied by the line corresponding to a given handle.
CRect GetLineVirtualRect (const Common::CDataObject *pDO) const
 Gets the virtual rectangle occupied by the grid line corresponding to the first found handle for a given data object.
CRect GetCellVisibleRect (HITEM hItem, Common::FID fid) const
 Gets a visible rectangle of the grid cell specified by a given handle and column identifier (identifier of a data object field).
CRect GetCellVisibleRect (const Common::CDataObject *pDO, Common::FID fid) const
 Gets a visible rectangle of the grid cell specified by the first found handle for a given data object and column identifier (identifier of a data object field).
CRect GetCellVirtualRect (HITEM hItem, Common::FID fid) const
 Gets a virtual rectangle of the grid cell specified by a given handle and column identifier (identifier of a data object field).
CRect GetCellVirtualRect (const Common::CDataObject *pDO, Common::FID fid) const
 Gets virtual size of grid cell specified by the first found handle for a given data object and column identifier (identifier of the data object field) without consideration of visible grid area dimensions.
int GetLinesPerPage (bool forward=true) const
 Calculates the number of fully visible lines per page in scrollable context of the grid.
int GetItemHeight (HITEM hItem) const
 Gets height of the line corresponding to a given handle.
void SetItemHeight (HITEM hItem, int height)
 Gets a height of the line corresponding to a given handle.
Selection
void AllowSelection (bool bEnable)
 Enables selection in the grid.
bool CanSelect () const
 Defines whether line selection in the grid is allowed.
void AllowMultiSelection (bool bEnable)
 Enables selection of multiple lines in the grid.
bool CanMultiSelect () const
 Defines whether multi-selection of lines is allowed in the grid.
void AllowSelectContext (ContextType contextType=AllContexts)
 Sets grid context where selection is allowed.
bool CanSelectContext (ContextType contextType) const
 Defines whether line selection is allowed in a given grid context.
int GetSelectedCount () const
 Gets the total number of selected lines in the grid.
bool Select (int nRow, ContextType contextType, bool bSelect)
 Changes selection of the line in a given position within a given context.
bool Select (HITEM hItem, bool bSelect)
 Enables selection of a line by its handle.
bool Select (const Common::CDataObject *pDO, bool bSelect)
 Changes selection for all the handles associated with a given data object in the grid.
Selection GetSelection (ContextType contextType) const
 Gets a list of selected handles.
bool IsSelected (int nRow, ContextType contextType) const
 Tests whether the line located in a given position in a given context is selected.
bool IsSelected (HITEM hItem) const
 Tests whether the line with a specified handle is selected.
bool IsSelected (const Common::CDataObject *pDO) const
 Tests whether the first line handle corresponding to the data object is selected.
void SelectAll ()
 Selects all visible lines in the grid if selection is allowed.
void ClearSelection ()
 Selects all lines in the grid.
void AllowMouseTrackSelection (bool bEnable)
 Enables selection with a mouse.
bool CanMouseTrackSelection () const
 Tests whether mouse selection is allowed.
Focus
void AllowFocusContext (ContextType contextType=AllContexts)
 Enables focusing lines in a given context.
bool CanFocusContext (ContextType contextType) const
 Checks if line focusing is allowed in a given grid context.
bool SetFocusedRow (int nRow, ContextType contextType)
 Sets a new focused line.
int GetFocusedRow () const
 Gets an index of a focused line in focused grid context.
ContextType GetFocusedContext () const
 Gets a focused grid context.
Updating
void UpdateRow (int nRow, ContextType contextType, Common::FID fid)
 Informs the grid about changing of a data object.
void UpdateItem (HITEM hItem, Common::FID fid)
 Informs the grid that a given handle has been updated.
void UpdateDataObject (const Common::CDataObject *pDO, Common::FID fid)
 Informs the grid that a data object has been updated.
int GetTimeElapsedSinceLastUpdate (int nRow, ContextType contextType, Common::FID fid) const
 Returns (in milliseconds) the time passed from the moment of the last update of a grid cell.
int GetTimeElapsedSinceLastUpdate (HITEM hItem, Common::FID fid) const
 Returns time (in milliseconds) passed from the moment of last update of a grid cell.
void InvalidateRow (int nRow, ContextType contextType, int spanTime=0)
 Redraws a line in the grid.
void InvalidateRow (HITEM hItem, int spanTime=0)
 Redraws the line corresponding to a given handle (if it is visible) in the grid.
void InvalidateRow (const Common::CDataObject *pDO, int spanTime=0)
 Redraws all the visible lines corresponding to a given data object in the grid.
void InvalidateCell (int nRow, ContextType contextType, Common::FID fid, int spanTime=0)
 Redraws the cell corresponding to a given line and column identifier in the grid.
void InvalidateCell (HITEM hItem, Common::FID fid, int spanTime=0)
 Redraws the cell corresponding to a given handle (if it is visible) and column identifier in the grid.
void InvalidateCell (const Common::CDataObject *pDO, Common::FID fid, int spanTime=0)
 Redraws all visible cells corresponding to a given data object and column identifier in the grid.
Notifications
void AllowNotifications (bool bAllow)
 The grid enables delivery of notifications to its owner by sending WM_NOTIFY messages.
bool IsNotificationsAllowed () const
 Returns the value indicating whether the grid is allowed to deliver notifications by sending WM_NOTIFY message to its owner.
Appearance
CAppearanceGetAppearance ()
 Gets CAppearance type object that collects basic visual grid characteristics such as text, background, vertical and horizontal lines colors, etc.
const CAppearanceGetAppearance () const
 Gets CAppearance type object that collects basic visual grid characteristics such as text, background, vertical and horizontal lines colors, etc. Const version.
void SetAppearance (const CAppearance &appearance)
 Sets a new grid appearance.
const CBackgroundImageGetBackgroundImage () const
 Gets a background image of the grid.
void SetBackgroundImage (const CBackgroundImage &settings)
 Sets a new background image for the grid.
void SetFont (CFont *font, BOOL bRedraw=TRUE)
 Sets font attributes to be used for text within the grid. Internally, the grid clones the font, and when this function is called, you should destroy it.
CFont * GetFont () const
 Gets the current font used in the grid.
CImageList * SetImageList (CImageList *imageList, bool stretchImage=false)
 Sets new ImageList to display icons within grid cells.
CImageList * GetImageList () const
 Gets the current ImageList value used by the grid.
void AllowStretchImageInCell (bool stretch)
 Sets the flag that enables icon stretching in grid cells.
bool CanStretchImageInCell () const
 Tests whether the flag enabling icons stretching in grid cells is set.
void AllowDrawContextSeparator (bool bDraw)
 Allows drawing of a separator between two grid contexts.
bool CanDrawContextSeparator () const
 Tests whether drawing of a separator between two grid contexts is allowed.
void SetContextSeparatorHeight (int nHeight)
 Sets height of separator between two grid contexts.
int GetContextSeparatorHeight () const
 Gets height of separator between two grid contexts.
void AllowHighlight (bool bAllow)
 Enables or disables grid cells highlighting.
bool CanHighlight () const
 Returns the value indicating if the grid can perform cells highlighting or not.
const CHighlightSettingsGetHighlightSettings () const
 Gets highlighting parameters collected in CHighlightSettings type object. Const version.
CHighlightSettingsGetHighlightSettings ()
 Gets highlighting parameters collected in CHighlightSettings type object.
void SetHighlightSettings (const CHighlightSettings &settings)
 Sets new parameters of highlighting in the grid.
ICustomDrawSetCustomDraw (ICustomDraw *customDraw)
 Sets a new interface to specify grid element drawing.
ICustomDrawGetCustomDraw () const
 Gets current ICustomDraw interface.
void SetPaintFilter (UINT paintFilter=defaultPaintFilter)
 Sets a new graphical filter.
UINT GetPaintFilter () const
 Gets current value of the graphical filter.
void SetFlickerFreeDrawing (bool enable)
 Enables use of double buffering mechanism to exclude the flicker effect at the time of elements drawing.
bool GetFlickerFreeDrawing () const
 Gets the value indicating whether double buffering mode is enabled.
int GetOptimalRowHeight (ContextType contextType) const
 Gets optimal value of line height in a given grid context.
void SetOptimalRowHeight (ContextType contextType, int height)
 Sets default row height.
int GetOptimalCellWidth (int nRow, ContextType contextType, Common::FID fid) const
 Gets optimal width value for a given grid cell.
int GetOptimalColumnWidth (ContextType contextType, Common::FID fid) const
 Calculates the optimal grid column size based on the optimal size for visible grid cells by GetOptimalCellWidth() function call.
Headers
CHeaderSetHeader (CHeader *newHeader)
 Sets a new header.
CHeaderGetHeader ()
 Gets the current header used by the grid.
const CHeaderGetHeader () const
 Gets the current header used by the grid. Const version.
void ShowHeader ()
 Makes the header visible.
void HideHeader ()
 Makes the header invisible.
bool IsHeaderVisible () const
 Returns the value indicating whether the header is visible.
virtual void ShowHeaderDialog ()
 Displays the dialog for configuring header columns.
const CColumnGetColumn (CPoint pt) const
 Searches a column in the grid according to the coordinates counted in the client area of the grid.
const CColumnGetNavigationColumn () const
 Gets a navigation column.
const CColumnGetHierarchicalColumn () const
 Gets the column that manages grid hierarchy.
void AdjustColumnByFid (Common::FID fid)
 Performs column width optimization for visible grid lines.
void AdjustColumnByIndex (int index)
 Performs column width optimization by index.
void AdjustAllColumns ()
 Performs all grid columns width optimization. The columns width is adjusted in such a way that grid cells in a given column haven't got partially hidden data.
int GetOptimalHeaderHeight () const
 Gets optimal header height.
void EnsureColumnVisible (Common::FID fid)
 The function makes a column fully visible in the grid.
Tooltips
void EnableTooltip (bool enable=true)
 Allows to display tooltips.
bool IsTooltipEnabled () const
 Returns value indicating whether tooltips are enabled.
const ITooltipCtrlGetTooltipCtrl ()
 Gets current ITooltipCtrl used by the grid.
ITooltipCtrlSetTooltipCtrl (ITooltipCtrl *control)
 Sets new ITooltipCtrl interface to control the tooltip window.
const ITooltipGetTooltip () const
 Gets the interface controlling tooltip content.
ITooltipSetTooltip (ITooltip *tooltip)
 Set a new interface for defining the tooltip content.
const CTooltipSettingsGetTooltipSettings () const
 Gets tooltip settings collected in CTooltipSettings class object. Const version.
CTooltipSettingsGetTooltipSettings ()
 Gets the tooltip settings collected in CTooltipSettings class object.
void SetTooltipSettings (const CTooltipSettings &settings)
 Sets new tooltip settings.
void EnableInPlaceTooltip (bool bEnable=true)
 Enables display of tooltips over grid cells when cell size is not sufficient for displaying text.
bool IsInPlaceTooltipEnabled () const
 Returns the value indicating whether the grid can show the tooltip above the grid cells when a cell size is not enough for displaying a text.
CTooltipSettingsGetInPlaceTooltipSettings ()
 Gets tooltip settings specifying the way of displaying tooltips over grid cells when cell size is not sufficient for displaying text.
void SetInPlaceTooltipSettings (const CTooltipSettings &settings)
 Specifies new settings that determine how should the grid display tooltips over grid cells when cell size is not sufficient for displaying text.
const ITooltipCtrlGetInPlaceTooltipCtrl () const
 Gets the current tooltip control used by the grid when cell size is not sufficient for displaying text.
ITooltipCtrlSetInPlaceTooltipCtrl (ITooltipCtrl *control)
 Sets new ITooltipCtrl interface to control the 'embedded' tooltip window.
Copy/cut/paste
bool Copy ()
 Copies selection to the clipboard.
bool Cut ()
 Cuts selection to the clipboard.
bool Paste ()
 Inserts elements into the grid to a location after the focused line .
bool Paste (HITEM hParent, HITEM hInsertAfter)
 Pastes data from the clipboard to a given position.
ICopyPasteSetCopyPaste (ICopyPaste *copyPaste)
 Sets new ICopyPaste interface.
ICopyPasteGetCopyPaste () const
 Gets the current ICopyPaste interface used by the grid.
const CCopyPasteSettingsGetCopyPasteSettings () const
 Gets settings collected in CCopyPasteSettings type object and used by the grid in copy/paste operations. Const version.
CCopyPasteSettingsGetCopyPasteSettings ()
 Gets the settings collected in CCopyPasteSettings type object and used by the grid in copy/paste operations.
void SetCopyPasteSettings (const CCopyPasteSettings &settings)
 Sets the new settings used by the grid for copy/paste operations.
void AllowCopyPaste (bool bAllow)
 Enables/disables copy/paste.
bool IsCopyPasteAllowed () const
 Gets the value indicating whether copy/paste operations are allowed.
Drag and drop
IDragDropSetDragDrop (IDragDrop *dragDrop)
 Sets new IDragDrop interface. This function also returns the previous interface used by the grid.
IDragDropGetDragDrop () const
 Gets the current IDragDrop interface used by the grid.
const CDragDropSettingsGetDragDropSettings () const
 Gets the drag&drop settings collected in CDragDropSettings type object. Const version.
CDragDropSettingsGetDragDropSettings ()
 Gets the drag&drop settings collected in CDragDropSettings type object.
void SetDragDropSettings (const CDragDropSettings &settings)
 Sets new drag&drop settings.
void AllowDragAndDrop (bool bAllow)
 Enables or disables drag&drop in the grid.
bool IsDragAndDropAllowed () const
 Gets the value indicating whether drad&drop operations are allowed.
CDragImage CreateDragImage (const Handles &handles, ContextType contextType, const CHeader *header) const
 Helper that enables image creation when grid content is dragged.
Sorting
void AllowSort (bool bEnable)
 Enables or disables sorting in the grid.
bool CanSort () const
 Returns the value indicating whether sorting is allowed.
void AllowMultiSort (bool bEnable)
 Allows multiple sorting in the grid.
bool CanMultiSort () const
 Returns the value indicating whether multiple sorting is allowed.
void SetSortedContext (ContextType contextType=AllContexts)
 Sets grid context where sorting is allowed.
ContextType GetSortedContext () const
 Gets contexts where sorting is allowed.
void ResetSort (bool redraw=true)
 Cancels sorting.
void SetSort (int level, CSortInfo sortInfo, bool applyImmediatelly=true)
 Sets a sort for a given level.
CSortInfo GetSort (int level) const
 Gets information about sorting for a given level.
void UpdateSort ()
 Performs data sorting in the grid according to sorting rules specified in a header.
int GetSortLevels () const
 Returns current value of sorting levels quantity.
Data filtration
IGridFilterSetFilter (IGridFilter *filter)
 Sets a new filter.
IGridFilterGetFilter () const
 Gets the current filter set in the grid.
void UpdateFilter ()
 Calls checking of all grid lines on whether or not they are filtered.
Navigation and keyboard
IKeyManagerSetKeyManager (IKeyManager *keyManager)
 Sets a new keyboard manager to control the grid.
IKeyManagerGetKeyManager () const
 Gets the current keyboard manager used by the grid.
void AllowNavigation (ContextType contextType=AllContexts)
 Allows to conduct navigation in given grid contexts.
bool CanNavigate (ContextType contextType) const
 Returns the value, indicating whether navigation is possible in given grid context.
void NavigateUp (bool bShift, bool bCtrl)
 Moves a focus up and scrolls down one line if it is necessary.
void NavigateDown (bool bShift, bool bCtrl)
 Moves a focus down and scrolls up one line if it is necessary.
void NavigatePageUp (bool bShift, bool bCtrl)
 Moves a focus up and scrolls down one page if it is necessary.
void NavigatePageDown (bool bShift, bool bCtrl)
 Moves a focus down and scrolls up one page if it is necessary.
void NavigateHome (bool bShift, bool bCtrl)
 Focuses the first line in the fixed or scrollable context according to navigation settings.
void NavigateEnd (bool bShift, bool bCtrl)
 Focuses the last line in the fixed or scrollable context according to navigation settings.
void ResetScroll ()
 Updates vertical and horizontal scrollbar positions.
Printing
void PrintPreview (const CPrintSettings &settings)
 The function opens a print preview dialog where the user can specify printer settings, paper position and size, zoom on-screen grid content or to enlarge a printed sheet on the screen.
void Print (const CPrintSettings &settings, CPrintInfo *printInfo=0)
 Launches printing of grid content.
Built in controls
CEmbeddedControlAdapterAttachControl (CWnd *control, HITEM hItem, Common::FID fid, const CEmbeddedControlParams &params=CEmbeddedControlParams())
 Attaches a control to a grid cell.
bool DetachControl (CWnd *control)
 Looks for the cell where a specified control is attached, and detaches it.
bool DetachControl (HITEM hItem, Common::FID fid, bool bDestroy)
 Detaches a control from the grid cell specified by hItem and fid values.
bool HasControl (HITEM hItem, Common::FID fid) const
 Checks whether MFC control is attached to a given cell.
bool HasControl (int nRow, ContextType contextType, Common::FID fid) const
 Checks whether MFC control is attached to a given cell.
Edit in place
IEditInPlaceSetEditInPlace (IEditInPlace *editInPlace)
 Sets new IEditInPlace interface. The function returns previous value of the interface.
IEditInPlaceGetEditInPlace () const
 Gets current IEditInPlace interface used by the grid.
bool CanStartEditInPlace (HITEM hItem, Common::FID fid, IEditInPlace::StartReason reason) const
 Checks if it is possible to start 'edit in place' for a given cell.
bool StartEditInPlace (HITEM hItem, Common::FID fid, IEditInPlace::StartReason reason=IEditInPlace::ActivateOnUserStart)
 Starts 'edit in place' process for a given grid cell.
bool StopEditInPlace (IEditInPlace::StopReason reason, bool postMessage=false)
 Requests the grid to stop' edit in place' specifying a reason (lost of focus, navigation, enter...).
CWnd * GetEditInPlaceControl () const
 Gets a pointer to the control that is currently participating in 'edit in place' operation.
const CEditInPlaceSettingsGetEditInPlaceSettings () const
 Gets current 'edit in place' settings collected in CEditInPlaceSettings class object. Const version.
CEditInPlaceSettingsGetEditInPlaceSettings ()
 Gets current 'edit in place' settings collected in CEditInPlaceSettings class object.
void SetEditInPlaceSettings (const CEditInPlaceSettings &settings)
 Sets new 'edit in place' settings.

Detailed Description

This class implements full featured thread-safe hierarchical list control.

Introduction
The grid is intended for working with data of almost any type. Such data is the object of usual C++ classes with the set of Get- and Set- methods that can be called by their identifiers. These identifiers are declared together with a class. To be able to insert such objects into the grid, the class should inherit from Common::CDataObject which permits to call the function by its identifier. These objects are displayed in the grid by using the binding mechanism. The rows of the grid correspond to objects of your classes and columns to their functions.

The grid supports automatic updating, sorting, highlighting and filtration of the objects for each value modification. To benefit from this, it is recommended to implement Common::CDataOnject::ISink interface that can fire notifications to the grid.

The grid enables simultaneous use of objects of different classes. The only condition is that types of values returned by the functions should be the same. It is not so critical for data painting and highlighting but for sorting it is required to compare values of one type.

Purpose of contexts
The grid has two graphical contexts: fixed and scrollable. These contexts have been implemented because it is not possible to set just a number of 'frozen' rows in the hierarchical grid. Indeed, the quantity of such rows is not constant and may vary depending on whether the children are expanded or collapsed. Furthermore, data objects can be automatically filtered in the IGridFilter interface.

Handles & lines in the grid
As mentioned above, the grid works with C++ objects. One data object can be inserted into one grid multiple times. Handles were organized for unique identification of object location in the grid. Handles take part in all grid operations. They also store information about hierarchy, selection, filtration, time of the last updating and so on. Sometimes a handle may be invisible on the screen. It can be filtered by IGridFilter interface or hidden by its parent. Such handle doesn't have a corresponding grid line. Handles can be easily detached from the grid with all hierarchy and inserted to any other point or grid.

Focus
Focus is designed to define the cursor location during navigation and lines selection in the grid. Grid may have only one focused line. As the grid can support multiple contexts, the focused context is the context where the focused line is located.

Appearance
Grid appearance is stored in an object of CAppearance type. Data drawing operation gets all colors from this object. All painting information is passed through ICustomDraw interface where it can be freely redefined.

Tooltips
A tooltip is designed to enhance application functionality for instances when information that must be provided to the user cannot be displayed entirely. Functionally the tooltip has two interfaces. The first interface is designed to manage a pop-up window, its color, location and so on. The second interface is designed to manage the content displayed in the window. GUI library provides two types of tooltips:

Copy & paste
Copy & paste enables you to move data within one grid, between grids or between applications. The grid enables you to export data to such applications as Excel and Word. In addition to standard clipboard formats, GUI library has new formats that enable hierarchical information maintenance and also support moving data between different applications with data serialization where it is possible. The programmer can customize the copy & paste mechanism at any moment. To control copy/paste process the grid provides ICopyPaste interface and its default implementation in CCopyPaste class.

Drag and Drop
The grid provides default Drag & drop implementation. It is possible to move selected lines inside one grid, between grids or between applications. Moreover, at any moment a programmer can customize drag & drop behavior for his own purposes. To indicate the dropping place, the grid illuminates the lines between which data will be inserted. However, it is not enough for hierarchical data because the hierarchy level remains unknown. Our grid can indicate this hierarchical level thus enabling you to clearly specify the user's wishes concerning data insertion to the desired position. All drag and drop steps are conducted though IDragDrop interface where they can be totally redefined.

Sorting
This is one of automated services that greatly simplify programming and at the same time improve application quality. If data is updated (notification from Common::CDataObject::ISink interface or UpdateRow(), UpdateItem() or UpdateDataObject() functions call), the grid automatically searches a new position according to sorting and hierarchy rules. Information about sorting is stored in the header. If the header is changed, sorting is also updated. Sorting can be single and multiple on one or several grid columns. Single click with the left mouse button on the header column switches single sorting on. Second click inverts the sorting direction. Multiple sorting is possible with mouse click with Ctrl key pressed. The second click with Ctrl key held changes sorting direction in the column where the click was made. To cancel sorting it's enough to click on the header with the left mouse button while holding Shift key. Of course it is possible to control sorting by programming means.

Data filtration
The grid supports automated data filtration. A grid line is considered filtered if the operator () of IGridFilter interface returns true. If the line is filtered, neither the line nor its children can be visible. The visibility check is carried out at C++ object insertion, at its updating through Common::CDataObject::ISink interface, at UpdateRow(), UpdateItem() or UpdateDataObject() functions call and in some other cases.

Navigation and keyboard
All navigation management is placed in the external module that opens virtually unlimited possibilities to manage keyboard events. All navigation is collected in the implementation of IKeyManager interface. We offer the default implementation in the CKeyManager class. You can get an object of this class by calling CPreferences::GetDefaultKeyManager().

Printing
The grid enables you to print its content on a printer and also has a 'print preview' option. There are various scaling levels and a possibility to choose either a portrait or a landscape mode.

Built in controls
Traditionally so called drawing of either control directly at the place of grid cells location is used to implement 'edit in place' possibilities. The controls themselves are created in the moment when the user clicks in a grid cell. Usually the range of such controls is rather limited and depends on grid developer. The necessity to use real controls or controls of outside developer scope may often arise. In such case it is required to keep a track of control location, its movements, size and visibility changes according to scrollbar location, filtration, cell size, hierarchy position, etc. Implementation of control positioning code is a difficult and laborious task for the programmer. To simplify development of the resulting application the grid provides a convenient service for positioning almost any controls above the grid. The programmer just needs to assign the cell to which a control has to be attached and specify some control settings. It is important to note that the grid doesn't manage control's life time. The programmer is fully responsible for creating and deleting controls. The grid only conducts control positioning relative to a grid cell.

Edit in place
The grid provides a very simple and useful positioning service for almost any MFC controls with navigation between them. In most cases buttons, check boxes, and other elements are not real controls but only images. Basically, such 'controls' are supplied together with grids and their number and functionality may be limited. Moreover, such approach does not allow the use of already existing solutions or third-party libraries. For real controls it is necessary to handle control location and size according to the number of elements in the grid and scrollbar positions, and also to manage their visibility (for filtration, expand/collapse and row deleting). This is not a trivial task and some difficulties may arise during its fulfillment. We offer the solution that enables you to attach almost any MFC control to any cell, and the grid handles the positioning and visibility of the controls itself.

Serialization
Serialization in CArchive is a useful grid feature. Position, column colors, user preferences and other items are serialized. The grid is designed in such a way that new grid versions are be compatible with archives made in previous versions.

Thread safety
The grid was designed to work in a heavy multi-threaded environment. Almost all functions are thread-safe. They use both synchronous and asynchronous mechanisms with or without blocking the calling thread. Inserting, removing, getting etc. block the calling thread. Any data updating operations are processed via the asynchronous mechanism. The calling thread does not wait for the end of updating operation. Many updating operations may occur at the same time. In this case the dead-lock between GUI and non-GUI threads is not possible.

To display information in cells, the grid needs to retrieve values from your business objects. There are two thread-safe modes to do it:

Read What is a data object? article to get more information about binding.

The article How to install the MFC grid and compile the first application? explains all steps of installing and compiling your first application.

Example:
How to create the grid:
 class CDemoView : public CView
 {
   ...
      afx_msg int  OnCreate(LPCREATESTRUCT lpCreateStruct);
      afx_msg void OnSize(UINT nType, int cx, int cy);
   private:
      Dapfor::GUI::CGrid m_Grid;
 };

 int CDemoView::OnCreate(LPCREATESTRUCT lpCreateStruct)
 {
    ...
    //Initialize the grid
    m_Grid.Create(0, 0, WS_VISIBLE|WS_CHILD, CRect(), this, 1000);
   
    //Create a header:
    Dapfor::GUI::CHeader* header = new Dapfor::GUI::CHeader(true);

    //Add some columns to the header. Field identifiers should be the same as declared in the data object
    //For more information see "How to install my first application"
    header->Add(new Dapfor::GUI::CColumn(CDemoClass::FidPrice,  _T("Field1"), 190));

    //Set the header to the grid     
    m_Grid.SetHeader(header);

    ...
    return 0;
 }

 void CDemoView::OnSize(UINT nType, int cx, int cy) 
 {
     CMDIChildWnd::OnSize(nType, cx, cy);

     //Fit the grid to the client's area
     CRect rc;
     GetClientRect(rc);
     m_Grid.MoveWindow(rc);
 }


 //Declaration of some C++ class:
  class CDemoClass : public Common::CDataObject
  {
  public:
      enum 
      {
         FidPrice,
      };
      ...
      double GetPrice() const;
      ...
  };

  //This code adds C++ objects to the grid:
  CDemoClass* obj = new CDemoClass();
  m_Grid.Add(obj);

Member Function Documentation

HITEM Add ( Common::CDataObject pDO,
HITEM  hParent = GI_SCROLLABLE_ROOT,
HITEM  hInsertAfter = GI_LAST 
)

Adds a data object to the grid.

The grid has hierarchical architecture. Scrolled (GI_SCROLLABLE_ROOT) or fixed (GI_FIXED_ROOT) contexts can have root value. These contexts are not displayed in the grid. That's why when a data object is added to these contexts, it is visually placed to the top level of the hierarchy. If addition is successful, a handle that identifies data object position in the grid and is unique for an application, is returned. The acquired handle can be used as a parent to add new objects. The hierarchy is usually built, when values are added but also can be changed later. The same data object can be inserted into the grid multiple times. A handle can be detached from the grid and attached to any other place or even to a different grid. It's important to note that the grid doesn't control the data objects life. Data can be stored at any place according to the programmer's desire. The method of data objects storage doesn't have to match grid hierarchy. Moreover, in other grids it is possible to built a completely different hierarchy using the same data objects. During data object implementation it is strongly recommended to use ISink interface that can notify the grid about data modification. It enables use of automatic data updating, sorting, highlighting and filtration services that make the application much simpler. It is also significant that if sorting is switched on, a data object is added to hParent in accordance with sorting rules. If hParent is collapsed or filtered, a data object is added but not seen. In terms of productivity, adding data to the end of the grid is several times more productive than to the beginning.

Parameters:
[in] pDO added data object
[in] hParent parent item to which a data object is added. The following values are available:
GI_SCROLLABLE_ROOT A data object is added to the first level of the hierarchy and is scrollable
GI_FIXED_ROOT A data object is added to the first level of the hierarchy and is not scrollable
HITEM Any handle acquired before addition to the grid.
[in] hInsertAfter a value used to specify location of an insertion. If sorting is switched on, this parameter doesn't have any meaning because a data object is inserted according to the sorting rules. If there is no sorting hInsertAfter can have the following values:
GI_FIRST Insertion to the beginning
GI_LAST Insertion to the end
HITEM Insertion after a given handle
Returns:
If a handle is added successfully, it returns unique data object position in the grid. Otherwise '0' is returned.
thread-safety
The function is thread-safe. When it is called from a non-GUI thread, synchronization is performed via SendMessage mechanism. If MemoryBuffer mode is used then all formatted and unformatted data in a calling thread is copied and forwarded to GUI thread.
Example
 class CAuthor : public Dapfor::Common::CDataObject
 { 
    ...
    CString GetFirstName() const;
    CString GetLastName() const;
    ...
 };

 class CBook : public Dapfor::Common::CDataObject
 { 
    ...
    CString GetAuthor() const;
    ...
 };
 
 //Instantiate author and his books
 CAuthor* author = new CAuthor(...);
 CBook* book1 = new CBook(...);
 CBook* book2 = new CBook(...);

 //Add author to the grid
 m_Grid.Add(author);

 //Attach books to the author in the hierarchical grid
 m_Grid.Add(book1, m_Grid.GetItem(author)); 
 m_Grid.Add(book2, m_Grid.GetItem(author)); 

 //The following code 'frezes' the author i.e. adds an author to fixed context:
 m_Grid.Add(new CAuthor(...), Dapfor::GUI::GI_FIXED_ROOT);
See also:
Read the How to compile my first application? article for step-by-step instructions on building an application. You can find more information about the data object here.

bool Delete ( HITEM  hItem  ) 

Deletes an item from the grid.

When this function is called, line that corresponds to specified handle is deleted together with all children. Deleting is done even if the handle is filtered or collapsed by the parent. The grid doesn't hold a data object but only displays it on screen through the system of formats. Therefore, when a handle is deleted, the data object is not physically destroyed, and if it is inserted multiple times into the same grid or into several grids, then it is displayed as before elsewhere, safe for the deleted line.

Parameters:
[in] hItem handle that has to be deleted.
Returns:
True if the handle has been successfully deleted. Otherwise - false.
thread-safety
The function is thread-safe. When it is called from a non-GUI thread synchronization is performed through SendMessage mechanism.
Example
 //Add an object to the grid
 CSomeClass* someObject = new CSomeClass(...);
 Dapfor::GUI::HITEM hItem = m_Grid.Add(someObject);

 ...

 //Remove the row with all children from the grid. Note, that calling does not destroy object of CSomeClass. 
 //It just removes the corresponding row.
 m_Grid.Delete(hItem);

 someObject->DoSomething(...);  //Ok, the object is alive.
See also:
Read the How to compile my first application? article for step-by-step instructions on application building. You can find more information about a data object here.

int Delete ( const Common::CDataObject pDO  ) 

Deletes all lines corresponding to a given data object from the grid.

This function can be useful when a data object is inserted into the grid multiple times. When a data object is deleted from the grid, it is not physically destroyed.

Parameters:
[in] pDO pointer to the data object that should be deleted from the grid.
Returns:
Found a number of data object entries in the grid.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
 //Adds an object to the grid
 CSomeClass* someObject = new CSomeClass(...);
 m_Grid.Add(someObject);

 ...

 //Remove all rows with their children that correspond to specified object from the grid. 
 //The grid looks for all GUI::HITEM (one or more) with the given data object and removes them.
 //Note that the call does not destroy the object of CSomeClass. 
 m_Grid.Delete(someObject);     

 someObject->DoSomething(...);  //Ok, the object is alive.

bool Delete ( int  nRow,
ContextType  contextType = ScrollableContext 
)

Deletes a visible line from a given data context.

If a line contains children (both visible and invisible) they all will also be deleted. The function doesn't delete data objects (doesn't call their destructors) but only deletes the reference to data objects found in the grid.

Parameters:
[in] nRow index of a visible line which starts from 0.
[in] contextType type of a data context. Available values: FixedContext, ScrollableContext. For AllContexts the grid is trying to delete the given line in every context.
Returns:
True if the given line has been successfully deleted. Otherwise - false.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
 //Remove the first non-scrollable row (indices start from 0) with all children. 
 //Note that the call does not destroy the data object. 
 m_Grid.Delete(0, Dapfor::GUI::FixedContext);       

void DeleteAll ( ContextType  contextType = AllContexts  ) 

Deletes all data from a given context.

Parameters:
[in] contextType type of a data context. Available values: FixedContext, ScrollableContext, AllContexts.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
 //Remove all non-scrollable rows. 
 m_Grid.DeleteAll(Dapfor::GUI::FixedContext);

 //Remove all scrollable & non-scrollable rows. 
 m_Grid.DeleteAll(Dapfor::GUI::AllContexts);

Handles GetHandles ( const Common::CDataObject pDO,
bool  visibleOnly,
ContextType  contextType = AllContexts 
) const

Gets all handles corresponding to a given data object.

Multiple handles can correspond to one data object. Some handles for one object might be filtered (lines is invisible) or hidden by their parents.

Parameters:
[in] pDO pointer to a data object.
[in] visibleOnly flag pointing that the returned handles is visible in the grid, i.e. not hidden by the parents or filtered.
[in] contextType type of the context where handles is searched. Available values: FixedContext, ScrollableContext, AllContexts.
Returns:
List of handles corresponding to a given data object.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
 //Gets all rows visible in the grid (scrollable and non-scrollable) corresponding to the specified data object
 Dapfor::GUI::Handles& handles = m_Grid.GetHandles(root, true);
 
 //Gets all visible and invisible (filtered or collapsed) non-scrollable rows 
 //that correspond to the specified data object
 Dapfor::GUI::Handles& handles = m_Grid.GetHandles(root, false, Dapfor::GUI::FixedContext);

Handles GetHandles ( ContextType  contextType = AllContexts  )  const

Get a copy of all handles inserted into the grid.

Parameters:
[in] contextType type of context where handles is searched. Available values: FixedContext, ScrollableContext, AllContexts.
Returns:
a copy of handles, stored in the grid.

bool Attach ( HITEM  hItem,
HITEM  hParent,
HITEM  hInsertAfter = GI_LAST 
)

This function enables attachment of a given hItem to the grid.

The ability to attach/detach handles was implemented to enable easy transfer of hierarchical data within one context, between different contexts and between different grids while preserving their hierarchy. This function is applicable only to data previously detached from the grid. One handle can't be attached two times to one or several grids.

Parameters:
[in] hItem Handle to be attached.
[in] hParent Parent, to which the attachment is done. Any got in Add() function value or one of the following contexts: GI_SCROLABLE_ROOT or GI_FIXED_ROOT can be a parent.
[in] hInsertAfter the value used to specify location of the insertion. If sorting is switched on then this parameter doesn't have any meaning because the data object is inserted according to the sorting rules. If there is no sorting hInsertAfter can have the following values:
GI_FIRST Insertion to the beginning
GI_LAST Insertion to the end
HITEM Insertion after a given handle
Returns:
True for successful operation. Otherwise - false. The function can complete unsuccessfully if hItem has not been previously detached or hParent and hInsertAfter values are incorrect.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool Detach ( HITEM  hItem  ) 

Detaches a handle inserted by Add() function from the grid.

Parameters:
[in] hItem Handle to be detached.
Returns:
True for a successful operation. Otherwise - false.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread synchronization is performed via SendMessage mechanism.

bool Exists ( HITEM  hItem  )  const

Checks whether a given handle is attached to the grid.

Parameters:
[in] hItem Handle to be verified
Returns:
True if the handle has already been added to the grid and actually attached to it. Otherwise false.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread synchronization is performed via SendMessage mechanism.

bool Exists ( const Common::CDataObject pDO  )  const

Checks whether a given data object is inserted into the grid. One data object can be inserted multiple times into a single grid. For each insertion a unique handle is created. This handle enables unique definition of object position and status in the grid.

Parameters:
[in] pDO data object to be verified
Returns:
True if at least one handle is found in the grid. Otherwise - False.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

unsigned int GetRowCount ( ContextType  contextType = ScrollableContext  )  const

Gets a number of visible grid lines (not filtered and not hidden by parents).

The search can be performed in one or both contexts.

Parameters:
[in] contextType Type of the context where the search is performed. Available values: FixedContext, ScrollableContext, AllContexts.
Returns:
Counted number of visible grid lines.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void ForEach ( IForEach functional,
HITEM  startFrom = GI_FIRST 
)

Conducts a search and passes all found handles with data objects to the functional object.

The search includes visible and invisible lines. It can be started not only from the first line but also from position assigned by startFrom. The search can be interrupted if IForEach returns 'false'.

Parameters:
[in] functional Functional where all found handles and data objects are handed over to.
[in] startFrom handle from which the search starts. Available values: GI_FIRST, GI_FIXED_ROOT, GI_SCROLLABLE_ROOT, any inserted onto the grid handle. If GI_FIRST is used, the search starts from fixed context, and if it has no elements - from scrollable context.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. It is important that at multi-threaded applications search and transmission of handles and data objects are always performed in GUI thread. If the function is called from another thread, the calling thread is blocked until it is returned by the function.
#include <Dapfor/GUI/IForEach.h>

//The functor that counts visible and invisible rows in the grid
class RowsCounter : public Dapfor::GUI::IForEach
{
public:
    int GetVisibleRows() const {return m_VisibleRows;}
    int GetInvisibleRows() const {return m_InvisibleRows;}

    virtual bool operator () (Dapfor::GUI::CGrid& grid, Dapfor::GUI::HITEM item, Dapfor::Common::CDataObject* pDO)
    {
        if(grid.IsVisible(item))
        {
            //Increment count of visible rows
            m_VisibleRows++;
        }
        else
        {
            //Increment count of invisible rows
            m_InvisibleRows++;
        }

        //Continue iterations
        return true;
    }

private:
    int m_VisibleRows;
    int m_InvisibleRows;
};


//How to use:

//the functor is applied to both visible and invisible items
RowsCounter functor1;
m_Grid.ForEach(functor1);

//the functor is applied only to visible rows
//functor2.GetInvisibleRows() will get zero.
RowsCounter functor2;
m_Grid.ForEachVisible(functor2);

void ForEachVisible ( IForEach functional,
HITEM  startFrom = GI_FIRST 
)

Conducts a search and passes all found visible handles with data objects to the functional object.

The search includes only visible lines. It can be started not only from the first line but also from position assigned by startFrom. The search can be interrupted if IForEach returns 'false'.

Parameters:
[in] functional Functional where all found handles and data objects are handed over to.
[in] startFrom handle from which the search starts. Available values: GI_FIRST, GI_FIXED_ROOT, GI_SCROLLABLE_ROOT, any value inserted to grid handle. If GI_FIRST is used then the search starts from fixed context, and if it has no elements then from scrollable context.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. It is significant that at multithread applications realization the search and transmission of handles and data objects are always performed in GUI thread. If the function is called from other thread, the calling thread is blocked until it is returned by the function.
#include <Dapfor/GUI/IForEach.h>

//The functor that counts visible and invisible rows in the grid
class RowsCounter : public Dapfor::GUI::IForEach
{
public:
    int GetVisibleRows() const {return m_VisibleRows;}
    int GetInvisibleRows() const {return m_InvisibleRows;}

    virtual bool operator () (Dapfor::GUI::CGrid& grid, Dapfor::GUI::HITEM item, Dapfor::Common::CDataObject* pDO)
    {
        if(grid.IsVisible(item))
        {
            //Increment count of visible rows
            m_VisibleRows++;
        }
        else
        {
            //Increment count of invisible rows
            m_InvisibleRows++;
        }

        //Continue iterations
        return true;
    }

private:
    int m_VisibleRows;
    int m_InvisibleRows;
};


//How to use:

//the functor is applied to both visible and invisible items
RowsCounter functor1;
m_Grid.ForEach(functor1);

//the functor is applied only to visible rows
//functor2.GetInvisibleRows() will get zero.
RowsCounter functor2;
m_Grid.ForEachVisible(functor2);

bool MoveBefore ( HITEM  movingItem,
HITEM  parentPosition,
HITEM  position 
)

Moves a given handle with all hierarchy to a position before the specified position for the specified parent.

The move is performed by consecutively detaching handle from the grid and then attaching it to the new position.

Parameters:
[in] movingItem Moved handle.
[in] parentPosition Parent, to which the moved handle is attached. The parent must not be a direct or indirect child of the moved handle. Available values:
0 Moving within a single parent
GI_SCROLLABLE_ROOT Moving to the highest level of the hierarchy in scrollable context
GI_FIXED_ROOT Moving to the highest level of the hierarchy in fixed context
[in] position Position before which the handle is inserted. Available values:
GI_FIRST Insertion to the first position
GI_LAST Insertion before the last position
HITEM Insertion before a given handle
Returns:
True if the handle has been successfully moved. Otherwise false.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
    //Get a handle that corresponds to the specified data object
    Dapfor::Common::CDataObject* pDO = ...;
    Dapfor::GUI::HITEM hItem = m_Grid.GetItem(pDO);
   
    //'Freeze' the item. i.e. move to fixed context
    m_Grid.MoveAfter(hItem, Dapfor::GUI::GI_FIXED_ROOT, Dapfor::GUI::GI_LAST);

bool MoveAfter ( HITEM  movingItem,
HITEM  parentPosition,
HITEM  position 
)

Moves a given handle with all hierarchy to a position after the specified position for the specified parent.

The move is performed by consecutively detaching handle from the grid and then attaching it to a new position.

Parameters:
[in] movingItem Moved handle.
[in] parentPosition Parent to which the moved handle is attached. The parent must not be a direct or indirect child of the moved handle. Available values:
0 Moving within one parent
GI_SCROLLABLE_ROOT Moving to the highest level of the hierarchy in scrollable context
GI_FIXED_ROOT Moving to the highest level of the hierarchy in fixed context
[in] position Position after which the handle is inserted. Available values:
GI_FIRST Insertion to the first position
GI_LAST Insertion after the last position
HITEM Insertion after a given handle
Returns:
True if the handle has been successfully moved. Otherwise false.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread synchronization is performed via SendMessage mechanism.
    //Get a handle that corresponds to the specified data object
    Dapfor::Common::CDataObject* pDO = ...;
    Dapfor::GUI::HITEM hItem = m_Grid.GetItem(pDO);
   
    //'Freeze' the item. i.e. move to fixed context
    m_Grid.MoveAfter(hItem, Dapfor::GUI::GI_FIXED_ROOT, Dapfor::GUI::GI_LAST);

Common::CValue GetValue ( HITEM  hItem,
Common::FID  fid 
) const

The function enables getting unformatted value of a data object corresponding to a 'fid'.

It is important that in CPreferences::MemoryBuffer mode data is obtained from the grid's cache but not from the data object. As the result, the data object is not accessed. In CPreferences::DirectCall mode the value is requested directly from the data object.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible.
[in] fid field identifier.
Returns:
Requested value in case of success. If a data object field is not found, Common::CValue with Common::Undefined identifier is returned.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread synchronization is performed via SendMessage mechanism. Its worth mentioning that in CPreferences::DirectCall mode data object values are always requested in GUI thread even if the function is called in other thread.
Example
//Declaration of a data object

class CTestClass : public Dapfor::Common::CDataObject
{
    enum
    {
        FidPrice,
    };  

    double GetPrice() const {return ...;}
    void   SetPrice(double newPrice) {...; NotifyUpdate(FidPrice);}
};

DF_BEGIN_FIELD_MAP(CTestClass)
    DF_DOUBLE_ID(FidPrice,    "Price",    &CTestClass::GetPrice,   &CTestClass::SetPrice, 0)
DF_END_FIELD_MAP()



//There are many ways to get a non-formatted value from a grid cell
//1. If you have a pointer to the object of your class
CTestClass* testClass;
double price = testClass->GetPrice();

//2. If you have a pointer to the data object and don't want to cast to the CTestClass type:
Dapfor::Common::CDataObject* testClass = new CTestClass();
double price = testClass->GetDouble(CTestClass::FidPrice);
//or
double price = testClass->GetValue(CTestClass::FidPrice);


//3. Get the value directly from the grid. Note, that you get the typed value!
//For Datfor::GUI::CPreferences::DirectCall mode the grid will get data from the data object
//by calling GetPrice() method.
//For Datfor::GUI::CPreferences::MemoryBuffer mode the grid will return value from the cache.
double price = m_Grid.GetValue(hItem, CTestClass::FidPrice);


//In the same way you can get formatted values as MFC or STL strings
Dapfor::Common::CDataObject* testClass = ...;
CString mfcText = testClass->GetFormattedMfcString(CTestClass::FidPrice, 0);
std::string stlText = testClass->GetFormattedStlString(CTestClass::FidPrice, 0);

//Or from the grid:
CString mfcText = m_Grid.GetFormattedMfcString(hItem, CTestClass::FidPrice);
std::string stlText = m_Grid.GetFormattedStlString(hItem, CTestClass::FidPrice);


//The preferred way to set a new value is to implement a notification mechanism 
//in the data object and to call Set- method.
CTestClass* testClass = new CTestClass();
test->SetPrice(...);

//Of course, you can call 
m_Grid.SetValue(hItem, CTestClass::FidPrice, (double)1.23);
testClass->SetValue(CTestClass::FidPrice, (double)1.23);

//Alternatively, if you want to transform MFC/STL string to a value, you can use the following
m_Grid.SetFormattedMfcString(hItem, CTestClass::FidPrice, "1.23");
testClass->SetFormattedMfcString(CTestClass::FidPrice, "1.23", 0);

bool SetValue ( HITEM  hItem,
Common::FID  fid,
const Common::CValue value 
)

Sets a new value for the data object.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible.
[in] fid Field's identifier.
[in] value New value that is set for the data object.
Returns:
True, if the value has been set. Otherwise - false.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread synchronization is performed via SendMessage mechanism. Regardless of thread-safety mode, the function accesses the data object to modify its value. Access and value modification are always performed in GUI thread. If the data object is supposed to be used in multi-threaded applications, its internal data should be protected with critical sections or mutexes.
Example
//Declaration of a data object

class CTestClass : public Dapfor::Common::CDataObject
{
    enum
    {
        FidPrice,
    };  

    double GetPrice() const {return ...;}
    void   SetPrice(double newPrice) {...; NotifyUpdate(FidPrice);}
};

DF_BEGIN_FIELD_MAP(CTestClass)
    DF_DOUBLE_ID(FidPrice,    "Price",    &CTestClass::GetPrice,   &CTestClass::SetPrice, 0)
DF_END_FIELD_MAP()



//There are many ways to get a non-formatted value from a grid cell
//1. If you have a pointer to the object of your class
CTestClass* testClass;
double price = testClass->GetPrice();

//2. If you have a pointer to the data object and don't want to cast to the CTestClass type:
Dapfor::Common::CDataObject* testClass = new CTestClass();
double price = testClass->GetDouble(CTestClass::FidPrice);
//or
double price = testClass->GetValue(CTestClass::FidPrice);


//3. Get the value directly from the grid. Note, that you get the typed value!
//For Datfor::GUI::CPreferences::DirectCall mode the grid will get data from the data object
//by calling GetPrice() method.
//For Datfor::GUI::CPreferences::MemoryBuffer mode the grid will return value from the cache.
double price = m_Grid.GetValue(hItem, CTestClass::FidPrice);


//In the same way you can get formatted values as MFC or STL strings
Dapfor::Common::CDataObject* testClass = ...;
CString mfcText = testClass->GetFormattedMfcString(CTestClass::FidPrice, 0);
std::string stlText = testClass->GetFormattedStlString(CTestClass::FidPrice, 0);

//Or from the grid:
CString mfcText = m_Grid.GetFormattedMfcString(hItem, CTestClass::FidPrice);
std::string stlText = m_Grid.GetFormattedStlString(hItem, CTestClass::FidPrice);


//The preferred way to set a new value is to implement a notification mechanism 
//in the data object and to call Set- method.
CTestClass* testClass = new CTestClass();
test->SetPrice(...);

//Of course, you can call 
m_Grid.SetValue(hItem, CTestClass::FidPrice, (double)1.23);
testClass->SetValue(CTestClass::FidPrice, (double)1.23);

//Alternatively, if you want to transform MFC/STL string to a value, you can use the following
m_Grid.SetFormattedMfcString(hItem, CTestClass::FidPrice, "1.23");
testClass->SetFormattedMfcString(CTestClass::FidPrice, "1.23", 0);

TString GetFormattedStlString ( HITEM  hItem,
Common::FID  fid,
const Common::CFormat format = 0 
) const

Gets a formatted string from a data object by its field identifier.

In CPreferences::MemoryBuffer mode the string is taken from cache, CPreferences::DirectCall mode the value is requested from the data object and then is formatted into a string.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible.
[in] fid Field's identifier.
[in] format The format that is used for formatting value in the string. If the format is not specified, search is conducted as follows: Firstly, the format is searched in object of CColumn class. If it is not found, the format is searched in data object Common::CFieldMap. If the format is not defined after that, the default format returned by Common::CFormat::GetDefaultFormat() function is selected.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. It's worth mentioning that in CPreferences::DirectCall mode data object values are always requested in GUI thread, even if the function is called in another thread.
Example
//Declaration of a data object

class CTestClass : public Dapfor::Common::CDataObject
{
    enum
    {
        FidPrice,
    };  

    double GetPrice() const {return ...;}
    void   SetPrice(double newPrice) {...; NotifyUpdate(FidPrice);}
};

DF_BEGIN_FIELD_MAP(CTestClass)
    DF_DOUBLE_ID(FidPrice,    "Price",    &CTestClass::GetPrice,   &CTestClass::SetPrice, 0)
DF_END_FIELD_MAP()



//There are many ways to get a non-formatted value from a grid cell
//1. If you have a pointer to the object of your class
CTestClass* testClass;
double price = testClass->GetPrice();

//2. If you have a pointer to the data object and don't want to cast to the CTestClass type:
Dapfor::Common::CDataObject* testClass = new CTestClass();
double price = testClass->GetDouble(CTestClass::FidPrice);
//or
double price = testClass->GetValue(CTestClass::FidPrice);


//3. Get the value directly from the grid. Note, that you get the typed value!
//For Datfor::GUI::CPreferences::DirectCall mode the grid will get data from the data object
//by calling GetPrice() method.
//For Datfor::GUI::CPreferences::MemoryBuffer mode the grid will return value from the cache.
double price = m_Grid.GetValue(hItem, CTestClass::FidPrice);


//In the same way you can get formatted values as MFC or STL strings
Dapfor::Common::CDataObject* testClass = ...;
CString mfcText = testClass->GetFormattedMfcString(CTestClass::FidPrice, 0);
std::string stlText = testClass->GetFormattedStlString(CTestClass::FidPrice, 0);

//Or from the grid:
CString mfcText = m_Grid.GetFormattedMfcString(hItem, CTestClass::FidPrice);
std::string stlText = m_Grid.GetFormattedStlString(hItem, CTestClass::FidPrice);


//The preferred way to set a new value is to implement a notification mechanism 
//in the data object and to call Set- method.
CTestClass* testClass = new CTestClass();
test->SetPrice(...);

//Of course, you can call 
m_Grid.SetValue(hItem, CTestClass::FidPrice, (double)1.23);
testClass->SetValue(CTestClass::FidPrice, (double)1.23);

//Alternatively, if you want to transform MFC/STL string to a value, you can use the following
m_Grid.SetFormattedMfcString(hItem, CTestClass::FidPrice, "1.23");
testClass->SetFormattedMfcString(CTestClass::FidPrice, "1.23", 0);

bool SetFormattedStlString ( HITEM  hItem,
Common::FID  fid,
const TString &  str,
const Common::CFormat format = 0 
)

Sets a new value into the data object using a formatted string.

A formatted string cannot be directly set for the data object because it works with and stores only unformatted values. A string is converted into an unformatted value via format object.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible.
[in] fid Field's identifier.
[in] str Unformatted string.
[in] format The format to convert a formatted string into value
Returns:
True, if the value has been set. Otherwise - false.
thread-safety
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. Regardless of thread-safety mode, the function accesses the data object to modify its value. Access and value modification are always performed in GUI thread. String is always converted into a value in GUI thread. If the data object is supposed to be used in multi-threaded applications, its internal data should be protected with critical sections or mutexes.
Example
//Declaration of a data object

class CTestClass : public Dapfor::Common::CDataObject
{
    enum
    {
        FidPrice,
    };  

    double GetPrice() const {return ...;}
    void   SetPrice(double newPrice) {...; NotifyUpdate(FidPrice);}
};

DF_BEGIN_FIELD_MAP(CTestClass)
    DF_DOUBLE_ID(FidPrice,    "Price",    &CTestClass::GetPrice,   &CTestClass::SetPrice, 0)
DF_END_FIELD_MAP()



//There are many ways to get a non-formatted value from a grid cell
//1. If you have a pointer to the object of your class
CTestClass* testClass;
double price = testClass->GetPrice();

//2. If you have a pointer to the data object and don't want to cast to the CTestClass type:
Dapfor::Common::CDataObject* testClass = new CTestClass();
double price = testClass->GetDouble(CTestClass::FidPrice);
//or
double price = testClass->GetValue(CTestClass::FidPrice);


//3. Get the value directly from the grid. Note, that you get the typed value!
//For Datfor::GUI::CPreferences::DirectCall mode the grid will get data from the data object
//by calling GetPrice() method.
//For Datfor::GUI::CPreferences::MemoryBuffer mode the grid will return value from the cache.
double price = m_Grid.GetValue(hItem, CTestClass::FidPrice);


//In the same way you can get formatted values as MFC or STL strings
Dapfor::Common::CDataObject* testClass = ...;
CString mfcText = testClass->GetFormattedMfcString(CTestClass::FidPrice, 0);
std::string stlText = testClass->GetFormattedStlString(CTestClass::FidPrice, 0);

//Or from the grid:
CString mfcText = m_Grid.GetFormattedMfcString(hItem, CTestClass::FidPrice);
std::string stlText = m_Grid.GetFormattedStlString(hItem, CTestClass::FidPrice);


//The preferred way to set a new value is to implement a notification mechanism 
//in the data object and to call Set- method.
CTestClass* testClass = new CTestClass();
test->SetPrice(...);

//Of course, you can call 
m_Grid.SetValue(hItem, CTestClass::FidPrice, (double)1.23);
testClass->SetValue(CTestClass::FidPrice, (double)1.23);

//Alternatively, if you want to transform MFC/STL string to a value, you can use the following
m_Grid.SetFormattedMfcString(hItem, CTestClass::FidPrice, "1.23");
testClass->SetFormattedMfcString(CTestClass::FidPrice, "1.23", 0);

bool IsExpanded ( HITEM  hItem  )  const

Gets the value specifying whether the line is expanded.

If the line is collapsed, all children attached to the given line children are invisible.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible.
Returns:
True if the line has been expanded. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

Handles GetChildren ( HITEM  hItem,
bool  visibleOnly 
) const

Gets handles of all children of a given parent.

Some handles can be filtered (lines are invisible) or hidden by parents.

Parameters:
[in] hItem line handle in the grid. Available for handle values:
HITEM Got from Add function value
GI_SCROLLABLE_ROOT Pseudo-value specifying that scrollable context can be a parental value
GI_FIXED_ROOT Pseudo-vale specifying that fixed context can be a parental value
[in] visibleOnly flag pointing that derivable handles is visible on the screen, i.e. not hidden by parent and not filtered.
Returns:
List of found children for a given parent.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

bool HasChildren ( HITEM  hItem  )  const

Gets the value specifying whether a given handle has at least one child.

Some handles can be filtered (lines are invisible.) or hidden by parents.

Parameters:
[in] hItem line handle in the grid. Available for handle values:
HITEM Got from Add function value
GI_SCROLLABLE_ROOT Pseudo-value specifying that scrollable context can be a parental value
GI_FIXED_ROOT Pseudo-vale specifying that fixed context can be a parental value
Returns:
True if the given handle has at least one child. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

int GetHierarchicalLevel ( HITEM  hItem  )  const

Gets hierarchical level of a given line.

The values of pseudo-handles GI_SCROLLABLE_ROOT and GI_FIXED_ROOT are '-1'. Lines attached to any of these contexts have level '0'. The next children have level '1', and so on. The number of levels is not limited.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible.
Returns:
Hierarchical level in the grid.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

HITEM GetParent ( HITEM  hItem  )  const

Gets the parent to which a line is attached.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible. Any value received from Add function can be used as a parameter.
Returns:
If successful, the parent to which a line is attached. Otherwise - zero.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

void Expand ( HITEM  hItem,
bool  withChildren 
)

Expands a line.

Children attached to this line become visible. Recursive expansion of all children is possible. If GI_SCROLLABLE_ROOT and GI_FIXED_ROOT are passed as an argument in recursive expansion, the grid expands all lines in a given context.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible. GI_SCROLLABLE_ROOT and GI_FIXED_ROOT can be used as parameters. Collapsing and expanding of the root item context doesn't have any effect but it can be useful for recursive data expansion when withChildren = true.
[in] withChildren indicates whether recursive data expansion should be performed for all children attached to a given line.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
This example explains how to expand or collapse items in the grid
CMyClass* myObject = new CMyClass(...);
Dapfor::GUI::HITEM hItem = m_Grid.Add(myObject);

//We expand this node so that all children added to this node are visible
m_Grid.Expand(hItem, false);

//To expand all rows in fixed or scrollable context, you can use a code like this:
m_Grid.Expand(Dapfor::GUI::GI_SCROLLABLE_ROOT, true);


//The same code can be used to collapse all rows
m_Grid.Collapse(Dapfor::GUI::GI_SCROLLABLE_ROOT, true);

void Expand ( const Common::CDataObject pDO,
bool  withChildren 
)

Expands the line, handle of which is associated with the data object.

If multiple handles are found in the grid, the operation is applied to each of them.

Parameters:
[in] pDO pointer to the data object.
[in] withChildren indicates whether recursive data expansion should be performed for all children attached to a given line.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
This example shows how to expand or collapse items in the grid
CMyClass* myObject = new CMyClass(...);
Dapfor::GUI::HITEM hItem = m_Grid.Add(myObject);

//We expand this node so that all children added to this node are visible
m_Grid.Expand(hItem, false);

//To expand all rows in fixed or scrollable context, you can use a code like this:
m_Grid.Expand(Dapfor::GUI::GI_SCROLLABLE_ROOT, true);


//The same code can be used to collapse all rows
m_Grid.Collapse(Dapfor::GUI::GI_SCROLLABLE_ROOT, true);

void Collapse ( HITEM  hItem,
bool  withChildren 
)

Collapses a line.

All children of the line become invisible.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible. GI_SCROLLABLE_ROOT and GI_FIXED_ROOT can be used as parameters. Collapsing and expanding of the root item context doesn't have any effect but can be useful for recursive data collapsing when withChildren = true.
[in] withChildren indicates whether recursive data collapsing should be performed for all children attached to a given line.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
This example shows how to expand or collapse items in the grid
CMyClass* myObject = new CMyClass(...);
Dapfor::GUI::HITEM hItem = m_Grid.Add(myObject);

//We expand this node so that all children added to this node are visible
m_Grid.Expand(hItem, false);

//To expand all rows in fixed or scrollable context, you can use a code like this:
m_Grid.Expand(Dapfor::GUI::GI_SCROLLABLE_ROOT, true);


//The same code can be used to collapse all rows
m_Grid.Collapse(Dapfor::GUI::GI_SCROLLABLE_ROOT, true);

void Collapse ( const Common::CDataObject pDO,
bool  withChildren 
)

Collapses the line, handle of which is associated with the data object.

If multiple handles are found in the grid, the operation is performed for each of them.

Parameters:
[in] pDO pointer to the data object.
[in] withChildren indicates whether recursive data collapsing should be performed for all children attached to a given line.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
This example shows how to expand or collapse items in the grid
CMyClass* myObject = new CMyClass(...);
Dapfor::GUI::HITEM hItem = m_Grid.Add(myObject);

//We expand this node so that all children added to this node are visible
m_Grid.Expand(hItem, false);

//To expand all rows in fixed or scrollable context, you can use a code like this:
m_Grid.Expand(Dapfor::GUI::GI_SCROLLABLE_ROOT, true);


//The same code can be used to collapse all rows
m_Grid.Collapse(Dapfor::GUI::GI_SCROLLABLE_ROOT, true);

int GetRow ( HITEM  hItem  )  const

Gets an index of a visible grid line for a given handle.

The count starts from '0' and is performed from the beginning of the context, not from the beginning of the grid. I.e. the first line in scrollable context always has '0' index. This index doesn't depend on the number of lines in fixed context.

Parameters:
[in] hItem line handle in the grid.
Returns:
Line index in the grid, if the handle is found and the line is not hidden (not filtered and not hidden by its parents). Otherwise - 1. To know the index of what context is returned, you may call GetContextType() function.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

int GetRow ( const Common::CDataObject pDO  )  const

Searches for the grid line corresponding to the first encountered handle of a given data object.

The search starts from fixed context and continues in scrollable context. If the handle is filtered or hidden by its parents, '-1' is returned.

Parameters:
[in] pDO Pointer to the data object
Returns:
Line index in the grid if the handle is found and the line is not hidden (not filtered and not hidden by its parents). Otherwise - 1. To know the index of what context is returned, you may call GetContextType() function.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

ContextType GetContextType ( HITEM  hItem  )  const

Gets grid context, where a given handle belongs.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible.
Returns:
The context, where the handle is inserted, if the handle is found. UndefinedContext if the line has been previously detached or is not found.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

ContextType GetContextType ( const Common::CDataObject pDO  )  const

Gets grid context, where the first encountered handle corresponding to a given data object is inserted.

The search starts from fixed context and continues in scrollable context. If the handle is filtered or hidden by its parents, UndefinedContext is returned.

Parameters:
[in] pDO Pointer to the data object
Returns:
Gets grid contextß ÷­ˇŕˇ the first encountered handle corresponding to a given data object is inserted. The search starts from fixed context and continues in scrollable context. If the handle is filtered or hidden by its parents, UndefinedContext is returned.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

HITEM GetItem ( int  nRow,
ContextType  contextType = ScrollableContext 
) const

Gets a line handle by its absolute location in grid context.

Parameters:
[in] nRow line index in grid context.
[in] contextType grid context. It can be ScrollableContext or FixedContext.
Returns:
Line handle if it is found. Otherwise - 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

HITEM GetItem ( const Common::CDataObject pDO  )  const

Gets the first encountered handle for a given data object.

The search starts from fixed context and continues in scrollable context.

Parameters:
[in] pDO Pointer to the data object
Returns:
Line handle if it is found. Otherwise - 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

HITEM GetItem ( CPoint  point  )  const

Gets a handle of the grid line located within given x, y coordinates.

The coordinates are counted from the beginning of the client area of the grid.

Parameters:
[in] point the coordinates counted in client area of the grid.
Returns:
Line handle if the line is found. Otherwise - 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

HITEM GetPreviousItem ( HITEM  hItem,
bool  jumpBetweenContexts = true 
) const

Gets a handle of the first visible line before a given handle.

To simplify navigation it is possible to jump from scrollable context to fixed context. In this case, if hItem is pointing to the first visible line in scrollable context,the previous line becomes the last visible line in fixed grid context.

Parameters:
[in] hItem handle of a visible line (not filtered and not hidden by parents) in the grid.
[in] jumpBetweenContexts enables search in fixed context if hItem is pointing to scrollable content.
Returns:
Line handle if the line is found. Otherwise - 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

HITEM GetNextItem ( HITEM  hItem,
bool  jumpBetweenContexts = true 
) const

Gets a handle of the next visible line after a given handle.

To simplify navigation, it is possible to jump from fixed context to scrollable context. In this case, if hItem is pointing to the last visible line in fixed context, the next line has '0' index in scrollable grid context.

Parameters:
[in] hItem handle of a visible line (not filtered and not hidden by parents) in the grid.
[in] jumpBetweenContexts enables search in scrollable context if hItem is pointing to the fixed one.
Returns:
Line handle if the line is found. Otherwise - 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

Common::CDataObject * GetDataObject ( HITEM  hItem  ) 

Gets the data object corresponding to a given handle.

Parameters:
[in] hItem hItem line handle in the grid. The line can be visible or invisible.
Returns:
Pointer to the data object if it is found. Otherwise - 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

const Common::CDataObject * GetDataObject ( HITEM  hItem  )  const

Gets the data object corresponding to a given handle. Const version.

Parameters:
[in] hItem hItem line handle in the grid. The line can be visible or invisible.
Returns:
Pointer to the data object if it has been found. Otherwise - 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

Common::CDataObject * GetDataObject ( int  nRow,
ContextType  contextType = ScrollableContext 
)

Gets the data object corresponding to the line located in a given grid context and at a given position.

Parameters:
[in] nRow index in grid context.
[in] contextType grid context.
Returns:
const pointer to the data object if success. Otherwise 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

const Common::CDataObject * GetDataObject ( int  nRow,
ContextType  contextType = ScrollableContext 
) const

Gets the data object corresponding to the line in a given grid context at a given position. Const version.

Parameters:
[in] nRow index in grid context.
[in] contextType grid context.
Returns:
const pointer to the data object if success. Otherwise 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more about location C++ objects in the grid

int GetFirstVisibleRow (  )  const

Gets the first visible line in scrollable context.

Returns:
Index of the first visible line in scrollable context. If there are no lines, -1 is returned.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

int GetLastVisibleRow ( ContextType  contextType = ScrollableContext  )  const

Gets the last visible line in a given context.

The index of the last line depends on grid size, number of inserted data objects and on position of vertical scrollbar in scrollable context.

Parameters:
[in] contextType type of context where the search is conducted.
Returns:
Index of the last visible line in a given context. If there are no lines, -1 is returned.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

void SetFirstVisibleRow ( int  nRow  ) 

Sets a given index as the first visible index in scrollable context.

Parameters:
[in] nRow Index of row in the scroolable area that is to be displaced.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

void SetFirstVisibleItem ( HITEM  hItem  ) 

Sets a given handle as the first visible handle in scrollable context.

If the given handle is located in fixed context or is invisible (filtered or hidden by the parents) then no action is taken.

Parameters:
[in] hItem handle of a visible line in scrollable context.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

void SetFirstVisibleItem ( const Common::CDataObject pDO  ) 

Searches for the first encountered line in scrollable context for a given data object.

If it is found and visible (not filtered or hidden by the parents), the line corresponding to this handle is set as the first line in scrollable context of the grid.

Parameters:
[in] pDO Pointer to the data object.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

void EnsureVisible ( int  nRow  ) 

Makes a given line visible in scrollable context.

Parameters:
[in] nRow Index of the row in the scroollable area.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
See also:
IsInVisibleRect()
Example
See more on computing visible and virtual bounds of rows/cells

void EnsureVisible ( HITEM  hItem  ) 

Makes a given handle visible in scrollable context.

The operation is not possible for filtered items. For hierarchical items, the grid expands all parents to show the specified handle.

Parameters:
[in] hItem Handle that is to be visible
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

void EnsureVisible ( const Common::CDataObject pDO  ) 

Makes the handle corresponding to the data object visible in scrollable context.

The operation is not possible if the specified handle is filtered. For hierarchical items the grid expands all parents to show the handle corresponding to the data object.

Parameters:
[in] pDO Pointer to the data object.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

bool IsVisible ( HITEM  hItem  )  const

Checks whether a given handle is visible in the grid.

The given handle and the data object corresponding to it are visible if they are not filtered in IGridFilter object, i.e. if () operator returns false for this pair. The second condition is that none of the direct or indirect parents of the given handle should be collapsed.

Parameters:
[in] hItem line handle in the grid.
Returns:
true if line handle is visible. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

bool IsVisible ( const Common::CDataObject pDO  )  const

Checks whether the first handle corresponding to the data object is visible in the grid.

The given handle and the data object corresponding to it are visible if they are not filtered in the IGridFilter object, i.e. () operator returns false for this pair. The second condition is that none of direct or indirect parents of given handle should be collapsed.

Parameters:
[in] pDO Pointer to the data object.
Returns:
true if the first line handle corresponding to the data object is visible. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

bool IsInVisibleRect ( HITEM  hItem  ) 

Checks whether at least a part of a given line is visible in the client area of the grid.

Parameters:
[in] hItem Handle that is to be checked
Returns:
True if at least a part of the given line is visible. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

bool IsInVisibleRect ( const Common::CDataObject pDO  ) 

Checks whether at least a part of the given line corresponding to the data object is visible in the client area of the grid.

Parameters:
[in] pDO Pointer to the data object.
Returns:
True if at least a part of given line is visible. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

bool IsInVisibleRect ( int  nRow,
ContextType  contextType 
)

Checks whether at least a part of the line in a given grid context and at a given position is visible in client area of the grid.

Parameters:
[in] nRow index in grid context.
[in] contextType grid context.
Returns:
True if at least a part of the given line is visible. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

CRect GetContextVisibleRect ( ContextType  contextType  )  const

Gets the visible rectangle occupied by a given grid context with consideration of client area dimensions and scrolling.

Parameters:
[in] contextType type of grid context. Available values: FixedContext and ScrollableContext.
Returns:
Visible rectangle occupied by a given grid context.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

CRect GetContextVirtualRect ( ContextType  contextType  )  const

Gets the virtual rectangle occupied by a given grid context without consideration of client area dimensions and scrolling.

Parameters:
[in] contextType type of grid context. Available values: FixedContext and ScrollableContext.
Returns:
Visible rectangle occupied by a given grid context.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

CRect GetLineVisibleRect ( HITEM  hItem  )  const

Gets the visible rectangle occupied by the grid line corresponding to a given handle.

Parameters:
[in] hItem handle of a visible line in any context.
Returns:
Visible area occupied by the grid line.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

CRect GetLineVisibleRect ( const Common::CDataObject pDO  )  const

Gets the visible rectangle occupied by grid line corresponding to the first found handle for a given data object.

Parameters:
[in] pDO Pointer to the data object.
Returns:
Visible area occupied by the grid line.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

CRect GetLineVirtualRect ( HITEM  hItem  )  const

Calculates the virtual rectangle occupied by the line corresponding to a given handle.

The rectangle is calculated without consideration of visible grid area dimensions and scrolling.

Parameters:
[in] hItem handle of a visible line in any context.
Returns:
Visible area occupied by the grid line.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

CRect GetLineVirtualRect ( const Common::CDataObject pDO  )  const

Gets the virtual rectangle occupied by the grid line corresponding to the first found handle for a given data object.

Parameters:
[in] pDO Pointer to the data object.
Returns:
Visible area occupied by the grid line.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

CRect GetCellVisibleRect ( HITEM  hItem,
Common::FID  fid 
) const

Gets a visible rectangle of the grid cell specified by a given handle and column identifier (identifier of a data object field).

The visible rectangle is bound by the visible area of grid context.

Parameters:
[in] hItem handle of a visible line in any context.
[in] fid field's identifier.
Returns:
Visible area occupied by the grid cell.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

CRect GetCellVisibleRect ( const Common::CDataObject pDO,
Common::FID  fid 
) const

Gets a visible rectangle of the grid cell specified by the first found handle for a given data object and column identifier (identifier of a data object field).

The visible rectangle is bound by the visible area of grid context.

Parameters:
[in] pDO Pointer to the data object.
[in] fid field identifier.
Returns:
Visible area occupied by grid cell.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

CRect GetCellVirtualRect ( HITEM  hItem,
Common::FID  fid 
) const

Gets a virtual rectangle of the grid cell specified by a given handle and column identifier (identifier of a data object field).

The visible rectangle is bound by the visible area of grid context.

Parameters:
[in] hItem handle of a visible line in any context.
[in] fid field's identifier.
Returns:
Virtual area occupied by the grid cell.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

CRect GetCellVirtualRect ( const Common::CDataObject pDO,
Common::FID  fid 
) const

Gets virtual size of grid cell specified by the first found handle for a given data object and column identifier (identifier of the data object field) without consideration of visible grid area dimensions.

The visible rectangle is bound by the visible area of grid context.

Parameters:
[in] pDO Pointer to the data object.
[in] fid field's identifier.
Returns:
Virtual area occupied by the grid cell.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

int GetLinesPerPage ( bool  forward = true  )  const

Calculates the number of fully visible lines per page in scrollable context of the grid.

If indices are in ascending order (forward is equal to 'true'), the sum of derived value and the first visible index can't exceed index of the last line in scrollable context. If indices are in descending order, the difference between the first visible index and derived value can't be less than 0.

Parameters:
[in] forward If the value is 'true', calculation is performed starting from the first visible index with index increase. Otherwise the number of lines per page is calculated in descending order starting from the first visible line.
Returns:
The number of fully visible lines per page.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

int GetItemHeight ( HITEM  hItem  )  const

Gets height of the line corresponding to a given handle.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible.
Returns:
line height
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
See more on computing visible and virtual bounds of rows/cells

void SetItemHeight ( HITEM  hItem,
int  height 
)

Gets a height of the line corresponding to a given handle.

Parameters:
[in] hItem line handle in the grid.
[in] height a new height of the line.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowSelection ( bool  bEnable  ) 

Enables selection in the grid.

Parameters:
[in] bEnable Sets selection in the grid. True - selection is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool CanSelect (  )  const

Defines whether line selection in the grid is allowed.

Returns:
True if selection is allowed. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowMultiSelection ( bool  bEnable  ) 

Enables selection of multiple lines in the grid.

Parameters:
[in] bEnable If true, the grid enables selection of multiple lines at once. Otherwise only one line can be selected.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool CanMultiSelect (  )  const

Defines whether multi-selection of lines is allowed in the grid.

Returns:
True if multi-selection is allowed. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowSelectContext ( ContextType  contextType = AllContexts  ) 

Sets grid context where selection is allowed.

The architecture of the grid sets two contexts: scrollable and fixed. In each of these contexts it is possible to allow a possibility of lines selection.

Parameters:
[in] contextType grid context. Available values: UndefinedContext, FixedContext, ScrollableContext, AllContexts.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread synchronization is performed via SendMessage mechanism.

bool CanSelectContext ( ContextType  contextType  )  const

Defines whether line selection is allowed in a given grid context.

Parameters:
[in] contextType grid context. Available values: FixedContext, ScrollableContext.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

int GetSelectedCount (  )  const

Gets the total number of selected lines in the grid.

Returns:
Number of selected lines in the grid.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool Select ( int  nRow,
ContextType  contextType,
bool  bSelect 
)

Changes selection of the line in a given position within a given context.

Parameters:
[in] nRow index of the line in grid context.
[in] contextType grid context.
[in] bSelect points whether a given line should be selected or selection should be cancelled. If true, the grid tries to perform selection.
Returns:
True if the value has been successfully set. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool Select ( HITEM  hItem,
bool  bSelect 
)

Enables selection of a line by its handle.

Selection can be performed for both visible and invisible (filtered or hidden by parents) grid lines.

Parameters:
[in] hItem line handle in the grid.
[in] bSelect points whether a given line should be selected or whether selection should be cancelled. If true, the grid tries to perform selection.
Returns:
True if the value has been successfully set. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool Select ( const Common::CDataObject pDO,
bool  bSelect 
)

Changes selection for all the handles associated with a given data object in the grid.

Parameters:
[in] pDO Pointer to the data object.
[in] bSelect points whether a given line should be selected or whether selection should be cancelled. If true, the grid tries to do selection.
Returns:
True if the value has been successfully set. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

Selection GetSelection ( ContextType  contextType  )  const

Gets a list of selected handles.

Parameters:
[in] contextType The context where the search is conducted. Available values: FixedContext, ScrollableContext, AllContexts.
Returns:
Returned container contains a list of selected grid lines.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool IsSelected ( int  nRow,
ContextType  contextType 
) const

Tests whether the line located in a given position in a given context is selected.

Parameters:
[in] nRow index of the line in grid context.
[in] contextType grid context.
Returns:
True the line if selected. If the line is not selected or out of range - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool IsSelected ( HITEM  hItem  )  const

Tests whether the line with a specified handle is selected.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible.
Returns:
True the line if selected. If the handle is not selected or not found - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool IsSelected ( const Common::CDataObject pDO  )  const

Tests whether the first line handle corresponding to the data object is selected.

Parameters:
[in] pDO Pointer to the data object.
Returns:
True the line if selected. If the handle is not selected or not found - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void SelectAll (  ) 

Selects all visible lines in the grid if selection is allowed.

If multi-selection is disabled, then only one line is selected.

thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void ClearSelection (  ) 

Selects all lines in the grid.

thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowMouseTrackSelection ( bool  bEnable  ) 

Enables selection with a mouse.

It can be used to select many grid lines at once. If the lines are outside the visible area, automatic data scrolling with selection is possible. Scrolling speed changes as the distance between the cursor and the grid increases.

Parameters:
[in] bEnable True if enable. Otherwise false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool CanMouseTrackSelection (  )  const

Tests whether mouse selection is allowed.

Returns:
True - selection is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowFocusContext ( ContextType  contextType = AllContexts  ) 

Enables focusing lines in a given context.

Lines focusing enables navigation over the grid. Specifically, at KeyUp, KeyDown ... keystroke the grid focuses the required line and ensures its visibility. The grid can have only one focused line.

Parameters:
[in] contextType grid context. Available values: UndefinedContext, FixedContext, ScrollableContext, AllContexts.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool CanFocusContext ( ContextType  contextType  )  const

Checks if line focusing is allowed in a given grid context.

Parameters:
[in] contextType grid context. Available values: FixedContext, ScrollableContext
Returns:
True - focus is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool SetFocusedRow ( int  nRow,
ContextType  contextType 
)

Sets a new focused line.

Parameters:
[in] nRow index of a line in grid context. -1 means that the focus is dropped.
[in] contextType grid context.
Returns:
True if success. Otherwise false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

int GetFocusedRow (  )  const

Gets an index of a focused line in focused grid context.

Returns:
Index of the focused line. If there is a focus, -1 is returned.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

ContextType GetFocusedContext (  )  const

Gets a focused grid context.

Returns:
One of grid contexts. If there is a focus, UndefinedContext is returned.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void UpdateRow ( int  nRow,
ContextType  contextType,
Common::FID  fid 
)

Informs the grid about changing of a data object.

When this function is called, the grid checks line location. If sorting is used, the grid moves it to the appropriate position. Moreover, the grid checks whether a handle and a data object meet the filtration criteria set in IGridFilter interface. If required, the grid makes the line visible or hides it. The grid updates the last update timestamp for the handle corresponding to the data object that is used for automatic cell highlighting and finally redraws the cell. The same actions are perofrmed when a notification from Common::CDataObject::ISink interface is received.

Parameters:
[in] nRow index of the line in grid context.
[in] contextType grid context.
[in] fid field's identifier.
thread-safety:
The function is thread-safe. It uses asynchronous synchronization using PostMessage mechanism. During updating, sorting and other operations the calling thread is not blocked. Such approach excludes the risk of DeadLock between the calling thread and GUI thread. In CPreferences::MemoryBuffer mode the unformatted value of the data object is first acquired and then transformed to a formatted string in the calling thread. Later on, the GUI thread doesn't access the data object during sorting and drawing. All necessary data is received from cache associated with the data object.

void UpdateItem ( HITEM  hItem,
Common::FID  fid 
)

Informs the grid that a given handle has been updated.

Filtration check, moving in the grid for sorting and text updating are performed only for a single line corresponding to the given handle. It is recommended to use notification of the grid from Common::CDataObject::ISink interface of the data object.

Parameters:
[in] hItem line handle in the grid.
[in] fid field's identifier.
thread-safety:
The function is thread-safe. It uses asynchronous synchronization using PostMessage mechanism. During updating, sorting and other operations the calling thread is not blocked. Such approach excludes the risk of DeadLock between the calling thread and GUI thread. In CPreferences::MemoryBuffer mode the unformatted value of the data object is first acquired and then transformed to a formatted string in the calling thread. Later on, the GUI thread doesn't access the data object during sorting and drawing. All necessary data is received from cache associated with the data object.

void UpdateDataObject ( const Common::CDataObject pDO,
Common::FID  fid 
)

Informs the grid that a data object has been updated.

The changes take place in all handles associated with a given data object. At the same time updates take place only in one grid. If one data object is inserted into several grids, the updates are not applied to other grids. That's why instead of direct call of UpdateRow(), UpdateItem() and UpdateDataObject() functions, it is recommended to send notification through Common::CDataObject::ISink interface. Its thread-safe asynchronous implementation prevents the risk of dead-lock between threads and automatically synchronizes object presentation in all grids.

Parameters:
[in] pDO Pointer to the data object.
[in] fid field's identifier.
thread-safety:
The function is thread-safe. It uses asynchronous synchronization using PostMessage mechanism. During updating, sorting and other operations the calling thread is not blocked. Such approach excludes the risk of DeadLock between the calling thread and GUI thread. In CPreferences::MemoryBuffer mode the unformatted value of the data object is first acquired and then transformed to a formatted string in the calling thread. Later on, the GUI thread doesn't access the data object during sorting and drawing. All necessary data is received from cache associated with the data object.

int GetTimeElapsedSinceLastUpdate ( int  nRow,
ContextType  contextType,
Common::FID  fid 
) const

Returns (in milliseconds) the time passed from the moment of the last update of a grid cell.

The time period is counted from the moment of UpdateRow(), UpdateItem() and UpdateDataObject() functions call or from the moment when the notification from Common::CDataObject::ISink interface are received.

Parameters:
[in] nRow index of the line in grid context.
[in] contextType grid context.
[in] fid field's identifier.
Returns:
Time in milliseconds elapsed since the last update. If the line is not found or has not been updated -1 is returned.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

int GetTimeElapsedSinceLastUpdate ( HITEM  hItem,
Common::FID  fid 
) const

Returns time (in milliseconds) passed from the moment of last update of a grid cell.

The time period is counted from the moment of UpdateRow(), UpdateItem() and UpdateDataObject() functions call or from the moment when notification from Common::CDataObject::ISink interface is received.

Parameters:
[in] hItem line handle in the grid. The line can be visible or invisible.
[in] fid field's identifier.
Returns:
Time in milliseconds elapsed since the last update. If the line is not found or has not been updated -1 is returned.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void InvalidateRow ( int  nRow,
ContextType  contextType,
int  spanTime = 0 
)

Redraws a line in the grid.

The main difference from Update(...) functions is that the grid doesn't perform any manipulations with lines. spanTime parameter is an additional parameter of this function that indicates when line redrawing should be done. For example, this function can be used with line highlighting in the grid.

Parameters:
[in] nRow index of the line in grid context.
[in] contextType grid context.
[in] spanTime The time period in milliseconds after which line redrawing is requested. If this value is equal to 0 then the request is sent immediately.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void InvalidateRow ( HITEM  hItem,
int  spanTime = 0 
)

Redraws the line corresponding to a given handle (if it is visible) in the grid.

The main difference from Update(...) functions is that the grid doesn't performs any manipulations with lines. spanTime parameter is an additional parameter of this function that indicates when line redrawing should be done. For example, this function can be used with line highlighting in the grid.

Parameters:
[in] hItem line handle in the grid.
[in] spanTime The time period in milliseconds after which line redrawing is requested. If this value is equal to 0 then the request is sent immediately.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void InvalidateRow ( const Common::CDataObject pDO,
int  spanTime = 0 
)

Redraws all the visible lines corresponding to a given data object in the grid.

The main difference from Update(...) functions is that the grid doesn't perform any manipulations with lines. spanTime parameter is an additional parameter of this function that indicates when line redrawing should be done. For example, this function can be used with line highlighting in the grid.

Parameters:
[in] pDO Pointer to the data object.
[in] spanTime The time period in milliseconds after which line redrawing is requested. If this value is equal to 0 then the request is sent immediately.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void InvalidateCell ( int  nRow,
ContextType  contextType,
Common::FID  fid,
int  spanTime = 0 
)

Redraws the cell corresponding to a given line and column identifier in the grid.

Parameters:
[in] nRow index of the line in grid context.
[in] contextType grid context.
[in] fid field's identifier.
[in] spanTime The time period in milliseconds after which cell redrawing is requested. If this value is equal to 0, the request is sent immediately.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void InvalidateCell ( HITEM  hItem,
Common::FID  fid,
int  spanTime = 0 
)

Redraws the cell corresponding to a given handle (if it is visible) and column identifier in the grid.

Parameters:
[in] hItem line handle in the grid.
[in] fid field's identifier.
[in] spanTime The time period in milliseconds after which cell redrawing is requested. If this value is equal to 0, the request is sent immediately.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void InvalidateCell ( const Common::CDataObject pDO,
Common::FID  fid,
int  spanTime = 0 
)

Redraws all visible cells corresponding to a given data object and column identifier in the grid.

Parameters:
[in] pDO Pointer to the data object.
[in] fid field's identifier.
[in] spanTime The time period in milliseconds after which cell redrawing is requested. If this value is equal to 0, the request is sent immediately.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowNotifications ( bool  bAllow  ) 

The grid enables delivery of notifications to its owner by sending WM_NOTIFY messages.

To improve grid productivity, this function enables blocking of notifications deliveries. (For example when a lot of elements are inserted into the grid.)

Parameters:
[in] bAllow Allows to send notifications. True - sending is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool IsNotificationsAllowed (  )  const

Returns the value indicating whether the grid is allowed to deliver notifications by sending WM_NOTIFY message to its owner.

Returns:
True - sending is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

CAppearance & GetAppearance (  ) 

Gets CAppearance type object that collects basic visual grid characteristics such as text, background, vertical and horizontal lines colors, etc.

When values in the return object are modified, CWnd::Invalidate() should be called to display changes on the screen.

Returns:
Grid's appearance.
thread-safety:
Function call is thread-safe. Synchronization method is SendMessage. However CAppearance object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from another thread, it is better to use SetAppearance() function.

const CAppearance & GetAppearance (  )  const

Gets CAppearance type object that collects basic visual grid characteristics such as text, background, vertical and horizontal lines colors, etc. Const version.

When values in the return object are modified, CWnd::Invalidate() should be called to display the changes on screen.

Returns:
Grid's appearance.
thread-safety:
Function call is thread-safe. Synchronization method is SendMessage. However CAppearance object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from another thread, it is better to use SetAppearance() function.

void SetAppearance ( const CAppearance appearance  ) 

Sets a new grid appearance.

With its running completed the function automatically requests grid updating by calling CWind::Invalidate function.

thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

const CBackgroundImage & GetBackgroundImage (  )  const

Gets a background image of the grid.

It is possible to assign a picture with different transparency coefficients. Transparency rate is defined by mixing colors of picture with colors specified in CAppearance object returned by the GetAppearance() function.

Returns:
reference to the background image.
thread-safety:
The function is thread-safe. Synchronization method is SendMessage. However CBackgroundImage object is not thread-safe.
Example

void SetBackgroundImage ( const CBackgroundImage image  ) 

Sets a new background image for the grid.

Parameters:
[in] image A new background image
thread-safety:
The function is thread-safe. When it is called from a non-GUI thread, synchronization is performed via the SendMessage mechanism.
Example

void SetFont ( CFont *  font,
BOOL  bRedraw = TRUE 
)

Sets font attributes to be used for text within the grid. Internally, the grid clones the font, and when this function is called, you should destroy it.

Parameters:
[in] font A new font.
[in] bRedraw value indicating that the grid should be redrawn.
thread-safety:
The function is not thread-safe.
Example:
This example demonstrates how to increase or decrease font size in the grid
//File MyView.h

class CMyView : public CView
{
...
protected:
    ... 
    afx_msg void OnIncreaseFont();
    afx_msg void OnDecreaseFont();
    ...
    
    Dapfor::GUI::CGrid m_Grid;
};





//File MyView.cpp

BEGIN_MESSAGE_MAP(CMyView, CView)
    ...
    ON_COMMAND(ID_INCREASE_FONT, OnIncreaseFont)
    ON_COMMAND(ID_DECREASE_FONT, OnDecreaseFont)
END_MESSAGE_MAP()

...

void CMyView::OnIncreaseFont()
{
    //Retrieves font from the grid
    CFont* pfn = m_Grid.GetFont();

    //If the grid doesn't have a font, we take the default one
    if(pfn == 0) pfn = Dapfor::GUI::CPreferences::GetFont();
    
    //Default font can also be obtained with the following code:
    //pfn = CFont::FromHandle((HFONT)::GetStockObject(DEFAULT_GUI_FONT));
    
    if(pfn != 0)
    {
        //Get the LOGFONT data
        LOGFONT logFont;
        pfn->GetLogFont(&logFont);
        
        //Increment font size
        if(CDC* pDC = m_Grid.GetDC())
        {
            int fontSize = -MulDiv(logFont.lfHeight, 72, GetDeviceCaps(pDC->m_hDC, LOGPIXELSY));
            if(fontSize < 24)
            {
                logFont.lfHeight = -MulDiv(fontSize + 1, GetDeviceCaps(pDC->m_hDC, LOGPIXELSY), 72);
            }
            m_Grid.ReleaseDC(pDC);
        }
        
        //Create a temporary font
        CFont font;
        font.CreateFontIndirect(&logFont);
        
        //Set this font to the grid
        m_Grid.SetFont(&font);
        
        //Destroy the temporary font
        font.DeleteObject();
    }
}



void CMyView::OnDecreaseFont()
{
    //Retrieve a font from the grid
    CFont* pfn = m_Grid.GetFont();
    
    //If the grid doesn't have the font, we'll take a default one
    if(pfn == 0) pfn = Dapfor::GUI::CPreferences::GetFont();
    
    //Default font can be obtained also with the next code:
    //pfn = CFont::FromHandle((HFONT)::GetStockObject(DEFAULT_GUI_FONT));
    
    if(pfn != 0)
    {
        //Get the LOGFONT data
        LOGFONT logFont;
        pfn->GetLogFont(&logFont);
        
        //Decrease the font's size
        if(CDC* pDC = m_Grid.GetDC())
        {
            int fontSize = -MulDiv(logFont.lfHeight, 72, GetDeviceCaps(pDC->m_hDC, LOGPIXELSY));
            if(fontSize > 6)
            {
                logFont.lfHeight = -MulDiv(fontSize - 1, GetDeviceCaps(pDC->m_hDC, LOGPIXELSY), 72);
            }
            m_Grid.ReleaseDC(pDC);
        }
        
        //Create a temporary font
        CFont font;
        font.CreateFontIndirect(&logFont);
        
        //Set this font to the grid
        m_Grid.SetFont(&font);
        
        //Destroy the temporary font
        font.DeleteObject();
    }
}

CFont * GetFont (  )  const

Gets the current font used in the grid.

Returns:
Current used font.
thread-safety:
The function is not thread-safe.

CImageList * SetImageList ( CImageList *  imageList,
bool  stretch = false 
)

Sets new ImageList to display icons within grid cells.

If icon size doesn't fit to cell height, the icon can be stretched for proper placement. Data drawing given ImageList and icon index are sent to ICustomDraw interface, where the icon and the whole ImageList can be changed.

Parameters:
[in] imageList A new image list.
[in] stretch Indicates whether icons should be stretched to cell height.
Returns:
Previous ImageList value.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

CImageList * GetImageList (  )  const

Gets the current ImageList value used by the grid.

Returns:
Current ImageList value.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. However the CImageList object is not thread-safe.

void AllowStretchImageInCell ( bool  stretch  ) 

Sets the flag that enables icon stretching in grid cells.

Parameters:
[in] stretch If true - enables stretching of icons in grid cells.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool CanStretchImageInCell (  )  const

Tests whether the flag enabling icons stretching in grid cells is set.

Returns:
True if the grid can stretch icons. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowDrawContextSeparator ( bool  bDraw  ) 

Allows drawing of a separator between two grid contexts.

Parameters:
[in] bDraw True if the grid can draw a separator between two grid contexts
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool CanDrawContextSeparator (  )  const

Tests whether drawing of a separator between two grid contexts is allowed.

Returns:
True if drawing of a separator between two grid contexts is allowed. Otherwise false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void SetContextSeparatorHeight ( int  nHeight  ) 

Sets height of separator between two grid contexts.

Parameters:
[in] nHeight height of a separator between two contexts in pixels.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

int GetContextSeparatorHeight (  )  const

Gets height of separator between two grid contexts.

Returns:
Height of a separator between two contexts in pixels.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowHighlight ( bool  bAllow  ) 

Enables or disables grid cells highlighting.

Highlighting is performed during the time period specified in CHighlightSettings object and returned by GetHighlightSettings() function. Highlighting starts from the moment of receiving a notification from Common::CDataObject::ISink interface or from the moment of UpdateRow(), UpdateItem() or UpdateDataObject() functions call. The grid provides several possible highlighting types from simple color inversion and to alpha blending on the background using a fading effect. All information on highlighting is sent to ICustomDraw interface where it can be freely redefined, allowed or forbidden for a single cell.

Parameters:
[in] bAllow Allows grid cells highlighting. True - highlighting is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
//Turn on cell highlighting
m_Grid.AllowHighlight(true);

//Select highlighting with fading effect
m_Grid.GetHighlightSettings().SetMode(Dapfor::GUI::FadingBackColor);
m_Grid.GetHighlightSettings().SetBackColor(RGB(230, 10, 14));

bool CanHighlight (  )  const

Returns the value indicating if the grid can perform cells highlighting or not.

Returns:
True - highlighting is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
//Turn on cell highlighting
m_Grid.AllowHighlight(true);

//Select highlighting with fading effect
m_Grid.GetHighlightSettings().SetMode(Dapfor::GUI::FadingBackColor);
m_Grid.GetHighlightSettings().SetBackColor(RGB(230, 10, 14));

const CHighlightSettings & GetHighlightSettings (  )  const

Gets highlighting parameters collected in CHighlightSettings type object. Const version.

Derived parameters include colors of the front and the rear background colors, highlighting of a time period, mode...

Returns:
Current highlighting parameters.
thread-safety:
Function call is thread-safe. Synchronization method is SendMessage. However CHighlightSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other threads, it is better to use SetHighlightSettings() function.
Example
//Turn on cell highlighting
m_Grid.AllowHighlight(true);

//Select highlighting with fading effect
m_Grid.GetHighlightSettings().SetMode(Dapfor::GUI::FadingBackColor);
m_Grid.GetHighlightSettings().SetBackColor(RGB(230, 10, 14));

CHighlightSettings & GetHighlightSettings (  ) 

Gets highlighting parameters collected in CHighlightSettings type object.

Derived parameters include front and rear background colors, time period highlighting, mode...

Returns:
Current highlighting parameters.
thread-safety:
Function call is thread-safe. Synchronization method is SendMessage. However CHighlightSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other threads, it is better to use SetHighlightSettings() function.
Example
//Turn on cell highlighting
m_Grid.AllowHighlight(true);

//Select highlighting with fading effect
m_Grid.GetHighlightSettings().SetMode(Dapfor::GUI::FadingBackColor);
m_Grid.GetHighlightSettings().SetBackColor(RGB(230, 10, 14));

void SetHighlightSettings ( const CHighlightSettings settings  ) 

Sets new parameters of highlighting in the grid.

Parameters:
[in] settings New highlighting parameters.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
Example
//Turn on cell highlighting
m_Grid.AllowHighlight(true);

//Select highlighting with fading effect
m_Grid.GetHighlightSettings().SetMode(Dapfor::GUI::FadingBackColor);
m_Grid.GetHighlightSettings().SetBackColor(RGB(230, 10, 14));

ICustomDraw * SetCustomDraw ( ICustomDraw customDraw  ) 

Sets a new interface to specify grid element drawing.

At grid implementation all cells drawing, highlighting, navigation and other similar operation were placed in external modules that totally define functionalities. During drawing all necessary parameters are gathered at one place and passed to ICustomDraw interface. If the interface is not assigned, the default implementation obtained by calling Creferences::GetDefaultCustomDraw() is applied. The purpose of the interface is to transmit parameters to the appropriate graphical format that directly performs drawing. There are two types of formats: line drawing format and cell drawing format. Default implementation of the line drawing format includes calculation of cell sizes and transmission of parameters to cell drawing format via ICustomDraw. Thus ICustomDraw is the central point, through which all information related to grid elements drawing is passed, and thus it is the most convenient place for its redefining.

Parameters:
[in] customDraw New interface to specify grid elements drawing.
Returns:
Previous drawing interface.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. It is important that all functions of the interface are called only in GUI thread.
See also:
Read Drawing workflow and Custom drawing for more information about custom drawing.

ICustomDraw * GetCustomDraw (  )  const

Gets current ICustomDraw interface.

Returns:
Current drawing interface if it exists. Otherwise 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
See also:
Read Drawing workflow and Custom drawing for more information about custom drawing.

void SetPaintFilter ( UINT  paintFilter = defaultPaintFilter  ) 

Sets a new graphical filter.

The filter is a list of PaintFilter type values. It enables display of appropriate grid elements. The filter that is set at the time of drawing is transmitted to ICustomDraw, where it can be totally redefined. This enables highlight blocking or selection drawing for an individual grid cell.

Parameters:
[in] paintFilter A new paint filter. Set of PaintFilter enumeration.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
See also:
Read Drawing workflow and Custom drawing to get more information about custom drawing.
Example
//This filter is defined in the Dapfor/GUI/Types.h file
enum PaintFilter    
{
    drawNothing                     = 0x00,     //Draws nothing
    drawText                        = 0x01,     //Draws text in the grid
    drawImage                       = 0x02,     //Draws image in a cell
    drawHeaderImage                 = 0x04,     //Draws image in a column
    drawBackground                  = 0x08,     //Draws grid background
    drawSelection                   = 0x10,     //Blends selection with foreground and background colors for selected lines.
    drawSelectionFrame              = 0x20,     //Draws a frame around selected lines
    drawColumnSort                  = 0x40,     //Blends column sorting with fore and back colors.
    drawMouseTrackSelection         = 0x80,     //Draws an area, selected by mouse with pressed left button
    drawFocusedRow                  = 0x100,    //Blends focus with foreground and background colors for selected lines.
    drawFocusedRowFrame             = 0x200,    //Draws a frame around the focused line
    drawHighlight                   = 0x400,    //Draws highlighting
    drawDropPosition                = 0x800,    //Draws indicators helping to drop clipboard content
    drawDropParentPosition          = 0x1000,   //Draws an indicator helping to select a hierarchical level during drop operation
    drawHierarchy                   = 0x2000,   //Draws a hierarchy. Each child is shifted relatively to its parent
    drawCollapseExpandIcon          = 0x4000,   //Draws collapse/expand icons
    drawHierarchicalLines           = 0x8000,   //Draws hierarchical lines
    drawHorizontalLines             = 0x10000,  //Draws horizontal lines between lines
    drawVerticalLines               = 0x20000,  //Draws vertical lines between columns
    drawEmbeddedControlBackground   = 0x40000,  //Forces an embedded MFC control to blend its background color with cell background color


    drawEverything  = drawText | drawImage | drawHeaderImage| drawBackground |  //Text, Image & background
    drawSelection | drawSelectionFrame |                                        //Selection
    drawMouseTrackSelection |                                                   //Mouse track selection
    drawFocusedRow | drawFocusedRowFrame |                                      //Focus
    drawColumnSort |                                                            //Column sorting
    drawHighlight |                                                             //Highlighting
    drawDropPosition | drawDropParentPosition |                                 //Drag & drop
    drawHierarchy |drawCollapseExpandIcon | drawHierarchicalLines |             //Hierarchy
    drawHorizontalLines | drawVerticalLines |                                   //Vertical & horizontal lines
    drawEmbeddedControlBackground |
    drawHorizontalLines | drawVerticalLines,                                    //Vertical & horizontal lines


    defaultPaintFilter = drawEverything,
};

//Using example:

//This code prevent from drawing the selection.
m_Grid.SetPaintFilter(m_Grid.GetPaintFilter() & ~(Dapfor::GUI::drawSelection|Dapfor::GUI::drawSelectionFrame));

//And this code prevent from drawing the focus.
m_Grid.SetPaintFilter(m_Grid.GetPaintFilter() & ~(Dapfor::GUI::drawFocusedRow|Dapfor::GUI::drawFocusedRowFrame));

UINT GetPaintFilter (  )  const

Gets current value of the graphical filter.

Returns:
Current filter. Set of PaintFilter enumeration.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.
See also:
Read Drawing workflow and Custom drawing to get more information about custom drawing.
Example
//This filter is defined in the Dapfor/GUI/Types.h file
enum PaintFilter    
{
    drawNothing                     = 0x00,     //Draws nothing
    drawText                        = 0x01,     //Draws text in the grid
    drawImage                       = 0x02,     //Draws image in a cell
    drawHeaderImage                 = 0x04,     //Draws image in a column
    drawBackground                  = 0x08,     //Draws grid background
    drawSelection                   = 0x10,     //Blends selection with foreground and background colors for selected lines.
    drawSelectionFrame              = 0x20,     //Draws a frame around selected lines
    drawColumnSort                  = 0x40,     //Blends column sorting with fore and back colors.
    drawMouseTrackSelection         = 0x80,     //Draws an area, selected by mouse with pressed left button
    drawFocusedRow                  = 0x100,    //Blends focus with foreground and background colors for selected lines.
    drawFocusedRowFrame             = 0x200,    //Draws a frame around the focused line
    drawHighlight                   = 0x400,    //Draws highlighting
    drawDropPosition                = 0x800,    //Draws indicators helping to drop clipboard content
    drawDropParentPosition          = 0x1000,   //Draws an indicator helping to select a hierarchical level during drop operation
    drawHierarchy                   = 0x2000,   //Draws a hierarchy. Each child is shifted relatively to its parent
    drawCollapseExpandIcon          = 0x4000,   //Draws collapse/expand icons
    drawHierarchicalLines           = 0x8000,   //Draws hierarchical lines
    drawHorizontalLines             = 0x10000,  //Draws horizontal lines between lines
    drawVerticalLines               = 0x20000,  //Draws vertical lines between columns
    drawEmbeddedControlBackground   = 0x40000,  //Forces an embedded MFC control to blend its background color with cell background color


    drawEverything  = drawText | drawImage | drawHeaderImage| drawBackground |  //Text, Image & background
    drawSelection | drawSelectionFrame |                                        //Selection
    drawMouseTrackSelection |                                                   //Mouse track selection
    drawFocusedRow | drawFocusedRowFrame |                                      //Focus
    drawColumnSort |                                                            //Column sorting
    drawHighlight |                                                             //Highlighting
    drawDropPosition | drawDropParentPosition |                                 //Drag & drop
    drawHierarchy |drawCollapseExpandIcon | drawHierarchicalLines |             //Hierarchy
    drawHorizontalLines | drawVerticalLines |                                   //Vertical & horizontal lines
    drawEmbeddedControlBackground |
    drawHorizontalLines | drawVerticalLines,                                    //Vertical & horizontal lines


    defaultPaintFilter = drawEverything,
};

//Using example:

//This code prevent from drawing the selection.
m_Grid.SetPaintFilter(m_Grid.GetPaintFilter() & ~(Dapfor::GUI::drawSelection|Dapfor::GUI::drawSelectionFrame));

//And this code prevent from drawing the focus.
m_Grid.SetPaintFilter(m_Grid.GetPaintFilter() & ~(Dapfor::GUI::drawFocusedRow|Dapfor::GUI::drawFocusedRowFrame));

void SetFlickerFreeDrawing ( bool  enable  ) 

Enables use of double buffering mechanism to exclude the flicker effect at the time of elements drawing.

However, when this mode is set, it can impact grid productivity. Usually it is not necessary to set this mode because an updated text almost never flickers on the screen.

Parameters:
[in] enable Enables double buffering mechanism. True - double buffering is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool GetFlickerFreeDrawing (  )  const

Gets the value indicating whether double buffering mode is enabled.

Returns:
True - double buffering is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

int GetOptimalRowHeight ( ContextType  contextType  )  const

Gets optimal value of line height in a given grid context.

The height is calculated in ICustomDraw interface based on font parameters and can be easily redefined.

Parameters:
[in] contextType grid context.
Returns:
Optimal value of line height in a given grid context.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void SetOptimalRowHeight ( ContextType  contextType,
int  height 
)

Sets default row height.

Parameters:
[in] contextType grid context.
[in] height default row height.

int GetOptimalCellWidth ( int  nRow,
ContextType  contextType,
Common::FID  fid 
) const

Gets optimal width value for a given grid cell.

Parameters for value calculation are passed to graphical grid cell drawing format via ICustomDraw interface. Line position in the hierarchy and icons, area for unrolling and rolling up children and current value of graphical filter presence are considered in calculation. ICustomDraw interface can impact calculation of derived value. The calculated value can be used for optimization of column size in the grid.

Parameters:
[in] nRow index of a line in grid context.
[in] contextType grid context. Available values: FixedContext, ScrollableContext.
[in] fid field's identifier.
Returns:
Optimal value of a given grid cell width.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

int GetOptimalColumnWidth ( ContextType  contextType,
Common::FID  fid 
) const

Calculates the optimal grid column size based on the optimal size for visible grid cells by GetOptimalCellWidth() function call.

Parameters:
[in] contextType grid context. Available values: FixedContext, ScrollableContext, AllContexts.
[in] fid field's identifier.
Returns:
Optimal grid column size.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

CHeader * SetHeader ( CHeader newHeader  ) 

Sets a new header.

If sorting is set in a new header, all grid lines are automatically sorted according to sorting rules. Header replacement makes management of data objects presentation in the grid rather easy and effective. Different headers can display different data object fields or the same fields in different formats.

Parameters:
[in] newHeader A new header.
Returns:
Previous header.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

CHeader * GetHeader (  ) 

Gets the current header used by the grid.

Returns:
Current header used by the grid.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

const CHeader * GetHeader (  )  const

Gets the current header used by the grid. Const version.

Returns:
Current header used by the grid.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void ShowHeader (  ) 

Makes the header visible.

thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void HideHeader (  ) 

Makes the header invisible.

thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool IsHeaderVisible (  )  const

Returns the value indicating whether the header is visible.

Returns:
true if the header is visible. Otherwise false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void ShowHeaderDialog (  )  [virtual]

Displays the dialog for configuring header columns.

thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

const CColumn * GetColumn ( CPoint  pt  )  const

Searches a column in the grid according to the coordinates counted in the client area of the grid.

Parameters:
[in] pt Location in the client area of the grid.
Returns:
CColumn type object if the column is found. Otherwise 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

const CColumn * GetNavigationColumn (  )  const

Gets a navigation column.

The grid enables quick search of lines by the first letters typed by user. When the letters are typed, they are compared with line values in a navigation column, and if a match is found, the grid scrolls to the first found match. The function gets the navigation column for quick line search.

Returns:
CColumn type object if the column is found. Otherwise 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

const CColumn * GetHierarchicalColumn (  )  const

Gets the column that manages grid hierarchy.

In this column the icons for unrolling lines and displaying child items are displayed. Usually this column is the first visible column of a header.

Returns:
CColumn type object if the column is found. Otherwise 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AdjustColumnByFid ( Common::FID  fid  ) 

Performs column width optimization for visible grid lines.

Column width is adjusted so that grid cells in a given column don't contain partially hidden data. Data object field identifier is used for column identification.

Parameters:
[in] fid field's identifier.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread synchronization is performed via SendMessage mechanism.

void AdjustColumnByIndex ( int  index  ) 

Performs column width optimization by index.

Column width is adjusted so that grid cells in a given column don't contain partially hidden data.

Parameters:
[in] index Zero-based column index.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AdjustAllColumns (  ) 

Performs all grid columns width optimization. The columns width is adjusted in such a way that grid cells in a given column haven't got partially hidden data.

thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

int GetOptimalHeaderHeight (  )  const

Gets optimal header height.

Returns:
Optimal header height.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void EnsureColumnVisible ( Common::FID  fid  ) 

The function makes a column fully visible in the grid.

If a column is invisible or partially visible, the grid performs horizontal scrolling to make given column wholly visible.

Parameters:
[in] fid field's identifier.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void EnableTooltip ( bool  bEnable = true  ) 

Allows to display tooltips.

Parameters:
[in] bEnable True - tooltips are allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool IsTooltipEnabled (  )  const

Returns value indicating whether tooltips are enabled.

Returns:
True - tooltips are enabled, false - disabled.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

const ITooltipCtrl * GetTooltipCtrl (  ) 

Gets current ITooltipCtrl used by the grid.

This interface serves for managing a tooltip window.

Returns:
Current ITooltipCtrl used by the grid if it exists. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

ITooltipCtrl * SetTooltipCtrl ( ITooltipCtrl control  ) 

Sets new ITooltipCtrl interface to control the tooltip window.

GUI library provides two implementation of the tooltip in CTooltipCtrl and CHtmlTooltipCtrl classes. When a new tooltip is set, the function returns the previous control.

Parameters:
[in] control A new tooltip control
Returns:
Previous tooltip control
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

const ITooltip * GetTooltip (  )  const

Gets the interface controlling tooltip content.

To display the tooltip, it is not necessary to implement this interface because ITooltipCtrl provides default implementation of this interface. If it is needed to redefine output text, the programmer can use a custom version of this interface.

Returns:
Current implementation of the interface controlling a tooltip content if it exists. Otherwise - 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

ITooltip * SetTooltip ( ITooltip tooltip  ) 

Set a new interface for defining the tooltip content.

Parameters:
[in] tooltip New tooltip interface.
Returns:
The function returns previous ITooltip interface.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

const CTooltipSettings & GetTooltipSettings (  )  const

Gets tooltip settings collected in CTooltipSettings class object. Const version.

Returns:
Tooltip settings
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. However CTooltipSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other threads, it is better to use SetTooltipSettings() function.

CTooltipSettings & GetTooltipSettings (  ) 

Gets the tooltip settings collected in CTooltipSettings class object.

Returns:
Tooltip settings
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. However CTooltipSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other thread, it is better to use SetTooltipSettings() function.

void SetTooltipSettings ( const CTooltipSettings settings  ) 

Sets new tooltip settings.

Parameters:
[in] settings New tooltip settings
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void EnableInPlaceTooltip ( bool  bEnable = true  ) 

Enables display of tooltips over grid cells when cell size is not sufficient for displaying text.

If grid cell size is not sufficient for displaying text, the 'embedded' tooltip enables partial or complete display of hidden text in the window located exactly above the grid cell, while preserving size and style of text. This kind of tooltip is shown on the screen automatically for invisible or partially visible text.

Parameters:
[in] bEnable True - tooltips are allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool IsInPlaceTooltipEnabled (  )  const

Returns the value indicating whether the grid can show the tooltip above the grid cells when a cell size is not enough for displaying a text.

Returns:
True - tooltips are allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

CTooltipSettings & GetInPlaceTooltipSettings (  ) 

Gets tooltip settings specifying the way of displaying tooltips over grid cells when cell size is not sufficient for displaying text.

Returns:
Settings collected in CTooltipSettings class object.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. However CTooltipSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other threads, it is better to use SetInPlaceTooltipSettings() function.

void SetInPlaceTooltipSettings ( const CTooltipSettings settings  ) 

Specifies new settings that determine how should the grid display tooltips over grid cells when cell size is not sufficient for displaying text.

Parameters:
[in] settings Settings collected in CTooltipSettings class object.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

const ITooltipCtrl * GetInPlaceTooltipCtrl (  )  const

Gets the current tooltip control used by the grid when cell size is not sufficient for displaying text.

Returns:
Current ITooltipCtrl used by the grid if it exists. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

ITooltipCtrl * SetInPlaceTooltipCtrl ( ITooltipCtrl control  ) 

Sets new ITooltipCtrl interface to control the 'embedded' tooltip window.

CInPlaceTooltipCtrl is the default implementation used by the grid.

Parameters:
[in] control A new tooltip control.
Returns:
Previous tooltip control.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool Copy (  ) 

Copies selection to the clipboard.

The copying process can be totally redefined in ICopyPaste interface.

Returns:
true if the content has been successfully copied to the clipboard. Otherwise false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool Cut (  ) 

Cuts selection to the clipboard.

The cut process can be totally redefined in ICopyPaste interface.

Returns:
true if the content has been successfully copied to the clipboard. Otherwise false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool Paste (  ) 

Inserts elements into the grid to a location after the focused line .

If there is no focused line in the grid, the elements are pasted to the end of the grid. If the elements are put to the clipboard by Cut() command, they are transfered from the previous position to the new one. This statement is true only for grids running in one application. When data is transferred from grids running in different applications, de-serialization and creation of corresponding types objects are performed and reconstructed objects are pasted to the grid.

thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool Paste ( HITEM  hParent,
HITEM  hInsertAfter 
)

Pastes data from the clipboard to a given position.

Parameters:
[in] hParent Parent that can be the target of attachment. Any got in Add() function value or one of the following contexts: GI_SCROLABLE_ROOT or GI_FIXED_ROOT, can be a parent.
[in] hInsertAfter the value used to specify location of the insertion. If sorting is switched on, this parameter is meaningless, because a data object is inserted according to the sorting rules. If there is no sorting, hInsertAfter can have the following values:
GI_FIRST Insertion to the beginning
GI_LAST Insertion to the end
HITEM Insertion after a given handle
Returns:
True for a successful operation. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

ICopyPaste * SetCopyPaste ( ICopyPaste copyPaste  ) 

Sets new ICopyPaste interface.

Returns:
Previous ICopyPaste interface.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

ICopyPaste * GetCopyPaste (  )  const

Gets the current ICopyPaste interface used by the grid.

Returns:
Current ICopyPaste interface used by the grid.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

const CCopyPasteSettings & GetCopyPasteSettings (  )  const

Gets settings collected in CCopyPasteSettings type object and used by the grid in copy/paste operations. Const version.

Returns:
Settings collected in CCopyPasteSettings class object.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. However CCopyPasteSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other threads, it is better to use SetCopyPasteSettings() function.

CCopyPasteSettings & GetCopyPasteSettings (  ) 

Gets the settings collected in CCopyPasteSettings type object and used by the grid in copy/paste operations.

Returns:
Settings collected in CCopyPasteSettings class object.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. However CCopyPasteSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other threads, it is better to use SetCopyPasteSettings() function.

void SetCopyPasteSettings ( const CCopyPasteSettings settings  ) 

Sets the new settings used by the grid for copy/paste operations.

Parameters:
[in] settings New settings to be used for copy/paste operations.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowCopyPaste ( bool  bAllow  ) 

Enables/disables copy/paste.

Parameters:
[in] bAllow Enables copy/paste.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool IsCopyPasteAllowed (  )  const

Gets the value indicating whether copy/paste operations are allowed.

Returns:
True - copy/paste operations are allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

IDragDrop * SetDragDrop ( IDragDrop dragDrop  ) 

Sets new IDragDrop interface. This function also returns the previous interface used by the grid.

Parameters:
[in] dragDrop New IDragDrop interface.
Returns:
Previous interface used by the grid.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

IDragDrop * GetDragDrop (  )  const

Gets the current IDragDrop interface used by the grid.

Returns:
Current IDragDrop interface used by the grid if it is found. Otherwise - 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

const CDragDropSettings & GetDragDropSettings (  )  const

Gets the drag&drop settings collected in CDragDropSettings type object. Const version.

Returns:
Settings collected in CDragDropSettings class object.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. However CDragDropSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other threads, it is better to use SetDragDropSettings() function.

CDragDropSettings & GetDragDropSettings (  ) 

Gets the drag&drop settings collected in CDragDropSettings type object.

Returns:
Settings collected in CDragDropSettings class object.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. However CDragDropSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other threads, it is better to use SetDragDropSettings() function.

void SetDragDropSettings ( const CDragDropSettings settings  ) 

Sets new drag&drop settings.

Parameters:
[in] settings Settings collected in CDragDropSettings class object.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowDragAndDrop ( bool  bAllow  ) 

Enables or disables drag&drop in the grid.

Parameters:
[in] bAllow Enables use of drag&drop.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool IsDragAndDropAllowed (  )  const

Gets the value indicating whether drad&drop operations are allowed.

Returns:
True - drad&drop operations are allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

CDragImage CreateDragImage ( const Handles &  handles,
ContextType  contextType,
const CHeader header 
) const

Helper that enables image creation when grid content is dragged.

For better visualization the grid enables use of transferred data images. As the result, the function returns CDragImage type object containing the image as CImageList object and the cursor position counted from the left upper corner of the picture. With drop operation completed it is necessary to delete the image by calling CImageList::DeleteImageList() and then its destructor.

Parameters:
[in] handles list of the handles participating in drag&drop operation.
[in] contextType Context type.
[in] header Current header used by the grid.
Returns:
CDragImage structure.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowSort ( bool  bEnable  ) 

Enables or disables sorting in the grid.

Parameters:
[in] bEnable True - sorting is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool CanSort (  )  const

Returns the value indicating whether sorting is allowed.

Returns:
True - sorting is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowMultiSort ( bool  bEnable  ) 

Allows multiple sorting in the grid.

Parameters:
[in] bEnable True - multiple sorting is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool CanMultiSort (  )  const

Returns the value indicating whether multiple sorting is allowed.

Returns:
True - multiple sorting is allowed, false - forbidden.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void SetSortedContext ( ContextType  contextType = AllContexts  ) 

Sets grid context where sorting is allowed.

Parameters:
[in] contextType Grid context. Available values: UndefinedContext, FixedContext, ScrollableContext, AllContexts. If UndefinedContext is applied then sorting will be forbidden in both contexts.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

ContextType GetSortedContext (  )  const

Gets contexts where sorting is allowed.

Returns:
Grid contexts where sorting is allowed. UndefinedContext means that sorting is forbidden in both contexts.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void ResetSort ( bool  redraw = true  ) 

Cancels sorting.

Parameters:
[in] redraw If the redraw flag is set for true then the grid is redrawn.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void SetSort ( int  level,
CSortInfo  sortInfo,
bool  applyImmediatelly = true 
)

Sets a sort for a given level.

The grid supports up to five levels of sorting. Level indexing starts from '0'. The function is used to set sorting for a given level. Sorting levels must be set in order without leaps. It is possible to start the process when all levels of sorting are set, not every time when a level is changed.

Parameters:
[in] level sorting level. The first level starts from '0'.
[in] sortInfo information about sorting. Assigns the column on which sorting is conducted and its direction.
[in] applyImmediatelly Indicates whether it should apply for new sorting parameters immediatelly.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

CSortInfo GetSort ( int  level  )  const

Gets information about sorting for a given level.

If sorting for a given level is not specified then the field identifier returned by CSortInfo::GetFid() is equal to Common::fieldNotSpesified.

Returns:
Information about sorting for a given level.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void UpdateSort (  ) 

Performs data sorting in the grid according to sorting rules specified in a header.

thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

int GetSortLevels (  )  const

Returns current value of sorting levels quantity.

Returns:
Count of sorting levels
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

IGridFilter * SetFilter ( IGridFilter filter  ) 

Sets a new filter.

At the same time the function also returns the previous value of the filter. At filter setting all grid lines are checked on whether or not they are filtered.

Parameters:
[in] filter New filter
Returns:
Previous filter
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

IGridFilter * GetFilter (  )  const

Gets the current filter set in the grid.

Returns:
Current filter if it is found. Otherwise - 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void UpdateFilter (  ) 

Calls checking of all grid lines on whether or not they are filtered.

thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

IKeyManager * SetKeyManager ( IKeyManager keyManager  ) 

Sets a new keyboard manager to control the grid.

The function also returns the previous manager.

Parameters:
[in] keyManager New keyboard manager.
Returns:
Previous keyboard manager.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

IKeyManager * GetKeyManager (  )  const

Gets the current keyboard manager used by the grid.

Returns:
Current keyboard manager if it is found. Otherwise - 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void AllowNavigation ( ContextType  contextType = AllContexts  ) 

Allows to conduct navigation in given grid contexts.

Parameters:
[in] contextType Available values: UndefinedContex, FixedContext, ScrollableContext, AllContexts. If UndefinedContext is applied then navigation is forbidden in both contexts.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool CanNavigate ( ContextType  contextType  )  const

Returns the value, indicating whether navigation is possible in given grid context.

Returns:
True if navigation is allowed. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void NavigateUp ( bool  bShift,
bool  bCtrl 
)

Moves a focus up and scrolls down one line if it is necessary.

The function hands over navigation parameters to the keyboard manager that moves grid lines focus and changes selection according to specified bShift and bCtrl values. If the keyboard manager is not set, the parameters are handed over to the default manager returned by CPreferences::GetDefaultKeyManager() function.

Parameters:
[in] bShift Indicates whether the shift button is pressed
[in] bCtrl Indicates whether the control button is pressed
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void NavigateDown ( bool  bShift,
bool  bCtrl 
)

Moves a focus down and scrolls up one line if it is necessary.

The function hands over navigation parameters to the keyboard manager that moves grid lines focus and changes selection according to specified bShift and bCtrl values. If the keyboard manager is not set, the parameters are handed over to the default manager returned by CPreferences::GetDefaultKeyManager() function.

Parameters:
[in] bShift Indicates whether the shift button is pressed
[in] bCtrl Indicates whether the control button is pressed
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void NavigatePageUp ( bool  bShift,
bool  bCtrl 
)

Moves a focus up and scrolls down one page if it is necessary.

The function hands over navigation parameters to the keyboard manager that moves grid lines focus and changes selection according to specified bShift and bCtrl values. If the keyboard manager is not set, the parameters are handed over to the default manager returned by CPreferences::GetDefaultKeyManager() function.

Parameters:
[in] bShift Indicates whether the shift button is pressed
[in] bCtrl Indicates whether the control button is pressed
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void NavigatePageDown ( bool  bShift,
bool  bCtrl 
)

Moves a focus down and scrolls up one page if it is necessary.

The function hands over navigation parameters to the keyboard manager that moves grid lines focus and changes selection according to specified bShift and bCtrl values. If the keyboard manager is not set, the parameters are handed over to the default manager returned by CPreferences::GetDefaultKeyManager() function.

Parameters:
[in] bShift Indicates whether the shift button is pressed
[in] bCtrl Indicates whether the control button is pressed
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void NavigateHome ( bool  bShift,
bool  bCtrl 
)

Focuses the first line in the fixed or scrollable context according to navigation settings.

The function hands over navigation parameters to the keyboard manager that moves grid lines focus and changes selection according to specified bShift and bCtrl values. If the keyboard manager is not set, the parameters are handed over to the default manager returned by CPreferences::GetDefaultKeyManager() function.

Parameters:
[in] bShift Indicates whether the shift button is pressed
[in] bCtrl Indicates whether the control button is pressed
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void NavigateEnd ( bool  bShift,
bool  bCtrl 
)

Focuses the last line in the fixed or scrollable context according to navigation settings.

The function hands over navigation parameters to the keyboard manager that moves grid lines focus and changes selection according to specified bShift and bCtrl values. If the keyboard manager is not set, the parameters are handed over to the default manager returned by CPreferences::GetDefaultKeyManager() function.

Parameters:
[in] bShift Indicates whether the shift button is pressed
[in] bCtrl Indicates whether the control button is pressed
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void ResetScroll (  ) 

Updates vertical and horizontal scrollbar positions.

thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void PrintPreview ( const CPrintSettings settings  ) 

The function opens a print preview dialog where the user can specify printer settings, paper position and size, zoom on-screen grid content or to enlarge a printed sheet on the screen.

Parameters:
[in] settings Specifies printing settings for a grid content.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

void Print ( const CPrintSettings settings,
CPrintInfo *  printInfo = 0 
)

Launches printing of grid content.

Parameters:
[in] settings Specifies printing settings for a grid content.
[in] printInfo MFC Informational data structure, containing nested printing information. Can be 0.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

CEmbeddedControlAdapter * AttachControl ( CWnd *  control,
HITEM  hItem,
Common::FID  fid,
const CEmbeddedControlParams params = CEmbeddedControlParams() 
)

Attaches a control to a grid cell.

Only one control can be attached to a cell. The grid has no limits and can attach almost any controls to cells. It is important that each control utilizes at least one window handle. A quantity of such handles in the system is limited.

Parameters:
[in] control User's control.
[in] hItem line handle in the grid. If the handle is filtered, than the control is invisible.
[in] fid field's identifier.
[in] params Attachment settings collected in CEmbeddedControlParams class object.
Returns:
True if MFC control has been successfully attached to the cell. Otherwise false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool DetachControl ( CWnd *  control  ) 

Looks for the cell where a specified control is attached, and detaches it.

Parameters:
[in] control Control to be detached.
Returns:
True if MFC control has been successfully detached from the cell. Otherwise false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool DetachControl ( HITEM  hItem,
Common::FID  fid,
bool  bDestroy 
)

Detaches a control from the grid cell specified by hItem and fid values.

Parameters:
[in] hItem line handle in the grid.
[in] fid field's identifier.
[in] bDestroy value indicates that when the control switched off, it should be destroyed.
Returns:
True if MFC control has been successfully detached from the cell. Otherwise false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool HasControl ( HITEM  hItem,
Common::FID  fid 
) const

Checks whether MFC control is attached to a given cell.

Parameters:
[in] hItem line handle in the grid.
[in] fid field's identifier.
Returns:
True if there is an MFC control attached to the specified cell. Otherwise false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool HasControl ( int  nRow,
ContextType  contextType,
Common::FID  fid 
) const

Checks whether MFC control is attached to a given cell.

Parameters:
[in] nRow index of a line in grid context.
[in] contextType grid context. Available values: FixedContext, ScrollableContext.
[in] fid field's identifier.
Returns:
True if there is MFC control attached to the specified cell. Otherwise false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

IEditInPlace * SetEditInPlace ( IEditInPlace editInPlace  ) 

Sets new IEditInPlace interface. The function returns previous value of the interface.

Parameters:
[in] editInPlace New edit in place interface.
Returns:
Previous edit in place interface
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

IEditInPlace * GetEditInPlace (  )  const

Gets current IEditInPlace interface used by the grid.

Returns:
Current IEditInPlace interface used by the grid. If it is not found, 0 is returned.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool CanStartEditInPlace ( HITEM  hItem,
Common::FID  fid,
IEditInPlace::StartReason  reason 
) const

Checks if it is possible to start 'edit in place' for a given cell.

The reason for calling this function is passed as the second parameter. Single or double click on a grid cell or navigation between controls can be such a reason.

Parameters:
[in] hItem line visible handle in the grid.
[in] fid field's identifier.
[in] reason The reason why this function is called.
Returns:
True if the grid can start edit in place for the given cell. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool StartEditInPlace ( HITEM  hItem,
Common::FID  fid,
IEditInPlace::StartReason  reason = IEditInPlace::ActivateOnUserStart 
)

Starts 'edit in place' process for a given grid cell.

All steps of 'edit in place' are conducted through IEditInPlace interface.

Parameters:
[in] hItem line visible handle in the grid.
[in] fid field's identifier.
[in] reason The reason why this function is called.
Returns:
True if edit in place process has been successfully started. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

bool StopEditInPlace ( IEditInPlace::StopReason  reason,
bool  postMessage = false 
)

Requests the grid to stop' edit in place' specifying a reason (lost of focus, navigation, enter...).

Sometimes it is necessary to process the request asynchronously. For this purpose a postMessage parameter is added. It indicates that the request shouldn't cause a direct stop of 'edit in place' and destruction of the window. Instead a message is posted, and the grid performs the required operations upon receiving it.

Parameters:
[in] reason The reason why this function has been called.
[in] postMessage If true, then edit in place operation should be stopped asynchronously.
Returns:
True if edit in place process has been successfully stopped. Otherwise - false.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

CWnd * GetEditInPlaceControl (  )  const

Gets a pointer to the control that is currently participating in 'edit in place' operation.

However this pointer is temporary and it's not recommended to save it.

Returns:
Control that is currently participating in 'edit in place' operation. If it is not found, 0 is returned.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism.

const CEditInPlaceSettings & GetEditInPlaceSettings (  )  const

Gets current 'edit in place' settings collected in CEditInPlaceSettings class object. Const version.

Returns:
Current settings collected in CEditInPlaceSettings class object.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. However CEditInPlaceSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other threads, it is better to use SetEditInPlaceSettings() function.

CEditInPlaceSettings & GetEditInPlaceSettings (  ) 

Gets current 'edit in place' settings collected in CEditInPlaceSettings class object.

Returns:
Current settings collected in CEditInPlaceSettings class object.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. However CEditInPlaceSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other threads, it is better to use SetEditInPlaceSettings() function.

void SetEditInPlaceSettings ( const CEditInPlaceSettings settings  ) 

Sets new 'edit in place' settings.

Parameters:
[in] settings New settings collected in CEditInPlaceSettings class object.
thread-safety:
The function is thread-safe. When it is called from a thread other than GUI thread synchronization is performed via SendMessage mechanism.

void Serialize ( CArchive &  ar  )  [virtual]

Saves a state and settings to the archive and restores them from the archive.

Parameters:
[in] ar Archive to store or restore grid data.
thread-safety:
The function is not thread-safe.

int GetSerializeVertion (  )  [static]

Gets current grid version that is used for compatibility with the archives made in the previous grid versions.

Returns:
Current serialization version The function is thread-safe.