Contexts - mattbichay/test GitHub Wiki
Rocket contexts are independent collections of documents. All documents exist within a single context. Contexts are rendered, updated and given input independently of each other at the application's discretion.
Most games will feature a single context for the main interface. Multiple contexts could be used however for a number of different reasons.
A second or subsequent context could be used to store alternative 'desktops' that the user could switch to, in a similar fashion to many Linux desktops. This could be very useful for interface-heavy games where the user may have several windows open at once, more than could fit easily onto one screen.
Computer terminals or consoles in a 3D game world could themselves be Rocket contexts. As they wouldn't necessarily be viewed parallel to the screen, mouse input would need to be projected onto the surface. When the context was rendered, it would need to be transformed correctly to fit onto the surface or rendered onto a texture.
To create a new context, use the CreateContext() function in Rocket::Core.
The context needs a unique string name and initial dimensions. The dimensions are used to generate relative lengths (for example, if a document has a percentage dimension), and sets the extents for the mouse cursor within the context.
To fetch a previously-constructed context, use the GetContext() function.
Contexts are reference counted, and begin with a reference count of one. Once you have finished with a context, call RemoveReference() to release it. It will be destroyed, and all of its documents released.
If a context is active, it should have Update() called on it after the frame's input events have been sent to it.
To render a context, call Render() on it. Easy!
Documents are loaded through contexts. To load a document from an RML file into a context, call the LoadDocument() function on the appropriate context.
The document_path parameter will be given to Rocket's [wiki:documention/C++Manual/Interfaces#Thefileinterface] to be open and read. If the document is loaded successfully, it will be added to the context and returned. Call Show() on the document to make it visible.
You can also load documents directly from a memory stream, this can be useful if you want to receive documents over the network or similar.
To create a new, empty document you can populate dynamically, use the CreateDocument() function.
The context will attempt to instance an element using the 'body' instancer, with the tag name specified by the caller. If a Rocket::Core::ElementDocument is instanced, it will be added to the context and returned.
Each context maintains a list of cursors that can be used to represent the mouse cursor. Regardless of the number of cursors loaded into a context, only one cursor is rendered at a time. The default cursor is the first element to be loaded; this will be the visible cursor unless an element overrides it through the [wiki:documentation/RCSS/UserInterface#Cursors:thecursorproperty].
Mouse cursors can be loaded into a context using the LoadMouseCursor() function.
Cursors are documents themselves, and are loaded the same way internally. Any valid RML document can be loaded as a document; of course, you're most likely to want a simple document with an image decorator, but you're not limited to this!
Note that the cursor's 'name' is the title of its document. This is the name you'll use to specify it through the 'cursor' property.
Mouse cursors can also be shared across contexts with the AddMouseCursor() function.
Call AddMouseCursor() with a cursor loaded into another context.
Event listeners can be attached to a context (rather than an element) to receive events sent to all elements within that context. As with elements, call AddEventListener() to attach a listener and RemoveEventListener() to detach.
See the section on [wiki:documentation/C++Manual/Input] for detail on sending user input from your application into Rocket contexts.
Contexts are created, like elements and decorators, through instancers. You can override the default context instancer if you want to create custom contexts. Generally, this is only required for adding support for scripting languages.
A custom context is a class derived from Rocket::Core::Context. There are no virtual methods on Rocket::Core::Context, so it cannot be specialised.
A custom context instancer needs to be registered with the Rocket factory in order to override the default instancer. A custom context instancer needs to be derived from Rocket::Core::ContextInstancer, and implement the required virtual methods:
InstanceContext() will be called whenever a new context is requested. It takes a single parameter, name, the name of the new context. If a context can be created, it should be initialised and returned. Otherwise, return NULL (0).
ReleaseContext() will be called whenever a context is released. The context instancer should destroy the context and free and resources allocated for it.
Release() will be called when Rocket is shut down. The instancer should delete itself if it was dynamically allocated.
To register a custom instancer with Rocket, call RegisterContextInstancer() on the Rocket factory after Rocket has been initialised.
Like other instancers, context instancers are reference counted and begin with a single reference. The factory will add its own reference to the instancer once it is registered, so you must remove the initial reference afterwards.
All active contexts can be enumerated via the Rocket::Core::GetNumContexts() and Rocket::Core::GetContext(int index) function calls.