Torque GUI
From TorqueWiki
Contents |
[edit] Intro
The GUI library manages the user interface of Torque applications. Based very loosely on the NeXTSTEP interface class library, the GUI library is designed specifically for the needs of game UI development
[edit] GUI Tutorials
Another GUI tutorial with example files Author: Gonzo T. Clown (Sep 29, 2004) Categories: Programming Code File: demoguitwo.zip http://www.garagegames.com/index.php?sec=mg&mod=resource&page=view&qid=6493
http://www.garagegames.com/index.php?sec=mg&mod=resource&page=view&qid=6482
[edit] General Links
Links for spezific topics are in the corresponding sections.
Basic GUI Demo (the simplest GUI)
http://tdn.garagegames.com/wiki/TGB/MiniTutorials/GUIIntroToProfiles
http://tdn.garagegames.com/wiki/GUI/Fonts/New_Fonts
http://tdn.garagegames.com/wiki/GUI/Profiles/ControlList
http://tdn.garagegames.com/wiki/GUI/Tips1_5#When_switching_key_maps...
http://www.luma.co.za/labs/tutorials/torque_gui/TGE%201.5%20GUIs.pdf
http://www.luma.co.za/labs/torque_pipeline_tutorials.html
http://tdn.garagegames.com/wiki/GUI/ChatHud
Guide will make use of a keyboard command to turn on an off a little section of the hud to allow for the simulation of binoculars: http://tdn.garagegames.com/wiki/GUI/Scope
This resource allows you to automatically scroll controls in your game. This can be used, for instance, to scroll text in a credits dialog, or scroll information in a ticker at the bottom of the user's screen: http://www.garagegames.com/index.php?sec=mg&mod=resource&page=view&qid=9049
Do's and Don'ts: general Tips to create, layout, size, organize GUI Menus: GUI Tips
Bonus Resource Bundle: http://www.garagegames.com/index.php?sec=mg&mod=resource&page=view&qid=11518
[edit] GUI Editor
[edit] Canvas
http://tdn.garagegames.com/wiki/TGB/Reference:_GuiCanvas
The base interface layer is the canvas:
- singleton instance of the GuiCanvas
- processing and dispatching mouse and keyboard events
- update regions and cursor handling
- calling the GuiControl render methods when it is time to draw the next frame
- keeps track of a stack of content controls - separate hierarchies of GuiControls that render from bottom to top.
- maintains a set of "dirty" bounding boxes signifying areas of the screen that need to be repainted - a button may change, for example, if the mouse has just been pressed; a control can call the setUpdate() method on itself signifying that it needs to be repainted
- Because the Torque engine works with page flipping devices and there may be as many as three separate buffers with old screen data, the Canvas maintains three dirty rectangles representing the dirty state of each of the (up to) three buffers.
Convas.setContent( myCoolInterface );
[edit] Dialogs and Layers
GPGT p. 457
[edit] Screen Size
The screen size of the canvas is virtual.
[edit] Profiles
Local Tutorial -> GUI Profile Tutorial
[edit] Backgroud, Buttons, and new Interfaces
[edit] Splashscreen
Locate the file splashscreen.gui and change the bitmap.
Locate the file menuscreen.gui and change the bitmap in GuiChunkedBitmapCtrl(MenuScreen).
[edit] Color Modulation
a) Use colour modulation instead multiple images. If you have a component that use images, and changes colour depending on its state, use colour modulation to create the colour change on a single image. This will make asset management easier.
new GuiBitmapCtrl(BlueIcon)
{
//...other fields
modulate = true;
modulationColor = “0 153 255”;
}
Since you can only modulate one colour, you may need to break up images to separate parts of the image that do change colour from those that do not.
b) Use colour modulation for animating
glows.
Colour modulation can also be used in customised
components to animate glowing components and
other colour changes, instead of using animation
sequences.
[edit] Changing the Background Interactively
Add a new button to the menuscreen.gui that calls the function ChangeBackground():
new GuiButtonCtrl() {
profile = "GuiButtonProfile";
horizSizing = "right";
vertSizing = "top";
position = "529 234";
extent = "110 20";
minExtent = "8 8";
visible = "1";
command = "ChangeBackground();";
helpTag = "0";
text = "Change Backgound";
groupNum = "-1";
buttonType = "PushButton";
};
Write the ChangeBackground() function in control/client/client.cs:
function ChangeBackground()
{
//MenuScreen.setVisible( false );
MenuScreen.setBitmap( expandFileName( "./interfaces/emaga_background.jpg") );
MenuScreen.setVisible( true );
//Canvas.repaint();
}
The setBitmap" function, loads the texture (which must of been in place when you started the TGE) and calls "setUpdate()" which triggers a render next rendering pass.
To trigger an update on the specific control and all its children is to make the following call on the object:
%obj.setVisible(true).
For updating all the current gui use
Canvas.repaint()
unfortunately, this call is not available on other controls.
[edit] Creating a New Interface
As a basis save the file client/interfaces/menuscreen.gui as myNewInterface.gui and change the objectname (class instance):
new GuiChunkedBitmapCtrl(myNewInterface)
Change the background bitmap of you new interface and add a button to switch back the menuscreen:
new GuiButtonCtrl() {
profile = "GuiButtonProfile";
horizSizing = "right";
vertSizing = "top";
position = "29 237";
extent = "110 20";
minExtent = "8 8";
visible = "1";
command = "ShowMenuScreen();";
helpTag = "0";
text = "Push this button ...";
groupNum = "-1";
buttonType = "PushButton";
};
Laod the new interface during startup. Edit the file
client/main.cs and add:
Exec("./interfaces/myNewInterface.gui");
This does not mean the interface becomes visible, but that it is present and can be pushed on the canvas:
Canvas.setContent( myNewInterfacs );
Create a new button in the menuscreen interface to launch this call:
new GuiButtonCtrl() {
profile = "GuiButtonProfile";
horizSizing = "right";
vertSizing = "top";
position = "529 334";
extent = "110 20";
minExtent = "16 8";
visible = "1";
command = "ShowMyNewInterface";
helpTag = "0";
text = "Show My New Interface";
groupNum = "-1";
buttonType = "PushButton";
};
Finally create the ShowMyNewInterface function in client.cs:
function ShowMyNewInterface()
{
// Startup the client with the menu...
Canvas.setContent( Mynewinterface );
Canvas.setCursor("DefaultCursor");
}
[edit] Schedule
%event = schedule( time, reference, command [, parm1,..,parmN] )
time in ms
reference is 0 or a valid object handle
command to execute and parameters for the command
returns eventID
You can cancel the event later using eventID:
cancel( eventD );
[edit] Übung "Schedule Interface Switch"
GPGT p. 387
When you switch to your new Interface schedule bringing the menuscreen back up:
function ShowMyNewInterface()
{
Canvas.setContent( MyNewInterface );
%eventid = schedule( 3000, 0, ShowMenuScreen );
}
[edit] Wrapping and Offset
GPGT p. 490
When wrap is true the bitmap in GuiBitmapCtrl is not scaled to fit the control.
new GuiBitmapCtrl(myScrollBg) {
profile = "GuiWindowProfile";
horizSizing = "width";
vertSizing = "height";
position = "50 0";
extent = "640 480";
minExtent = "8 8";
visible = "1";
helpTag = "0";
useVariable = "0";
tile = "0";
bitmap = "./interfaces/berge";
wrap = "true";
If the bit is larger than the control, you can specify an offset with setValue():
function myScrollBg::scrollMe( %this )
{
//if( ! %this.isScrolling ) { return; }
%this.curX += 1;
//%this.curY += 2;
if( %this.curX > 600)
{
%this.curX = 0;
%this.curY = 0;
}
%this.setValue( %this.curX, %this.curY );
%this.schedule( 32, scrollMe );
}
[edit] Fade in and out
GPGT p. 387
Add a new Interface that keeps fading in and out:
function ShowFadeInOutInterface()
{
// Startup the client with the menu...
FadeInOutInterface.done = false;
Canvas.setContent( FadeInOutInterface );
Canvas.setCursor("DefaultCursor");
}
[edit] Root and Container Controls
[edit] GuiControl--the Root GUI Class
- the root class for all the GUI controls
- derived from SimGroup and can contain any number of child GUI controls
- maintains a bounding rectangle in the coordinate system of its parent control
- irtual methods for processing input events (onMouseDown, onMouseUp, onMouseEnter, onMouseLeave, onMouseMove, onMouseDragged, onRightMouseDown, onKeyDown, onKeyUp,onKeyRepeat)
- methods called by the Canvas for rendering (onPreRender, onRender)
GPGT p. 463, 470
[edit] Container
GPPT P. 478
All controls can act as a container for other controls.
To layout your screen use GuiFrameSetControl.
[edit] GuiFramsetCtrl
GuiFrameSetCtrl can contain any number of childs in row-column format.
new GuiFrameSetCtrl() {
profile = "GuiButtonProfile";
visible = "1";
helpTag = "0";
horizSizing = "right";
vertSizing = "top";
position = "0 200";
minExtent = "8 8";
extent = "200 200";
columns = "0 85";
rows = "0 125";
new child ....
new child ....
new child ....
new child ....
Children are added following a left-to-right, top-to-bottom order.
[edit] GuiScrollCtrl
GPGT P. 480
GuiScrollCtrl provides scrollbars, margins, and control over the content like force to scroll text somewhere.
new GuiScrollCtrl() {
horizSizing = "right";
vertSizing = "top";
position = "250 -100";
extent = "150 150";
minExtent = "8 8";
visible = "1";
hscrollBar = "dynamic";
vscrollBar = "alwayson";
constantThumbHeight = false;
childmargin = "10 10";
};
[edit] GuiWindowCtrl
GPGT p. 487
new GuiWindowCtrl( myWindow ) {
position = "250 200";
extent = "150 150";
minExtent = "8 8";
visible = "1";
text = "My Window";
reszieWidth = "1";
reszieHeight = "1";
canMove = "1";
canClose = "1";
closeCommand = "Quit();";
canMinimize = "1";
canMaximize = "1";
minSize = "50 50";
};
Quit() might not be the command you want, to replace it define a new closeCommand:
closeCommand = "myCloseWindow();";
function myCloseWindow()
{
myWindow.delete();
}
[edit] GUI Skinning
GPGT p. 476
[edit] Text
[edit] GuiTextCtrl
This is good for labels:
new GuiTextCtrl() {
profile = "GuiTextProfile";
horizSizing = "right";
vertSizing = "top";
position = "140 250";
extent = "150 20";
minExtent = "8 8";
visible = "1";
helpTag = "0";
text = "Press this button -> ";
maxlength = "64";
};
[edit] GuiMLTextCtrl
GPGT p. 497
[edit] Scolling Text in a Window
You may include the GuiTextCtrl directly into the window:
new GuiWindowCtrl(myWindow) {
position = "200 200";
extent = "150 150";
minExtent = "8 8";
visible = "1";
text = "My Window";
reszieWidth = "1";
reszieHeight = "1";
canMove = "1";
canClose = "1";
closeCommand = "myCloseWindow();";
canMinimize = "1";
canMaximize = "1";
minSize = "50 50";
new GuiMLTextCtrl() {
position = "10 100";
text = "This is a sample text...";
};
};
Better would be nesting GuiMLTextCtrl into a GuiScrollCtrl and then both in a GuiWindowCtrl.
new GuiWindowCtrl(myWindow) {
position = "200 200";
extent = "150 150";
minExtent = "8 8";
visible = "1";
text = "My Window";
reszieWidth = "1";
reszieHeight = "1";
canMove = "1";
canClose = "1";
closeCommand = "myCloseWindow();";
canMinimize = "1";
canMaximize = "1";
minSize = "50 50";
new GuiMLTextCtrl() {
position = "10 120";
text = "This is a sample text...";
};
new GuiScrollCtrl() {
horizSizing = "width";
vertSizing = "height";
position = "0 20";
extent = "150 126";
minExtent = "8 8";
visible = "1";
hscrollBar = "dynamic";
vscrollBar = "alwayson";
constantThumbHeight = false;
childmargin = "10 10";
new GuiMLTextCtrl( myScrollText )
{
extent = "130 120";
text = "This is a sample text...";
};
};
};
Experimnet with the positions and extents. Note that the scrollbar always comes with its own "content canvas", thus it does not scroll the content of an other control (as it is the case, e.g., with XMotif widgets, xforms or Qt).
[edit] GuiTextCtrl and TorqueML
You can dynamically add text to the GuiTextControl by calling the following fuction via a button:
function addSomeText()
{
myScrollText.setText( "the set up and operation of the player's in-game interface." );
myScrollText.addText( "more and more text and more and more is coming in ...", false );
//myScrollText.addText( "more and more text and more and more is coming in ...", true );
}
When you add more then one line you can postpone the refomatting until after the last line, using:
myScrollText.forceReflow();
myScrollText.scrollToTop();
myScrollText.scrollToTag();
using the tag tag, for example:
<tag:3>
function addSomeText()
{
myScrollText.setText( "the set up and operation of the player's in-game interface." );
myScrollText.addText( "more and more text and more and more is coming in ...", true );
myScrollText.addText( " <spush> after spush <font:arial:18> font this <spop> is the second line :----more and more text and more and more is coming in ...", true );
myScrollText.addText( " <spush> after spush <font:arial:18> font this <spop> is the second line :----more and more text and more and more is coming in ...", false );
myScrollText.addText( " <br><br><tab:60> tab 60<br>next line\tafter the tab<br>", false );
myScrollText.addText( " <br><br><tab:60> tab 60<br>next line but more in the first column\tafter the tab<br>", false );
myScrollText.addText( " <br><br><tab:60> tab 60<br><clip:58>next line but more in the first column</clip>\tafter the tab<br>", false );
myScrollText.addText( " <br><br><tag:1><tab:60> tab 60<br>next line\tafter the tab<br>", false );
myScrollText.addText( " <br><br><tag:2><tab:60> tab 60<br>next line but more in the first column\tafter the tab<br>", false );
myScrollText.addText( " <br><br><tag:3><tab:60> tab 60<br><clip:58>next line but more in the first column</clip>\tafter the tab<br>", false );
}
function myScroll()
{
myScrollText.scrollToTag( 1 );
}
[edit] Unicode / UTF UTF8 UTF16
http://tdn.garagegames.com/wiki/TorqueUnicode
http://tdn.garagegames.com/wiki/GUI/Fonts/New_Fonts
http://tdn.garagegames.com/wiki/TorqueLocalization
[edit] Input and Events
Torque Device and Input -> Input Event Processing in the GUI system
GuiNoMouseCtrl to move around a window,
Top parent of the chat HUD is GuiNoMouseCtrl.
GuiNoMouseCtrl to Position = 50,50 it will move everything below him to the correct location.
GuiNoMouseCtrl : http://www.garagegames.com/mg/forums/result.thread.php?qt=9397
[edit] Nested GUI Conrols
new GuiControlProfile( nonModal_Profile : GuiDefaultProfile )
{
Modal = false;
};
new GuiControl() {
//new GuiNoMouseCtrl() { // no mouse events also for children
....
Profile = "nonModal_Profile";
...
};
<pre>
===GuiMouseEventCtrl===
http://www.garagegames.com/mg/forums/result.thread.php?qt=53463
=Cursor=
http://www.garagegames.com/index.php?sec=mg&mod=resource&page=view&qid=8192
GUI Canvas: http://tdn.garagegames.com/wiki/TGB/Reference:_GuiCanvas
GUI Cursor: http://tdn.garagegames.com/wiki/TGB/Reference:_GuiCursor
http://torque.realinfo.de/index.php?title=Magic_Wand#Adding_a_Control_Button
=Tooltips=
I was looking for tooltips and I found this post. Just wanted to say that it is now inside of the engine. To access the tooltips you do it in the gui editor (F10) and go to the section that says tooltips.
=Bubble (balloon) text=
http://tdn.garagegames.com/wiki/ScriptStyleGuide
http://tdn.garagegames.com/wiki/TGB_GUI_Overview#GuiBubbleTextCtrl
=GUI Video=
http://tdn.garagegames.com/wiki/GUI/Video
=Links=
Interactive HUD: http://www.garagegames.com/index.php?sec=mg&mod=resource&page=view&qid=9687
GUIs and Photoshop layers: http://tdn.garagegames.com/wiki/GUI/Lessons/Complete_Change
Video buttons: http://www.garagegames.com/index.php?sec=mg&mod=resource&page=view&qid=12471
