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