FE 'tkGooie' Utilities

'TEXTtools' group

The FE 'xpg' text-file
browse-search utility

(with the 'SAM' =
'Show All
Match-lines'
capability)

(FE = Freedom Environment)

The 'xpg' utility showing the
'shofil.tk' Tk script that is
the main script of the 'xpg'
text file browse / search /
extract-lines utility.

Large, hi-res images are below.

FE Home Page > FE Downloads Page >

FE 'tkGooies' Description Page >

FE 'tkGooies' 'TEXTtools' Page >

This FE 'xpg' text file
browse, search, and extract-lines
utility tkGooie Page

INTRODUCTION to
Tcl-Tk scripts and shell scripts code
for the FE 'xpg' text file
browse-and-search tool

In 2012, I made a personal committment to contribute to the Tcler's wiki at wiki.tcl.tk five 'PlotQuik' utilities (Tk scripts), adapted into 'stand-alone' scripts from their original 'integrated' form in the FE 'feHandyTools' subsystem.

In addition to the plot utilities, there is one other 'Freedom Environment' utility that I would like to contribute to Tcler's Wiki --- a text file browser utility that I call 'xpg'.

The 'xpg' utility was 'integrated into' the FE 'xpg' subsystem --- and into the FE 'feAppMenus' and 'feHandyTools' subsystems.

The 'xpg' utility has a powerful 'Show-All-Match-lines' feature that I have used over and over in helping me write the 45-plus Tk scripts that I have donated to the Tclers' Wiki pages.

The 'xpg' utility has also helped me write web pages like this one.

One reason I would like to donate this utility to the Tclers' Wiki site is because I get tired of reading web postings claiming that Tcl-Tk is dead.

I think this 'xpg' utility, that I use almost daily, shows that Tcl-Tk is not dead.

It lives every day --- at least for me.

The features of the 'xpg' utility have evolved over multiple years (from crude beginnings around 1999), but I have been using it for several years now (circa 2012) with no major enhancements.

So I think it is appropriate to donate the code to the Tclers' Wiki at this time (2013).

Below is an image that demonstrates what the GUI looks like.

In this image, the 'xpg' utility is showing the text file 'shofil.tk', which is the Tk code that is showing this GUI.

You can see that the GUI includes the typical 'Exit' and 'Help' buttons, as well as a 'Search string' entry field that is typical of applications that browse text files.

The really powerful feature of this 'xpg' utility comes from the 'SAM' (Show All Matches) button on the GUI.

If the user clicks on the SAM button, instead of the Search button, the 'xpg' utility uses itself to show a listing of match lines in a new popup window.

In fact, the 'xpg' utility uses itself to show the Help file that is shown when the user clicks on the 'Help' button.

Another couple of buttons that need a little explaining are the '<-Ybar->' button and the 'OtherOpts' button.

---

The '<-Ybar->' button toggles the vertical scrollbar back-and-forth, from the right side of the GUI to the left, and back.

I use this quite frequently, because I often like to have the scrollbar on the left --- as I am editing a Tk script in the 'Scite' text editor, while having some sample code in 'xpg', for reference.

---

The 'OtherOpts' button shows a 'hidden' frame of additional search options ('Backward', 'CaseSense', 'RegExp') and a 'WinColor' button and a 'TxtFont' button --- below the line of 'Search(again)' and 'SAM' buttons.

The 'OtherOpts' frame can be seen in a screenshot that is posted below --- below the 'shofil.tk' code-link on this page.

Both the '<-Ybar->' button and the 'OtherOpts' button are implemented by use of the Tk 'pack forget' command.

---

One other feature of the GUI that is worth pointing out at this point is the '+/-' label on the GUI, just to the right of the 'SAM' button.

The number 0 appears just to the right of that string, and there is a popout menu there that allows the user to change the number.

That number allows the user to request that NOT JUST THE MATCH LINES be shown when the 'SAM' button is clicked, but ALSO N-lines above and below each match line.

This can be handy when one is, for example, looking for info on an issue in a large README file, and one needs to see the lines above and below match lines in order to see the lines that are needed to fully describe the issue -- the complete sentences containing the search-word(s).


DESCRIPTION OF THE CODE

Below, I provide the Tk script code (and shell scripts) for this 'xpg' utility.

This utility is actually composed of about 8 files (four shell scripts, 3 Tk scripts, and a help file) --- but the central guts of the 'xpg' utility is a Tk script that I call 'shofil.tk'.

The other two Tk scripts are color-selector and font-selector utility scripts that I have posted on this web site --- and on the Tcler's Wiki.

You can make that color-selector script by cutting-and-pasting the code from the page offering

'a non-obfuscated color selector GUI'

on this site.

You can make that font-selector script by cutting-and-pasting the code from the page offering

'YAFSG - Yet Another Font Selector GUI'.

The 4 shell scripts have fairly descriptive names:

  • findANDshow_stringsINfile_plusminusNlines.sh

  • findANDshow_NOTstringsINfile.sh

  • set_localoutlist.sh

  • xpg

The 'xpg' script is a 'wrapper' script for the 'shofil.tk' script.

I will post the code for the 4 shell scripts below the code for 'shofil.tk', below.


More about the shell scripts

The two 'find' shell scripts use the 'awk' command to perform their function.

And the other 2 shell scripts use quite standard Linux/Unix/BSD commands to do their work.

So ALL of this contributed code should work on most Linux, Unix, and BSD systems.

If there are small differences in the way the 'awk' command works on a particular system, you can probably get the two 'find' scripts to work by making no more than a few minor changes.

And since Apple Mac operating systems are based on BSD systems, it is quite likely that this set of scripts will work on Mac's --- but I have no Mac machine on which to try this (nor do I want to spend the time to do such testing --- I have too many other Tcl-Tk projects to address).

But if anyone tries out this set of code on a Mac, I would be interested to hear whether it all worked out.

In relation to Microsoft operating systems, the 'shofil.tk' Tk script --- and the color-selector and font-selector Tk scripts --- should probably work with few changes.

However, the 'SAM' button, which uses the 2 'find' scripts, will not work unless the user has a package installed that includes the 'awk' program --- and even then some changes to the scripts will probably have to be made.

Another alternative would be to rewrite the 2 'find' scripts in C code, and replace the 2 find scripts with compiled C code.

(I leave it to others to handle porting these files to a Microsoft OS.)

---

I followed my usual 'canonical' structure for Tk code in writing the 'shofil.tk' script:



  0) Set general window & widget parms (win-name, win-position,
     win-color-scheme, fonts, widget-geometry-parms, win-size-control,
     text-array-for-labels-etc).

  1a) Define ALL frames (and sub-frames, if any).
  1b) Pack   ALL frames and sub-frames.

  2) Define & pack all widgets in the frames, frame by frame.
              Within each frame, define ALL the widgets.
              Then pack the widgets.

  3) Define keyboard and mouse/touchpad/touch-sensitive-screen action
     BINDINGS, if needed.

  4) Define PROCS, if needed.

  5) Additional GUI initialization (typically with one or more of
     the procs), if needed.


This Tk coding structure is discussed in more detail on the page A Canonical Structure for Tk Code --- and variations.

This structure makes it easy for me to find code sections --- while generating and testing a Tk script, and when looking for code snippets to include in other scripts (code re-use).

I call your attention to step-zero.

One new thing that I have started doing recently is using a text-array variable --- named 'aRtext' --- for text in labels, buttons, and other widgets in the GUI.

This can make it easier for people to internationalize my scripts.

I will be using a text-array like this in most of my scripts in the future.


Experimenting with the GUI

As in all my scripts that use the 'pack' geometry manager (which is all of my 100-plus scripts, so far), I provide the four main 'pack' parameters:

  • '-side'
  • '-anchor'
  • '-fill'
  • '-expand'

on all of the 'pack' commands for the frames and widgets.

That helps me when I am initially testing the behavior of a GUI (the various widgets within it) as I resize the main window.

I think that I have used a nice choice of the 'pack' parameters for the 'shofil.tk' GUI.

In particular ...

The labels and buttons and checkbuttons stay fixed in size and relative-location as the window is re-sized
---
while the search-string entry field x-exands as the window x-expands
---
and the 'text' widget and its x and y scrollbars expand/contract appropriately as the window is re-sized.

    You can experiment with the '-side', '-anchor', '-fill', and '-expand' parameters on the 'pack' commands for the various frames and widgets --- to get the widget behavior that you want.

---

Additional experimentation with the GUI
--- its appearance:

You might want to change the fonts used for the various GUI widgets.

For example, you could change '-weight' from 'bold' to 'normal' --- or '-slant' from 'roman' to 'italic'.

Or change font families.

    In fact, you may NEED to change the font families, because the families I used may not be available on your computer --- and the default font that the 'wish' interpreter chooses may not be very pleasing.

I use variables to set geometry parameters of widgets --- parameters such as border-widths and padding.

And I have included the '-relief' parameter on the definitions of frames and widgets.

Feel free to experiment with those 'appearance' parameters as well.


Some features in the code

The code for the Tk GUI script 'shofil.tk' has plenty of comments to describe what most of the code-sections are doing.

You can look at the top of the PROCS section of the code to see a list of the procs used in the 'shofil.tk' script, along with brief descriptions of how the procs are called and what they do.

The two main procs that do the search functions are

  • 'search4string'
and
  • 'all_matches2string'.

The second of these implements the 'SAM' (Show All Match-lines) button.

Another main proc is 'getfile2textwidget' which uses the Tcl 'gets' command to load lines from a user-selected file into the 'text' widget.


A fervent hope

It is my hope that the copious comments in the code will help Tcl-Tk coding 'newbies' get started in making GUI's like this.

Without the comments, potential young Tcler's might be tempted to return to their iPhones and iPads and iPods --- to watch videos of friends bashing friends in the face.

(I wonder how many are still friends?)


The Tcl-Tk CODE

Here is a link to CODE for the script

'shofil.tk'.


Below is a screenshot that shows the frame revealed by clicking on the 'OtherOpts' button.

For this image, I used the 'WinColor' button to bring up the color-selector GUI and set the window color to a brown that sort of matches the brown shades that were common to the Ubuntu Linux desktop in the 2008-2009 era.


Shell scripts CODE
(for four scripts)

Following are links to the code for the 4 shell scripts of the 'xpg' system.

Here is a link to CODE for the SHELL script

'findANDshow_stringsINfile_ plusminusNlines.sh'.

----

Here is a link to CODE for the SHELL script

'findANDshow_NOTstringsINfile.sh'.

----

Here is a link to CODE for the SHELL script

'set_localoutlist.sh'.

----

Here is a link to CODE for the SHELL script

'xpg'

which is a wrapper script for the 'shofil.tk' Tk script.


POTENTIAL ENHANCEMENTS:

As I mentioned above, I have been using the 'xpg' utility for several years now (circa 2009-2012) and I have not found a need to add new features.

So I have no plans to make any enhancements at this time.

However, in the process of making a 'stand-alone' 'xpg' system from the 'integrated' 'FE xpg' system (with its Tk 'include' files making for even more files in the installation), I must confess that when I got all the features working, I had run out of energy to go through the procs section of the 'shofil.tk' script and clean up the procs and improve their organization (their order).

Also I ran out of steam to go through the comments of the 2 'find' scripts and the 'set_outlist.sh' script.

So, someday, when I have more energy, I may return to this page and try to touch up the code --- mainly the comments and the order of the procs.


Meaning of the "stand-alone" terminology

In making this 'stand-alone' version of 'xpg' from the 'integrated' version in the 'FE xpg' subsystem, I merged the code from about five Tk 'include' files that I used to set various GUI parameters, such as colors, fonts, and widget geometry (padding and border-widths).

Those '.tki' Tk include files were used, via Tcl 'source' statements, to provide a consistent user interface for the 3 main Tk scripts in the 'FE xpg' subsystem --- the 'shofil.tk' script and the scripts for the color-selector and the font-selector.

Hence this set of 'xpg' files is 'stand-alone' in the sense that when the color-selector or font-selector GUI's pop up, they may not have the same color and font and widget-geometry as the 'shofil.tk' GUI.

But you can easily make the 3 GUI's look alike by editing the 3 Tk scripts to change, for example, the 'tk_setPalette' statement to give all 3 GUI's a common color.

Here is a situation in which my 'canonical' form for all three scripts comes in handy.

The color-setting, font-setting, and widget-geometry setting code is located in the same area in all three scripts --- near the top of the code (or, sometimes, in the 'Additional GUI Initialization' section at the bottom of the code).


THE HELP FILE:

There is one more file to this installation --- the help file.

This 'xpg' utility has a lot of operational features that need some explaining.

I provide the help file in this link to the plain-text file

shofil.hlp.

Methods of setting up the 'xpg' command for execution are described in that help file.

For this 'stand alone' version, it is assumed that the following 8 files of the 'stand-alone' 'xpg' system are installed, together, in a single directory --- such as

$HOME/apps/xpg

--- not in several separate sub-directories, as they are in the 'integrated' 'FE xpg' system.

  • shofil.tk
  • sho_colorvals_via_sliders3rgb.tk
  • select_tkFont.tk
  • findANDshow_NOTstringsINfile.sh
  • findANDshow_stringsINfile_plusminusNlines.sh
  • set_localoutlist.sh
  • xpg
  • shofil.hlp

IN CONCLUSION

I think we Tcler's need some examples of very useful code that can help us counter the claims of some 'nattering nabobs of negativism' --- that 'Tcl-Tk is dead'.

    For youngsters reading this, the quote 'nattering nabobs of negativism' comes from Spiro Agnew, circa 1970.

Tcl-Tk not dead for me. I hope it is not dead for you.

If you could use the 'ShowAllMatches' capability of this 'xpg' utility, then I think you will find that, indeed, Tcl-Tk is not dead for you.

As I have said on other code-donation pages on this site ...

A BIG THANK YOU to Ousterhout for starting Tcl-Tk, and a BIG THANK YOU to the Tcl-Tk developers and maintainers who have kept the simply MAH-velous 'wish' interpreter going.

Bottom of this page for
Tcl-Tk and shell scripts Code for
the FE 'xpg' text-file browse/search utility
--- a utility in the FE 'tkGooies' system,
in the 'TEXTtools' group.

To return to a previously visited web page location, click on the Back button of your web browser a sufficient number of times.

OR, use the History-list option of your web browser.

OR ...

< Go to Top of Page, above. >

Page history:

The 'stand alone' code was created in 2013 --- and posted 2013 Aug 05 at http://wiki.tcl.tk/38443.

This FE web page was created 2014 May 11.
(as a backup and alternative to the wiki.tcl.tk page)

This page was changed 2015 Oct 05.
(Small changes.)

Page was changed 2019 Mar 02.
(Added css and javascript to try to handle text-size for smartphones, esp. in portrait orientation.)

Page was changed 2019 Jul 03.
(Specified image widths in percents to size the images according to width of the browser window. Also added some web links.)

Page was changed 2024 Sep 06.
(Changed links to other web pages so they load in a separate window or tab so that this page remains available in its window or tab.)


NOTE:
The code here MAY BECOME more 'up-to-date' than the code posted on the Tcler's Wiki --- wiki.tcl-lang.org --- formerly wiki.tcl.tk.