treectrl.h

Wxpython Implemented on Windows CE, Source code

/////////////////////////////////////////////////////////////////////////////
// Name:        wx/os2/treectrl.h
// Purpose:     wxTreeCtrl class
// Author:      David Webster
// Modified by:
// Created:     01/23/03
// RCS-ID:      $Id: treectrl.h,v 1.16 2006/03/28 13:11:18 ABX Exp $
// Copyright:   (c) David Webster
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

#ifndef _WX_TREECTRL_H_
#define _WX_TREECTRL_H_

// ----------------------------------------------------------------------------
// headers
// ----------------------------------------------------------------------------

#if wxUSE_TREECTRL

#include "wx/textctrl.h"
#include "wx/dynarray.h"
#include "wx/treebase.h"
#include "wx/hashmap.h"

// the type for "untyped" data
typedef long wxDataType;

// fwd decl
class  WXDLLEXPORT wxImageList;
class  WXDLLEXPORT wxDragImage;
struct WXDLLEXPORT wxTreeViewItem;

// a callback function used for sorting tree items, it should return -1 if the
// first item precedes the second, +1 if the second precedes the first or 0 if
// they're equivalent
class wxTreeItemData;

#if WXWIN_COMPATIBILITY_2_6
    // flags for deprecated InsertItem() variant
    #define wxTREE_INSERT_FIRST 0xFFFF0001
    #define wxTREE_INSERT_LAST  0xFFFF0002
#endif

// hash storing attributes for our items
WX_DECLARE_EXPORTED_VOIDPTR_HASH_MAP(wxTreeItemAttr *, wxMapTreeAttr);

// ----------------------------------------------------------------------------
// wxTreeCtrl
// ----------------------------------------------------------------------------
class WXDLLEXPORT wxTreeCtrl : public wxControl
{
public:
    // creation
    // --------
    wxTreeCtrl() { Init(); }

    wxTreeCtrl( wxWindow*          pParent
               ,wxWindowID         vId = wxID_ANY
               ,const wxPoint&     rPos = wxDefaultPosition
               ,const wxSize&      rSize = wxDefaultSize
               ,long               lStyle = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT
               ,const wxValidator& rValidator = wxDefaultValidator
               ,const wxString&    rsName = wxTreeCtrlNameStr
              )
    {
        Create( pParent
               ,vId
               ,rPos
               ,rSize
               ,lStyle
               ,rValidator
               ,rsName
              );
    }
    virtual ~wxTreeCtrl();

    bool Create( wxWindow*          pParent
                ,wxWindowID         vId = wxID_ANY
                ,const wxPoint&     rPos = wxDefaultPosition
                ,const wxSize&      rSize = wxDefaultSize
                ,long               lStyle = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT
                ,const wxValidator& rValidator = wxDefaultValidator
                ,const wxString&    rsName = wxTreeCtrlNameStr
               );

    //
    // Accessors
    // ---------
    //

    //
    // Get the total number of items in the control
    //
    virtual unsigned int GetCount(void) const;

    //
    // Indent is the number of pixels the children are indented relative to
    // the parents position. SetIndent() also redraws the control
    // immediately.
    //
    unsigned int GetIndent(void) const;
    void         SetIndent(unsigned int uIndent);

    //
    // Spacing is the number of pixels between the start and the Text
    //
    unsigned int GetSpacing(void) const { return 18; } // return wxGTK default
    void SetSpacing(unsigned int uSpacing) { }

    //
    // Image list: these functions allow to associate an image list with
    // the control and retrieve it. Note that the control does _not_ delete
    // the associated image list when it's deleted in order to allow image
    // lists to be shared between different controls.
    //
    // OS/2 doesn't really use imagelists as MSW does, but since the MSW
    // control is the basis for this one, until I decide how to get rid of
    // the need for them they are here for now.
    //
    wxImageList* GetImageList(void) const;
    wxImageList* GetStateImageList(void) const;

    void         AssignImageList(wxImageList* pImageList);
    void         AssignStateImageList(wxImageList* pImageList);
    void         SetImageList(wxImageList* pImageList);
    void         SetStateImageList(wxImageList* pImageList);

    //
    // Functions to work with tree ctrl items. Unfortunately, they can _not_ be
    // member functions of wxTreeItem because they must know the tree the item
    // belongs to for Windows implementation and storing the pointer to
    // wxTreeCtrl in each wxTreeItem is just too much waste.

    //
    // Item's label
    //
    wxString GetItemText(const wxTreeItemId& rItem) const;
    void     SetItemText( const wxTreeItemId& rItem
                         ,const wxString&     rsText
                        );

    //
    // One of the images associated with the item (normal by default)
    //
    int  GetItemImage( const wxTreeItemId& rItem
                      ,wxTreeItemIcon      vWhich = wxTreeItemIcon_Normal
                     ) const;
    void SetItemImage( const wxTreeItemId& rItem
                      ,int                 nImage
                      ,wxTreeItemIcon      vWhich = wxTreeItemIcon_Normal
                     );

    //
    // Data associated with the item
    //
    wxTreeItemData* GetItemData(const wxTreeItemId& rItem) const;
    void            SetItemData( const wxTreeItemId& rItem
                                ,wxTreeItemData*     pData
                               );

    //
    // Item's text colour
    //
    wxColour GetItemTextColour(const wxTreeItemId& rItem) const;
    void     SetItemTextColour( const wxTreeItemId& rItem
                               ,const wxColour&     rColor
                              );

    //
    // Item's background colour
    //
    wxColour GetItemBackgroundColour(const wxTreeItemId& rItem) const;
    void     SetItemBackgroundColour( const wxTreeItemId& rItem
                                     ,const wxColour&     rColour
                                    );

    //
    // Item's font
    //
    wxFont GetItemFont(const wxTreeItemId& rItem) const;
    void   SetItemFont( const wxTreeItemId& rItem
                       ,const wxFont&       rFont
                      );

    //
    // Force appearance of [+] button near the item. This is useful to
    // allow the user to expand the items which don't have any children now
    // - but instead add them only when needed, thus minimizing memory
    // usage and loading time.
    //
    void SetItemHasChildren( const wxTreeItemId& rItem
                            ,bool                bHas = true
                           );

    //
    // The item will be shown in bold
    //
    void SetItemBold( const wxTreeItemId& rItem
                     ,bool                bBold = true
                    );

    //
    // The item will be shown with a drop highlight
    //
    void SetItemDropHighlight( const wxTreeItemId& rItem
                              ,bool                bHighlight = true
                             );

    //
    // Item status inquiries
    // ---------------------
    //

    //
    // Is the item visible (it might be outside the view or not expanded)?
    //
    bool IsVisible(const wxTreeItemId& rItem) const;

    //
    // Does the item has any children?
    //
    bool ItemHasChildren(const wxTreeItemId& rItem) const;

    //
    // Is the item expanded (only makes sense if HasChildren())?
    //
    bool IsExpanded(const wxTreeItemId& rItem) const;

    //
    // Is this item currently selected (the same as has focus)?
    //
    bool IsSelected(const wxTreeItemId& rItem) const;

    //
    // Is item text in bold font?
    //
    bool IsBold(const wxTreeItemId& rItem) const;

    //
    // Number of children
    // ------------------
    //

    //
    // If 'bRecursively' is false, only immediate children count, otherwise
    // the returned number is the number of all items in this branch
    //
    size_t GetChildrenCount( const wxTreeItemId& rItem
                            ,bool                bRecursively = true
                           ) const;

    //
    // Navigation
    // ----------
    //

    //
    // Get the root tree item
    //
    wxTreeItemId GetRootItem(void) const;

    //
    // Get the item currently selected (may return NULL if no selection)
    //
    wxTreeItemId GetSelection(void) const;

    //
    // Get the items currently selected, return the number of such item
    //
    size_t GetSelections(wxArrayTreeItemIds& rSelections) const;

    //
    // Get the parent of this item (may return NULL if root)
    //
    wxTreeItemId GetItemParent(const wxTreeItemId& rItem) const;

        // for this enumeration function you must pass in a "cookie" parameter
        // which is opaque for the application but is necessary for the library
        // to make these functions reentrant (i.e. allow more than one
        // enumeration on one and the same object simultaneously). Of course,
        // the "cookie" passed to GetFirstChild() and GetNextChild() should be
        // the same!

        // get the first child of this item
    wxTreeItemId GetFirstChild(const wxTreeItemId& item,
                               wxTreeItemIdValue& cookie) const;
        // get the next child
    wxTreeItemId GetNextChild(const wxTreeItemId& item,
                              wxTreeItemIdValue& cookie) const;

    //
    // Get the last child of this item - this method doesn't use cookies
    //
    wxTreeItemId GetLastChild(const wxTreeItemId& rItem) const;

    //
    // Get the next sibling of this item
    //
    wxTreeItemId GetNextSibling(const wxTreeItemId& rItem) const;

    //
    // Get the previous sibling
    //
    wxTreeItemId GetPrevSibling(const wxTreeItemId& rItem) const;

    //
    // Get first visible item
    //
    wxTreeItemId GetFirstVisibleItem(void) const;

    //
    // Get the next visible item: item must be visible itself!
    // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
    //
    wxTreeItemId GetNextVisible(const wxTreeItemId& rItem) const;

    //
    // Get the previous visible item: item must be visible itself!
    //
    wxTreeItemId GetPrevVisible(const wxTreeItemId& rItem) const;

    //
    // Operations
    // ----------
    //

    //
    // Add the root node to the tree
    //
    wxTreeItemId AddRoot( const wxString& rsText
                         ,int             nImage = -1
                         ,int             nSelectedImage = -1
                         ,wxTreeItemData* pData = NULL
                        );

    //
    // Insert a new item in as the first child of the parent
    //
    wxTreeItemId PrependItem( const wxTreeItemId& rParent
                             ,const wxString&     rsText
                             ,int                 nImage = -1
                             ,int                 nSelectedImage = -1
                             ,wxTreeItemData*     pData = NULL
                            );

    //
    // Insert a new item after a given one
    //