TkCodex: User Reference

If you start TkCodex without any arguments, you get an empty command window. If you want to include a starting directory as the first argument, you must also include a filename extension as the second argument. The extension should not include a period, but you can include multiple extensions separated by a comma:

TkCodex /home/user/files/webpage php,html,css,cgi

You can also include a regular expression to search for as a third argument, in quotes if necessary.

This is the empty command window:

Using "enter" in the command window doesn't do anything; you must use the buttons. If you press regexp, the file list box will be filled with all the files in the directory tree with a correct suffix that contain the regular expression in the regular expression entry. The files are sorted according to the number of occurrences, which is shown in parentheses. If you press dir, the regular expression entry is cleared and the file list box will contain all files in the tree with a correct suffix. Again, the suffix should not contain a period, but it may be a comma separated list (no spaces). Unless there are multiple files in the tree with the same name, only the pathless filename will appear in the file list box. By default, TkCodex follows symlinks. If this is a problem (it can be), you can turn it off (see configuration).

TkCodex has a line history which is empty at start-up. There after, all the terms used in the regular expression entry of the command window, or in any of the search entries of the view windows, will be added to the history. These entries are all linked together -- there is one history for the whole thing, so you can access previous terms from the command window in any of the view windows, and vice versa. The up and down arrows cycle thru the line history.

The directory entry does not have a line history, but you can keep permanent bookmarks of directories you commonly use. These are stored by default in ~/tkcodex/tkcodex.bookmarks or in an alternate place specified in the configuration file (see configuration). To add the current directory, press ctrl-a in the directory entry. Cycle through bookmarks with the up and down arrows. To delete a bookmark, use ctrl-d.

Initially, none of the three available view windows are visible. One shortcoming of perl/Tk is that the memory taken by a widget cannot be freed when it is destroyed, so rather than creating and destroying different TkCodex windows as they are used (which would cause the amount of memory used to steadily increase), the windows are "withdrawn" and then made to reappear as necessary. For the user, the only difference this makes is that you must never use your window manager to "close" a window (if you do, the window you "closed" will be destroyed and you will have to restart TkCodex). The large view windows are invoked and withdrawn the same way, with the first three F keys -- if the window is visible, it will disappear, if not, it will appear. The F keys work this way everywhere in TkCodex. The command window cannot be made to disappear, but you can iconify it, and the view windows too.

To load a file from the command window, select it in the file list box and press 1, 2, or 3. This will load the file into the first open tab in the corresponding view window, but you still have to use an F key to make that window visible. Files which have been loaded appear with one or more asterisks before their name in the file list box, and when selected a window number/tab letter (eg, 1A) will appear in the location indicator area for each tab the file appears in.

You can also load a set of files from a view window with the 1st 4 button. This will clear the contents of all tabs in that view window and load the first four files from the command window file list box into the four view window tabs. Again, to keep memory usage stable, the tabs are not opened or closed, they are used or "E M P T Y". The CLEARALL button in the command window empties all 12 tabs. Individual tabs can be emptied with the clear button in the view window, and all four tabs with all.

The View Window

The only thing the enter button does in the view window is send you to a line number from the text entry. To search for a term from the text entry (including a number), use the hilite button. This highlights the term pink on orange, and the entire line in italic blue, with an entry for each instance in the tag index list:

Because just doing a regular search for "enter" would have caught "center" too many times, I used the regular expression checkbutton to do a case insensitive search for "\benter\b" -- \b representing a word boundary in perl regular expressions. This way, we also caught the literal instance of '"enter"'. The results of regular expression searches are shown in white in the tag index list; normal searches are light gray. Regarding "normal" searches, you may want to look at known issue #1.

It's important to know how a search hit was produced if you want to remove it later. Unless the tag index list was from a previous save, the term itself will be in the line history. If not, you can always type it in. To eliminate the entire set of a search result, use the unlite button. However, TkCodex will only eliminate instances in the tag index list if the search criteria are also identical. In other words, to get rid of all highlighted instances of "\benter\b" in the tag index list, we must also have the regular expression checkbutton on and the case sensitivity off.

There is only one case sensitivity checkbutton for all of TkCodex, the one in the command window. When on, a big red asterisk appears left of the unlite button in all view windows. This is so you can do case sensitive searches of the directory tree from the command window regexp button. Hits from case sensitive searches are preceded in the tag index list by an asterisk.

There are no scrollbars anywhere in TkCodex, but the windows do scroll in all directions when there is sufficient content. The easiest way to scroll the command window file list box is to just hold the left mouse button down and move the selection bar. You can do this everywhere else too, but a better way to navigate in the view windows is to use ctrl with i,k,o, and l -- i and k move the text area up and down without moving the cursor, while o and l do the same for the tag index list. If you select a tag in the list with the left button, you can move it into view with the right button. Pressing both buttons will remove the selected tag(s).

You can cycle through the four notebook tabs with ctrl-PgUp and ctrl-PgDn.

TkCodex also has a pop-up menu available from the right mouse button in the text area of the view windows. All of the items in the menu can also be called with a ctrl key. ctrl-B and ctrl-b will set and return you to a bookmark. Ctrl-g will return the cursor to it's previous position (usually not far away, unless you moved using the tag index list). There is only one bookmark. As previously mentioned, typing a number into the text entry and pressing enter will take you to that line number. This will also replace the number with the line number you just came from, so if you leave the text entry alone, you can go back to where you started easily. Numbers do not get saved as part of the text entry's history unless you do a search for them. You can see the exact line and character position of the cursor, where 1.0 is the top left, with ctrl-c. This will replace (for example) "line 2" with "2.13" in red at the bottom right.

If you want to do an un-obtrusive, un-indexed search in the style of most word processors et. al., you can use ctrl-f instead of the hilite button. This will highlight the term in bold green. No entries will be added to the tag index list, but you can always move to the next green highlight with ctrl-n, and the previous one with ctrl-p. Only one term can be highlighted green at one time. Using ctrl-f again will remove the last set of finds and create a new one. You can do the exact same thing in bold red with ctrl-R. However, red highlights are not automatically removed, and there is no previous and next function. But red highlights are added to the tag index. Normally, they do not appear in the list -- you can toggle their appearance with ctrl-x. You can remove them either individually from the tag index list (when visible) or by using ctrl-U, the equivalent of "unlite". Except for hypertext-notes, red is the only highlight you can add to a hand selected region, using ctrl-r (this also toggles the red indexes on in the list). All red highlights are saved.

A unique thing about red and green highlights is that they do not disappear when you switch to the subroutine index. The yellow-on-gray subroutine (or function) index is accessed via ctrl-z (switch back the same way).

TkCodex determines what to show in the subroutine index by the file's suffix. There are two defaults, one for perl and one for c. C-style applies to all files with a .c or .h; perl-style applies to .pl. You can change the defaults and what they apply to and add new styles for other suffixes via the configuration file. To create the list, TkCodex applies a regular expression to the file when it is first loaded. For perl, this is straightforward, since perl subroutines all begin with the form "sub NAME {". For C functions, this is somewhat more complex and idiosyncratic, so you will likely have to come up with a customized regular expression and even alternate versions to cover files written by different people.

You can add hypertext to a selected area of text with ctrl-N. This calls up the yellow on gray note window, which is also what appears when you double-left click on the highlighted text, although then it will contain the text of the note instead of being empty. Always use the "done" button to dismiss the note window, for reasons discussed above. Any changes you make to the note are kept. Notes, along with the tag index list, can be saved and reloaded for a specific file using the save and load buttons. TkCodex never alters an actual file; the notes are saved separately. There is a complete explanation of this on the "Keeping Notes" page, as well as further details about highlighting in TkCodex.

A final handy feature of TkCodex is that if you have vim compiled with the server option, you can send it lines while in INSERT mode (via. "vim --remote 'line content'). Just position the cursor on the line you want sent and press ctrl-v. Because this is handled by the shell, single quotes in the line are replaced by a double-asterisk, and you will have to use s/\*\*/'/g to change them back.

Known Issues