.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ColorEditor 3"
.TH ColorEditor 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Tk::ColorEditor \- a general purpose Tk widget Color Editor
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&   use Tk::ColorEditor;
\&
\&   $cref = $mw\->ColorEditor(\-title => $title, \-cursor => @cursor);
\&
\&   $cref\->Show;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
ColorEditor is implemented as an object with various methods, described
below.  First, create your ColorEditor object during program initialization
(one should be sufficient), and then configure it by specifying a list of Tk
widgets to colorize. When it's time to use the editor, invoke the \fBShow()\fR
method.
.PP
ColorEditor allows some customization: you may alter the color attribute
menu by adding and/or deleting menu items and/or separators, turn the status
window on or off, alter the configurator's list of color widgets, or even
supply your own custom color configurator callback.
.IP 1. 4
Call the constructor to create the editor object, which in turn returns a
blessed reference to the new object:
.Sp
.Vb 1
\&   use Tk::ColorEditor;
\&
\&   $cref = $mw\->ColorEditor(
\&       \-title  => $title,
\&       \-cursor => @cursor,
\&   );
\&
\&      mw     \- a window reference, usually the result of a MainWindow\->new
\&               call.  As the default root of a widget tree, $mw and all
\&               descendant widgets at object\-creation\-time are configured
\&               by the default color configurator procedure.  (You probably
\&               want to change this though or you might end up colorizing
\&               ColorEditor!)
\&      title  \- Toplevel title, default = \*(Aq \*(Aq.
\&      cursor \- a valid Tk \*(Aq\-cursor\*(Aq specification (default is
\&               \*(Aqtop_left_arrow\*(Aq).  This cursor is used over all ColorEditor
\&               "hot spots".
.Ve
.IP 2. 4
Invoke the \fBconfigure()\fR method to change editor characteristics:
.Sp
.Vb 1
\&   $cref\->configure(\-option => value, ..., \-option\-n => value\-n);
\&
\&      options:
\&        \-command             : a callback to a  \`set_colors\*(Aq replacement.
\&        \-widgets             : a reference to a list of widget references
\&                               for the color configurator.
\&        \-display_status      : TRUE IFF display the ColorEditor status
\&                               window when applying colors.
\&        \-add_menu_item       : \*(AqSEP\*(Aq, or a color attribute menu item.
\&        \-delete_menu_item    : \*(AqSEP\*(Aq, a color attribute menu item, or color
\&                               attribute menu ordinal.
\&
\&   For example:
\&
\&      $cref\->configure(\-delete_menu_item   => 3,
\&          \-delete_menu_item   => \*(Aqdisabledforeground\*(Aq,
\&          \-add_menu_item      => \*(AqSEP\*(Aq,
\&          \-add_menu_item      => \*(AqNew color attribute\*(Aq,
\&          \-widgets            => [$ce, $qu, $f2b2],
\&          \-widgets            => [$f2\->Descendants],
\&          \-command            => [\e&my_special_configurator, some, args ]
\&      );
.Ve
.IP 3. 4
Invoke the \fBShow()\fR method on the editor object, say, by a button or menu press:
.Sp
.Vb 1
\&   $cref\->Show;
.Ve
.IP 4. 4
The cget(\-widgets) method returns a reference to a list of widgets that
are colorized by the configurator.  Typically, you add new widgets to
this list and then use it in a subsequent \fBconfigure()\fR call to expand your
color list.
.Sp
.Vb 5
\&   $cref\->configure(
\&       \-widgets => [
\&           @{$Filesystem_ref\->cget(\-widgets)}, @{$cref\->cget(\-widgets)},
\&       ]
\&   );
.Ve
.IP 5. 4
The \fBdelete_widgets()\fR method expects a reference to a list of widgets which are
then removed from the current color list.
.Sp
.Vb 1
\&   $cref\->delete_widgets($OBJTABLE{$objname}\->{\*(Aq\-widgets\*(Aq})
.Ve
.SH AUTHORS
.IX Header "AUTHORS"
Stephen O. Lidie, Lehigh University Computing Center.  95/03/05
lusol@Lehigh.EDU
.PP
Many thanks to Guy Decoux (decoux@moulon.inra.fr) for doing the initial
translation of tcolor.tcl to TkPerl, from which this code has been derived.