TreeDisplay.hxx

Go to the documentation of this file.

// =============================================================== //
//                                                                 //
//   File      : TreeDisplay.hxx                                   //
//   Purpose   :                                                   //
//                                                                 //
//   Institute of Microbiology (Technical University Munich)       //
//   http://www.arb-home.de/                                       //
//                                                                 //
// =============================================================== //

#ifndef TREEDISPLAY_HXX
#define TREEDISPLAY_HXX

#ifndef AP_TREE_HXX
#include <AP_Tree.hxx>
#endif
#ifndef GROUP_HXX
#include <Group.hxx>
#endif
#ifndef AWT_CANVAS_HXX
#include <awt_canvas.hxx>
#endif
#ifndef _GLIBCXX_VECTOR
#include <vector>
#endif
#ifndef _GLIBCXX_MAP
#include <map>
#endif

// Increase stacklimit to 20Mb (before was ~8Mb on my system).
// This was done to fix #824 (crash on display of huge trees).
#define TREEDISP_STACKSIZE (1024L*1024L*20) // stacksize required for tree-display

// the possible MAX_TREEDISP_RECURSION_DEPTH corresponds with the TREEDISP_STACKSIZE:
#define MAX_TREEDISP_RECURSION_DEPTH 20000
#define TREEDISP_TRUNCATION_MESSAGE "Warning: depth limit reached => subtree not shown (use logical zoom to workaround)"


#define td_assert(cond) arb_assert(cond)

#define AWAR_DTREE_BASELINEWIDTH   "awt/dtree/baselinewidth"
#define AWAR_DTREE_VERICAL_DIST    "awt/dtree/verticaldist"
#define AWAR_DTREE_BRANCH_STYLE    "awt/dtree/branch_style"
#define AWAR_DTREE_ATTACH_SIZE     "awt/dtree/attach_size"
#define AWAR_DTREE_ATTACH_LEN      "awt/dtree/attach_len"
#define AWAR_DTREE_ATTACH_GROUP    "awt/dtree/attach_group"
#define AWAR_DTREE_GROUP_DOWNSCALE "awt/dtree/downscaling"
#define AWAR_DTREE_GROUP_SCALE     "awt/dtree/groupscaling"
#define AWAR_DTREE_AUTO_JUMP       "awt/dtree/autojump"
#define AWAR_DTREE_AUTO_JUMP_TREE  "awt/dtree/autojump_tree"
#define AWAR_DTREE_AUTO_UNFOLD     "awt/dtree/auto_unfold"
#define AWAR_DTREE_SHOW_BRACKETS   "awt/dtree/show_brackets"
#define AWAR_DTREE_GROUP_STYLE     "awt/dtree/groupstyle"
#define AWAR_DTREE_GROUP_ORIENT    "awt/dtree/grouporient"
#define AWAR_DTREE_GREY_LEVEL      "awt/dtree/greylevel"
#define AWAR_DTREE_GROUPCOUNTMODE  "awt/dtree/groupcountmode"
#define AWAR_DTREE_GROUPINFOPOS    "awt/dtree/groupinfopos"

#define AWAR_DTREE_BOOTSTRAP_MIN   "awt/dtree/bootstrap/min"
#define AWAR_DTREE_BOOTSTRAP_MAX   "awt/dtree/bootstrap/max"
#define AWAR_DTREE_BOOTSTRAP_SHOW  "awt/dtree/bootstrap/show"
#define AWAR_DTREE_BOOTSTRAP_STYLE "awt/dtree/bootstrap/style"
#define AWAR_DTREE_CIRCLE_SHOW     "awt/dtree/bootstrap/circle/show"
#define AWAR_DTREE_CIRCLE_FILL     "awt/dtree/bootstrap/circle/fill"
#define AWAR_DTREE_CIRCLE_ELLIPSE  "awt/dtree/bootstrap/circle/ellipse"
#define AWAR_DTREE_CIRCLE_ZOOM     "awt/dtree/bootstrap/circle/zoom"
#define AWAR_DTREE_CIRCLE_LIMIT    "awt/dtree/bootstrap/circle/limit"

#define AWAR_DTREE_RADIAL_ZOOM_TEXT "awt/dtree/radial/zoomtext"
#define AWAR_DTREE_RADIAL_XPAD      "awt/dtree/radial/xpadding"

#define AWAR_DTREE_DENDRO_ZOOM_TEXT "awt/dtree/dendro/zoomtext"
#define AWAR_DTREE_DENDRO_XPAD      "awt/dtree/dendro/xpadding"

#define AWAR_DTREE_GROUP_MARKED_THRESHOLD           "awt/dtree/markers/group_marked_threshold"
#define AWAR_DTREE_GROUP_PARTIALLY_MARKED_THRESHOLD "awt/dtree/markers/group_partially_marked_threshold"
#define AWAR_DTREE_MARKER_WIDTH                     "awt/dtree/markers/marker_width"
#define AWAR_DTREE_PARTIAL_GREYLEVEL                "awt/dtree/markers/partial_greylevel"

#define NT_BOX_WIDTH      7   // pixel
#define NT_DIAMOND_RADIUS 5
#define NT_ROOT_WIDTH     9
#define NT_SELECTED_WIDTH 11

#define AWT_TREE(ntw) (ntw)->get_graphic_tree()

enum AP_tree_display_style {
    AP_TREE_NORMAL, // normal tree display (dendrogram)
    AP_TREE_RADIAL, // radial tree display
    AP_TREE_IRS, // like AP_TREE_NORMAL, with folding line
    AP_LIST_NDS,
    AP_LIST_SIMPLE // simple display only showing name (used at startup to avoid NDS error messages)
};

enum AP_tree_jump_type {         // bit-values
    AP_JUMP_KEEP_VISIBLE   = 1,  // automatically make selected node visible (on changes)          [VALUE STORED IN AWAR!]
    AP_JUMP_LOGICAL_UNZOOM = 2,  // adapts logical zoom (if target is outside zoomed subtree)
    AP_JUMP_FORCE_VCENTER  = 4,  // force vertical centering (even if visible)
    AP_JUMP_ALLOW_HCENTER  = 8,  // force horizontal centering (if vertically centered); only works together with AP_JUMP_FORCE_VCENTER
    AP_JUMP_FORCE_HCENTER  = 16, // force horizontal centering
    AP_JUMP_BE_VERBOOSE    = 32, // tell why nothing happened etc.
    AP_JUMP_AUTO_UNFOLD    = 64, // temporarily auto-unfold folded target node

    // convenience defs:
    AP_DONT_JUMP         = 0,                                           // [VALUE STORED IN AWAR!]
    AP_JUMP_SMART_CENTER = AP_JUMP_FORCE_VCENTER|AP_JUMP_ALLOW_HCENTER, // [VALUE STORED IN AWAR!]
    AP_JUMP_FORCE_CENTER = AP_JUMP_FORCE_VCENTER|AP_JUMP_FORCE_HCENTER, // [VALUE STORED IN AWAR!]

    AP_JUMP_BY_BUTTON = AP_JUMP_SMART_CENTER|AP_JUMP_LOGICAL_UNZOOM|AP_JUMP_AUTO_UNFOLD|AP_JUMP_BE_VERBOOSE,
};

enum AP_tree_jump_reason {
    AP_JUMP_REASON_TREE,
    AP_JUMP_REASON_STYLE,
    AP_JUMP_REASON_SPECIES,
    AP_JUMP_REASON_GROUP,
};

enum ClickedType {
    CL_NODE = 1,
    CL_SPECIES,
    CL_RULER,
    CL_FLAG,
    CL_BRANCH,
    CL_ROOTNODE,
};

inline bool is_list_style(AP_tree_display_style style) { return style == AP_LIST_NDS || style == AP_LIST_SIMPLE; }
inline bool is_tree_style(AP_tree_display_style style) { return !is_list_style(style); }

class NDS_Labeler;
class AWT_graphic_tree_group_state;

struct AWT_scaled_font_limits {
    double ascent;
    double descent;
    double height;
    double width;

    void init(const AW_font_limits& font_limits, double factor) {
        ascent  = font_limits.ascent*factor;
        descent = font_limits.descent*factor;
        height  = font_limits.get_height()*factor;
        width   = font_limits.width*factor;
    }
};

enum AD_MAP_VIEWER_TYPE {
    ADMVT_NONE = 0,
    ADMVT_INFO,
    ADMVT_WWW,
    ADMVT_SELECT
};

typedef void (*AD_map_viewer_cb)(GBDATA *gbd, AD_MAP_VIEWER_TYPE type);

struct DendroSubtreeLimits {
    double y_branch;                                // ypos of branch to subtree
    double y_top;                                   // top ypos of whole subtree
    double y_bot;                                   // bottom ypos of whole subtree
    double x_right;                                 // rightmost xpos of whole subtree

    void combine(const DendroSubtreeLimits& other) {
        y_top   = std::min(y_top, other.y_top);
        y_bot   = std::max(y_bot, other.y_bot);
        x_right = std::max(x_right, other.x_right);
    }
};

struct AWT_command_data {
    virtual ~AWT_command_data() {}
};

enum CollapseMode {
    COLLAPSE_ALL      = 0,
    EXPAND_MARKED     = 1,  // do not collapse groups containing marked species
    COLLAPSE_TERMINAL = 2,  // do not collapse groups with subgroups
    EXPAND_ALL        = 4,
    EXPAND_COLOR      = 8,  // do not collapse groups containing species with color == parameter 'color_group' (or any color if 'color_group' is -1)
    EXPAND_ZOMBIES    = 16, // do not collapse groups containing zombies
    EXPAND_UNMARKED   = 32, // do not collapse groups containing unmarked species
};

class NodeMarkers {
    // represents markers at a node (species or group)

    int              nodeSize; // number of species in group (or 1)
    std::vector<int> mark;     // how often each marker is set in group
public:
    NodeMarkers() {} // default for cache
    explicit NodeMarkers(int numMarks)
        : nodeSize(0),
          mark(numMarks, 0)
    {}

    void incMarker(size_t markerIdx) {
        td_assert(markerIdx<mark.size());
        mark[markerIdx]++;
    }
    int markerCount(size_t markerIdx) const {
        td_assert(markerIdx<mark.size());
        return mark[markerIdx];
    }

    void incNodeSize() { nodeSize++; }
    int getNodeSize() const { return nodeSize; }

    double getMarkRate(size_t markerIdx) const { return markerCount(markerIdx) / double(getNodeSize()); }

    void add(const NodeMarkers& other) {
        size_t size = mark.size();
        td_assert(size == other.mark.size());
        for (size_t i = 0; i<size; ++i) {
            mark[i] += other.mark[i];
        }
        nodeSize += other.nodeSize;
    }
};

class MarkerDisplay {
    // defines which markers shall be displayed

    typedef std::map<const AP_tree*,NodeMarkers> GroupMarkerCache;

    GroupMarkerCache cache;
    int              numMarkers;

public:
    MarkerDisplay(int numMarkers_)
        : numMarkers(numMarkers_)
    {
        td_assert(numMarkers>0);
    }
    virtual ~MarkerDisplay() {}

    virtual const char *get_marker_name(int markerIdx) const                                      = 0;
    virtual void retrieve_marker_state(const char *speciesName, NodeMarkers& matches)             = 0;
    virtual void handle_click(int markerIdx, AW_MouseButton button, AWT_graphic_exports& exports) = 0;

    const NodeMarkers *read_cache(const AP_tree *at) const {
        GroupMarkerCache::const_iterator found = cache.find(at);
        return found == cache.end() ? NULp : &found->second;
    }
    void write_cache(const AP_tree *at, const NodeMarkers& markers) { cache[at] = markers; }
    void flush_cache() { cache.erase(cache.begin(), cache.end()); }
#if defined(ASSERTION_USED)
    bool cache_is_flushed() const { return cache.empty(); }
#endif

    int size() const { return numMarkers; }
};

struct GroupInfo {
    const char *name;
    const char *count;
    unsigned    name_len;
    unsigned    count_len;
};

enum GroupInfoMode {
    GI_COMBINED,             // only sets GroupInfo::name (will contain "name (count)" or only "name" if counters disabled)
    GI_SEPARATED,            // set GroupInfo::name and GroupInfo::count (to "name" and "count")
    GI_SEPARATED_PARENTIZED, // like GI_SEPARATED, but GroupInfo::count will be "(count)"
};

enum GroupInfoPosition {
    GIP_SEPARATED, // name attached, count overlayed             (=old hardcoded default for AP_TREE_NORMAL and AP_TREE_IRS)
    GIP_ATTACHED,  // "name (count)" attached "next to" group    (=old hardcoded default for AP_TREE_RADIAL)
    GIP_OVERLAYED, // "name (count)" overlayed with group polygon
};

enum GroupCountMode {
    GCM_NONE,    // do not show group count         (=old hardcoded default for AP_TREE_RADIAL)
    GCM_MEMBERS, // show number of group members    (=old hardcoded default for AP_TREE_NORMAL and AP_TREE_IRS)
    GCM_MARKED,  // show number of marked group members (show nothing if none marked)
    GCM_BOTH,    // show "marked/members" (or "members" if none marked)
    GCM_PERCENT, // show percent of marked group members (show nothing if none marked)
    GCM_BOTH_PC, // show "percent/members" (or "members" if none marked)
};

enum BranchStyle {
    BS_RECTANGULAR, // traditional rectangular branches
    BS_DIAGONAL,    // diagonal branches (directly from fathers to sons attach point)
};

enum GroupStyle {
    GS_TRAPEZE, // traditional style
    GS_TRIANGLE,
};

enum GroupOrientation {
    GO_TOP,      // long clade side at top
    GO_BOTTOM,   // long clade side at bottom
    GO_INTERIOR, // long clade side towards center of subtree
    GO_EXTERIOR, // long clade side towards margin of subtree
};

class AWT_graphic_tree;
DECLARE_CBTYPE_FVV_AND_BUILDERS(GraphicTreeCallback, void, AWT_graphic_tree*); // generates makeGraphicTreeCallback

class PaintedNode {
    AW::Position  pos;
    AP_tree      *node;
public:
    PaintedNode() : pos(AW::Origin), node(NULp) {}
    PaintedNode(const PaintedNode& other) : pos(other.pos), node(other.node) {}
    PaintedNode(const AW::Position& p, AP_tree *n) : pos(p), node(n) {}
    DECLARE_ASSIGNMENT_OPERATOR(PaintedNode);
    ~PaintedNode() {}

    bool was_displayed() const { return node || are_distinct(AW::Origin, pos); }

    const AW::Position& get_pos() const { return pos; }
    AP_tree *get_node() const { return node; } // NULp in list-mode or if got no tree
};

enum BootstrapStyle {
    BS_PERCENT,
    BS_PERCENT_NOSIGN,
    BS_FLOAT,
};

struct BootstrapConfig {
    const AW_bitset circle_filter;
    const AW_bitset text_filter;

    int bootstrap_min; // minimum shown bootstrap (lower values are hidden)
    int bootstrap_max; // maximum shown bootstrap (higher values are hidden)

    BootstrapStyle style;

    bool  show_boots;
    bool  show_circle;
    float fill_level;
    bool  elipsoid;

    bool show_100_if_empty; // automatically add 100% at branches w/o bootstraps (last loaded state contains bootstraps!)

    float zoom_factor;
    float max_radius;

    double scaled_remark_ascend;

    BootstrapConfig();

    void display_remark(AW_device *device, const char *remark, const AW::Position& center, double blen, double bdist, const AW::Position& textpos, AW_pos alignment) const;
    void display_node_remark(AW_device *device, const AP_tree *at, const AW::Position& center, double blen, double bdist, AW::RoughDirection textArea) const;

    void update_empty_branch_behavior(const TreeRoot *troot)  {
        show_100_if_empty = troot->has_bootstrap();
    }

    bool shall_show_remark_for(const TreeNode *node) const {
        return !node->is_leaf() && (show_100_if_empty || node->get_remark_ptr().isSet());
    }
};

class AWT_graphic_tree : public AWT_graphic, virtual Noncopyable {
    char  *species_name;
    Group  selected_group;

    PaintedNode selSpec;   // is set while tree display gets refreshed
    PaintedNode selGroup;  // is set while tree display gets refreshed // @@@ no need to store node; store rectangle area instead of position

    int baselinewidth;

    BootstrapConfig bconf;

    int zombies;    // # of zombies during last load()
    int duplicates; // # of duplicates during last load()

    AP_tree *tree_proto;

    bool show_brackets;

    bool link_to_database; // link on load?

    GroupStyle       group_style;
    GroupOrientation group_orientation;

    double list_tree_ruler_y;
    double irs_tree_ruler_scale_factor;
    double attach_size;   // 1.0 = at bigger subtree ; 0.0 = centered;         -1.0 = at smaller subtree (trad.)
    double attach_len;    // 1.0 = at longer branch;   0.0 = centered (trad.); -1.0 = at shorter branch
    double attach_group;  // 1.0 = at longer side;     0.5 = centered (trad.);  0.0 = at shorter side (of group polygon)

    AWT_scaled_font_limits scaled_font;

    double scaled_branch_distance; // vertical distance between branches (may be extra-scaled in options)

    AW_grey_level group_greylevel;
    AW_grey_level marker_greylevel;

    AW_device *disp_device; // device for recursive functions

    const AW_bitset line_filter, vert_line_filter, mark_filter, group_bracket_filter;
    const AW_bitset leaf_text_filter, group_text_filter, other_text_filter;
    const AW_bitset ruler_filter, root_filter, marker_filter;

    GroupInfoPosition group_info_pos;
    GroupCountMode    group_count_mode;
    BranchStyle       branch_style;

    MarkerDisplay *display_markers;
    struct {
        double marked;
        double partiallyMarked;
    } groupThreshold;

    AD_map_viewer_cb  map_viewer_cb;
    AWT_command_data *cmd_data;

    AP_tree_root *tree_static;
    AP_tree      *displayed_root; // root node of shown (sub-)tree; differs from real root if tree is zoomed logically

    GraphicTreeCallback tree_changed_cb;
    static GraphicTreeCallback group_changed_cb;

    class AP_tree_folding *autoUnfolded;

    AW_root *aw_root;
    GBDATA  *gb_main;

    AP_tree_display_style tree_style;
    bool                  nds_only_marked; // true -> display only marked species (only for list-styles)

    AW_pos paint_irs_sub_tree(AP_tree *node, AW_pos x_offset, const NDS_Labeler& labeler); // returns y pos
    void   unload();

    // functions to compute displayinformation

    void show_dendrogram(AP_tree *at, AW::Position& pen, DendroSubtreeLimits& limits, const NDS_Labeler& labeler);
    void show_radial_tree(AP_tree *at, const AW::Position& base, const AW::Position& tip, const AW::Angle& orientation, const double tree_spread, const NDS_Labeler& labeler);
    void show_nds_list(GBDATA * gb_main, bool use_nds, const NDS_Labeler& labeler);
    void show_irs_tree(AP_tree *at, double height, const NDS_Labeler& labeler);

    void summarizeGroupMarkers(AP_tree *at, NodeMarkers& markers);
    void drawMarker(const class MarkerPosition& marker, const bool partial, const int midx);
    void detectAndDrawMarkers(AP_tree *at, double y1, double y2);
    void drawMarkerNames(AW::Position& Pen);

    void pixel_box(int gc, const AW::Position& pos, int pixel_width, AW::FillStyle filled);

    AP_tree *find_selected_node() const;
    AP_tree *find_selected_group();

    void toggle_folding_at(AP_tree *at, bool force_jump);

    const GroupInfo& get_group_info(AP_tree *at, GroupInfoMode mode, bool swap, const NDS_Labeler& labeler) const;

    bool handle_cursor(AW_key_code kcode, AW_key_mod mod);
    void handle_key(AW_device *device, AWT_graphic_event& event);

    GB_ERROR create_group(AP_tree * at) __ATTR__USERESULT;

protected:
    group_scaling groupScale; // scaling for folded groups

    void store_command_data(AWT_command_data *new_cmd_data) {
        delete cmd_data;
        cmd_data = new_cmd_data;
    }
    AWT_command_data *get_command_data() { return cmd_data; }

public:
    AWT_graphic_tree(AW_root *aw_root, GBDATA *gb_main, AD_map_viewer_cb map_viewer_cb);
    ~AWT_graphic_tree() OVERRIDE;

    void filled_box(int gc, const AW::Position& pos, int pixel_width) { pixel_box(gc, pos, pixel_width, AW::FillStyle::SOLID); }
    void empty_box(int gc, const AW::Position& pos, int pixel_width) { pixel_box(gc, pos, pixel_width, AW::FillStyle::EMPTY); }
    void diamond(int gc, const AW::Position& pos, int pixel_radius);

    const char *ruler_awar(const char *name);

    void set_line_attributes_for(AP_tree *at) const {
        disp_device->set_line_attributes(at->gr.gc, at->get_linewidth()+baselinewidth, AW_SOLID);
    }

    virtual void read_tree_settings();
    void update_structure() FINAL_OVERRIDE {
        AP_tree *root = get_root_node();
        if (root) {
            forget_auto_unfolded();
            root->compute_tree();
        }
    }
    void apply_zoom_settings_for_treetype(AWT_canvas *ntw);

    int draw_branch_line(int gc, const AW::Position& root, const AW::Position& leaf, AW_bitset filter) {
        const AW_click_cd *old = disp_device->get_click_cd();
        td_assert(old && old->get_cd1() && old->get_cd2() == CL_NODE); // cd1 should be the node

        AW_click_cd branch(disp_device, old->get_cd1(), CL_BRANCH);
        return disp_device->line(gc, root, leaf, filter);
    }

    bool warn_inappropriate_mode(AWT_COMMAND_MODE mode);

    virtual AP_tree_root *create_tree_root(AliView *aliview, AP_sequence *seq_prototype, bool insert_delete_cbs);

    AW_root *get_root() const { return aw_root; }
    GBDATA *get_gbmain() const { return gb_main; }

    AP_tree_root *get_tree_root() { return tree_static; }

    AP_tree       *get_root_node()       { return tree_static ? tree_static->get_root_node() : NULp; }
    const AP_tree *get_root_node() const { return const_cast<AWT_graphic_tree*>(this)->get_root_node(); }

    AP_tree       *get_logical_root()       { return displayed_root; }
    const AP_tree *get_logical_root() const { return displayed_root; }

    bool is_logically_zoomed() { return displayed_root != get_root_node(); }
    void set_logical_root_to(AP_tree *node) {
        displayed_root = node;
        tree_changed_cb(this);
    }

    void init(AliView *aliview, AP_sequence *seq_prototype, bool link_to_database_, bool insert_delete_cbs);
    AW_gc_manager *init_devices(AW_window *, AW_device *, AWT_canvas *ntw) OVERRIDE;

    void show(AW_device *device) OVERRIDE;
    const AW::Position& get_cursor() const { return selSpec.get_pos(); }
    const AW::Position& get_group_cursor() const { return selGroup.get_pos(); }

    void handle_command(AW_device *device, AWT_graphic_event& event) OVERRIDE;

    long mark_species_in_tree(AP_tree *at, int mark);
    long mark_species_in_tree_that(AP_tree *at, int mark, bool (*condition)(GBDATA*, void*), void *cd);

    void mark_species_in_rest_of_tree(AP_tree *at, int mark);

    bool tree_has_marks(AP_tree *at);
    bool rest_tree_has_marks(AP_tree *at);

    void detect_group_state(AP_tree *at, AWT_graphic_tree_group_state *state, AP_tree *skip_this_son);

    bool group_tree(AP_tree *at, CollapseMode mode, int color_group);
    void group_rest_tree(AP_tree *at, CollapseMode mode, int color_group);
    void reorderTree(TreeOrder mode);
    void toggle_group(AP_tree * at);

    GB_ERROR load_from_DB(GBDATA *gb_main, const char *name) FINAL_OVERRIDE __ATTR__USERESULT;
    GB_ERROR save_to_DB(GBDATA *gb_main, const char *name) FINAL_OVERRIDE __ATTR__USERESULT;
    void     check_for_DB_update(GBDATA *gb_main) FINAL_OVERRIDE;
    void     notify_synchronized(GBDATA *gb_main) FINAL_OVERRIDE;

    void fast_sync_changed_folding(AP_tree *parent_of_all_changes); // use carefully

    void set_tree_style(AP_tree_display_style style, AWT_canvas *ntw);
    AP_tree_display_style get_tree_style() const { return tree_style; }

    double get_irs_tree_ruler_scale_factor() const { return irs_tree_ruler_scale_factor; }
    void show_ruler(AW_device *device, int gc);
    void get_zombies_and_duplicates(int& zomb, int& dups) const { zomb = zombies; dups = duplicates; }

    void hide_marker_display() {
        delete display_markers;
        display_markers = NULp;
    }
    void set_marker_display(MarkerDisplay *display) { // takes ownership of 'display'
        hide_marker_display();
        display_markers = display;
    }
    MarkerDisplay *get_marker_display() { return display_markers; }

    void install_tree_changed_callback(const GraphicTreeCallback& gtcb);
    void uninstall_tree_changed_callback();

    static void install_group_changed_callback(const GraphicTreeCallback& gccb) {
        group_changed_cb = gccb;
    }

    void auto_unfold(AP_tree *want_visible);
    void forget_auto_unfolded();

private:
    void select_group(const Group& group) {
        if (selected_group != group) {
            selected_group = group;
            group_changed_cb(this);
        }
    }
public:
    void select_group(AP_tree *node) { // select + locate
        td_assert(node && node->is_clade());
        select_group(Group(node));
    }
    void select_group(GBDATA *gb_group) { // unlocated select (or deselect if called with NULp)
        select_group(gb_group ? Group(gb_group) : Group());
    }
    void deselect_group() {
        select_group(Group());
    }
    const Group& get_selected_group() const {
        return selected_group;
    }
    AP_tree *locate_selected_group(AP_tree *in_subtree) {
        AP_tree *node = NULp;
        if (selected_group.is_valid()) {
            if (selected_group.locate(in_subtree)) {
                node = selected_group.get_node();
            }
        }
        return node;
    }
    void dislocate_selected_group() {
        // has to be called whenever the keeled-state of a group may change
        selected_group.dislocate();
    }

#if defined(UNIT_TESTS) // UT_DIFF
    friend class fake_AWT_graphic_tree;
#endif
    PREPARE_MARK_NONFINAL_CLASS(AWT_graphic_tree);
};
MARK_NONFINAL_CLASS(AWT_graphic_tree);
MARK_NONFINAL_FUNCTION(AWT_graphic_tree,AP_tree_root*,create_tree_root,(AliView*,AP_sequence*,bool),NULp);

class ClickedTarget {
    AP_tree *tree_node;
    GBDATA  *gb_species;

    bool ruler;
    bool branch;
    int  markerflag; // = markerindex + 1

    const AW_clicked_element *elem;

    void init() {
        tree_node  = NULp;
        gb_species = NULp;
        ruler      = false;
        branch     = false;
        markerflag  = 0;
    }

    void identify(AWT_graphic_tree *agt) {
        init();
        if (elem && elem->does_exist()) {
            ClickedType what = (ClickedType)elem->cd2();

            switch (what) {
                case CL_SPECIES:
                    gb_species = (GBDATA*)elem->cd1();
                    td_assert(gb_species);
                    break;

                case CL_RULER:
                    ruler = !elem->cd1();
                    break;

                case CL_FLAG:
                    markerflag = elem->cd1()+1;
                    break;

                case CL_BRANCH:
                    branch = true;
                    // fall-through!
                case CL_NODE:
                    tree_node = (AP_tree*)elem->cd1();
                    break;

                case CL_ROOTNODE:
                    if (agt) tree_node = agt->get_root_node();
                    break;

#if defined(DEBUG)
                default:
                    td_assert(0); // unknown element type
#endif
            }
        }
        else { // use whole tree if mouse does not point to a subtree
            tree_node = agt ? agt->get_root_node() : NULp;
        }
        td_assert(implicated(branch, tree_node));
    }

public:

    ClickedTarget(AWT_graphic_tree *agt, const AW_clicked_element *clicked) : elem(clicked) {
        // uses root of tree as target, when a position outside of the tree is selected
        // (e.g. used for key-commands)
        identify(agt);
    }
    ClickedTarget(const AW_clicked_element *clicked) : elem(clicked) {
        // accept only normal branches as targets
        identify(NULp);
    }

    const AW_clicked_element *element() const { return elem; }
    AP_tree *node() const { return tree_node; }
    GBDATA *species() const { return gb_species; }
    int get_markerindex() const { return markerflag-1; }

    bool is_text() const { return elem && elem->is_text(); }
    bool is_line() const { return elem && elem->is_line(); }
    bool is_branch() const { return branch; }
    bool is_ruler() const { return ruler; }
    bool is_marker() const { return markerflag; }

    double get_rel_attach() const {
        // return [0..1] according to exact position where element is dropped
        if (is_line() && (is_branch() || ruler)) return elem->get_rel_pos();
        return 0.5; // act like "drop on branch-center"
    }
};

class TREE_canvas : public AWT_canvas { // derived from Noncopyable
    AW_awar *awar_tree; // awar containing name of displayed tree
    int      index;     // unique index [0..MAX_NT_WINDOWS-1]

    static int count;

public:
    TREE_canvas(GBDATA *gb_main_, AW_window *aww_, const char *gc_base_name_, AWT_graphic *gfx_, AW_awar *awar_tree_) :
        AWT_canvas(gb_main_, aww_, gc_base_name_, gfx_),
        awar_tree(awar_tree_),
        index(count++)
    {}

    void at_screen_update_call(screen_update_callback cb, AW_CL cd) {
        td_assert(!announce_update_cb || (announce_update_cb == cb && user_data == cd));

        announce_update_cb = cb;
        user_data          = cd;
    }

    AWT_graphic_tree *get_graphic_tree() const { return DOWNCAST(AWT_graphic_tree*, gfx); }
    AW_awar *get_awar_tree() const { return awar_tree; }
    int get_index() const { return index; }
};


void       TREE_create_awars(AW_root *aw_root, AW_default db);
void       TREE_install_update_callbacks(TREE_canvas *ntw);
AW_window *TREE_create_settings_window(AW_root *aw_root);
AW_window *TREE_create_marker_settings_window(AW_root *root);

AWT_graphic_tree *NT_generate_tree(AW_root *root, GBDATA *gb_main, AD_map_viewer_cb map_viewer_cb);

#else
#error TreeDisplay.hxx included twice
#endif // TREEDISPLAY_HXX