include/vcl/mnemonicengine.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 VCL_MNEMONICENGINE_HXX
  21 #define VCL_MNEMONICENGINE_HXX
  22
  23 #include "dllapi.h"
  24
  25 #include <sal/config.h>
  26 #include <sal/types.h>
  27
  28 #include <memory>
  29
  30 class String;
  31 class KeyEvent;
  32
  33 //........................................................................
  34 namespace vcl
  35 {
  36 //........................................................................
  37
  38     //====================================================================
  39     //= IMnemonicEntryList
  40     //====================================================================
  41     /// callback for a MnemonicEngine
  42     class SAL_NO_VTABLE VCL_DLLPUBLIC IMnemonicEntryList
  43     {
  44     public:
  45         /** returns the first list entry for the mnemonic search
  46
  47             @return
  48                 a pointer which can be used to unuquely identify the entry.
  49                 The MenomonicEngine itself does not use this value, it
  50                 is only passed to other methods of this callback interface.
  51
  52                 If this value is <NULL/>, searching stops.
  53         */
  54         virtual const void* FirstSearchEntry( String& _rEntryText ) const = 0;
  55
  56         /** returns the next list entry for the mnemonic search
  57
  58             @return
  59                 a pointer which can be used to unuquely identify the entry.
  60                 The MenomonicEngine itself does not use this value, it
  61                 is only passed to other methods of this callback interface.
  62
  63                 If this value is <NULL/>, searching stops.
  64
  65                 If this value is the same as returned by the previous call
  66                 to <member>FirstSearchEntry</member> (i.e. you cycled
  67                 around), then searching stops, too.
  68         */
  69         virtual const void* NextSearchEntry( const void* _pCurrentSearchEntry, String& _rEntryText ) const = 0;
  70
  71         /** "selects" a given entry.
  72
  73             Note: The semantics of "select" depends on your implementation. You
  74             might actually really select the entry (in the sense of a selected
  75             list box entry, for example), you might make it the current entry,
  76             if your implementation supports this - whatever.
  77
  78             @param _pEntry
  79                 the entry to select. This is the return value of a previous call
  80                 to <member>FirstSearchEntry</member> or <member>NextSearchEntry</member>.
  81         */
  82         virtual void    SelectSearchEntry( const void* _pEntry ) = 0;
  83
  84         /** "executes" the current search entry, i.e. the one returned
  85             in the previous <member>NextSearchEntry</member> call.
  86
  87             Note: The semantics of "execute" depends on your implementation. You
  88             might even have a list of entries which cannot be executed at all.
  89
  90             This method is called after <member>SelectSearchEntry</member>,
  91             if and only if the current entry's mnemonic is unambiguous.
  92
  93             For instance, imagine a list which has two entries with the same mnemonic
  94             character, say "c". Now if the user presses <code>Alt-C</code>, the MnemonicEngine
  95             will call <member>SelectCurrentEntry</member> as soon as it encounters
  96             the first entry, but it'll never call <member>ExecuteSearchEntry</member>.
  97
  98             If, however, "c" is a unique mnemonic character in your entry list, then the
  99             call of <member>SelectSearchEntry</member> will be followed by a
 100             call to <member>ExecuteSearchEntry</member>.
 101
 102             This way, you can implement cyclic selection of entries: In
 103             <member>FirstSearchEntry</member>, return the entry which was previously
 104             selected, and in <member>NextSearchEntry</member>, interlly cycle around
 105             in your list. Then, multiple user inputs of <code>Alt-C</code> will
 106             cycle through all entries with the mnemonic being "c".
 107
 108             @param _pEntry
 109                 the entry to select. This is the return value of a previous call
 110                 to <member>FirstSearchEntry</member> or <member>NextSearchEntry</member>.
 111         */
 112         virtual void    ExecuteSearchEntry( const void* _pEntry ) const = 0;
 113
 114     protected:
 115         ~IMnemonicEntryList() {}
 116     };
 117
 118     //====================================================================
 119     //= MnemonicEngine
 120     //====================================================================
 121     struct MnemonicEngine_Data;
 122     class VCL_DLLPUBLIC MnemonicEngine
 123     {
 124         ::std::auto_ptr< MnemonicEngine_Data >  m_pData;
 125
 126     public:
 127         MnemonicEngine( IMnemonicEntryList& _rEntryList );
 128         ~MnemonicEngine();
 129
 130         /** handles a key event
 131
 132             If the key event denotes pressing an accelerator key, then the
 133             entry list is searched for a matching entry. If such an entry is
 134             found, <member>IMnemonicEntryList::SelectSearchEntry</member>
 135             is called.
 136
 137             If the entry is the only one with the given mnemonic character, then
 138             also <member>IMnemonicEntryList::ExecuteSearchEntry</member>
 139             is called.
 140
 141             @return
 142                 if the key event has been handled, and should thus not be processed
 143                 further.
 144         */
 145         bool    HandleKeyEvent( const KeyEvent& _rKEvt );
 146     };
 147
 148 //........................................................................
 149 } // namespace vcl
 150 //........................................................................
 151
 152 #endif // VCL_MNEMONICENGINE_HXX
 153
 154 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */