Text Bucket Help

You have 26 tabs to store your text on. To access a tab, just hit its letter (or use right and left arrow keys). Use tabs for logical grouping of text - maybe one for work, one for personal dev, one for scripts, and so on.
Each tab has 10 slots of text. Hit the number of the slot to access it. If it's empty, the current clipboard will be stored. If it's not, then the value will be returned to you, based upon the rules defined.		Invoke the app whenever you need it with the hotkey combo you defined (The default is cmd-opt-ctrl-B), or by choosing "Activate Text Bucket" from the Text Bucket Menu.
The buttons in the lower right let you do things. In order, they: Quit the app, Pin Text Bucket open, Bring up the Preferences, Bring up the Help, Delete the contents of a slot, and Begin editing a slot. Or, you can hit cmd-Q, cmd-`,cmd-,, cmd-?, -, and +, respectively.

To enable access for assistive devices -

1. First quit Text Bucket if it's already open. If you closed the window, you can double click on the icon to bring it back up.
2. Launch System Preferences
3. Choose "Universal Access" on the far right of the System line
4. Select "Enable access for assistive devices" on the bottom of the window.
5. Finally, re-launch Text Bucket after enabling it.

Setting up your first slot

1. Open your favorite Text Editor, such as TextEdit, included in your Applications/Utilities Folder.
2. Open a new document (and just leave it open, you'll want to have it for testing purposes.
3. Type in "Text Bucket is fun and easy", then select it.
4. Now, bring up Text Bucket via the hotkey (command-option-control-B, unless you changed it)
5. Type the letter "T" to bring you to the "T" tab.
6. Now press the number "7".
7. You'll see the slot get populated with the value "Text Bucket is fun and easy"
8. Alternatively, you can drag the selected text on top of slot 7 to place it there.

Copying out of a slot

1. Go back to your text document, or create a new one.
2. Now, bring up Text Bucket via the hotkey (command-option-control-B, unless you changed it)
3. Press the letter "T" to bring you to the "T" tab, where we previously set up the slot
4. Now press the number "7"
5. Since the slot already had a value in it, it's pasted into your open document at the current cursor location.
6. Alternatively, you can drag the contents of slot 7 to your document to place wherever you would like.

Deleting slot contents

1. Bring up Text Bucket via the hotkey (command-option-control-B, unless you changed it)
2. Press the letter "T" to bring you to the "T" tab, where we previously set up the slot
3. Next press the "-" key, or click on the delete button in the lower right. Text Bucket will enter Delete Mode You can also right click on the slot and choose "Delete this slot."
4. Now press the number "7"
5. It will prompt you to confirm deletion of slot T-7. Click Okay (or Cancel to keep it)

Advanced editing

1. Bring up Text Bucket via the hotkey (command-option-control-B, unless you changed it)
2. Press the letter "T" to bring you to the "T" tab, where we previously set up the slot
3. Next press the "+" key, or click on the edit button in the lower right. Text Bucket will enter Edit Mode. You can also right click on the slot and choose "Edit this Slot."
4. Now press the number "7". The editor window will pop up.
5. From here you can set additional options -
   • Title: - Normally, Text Bucket will put the value of the slot as its title. If you'd prefer, you can specify a descriptive title here that will be displayed instead.
   • Label - You may color code slots for ease of identification. Labels are configured in the Preferences.
   • Execute as... - Text Bucket slots can be executed as scripts. Instead of static content being returned, the output of the script will be used. This is for more advanced users.
   • Send results to clipboard - By default, the contents of the accessed slot will be placed on the clipboard. You can turn it off here.
   • Send results to calling application - By default, the contents of the accessed slot will be pasted into the calling application. So you can put text directly into your app without manually cutting and pasting. If you'd rather not do this, you can disable the option here.
   • Reprocess script output - Scripts can generate macro strings. If this option is checked, then the contents of the slot will be re-processed as a script as long as macros are being output.
   • Alert script output via Growl - If it's useful, you can alert the results of a script as a growl notification (requires Growl be installed on your machine). This may be beneficial if you are using Text Bucket as a controller to launch scripts for you.
   • Alert script errors via Growl - if your script prints anything to STDERR, processing will halt. if this option is checked, it will be displayed in a Growl alert.
   • Run script in the background - long running scripts will keep Text Bucket visible as long as they are active. If this option is checked, then Text Bucket will hide immediately once the script starts. Only use this for long running scripts.

Macros

Text Bucket contains several useful macros to help customize script output. The parse strings can be configured in the preferences.

• S#SELECTION# - this string will be replaced by the currently selected text, or if no text is selected, then by the contents of the clipboard.
• C#CLIPBOARD# - this string will be replaced by the current contents of the clipbard.
• M#MACRO# - Any text between M# and # will prompt the user to type in that value.

  • For example, if your slot contents were:

    drop database M#DATABASE#; create database M#DATABASE#; import database M#DATABASE# < M#DATABASE#.mysqldump

    Text Bucket would prompt you to type in the value of DATABASE. For sake of example, let's say you typed in "Test123". It would then would return:

    drop database Test123; create database Test123; import database Test123 < Test123.mysqldump

  You can also specify a default value with an equals sign = M#NAME=VALUE#. This will prompt you to specify a value for "NAME", and will pre-populate the text field with "VALUE". Even if a macro is re-used multiple times in the slot, you only need to specify the default once. If it is specified multiple times, then the FIRST default found will win.

• S#T-7 - Will replace the string with the current contents of that slot. Any macros or script execution performed by that slot will be done before replacement. Specify whichever slot you would like to substitute.

More advanced Macros

To really see a the macro functionality in action, let's work through a more elaborate example. As a Cocoa developer, who for sake of example we will assume is writing code in the older Objective-C 1.0 style, you'd write a lot of code like this:

-(id) foo { return foo; } -(void) setFoo:(id) newFoo { [newFoo retain]; [foo release]; foo = newFoo; }

It's very tedious doing that over and over and over again. So we can use Text Bucket to help us. Open up Text Bucket, and choose an empty slot. For example purposes, let's say we're using slot A-8. So hit the letter "A" to jump to tab "A". Next hit "+" to go into Edit mode (or hit the "+" button), and then type the number 8 (or click on that slot). Once the editor is up, type this in:

-(id) S#SELECTION# { return S#SELECTION#; } -(void) setS#SELECTION#:(id) newS#SELECTION# { [newS#SELECTION# retain]; [S#SELECTION# release]; S#SELECTION# = newS#SELECTION#; }

You can also give the slot a meaningful title, such as "method accessors". Click the save button when you're done.

Now, pop over to Xcode (or your Text Editor of choice), and type in the name of your attribute. Let's say that it's "bar", for our example. Highlight the word "bar", and then bring up Text Bucket (cmd-opt-ctrl-B). In the Text Bucket Window, type and "A" to make sure we're on tab "A" (we should still be there from when you closed the window), and press 8. Voila! Your single word "bar" should now be replaced with:

-(id) bar { return bar; } -(void) setbar:(id) newbar { [newbar retain]; [bar release]; bar = newbar; }

Ta da! Much simpler than constantly retyping that boiler plate code. But, unfortunately, it's not quite right. The mutator is named "setbar" and we wanted it to be "setBar". The new variable in there is also called "newbar", and we wanted "newBar". Fortunately, this is straightforward to deal with as well, but it's a little more than the built in macros can handle. Instead, we'll execute the contents of our slot as a perl script. Open up the slot in the editor again, and put this in:

use strict; use warnings; my $accessor = "S#SELECTION#"; my $mutator = "set" . ucfirst($accessor); my $newVar = "new" . ucfirst($accessor); print qq[ -(id) $accessor { return $accessor; } -(void) $mutator:(id) $newVar { [$newVar retain]; [$accessor release]; $accessor = $newVar; } ];

Learning Perl is left as an execise to the reader. In a nutshell, this reads in the value of our selection, and then uses that to create variables for the mutator and new variable, by uppercasing the first letter.

Before you close the editor window, be sure to tell it to execute as a Perl script. In the pop up below the main editor field, it says "Do not execute as script". Click on it, and choose "Execute as Perl script" instead.

Now, go back to Xcode, type and highlight "bar" again, invoke Text Bucket, and you get:

-(id) bar { return bar; } -(void) setBar:(id) newBar { [newBar retain]; [bar release]; bar = newBar; }

Much nicer, and in proper style. But there's one last thing we can do. This is just setting the attribute type to id, but we may have a specific value in mind. Of course, we may not, so just using "id" may be sufficient. We can set up a macro for the type to handle this for us. Go back to your editor, and update the script to be this:

use strict; use warnings; my $accessor = "S#SELECTION#"; my $mutator = "set" . ucfirst($accessor); my $newVar = "new" . ucfirst($accessor); print qq[ -(M#TYPE=id#) $accessor { return $accessor; } -(void) $mutator:(M#TYPE#) $newVar { [$newVar retain]; [$accessor release]; $accessor = $newVar; } ];

We just changed the two references to "id" to be macros - "M#TYPE=id#". Same drill, go back to Xcode, type and highlight "bar", invoke Text Bucket and hit slot 8.

This type, you got a prompt asking to know the type of the attribute, with the value "ID" already inserted. Change it to whatever you want, let's say "NSString*" and hit the go button (or press cmd-return):

-(NSString*) bar { return bar; } -(void) setBar:(NSString*) newBar { [newBar retain]; [bar release]; bar = newBar; }

And voila! A generic accessor from boiler plate template code that you can insert anywhere, for any type.

Of course, if you'd rather not write Text Bucket scripts in Perl, you can use any other language. References for Python, Ruby, and AppleScript are also built in, and these can be changed in the Preferences if you're just a die hard TCL user and want to include that.

Finally, if you invoke that slot without selecting any text (or if Text Bucket was unable to find it, for some reason), then it'll just prompt you for the selection instead.