Integration

This guide covers how to use OpenGUI in a C++ project. Interfaces to OpenGUI may exist for other languages, and those interfaces should provide their own usage documentation as they are not covered here.

Should you need assistance using OpenGUI beyond the scope of this documentation, the following sources are made available for public use:

Includes and Linker Input

In order to begin using OpenGUI in your application, you will need to include OpenGUI.h in every source file that will use parts of the library. This can be performed by the following code:

 #include "OpenGUI.h"

Due to the scale of OpenGUI, it is not practical for all classes to be defined within a single header file. As such, OpenGUI.h is a super header that automatically includes all other necessary headers. You will need to add the location of OpenGUI.h as an include search path for your compiler. The steps required to perform this are compiler specific, so they are not covered here.

Note:: It is completely safe to include only the specific headers you need at any given time, but it is much easier to simply include this super header.

In addition to the header file, you'll also need to provide your linker with the appropriate library (*.lib ) file when building fully linked binaries. The name of this file is either OpenGUI_d.lib for the debug library, or OpenGUI.lib for the release library.

Currently OpenGUI only supports use as a DLL, so you'll also need to place the appropriate DLL into the same directory as your application binary. There are a few other options available for this, but they are out of the scope of this document. The debug DLL is OpenGUI_d.dll, the release DLL is OpenGUI.dll.

Summary Information

 #include "OpenGUI.h"

OpenGUI_d.lib - Debug Library
OpenGUI_d.dll - Debug DLL
OpenGUI.lib - Release Library
OpenGUI.dll - Release DLL

Initializing OpenGUI

Initialization of OpenGUI can be broken up into a few simple steps.

Create a Renderer
Create a ResourceProvider (optional)
Create a LogListener (optional)
Create the System, passing in the previously created support objects

For the sake of this document, we'll use the built in ResourceProvider and LogListener, and the reference OpenGL Renderer.

#include "OpenGUI.h"
#include "OpenGUI_OGLRenderer.h"
using namespace OpenGUI;

[...]

Renderer* renderer = new OGLRenderer( 800, 600 );
System* system = new System( renderer );

That's basically all it takes to initialize OpenGUI. You simply pass the System constructor pointers to the necessary user provided support classes and it will take care of the rest. The end result is a pointer to a fully initialized OpenGUI instance, ready for use.

Create a Screen

All GUIs are built upon Screen objects. A Screen is basically a virtual monitor. A Screen can either render directly to the main frame buffer, or it can render to a texture. In this case, we're going to use the default render targeting of a Screen, which is to render directly to the frame buffer.

screen = ScreenManager::getSingleton().createScreen( "MainScreen", FVector2( 800, 600 ) );

This snippet of code creates a single Screen, named "MainScreen", that has a virtual resolution of 800 x 600. The resolution of a Screen is completely abstracted from the true resolution of the destination render surface. No matter what size of the render surface, a Screen will always map its virtual resolution evenly across the entire destination surface. This allows you to create a GUI once, and it will automatically scale correctly across all possible render target resolutions. Fonts are always automatically scaled appropriately to preserve true pixel alignment to the render target surface, while maintaining their visual size within the virtual resolution of the Screen. In other words, your text will always look crisp, regardless of the true resolution of the render target, and will always be proportional to the original GUI design.

Input Injection

At some point you're going to need to allow the user to interact with your GUI. The process of injecting input is performed individually per Screen. This is to allow multiple Screens to run simultaneously. A good example of this would be a game scene full of computer monitors that the user can interact with. Each might have a completely different GUI layout applied to them with their own animations and event hooks. However, in this example we're going to stick with the single, frame buffer attached Screen that we created earlier.

// assume that "yourInputSystem" is a pointer to some input system
float x_abs, y_abs; // some floats to hold the mouse position
// The next function call represents your own input system
// retrieving the mouse position as a percentage (0.0f thru 1.0f)
yourInputSystem->getMousePosition( &x_abs, &y_abs );
screen->injectCursorPosition_Percent( x_abs, y_abs );
screen->injectCursorPress_State( yourInputSystem->isButtonDown() );

The previous code uses the fictitious yourInputSystem to retrieve the mouse position, which it then injects into the Screen as an absolute position within the GUI using injectCursorPress_State. The next call retrieves the button up/down state for the mouse, and feeds it into the state-aware button function injectCursorPress_State. The Screen class provides several different methods for input injections, so you can use the one that is most appropriate for your specific needs.

Showing the Cursor

Unlike many GUI systems, OpenGUI does not assume that you want a visible cursor, or that you always want to process cursor input injections. By default the cursor is visible but disabled. A cursor will not draw unless it is both enabled and visible, so initially there is no displayed cursor until you enable it. However, you cannot have a visible cursor without first defining the default cursor for the Screen. The default cursor is the cursor that will be drawn when the cursor is over a widget that does not define its own preferred cursor.

// for our purposes, we'll assume that "Arrow" is an already defined Cursor
CursorPtr cursor = CursorManager::getSingleton().CreateDefinedCursor( "Arrow" ); // create an instance of the cursor
screen->setCursor( cursor ); // set this cursor to be the default for the Screen
cursor = 0; // free the handle any way you like, either explicitly or by letting it run out of scope
screen->enableCursor(); // enable the cursor for this Screen

Once you've done this, the Arrow cursor will be displayed as the default cursor for the Screen. Alternatively, if we wanted to enable an invisible cursor (because we're using a hardware cursor, or some other pointing device), we could have simply enabled the cursor without setting a default Cursor for the Screen. Since you cannot have a visible cursor without the Screen having a default Cursor to show, the Screen will automatically mark the cursor hidden upon enabling.

screen->enableCursor(); // enable the cursor for this Screen, it will automatically be marked hidden

Updating the Screen

In order for anything to be drawn at all, we need to tell OpenGUI when to perform updates for the Screens. This can be done at several different levels, with the application assuming varying amounts of additional work. For the purposes of this example, we'll use the most basic update method, which is to ask System to update all Screens for us.

system->update(); // perform fully automated update

By using System::update, we're asking OpenGUI to update all Screens, as well as perform time injections. Refer to the API documentation for more information on the various levels at which Screens can be updated, and the additional responsibilities the application assumes when doing so.

That pretty much covers the basics of integrating OpenGUI into your application. The demos can be referenced for further example code, and the resources listed at the top can be utilized if you require further assistance.