Tk::ROSyntaxText - Read-only text widget with syntax highlighting
This document describes Tk::ROSyntaxText version 1.001
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);
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.
Tk::ROText
Tk::Text
The syntax parsing is carried out via Syntax::Highlight::Engine::Kate.
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.
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):
-dark_style => 1
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 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
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::ROSyntaxText
my $scrolled_syntax = $parent->ScrlROSyntaxText(%options);
$scrolled_syntax
Newly created Tk::ROSyntaxText widget with scrollbars.
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.
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
-font => [qw{ -family Courier -size 10 -weight normal -slant roman -underline 0 -overstrike 0 }]
-foreground
-foreground => q{#000000}
-highlightbackground
-highlightcolor
-highlightthickness
-padx
-pady
-relief
-selectbackground
-selectborderwidth
-selectforeground
-setgrid
-takefocus
-xscrollcommand
-yscrollcommand
Some inherited options are configured, as indicated below; the remainder retain their default values.
-height
-spacing1
-spacing1 => 1
-spacing2
-spacing2 => 2
-spacing3
-spacing3 => 2
-state
-tabs
-width
-wrap
Normally left as the default but see Scrollbar Options below.
These options only pertain to a Tk::ROSyntaxText widget instantiated as:
my $scrolling_syntax = $parent->ScrlROSyntaxText(%options);
-scrollbars
-scrollbars => q{osoe}
-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.
<
E<lt>
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.
A -custom_config option nested inside another -custom_config option is simply ignored. No warning is emitted.
See Highlighting above for further discussion.
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.
Default: 0
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
Perl
-shek_*
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
$self->insert($text);
$self
An instance of Tk::ROSyntaxText.
$text
The text whose syntax is to be highlighted.
void
IMPORTANT! Tk::ROSyntaxText::insert() overrides Tk::Text::insert()
Tk::ROSyntaxText::insert()
Tk::Text::insert()
Differences to note:
You can't specify an index.
You can't specify a tagList.
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.
insert()
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.
Tk::ROSyntaxText requires no configuration files or environment variables.
Test::More
None reported.
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.
bug-tk-rosyntaxtext@rt.cpan.org
Ken Cotterill <kcott@cpan.org>
<kcott@cpan.org>
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.
Tk::ROText, Tk::Text, Tk::Scrolled, Tk::options
Tk::Scrolled
Tk::options
font
All syntax parsing is performed via this module.
http://www.kate-editor.org/article/writing_a_kate_highlighting_xml_file Note the Available Default Styles section.
http://docs.kde.org/development/en/kdesdk/kate/index.html
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.