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