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