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

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