dgw::sfinddialog

Detlef Groth, Schwielowsee, Germany

2020-01-04

NAME

dgw::sfinddialog - snit toplevel dialog for text search in other widgets. A implementation to search a text widget inbuild.

Table of Contents

SYNOPSIS

package require dgw::sfinddialog
namespace import ::dgw::sfinddialog
sfinddialog pathName options
pathName configure -findcmd script
pathName configure -findnextcmd script
pathName configure -textvariable varname
pathName configure -nocase boolean
pathName configure -word boolean
pathName configure -regexp boolean
pathName configure -title string
pathName cancel cmd options
pathName entry cmd options
pathName find cmd options
pathName next cmd options

DESCRIPTION

sfinddialog - is a toplevel search dialog to perform a text search in other widgets. As such functionalitye is mostly required for the Tk text widget, a implementation to search a Tk text widget is embedded within the sfinddialog widget. The buttons and the text entry are exposed to the programmer, so the programmer has for instance the possibility to manually insert a value in the search entry or to click a button programmatically.

COMMAND

sfinddialog pathName ?options?

Creates and configures the sfinddialog toplevel widget using the Tk window id pathName and the given options.

WIDGET OPTIONS

-findcmd script

Set a command if the user clicks on the find button. Please note, that if you would like to add search functionality to a Tk text widget, just use the -textwidget option described below.

-findnext script

Set a command if the clicks on the next button. Please note, that if you would like to add search functionality to a Tk text widget, just use the -textwidget option described below.

    global textvar
    testing mFind
    proc Next {} {
       global textvar
       wm title .s "Next $textvar words: [.s cget -word]"
       puts "Next $textvar words: [.s cget -word]"
    }
    proc Find {} {
       global textvar
       wm title .s "Find $textvar words: [.s cget -word]"
       puts "Find $textvar words: [.s cget -word]"
    }
    set textvar test
    dgw::sfinddialog .s -nocase 1 -findnextcmd Next -findcmd Find -textvariable textvar
    wm title .s "Search "

-forward boolean

Checkbox configuration to indicate the search direction. This value can be modified by the user later by clicking the checkbutton belonging to this option.

-nocase boolean

Sets the default value for the checkbox related to case insensitive search. This value can be modified by the user later by clicking the checkbutton belonging to this option.

-regexp boolean

Checkbox configuration to indicate if the search string should be used as regular expression. This value can be modified by the user later by clicking the checkbutton.

-textvariable varname

Configures the entry text to be synced with the variable varname.

-textwidget pathname

The existing textwidget will get functionality to be searched by the sfinddialog. Here is an example on how to use it for a text widget:

     pack [text .text]
     dgw::sfinddialog .st -nocase 0 -textwidget .text -title "Search"
     .text insert end "Hello\n"
     .text insert end "Hello World!\n"
     .text insert end "Hello Search Dialog!\n"
     .text insert end "End\n"
     .text insert end "How are your?\n"
     .text insert end "I am not prepared :(\n"
   
     bind .text <Control-f> {wm deiconify .st}

-title string

Sets the title of the sfinddialog toplevel.

-word boolean

Checkbox configuration to indicate that the search should be performed on complete words. This value can be modified by the user later by clicking the checkbutton belonging to this option. Please note that this works currently only together with regular expressions, even if the option is not set in the dialog.

WIDGET COMMANDS

Each sfinddialog toplevel supports the following widget commands.

pathName cancel cmd ?option ...?

This function provides access for the programmer to the cancel button. For instance to close the dialog it is possible to use: pathName cancel invoke. See the button manual page for other commands.

pathName cget option

Returns the given sfinddialog configuration value for the option.

pathName configure option value ?option value?

Configures the sfinddialog toplevel with the given options.

pathName entry cmd ?option ...?

This function provides access for the programmer to the embedded entry widget. For instance to get the current text you could use: pathName entry get. See the entry manual page for other commands available for the entry widget.

pathName find cmd ?option ...?

This function provides access for the programmer to the find button. For instance to execute the search it is possible to use: pathName find invoke. See the button manual page for other commands.

pathName findnext cmd ?option ...?

This function provides access for the programmer to the findnext button. For instance to execute the next search it is possible to use: pathName findnext invoke. See the button manual page for other commands.

EXAMPLE

proc Test_Find {} {
   global textvar
   # testing mFind
   proc Next {} {
       global textvar
       wm title .s "Next $textvar words: [.s cget -word]"
       puts "Next $textvar words: [.s cget -word]"
   }
   proc Find {} {
       global textvar
       wm title .s "Find $textvar words: [.s cget -word]"
      puts "Find $textvar words: [.s cget -word]"
   }
   
   set textvar test
   dgw::sfinddialog .s -nocase 1 -findnextcmd Next -findcmd Find -textvariable textvar
   wm title .s "Search "
  
   .s find configure -bg red
   set btn [.s find]
   $btn configure -bg blue
   bind .s <Control-f> {wm deiconify .s}
   pack [button .btn -text "Open find dialog again ..." -command {wm deiconify .s}]
   pack [text .text]
   dgw::sfinddialog .st -nocase 0 -textwidget .text -title "Search"
   .text insert end "Hello\n"
   .text insert end "Hello World!\n"
   .text insert end "Hello Search Dialog!\n"
   .text insert end "End\n"
   .text insert end "How are your?\n"
   .text insert end "I am not prepared :(\n"
   
   bind .text <Control-f> {wm deiconify .st}
}
Test_Find

INSTALLATION

Installation is easy you can install and use the dgw::sfinddialog package if you have a working install of:

If you have the snit Tcl packages installed, you can either use the sfinddialog package by sourcing it with: source /path/to/sfinddialog.tcl, by copying the folder dgw to a path belonging to your Tcl $auto_path variable or by installing it as a Tcl module. To do the latter, make a copy of sfinddialog.tcl to a file like sfinddialog-0.4.tm and put this file into a folder named dgw where the parent folder belongs to your module path. You must eventually adapt your Tcl-module path by using in your Tcl code the command: tcl::tm::path add /parent/dir/ of the dgw directory. For details of the latter, consult the manual page of tcl::tm.

Alternatively there is an --install option you can use as well. Try: tclsh sfinddialog.tcl --install which should perform the procedure described above automatically. This requires eventually the setting of an environment variables like if you have no write access to all your module paths. For instance on my computer I have the following entry in my .bashrc

export TCL8_6_TM_PATH=/home/groth/.local/lib/tcl8.6

If I execute tclsh sfinddialog.tcl --install the file sfinddialog.tcl will be copied to
/home/groth/.local/lib/tcl8.6/dgw/sfinddialog-0.1.tm and is thereafter available for a
package require dgw::sfinddialog.

DEMO

Example code for this package can be executed by running this file using the following command line:

$ wish sfinddialog.tcl --demo

The example code used for this demo can be seen in the terminal by using the following command line:

$ wish sfinddialog.tcl --code

DOCUMENTATION

The script contains embedded the documentation in Markdown format. To extract the documentation you should use the following command line:

$ tclsh sfinddialog.tcl --markdown

This will extract the embedded manual pages in standard Markdown format. You can as well use this markdown output directly to create html pages for the documentation by using the --html flag.

$ tclsh sfinddialog.tcl --html

This will directly create a HTML page sfinddialog.html which contains the formatted documentation. Github-Markdown can be extracted by using the --man switch:

$ tclsh sfinddialog.tcl --man

The output of this command can be used to feed a markdown processor for conversion into a man page, a html or a pdf document. If you have pandoc installed for instance, you could execute the following commands:

# man page
tclsh sfinddialog.tcl --man | pandoc -s -f markdown -t man - > sfinddialog.n
# html page
tclsh ../sfinddialog.tcl --man > sfinddialog.md
pandoc -i sfinddialog.md -s -o sfinddialog.html
# pdf
pandoc -i sfinddialog.md -s -o sfinddialog.tex
pdflatex sfinddialog.tex

SEE ALSO

TODO

AUTHOR

The sfinddialog widget was written by Detlef Groth, Schwielowsee, Germany.

COPYRIGHT

Copyright (c) 2019 Dr. Detlef Groth, E-mail: detlef(at)dgroth(dot)de

LICENSE

Text search dialog widget dgw::sfinddialog, version 0.4.

Copyright (c) 2019 Dr. Detlef Groth, E-mail: detlef(at)dgroth(dot)de

This library is free software; you can use, modify, and redistribute it for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions.

This software is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.