NAME

Tk::contrib - how to find/contribute perl/Tk code

DESCRIPTION

Here are some guidelines you can use to find a peace of code is already available and how to contribute your code.

If you have perl/Tk code that can be reused or used as an example or starting point please check if one could find it using the method in the next section. If it's not findable think about to contribute your work (described later).

What's already avaiable?

If you are seriously planning to write the beast you are looking for when it does not exists you can take the short route and ask the ptk list <ptk@lists.stanford.edu>. Make sure to mention Tk::contrib to prevent RTFM replies. Otherwise try the checklist below first:

o http://www.perl.com/ptk/ or Grahams perl/Tk home page ??
o tk-modules-list
o tcl/tk faq 4&5
o http://www.perl.com/CPAN/modules/by-modules/Tk
	                        /scripts/??????
o Archive http://www.xray.mpe.mpg.de/mailing-lists/ptk/

How to contribute code?

Have spend a lot time of on a specific topic and it was not at the end and RFTM? Yes? Please least take the time to post your solution to the perl/Tk mailing list ptk@lists.stanford.edu. So other can find it later in the list archive http://www.xray.mpe.mpg.de/mailing-lists/ptk/ If it's a common problem this may be even enough to enhance/extend the perl/Tk FAQ

But wait there is more you can do without much afford:

?? scripts. What's the status of CPAN/scripts ??

Perl/Tk Module List

is a central reference of modules and scripts

http://www.connect.net/gbarr/PerlTk/tk-modlist.html

Send a mail to <ptk@lists.standford.edu> and Graham Barr <gbarr@pobox.com> that describes your contribution.

It's enough if would send your contribution on an e-mail request. But there more ...

CPAN account

Simply send mail to ptk o handling of modules (widget) and scripts (applications) o send code to ptk for comments (widget name!, etc.) o Tk-modules list: register early (even if alpha) o CPAN account. Refer to docs how to do it o Tk-Contrib ask for addition on ptk (also happy users of an widget for). Use convenience method before stuff gets lost. o Still to complicated? :-( Then post at least your code to ptk@lists.stanford.edu. So other could find it later in the list archive http://www.xray.mpe.mpg.de/mailing-lists/ptk/

$widget->Busy

Turn the pointer into a 'watch' for $widget and all decendants. Beeps on key events for all these widgets. (Eh? Beeps on mouse clicks for all widgets in the Toplevel Eh?)

Note: Does only with descendants that have a undefined -cursor value. E.g., Entry and Text widgets don't work with Busy by default. A simple work around it to set -cursor=>undef.

$widget->Unbusy

Undo last Busy.

Balloon.pod ===========

-statusbar: Label + -text has the disadvantage
	Label may resize for messages that are too
	long.   Entry + -textvariable has not the problem
	but it's editable. -> ROEntry ???

configspec.pod ============== o IMO use 'fallback' instead of 'default' because the default a widget uses is taken from the resource database and if there's nothing it fallbacks to the value specified in ConfigSpecs.

o one should now be able to use $self instead of 'SELF' but I've not
  verified it so this is more a reminder for my pod/TODO file :-)

STANDARD OPTIONS ================

o -width listed in Listbox but not in options.pod

There a need for a check what options are listed in STD OPTIONS section and what's really in options.pod (maybe same what in options but also listed in widget specific WIDGET OPTIONS

getOpenFile: ============

o perlize filePattern when it's clear what it should be (It's not clear if Tcl/Tk scheme will be adopted

discrepancies with docs (on Unix):

o One does not get a dialog when the file does not exists and path is not absolute as stated in the docs

ptksh> p $mw->getOpenFile ./bla|

o Centers itself always over the parent widget. Even if parent is small and e.g. in the upper left corner So a lot of the Dialog is outside the of the screen. E.g. create a main window and

ptksh> $mw->geometry('+0+0') ptksh> $mw->getOpenFile

o -filetypes option not supported (could be PASSIVE for now).

ptksh> p $mw->getOpenFile(-filetypes=>'*.pod') Can't set -filetypes to `*.pod' for Tk::FileSelect=HASH(0x1402bbb08): Can't set -filetypes to `*.pod' for Tk::Frame=HASH(0x14061cc78): Bad option `-filetypes' at /home/ach/perl/5.004_64/site+standard/Tk/Derived.pm line 290.

o defaultextention docs not work:

ptksh> p $mw->getOpenFile(-defaultextension=>'pod') ./bla| ptksh> p $mw->getOpenFile(-defaultextension=>'.pod') ./bla|

o if one currently gives a filepattern '.pod' the filter displays './*..pod' so one should use 'pod'. On the other hand SPECIFING FILE PATTERS suggest to use .pod.

Misc. comments:

o It would be useful if the 'File' entry would get the focus on startup So one can start typing without selecting the entry (with click to focus policy

o If one clicks on a filename. This is interpreted as the 'accept' and Dialog disapprear. While confirm with tcl/tk it makes me nervous. I prefer a double click

o Still much functionality not implemented

HList (and some BUGS) ===========

1) headerSize still returns tclish string. (As documented but this should change) 2) headerSize err msg for non existant col contains garbage IMO

ptksh> $h->entryconfigure('one.two', -text=>'bar') ptksh> $h->headerCreate(0, -text=>'heading') ptksh> $h->configure(-header=>1) ptksh> p $h->headerSize(0) 74 22| ptksh> p $h->headerSize(1) Column "KC@" does not exist at /home/ach/perl/5.004_64/site+standard/Tk/Submethods.pm line 19.

3) Not all Submethods are defined and documented. E.g.

ptksh> p $h->infoSelection Goto undefined subroutine &Tk::HList::infoSelection at /home/ach/perl/5.004_64/site+standard/Tk/Widget.pm line 305.

ptksh> p $h->info('selection') one| one.two|

Wm.pod (BUG?) ======

Eh? What's that?

ptksh> print "okay\n\n" if defined($mw->wm('aspect') ) ptksh> print "okay\n\n" if ("" eq $mw->wm('aspect') ) okay

ptksh> p scalar( $mw->wm('aspect') ) |

Image stuff: ============

o ?? Extract standard constructor options like -file, -data into
  Tk::Image/"STANDARD OPTIONS"
o same for common method, e.g., type() 
o Use $image or $bitmap, $photo, $pixmap (like $widget and $text, ...)

o DefineBitmap shares names between mainwindows and croak on dubl. names
  (See e.g., Tk::Numentry)

Dunnigan,Jack [Edm] wrote: > > How does one ingest a bitmap into an icon for a perl/Tk application? > > The reference guide has: > > $main->iconbitmap(?bitmap?); > > but I'm unsure as to what form (?bitmap?) should be written? > My full path name to the file is: /users/im/perlscripts/image/pirep.bmp > > Can someone show me the proper format?

You need an X11 bitmap (typical "externsion" is .xbm):

$icbm = $w->iconbitmap('@path_to_bitmap');

The '@' differentiates a pathname from an builtin bitmap name.

Photo.pod =========

o check and perlize RHS lists of =>

o Photo configure resName, resClass are undefined so
  optiondb is not used.  Intention? If yes this should
  be mentioned in POD.

options.pod ===========

o add note about undef name class prevents optiondb lookup

SYNTAX: =======

  o , and ? are not correct
	(?I<switches>,? I<pattern, index, >?I<stopIndex>?)
    should be IMO
	(?I<switches>,? I<pattern, index>?, I<stopIndex>?)
    But first ,? is correct second isn't.   !!!!	

  o Inconsistency in submethod describtion some one methSub, I've
    added some meth('sub'.. and methSub, other use only methSub
    

MARKUP: ====== still lot of $widget instead of $widget Maybe still some buggy window->$widget from autoconvertion

LINKS: ====== Tk_GetPixels --> Tk_GetPixels Tk_GetBoolean --> Tk_GetBoolean Tk_GetBool.* not found in pTk pods

.... check for other, general case B<Tk_.*> ??

POD Conflict: ============= pod/Font.pod Tk/Font.pm (I assume pod/Font sould be pod/font.pm (my guess first char case script got it wrong) but having Font and font is same mess as grid and Grid before.

STILL TCLISH: ============= getOpenFile messageBox ?...?

Canvas.pod ==========

o bind method: + to append a binding is not available in perl. Somewhere (bind.pod?) should be a blurb how to do it. Or provide a AddBind method.

o Mhmm, ->bind without callback returns an error when no callback is defined bind return undef, blech! (check if really the case)

o Tcl continue -> return from callback or is there more magic. Check it!

o Find Nick's mail that one can't prevent from item callback that canvas callback get invoked.

o No docs for update method in Widget or After. update (check also other pod so insert the link)

o No CanvasLower CanvasRaise methods. ??? Is there a Raise Lower method that always works on the widget?

Pixmap.pod ========== o -id not documented

tk8 font: =========

o I've added L<Tk::Font> to Widget.pod. May be wrong. Deps. on final
  name and now tools prefers of name.pod or name.pm

o L<scaling|Tk::Widget/scaling>  but /scaling will not work I guess
  push A<show this|anchorname> support on top of TODO list :-)

o Add link to Grahams Tk::Font where X11 XFLD  are mentioned. Currently
  Font.pm and Font.pod collide

tkerror : =========

o *** Add stuff Nick explained on ptk when 'ideal error msg' thread finds an end *** Old questions of mine:

o Is it save to document that first arg of Tk::Error is a $mainwindow? E.g., $label->Error('shit') works (a widget is-a tk). So should it be Tk::MainWindow::Error to disable $label->Error?

o $w->BackTrace not mentioned/explained. Should it be mentioned? Has someone a BackTrace describtion at hand? :-)

o what to do with 'command Tk::Error'? Use 'method Tk::Error'? (Hmm Tk.pm provides default Tk::Error so $w->Tk::Error(...) is effectively always the same as Tk::Error($w,...) So it would IMO make more sense to write 'Tk::Error subroutine' or use 'Error method'.

o IMO require Tk::ErrorDialog should only be used in perl script and *not* in modules. I would consider it bad style when a script 'overrides' global error handling (that may occur delayed due to 'require only when need' of such a module.

o I've also have a need for a special Tk::Error function. How to get *all* die, warn (even before MainLoop is reached) return a complete stack trace. If this is not easy to achieve (as I think I found out :-( ) should tkerror include a suggestion to 'use Carp' in Tk:: modules to help debugging?

Geometry manager: =================

o Describe their behaviour if a toplevel widget gets resized so
  available space is smaller than the requested x/y of the
  widgets.

o use same style SYNOPSIS and KEYWORDS' section

o gridSize  $master not managed by grid return (0,0) not
	documented (intentional)?
o Form:
	o check/verify/understand I<anchor_point> syntax:
	  	'%$a'  could only work with dyn. var. not lex.
		\$a  man->pod error?
	o make undocumented/partial impl. 'spring' invisible
	  and a add TODO ???
	o add a intro I<-side>, I<-side>B<spring>, -pad<side> so one
	  faster sees what's going on 
	o check TRUE FALSE return of formCheck
	o try formGrid.  the description seem wrong. Missing 'not'?
	o check form(-top... -left...) != form(-left...-top...)
	o ABREVIATIONS "-0", versus -0  wasn't there something about
	  that on p5p?

o grid mention raise lower to change stacking order.  Works for non
  toplevel too.   Try it.  (add links for raise lower)

o Add a ptkmgr.pod  explaining common stuff (e.g., possible
  $master's, command 'submethods' mgr, mgrForget, mgrInfo)
  mention manager (wm for toplevels: are there similar wmForget
  etc. methods, seams useful).   *Propagate,
  Raise Lower explanations.   $master <=> widgettree correlation

composite:

o note that ..$opt=delete $args->{-opt}.. handles const.
  only options is confusing. a) There would not be a
  'readonly' option as for -class, visual, ... 
  Using CreateArgs does not work for composites, cries
  for a support method  (where=READONLY in configspec?)
o Add skeleton of a Frame based composite?

callbacks:

o IMO remove BUGs section closure are not 'the' solution
  especially they are not (?) useable in ClassInit
o add some more 'normal' callback examples.
o 'pronouce' that the actual arguments list passed to a
   callback may differ. 
o Then concentate 'special' handling of a bind callback in
  it's own section.
o Describe how emulate bind in your callback handling
o Ev() example/explanations better moved to Tk::bind ?
o BUGS entry?: Missing is a -callback switch that treats
  callbacks as bind does automaticly

configspec:

	o SETMETHOD, GETMETHOD undocumented (check Derived.pm
          for more)

Configure:

o detail about composite widgets are distributed in the
  docs. Bundle them into a separate section. First discribe
  general interface then go into details about composite:

o Add section with details about Tk::Configure->new

DItem: o pod markup of ITEM OPTIONS and STYLE OPTIONS is wrong but fix would conflict with pending Config:,Name:,Class change

o all STANARD OPTIONS still use res. name not option name

o remove C<>

Text:

o Intentional(?): o Tag and Tags not documented (doc for Text::Tag?) o TIE interface undocumented

o Go through EMB IMAGE and image method stuff

o textBind describtion still tclish. See also same item in Canvas.pod below o dump method output already perlish??

o windowCreate -create requires pathname as return value (as documented) but should also accepts

Fix Text.pod when $w is also okay.

o windowNames return path of emb. widgets. So IMO there's a windowObjects|Refs missing returning the ref to the widgets (windowSlaves like in packSlaves, gridSlaves ??)

o Missing (intentional?) Tk::submethods

	x|yview => [ qw(moveto scroll) ]

  a specialcase for  x|yviewPickplace ??????????

o sub Tag; and sub Tags; predeclared. Isn't this be done by autosplit.ix and AutoLoader ?

o search and regexp, check if perl or tcl regexp are used and document it.

TList: ======

o Click on 'one' in example at the end does not make it 'one' the 'active item

__END__