NAME

Prima::Markup - Allow markup in Prima Widgets

SYNOPSIS

    use Prima qw(Application Buttons Markup);
    my $markup_button = Prima::Markup::Button->create(...);

DESCRIPTION

Prima::Markup adds the ability to recognize POD-like markup to Prima widgets. Currently supported markup sequences are B (bold text), I (italic text), U (underlined text), E (escape sequences), F (change font), S (change font size), N (change font encoding), and C (change color).

The F sequence is used as follows: F<n|text>, where n is a 0-based index into the fontPalette.

The S sequence is used as follows: S<n|text>, where n is the font size. The font size may optionally be preceded by + or -, in which case it is relative to the current font size.

The N sequence is used as follows: N<n|text>, where n is a 0-based index into the encodings.

The C sequence is used as follows: C<c|text>, where c is a color in any form accepted by Prima, including the cl constants (Black Blue Green Cyan Red Magenta Brown LightGray DarkGray LightBlue LightGreen LightCyan LightRed LightMagenta Yellow White Gray).

The methods text_out and get_text_width are affected by Prima::Markup. text_out will write formatted text to the canvas, and get_text_width will return the width of the formatted text. NOTE: These methods do not save state between calls, so your markup cannot span lines (since each line is drawn or measured with a separate call).

AUTHORS

Teo Sankaro, <teo_sankaro@hotmail.com> minor fixes by Dmitry Karasik, <dmitry@karasik.eu.org>.

WIDGETS

The following widgets are defined:

    Markup::Button
    Markup::Radio
    Markup::CheckBox
    Markup::GroupBox

    Markup::ComboBox

    Markup::DetailedList

    Markup::CheckList

    Markup::Header

    Markup::Label

    Markup::ListBox

    Markup::TabSet
    Markup::TabbedNotebook

    Markup::StringOutline

You need only use Prima::Markup (or use Prima qw(Markup)) to make any markup control available. This is so you don't have to say

 use Prima qw(Application Buttons Label Markup::Button Markup::CheckBox Markup::Label);

but instead can say

 use Prima qw(Application Buttons Label Markup);

(In fact, you don't even have to specify Buttons or Label unless you plan on using a non-markup version before you use a markup version, since the markup version will make sure that the base version is loaded.)

BUGS

Prima::Markup cannot be used when widget draws parts of text string. In particular, Prima::Edit is not convertable to markup scheme. Prima::PodView or Prima::TextView rich text widgets can be used as a partical substitution here.

PROPERTIES

The following new properties are introduced:

$widget->fontPalette([@fontPalette])

Gets or sets the font palette to be used for F sequences within this widget. Each element of the array should be a hashref suitable for setting a font. This method can also accept an arrayref instead of an array. If called in list context, returns an array; if called in scalar context, returns an arrayref.

$widget->encodings([@encodings])

Gets or sets the encodings array to be used within N (and possibly E) sequences within this widget. See the Prima::Application method fonts for information on valid values for encodings. This method can also accept an arrayref instead of an array. If called in list context, returns an array; if called in scalar context, returns an arrayref.

$widget->escapes([%escapes])

Gets or sets the custom escapes hash for a widget. The keys in the hash should be the escape sequences, and the values can be a scalar, a coderef, or an arrayref. If a scalar, the scalar will be inserted into the text. If a coderef, the return value will be inserted into the text (this is useful for inserting the current date and/or time, for example). If an arrayref, the first element is an index into encodings and the second is a position within that encoding (the current font must be valid for the encoding, or the character will not display properly). This method can also accept a hashref instead of a hash. If called in list context, returns a hash; if called in scalar context, returns a hashref.

When an E sequence is encountered, the code first checks the custom escapes hash, then checks the default escapes hash (which was lifted directly from Pod::Text).

Numeric escapes are automatically converted to the appropriate character; no checking of either escapes hash is performed. It accepts either decimal or hexadecimal numbers.

The default escapes are:

    'amp'       =>    '&',      # ampersand
    'lt'        =>    '<',      # left chevron, less-than
    'gt'        =>    '>',      # right chevron, greater-than
    'quot'      =>    '"',      # double quote
                                 
    "Aacute"    =>    "\xC1",   # capital A, acute accent
    "aacute"    =>    "\xE1",   # small a, acute accent
    "Acirc"     =>    "\xC2",   # capital A, circumflex accent
    "acirc"     =>    "\xE2",   # small a, circumflex accent
    "AElig"     =>    "\xC6",   # capital AE diphthong (ligature)
    "aelig"     =>    "\xE6",   # small ae diphthong (ligature)
    "Agrave"    =>    "\xC0",   # capital A, grave accent
    "agrave"    =>    "\xE0",   # small a, grave accent
    "Aring"     =>    "\xC5",   # capital A, ring
    "aring"     =>    "\xE5",   # small a, ring
    "Atilde"    =>    "\xC3",   # capital A, tilde
    "atilde"    =>    "\xE3",   # small a, tilde
    "Auml"      =>    "\xC4",   # capital A, dieresis or umlaut mark
    "auml"      =>    "\xE4",   # small a, dieresis or umlaut mark
    "Ccedil"    =>    "\xC7",   # capital C, cedilla
    "ccedil"    =>    "\xE7",   # small c, cedilla
    "Eacute"    =>    "\xC9",   # capital E, acute accent
    "eacute"    =>    "\xE9",   # small e, acute accent
    "Ecirc"     =>    "\xCA",   # capital E, circumflex accent
    "ecirc"     =>    "\xEA",   # small e, circumflex accent
    "Egrave"    =>    "\xC8",   # capital E, grave accent
    "egrave"    =>    "\xE8",   # small e, grave accent
    "ETH"       =>    "\xD0",   # capital Eth, Icelandic
    "eth"       =>    "\xF0",   # small eth, Icelandic
    "Euml"      =>    "\xCB",   # capital E, dieresis or umlaut mark
    "euml"      =>    "\xEB",   # small e, dieresis or umlaut mark
    "Iacute"    =>    "\xCD",   # capital I, acute accent
    "iacute"    =>    "\xED",   # small i, acute accent
    "Icirc"     =>    "\xCE",   # capital I, circumflex accent
    "icirc"     =>    "\xEE",   # small i, circumflex accent
    "Igrave"    =>    "\xCD",   # capital I, grave accent
    "igrave"    =>    "\xED",   # small i, grave accent
    "Iuml"      =>    "\xCF",   # capital I, dieresis or umlaut mark
    "iuml"      =>    "\xEF",   # small i, dieresis or umlaut mark
    "Ntilde"    =>    "\xD1",   # capital N, tilde
    "ntilde"    =>    "\xF1",   # small n, tilde
    "Oacute"    =>    "\xD3",   # capital O, acute accent
    "oacute"    =>    "\xF3",   # small o, acute accent
    "Ocirc"     =>    "\xD4",   # capital O, circumflex accent
    "ocirc"     =>    "\xF4",   # small o, circumflex accent
    "Ograve"    =>    "\xD2",   # capital O, grave accent
    "ograve"    =>    "\xF2",   # small o, grave accent
    "Oslash"    =>    "\xD8",   # capital O, slash
    "oslash"    =>    "\xF8",   # small o, slash
    "Otilde"    =>    "\xD5",   # capital O, tilde
    "otilde"    =>    "\xF5",   # small o, tilde
    "Ouml"      =>    "\xD6",   # capital O, dieresis or umlaut mark
    "ouml"      =>    "\xF6",   # small o, dieresis or umlaut mark
    "szlig"     =>    "\xDF",   # small sharp s, German (sz ligature)
    "THORN"     =>    "\xDE",   # capital THORN, Icelandic
    "thorn"     =>    "\xFE",   # small thorn, Icelandic
    "Uacute"    =>    "\xDA",   # capital U, acute accent
    "uacute"    =>    "\xFA",   # small u, acute accent
    "Ucirc"     =>    "\xDB",   # capital U, circumflex accent
    "ucirc"     =>    "\xFB",   # small u, circumflex accent
    "Ugrave"    =>    "\xD9",   # capital U, grave accent
    "ugrave"    =>    "\xF9",   # small u, grave accent
    "Uuml"      =>    "\xDC",   # capital U, dieresis or umlaut mark
    "uuml"      =>    "\xFC",   # small u, dieresis or umlaut mark
    "Yacute"    =>    "\xDD",   # capital Y, acute accent
    "yacute"    =>    "\xFD",   # small y, acute accent
    "yuml"      =>    "\xFF",   # small y, dieresis or umlaut mark
                                  
    "lchevron"  =>    "\xAB",   # left chevron (double less than) laquo
    "rchevron"  =>    "\xBB",   # right chevron (double greater than) raquo

    "iexcl"  =>   "\xA1",   # inverted exclamation mark
    "cent"   =>   "\xA2",   # cent sign
    "pound"  =>   "\xA3",   # (UK) pound sign
    "curren" =>   "\xA4",   # currency sign
    "yen"    =>   "\xA5",   # yen sign
    "brvbar" =>   "\xA6",   # broken vertical bar
    "sect"   =>   "\xA7",   # section sign
    "uml"    =>   "\xA8",   # diaresis
    "copy"   =>   "\xA9",   # Copyright symbol
    "ordf"   =>   "\xAA",   # feminine ordinal indicator
    "laquo"  =>   "\xAB",   # left pointing double angle quotation mark
    "not"    =>   "\xAC",   # not sign
    "shy"    =>   "\xAD",   # soft hyphen
    "reg"    =>   "\xAE",   # registered trademark
    "macr"   =>   "\xAF",   # macron, overline
    "deg"    =>   "\xB0",   # degree sign
    "plusmn" =>   "\xB1",   # plus-minus sign
    "sup2"   =>   "\xB2",   # superscript 2
    "sup3"   =>   "\xB3",   # superscript 3
    "acute"  =>   "\xB4",   # acute accent
    "micro"  =>   "\xB5",   # micro sign
    "para"   =>   "\xB6",   # pilcrow sign = paragraph sign
    "middot" =>   "\xB7",   # middle dot = Georgian comma
    "cedil"  =>   "\xB8",   # cedilla
    "sup1"   =>   "\xB9",   # superscript 1
    "ordm"   =>   "\xBA",   # masculine ordinal indicator
    "raquo"  =>   "\xBB",   # right pointing double angle quotation mark
    "frac14" =>   "\xBC",   # vulgar fraction one quarter
    "frac12" =>   "\xBD",   # vulgar fraction one half
    "frac34" =>   "\xBE",   # vulgar fraction three quarters
    "iquest" =>   "\xBF",   # inverted question mark
    "times"  =>   "\xD7",   # multiplication sign
    "divide" =>   "\xF7",   # division sign

METHODS

subclass $new_class, $ancestor, %options

Creates $new_class package derived from $ancestor and Prima::Markup, defining profile_default and init methods so all intrinsic markup properies are correctly initialized and text_out/get_text_width method overloaded. Recognized %options keys:

module

If present, $new_class overloads create method so $module is loaded prior $new_class creation. This is useful for letting Markup:: class to decite which module it needs instead of pressing the programmer explicitly load the underlying packages.

profile_default

Includes string of code, to be put in profile_default class method. Useful when minor properties adjustment are needed.

init

Includes string of code, to be put in profile_default class method. Useful when new properties are defined.

COPYRIGHT

Copyright 2003 Teo Sankaro

Portions of this code were copied or adapted from Pod::Text by Russ Allbery and Pod::Parser by Brad Appleton, both of which derive from the original Pod::Text by Tom Christianson.

You may redistribute and/or modify this module under the same terms as Perl itself. (Although a credit would be nice.)

AUTHOR

Teo Sankaro, <teo_sankaro@hotmail.com>.

cpanm Prima

perl -MCPAN -e shell
install Prima