WebSVN – vanilla-wow-addons – Blame – Rev 1

			Adds a startup function to Timex.&nbsp; A startup function runs immediately after Timex has initialized.&nbsp; This is soon after the player logs in or has reloaded their UI,

78

			soon after the <code>VARIABLES_LOADED</code> event.&nbsp; It is similar to the <code>Enable</code> method of Ace addons, and is mostly there for use with non-Ace addons.<br>

79

<br>

80

<dl>

81

<dt class="bold">Parameters:</dt>

82

<dd><code>f</code> - the startup function.</dd>

83

<dd><code>a1..a20</code> - the arguments (optional).</dd>

</dl>

<br>

<dl>

<dt class="underline">Example:</dt>

88

<dd>

89

<pre><code>Timex:AddStartupFunc(self.AddonFunc, ace.print, ace, "I have entered the game!")</code></pre>

90

91

This will print "I have entered the game!" to the ChatFrame on login.

</dd>

</dl>

</div></dd>

</dl>

	<!--------------

99

	AddSchedule

100

--------------->

101

<h2>Adding a Timex Entry<a name="AddingaTimexEntry"/></h2>

102

103

<h3>Timex:AddSchedule</h3>

104

<dl>

105

<dt>

106

<pre>void Timex:<b>AddSchedule</b>(object id,

number t,

boolean r,

number c,

function/string f,

object a1,

object a2,

object a3, ...

object a20)</pre>

</dt>

<dd><div>

			Adds a schedule entry to Timex.&nbsp; This is the fundamental method of Timex.&nbsp; This is used to schedule a function to run, or an event to be triggered, at some

118

point in the future.<br>

119

<br>

120

			<u>Argument subsitution:</u>&nbsp;Timex supports argument substition.  If you use one of the following values in the argument list, Timex will substitute the appropriate value

121

when the function/event is called.<br>

122

<br>

123

<dl>

124

<dd><code>Timex.ARG_ID</code> - the id of this schedule.</dd>

125

<dd><code>Timex.ARG_COUNT</code> - the number of times this schedule has run.</dd>

126

<dd><code>Timex.ARG_ELAPSED</code> - the elapsed time since this schedule last fired.</dd>

</dl>

<br>

<dl>

<dt class="bold">Parameters:</dt>

131

<dd><code>id</code> - the id, for persistent entries (optional).</dd>

132

<dd><code>t</code> - the time delay.</dd>

133

<dd><code>r</code> - whether the schedule should be repeated continuously (optional, not to be used with c).</dd>

134

<dd><code>c</code> - the number of times the schedule should be repeated before removal (optional).</dd>

135

<dd><code>f</code> - the function (pointer) or event (string) to trigger.</dd>

136

<dd><code>a1..a20</code> - the arguments (optional).</dd>

</dl>

<br>

<dl>

<dt class="underline">Example #1:</dt>

141

<dd>

142

<pre><code>Timex:AddSchedule("MyAddOn", 5, nil, nil, ace.print, ace, "Hello World!")</code></pre>

143

144

This is a standard Timex entry - after two seconds, "Hello World!" will be printed to the ChatFrame.<br>

<br>

</dd>

<dt class="underline">Example #2:</dt>

149

<dd>

150

<pre><code>Timex:AddSchedule("MyAddOn", 2, TRUE, nil, ace.print, ace, "Yadda!")</code></pre>

151

152

					In this example repeat is being used - this will print "Yadda!" to the ChatFrame every two seconds until the entry is manually deleted.<br>

<br>

</dd>

<dt class="underline">Example #3:</dt>

157

<dd>

158

<pre><code>Timex:AddSchedule("MyAddOn", 2, nil, 5, ace.print, ace, "Blah.")</code></pre>

159

160

					In this example we see count being used - this will print "Blah." to the ChatFrame every two seconds until it has done this five times, then it will stop.<br>

<br>

</dd>

<dt class="underline">Example #4:</dt>

165

<dd>

166

					<pre><code>Timex:AddSchedule(timexBar, 0.1, nil, time*10, timexHandler, self, timexBar, Timex.ARG_ELAPSED)</code></pre>

167

168

					In this example we see count being used - this will print "Blah." to the ChatFrame every two seconds until it has done this five times, then it will stop.<br>

<br>

</dd>

<dt class="underline">Example #5:</dt>

173

<dd>

174

<pre><code>Timex:AddSchedule("MyAddOn", 2, TRUE, nil, "MY_TIMEX_UPDATE", "% has seen %s counts", Timex.ARG_COUNT)

175

176

function AddOnName:Enable()

177

self:RegisterEvent("MY_TIMEX_UPDATE")

178

end

179

180

function AddOnName:MY_TIMEX_UPDATE(msg, c)

181

-- c is the current count.

182

ace:print(format(msg, c)

183

if c == 2 then

184

ace:print("Second.")

185

elseif c == 1 then

186

ace:print("First.")

187

end

188

end</code></pre>

189

					The fifth example gets more complex.&nbsp; If you enter a string as the function, Timex will fire that event when the schedule is due (the "doTimexEvent" string

190

					will actually fire the "TIMEX_UPDATE" event for backwards-compatibility with older versions of Timex).&nbsp; This may be useful if you wish to use an event-driven

191

					timing system, rather than one that relies on function calls.&nbsp;  Note that this only works for Ace-developed AddOns, due to the way the event is distributed.<br>

</dd>

</dl>

</div></dd>

</dl>

<h2>Checking a Timex Entry<a name="CheckingaTimexEntry"/></h2>

199

200

<h3>Timex:ScheduleCheck</h3>

201

<dl>

202

<dt>

203

<pre>boolean/number Timex:<b>ScheduleCheck</b>(object id,

boolean r)</pre>

</dt>

<dd><div>

			This method is used to check the current status of any Timex entries.  It can also be used to check the time that has elapsed on a particular timer.&nbsp; This can be used to

208

			check how much time has passed from point A to point B.  You can add a Timex entry without a function for this very purpose.<br>

209

<br>

210

<dl>

211

<dt class="bold">Parameters:</dt>

212

<dd><code>id</code> - the id of the entry.</dd>

213

<dd><code>r</code> - whether to return the time elapsed. (optional).</dd>

214

<dt class="bold">Returns:</dt>

215

				<dd>If <code>r</code> is <code>FALSE</code> or <code>nil</code>, <code>TRUE</code> if the entry exists, <code>nil</code> otherwise.  If <code>r</code> is not

216

<code>FALSE</code> or <code>nil</code>, the time elapsed on the entry, <code>nil</code> otherwise.</dd>

</dl>

<br>

<dl>

<dt class="underline">Example #1:</dt>

221

<dd>

222

<pre><code>local a = Timex:ScheduleCheck("MyAddOn")

223

if a then

224

ace:print("Exists.")

225

end</code></pre>

226

This example will return true if the Timex entry with id "MyAddOn" is present, and nil otherwise.

227

</dd>

228

<br>

229

<dt class="underline">Example #2:</dt>

230

<dd>

231

<pre><code>local a = Timex:ScheduleCheck("MyAddOn", TRUE)

if a then

ace:print(a)

end</code></pre>

This example will return the time remaining for the Timex entry with id "MyAddOn" is present, and nil otherwise.

</dd>

</dl>

</div></dd>

</dl>

<h2>Deleting a Timex Entry<a name="DeletingaTimexEntry"/></h2>

243

244

<h3>Timex:DeleteSchedule</h3>

245

<dl>

246

<dt>

247

<pre>void Timex:<b>DeleteSchedule</b>(object id)</pre>

248

</dt>

249

<dd><div>

250

This method is used to remove a Timex entry.<br>

251

<br>

252

<dl>

253

<dt class="bold">Parameters:</dt>

254

<dd><code>id</code> - the id of the entry.</dd>

</dl>

<br>

<dl>

<dt class="underline">Example:</dt>

259

<dd>

260

<pre><code>Timex:DeleteSchedule("MyAddOn")</code></pre>

261

262

This will delete the "MyAddOn" entry from Timex's database.

</dd>

</dl>

</div></dd>

</dl>

<h2>Changing an Entry's Duration<a name="ChanginganEntrysDuration"/></h2>

269

270

<p>

271

		This method is used to change a timer's duration while it is running.  For example, it can be used to change the 'tick rate' of a

repeating timer.

</p>

<h3>Timex:ChangeDuration</h3>

276

<dl>

277

<dt>

278

<pre>void Timex:<b>ChangeDuration</b>(object id

number t)</pre>

</dt>

<dd><div>

This method is used to remove a Timex entry.<br>

283

<br>

284

<dl>

285

<dt class="bold">Parameters:</dt>

286

<dd><code>id</code> - the id of the entry.</dd>

287

<dd><code>t</code> - the new duration of the entry.</dd>

</dl>

<br>

<dl>

<dt class="underline">Example:</dt>

292

<dd>

293

<pre><code>Timex:DeleteSchedule("MyAddOn", 15)</code></pre>

294

295

This will change the duration of the "MyAddOn" timer to 15 seconds.

</dd>

</dl>

</div></dd>

</dl>

<br>

<br>

<h1>ii. Developers - Timex Bars<a name="ii"/></h1>

306

307

<p>

308

		This module of timex exists for providing timer bars to both players for their macros and to developers for AddOns that need to display a

309

		timer.&nbsp; The bar has two text elements, these are timer and text.&nbsp; The colour of the bar and text are both configurable along with

310

		the size and shape of the bar.&nbsp; Further, there's a button to the left of the bar which can display a spell/item texture for easy viewing of

311

whatever's ticking down. Note that the interface for TimexBar has changed in R23.

312

</p>

313

<p>

314

Here's a visual example of a standard Timex Bar, as shown by the AceTimer AddOn:

315

</p>

316

<p style="text-align: center">

317

		<img alt="[ Timex Bars ]"  title="Timex Bars" src="TimexBars.jpg" style="border: 5px solid ; width: 246px; height: 96px;"/>

318

</p>

319

<p>

320

		These bars are currently at their default length and size.  Once a bar has finished ticking down, it can fire off a function, so if you want to

321

		rearrange your GUI based on when bars show and hide, you can now do so.&nbsp; For example, you could create a bunch of bars which anchor off of

322

each other to the right and when one disappears, the next bar over crops left to take its space.

323

</p>

324

<p>

325

		These bars are currently at their default length and size.  Once a bar has finished ticking down, it can fire off a function, so if you want to

326

		rearrange your GUI based on when bars show and hide, you can now do so.&nbsp; For example, you could create a bunch of bars which anchor off of

327

each other to the right and when one disappears, the next bar over crops left to take its space.

328

</p>

329

<p>

330

		The interface for creating and starting a bar has changed somewhat from pre-R23 versions of Timex.  Essentially, you get Timex to assign a bar

331

		from its free pool to your id, then you format the bar and start it.  Note that a bar is only truly reserved (ie removed from the free pool) once

332

it has started. A bar returns to the free pool when it finishes running, or if it is stopped.

333

</p>

334

335

<h2>Getting a Timex Bar<a name="GettingaTimexBar"/></h2>

336

337

<h3>TimexBar:Get</h3>

338

<dl>

339

<dt>

340

<pre>void TimexBar:<b>Get</b>(object id)</pre>

341

</dt>

342

<dd><div>

343

			This will assign a bar to the id you provide.  Note that you cannot 'Get' a bar, and then format/start it at some later stage.  It is quite likely

344

			that the bar will be assigned to another id the next time another 'Get' call is made, so you will have to 'Get' a bar again.  Generally you should

345

get and format a bar at the time that you intend to start it.<br>

346

<br>

347

<dl>

348

<dt class="bold">Parameters:</dt>

349

<dd><code>id</code> - the id of the bar.</dd>

</dl>

</div></dd>

</dl>

<h3>TimexBar:GetName</h3>

355

<dl>

356

<dt>

357

<pre>string TimexBar:<b>GetName</b>(object id)</pre>

358

</dt>

359

<dd><div>

360

			Gets the name of the TimexBar assigned to the given id.  Returns <code>nil</code> if no TimexBar is assigned to the id.<br>

361

<br>

362

<dl>

363

<dt class="bold">Parameters:</dt>

364

<dd><code>id</code> - the id of the bar.</dd>

365

<dt class="bold">Returns:</dt>

366

<dd>The name of the TimexBar assigned to <code>id</code>, or <code>nil</code>.</dd>

</dl>

</div></dd>

</dl>

<h2>Formatting a Timex Bar<a name="FormattingaTimexBar"/></h2>

373

374

<p>

375

		There are a number of formatting methods to change the appearance of a Timex bar...generally these are similar to the formatting options available

376

on the standard UI Frame elements. All are optional (ie you don't have to set any of them if you don't wish to).

377

</p>

378

379

<h3>TimexBar:SetColor</h3>

380

<dl>

381

<dt>

382

<pre>void TimexBar:<b>SetColor</b>(object id

number red,

number green,

number blue,

number alpha)</pre>

387

</dt>

388

<dd><div>

389

Sets the color of the bar.<br>

390

<br>

391

<dl>

392

<dt class="bold">Parameters:</dt>

393

<dd><code>id</code> - the id of the bar.</dd>

394

<dd><code>red</code> - red channel.</dd>

395

<dd><code>green</code> - green channel.</dd>

396

<dd><code>blue</code> - blue channel.</dd>

397

<dd><code>alpha</code> - alpha channel (optional).</dd>

</dl>

</div></dd>

</dl>

<h3>TimexBar:SetTextColor</h3>

403

<dl>

404

<dt>

405

<pre>void TimexBar:<b>SetTextColor</b>(object id

number red,

number green,

number blue,

number alpha)</pre>

410

</dt>

411

<dd><div>

412

Sets the color of the text in the bar.<br>

413

<br>

414

<dl>

415

<dt class="bold">Parameters:</dt>

416

<dd><code>id</code> - the id of the bar.</dd>

417

<dd><code>red</code> - red channel.</dd>

418

<dd><code>green</code> - green channel.</dd>

419

<dd><code>blue</code> - blue channel.</dd>

420

<dd><code>alpha</code> - alpha channel (optional).</dd>

</dl>

</div></dd>

</dl>

<h3>TimexBar:SetPoint</h3>

426

<dl>

427

<dt>

428

<pre>void TimexBar:<b>SetPoint</b>(object id

429

string point,

430

string relativeFrame,

431

string relativePoint,

432

number xOffset,

433

number xOffset)</pre>

434

</dt>

435

<dd><div>

436

Sets the position of the bar.<br>

437

<br>

438

<dl>

439

<dt class="bold">Parameters:</dt>

440

<dd><code>id</code> - the id of the bar.</dd>

441

<dd><code>point</code> - the anchor point of the bar.</dd>

442

<dd><code>relativeFrame</code> - the anchor frame (that the bar's position will be relative to).</dd>

443

<dd><code>relativePoint</code> - the anchor point of the anchor frame.</dd>

444

<dd><code>xOffset</code> - X offset.</dd>

445

<dd><code>yOffset</code> - Y offset.</dd>

</dl>

</div></dd>

</dl>

<h3>TimexBar:SetScale</h3>

451

<dl>

452

<dt>

453

<pre>void TimexBar:<b>SetScale</b>(object id

454

number scale)</pre>

455

</dt>

456

<dd><div>

457

			Sets the scale of the bar.  This is best suited to changing the size of the entire bar (the bar, the text, the icon, everything).<br>

458

<br>

459

<dl>

460

<dt class="bold">Parameters:</dt>

461

<dd><code>id</code> - the id of the bar.</dd>

462

<dd><code>scale</code> - the scale of the bar.</dd>

</dl>

</div></dd>

</dl>

<h3>TimexBar:SetWidth</h3>

468

<dl>

469

<dt>

470

<pre>void TimexBar:<b>SetWidth</b>(object id

471

number width)</pre>

472

</dt>

473

<dd><div>

474

			Sets the width of the bar.  This is best suited to changing the dimensions of the bar relative to the other elements (eg the icon or

the text).<br>

<br>

<dl>

<dt class="bold">Parameters:</dt>

479

<dd><code>id</code> - the id of the bar.</dd>

480

<dd><code>width</code> - the width of the bar.</dd>

</dl>

</div></dd>

</dl>

<h3>TimexBar:SetHeight</h3>

486

<dl>

487

<dt>

488

<pre>void TimexBar:<b>SetHeight</b>(object id

489

number height)</pre>

490

</dt>

491

<dd><div>

492

			Sets the height of the bar.  This is best suited to changing the dimensions of the bar relative to the other elements (eg the icon or

the text).<br>

<br>

<dl>

<dt class="bold">Parameters:</dt>

497

<dd><code>id</code> - the id of the bar.</dd>

498

<dd><code>height</code> - the height of the bar.</dd>

</dl>

</div></dd>

</dl>

<h3>TimexBar:SetTimeWidth</h3>

504

<dl>

505

<dt>

506

<pre>void TimexBar:<b>SetTimeWidth</b>(object id

507

number timeWidth)</pre>

508

</dt>

509

<dd><div>

510

			Sets the width of the 'time' portion of the text display of the bar.  This is best suited to changing the size of the timer relative

511

to the other elements (eg the icon, the bar, or the text).<br>

512

<br>

513

<dl>

514

<dt class="bold">Parameters:</dt>

515

<dd><code>id</code> - the id of the bar.</dd>

516

<dd><code>timeWidth</code> - the width of the timer.</dd>

</dl>

</div></dd>

</dl>

<h3>TimexBar:SetText</h3>

522

<dl>

523

<dt>

524

<pre>void TimexBar:<b>SetText</b>(object id

string text)</pre>

</dt>

<dd><div>

Sets the text that the bar will display (ie the label).<br>

529

<br>

530

<dl>

531

<dt class="bold">Parameters:</dt>

532

<dd><code>id</code> - the id of the bar.</dd>

533

<dd><code>text</code> - the text of the bar.</dd>

</dl>

</div></dd>

</dl>

<h3>TimexBar:SetTexture</h3>

539

<dl>

540

<dt>

541

<pre>void TimexBar:<b>SetTexture</b>(object id

542

string texture)</pre>

543

</dt>

544

<dd><div>

545

Sets the texture (icon) that will be displayed next to the bar.<br>

546

<br>

547

<dl>

548

<dt class="bold">Parameters:</dt>

549

<dd><code>id</code> - the id of the bar.</dd>

550

<dd><code>texture</code> - path to the texture to display with the bar.</dd>

</dl>

</div></dd>

</dl>

<h3>TimexBar:SetFunction</h3>

556

<dl>

557

<dt>

558

<pre>void TimexBar:<b>SetFunction</b>(object id,

function f,

object a1,

object a2,

object a3, ...

object a20)</pre>

</dt>

<dd><div>

			Sets a function that will be called when the bar finishes.  This will <em>not</em> be called if the bar is stopped manually (ie

567

through the <code>TimexBar:Stop</code> method.<br>

568

<br>

569

			<u>Argument subsitution:</u>&nbsp;TimexBars also support argument substition.  If you use one of the following values in the argument list,

570

Timex will substitute the appropriate value when the function/event is called.<br>

571

<br>

572

<dl>

573

<dd><code>Timex.ARG_ID</code> - the id of this TimexBar.</dd>

574

<dd><code>Timex.ARG_ELAPSED</code> - the elapsed time since this TimexBar was last updated.</dd>

575

<dd><code>Timex.ARG_REMAINING</code> - the time remaining on this TimexBar.</dd>

</dl>

<br>

<dl>

<dt class="bold">Parameters:</dt>

580

<dd><code>id</code> - the id of the bar.</dd>

581

<dd><code>f</code> - the function to be run.</dd>

582

<dd><code>a1..a20</code> - the arguments (optional).</dd>

</dl>

</div></dd>

</dl>

<h3>TimexBar:SetUpdateFunction</h3>

588

<dl>

589

<dt>

590

<pre>void TimexBar:<b>SetUpdateFunction</b>(object id,

function f,

object a1,

object a2,

object a3, ...

object a20)</pre>

</dt>

<dd><div>

			Sets a function that will be called every time the bar is updated.  This method also supports argument substitution.<br>

599

<br>

600

<dl>

601

<dt class="bold">Parameters:</dt>

602

<dd><code>id</code> - the id of the bar.</dd>

603

<dd><code>f</code> - the function to be run.</dd>

604

<dd><code>a1..a20</code> - the arguments (optional).</dd>

</dl>

</div></dd>

</dl>

<h2>Starting a Timex Bar<a name="StartingaTimexBar"/></h2>

610

611

<p>

612

		After assigning and formatting your bar, it is time to start it.  This removes the bar from the free pool and displays it to the user.  It will

613

start running immediately.

614

</p>

615

616

<h3>TimexBar:Start</h3>

617

<dl>

618

<dt>

619

<pre>void TimexBar:<b>Start</b>(object id,

number time,

number res)</pre>

</dt>

<dd><div>

			Starts a TimexBar.  This removes the bar from the free pool and displays it. It is possible to alter the resolution of the bar's updates...by default

625

			the bar will update every 0.1 seconds, but for a long-running bar, u might want to update it only once every sec, in which case you would set

626

the <code>res</code> parameter to 1.<br>

627

<br>

628

<dl>

629

<dt class="bold">Parameters:</dt>

630

<dd><code>id</code> - the id of the bar.</dd>

631

<dd><code>time</code> - The duration of the bar.</dd>

632

<dd><code>res</code> - The resolution of the bar display in seconds (optional, default 0.1).</dd>

633

<dt class="bold">Returns:</dt>

634

<dd>The name of the bar assigned (eg TimexBar3).</dd>

</dl>

</div></dd>

</dl>

<p>

<h2>An Example<a name="TimexBarExample"/></h2>

641

642

<p>The following code shows how to format and start a TimexBar.</p>

643

644

645

<pre class="indent">local toggle;

646

local function toggleAppearance(id, remaining)

647

if toggle then

648

TimexBar:SetText(id, "My Bar #2 - " .. remaining);

649

TimexBar:SetColor(id, 1.0, 1.0, 1.0);

650

TimexBar:SetTextColor(id, 0, 0, 0);

651

else

652

TimexBar:SetText("MyBar", "My Bar #1 - " .. remaining)

653

TimexBar:SetColor("MyBar", 1.0, 0.2, 0.2)

654

TimexBar:SetTextColor("MyBar", 1.0, 1.0, 0.2)

655

end

656

toggle = not toggle;

657

end

658

659

TimexBar:Get("MyBar")

660

TimexBar:SetText("MyBar", "My Bar #1")

661

TimexBar:SetTexture("MyBar", "Interface\\Icons\\Spell_Nature_ResistNature")

662

TimexBar:SetColor("MyBar", 1.0, 0.2, 0.2)

663

TimexBar:SetTextColor("MyBar", 1.0, 1.0, 0.2)

664

665

TimexBar:SetPoint("MyBar", "BOTTOMLEFT", "UIParent", "CENTER", 40, 40)

666

TimexBar:SetWidth("MyBar", "200")

667

TimexBar:SetHeight("MyBar", "20")

668

TimexBar:SetTimeWidth("MyBar", "50")

669

TimexBar:SetScale("MyBar", "1.6")

670

671

TimexBar:SetFunction("MyBar", ace.cmd.msg, ace.cmd, "'%s' bar hidden.", TimexBar.ARG_ID)

672

673

toggle = true;

674

TimexBar:SetUpdateFunction("MyBar", toggleAppearance, TimexBar.ARG_ID, TimexBar.ARG_REMAINING);

675

676

local name = TimexBar:Start("MyBar", 10, 0.5)

677

ace:print(name.." is active.")</pre>

678

679

	<p>First we assign a bar to the id "MyBar" using <code>Timex:Get</code>.  The next two lines set the text and icon of the bar.  After this, we set the color

680

of the bar, and the color of the text displayed.</p>

681

682

	<p>Next we set the bar so that it's bottom-left corner is 40 pixels to the left and 40 pixels above the center of the screen.  We set the width and height

683

		of the bar, and set the time display so that it takes up a quarter of the bar's width.  Then we set the scale to 1.6 - the default scale is 0.8, so this

684

bar will appear twice the size as the default.</p>

685

686

	<p>We then set a function so that the bar will print, "'MyBar' bar hidden." to the chat log when it completes.  We also set a function to toggle the

687

appearance of the bar every time it is updated.</p>

688

689

	<p>Lastly, we start the bar so that it updates every half second for 10 seconds, and print the name of the bar to the chat log with a message saying

690

that it has started</p>

691

692

<h2>Checking a Timex Bar<a name="CheckingaTimexBar"/></h2>

693

694

<h3>TimexBar:Check</h3>

695

<dl>

696

<dt>

697

<pre>boolean/number TimexBar:<b>Check</b>(object id,

boolean r)</pre>

</dt>

<dd><div>

			This method is used to check whether a TimexBar exists for the given id, and can optionally return the name of the TimexBar.<br>

702

<br>

703

<dl>

704

<dt class="bold">Parameters:</dt>

705

<dd><code>id</code> - the id of the bar.</dd>

706

<dd><code>r</code> - whether to return the name of the bar (optional).</dd>

707

<dt class="bold">Returns:</dt>

708

				<dd>If <code>r</code> is <code>FALSE</code> or <code>nil</code>, <code>TRUE</code> if the bar exists, <code>nil</code> otherwise.  If <code>r</code> is not

709

<code>FALSE</code> or <code>nil</code>, the name of the bar, <code>nil</code> otherwise.</dd>

</dl>

<br>

<dl>

<dt class="underline">Example:</dt>

714

<dd>

715

<pre>local a = TimexBar:Bar("MyBar")

716

if a then

717

ace:print("Exists.")

718

end</pre>

719

720

This example will print, "Exists." to the chat log if a TimexBar exists for the id "MyBar".

</dd>

</dl>

</div></dd>

</dl>

<h2>Stopping a Timex Bar<a name="StoppingaTimexBar"/></h2>

728

729

<h3>TimexBar:Stop</h3>

730

<dl>

731

<dt>

732

<pre>boolean/number TimexBar:<b>Stop</b>(object id)</pre>

733

</dt>

734

<dd><div>

735

This method is used to stop a TimexBar.<br>

736

<br>

737

<dl>

738

<dt class="bold">Parameters:</dt>

739

<dd><code>id</code> - the id of the bar.</dd>

</dl>

<br>

<dl>

<dt class="underline">Example:</dt>

744

<dd>

745

<pre>local a = TimexBar:Bar("MyBar")</pre>

746

747

This example will stop TimexBar for the id "MyBar".

</dd>

</dl>

</div></dd>

</dl>

<h1>iii. Developers - Miscellaneous<a name="iii"/></h1>

754

755

<h2>Syntactic Mayhem<a name="SyntacticMayhem"/></h2>

756

757

<p>

758

So you now know the ins and outs of developing using Timex and its Bars

759

module, is there anything to add?  Not really, though I would like

760

to explain a few things about syntax first and how syntax differs

761

through code formats.

</p>

<p>

Throughout your days coding for the World of Warcraft community you're

766

going to see many kinds of coding styles, this is going to change how

767

you use Timex as far as the syntax of calling functions is

768

concerned.  To avoid confusion later I've decided that it would be

769

best to explain the differences between these and the best way to

770

handle them.  Note: I'll be using AddSchedule to demonstrate

771

how these work but these examples will work for any part of Timex that

accepts functions.

</p>

<h3>Scripting</h3>

<p>This is a basic function format that's most frequently used.</p>

778

779

<dl>

780

<dt class="underline">Format:</dt>

781

<dd><div><pre>function AddOn_Function_Blah(arg1, arg2)</pre></div></dd>

782

<dt class="underline">Result:</dt>

783

<dd><div><pre>Timex:AddSchedule(..., AddOn_Function_Blah, arg1, arg2)</div></pre></dd>

</dl>

<h3>Tabled</h3>

<p>This is a slightly more advanced format used infrequently.</p>

790

791

<dl>

792

<dt class="underline">Format:</dt>

793

<dd><div><pre>function Table.Function_Name(arg1, arg2)</pre></div></dd>

794

<dt class="underline">Result:</dt>

795

<dd><div><pre>Timex:AddSchedule(..., Table.Function_Name, arg1, arg2)</div></pre></dd>

796

</dl>

797

798

<h3>Object-Oriented</h3>

799

800

	<p>This is the most advanced form Lua has to offer, all the cool kids are using it.&nbsp; It has a few variations on the basic form.</p>

801

802

<dl>

803

<dt class="underline">Format #1:</dt>

804

<dd><div><pre>function AddonName:DoSomething(arg1, arg2)</pre></div></dd>

805

<dt class="underline">Format #2:</dt>

806

<dd><div><pre>function AddonName.DoSomething(self, arg1, arg2)</pre></div></dd>

807

<dt class="underline">Format #3:</dt>

808

<dd><div><pre>AddOnName {

809

DoSomething = function(self, arg1, arg2),

810

}</pre></div></dd>

811

<dt class="underline">Result:</dt>

812

<dd><div><pre>Timex:AddSchedule(..., self.DoSomething, self, arg1, arg2)</div></pre></dd>

</dl>

<p>

		Note: You only need to pass self if the function you're passing too actually references self.&nbsp; Lua uses pseudo-OO so it's up to you, you can

817

mix and match function types.

</p>

<br>

<h1>iv. Players<a name="iv"/></h1>

822

823

<h2>Timex Compatibility<a name="TimexCompatibility"/></h2>

824

825

<p>

826

		The Chronos placeholder addon is provided in case people wish to use Timex in place of Chronos - the aim is to be fully compatible with Chronos where

827

possible. Drop us a line if you find that in practice Timex is not working properly with Chronos-based addons.

<p>

<br>

<h2>Chat Commands<a name="ChatCommands"/></h2>

832

833

<p>

834

		Timex has a chat-command system for options, it uses a one-line system for ease of typing and to allow for bigger macros (so you don't have to

835

		retype our chat-operator on every line).&nbsp; Further, the chat-command system isn't watered down in any way and provides as much of the power of Timex

836

as we were able to cram in, so it is slightly complex but I shall endeavour to explain how each of the commands works.

837

</p>

838

839

<h3>The Do Command<a name="TheDoCommand"/></h3>

840

841

<div class="indent">

842

843

<p>Here's the basic layout of the system:</p>

844

845

<pre class="indent">/tmx do n="[timer name]" t=[time] r=[repeat] c=[count] f=[function] a=[args]</pre>

846

847

<p>

848

			The first thing to cover is: what's up with those quotation marks?&nbsp; The chat-command system separates by spaces, so if something you want to use

849

			(such as the name or an arg) has a space in it, you'll have to wrap it in quotation marks to ensure that the space inside isn't considered as a

850

			separator.&nbsp; Basically, if you're not actively typing spaces between the commands and you have a space that's not command related, wrap quotation

851

marks around the entire thing, as shown by 'timer name'.

852

</p>

853

854

<span class="bold">Parameters:</span><br>

855

		<div class="hanging-indent"><code>timer name</code> - this is the name of your timer, you don't have to supply this at all but if you want to be able to stop your timer at

856

			any point, it's a good idea.&nbsp; The format of name is either <code>n=mytimer</code> or <code>n="my timer"</code>.</div>

857

		<div class="hanging-indent"><code>time</code></span> - this is the amount of time that will pass before the Timex does its stuff.&nbsp; If you set this to eight seconds

858

			then Timex will delay for 8 seconds before using the function that you gave it.&nbsp; The format of time is <code>t=8</code>.</div>

859

		<div class="hanging-indent"><code>repeat</code></span> - repeat will make your timer continuous, so it'll cycle on a basis of the time you gave it.&nbsp; If you provide

860

			it with 8 seconds then every 8 seconds it will fire the function you gave it until it's stopped.&nbsp; To make repeat happen, supply <code>r=TRUE</code> as a command.</div>

861

		<div class="hanging-indent"><code>count</code></span> - similar to repeat, however it will only cycle for the amount of times that you specify.&nbsp; If that's three cycles,

862

			it will fire your function three times (waiting for the delay first of cocurse), then automatically stop.&nbsp; The format of count is <code>c=8</code>.</div>

863

		<div class="hanging-indent"><code>function</code></span> - this is the function you wish to call.&nbsp; It is supplied as a pointer, so if your function is <code>DoThis(a, b)</code>,

864

you'll have to supply <code>DoThis</code> here.  The format of function is <code>f=DoThis</code>.</div>

865

		<div class="hanging-indent"><code>args</code></span> - these are the arguments you wish to supply along with your function, so if your function is <code>DoThis(a, b)</code>,

866

			you'll have to supply 'a, b' here.&nbsp; The format of args is either <code>a=arg</code> if it's one arg or <code>a="arg1, arg2, arg3 ... etcetera"</code>

867

if it's more.</div>

868

869

<p>Here's an example of the above in action:</p>

870

871

<pre class="indent">/tmx do n="my print" t=5 f=SendChatMessage a="'Hello World!', SAY"</pre>

872

873

<p>This would make you say 'Hello World!' after five seconds have passed.</p>

</div>

<h3>The Stop Command<a name="TheStopCommand"/></h3>

878

879

<div class="indent">

880

<p>

881

			Now that adding timers is out of the way, how would you go about stopping them?&nbsp; That's easy too.&nbsp; There's a stop command that you can supply a timer name

882

			too, it will look for that timer name and stop it.&nbsp; So if you've decided you don't want a timer to run or you have something on a repeat or a count and you

883

wish to stop it then you can easily do so with a quickly accessible chat-command.

884

</p>

885

<pre>/tmx stop my print</pre>

886

887

<p>

888

			This would search for the 'my print' timer and stop it.&nbsp; Use both of these commands to your advantage in macros and really take command of your

playing style.

</p>

</div>

<h1>Fin</h1>

</body>

</html>

vanilla-wow-addons – Blame information for rev 1