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:

The [ See Code ] pages in the widget demo
Documentation viewers such as TkMan
A CPAN module code viewer
Source code viewers for revision control system repositories
WWW markup viewer
XML source code viewer
Configuration settings viewer
A generic document viewer which reconfigures itself based on MIME type

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.

    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

Options available to most widgets, such as -borderwidth and -padx.
Inherited Options

Options specific to text widgets, such as -height and -tabs.
Scrollbar Options

Options specific to TK::ROSyntaxText widgets created with scrollbars.
Widget-specific Options

Options specific to TK::ROSyntaxText.

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}

-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 < 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

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

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.

To install Tk::ROSyntaxText, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Tk::ROSyntaxText

CPAN shell

perl -MCPAN -e shell
install Tk::ROSyntaxText

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

Highlighting

Applications

INTERFACE

Constructors

Tk::ROSyntaxText

Tk::Widget::ScrlROSyntaxText

Options

Standard Options

Inherited Options

Scrollbar Options

Widget-specific Options

The `-shek_*` Options

Methods

insert()

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

AUTHOR

LICENCE AND COPYRIGHT

SEE ALSO

DISCLAIMER OF WARRANTY

NAME

VERSION

SYNOPSIS

DESCRIPTION

Highlighting

Applications

INTERFACE

Constructors

Tk::ROSyntaxText

Tk::Widget::ScrlROSyntaxText

Options

Standard Options

Inherited Options

Scrollbar Options

Widget-specific Options

The -shek_* Options

Methods

insert()

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

AUTHOR

LICENCE AND COPYRIGHT

SEE ALSO

DISCLAIMER OF WARRANTY

Module Install Instructions

The `-shek_*` Options