CTreeView

			GtkOL Reference Manual

CTreeView

Like the gtk view representations, the gtkol tree view definition is based on a model. This model is specified as a metaclasses list of item field values instances. The gtkol tree view instance works on tree view items that own the field values of the specific handled tree view model. The tree view model must be defined before any tree view item is added to the tree view widget so that the tree view widget knows how to handle the field values of the owned items. The tree view item field values must map the tree view widget defined model or the owner affectation of the tree view item to another tree view item or to the tree view widget would fail because of not corresponding to the expected model. If not specified, the default model is the simpliest one i.e. a field value for each tree view item corresponding to a CItemFieldValueString one and so displays just a string for each item. A field value is mapped as an independant tree view column unless the model specifies pack sets with a CItemFieldValuePack metaclass specification.

As a summary, a CTreeView instance handles a model designed as a list of metaclasses and owns CTreeViewItem subcomponents. CTreeViewItem subcomponents own CItemFieldValue instances that match the view model i.e. a potential list of CItemFieldValueString, CItemFieldValueBoolean, CItemFieldValuePixbuf, CItemFieldValueCombo and CItemFieldValueProgress instances.

The Tree view item derives the CControl definition. It is also a draggable and dropsiteable component.

XML serialization

Metaclass declaration

DECLARE_DYNAMIC_METACLASS ('trvw', CTreeView, CContainer);
DECLARE_GENERIC_METACLASS ('_trw', CTreeViewListener, CWidgetListener);
DECLARE_DYNAMIC_METACLASS ('trwi', CTreeViewItem, CControl);
DECLARE_DYNAMIC_METACLASS ('_tpi', CTreeViewItemFieldValueAPIListener, CItemFieldValueAPIListener);

Hierarchy Definition

    [CClass]
        [CSerialized]
            [CMetaModule]
                [CObject]
                    CComponent
                        CControl
                            CTreeViewItem
                            CWidget
                                CContainer
                                    CTreeView
    [CClass]
        [CSerialized]
            [CMetaModule]
                [CObjectListener]
                    CItemFieldValueAPIListener
                        CTreeViewItemFieldValueAPIListener
                    CWidgetListener
                        CTreeViewListener

API description

#include "ccontainer.h"
#include "citemfieldvalue.h"

class CTreeView;
class CTreeViewListener;
class CTreeViewItem;

typedef NServices::TBuffer <CTreeViewItem *> CTreeViewItems;

class CTreeViewListener : public CWidgetListener
{
    public :

        CTreeViewListener        ();
        virtual ~CTreeViewListener  () =0;

    public :

        virtual void            OnItemQuerySelect        (CObject *inSender, CObject *inItem, const Bool inCurrent,
Bool &ioDoToggle)                    { }
        virtual void            OnItemSelectionChanged   (CObject *inSender)                    { }

        virtual void            OnItemActivated          (CObject *inSender, CObject *inItem)            { }

        virtual void            OnItemQueryExpand        (CObject *inSender, CObject *inItem, Bool &ioExpand)    { }
        virtual void            OnItemExpanded           (CObject *inSender, CObject *inItem)            { }

        virtual void            OnItemQueryCollapse      (CObject *inSender, CObject *inItem, Bool &ioCollapse)    { }
        virtual void            OnItemCollapsed          (CObject *inSender, CObject *inItem)            { }

        virtual void            OnItemToggled            (CObject *inSender, CObject *inItem, const size_t inIndex,
                                        Bool &ioDoChange)                    { }

        virtual void              OnItemEdited            (CObject *inSender, CObject *inItem, const size_t inIndex,
                                        CString &ioNewString, Bool &ioDoChange)        { }
        SECTION_GENERIC_METACLASS;
};

class CTreeView : public CContainer
{
    public :

        CTreeView            (CContainer *inOwner=NULL, const CMetaClasses &inModel=_IFVString_,
                          const CTreeViewListener *inListener=NULL) THROWABLE;
        virtual ~CTreeView        ();

    protected :

        virtual GtkWidget *        PerformWidgetInstanciate   ();
        virtual void            PerformWidgetInitialize    ();

  public :

        virtual const CMetaClass * ListenerMustBe            () const;

        virtual CMetaClasses       OwnerMustBe            () const;
        virtual CMetaClasses       ChildMustBe            () const;

        virtual CControl *        GetControlAtPoint        (const TPoint &inRelativePoint) const;

        Bool                SetModel           (const CMetaClasses &inModel);
        CMetaClasses            GetModel            () const;

        virtual void            SetSelectionMode        (const GtkSelectionMode inSelectionMode);
        GtkSelectionMode        GetSelectionMode        () const;

        CTreeViewItems            GetSelection           () const;

        virtual void            Serialize              (CXMLElementNode *&ioXMLElementNode, const int inMode) THROWABLE;

    protected :

        CMetaClasses           m_Model;
        CStrings            m_ColumnsTitle;

        static void              OnItemEdited           (GtkCellRendererText *, const gchar *, const gchar *, gpointer);
        static void            OnItemToggled            (GtkCellRendererToggle *, gchar *, gpointer);
        static void            OnItemActivated            (GtkTreeView *, GtkTreePath *, GtkTreeViewColumn *, gpointer);
        static gboolean            OnItemQueryExpand        (GtkTreeView *, GtkTreeIter *, GtkTreePath *, gpointer);
        static gboolean            OnItemQueryCollapse        (GtkTreeView *, GtkTreeIter *, GtkTreePath *, gpointer);
        static void            OnItemExpanded            (GtkTreeView *, GtkTreeIter *, GtkTreePath *, gpointer);
        static void              OnItemCollapsed            (GtkTreeView *, GtkTreeIter *, GtkTreePath *, gpointer);
        static gboolean            OnItemQuerySelect        (GtkTreeSelection *, GtkTreeModel *, GtkTreePath *, gboolean, gpointer);
        static void            OnItemSelectionChanged     (GtkTreeSelection *, gpointer);

        SECTION_DYNAMIC_METACLASS;
};

class CTreeViewItem : public CControl
{
    public :

        CTreeViewItem            (CTreeView *inOwner=NULL, const CItemFieldValues &inFieldValues=CItemFieldValues(),
                            const CObjectListener *inListener=NULL);
        CTreeViewItem           (CTreeViewItem *inOwner, const CItemFieldValues &inFieldValues=CItemFieldValues(),
                          const CObjectListener *inListener=NULL);
        virtual ~CTreeViewItem    ();

    public :

        GtkTreeIter *            GetGtkTreeIter            () const;
        static CTreeViewItem *    GetTreeViewItem           (const GtkTreeIter *inGtkTreeIter);

        virtual CMetaClasses       OwnerMustBe           () const;
        virtual CMetaClasses       ChildMustBe           () const;

        virtual bool            SetOwner              (CComponent *inOwner, const SInt16 inIndex=-1);

        virtual TBounds            GetBounds           () const;

        virtual CPixbuf *        GetControlPixbuf          () const;

        virtual Bool           SetItemFieldValues        (const CItemFieldValues &inItemFieldValues);
        CItemFieldValues        GetItemFieldValues        () const;

CItemFieldValue & operator [] (const size_t inIndex) const;

        virtual void           Select            (const bool inSelect=true);
        virtual bool            IsSelected            () const;

        virtual void           Expand            (const bool inAll=false);
        virtual void           Collapse              ();
        virtual Bool            IsExpanded        () const;

        virtual void           Serialize            (CXMLElementNode *&ioXMLElementNode, const int inMode) THROWABLE;

    protected :

        GtkTreeIter              m_GtkTreeIter;
        CItemFieldValues        m_ItemFieldValues;

        friend class            CTreeView;

        SECTION_DYNAMIC_METACLASS;
};

class CTreeViewItemFieldValueAPIListener : public CItemFieldValueAPIListener
{
    public :

        virtual void           OnStateChange            (CObject *);

        SECTION_DYNAMIC_METACLASS;
};

CTreeViewListener API details

virtual void CTreeViewListener::OnItemQuerySelect (CObject *inSender, CObject *inItem, const Bool inCurrent,
Bool &ioDoToggle);

Called when the specified tree view item of the inSender tree view is about to be selected / unselected, the inCurrent parameter specifies the current state of the tree view item to be changed.

virtual void CTreeViewListener::OnItemSelectionChanged (CObject *inSender);

Called when the selection of the specified inSender tree view has changed.

virtual void CTreeViewListener::OnItemActivated (CObject *inSender, CObject *inItem);

Called when the specified tree view item of the inSender tree view has been activated i.e. double clicked.

virtual void CTreeViewListener::OnItemQueryExpand (CObject *inSender, CObject *inItem, Bool &ioExpand);

Called when the specified tree view item of the inSender tree view is about to be expanded.

virtual void CTreeViewListener::OnItemExpanded (CObject *inSender, CObject *inItem);

Called when the specified tree view item of the inSender tree view has been expanded.

virtual void CTreeViewListener::OnItemQueryCollapse (CObject *inSender, CObject *inItem, Bool &ioCollapse);

Called when the specified tree view item of the inSender tree view is about to be collapsed.

virtual void CTreeViewListener::OnItemCollapsed (CObject *inSender, CObject *inItem);

Called when the specified tree view item of the inSender tree view has been collapsed.

virtual void CTreeViewListener::OnItemToggled (CObject *inSender, CObject *inItem, const size_t inIndex,
Bool &ioDoChange);

CItemFieldValueBoolean specific : called when the specified indexed boolean field value of the inSender's tree view item is about to be toggled.

virtual void CTreeViewListener::OnItemEdited (CObject *inSender, CObject *inItem, const size_t inIndex,
CString &ioNewString, Bool &ioDoChange);

CItemFieldValueString specific : called when the specified indexed string field value of the inSender's tree view item is about to be modified after beeing edited.

CTreeViewItem API details

CTreeViewItem::CTreeViewItem (CTreeView *inOwner=NULL, const CItemFieldValues &inFieldValues=CItemFieldValues(),
const CObjectListener *inListener=NULL);

CTreeViewItem default constructor. If the owner is specified, the tree view item is added to the tree view as a new root item. If given, the inFieldValues parameter is a buffer of CItemFieldValue specific instances matching the tree view expected model - see the above introduction summary -.

CTreeViewItem::CTreeViewItem (CTreeViewItem *inOwner, const CItemFieldValues &inFieldValues=CItemFieldValues(),
const CObjectListener *inListener=NULL);

CTreeViewItem constructor. When instanciated, the item is added at the end of the children list of the given owner item. If given, the inFieldValues parameter is a buffer of CItemFieldValue specific instances matching the tree view expected model - see the above introduction summary -.

virtual CTreeViewItem::~CTreeViewItem ();

CTreeViewItem destructor. When called, it performs a proper deletion of the whole subcomponents hierarchy of tree view items.

GtkTreeIter * CTreeViewItem::GetGtkTreeIter () const;

Retreives the GtkTreeIter of the CTreeViewItem instance - do not free the pointer when done -.

static CTreeViewItem * CTreeViewItem::GetTreeViewItem (const GtkTreeIter *inGtkTreeIter);

Retreives the CTreeViewItem instance associated to the specified GtkTreeIter if any. NULL if none.

virtual CMetaClasses CTreeViewItem::OwnerMustBe () const;

Returns the tree view item expected owner type list : CTreeViewItem or CTreeView as potential owners.

virtual CMetaClasses CTreeViewItem::ChildMustBe () const;

Returns the tree view item expected children type : CTreeViewItem.

virtual bool CTreeViewItem::SetOwner (CComponent *inOwner, const SInt16 inIndex=-1);

Affect the owner of the tree view item. The inOwner parameter must be a CTreeViewItem or CTreeView instance for the operation to succeed. The inIndex parameter specifies which index the instance caller should be inserted to, -1 to append at the end of the owner's children list.

virtual TBounds CTreeViewItem::GetBounds () const;

Retreives the in tree view bounds of the tree view item caller.

virtual CPixbuf * CTreeViewItem::GetControlPixbuf () const;

Returns a representation of the tree view item caller.

virtual Bool CTreeViewItem::SetItemFieldValues (const CItemFieldValues &inItemFieldValues);

Sets the tree view item field values. The inItemFieldValues parameter is a buffer of CItemFieldValue specific instances matching the tree view expected model - see the above introduction summary -.

CItemFieldValues CTreeViewItem::GetItemFieldValues () const;

Get the tree view item field values buffer list corresponding to the tree view handled model. - see the above introduction summary -. When modifying those field values instances, the gui of the tree view is automatically updated accordinaly. Do not free the returned buffer instances as the tree view item manages it.

CItemFieldValue & CTreeViewItem::operator [] (const size_t inIndex) const;

Get the specified tree view item 0 indexed field value. This is a commodity operator. There is no verification on the specified index, so be carefull. The returned reference may be casted as any of the CItemFieldValueString, CItemFieldValueBoolean, CItemFieldValuePixbuf, CItemFieldValueCombo or CItemFieldValueProgress depending on the handled tree view model. The polymorphism of the generic CItemFieldValue defined operators may be easily used too.
    The tree view item [] operator is accessible only when :
        - the tree view item has not been specified a CItemFieldValues buffer list yet but has an affected owner - OR -
        - the tree view item has been instanciated with an explicit specified CItemFieldValues buffer list even if it has no owner yet - OR -
        - the tree view item has been explicitly requested the SetItemFieldValues function event if it has no owner yet.
    Otherwise the buffer is not populated and the index is out of range. If not sure when performing the request, you can simply check the buffer length before by requesting a CTreeViewItem::GetItemFieldValues().GetLength() call for example.

virtual void CTreeViewItem::Select (const bool inSelect=true);

Selects or unselects the tree view item.

virtual bool CTreeViewItem::IsSelected () const;

Checks if the tree view item is selected.

virtual void CTreeViewItem::Expand (const bool inAll=false);

Expand the tree view item if it owns children items. Expand the whole descent hierarchy if inAll is specified.

virtual void CTreeViewItem::Collapse ();

Collapse the tree view item if it owns children items.

virtual Bool CTreeViewItem::IsExpanded () const;

Checks the tree view item is expanded.

virtual void CTreeViewItem::Serialize (CXMLElementNode *&ioXMLElementNode, const int inMode) THROWABLE;

Performs the sepcific tree view item serialization by requesting the owned field values serialization.

GtkTreeIter CTreeViewItem::m_GtkTreeIter;

Internally used : the gtkol tree view item associated GtkTreeIter structure.

CItemFieldValues CTreeViewItem::m_ItemFieldValues;

Internally used : the tree view item managed field values instances buffer list.

CTreeView API details

CTreeView::CTreeView (CContainer *inOwner=NULL, const CMetaClasses &inModel=_IFVString_,
const CTreeViewListener *inListener=NULL) THROWABLE;

CTreeView constructor. The model consists of a buffer list of metaclasses derived from CItemFieldValue. It generates an exception otherwise. As a commodity, constants are defined to enable passing the model as _IFVString_ + _IFVBoolean_ + _IFVPixbuf_ + _IFVProgress_ + _IFVCombo_. If not explicitly set when instanciating the tree view, it maps a default single _IFVString_ model that owns tree view items handling just one field value : a CItemFieldValueString one. Anyway, the model may be overwritten by a call to CTreeView::SetModel before allocating the tree view items.

virtual CTreeView::~CTreeView ();

CTreeView destructor.

virtual GtkWidget * CTreeView::PerformWidgetInstanciate ();

Internally used : returns the handled gtk tree view widget.

virtual void CTreeView::PerformWidgetInitialize ();

Internally used : performs the gtk widget initialization, the model affectation and the specific signals connections.

virtual const CMetaClass * CTreeView::ListenerMustBe () const;

Returns the CTreeViewListener metaclass.

virtual CMetaClasses CTreeView::OwnerMustBe () const;

Returns the tree view expected owner type : CContainer.

virtual CMetaClasses CTreeView::ChildMustBe () const;

Returns the tree view expected children type : CTreeViewItem.

virtual CControl * CTreeView::GetControlAtPoint (const TPoint &inRelativePoint) const;

Retreives the owned tree view item at the specified given tree view relative point.

Bool CTreeView::SetModel (const CMetaClasses &inModel);

Sets the tree view model; should be called before instanciating any descent tree view item. See the CTreeView constructor for details.

CMetaClasses CTreeView::GetModel () const;

Returns the owned model as a list of metaclasses, each deriving the abstract CItemFieldValue definition.

virtual void CTreeView::SetSelectionMode (const GtkSelectionMode inSelectionMode);

Sets the tree view selection mode.

GtkSelectionMode CTreeView::GetSelectionMode () const;

Returns the tree view selection mode.

CTreeViewItems CTreeView::GetSelection () const;

Returns the actual tree view selected items as a buffer list if any.

virtual void CTreeView::Serialize (CXMLElementNode *&ioXMLElementNode, const int inMode) THROWABLE;

Performs the tree view level serialization.

CMetaClasses CTreeView::m_Model;

Internally used : the owned metaclasses model.

CStrings CTreeView::m_ColumnsTitle;

Internally used : the tree view columns titles (not handled yet due to coordinates recalculation when performing drag & drop).

static void CTreeView::OnItemEdited (GtkCellRendererText *, const gchar *, const gchar *, gpointer);

Internally used : "edited" signal connection.

static void CTreeView::OnItemToggled (GtkCellRendererToggle *, gchar *, gpointer);

Internally used : "toggled" signal connection.

static void CTreeView::OnItemActivated (GtkTreeView *, GtkTreePath *, GtkTreeViewColumn *, gpointer);

Internally used : "raw-activated" signal connection.

static gboolean CTreeView::OnItemQueryExpand (GtkTreeView *, GtkTreeIter *, GtkTreePath *, gpointer);

Internally used : "test-expand-row" signal connection.

static gboolean CTreeView::OnItemQueryCollapse (GtkTreeView *, GtkTreeIter *, GtkTreePath *, gpointer);

Internally used : "test-collapse-row" signal connection.

static void CTreeView::OnItemExpanded (GtkTreeView *, GtkTreeIter *, GtkTreePath *, gpointer);

Internally used : "row-expanded" signal connection.

static void CTreeView::OnItemCollapsed (GtkTreeView *, GtkTreeIter *, GtkTreePath *, gpointer);

Internally used : "row-collapsed" signal connection.

static gboolean CTreeView::OnItemQuerySelect (GtkTreeSelection *, GtkTreeModel *, GtkTreePath *, gboolean, gpointer);

Internally used : Selection function connection.

static void CTreeView::OnItemSelectionChanged (GtkTreeSelection *, gpointer);

Internally used : "changed" signal connection.

CTreeViewItemFieldValueAPIListener API details

virtual void CTreeViewItemFieldValueAPIListener::OnStateChange (CObject *);

Internally used : automatically called when a field value of a tree view item is explictly modified by a programmer request in order to perform associated gui modifications.