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 it.

static int GetSerializeVertion ()

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

Public Member Functions

Addition, deleting, positioning, enumeration

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 corresponding to a given data object lines 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 corresponding to a given data object handles.

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)

The function permits to attach a given hItem to the grid.

bool Detach (HITEM hItem)

Detaches the 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 several times into one grid. At each insertion a unique handle is created which allows to uniquely define the 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 object of functional.

void ForEachVisible (IForEach &functional, HITEM startFrom=GI_FIRST)

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

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

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

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

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

Getting and setting formatted and non-formatted data

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

The function allows to get corresponding to the 'fid' unformatted value of a data object.

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

Sets new value into 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 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 to work with hierarchy

bool IsExpanded (HITEM hItem) const

Gets the value pointing whether a line is expanded.

Handles GetChildren (HITEM hItem, bool visibleOnly) const

Gets handles of all the children of a given parent.

bool HasChildren (HITEM hItem) const

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

int GetHierarchicalLevel (HITEM hItem) const

Gets a 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 which handle 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 which handle is associated with the data object.

Data objects and lines search 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 met handle of a given data object.

ContextType GetContextType (HITEM hItem) const

Gets the grid context to which a given handle belongs.

ContextType GetContextType (const Common::CDataObject *pDO) const

Gets the grid context into which the first met handle corresponding to a given data object is inserted.

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

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

HITEM GetItem (const Common::CDataObject *pDO) const

Gets the first met 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 previous visible line located before a given handle.

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

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

Common::CDataObject * GetDataObject (HITEM hItem)

Gets the data object corresponding to a given handle.

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

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

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.

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

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

Visibility, placement and bounds

int GetFirstVisibleRow () const

Gets the first visible on the screen line in the scrollable context.

int GetLastVisibleRow (ContextType contextType=ScrollableContext) const

Gets the last visible on the screen line in a given context.

void SetFirstVisibleRow (int nRow)

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

void SetFirstVisibleItem (HITEM hItem)

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

void SetFirstVisibleItem (const Common::CDataObject *pDO)

The first met line's handle in the scrollable context for a given data object is searched.

void EnsureVisible (int nRow)

Makes a given line visible in the scrollable context.

void EnsureVisible (HITEM hItem)

Makes a given handle visible in the scrollable context.

void EnsureVisible (const Common::CDataObject *pDO)

Makes the handle corresponding to the data object visible in the 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's 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's area of the grid.

bool IsInVisibleRect (int nRow, ContextType contextType)

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

CRect GetContextVisibleRect (ContextType contextType) const

Gets the visible rectangle occupied by a given grid context taking the size of the client's grid area and scrolling into consideration.

CRect GetContextVirtualRect (ContextType contextType) const

Gets the virtual rectangle occupied by a given grid context without taking the size of the client's grid area and scrolling into consideration.

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 the 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 a virtual size of the grid cell specified by the first found handle for a given data object and column identifier (identifier of the data object field) without taking the size of the visible grid area into consideration.

int GetLinesPerPage (bool forward=true) const

Calculates a quantity of wholly visible lines per page in the scrollable context of the grid.

int GetItemHeight (HITEM hItem) const

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

Selection

void AllowSelection (bool bEnable)

Allows to perform selection in the grid.

bool CanSelect () const

Defines whether lines selection in the grid is allowed.

void AllowMultiSelection (bool bEnable)

Allows the possibility to select several lines in the grid.

bool CanMultiSelect () const

Defines whether lines multi selection is allowed in the grid.

void AllowSelectContext (ContextType contextType=AllContexts)

Sets the grid context where selection is allowed.

bool CanSelectContext (ContextType contextType) const

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

int GetSelectedCount () const

Gets a total number of selected lines in the grid.

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

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

bool Select (HITEM hItem, bool bSelect)

Allows to select 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's handle corresponding to the data object is selected.

void SelectAll ()

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

void ClearSelection ()

Selects out all lines in the grid.

void AllowMouseTrackSelection (bool bEnable)

Allows selection using the mouse.

bool CanMouseTrackSelection () const

Tests whether selection using the mouse is allowed.

Focus

void AllowFocusContext (ContextType contextType=AllContexts)

Allows to focus lines in a given context.

bool CanFocusContext (ContextType contextType) const

Checks if lines 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 a 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 (in milliseconds) the time passed from the moment of the 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 the visible cells corresponding to a given data object and column identifier in the grid.

Notifications

void AllowNotifications (bool bAllow)

The grid provides the possibility to deliver 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

CAppearance & GetAppearance ()

Gets CAppearance type object where the basic visual grid characteristics such as text, background, vertical and horizontal lines colors and so on are collected.

const CAppearance & GetAppearance () const

Gets CAppearance type object where the basic visual grid characteristics such as text, background, vertical and horizontal lines colors and so on are collected. Const version.

void SetAppearance (const CAppearance &appearance)

Sets a new grid appearance.

const CBackgroundImage & GetBackgroundImage () const

Gets a background image of the grid.

void SetBackgroundImage (const CBackgroundImage &settings)

Sets a new background image into the grid.

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

Sets font attributes to be used for a text within the grid. Internally, the grid clones the font, and after this function has been called, you should to 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 allowing to stretch icons in grid cells.

bool CanStretchImageInCell () const

Tests whether the flag allowing to stretch icons 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 two grid contexts separator's height.

int GetContextSeparatorHeight () const

Gets two grid contexts separator's height.

void AllowHighlight (bool bAllow)

Allows or forbids grid cells highlighting.

bool CanHighlight () const

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

const CHighlightSettings & GetHighlightSettings () const

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

CHighlightSettings & GetHighlightSettings ()

Gets the highlighting parameters collected in CHighlightSettings type object.

void SetHighlightSettings (const CHighlightSettings &settings)

Sets new parameters of highlighting in the grid.

ICustomDraw * SetCustomDraw (ICustomDraw *customDraw)

Sets a new interface to specify grid elements drawing.

ICustomDraw * GetCustomDraw () 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)

Allows to use the mechanism of double buffering in order to exclude the flicker effect at the moment of elements drawing.

bool GetFlickerFreeDrawing () const

Gets the value indicating whether a double buffering mode is allowed.

int GetOptimalRowHeight (ContextType contextType) const

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

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

Gets optimal value of a given grid cell width.

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

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

Headers

CHeader * SetHeader (CHeader *newHeader)

Sets a new header.

CHeader * GetHeader ()

Gets the current header used by the grid.

const CHeader * GetHeader () 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 ()

Shows the dialog allowing to configure columns of the header.

const CColumn * GetColumn (CPoint pt) const

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

const CColumn * GetNavigationColumn () const

Gets a navigation column.

const CColumn * GetHierarchicalColumn () const

Gets the column that manages the grid hierarchy.

void AdjustColumnByFid (Common::FID fid)

Performs column width optimization for visible grid lines.

void AdjustColumnByIndex (int index)

Performs column width optimization by its 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 partly hidden data.

int GetOptimalHeaderHeight () const

Gets optimal header's height.

void EnsureColumnVisible (Common::FID fid)

The function makes a column wholly visible in the grid.

Tooltips

void EnableTooltip (bool enable=true)

Allows to display tooltips.

bool IsTooltipEnabled () const

Returns the value indicating whether tooltip displaying is allowed.

const ITooltipCtrl * GetTooltipCtrl ()

Gets current ITooltipCtrl used by the grid.

ITooltipCtrl * SetTooltipCtrl (ITooltipCtrl *control)

Sets new ITooltipCtrl interface to control the tooltip window.

const ITooltip * GetTooltip () const

Gets the interface controlling the tooltip content.

ITooltip * SetTooltip (ITooltip *tooltip)

Set a new interface for defining the tooltip content.

const CTooltipSettings & GetTooltipSettings () const

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

CTooltipSettings & GetTooltipSettings ()

Gets the tooltip settings collected in CTooltipSettings class object.

void SetTooltipSettings (const CTooltipSettings &settings)

Sets new tooltip settings.

void EnableInPlaceTooltip (bool bEnable=true)

Allows to show the tooltip above grid cells when a cell size is not enough for displaying a 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.

CTooltipSettings & GetInPlaceTooltipSettings ()

Gets the tooltip settings determinant how the grid should show the tooltip above the grid cells when a cell size is not enough for displaying a text.

void SetInPlaceTooltipSettings (const CTooltipSettings &settings)

Sets the new settings determinant how the grid should show the tooltip above the grid cells when a cell size is not enough for displaying a text.

const ITooltipCtrl * GetInPlaceTooltipCtrl () const

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

ITooltipCtrl * SetInPlaceTooltipCtrl (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 the located after the focused line place.

bool Paste (HITEM hParent, HITEM hInsertAfter)

Pastes data from the clipboard to a given position.

ICopyPaste * SetCopyPaste (ICopyPaste *copyPaste)

Sets new ICopyPaste interface.

ICopyPaste * GetCopyPaste () const

Gets the current ICopyPaste interface used by the grid.

const CCopyPasteSettings & GetCopyPasteSettings () const

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

CCopyPasteSettings & GetCopyPasteSettings ()

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

void SetCopyPasteSettings (const CCopyPasteSettings &settings)

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

void AllowCopyPaste (bool bAllow)

Allows or forbids to use copy/paste.

bool IsCopyPasteAllowed () const

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

Drag and drop

IDragDrop * SetDragDrop (IDragDrop *dragDrop)

Sets new IDragDrop interface. At the same time the function returns the previous interface used by the grid.

IDragDrop * GetDragDrop () const

Gets the current IDragDrop interface used by the grid.

const CDragDropSettings & GetDragDropSettings () const

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

CDragDropSettings & GetDragDropSettings ()

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

void SetDragDropSettings (const CDragDropSettings &settings)

Sets new drag&drop settings.

void AllowDragAndDrop (bool bAllow)

Allows or forbids 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 which allows to create an image while grid content dragging.

Sorting

void AllowSort (bool bEnable)

Allows or forbids 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 the grid context where sorting is allowed.

ContextType GetSortedContext () const

Gets the 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 ()

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

int GetSortLevels () const

Returns current value of sorting levels quantity.

Data filtration

IGridFilter * SetFilter (IGridFilter *filter)

Sets a new filter.

IGridFilter * GetFilter () 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

IKeyManager * SetKeyManager (IKeyManager *keyManager)

Sets a new keyboard manager to control the grid.

IKeyManager * GetKeyManager () 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 ()

Conducts updating of vertical and horizontal scrollbars' positions.

Printing

void PrintPreview (const CPrintSettings &settings)

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

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

Launches a printing process for a grid content.

Built in controls

CEmbeddedControlAdapter * AttachControl (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

IEditInPlace * SetEditInPlace (IEditInPlace *editInPlace)

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

IEditInPlace * GetEditInPlace () 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' giving a reason (lost of focus, navigation, enter...).

CWnd * GetEditInPlaceControl () const

Gets a pointer to the control that at the present moment is participating in 'edit in place' operation.

const CEditInPlaceSettings & GetEditInPlaceSettings () const

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

CEditInPlaceSettings & GetEditInPlaceSettings ()

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 oriented to work with data of practically any types. These data are the objects of usual C++ classes with the set of Get- and Set- methods that can be called by their identifiers. These identifiers are declared with a class together. In order 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 provides possibilities of automatic updating, sorting, highlighting and filtration of the objects at each values modification. To benefit this, it is recommended to implement Common::CDataOnject::ISink interface that can fire notifications to the grid.

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

Purpose of contexts

The grid has two graphical contexts: fixed and scrollable. The reason why these contexts have been organized is that it is not possible to set just a number of 'frozen' rows in the hierarchical grid. Indeed, the quantity of them 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 many times inserted into one grid. Handles were organized in order to uniquely determine object's location in the grid. Handles take part in all grid operations. Besides they keep information about hierarchy, selection, filtration, time of the last updating and so on. A handle may not be always visible on the screen. It can be filtered by IGridFilter interface or hidden by its parent. So, for such handle the corresponding grid line does not exist. Handles can be easily detached from the grid with all hierarchy and inserted into any other place or grid.

Focus

Focus is designed to define the cursor location at navigation and lines selection in the grid. Only one focused line is permitted in the grid. As the grid can support several contexts then the focused context is the context where the focused line is located.

Appearance

Grid appearance is stored in an object of CAppearance type. At data drawing all colors are got from this object. The all painting information is passed through ICustomDraw interface where it can be freely re-defined.

Tooltips

A tooltip is designed to enlarge an application functionality for instances when information that must be provided to the user cannot be displayed entirely. Functionally the tooltip is divided into 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 tooltips:

A tooltip that shows information in the small popup window as a plain text or an html text in the popup browser.
Embedded tooltip. In case when some part of a text in a cell becomes invisible then the remaining text is automatically shown in the tooltip above the cell with the same font.

Copy & paste

Copy & paste allows you to move data inside one grid, between various grids or between different applications. The grid allows you to export data to such applications as Excel and Word. In addition to standard clipboard formats, GUI library has new ones that allow you to maintain a hierarchical information and also to move data between different applications with data serialization where it is possible. At any moment the programmer can customize the copy & paste mechanism. To control copy/paste process the grid provides ICopyPaste interface and its default implementation in the 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 different applications. Moreover, at any moment the programmer can customize drag & drop behavior for his purposes. To indicate a dropping place the grid illuminates the lines between which data will be inserted. However in case of hierarchical data it is not enough because the level of hierarchy remains unknown. Our grid has a possibility to indicate this hierarchical level that allows you to clearly specify the user's wishes concerning inserting data into the desirable position. All drag and drop steps are conducted though IDragDrop interface where they can be totally redefined.

Sorting

This is one of automatic services that allows you to greatly simplify programming and at the same time raising application quality. If data are updated (notification from Common::CDataObject::ISink interface or UpdateRow(), UpdateItem() or UpdateDataObject() functions call), the grid will automatically search a new position according to the sorting and hierarchy rules. Information about sorting is kept in the header. If the header is changed then 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 the single sorting on. Second click inverts the direction of sorting. Multiple sorting is possible with mouse click while Ctrl key is hold. The second click with Ctrl key hold changes sorting direction in the column where the click was made. In order to cancel sorting it's enough to click on the header with the left mouse button and holding Shift key. Of course it is possible to control sorting by programming.

Data filtration

The grid allows to realize automatic data filtration. A grid line is considered filtered if the operator () of IGridFilter interface returns true. If the line is filtered then neither the line nor its children can be visible. The check for visibility 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 management over navigation is put to the external module that opens practically unlimited possibilities to manage received from the keyboard events. All navigation is collected in the implementation of IKeyManager interface. We offer the default implementation in the CKeyManager class. An object of this class can be got by calling CPreferences::GetDefaultKeyManager().

Printing

The grid allows you to print its content on a printer and also has a 'print preview' option. There are various levels for scaling 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 realize 'edit in place' possibilities. The controls themselves are created in the moment when the user clicks in a grid cell. Usually assortment of such controls is rather limited and depends on the grid's developer. Often the necessity to use real controls or controls of outside developers appears. In such case it is required to keep a track of control location, its movements, size and visibility changes according to scrollbars location, filtration, cells size, position in a hierarchy and so on. Realization of the code positioning the control is a difficult and laborious task for the programmer. In order to simplify development of a resulting application the gird provides a convenient service for positioning practically any controls above the grid. The programmer just needs to assign the cell to which a control is to be attached and specify some control settings. Necessary to consider that the grid doesn't manage control's life time. The programmer takes all responsibility 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 practically any MFC controls with navigation between them. In most cases, buttons, check boxes, and so on are not real controls but only their drawings. Basically, such 'controls' are supplied together with the grids and their number and functionality may be limited. Moreover such approach does not allow the use of already existing solutions or the third-party libraries. In case of real controls it is necessary to handle their location and size according to a number of elements in the grid, scrollbars' positions and also to manage their visibility (in case of filtration, expand/collapse and row deleting). This is not a trivial task and some difficulties may appear in the process of its realization. We offer the solution that permits you to attach pratically any MFC control to any cell and the grid will handle the positioning and visibility of the controls itself.

Serialization

Serialization in CArchive is a useful grid feature. A position, color of columns, colors, the user's preferences, and so on are serialized. The grid is projected in such a way that new grid versions will be compatible with the archives made in previous ones.

Thread safety

The grid was designed to work in a heavy multi-threaded environment. Practically all functions are thread-safe. They use both synchronous and as asynchronous mechanisms with or without blocking the calling thread. Inserting, removing, getting etc. work with blocking the calling thread. Any data updating are processed through the asynchronous mechanism. The calling thread does not wait for the end of updating operation. Much updating 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:

CPreferences::DirectCall: The grid asks for values in the GUI thread each time when it needs to paint cells or scroll lines. It is up to you to protect your business data (the grid is thread safe). This mode is more productive than the other. It has low CPU loading and low memory consumption.
CPreferences::MemoryBuffer: At each update the grid copies values and formats them in the calling thread and then no longer calls methods of your objects. The grid gets all information from the local cache. This mode is less productive but more secure.

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? will explain all steps how to install and compile 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 header. Field identifiers should be the same that 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 a hierarchical architecture. Scrolled (GI_SCROLLABLE_ROOT) or fixed (GI_FIXED_ROOT) contexts can be root value. They are not displayed in the grid. That's why when a data object is added to them visually it will be placed on the top level of the hierarchy. If the addition is successful then the handle, which uniquely determines the 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 many times. A handle can be detached form the grid and attached to any other place or even to a different grid. It's significant 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 keeping doesn't have to repeat the grid hierarchy at all. Moreover in other grids it is possible to built a completely different hierarchy using the same data objects. At data object realization it is strongly recommended to implement ISink interface that will allow to notify the grid about data modification. That makes it possible to use the services of automatic data updating, sorting, highlighting and filtration that will considerably simplify the application. Also it is significant that if sorting is switched on a data object will be added to hParent according to the sorting rules. In case if hParent is collapsed or filtered a data object will be added but not seen. In terms of productivity to add data to the end of the grid is several times more productive than to add them to the beginning.

Parameters:

[in] pDO added data object

[in]

hParent

parent item to which a data object will be added. The following values are available:

GI_SCROLLABLE_ROOT	Data object is added on the first level of the hierarchy and can be scrollable
GI_FIXED_ROOT	Data object is added on the first level of the hierarchy but cannot be scrollable
HITEM	Any handle acquired before at addition into the grid.

[in]

hInsertAfter

the value used to specify location of an insertion. If sorting is switched on then this parameter doesn't have any meaning because a data object will be 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:: In case of successful addition the handle uniquely determining the data object position in the grid is returned. Otherwise '0' is returned.

Thread safety: The function is thread safe. When it is called from a non-GUI thread, synchronization is carried out through SendMessage mechanism. If MemoryBuffer mode is used then in a calling thread all formatted and unformatted data are 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 autor 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 next code 'frezes' the autor i.e. adds the autor to the fixed context:
 m_Grid.Add(new CAuthor(...), Dapfor::GUI::GI_FIXED_ROOT);

See also:: Read the How to compile my first application? article to get step-by-step instructions how to build the application. More information about the data object you can get here.

bool Delete ( HITEM hItem )

Deletes an item from the grid.

When the function is called corresponding to a given handle line is deleted together with all children. Deleting will be 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 the screen through the system of formats. So when the handle is deleted the data object will not be physical destructed and if the data object is inserted several times into the same grid or into several grids then except for the deleted line in other places it will be displayed as before.

Parameters:

[in] hItem handle that is 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 the thread different from GUI thread synchronization is carried out 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 the call does not destroy the 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 to get step-by-step instructions how to build the application. More information about the data object you can get here.

int Delete ( const Common::CDataObject * pDO )

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

This function can be useful in case of multiple insertion of a data object into the grid. When the data object is deleted from the grid it is not physically destroyed.

Parameters:

[in] pDO pointer to the data object which should be deleted from the grid.

Returns:: Found a quantity of data object entries in the grid.

Thread safety: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example

 //Add an object to the grid
 CSomeClass* someObject = new CSomeClass(...);
 m_Grid.Add(someObject);

 ...

 //Remove all rows with theirs children that correspond to the specified object from the grid. 
 //The grid will look for all GUI::HITEM (one or more) with the given data object and remove 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 the line contains children (both visible and invisible) they all also will be deleted. The function doesn't delete data objects (doesn't call their destructors) but only deletes the reference to a found data object 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. In case of AllContexts the grid is trying to delete 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example

 //Remove the first non-scrollable row (the indexes are started 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 the thread different from GUI thread synchronization is carried out through 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 corresponding to a given data object handles.

Let's mention that several handles can correspond to one data object. Part of the handles for one object might be filtered (lines will be invisible) or hidden by their parents.

Parameters:

`[in]`	pDO	pointer to a data object.
`[in]`	visibleOnly	flag pointing that the returned handles will be visible in the grid, i.e. not hidden by the parents or filtered.
`[in]`	contextType	type of the context where handles will be searched. Available values: FixedContext, ScrollableContext, AllContexts.

Returns:: List of corresponding to a given data object handles.

Thread safety: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example

 //Gets all visible in the grid rows (scrollable and non-scrollable) that correspond 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 the context where handles will be 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`
	)

The function permits to attach a given hItem to the grid.

The possibility to attach/detach handles was implemented in order to be able to easily transfer hierarchical data inside one context, between different contexts and between different grids while keeping their hierarchy. This function is applicable only to the 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 can be 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 will be 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 in case of successful operation. Otherwise - false. The function can be concluded 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool Detach ( HITEM hItem )

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

Parameters:

[in] hItem Handle to be detached.

Returns:: True in case of successful operation. Otherwise - false.

Thread safety: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through 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 several times into one grid. At each insertion a unique handle is created which allows to uniquely define the 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 the thread different from GUI thread synchronization is carried out through 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 carried out in one or both contexts.

Parameters:

[in] contextType Type of the context where the search will be carried out. Available values: FixedContext, ScrollableContext, AllContexts.

Returns:: Counted number of visible grid lines.

Thread safety: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void ForEach	(	IForEach &	functional,
		HITEM	startFrom = `GI_FIRST`
	)

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

The search is carried out among visible and invisible lines. It can be started not only from the first line but from the 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 then the search starts from the fixed context and if it has no elements then from the scrollable context.

Thread safety: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism. It is significant that at multithread applications realization the search and transmission of handles and data objects are always carried out in GUI thread. If the function is called from other thread then the calling thread will be blocked until its return from 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 for both visible and invisible items
RowsCounter functor1;
m_Grid.ForEach(functor1);

//the functor is applied only for 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 object of functional.

The search is carried out among visible lines. It can be started not only from the first line but from the 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 then the search starts from the fixed context and if it has no elements then from the scrollable context.

Thread safety: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism. It is significant that at multithread applications realization the search and transmission of handles and data objects are always carried out in GUI thread. If the function is called from other thread then the calling thread will be blocked until its return from 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 for both visible and invisible items
RowsCounter functor1;
m_Grid.ForEach(functor1);

//the functor is applied only for 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 before a given position for a given parent.

The moving is conducted by the consecutive handle detaching from the grid and then attaching to a new position.

Parameters:

[in] movingItem Moved handle.

[in]

parentPosition

Parent to which the moved handle will be 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 on the highest level of the hierarchy in the scrollable context
GI_FIXED_ROOT	Moving on the highest level of the hierarchy in the fixed context

[in]

position

Position before which the handle will be 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 the thread different from GUI thread synchronization is carried out through 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 the 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 after a given position for a given parent.

The moving is conducted by the consecutive handle detaching from the grid and then attaching to a new position.

Parameters:

[in] movingItem Moved handle.

[in]

parentPosition

Parent to which the moved handle will be 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 on the highest level of the hierarchy in the scrollable context
GI_FIXED_ROOT	Moving on the highest level of the hierarchy in the fixed context

[in]

position

Position after which the handle will be inserted. Available values:

GI_FIRST	Insertion to the first position
GI_LAST	Insertion after the last position
HITEM	Insertion after 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 the thread different from GUI thread synchronization is carried out through 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 the 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 allows to get corresponding to the 'fid' unformatted value of a data object.

It is significant that during operating in CPreferences::MemoryBuffer mode data are got from the grid's cache but not from the data object. As a result access to the data object is not carried out. In case of CPreferences::DirectCall mode the value is requested directly from the data object.

Parameters:

`[in]`	hItem	Line's handle in the grid. The line can be visible and invisible as well.
`[in]`	fid	Field's identifier.

Returns:: Requested value in case of success. If a data object field has not been found then Common::CValue with Common::Undefined identifier will be returned.

Thread safety: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism. Its worth to be mentioned that in case of 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 the non-formatted value from the grid's 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 the Datfor::GUI::CPreferences::DirectCall mode the grid will get the data from the data object
//by calling GetPrice() method.
//For the 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 it is possible to 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 notifications mechanism 
//in the data object and 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);

//Or if you want to transform MFC/STL string to the value, you can use the next
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 new value into the data object.

Parameters:

`[in]`	hItem	Line's handle in the grid. The line can be visible and invisible as well.
`[in]`	fid	Field's identifier.
`[in]`	value	New value which is set into 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism. Regardless of thread safety mode the function accesses the data object to modify its value. Access and value modification is always carried out in GUI thread. If the data object is supposed to be used in multithread applications then 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 the non-formatted value from the grid's 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 the Datfor::GUI::CPreferences::DirectCall mode the grid will get the data from the data object
//by calling GetPrice() method.
//For the 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 it is possible to 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 notifications mechanism 
//in the data object and 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);

//Or if you want to transform MFC/STL string to the value, you can use the next
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 case of CPreferences::MemoryBuffer mode the string is taken from a cache, in case of CPreferences::DirectCall mode the value is requested from the data object and then is formatted into a string.

Parameters:

`[in]`	hItem	Line's handle in the grid. The line can be visible and invisible as well.
`[in]`	fid	Field's identifier.
`[in]`	format	The format by which the value will be formatted into the string. If the format is not specified then its search will be conducted according to the following order: firstly the format is searched in object of CColumn class, if it has not been found the format is searched in data object Common::CFieldMap and if after that the format has not been defined then the default format returned by Common::CFormat::GetDefaultFormat() function is selected.

Thread safety: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism. Its worth to be mentioned that in case of 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 the non-formatted value from the grid's 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 the Datfor::GUI::CPreferences::DirectCall mode the grid will get the data from the data object
//by calling GetPrice() method.
//For the 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 it is possible to 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 notifications mechanism 
//in the data object and 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);

//Or if you want to transform MFC/STL string to the value, you can use the next
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 new value into the data object using a formatted string.

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

Parameters:

`[in]`	hItem	Line's handle in the grid. The line can be visible and invisible as well.
`[in]`	fid	Field's identifier.
`[in]`	str	Unformatted string.
`[in]`	format	The format to covert 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism. Regardless of thread safety mode the function accesses the data object to modify its value. Access and value modification is always carried out in GUI thread. String conversion into value is always conducted in GUI thread too. If the data object is supposed to be used in multithread applications then 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 the non-formatted value from the grid's 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 the Datfor::GUI::CPreferences::DirectCall mode the grid will get the data from the data object
//by calling GetPrice() method.
//For the 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 it is possible to 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 notifications mechanism 
//in the data object and 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);

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

bool IsExpanded ( HITEM hItem ) const

Gets the value pointing whether a line is expanded.

If the line is collapsed then all attached to the given line children will be invisible.

Parameters:

[in] hItem line's handle in the grid. The line can be visible and invisible as well.

Returns:: True if the line has been expanded. Otherwise - false.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Handles GetChildren	(	HITEM	hItem,
		bool	visibleOnly
	)			const

Gets handles of all the children of a given parent.

Part of handles can be filtered (lines will be invisible.) or hidden by parents.

Parameters:

[in]

hItem

line's handle in the grid. Available for handles values:

HITEM	Got from Add function value
GI_SCROLLABLE_ROOT	Pseudo-value pointing that the scrollable context can be parental value
GI_FIXED_ROOT	Pseudo-vale pointing that the fixed context can be parental value

[in] visibleOnly flag pointing that derivable handles will be 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more about location C++ objects in the grid

bool HasChildren ( HITEM hItem ) const

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

Part of handles can be filtered (lines will be invisible.) or hidden by parents.

Parameters:

[in]

hItem

line's handle in the grid. Available for handles values:

HITEM	Got from Add function value
GI_SCROLLABLE_ROOT	Pseudo-value pointing that the scrollable context can be parental value
GI_FIXED_ROOT	Pseudo-vale pointing that the fixed context can be parental value

Returns:: True if a given handle has at least one child. Otherwise - false.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more about location C++ objects in the grid

int GetHierarchicalLevel ( HITEM hItem ) const

Gets a hierarchical level of a given line.

The value of pseudo-handles GI_SCROLLABLE_ROOT and GI_FIXED_ROOT are '-1'. The lines attached to any of these contexts will have level '0'. Next children will have level '1'. And so on. A number of levels is not limited.

Parameters:

[in] hItem line's handle in the grid. The line can be visible and invisible as well.

Returns:: Hierarchical level in the grid.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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's handle in the grid. The line can be visible and invisible as well. Any value got from Add function can be used as a parameter.

Returns:: If success, the parent to which a line is attached. Otherwise - zero.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more about location C++ objects in the grid

void Expand	(	HITEM	hItem,
		bool	withChildren
	)

Expands a line.

Attached to this line children become visible. Recursive expansion of all children is possible. In case of recursion if GI_SCROLLABLE_ROOT and GI_FIXED_ROOT are passed as an argument the grid will expand all lines in a given context.

Parameters:

`[in]`	hItem	line handle in the grid. The line can be visible and invisible as well. GI_SCROLLABLE_ROOT and GI_FIXED_ROOT can be used as a parameter. Collapsing and expanding of the root item context don't have any effect but it can be useful in case of recursive data expansion when withChildren = true.
`[in]`	withChildren	indicates whether recursive data expansion should be done for all attached to a given line children.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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'll expand this node, so all children, added to this node will be visible
m_Grid.Expand(hItem, false);

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


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

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

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

If several handles are found in the grid then the operation will be applied to each of them.

Parameters:

`[in]`	pDO	pointer to the data object.
`[in]`	withChildren	indicates whether recursive data expansion should be done for all attached to a given line children.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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'll expand this node, so all children, added to this node will be visible
m_Grid.Expand(hItem, false);

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


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

void Collapse	(	HITEM	hItem,
		bool	withChildren
	)

Collapses a line.

All attached to the line children become invisible.

Parameters:

`[in]`	hItem	line handle in the grid. The line can be visible and invisible as well. GI_SCROLLABLE_ROOT and GI_FIXED_ROOT can be used as a parameter. Collapsing and expanding of the root item context don't have any effect but it can be useful in case of recursive data collapsing when withChildren = true.
`[in]`	withChildren	indicates whether recursive data collapsing should be done for all attached to a given line children.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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'll expand this node, so all children, added to this node will be visible
m_Grid.Expand(hItem, false);

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


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

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

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

If several handles are found in the grid then the operation will be applied to each of them.

Parameters:

`[in]`	pDO	pointer to the data object.
`[in]`	withChildren	indicates whether recursive data collapsing should be done for all attached to a given line children.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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'll expand this node, so all children, added to this node will be visible
m_Grid.Expand(hItem, false);

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


//The same code you can use 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.

Counting out starts from '0' and is carried out from the beginning of the context, not from the beginning of the grid. I.e. the first line in the scrollable context will always have '0' index. And this index doesn't depend on a quantity of the lines in the fixed context.

Parameters:

[in] hItem line's handle in the grid.

Returns:: Line index in the grid if the handle has been found and the line is not hidden (not filtered and not hidden by its parents). Otherwise - 1. In order 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 the thread different from GUI thread synchronization is carried out through 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 met handle of a given data object.

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

Parameters:

[in] pDO Pointer to the data object

Returns:: Line index in the grid if the handle has been found and the line is not hidden (not filtered and not hidden by its parents). Otherwise - 1. In order 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more about location C++ objects in the grid

ContextType GetContextType ( HITEM hItem ) const

Gets the grid context to which a given handle belongs.

Parameters:

[in] hItem line's handle in the grid. The line can be visible and invisible as well.

Returns:: The context into which handle is inserted if the handle has been found and UndefinedContext if the line has been previously detached or can't be found.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more about location C++ objects in the grid

ContextType GetContextType ( const Common::CDataObject * pDO ) const

Gets the grid context into which the first met handle corresponding to a given data object is inserted.

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

Parameters:

[in] pDO Pointer to the data object

Returns:: Gets the grid context into which the first met handle corresponding to a given data object is inserted. The search starts from the fixed context and continues in the scrollable context. If the handle is filtered or hidden by its parents then UndefinedContext will be returned.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more about location C++ objects in the grid

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

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

Parameters:

`[in]`	nRow	line's index in the grid context.
`[in]`	contextType	grid context. It can be ScrollableContext or FixedContext.

Returns:: Line's handle if it has been found. Otherwise - 0.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more about location C++ objects in the grid

HITEM GetItem ( const Common::CDataObject * pDO ) const

Gets the first met handle for a given data object.

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

Parameters:

[in] pDO Pointer to the data object

Returns:: Line's handle if it has been found. Otherwise - 0.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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's area of the grid.

Parameters:

[in] point the coordinates counted in client area of the grid.

Returns:: Line's handle if the line has been found. Otherwise - 0.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 previous visible line located before a given handle.

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

Parameters:

`[in]`	hItem	handle of a visible line (not filtered and not hidden by parents) in the grid.
`[in]`	jumpBetweenContexts	permits to search in the fixed context if hItem is pointing to the scrollable one.

Returns:: Line's handle if the line has been found. Otherwise - 0.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 located after a given handle.

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

Parameters:

`[in]`	hItem	handle of a visible line (not filtered and not hidden by parents) in the grid.
`[in]`	jumpBetweenContexts	permits to search in the scrollable context if hItem is pointing to the fixed one.

Returns:: Line's handle if the line has been found. Otherwise - 0.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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's handle in the grid. The line can be visible and invisible as well.

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 the thread different from GUI thread synchronization is carried out through 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's handle in the grid. The line can be visible and invisible as well.

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 the thread different from GUI thread synchronization is carried out through 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 the 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 the thread different from GUI thread synchronization is carried out through 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 located in a given grid context and at a given position. Const version.

Parameters:

`[in]`	nRow	index in the 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more about location C++ objects in the grid

int GetFirstVisibleRow ( ) const

Gets the first visible on the screen line in the scrollable context.

Returns:: Index of the first visible line in the scrollable context. If there are no lines, -1 will be returned.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

int GetLastVisibleRow ( ContextType contextType = ScrollableContext ) const

Gets the last visible on the screen line in a given context.

The index of the last line depends on the grid's size, quantity of inserted data objects and for scrollable context also from the position of vertical scrollbar.

Parameters:

[in] contextType type of the context where the search is conducted.

Returns:: Index of the last visible line in a given context. If there are no lines, -1 will be returned.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

void SetFirstVisibleRow ( int nRow )

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

Parameters:

[in] nRow Index of the row in the scroolable area that is to be displaced.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

void SetFirstVisibleItem ( HITEM hItem )

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

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

Parameters:

[in] hItem handle of a visible line in the scrollable context.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

void SetFirstVisibleItem ( const Common::CDataObject * pDO )

The first met line's handle in the scrollable context for a given data object is searched.

If it is found and visible (not filtered or hidden by the parents) then corresponding to this handle line will be set as the first in the 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

void EnsureVisible ( int nRow )

Makes a given line visible in the 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

See also:: IsInVisibleRect()

Example: See more how to compute visible and virtual bounds of rows/cells

void EnsureVisible ( HITEM hItem )

Makes a given handle visible in the scrollable context.

The operation is not possible for filtered items. In the case of hierarchical items, the grid will expand all parents to show a specified handle.

Parameters:

[in] hItem Handle that is to be visible

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

void EnsureVisible ( const Common::CDataObject * pDO )

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

The operation is not possible if the specified handle is filtered. In the case of hierarchical items, the grid will expand all parents to show 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

bool IsVisible ( HITEM hItem ) const

Checks whether a given handle is visible in the grid.

Visibility is determined by the condition that the given handle and corresponding to it data object are not filtered in IGridFilter object. I.e. the operator () for this pair returns false. The second condition is that none of the direct or indirect parents of the given handle is not collapsed.

Parameters:

[in] hItem line's handle in the grid.

Returns:: true if line's handle is visible. Otherwise - false.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute 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.

Visibility is determined by the condition that given handle and corresponding to it data object are not filtered in the IGridFilter object. I.e. operator () for this pair returns false. The second condition is that none of direct or indirect parents of given handle is not collapsed.

Parameters:

[in] pDO Pointer to the data object.

Returns:: true if the first line's handle corresponding to the data object is visible. Otherwise - false.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute 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's 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute 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's 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

bool IsInVisibleRect	(	int	nRow,
		ContextType	contextType
	)

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

Parameters:

`[in]`	nRow	index in the 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

CRect GetContextVisibleRect ( ContextType contextType ) const

Gets the visible rectangle occupied by a given grid context taking the size of the client's grid area and scrolling into consideration.

Parameters:

[in] contextType type of a 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

CRect GetContextVirtualRect ( ContextType contextType ) const

Gets the virtual rectangle occupied by a given grid context without taking the size of the client's grid area and scrolling into consideration.

Parameters:

[in] contextType type of a 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

CRect GetLineVisibleRect ( const Common::CDataObject * pDO ) const

Gets the visible 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute 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 taking the size of the visible grid area and scrolling into consideration.

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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute 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 bounded by the visible area of the 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute 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 bounded by the visible area of the grid context.

Parameters:

`[in]`	pDO	Pointer to the data object.
`[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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute 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 bounded by the visible area of the 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

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

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

The visible rectangle is bounded by the visible area of the 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

int GetLinesPerPage ( bool forward = true ) const

Calculates a quantity of wholly visible lines per page in the scrollable context of the grid.

If indexes are increasing while counting (forward is equal to 'true') then the sum of derived value and the first visible index can't be more than the index of the last line in the scrollable context. And if indexes are reducing the difference between the first visible index and derived value can't be less than 0.

Parameters:

[in] forward If the value is 'true' then calculation is conducted starting from the first visible index with index increase. Otherwise quantity of lines per page is calculated in direction of indexes reduction starting from the first visible line.

Returns:: Quantity of a line with a wholly visible height per page.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

int GetItemHeight ( HITEM hItem ) const

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

Parameters:

[in] hItem line's handle in the grid. The line can be visible and invisible as well.

Returns:: Line's height

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example: See more how to compute visible and virtual bounds of rows/cells

void AllowSelection ( bool bEnable )

Allows to perform 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool CanSelect ( ) const

Defines whether lines 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void AllowMultiSelection ( bool bEnable )

Allows the possibility to select several lines in the grid.

Parameters:

[in] bEnable If true then the grid allows to select several lines at once. Otherwise only one line can be selected.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool CanMultiSelect ( ) const

Defines whether lines multi selection 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void AllowSelectContext ( ContextType contextType = AllContexts )

Sets the 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool CanSelectContext ( ContextType contextType ) const

Defines whether lines 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

int GetSelectedCount ( ) const

Gets a 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

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

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

Parameters:

`[in]`	nRow	index of the line in the grid context.
`[in]`	contextType	grid context.
`[in]`	bSelect	points whether a given line should be selected or selection should be cancelled. In case of 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool Select	(	HITEM	hItem,
		bool	bSelect
	)

Allows to select a line by its handle.

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

Parameters:

`[in]`	hItem	line's handle in the grid.
`[in]`	bSelect	points whether a given line should be selected or selection should be cancelled. In case of 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 the thread different from GUI thread synchronization is carried out through 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 selection should be cancelled. In case of 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through 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 the 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool IsSelected ( HITEM hItem ) const

Tests whether the line with a specified handle is selected.

Parameters:

[in] hItem line's handle in the grid. The line can be visible and invisible as well.

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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool IsSelected ( const Common::CDataObject * pDO ) const

Tests whether the first line's 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void SelectAll ( )

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

If multiselection is disabled, then only one line will be selected.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void ClearSelection ( )

Selects out all lines in the grid.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void AllowMouseTrackSelection ( bool bEnable )

Allows selection using the mouse.

With its help it is possible to select many grid lines at once. If the lines are located outside of the visible area there is a possibility of automatic data scrolling with their selection. And scrolling speed will change 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool CanMouseTrackSelection ( ) const

Tests whether selection using the mouse is allowed.

Returns:: True - selection is allowed, false - forbidden.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void AllowFocusContext ( ContextType contextType = AllContexts )

Allows to focus lines in a given context.

Lines focusing allows to perform navigation in the grid. Particularly at KeyUp, KeyDown ... keystroke the grid allows to focus a necessary line and ensure 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool CanFocusContext ( ContextType contextType ) const

Checks if lines 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool SetFocusedRow	(	int	nRow,
		ContextType	contextType
	)

Sets a new focused line.

Parameters:

`[in]`	nRow	index of a line in the grid context. -1 means that the focus will be dropped.
`[in]`	contextType	grid context.

Returns:: True if success. Otherwise false.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

int GetFocusedRow ( ) const

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

Returns:: Index of the focused line. If there is a focus, -1 will be returned.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

ContextType GetFocusedContext ( ) const

Gets a focused grid context.

Returns:: One of grid contexts. If there is a focus, UndefinedContext will be returned.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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's location and in case of sorting moves it to the appropriate position. Moreover the grid checks whether a handle and a data object satisfy the filtration rules set in IGridFilter interface. If required the grid makes a line visible or hides it. The grid updates time stamp of the last updating for the handle corresponding to the data object what is used for automatic cell highlighting and finally redraws the cell. The same actions are made when a notification from Common::CDataObject::ISink interface has been received.

Parameters:

`[in]`	nRow	index of the line in the grid context.
`[in]`	contextType	grid context.
`[in]`	fid	field's identifier.

Thread safety:: The function is thread safe. The method of synchronization is asynchronous using PostMessage mechanism. At the same time during updating, sorting and so on the calling thread is not blocked. Such approach allows to exclude the risk of DeadLock between the calling thread and GUI thread. In case of CPreferences::MemoryBuffer mode at first unformatted value of the data object is acquired then it is transformed to a formatted string in the calling thread. Later on while sorting and drawing the GUI thread doesn't access the data object any more. All necessary data are got from the 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 in case of sorting and text updating will be performed only for one line corresponding to the given handle. Let's emphasize that notification of the grid from Common::CDataObject::ISink interface of the data object is a recommended solution.

Parameters:

`[in]`	hItem	line's handle in the grid.
`[in]`	fid	field's identifier.

Thread safety:: The function is thread safe. The method of synchronization is asynchronous using PostMessage mechanism. At the same time during updating, sorting and so on the calling thread is not blocked. Such approach allows to exclude the risk of DeadLock between the calling thread and GUI thread. In case of CPreferences::MemoryBuffer mode at first unformatted value of the data object is acquired then it is transformed to a formatted string in the calling thread. Later on while sorting and drawing the GUI thread doesn't access the data object any more. All necessary data are got from the 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 associated with a given data object handles. At the same time updates take place only in one grid. If one data object is inserted into several grids then 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 realization permits to exclude the risk of dead-lock between threads and automatically synchronize 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. The method of synchronization is asynchronous using PostMessage mechanism. At the same time during updating, sorting and so on the calling thread is not blocked. Such approach allows to exclude the risk of DeadLock between the calling thread and GUI thread. In case of CPreferences::MemoryBuffer mode at first unformatted value of the data object is acquired then it is transformed to a formatted string in the calling thread. Later on while sorting and drawing the GUI thread doesn't access the data object any more. All necessary data are got from the 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 the moment when the notification from Common::CDataObject::ISink interface has been received.

Parameters:

`[in]`	nRow	index of the line in the 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 will be returned.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

int GetTimeElapsedSinceLastUpdate	(	HITEM	hItem,
		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 the moment when the notification from Common::CDataObject::ISink interface has been received.

Parameters:

`[in]`	hItem	Line's handle in the grid. The line can be visible and invisible as well.
`[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 will be returned.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 performs no 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 during realizing line highlighting in the grid.

Parameters:

`[in]`	nRow	index of the line in the grid context.
`[in]`	contextType	grid context.
`[in]`	spanTime	The time period in milliseconds after which line redrawing will be 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 the thread different from GUI thread synchronization is carried out through 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 performs no 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 during realizing line highlighting in the grid.

Parameters:

`[in]`	hItem	Line's handle in the grid.
`[in]`	spanTime	The time period in milliseconds after which line redrawing will be 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 the thread different from GUI thread synchronization is carried out through 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 performs no 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 during realizing line highlighting in the grid.

Parameters:

`[in]`	pDO	Pointer to the data object.
`[in]`	spanTime	The time period in milliseconds after which line redrawing will be 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 the thread different from GUI thread synchronization is carried out through 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 the grid context.
`[in]`	contextType	grid context.
`[in]`	fid	field's identifier.
`[in]`	spanTime	The time period in milliseconds after which cell redrawing will be 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 the thread different from GUI thread synchronization is carried out through 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's handle in the grid.
`[in]`	fid	field's identifier.
`[in]`	spanTime	The time period in milliseconds after which cell redrawing will be 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

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

Redraws all the 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 will be 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void AllowNotifications ( bool bAllow )

The grid provides the possibility to deliver notifications to its owner by sending WM_NOTIFY messages.

In order to raise grid productivity this function permits to block the delivery of notifications. (For example when a large number 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

CAppearance & GetAppearance ( )

Gets CAppearance type object where the basic visual grid characteristics such as text, background, vertical and horizontal lines colors and so on are collected.

When values in the return object are modified CWnd::Invalidate() should be called in order the changes to be displayed 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 other thread it's better to use SetAppearance() function.

const CAppearance & GetAppearance ( ) const

Gets CAppearance type object where the basic visual grid characteristics such as text, background, vertical and horizontal lines colors and so on are collected. Const version.

When values in the return object are modified CWnd::Invalidate() should be called in order the changes to be displayed 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 other thread it's 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 the thread different from GUI thread synchronization is carried out through 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 the picture with the 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 into the grid.

Parameters:

[in] image A new background image

Thread safety:: The function is thread safe. When it is called from the non-GUI thread, synchronization is carried out through the SendMessage mechanism.

Example

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

Sets font attributes to be used for a text within the grid. Internally, the grid clones the font, and after this function has been called, you should to 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 the font 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()
{
    //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);
        
        //Increment the font's 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 an icon size doesn't fit to a cell height the icon can be stretched to be correctly placed in the grid. At data drawing given ImageList and icon's index are sent to ICustomDraw interface where the icon and whole ImageList can be changed.

Parameters:

`[in]`	imageList	A new image list.
`[in]`	stretch	Indicates whether icons should be stretched to a cell height.

Returns:: Previous ImageList value.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism. However the CImageList object is not thread safe.

void AllowStretchImageInCell ( bool stretch )

Sets the flag allowing to stretch icons in grid cells.

Parameters:

[in] stretch If true - permits to stretch icons in grid cells.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool CanStretchImageInCell ( ) const

Tests whether the flag allowing to stretch icons 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void SetContextSeparatorHeight ( int nHeight )

Sets two grid contexts separator's height.

Parameters:

[in] nHeight height of a separator between two contexts in pixels.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

int GetContextSeparatorHeight ( ) const

Gets two grid contexts separator's height.

Returns:: Height in pixels of a separator between two contexts.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void AllowHighlight ( bool bAllow )

Allows or forbids grid cells highlighting.

Highlighting is done 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 starting with simple colors inversion and ending with alpha blending on the background using a fading effect. All the information concerning 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example

//Turn on cells highlighting
m_Grid.AllowHighlight(true);

//Select the highlighting with a 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example

//Turn on cells highlighting
m_Grid.AllowHighlight(true);

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

const CHighlightSettings & GetHighlightSettings ( ) const

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

Derived parameters include colors of the front and the rear background colors, highlighting 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's better to use SetHighlightSettings() function.

Example

//Turn on cells highlighting
m_Grid.AllowHighlight(true);

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

CHighlightSettings & GetHighlightSettings ( )

Gets the highlighting parameters collected in CHighlightSettings type object.

Derived parameters include colors of the front and the rear background colors, highlighting 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's better to use SetHighlightSettings() function.

Example

//Turn on cells highlighting
m_Grid.AllowHighlight(true);

//Select the highlighting with a 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

Example

//Turn on cells highlighting
m_Grid.AllowHighlight(true);

//Select the highlighting with a 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 elements drawing.

At grid realization all cells drawing, highlighting, navigation and so on were put to the external modules that totally define one or another functionality. Particularly during drawing all necessary parameters are gathered at one place and passed to ICustomDraw interface. If the interface is not assigned then the default realization got by calling Creferences::GetDefaultCustomDraw() is applied. The mission of the interface is to transmit parameters to the appropriate graphical format that directly conducts drawing. There are two types of formats: lines drawing format and cells drawing format. Default realization of the lines drawing format includes calculation of cells sizes and transmission of the parameters to the cells drawing format through ICustomDraw. Thus ICustomDraw is the central place through which all information at grid elements drawing is passed and this 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism. It is significant that all functions of the interface are called only in GUI thread.

See also:: Read Drawing workflow and Custom drawing to get 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

See also:: Read Drawing workflow and Custom drawing to get more information about custom drawing.

void SetPaintFilter ( UINT paintFilter = defaultPaintFilter )

Sets a new graphical filter.

The filter is a list of PaintFilter type values and allows to conduct appropriate grid elements. The set filter at the moment of drawing is transmitted to ICustomDraw where it can be totally redefined. This permits to block highlighting or selection drawing for a separate 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 the thread different from GUI thread synchronization is carried out through 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 the text in the grid
    drawImage                       = 0x02,     //Draws an image in the cell
    drawHeaderImage                 = 0x04,     //Draws an image in the columns
    drawBackground                  = 0x08,     //Draws a background in the grid
    drawSelection                   = 0x10,     //Blends selection with fore and back 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 fore and back colors for selected lines.
    drawFocusedRowFrame             = 0x200,    //Draws a frame around the focused line
    drawHighlight                   = 0x400,    //Draws highlighting
    drawDropPosition                = 0x800,    //Draws indicators helping to drop a 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 one of the cell


    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 the thread different from GUI thread synchronization is carried out through 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 the text in the grid
    drawImage                       = 0x02,     //Draws an image in the cell
    drawHeaderImage                 = 0x04,     //Draws an image in the columns
    drawBackground                  = 0x08,     //Draws a background in the grid
    drawSelection                   = 0x10,     //Blends selection with fore and back 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 fore and back colors for selected lines.
    drawFocusedRowFrame             = 0x200,    //Draws a frame around the focused line
    drawHighlight                   = 0x400,    //Draws highlighting
    drawDropPosition                = 0x800,    //Draws indicators helping to drop a 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 one of the cell


    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 )

Allows to use the mechanism of double buffering in order to exclude the flicker effect at the moment of elements drawing.

However when this mode is set it can influence grid productivity. Usually it is not necessary to set this mode because an updated text practically doesn't flicker on the screen.

Parameters:

[in] enable Allows to use the mechanism of double buffering. True - double buffering is allowed, false - forbidden.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool GetFlickerFreeDrawing ( ) const

Gets the value indicating whether a double buffering mode is allowed.

Returns:: True - double buffering is allowed, false - forbidden.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

int GetOptimalRowHeight ( ContextType contextType ) const

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

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

Parameters:

[in] contextType grid context.

Returns:: Optimal value of lines height in a given grid context.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

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

Gets optimal value of a given grid cell width.

The parameters for value calculation are passed to the graphical grid cells drawing format through ICustomDraw interface. Line position in the hierarchy and also icons, area for unrolling and rolling up children and current value of graphical filter presence are taken into consideration at calculation. ICustomDraw interface can influence the calculation of the derived value. The calculated value can be used for optimization of a column size in the grid.

Parameters:

`[in]`	nRow	index of a line in the 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

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

Calculates the optimal grid column size based on the optimal sizes got for grid visible 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

CHeader * SetHeader ( CHeader * newHeader )

Sets a new header.

If sorting is set in a new header then all grid lines will be automatically sorted according to the sorting rules. Headers replacing allows to manage data objects presentation in the grid rather easy and effective. Particularly different headers can display different data objects fields or same fields but in different formats.

Parameters:

[in] newHeader A new header.

Returns:: Previous header.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void ShowHeader ( )

Makes the header visible.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void HideHeader ( )

Makes the header invisible.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void ShowHeaderDialog ( ) [virtual]

Shows the dialog allowing to configure columns of the header.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

const CColumn * GetColumn ( CPoint pt ) const

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

Parameters:

[in] pt Location in the client's 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

const CColumn * GetNavigationColumn ( ) const

Gets a navigation column.

The grid allows to perform a quick line search according to the first letters typed by the user. During letters typing their comparison with the lines values in a navigation column is conducted and in case of coincidence scrolling to the first coincidence is done. The function gets the navigation column according to which the quick lines search can be performed.

Returns:: CColumn type object if the column is found. Otherwise 0.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

const CColumn * GetHierarchicalColumn ( ) const

Gets the column that manages the grid hierarchy.

In this column the icons allowing to unroll a line and show children items are displayed. Usually this column is the first visible column in 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void AdjustColumnByFid ( Common::FID fid )

Performs column width optimization for visible grid lines.

A column width is adjusted in such a way that the grid cells in a given column haven't got partly hidden data. Data object field identifier is used to identify the column.

Parameters:

[in] fid field's identifier.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void AdjustColumnByIndex ( int index )

Performs column width optimization by its index.

A column width is adjusted in such a way that the grid cells in given column haven't got partly hidden data.

Parameters:

[in] index Zero-based column index.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 partly hidden data.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

int GetOptimalHeaderHeight ( ) const

Gets optimal header's height.

Returns:: Optimal header's height.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void EnsureColumnVisible ( Common::FID fid )

The function makes a column wholly visible in the grid.

If a column is invisible or partly visible then the grid performs horizontal scrolling in order to make given column wholly visible.

Parameters:

[in] fid field's identifier.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool IsTooltipEnabled ( ) const

Returns the value indicating whether tooltip displaying is allowed.

Returns:: True - tooltips are allowed, false - forbidden.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

ITooltipCtrl * SetTooltipCtrl ( ITooltipCtrl * control )

Sets new ITooltipCtrl interface to control the tooltip window.

GUI library provides two realizations of the tooltip made 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

const ITooltip * GetTooltip ( ) const

Gets the interface controlling the tooltip content.

To display the tooltip it is not necessary to implement this interface because ITooltipCtrl provides default realization of this interface. If it is required to redefine an outputted text the programmer can give his 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

const CTooltipSettings & GetTooltipSettings ( ) const

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

Returns:: Tooltip settings

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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's 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 the thread different from GUI thread synchronization is carried out through 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's 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void EnableInPlaceTooltip ( bool bEnable = true )

Allows to show the tooltip above grid cells when a cell size is not enough for displaying a text.

In case if a grid cell size is not enough for displaying a text then the 'embedded' tooltip allows to display a hidden text partly or wholly in the window located exactly above the grid cell keeping a size and style of the outputted text. This kind of tooltip is shown on the screen automatically in case of a invisible or partly visible text.

Parameters:

[in] bEnable True - tooltips are allowed, false - forbidden.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

CTooltipSettings & GetInPlaceTooltipSettings ( )

Gets the tooltip settings determinant how the grid should show the tooltip above the grid cells when a cell size is not enough for displaying a text.

Returns:: Settings collected in CTooltipSettings class object.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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's better to use SetInPlaceTooltipSettings() function.

void SetInPlaceTooltipSettings ( const CTooltipSettings & settings )

Sets the new settings determinant how the grid should show the tooltip above the grid cells when a cell size is not enough for displaying a text.

Parameters:

[in] settings Settings collected in CTooltipSettings class object.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

const ITooltipCtrl * GetInPlaceTooltipCtrl ( ) const

Gets the current tooltip control used by the grid when a cell size is not enough for displaying a 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

ITooltipCtrl * SetInPlaceTooltipCtrl ( ITooltipCtrl * control )

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

CInPlaceTooltipCtrl is the default realization 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool Copy ( )

Copies selection to the clipboard.

The copy 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool Paste ( )

Inserts elements into the grid to the located after the focused line place.

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

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

bool Paste	(	HITEM	hParent,
		HITEM	hInsertAfter
	)

Pastes data from the clipboard to a given position.

Parameters:

[in] hParent Parent to which the attachment can be 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 a data object will be 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 in case of successful operation. Otherwise - false.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

const CCopyPasteSettings & GetCopyPasteSettings ( ) const

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

Returns:: Settings collected in CCopyPasteSettings class object.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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's better to use SetCopyPasteSettings() function.

CCopyPasteSettings & GetCopyPasteSettings ( )

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

Returns:: Settings collected in CCopyPasteSettings class object.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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's better to use SetCopyPasteSettings() function.

void SetCopyPasteSettings ( const CCopyPasteSettings & settings )

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

Parameters:

[in] settings New settings to be used at copy/paste operations.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void AllowCopyPaste ( bool bAllow )

Allows or forbids to use copy/paste.

Parameters:

[in] bAllow Enables to use copy/paste.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

IDragDrop * SetDragDrop ( IDragDrop * dragDrop )

Sets new IDragDrop interface. At the same time the function 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through 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's 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 the thread different from GUI thread synchronization is carried out through 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's 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void AllowDragAndDrop ( bool bAllow )

Allows or forbids drag&drop in the grid.

Parameters:

[in] bAllow Enables to use drag&drop.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

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

Helper which allows to create an image while grid content dragging.

For more visualization the grid provides the possibility to use an image of transferred data. As a result the function returns CDragImage type object containing the image as CImageList object and the cursor's 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void AllowSort ( bool bEnable )

Allows or forbids 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void SetSortedContext ( ContextType contextType = AllContexts )

Sets the 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

ContextType GetSortedContext ( ) const

Gets the 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void ResetSort ( bool redraw = true )

Cancels sorting.

Parameters:

[in] redraw If the redraw flag is set for true then the grid will be redrawn.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 permits to set sorting for a given level. Levels of sorting must be set in order without leaps. There is a possibility to start the process after all levels of sorting have been 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

CSortInfo GetSort ( int level ) const

Gets information about sorting for a given level.

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

Returns:: Information about sorting for a given level.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

void UpdateSort ( )

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

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

IGridFilter * SetFilter ( IGridFilter * filter )

Sets a new filter.

At the same time the function 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through SendMessage mechanism.

IKeyManager * SetKeyManager ( IKeyManager * keyManager )

Sets a new keyboard manager to control the grid.

At the same time the function 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 the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through 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 will be forbidden in both contexts.

Thread safety:: The function is thread safe. When it is called from the thread different from GUI thread synchronization is carried out through 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 the thread different from GUI thread synchronization is carried out through 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, which carries out movements of the grid lines focus and selection changing according to the specified values of bShift and bCtrl. In case if the keyboard manager is not set then 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 the thread different from GUI thread synchronization is carried out through 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, which carries out movements of the grid lines focus and selection changing according to the specified values of bShift and bCtrl. In case if the keyboard manager is not set then 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 the thread different from GUI thread synchronization is carried out through 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, which carries out movements of the grid lines focus and selection changing according to the specified values of bShift and bCtrl. In case if the keyboard manager is not set then 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 the thread different from GUI thread synchronization is carried out through 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, which carries out movements of the grid lines focus an