Layout-TNG.h revision 4ffc73d2f7ced0101455af195be98c7f45d9efb2
246N/A * Inkscape::Text::Layout - text layout engine 281N/A * Richard Hughes <cyreve@users.sf.net> 131N/A * Copyright (C) 2005 Richard Hughes 131N/A * Released under GNU GPL, read the file 'COPYING' for more information 131N/A/** \brief Generates the layout for either wrapped or non-wrapped text and stores the result 131N/AUse this class for all your text output needs. It takes text with formatting 131N/Amarkup as input and turns that into the glyphs and their necessary positions. 340N/AIt stores the glyphs internally, but maintains enough information to both 340N/Aretrieve your own rendering information if you wish and to perform visual 131N/Atext editing where the output refers back to where it came from. 131N/A-# Set the text using appendText() and appendControlCode() 131N/A-# If you want text wrapping, call appendWrapShape() a few times 183N/A-# You can go several directions from here, but the most interesting 131N/A things start with creating a Layout::iterator with begin() or end(). 131N/ATerminology, in descending order of size: 340N/A- Flow: Not often used, but when it is it means all the text 340N/A- Shape: A Shape object which is used to represent one of the regions inside 340N/A which to flow the text. Can overlap with... 340N/A- Paragraph: Err...A paragraph. Contains one or more... 131N/A- Line: An entire horizontal line with a common baseline. Contains one or 131N/A- Chunk: You only get more than one of these when a shape is sufficiently 131N/A complex that the text has to flow either side of some obstruction in 131N/A the middle. A chunk is the base unit for wrapping. Contains one or more... 131N/A- Span: A convenient subset of a chunk with the same font, style, 131N/A directionality, block progression and input stream. Fill and outline 131N/A need not be constant because that's a later rendering stage. 214N/A- This is where it gets weird because a span will contain one or more 214N/A elements of both of the following, which can overlap with each other in 131N/A - Character: a single Unicode codepoint from an input stream. Many arabic 131N/A characters contain multiple glyphs 131N/A - Glyph: a rendering primitive for font engines. A ligature glyph will 131N/A represent multiple characters. 131N/A- Input stream: An object representing a single call to appendText() or 131N/A- Control code: Metadata in the text stream to signify items that occupy 131N/A real space (unlike style changes) but don't belong in the text string. 131N/A Paragraph breaks are in this category. See Layout::TextControlCode. 131N/A- SVG1.1: The W3C Recommendation "Scalable Vector Graphics (SVG) 1.1" 131N/A- 'left', 'down', etc: These terms are generally used to mean what they 131N/A mean in left-to-right, top-to-bottom text but rotated or reflected for 131N/A the current directionality. Thus, the 'width' of a ttb line is actually 131N/A its height, and the (internally stored) y coordinate of a glyph is 131N/A actually its x coordinate. Confusing to the reader but much simpler in 131N/A the code. All public methods use real x and y. 131N/A- There's a strong emphasis on international support in this class, but 131N/A that's primarily because once you can display all the insane things 131N/A required by various languages, simple things like styling text are 227N/A- There are a few places (appendText() is one) where pointers are held to 131N/A caller-owned objects and used for quite a long time. This is messy but 131N/A is safe for our usage scenario and in many cases the cost of copying the 131N/A- "Why isn't foo here?": Ask yourself if it's possible to implement foo 131N/A externally using iterators. However this may not mean that it doesn't 131N/A belong as a member, though. 131N/A- I've used floats rather than doubles to store relative distances in some places (internal only) where it would save significant amounts of memory. The SVG spec allows you to do this as long as intermediate calculations are done double. Very very long lines might not finish precisely where you want, but that's to be expected with any typesetting. Also, SVGLength only uses floats. - If you look at the six arrays for holding the output data you'll realise that there's no O(1) way to drill down from a paragraph to find its starting glyph. This was a conscious decision to reduce complexity and to save memory. Drilling down isn't actually that slow because a binary chop will work nicely. Add this to the realisation that most of the times you do this will be in response to user actions and hence you only need to be faster than the user and I think the design makes sense. - There are a massive number of functions acting on Layout::iterator. A large number are trivial and will be inline, but is it really necessary to have all these, especially when some can be implemented by the caller - The separation of methods between Layout and Layout::iterator is a bit arbitrary, because many methods could go in either. I've used the STL model where the iterator itself can only move around; the base class is required to do anything interesting. - I use Pango internally, not Pangomm. The reason for this is lots of Pangomm methods take Glib::ustrings as input and then output byte offsets within the strings. There's simply no way to use byte offsets with ustrings without some very entertaining reinterpret_cast<>s. The Pangomm docs seem to be lacking quite a lot of things mentioned in the Pango /** Used to specify any particular text direction required. Used for both the 'direction' and 'block-progression' CSS attributes. */ /** Display alignment for shapes. See appendWrapShape(). */ /** The optional attributes which can be applied to a SVG text or related tag. See appendText(). See SVG1.1 section 10.4 for the definitions of all these members. See sp_svg_length_list_read() for the standard way to make these vectors. It is the responsibility of the caller to deal with the inheritance of these values using its knowledge of the parse tree. */ /** Control codes which can be embedded in the text to be flowed. See SHAPE_BREAK,
/// forces the flow to ignore the remainder of the current shape (from #flow_inside_shapes) and continue at the top of the one after. ARBITRARY_GAP /// inserts an arbitrarily-sized hole in the flow in line with the current text. /** For expressing paragraph alignment. These values are rotated in the case of vertical text, but are not dependent on whether the paragraph is rtl or ltr, thus LEFT is always either left or top. */ /** The CSS spec allows line-height:normal to be whatever the user agent thinks will look good. This is our value, as a multiple of font-size. */ // ************************** describing the stuff to flow ************************* Methods for describing the text you want to flow, its style, and the /** Empties everything stored in this class and resets it to its original state, like when it was created. All iterators on this object will be invalidated (but can be revalidated using /** Queries whether any calls have been made to appendText() or appendControlCode() since the object was last cleared. */ /** adds a new piece of text to the end of the current list of text to be processed. This method can only add text of a consistent style. To add lots of different styles, call it lots of times. \param text The text. \b Note: only a \em pointer is stored. Do not mess with the text until after you have called \param style The font style. Layout will hold a reference to this object for the duration of its ownership, ie until you call clear() or the class is destroyed. Must not be NULL. \param source_cookie This pointer is treated as opaque by Layout but will be passed through the flowing process intact so that callers can use it to refer to the original object that generated a particular glyph. See Layout::iterator. Implementation detail: currently all callers put an \param optional_attributes A structure containing additional options for this text. See OptionalTextTagAttrs. The values are copied to internal storage before this method returns. \param optional_attributes_offset It is convenient for callers to be able to use the same \a optional_attributes structure for several sequential text fields, in which case the vectors will need to be offset. This parameter causes the <i>n</i>th element of all the vectors to be read as if it were the \param text_begin Used for selecting only a substring of \a text \param text_end Used for selecting only a substring of \a text /** Control codes are metadata in the text stream to signify items that occupy real space (unlike style changes) but don't belong in the text string. See TextControlCode for the types available. A control code \em cannot be the first item in the input stream. Use appendText() with an empty string to set up the paragraph properties. \param code A member of the TextFlowControlCode enumeration. \param width The width in pixels that this item occupies. \param ascent The number of pixels above the text baseline that this \param descent The number of pixels below the text baseline that this \param source_cookie This pointer is treated as opaque by Layout but will be passed through the flowing process intact so that callers can use it to refer to the original object that generated a particular area. See Layout::iterator. Implementation detail: currently all callers put an Note that for some control codes (eg tab) the values of the \a width, \a ascender and \a descender are implied by the surrounding text (and in the case of tabs, the values set in tab_stops) so the values you pass /** Stores another shape inside which to flow the text. If this method is never called then no automatic wrapping is done and lines will continue to infinity if necessary. Text can be flowed inside multiple shapes in sequence, like with frames in a DTP package. If the text flows past the end of the last shape all remaining text is ignored. \param shape The Shape to use next in the flow. The storage for this is managed by the caller, and need only be valid for the duration of the call to calculateFlow(). \param display_align The vertical alignment of the text within this shape. See XSL1.0 section 7.13.4. The behaviour of settings other than DISPLAY_ALIGN_BEFORE when using non-rectangular shapes is undefined. // ************************** doing the actual flowing ************************* The method to do the actual work of converting text into glyphs. /** Takes all the stuff you set with the members above here and creates a load of glyphs for use with the members below here. All iterators on this object will be invalidated (but can be fixed with validateIterator(). The implementation just creates a new Layout::Calculator and calls its Calculator::Calculate() method, so if you want more details on the \return false on failure. // ************************** operating on the output glyphs ************************* Methods for reading and interpreting the output glyphs. See also /** Returns true if there are some glyphs in this object, ie whether computeFlow() has been called on a non-empty input since the object was created or the last call to clear(). */ /** Adds all the output glyphs to \a in_arena using the given \a paintbox. \param in_arena The arena to add the glyphs group to \param paintbox The current rendering tile /** Calculates the smallest rectangle completely enclosing all the \param bounding_box Where to store the box \param transform The transform to be applied to the entire object prior to calculating its bounds. /** Sends all the glyphs to the given print context. /** debug and unit test method. Creates a textual representation of the contents of this object. The output is designed to be both human-readable and comprehensible when diffed with a known-good dump. */ /** Moves all the glyphs in the structure so that the baseline of all the characters sits neatly along the path specified. If the text has more than one line the results are undefined. The 'align' means to use the SVG align method as documented in SVG1.1 section 10.13.2. NB: njh has suggested that it would be cool if we could flow from shape to path and back again. This is possible, so this method will be A pointer to \a path is retained by the class for use by the cursor positioning functions. */ /** Convert the specified range of characters into their bezier /** Apply the given transform to all the output presently stored in this object. This only transforms the glyph positions, The glyphs themselves will not be transformed. */ /** \name Output (Iterators) Methods for operating with the Layout::iterator class. The method names ending with 'Index' return 0-based offsets of the number of items since the beginning of the flow. /** Returns an iterator pointing at the first glyph of the flowed output. The first glyph is also the first character, line, paragraph, etc. */ /** Returns an iterator pointing just past the end of the last glyph, which is also just past the end of the last chunk, span, etc, etc. */ /** Returns an iterator pointing at the given character index. This index should be related to the result from a prior call to iteratorToCharIndex(). */ /** Returns the character index from the start of the flow represented by the given iterator. This number isn't very useful, except for when editing text it will stay valid across calls to computeFlow() and will change in predictable ways when characters are added and removed. It's also useful when transitioning old code. */ /** Checks the validity of the given iterator over the current layout. If it points to a position out of the bounds for this layout it will be corrected to the nearest valid position. If you pass an iterator belonging to a different layout it will be converted to one for this /** Returns an iterator pointing to the cursor position for a mouse click at the given coordinates. */ /** Returns an iterator pointing to the letter whose bounding box contains the given coordinates. end() if the point is not over any letter. The iterator will \em not point at the specific glyph within the character. */ /** Returns an iterator pointing to the character in the output which was created from the given input. If the character at the given byte offset was removed (soft hyphens, for example) the next character after it is returned. If no input was added with the given cookie, end() is returned. If more than one input has the same cookie, the first will be used regardless of the value of \a text_iterator. If \a text_iterator is out of bounds, the first or last character belonging to the given input will be returned accordingly. */ /** Returns an iterator pointing to the first character in the output which was created from the given source. If \a source_cookie is invalid, end() is returned. If more than one input has the same cookie, the first one will be used. */ // many functions acting on iterators, most of which are obvious // also most of them don't check that \a it != end(). Be careful. /** Returns the bounding box of the given glyph, and its rotation. The centre of rotation is the horizontal centre of the box at the /** Returns the zero-based line number of the character pointed to by /** Returns the zero-based number of the shape which contains the character pointed to by \a it. */ /** Returns true if the character at \a it is a whitespace, as defined by Pango. This is not meant to be used for picking out words from the output, use iterator::nextStartOfWord() and friends instead. */ /** Returns the unicode character code of the character pointed to by \a it. If \a it == end() the result is undefined. */ /** Discovers where the character pointed to by \a it came from, by retrieving the cookie that was passed to the call to appendText() or appendControlCode() which generated that output. If \a it == end() then NULL is returned as the cookie. If the character was generated from a call to appendText() then the optional \a text_iterator parameter is set to point to the actual character, otherwise \a text_iterator is unaltered. */ /** For latin text, the left side of the character, on the baseline */ /** This is that value to apply to the x,y attributes of tspan role=line elements, and hence it takes alignment into account. */ /** Returns the box extents (not ink extents) of the given character. The centre of rotation is at the horizontal centre of the box on the /** Basically uses characterBoundingBox() on all the characters from \a start to \a end and returns the union of these boxes. The return value is a list of zero or more quadrilaterals specified by a group of four points for each, thus size() is always a multiple of four. */ /** Returns true if \a it points to a character which is a valid cursor position, as defined by Pango. */ /** Gets the ideal cursor shape for a given iterator. The result is undefined if \a it is not at a valid cursor position. \param it The location in the output \param position The pixel location of the centre of the 'bottom' of \param height The height in pixels of the surrounding text \param rotation The angle to draw from \a position. Radians, zero up, /** Returns true if \a it points to a character which is a the start of a word, as defined by Pango. */ /** Returns true if \a it points to a character which is a the end of a word, as defined by Pango. */ /** Returns true if \a it points to a character which is a the start of a sentence, as defined by Pango. */ /** Returns true if \a it points to a character which is a the end of a sentence, as defined by Pango. */ /** Returns the zero-based number of the paragraph containing the character pointed to by \a it. */ /** Returns the actual alignment used for the paragraph containing the character pointed to by \a it. This means that the CSS 'start' and 'end' are correctly translated into LEFT or RIGHT according to the paragraph's directionality. For vertical text, LEFT is top alignment and RIGHT is bottom. */ /** Returns kerning information which could cause the current output to be exactly reproduced if the letter and word spacings were zero and full justification was not used. The x and y arrays are not used, but they are cleared. The dx applied to the first character in a chunk will always be zero. If the region between \a from and \a to crosses a line break then the results may be surprising, and are undefined. Trailing zeros on the returned arrays will be trimmed. */ /// it's useful for this to be public so that ScanlineMaker can use it void max(
LineHeight const &
other);
/// makes this object contain the largest of all three members between this object and other /// see _enum_converter() /** Erases all the stuff set by the owner as input, ie #_input_stream and #_input_wrap_shapes. */ /** Erases all the stuff output by computeFlow(). Glyphs and things. */ // ******************* input flow /** Represents a text item in the input stream. See #_input_stream. Most of the members are copies of the values passed to appendText(). */ int text_length;
/// in characters, from text_start to text_end only /** These vectors can (often will) be shorter than the text in this source, but never longer. */ // a few functions for some of the more complicated style accesses /// The return value must be freed with pango_font_description_free() /** Represents a control code item in the input stream. See #_input_streams. All the members are copies of the values passed to /** This is our internal storage for all the stuff passed to the appendText() and appendControlCode() functions. */ /** The parameters to appendText() are allowed to be a little bit complex. This copies them to be the right length and starting at zero. We also don't want to write five bits of identical code just with different variable names. */ /** There are a few cases where we have different sets of enums meaning the same thing, eg Pango font styles vs. SPStyle font styles. These need /** The overall block-progression of the whole flow. */ /** so that LEFT_TO_RIGHT == RIGHT_TO_LEFT but != TOP_TO_BOTTOM */ /** If the output is empty callers still want to be able to call queryCursorShape() and get a valid answer so, while #_input_wrap_shapes can still be considered valid, we need to precompute the cursor shape // ******************* input shapes Shape const *
shape;
/// as passed to Layout::appendWrapShape() // ******************* output /** as passed to fitToPathAlign() */ float x;
/// relative to the start of the chunk float y;
/// relative to the current line's baseline float rotation;
/// absolute, modulo any object transforms, which we don't know about float x;
/// relative to the start of the *span* (so we can do block-progression) int in_glyph;
/// will be -1 if this character has no visual representation // to get the advance width of a character, subtract the x values if it's in the middle of a span, or use span.x_end if it's at the end float x_start;
/// relative to the start of the chunk float x_end;
/// relative to the start of the chunk /** gets the overall matrix that transforms the given glyph from local // loads of functions to drill down the object tree, all of them // annoyingly similar and all of them requiring predicate functors. // I'll be buggered if I can find a way to make it work with // functions or with a templated functor, so macros it is. /** given an x coordinate and a line number, returns an iterator pointing to the closest cursor position on that line to the /** calculates the width of a chunk, which is the largest x coordinate (start or end) of the spans contained within it. */ /** \brief Holds a position within the glyph output of Layout. Used to access the output of a Layout, query information and generally move around in it. See Layout for a glossary of the names of functions. I'm not going to document all the methods because most of their names make their function self-evident. A lot of the functions would do the same thing in a naive implementation for latin-only text, for example nextCharacter(), nextCursorPosition() and cursorRight(). Generally it's fairly obvious which one you should use in a given situation, but sometimes you might need to put some thought in to it. All the methods return false if the requested action would have caused the current position to move out of bounds. In this case the position is moved to either begin() or end(), depending on which direction you were going. Note that some characters do not have a glyph representation (eg line breaks), so if you try using prev/nextGlyph() from one of these you're // this is just so you can create uninitialised iterators - don't actually try to use one // no copy constructor required, the default does what we want /* mustn't compare _glyph_index in these operators because for characters that don't have glyphs (line breaks, elided soft hyphens, etc), the glyph index is -1 which makes them not well-ordered. To be honest, interating by glyphs is not very useful and should be avoided. */ /* **** visual-oriented methods **** */ /* **** text-oriented methods **** */ //no endOfPara methods because that's just the previous char //logical cursor movement //logical cursor movement (by word or paragraph) /** for cursor up/down movement we must maintain the x position where we started so the cursor doesn't 'drift' left or right with the repeated quantization to character boundaries. */ void beginCursorUpDown();
/// stores the current x coordinate so that the cursor won't drift. See #_x_coordinate /** moves forward or backwards one cursor position according to the directionality of the current paragraph, but ignoring block progression. Helper for the cursor*() functions. */ /** moves forward or backwards by until the next character with is_word_start according to the directionality of the current paragraph, but ignoring block progression. Helper for the cursor*WithControl() // ************************** inline methods c-file-style:"stroustrup" c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +)) // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :