Upon starting GTKeyboard, you'll be presented with a full keyboard including all punctuation and symbols available to you on the keyboard.
The window that is displayed has two different text boxes. The first, which is not editable by the user, contains GTKeyboard status messages to the user, for example, whether the CAPS LOCK key is ON or OFF, whether the SHIFT key is ON or OFF, and other messages pertaining to options that you can change within the program, such as whether or not the program will ask you if you want to save on exit, and so on.
The second text box below the first, is the editable input/output box. In this box, you can type as you would normally in any other program, or you can hit any of the keys above on the keyboard to insert text into this location. If you write text past the end of the line, you will notice that the text automatically wraps around with a small curling arrow sign at the end of the previous line showing that you have gone past the end of that line. You may also toggle word wrap under the Misc window.
All punctuation necessary for writing should be available on the keyboard for editing.
When you are ready to save your document, you have a choice of two things. You can either save the file under the default filename, which is usually /tmp/GTKeyboard, or you can specify the filename you wish to save it under and then save it. To specify the filename you wish to save it as, click the File menu on the top bar, and select New File. A dialog box will pop up, prompting you for the new filename.
The status logging toggle option in the Misc menu is what controls whether or not the status window's text is saved on exit of the program. When you use the menu, it will let you know in the status menu itself what the current setting is.
A few quick notes: The "Clear All" button, which is located at the very bottom of the button row at the bottom of the application, is not a cut button. It will clear all of the text in the buffer, and it will not copy it to the X cut buffer, i.e. you will not be able to paste that text back into the document again. For that reason, I had to put in an "are you sure" popup dialog.
This manual was a plaintext to HTML conversion of the old GTKeyboard manual that came with the program. I've tried to mention just about everything, but I'm sure there are things that I missed.
If you would like to report some feature documentation missing that you'd like to see, suggest another subtopic, correct my spelling or grammar, please email me at <s2mdalle@titan.vcu.edu> and I'll clear it up as quickly as possible. If you would like to write a section, go for it, and I'll incorporate it as long as it's relevant to GTKeyboard.
I am David Allen, I'm a college student attending Virginia Commonwealth University in Richmond, Virginia (as of this writing). I major in Computer Science and Psychology. I originally wrote the program to learn the GTK+ toolkit, but as time went on, people found some new uses for the software I hadn't imagined, and were requesting new features and bugfixes, which I was more than happy to provide.
I try to make it as easy as possible to get a copy of GTKeyboard. Here is a list of places that you're likely to find GTKeyboard hanging out if you want the latest copy, and older copy, (they're pretty embarassing for me, but sometimes so are the newer versions :) or an RPM (source or i386). As of this writing, I don't make or provide any debian, stampede, or other packages of GTKeyboard. For this, I recommend either alien, a package converter, or that you make your own. If you do make your own, let me know, and I'll arrange to distribute them with the rest of the packages.
Where to find GTKeyboard:
GTKeyboard has many features that hopefully help the user out in getting many and varied tasks done. Here is a brief overview of some of the features available.
There is one other point that I'd like to make about the feature set of GTKeyboard. Although it's constantly growing, sometimes I get an email that asks me why I put in a specific feature. Currently, there are people who are working towards using GTKeyboard in an ICU/OR setting whos user interface requirements are much different from that of the standard user. I have attempted to make each feature as small as possible, to minimize growth of the binary and memory usage. If you find that a certain feature is strange, or doesn't sound like something you'd ever use, that's fine, but most likely they will stay in GTKeyboard to add flexibility to the application in addition to letting other people with different agendas use the application for their purposes.
GTKeyboard reads a configuration file at startup to determine which options you want functioning in the program, and which you don't want functioning. The file is always located in your home directory with the name .gtkeyboardrc. ~/.gtkeyboardrc contains a few lines that toggle features on and off at the start of GTKeyboard. You may specify a default file to edit at startup, whether you want to use word wrap or not, whether to ask you to save the document on exit, and so on. If there are other aspects of GTKeyboard you would like to be able to customize, mail me, and I'll see if I can work it in.
If a configuration file is not present, GTKeyboard will copy a default configuration file and choose values that I think are reasonable. But not everybody likes things the same way, what I think is reasonable you might consider absurd, so please edit the file to your liking. Editing this file is optional though, since GTKeyboard can run with the default provided resource file.
Entries in the file look like this:
set OPTION_NAME VALUEOr, alternatively, like this:
toolbar ELEMENT [ON|OFF]
First, the option names. "Toolbar" statements are explained below
OPTION_NAMEs include ASK_SAVE_ON_EXIT, WORKING_FILE, WORD_WRAP,
STATUS_LOGGING, RANDOM_STRLEN, with more to come in the
future. VALUE is any integer value that you want to set the feature
to. If you enter 0, the feature is turned OFF, any other value will
result in the feature being enabled. That is,
set ASK_SAVE_ON_EXIT 1and
set ASK_SAVE_ON_EXIT 323and even
set ASK_SAVE_ON_EXIT ONAre functionally equivalent. Both will cause GTKeyboard to prompt you as to whether or not you want to save the file before you quit. But if you enter
set ASK_SAVE_ON_EXIT 0then you will not be prompted.
Some option names take strings as arguments, examples being
WORKING_FILE and KEYBOARD_FILE. In
these cases, syntax is simply:
set variable_name string_value
set KEYBOARD_FILE /home/user/gtkeyboard-layouts/DE.key
Option Names (listed alphabetically):
Each statement goes on a line by itself, and at this point, all lines
that are not of that form are ignored or rejected as illegal input.
You can find a sample rc file with this package, called
defaults.gtkeyboard which should be changed and moved to your
home directory as .gtkeyboardrc. You can then edit it and go on with
your bad self. :) You will mostly likely want to edit the WORKING_FILE
option .. for example, at home in my gtkeyboardrc I use
set WORKING_FILE /home/x/.gtkeyboardrc
If you choose not to have a working file, then just put something in there that isn't a real filename. GTKeyboard will complain in the status window about not being able to open it, but hey, that's life.
If you specify a file on the command line to edit with GTKeyboard, the default file option in the rcfile will be ignored and you will work with the file you specified.
These are simple statements of the form:
[show|hide] element
Keyboard statments are very similar to layout statements. The only main difference is that a keyboard statement only controls a subsection of the keyboard. It allows the user to show/hide arbitrary parts of the keyboard.
Syntax for keyboard statements is:
keyboard element_name [on|off]
For example, a layout file that wanted to only show the main keyboard and nothing else would have statements looking like this (note that case doesn't matter in resource file statements):
keyboard keyboard on # Turns the main keyboard ON keyboard cursor_keys off # Turns the cursor keys off keyboard number_pad off # Do not show the number pad keyboard f_keys off # Do not show the f-keys.
The default value for all of the above elements is ON.
Mentioned above, a statement of the form
toolbar ELEMENT VALUEAllows the user to customize the toolbar via the resource file. ELEMENT stands for the name of a toolbar element, and VALUE for what that element should be. An example of this would be something like the following:
toolbar window_grab OFFWhich would cause the window grabbing button on the toolbar not to be shown when GTKeyboard starts. ELEMENTs are case INSENSITIVE, which is to say, there is no difference between specifying the ELEMENT as "copy" or "COPY".
Each button on the toolbar has a name associated with it, which corresponds to an ELEMENT. You can control which ELEMENTs are shown and which are hidden by using the ON/OFF specifiers in the resource file. Note that ALL toolbar buttons are always ON by default. If you don't want to see them, you must set them OFF in your resource file.
The following are the names of the different ELEMENT statements possible when using the "toolbar" line in an rcfile. More can be added upon request as well as more possible toolbar buttons in general. Note that if you disable all of the toolbar buttons, the toolbar will not appear on the screen, but if that is your intention, it is probably easier to use the Hide Toolbar command in the Options->Looks>Toolbar>Hide menu to achieve the same effect.
The onscreen keyboard in GTKeyboard functions exactly like a normal keyboard on your desktop. Each of the buttons has its normal function, with the exception of the buttons on the top row, (F1-F12, ESC, Scroll Lock, etc) which do not have any function yet. The shift and caps lock buttons work just like they would on a normal keyboard, as well as all the other symbols like !@#$ etc.
As soon as the application starts, you can begin typing, and the output of your typing will appear in the output buffer, the text space near the bottom of the screen where the guide buttons are at the bottom. Each key that you press will put its corresponding symbol into the buffer at the bottom, possibly modified if the shift key is on. In addition, the NUM LOCK key and the CAPS LOCK key are toggle keys - the status buffer will inform you when they are turned off or on, and they will remain pressed down when on. To release them, just press them again.
On the bottom row of the main window, there are convenience shortcut buttons to perform common tasks such as to select all of the text in the widget, to open a file, to clear all the text out, to quit the application, and so on.
For convenience, there is also a popup menu that you can use with GTKeyboard. Just right-click in the text area at the bottom where you normally type into, and a menu will appear to let you perform common GTKeyboard tasks with, such as hiding/showing different screen elements, customizing fonts/colors, and so on.
Don't bother wasting button presses on repetitive things like quoting certain sections of text! The shortcuts menu in the top menubar will help you out with things like that. If you go into the quoting submenu, and click on "Quote", it will produce "" and put the cursor between the two quotes so that you can continue typing your quoted text. When you're done with the quoted text, use the cursor keys next to the spacebar to go to the left or right of where you currently are to continue typing.
In the Misc menu, there are also functions to move the cursor automatically to the beginning or end of the file, as well as the beginning or end of a particular line. It will place the cursor appropriately so that you don't have to worry about hitting the cursor keys the right number of times in order to go to the beginning/end of the line/document. They function just like the HOME and END keys on a normal keyboard.
Also, currently with the keypad, you have the buttons Home, End, and Delete. They function just like the keys on the keyboard. The HOME key takes you to the beginning of the current line, delimited by a linebreak, the END key takes you to the very end of the line, and the delete key deletes one key forward from your current position, just like on a normal keyboard.
GTKeyboard can define up to three different symbols for each key on the keyboard. Those three symbols are referred to as the normal symbol, the "shift&qout; symbol, and the "mode-switch" or "alt-gr" symbols.
Generally, the way you generate those symbols is as follows. If you just want the regular symbol, (the same thing as the symbol that shows on the face of the key) you just mouse-click on top of that button. If you want the shift symbol, you click on the Shift keyboard key, or possibly the Caps Lock key, and then click your symbol. For alt-gr symbols, an Alt-Gr or Mode Switch key must be present on the keyboard.
GTKeyboard offers a shortcut to skip through the symbols you need to select with each button. The first mouse button generates the "normal" symbol, the second mouse button generates the "shift" or upper case symbol, and the third button generates the "alt-gr" symbol if one exists. If it doesn't exist, nothing happens. Note that button 3 on most people's mouse will actually be the middle button, not the right-most button.
There are two ways to choose a window to redirect data from the keyboard to. They are the implicit method, and the explicit method. The implicit method, which is the default, is quite easy. Whichever window had the focus last is the window that is designated to receive the key presses. The explicit mode is where the user chooses a window explicitly for redirection.
In order to use the implicit mode, all you have to do is make sure that the window you want to redirect to is the window that last had the keyboard focus in your window manager. That's it. Generally, if you need to assign this, you can just click on the window you want to focus on with your mouse, and then click on GTKeyboard again. You should see a message in your status window saying "Found new focus window: window name" All keyboard usage after that will go into the foreign window.
In order to choose a new window to redirect output to (using explicit mode), click on the Output menu, then click on Choose a Window. Your cursor will change, at which time you go out and choose a window by clicking on an active window. When that is done, you just type with the on-screen keyboard as normal, or do whatever you would normall do, except that output goes into the foreign window rather than where it usually goes. See the BUGS file about some things that don't seem to want to work properly like xterm which are traditionally a pain to send X events to. For most things, this will work just that easily. (e.g. an rxvt window/other terminal emulator)
Sometimes, you will want to redirect text to a certain box within a certain window. (Like for example, the URL box in Netscape Navigator). This is no problem, GTKeyboard will let you do that too, but you must make sure that the box you want to type into has the focus. Basically, after you select the window, click on the box that you want one more time so a thin black border comes up around it as is traditional for most windows that have the focus, and then you can begin typing into that window.
Some notes about redirection to other windows:
You will also find a "Choose Window" and "Ignore Window" option under the shortcuts menu. They're just there for convenience, there is no difference between them, only that some people look in different places for the same things.
The ignore window button does exactly what it says it does: It ignores the current active window. So if you're workin on something within an rxvt window, and you want to go back to editing within the GTKeyboard text buffer, click on the Ignore Window button either at the bottom of the screen or in the Shortcuts or Output menus, and GTKeyboard will take focus away from that window and begin sending all keystrokes back into the GTKeyboard editing buffer. This allows you the flexibility to flip back and forth between small editing tasks and/or using GTKeyboard like a clipboard for text, and actually editing in other windows or performing other tasks with the on screen keyboard.
By request of several users, GTKeyboard now has the ability to let users define their own shortcuts and use them for quick advanced editing. On the toolbar, you will find several buttons, DS, S1, S2, and so on. These buttons provide access to the different GTKeyboard User Defined Shortcuts features.
All you have to do to define your own shorcuts is to click on either the "DS" button on the toolbar, or go to the options menu, and choose Define User Shortcuts.
Once you are in the definition menu, you will be able to type in whatever you want GTKeyboard to spit out when you click on the corresponding shortcut button. Right now, what you can add is pretty primitive, but it is functional, and also works when redirecting to other windows. Important: if you want the shortcuts to work, you must click "Install" after each shortcut to let GTKeyboard know that you have chosen what you want for that shortcut and it is to remember the shortcut.
Unfortunately, GTKeyboard does not currently remember which shortcuts you defined between sessions, but that will change soon. Also, currently you must actually use the keyboard to use the user defined shortcuts feature, but when the window redirection code gets rewritten, you should be able to choose those widgets as redirect windows and type in using the on screen keyboard provided what you want for that shortcut.
All you have to do to change the shortcuts is to reopen the shortcut definition window, as described above, and type in the new shortcut value. In the status window, GTKeyboard will let you know that it is throwing away the old value, and what that value was. After you click the "Install" button after entering the new shortcut text, you're done.
For users who want to, GTKeyboard allows the customization of fonts, screen layout, and colors that the application is displayed in. This section is about how to take advantage of that support to make GTKeyboard look they way you want it to look.
GTKeyboard comes with several different foreign keyboard, at this point in time including Spanish, Italian, German, American, UK, and French keyboard layouts. If you don't see support for the national keyboard you prefer to use with GTKeyboard, see the KEY/ directory of the source distribution, which contains notes on how to create a keyboard for your country. If you create any keyboards that GTKeyboard doesn't have, I would greatly appreciate hearing about it so I can include it in future releases of GTKeyboard.
To change keyboard layouts, just click on the Options menu, and select the "choose layout" menu item. It will bring up a file selection dialog which you can use to select the .key file corresponding to the keyboard that you want to use. Multiple key files are installed wherever you installed GTKeyboard, which will most likely be in /usr/local/share/gtkeyboard/ - but it may also be in /usr/share/gtkeyboard/ depending on how your copy was installed. GTKeyboard will try to choose the correct directory where the files are located by default. After you have chosen the correct file, press OK in the dialog, and the keyboard will remap itself. At this point, if you wish to use the foreign keys in a redirect window, you will have to remap the keyboard before continuing. Otherwise, if you just want to edit text, then you don't have to do anything extra.
To customize the color look of GTKeyboard, all you have to do is either click on the four-colored toolbar icon on the toolbar with the C on it, or go to the Options menu, then Looks, then Colors, then choose colors. You will be presented with a standard GTK+ color selection dialog that will let you choose which color you would like to have your application displayed in.
When you've found a color you like, click ok, and the color will be applied to the entire keyboard and application layout. At this time, the color is NOT applied to the pulldown menus. I believe this is a GTK+ issue, but I'll keep looking on my end of things too.
Please note that just because you can choose a color doesn't mean that it will look good or be useful when you apply it to the application. Case in point, choose all black for your colors, and all of the buttons will effectively disappear, making it impossible to see which key you're hitting! When choosing a color, you should probably choose a color that looks ok against black, since that's usually what color the button labels are in. (This could differ, depending on whether or not you're using a GTK+ Theme.)
If you ever want to return to the original application default, i.e., what GTKeyboard looked like when you started it, click on either the black "C" icon on the toolbar, or go to Options->Looks->Colors->Reset Colors to change them back to the application defaults. That's it. With GTKeyboard, you can choose just about any color that your X server can display to be the working color for the application.
If you find a color that you like, and would like to keep using for GTKeyboard in the future, you can use the Options->Looks->Save Layout Settings menu item to save those settings to a file. That file will then be loaded each time GTKeyboard runs. (For exceptions to that rule, see the IGNORE_LAYOUT_FILE rcfile option.
You may also customize the font type, weight, and size that the main text widget uses for editing text with the font button on the toolbar. Just click on the italic "F" button on the toolbar, choose your font, and click ok to apply it to the main text editing window.
As with application colors, this can be saved for future use with the use of the Options->Looks>Save Layout Settings menu item.
Many people find that the keyboard is either too big or too small for their use. That's no problem. On the toolbar, and in the Options menu, there are items that allow you to select the font of the keyboard. Click on the red "f" letter on the toolbar to customize the keyboard's font. Not only will it allow you to downsize the font, but you can also change the type of font used for different "looks"
Depending on the font size, the buttons will shrink or grow, along with the rest of the window. If you want a very small window, go with an 8 or 10 point font, although this can be hard to read.
As with application colors and text fonts, this can be saved for future use with the use of the Options->Looks>Save Layout Settings menu item.
Sometimes people use GTKeyboard primarily to type into an rxvt, or for some other task that does not require showing all of the different screen elements on the screen. For this, in the Options menu, there is a Looks submenu, where you can choose from options having to do with the main text box, the status box, the keyboard itself, the toolbar, the bottom row of buttons, and a few other things. All you have to do to customize the layout of the screen is to go to the submenu of your choice within Options->Looks and choose the "Hide" option. Whenever you want it to come back, click the "Show" option within the same menu, and that screen element will be redisplayed on the screen.
For convenience, items have been added to the Options menu to include the ability to hide everything except the keyboard, and also to show everything. This way you can toggle back and forth between using GTKeyboard primarily as a tool to insert text into other windows and using it as a simple text editor.
Currently, there are options to show or hide the following GTKeyboard screen elements: The keyboard itself, the toolbar, the bottom row of buttons, the text area where normal buttonpresses go, and the status area that tells you what is going on with the application. Using these, you can make GTKeyboard as small as you like. Note that when you hide the output text area, the bottom row of buttons is automatically hidden with it.
Once you've found a screen layout that you like, you can click on the "Save Layout" item underneath the Options->Layout menu. A file called ~/.gtkeyboard-layout will be saved that will be used to determine your keyboard layout for subsequent runs of the program. IMPORTANT NOTE: When you use this feature, it creates a file in your home directory called ~/.gtkeyboard-layout. It contains statements on how the application should be laid out. This file is read and used each time the application starts up, overriding any layout statements you may have in your ~/.gtkeyboardrc. To avoid this behavior, use the IGNORE_LAYOUT_FILE option, described in the configuration section. Also, if you wish for the application to stop using your layout settings permanently, you can use the "Forget Layout Settings" located just under the "Save Layout Settings" menu item in the Options->Looks menu.
In recent releases of GTKeyboard, a directory called "CONFIG" has appeared in the source distribution - it holds several different configuration files for GTKeyboard that seem to be used the most by various people. It has one file that enables all of GTKeyboard's features, one that makes the program appear only as a menu system and a small keyboard, and others. Please check those files out for different styles of layout to use the program with.
GTKeyboard allows you to use several different foreign character keyboard layouts to edit text in the text window of the application, but at the same time, it lets you direct characters to foreign windows. Remapping the keyboard is the way that you coordinate these two objectives.
X provides a way to change what each keypress on the keyboard does. In order to go from using an American keyboard to a German keyboard in a foriegn window, you first have to change the layout of your window to "DE" for German layout, and then you have to choose the option Misc->Remap Keyboard which will essentially change the function of just about every key on your keyboard. There are several very important things that you need to know about this process.
This error is generated when GTKeyboard tries to send a key to a foreign window that is not a key that X understands. In order to send nonstandard keys to redirect windows, you must remap the keyboard.
Starting in version 1.1, GTKeyboard provides a mechanism for word completion, similar to the mechanism provided by GNU readline. The only difference is that rather than working with commands, the word completion facility in GTKeyboard works with real English (or any other language) words. The word completion facility allows the user to type using the on-screen keyboard much faster than he/she would ordinarily be able to type, because GTKeyboard can fill the rest of the word in for you. The majority of the guts of the code for word completion was written by Dr. Tom tomh@po.crl.go.jp who allowed the code to be used in GTKeyboard.
In order to use the word completion facilities in GTKeyboard, you need to select the "New Completion Window" menu item from the Misc menu. A new window will pop up, containing ten numbered items with small arrow buttons on the right hand side of the rows.
This is the completion window. Whenever you type a new character into GTKeyboard, regardless of whether it goes to the text editing buffer or to a redirect window, the redirection window will "listen" to the character you press, and will suggest up to 10 words that start with what you typed.
If you wish to use on of the listed completions, simply click on the arrow icon to the right of the completion that is listed. GTKeyboard will insert the remainder of the word wherever your output was going. (That is, if you were using a redirect window, the completion will go there, otherwise it will go to the text editing buffer).
In the main word completion window, you will notice two check buttons. One is labeled "Show Empty Completion Slots&qout;, and the other is labeled "Insert space after completion".
The first option, "Show Empty Completion Slots" controls whether or not GTKeyboard presents you with empty options. This is merely a visual distinction - if this button is pressed down, then all 10 completion possibilities will be shown all of the time, even if one or more of them is empty. If this button is unchecked, then options that do not contain a valid completion will be hidden from view.
The second option is "Insert space after completion" which controls the way GTKeyboard completes words. Normally, if you type q and GTKeyboard suggests the completion quickening, when you choose to insert the completion, the result is "quickening", as it should be. If the "Insert space after completion" button is checked, instead of inserting "quickening" GTKeyboard will insert "quickening ". (The same word followed by a space character). For people who use this feature, it is to account for the fact that if a word is completed, the user will usually go on to type the next word rather than adding on to the current word. If that is the case, it can save time to insert a regular space for the user.
Word completion in GTKeyboard uses a special cache file that guides GTKeyboard in suggesting which word may be the most useful to insert given a particular set of characters. For example, when you type the letter "c", how does GTKeyboard know whether you're thinking of the word "cache", "communist", "catchy", "cantankerous", or any of the other hundreds of words that start with "c"?
Well, frankly, it doesn't. But it can take a good guess. This is what cache files are for. A cache file specifies a list of words with their frequencies. For example, in a text file about Darwin and Evolution, the term "evolution" or the term "species" may be quite common. The common terms are the terms that we want to appear first in the completion list given the beginning of the word. The frequency of different words provided by the cache file fits this role perfectly.
The default user cache file is located at
~/.gtkeyboard-wordcache. It will contain a list of an
arbitrary number of words with their frequencies in a given document.
Although the file is not meant to be edited by hand, its general form
looks like this:
5 above 1 absence 2 accept 1 acceptance 2 access 1 accompanies 1 accord 1 achieve 2 act 1 actions 2 add 1 additionSimply a number corresponding to the number of times the word occured in the document followed by the word itself. (The word "above" occurred 5 times, but the word "acceptance" occured only once) If this cache file were used in GTKeyboard, and the character "a" were typed, GTKeyboard would suggest 10 completions, from the most often occuring to the least often occuring. The way the words are ranked is by the frequency number found in the cache file.
When a new completion window is created, GTKeyboard will always load ~/.gtkeyboard-wordcache if it exists. If it doesn't, then GTKeyboard has to do the best it can, and usually loads the dictionary file. (This file is often located at /usr/dict/words on may GNU/Linux systems). While the dictionary file is not optimal, it still produces decent results depending on the application.
To load a new cache file into GTKeyboard's word completion facility, click on the "Load Cache File" button in the main word completion window. It will present you with a file chooser dialog. Once you hit "OK", the new cache file will be loaded in.
Users may find it interesting to have different cache files for different tasks to speed up the task at hand. For general text editing that doesn't really have a particularly well defined domain, using no cache file, (letting GTKeyboard use only /usr/dict/words) is usually best. For specialized tasks, such as Perl or HTML programming with GTKeyboard, a specialized cache file may be most helpful. For example, a Perl cache file that ranked the word "print" over the word "perfect" would be very helpful, since "print" is the name of a built in Perl function, and "perfect" isn't, even though it would occur more often than "print" if the document were a general text document.
Please note that you may find several different cache files which may be of use located in the cache/ subdirectory of the GTKeyboard documentation directory.
Creating word completion cache files is quite easy - simply choose the "Convert Text File to Word Cache" button located in the main word completion window. It will present you with a dialog asking you to specify which file is to be converted, and what it should be saved as. The default is to save the newly created cache file as ~/.gtkeyboard-wordcache, which will overwrite your previous word cache.
Using the browse buttons to the right of the entry areas, you may choose a filename to convert, and what to convert it to. Note that this process works only for text files. It will also work on any file you give it, but the results will most likely be an ugly, unusable cache. The cache file creation mechanism makes each block of letters it sees into a word in the cache. If you try to make a cache out of a bit of HTML such as "<P>This is a bit of HTML" the result will be a cache that looks like this:
1 <P>This 1 is 1 a 1 bit 1 of 1 HTML(Notice that GTKeyboard saw "<P>This" as a word, which you probably didn't intend)
You may also choose to click the toggle button below the entry areas, labled "Cache words in lower case" which will cause words in the cache to be all lower case. This can be helpful, since GTKeyboard would normall consider the words "Hello" and "hello" to be different words and would count their occurance seperately.
When you are done picking options, click the "OK" button, and the cache will be created. A status message signalling completion will be printed into the status window. Note: GTKeyboard does not automatically load newly converted cache files.
In addition to this method, there is a perl script distributed with GTKeyboard called gtkeyboard-create-cache-file. It is located in the same directory that the GTKeyboard binary was installed in. To use this program, call it with two arguments. The first argument should be the file to read from, and the second argument the file to save the new cache to.
By default, gtkeyboard-create-cache-file caches all words as lower case, and strips all punctuation from the words. Please note that using this additional program requires Perl, which is freely available from http://www.perl.com/.
GTKeyboard is also in the early stages of supporting HTML editing by way of the graphical user interface. In the HTML menu on the top bar of the application, you will find a menu full of different items, all corresponding to HTML tags. Clicking on any of the tagnames will cause the related tag to pop into the output text box at the bottom of the screen.
Some tags have mandatory input areas. Rather than pop up a dialog as other applications do, (which I happen to hate :) GTKeyboard prints the full tag out to the output section, and then places the cursor (or point) at the location where the FIRST input is needed.
Example: When clicking on the LINK item in the HTML menu, the following text is inserted into the output buffer:
<A HREF=""></A>
GTKeyboard will then place the point between the set of quotation marks, where the first input for the link is expected, i.e. the target of the link. (Note: Sometimes the cursor doesn't appear to be in the right place right after a tag has been inserted, but it is.)
Any tags that are not included in GTKeyboard can be added very quickly by simply requesting them. contact me and let me know which tag you'd like in GTKeyboard, and I'll add it. Alternately, write your own function to put into html_mode.c and send it to me
GTKeyboard already has a long list of supported tags. You can't find a complete list here, but here's a sampling of some of the most commonly used tags in super-unorganized format:
<HTML> </HTML> <BODY> </BODY>
<A HREF=""></A> <B> </B> <STRONG>
</STRONG> <I> </I> <BR> <HR> <P>
<UL></UL> <LI> <TABLE></TABLE>
<TD></TD> <TR></TR> <H1></H1>
<H2></H2> <H3></H3> <H4></H4>
<H5></H5> <H6></H6> <PRE></PRE>
<!-- HTML Comments --> <FONT COLOR=#""></FONT>
<FONT SIZE=></FONT> <BLINK></BLINK>
There are also a few "convenience" buttons that include FTP and HTTP which simply print out "ftp://" and "http://" respectively for quicker editing of links. There's even a "Close Anonymous Tag" for any closing HTML tag, that will print </> and put the cursor in the appropriate place for closing a tag off.
For those of you with special needs for HTML coding, or who want more possibilities, I suggest you check out the shortcut ability to define your own shortcuts.
GTKeyboard provides a method of doubling the output of any keystroke on the keyboard. In these situations, whenever the user presses a button on the graphical keyboard, it is both sent to the redirect window, (if there is one) and the normal text editing buffer.
This feature is used most often for people who want complete logs of their keystrokes. Normally, you would use this by hiding the editing text buffer, and typing as normal into the redirect window. When you're done with the redirect window, you can show the text buffer on the screen again which will contain a rough carbon copy of whatever you typed into the foreign buffer. This can be used as somewhat of a virtual "typescript" feature.
The option is toggled off and on through the use of the Options->Output->Double Output menu item. Alternatively, it can be specified through the resource file by using the SEND_DATA_TO_BOTH_WINDOWS option.
GTKeyboard provides a quick way to get to several commonly used networking applications as well. Under the Shortcuts->External Progs menu, there is a list of applications, containing Lynx, Telnet, and FTP. Selecting each of those items will launch the corresponding application. By default, they are launched inside of an RXVT terminal emulation window if that program is available.
The first thing that should be said under any heading in the manual for GTKeyboard is that if you don't see a shortcut in the menu that you would like to have, please email me and I'll see what I can do about building it into the program. They are very easy and quick to build in, and if you check what things look like in the shortcuts.c file and in master.h you may be able to add them yourself even. Even obscure ones are ok with me, because you can put the less used ones fairly deep into a branching hierarchy so it doesn't clutter things but is still there to speed up the process.
If you would like to use GTKeyboard for programming, no problem! The
shortcuts provided in the shortcuts menu should speed the entry of
programming code in just about any language. For example, in C, where
you might have to enter something like
#include <stdio.h>
there is a shortcut for the angle braces, that will produce < > and
position the cursor between the angle braces. You may also use the
quotation short cut for grouping text, and so on, so that if you were
to print the perl command
print "Hello World!\n";you can speed up cursor positioning and not have to hit the shift key and the " to produce the quotation marks.
There are many shortcuts that are available for the user to speed things up, from the most normal to some that are a bit strange, such as the smiley, which will automatically insert :). Play around with the shortcuts menu a while, and you'll definately find a bunch of shortcuts that can help speed up your work with GTKeyboard.
You can use these shortcuts to use emacs within a rxvt window, run make to compile the latest version of GTKeyboard, or do any number of other things.
If you are a user of GTKeyboard, and have no interest in developing on it, feel free to ignore this section.
Please, If you create any additions or modifications of this program, I would really appreciate it if you let me know, and if it seems reasonable, I will add it into the "official" release of GTKeyboard giving credit to you in the README and AUTHORS files as well as where the actual code is.
Compilation with debugging symbols is usually OFF by default. If you would like to change that, then just add the -g option inside of the CFLAGS variable in the main "Makefile". Different versions differ in policy about that. Along with debugging, there is an option in the help menu, under debugging, that is for you to be able to dump core if you want to. That's something I've used on and off, and it can be useful, so it was added in. I'm trying to force people to use that if they want a corefile, since hopefully it's set up so you can't get it to dump core any other way. :)
If you would like to compile with all debugging enabled, make sure that the symbol "PROD" is not defined in the Makefile, and recompile with "make static". (Note: Before you can "make static", you have to run "make obscure" which copies your static libraries into the foo/ directory, where it will link against them. If your static libraries are in different places, you'll need to copy them into that location.) With "make static", GTKeyboard will compile with static libraries, with calls like g_mem_profile() compiled in. (You did compile your glib/GTK+ with memory profiling, didn't you?) It will also print the result of various memory macros that are located in the include/ directory in mem_header.h. This causes quite verbose output, but in the end you get a total of how much memory has been allocated/freed by GTKeyboard. The g_mem_profile() call of course includes statistics on memory allocated by GTK+ as well.
Note that in the file include/memheader.h there are
several macros for tracking memory usage which won't really expanded
to much if debugging is not on, but if it is, sometimes to multiple
statements. Particularly the glib calls that end with an
underscore. Because they are multiexpression macros, you really don't
want to do something like:
if(mem)
g_free_(mem);
But rather do this:
if(mem)
{
g_free_(mem);
}
To account for the fact that it may or may not be a single replacement
line macro.
Also of interest to developers are the files INTERNALS and gtkeyboard-arch.txt located in the main directory of the source tree. They explain parts of the way the source works, to facilitate others in hacking on GTKeyboard. At the moment, that documentation isn't really all that great, but at least it's there, and it's something. If you would like to see any more specific information in that document, please write the section and submit it to s2mdalle@titan.vcu.edu for inclusion in the next version or let me know and I'll do the write up myself when time becomes available.
Extra debugging messages that are normally sent to stderr are also off for regular use as a program. If you'd like to see those messages, then make sure the symbol "DEBUGGING" is defined, for example, insert the line -DDEBUGGING=1 into the CFLAGS line of the Makefile. Then the program will compile with extra debugging messages letting you know what it's doing at any given time. Also, for a given version, defining TEMP_DEBUGGING will spit out debugging messages that have been recently added and so on. Finally, if you're paranoid about the way that keysym_callback() is working, (it is what drives the insertion of text into output_text widget) then define CONSOLE_OUTPUT and it will spit diagnosticts to stdout and stderr as it's needed. To enable all possible ugliness in the code, put the following in the CFLAGS variable in the top level Makefile: -DCONSOLE_OUTPUT=1 -DDEBUGGING=1 -DTEMP_DEBUGGING=1 -DV_DEBUGGING=1 and recompile. Also, if you define GUI_EVERYTHING in app.c, then write success/error messages will pop up in their own windows rather than just in the status buffer.
Probably the easiest part of GTKeyboard to hack on is to add HTML items. If you're interested, check out html_mode.c where you can add all of the new HTML tags that you want. You then have to edit master.h and edit the menu structure to include whatever function you put in there. If you're familiar with item factories, it's criminally simple. The same goes for shortcuts.c which I would like to see more shortcuts in. Basically when I code, I put in what I think people can use, and if anybody sends me a suggestion that gets put in to. In html_mode.c I use the function vanilla(char *input) which inserts into output_text heavily. That way, if I find I wanna redirect things later, I make some simple changes to vanilla and change where everything goes. Also I provided cursor_left_x_times(int whatever) so that you could repeat cursor_left() without having to set up for loops and extra variables. Just pass it the strlen(something) where something is usually the closing HTML tag. (html_mode.c has 1000 examples)
We're currently working on cleaning up the issues with remapping keyboards, and adding more keyboards, which may be somewhat slow. I incorporate user requests for features as long as they're reasonable. (Don't ask for a 3D graphics keyboard "visualizer" :)
And of course, the future brings the hope that I will ruthlessly eradicate any bug that I (or you) can find in GTKeyboard. As said, the redirection code is up for a rewrite, and when that happens, there may be some small issues to work out.
To successfully compile GTKeyboard, you need a few things. First, you'll need GTK+/glib (The GIMP Toolkit) which can be obtained from http://www.gtk.org, a standard C library, an ANSI C compiler, (such as gcc/egcs), the GNU make program, and of course, a shell, and a reasonably recent version of X11 (with headers). If you already have GTK+ installed, you shouldn't have much of a problem, since GTK+ and GTKeyboard share many prerequisites.
GTKeyboard is written and tested on a PII 233Mhz system running a variant of Red Hat Linux 6.1 (heavily modified). The program compiles with special flags telling the compiler to issue all relevant warnings, and compiles without any warnings on my machine. I have also compiled it on a few 64bit alpha CPUs with a few warnings, but no problem in the functioning of the resulting binary.
If you have problems compiling GTKeyboard, I'm betting that its one of a few things right off the bat: Do you really have an ANSI C standard compiler? If not, go grab a copy of GCC from the Cygnus EGCS page http://egcs.cygnus.com Previously, you would have also needed to have a libc that contained the strsep() call, but this requirement has been eliminated and replaced with glib calls.
If you have a compilation problem that you're sure is not one of the above, and you have all of the needed libraries/software to compile it, please mail s2mdalle@titan.vcu.edu and let me know about it, along with the exact output of the configure script, and of the make process, and a copy of your config.h file which will be generated at the end of the configure process.
When you ran the configure script, did you give it a --prefix=/my/home/directory argument? If you didn't, then GTKeyboard is going to install itself into /usr/local/bin/ by default, with the documentation in /usr/local/share/gtkeyboard. If you have problems installing, edit the Makefile, and change the PREFIX = line to wherever you want it to install. Failing that, just move the gtkeyboard binary to wherever you like, and copy the documentation wherever you like as well. (Some information popups look for the documentation in predictable places though, and if it can't find it there, it won't display properly.)
First, are you trying to insert text into a box within a window? If so, make sure that the box you want to redirect to is focused. (Just click on it once, and it should get a thin black border to let you know that it's focused).
Are you using xterm or XEmacs? Some users just have problems with that. See the section on redirecting to other windows for some notes on what will work and what will work with some special configuration.
Are you using an application that should work, but doesn't? Mail me and let me know about it.
(i.e. getting the application to look the way you want it to look)
The most common problem in this area is that a person will have spent a few minutes writing his/her ~/.gtkeyboardrc file to make the program look the way he/she wants it to, they start the application up, and the layout is totally different. What gives? Usually this is due to a ~/.gtkeyboard-layout file which the program is reading and using as your layout, ignoring your configuration file settings. If you'd rather use your configuration file to specify layout, use the IGNORE_LAYOUT_FILE option in your .gtkeyboardrc to tell the program to ignore the layout file. Restart the program, and everything should be peachy.
To customize the program's looks, your first stop is the the options section of the manual to see what's available. Then, check out the layout section to see what you can do in the way of showing/hiding different elements of the screen layout.
Other than that, if you've gotten GTKeyboard to a layout that you like, use the "Save Layout Settings" option in the Options->Looks menu to save it all to a file, ~/.gtkeyboard-layout. Please note though that this may cause the first problem in this section if you're not paying attention. :)
There are a lot of other features to GTKeyboard that aren't included in this manual that give you various degrees of freedom with the application. Among the (currently) undocumented features in GTKeyboard are the following that you can play with. Most that aren't described here are fairly straightforward. Actually, some are documented in the various README files within the source distribution, if you're interested.
There is a package similar to GTKeyboard available currently for Windows called EOSK the Extended On Screen Keyboard. As I understand, this package is available under the GNU General Public License, and is written in Delphi if my memory serves me right.
The buglist for gtkeyboard is bug-gtkeyboard@gnu.org for your enlightenment. It is a currently a mail alias, but may be a list in the future. Send all bug reports there. You will find a list of known bugs in the BUGS file in the main source directory. You may also send bug reports to s2mdalle@titan.vcu.edu.
The current bugs in GTKeyboard are usually small cosmetic issues, and sometimes minor annoying things that I'm working on currently or are planned to be fixed. There aren't any major stability issues that I know of. If you find one, email the bug list and let us know.
There should be a good number of very interesting things happening with the program in the future. I've gotten submissions from various people around the net of pieces of code that would possibly allow us to build in handwriting recognition and word completion against a fixed cache of words. There also seem to always be the calls for more customizeability which will possibly be added as we get the time to deal with them.
If you think you can do any part of GTKeyboard better, let me know and I'd love to get other people involved to speed up development. I'm also always totally open to suggestions for features. Whether they're incorporated or not has to do with whether I can code them, but I try hard to keep the users happy since this project is primarily for the users.
GTKeyboard is written in C, using the fine GTK+ toolkit available from http://www.gtk.org. It is written and tested on a RedHat Linux machine running a PII 233 Mhz processor, currently using XFree86-3.3.5. It has not been tested on other X servers to my knowledge, but if you have tested it successfully (or unsuccessfully) on another X server, please let me know. GTKeyboard is completely Free Software, licensed under the terms of the GNU General Public License. If you would like to reuse some of the code that is in GTKeyboard, feel free. I would appreciate it if you would mention my name in the list of contributors to the project that you include some of this code into - and most of all, that if you use any of the code from this program, you respect the fact that it is covered under the GPL...
The file COPYING that should come with the source distribution of GTKeyboard as well as any binary packages you may download contains the terms of the license. If you did not get a copy of the license with this program, you can either write me, David Allen, <s2mdalle@titan.vcu.edu>, or you can get in touch with the Free Software Foundation, at http://www.gnu.org/ for a copy of the license. Since it is under the GNU General Public License, I should probably tell you about...
Do not use GTKeyboard to run nuclear power plants, pilot aircraft, please your wife, start international war, blend fruits and nuts into a creamy shake, self-medicate, or as a treatment or cure for any disease. I have tried to make the program as robust as possible, but there is always the vague possibility that the application will suddenly start cursing at you in Russian or otherwise behave strangely depending on your platform, operating system, or configuration. GTKeyboard is written and tested on a hybrid Red Hat Linux workstation, with several other users contributing patches for interoperability with other operating systems including Solaris, and Linux/PPC.
And now less chicanery and what I really came here to say...
So, hoping that didn't scare you off, enjoy the program! If you enjoy the software, you can pay me simply by emailing me with your name, and where you live, and how you use GTKeyboard. You are of course not obligated to do that, I just enjoy hearing about where GTKeyboard has traveled, as I like to live vicariously through software. :)
Closing observations:
Useful GTKeyboard Links:
Other links:
Author Contact information:
M. David Allen
1108 W. Franklin St.
Apartment #206
Richmond, VA 23220 USA
Email: <s2mdalle@titan.vcu.edu>
Web: http://opop.nols.com
Document last updated: Sunday, May 7, 2000 18:13 to reflect GTKeyboard 1.1 - Weblinted for your reading pleasure, and written with (what else) The One True Editor Emacs
Thank you, drive through. EOF