# Welcome to Chatr!

Chatr is a World of Warcraft addon which makes private chats easier, simpler, more powerful and best of all actually intuitive by opening a new window for each conversation. This is reminiscent of (m)IRC query windows, MSN Messenger, AIM, ICQ, Jabber or other instant messaging systems. Also this is not an original idea - [ForgottenChat](http://ui.worldofwar.net/ui.php?id=1686) beat me to it a long time ago. Thank you for the inspiration! :)

Also, with the included Channeler plugin, you can actually chat on party, guild, raid, say and custom channels using Chatr.

Due to all the confusion, feature requests and such on ui.worldofwar.net I decided to write this documentation to clarify *all* the features in Chatr.

# Installation and Configuration

## Installing
Installing Chatr goes pretty much like all the other addons you see - just copy the folders contained in the archive file to your Interface/Addons folder. WoW will not recognize new addons unless it is restarted, so (re)start it now.

## Addons Window and Plugins
When you log in, you should see an *Addons* button in the lower left corner of the character selection screen. This will bring up the Addons window. If you scroll the list roughly to C (and have installed the addons correctly), there should be Chatr and a menagerie of accompanied plugins.

"Plugins?", I hear you cry. Chatr is modular. The core functions are provided by the addon named (surprisingly enough) Chatr, the rest are plugins. I would suggest you start off with all the plugins enabled, then disable what you don't need later. Also, if you deselect Chatr from the list, the Chatr plugins are disabled as well, as they require Chatr to be loaded. Simple, don't you think?

When you're overwhelmed enough by this, just click Okay and enter the world with the character you want.

# Using Chatr in Azeroth
Chatr notifies you of itself by telling you it's loaded in the chat frame. (Each plugin also does this.)

There's no real configuration that needs to be done (unless you want to), so just whisper someone. Lo and behold! A Chatr window pops up (or should ;) bearing the name of whoever you just whispered and whatever you just said. You can now use this Chatr window to chat with your buddy.

Below the main box (this is called the chatbox) there's the entry line (ahem, yes, this is called the entry line). When it's inactive, it's translucent, so if you think your screen has a funny horizontal smudge just there, it probably doesn't. If you click the entry line, it'll be focused and you will be able to type in it. When you press Enter, the message is sent. If you happen to press ESC, the box is cleared and defocused to allow you to, say, fend off Ragnaros, if that is what you happened to be doing.

The rest of the box? There's the multi-purpose close button in the corner.

*  If you left-click it, the window will close without a trace.
*  If you right-click (or shift-click, if your mouse only has one button), the window will minimize to a tiny box, or alternately, had it been already minimized, restore back to the normal version. This minimized box will turn orange if the person you were talking to has something to say. *You can also minimize windows by double-clicking their title bars.*
*  If you middle-click (alt-click) it, the window will dock (or undock). More information on the dock to follow.

Next to the close button is the M (menu) button. By clicking this, you activate a context menu with actions to

*  Invite the person to your group
*  Target and inspect him or her (not in BC/2.0)
*  Do a /who query (this is reflected in the title bar of the window)
*  Follow the person
*  Trade with the person (Hello, "water plz")
*  Duel with him/her and his/her pets

You can move the window by grabbing an edge or the titlebar. You can resize it by grabbing the little red resizer box in the corner. If you hold SHIFT while resizing, the size of the window is set as the new default size. To scroll the chat window, use the scrollwheel. There is (nor will be) any other way to scroll it. If you hold SHIFT while scrolling, the window is scrolled to the top or the very bottom.

# Docking
Ever used [Firefox](http://www.getfirefox.com) or any [other](http://www.opera.com) [Internet browser](http://www.maxthon.com/) [with](http://www.avantbrowser.com/) [tab support](http://www.netcaptor.com/)? ;) The dock does just this. All docked conversations show up as tabs, which are browseable by clicking on them or through keybinds.

As stated before, alt-click on a chat window close button to dock or undock it. Moving docked windows moves the dock (and the tabs, etc) instead. There's a small translucent red button next to the tabs. This is used to minimize and restore the dock. You can select the dock orientation (left, right or smart) as well as the tab positioning in the Chatr settings. (More on this later.)

# Settings and Slash Commands

## Slash Commands
Chatr provides several slash commands, but configuration is mostly done via a fancy graphical interface. The slash commands are (in usefulness order and ripped straight from */chatr help*):

Command               | Description
--------------------- | -----------
/chatr                | Opens the settings screen
/chatr on/off         | Turn new windows on/off (if you don't have any other way of seeing whispers, you might miss a couple...)
/chatr clear          | Closes all boxes
/chatr credits        | Toggles the credits screen :)
/chatr forget         | Resets remembered frame positions
/chatr reset          | Resets all options for all profiles
/chatr debug          | Turns debugging mode on and off
/chatr t              | Opens testing boxes
/chatr size <w> <h>   | Sets the default size to <w> x <h> (pixels)
/chatr pos <x> <y>    | Sets default position to <x>,<y> measured as an offset from the screen center
/chatr load <profile> | Loads settings from profile <profile>. (name@realm)
/chatr dm <text>      | A comma-separated list of window titles which will not be minimized in combat. Omit *text* to only show the current list
/chatr ghost          | Toggles ghost mode on and off.
/chatr pin            | Toggles focus pinning on and off.

## Settings
The settings window (opened via /chatr) provides pretty much everything you need for Chatr configuration.

On the left side of the window are the settings buttons provided by plugins. Clicking one of these will open the corresponding plugin option window. They are described in the plugins documentation below.

The first two boxes in the main window - Text Format and Note Format - are used to customize the way messages are displayed. The special *%X* symbols modify the timestamp, the *$...* ones denote the text.

The time symbols are as follows:

Symbol  | Description
------- | -----------
%a      | Locale's abbreviated weekday name.
%A      | Locale's full weekday name.
%b      | Locale's abbreviated month name.
%B      | Locale's full month name.
%c      | Locale's appropriate date and time representation.
%d      | Day of the month as a decimal number [01,31].
%H      | Hour (24-hour clock) as a decimal number [00,23].
%I      | Hour (12-hour clock) as a decimal number [01,12].
%j      | Day of the year as a decimal number [001,366].
%m      | Month as a decimal number [01,12].
%M      | Minute as a decimal number [00,59].
%p      | Locale's equivalent of either AM or PM.
%S      | Second as a decimal number [00,61].
%U      | Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]
%w      | Weekday as a decimal number [0(Sunday),6].
%W      | Week number of the year (Monday as the first day of the week) as a decimal number [00,53]
%x      | Locale's appropriate date representation.
%X      | Locale's appropriate time representation.
%y      | Year without century as a decimal number [00,99].
%Y      | Year with century as a decimal number.
%Z      | Time zone name (no characters if no time zone exists).

Currently, the text symbols available are:

Symbol  | Description
------- | -----------
$name   | Whoever talked. Not available for notes.
$text   | The message or note text.

Notes are, for example "Zerun is AFK (getting coffee, coffee is good)".

Next up are the color settings. These are simply used to set the color settings for chat boxes. Should be quite self-explanatory. After those is the font size slider. You set the font size with it. :)

Then you see a veritable plethora of checkboxes. These affect highly how Chatr behaves.

Setting                 | Description
----------------------- | -----------
Automatic /who          | Whenever a window is opened, a /who query is made to make it easier to see where the target is.
Automatic Fading        | If this is on, the Chatr windows turn translucent when your mouse is not on top of them.
Dock By Default         | All new windows will pop up in the dock instead of as free-floating windows.
Entry Box Inside Frame  | Inlines the entry box.
Execute Slash Commands  | Allows you to use "standard" slash commands inside Chatr. This does not include emotes, channel or whisper commands. Additionally, /me will be always be transmitted as-is through Chatr. Other Chatr users will see this "correctly".
Focus by Click          | Allows you to focus the edit box by clicking a non-active part of the chat box.
Minimize in Combat      | Minimizes all Chatr windows and the dock when you enter combat and restores them upon ending combat.
Open Minimized          | Opens new conversations as minimized Chatrs. Mutually exclusive with "Dock By Default".
Play Incoming Sound     | Will play the WoW default whisper sound whenever you get a whisper.
Sync Docked Sizes       | Whenever you resize a docked window, all other docked windows will be resized to that size too.
Vertical Dock           | The dock buttons will show up as a column instead of a row.

Right at the bottom is the "Save Per Character" checkbox. If this is checked, the set settings are saved only for the current character. Other characters (with no per-character profiles) will still use the global profile.

# Key Bindings

Chatr provides a couple of handy keybindings.

Keybinding               | Description
------------------------ | -----------
Focus Last Clicked Chat  | Focuses the entry box that was last clicked.
Open Chatr to Reply      | Opens a Chatr box to reply to the last received whisper (in the base UI)
QuickToggle              | Toggles the visibility of every Chatr box and dock on and off.
Dock: Focus Current Tab  | Focuses the entry box of the current dock tab.
Dock: Next Tab           | Browses to the next chat tab, wrapping around if needed.
Dock: Previous Tab       | Browses to the previous chat tab, wrapping around if needed.
Dock: Close Tab          | Closes the current dock tab.

# Plugins

As stated before, Chatr is modular, plugin-based and generally a lovely little widget to play around with. ;) Here listed are the plugins Chatr comes with.

## ChatrAlterEgo

ChatrAlterEgo adds alternate name support. This makes it possible to make your friends, despite their character names, _look_ like the same name. This will not open different characters to the same window, though. For example, if you have the lines "Foo:Steven" and "Bar:Steven" in your AlterEgo configuration, when Steven logs in as Foo and says "hi mate", you'll see a whisper window open with the title "Foo", but "Steven" in the main chat. When Steven logs in as Bar, ... check above.

Like ChatrCrayons and ChatrFilter, its configuration consists of lines in the format `<oldname>:<newname>`. Additionally, if *oldname* starts with a tilde (~), the rest of it is considered a Lua pattern that must be found in the name to match it. The lines are applied sequentially from top to bottom.

## ChatrBacklog

ChatrBacklog keeps track of your previous conversations over Chatr window closures. If you (accidentally) close the chat, Backlog will fill it with the latest 5 messages when next opened. Currently there are no options for ChatrBacklog except for the big red Clear button, which will (surprisingly enough) clear the Backlog buffer.

## ChatrBuddies

ChatrBuddies is a tiny little buddy list window plugin with a handful of neat features. The window is disabled by default, so you'll have to either use */chatr buddies* or the ChatrBuddies options window to enable it. When enabled, it will show up as a little box with the names of your online friends (or at least, the first 32 of them). If you mouseover one of these, the relevant information (current zone, level, etc) will be shown next to the name. If you double-click a name, a Chatrbox will pop up, already focused to the chatbox and ready to go.

The various color shades in ChatrBuddies are:

* White - online
* Gray - offline
* Blue - in your zone
* Dark Red - DND
* Orangeish - AFK
* Yellow - leveled up (be the first to congratulate ;)
* Greenish - Guildmate

These vary.

### ChatrBuddies Options

* Show Count - if you don't want a huge buddies box, limit it here.
* Show At Start - show the buddy list when you log in
* Show Offline - shows your offline friends as well
* Show Guildies - shows your guildmates (not counted in the buddies online/offline counter)
* Custom Labels - a comma-separated list of names or channels you want always to show up in the buddy list (but within the built-in 64 name limit).

## ChatrChanneler

ChatrChanneler has undoubtedly the best usability-to-configuration ratio in Chatr's plugins. It has absolutely no configuration, but allows you to chat in arbitrary channels, such as the party, raid, guild and officer channels as well as custom channels (/join *channel* style) in Chatr windows. To open such a chat window, either

* Set one up as a custom label in ChatrBuddies
* Use /chch *channel* (guild, party, raid, officer and say channels are "guild", "party", "raid", "officer" and "say").
* Use Chatr_OpenFor("#channel") in scripts

Easy as that.

## ChatrCrayons

If you want to customize the look of your Chatr frames, this is the best bet. ChatrCrayons (described as *Creative Coloring. Suitable for Level 3+, May Contain Small Parts*) allows you to set the border and background colors of your Chatr frames depending on their name, guild, zone or whether they are a friend of yours.

### ChatrCrayons Configuration

Crayons are set as lines in the configuration window for ChatrCrayons.

Lines starting with # are ignored. (For testing, or comments.)
The lines follow the format `<ident>:<mode>:<color>`.
Ident defines when the crayon is applied.

Ident    | Description                                                | Example
-------- | ---------------------------------------------------------- | -----------------
n...     | Name must match ...                                        | `nZerun` - name must be Zerun
g...     | Guild must match ...                                       | `gThe Great Foobars` - target guild must be The Great Foobars
zmatch   | In the same zone as you are                                | `zmatch` - they're right behind you
z...     | Zone must match ...                                        | `zAlterac Valley` - they're fighting in AV
friend   | They're a friend of yours (this requires Buddies enabled)  | `friend` - they're your chums!

Mode defines what part of the frame to change.

Mode     | Description
-------- | -----------
bo       | The border color
bg       | The background color
boa      | The border alpha value (transparency)
bga      | The background alpha value (transparency)

Color is either a RRGGBB (red-green-blue) [hex triplet](http://en.wikipedia.org/wiki/Web_colors) or a named color (there are a couple common ones included). For alpha value modes, the value must be a number from 0 to 1, zero being totally transparent and 1 totally solid.

Example: everyone from 'MyGuild' have an orange border: `gmyguild:bo:orange`

## ChatrFilter

ChatrFilter is probably the most versatile plugin in Chatr. It allows you to selectively ignore, modify, mangle etc. etc. the incoming or outgoing text. (However, this is merely visual. Outgoing text isn't *really* altered.)

### ChatrFilter Options

As with ChatrCrayons, ChatrFilter's configuration is basically a collection of lines which determine the behavior.

Lines not starting with I, O or * are disregarded.
The line format is as follows: `<Direction>:<Type>:<Match>:<Action>`

* Direction may be I (inbound) or O (outbound) or * (both).
* Type may be M (message), ML (message, lowercased) or N (name).
* Match is a [Lua pattern](http://lua-users.org/wiki/PatternsTutorial) to match against.
* Action may be one of the following:

Action      | Description
----------- | -----------
i           | Ignores the line (it never shows up for you)
s <pattern> | Substitutes the matched part with <pattern>.
r <text>    | Replaces the entire message/name with text.
l <lua>     | Runs the specified LUA code.
e <reply>   | Replies to the message with <reply>.

Examples:

* Filter "OMG" to "Oh gosh!": `I:M:OMG:s Oh gosh!`
* Never show anything with "DKP" (in any CaSe) that is whispered to you: `I:ML:dkp:i`

## ChatrShoo

ChatrShoo closes windows after a set period of inactivity. This is disabled by default; check the options.

### ChatrShoo Options

There's one slider here, which allows you to set the inactivity timer.

# Other Addons and Chatr

Chatr has built-in support for many Blizzard features and third-party addons such as

* Inventory/Tradeskill/Craft/AH linking - you can link items from wherever to Chatr
* EnhTooltip/Auctioneer/other tooltip mods - items in Chatr show up with proper information
* Fizzwidget's Linkerator - you can just use Linkerator as you would with any chat frame from Chatr
* Quest mods
  * MonkeyQuest
  * Quest-I-On (untested)
* Inventory mods
  * EnchantDB
  * EngInventory
  * All-in-One Inventory
  * Bagnon/Banknon


Additionally, I've been trying to hook as little functions as possible and generally tried to play nice all around. Chatr should cause *minimum interference* with other addons.

# Oft-asked Questions and Answers to Them

## Hey, my whispers show up in the chat panel as well! :(

Use the WoW chat frame options to disable them. Right-click the chat frame tab and find the "Whisper" option in the menu.

## If I bind a character-producing key to "Reply"/"Focus", I get that character in the entry box! :(

Actually, this has been cleverly worked around in WoW's interface source code as well, so you could say it's a known problem. Because I didn't want to include an OnUpdate handler (basically running code every frame -> slight speed decrease), I worked around this by using the [Chronos](http://ui.worldofwar.net/ui.php?id=1354) timing library. I've heard that there's been bad things being said about Chronos, but I assure you, it doesn't do bad things... like, for example, the Sky addon communication/chat system. (No offense, but ... Sky makes kittens cry.) So, if you don't want that character to pop up, just install Chronos.

## I can't link from my *non-standard inventory/tradeskill/item linking addon* :(

It's not supported. Drop me a line on ui.worldofwar.net.

## My Chatr windows aren't showing up properly! :(

Try */chatr clear* and */chatr forget* to clear the "last positions" table.


# Credits, Thanks, Contacting Me

## Credits

Coding and such by AKX. This project was started 23rd June 2006.

## Thanks and greets

* shouden, yacoob, Kovah, harl, Unne, toazron, Flarin, trefaes for suggestions, bug reports and such
* everyone who commented on ui.worldofwar.net
* YOU for downloading this addon
* Wrath, MHRC, Lost Order - wuv ya guys
* All my guinea pig posse at Moonglade, including but not limited to: Cleaver, Gha, Golkahar, Conall, Goren, Wara
* My guinea pigs on Steamwheedle Cartel
* ui.worldofwar.net for [hosting this damn thing](http://ui.worldofwar.net/ui.php?id=2766)

## Contacting the Author

* ui.worldofwar.net: [akx](http://ui.worldofwar.net/users.php?name=akx) - Feedback on this addon is preferred as [a comment here](http://ui.worldofwar.net/ui.php?id=2766)
* EU-Moonglade: Zerun (troll), Lethn (undead), Hooves (tauren, while developing)
* EU-Steamwheedle Cartel: Rainfall (NE)
* IRC: AKX @ QuakeNet / IRCnet
* Email: theakx at gmail dot com

## Other Stuff

* The HTML documentation is generated from the Readme.txt via [Markdown](http://www.michelf.com/projects/php-markdown/dingus/). Thanks for making it all so easy Michel (and Mr. Gruber too)
* Look!

# Changelog

## 0.3.7

- Shift-resizing a window will set the default size
- Some settings are now correctly loaded
- Smarter checkbox system
- Crayons: added color picker
- Autofading: All docked chatrs will now fade simultanioueousouesusueeusouly. That is, synced.
- Windows try to overlap each other less now. This may cause slight lag when opening windows at times and will spread out windows on the screen.
- Moving a docked window by the titlebar will now move the dock instead.
- Added Focus by Clicking option.
- Fixed Chronos missing bug.
- Added EngInventory support.
- Tradeskill linking should work now. Not tested on Enchanting yet, though

## 0.3.7b

- EngInventory support WORKS.
- Tradeskill and craft support works flawlessly.
- Added preliminary color code support. {{red}} {{green}} {{blue}}

## 0.3.7c

- Added Credits... /chatr credits :P
- Raised window limit to 20
- I can't reproduce the /nil/ bug - but I added some extra safety checks *shrug* Hope it works

## 0.3.7c2

- Fixed a silly bug.

## 0.3.7c3

- Removed experimental minimization code.
- DOCUMENTED THE DAMN THING! Seriously, this was the hardest thing since I started developing Chatr :D
- Silly version number, don't you think?

## 0.3.8

- Added "Open Minimized".
- May have fixed silly dock button bug.
- If Sync Sizes is on, new docked windows will adapt to the size of the first docked window..
- Added middle-click close button to dock/undock.
- Added character entry hook.
- Added AIOI support.
- Added "Don't Minimize" slash command (allows autohide exclusions).
- Added "Show Guildies" to Buddies.
- Hiked buddies limit to 64 O_o.
- Added AlterEgo plugin.
- Buddies will eliminate duplicate entries.
- Added FAQ to the manual.

## 0.3.9

- Added EnchantDB (or whatever) support
- Added auction frame linking support
- Beautified "set size from this frame".
- Filter: Added exact matching, edited help text.
- Added standard context menu for player names.
- Split hooks to a different file.
- Added pinning support (see the M menu)

## 0.3.9.1

- Really working EnchantDB support, I think.
- Added MonkeyQuest and untested Quest-I-On support.
- Pin slash command: /chatr pin
- Pin keybind
- Ghost mode: /chatr ghost or keybind
- Fixed trivial little buglet in Filter

## 0.3.9.2

- Fixed docked default size bug ^^
- Updated everything to 11200 (1.12)
- Added #say, #bg and #addon to Channeler.
- Made ghost more convincing.
- Fixed rather embarrassing bug with auction hooking.
- Probably fixed a bug regarding combat minimization and manual minimization.
- Own name now colorized as well.
- Note color setting works. (That's a long-standing bug no one has noticed. :D)
- Added dock tab background color. Ish?
- Added "topmost" option.
- Added "menu by default" feature.

## 0.3.9.3 (6 Dec 2006)

- BC/2.0 compatibility.

## 0.3.9.4 (30 Dec 2006)

- Fixed the tab text issue.

## 0.3.9.4.5 (10 Jan 2007)

- Fixed no incoming messages bug caused by new patch
- Fixed Shoo
- 20003 interface version