sd/source/ui/slidesorter/inc/controller/SlsFocusManager.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_SD_SOURCE_UI_SLIDESORTER_INC_CONTROLLER_SLSFOCUSMANAGER_HXX
  21 #define INCLUDED_SD_SOURCE_UI_SLIDESORTER_INC_CONTROLLER_SLSFOCUSMANAGER_HXX
  22
  23 #include <model/SlsSharedPageDescriptor.hxx>
  24
  25 #include <sal/types.h>
  26 #include <tools/link.hxx>
  27 #include <vector>
  28
  29 namespace sd { namespace slidesorter {
  30 class SlideSorter;
  31 } }
  32
  33 namespace sd { namespace slidesorter { namespace controller {
  34
  35 /** This class manages the focus of the slide sorter.  There is the focus
  36     page which is or is not focused.  Initialized to point to the first page
  37     it can be set to other pages by using the MoveFocus() method.  The
  38     focused state of the focus page can be toggled with the ToggleFocus()
  39     method.
  40 */
  41 class FocusManager
  42 {
  43 public:
  44     /** Create a new focus manager that operates on the pages of the model
  45         associated with the given controller.  The focus page is set to the
  46         first page.  Focused state is off.
  47     */
  48     FocusManager (SlideSorter& rSlideSorter);
  49
  50     ~FocusManager();
  51
  52     enum FocusMoveDirection
  53     {
  54         FMD_NONE,
  55         FMD_LEFT,
  56         FMD_RIGHT,
  57         FMD_UP,
  58         FMD_DOWN
  59     };
  60
  61     /** Move the focus from the currently focused page to one that is
  62         displayed adjacent to it, either vertically or horizontally.
  63         @param eDirection
  64             Direction in which to move the focus.  Wrap around is done
  65             differently when moving vertically or horizontally.  Vertical
  66             wrap around takes place in the same column, i.e. when you are
  67             in the top row and move up you come out in the bottom row in the
  68             same column.  Horizontal wrap around moves to the next
  69             (FMD_RIGHT) or previous (FMD_LEFT) page.  Moving to the right
  70             from the last page goes to the first page and vice versa.
  71             When FMD_NONE is given, the current page index is checked for
  72             being valid.  If it is not, then it is set to the nearest valid
  73             page index.
  74     */
  75     void MoveFocus (FocusMoveDirection eDirection);
  76
  77     /** Show the focus indicator of the current slide.
  78         @param bScrollToFocus
  79             When <TRUE/> (the default) then the view is scrolled so that the
  80             focus rectangle lies inside its visible area.
  81     */
  82     void ShowFocus (const bool bScrollToFocus = true);
  83
  84     /** Hide the focus indicator.
  85     */
  86     void HideFocus();
  87
  88     /** Toggle the focused state of the current slide.
  89         @return
  90             Returns the focused state of the focus page after the call.
  91     */
  92     bool ToggleFocus();
  93
  94     /** Return whether the window managed by the called focus manager has
  95         the input focus of the application.
  96     */
  97     bool HasFocus() const;
  98
  99     /** Return the descriptor of the page that currently has the focus.
 100         @return
 101             When there is no page that currently has the focus then NULL is
 102             returned.
 103     */
 104     model::SharedPageDescriptor GetFocusedPageDescriptor() const;
 105
 106     /** Return the index of the page that currently has the focus as it is
 107         accepted by the slide sorter model.
 108         @return
 109             When there is no page that currently has the focus then -1 is
 110             returned.
 111     */
 112     sal_Int32 GetFocusedPageIndex() const { return mnPageIndex;}
 113
 114     /** Set the focused page to the one described by the given page
 115         descriptor.  The visibility of the focus indicator is not modified.
 116         @param rDescriptor
 117             One of the page descriptors that are currently managed by the
 118             SlideSorterModel.
 119     */
 120     void SetFocusedPage (const model::SharedPageDescriptor& rDescriptor);
 121
 122     /** Set the focused page to the one described by the given page
 123         index.  The visibility of the focus indicator is not modified.
 124         @param nPageIndex
 125             A valid page index that is understood by the SlideSorterModel.
 126     */
 127     void SetFocusedPage (sal_Int32 nPageIndex);
 128
 129     void SetFocusedPageToCurrentPage();
 130
 131     /** Return <TRUE/> when the focus inidcator is currently shown.  A
 132         prerequisite is that the window managed by this focus manager has
 133         the input focus as indicated by a <TRUE/> return value of
 134         HasFocus().  It is not necessary that the focus indicator is
 135         visible.  It may have been scrolled outside the visible area.
 136     */
 137     bool IsFocusShowing() const;
 138
 139     /** Add a listener that is called when the focus is shown or hidden or
 140         set to another page object.
 141         @param rListener
 142             When this method is called multiple times for the same listener
 143             the second and all following calls are ignored.  Each listener
 144             is added only once.
 145     */
 146     void AddFocusChangeListener (const Link<>& rListener);
 147
 148     /** Remove a focus change listener.
 149         @param rListener
 150             It is save to pass a listener that was not added are has been
 151             removed previously.  Such calls are ignored.
 152     */
 153     void RemoveFocusChangeListener (const Link<>& rListener);
 154
 155     /** Create an instance of this class to temporarily hide the focus
 156         indicator.  It is restored to its former visibility state when the
 157         FocusHider is destroyed.
 158     */
 159     class FocusHider
 160     {
 161     public:
 162         FocusHider (FocusManager&);
 163         ~FocusHider();
 164     private:
 165         bool mbFocusVisible;
 166         FocusManager& mrManager;
 167     };
 168
 169 private:
 170     SlideSorter& mrSlideSorter;
 171
 172     /** Index of the page that may be focused.  It is -1 when the model
 173         contains no page.
 174     */
 175     sal_Int32 mnPageIndex;
 176
 177     /** This flag indicates whether the page pointed to by mpFocusDescriptor
 178         has the focus.
 179     */
 180     bool mbPageIsFocused;
 181
 182     ::std::vector<Link<>> maFocusChangeListeners;
 183
 184     /** When vertical wrap is active then pressing UP in the top row moves
 185         the focus to the bottom row, DOWN in the bottom row moves the focus
 186         to the top row.
 187     */
 188     bool mbIsVerticalWrapActive;
 189
 190     /** Reset the focus state of the given descriptor and request a repaint
 191         so that the focus indicator is hidden.
 192         @param pDescriptor
 193             When NULL is given then the call is ignored.
 194     */
 195     void HideFocusIndicator (const model::SharedPageDescriptor& rpDescriptor);
 196
 197     /** Set the focus state of the given descriptor, scroll it into the
 198         visible area and request a repaint so that the focus indicator is
 199         made visible.
 200         @param pDescriptor
 201             When NULL is given then the call is ignored.
 202         @param bScrollToFocus
 203             When <TRUE/> (the default) then the view is scrolled so that the
 204             focus rectangle lies inside its visible area.
 205     */
 206     void ShowFocusIndicator (
 207         const model::SharedPageDescriptor& rpDescriptor,
 208         const bool bScrollToFocus);
 209
 210     /** Call all currently registered listeners that a focus change has
 211         happened.  The focus may be hidden or shown or moved from one page
 212         object to another.
 213     */
 214     void NotifyFocusChangeListeners() const;
 215 };
 216
 217 } } } // end of namespace ::sd::slidesorter::controller
 218
 219 #endif
 220
 221 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */