StyledText

UserPreferences

1. Summary

Second Beta, likely to be loaded with bugs!

This small library of widgets and demo are designed with the purpose of a full "styled text editing" widget; sort of a mini-word processor. The demo runs "as is" on my WinXP machine with Python 2.5. The demo allows styling of any selected text via toolbars; just select the text, then select the styling. Also insert images via the toolbar. Included are buttons to save and retrieve all content and styling information (works for the small tests I've tried myself, however, expect bugs!).

There are actually several classes: EnhancedText (and support classes), a drop-in replacement for the Text widget which fixes some weird cursor movement problems. It's a subclass of Text and the superclass of StyledText. Font, a new class for encapsulating StyledText's definition of a font object. Style, StyledText's object which holds styling information. StyledText, the main widget of this small library. DocumentWriter, A mini Python word processor with toolbars all thrown into a Frame -- primarily intended for use as a demo of StyledText. StyleEditor, a dialog box for allowing a user to edit and create custom Style objects.

Suggestions for imporvements are more than welcome.

2. Description

2.1. Indices

Indices are identical to those of the Text widget.

2.2. Attributes & Styles

StyledText has two kinds of styling objects. An attribute is a single styling entity such as font family, foreground color or tab settings. StyledText recognizes the following attributes:

• Font attributes: family, size, weight, slant, offset, bold, italic
• Pen attributes: foreground, background, fgstipple, bgstipple, underline, overstrike, borderwidth, relief
• Paragraph attributes: justify, wrap, tags, lmargin1, lmargin2, spacing1, spacing2, spacing3

Most are identical to those of the Text object with the same name. However, there are some variations. bold, and italic are alternative ways to express the same thing expressed by slant and weight. However, Bold and Italic take boolean values. Either method will produce the desired results.

offset can have any of the values acceptable by Text's offset. It can also take 'normal', 'superscript' or 'subscript'.

The spacing options can have any of the values acceptable by the Text's widgets options of the same name. They can also have one of the following values: 'None', 'Half Line', 'One Line' or 'Two Lines'.

A Style is a class whose instances have the complete set of styling attributes. Style contains a value DEFAULT_STYLE which contains the complete styling of the Text widget when it first comes up. A Style instance is guaranteed to have a value for each attribute. It is possible to define an empty Style instance Style(), or one with just a few values Style(foreground='blue'), in these cases, if client software requests styling for an attribute not explicitly assigned, Style will get the value from the DEFAULT_STYLE object.

StyledText maintains a dictionary object which maps style names to Style objects. This dictionary is guaranteed to contain at least one object named 'default' whose value is DEFAULT_STYLE.

Note that the term styling in this document refers to Style objects as well as attribute objects.

2.3. Styling Layers

StyledText takes advantage of the Text widget's tags and tag stacking to form a logical arrangement of styling in three layers. In this layering scheme, values assigned in higher layers obscure those in lower layers. If a value is removed from a higher layer, the previously obscured value in the lower layer takes effect.

The bottom layer is the global style layer. It's defined by exactly one Style instance which applies to the entire document. This Style object is called "default" in StyledText's style library.

Next is the local style layer. In this layer Style instances are assigned to regions of text. Only one Style instance may be assigned to any region. Therefore successive assignments on the same or an intersecting region replaces the previous Style. So, if region '1.0' to '10.6' is assigned Style AA, then '5.5' to '20.0' is assigned Style BB, then AA now only covers region '1.0' to '5.5'. It gets removed from whereever style BB overlaps. This is to prevent there be unused styles obscured by more recently applied styles (a problem with Text's tag stack).

The third (and top) layer is the attribute layer. In this layer, individual attributes may be assigned to override those in the global or local default layers below.

3. EnhancedText Methods

A subclass of Text, this class implements a complete rewrite of the Text widget's controller and introduces four new methods useful for working with indices.

• dline_prev( index, useThisX=None ), returns the index of the display-line immediately above the index provided. If useThisX is provided, the returned index is as close to x as possible, otherwise, the x from bbox(index) is used.
• dline_next( index, useThisX=None ), returns the index of the display-line immediately below the index provided. If useThisX is provided, the returned index is as close to x as possible, otherwise, the x from bbox(index) is used.
• dline_start( index ), returns the index of the first character on the display line which contains index.
• dline_end( index ), returns the index of the last character on the display line which contains index.

4. StyledText Methods

4.1. Document Contents

• insert( index, object, type=None ), insert the specified object in the given location. This is mostly a lazy-man's version the inherited

insert() method. If type is None or 'text', object may be a simple string. If type is 'dump', object may be element 0 of a sequence returned by get(). If type is 'model', object is the sequence returned by get(). If type is 'image', object is a pathname (string) to a .gif file. if type is 'widget', object is a Tkinter widget.

• get( index1, index2, dump=True ), returns the contents of the widget between the two indices. If dump is False, the contents are returned as a plain string (styling is stripped). Otherwise, styling is left intact and the result is a sequence.
• objects( ), return a dictionary of object names to objects (embedded images and widgets)

4.2. Local Styling Layer

• styles( ), return a dictionary of stylenames to style objects. To define new styles, add them to the returned dictionary. By default "default" (the Global Styling) is the only style in this dictionary.
• setInsertStyling( style ), the local default styling for any characters yet to be typed is set to style.
• setDefaultStyling( inex1, index2, styleName ), choose the local default styling for a given region.
• getDefaultStyling( index ), return the local default styling at a given index.

4.3. Attribute Styling Layer

• modifyInsertAttributes( **attributes ), Set attributes for characters yet to be typed.
• applyAttribute( index1, index2, attributeName, attributeValue ), change the value of a attribute over the indicated region.
• clearAttributes( index1, index2=None, includeStyling=True ), Clears all the styling attributes over a given region (results in default styling for that region). If includeStyling=True, then local default stying is also removed, thus only Global Default, "default", remains.

4.4. Retrieve Styling Information

• effectiveInsertStyling( ), returns the effective styling at insertion (how the next character typed would look).
• effectiveStyling( index ), returns the effective styling at the indicated index.
• iterRegion( index1, index2 ), iterate over a region one subregion at a time. yields: (startIndex, endIndex, tagNameList). A subregion is any group of one or more indices for which styling is the same. iterRegion does not skip over any subregion.

4.4.1. Other Methods

5. Implementation Details

Details of the implementation are in ?DocumentWriter.txt as part of the download.

Download Upload new attachment "DocumentWriter.zip"

Immutable page   [current page size 8442 bytes]   (last edited 2008-04-19 19:17:47 by RonLongo) FindPage by browsing, title search , text search or an index Or try one of these actions: AttachFile, DeletePage, LikePages, LocalSiteMap, SpellCheck