/* -*- 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_inspection_XObjectInspectorModel_idl__
#define __com_sun_star_inspection_XObjectInspectorModel_idl__

#include <com/sun/star/uno/XInterface.idl>
#include <com/sun/star/inspection/PropertyCategoryDescriptor.idl>

module com {  module sun {  module star {  module inspection {

interface XPropertyHandler;

/** describes the model of an ObjectInspector

    @see ObjectInspector

    @since OOo 2.0.3
*/
interface XObjectInspectorModel
{
    /** describes a set of factories for creating XPropertyHandlers

        <p>Every element of the sequence must contain information to create a
        XPropertyHandler instance. Two ways are currently supported:
        <ul>
            <li>A service name:</br>
                If a sequence element contains a string, this string is interpreted
                as service name, and an com::sun::star::lang::XMultiComponentFactory
                is asked to create an instance of this service.</li>
            <li>A factory:<br/>
                If a sequence element contains an instance implementing the
                com::sun::star::lang::XSingleComponentFactory interface, this factory
                is used to create a property handler.</li>
        </ul></p>

        <p>This attribute is usually only evaluated by the ObjectInspector instance
        which the model is currently bound to.</p>

        <p>The order of factories is important: If two property handlers declare themselves responsible
        for the same property, the one whose factory is listed <strong>last</strong> wins. Also,
        if a handler <code>B</code> wants to supersede a property of another handler <code>A</code>,
        <code>A</code>'s factory must precede the factory of <code>B</code>.</p>

        @see XPropertyHandler::getSupportedProperties
        @see XPropertyHandler::getSupersededProperties
    */
    [attribute, readonly] sequence< any > HandlerFactories;

    /** describes the property categories used by the property handlers.

        <p>Properties can be sorted into different categories, described by the <member>LineDescriptor::Category</member>
        attribute, which is filled in XPropertyHandler::describePropertyLine()
        method of your property handler.<br/>
        Those names provided by the handlers are programmatic names. All other information
        about categories is part of the PropertyCategoryDescriptor, and
        describeCategories() assembles information about all categories which
        all property handlers provided by the model use.</p>

        @return
            a sequence of category descriptors. Their relative ordering also describes
            the relative ordering of the categories in the ObjectInspector's
            user interface.<br/>
            The sequence must not contain two entries with the same programmatic name.<br/>
            <br/>
            The model implementation might return an empty sequence here, in this case, the ObjectInspector
            automatically builds its category information from the categories provided by the
            property handlers.
        @see PropertyCategoryDescriptor
        @see LineDescriptor::Category
    */
    sequence< PropertyCategoryDescriptor > describeCategories();

    /** retrieves an index in a global property ordering, for a given property name

        <p>In the user interface of an ObjectInspector, single properties are represented by
        single lines, and those lines are displayed successively. To determine an order of
        the property lines, the inspector model can associate an "order index" with each property.
        The ObjectInspector will then sort the property lines in a way that they
        have the same relative ordering as the "order indexes" of their properties.</p>

        <p>Note that the concrete value the model returns for a given property does not
        matter. All what matters is that if you want a certain property <code>Foo</code>
        to be displayed after another property <code>Bar</code>, then the order index
        of <code>Foo</code> should be greater than the order index of <code>Bar</code>.

        <p>If for two different properties the same order index is returned, the
        ObjectInspector will assume the order in which those properties
        were provided by the respective property handler
        (XPropertyHandler::getSupportedProperties()).<br/>
        If two such properties originate from different handlers, they will be ordered according
        to the order of the handlers, as provided in the <member>HandlerFactories</member> attribute.</p>

        @param PropertyName
            the property whose global order index should be retrieved
        @return
            the global order index of <arg>PropertyName</arg>.
    */
    long    getPropertyOrderIndex( [in] string PropertyName );

    /** indicates that the object inspector should have a help section.

        <p>The object inspector displays lines of property/values, optionally grouped
        into categories, as described by the property handlers.<br/>
        Additionally, the inspector can optionally display a section dedicated to help
        texts. Clients could use this section to display context-sensitive help, for
        instance short texts explaining the currently selected property.</p>

        @since OOo 2.2
    */
    [attribute, readonly] boolean HasHelpSection;

    /** denotes the minimum number of lines of text to be reserved for the help
        section.

        <p>This property is ignored by the ObjectInspector if
        <member>HasHelpSection</member> is <FALSE/>.</p>

        <p>The layout of the ObjectInspector is undefined if
        <member>MinHelpTextLines</member> is larger than
        <member>MaxHelpTextLines</member>.</p>

        @since OOo 2.2
    */
    [attribute, readonly] long MinHelpTextLines;

    /** denotes the maximum number of lines of text to be reserved for the help
        section.

        <p>This property is ignored by the ObjectInspector if
        <member>HasHelpSection</member> is <FALSE/>.</p>

        <p>The layout of the ObjectInspector is undefined if
        <member>MaxHelpTextLines</member> is smaller than
        <member>MinHelpTextLines</member>.</p>

        @since OOo 2.2
    */
    [attribute, readonly] long MaxHelpTextLines;

    /** determines whether the object inspector's UI should be read-only.

        <p>In this case, the user is able to browse through all properties, but cannot
        change any of them.</p>

        <p>In a read-only object inspector, the property controls are readonly or
        disabled themselves, and the primary and secondary buttons of a property line
        are both disabled.</p>

        @see XPropertyControl
        @see LineDescriptor
    */
    [attribute, bound] boolean IsReadOnly;
};


}; }; }; };

#endif


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