sw/inc/IDocumentBookmarkAccess.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: IDocumentBookmarkAccess.hxx,v $
  10  * $Revision: 1.6 $
  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 IDOCUMENTBOOKMARKACCESS_HXX_INCLUDED
  32 #define IDOCUMENTBOOKMARKACCESS_HXX_INCLUDED
  33
  34 #include <sal/types.h>
  35
  36 class SwBookmark;
  37 class SwFieldBookmark;
  38 class SwBookmarks;
  39 class SwPaM;
  40 class KeyCode;
  41 class String;
  42 struct SwPosition;
  43 class SwTxtNode;
  44
  45 /** Provides access to the bookmarks of a document.
  46 */
  47 class IDocumentBookmarkAccess
  48 {
  49 public:
  50     enum BookmarkType
  51     {
  52         BOOKMARK,
  53         MARK,
  54         DDE_BOOKMARK,
  55         UNO_BOOKMARK,
  56         // --> OD 2007-10-11 #i81002# - bookmark type for cross-references
  57         CROSSREF_BOOKMARK,
  58         // <--
  59  //             FIELDMARK, // for future use...
  60                 FORM_FIELDMARK_TEXT,
  61                 FORM_FIELDMARK_NO_TEXT
  62     };
  63
  64     // --> OD 2007-11-16 #i83479#
  65     enum CrossReferenceBookmarkSubType
  66     {
  67         HEADING,
  68         NUMITEM
  69     };
  70     // <--
  71
  72 public:
  73     /** Returns all bookmarks set at the document.
  74
  75        @returns
  76        the bookmarks set at the document.
  77         */
  78     virtual const SwBookmarks& getBookmarks() const = 0;
  79
  80     /** Generates a new bookmark in the document.
  81
  82        @param rPaM
  83        [in] the location of the new bookmark.
  84
  85        @param rKC
  86        [in] ???
  87
  88        @param rName
  89        [in] the name of the new bookmark.
  90
  91        @param rShortName
  92        [in] the short name of the new bookmark.
  93
  94        @param eMark
  95        [in] the type of the new bookmark.
  96
  97        @returns
  98        a pointer to the new bookmark.
  99     */
 100     virtual SwBookmark* makeBookmark( /*[in]*/const SwPaM& rPaM, /*[in]*/const KeyCode& rKC,
 101                                       /*[in]*/const String& rName, /*[in]*/const String& rShortName,
 102                                       /*[in]*/BookmarkType eMark ) = 0;
 103
 104     /** Deletes a bookmark.
 105
 106        @param nPos
 107        [in] the position of the bookmark to be deleted.
 108     */
 109     virtual void deleteBookmark( /*[in]*/sal_uInt16 nPos ) = 0;
 110
 111     /** Deletes a bookmark.
 112
 113        @param rName
 114        [in] the name of the bookmark to be deleted.
 115     */
 116     virtual void deleteBookmark( /*[in]*/const String& rName ) = 0;
 117
 118     /** Checks, if the given name fits to the cross-reference bookmark
 119         name schema
 120
 121         OD 2007-10-24 #i81002#
 122
 123         @author OD
 124
 125         @param rName
 126         [in] the name to be checked.
 127
 128         @returns
 129         boolean indicating , if the name fits or not
 130     */
 131     virtual bool isCrossRefBookmarkName( /*[in]*/const String& rName ) = 0;
 132
 133     /** Find a bookmark.
 134
 135        @param rName
 136        [in] the name of the bookmark to be found.
 137
 138        @returns
 139        the position of the bookmark in the bookmark container.
 140     */
 141     virtual sal_uInt16 findBookmark(  /*[in]*/const String& rName ) = 0;
 142
 143     /** Generates a unique bookmark name. The name has to be passed to the
 144         function, a number will be added to the name if the name is already
 145         used.
 146
 147        @param rName
 148        [in/out] the name of the bookmark.
 149     */
 150     virtual void makeUniqueBookmarkName( /*[in/out]*/String& rName ) = 0;
 151
 152     /** Get the number of ::com::sun::star::text::Bookmarks.
 153
 154        @param bBkmrk
 155        [in] if set, only "real" bookmarks are considered.
 156
 157        @returns
 158        the number of bookmarks.
 159     */
 160     virtual sal_uInt16 getBookmarkCount( /*[in]*/bool bBkmrk) const = 0;
 161
 162     /** Get a bookmark.
 163
 164        @param nPos
 165        [in] the position of the bookmark in the bookmark container.
 166
 167        @param bBkmrk
 168        [in] if set, only "real" bookmarks are considered.
 169
 170        @returns
 171        the bookmark.
 172     */
 173     virtual SwBookmark& getBookmark(  /*[in]*/sal_uInt16 nPos, /*[in]*/bool bBkmrk) = 0;
 174
 175     /** Get cross-reference bookmark name for certain text node
 176
 177         OD 2007-11-16 #i83479#
 178
 179         @author OD
 180
 181         @param rTxtNode
 182         [in] reference to text node, whose cross-reference bookmark name has to be returned.
 183
 184         @param nCrossRefType
 185         [in] sub type of cross-reference bookmark, whose name has to be returned.
 186
 187         @returns
 188         name of cross-reference bookmark of given cross-reference sub type,
 189         if such a cross-reference bookmark exists at given textnode.
 190         otherwise, empty string
 191     */
 192     virtual String getCrossRefBookmarkName(
 193             /*[in]*/const SwTxtNode& rTxtNode,
 194             /*[in]*/const CrossReferenceBookmarkSubType nCrossRefType ) const = 0;
 195
 196     /** Generates new cross-reference bookmark for given text node of given sub type
 197
 198         OD 2007-11-16 #i83479#
 199
 200         @author OD
 201
 202         @param rTxtNode
 203         [in] reference to text node, at which the cross-reference bookmark has to be generated.
 204
 205         @param nCrossRefType
 206         [in] sub type of cross-reference bookmark.
 207
 208         @returns
 209         name of generated cross-reference bookmark.
 210         If empty, cross-reference bookmark is not generated.
 211     */
 212     virtual String makeCrossRefBookmark(
 213                 /*[in]*/const SwTxtNode& rTxtNode,
 214                 /*[in]*/const CrossReferenceBookmarkSubType nCrossRefType ) = 0;
 215
 216     virtual SwBookmark* getFieldBookmarkFor(const SwPosition &pos) const = 0;
 217     virtual SwFieldBookmark* getFormFieldBookmarkFor(const SwPosition &pos) const = 0;
 218     virtual SwBookmark* getNextFieldBookmarkFor(const SwPosition &pos) const = 0;
 219     virtual SwBookmark* getPrevFieldBookmarkFor(const SwPosition &pos) const = 0;
 220
 221 protected:
 222     virtual ~IDocumentBookmarkAccess() {};
 223 };
 224
 225 namespace bookmarkfunc
 226 {
 227     /** return the prefix used for cross-reference bookmark for headings
 228
 229         OD 2007-11-16 #i83479#
 230
 231         @author OD
 232     */
 233     const String getHeadingCrossRefBookmarkNamePrefix();
 234
 235     /** return the prefix used for cross-reference bookmark for numbered items
 236
 237         OD 2007-11-16 #i83479#
 238
 239         @author OD
 240     */
 241     const String getNumItemCrossRefBookmarkNamePrefix();
 242
 243     /** Checks, if the given name fits to the heading cross-reference bookmark
 244         name schema
 245
 246         OD 2007-11-09 #i81002#
 247
 248         @author OD
 249
 250         @param rName
 251         [in] the name to be checked.
 252
 253         @returns
 254         boolean indicating , if the name fits or not
 255     */
 256     bool isHeadingCrossRefBookmarkName( /*[in]*/const String& rName );
 257
 258     /** Checks, if the given name fits to the numbered item cross-reference
 259         bookmark name schema
 260
 261         OD 2007-11-09 #i81002#
 262
 263         @author OD
 264
 265         @param rName
 266         [in] the name to be checked.
 267
 268         @returns
 269         boolean indicating , if the name fits or not
 270     */
 271     bool isNumItemCrossRefBookmarkName( /*[in]*/const String& rName );
 272
 273     /** generate new name for a cross-reference bookmark of given sub type
 274
 275         OD 2007-11-16 #i83479#
 276
 277         @author OD
 278     */
 279     String generateNewCrossRefBookmarkName(
 280             /*[in]*/const IDocumentBookmarkAccess::CrossReferenceBookmarkSubType nSubType );
 281 }
 282 #endif // IDOCUMENTBOOKMARKACCESS_HXX_INCLUDED