sw/source/core/inc/SwPortionHandler.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: SwPortionHandler.hxx,v $
  10  * $Revision: 1.5 $
  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 #ifndef _SW_PORTIONHANDLER_HXX
  31 #define _SW_PORTIONHANDLER_HXX
  32
  33 #include <tools/solar.h>
  34 class String;
  35
  36 /** The SwPortionHandler interface implements a visitor for the layout
  37  * engine's text portions. This can be used to gather information of
  38  * the on-screen representation of a single paragraph.
  39  *
  40  * For each text portion, one of the methods text(...) or special(...)
  41  * is called, depending on whether it is a 'normal' run of text, or
  42  * any other portion. Additionally, the linebreak() method is called
  43  * once at the end of every on-screen line.
  44  *
  45  * All parameters relate to the 'model string', which is the text string
  46  * held by the corresponding SwTxtNode.
  47  *
  48  * The SwPortionHandler can be used with the
  49  * SwTextFrame::VisitPortions(...) method.
  50  */
  51 class SwPortionHandler
  52 {
  53 public:
  54
  55     SwPortionHandler() {}           /// (emtpy) constructor
  56
  57     virtual ~SwPortionHandler() {}  /// (empty) destructor
  58
  59     /** text portion. A run of nLength characters from the model
  60      * string, that contains no special characters like embedded
  61      * fields, etc. Thus, the on-screen text of this portion
  62      * corresponds exactly to the corresponding characters in the
  63      * model string.
  64      */
  65     virtual void Text(
  66         USHORT nLength,      /// length of this portion in the model string
  67         USHORT nType         /// type of this portion
  68         ) = 0;
  69
  70     /** special portion. This method is called for every non-text
  71      * portion. The parameters describe the length of the
  72      * corresponding characters in the model string (often 0 or 1),
  73      * the text which is displayed, and the type of the portion.
  74      */
  75     virtual void Special(
  76         USHORT nLength,      /// length of this portion in the model string
  77         const String& rText, /// text which is painted on-screen
  78         USHORT nType         /// type of this portion
  79         ) = 0;
  80
  81     /** line break. This method is called whenever a line break in the
  82      * layout occurs.
  83      */
  84     virtual void LineBreak() = 0;
  85
  86     /** skip characters. The SwTxtFrame may only display partially
  87      * display a certain paragraph (e.g. when the paragaph is split
  88      * across multiple pages). In this case, the Skip() method must be
  89      * called to inform the portion handler to ignore a certain run of
  90      * characters in the 'model string'. Skip(), if used at all, must
  91      * be called before any of the other methods is called. Calling
  92      * Skip() between portions is not allowed.
  93      */
  94     virtual void Skip(
  95         USHORT nLength   /// number of 'model string' characters to be skipped
  96         ) = 0;
  97
  98     /** end of paragraph. This method is to be called when all the
  99      * paragraph's portions have been processed.
 100      */
 101     virtual void Finish() = 0;
 102 };
 103
 104 #endif