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 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     void 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     void SetFocusedPageToCurrentPage();
 128
 129     /** Return <TRUE/> when the focus inidcator is currently shown.  A
 130         prerequisite is that the window managed by this focus manager has
 131         the input focus as indicated by a <TRUE/> return value of
 132         HasFocus().  It is not necessary that the focus indicator is
 133         visible.  It may have been scrolled outside the visible area.
 134     */
 135     bool IsFocusShowing() const;
 136
 137     /** Add a listener that is called when the focus is shown or hidden or
 138         set to another page object.
 139         @param rListener
 140             When this method is called multiple times for the same listener
 141             the second and all following calls are ignored.  Each listener
 142             is added only once.
 143     */
 144     void AddFocusChangeListener (const Link<LinkParamNone*,void>& rListener);
 145
 146     /** Remove a focus change listener.
 147         @param rListener
 148             It is safe to pass a listener that was not added are has been
 149             removed previously.  Such calls are ignored.
 150     */
 151     void RemoveFocusChangeListener (const Link<LinkParamNone*,void>& rListener);
 152
 153     /** Create an instance of this class to temporarily hide the focus
 154         indicator.  It is restored to its former visibility state when the
 155         FocusHider is destroyed.
 156     */
 157     class FocusHider
 158     {
 159     public:
 160         FocusHider (FocusManager&);
 161         ~FocusHider() COVERITY_NOEXCEPT_FALSE;
 162     private:
 163         bool const mbFocusVisible;
 164         FocusManager& mrManager;
 165     };
 166
 167 private:
 168     SlideSorter& mrSlideSorter;
 169
 170     /** Index of the page that may be focused.  It is -1 when the model
 171         contains no page.
 172     */
 173     sal_Int32 mnPageIndex;
 174
 175     /** This flag indicates whether the page pointed to by mpFocusDescriptor
 176         has the focus.
 177     */
 178     bool mbPageIsFocused;
 179
 180     ::std::vector<Link<LinkParamNone*,void>> maFocusChangeListeners;
 181
 182     /** Reset the focus state of the given descriptor and request a repaint
 183         so that the focus indicator is hidden.
 184         @param pDescriptor
 185             When NULL is given then the call is ignored.
 186     */
 187     void HideFocusIndicator (const model::SharedPageDescriptor& rpDescriptor);
 188
 189     /** Set the focus state of the given descriptor, scroll it into the
 190         visible area and request a repaint so that the focus indicator is
 191         made visible.
 192         @param pDescriptor
 193             When NULL is given then the call is ignored.
 194         @param bScrollToFocus
 195             When <TRUE/> (the default) then the view is scrolled so that the
 196             focus rectangle lies inside its visible area.
 197     */
 198     void ShowFocusIndicator (
 199         const model::SharedPageDescriptor& rpDescriptor,
 200         const bool bScrollToFocus);
 201
 202     /** Call all currently registered listeners that a focus change has
 203         happened.  The focus may be hidden or shown or moved from one page
 204         object to another.
 205     */
 206     void NotifyFocusChangeListeners() const;
 207 };
 208
 209 } } } // end of namespace ::sd::slidesorter::controller
 210
 211 #endif
 212
 213 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */