framework/inc/classes/framelistanalyzer.hxx

   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: framelistanalyzer.hxx,v $
  10  * $Revision: 1.4 $
  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
  31 #ifndef __FRAMEWORK_CLASSES_FRAMELISTANALYZER_HXX_
  32 #define __FRAMEWORK_CLASSES_FRAMELISTANALYZER_HXX_
  33
  34 //_______________________________________________
  35 //      my own includes
  36
  37 #include <threadhelp/threadhelpbase.hxx>
  38 #include <macros/debug.hxx>
  39 #include <general.h>
  40
  41 //_______________________________________________
  42 //      interface includes
  43 #include <com/sun/star/frame/XFrame.hpp>
  44
  45 //_______________________________________________
  46 //      other includes
  47
  48 //_______________________________________________
  49 //      namespace
  50
  51 namespace framework{
  52
  53 //_______________________________________________
  54 //      exported const
  55
  56 //_______________________________________________
  57 //      exported definitions
  58
  59 /** analyze and split the current available frame list of a given frames supplier
  60     into different parts.
  61
  62     These analyzed informations can be used e.g. to decide if it's neccessary
  63     to switch into the backing mode, close the current active frame only or
  64     exit the whole application explicitly or implicitly.
  65  */
  66 class FrameListAnalyzer
  67 {
  68     //_______________________________________
  69     // types
  70
  71     public:
  72
  73         /** These enums can be combined as flags to enable/disable
  74             special search algorithm during analyze phase.
  75             see impl_analyze() for further informations.
  76             But note: To be useable as flags, these enums
  77             must be values of range [2^n]! */
  78         enum EDetect
  79         {
  80             E_MODEL             =     1,
  81             E_HELP              =     2,
  82             E_BACKINGCOMPONENT  =     4,
  83             E_HIDDEN            =     8,
  84             E_ALL               =    15,
  85             E_ZOMBIE            = 32768 // use it for special test scenarios only!!!
  86         };
  87
  88     //_______________________________________
  89     // member
  90
  91     public:
  92
  93         /** provides access to the frame container, which should be analyzed. */
  94         const css::uno::Reference< css::frame::XFramesSupplier >& m_xSupplier;
  95
  96         /** hold the reference frame, which is used e.g. to detect other frames with the same model. */
  97         const css::uno::Reference< css::frame::XFrame >& m_xReferenceFrame;
  98
  99         /** enable/disable some special analyzing steps.
 100             see impl_analyze() for further informations. */
 101         sal_uInt32 m_eDetectMode;
 102
 103         /** contains all frames, which uses the same model like the reference frame.
 104             Will be filled only if m_eDetectMode has set the flag E_MODEL.
 105             The reference frame is never part of this list! */
 106         css::uno::Sequence< css::uno::Reference< css::frame::XFrame > > m_lModelFrames;
 107
 108         /** contains all frames, which does not contain the same model like the reference frame.
 109             Filling of it can't be supressed by m_eDetectMode.
 110             The reference frame is never part of this list!
 111             All frames inside this list are visible ones. */
 112         css::uno::Sequence< css::uno::Reference< css::frame::XFrame > > m_lOtherVisibleFrames;
 113
 114         /** contains all frames, which does not contain the same model like the reference frame.
 115             Filling of it can't be supressed by m_eDetectMode.
 116             The reference frame is never part of this list!
 117             All frames inside this list are hidden ones. */
 118         css::uno::Sequence< css::uno::Reference< css::frame::XFrame > > m_lOtherHiddenFrames;
 119
 120         /** points to the help frame.
 121             Will be set only, if any other frame (means different from the reference frame)
 122             contains the help component. If the reference frame itself includes the help module
 123             it's not set ... but another member m_bIsHelp is used to safe this information.
 124             See following example code:
 125
 126             <listing>
 127             if (m_xReferenceFrame == help)
 128             {
 129                 m_xHelp   = NULL;
 130                 m_bIsHelp = TRUE;
 131             }
 132             else
 133             if (xOtherFrame == help)
 134             {
 135                 m_xHelp   = xOtherFrame;
 136                 m_bIsHelp = FALSE;
 137             }
 138             </listing>
 139
 140             Analyzing of the help frame ignores the visible state of any frame.
 141             But note: a hidden help frame indicates a wrong state!
 142          */
 143         css::uno::Reference< css::frame::XFrame > m_xHelp;
 144
 145         /** points to the frame, which contains the backing component.
 146             Will be set only, if any other frame (means different from the reference frame)
 147             contains the backing component. If the reference frame itself includes the
 148             backing component it's not set ... but another member m_bIsBackingComponent
 149             will used to safe this information.
 150             See following example code:
 151
 152             <listing>
 153             if (m_xReferenceFrame == backing)
 154             {
 155                 m_xBackingComponent   = NULL;
 156                 m_bIsBackingComponent = TRUE;
 157             }
 158             else
 159             if (xOtherFrame == backing)
 160             {
 161                 m_xBackingComponent   = xOtherFrame;
 162                 m_bIsBackingComponent = FALSE      ;
 163             }
 164             </listing>
 165
 166             Analyzing of the help frame ignores the visible state of any frame.
 167             But note: a hidden backing mode frame indicates a wrong state!
 168          */
 169         css::uno::Reference< css::frame::XFrame > m_xBackingComponent;
 170
 171         /** is set to true only, if the reference frame is a hidden one.
 172             This value is undefined if m_eDetectMode doesn't have set the flag E_HIDDEN! */
 173         sal_Bool m_bReferenceIsHidden;
 174
 175         /** is set to true only, if the reference frame contains the help component.
 176             In this case the member m_xHelp is set to NULL everytimes.
 177             This value is undefined if m_eDetectMode doesn't have set the flag E_HELP! */
 178         sal_Bool m_bReferenceIsHelp;
 179
 180         /** is set to true only, if the reference frame contains the backing component.
 181             In this case the member m_xBackingComponent is set to NULL everytimes.
 182             This value is undefined if m_eDetectMode doesn't have set the flag E_BACKINGCOMPONENT! */
 183         sal_Bool m_bReferenceIsBacking;
 184
 185     //_______________________________________
 186     // interface
 187
 188     public:
 189
 190         /** starts analyze phase and fille all members with valid informations.
 191
 192             @param xSupplier
 193                     Must be a valid reference to a frames supplier, which provies
 194                     access to the frame list for analyzing.
 195
 196             @param xReferenceFrame
 197                     This frame must(!) exist inside the analyzed frame list and
 198                     is used for some comparing functions. Further some member states
 199                     depends from the current state of this frame.
 200
 201             @param eDetectMode
 202                     It represent a flag field, which can enable/disable special
 203                     analyze steps. Note: Some member values will be undefined, if
 204                     an analyze step will be disabled.
 205          */
 206                  FrameListAnalyzer( const css::uno::Reference< css::frame::XFramesSupplier >& xSupplier       ,
 207                                     const css::uno::Reference< css::frame::XFrame >&          xReferenceFrame ,
 208                                           sal_uInt32                                          eDetectMode     );
 209         virtual ~FrameListAnalyzer();
 210
 211     //_______________________________________
 212     // helper
 213
 214     private:
 215
 216             void impl_analyze();
 217
 218
 219 }; // class FrameListAnalyzer
 220
 221 } // namespace framework
 222
 223 #endif // #ifndef __FRAMEWORK_CLASSES_FRAMELISTANALYZER_HXX_