FE 'tkGooie' Utilities

---

'SELECTORtools' group

---

tkSiteLatitudeLongitudeSelector

(where 'sites' may be cities,
countries, parks, etc.)

(FE = Freedom Environment)

FE Home Page > FE Downloads Page > FE 'tkGooies' Description Page >

FE 'tkGooies' 'SELECTORtools' Page > This Page

INTRODUCTION to 'tkSiteLatitudeLongitudeSelector'

I am planning (in 2016-2017) to make some Tcl-Tk GUI's for plotting maps of various kinds on a Tk 'canvas' widget --- maps of portions of the Earth --- and perhaps, eventually, maps of other essentially spherical bodies, such as the Earth's moon or Mars or some other body with 'sites' located in latitude and longitude coordinates.

The locations of items on maps of the Earth are typically given as a latitude and longitude --- either in decimal-degrees or in degrees-minutes-seconds (or simply degrees-minutes for locations of fairly wide 'sites', such as cities or national parks).

    At the equator, the circumference of the Earth is about 24,901 miles (40,075 kilometers). Since one minute is one-sixtieth of a degree and there are 360 degrees in the circumference, at the Equator, one minute along the Equatorial latitude is

           1 / (360 * 60) = 1 / 21,600
    

    of the Earth's circumference. This amounts to 1.15 miles (1.86 kilometers) --- close enough for 'marking' the location of most cities.

    A minute of longitude amounts to an even smaller (more accurate) distance at northern and southern latitudes.

    A minute of latitude (to the north or south of the Equator) is about 1.15 miles (1.86 kilometers) no matter the location on the Earth.

In making the maps, I may want to designate certain spots, such as cities, on a map. By having a 'site-latitude-longitude-selector' at hand (on my development computer), I can quickly look up the latitude-longitude data that I might need --- without needing a connection to the Internet.

In fact, in some cases, in a Tcl-Tk map-maker utility, I may want to build in a 'site-latitude-longitude-selector', so that the user can choose 'sites' to 'mark' on the map.

Since I have plenty of 'selector' code to use as a starting point, I decided to code this relatively simple 'selector' utility.

The toughest part of making this utility would be to enter all the site-description data and latitude-longitude data (in both decimal-degrees and degrees-minutes) --- for hundreds of cities, and for other 'sites' --- such as countries and national parks.

To make the job a little easier whenever I find data in one format or the other (decimal-degrees only or degrees-minutes only), I can use my tkDegreesMinSecConvertSelect utility to convert from one format to the other.


THE GUI DESIGN

Following a coding pattern I started using around 2015, I laid out a 'text-sketch' of a proposed layout for the GUI.

In the below sketch of the GUI:

  SQUARE BRACKETS indicate a comment (not to be placed on the GUI).
  BRACES          indicate a Tk 'button' widget.
  A COLON         indicates that the text before the colon is on a 'label' widget.

  <----O---->     would indicate a horizontal Tk 'scale' widget (if any).
  UNDERSCORES     would indicate a Tk 'entry' widget (if any).
  CAPITAL-O       would indicates a Tk 'radiobutton' widget (if any).
  CAPITAL-X       would indicates a Tk 'checkbutton' widget (if any).

The options available to the user are indicated by the following 'sketch' of the GUI:

 FRAMEnames
 VVVVVVVVVV

                   -----------------------------------------------------------------------------------
                   tkSiteLatitududeLongitude Selector
                   [window title]
                   -----------------------------------------------------------------------------------

.fRbuttons         {UseIt} {Cancel} {Help}  

.fRselected        Selected line: ....[text widget]............
                           
                   SITES with latitude & longitude
                   (in signed-decimal-degrees AND in degrees-and-minutes):                         
                   |-------------------------------------------------------------------------------A
.fRlist            | [ LISTBOX widget to hold lines of                                             |
                   |   site IDs and location data, such as ]                                       |
                   | ...                                                                           |
                   | United States, California, San Diego # decimal degrees # degrees, minutes     |
                   | United States, California, San Franisco # decimal degrees # degrees, minutes  |
                   | ...                                                                           |
                   | ...                                                                           |
                   |                                                                               |
                   |                                                                               |
                   |                                                                               |
                   |<----------------------------------------------------------------------------->V


---

GUI components:

From the GUI 'sketch' above, it is seen that the GUI consists of about

   -  3 button widgets
   -  2 label widgets
   -  1 one-line text widget
   -  1 listbox widget (with x,y scrollbars)
   -  0 entry widgets
   -  0 radiobutton widgets
   -  0 checkbutton widgets
   -  0 scale widgets
   -  0 canvas widgets


A SCREENSHOT

So I set to work converting the code of another selector GUI to this proposed GUI, and I ended up with the GUI seen in the following image.

This is the GUI as it appears on startup --- the 'Selected line:' text-line is empty.

After scrolling down in the listbox and selecting a line, the contents of the selected line appear, as seen in the following screenshot.

If this selector utility is embedded in another 'app', such as a map-making app, the 'Selected line:' info confirms to the user the character string that will be returned to the calling-app when the 'UseIt' button is clicked.


The 'Help' button on the GUI provides pretty complete and detailed help for using the GUI.


DESCRIPTION OF THE CODE

Below, I provide the Tk script code for this 'tkSiteLatitudeLongitudeSelector' utility.

I follow my usual 'canonical' structure for Tk code for this 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 from other scripts (code re-use).

I call your attention to step-zero. One new thing that I started doing around 2014 is using a text-array 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.

All the 'set' statements for the text array are in one contiguous section toward the top of the code.


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.

In this particular GUI, I have chosen to allow the window to be re-sized --- so that the listbox can be re-sized.

However, one could un-comment the statement

   wm resizable . 0 0

to make the window fixed at its initial size.

With the window resizable, 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: 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

There are plenty of comments in the code, 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 this script, along with brief descriptions of how they are called and what they do.

Here is a quick view of how each of the procs are 'triggered'.

    'listbox_select_siteID'   - called by a button1-release binding on
                                the SiteIDs listbox widget.

    'put_vars'                - called by the 'UseIt' button

    'popup_msg_var_scroll'    - called by the 'Help' button


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 other equivalents) --- to surf the web looking for the latest rumors (or fabrications) about Kim Kardashian and Kanye West. (By the end of 2016, this drama may have ended and other dramas introduced in its place.)


THE CODE

Here is a link to CODE for the script 'tkSiteLatitudeLongitudeSelector.tk'.

With your web browser, you can 'right-click' on this link --- and in the menu that pops up, select an item like 'Save Link Target As ...' --- to save this file to your local computer.

Then you can rename the file to remove the '.txt' suffix. Make sure that you have execute permission set on the file --- in order to execute the script.


SOME POTENTIAL ENHANCEMENTS:

A couple of possible enhancements come to mind:

  • Search option:
    A search-string entry field could be added to the GUI to make it easy to quickly locate a line (or lines) for a given string --- numeric-search as well as alphabetic.

  • Sort option:
    An option to sort on any of several 'columns':

    • site description
    • decimal-latitude
    • decimal-longitude
    • degrees-minutes-latitude
    • degrees-minutes-longitude

    might be a nice feature to add to the GUI.

If I ever find that I am using this utility --- either 'manually' or called within a script --- and I find that either of these features is highly advisable to add, then I may return to this script to provide that feature.


IN CONCLUSION

As I have said on quite a few other code-donation pages on this wiki ...

There's a lot to like about a utility that is 'free freedom' --- that is, no-cost and open-source so that you can modify/enhance/fix it without having to wait for someone else to do it for you (which may be never).

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 the page for tkSiteLatitudeLongitudeSelector --- a utility in the FE 'tkGooies' system, in the 'SELECTORtools' 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. >
< Go to FE 'tkGooies' 'SELECTORtools' Page >
< Go to FE 'tkGooies' Description page >
< Go to FE Home page. >

This FE web page was created 2016 Apr 11.

If I ever post a copy of this code on the Tcler's Wiki site (wiki.tcl.tk) ---
as a backup and alternative to this page, I plan to put a link to that page here.