[ChosensHelper 1.1 readme.txt file (2008-10-07).]

ChosensHelper is a Warhammer Online addon for management of Chosen auras.
Copyright 2008 by Peter Kirby (email <peterkirby@gmail.com>)

This is the readme.txt for ChosensHelper. It may NOT be the latest
information for the ChosensHelper addon. For the latest information,
always refer to the curse.com description page:

http://war.curse.com/downloads/details/13736/

Also refer to the description and downloads at curseforge.com, which are
always updated at least a few hours more quickly. This is also the easiest
way to submit a bug report for ChosensHelper. Report bugs FIRST, comment on
the curse.com main page ONLY if the bug is confirmed as an issue... and
even then, it should be added to the known issues anyway!

http://war.curseforge.com/projects/chosenshelper/

The first video for using ChosensHelper was created in October 2008 using
the 1.01 version of the software. It may be quite a bit out of date, and
it may not have the most optimal advice for setup, but it is at least
fairly easy to diget...being a visual aid. The current link for this
video and any other videos will be found in the curse.com description.

0.0 VERSION NUMBERS
1.0 INSTALLATION
 .1 Dependencies
 .2 Install Folder
2.0 SETUP
3.0 USAGE: /chosen command
 .1 usage, help, dumpdata
 .2 nospam
 .3 toggledisplay
 .4 sound
 .5 setbar
 .6 start
 .7 + and -
 .8 stop
 .9 resume
 .10 reactiontime
 .11 using "chosen" commands within macros
 .12 stuff to mess with only if you're brave
4.0 WHEN THINGS GO WRONG
 .1 What the Author Already Knows Will Likely Go Wrong
 .2 What to Do if You Have Found a Unique Way to Make Things Fail
5.0 SOFTWARE LICENSE

~~~~~~~~  0.0 VERSION NUMBERS ~~~~~~~~~~

Every release, beginning with 1.10, has a major version number and an
extra minor version number. The major version number for 1.10 is 1.1.
The last digit is a minor revision number, which is even for a "stable"
release or, at least, a release that I think users should defintely install.
The last digit is odd if it is a beta release. Starting with the 1.11 beta,
there will be several different code files released under the 1.11 version
number, but the 1.10 files and the 1.12 files will never change.

The ChosensHelper.mod file will always have the major version number (such
as "1.1") so that your settings from 1.10 will stick when 1.12 comes out.
But they will break when 1.20 (a major revision) comes out, if ever.

Please be sure to upgrade to the latest stable "release" version of the
addon. You can always find the latest stable "release" version on curse.com
but you can get it just a bit earlier through the curseforge.com project
page for ChosensHelper.

The first release (0.9) and the subsequent three releases (1.0, 1.01, 1.02)
followed no particular numbering scheme. They've all now been marked beta.
Using any of them is deprecated.

~~~~~~~~  1.0 INSTALLATION  ~~~~~~~~

It's pretty straightforward if you're not new to addons.

~~~~ 1.1 Dependencies ~~~~

ChosensHelper Aura Twister REQUIRES LibSlash addon.

Get it at http://war.curse.com/downloads/details/13510/.

~~~~ 1.2 Install Folder ~~~~

To install, put the ChosensHelper folder in the Interface/Addons directory
of your Warhammer installation. A fresh Warhammer install does not have this
folder. You must create the folder "interface" and within it the folder
"addons," and in that folder you place the folders (such as "ChosensHelper")
for your addons. Here are two examples of potentially valid paths:

C:\Games\War\interface\addons\fooAddon
D:\Program Files\Electronic Arts\Warhammer Online\Interface\AddOns\fooAddon

Note that none of these folder paths are case-sensitive and that the "war"
folder can be named anything as long it is where the war.exe file that
launches the game can be found. If you need more help than this with
installation, you should probably visit the WarhammerAlliance UI Discussion
board, especially this sticky thread with many FAQ's answered:

http://www.warhammeralliance.com/forums/showthread.php?t=67885

The curse.com description page for each addon also has a tab called "Install"
with their directions for installing Warhammer Online addons, with a link to
the "Curse Client" that may optionally be used for install.

You will see a message about using the "/chosen" command to activate the
addon upon loading your Warhammer user interface if installation was
successful. It should also display a version number upon loading, perhaps
even the correct one for the version you downloaded!

~~~~~~~~ 2.0 SETUP ~~~~~~~~

This (or maybe usage) will be the hardest part for most users.

There is more than one way to do it.

The basic idea is that the same slot of several different actionbar pages
will have different Chaotic Aura abilities. So it should look like this:

PAGE3: slot1 - slot2 - slot3 - slot4 - AuraA - slot6 - slot7 - slot8 ...
PAGE4: slot1 - slot2 - slot3 - slot4 - AuraB - slot6 - slot7 - slot8 ...
PAGE5: slot1 - slot2 - slot3 - slot4 - AuraC - slot6 - slot7 0 slot8 ...

A note about terminology.

There are FOUR potential actionbars. They are the UI elements on your screen.
By default you will have only one or two; you have to tell Warhammer to use
four, or you will have to use the "setbar" command (below) to set the bar
you want to use to something other than the default (which is 4).

There are FIVE actionbar PAGES. These pages have a shadowy existence because
your keybindings are relative to your actionbars, NOT your actionbar PAGES.
The pages can be loaded into any of actionbars, and the pages can be loaded
into two different actionbars at once. However, the pages ARE what remembers
which ability goes into which slot. So your page 1 can have Shield Wall in
slot 8, while your page 2 can have Shield Wall in slot 1. If page 1 is in
your actionbar #1, then Shield Wall will be keybinding button #8, but if
page 2 is in your actionbar #1, then Shield Wall will be keybinding #1.

So... keybindings 1 through 12 are relative to the first 12 slots of the
first actionbar, 13 through 24 are relative to actionbar #2, 25 through 36
are relative to actionbar #3, and 37 through 48 are relative to actionbar #4.
There are more bind buttons but they can't be used yet; you can only make
up to 48 actionbar button keybindings and use them.

Why does this matter?

Well, since an addon can easily and quickly change the page displayed to
a particular actionbar...

And since directly changing the keybindings has been iffy for developers, at
least in my personal experience...

An optimal way to use ONE keybinding for MULTIPLE (up to 5) abilities is to
rotate PAGES with those (up to 5) abilities on the SAME SLOT of each page
(slot #N) and use the actionbar's keybinding (actionbar button offset N)
for that slot, which will be a DIFFERENT ability depending on which page is
currently loaded into that actionbar.

This is much easier to see than to understand through text. Therefore, please
watch the video linked through the curse.com description page for more
help with setup.

I will make a final note: there is more than one way to do it, especially if
you are using another addon such as Vertigo to customize your actionbars.
Advanced users may want to set up their fourth hotbar (or other hotbar) with
only one button visible. That way, they won't need to look at 11 empty
button slots or waste the space of 33 buttons duplicating 11 buttons 3 times.
(A noobie fix for the wasted buttons is to duplicate the button abilities for
each of the 3 slots used for rotation.) A further improvement for the
advanced user, especially the one who is using Vertigo to make a 1-button
actionbar, is to feel free to use all 5 pages instead of just 3, 4, 5. There
is no limit in the software; the "usage" falsely implies that there is, but
there isn't. You can rotate page 1 or 2 just as easily if you like.

~~~~~~~~  3.0 USAGE: /chosen command  ~~~~~~~~

This addon uses text commmands to operate. This is not everyone's cup of tea,
but it is easy enough for me to code, friendly to macros, and I try to make
it understandable to the person who is not an IT expert. I probably will never
create a GUI driver specifically for ChosensHelper, but it is possible that I
or a third party creates a graphical front-end for using LibSlash commands.
None exists right now, so you will have to use your fingers (and set up a few
macros if you are an advanced user who wants to use less typing in the future).

~~~~ 3.1 usage, help, dumpdata ~~~~

The null command /chosen has its own message to display, as you may find out.

/chosen usage

This will display some text with examples about the commands available.

/chosen help

This will display a mini-readme.txt ... fortunately for you, you found
the real thing! I award you +1,000,000 influence with the Peter Kirby clan.

/chosen dumpdata

This will display some information about a select few variables within
the ChosensHelper addon, mostly the persistent ones.

~~~~ 3.2 nospam ~~~~

You can get your influence reward with the Peter Kirby clan by typing:

/chosen nospam

This will toggle a flag within the addon that redirects many things to the
debug window (which you can type /debug and look at with logging turned on):

1. Automated messages from the addon (startup, stop/resume)
2. Whiny messages from the addon for noobs
3. Error message type prints

This feature is intended to keep showing stuff to the Chat window that is
in direct response to a command where the obvious thing is to see a reply
from the addon. But if your message isn't in the chat window, you can be
sure to find it in the debug log (again, if logging is turned on).

A select few commands also have bonus messages for those with nospam on.

Type /chosen nospam again anytime if you want to get the nooby messages back.

I'm sure that this will find its way to the forums. If you read it here
in the readme.txt first, though, kudos!

~~~~ 3.3 toggledisplay ~~~~

By default, alerts to change auras are displayed on the mainscreen as the
large text alerts in your viewport.

Typing /chosen toggledisplay once will redirect those alerts to Chat.

Typing /chosen toggledisplay again will divert them to your Combat log.

Typing /chosen toggledisplay a third time will restore the default alerts.

~~~~ 3.4 sound ~~~~

Typing /chosens sound 0 will turn sounds off.

Typing /chosen sound 211 will give you the default sound (RvR objective
captured) played simultaneous with the change aura alert message.

The number can be something other than 0 or 211 if you are an advanced user.
type /debug and turn on logs and then type /script DUMP_TABLE(Sounds) to get
a full list of sounds available within the game.

~~~~ 3.5 setbar ~~~~

This is a command that many users will have to use. On a fresh install of
ChosensHelper, there is no actionbar set as the one to use with the addon.
This forces you to make a conscious decision about which bar on your
interface to use (there are 1, 2 or 4 of them) to rotate the 5 pages.

The syntax is /chosen setbar N where the number N is 1 through 4 and
corresponds with the actionbar (first, second, third, or fourth) that you
want to use.

This has NO relationship to the pages you will rotate. There are five pages
and only 1, 2, or 4 actionbar interface windows. The setbar command relates
to which actionbar interface window will be used for the addon.

~~~~ 3.6 start ~~~~

Syntax:

/chosen start N1 [N2 [N3]]

Where N is a number from 1 to 5 corresponding to a page of ability slots.

You can use the start command to start rotating one, two, or three pages
in the bar you set above. The behavior of the addon is different depending
on the number of pages you are rotating:

1. One page: No rotation, only one alert to change aura upon start.

2. Two pages: Alerts when the previous aura expires (12 seconds after you
activated the other one). Rotation swaps back and forth.

3. Three pages: Alerts when the aura just previous has 6 seconds left on
its linger timer (the oldest lingering aura, which you are going to switch
to, might have just expired if you have been good on reaction time). Rotation
follows an order based on when the pages were added to the rotation queue.
So, if you just added a page, it may be at the end of the queue and won't
have its aura come up for use for many seconds.

Some examples:

/chosen start 1
/chosen start 2 3 4
/chosen start 5 3 2
/chosen start 4 1
/chosen start 2 4
/chosen start 1 5

Note that you can only have up to three pages in active rotation, but you
can prepare up to ALL the pages for eventually being used in your rotation.
So, if you like 5 of your auras and can't pare down to just 3 which you want
to use, and if you hate mucking with ability pages, you can start using the
1st and 2nd pages in addition to pages 3, 4, and 5. Of course there will
still be a limit on number of actively rotating pages (3 max), but you will
have two other auras on reserve, which you can use the + and - or reuse
the start command in order to pull into active duty.

~~~~ 3.7 + and - commmands ~~~~

Usage:

/chosen +N
/chosen -N
/chosen [-N1] [+N2] [+N3] [-N4] ...

The + command will add a page to the rotation at the end of the list of pages
being rotated. The - command will take a page out of the list.

These commands are executed from left to right. If at any time you will drop
below 1 page in rotation or go above 3, the whole command fails. So the
order in which you type your + and - commands can be important.

~~~~ 3.8 stop ~~~~

This is the opposite of 'start' and 'resume'. It will prevent any alerts
or rotations from being done. It toggles a persistent setting about the
addon being active, which you can toggle back to true with resume. All
your persistent settings (including which pages to rotate) will remain.

~~~~ 3.9 resume ~~~~

This is the direct opposite of 'stop'. It will set the flag for the addon
being active to true, which will allow alerts to fly and pages to rotate.

~~~~ 3.10 reactiontime ~~~~

Syntax: /chosen reactiontime N

Along with "nospam", the other goodie you get for looking through readme.txt
is the "reactiontime" command. Set this to a value between 10 and 3000 in order
to have an advance warning for your alerts to change auras of as much as
2.500 seconds (2500 milliseconds). By default it is 1100 ms (1.1 s). You can
also set it to 0 to have no advance time between alert and needed aura changes.
This will feel like alerts come after the auras expire due to the way that buffs,
alerts, and the script in general has some lag.

The minimum is 10 ms, so that you don't mistakenly enter a value in seconds. The
integer value in milliseconds is converted to a floating point value in seconds.

~~~~ 3.11 using "chosen" commands within macros ~~~~

Any command starting with

    /chosen command ...

Can be rewritten for a macro as

    /script slash("chosen command ...")

Because that's the way you do it.

~~~~ 3.12 stuff to mess with only if you're brave ~~~~

Change the DEBUG variable in the ChosensHelper.lua file to 'true'.

Read the source code comments.

Hack on the source code itself and send me your patch.

Find a useful purpose for having an alternating hotbar.

~~~~~~~~ 4.0 WHEN THINGS GO WRONG ~~~~~~~~

Please post a negative comment on the curse.com website immediately. Others
must know about this rogue addon and its insurmountable flaws! Fight the
power! Death to developers!

~~~ 4.1 What the Author Already Knows Will Likely Go Wrong ~~~~

As of version 1.1:

This addon requires LibSlash... not a big deal since many others do too.

This addon works ONLY with English-language clients. That means it does NOT
work with the German, French, Spanish, Italian, Russian, or Swahili client.
The problem goes beyond localizing addon messaging. It just doesn't work.

This addon is quite sensitive to how you set up your actionbars, and doing
it wrong can cause you no end of grief. You need to set up a keybinding
too, one which is relative to the actionbar you are rotating pages in.

Also, use the setbar command right. It's about UI actionbar, not page.

This addon is dependent on the default BuffTrackers window that is shown
in the player's own unit frame. Other addons, such as CleanUnitFrames and
my own Buffbegone Ultra, will muck with this and break ChosensHelper.
If you need ChosensHelper, something's got to give (sorry cUF).

This addon has historically had a lot of trouble with loading new zones
such as scenarios. If you find the addon completely unresponsive, try
using /reloadui and then /chosen resume. Please also report the incident
and its circumstances so that this bug, at least, can be squashed for good.

The instruction video has an error about how to set up macros. If you follow
the code in the video, you will be told that /chosen is not a command. You
need to follow the instructions above for using chosen commands in macros.

ALERTS DO NOT HAPPEN OUT OF COMBAT, with the sole exception of when first
activating the addon. This is a FEATURE and will never be changed.

As a gameplay precuation, I want to note an easy mistake to make, and that is
to hit the keybinding rapidly and thus deactivate the aura as soon as it
begins. Guard against this by hitting the keybinding only once per aura change.
You can do this a full second before the ability actually becomes available
from cooldown and still have it go off fine.

~~~~ 4.2 What to Do if You Have Found a Unique Way to Make Things Fail ~~~~

In order...

1. Try to do it again, maybe you made a typo or something.
2. Try to do it again, after reading /chosen help and /chosen usage.
3. Try to do it again, after watching the instruction video.
4. Shut down everything. Read the entire readme.txt file. Try to do it again.
5. Look for known issues (the curse.com description is good for this) and
any possible workarounds from the author or fellow users.

Okay, so you found a bug? Congratulations! You can find the bugtracker on
the curseforge.com page and you can always shoot an email off to the author.
When you do so, include the following:

1. Version of addon
2. Actions performed (including exact text of commands)
3. Behavior resulted (including all text of error messages)
4. Add in any messsages printed to the /debug window if you can hack it
5. Throw in some screenshots for good measure, especially if the problem
may be particular to your UI setup
6. If you have any addons besides ChosensHelper and LibSlash, it helps to
list them because some may be contributing to the problem

A good report will have as many of these as possible. A good report will
be filed (either with the bugtracker or by email) before blabbing on some
board or through the curse.com comments page about how this addon is broken.
It will also help me fix it more than a random "it didn't work" comment.

5.0 SOFTWARE LICENSE

This software is freeware and may be used by anyone as freeware. This
software is copyright 2008 Peter Kirby, all rights reserved. No portion of
this software may be copied without permission from Peter Kirby.

This readme.txt file is also copyright 2008 Peter Kirby.