From EagleEye TV Projects

Please join the EEGUI Google Group for help, support, and to get the latest DLL download.

Contents 1 EEGUI by EagleEye 1.1 Introduction 1.1.1 EEGUI Design and Design Goals 1.1.2 EEGUI Features 1.1.3 Change Log 1.1.4 User Testimonials 1.2 Getting/Purchasing EEGUI 1.2.1 Download Link 1.2.2 License Agreement 1.2.3 Purchasing Information 1.3 EEGUI Features 1.3.1 Extendability 1.3.2 Controls 1.3.3 Colors and textures 1.3.4 Other features 1.3.5 Screenshots 1.3.6 Demo Video 1.4 EEGUI Documentation 1.4.1 Requirements 1.4.2 Class Structure 1.4.2.1 Controls 1.4.2.2 Other Classes 1.4.2.3 Structs 1.4.2.4 Enums 1.4.3 Implementing EEGUI in your project 1.4.3.1 A sample render loop 1.4.4 Creating your own extended controls 1.4.5 Events 1.4.5.1 guiControlBase Events 1.4.5.2 guiButton Events 1.4.5.3 guiCheckbox Events 1.4.5.4 guiTextBox Events 1.4.5.5 guiList 1.4.5.6 guiProgressBar

EEGUI by EagleEye

Introduction

EEGUI is a GUI system developed in Visual Studio 2005 using Visual Basic .NET.

EEGUI stands for EagleEye's GUI.

EEGUI Design and Design Goals

EEGUI was designed with two main goals in mind: Ease of GUI development, and extensibility using a pure Object-Oriented approach. Developers using EEGUI should be familiar with OOP concepts, and should read this documentation completely (or at least refer back to it often) to understand how to utilize the functionality contained within EEGUI.

Regarding the Ease-of-use goal, the main accomplishment in this area was the ability to quickly create, size, and position GUI objects within your code. What this meant to EagleEye was allowing for the instant instantiation of GUI objects via the "New" command (in VB).

For example, instead of having to do "Public ThisButton as guiButton", then later having to do "ThisButton = new guiButton", you can simply declare your button as "new" right away. "Public ThisButton as New guiButton" in the declarations area of your class.

All objects created as new instances of an object take zero parameters, and have a slew of default parameters. By requiring no parameters during instantiation, users are able to simply "new" everything without having to specify a parent, size, width, etc...

Regarding the extensibility goal, EEGUI has been programmed according to strict OOP standards. This means that properties, variables, events, and methods for each control type are ONLY a part of their specific control. An example of this is that while all controls may have a "MouseUp" event, it's only when you get to the guiButton type where you see a "Triggered" event (because a button may be triggered by the space or enter keys, rather than just the mouseup event).

Utilizing an Overridable render sub, each portion of a control is rendered on each level of the inheritance. This also allows the user of EEGUI to extend that render sub in their own custom controls by simply declaring a "Public Overrides Sub Render" in their own custom objects (which then calls MyBase.Render).

EEGUI Features

EEGUI has many features that are needed for a GUI.

- It's fast!

By using a special "redraw" flag, the GUI is only re-rendered when something changes. Most GUIs are pretty static from frame to frame, so EEGUI utilizes a rendersurface that is drawn to, which acts as a holder for the painted 2D image between frames. This rendersurface is only cleared and redrawn if something on the GUI changes (like a background color of a control, or the size/location of a control, etc). In testing, we had a base FPS of 250 when rendering just our scene without the GUI. When re-rendering the GUI every frame, that FPS dropped to 90. Once the redraw flag was added, the FPS went back up to 250, with only minor dips during mouseover events. FPS will probably decline significantly during control dragging operations, since the GUI is changing just about every frame, but it shouldn't drop as bad as when redrawing the GUI every frame.

With the addition of a "redraw throttle", EEGUI now allows you to say "I don't want the GUI redrawn unless it's been (X)milliseconds since the last redraw happened". Setting this to 50, for example, ensures at least 20fps, even when changes are happening every frame.

- It's extensible!

Users are highly encouraged to create their own top-level classes for their objects, which inherit the base classes contained in EEGUI. The EEGUI base classes only contain properties and methods for handling the GUI's core functionality. Default values are set, but the user will want to change many of these values. For more information on this, see below in the documentation.

- It's flexible!

Do you want your controls to have a normal color, a different color when the mouse is over the control, a different color when the control has focus, and yet another color when the control is not enabled? All controls have those four colors defined, with the ability to enable/disable each of them! Want to use textures instead? There are the same four types of textures, all able to be enabled/disabled.

- It's easy to use!

Creating a GUI is tough without a forms designer to use. This is the main gripe of many developers used to working with VB6 or Visual Studio. Well, EEGUI doesn't have a visual window designer, but it DOES have helper functions for positioning controls! Want to center your control? Want to position a control relative to another? You can do so easily, without having to do all of that math yourself, or remembering which variables to use.

- Sample Code is included!

The EEGUI package comes with the core DLL, and heavily commented source code in the demo application.

Change Log

For a log of changes, Go Here

User Testimonials

Check out EEGUI User Testimonials here!

Getting/Purchasing EEGUI

Download Link

To download EEGUI, please visit the EEGUI Google Group

License Agreement

EEGUI is currently free to use for anyone who wishes to do so. Non-Licensed users will be forced to endure a watermark/unregistered logo on the top left of their windows.

For more information about what you are granted with your purchase/license, please go here

Purchasing Information

You can purchase EEGUI by sending $65 via PayPal to eagleeye@eeisi.com - Please include your desired username.

EEGUI Features

Extendability

EEGUI is designed to be extended by you, the developer that uses the EEGUI.dll. What this means is that you can create your own custom controls simply by inheriting from the base controls. Does this mean EEGUI doesn't have its own enhanced controls? On the contrary, there are plenty!

Controls

Base controls include: Label, Button, Textbox, Image, Checkbox, and Window. Complex/enhanced controls include: Combobox, Listbox (which is sortable in multiple ways), Progress bar, and an Enhanced Window (with scrollbars, resizer, title bar/handle, and topright button (for use as a close button, or other interaction button)), and many more!

Colors and textures

EEGUI supports normal and alpha texturing. For both solid colors and textures, there are many options on EACH CONTROL for making your controls customized. Base color/texture, Selected (focus) color/texture, disabled color/texture, and a border color, all 100% customizable for each control.

Other features

Screenshots

Demo Video

Click here for demo video (WMV format, 16 MB)

EEGUI Documentation

Requirements

TrueVision3D 6.5 Beta
Visual Studio 2005 (and thus, .NET 2.0)

EEGUI should be usable by developers who develop in VB.NET, C#, or any other .NET language, so long as they're using VS2005 and .NET 2.0. If you are unable to do so, let EagleEye know.

Class Structure

Controls

guiControlBase

- guiImage

- - guiRotatingImage

- - guiProgressBar

- - guiCheckbox

- guiLabel

- - guiButton

- - guiTextBox

- - - guiTextWindow

- - guiMultiLineLabel

- guiWindow

- guiAttachableControl

- - guiWindowHandle

- - guiWindowTopRightButton

- - guiResizer

- - guiSliderBase

- - - guiSliderHorizontal

- - - guiSliderVertical

- guiListBox

- guiComboBox

- guiRadioButton (incomplete)

- guiValueSlider (Horizontal and Vertical)

More controls will be added at a later date

Other Classes

ColoredComponent - Has Base, Selected, MouseOver, and Disabled GUIColor objects

GUITexture - Defines a texture used in the GUI. Contains Texture name string, IsAlpha boolean, AlphaColor, and an Enabled flag.

GUIColor - Contains Color Integer, and TVColor <-> Color conversion automatically built in. Contains "Enabled" flag.

MouseState - Contains the current mouse state on each frame, including all buttons, mousewheel, x/y position on screen, etc...

Structs

PaddingStruct - Contains padding values: Top, Left, Right, Bottom.

ViewportData - Struct used internally. Even though this is public (so all EEGUI classes can see it), it should not be modified or accessed by the user.

Enums

GUIMousebuttons - Left, Right, Third, Fourth - Used in mouse events (such as MouseDown, Click, etc) to identify which button triggered the event.

HorizAlign - Left, Center, Right - Used for text alignment.

VertAlign - Top, Center, Bottom - Used for text alignment.

EscapeActions - Do Nothing, Close Window, Hide Window, Raise an Event - Used for determining what a window will do when escape is pressed.

Orientation - Horizontal or Vertical - Used in various areas for determining which direction to go.

DiagnoalDirection - All controls that inherit from the guiLabel control can set the text's shadow direction. BottomRight is default, but the other 3 directions are available as well.

RelativeDirections - Above, Below, Right, Left - Used for relative positioning of controls.

Sides - Top, Left, Bottom, Right - Used for relative positioning of controls.

Dimensions - Height, Width - Used for relative positioning of controls.

RelativeDirections - Left, Right, Above, Below - Used for relative positioning.

SortingMethods - DoNotSort, ByName, ByTagID, ByTagString, ByText - Used to set sorting behavior of listboxes/comboboxes.

ToolTipDirections - All 8 directions around the cursor.

ControlStates - Normal, MouseOver, MouseDown, Selected, Disabled.

DragBehaviors - DoNotAllow, DragWithinParent, PluckFromParent - Tells the engine how to treat a control that is being clicked and dragged. DragWithinParent directly modifies the "Position" variable, but maintains the same parent. PluckFromParent immediately changes the control's parent to the GUI Desktop, and moves it within that, expecting it to be dropped on another control that allows dropped controls.

AutoSizingMode - DoNotAutosize, GrowOnly, ShrinkOnly, GrowAndShrink (default) - Textboxes and labels can be set to autosize using this enum on the AutoSize property.

AutoSizingDirections - Both, Height, Width - If autosizing is on, you may want the autosizing to only be in a single direction.

Implementing EEGUI in your project

EEGUI can easily be plugged in to a current TV project by following these steps:

- Move the EEGUI.dll to your project's bin folder, or wherever you keep add-on DLLs for your project.

- Add EEGUI.dll as a reference. Optionally, you can select to always "Imports" EEGUI in to your classes (recommended).

- Add a variable "as EEGUI" to your app's main form or module. Do not "new" it!

Public GUI as EEGUI

- (Recommended) Create your own base GUI class (such as MyGUI) to contain all of your main windows.

Public Class MyGUI
  Public MyMainWindow as New MyWindow
  Public MyOtherWindow as New MyWindow
End Class

- In that class, create an Initialize sub. In that sub, "new" the GUI object you created before.

  GUI = new EEGUI

The Render Window MUST BE SHOWN before EEGUI is instantiated, so it gets the initial viewport height and width.

In your form's "new" sub, call "Show" before you call MyGUI.Initialize.  See included demo source code for the proper sequence.

- Initialize your gui and anything that will be placed on the main GUI Desktop.

At this point it is important to understand how to create your own definitions for your own extensions of the EEGUI classes. Skip down to that part of the documentation before continuing.

- Initialize your GUI. You will want to do this as one of the last things you do when creating your scene, just prior to starting your render loop.

Public Class MyGUI
  Public MyMainWindow as New MyWindow
  Public MyOtherWindow as New MyWindow

  Public Sub Initialize
     GUI = New EEGUI
     MyMainWindow.Initialize
     MyOtherWindow.Initialize
  End Sub
End Class

- In your render loop, you MUST DO TWO THINGS.

- PRIOR TO THE TV.CLEAR CALL - Update the GUI

GUI.UpdateGUI

- JUST PRIOR TO YOUR TV.RENDERTOSCREEN CALL - Render the GUI. (This ensures the GUI is rendered last, on top of everything else.)

GUI.Render

That's all there is to it!

A sample render loop

   Private Sub DoRenderLoop()
       Do
           Try
               CheckInput()
               GUI.UpdateGUI()
               TV.Clear(False)
                Insert your other render calls here for things like sky, land, meshes, etc...
               GUI.Render()
               TV.RenderToScreen()
               Application.DoEvents()
           Catch ex As Exception
           End Try
       Loop Until EEGUIDemo.Shutdown
   End Sub

Creating your own extended controls

The GUI's base controls (those prefixed with "gui", such as guiLabel, guiButton, guiTextbox, etc) give all of the basic functionality, and default parameters of each control. It's wise, however, to create your own extensions of these classes to define YOUR preferred parameters for your controls. These extended controls would do things such as specifying your textures, enabling/disabling colored areas of the control (like, "Background.MouseOver.Enabled = False" to disable the background mouseover color), and for specifying default sizes and behavior (such as centering text on all of your buttons).

Because of the open-ended parent/child relationship of the controls, it is actually possible to add additional controls to any other control. If you want, you can put a label on your images, or 2 or 3 labels on the same image, if you want. Imagine having an image with 3 labels, aligned top left, top right, and centered, all on the same GUI image... that's what we mean when the GUI is able to be extended to suit your specific needs!

Even still, you will want to specify all of the parameters in your own controls which inherit the EEGUI controls.

Here is an example of an extended control.

Imports EEGUI

Public Class MyButton
   Inherits guiButton

   Public Sub Initialize(ByVal LabelText As String)
       Text = LabelText
       Me.Background.Enabled = False
       Me.Border.Enabled = False
       Me.TextAlignHoriz = HorizAlign.Center
       Me.TextAlignVert = VertAlign.Center
       Size = New Size(100, 20)
       FontIndex = SText.TextureFont_GetFontByName("Main")
       With Texture
           .Enabled = True
           .Tex = "buttonBack.jpg"
       End With
       With MouseOverTexture
           .Enabled = True
           .Tex = "buttonOver.jpg"
       End With
       With SelectedTexture
           .Enabled = False
           .Tex = "buttonDown.jpg"
       End With
       With DownTex
           .Enabled = True
           .Tex = "buttonDown.jpg"
       End With
       With Background
           .Enabled = False
           .Base.Color = CONST_TV_COLORKEY.TV_COLORKEY_GREEN
           .MouseOver.Enabled = True
           .MouseOver.Color = CONST_TV_COLORKEY.TV_COLORKEY_YELLOW
           .Selected.Enabled = True
           .Selected.Color = CONST_TV_COLORKEY.TV_COLORKEY_RED
       End With
       With Foreground
           .Enabled = True
           .Base.Color = CONST_TV_COLORKEY.TV_COLORKEY_WHITE
       End With
       With ForeShadow
           .Enabled = True
           .Base.Color = CONST_TV_COLORKEY.TV_COLORKEY_BLACK
       End With
       With Border
           .Enabled = True
           .Base.TVColor = New TV_COLOR(0.5, 0.5, 0.5, 1)
           .MouseOver.Enabled = True
           .MouseOver.Color = CONST_TV_COLORKEY.TV_COLORKEY_WHITE
           .Selected.Enabled = True
           .Selected.TVColor = New TV_COLOR(0.75, 0.75, 0.75, 1)
       End With
       Alpha = 1
       Foreground.SetAlpha(1)
   End Sub
End Class

As you can see, this class doesn't have anything in it except for an Initialize sub that specifies all of the textures, disables a few colors, specifies the colors of those colors that are enabled. By creating your own custom class, you avoid having all of this code being repeated in your GUI initialization code. Simply create a new instance of MyButton! If you have different types of buttons, it's a simple thing to either inherit from your own MyButton class, or create a new class (MyOtherButton) that defines different parameters.

Events

EEGUI has a whole bunch of events that are raised depending on various things that happen to the controls.

guiControlBase Events

   Public Event Click(ByVal MouseData As MouseStates)
   Public Event DblClick(ByVal MouseData As MouseStates)
   Public Event MouseDown(ByVal MouseData As MouseStates)
   Public Event MouseOver(ByVal MouseData As MouseStates)
   Public Event MouseLeave(ByVal MouseData As MouseStates)
   Public Event MouseUp(ByVal MouseData As MouseStates)
   Public Event DragStart()
   Public Event Dragging()
   Public Event DragStop(ByVal PreviousPosition As Point)
   Public Event DragDrop(ByRef DroppedObject As Object)
   Public Event GotFocus()
   Public Event LostFocus()
   Public Event Resized()
   Public Event Moved()
   Public Event Shown()
   Public Event Hidden()
   Public Event KeyInjected(ByVal K As TV_KEYDATA)
   Public Event ParentChanged(ByRef NewParent As guiControlBase)
   Public Event ChildAdded(ByRef NewChild As guiControlBase)
   Public Event ChildRemoved(ByRef OldChild As guiControlBase)
   Public Event ChildrenChanged()
   Public Event TabPressed()
   Public Event MouseScrolledUp()
   Public Event MouseScrolledDown()

guiButton Events

   Public Event Triggered()

guiCheckbox Events

   Public Event Toggled()

guiTextBox Events

   Public Event KeyPressed(ByRef TVKeyCode As TV_KEYDATA)
   Public Event KeyReleased(ByRef TVKeyCode As TV_KEYDATA)
   Public Event EscapePressed()
   Public Event TextChanged()

guiList

   Public Event ItemClick(ByVal Item As guiControlBase)

guiProgressBar

   Public Event FillPercentChanged(ByVal Percent As Single)