path: root/offapi/com/sun/star/awt/tree/XTreeControl.idl

/* -*- 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_XTreeControl_idl__
#define __com_sun_star_awt_tree_XTreeControl_idl__

#include <com/sun/star/awt/XControl.idl>
#include <com/sun/star/awt/tree/XTreeExpansionListener.idl>
#include <com/sun/star/view/XMultiSelectionSupplier.idl>
#include <com/sun/star/awt/tree/XTreeEditListener.idl>


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


/** An interface to a control that displays a set of hierarchical data as an outline.

    @see TreeControl
 */
interface XTreeControl
{
    /** This interfaces provides access to the selection of tree nodes for this control.

        <p>valid selection values for this interface are
        XTreeNode or sequence&lt;XTreeNode&gt;.</p>

        ::com::sun::star::view::XSelectionSupplier::getSelection()
        returns an empty any for no selection, an any with XTreeNode for
        a single selection and a sequence&lt;XTreeNode&gt; for a multiselection.
    */
    interface ::com::sun::star::view::XMultiSelectionSupplier;

    // expanding/collapsing/visible

    /** Returns `TRUE` if <var>Node</var> is currently expanded.

        @param Node
            the XTreeNode specifying the node to check.

        @returns
            `FALSE` if <var>Node</var> or at least one of its parent nodes are collapsed,
            `TRUE` if <var>Node</var> and all of its parent nodes are expanded.

        @throws ::com::sun::star::lang::IllegalArgumentException
            if <var>Node</var> is not a valid node of the corresponding XTreeDataModel.
    */
    boolean isNodeExpanded( [in] XTreeNode Node )
        raises( ::com::sun::star::lang::IllegalArgumentException );

    /** Returns `TRUE` if <var>Node</var> is currently collapsed.

        @param Node
            the XTreeNode specifying the node to check

        @returns
            `TRUE` if <var>Node</var> or at least one of its parent nodes are collapsed,
            `FALSE` if <var>Node</var> and all of its parent nodes are expanded

        @throws ::com::sun::star::lang::IllegalArgumentException
            if <var>Node</var> is not a valid node of the corresponding XTreeDataModel.
    */
    boolean isNodeCollapsed( [in] XTreeNode Node )
        raises( ::com::sun::star::lang::IllegalArgumentException );

    /** Ensures that <var>Node</var> is currently visible.
        <p>This includes expanding all parent nodes and scroll the control so this
        node is visible in the controls display area.</p>

        @param Node
            the XTreeNode specifying the node to make visible.

        @throws ::com::sun::star::lang::IllegalArgumentException
            if <var>Node</var> is not a valid node of the corresponding XTreeDataModel.

        @throws ExpandVetoException
            if <var>Node</var>can't be made visible since at least one of the parent nodes are
            collapsed and expanding failed because at least one of the registered
            XTreeExpansionListener raised an ExpandVetoException.
    */
    void makeNodeVisible( [in] XTreeNode Node )
        raises( com::sun::star::lang::IllegalArgumentException, ExpandVetoException );

    /** Returns `TRUE` if <var>Node</var> is currently visible.
        <p>Visible means it is either the root or all of its parents are expanded.</p>

        @returns
            `TRUE` if <var>Node</var> is visible, otherwise `FALSE`

        @throws ::com::sun::star::lang::IllegalArgumentException
            if <var>Node</var> is not a valid node of the corresponding XTreeDataModel.
    */
    boolean isNodeVisible( [in] XTreeNode Node )
        raises( com::sun::star::lang::IllegalArgumentException );

    /** Ensures that <var>Node</var> is expanded and visible.
        <p>If <var>Node</var> is a leaf node, this will have no effect.</p>

        @param Node
            the XTreeNode identifying a node.

        @throws ::com::sun::star::lang::IllegalArgumentException
            if <var>Node</var> is not a valid node of the corresponding XTreeDataModel.

        @throws ExpandVetoException
            if expanding <var>Node</var> failed because at least one of the registered
            XTreeExpansionListener raised an ExpandVetoException.
    */
    void expandNode( [in] XTreeNode Node )
        raises( com::sun::star::lang::IllegalArgumentException, ExpandVetoException );

    /** Ensures that <var>Node</var> is collapsed.

        @param Node
            the XTreeNode identifying a node

        @throws ::com::sun::star::lang::IllegalArgumentException
            if <var>Node</var> is not a valid node of the corresponding XTreeDataModel.

        @throws ExpandVetoException
            if collapsing <var>Node</var> failed because at least one of the registered
            XTreeExpansionListener raised an ExpandVetoException.
    */
    void collapseNode( [in] XTreeNode Node )
        raises( com::sun::star::lang::IllegalArgumentException, ExpandVetoException );

    /** Adds a listener for TreeExpansion events.

        @param Listener
            a XTreeExpansionListener that will be notified when a tree
            node is expanded or collapsed.
    */
    void addTreeExpansionListener( [in] XTreeExpansionListener Listener );

    /** Removes a listener for TreeExpansion events.

        @param Listener
            the XTreeExpansionListener to remove.
    */
    void removeTreeExpansionListener( [in] XTreeExpansionListener Listener );

    /** If the given URL points to a loadable graphic, the graphic is rendered
        before expanded non leaf nodes.

        <p>This can be overridden for individual nodes by XTreeNode::getExpandedGraphicURL()</p>
    */
    [attribute] string DefaultExpandedGraphicURL;

    /** If the given URL points to a loadable graphic, the graphic is rendered
        before collapsed non leaf nodes.

        <p>This can be overridden for individual nodes by XTreeNode::getCollapsedGraphicURL()</p>
    */
    [attribute] string DefaultCollapsedGraphicURL;

    // tree geometry

    /** Returns the node at the specified location.

        @param x
            an integer giving the number of pixels horizontally from the left edge of the controls display area
        @param y
            an integer giving the number of pixels vertically from the top edge of the controls display area
        @returns
            the XTreeNode for the node at that location, or 0 if there is no node at the given position
    */
    XTreeNode getNodeForLocation( [in] long x, [in] long y );

    /** Returns the node that is closest to x,y.
        <p>If no nodes are currently viewable, or there is no model, returns null,
        otherwise it always returns a valid node. To test if the node is exactly
        at x, y, use getNodeForLocation().

        @param x
            an integer giving the number of pixels horizontally from the left edge of the controls display area
        @param y
            an integer giving the number of pixels vertically from the top edge of the controls display area
        @returns
            the XTreeNode for the node closest to that location, null if nothing is viewable or there is no model
    */
    XTreeNode getClosestNodeForLocation( [in] long x, [in] long y );

    /** returns the rectangle occupied by the visual representation of the given node

        @param Node
            the node whose geometry should be obtained
        @throws ::com::sun::star::lang::IllegalArgumentException
            if the given node is `NULL`, or does not belong to the tree's data model
    */
    ::com::sun::star::awt::Rectangle
        getNodeRect( [in] XTreeNode Node )
            raises( ::com::sun::star::lang::IllegalArgumentException );

    // tree editing

    /** Returns `TRUE` if one of tree's nodes is being currently edited.
        <p>The node that is being edited can be obtained using com::sun::star::view::XSelectionSupplier::getSelection().

        @returns
            `TRUE` if the user is currently editing a node
    */
    boolean isEditing();

    /** Ends the current editing session.
        <p>All registered XTreeEditListener are notified if an editing session was in progress</p>
        <p>Has no effect if the tree isn't being edited.</p>

        @returns
            `TRUE` if editing was in progress and is now stopped, `FALSE` if editing was not in progress
    */
    boolean stopEditing();

    /** Cancels the current editing session.
        <p>Has no effect if the tree isn't being edited.</p>
    */
    void cancelEditing();

    /** Selects <var>Node</var> and initiates editing.

        <p>If TreeControlModel::Editable is `FALSE` or if there are no
        registered XTreeEditListener, this call has no effect.</p>

        <p>Calling this method also ensures that <var>Node</var> will become visible.</p>

        @param Node
            the XTreeNode identifying a node.

        @throws ::com::sun::star::lang::IllegalArgumentException
            if <var>Node</var> is not a valid node of the corresponding XTreeDataModel.
    */
    void startEditingAtNode( [in] XTreeNode Node )
        raises( ::com::sun::star::lang::IllegalArgumentException );

    /** Adds a XTreeEditListener.

        @param Listener
            a XTreeEditListener that will be notified
            before and after a tree node is edited.
    */
    void addTreeEditListener( [in] XTreeEditListener Listener );

    /** Removes a XTreeEditListener.

        @param Listener
            the XTreeEditListener to remove
    */
    void removeTreeEditListener( [in] XTreeEditListener Listener );
};


}; }; }; }; };

#endif

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