Ken Cotterill > Tk-ROSyntaxText-1.001 > Tk::ROSyntaxText

Download:
Tk-ROSyntaxText-1.001.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.001   Source  

NAME ^

Tk::ROSyntaxText - Read-only text widget with syntax highlighting

VERSION ^

This document describes Tk::ROSyntaxText version 1.001

SYNOPSIS ^

    use Tk;
    use Tk::ROSyntaxText;
    
    my $syntax = $parent->ROSyntaxText(%options);
    
    $syntax->pack();
    
    $syntax->insert($text);
    
    # For scrollbars to be automatically added (when required)
    
    my $scrolling_syntax = $parent->ScrlROSyntaxText(%options);

DESCRIPTION ^

Tk::ROSyntaxText is a read-only text widget that applies syntax highlighting to its data.

Tk::ROSyntaxText inherits from Tk::ROText which, in turn, inherits from Tk::Text.

The syntax parsing is carried out via Syntax::Highlight::Engine::Kate.

Highlighting is achieved through Tk::Text options to change colours, embolden text and so on. See the section on Highlighting below for a further discussion.

There are many applications where this widget would be useful: a subset is listed in the Applications section below.

Highlighting

If a Tk::ROSyntaxText widget is created without any options, it will have the default syntax hightlighting used by Syntax::Highlight::Engine::Kate but without any italicised or emboldened text.

    my $syntax = $parent->ROSyntaxText();

This is a white background with variables, keywords, comments, etc. presented in a variety of colours.

For those who prefer a dark background, set the -dark_style option to a TRUE value:

    my $syntax = $parent->ROSyntaxText(-dark_style => 1);

This is a black background with the syntax elements in a variety of colours tailored to the darker background.

Finer control over the colours requires additional options (see Options below). In general, if only one or two default options are to be altered, it's probably easiest to use these directly when the widget is created:

    my $syntax = $parent->ROSyntaxText(-opt1 => val1, -opt2 => val2);

For a large number of changes, or when multiple widgets are to be used, or if a completely customised look-and-feel is required, the -custom_config option may prove to be more useful:

    my %options = (
        -option1 => value1,
        ...
        -optionN => valueN
    );
    
    my $syntax = $parent->ROSyntaxText(-custom_config => \%options);

NOTE: You may include any options that appear in the Options section in the -custom_config option list. However, two options are handled specially: see -custom_config under Widget-specific Options for details.

IMPORTANT: To tweak the -dark_style configuration, when the -dark_style option has been used explicitly, the -custom_config option must be used:

    my $syntax = $parent->ROSyntaxText(-dark_style => 1,
                                       -custom_config => \%options);

An easier way of handling this is to add -dark_style => 1 to the -custom_config option list (the position in the list is immaterial):

    my %options = (
        -option1    => value1,
        ...
        -dark_style => 1,
        ...
        -optionN    => valueN
    );
    
    my $syntax = $parent->ROSyntaxText(-custom_config => \%options);

In addition to colour, other aspects of the presentation may be changed via the -font option. This may be done globally, e.g.

    -font => [qw{-family Times -size 12 -weight bold -slant italic}]

or for a specific syntax type, e.g.

    -shek_Comment => [
        -background => q{#0000ff},
        -foreground => q{#c0c0c0},
        -font => [ -slant => 'italic' ],
    ]

The defaults (for Tk::ROSyntaxText) are:

    Font:       Courier
    Size:       10
    Weight:     normal (i.e. not bold)
    Slant:      roman (i.e. upright, not italic)
    Underline:  NO
    Overstrike: NO

Applications

Applications for Tk::ROSyntaxText might include:

INTERFACE ^

Constructors

Tk::ROSyntaxText

    my $syntax = $parent->ROSyntaxText(%options);
$parent

Parent widget, e.g. Frame, Main window, etc.

%options

Instantiation options - see Options below.

$syntax

Newly created Tk::ROSyntaxText widget.

Tk::Widget::ScrlROSyntaxText

    my $scrolled_syntax = $parent->ScrlROSyntaxText(%options);
$parent

Parent widget, e.g. Frame, Main window, etc.

%options

Instantiation options - see Options below.

$scrolled_syntax

Newly created Tk::ROSyntaxText widget with scrollbars.

Options

Available options are broken up into four categories:

Standard Options

Some standard options are configured, as indicated below; the remainder retain their default values.

-background

Configured by Tk::ROSyntaxText. Starting value:

    -background => q{#ffffff}
-borderwidth
-cursor
-exportselection
-font

Configured by Tk::ROSyntaxText. Starting value:

    -font => [qw{
        -family     Courier
        -size       10
        -weight     normal
        -slant      roman
        -underline  0
        -overstrike 0
    }]
-foreground

Configured by Tk::ROSyntaxText. Starting value:

    -foreground => q{#000000}
-highlightbackground
-highlightcolor
-highlightthickness
-padx
-pady
-relief
-selectbackground
-selectborderwidth
-selectforeground
-setgrid
-takefocus
-xscrollcommand
-yscrollcommand

Inherited Options

Some inherited options are configured, as indicated below; the remainder retain their default values.

-height
-spacing1

Configured by Tk::ROSyntaxText. Starting value:

    -spacing1 => 1
-spacing2

Configured by Tk::ROSyntaxText. Starting value:

    -spacing2 => 2
-spacing3

Configured by Tk::ROSyntaxText. Starting value:

    -spacing3 => 2
-state
-tabs
-width
-wrap

Normally left as the default but see Scrollbar Options below.

Scrollbar Options

These options only pertain to a Tk::ROSyntaxText widget instantiated as:

    my $scrolling_syntax = $parent->ScrlROSyntaxText(%options);
-scrollbars

Configured by Tk::ROSyntaxText. Starting value:

    -scrollbars => q{osoe}
-wrap

Configured by Tk::ROSyntaxText. Starting value:

    -wrap => q{none}

Widget-specific Options

-char_subs

This option provides a mapping of characters to substitute text. It is typically used for characters that need to be escaped to prevent interpretation by the output medium.

An example is the less-than sign (<) which would be converted to &lt; before being output to HTML; and to E<lt> before being output to POD.

As a point of interest, you can map characters outside of the set normally referred to as printable characters. For instance, you can map tabs:

    -char_subs => { "\t" => 'TAB' }

You can map newlines and carriage returns:

    -char_subs => { "\n" => 'NL', "\r" => 'CR' }

although that will almost certainly mess up the overall layout of the text.

Default: {}

-custom_config

This option takes a hashref of option/value pairs. Any options listed in the Options section may be used; however, two options are handled specially:

  • -dark_style

    A -dark_style option that is included in the -custom_config hashref will override any other -dark_style option (whether the implicit FALSE default value or an explicit TRUE or FALSE value). No warning is emitted.

  • -custom_config

    A -custom_config option nested inside another -custom_config option is simply ignored. No warning is emitted.

See Highlighting above for further discussion.

Default: {}

-dark_style

This is a boolean option. When set to a TRUE value, the background is changed to black and the foreground colours of the syntax elements are tailored to this darker background.

See Highlighting above for further discussion.

Default: 0

-syntax_lang

This is the language whose syntax you are highlighting. It might be a programming language, a markup language or something else with a formal syntax. Syntax::Highlight::Engine::Kate has Plugins for over 100 languages.

Default: Perl

The -shek_* Options

All syntax parsing is carried out via Syntax::Highlight::Engine::Kate (whose initials are SHEK: hence the -shek_ prefix).

The part after this prefix matches one of the syntax types identified by Syntax::Highlight::Engine::Kate, e.g. Comment, Keyword, String, etc.

The value of each option is an arrayref of key/value pairs.

Each key/value pair affects how its associated text type is highlighted.

For instance, to make the syntax type Error appear as yellow text on a red background:

    -shek_Error => [
        -background => q{#ff0000},
        -foreground => q{#ffff00},
    ]

To make this stand out even more with emboldened text:

    -shek_Error => [
        -background => q{#ff0000},
        -foreground => q{#ffff00},
        -font => [qw{-weight bold}]
    ]

As a further example, say you wanted comments in the Times font with italicised silver text on a blue background:

    -shek_Comment => [
        -background => q{#0000ff},
        -foreground => q{#c0c0c0},
        -font => [qw{-family Times -slant italic}]
    ]

Here's the list of -shek_* options:

-shek_Alert
-shek_BaseN
-shek_BString
-shek_Char
-shek_Comment
-shek_DataType
-shek_DecVal
-shek_Error
-shek_Float
-shek_Function
-shek_IString
-shek_Keyword
-shek_Normal
-shek_Operator
-shek_Others
-shek_RegionMarker
-shek_Reserved
-shek_String
-shek_Variable
-shek_Warning

Methods

insert()

    $self->insert($text);
$self

An instance of Tk::ROSyntaxText.

$text

The text whose syntax is to be highlighted.

Context: void

IMPORTANT! Tk::ROSyntaxText::insert() overrides Tk::Text::insert()

Differences to note:

No insertion point

You can't specify an index.

No tags

You can't specify a tagList.

No list

You can't specify a list of text items.

Each invocation of insert() causes all text currently in the widget to be deleted. The text indicated in insert()'s argument is then displayed (in the now empty widget) with its syntax highlighted.

DIAGNOSTICS ^

Unknown type (%s) encountered for text (%s). Using default.

Syntax::Highlight::Engine::Kate flags portions of text according to type: String, Comment and so on. In this instance, an unknown type was encountered. The text has still been displayed, but without any highlighting. The most likely cause would be some change in Syntax::Highlight::Engine::Kate. Please report this bug - see BUGS AND LIMITATIONS below for details of how to do this - thankyou.

CONFIGURATION AND ENVIRONMENT ^

Tk::ROSyntaxText requires no configuration files or environment variables.

DEPENDENCIES ^

Syntax::Highlight::Engine::Kate 0.06
Test::More 0.94

INCOMPATIBILITIES ^

None reported.

BUGS AND LIMITATIONS ^

No bugs have been reported.

Please report any bugs to bug-tk-rosyntaxtext@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR ^

Ken Cotterill <kcott@cpan.org>

LICENCE AND COPYRIGHT ^

Copyright (c) 2010, Ken Cotterill <kcott@cpan.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

SEE ALSO ^

Related Tk modules

Tk::ROText, Tk::Text, Tk::Scrolled, Tk::options

Tk POD documentation for fonts

font

Syntax::Highlight::Engine::Kate

All syntax parsing is performed via this module.

Article: Writing a Kate Highlighting XML File

http://www.kate-editor.org/article/writing_a_kate_highlighting_xml_file Note the Available Default Styles section.

The Kate Handbook

http://docs.kde.org/development/en/kdesdk/kate/index.html

DISCLAIMER OF WARRANTY ^

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

syntax highlighting: