/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */
#ifndef __com_sun_star_awt_tree_TreeControl_idl__
#define __com_sun_star_awt_tree_TreeControl_idl__

#include <com/sun/star/awt/tree/XTreeControl.idl>


module com {  module sun {  module star {  module awt { module tree {


/** A control that displays a set of hierarchical data as an outline.

    <p>
    <h4>The Data Model</h4>
    <p>A specific node in a tree is identified by a XTreeNode.
    A leaf node is a node without any children and that returns `FALSE` when calling XTreeNode::hasChildrenOnDemand().
    An expanded node is a non-leaf node that will displays its children when all its ancestors are expanded.
    A collapsed node is one which hides them.
    A node is visible when all parent nodes are expanded and the node itself is in the display area.
    </p>

    <p>The nodes are retrieved from a XTreeDataModel.
    You can implement it yourself or use the MutableTreeDataModel
    which uses XMutableTreeNode and XMutableTreeDataModel
    for a simple and mutable data model.

    <p>The data model must be set at the TreeControlModel::TreeDataModel property.</p>

    <h4>Selection</h4>
    <p>If you are interested in knowing when the selection changes implement a
    com::sun::star::view::XSelectionChangeListener and add the instance with the method
    ::com::sun::star::view::XSelectionSupplier::addSelectionChangeListener().
    You than will be notified for any selection change.
    </p>

    <p>
    If you are interested in detecting either double-click events or when a user clicks on a node,
    regardless of whether or not it was selected, you can get the com::sun::star::awt::XWindow
    and add yourself as a com::sun::star::awt::XMouseClickHandler. You can use the
    method XTreeControl::getNodeForLocation() to retrieve the node that was under the
    mouse at the time the event was fired.
    </p>

    <h4>Adding child nodes on demand</h4>
    <p>If you want to add child nodes to your tree on demand you can do the following.
    <ul>
    <li>Make sure the parent node returns `TRUE` for XTreeNode::hasChildrenOnDemand() either
    by implementing XTreeNode yourself or if you use the MutableTreeDataModel,
    use XMutableTreeNode::setHasChildrenOnDemand().</li>
    <li>Implement a XTreeExpansionListener and add the instance with the method
    XTreeControl::addTreeExpansionListener().</li>
    </ul>
    Now you get called when the node will become expanded or collapsed.
    So on XTreeExpansionListener::treeExpanding() you can
    check the TreeExpansionEvent if the parent node with children on demand is going to
    be expanded and in that case add the missing child nodes. You can also veto the expansion or
    collapsing of a parent node by using the ExpandVetoException.
    </p>
 */
service TreeControl: XTreeControl
{
};


}; }; }; }; };

#endif

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */