Dapfor MFC Grid manual

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

Adds a data object to the grid.

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

Parameters:

[in] pDO added data object

[in]

hParent

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

GI_SCROLLABLE_ROOT	A data object is added to the first level of the hierarchy and is scrollable
GI_FIXED_ROOT	A data object is added to the first level of the hierarchy and is not scrollable
HITEM	Any handle acquired before addition to the grid.

[in]

hInsertAfter

a value used to specify location of an insertion. If sorting is switched on, this parameter doesn't have any meaning because a data object is inserted according to the sorting rules. If there is no sorting hInsertAfter can have the following values:

GI_FIRST	Insertion to the beginning
GI_LAST	Insertion to the end
HITEM	Insertion after a given handle

Returns:: If a handle is added successfully, it returns unique data object position in the grid. Otherwise '0' is returned.

thread-safety: The function is thread-safe. When it is called from a non-GUI thread, synchronization is performed via SendMessage mechanism. If MemoryBuffer mode is used then all formatted and unformatted data in a calling thread is copied and forwarded to GUI thread.

Example

 class CAuthor : public Dapfor::Common::CDataObject
 { 
    ...
    CString GetFirstName() const;
    CString GetLastName() const;
    ...
 };

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

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

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

 //The following code 'frezes' the author i.e. adds an author to fixed context:
 m_Grid.Add(new CAuthor(...), Dapfor::GUI::GI_FIXED_ROOT);

See also:: Read the How to compile my first application? article for step-by-step instructions on building an application. You can find more information about the data object here.

bool Delete ( HITEM hItem )

Deletes an item from the grid.

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

Parameters:

[in] hItem handle that has to be deleted.

Returns:: True if the handle has been successfully deleted. Otherwise - false.

thread-safety: The function is thread-safe. When it is called from a non-GUI thread synchronization is performed through SendMessage mechanism.

Example

 //Add an object to the grid
 CSomeClass* someObject = new CSomeClass(...);
 Dapfor::GUI::HITEM hItem = m_Grid.Add(someObject);

 ...

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

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

See also:: Read the How to compile my first application? article for step-by-step instructions on application building. You can find more information about a data object here.

int Delete ( const Common::CDataObject * pDO )

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

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

Parameters:

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

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

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

Example

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

 ...

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

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

bool Delete	(	int	nRow,
		ContextType	contextType = `ScrollableContext`
	)

Deletes a visible line from a given data context.

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

Parameters:

`[in]`	nRow	index of a visible line which starts from 0.
`[in]`	contextType	type of a data context. Available values: FixedContext, ScrollableContext. For AllContexts the grid is trying to delete the given line in every context.

Returns:: True if the given line has been successfully deleted. Otherwise - false.

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

Example

 //Remove the first non-scrollable row (indices start from 0) with all children. 
 //Note that the call does not destroy the data object. 
 m_Grid.Delete(0, Dapfor::GUI::FixedContext);

void DeleteAll ( ContextType contextType = AllContexts )

Deletes all data from a given context.

Parameters:

[in] contextType type of a data context. Available values: FixedContext, ScrollableContext, AllContexts.

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

Example

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

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

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

Gets all handles corresponding to a given data object.

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

Parameters:

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

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

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

Example

 //Gets all rows visible in the grid (scrollable and non-scrollable) corresponding to the specified data object
 Dapfor::GUI::Handles& handles = m_Grid.GetHandles(root, true);
 
 //Gets all visible and invisible (filtered or collapsed) non-scrollable rows 
 //that correspond to the specified data object
 Dapfor::GUI::Handles& handles = m_Grid.GetHandles(root, false, Dapfor::GUI::FixedContext);

Handles GetHandles ( ContextType contextType = AllContexts ) const

Get a copy of all handles inserted into the grid.

Parameters:

[in] contextType type of context where handles is searched. Available values: FixedContext, ScrollableContext, AllContexts.

Returns:: a copy of handles, stored in the grid.

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

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

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

Parameters:

[in] hItem Handle to be attached.

[in] hParent Parent, to which the attachment is done. Any got in Add() function value or one of the following contexts: GI_SCROLABLE_ROOT or GI_FIXED_ROOT can be a parent.

[in]

hInsertAfter

the value used to specify location of the insertion. If sorting is switched on then this parameter doesn't have any meaning because the data object is inserted according to the sorting rules. If there is no sorting hInsertAfter can have the following values:

GI_FIRST	Insertion to the beginning
GI_LAST	Insertion to the end
HITEM	Insertion after a given handle

Returns:: True for successful operation. Otherwise - false. The function can complete unsuccessfully if hItem has not been previously detached or hParent and hInsertAfter values are incorrect.

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

bool Detach ( HITEM hItem )

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

Parameters:

[in] hItem Handle to be detached.

Returns:: True for a successful operation. Otherwise - false.

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

bool Exists ( HITEM hItem ) const

Checks whether a given handle is attached to the grid.

Parameters:

[in] hItem Handle to be verified

Returns:: True if the handle has already been added to the grid and actually attached to it. Otherwise false.

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

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

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

Parameters:

[in] pDO data object to be verified

Returns:: True if at least one handle is found in the grid. Otherwise - False.

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

unsigned int GetRowCount ( ContextType contextType = ScrollableContext ) const

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

The search can be performed in one or both contexts.

Parameters:

[in] contextType Type of the context where the search is performed. Available values: FixedContext, ScrollableContext, AllContexts.

Returns:: Counted number of visible grid lines.

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

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

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

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

Parameters:

`[in]`	functional	Functional where all found handles and data objects are handed over to.
`[in]`	startFrom	handle from which the search starts. Available values: GI_FIRST, GI_FIXED_ROOT, GI_SCROLLABLE_ROOT, any inserted onto the grid handle. If GI_FIRST is used, the search starts from fixed context, and if it has no elements - from scrollable context.

thread-safety: The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. It is important that at multi-threaded applications search and transmission of handles and data objects are always performed in GUI thread. If the function is called from another thread, the calling thread is blocked until it is returned by the function.

#include <Dapfor/GUI/IForEach.h>

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

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

        //Continue iterations
        return true;
    }

private:
    int m_VisibleRows;
    int m_InvisibleRows;
};


//How to use:

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

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

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

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

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

Parameters:

`[in]`	functional	Functional where all found handles and data objects are handed over to.
`[in]`	startFrom	handle from which the search starts. Available values: GI_FIRST, GI_FIXED_ROOT, GI_SCROLLABLE_ROOT, any value inserted to grid handle. If GI_FIRST is used then the search starts from fixed context, and if it has no elements then from scrollable context.

thread-safety: The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. It is significant that at multithread applications realization the search and transmission of handles and data objects are always performed in GUI thread. If the function is called from other thread, the calling thread is blocked until it is returned by the function.

#include <Dapfor/GUI/IForEach.h>

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

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

        //Continue iterations
        return true;
    }

private:
    int m_VisibleRows;
    int m_InvisibleRows;
};


//How to use:

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

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

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

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

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

Parameters:

[in] movingItem Moved handle.

[in]

parentPosition

Parent, to which the moved handle is attached. The parent must not be a direct or indirect child of the moved handle. Available values:

0	Moving within a single parent
GI_SCROLLABLE_ROOT	Moving to the highest level of the hierarchy in scrollable context
GI_FIXED_ROOT	Moving to the highest level of the hierarchy in fixed context

[in]

position

Position before which the handle is inserted. Available values:

GI_FIRST	Insertion to the first position
GI_LAST	Insertion before the last position
HITEM	Insertion before a given handle

Returns:: True if the handle has been successfully moved. Otherwise false.

thread-safety

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

    //Get a handle that corresponds to the specified data object
    Dapfor::Common::CDataObject* pDO = ...;
    Dapfor::GUI::HITEM hItem = m_Grid.GetItem(pDO);
   
    //'Freeze' the item. i.e. move to fixed context
    m_Grid.MoveAfter(hItem, Dapfor::GUI::GI_FIXED_ROOT, Dapfor::GUI::GI_LAST);

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

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

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

Parameters:

[in] movingItem Moved handle.

[in]

parentPosition

Parent to which the moved handle is attached. The parent must not be a direct or indirect child of the moved handle. Available values:

0	Moving within one parent
GI_SCROLLABLE_ROOT	Moving to the highest level of the hierarchy in scrollable context
GI_FIXED_ROOT	Moving to the highest level of the hierarchy in fixed context

[in]

position

Position after which the handle is inserted. Available values:

GI_FIRST	Insertion to the first position
GI_LAST	Insertion after the last position
HITEM	Insertion after a given handle

Returns:: True if the handle has been successfully moved. Otherwise false.

thread-safety

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

    //Get a handle that corresponds to the specified data object
    Dapfor::Common::CDataObject* pDO = ...;
    Dapfor::GUI::HITEM hItem = m_Grid.GetItem(pDO);
   
    //'Freeze' the item. i.e. move to fixed context
    m_Grid.MoveAfter(hItem, Dapfor::GUI::GI_FIXED_ROOT, Dapfor::GUI::GI_LAST);

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

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

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

Parameters:

`[in]`	hItem	line handle in the grid. The line can be visible or invisible.
`[in]`	fid	field identifier.

Returns:: Requested value in case of success. If a data object field is not found, Common::CValue with Common::Undefined identifier is returned.

thread-safety: The function is thread-safe. When it is called from a thread other than GUI thread synchronization is performed via SendMessage mechanism. Its worth mentioning that in CPreferences::DirectCall mode data object values are always requested in GUI thread even if the function is called in other thread.

Example

//Declaration of a data object

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

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

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



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

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


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


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

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


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

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

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

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

Sets a new value for the data object.

Parameters:

`[in]`	hItem	line handle in the grid. The line can be visible or invisible.
`[in]`	fid	Field's identifier.
`[in]`	value	New value that is set for the data object.

Returns:: True, if the value has been set. Otherwise - false.

thread-safety: The function is thread-safe. When it is called from a thread other than GUI thread synchronization is performed via SendMessage mechanism. Regardless of thread-safety mode, the function accesses the data object to modify its value. Access and value modification are always performed in GUI thread. If the data object is supposed to be used in multi-threaded applications, its internal data should be protected with critical sections or mutexes.

Example

//Declaration of a data object

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

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

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



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

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


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


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

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


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

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

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

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

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

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

Parameters:

`[in]`	hItem	line handle in the grid. The line can be visible or invisible.
`[in]`	fid	Field's identifier.
`[in]`	format	The format that is used for formatting value in the string. If the format is not specified, search is conducted as follows: Firstly, the format is searched in object of CColumn class. If it is not found, the format is searched in data object Common::CFieldMap. If the format is not defined after that, the default format returned by Common::CFormat::GetDefaultFormat() function is selected.

thread-safety: The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. It's worth mentioning that in CPreferences::DirectCall mode data object values are always requested in GUI thread, even if the function is called in another thread.

Example

//Declaration of a data object

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

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

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



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

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


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


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

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


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

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

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

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

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

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

Parameters:

`[in]`	hItem	line handle in the grid. The line can be visible or invisible.
`[in]`	fid	Field's identifier.
`[in]`	str	Unformatted string.
`[in]`	format	The format to convert a formatted string into value

Returns:: True, if the value has been set. Otherwise - false.

thread-safety: The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. Regardless of thread-safety mode, the function accesses the data object to modify its value. Access and value modification are always performed in GUI thread. String is always converted into a value in GUI thread. If the data object is supposed to be used in multi-threaded applications, its internal data should be protected with critical sections or mutexes.

Example

//Declaration of a data object

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

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

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



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

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


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


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

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


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

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

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

bool IsExpanded ( HITEM hItem ) const

Gets the value specifying whether the line is expanded.

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

Parameters:

[in] hItem line handle in the grid. The line can be visible or invisible.

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

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

Handles GetChildren	(	HITEM	hItem,
		bool	visibleOnly
	)			const

Gets handles of all children of a given parent.

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

Parameters:

[in]

hItem

line handle in the grid. Available for handle values:

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

[in] visibleOnly flag pointing that derivable handles is visible on the screen, i.e. not hidden by parent and not filtered.

Returns:: List of found children for a given parent.

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

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

bool HasChildren ( HITEM hItem ) const

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

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

Parameters:

[in]

hItem

line handle in the grid. Available for handle values:

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

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

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

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

int GetHierarchicalLevel ( HITEM hItem ) const

Gets hierarchical level of a given line.

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

Parameters:

[in] hItem line handle in the grid. The line can be visible or invisible.

Returns:: Hierarchical level in the grid.

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

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

HITEM GetParent ( HITEM hItem ) const

Gets the parent to which a line is attached.

Parameters:

[in] hItem line handle in the grid. The line can be visible or invisible. Any value received from Add function can be used as a parameter.

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

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

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

void Expand	(	HITEM	hItem,
		bool	withChildren
	)

Expands a line.

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

Parameters:

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

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

Example

This example explains how to expand or collapse items in the grid

CMyClass* myObject = new CMyClass(...);
Dapfor::GUI::HITEM hItem = m_Grid.Add(myObject);

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

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


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

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

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

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

Parameters:

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

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

Example

This example shows how to expand or collapse items in the grid

CMyClass* myObject = new CMyClass(...);
Dapfor::GUI::HITEM hItem = m_Grid.Add(myObject);

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

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


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

void Collapse	(	HITEM	hItem,
		bool	withChildren
	)

Collapses a line.

All children of the line become invisible.

Parameters:

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

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

Example

This example shows how to expand or collapse items in the grid

CMyClass* myObject = new CMyClass(...);
Dapfor::GUI::HITEM hItem = m_Grid.Add(myObject);

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

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


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

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

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

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

Parameters:

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

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

Example

This example shows how to expand or collapse items in the grid

CMyClass* myObject = new CMyClass(...);
Dapfor::GUI::HITEM hItem = m_Grid.Add(myObject);

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

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


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

int GetRow ( HITEM hItem ) const

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

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

Parameters:

[in] hItem line handle in the grid.

Returns:: Line index in the grid, if the handle is found and the line is not hidden (not filtered and not hidden by its parents). Otherwise - 1. To know the index of what context is returned, you may call GetContextType() function.

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

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

int GetRow ( const Common::CDataObject * pDO ) const

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

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

Parameters:

[in] pDO Pointer to the data object

Returns:: Line index in the grid if the handle is found and the line is not hidden (not filtered and not hidden by its parents). Otherwise - 1. To know the index of what context is returned, you may call GetContextType() function.

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

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

ContextType GetContextType ( HITEM hItem ) const

Gets grid context, where a given handle belongs.

Parameters:

[in] hItem line handle in the grid. The line can be visible or invisible.

Returns:: The context, where the handle is inserted, if the handle is found. UndefinedContext if the line has been previously detached or is not found.

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

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

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

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

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

Parameters:

[in] pDO Pointer to the data object

Returns:: Gets grid context� �� the first encountered handle corresponding to a given data object is inserted. The search starts from fixed context and continues in scrollable context. If the handle is filtered or hidden by its parents, UndefinedContext is returned.

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

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

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

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

Parameters:

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

Returns:: Line handle if it is found. Otherwise - 0.

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

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

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

Gets the first encountered handle for a given data object.

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

Parameters:

[in] pDO Pointer to the data object

Returns:: Line handle if it is found. Otherwise - 0.

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

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

HITEM GetItem ( CPoint point ) const

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

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

Parameters:

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

Returns:: Line handle if the line is found. Otherwise - 0.

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

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

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

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

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

Parameters:

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

Returns:: Line handle if the line is found. Otherwise - 0.

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

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

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

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

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

Parameters:

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

Returns:: Line handle if the line is found. Otherwise - 0.

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

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

Common::CDataObject * GetDataObject ( HITEM hItem )

Gets the data object corresponding to a given handle.

Parameters:

[in] hItem hItem line handle in the grid. The line can be visible or invisible.

Returns:: Pointer to the data object if it is found. Otherwise - 0.

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

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

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

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

Parameters:

[in] hItem hItem line handle in the grid. The line can be visible or invisible.

Returns:: Pointer to the data object if it has been found. Otherwise - 0.

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

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

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

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

Parameters:

`[in]`	nRow	index in grid context.
`[in]`	contextType	grid context.

Returns:: const pointer to the data object if success. Otherwise 0.

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

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

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

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

Parameters:

`[in]`	nRow	index in grid context.
`[in]`	contextType	grid context.

Returns:: const pointer to the data object if success. Otherwise 0.

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

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

int GetFirstVisibleRow ( ) const

Gets the first visible line in scrollable context.

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

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

Example: See more on computing visible and virtual bounds of rows/cells

int GetLastVisibleRow ( ContextType contextType = ScrollableContext ) const

Gets the last visible line in a given context.

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

Parameters:

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

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

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

Example: See more on computing visible and virtual bounds of rows/cells

void SetFirstVisibleRow ( int nRow )

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

Parameters:

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

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

Example: See more on computing visible and virtual bounds of rows/cells

void SetFirstVisibleItem ( HITEM hItem )

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

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

Parameters:

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

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

Example: See more on computing visible and virtual bounds of rows/cells

void SetFirstVisibleItem ( const Common::CDataObject * pDO )

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

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

Parameters:

[in] pDO Pointer to the data object.

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

Example: See more on computing visible and virtual bounds of rows/cells

void EnsureVisible ( int nRow )

Makes a given line visible in scrollable context.

Parameters:

[in] nRow Index of the row in the scroollable area.

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

See also:: IsInVisibleRect()

Example: See more on computing visible and virtual bounds of rows/cells

void EnsureVisible ( HITEM hItem )

Makes a given handle visible in scrollable context.

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

Parameters:

[in] hItem Handle that is to be visible

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

Example: See more on computing visible and virtual bounds of rows/cells

void EnsureVisible ( const Common::CDataObject * pDO )

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

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

Parameters:

[in] pDO Pointer to the data object.

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

Example: See more on computing visible and virtual bounds of rows/cells

bool IsVisible ( HITEM hItem ) const

Checks whether a given handle is visible in the grid.

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

Parameters:

[in] hItem line handle in the grid.

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

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

Example: See more on computing visible and virtual bounds of rows/cells

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

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

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

Parameters:

[in] pDO Pointer to the data object.

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

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

Example: See more on computing visible and virtual bounds of rows/cells

bool IsInVisibleRect ( HITEM hItem )

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

Parameters:

[in] hItem Handle that is to be checked

Returns:: True if at least a part of the given line is visible. Otherwise - false.

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

Example: See more on computing visible and virtual bounds of rows/cells

bool IsInVisibleRect ( const Common::CDataObject * pDO )

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

Parameters:

[in] pDO Pointer to the data object.

Returns:: True if at least a part of given line is visible. Otherwise - false.

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

Example: See more on computing visible and virtual bounds of rows/cells

bool IsInVisibleRect	(	int	nRow,
		ContextType	contextType
	)

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

Parameters:

`[in]`	nRow	index in grid context.
`[in]`	contextType	grid context.

Returns:: True if at least a part of the given line is visible. Otherwise - false.

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

Example: See more on computing visible and virtual bounds of rows/cells

CRect GetContextVisibleRect ( ContextType contextType ) const

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

Parameters:

[in] contextType type of grid context. Available values: FixedContext and ScrollableContext.

Returns:: Visible rectangle occupied by a given grid context.

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

Example: See more on computing visible and virtual bounds of rows/cells

CRect GetContextVirtualRect ( ContextType contextType ) const

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

Parameters:

[in] contextType type of grid context. Available values: FixedContext and ScrollableContext.

Returns:: Visible rectangle occupied by a given grid context.

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

Example: See more on computing visible and virtual bounds of rows/cells

CRect GetLineVisibleRect ( HITEM hItem ) const

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

Parameters:

[in] hItem handle of a visible line in any context.

Returns:: Visible area occupied by the grid line.

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

Example: See more on computing visible and virtual bounds of rows/cells

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

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

Parameters:

[in] pDO Pointer to the data object.

Returns:: Visible area occupied by the grid line.

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

Example: See more on computing visible and virtual bounds of rows/cells

CRect GetLineVirtualRect ( HITEM hItem ) const

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

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

Parameters:

[in] hItem handle of a visible line in any context.

Returns:: Visible area occupied by the grid line.

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

Example: See more on computing visible and virtual bounds of rows/cells

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

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

Parameters:

[in] pDO Pointer to the data object.

Returns:: Visible area occupied by the grid line.

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

Example: See more on computing visible and virtual bounds of rows/cells

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

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

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

Parameters:

`[in]`	hItem	handle of a visible line in any context.
`[in]`	fid	field's identifier.

Returns:: Visible area occupied by the grid cell.

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

Example: See more on computing visible and virtual bounds of rows/cells

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

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

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

Parameters:

`[in]`	pDO	Pointer to the data object.
`[in]`	fid	field identifier.

Returns:: Visible area occupied by grid cell.

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

Example: See more on computing visible and virtual bounds of rows/cells

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

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

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

Parameters:

`[in]`	hItem	handle of a visible line in any context.
`[in]`	fid	field's identifier.

Returns:: Virtual area occupied by the grid cell.

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

Example: See more on computing visible and virtual bounds of rows/cells

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

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

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

Parameters:

`[in]`	pDO	Pointer to the data object.
`[in]`	fid	field's identifier.

Returns:: Virtual area occupied by the grid cell.

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

Example: See more on computing visible and virtual bounds of rows/cells

int GetLinesPerPage ( bool forward = true ) const

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

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

Parameters:

[in] forward If the value is 'true', calculation is performed starting from the first visible index with index increase. Otherwise the number of lines per page is calculated in descending order starting from the first visible line.

Returns:: The number of fully visible lines per page.

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

Example: See more on computing visible and virtual bounds of rows/cells

int GetItemHeight ( HITEM hItem ) const

Gets height of the line corresponding to a given handle.

Parameters:

[in] hItem line handle in the grid. The line can be visible or invisible.

Returns:: line height

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

Example: See more on computing visible and virtual bounds of rows/cells

void SetItemHeight	(	HITEM	hItem,
		int	height
	)

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

Parameters:

`[in]`	hItem	line handle in the grid.
`[in]`	height	a new height of the line.

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

void AllowSelection ( bool bEnable )

Enables selection in the grid.

Parameters:

[in] bEnable Sets selection in the grid. True - selection is allowed, false - forbidden.

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

bool CanSelect ( ) const

Defines whether line selection in the grid is allowed.

Returns:: True if selection is allowed. Otherwise - false.

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

void AllowMultiSelection ( bool bEnable )

Enables selection of multiple lines in the grid.

Parameters:

[in] bEnable If true, the grid enables selection of multiple lines at once. Otherwise only one line can be selected.

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

bool CanMultiSelect ( ) const

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

Returns:: True if multi-selection is allowed. Otherwise - false.

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

void AllowSelectContext ( ContextType contextType = AllContexts )

Sets grid context where selection is allowed.

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

Parameters:

[in] contextType grid context. Available values: UndefinedContext, FixedContext, ScrollableContext, AllContexts.

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

bool CanSelectContext ( ContextType contextType ) const

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

Parameters:

[in] contextType grid context. Available values: FixedContext, ScrollableContext.

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

int GetSelectedCount ( ) const

Gets the total number of selected lines in the grid.

Returns:: Number of selected lines in the grid.

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

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

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

Parameters:

`[in]`	nRow	index of the line in grid context.
`[in]`	contextType	grid context.
`[in]`	bSelect	points whether a given line should be selected or selection should be cancelled. If true, the grid tries to perform selection.

Returns:: True if the value has been successfully set. Otherwise - false.

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

bool Select	(	HITEM	hItem,
		bool	bSelect
	)

Enables selection of a line by its handle.

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

Parameters:

`[in]`	hItem	line handle in the grid.
`[in]`	bSelect	points whether a given line should be selected or whether selection should be cancelled. If true, the grid tries to perform selection.

Returns:: True if the value has been successfully set. Otherwise - false.

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

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

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

Parameters:

`[in]`	pDO	Pointer to the data object.
`[in]`	bSelect	points whether a given line should be selected or whether selection should be cancelled. If true, the grid tries to do selection.

Returns:: True if the value has been successfully set. Otherwise - false.

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

Selection GetSelection ( ContextType contextType ) const

Gets a list of selected handles.

Parameters:

[in] contextType The context where the search is conducted. Available values: FixedContext, ScrollableContext, AllContexts.

Returns:: Returned container contains a list of selected grid lines.

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

bool IsSelected	(	int	nRow,
		ContextType	contextType
	)			const

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

Parameters:

`[in]`	nRow	index of the line in grid context.
`[in]`	contextType	grid context.

Returns:: True the line if selected. If the line is not selected or out of range - false.

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

bool IsSelected ( HITEM hItem ) const

Tests whether the line with a specified handle is selected.

Parameters:

[in] hItem line handle in the grid. The line can be visible or invisible.

Returns:: True the line if selected. If the handle is not selected or not found - false.

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

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

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

Parameters:

[in] pDO Pointer to the data object.

Returns:: True the line if selected. If the handle is not selected or not found - false.

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

void SelectAll ( )

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

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

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

void ClearSelection ( )

Selects all lines in the grid.

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

void AllowMouseTrackSelection ( bool bEnable )

Enables selection with a mouse.

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

Parameters:

[in] bEnable True if enable. Otherwise false.

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

bool CanMouseTrackSelection ( ) const

Tests whether mouse selection is allowed.

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

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

void AllowFocusContext ( ContextType contextType = AllContexts )

Enables focusing lines in a given context.

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

Parameters:

[in] contextType grid context. Available values: UndefinedContext, FixedContext, ScrollableContext, AllContexts.

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

bool CanFocusContext ( ContextType contextType ) const

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

Parameters:

[in] contextType grid context. Available values: FixedContext, ScrollableContext

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

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

bool SetFocusedRow	(	int	nRow,
		ContextType	contextType
	)

Sets a new focused line.

Parameters:

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

Returns:: True if success. Otherwise false.

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

int GetFocusedRow ( ) const

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

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

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

ContextType GetFocusedContext ( ) const

Gets a focused grid context.

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

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

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

Informs the grid about changing of a data object.

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

Parameters:

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

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

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

Informs the grid that a given handle has been updated.

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

Parameters:

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

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

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

Informs the grid that a data object has been updated.

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

Parameters:

`[in]`	pDO	Pointer to the data object.
`[in]`	fid	field's identifier.

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

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

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

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

Parameters:

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

Returns:: Time in milliseconds elapsed since the last update. If the line is not found or has not been updated -1 is returned.

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

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

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

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

Parameters:

`[in]`	hItem	line handle in the grid. The line can be visible or invisible.
`[in]`	fid	field's identifier.

Returns:: Time in milliseconds elapsed since the last update. If the line is not found or has not been updated -1 is returned.

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

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

Redraws a line in the grid.

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

Parameters:

`[in]`	nRow	index of the line in grid context.
`[in]`	contextType	grid context.
`[in]`	spanTime	The time period in milliseconds after which line redrawing is requested. If this value is equal to 0 then the request is sent immediately.

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

void InvalidateRow	(	HITEM	hItem,
		int	spanTime = `0`
	)

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

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

Parameters:

`[in]`	hItem	line handle in the grid.
`[in]`	spanTime	The time period in milliseconds after which line redrawing is requested. If this value is equal to 0 then the request is sent immediately.

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

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

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

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

Parameters:

`[in]`	pDO	Pointer to the data object.
`[in]`	spanTime	The time period in milliseconds after which line redrawing is requested. If this value is equal to 0 then the request is sent immediately.

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

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

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

Parameters:

`[in]`	nRow	index of the line in grid context.
`[in]`	contextType	grid context.
`[in]`	fid	field's identifier.
`[in]`	spanTime	The time period in milliseconds after which cell redrawing is requested. If this value is equal to 0, the request is sent immediately.

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

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

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

Parameters:

`[in]`	hItem	line handle in the grid.
`[in]`	fid	field's identifier.
`[in]`	spanTime	The time period in milliseconds after which cell redrawing is requested. If this value is equal to 0, the request is sent immediately.

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

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

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

Parameters:

`[in]`	pDO	Pointer to the data object.
`[in]`	fid	field's identifier.
`[in]`	spanTime	The time period in milliseconds after which cell redrawing is requested. If this value is equal to 0, the request is sent immediately.

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

void AllowNotifications ( bool bAllow )

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

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

Parameters:

[in] bAllow Allows to send notifications. True - sending is allowed, false - forbidden.

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

bool IsNotificationsAllowed ( ) const

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

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

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

CAppearance & GetAppearance ( )

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

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

Returns:: Grid's appearance.

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

const CAppearance & GetAppearance ( ) const

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

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

Returns:: Grid's appearance.

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

void SetAppearance ( const CAppearance & appearance )

Sets a new grid appearance.

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

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

const CBackgroundImage & GetBackgroundImage ( ) const

Gets a background image of the grid.

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

Returns:: reference to the background image.

thread-safety:: The function is thread-safe. Synchronization method is SendMessage. However CBackgroundImage object is not thread-safe.

Example

void SetBackgroundImage ( const CBackgroundImage & image )

Sets a new background image for the grid.

Parameters:

[in] image A new background image

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

Example

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

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

Parameters:

`[in]`	font	A new font.
`[in]`	bRedraw	value indicating that the grid should be redrawn.

thread-safety:: The function is not thread-safe.

Example:

This example demonstrates how to increase or decrease font size in the grid

//File MyView.h

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





//File MyView.cpp

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

...

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

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



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

CFont * GetFont ( ) const

Gets the current font used in the grid.

Returns:: Current used font.

thread-safety:: The function is not thread-safe.

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

Sets new ImageList to display icons within grid cells.

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

Parameters:

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

Returns:: Previous ImageList value.

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

CImageList * GetImageList ( ) const

Gets the current ImageList value used by the grid.

Returns:: Current ImageList value.

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

void AllowStretchImageInCell ( bool stretch )

Sets the flag that enables icon stretching in grid cells.

Parameters:

[in] stretch If true - enables stretching of icons in grid cells.

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

bool CanStretchImageInCell ( ) const

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

Returns:: True if the grid can stretch icons. Otherwise - false.

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

void AllowDrawContextSeparator ( bool bDraw )

Allows drawing of a separator between two grid contexts.

Parameters:

[in] bDraw True if the grid can draw a separator between two grid contexts

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

bool CanDrawContextSeparator ( ) const

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

Returns:: True if drawing of a separator between two grid contexts is allowed. Otherwise false.

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

void SetContextSeparatorHeight ( int nHeight )

Sets height of separator between two grid contexts.

Parameters:

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

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

int GetContextSeparatorHeight ( ) const

Gets height of separator between two grid contexts.

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

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

void AllowHighlight ( bool bAllow )

Enables or disables grid cells highlighting.

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

Parameters:

[in] bAllow Allows grid cells highlighting. True - highlighting is allowed, false - forbidden.

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

Example

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

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

bool CanHighlight ( ) const

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

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

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

Example

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

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

const CHighlightSettings & GetHighlightSettings ( ) const

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

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

Returns:: Current highlighting parameters.

thread-safety:: Function call is thread-safe. Synchronization method is SendMessage. However CHighlightSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other threads, it is better to use SetHighlightSettings() function.

Example

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

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

CHighlightSettings & GetHighlightSettings ( )

Gets highlighting parameters collected in CHighlightSettings type object.

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

Returns:: Current highlighting parameters.

thread-safety:: Function call is thread-safe. Synchronization method is SendMessage. However CHighlightSettings object is not thread-safe. That's why it is recommended to change return object values only in GUI thread. If it is necessary to make changes from other threads, it is better to use SetHighlightSettings() function.

Example

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

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

void SetHighlightSettings ( const CHighlightSettings & settings )

Sets new parameters of highlighting in the grid.

Parameters:

[in] settings New highlighting parameters.

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

Example

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

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

ICustomDraw * SetCustomDraw ( ICustomDraw * customDraw )

Sets a new interface to specify grid element drawing.

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

Parameters:

[in] customDraw New interface to specify grid elements drawing.

Returns:: Previous drawing interface.

thread-safety:: The function is thread-safe. When it is called from a thread other than GUI thread, synchronization is performed via SendMessage mechanism. It is important that all functions of the interface are called only in GUI thread.

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

ICustomDraw * GetCustomDraw ( ) const

Gets current ICustomDraw interface.

Returns:: Current drawing interface if it exists. Otherwise 0.

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

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

void SetPaintFilter ( UINT paintFilter = defaultPaintFilter )

Sets a new graphical filter.

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

Parameters:

[in] paintFilter A new paint filter. Set of PaintFilter enumeration.

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

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

Example

//This filter is defined in the Dapfor/GUI/Types.h file
enum PaintFilter    
{
    drawNothing                     = 0x00,     //Draws nothing
    drawText                        = 0x01,     //Draws text in the grid
    drawImage                       = 0x02,     //Draws image in a cell
    drawHeaderImage                 = 0x04,     //Draws image in a column
    drawBackground                  = 0x08,     //Draws grid background
    drawSelection                   = 0x10,     //Blends selection with foreground and background colors for selected lines.
    drawSelectionFrame              = 0x20,     //Draws a frame around selected lines
    drawColumnSort                  = 0x40,     //Blends column sorting with fore and back colors.
    drawMouseTrackSelection         = 0x80,     //Draws an area, selected by mouse with pressed left button
    drawFocusedRow                  = 0x100,    //Blends focus with foreground and background colors for selected lines.
    drawFocusedRowFrame             = 0x200,    //Draws a frame around the focused line
    drawHighlight                   = 0x400,    //Draws highlighting
    drawDropPosition                = 0x800,    //Draws indicators helping to drop clipboard content
    drawDropParentPosition          = 0x1000,   //Draws an indicator helping to select a hierarchical level during drop operation
    drawHierarchy                   = 0x2000,   //Draws a hierarchy. Each child is shifted relatively to its parent
    drawCollapseExpandIcon          = 0x4000,   //Draws collapse/expand icons
    drawHierarchicalLines           = 0x8000,   //Draws hierarchical lines
    drawHorizontalLines             = 0x10000,  //Draws horizontal lines between lines
    drawVerticalLines               = 0x20000,  //Draws vertical lines between columns
    drawEmbeddedControlBackground   = 0x40000,  //Forces an embedded MFC control to blend its background color with cell background color


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


    defaultPaintFilter = drawEverything,
};

//Using example:

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

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

UINT GetPaintFilter ( ) const

Gets current value of the graphical filter.

Returns:: Current filter. Set of PaintFilter enumeration.

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

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

Example

//This filter is defined in the Dapfor/GUI/Types.h file
enum PaintFilter    
{
    drawNothing                     = 0x00,     //Draws nothing
    drawText                        = 0x01,     //Draws text in the grid
    drawImage                       = 0x02,     //Draws image in a cell
    drawHeaderImage                 = 0x04,     //Draws image in a column
    drawBackground                  = 0x08,     //Draws grid background
    drawSelection                   = 0x10,     //Blends selection with foreground and background colors for selected lines.
    drawSelectionFrame              = 0x20,     //Draws a frame around selected lines
    drawColumnSort                  = 0x40,     //Blends column sorting with fore and back colors.
    drawMouseTrackSelection         = 0x80,     //Draws an area, selected by mouse with pressed left button
    drawFocusedRow                  = 0x100,    //Blends focus with foreground and background colors for selected lines.
    drawFocusedRowFrame             = 0x200,    //Draws a frame around the focused line
    drawHighlight                   = 0x400,    //Draws highlighting
    drawDropPosition                = 0x800,    //Draws indicators helping to drop clipboard content
    drawDropParentPosition          = 0x1000,   //Draws an indicator helping to select a hierarchical level during drop operation
    drawHierarchy                   = 0x2000,   //Draws a hierarchy. Each child is shifted relatively to its parent
    drawCollapseExpandIcon          = 0x4000,   //Draws collapse/expand icons
    drawHierarchicalLines           = 0x8000,   //Draws hierarchical lines
    drawHorizontalLines             = 0x10000,  //Draws horizontal lines between lines
    drawVerticalLines               = 0x20000,  //Draws vertical lines between columns
    drawEmbeddedControlBackground   = 0x40000,  //Forces an embedded MFC control to blend its background color with cell background color


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


    defaultPaintFilter = drawEverything,
};

//Using example:

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

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

void SetFlickerFreeDrawing ( bool enable )

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

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

Parameters:

[in] enable Enables double buffering mechanism. True - double buffering is allowed, false - forbidden.

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

bool GetFlickerFreeDrawing ( ) const

Gets the value indicating whether double buffering mode is enabled.

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

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

int GetOptimalRowHeight ( ContextType contextType ) const

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

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

Parameters:

[in] contextType grid context.

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

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

void SetOptimalRowHeight	(	ContextType	contextType,
		int	height
	)

Sets default row height.

Parameters:

`[in]`	contextType	grid context.
`[in]`	height	default row height.

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

Gets optimal width value for a given grid cell.

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

Parameters:

`[in]`	nRow	index of a line in grid context.
`[in]`	contextType	grid context. Available values: FixedContext, ScrollableContext.
`[in]`	fid	field's identifier.

Returns:: Optimal value of a given grid cell width.

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

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

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

Parameters:

`[in]`	contextType	grid context. Available values: FixedContext, ScrollableContext, AllContexts.
`[in]`	fid	field's identifier.

Returns:: Optimal grid column size.

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

CHeader * SetHeader ( CHeader * newHeader )

Sets a new header.

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

Parameters:

[in] newHeader A new header.

Returns:: Previous header.

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

CHeader * GetHeader ( )

Gets the current header used by the grid.

Returns:: Current header used by the grid.

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

const CHeader * GetHeader ( ) const

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

Returns:: Current header used by the grid.

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

void ShowHeader ( )

Makes the header visible.

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

void HideHeader ( )

Makes the header invisible.

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

bool IsHeaderVisible ( ) const

Returns the value indicating whether the header is visible.

Returns:: true if the header is visible. Otherwise false.

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

void ShowHeaderDialog ( ) [virtual]

Displays the dialog for configuring header columns.

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

const CColumn * GetColumn ( CPoint pt ) const

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

Parameters:

[in] pt Location in the client area of the grid.

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

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

const CColumn * GetNavigationColumn ( ) const

Gets a navigation column.

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

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

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

const CColumn * GetHierarchicalColumn ( ) const

Gets the column that manages grid hierarchy.

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

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

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

void AdjustColumnByFid ( Common::FID fid )

Performs column width optimization for visible grid lines.

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

Parameters:

[in] fid field's identifier.

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

void AdjustColumnByIndex ( int index )

Performs column width optimization by index.

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

Parameters:

[in] index Zero-based column index.

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

void AdjustAllColumns ( )

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

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

int GetOptimalHeaderHeight ( ) const

Gets optimal header height.

Returns:: Optimal header height.

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

void EnsureColumnVisible ( Common::FID fid )

The function makes a column fully visible in the grid.

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

Parameters:

[in] fid field's identifier.

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

void EnableTooltip ( bool bEnable = true )

Allows to display tooltips.

Parameters:

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

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

bool IsTooltipEnabled ( ) const

Returns value indicating whether tooltips are enabled.

Returns:: True - tooltips are enabled, false - disabled.

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

const ITooltipCtrl * GetTooltipCtrl ( )

Gets current ITooltipCtrl used by the grid.

This interface serves for managing a tooltip window.

Returns:: Current ITooltipCtrl used by the grid if it exists. Otherwise - false.

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

ITooltipCtrl * SetTooltipCtrl ( ITooltipCtrl * control )

Sets new ITooltipCtrl interface to control the tooltip window.

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

Parameters:

[in] control A new tooltip control

Returns:: Previous tooltip control

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

const ITooltip * GetTooltip ( ) const

Gets the interface controlling tooltip content.

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

Returns:: Current implementation of the interface controlling a tooltip content if it exists. Otherwise - 0.

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

ITooltip * SetTooltip ( ITooltip * tooltip )

Set a new interface for defining the tooltip content.

Parameters:

[in] tooltip New tooltip interface.

Returns:: The function returns previous ITooltip interface.

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

const CTooltipSettings & GetTooltipSettings ( ) const

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

Returns:: Tooltip settings

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

CTooltipSettings & GetTooltipSettings ( )

Gets the tooltip settings collected in CTooltipSettings class object.

Returns:: Tooltip settings

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

void SetTooltipSettings ( const CTooltipSettings & settings )

Sets new tooltip settings.

Parameters:

[in] settings New tooltip settings

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

void EnableInPlaceTooltip ( bool bEnable = true )

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

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

Parameters:

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

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

bool IsInPlaceTooltipEnabled ( ) const

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

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

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

CTooltipSettings & GetInPlaceTooltipSettings ( )

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

Returns:: Settings collected in CTooltipSettings class object.

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

void SetInPlaceTooltipSettings ( const CTooltipSettings & settings )

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

Parameters:

[in] settings Settings collected in CTooltipSettings class object.

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

const ITooltipCtrl * GetInPlaceTooltipCtrl ( ) const

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

Returns:: Current ITooltipCtrl used by the grid if it exists. Otherwise - false.

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

ITooltipCtrl * SetInPlaceTooltipCtrl ( ITooltipCtrl * control )

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

CInPlaceTooltipCtrl is the default implementation used by the grid.

Parameters:

[in] control A new tooltip control.

Returns:: Previous tooltip control.

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

bool Copy ( )

Copies selection to the clipboard.

The copying process can be totally redefined in ICopyPaste interface.

Returns:: true if the content has been successfully copied to the clipboard. Otherwise false.

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

bool Cut ( )

Cuts selection to the clipboard.

The cut process can be totally redefined in ICopyPaste interface.

Returns:: true if the content has been successfully copied to the clipboard. Otherwise false.

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

bool Paste ( )

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

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

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

bool Paste	(	HITEM	hParent,
		HITEM	hInsertAfter
	)

Pastes data from the clipboard to a given position.

Parameters:

[in] hParent Parent that can be the target of attachment. Any got in Add() function value or one of the following contexts: GI_SCROLABLE_ROOT or GI_FIXED_ROOT, can be a parent.

[in]

hInsertAfter

the value used to specify location of the insertion. If sorting is switched on, this parameter is meaningless, because a data object is inserted according to the sorting rules. If there is no sorting, hInsertAfter can have the following values:

GI_FIRST	Insertion to the beginning
GI_LAST	Insertion to the end
HITEM	Insertion after a given handle

Returns:: True for a successful operation. Otherwise - false.

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

ICopyPaste * SetCopyPaste ( ICopyPaste * copyPaste )

Sets new ICopyPaste interface.

Returns:: Previous ICopyPaste interface.

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

ICopyPaste * GetCopyPaste ( ) const

Gets the current ICopyPaste interface used by the grid.

Returns:: Current ICopyPaste interface used by the grid.

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

const CCopyPasteSettings & GetCopyPasteSettings ( ) const

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

Returns:: Settings collected in CCopyPasteSettings class object.

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

CCopyPasteSettings & GetCopyPasteSettings ( )

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

Returns:: Settings collected in CCopyPasteSettings class object.

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

void SetCopyPasteSettings ( const CCopyPasteSettings & settings )

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

Parameters:

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

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

void AllowCopyPaste ( bool bAllow )

Enables/disables copy/paste.

Parameters:

[in] bAllow Enables copy/paste.

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

bool IsCopyPasteAllowed ( ) const

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

Returns:: True - copy/paste operations are allowed, false - forbidden.

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

IDragDrop * SetDragDrop ( IDragDrop * dragDrop )

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

Parameters:

[in] dragDrop New IDragDrop interface.

Returns:: Previous interface used by the grid.

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

IDragDrop * GetDragDrop ( ) const

Gets the current IDragDrop interface used by the grid.

Returns:: Current IDragDrop interface used by the grid if it is found. Otherwise - 0.

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

const CDragDropSettings & GetDragDropSettings ( ) const

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

Returns:: Settings collected in CDragDropSettings class object.

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

CDragDropSettings & GetDragDropSettings ( )

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

Returns:: Settings collected in CDragDropSettings class object.

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

void SetDragDropSettings ( const CDragDropSettings & settings )

Sets new drag&drop settings.

Parameters:

[in] settings Settings collected in CDragDropSettings class object.

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

void AllowDragAndDrop ( bool bAllow )

Enables or disables drag&drop in the grid.

Parameters:

[in] bAllow Enables use of drag&drop.

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

bool IsDragAndDropAllowed ( ) const

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

Returns:: True - drad&drop operations are allowed, false - forbidden.

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

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

Helper that enables image creation when grid content is dragged.

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

Parameters:

`[in]`	handles	list of the handles participating in drag&drop operation.
`[in]`	contextType	Context type.
`[in]`	header	Current header used by the grid.

Returns:: CDragImage structure.

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

void AllowSort ( bool bEnable )

Enables or disables sorting in the grid.

Parameters:

[in] bEnable True - sorting is allowed, false - forbidden.

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

bool CanSort ( ) const

Returns the value indicating whether sorting is allowed.

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

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

void AllowMultiSort ( bool bEnable )

Allows multiple sorting in the grid.

Parameters:

[in] bEnable True - multiple sorting is allowed, false - forbidden.

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

bool CanMultiSort ( ) const

Returns the value indicating whether multiple sorting is allowed.

Returns:: True - multiple sorting is allowed, false - forbidden.

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

void SetSortedContext ( ContextType contextType = AllContexts )

Sets grid context where sorting is allowed.

Parameters:

[in] contextType Grid context. Available values: UndefinedContext, FixedContext, ScrollableContext, AllContexts. If UndefinedContext is applied then sorting will be forbidden in both contexts.

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

ContextType GetSortedContext ( ) const

Gets contexts where sorting is allowed.

Returns:: Grid contexts where sorting is allowed. UndefinedContext means that sorting is forbidden in both contexts.

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

void ResetSort ( bool redraw = true )

Cancels sorting.

Parameters:

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

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

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

Sets a sort for a given level.

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

Parameters:

`[in]`	level	sorting level. The first level starts from '0'.
`[in]`	sortInfo	information about sorting. Assigns the column on which sorting is conducted and its direction.
`[in]`	applyImmediatelly	Indicates whether it should apply for new sorting parameters immediatelly.

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

CSortInfo GetSort ( int level ) const

Gets information about sorting for a given level.

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

Returns:: Information about sorting for a given level.

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

void UpdateSort ( )

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

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

int GetSortLevels ( ) const

Returns current value of sorting levels quantity.

Returns:: Count of sorting levels

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

IGridFilter * SetFilter ( IGridFilter * filter )

Sets a new filter.

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

Parameters:

[in] filter New filter

Returns:: Previous filter

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

IGridFilter * GetFilter ( ) const

Gets the current filter set in the grid.

Returns:: Current filter if it is found. Otherwise - 0.

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

void UpdateFilter ( )

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

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

IKeyManager * SetKeyManager ( IKeyManager * keyManager )

Sets a new keyboard manager to control the grid.

The function also returns the previous manager.

Parameters:

[in] keyManager New keyboard manager.

Returns:: Previous keyboard manager.

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

IKeyManager * GetKeyManager ( ) const

Gets the current keyboard manager used by the grid.

Returns:: Current keyboard manager if it is found. Otherwise - 0.

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

void AllowNavigation ( ContextType contextType = AllContexts )

Allows to conduct navigation in given grid contexts.

Parameters:

[in] contextType Available values: UndefinedContex, FixedContext, ScrollableContext, AllContexts. If UndefinedContext is applied then navigation is forbidden in both contexts.

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

bool CanNavigate ( ContextType contextType ) const

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

Returns:: True if navigation is allowed. Otherwise - false.

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

void NavigateUp	(	bool	bShift,
		bool	bCtrl
	)

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

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

Parameters:

`[in]`	bShift	Indicates whether the shift button is pressed
`[in]`	bCtrl	Indicates whether the control button is pressed

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

void NavigateDown	(	bool	bShift,
		bool	bCtrl
	)

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

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

Parameters:

`[in]`	bShift	Indicates whether the shift button is pressed
`[in]`	bCtrl	Indicates whether the control button is pressed

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

void NavigatePageUp	(	bool	bShift,
		bool	bCtrl
	)

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

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

Parameters:

`[in]`	bShift	Indicates whether the shift button is pressed
`[in]`	bCtrl	Indicates whether the control button is pressed

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

void NavigatePageDown	(	bool	bShift,
		bool	bCtrl
	)

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

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

Parameters:

`[in]`	bShift	Indicates whether the shift button is pressed
`[in]`	bCtrl	Indicates whether the control button is pressed

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

void NavigateHome	(	bool	bShift,
		bool	bCtrl
	)

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

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

Parameters:

`[in]`	bShift	Indicates whether the shift button is pressed
`[in]`	bCtrl	Indicates whether the control button is pressed

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

void NavigateEnd	(	bool	bShift,
		bool	bCtrl
	)

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

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

Parameters:

`[in]`	bShift	Indicates whether the shift button is pressed
`[in]`	bCtrl	Indicates whether the control button is pressed

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

void ResetScroll ( )

Updates vertical and horizontal scrollbar positions.

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

void PrintPreview ( const CPrintSettings & settings )

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

Parameters:

[in] settings Specifies printing settings for a grid content.

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

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

Launches printing of grid content.

Parameters:

`[in]`	settings	Specifies printing settings for a grid content.
`[in]`	printInfo	MFC Informational data structure, containing nested printing information. Can be 0.

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

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

Attaches a control to a grid cell.

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

Parameters:

`[in]`	control	User's control.
`[in]`	hItem	line handle in the grid. If the handle is filtered, than the control is invisible.
`[in]`	fid	field's identifier.
`[in]`	params	Attachment settings collected in CEmbeddedControlParams class object.

Returns:: True if MFC control has been successfully attached to the cell. Otherwise false.

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

bool DetachControl ( CWnd * control )

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

Parameters:

[in] control Control to be detached.

Returns:: True if MFC control has been successfully detached from the cell. Otherwise false.

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

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

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

Parameters:

`[in]`	hItem	line handle in the grid.
`[in]`	fid	field's identifier.
`[in]`	bDestroy	value indicates that when the control switched off, it should be destroyed.

Returns:: True if MFC control has been successfully detached from the cell. Otherwise false.

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

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

Checks whether MFC control is attached to a given cell.

Parameters:

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

Returns:: True if there is an MFC control attached to the specified cell. Otherwise false.

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

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

Checks whether MFC control is attached to a given cell.

Parameters:

`[in]`	nRow	index of a line in grid context.
`[in]`	contextType	grid context. Available values: FixedContext, ScrollableContext.
`[in]`	fid	field's identifier.

Returns:: True if there is MFC control attached to the specified cell. Otherwise false.

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

IEditInPlace * SetEditInPlace ( IEditInPlace * editInPlace )

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

Parameters:

[in] editInPlace New edit in place interface.

Returns:: Previous edit in place interface

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

IEditInPlace * GetEditInPlace ( ) const

Gets current IEditInPlace interface used by the grid.

Returns:: Current IEditInPlace interface used by the grid. If it is not found, 0 is returned.

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

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

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

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

Parameters:

`[in]`	hItem	line visible handle in the grid.
`[in]`	fid	field's identifier.
`[in]`	reason	The reason why this function is called.

Returns:: True if the grid can start edit in place for the given cell. Otherwise - false.

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

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

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

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

Parameters:

`[in]`	hItem	line visible handle in the grid.
`[in]`	fid	field's identifier.
`[in]`	reason	The reason why this function is called.

Returns:: True if edit in place process has been successfully started. Otherwise - false.

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

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

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

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

Parameters:

`[in]`	reason	The reason why this function has been called.
`[in]`	postMessage	If true, then edit in place operation should be stopped asynchronously.

Returns:: True if edit in place process has been successfully stopped. Otherwise - false.

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

CWnd * GetEditInPlaceControl ( ) const

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

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

Returns:: Control that is currently participating in 'edit in place' operation. If it is not found, 0 is returned.

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

const CEditInPlaceSettings & GetEditInPlaceSettings ( ) const

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

Returns:: Current settings collected in CEditInPlaceSettings class object.

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

CEditInPlaceSettings & GetEditInPlaceSettings ( )

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

Returns:: Current settings collected in CEditInPlaceSettings class object.

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

void SetEditInPlaceSettings ( const CEditInPlaceSettings & settings )

Sets new 'edit in place' settings.

Parameters:

[in] settings New settings collected in CEditInPlaceSettings class object.

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

void Serialize ( CArchive & ar ) [virtual]

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

Parameters:

[in] ar Archive to store or restore grid data.

thread-safety:: The function is not thread-safe.

int GetSerializeVertion ( ) [static]

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

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

CGrid Class Reference

Serialization

Public Member Functions

Detailed Description

Member Function Documentation