offapi/com/sun/star/inspection/ObjectInspector.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27 #ifndef __com_sun_star_inspection_ObjectInspector_idl__
  28 #define __com_sun_star_inspection_ObjectInspector_idl__
  29
  30 #ifndef __com_sun_star_inspection_XObjectInspector_idl__
  31 #include <com/sun/star/inspection/XObjectInspector.idl>
  32 #endif
  33
  34 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  35 #include <com/sun/star/lang/IllegalArgumentException.idl>
  36 #endif
  37
  38 //=============================================================================
  39 module com {  module sun {  module star {  module inspection {
  40
  41 //-----------------------------------------------------------------------------
  42 /** describes an <type scope="com::sun::star::frame">Controller</type> which can be used to
  43     browse and modify properties of components.
  44
  45     <p>The controller can be plugged into an <type scope="com::sun::star::frame">XFrame</type>, and will
  46     provide a visual component for inspecting and modifying component properties.<br/>
  47     Note that "property" here is a generic term - any aspect of a component can be considered a property,
  48     as long as some property handler is able to describe this aspect in a property-like way.</p>
  49
  50     <p>The basic idea is that one facet of the inspected component is represented by a single line
  51     of controls: A label, an input control, and optionally one or two buttons which, when pressed,
  52     trigger additional user interaction (e.g. a more sophisticated dialog to enter a property value).</p>
  53
  54     <p>Additionally, property lines can be grouped into different categories. A usual implementation
  55     of such categories would be tab pages, but other implementations are possible, too.</p>
  56
  57     <p>Even more, the inspector can optionally display a help section at the bottom of its
  58     window, which can display arbitrary (context-sensitive) help texts.</p>
  59
  60     <p>An <type>ObjectInspector</type> needs one or more property handlers which describe
  61     the facets of an inspected component - without such handlers, the inspector window will simply
  62     stay empty.</p>
  63
  64     <p>The property handlers, as well as more information about the layout of the inspector,
  65     are provided by a inspector model, which has to be implemented by the user of the inspector.</p>
  66     <p/>
  67
  68     <p>Since property handlers might have the need to raise UI, they will be created with a context
  69     value named "DialogParentWindow", which contains an XWindow which should be used as parent of
  70     any windows to raise.<br/>
  71     If the <type scope="com::sun::star::uno">XComponentContext</type> in which the <type>ObjectInspector</type>
  72     was created already contains such a value, it is not overwritten. Only if it doesn't, the inspector
  73     will add an own value - which contains the inspector's main window - to the context when creating
  74     handlers.</p>
  75
  76     @see XPropertyHandler
  77     @see LineDescriptor
  78     @see PropertyControlType
  79     @see ObjectInspectorModel
  80     @see com::sun::star::uno::XComponentContext
  81     @see com::sun::star::lang::XMultiComponentFactory
  82
  83     @since OOo 2.0.3
  84 */
  85 service ObjectInspector : XObjectInspector
  86 {
  87     /** creates a default instance of the ObjectInspector
  88
  89         @since OOo 2.2
  90     */
  91     createDefault();
  92
  93     /** creates an instance of the ObjectInspector, using a given <type>ObjectInspectorModel</type>
  94
  95         @throws ::com::sun::star::lang::IllegalArgumentException
  96             if <arg>Model</arg> is <NULL/>.
  97
  98         @since OOo 2.2
  99     */
 100     createWithModel( [in] XObjectInspectorModel Model )
 101         raises ( ::com::sun::star::lang::IllegalArgumentException );
 102 };
 103
 104 //=============================================================================
 105
 106 }; }; }; };
 107
 108 #endif
 109
 110
 111