Todays topic: Tooltips

Here’s a snippet of the changelog:

“Desktop.TooltipControl is now of type Tooltip.
Inherit the abstract Tooltip class to create your own Tooltip behaviour.
Tooltip inherits Frame. Override the SetContext method to receive the current tooltip context.
Several Desktop properties wered moved into this new class.
The TooltipControl defaults to a SimpleTooltip, which is an autosized label.” 

I think this sums it up pretty well. This change allows you to create Tooltip controls of arbitrary complexity. You can nest controls, animate them, position/align the whole salad where you want, or set AutoLayout to true and have the baseclass handle it for you.

This is important to understand:
In order to use your Tooltip control, you assign it to Desktop.TooltipControl.
This control is dynamically added/removed to Desktop.Elements, based on its Visible property.
This ensures it always stays on top of all other controls.

Note how i use the properties Delay, Opacity and Visible in the SimpleTooltip sourcecode below:

    // Simple text tooltip that fades in and out
    public class SimpleTooltip : Tooltip
    {
        private int FadeDirection = 1; // used to fade in&out
        private float DelayTimer; // timer to keep track of delay

        // label to display text
        public Label Label { get; private set; }

        // time (ms) it takes to fade in&out
        public float FadeDuration { get; set; }

        // time (ms) it takes before the tooltip fades in.
        // Delay only applies when the tooltip is completely faded out.
        public float Delay { get; set; }

        public SimpleTooltip()
        {
            Delay = 500f; // 0.5 seconds delay
            FadeDuration = 500f; // 0.5 seconds fade
            Opacity = 0; // start transparent
            AutoSize = AutoSize.HorizontalVertical;

            // lets just use a Label to display the tooltip as simple text
            Label = new Label();
            Label.BBCodeEnabled = true;
            Label.AutoSize = AutoSize.HorizontalVertical;
            Label.Style = "tooltip";
            Controls.Add(Label);
        }

        // Gets called when the tooltip context is updated.
        // This occurs when the Hot control changes.
        public override void SetContext(Control context)
        {
            // if there's no tooltip context
            if (context == null || string.IsNullOrEmpty(context.Tooltip))
            {
                // fade out
                FadeDirection = -1;
            }
            else
            {
                // grab the tooltip text
                Label.Text = context.Tooltip;

                // make the control visible
                Visible = true;

                // fade in
                FadeDirection = 1;
            }
        }

        protected override void Update()
        {
            // increment timer if delay isnt reached
            if(DelayTimer < Delay) DelayTimer += GuiHost.TimeElapsed;                          // if delay is reached             if (DelayTimer >= Delay)
            {
                // fade Opacity in/out over Duration depending on FadeDirection
                Opacity += (GuiHost.TimeElapsed / FadeDuration) * FadeDirection;

                // clamp between 0 and 1
                Opacity = Opacity < 0 ? 0 : (Opacity > 1 ? 1 : Opacity);
            }

            // make the control invisible when completely faded out
            if (FadeDirection < 0 && Opacity == 0)
            {
                Visible = false;
                DelayTimer = 0;
            }
        }
    }

There are a few things in 1.0.4 that i’d like to explain in more detail, as i’m convinced that users will wonder about some of my decisions in this version.

Breaking Changes

1. Control.Initialize was removed
The Initialize method used to be called in the Control base class, subclassed controls then used to override Initialize. This lead to subclass constructors being called after Initialize, which was confusing for most users and rarely useful. Because of this, we decided to remove Initialize completely.
As a result, all controls are now initialized in their constructors.

2. UVCoords were removed and replaced with Rectangle.
Style textures are now expressed in pixels instead of UV coords.
This makes building styles a lot easier, thinking in pixels is much more straight forward.
Thanks to all the Beta testers that urged me to make this happen!

3. Changed 2 method signatures in ISquidRenderer
ISquidRenderer.DrawTexture now uses a Rectangle instead of UVCoords.
The Rectangle represents the source texture rectangle in pixels.
Most renderer implementations benefit from this change, since Graphics APIs usually work with a similar rectangle struct layout.
ISquidRenderer.SetScissor now uses width/height parameters, instead of x2/y2
A small but important change to avoid redundant calculations in renderer implementations.

4. HScrollbar and VScrollbar replaced with ScrollBar
These two controls were redundant, so now there’s only one control, the ScrollBar.
You can change between horizontal/vertical scrolling via the Orientation property.

5. Naming conventions
We’ve aligned the naming conventions for events with those proposed and used by Microsoft.
Before 1.0.4 : control.OnMouseClick
After 1.0.4 : control.MouseClick

Fixes and Improvements

A lot of fixes to TextBox!
Such as blinking caret, clean linebreaks, selection color, and most importantly improved Text alignment.
When different font sizes are used in one line, the fonts will now align to their baseline.
Note that this is a first iteration of this fix and will most likely need some tweaking in the near future.
Further bugfixes include missing caret on first character and a wrong textoffset when selected text was deleted in a scrolled textbox.

Multiline TextBox aka TextArea!
This new control, as the name already reveals, provides multiline input, selection and arrow key navigation.
For now it does not support BBCode nor auto-textwrap, hard linebreaks are of course respected.
Both are being worked on and will hopefully make it into 1.0.5 or even an earlier hotfix.

Sample Project
We’re working on a new sample, with the intention of gearing it more towards a typical “Game” user interface. You will find a range of widgets that you are familiar with from many games, like an Inventory, Skillbook, Chatpanel, ActionBars, StatusBars, PaperDoll, item/action tooltips, and a command line Console.

Watch out for 1.0.4 hitting the download area very soon!

Note to Unity users: 1.0.4 will be out for Unity shortly after the SDK is updated. 

In development for 1.0.4:

• fading tooltips
• support for Angelcode BMFont
• improved Drag&Drop

Release Notes 1.0.3

• fixed Control.AutoSize now takes Controls and Elements into account
• fixed Label and classes derived from Label now chose AutoSize based on Text and Elements
• fixed ActiveList<T> now exposes events: ItemRemove, ItemAdded, ItemsCleared, BeforeItemAdded, BeforeItemRemoved, BeforeItemsCleared
• fixed a bug that caused only button 0 to fire some events
• fixed a bug that caused wrong linebreaks in Label.Text when TextWrap was true
• fixed Desktop.TooltipControl go out of screen bounds
• fixed a bug in Window.Show() that caused double modality
• fixed a potential crash when Window.Show() was called with null parameter
• fixed cursor position while resizing. cursor remains perfectly sticky now
• fixed text display problems with some special characters
• fixed wrong render order of textbox highlight
• fixed DropDownList not processing events when nested in a modal window
• fixed a bug that caused some controls to be inactive in a modal window
• fixed a null exception in ListBox.SelectedItem
• fixed ListBoxItem.Selected and LIstBox.SelectedItems now interact correctly
• fixed TextBox processing some input when ReadOnly
• fixed several bugs related to ListBox.SelectedItemChanged

• renamed virtual void Control.OnUpdate to Control.Update
• renamed virtual void Control.OnStateChanged to Control.StateChanged
• renamed virtual void Control.OnLateUpdate to Control.LateUpdate

• added new event Control.OnUpdate
• added new event Button.BeforeCheckedChanged
• added new control RadioButton, suppports grouping
• added new method Control.FindControls<T> to find direct children of a given type
• added int TextBox.HighlightColor to change the background color of selected text
• added property ListBox.SelectedItems and event ListBox.SelectedItemsChanged
• added ListBox.MaxSelected to limit the max number or selected items
• added Color.Tint property. Used to tint the control style.
• added Flipbook class for animated texture uv coords
• added FlipbookCursor class for animated cursors

Note:

I was asked to include a GridView control in this release, but i wasn’t able to finish it.
So instead of rushing it i included the unfinished GridView sourcecode as part of the SampleControls project!
This gives everyone another example of how to develop your own complex controls using Squid.

Release note:

- fixed a fatal bug in XmlSerializer
- fixed an issue with smooth scrolling getting out of bounds on low frame rates

- added MouseEventArgs to OnMouseClick/MouseDown/MouseUp/MousePres/MouseDoubleClick
- removed Control.OnKeyEvent
- added Control.OnKeyDown and Control.OnKeyUp
- MouseEventArgs carry the mouse button index
- KeyEventArgs now carry the key/scancode that is down or up

- added GridView control sourcecode to SampleControls

See the downloads section.

Below the release notes for this version.

General:
- fixed several exceptions in base Control class
- fixed wrong Font offset caused by TextPadding.Bottom
- fixed wrong Font offset when TextAlign.MiddleLeft/Right/Center was used
- fixed Font import for fontbuilder Divo files (Unity3D)
- fixed Font rendering issues with large fonts (Unity3D)
- added bool Slider.Ease, float Slider.EasedValue for smooth content scrolling
- added Ease/EasedValue to HScrollbar and VScrollbar
- added enum: Alignment.Inherit
- added enum: TextureMode

TextureMode.Stretch : stretch texture to fit control
TextureMode.Grid : use 9slice defined in style.Grid
TextureMode.GridRepeat: like Grid, but repeats the borders
TextureMode.Repeat : repeat texture on both axis
TextureMode.RepeatX : repeat texture on X
TextureMode.RepeatY : repeat texture on Y

* Glyph (Unity3D)
- added fields: Width, Height, OffsetX, OffsetY, Advance

* Style
- removed properties: GridEnabled, GridRepeat
- added property: Tiling (defaults to TextureMode.Stretch)
- Style.TextAlign now defaults to Inherit

* Label
- added property: TextAlign (defaults to Alignment.MiddleLeft)
- Text will now use control.TextAlign if style.TextAlign is Inherit.

The SDK download is available again. See the downloads section.

Below the release notes for this version.

General:

- added Squid.Xml.XmlSerializer for loading/saving desktops, controls and skins
- added (Label) Leading (en.wikipedia.org/wiki/Leading)
- added (Label) BBCode support (font, color, url, img)
- added (Label) clickable links (Label.OnLinkClicked(string url))
- added style.GridRepeat (repeats left/top/right/bottom slices)
- added control.TabIndex
- added control.Animation
- added Skin class
- added VS9 and VS10 solutions
- added SplitContainer.Orientation (hor/vert)
- added Control.GetControl(string name). (searches any depth)
- added Control.MinSize/MaxSize (only used if maxsize > 0)
- added DockStyle.Middle/Center
- added Desktop.TooltipAlign (TopLeft/TopRight/MiddleLeft/etc.)
- renamed SplitContainer.Aspect to AspectRatio
- SplitContainer.Frame1 now respects MinSize/MaxSize
- Desktop now also fires OnDragDrop if drop target was null

Fixes:

- Squid.GUI renamed to Squid.GuiHost to avoid conflicts with other libraries
- fixed window resizing behaviour in respect to min/max size
- fixed (Label) TextAlign (text is now properly aligned in all cases)
- fixed FlowLayoutFrame not updating correctly if AutoSize != None
- fixed Panel.Content not showing sometimes
- fixed Opacity for drawn text
- fixed InputManager examples (SlimDX, XNA)
- moved StyleMap.cs to example code
- replaced XNA3.1 with XNA4.0
- removed System.Xml

Notes:

- Tab, Shift+Tab now cycle through tabs (not hierarchical)
- TextAlign and TextWrap now work together
- TextWrap is disabled if AutoSize != None
- Controls can now be animated via coroutines (see code samples)
- added XmlReader, XmlWriter, XmlSerializer, XmlIgnoreAttribute, HiddenAttribute

-
Some of you might have used the XNA SpriteBatch or the SlimDX Sprite in order to batch quads.
And a few of you might have wondered why changing the ScissorRect between batch.Draw calls doesn’t do what you expect.

The explanation is really simple when you understand what the batch class does under the hood:
Every Batch.Draw call stores a single primitive in the batch. The next call to Batch.End then updates a dynamic vertex buffer, binds it to the device and issues a Device.Draw call.

There is no way to change the scissor rect in between batch.Draw calls.

The only way around this is to end the batch, change the scissor rect, and start the batch again, which is exactly what Squid does.  But this leads to more draw calls, actually as many as there are scissor rect changes.

In practice, the batch will also submit a Device.Draw call for every different texture that was used in Batch.Draw, in order of appearance. And this leads to even more draw calls. Some batches give you the option to sort by texture, which is convenient in some situations, but not relevant for GUI drawing. For our purposes, all we need is an alphablended painters algorithm aka everything is drawn in the order it was submitted.

Now, all of this is not a big problem, since you can clip your quads manually before drawing them in a batch.
That way you can avoid the hardware scissor rect alltogether, but that’s where fonts become a real problem.
Even in XNA 4.0 the SpriteFont class doesn’t let you do software clipping. In order to clip fonts pixel perfect,
you either need to use the hardware scissor rect (which we’re trying to get rid of here) or roll your own SpriteFont class.

The solution is a custom SpriteFont class that respects the current software scissor rectangle.

All in all, here’s what we have to do in order to reduce draw calls, and possibly even reduce the whole GUI rendering to a single Device.Draw call:

• replace hardware scissor test with software clipping (scissor quads before sending them to the batch)
• use custom spritefont (scissor glyphs  before sending them to the batch)
• avoid texture switches (use texture array or atlas, depending on available hardware)

How is this relevant for Squid?

-
Whenever the scissor rect changes, Squid makes a call to Renderer.EndBatch, Renderer.Scissor, Renderer.StartBatch.
This degrades the performance of batching. Imagine every single control would scissor. That’s right, this would result in 1 draw call per control, which is not acceptable.

So it’s very important to wisely decide which controls actually need scissor and which do not.
This is why Squid lets you enable/disable the scissor testing via the Control.Scissor property, which is false by default.

But there is more.
Because i assumed any renderer implementation would use the hardware scissor test, Squid sends you un-clipped  quads. A little known fact that will change in the next version, where Squid will send you software clipped quads with correctly adjusted UVs. Which means, everything but text will be clipped correctly, even without the hardware scissor test!  The clipping itself is boiler plate code which will be wrapped away in Squid. And Squid will still give you a scissor rect which you can use to clip font glyphs.

Hint: You can do all this by yourself already, if you use a custom SpriteFont equivalent!

Wait, when we don’t use hardware scissor, why stop the batch? The answer is we don’t have to.
Squid will still make the same calls to EndBatch/Scissor/StartBatch, but you can ignore every End/Start betwen the first Start and the very last End call. I’ll show an example of this in my next blog.

Why that is important:

1. Smart users can use Squid with software scissor on every single control at virtually no cost.
2. Very smart users can reduce the whole GUI rendering to a single Device.Draw call.
3. Unity3D renderer will be possible to implement in several ways.

How do i get optimal Squid performance:

1. Use software clipping, also for fonts.
2. Use less textures. Merge textures into arrays or an atlas.

Upcoming Squid changes:

1. Squid will send you clipped quads with clipped UVs.
2. EndBatch will change to EndBatch(bool final), to signal when the whole GUI rendering is done.
3. Squid will include a sample XNA4.0 renderer.
4. Squid will include a sample DirectX11 renderer, using PointList and Geometry Shader.

I’ll explain more about #4 in my next blog: An optimal Squid renderer in DirectX11.

Stay tuned.

Small maintenance update.

Release notes:

• added Desktop.TooltipOffset
• added Window.AllowDragOut
• added ISquidRenderer.TranslateKey
• added experimental DropDownButton class
• renamed ComboBox to DropDownList
• TreeNode is no longer a text control. use TreeNodeLabel or create your own custom class.
• updated sample renderer sourcecode to translate virtual keys
• SQUID should now be be fully XBOX/Win7 compatible

Grab the new download HERE and have fun with it!

We completely revamped the samples, moved everything into one solution and included sample projects for Truevision3D, XNA3.1 and SlimDX. Added a few new controls, drag&drop and a brand new and slick looking style.

Screenshot of the code samples in action:

Release notes:

• added TabControl
• added HScrollBar control
• added Panel control
• added Drag & Drop
• added SlimDX sample
• added XNA 3.1 sample
• added a completely new style
• lots of bug fixes

Grab the new download HERE and have fun with it!

Take a look at the source code:

 public abstract class Dialog : Window
    {
        private DialogResult _dialogResult;

        public delegate void DialogResultEventHandler(Dialog sender, DialogResult result);
        public event DialogResultEventHandler OnDialogResult;

        protected DialogResult DialogResult
        {
            get
            {
                return _dialogResult;
            }
            set
            {
                if (_dialogResult == value) return;

                _dialogResult = value;

                if (OnDialogResult != null)
                    OnDialogResult(this, _dialogResult);
            }
        }

        public override void Show(Desktop target)
        {
            _dialogResult = DialogResult.None;
            base.Show(target);
        }
    }

As you can see, it’s a rather naked class, but the event is valuable once you start using modal dialogs, such as confirmation dialogs, notification popups, etc.

For obvious reasons, we cannot stall the game loop in order to wait for user input.
Instead we use a straight forward delegate to catch the dialog result.
Lets take a look at  how you make use of this.

We start by writing our own little Dialog:

    public class MyDialog : Dialog
    {
        protected override void Initialize()
        {
            // set some default size
            Size = new Point(200, 100);

            Button buttonCancel = new Button();
            buttonCancel.Text = "Cancel";
            buttonCancel.Size = new Point(200, 35);
            buttonCancel.Dock = DockStyle.Bottom;
            Controls.Add(buttonCancel);

            Button buttonOK = new Button();
            buttonOK.Text = "OK";
            buttonOK.Size = new Point(200, 35);
            buttonOK.Dock = DockStyle.Bottom;
            Controls.Add(buttonOK);

            // set the dialog result as needed
            buttonCancel.OnMouseClick += delegate(Control sender) { DialogResult = DialogResult.Cancel; };
            buttonOK.OnMouseClick += delegate(Control sender) { DialogResult = DialogResult.OK; };
        }
    }

Phew, that was straight forward.

And here is how we open the dialog and handle possible results :

        MyDialog dialog = new MyDialog();
        dialog.Modal = true;
        // handle the result
        dialog.OnDialogResult+=new Dialog.DialogResultEventHandler(dialog_OnDialogResult);
        dialog.Show(this);

        void dialog_OnDialogResult(Dialog sender, DialogResult result)
        {
            // do something
        }

And that’s it already!
Note that the Dialog will have to be closed in order to access the rest of the GUI again:

        void dialog_OnDialogResult(Dialog sender, DialogResult result)
        {
            // do something with result
            // and close it
            sender.Close();
        }

You can open as many modal dialogs as you like, and they have to be closed in order of appearance. Exactly like you’re used to from your operating system.

Take a good look at the MessageBox class in the latest version of the demo application. It shows how to inherit Dialog and create a resemblence of the  Windows.Forms.MessageBox functionality.

Just grab the latest version and have fun!