Graphical User Interface
Detailed Description
This section of the documentation covers the Nebula GUI system that can be used to create an in-game graphical user interface.Initialization and Rendering
The first thing step in initalizing the GUI system is to specify the root path of the GUI system. This root path is where the created GUI widgets live. It is set by calling nGuiServer::SetRootPath(). If you do not explicitly set the root path, it will be set on'/res/gui' by default.Next, call nGuiServer::Open() to initialize GUI system.
guiServer->SetRootPath("/gui")
guiServer->Open();
nGuiServer::Open() internally calls nScriptServer::RunScript() and runs the script 'OnGuiServerOpen'. So the OnGuiServerOpen script should be defined before nGuiServer::Open() is called if you want to do some of your own initialization for the GUI system.
The 'OnGuiServerClose' script is called by nGuiServer::Close() in the same manner.
A default root window named 'SystemRootWindow' is created by nGuiServer::Open(). All windows created by the programmer will be located under this root window.
You can hide all windows by passing 0 to nGuiServer::SetRootWindow():
guiServer->SetRootWindow(0);
or with the script form:
/>sel /sys/servers/gui
/sys/servers/gui>.setrootwindow ""
To render GUI windows, you should call nGuiServer::Trigger() and nGuiServer::Render() in your rendering loop.
// render loop
...
guiServer->Trigger();
...
if (sceneServer->BeginScene(viewMatrix))
{
...
sceneServer->EndScene();
...
guiServer->Render();
...
sceneServer->PresentScene();
}
Call nGuiServer::Trigger() as with all other Nebula servers. Call nGuiServer::Render() after rendering the scene. This will render the GUI on top of the rendered scene.
You should call nGuiServer::Close() when the application is closed.
guiServer->Close();
Lastly, release the GUI server by calling its Release() member function.
guiServer->Release();
Setting up the Skin
To use GUI system, you should create its skin first. Usually it is good to create and define a skin in theOnGuiServerOpen script. The default startup.tcl (and the startup.lua scripts that come with some of the contribs) provide examples of how to configure a skin. The skin is defined via script to make it easily editable.You can create a skin by calling nGuiServer::NewSkin() with a given skin name.
// 'system' is skin name. skin = guiServer->NewSkin("system");
Then specify a path of the skin texture and its file extension.
skin->SetTexturePrefix("home:export/textures/system/"); skin->SetTexturePostfix(".dds");
A Skin also needs to specify its color for when it is active and inactive.
skin->SetActiveWindowColor(1.0, 1.0, 1.0, 0.9); skin->SetInactiveWindowColor(0.6, 0.6, 0.6, 0.6);
Finally, register brush to be used in the skin. See nGuiSkin::AddBrush() for more details on the arguments.
skin->BeginBrushes() skin->AddBrush("titlebar", "skin", 0, 52, 43, 20, 1.0, 1.0, 1.0, 1.0) skin->AddBrush("window", "skin", 0, 77, 15, 13, 1.0, 1.0, 1.0, 1.0) skin->EndBrushes()
Creating a Window
This section provides a brief example of creating a window on console to make it easier to understand Nebula GUI system.You can create a window by calling nGuiServer::NewWindow() with a given class name specifying the type of window to create.
Run nviewer.exe and type this on it's console:
/>sel /sys/servers/gui
/sys/servers/gui>.newwindow nguiclientwindow true
or on C++:
nGuiClientWindow* wnd = (nGuiClientWindow*)guiServer->NewWindow("nguiclientwindow", true);
The above code create a window of nGuiClientWindow type under the root window, 'SystemRootWindow'. The name of the created window is automatically assigned by nGuiServer when it is created by calling nGuiServer::NewWindow(). The first window is 'window0', the second is 'window1', and so on.
After creating the window, you will be directly moved to the created object hierarchy. Therefore you can specify the title of the window by calling 'settitle' command. Then you can specify position and size of the window by calling 'setrect' command.
/gui/SystemRootWindow/window3>.settitle MyWindow
/gui/SystemRootWindow/window3>.setrect 0.48 0.9 0.52 1.0
Windows of the type nGuiClientWindow have Titlebar, CloseButton, SizeButton and Layout elements by default.
You can check this by typing 'dir' command under the created window:
/gui/SystemRootWindow/window3>dir
TitleBar CloseButton SizeButton Layout
/gui/SystemRootWindow/window3>
If you want to add a button or some other GUI element as a child of that window, you must create those widgets under the Layout node.
/gui/SystemRootWindow/window3>sel Layout
/gui/SystemRootWindow/window3/Layout>new nguibutton mybutton
/gui/SystemRootWindow/window3/Layout>sel mybutton
/gui/SystemRootWindow/window3/Layout/mybutton>.setrect 0.05 0.35 0.05 0.15
/gui/SystemRootWindow/window3/Layout/mybutton>.setdefaultbrush terminal_n
/gui/SystemRootWindow/window3/Layout/mybutton>.setpressedbrush terminal_p
/gui/SystemRootWindow/window3/Layout/mybutton>.sethighlightbrush terminal_h
/gui/SystemRootWindow/window3/Layout/mybutton>.settooltip test
/gui/SystemRootWindow/window3/Layout/mybutton>sel ..
/gui/SystemRootWindow/window3/Layout>.attachform mybutton left 0.0
/gui/SystemRootWindow/window3/Layout>.attachform mybutton top 0.0
/gui/SystemRootWindow/window3/Layout>.attachform mybutton bottom 0.0
/gui/SystemRootWindow/window3/Layout>.attachpos mybutton right 0.3
or on C++:
nGuiButton* btn; btn = (nGuiButton*) kernelServer->New("nguibutton", "mybutton"); // the brushes terminal_n, terminal_p and terminal_h should be // aleady defined when a skin is created. btn->SetDefaultBrush("terminal_n"); btn->SetPressedBrush("terminal_p"); btn->SetHighlightBrush("terminal_h"); btn->SetTooltip("Button Test"); layout->AttachForm(btn, nGuiFormLayout::Left, 0.0f); layout->AttachForm(btn, nGuiFormLayout::Top, 0.0f); layout->AttachForm(btn, nGuiFormLayout::Bottom, 0.0f); // assume btnSize is 0.3 layout->AttachPos(btn, nGuiFormLayout::Right, 1 * btnSize);
As like the creation of the window, you should spcecify the position and size of the button by calling 'setrect' command. Note that all widgets should be specified its position and size after it is created by its SetRect() member function.
nGuiWidget and all classes that derived from it have four states:
- Normal
- Pressed
- Highlight
- Disabled
When the widget is created, you should specify all of the brush states by calling:
- nGuiWidget::SetDefaultBrush()
- nGuiWidget::SetPressedBrush()
- nGuiWidget::SetHighlightBrush()
- nGuiWidget::SetDisabledBrush()
If you do not that, the button will be not shown on the window.
nGuiFormLayout is used to provide a flexible layout scheme. It provides relative positioning of child elements. The created 'mybutton' has its left, top and bottom edges aligned with the form. Its right edge is placed at 30% of the width of the form.
nGuiFormLayout provides three type of layout scheme.
- nGuiFormLayout::AttachForm()
- nGuiFormLayout::AttachWidget()
- nGuiFormLayout::AttachPosition()
A position and size of the widget is specified by its SetRect() member function. But nGuiWidget::SetRect() doesn't affect the change of the size of child widget when the parent widget changes its size. Applying the layout scheme with nGuiFormLayout enables that relative change of the size of the child widget whenever its parent widget changes its size.
Classes | |
| class | nGuiAdjustDisplayWindow |
| class | nGuiBar |
| Fillable GUI bars. May be filled from left to right or vice versa. Examples are Healthbars, Progressbars, etc. More... | |
| class | nGuiBrush |
| A brush object which caches the pointer to the GUI resource inside a skin object. More... | |
| class | nGuiButton |
| A GUI button class. More... | |
| class | nGuiCanvas |
| A GuiWidget which enables the user to draw lines and text. More... | |
| class | nGuiCategoryBrowser |
| A category/file browser widget. More... | |
| class | nGuiCharacterControlWindow |
| Character Controls. More... | |
| class | nGuiCheckButton |
| An on/off check button widget. More... | |
| class | nGuiCheckButtonGroup |
| Groups child check buttons so that only one is selected at any time. (OBSOLETE). More... | |
| class | nGuiCheckButtonGroup2 |
| A new style check button group which creates its check buttons and places them in a horizontal row. More... | |
| class | nGuiClientWindow |
| A window with optional titlebar, close button, size handles and a client area. More... | |
| class | nGuiCmdEntry |
| A specialized text view widget which displays the current kernel server's line buffer and lets the user enter script commands. More... | |
| class | nGuiColorAdjust |
| To select a rgb-color. More... | |
| class | nGuiColorAdjustWindow |
| To select a rgb-color. More... | |
| class | nGuiColorLabel |
| A label widget which screens one color. More... | |
| class | nGuiColorPicker |
| to choose and select a rgb-color More... | |
| class | nGuiColorSliderGroup |
| A complete color slider group, consisting of a horizontal intensity slider, and a color label. More... | |
| class | nGuiConsoleWindow |
| A complete Nebula command console window. More... | |
| class | nGuiContextMenu |
| A context menu base class. Implement OnEvent() behavior in a derived subclass. More... | |
| class | nGuiDiagramCanvas |
| A GuiWidget which creates a diagram canvas. More... | |
| class | nGuiDirLister |
| A complete directory listing widget. More... | |
| class | nGuiDockWindow |
| The global dock window which replaces the old scripting console as Nebula's default ingame console. More... | |
| class | nGuiDragBox |
| Implements a drag box as 2d screen space rectangle. More... | |
| class | nGuiEvent |
| A gui event class. More... | |
| class | nGuiEventHandler |
| class | nGuiFadeOutTextLabel |
| FadeOut the Text. More... | |
| class | nGuiFileDialog |
| A file dialog base class. More... | |
| class | nGuiFormLayout |
| Lays out size and position of child widgets based on own position. More... | |
| class | nGuiGraphicsBrowserWindow |
| A client window which browses the proj:export/gfxlib directory, and loads graphics objects under /usr/scene. More... | |
| class | nGuiHardpointsBrowserWindow |
| class | nGuiHardpointsLister |
| class | nGuiHoriSliderGroup |
| A horizontal slider group consisting of a label, a horizontal slider, and a text label which displays the current slider's numerical value as a printf-formatted string. More... | |
| class | nGuiIcon |
| A drag and drop icon widget. (OBSOLETE?). More... | |
| class | nGuiIconCanvas |
| A canvas for drag and drop icons (OBSOLETE?). More... | |
| class | nGuiIpAddressEntry |
| An text entry gadget which restricts input to ip addresses. More... | |
| class | nGuiLabel |
| A widget which is a graphical label. More... | |
| class | nGuiMessageBox |
| A complete modal message box window. More... | |
| class | nGuiMouseCursor |
| class | nGuiResource |
| A gui resource for Nebula2's gui subsystem. More... | |
| class | nGuiSceneControlWindow |
| Scene Controls for adjusting stdlight, postion & color... More... | |
| class | nGuiServer |
| The central server object of the Nebula2 user interface subsystem. More... | |
| class | nGuiAdjustDisplayFileDialog |
| class | nGuiSettingsForm |
| Implements a form layout with user customizable settings widgets. Uses persistency server for storing the settings. More... | |
| class | nGuiSettingsManagementWindow |
| class | nGuiSkin |
| A GUI skin object holds an user-defined table of gui resources which are used by the GUI widgets to render themselves. More... | |
| class | nGuiSkyEditor |
| To edit nSkyNode on the fly... More... | |
| class | nGuiSlide |
| A slide class for use with the nGuiSlideShow widget. More... | |
| class | nGuiSlider2 |
| A vertical or horizontal slider widget. More... | |
| class | nGuiSlideShow |
| A widget which implements a picture slideshow. More... | |
| class | nGuiSystemInfoWindow |
| A Nebula system information window. More... | |
| class | nGuiTabbedLayout |
| A tabbed layout is a form layout which embeds several child form layouts which can be flipped through a row of tab buttons at the top. More... | |
| class | nGuiTexBrowserWindow |
| A window to browse the currently loaded textures and display information about them. More... | |
| class | nGuiTextButton |
| A gui button which contains a label text. More... | |
| class | nGuiTextEntry |
| A text entry widget. More... | |
| class | nGuiTextLabel |
| Uses the text server to render a gui label which contains ASCII text. More... | |
| class | nGuiTextTable |
| A table layout which implements a grid of texts. More... | |
| class | nGuiTextureView |
| A label widget which directly renders a texture. Used by the texture browser. More... | |
| class | nGuiTextView |
| A multiline text viewing widgets, which can display lines of text. More... | |
| class | nGuiTextWindow |
| A text viewer window which can display text from a text file. More... | |
| class | nGuiTickerWidget |
| Ticker widget (for Genius). Not very useful for the general case. More... | |
| class | nGuiToolTip |
| A tooltip widget with text which always positions itself relative to the mouse. More... | |
| class | nGuiWatcherWindow |
| A debug watcher window. More... | |
| class | nGuiWidget |
| An abstract gui widget (a rectangular click area). More... | |
| class | nGuiWindow |
| A window that defines a rectangular area on screen and may contain other widgets. More... | |
