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