Welcome to Twit Menulet

Twit Menulet is a simple, fun, and powerful Twitter client for Mac OS X.  We hope you will have as much fun using it as we had writing it.

1. Getting Started

To use Twit Menulet, you must have a Twitter account.  If you don’t have one, visit http://twitter.com and sign up.

When first started, Twit Menulet will ask for your Twitter account credentials.  The Twitter Accounts table will be opened automatically.  Enter your Twitter user name and password.  The message “Downloading tweets…” will be displayed in the menu bar and then, shortly, a tweet will be displayed instead.

2. Tweets in the menu bar

Twit Menulet displays one tweet in the menu bar at a time.  When the menulet has sufficient width, the posting user’s icon is displayed to the left and the text of the tweet is displayed to the right.

The first tweet displayed is the oldest of the downloaded tweets (but Twit Menulet will “fast-forward” to avoid tweets more than 24 hours old).  Twit Menulet will then step through your tweetstream, displaying more and more recent tweets on a schedule designed to get through them before the next scheduled download.

New tweets are initially collected from Twitter every 50 seconds.  This schedule is then adjusted to in response to collected tweets; e.g., if no tweets are collected then the interval is extended slightly.  Conversely, collected tweets prompt a decrease in the interval. 

Normal tweets are displayed in the system font; direct messages are displayed in italics.

3. The drop-down menu

Click on the menulet to display the drop-down menu.  This menu lists your tweets for easy viewing, with the most recent tweet at the top.  The menu items listed include:

• “Tweet…”

Choose this item to send a tweet!  Choosing it opens a new panel with a text box for sending.  See the section below titled The “Send a Tweet” panel.

• The tweet list

Up to twelve tweets are displayed in the drop-down menu.  The posting user’s icon is displayed at left and the text of the tweet is displayed at right.  If somebody has responded to the tweet, then an envelope icon is displayed to the left of the user icon.

Selecting a tweet in the list and releasing the mouse will open the last link shown in the body of the tweet.  To visit other links listed in the body of the tweet, open the submenu associated with that tweet.  Whenever a tweet contains more than one link (including @ mentions, hashtags, and StockTwits-style stock symbols), the links will be listed under the “Visit links” submenu.  See the section below titled Per-tweet submenus.

• “More tweets”

This item contains a submenu with up to 30 tweets that didn’t fit on the main drop-down menu.  The submenu, too, may contain a “More tweets” menu.  There is no limit to the number of tweets that Twit Menulet can display.

• “Preferences…”

Choose this item to open the Preferences panel.  This panel contains a variety of user settings, including the width of the menu bar item and its font size.  See the section below titled The “Preferences” panel.

• “Quit Twit Menulet”

Choose this item to quit the program and remove the menulet from the menu bar.

4. The “Preferences” panel

The preferences panel is displayed after choosing “Preferences…” from the main menu.  The panel is divided into three tabs: Preferences, Twitter Accounts, and Lists.  The Twitter Accounts tab contains a table that can accommodate the user information for all your Twitter Accounts.  Press the “+” button to add another account; edit the user name and password directly in the table.  Similarly, the Lists tab contains a table showing all the lists to which you have subscribed.  Press the “+” button to subscribe to a new list and then enter the list specifier in the table.  The list specifier contains the screen name of the list curator (e.g., “bettydraper”), a forward slash (“/”), and the name of the list itself (e.g., “rolodex”).  Therefore, @bettydraper’s list called “rolodex” should be entered into the table as “bettydraper/rolodex”.

The Preferences tab allows you to customize Twit Menulet’s behavior:

• “Item width” sets the width of the menulet (in pixels) as it appears in the menu bar.

• “Font size” sets the size of the scrolling text that appears in the menu bar.  The size of the text in the drop-down menu cannot be set by the user.

• “Show icon only” restricts the menu-bar display to the icon of the user posting the current tweet.  No scrolling text will be displayed when this option is selected.

• “Open at login” adds Twit Menulet to the user’s list of Startup Items.  Twit Menulet will be started automatically whenever the user logs in.

• “Show sub-menus” controls whether each tweet has a sub-menu with various options for responding to the tweet or exploring its contents.  For example, when this option is selected, a user can post a retweet by simply selecting “Retweet” from the tweet’s sub-menu. See the section below titled Per-tweet submenus.

• “Open links in background” indicates whether the user’s browser will be brought to the foreground when a link is followed.  When this option is selected, the browser will not be brought to the foreground and the user must use the Application Switcher (part of MacOS) to view the link content.

• “Show replies in main menu” controls whether tweets that are posted in reply to another tweet are shown in the main drop-down menu, or are only shown in the per-tweet submenus (under “Replies to this tweet”). See the section below titled Per-tweet submenus.

• “Cache tweets on local drive” tells Twit Menulet whether to archive all the tweets you send and receive.  The Tweets are archived in the directory ~/Library/Application Support/Twit Menulet/Tweets. “Max number to load” indicates how many tweets should be loaded from the archive.

• “Auto-navigate to last tweet” indicates if Twit Menulet should move to the last tweet with which you interacted when next opening the menu.  This preference is useful if you wish to continue browsing through the tweetstream from a point deep in the menu hierarchy.  For example, suppose you decide to retweet a tweet that appears in the fifth “More tweets” menu and then wish to continue browsing from that point backward in time.  If this preference item is selected, then Twit Menulet will automatically navigate to the re-tweeted tweet, so that you do not have to navigate the menu hierarchy again.

• “Show byline and date” controls whether the tweet author and sending time are shown on each tweet.  When this preference item is selected, this information will be shown in light gray text at the lower right of each tweet.  Note that these items are only shown when there is sufficient space to display them.

5. The “Send a tweet” panel

The “Send a Tweet” panel appears after choosing “Tweet…” from the main menu.  The panel is dominated by a text box.  Type the text of your tweet in this box.  The number of characters remaining before reaching Twitter’s 140-character maximum is shown at upper right.  The “Send” button is located below the text box.

When you have entered more than one Twitter account in the Twitter Accounts panel, the “Send” button will be replaced with a “Send as” button that is juxtaposed with a popup menu allowing you to choose the account for sending.

When more than 140 characters are entered in the text box, Twit Menulet gives you the option to send your text as a “long tweet” (a checkbox appears beneath the text box labeled “Send as a long tweet”).  Leave this box check to send your text as a single “long tweet” than can be properly displayed by Twitter clients that follow our specification.  Clients that don’t follow the specification will display two or more consecutive tweets separated by ellipses.

If you have a URL in your tweet that you would like to shorten with bit.ly, control-click (i.e., right click) on the URL.  The first item in the popup menu will read Shorten with bit.ly.  After choosing this item, the URL is replaced with the shortened bit.ly link.

To send a direct message, use the official Twitter format: type the single letter d (in lower case), a space, the screen name of the recipient (without the @ symbol), and the message itself.

6. Per-tweet submenus

Each tweet displayed in the drop-down menu is linked to a sub-menu containing common actions to be taken.  These per-tweet submenus can be hidden by un-checking the “Show sub-menus” item in the Preferences panel (see the section above titled The “Preferences” panel.)  The options shown are:

• Retweet.  Choosing this item opens the “Send a Tweet” panel and fills the text box with a standard retweet: the letters RT followed by the sender’s screen name, a colon, and the text of the tweet.  Edit the text if desired and press Send.

• Retweet verbatim.  Choosing this item opens the “Send a Tweet” panel and replaces the text box with a “native” retweet.  Native retweets have some advantages over “organic” retweets (the first option described above).  Most importantly, your followers will see only one copy of each native retweet, regardless of how many times it is retweeted.  In addition, the authorship of native retweets is properly attributed to the orginal author.  However, native retweeting does not allow you to make any edits or additional comments to the original tweet.

• Reply to this tweet.  This item also opens the “Send a Tweet” panel but fills the text box only with the sender’s screen name.  Add the text of your reply after the sender’s screen name and press Send.  Twitter is informed that the tweet you send is a reply to a specific tweet.

• Forward via e-mail.  This item prepares a new e-mail in your standard e-mail software.  The subject is set to “Check out this tweet” and the body is filled with a standard message stating the screen name of the tweet’s sender, the text of the tweet, and a link to the status’s page at Twitter.

• Visit links.  This item only appears if the tweet contains more than one link.  When the tweet contains a single link, simply choose the tweet itself from the main drop-down menu to open the link automatically in your browser.  When the tweet contains multiple links, use this sub-menu item to choose a link for opening.

• Direct message @thesender.  Choosing this item prepares a direct message in  the “Send a Tweet” panel: the text box is pre-filled with the lower-case letter d, a space, and the screen name of the recipient.  Add the text of your direct message and press Send.

• Show only tweets from @thesender.  This item filters your tweetstream to show only tweets sent by the sender of this specific tweet.  Use this item to see a history of postings by a single user whom you follow.  After choosing this item, a new item will appear in the main drop-down menu: “Show tweets from all users”.  Choose this item to again show your entire tweetstream.

• Filter tweets from @thesender.  Choosing this item removes tweets from this sender from your tweetstream.  Use this item to temporarily hide tweets from users who are posting tweets that are not of interest to you. After choosing this item, a new item will appear in the main drop-down menu: “Show tweets from all users”.  Choose this item to again show your entire tweetstream.

• Unfollow @thesender.  Use this item to unfollow the sender of this tweet.  Note that this item only issues the unfollow command for one account (whichever account was used to download the tweet).  If you follow the sender from multiple accounts, then tweets from the sender may continue to appear in your tweetstream.

7. Global hotkeys

Twit Menulet implements global hotkeys to allow easy, direct access to the tweetstream at any time:

• Option-command-right arrow: opens the “Send a Tweet” panel.  For example, to send a tweet when browsing the web, you might (i) select relevant text; (ii) press Cmd-C to copy; (iii) press Opt-cmd-right arrow to open the Send a Tweet panel; (iv) press Cmd-V to paste; (v) edit and send.

• Option-command-down arrow: shows the tweetstream by opening the Twit Menulet menu.  While working in another application, for example, if you wish to check the tweetstream, press Opt-cmd-down arrow.  To close the menu again after viewing, press Return.

• Option-command-left arrow: toggles display of scrolling text in the menu bar.  Display of scrolling text in the menu bar is often desirable, but can occasionally be distracting.  To remove scrolling text and show only the miniature icon for the current tweet, press Opt-cmd-left arrow.  To show scrolling text again, press the same key combination.

• Standard menu control combinations.  Twit Menulet supports the normal keyboard combinations that control menu navigation in MacOS.  Most importantly, these include: (i) opt-down arrow to move to the last item in a menu; (ii) right arrow to open a submenu; (iii) left arrow to close a submenu; (iv) up and down arrows to navigate between menu items; and (v) return to execute a menu action.  These combinations allow easy control over Twit Menulet from the keyboard.  For example, one could open the menu with Opt-cmd-down arrow, browse to an interesting tweet with the down arrow, and press return to follow an embedded link.  Alternatively, one might open the menu with Opt-cmd-down arrow, press Opt-down arrow to go to the last item, press up arrow to get to the “More tweets” item, and press right arrow to open the “More tweets” submenu.