include/framework/framelistanalyzer.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_FRAMEWORK_FRAMELISTANALYZER_HXX
  21 #define INCLUDED_FRAMEWORK_FRAMELISTANALYZER_HXX
  22
  23 #include <com/sun/star/frame/XFrame.hpp>
  24
  25 #include <framework/fwedllapi.h>
  26
  27 namespace framework{
  28
  29 /** analyze and split the current available frame list of a given frames supplier
  30     into different parts.
  31
  32     These analyzed information can be used e.g. to decide if it's neccessary
  33     to switch into the backing mode, close the current active frame only or
  34     exit the whole application explicitly or implicitly.
  35  */
  36 class FWE_DLLPUBLIC FrameListAnalyzer
  37 {
  38     //_______________________________________
  39     // types
  40
  41     public:
  42
  43         /** These enums can be combined as flags to enable/disable
  44             special search algorithm during analyze phase.
  45             see impl_analyze() for further information.
  46             But note: To be useable as flags, these enums
  47             must be values of range [2^n]! */
  48         enum EDetect
  49         {
  50             E_MODEL             =     1,
  51             E_HELP              =     2,
  52             E_BACKINGCOMPONENT  =     4,
  53             E_HIDDEN            =     8,
  54             E_ALL               =    15,
  55             E_ZOMBIE            = 32768 // use it for special test scenarios only!!!
  56         };
  57
  58     //_______________________________________
  59     // member
  60
  61     public:
  62
  63         /** provides access to the frame container, which should be analyzed. */
  64         const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFramesSupplier >& m_xSupplier;
  65
  66         /** hold the reference frame, which is used e.g. to detect other frames with the same model. */
  67         const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame >& m_xReferenceFrame;
  68
  69         /** enable/disable some special analyzing steps.
  70             see impl_analyze() for further information. */
  71         sal_uInt32 m_eDetectMode;
  72
  73         /** contains all frames, which uses the same model like the reference frame.
  74             Will be filled only if m_eDetectMode has set the flag E_MODEL.
  75             The reference frame is never part of this list! */
  76         ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame > > m_lModelFrames;
  77
  78         /** contains all frames, which does not contain the same model like the reference frame.
  79             Filling of it can't be supressed by m_eDetectMode.
  80             The reference frame is never part of this list!
  81             All frames inside this list are visible ones. */
  82         ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame > > m_lOtherVisibleFrames;
  83
  84         /** contains all frames, which does not contain the same model like the reference frame.
  85             Filling of it can't be supressed by m_eDetectMode.
  86             The reference frame is never part of this list!
  87             All frames inside this list are hidden ones. */
  88         ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame > > m_lOtherHiddenFrames;
  89
  90         /** points to the help frame.
  91             Will be set only, if any other frame (means different from the reference frame)
  92             contains the help component. If the reference frame itself includes the help module
  93             it's not set ... but another member m_bIsHelp is used to safe this information.
  94             See following example code:
  95
  96             <listing>
  97             if (m_xReferenceFrame == help)
  98             {
  99                 m_xHelp   = NULL;
 100                 m_bIsHelp = sal_True;
 101             }
 102             else
 103             if (xOtherFrame == help)
 104             {
 105                 m_xHelp   = xOtherFrame;
 106                 m_bIsHelp = sal_False;
 107             }
 108             </listing>
 109
 110             Analyzing of the help frame ignores the visible state of any frame.
 111             But note: a hidden help frame indicates a wrong state!
 112          */
 113         ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame > m_xHelp;
 114
 115         /** points to the frame, which contains the backing component.
 116             Will be set only, if any other frame (means different from the reference frame)
 117             contains the backing component. If the reference frame itself includes the
 118             backing component it's not set ... but another member m_bIsBackingComponent
 119             will used to safe this information.
 120             See following example code:
 121
 122             <listing>
 123             if (m_xReferenceFrame == backing)
 124             {
 125                 m_xBackingComponent   = NULL;
 126                 m_bIsBackingComponent = sal_True;
 127             }
 128             else
 129             if (xOtherFrame == backing)
 130             {
 131                 m_xBackingComponent   = xOtherFrame;
 132                 m_bIsBackingComponent = sal_False      ;
 133             }
 134             </listing>
 135
 136             Analyzing of the help frame ignores the visible state of any frame.
 137             But note: a hidden backing mode frame indicates a wrong state!
 138          */
 139         ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame > m_xBackingComponent;
 140
 141         /** is set to true only, if the reference frame is a hidden one.
 142             This value is undefined if m_eDetectMode doesn't have set the flag E_HIDDEN! */
 143         sal_Bool m_bReferenceIsHidden;
 144
 145         /** is set to true only, if the reference frame contains the help component.
 146             In this case the member m_xHelp is set to NULL every time.
 147             This value is undefined if m_eDetectMode doesn't have set the flag E_HELP! */
 148         sal_Bool m_bReferenceIsHelp;
 149
 150         /** is set to true only, if the reference frame contains the backing component.
 151             In this case the member m_xBackingComponent is set to NULL every time.
 152             This value is undefined if m_eDetectMode doesn't have set the flag E_BACKINGCOMPONENT! */
 153         sal_Bool m_bReferenceIsBacking;
 154
 155     //_______________________________________
 156     // interface
 157
 158     public:
 159
 160         /** starts analyze phase and fille all members with valid information.
 161
 162             @param xSupplier
 163                     Must be a valid reference to a frames supplier, which provies
 164                     access to the frame list for analyzing.
 165
 166             @param xReferenceFrame
 167                     This frame must(!) exist inside the analyzed frame list and
 168                     is used for some comparing functions. Further some member states
 169                     depends from the current state of this frame.
 170
 171             @param eDetectMode
 172                     It represent a flag field, which can enable/disable special
 173                     analyze steps. Note: Some member values will be undefined, if
 174                     an analyze step will be disabled.
 175          */
 176                  FrameListAnalyzer( const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFramesSupplier >& xSupplier       ,
 177                                     const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame >&          xReferenceFrame ,
 178                                           sal_uInt32                                          eDetectMode     );
 179         virtual ~FrameListAnalyzer();
 180
 181     //_______________________________________
 182     // helper
 183
 184     private:
 185
 186             void impl_analyze();
 187
 188
 189 }; // class FrameListAnalyzer
 190
 191 } // namespace framework
 192
 193 #endif // INCLUDED_FRAMEWORK_FRAMELISTANALYZER_HXX
 194
 195 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */