RGItemTreeSelector.hh

Go to the documentation of this file.

//======================================================================
/*! \file RGItemTreeSelector.hh
 *
 *  Include file for class RGItemTreeSelector
 */
//======================================================================

#ifndef RG_TREE_SELECTOR_HH
#define RG_TREE_SELECTOR_HH

#include "RBaseFunctions.hh"
#include "GItemTree.hh"
#include "RGItem.hh"

#include <TGCanvas.h>
#include <TGListTree.h>
#include <TGPicture.h>
#include <TGFrame.h>
#include <TGLabel.h>
#include <TGButton.h>
#include <TGMenu.h>

///! Default picture name for icons of elemnts of RGItemTreeSelector
#define RG_ITL_DEFAULT_TREE_PICT  "doc_t.xpm"

///! RGItemTreeSelector widget options
enum RGItemTreeSelectorOptions
{
  // -- Label options
  rgITSLabelCenterAligned   = 0x00000000,   // Centered label (default)
  rgITSLabelLeftAligned     = 0x00000001,   // Label left aligned
  rgITSLabelRightAligned    = 0x00000002,   // Label right aligned

  rgITSLabelAboveList       = 0x00000000,   // Label on top of the tree view (default)
  rgITSLabelBelowList       = 0x00000004,   // Label below the tree view

  // -- Side buttons position options
  rgITSSideButtonsRight     = 0x00000000,   // boutons latéraux placés à droite (défaut)
  rgITSSideButtonsLeft      = 0x00000008,   // boutons latéraux placés à gauche
  rgITSSideButtonsCenter    = 0x00000000,   // boutons latéraux placés au milieu verticalement (défaut)
  rgITSSideButtonsUp        = 0x00000010,   // boutons latéraux placés en haut
  rgITSSideButtonsUpRight   = 0x00000010,   // boutons latéraux placés en haut à droite
  rgITSSideButtonsUpLeft    = 0x00000018,   // boutons latéraux placés en haut à gauche
  rgITSSideButtonsDown      = 0x00000020,   // boutons latéraux placés en bas
  rgITSSideButtonsDownRight = 0x00000020,   // boutons latéraux placés en bas à droite
  rgITSSideButtonsDownLeft  = 0x00000028,   // boutons latéraux placés en bas à gauche

  // -- Side buttons definition options
  rgITSFolderButtons        = 0x00000100,   // include default all folders open / close buttons
  rgITSMoveButtons          = 0x00000200,   // include default in-folder move buttons
  rgITSEditButtons          = 0x00000400,   // include default edit buttons
  rgITSCustomButtons        = 0x00008000,   // custom side buttons will be added (for derived classes)

  rgITSDefaultButtons       = 0x00000F00,   // include all default standard side buttons
  rgITSSideButtons          = 0x00008F00,   // flags indicating that there are side buttons

  // -- Context menu definition options
  rgITSMenuItem             = 0x00040000,   // create a context menu for items
  rgITSMenuItemEdit         = 0x00140000,   // create a context menu with items edit entries
  rgITSMenuItemMove         = 0x00240000,   // create a context menu with items move entries

  rgITSMenuFolder           = 0x00080000,   // create a context menu for folders
  rgITSMenuFolderEdit       = 0x01080000,   // create a context menu to create a new sub-folder
  rgITSMenuFolderMove       = 0x02080000,   // create a context menu with folder move entries
  rgITSMenuFolderOpen       = 0x04080000,   // create a context menu with all folder open / close entries

  rgITSMenuCreate           = 0x000C0000,   // create a context menu for items and folders
  rgITSMenuDefault          = 0x0FFC0000,   // create a context menu with all predefined entries for items and folders

  // -- Selection options
  rgITSSingleSelection      = 0x00000000,   // Only 1 element may be selected
  rgITSMultipleSelection    = 0x10000000,   // Multiple elements selections

  // -- Tree structure options
  rgITSAutoCreateFolder     = 0x20000000,   // Automatically create required folders


  // -- Dummy
  rgITSDummy                = 0x00000000    // just to avoid coma problems
};

//======================================================================
/*! \class RGItemTreeSelector
 *
 *  This class defines a widget containing a tree of items for selection of
 *  elements.
 *  The elements are pointers on user objects, referred to by GItem
 *  objects.
 *
 *  In case of a single selection widget, no check-box is associated
 *  to the items in the tree view.
 *
 *  Objects in the tree are referred to using RGItem objects to refer to
 *  to them (RGItem is the class for the tree structure template).
 *  The user data of the tree nodes is used for the connection between
 *  the tree structure nodes and the tree view elements.
 *
 *  When selecting or unselecting a folder, all elements in that folder
 *  are selected or unselected.
 *
 *  The widget also provides also options for pre-defined actions (see
 *  option flags defined in RGItemTreeSelectorOptions) from buttons
 *  and context menu for tree elements.
 *  For these actions, a signal is emitted \b before the corresponding
 *  action is performed, so that, depending on the context, the
 *  calling object (embbeding the RGItemTreeSelector) can cancel the
 *  predefined action in a slot if it calls the CancelAction() function.
 *
 *  The optional button actions are
 *  - a set of \b move buttons to move elements up and down in their own
 *    folder
 *  - a set of \b move buttons (<b>new folder</b> creation, <b>new item</b>
 *    creation, selected item \b edit or \b delete)
 *  - buttons to open / close all folders (these actions do not check the
 *    action cancellation, since they do not alter the tree structure)
 *
 *  The optional context menus can be defined for folder elements or
 *  for item elements of the tree structure.
 *  The optional menu actions are:
 *  - menus to open / close all sub-folders
 *  - menus to move current element one level up (to parent folder) in
 *    the tree structure
 *
 *
 *  \par Adding custum buttons and menus
 *
 *  If the \b rgITSCustomButtons option is selected, a frame is added in the
 *  side buttons area to add extra user buttons.
 *  It is possible to add buttons in this frame with the AddSideButton
 *  functions.
 *  Such buttons will then emit the CustomClicked signal.
 *
 *  If the context menus have been defined for items and/or for folders,
 *  it is possible to add entries to these menus, with the AddMenuItemEntry
 *  and the AddMenuFolderEntry functions.
 *  Note that item and folder menus share the same processing function
 *  (MenuActivated) and signal (CustomMenuActivated), and entries identifiers
 *  should then be different for items and folders menus.
 *  Nevertheless, this does not need to the case if a menu may be defined
 *  for both items and folders (but the entry has to be defined explicitely
 *  for both).
 *  For custom menu entries identifiers, use values \b below 65536, since
 *  values above are used for predefined menus.
 *
 *
 *  \note
 *  - the user data of the TGListTreeItem elements of the tree view
 *    contain the pointer to the GItemTreeNote nodes of the tree structure
 *  - the user data of the nodes contain the pointer to the the
 *    TGListTreeItem elements
 *  - the user data of the RGItem (for tree leaves) is supposed to
 *    point on the program objects.
 *
 *
 *  \par Options defined in the RGItemTreeSelectorOptions enumeration
 *
 *  - Label options (related to TGGroupFrame base class)
 *    - \b rgITSLabelCenterAligned:     label is centered (default)
 *    - \b rgITSLabelLeftAligned:       label at left position
 *    - \b rgITSLabelRightAligned:      label at right position
 *    - \b rgITSLabelAboveList:         label is located above the list (default)
 *    - \b rgITSLabelBelowList:         label is located below the list
 *
 *  - Side buttons position options
 *    - \b rgITSSideButtonsRight:       side buttons on the right side (default)
 *    - \b rgITSSideButtonsLeft:        side buttons on the left side
 *    - \b rgITSSideButtonsCenter:      side buttons vertically centered (default)
 *    - \b rgITSSideButtonsUp:          side buttons vertically placed up
 *    - \b rgITSSideButtonsUpRight:     side buttons placed up and right
 *    - \b rgITSSideButtonsUpLeft:      side buttons placed up and left
 *    - \b rgITSSideButtonsDown:        side buttons vertically placed down
 *    - \b rgITSSideButtonsDownRight:   side buttons placed down and right
 *    - \b rgITSSideButtonsDownLeft:    side buttons placed down and left
 *
 *  - Side buttons actions options
 *    - \b rgITSFolderButtons:          include buttons for open / close of all folders
 *    - \b rgITSMoveButtons:            include default move buttons (move up, down, top, bottom)
 *    - \b rgITSEditButtons:            include default edition buttons (new folder, new item, edit and delete)
 *    - \b rgITSCustomButtons:          custom side buttons will be added (for derived classes)
 *
 *  - Context menu options
 *    - \b rgITSMenuItem:               create the context menu for items (empty menu)
 *    - \b rgITSMenuItemMove:           define items context menu entries to move element top or to another folder
 *    - \b rgITSMenuItemEdit:           define items context menu entries to edit elements
 *
 *    - \b rgITSMenuFolder:             create the context menu for folders (empty menu)
 *    - \b rgITSMenuFolderOpen:         define folders context menu entries for open / close of all folders (same as corresponding buttons)
 *    - \b rgITSMenuFolderEdit:         define folders context menu entries create a new sub-folder
 *    - \b rgITSMenuFolderMove:         define folders context menu entries to move element top or to another folder
 *
 *    - \b rgITSMenuDefault:            create all predefined entries for context menus
 *
 *  - Tree structure and selection options
 *    - \b rgITSSingleSelection:        single selection only (default)
 *    - \b rgITSMultipleSelection:      multiple selection 
 *    - \b rgITSAutoCreateFolder:       automatically create folders if needed
 *                                      when adding elements
 *
 *  \par Tree structure organisation
 *
 *
 *  \image html RGItemTreeSelector.png
 *  
 */
class RGItemTreeSelector : public TGGroupFrame
{
  //------------------------------------------------------------
  /*! \object_doc{RGItemTreeSelector} */
  GObject(RGItemTreeSelector);
  //------------------------------------------------------------

  public:
    /*! Values associated to default context menus.
     *  If a menu is defined for both folders and items, the menu identification
     *  value is the same.
     */
    enum TreeContextMenu
    {
      menuFoldersOpen     = 0x00010000,
      menuFoldersOpenAll  = 0x00020000,
      menuFoldersClose    = 0x00030000,
      menuFoldersCloseAll = 0x00040000,

      menuMoveTop         = 0x00100000,
      menuMoveUp          = 0x00200000,
      menuMoveDown        = 0x00300000,
      menuMoveBottom      = 0x00400000,
      menuMoveToFolder    = 0x00500000,
      menuMoveToParent    = 0x00600000,

      menuFolderCreate    = 0x00700000,
      menuFolderNewItem   = 0x00800000,
      menuItemEdit        = 0x00900000,
      menuItemDelete      = 0x00A00000,

      menuDummy           = 0x00000000
    };

  protected:

    string              default_element_pic;  ///< Default picture name for elements

    UInt_t              tree_w_min;         ///< Tree widget minimum width
    UInt_t              tree_h_min;         ///< Tree widget minimum height

    UInt_t              options;            ///< Widget options

    GItemTreeBranch   * root_node;          ///< Root tree node of GItems
    bool                local_tree;         ///< Indicates if the tree is created internally and should be deleted with the widget

    // sub-widgets
    TGHorizontalFrame   * w_widgets_frame;  ///< Main frame
    TGVerticalFrame     * w_tree_frame;     ///< Tree and side buttons frame

    TGCanvas            * w_tree_canvas;    ///< Canvas holding the tree widget
    TGListTree          * w_tree;           ///< Tree (list-tree) widget

    TGHorizontalFrame   * w_button_frame;   ///< List buttons frame
    TGTextButton        * w_all_button;     ///< All elements selection button
    TGTextButton        * w_none_button;    ///< None elements selection button
    TGTextButton        * w_invert_button;  ///< Invert selection button

    // - side frame for additional buttons
    TGVerticalFrame     * w_side_frame;         ///< Side buttons frame

    TGVerticalFrame     * w_folder_buttons_frame; ///< Frame for folder buttons
    TGTextButton        * w_open_all_button;        ///< Open all folders button
    TGTextButton        * w_close_all_button;       ///< Close all folders button

    TGVerticalFrame     * w_move_buttons_frame;   ///< Frame for move buttons
    TGTextButton        * w_move_up_button;         ///< In-folder selected item move button
    TGTextButton        * w_move_down_button;       ///< In-folder selected item move button
    TGTextButton        * w_move_top_button;        ///< In-folder selected item move button
    TGTextButton        * w_move_bottom_button;     ///< In-folder selected item move button
    TGTextButton        * w_move_parent_button;     ///< Button to move selected item to its parent folder
    TGTextButton        * w_move_folder_button;     ///< Button to move selected item to another folder

    TGVerticalFrame     * w_edit_buttons_frame;   ///< Frame for edit buttons
    TGTextButton        * w_new_folder_button;      ///< New folder creation button
    TGTextButton        * w_new_item_button;        ///< New element definition button
    TGTextButton        * w_edit_item_button;       ///< Edit element button
    TGTextButton        * w_delete_button;          ///< Delete button

    TGVerticalFrame     * w_custom_buttons_frame; ///< Frame for additional buttons

    // - contex menus
    TGPopupMenu         * w_menu_item;      ///< Define the context menu for item selected
    TGPopupMenu         * w_menu_folder;    ///< Define the context menu for folder selected

    // this is defined to be able to unselect a selected item
    TGListTreeItem *      prev_selected;    ///< Previously selected item

    Bool_t                cancel_action;    ///< Flag for cancellation of default requested action


  //------------------------------------------------------------
  /** @name Constructors, affectation, destructor */
  //@{
  public:
    RGItemTreeSelector ( TGWindow    * p,
                         const char  * label = NULL,
                         const UInt_t  opts  = 0,
                         const UInt_t  w_min = 160,
                         const UInt_t  h_min = 200 );
    
  protected:
    RGItemTreeSelector ( const RGItemTreeSelector &original );

  public:
    virtual ~RGItemTreeSelector ( );
  //@}

  //------------------------------------------------------------
  /** @name Sub-widgets functions */
  //@{
    virtual TGListTree        * GetListTree  ( ) const;       // inline

    virtual TGTextButton      * GetAllButton    ( ) const;    // inline
    virtual TGTextButton      * GetNoneButton   ( ) const;    // inline
    virtual TGTextButton      * GetInvertButton ( ) const;    // inline

    // default standard side buttons
    virtual TGVerticalFrame   * GetSideButtonsFrame ( ) const;  // inline

    virtual TGVerticalFrame   * GetFoldersButtonsFrame ( ) const;   // inline
    virtual TGTextButton      * GetFoldersOpenButton   ( ) const;   // inline
    virtual TGTextButton      * GetFoldersCloseButton  ( ) const;   // inline

    virtual TGVerticalFrame   * GetMoveButtonsFrame ( ) const;      // inline
    virtual TGTextButton      * GetMoveUpButton     ( ) const;      // inline
    virtual TGTextButton      * GetMoveDownButton   ( ) const;      // inline
    virtual TGTextButton      * GetMoveTopButton    ( ) const;      // inline
    virtual TGTextButton      * GetMoveBottomButton ( ) const;      // inline
    virtual TGTextButton      * GetMoveParentButton ( ) const;      // inline
    virtual TGTextButton      * GetMoveFolderButton ( ) const;      // inline

    virtual TGVerticalFrame   * GetEditButtonsFrame ( ) const;      // inline
    virtual TGTextButton      * GetNewFolderButton  ( ) const;      // inline
    virtual TGTextButton      * GetNewItemButton    ( ) const;      // inline
    virtual TGTextButton      * GetEditItemButton   ( ) const;      // inline
    virtual TGTextButton      * GetDeleteButton     ( ) const;      // inline

    virtual TGVerticalFrame   * GetCustomButtonsFrame  ( ) const;   // inline

    // adding widget capabilities
    virtual TGButton          * AddSideButton  ( const char *text, const Int_t id, TGLayoutHints *l, const char *tooltip = NULL );
    virtual TGButton          * AddSideButton  ( TGButton *but, const Int_t id, TGLayoutHints *l );
    virtual TGFrame           * AddSideFrame   ( TGFrame *f, TGLayoutHints *l = NULL );
    virtual TGFrame           * AddBottomFrame ( TGFrame *f, TGLayoutHints *l = NULL );

    virtual void  AddMenuItemSeparator ( );
    virtual void  AddMenuItemEntry ( const string & title, Int_t id );
    virtual void  AddMenuItemEntry ( const string & title, TGPopupMenu * submenu );

    virtual void  AddMenuFolderSeparator ( );
    virtual void  AddMenuFolderEntry ( const string & title, Int_t id );
    virtual void  AddMenuFolderEntry ( const string & title, TGPopupMenu * submenu );
  //@}

  //------------------------------------------------------------
  /** @name Widget functions */
  //@{
    Bool_t  MultipleSelection ( ) const;    // inline

  protected:
    virtual void  Construct     ( );

  public:
    virtual void  MapSubwindows   ( );
    virtual void  RefreshTreeView ( );
  //@}

  //------------------------------------------------------------
  /** @name Internal functions (no need to be protected) */
  //@{
    virtual void  UpdateItemSelection    ( GItemTreeBranch * branch = NULL );

    virtual void  RecreateTreeDisplay    ( );
    virtual void  RecreateTreeSubDisplay ( GItemTreeBranch * branch );

    virtual void  UpdateTreeDisplay      ( );
    virtual void  UpdateButtonsState     ( );
    virtual void  UpdateMenuItem         ( GItemTreeLeaf   * leaf   );
    virtual void  UpdateMenuFolder       ( GItemTreeBranch * branch );
  //@}

  //------------------------------------------------------------
  /** @name Tree structure functions */
  //@{
    const GItemTreeBranch * GetTreeRoot ( ) const;    // inline
    void                    SetDefaultPicture ( const string & pic_name );  // inline

    GItemTreeBranch   * AddFolder  ( const string & name );
    GItemTreeBranch   * AddFolder  ( GItemTreeBranch * parent, const string & name );
    GItemTreeLeaf     * AddElement ( const string & name, void * data, const TGPicture * pic = NULL );
    GItemTreeLeaf     * AddElement ( GItemTreeBranch * parent, const string & name, void * data, const TGPicture * pic = NULL );

    GItemTreeBranch   * SetRootNode ( GItemTreeBranch * root, bool adopt = false );

    virtual TGListTreeItem  * SelectItem ( GItemTreeNode  * node );
    virtual TGListTreeItem  * SelectItem ( TGListTreeItem * elem );

    GItemTreeNode  * GetSelected     ( ) const;
    GItemTreeLeaf  * GetSelectedLeaf ( ) const;
  //@}

  //------------------------------------------------------------
  /** @name Buttons / menu related actions */

    // functions called from buttons and menus
    virtual void        OpenSelectedSubFolders  ( );
    virtual void        CloseSelectedSubFolders ( );
    virtual void        OpenSubFolders  ( TGListTreeItem * item );
    virtual void        CloseSubFolders ( TGListTreeItem * item );

    virtual void        OpenAllFolders  ( );
    virtual void        CloseAllFolders ( );

    // move buttons / menus
    virtual void        MoveSelectedMoveTop    ( Bool_t emit = kTRUE );
    virtual void        MoveSelectedMoveUp     ( Bool_t emit = kTRUE );
    virtual void        MoveSelectedMoveDown   ( Bool_t emit = kTRUE );
    virtual void        MoveSelectedMoveBottom ( Bool_t emit = kTRUE );
    virtual void        MoveSelectedToParent   ( Bool_t emit = kTRUE );
    virtual void        MoveSelectedToFolder   ( Bool_t emit = kTRUE );

    // edit buttons / menus
    virtual void        CreateNewFolder ( );
    virtual void        CreateSubFolder ( GItemTreeBranch * parent );
    virtual void        CreateNewItem       ( );
    virtual void        EditSelectedItem    ( );
    virtual void        DeleteSelectedItem  ( );
    virtual void        DeleteItem          ( GItemTreeLeaf   * item,   bool update = true );
    virtual void        DeleteFolder        ( GItemTreeBranch * branch, bool update = true );

    virtual void        CancelAction          ( const Bool_t cancel = kTRUE );  // inline
    virtual Bool_t      GetCancelActionState  ( ) const;                        // inline

  //@}

  //------------------------------------------------------------
  /** @name Slots from sub-widgets */
  //@{
  public:

    virtual void  SelectAll     ( );
    virtual void  SelectNone    ( );
    virtual void  SelectInvert  ( );

    virtual void  TreeClicked       ( TGListTreeItem * item, Int_t btn );
    virtual void  TreeDoubleClicked ( TGListTreeItem * item, Int_t btn );
    virtual void  TreeReturnPressed ( TGListTreeItem * item );

    virtual void  ItemChecked ( TObject * obj, Bool_t check );

    virtual void  ProcessedEvent    ( Event_t * event );
    virtual void  MenuActivated     ( Int_t id );
  //@}

  //------------------------------------------------------------
  /** @name Signals */
  //@{

    // Multiple selection buttons signals
    virtual void  SelectAllClicked    ( );   // *SIGNAL*
    virtual void  SelectNoneClicked   ( );   // *SIGNAL*
    virtual void  SelectInvertClicked ( );   // *SIGNAL*

    // Signals from tree-list
    virtual void  SelectionChanged ( );         // *SIGNAL*

    // Side buttons signals
    virtual void  MoveUpClicked       ( );        // *SIGNAL*
    virtual void  MoveDownClicked     ( );        // *SIGNAL*
    virtual void  MoveTopClicked      ( );        // *SIGNAL*
    virtual void  MoveBottomClicked   ( );        // *SIGNAL*
    virtual void  MoveToParentClicked ( );        // *SIGNAL*
    virtual void  MoveToFolderClicked ( );        // *SIGNAL*

    virtual void  SelectionMoved    ( );          // *SIGNAL*

    virtual void  NewFolderClicked  ( );          // *SIGNAL*
    virtual void  NewItemClicked    ( );          // *SIGNAL*
    virtual void  EditItemClicked   ( );          // *SIGNAL*
    virtual void  DeleteClicked     ( );          // *SIGNAL*

    virtual void  NewFolderCreated  ( TGListTreeItem  * item );   // *SIGNAL*
    virtual void  CreateItem        ( GItemTreeBranch * parent ); // *SIGNAL*
    virtual void  EditItem          ( GItemTreeLeaf   * item );   // *SIGNAL*
    virtual void  ItemRemoved       ( void * data );              // *SIGNAL*

    virtual void  CustomClicked       ( Int_t id );   // *SIGNAL*
    virtual void  CustomMenuActivated ( Int_t id );   // *SIGNAL*

    virtual void  SingleSelected      ( ULong64_t leaf_ptr );  // *SIGNAL*
  //@}

  //------------------------------------------------------------
  /** @name ROOT related functions */
  //@{
    /*! For ROOT dictionary.*/
    ClassDef(RGItemTreeSelector,0);
  //@}
};

//----------------------------------------------------------------------
//  Inline functions
#include "icc/RGItemTreeSelector.icc"

//======================================================================
#endif