Text Grabber
~~~~~~~~~~~~

An OmniDesk Utility
by Richard G. Hallas

Text Grabber is a very versatile utility for transferring text around the desktop. It can be used to copy text between virtually any two text areas, and there is no limit on the amount of text that can be handled. Therefore, Text Grabber can also be used as a kind of extra clip-board for text which is external to your word processor.

Its use is slightly more complicated than might at first be apparent, and will be dealt with shortly.

Clicking Menu over the Text Grabber window presents the main utility menu:

'Info' leads to a standard information window.

'Clear text' will make Text Grabber lose the text it currently knows about, and release the memory which it was occupying.

'Type text out' makes Text Grabber type the text to the caret, just as if it were being typed at the keyboard. The menu item will be ticked whilst this is happening, and you can stop the process before it has finished by choosing the menu item again. If there is no caret, the computer will simply beep. Note that whilst Text Grabber is typing text the keyboard is still enabled, so if you type something yourself it will mix in with the text from Text Grabber. Also, if you move the caret, the typed text will of course follow it.

'Window position' leads to a window which lets you determine where the Text Grabber window appears on the screen. This corresponds to an invisible grid, and when you change screen mode the window will snap to this grid. (This feature can be disabled by clicking Adjust on the small window icon, which makes it disappear.)

'Save text' lets you save your grabbed text out as a file.

'Save settings' will save the screen location of the Text Grabber window.

Using Text Grabber
~~~~~~~~~~~~~~~~~~

Grabbing
--------

Text Grabber can take text from two sources: icons on the desktop or text files saved into it. Saving text into Text Grabber is a simple matter of either dragging a file onto its window from a Filer display, or marking some text in your word processor (etc) and dragging the file icon from the save (or save selection) window into TextGrabber.

In order to grab text from icons, you must use the 'Grab text' button. When you click on this, the pointer changes into a hand with a pointing finger. Move the finger to the text you require, and click. With any luck, the text you pointed to will appear in the TextGrabber window. Unfortunately, due to the way the desktop works, this cannot be guaranteed. Some bits of text which look as though they ought to be icons are not icons at all (for example, files in Filer directories) and cannot be grabbed.

Text Grabber can, in fact, grab sprites! For example, if you click on the 'Grab text' button and follow it by pointing on the Palette utility icon on the icon bar, you will see "palette" (the name of the sprite) appear in the Text Grabber window.

As well as text and sprite icons, Text Grabber can also grab the contents of window title bars. This is very useful for extracting full path-names from Filer windows.

Note: Although Text Grabber can hold any amount of text (memory permitting), only a small portion of text can be displayed in the Text Grabber window. As much text as can fit will be shown, and if some overflows an arrow () will appear at the end. In some rare cases the displayed text can overflow the display area. This looks messy, but is nothing to worry about (and is unavoidable).

Also note that Text Grabber filters out control characters, and displays carriage returns as '' to save space. When exporting text, carriage returns are preserved but other control characters are not.

Exporting
---------

Exporting text is slightly more complicated than grabbing. There are four ways of exporting text: transmitting, injecting, saving and typing. In order:

'Transmitting' text: When you click Select on the 'Export button', the text in the Text Grabber window will be sent to the caret instantly. This is the normal method of operation.

'Injecting' text: This is the exact opposite of the way the 'Grab text' button works. If you click Adjust on the 'Export' button, the pointer will change into a pointing hand, with which you then indicate to Text Grabber where you want the text to go. If you point at the background of the window containing the caret, Text Grabber will behave just as though you transmitted the text to the caret in the normal way; otherwise it will try to inject the text into the icon you pointed to. This is less likely to work than the grabbing equivalent, as many icons are 'read-only'.

'Saving' text behaves in exactly the same way as any other application: you open the Save window from the main menu, and drag the file to where you want the text to go. If you are dragging to another application (rather than a Filer directory), RAM transmission is used so that the operation is very fast.

'Typing' text is for cases where none of the above work. Choose the 'Type text out' option from the main menu, and Text Grabber will type it for you. This is the least preferable option as it is the slowest, and is susceptible to accidents if you continue to use the computer whilst it is operating.

IMPORTANT NOTE: When using the 'inject' feature, it is important to remember that this is NOT the same as trying to save a text file into an application. For example, if you dragged a text file to the Edit icon, Edit would open up a window containing the file. However, if you used the Text Grabber 'inject' feature, Text Grabber would attempt to insert the text into the Edit ICON itself. This kind of activity is unpredictable at best. With the Filer icons (which have text beneath them) it works fine. Often, with other icons, you will get a message from Text Grabber saying "inappropriate destination". However, if you try this with Edit (and a few other applications) the icon will vanish from the icon bar (although the program will still be running). There is nothing Text Grabber can do in this situation to find out what will happen. The thing to remember is that you are very unlikely to want to 'inject' text into a sprite icon, although it is possible to do so. 'Inject' is the most 'dangerous' kind of export.

Hot-keys
--------

Hot-keys play a very important part in Text Grabber. As well as duplicating some of the functions mentioned above, they also provide a couple of extra features which are not otherwise available.

There are four hot-key combinations:

        CTRL-COPY: This is similar to the 'Grab text' button, but works instantly, and grabs the text under the pointer.
  CTRL-SHIFT-COPY: In one move, this key-press grabs the text under the pointer and sends it straight to the caret.
      CTRL-INSERT: This is similar to the Adjust-'Export' button, but works instantly, injecting the text into the icon under the pointer.
CTRL-SHIFT-INSERT: This is the same as the normal 'Export' function, and sends the grabbed text straight to the caret.

It is possible to grab text from menus, but only by using the CTRL-COPY and CTRL-SHIFT-COPY hot-key combinations. Although you can click on 'Grab text' and then point to an open menu structure, as far as Text Grabber is concerned, the menu will be closed before it can grab the text. However, using the hot-keys should usually be successful.

Remember that if another application has "input focus" (its title bar is cream) it may intercept some of Text Grabber's hot-keys, preventing them from working. To make them work again, you could choose "Turn caret off" from the OmniDesk Utilities menu.

WARNING
=======

Every possible effort has be made to ensure that Text Grabber functions correctly and does not cause the computer to crash, and it is unlikely that any problems will be experienced with its use. Illegal actions simply result in warning messages from Text Grabber. However, Text Grabber performs some unusual functions, and the 'inject text into icons' facility is potentially capable of causing the program it is used on to crash. Therefore, use this facility with caution.

For RISC OS 2 users, there is one potential way of making the utility crash, although the circumstances are highly improbable: if you try to grab the contents of a title bar of a window which is more than 32K in size, then Text Grabber may crash. However, this would require the window in question to contain a vast number of icons (they only take 88 bytes each), and so it is highly unlikely that it would happen. This problem will not occur under RISC OS 3, since an extension to the operating system has allowed the situation to be circumvented.
