The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Gtk2-Ex-WYSIWYG-0.02
River stage zero No dependents
++
/ Gtk2::Ex::WYSIWYG

NAME

Gtk2::Ex::WYSIWYG - A WYSIWYG editor ready to drop into a GUI.

VERSION

Version 0.02

DESCRIPTION

This module is a subclass of Gtk2::Table containing both a text view and a 'toolbar' to allow a user to edit and format text. It can serialise to a plain text block and a tag stack, or to incomplete HTML (the output is not a complete HTML document, but can be included inside one). It can also 'deserialise' from this same data to easily allow content from one WYSIWYG to be transfered to another - the more efficient of these is the text/tag stack, however the HTML form can be more easily stored.

An undo/redo stack is also included, as well as a modification to the text view's popup menu to allow the user to set the wrap mode with ease.

It should be noted that WYSIWYG emulates paragraphs by using \n\s*\n as a paragraph separator. The leading newline in the sequence will belong to the leading paragraph, and the rest to 'interparagraph space'. This has some implications - interparagraph space honours vertical space (ie, extra newlines will be rendered when exporting to HTML) but not horizontal space - any spaces you put inside interparagraph space will be ignored, as will any font formatting you apply.

It also means that should two paragraphs be joined by a user edit (either by inserting non-whitespace or by deleteing whitespace) any paragraph-level formatting applied to the paragraph that used to be before the interparagraph space will be applied to any affected paragraphs after it.

See the TAGS section below for supported tags.

There are currently three 'sub-packages' contained within Gtk2::Ex::WYSIWYG as well - Gtk2::Ex::WYSIWYG::HTML (for parsing and generating HTML from the view), Gtk2::Ex::WYSIWYG::FormatMenu (a Gtk2::ComboBox replacement that shows formatting in the option menu but not in the main widget) and Gtk2::Ex::WYSIWYG::SizeMenu (a beefed up Gtk2::ComboBoxEntry with a few extra features, specifically designed for the font size setting).

HIERARCHY

  Glib::Object
  +----Glib::InitiallyUnowned
       +----Gtk2::Object
            +----Gtk2::Widget
                 +----Gtk2::Container
                      +----Gtk2::Table
                           +---Gtk2::Ex::WYSIWYG

METHODS

Gtk2::Ex::WYSIWYG->new()

Returns a new WYSIWYG instance. There are a few properties you can set, see the PROPERTIES section below.

$wysiwyg->clear_undo()

Empties the undo and redo stacks.

$wysiwyg->undo()

Performs a single undo action. Does nothing if there is nothing to undo. Undo actions are user-action based, so if a user made a change that actually made multiple changes to the content, all those changes will be reversed at once.

$wysiwyg->redo()

Performs a single redo action. Does nothing if there is nothing to redo. Undo actions are user-action based, so if a user made a change that actually made multiple changes to the content, all those changes will be reapplied at once.

$textview = $wysiwyg->get_text()

Returns the Gtk2::TextView widget that forms the main body of the WYSIWYG mega-widget. Please be careful with it - making direct modifications may seriously confuse the serialisation/deserialisation methods.

$textbuffer = $wysiwyg->get_buffer()

Returns the Gtk2::TextBuffer widget within the WYSIWYG mega-widget. Toy with this at your peril.

($text, @tags) = $wysiwyg->serialise()

The more efficient of the (currently) two serialisation methods, serialise will return both the raw text and a sequence of tags that when applied to the text will render the original look.

Tags are hashrefs with keys of 'Start' (the index to start applying the tag), 'End' (the index to stop applying the tag) and 'Tags' (a hashref of key value pairs containing the actual tag information). They are ordered by the Start key, and they do NOT overlap (ie, one tag's range is never inside the range of another tag).

Tags include more than just the tags applied by the user - three other tags are also added (and take precedence over user tags) - a 'br' tag (for intra-paragraph newlines), a 'p' tag (to specify interparagraph space) and a 'ws' tag (to tag multiple-character whitespace strings). These are mainly used for conversion to HTML.

$wysiwyg->deserialise($txt, @tags)

The inverse of serialise. Note that this also clears the undo and redo stacks.

$text = $wysiwyg->get_html()

Outputs the contents of the WYSIWYG as HTML. This can also be used as a less efficient but more storable serialisation method as the WYSIWYG can re-parse the output HTML and display it.

Note that the output HTML is incomplete - only the formatting markup is included, but it would be trivial to wrap the appropriate tags around it.

Font sizes are a little tricky, so WYSIWYG converts sizes to em values (assuming size 16 is 1 em).

Remember that as-is tags are not 'html-cleaned' (that's the point - so you can insert HTML tags that WYSIWYG itself doesn't support), so be careful!

$wysiwyg->set_html($text)

The inverse of get_html, this takes HTML text and attempts to parse it back into the WYSIWYG.

While this is primarily designed to take text created with get_html, it can handle being given arbitrary HTML. Any HTML tags it doesn't understand it will insert tagged as 'as-is', so that a later call to get_html should return something very similar to what was given to set_html.

$wysiwyg->debug()

This function is what is called by the special 'debug' button (which appears if you set the debug property to true). By default it simply prints "DEBUG\n" to the screen, but you can override it to do whatever you like.

Two examples are included in the function - the first tests the serialisation by serialising the current text and then deserialising that data back into the WYSIWYG, and the second does the same but for the HTML serialisation.

PROPERTIES

'undo-stack' (Glib::UInt : readable / writable)

The number of items allowed on the undo and redo stacks. A value of zero indicates no limit, which is the default.

'check-spelling' (Glib::Boolean : readable/writable)

If this is turned on (and you have Gtk2::Spell installed), WYSIWYG will attach a Gtk2::Spell instance to its text view.

'flat-toolbar' (Glib::Boolean : readable/writable)

The tool bar can be rendered either as 'fat' (two lines of buttons with named groups) or 'flat' (one line of buttons). If flat-toolbar is set to true the latter will be used, otherwise the former will be. The change will be mirrored in the widget immediately. The default toolbar is the 'fat' version.

'map-fill-to-left' (Glib::Boolean : readable/writable)

Old versions of Gtk2 don't support the fill justification method, and will complain loudly if you try to use it. If you're using such a version, set this property to true to make WYSIWYG use the left justification tag instead.

This won't affect how the WYSIWYG outputs justification data - just how it displays it.

'debug' (Glib::Boolean : readable/writable)

When set to true, this activates the 'debug' button on the toolbar. This button will trigger the WYSIWYG's debug method - you'll probably want to override that to do something useful.

TAGS

There are two classes of tags available in the WYSIWYG - font tags and paragraph tags.

Font Tags

Font tags are applied to arbitrary lengths of text, and only affect those lengths of text.

The following font tags are pre-defined:

font

size

bold

italic

underline

strikethrough

superscript

Cannot be applied to text at the same time as subscript.

subscript

Cannot be applied to text at the same time as superscript.

pre

Preformatted text, like the HTML tag.

asis

A special tag that allows you to enter 'code' that the WYSIWYG would otherwise not be able to understand as formatting. All other font tags are removed from text marked as 'as-is'.

Paragraph Tags

Paragraph tags apply to a whole paragraph, and cannot be applied to only part of a paragraph.

The following paragraph tags are predefined:

h1

Heading 1 - cannot be used in the same paragraph as other Heading tags.

h2

Heading 2 - cannot be used in the same paragraph as other Heading tags.

h3

Heading 3 - cannot be used in the same paragraph as other Heading tags.

h4

Heading 4 - cannot be used in the same paragraph as other Heading tags.

h5

Heading 5 - cannot be used in the same paragraph as other Heading tags.

left

Left justification - cannot be used in the same paragraph as other Justification tags.

center

Center justification - cannot be used in the same paragraph as other Justification tags.

Right justification - cannot be used in the same paragraph as other Justification tags.

fill

Fill justification - cannot be used in the same paragraph as other Justification tags. See the 'map-fill-to-left' property for older versions of Gtk2 that do not support fill justification properly.

indent

The size of the left margin (or the right for right justified paragraphs).

AUTHOR

Matthew Braid, <perl-pkg at mdb.id.au>

TODO

  • Separate the toolbar from the text view

  • Find some way to support bulleted/numbered lists

BUGS

Please report any bugs or feature requests to bug-gtk2-ex-wysiwyg at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Gtk2-Ex-WYSIWYG. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Gtk2::Ex::WYSIWYG

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2010 Matthew Braid.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.