sd/source/ui/slidesorter/inc/controller/SlsFocusManager.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: SlsFocusManager.hxx,v $
  10  * $Revision: 1.10 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef SD_SLIDESORTER_FOCUS_MANAGER_HXX
  32 #define SD_SLIDESORTER_FOCUS_MANAGER_HXX
  33
  34 #include <model/SlsSharedPageDescriptor.hxx>
  35
  36 #include <sal/types.h>
  37 #include <tools/link.hxx>
  38 #include <vector>
  39
  40 namespace sd { namespace slidesorter {
  41 class SlideSorter;
  42 } }
  43
  44
  45 namespace sd { namespace slidesorter { namespace controller {
  46
  47 /** This class manages the focus of the slide sorter.  There is the focus
  48     page which is or is not focused.  Initialized to point to the first page
  49     it can be set to other pages by using the MoveFocus() method.  The
  50     focused state of the focus page can be toggled with the ToggleFocus()
  51     method.
  52 */
  53 class FocusManager
  54 {
  55 public:
  56     /** Create a new focus manager that operates on the pages of the model
  57         associated with the given controller.  The focus page is set to the
  58         first page.  Focused state is off.
  59     */
  60     FocusManager (SlideSorter& rSlideSorter);
  61
  62     ~FocusManager (void);
  63
  64     enum FocusMoveDirection
  65     {
  66         FMD_NONE,
  67         FMD_LEFT,
  68         FMD_RIGHT,
  69         FMD_UP,
  70         FMD_DOWN
  71     };
  72
  73     /** Move the focus from the currently focused page to one that is
  74         displayed adjacent to it, either vertically or horizontally.
  75         @param eDirection
  76             Direction in which to move the focus.  Wrap arround is done
  77             differently when moving vertically or horizontally.  Vertical
  78             wrap arround takes place in the same column, i.e. when you are
  79             in the top row and move up you come out in the bottom row in the
  80             same column.  Horizontal wrap arround moves to the next
  81             (FMD_RIGHT) or previous (FMD_LEFT) page.  Moving to the right
  82             from the last page goes to the first page and vice versa.
  83             When FMD_NONE is given, the current page index is checked for
  84             being valid.  If it is not, then it is set to the nearest valid
  85             page index.
  86     */
  87     void MoveFocus (FocusMoveDirection eDirection);
  88
  89     /** Show the focus indicator of the current slide.
  90     */
  91     void ShowFocus (void);
  92
  93     /** Hide the focus indicator.
  94     */
  95     void HideFocus (void);
  96
  97     /** Toggle the focused state of the current slide.
  98         @return
  99             Returns the focused state of the focus page after the call.
 100     */
 101     bool ToggleFocus (void);
 102
 103     /** Return whether the window managed by the called focus manager has
 104         the input focus of the application.
 105     */
 106     bool HasFocus (void) const;
 107
 108     /** Return the descriptor of the page that currently has the focus.
 109         @return
 110             When there is no page that currently has the focus then NULL is
 111             returned.
 112     */
 113     model::SharedPageDescriptor GetFocusedPageDescriptor (void) const;
 114
 115     /** Return the index of the page that currently has the focus as it is
 116         accepted by the slide sorter model.
 117         @return
 118             When there is no page that currently has the focus then -1 is
 119             returned.
 120     */
 121     sal_Int32 GetFocusedPageIndex (void) const;
 122
 123     /** DEPRECATED. (Use equivalent SetFocusedPage(sal_Int32) instead.
 124
 125         Set the focus to the page with the given index.  This does not make
 126         the focus visible.
 127         @param nPageIndex
 128             Index of a page as it is accepted by the slide sorter model.
 129             The index is not checked for validity.
 130     */
 131     void FocusPage (sal_Int32 nPageIndex);
 132
 133     /** Set the focused page to the one described by the given page
 134         descriptor.  The visibility of the focus indicator is not modified.
 135         @param rDescriptor
 136             One of the page descriptors that are currently managed by the
 137             SlideSorterModel.
 138     */
 139     void SetFocusedPage (const model::SharedPageDescriptor& rDescriptor);
 140
 141     /** Set the focused page to the one described by the given page
 142         index.  The visibility of the focus indicator is not modified.
 143         @param nPageIndex
 144             A valid page index that is understood by the SlideSorterModel.
 145     */
 146     void SetFocusedPage (sal_Int32 nPageIndex);
 147
 148     /** Return <TRUE/> when the focus inidcator is currently shown.  A
 149         prerequisite is that the window managed by this focus manager has
 150         the input focus as indicated by a <TRUE/> return value of
 151         HasFocus().  It is not necessary that the focus indicator is
 152         visible.  It may have been scrolled outside the visible area.
 153     */
 154     bool IsFocusShowing (void) const;
 155
 156     /** Add a listener that is called when the focus is shown or hidden or
 157         set to another page object.
 158         @param rListener
 159             When this method is called multiple times for the same listener
 160             the second and all following calls are ignored.  Each listener
 161             is added only once.
 162     */
 163     void AddFocusChangeListener (const Link& rListener);
 164
 165     /** Remove a focus change listener.
 166         @param rListener
 167             It is save to pass a listener that was not added are has been
 168             removed previously.  Such calls are ignored.
 169     */
 170     void RemoveFocusChangeListener (const Link& rListener);
 171
 172     /** Move focus to sibling outside the actual slide sorter.  This is
 173         typically the tool bar with the close button.
 174     */
 175     void SetFocusToToolBox (void);
 176
 177     /** Create an instance of this class to temporarily hide the focus
 178         indicator.  It is restored to its former visibility state when the
 179         FocusHider is destroyed.
 180     */
 181     class FocusHider
 182     {
 183     public:
 184         FocusHider (FocusManager&);
 185         ~FocusHider (void);
 186     private:
 187         bool mbFocusVisible;
 188         FocusManager& mrManager;
 189     };
 190
 191 private:
 192     SlideSorter& mrSlideSorter;
 193
 194     /** Index of the page that may be focused.  It is -1 when the model
 195         contains no page.
 196     */
 197     sal_Int32 mnPageIndex;
 198
 199     /** This flag indicates whether the page pointed to by mpFocusDescriptor
 200         has the focus.
 201     */
 202     bool mbPageIsFocused;
 203
 204     ::std::vector<Link> maFocusChangeListeners;
 205
 206     /** Reset the focus state of the given descriptor and request a repaint
 207         so that the focus indicator is hidden.
 208         @param pDescriptor
 209             When NULL is given then the call is ignored.
 210     */
 211     void HideFocusIndicator (const model::SharedPageDescriptor& rpDescriptor);
 212
 213     /** Set the focus state of the given descriptor, scroll it into the
 214         visible area and request a repaint so that the focus indicator is
 215         made visible.
 216         @param pDescriptor
 217             When NULL is given then the call is ignored.
 218     */
 219     void ShowFocusIndicator (const model::SharedPageDescriptor& rpDescriptor);
 220
 221     /** Call all currently registered listeners that a focus change has
 222         happended.  The focus may be hidden or shown or moved from one page
 223         object to another.
 224     */
 225     void NotifyFocusChangeListeners (void) const;
 226 };
 227
 228 } } } // end of namespace ::sd::slidesorter::controller
 229
 230 #endif
 231