// ================================================================================
// ==      This file is a part of Turbo Badger. (C) 2011-2014, Emil Segerås      ==
// ==                     See tb_core.h for more information.                    ==
// ================================================================================

Turbo Badger Integration guide
-----------------------------

This is a short guide to integrating Turbo Badger in a game or application.
It basically list what you most probably want to do.
More details is found in the method definitions.

Build configuration
-------------------

There are defines in tb_config.h that control some features & implementation
details. This file may be overridden by your own configuration (see tb_config.h for
more info).

Input
-----

You need to create at least one "root widget" for your UI widgets. A TBWidget that
act as receiver for input, painting etc, and is parent to your other widgets.
Turbo Badger will handle input capture, focus, etc. automatically.

List of input triggers (root is your root TBWidget):

	root->InvokePointer[Down/Up/Move/Cancel] - Mouse or touch input
	root->InvokeTouch[Down/Up/Move/Cancel]   - Touch input (touch indices > 0).
	root->InvokeWheel                        - Mouse wheel input
	root->InvokeKey                          - Keyboard input

Additionally, there's common event types that can be invoked by root->InvokeEvent
like f.ex: EVENT_TYPE_SHORTCUT, EVENT_TYPE_CONTEXT_MENU, EVENT_TYPE_FILE_DROP...

Animations, Layout and Painting
-------------------------------

Before painting, it is a good time to run animations, update widgets input states
and layout, since all that affect the rendering. This is done by calling:

	TBAnimationManager::Update()
	root->InvokeProcessStates()
	root->InvokeProcess()

Before painting the root widget (and all its children), you need to prepare
the renderer to set up the correct matrix etc.

	g_renderer->BeginPaint(window_width, window_height);
	root->InvokePaint(TBWidget::PaintProps())
	g_renderer->EndPaint();

Message handling
----------------

TBMessageHandler::ProcessMessages() needs to be called frequently to process
the message queue.

If you have a game running its loop continuously, you can just call ProcessMessages()
each time.

If you have a event driven application that should only consume CPU when needed
you can call TBMessageHandler::GetNextMessageFireTime() for scheduleing when to run
ProcessMessage next. Also, TBSystem::RescheduleTimer will be called back if the time
it needs to run next is changed.

Rendering
---------

TBRenderer & TBBitmap are the interfaces that implements everything that Turbo Badger
needs for rendering. There is already a OpenGL renderer implementation that can be
used, or you can implement your own (See tb_config.h).

Some apps need to unload all graphics and reload it again, f.ex when the app
is put to sleep in the background and the graphics context is lost.
Turbo Badger implements a renderer listener to handle this in all places that needs
it, so the only thing you need to do is to call:

	g_renderer->InvokeContextLost(); // Forget all bitmaps
	...
	g_renderer->InvokeContextRestored(); // Reload all bitmaps

Font system
-----------

There is font implementations for freetype and stb_truetype.h, and a bitmap font
system (tbbf - "turbo badger bitmap font") that is very simple to use and supports
any range or characters, glow & shadow. You can choose any of these or add your own.
It possible to use multiple backends, so you can f.ex use tbbf for some bitmap fonts,
and a freetype backend for other fonts.

The implementation API render glyph by glyph, but if it's requested to externalize
the entire string measuring & drawing, support for that shouldn't be hard to add.

If no font implementation is choosen (or if using font ID 0), a test dummy font
is used which renders squares.

System integration
------------------

Here are some additional API's that needs implementations:

TBImageLoader
API for loading images. There's a implementation available using STBI. Note: STBI
should only be used to load your well known resources and nothing from the net,
since the library doesn't handle corrupt files safely which might be a security
issue.

TBSystem
Needs to be implemented for timers & some settings.

TBClipboard
Needs to be implemented for clipboard support.

TBFile
Needs to be implemented for file loading.
