http://wildfiregames.com/~code/resources/divisions/GUI/TDD/GUI_Engine_TDD_1.41.doc

http://wildfiregames.com/~code/resources/divisions/GUI/TDD/GUI_Engine_TDD_1.41.xls

== '''Underscores versus Hyphens''' ==

The GUI interface now lets you interchangeablely use underscores instead of hyphens: 

`object.cell_id`

is exactly equivalent to 

`object["cell-id"]`

As a naming convention, it's best to just stick to alphanumerics (A..Z, a..z, 0-9) and underscores wherever possible since the hyphen is a reserved character.

== '''New Sizing''' ==

(posted by Gustav, 24th November 2003)

Okay fellow GUI-guys, the new sizing is now implemented and you will have to start sketching the GUI in the lowest allowed resolution, and also how things should tile or stretch or whatever you want them to do when the resolution is higher than that.

Now each object's size and position is described with not 4 values like before, but with 8 values, the doubling is because now there is a percentage-modifier. You see if you want to place something so it sticks out from the right edge of the screen 10 pixels, you want the '''left''' being "100%-10" and the '''right''' being "100%"... Do you follow me? In the XML files you now go like: "0 50%-10 100% 50%+10" or something like that.

Got it?

== '''Controls Specifications''' ==

(posted by Gustav, 2nd January 2004)

I thought I'd compile a little list of the basic controls and how the will work both technically and graphically... This way you can comment on things and suggest changes/additions... I just want to know I am on the same page as you guys :)

I will write this in "this is how it is," but don't think that isn't changable... It's just, if you have suggestions, and I decide to change things, then I will edit this document.

Notice also that when a sprite fills a whole area, remember that a GUI sprite can have *real* images outside the sprite's perimeter. Just so you know the graphical 
potential. Also sprites are always optional, many times text is to too!

'''Frame'''
Filled with a sprite. Does nothing beyond that. If you remove the sprite it is equivalent to an "Empty" control.

'''Button'''
A button consist of a sprite filling all of its size and text that can be placed in any alignment. When hovered, pressed or disabled, both the sprite and the text color can be changed.
The buttons work as in Windows, you can press it, but it is once you release it the action is committed.

'''Text'''
A text box has got a sprite filling all of its size, text can be placed in any alignment. A horisontal scroll-bar can be added (and it will always show, like in Internet Explorer, even when there is nothing to scroll... would you like this to change?). When a scroll-bar is added, valign is omitted and "top" is always used.

Images can be inserted both like smileys :) and like images. Also font, size and color of text will be able to be changed with syntax similar to the one on this forum. This control will be alone with these features, they will not be generic to all text rendering (or do you want them to be that?).

'''Input'''
An input is a sprite filling all of its size, and text that can be edited. You will be able to edit this text as in a Windows edit box. Selecting a section of it will make a sprite appear in below the text (remember they can be monochrome), and a specific text color for parts that are selected can be set.
The text being inputted will never span more than a single row. If too much is entered the same as in a windows text box will happen: A horisontal scrolling but with no idicator than the text itself.
The option of making the caption being cleared the first time the edit box is receiving focus is available. Such as: "Enter your name here", and then when you press it, it clears. Also that initial text might be in another color (unless you wanna scrap the feature).
Ideally I would like to support clipboard features, such as paste (from outside the application... It is WONDERFUL for IP-adresses and domain names for servers)... I haven't researched the technicalities of this (vis-�-vis SDL) yet.

'''Empty'''
Has got no functionality at all, works as a container for children. Can be used as a coordinate-system for instance, making the children relative in position. Will also be the default type, so one could go <object> </object> in the XML files, and one would have a container that per se wouldn't be interactable or do anything.
Notice if you give the empty class a size and position, it will catch (although not do anything with) the mouse-over if that is the case. In other words, it will be a glass layer. The option of removing this behavior is available though (as is for all controls).

'''Progress-Bar'''
A progress-bar is given the value between 0 and 100. First a sprite is drawn to fill the whole size of the progress-bar. Then another sprite is drawn on top of the first one, but spanning only to an extent, representing the given value, in width... In height it is the same as the first one.

'''Check Box'''
A check-box contains a squared sprite to the left (or right) with text on the opposite side. The square itself can have 8 different kinds of sprites (although many are optional): false, false-over, false-pressed and false-disabled, true, true-over, true-pressed, true-disabled... false and true being unchecked and checked. By pressing the whole size of the check-box one can change its value (the pressing is of the same behavior as a button); notice that implies that the text can also be pressed, not just the square itself.

'''Radio Button'''
A radio button is derived from the check-box, so it is similar in all ways, except that when pressed, the box pressed is always set to checked, and the siblings (!) is set to false (unchecked). To make a group of radio buttons, it is advised to use an object of type empty; and fill it with nothing but radio buttons that you want to group!
Also, the little difference between the check box and the radio button will of course change when you make intuitive graphics for them that will accentuate the difference (round and square I presume) :)

'''List Box'''
I won't explain this in detail because I hope everyone knows how a list box looks (I can fetch images otherwise). One sprite will cover the background (even behind the scroll-bar, this is because one could set a border outside this area), one sprite will be the background of the selected element. Only one element can be selected at once. A scrollbar will be attached to the right, although optional if should be present even when there is nothing to scroll.

[b]Drop Down [list]
A drop down list box is like a list box (informational), only it hides the unselected items. Yes we've all seen them so I need not to explain further. Anyway, there will be a squared button to the right, it will be able to change sprite when hovered/pressed/disabled. When pressed an area below will appear, it will graphically be equivalent to the list box (including scrollbar stuff), but it will disappear when pressing outside (that press won't do squat to the outside, if you were hovering a button, you will have to presst twice. Like in Windows... Do tell me if this is a nuisance rather than a intuition, since the other way is simpler, technically).

'''Slider'''
I forgot the slider, will need some feedback on how you guys want the slider to look. Horisontal? Vertical? With markers? Snap to the markers?

'''Menu'''
A menu system like "File Edit ..." in Windows. One will be able to make a row of root menus. After pressing a root menu, its sub-menu appears. Sub-menus can also have sub-menus, in an unlimited spectrum. The menu structure is declared in XML within the <object ...></object> of the menu object.
The root menus will always open downwards (these menus are meant to be placed on the top of the screen). Sub-menus will be opened like in windows, next to the arrow, but on top of its parent. An element will be able to be: something that executes a script, a parent (that opens a sub-menu) or a seperator. Elements and root menus will be able to be disabled.
Icons will be able to be attached to these elements (icons are just textures).
Once a menu is opened it won't be closed until having pressed outside, hovering an element that opens a sub-menu for a brief moment, will open the sub-menu, one can also click it. Hovering an element of a different kind for the same amount of time, will close the sub-menu (this is just like Windows).
There is a lot of behaviors to explain here, but I will try making it as alike as windows as possible. Some things will inevitably vary.
Elements will be declared either 'always visible' or 'initially hidden'. The ones initially hidden will only open once the last element is pressed (this element will probably have >> only pointing down in the middle). That element will disappear once opened. There will be no animations when reveiling the hidden ones (like there is in Office).
More on this when I actually start working on this class.

'''Color Picker'''
Needs more specifications.

'''Wiki (not the established name)'''
Customized text box with links and such. Needs more specifications.


I'm not looking for heaps of comments (although they are welcomed), I was just thinking a reference page like this should be established, so that all you GUI designers know what controls you can work with. If you want more, suggest them here.

'''[size=7]GUI XML Crookedness'''![/size]

(Posted by Gustav, 14th October 2004)

Alright, having reviewed some of the XML code, I've decided I need a thread where I can point out things that's done crooked, or possibly if there are easier ways of doing things. Yeah, that's basically it.

This thread is all about learning how the GUI works, and how to use it correctly. I'm sorry if I will come off stern, but I'll just go ahead and tell you guys everything that I feel is out there, and don't feel bad, you're not even forced to agree with me, this is just my pointers.

'''Sizing'''
`<object type="text" ... size="100%-376 4 20 20" z="100" ...></object>`
The sizing is defined as following: "'''left top right bottom'''" and not "left top width height". This is very important, because what that object creates, is a rectangle that will capture the event of the mouse (or maybe not, I'm not sure). In either case, it's not good.
The sprite in this one is added without percentage modifiers, so it still turns out okay. Although using these conventions will result eventually in major crookedness, because when drawing a sprite, we want the mouse to know when it's hovering the sprite, and that is done with the texture being stretched and the size being the size of the sprite. '''I recommend specifying textures as "0 0 100% 100%" and letting the size of the object define the resulting sprite size''' when applicable.
Also, those objects, is it meant for the user to be able to click them and still interact with the game? Or should they block that?
If they shouldn't interfere, they should be set as "ghost", and if they should, they need correct sizing.

I just committed an update that makes the GUI blocks signals to the game, so that if you select the GUI menu now, an object won't be selected in the background. Although, this has revealed that at some places the GUI blocks empty space, like the bottom menu, it blocks everything from the horisontal line from the top of the minimap and below:
`<object type="text" name="session_panel_minimap_bg" sprite="session_panel_minimap_bg" size="0 100%-179 100% 100%" z="60" hidden="false" />`
I took a quick look, and found that one, it is set to 100% in x2, which blocks a lot of unwanted things. Again, I suggest (not forcing though :P) using texture coordinates "0 0 100% 100%" and specifying the correct size. Also, this object should be 'image' now that I've added a controls for the purpose.

A good to know is that I've made the control 'empty' completely hollow, it cannot be hovered, so it can't block the mouse's focus. This is because if you need a hollow blocker, it's more intuitive to use an 'image' without a sprite, and primarly because all those '<object type="empty" size="0 0 100% 100%">' were blocking the mouse for the world interaction.

'''Text => Images'''
I mentioned it, but I thought I'd make a clearer reminder that all 'text' objects used only for sprites, can be changed to 'image' objects now.

'''Default values'''
Some things are default, and need not to be specified every time, it is of course completely optional, but at some parts I saw a tremendous amount of 'hidden="false"' which is default, and can be omitted.

'''Z value'''
Z value is automatically set to the 10 more than its parent, so not specifying any z values at all, should still keep a logical order of things, it's only when we need to correct certain things, or when we need to make extra space, or when we need to sort order between overlapping siblings we need to specify the Z value automatically. Something to think about. In the long run, I think it will result in cleaner code if we try omitting as much unnecessary as possible. Although maybe you feel more comfortable setting z manually at all time, and that's purely a preference choice, and I won't dictate any convention (at least not with that :P).

Alright that's the first batch, I'll update this thread every time I spot some crookedness.

== '''Text Renderer''' ==

(posted by Gustav, 31st August 2004)

I'm making great headway on the GUI and trying out and implementing things I designed well over a year ago (!). Anyway I thought I would dedicate a thread for GUI Engine progress, because when I add features, I know you want to be able to play around with them, and use them to enhance the GUI to resemble your vision ever more accurately. So every time I make progress that enables the user to do more, I'll report it here and let you know how to play around with it. OK. Questions are also appropriate in this thread.


How would such a thread be without something to start off with?

I've been working the last week on bug-fixing, and adding features to the GUI Generic Text Renderer (aka text processing thingamajigger with word-wrapping and lots of nice stuff for the whole family)

Alright, check this image out:
[[Image([[Image(http://gee.pyro.nu/screen.gif)]]!)]]

'''Color and font tags'''
First of all, you can switch color and font at anytime like this:

`Hello [font="verdana16"]there [color="255 0 0"]I'm![/color]![/font] here.`

You can't enter `[color=blue]` yet. Although I'm thinking of making it possible to great customized colors in a setup file. I can imagine we'll have a lot of specific colors, and I would suffer seeing them typed out each time :P

'''Icons'''
Moving on we've got the icons, they are handled just like text, so if you bundle them up with text they will word-wrap together with it, making it perfectly possible to substitute letters with icons. As you can see in the image's icon part, icons are placed on the same line the text is drawn on. But you can always adjust the image when creating sprites to get pixel-exactness! I'm very fastidious about such things, and if I see things aligned one pixel off, I'm displeased. For instance, the upper part of the icon will be aligned with the bottom line of the previous row's text, which means characters dropping below that line (like gpqyj) might be obstructed. This can be solved by making the icon larger than the sprite, and then create an image which is placed on the bottom part of the sprite leaving empty space on top. Follow me? No worries just play around with it and if you can't achieve wanted result, ask me about it.

It may seem tedious, but it was a scenario unlikely to happen because I'm guessing there won't be a whole lot of smileys in the game (I'm just saying the sprite-tool makes it possible). Which leads me to another point, which is the name 'icon' that shouldn't give associations that it can only be used on small 16x16 images. If you want a large image between two paragraphs (maybe even a horizontal bar, play with it), the [icon]-tag can be used for that too.

Icons are declared in a setup file (a file with root element <setup>) as following:

`<icon name="smiley" sprite="smiley-texture" size="20 20" />`

Notice '''sprite''' is not texture, no filename references here. Only sprite names which have been declared (or will be declared) in a sprite file. To use the icon:

`This is within GUI text [icon="smiley"]`
or
`This is within GUI text [icon=smiley]`
latter example ONLY if reference name doesn't contain whitespace. If unsure what is safe, go with quotation marks.

'''Floating images'''
''Floating images'' are images (or actually icons) placed to the right or left with text drawn on the side of it (as shown in the image). They use the icons, so there's not that much more to it:
`Here's some[imgleft="ragnarok"] text that will be [imgright="smiley"]surrounded by images`
Notice that the tag can go anywhere, it will be top-aligned with the text nearby the tag (if the placement is displeasing, just try moving the tag around some).

'''Scroll Bar'''
Sure this and 90% of all above has been available for like 4 months, but I'm not sure if you've got to taste it completely. Play around with the scrollbars, notice the graphics won't be clipped, so you'll still see what is beeing scrolled away. Scrollbar-styles are declared in a setup file (again, with <setup> root), check out setup.xml to see an example. It's basically just the width and all sprites. Horizontal scroll-bar are not available yet, they will never be available for the text box, so you'll just have to wait for later controls.

'''Styles'''
This is a real oldie, I just haven't seen it being used even once, so I wanted to make sure you guys were aware of it. You create styles in a file with root element <styles> (like styles.xml), and basically what you're doing is creating a list of setting and default values. Any object can take the setting '''style''' and you set it to whatever you gave the style for name. That object will then use the style for all values that aren't manually set. It doesn't matter if the style contains more settings than the object you  use it on have, it will just ignore unsuccessful sets (this means styles are not bound by object type and are completely generic).

When to use styles? Well in the final game I imagine a look n' feel that is quite unified, a lot of the buttons will look the same, a lot of the text boxes etc. Create styles and you can easily create a multitude of similar-looking objects. Enjoy.

Also the styles with the name "default" is very special, because its values are the very default values of *every* object, regarding if another style is used, or if no style at all is used! So they are pretty much a more easier managed way than defaulting each values hardcoded.

'''Text'''
Also note that I changed the text rendering test from a button-object to a text-object (which is more logical). Also I've added the setting "buffer-zone" to that type, that tells how much space there will be between the edge and text, also between floating images and text. buffer-zone is now set in styles.xml but can be overridden or changed of course. Soon you will be able to center text in both text and buttons too.

''[color=purple]The GUI is being constantly upgraded and there's a lot of features that still needs heavy testing, don't be alarmed if you come across something irregular or erroneous, just report back to me whenever that happens.![/color]''

'''[size=7]Image Placement'''![/size]

(posted by Gustav, 1st September 2004)

Thanks all! and yeah Jason my thorough design has sure paid off a lot =) I love it.

[quote]What are the next feature you want to implement ? Should I probably write down my list of most needed things for the next PASAP versions ?![/quote]
Right now I'm working on what comes up and I feel is urgent that I tackle, although the time will come when it isn't obvious what's next, I'd love it if you had such list ready for me until then.


Alright, second round :)

'''New control: image'''
Nothing to celebrate, I just decided to make a control dedicated for just sprite-drawing. It's called "image" and takes the base settings plus "sprite" of course. In the TDD it was originally planned that a "text" control without text would fill this need, put apparently this is not obvious for the user and a button without functionality may just as equally satisfy. But because the button control does a lot more processing, I thought this is just unnecessary overhead. Also, when scanning through a file it's not easy to orient when sprites are called 'text' or 'button'. More intuitive, faster, there's not much more to it.

'''Precision! '''
Now here's one I had a fun 10 hours struggle with, yey :)
I had noticed that in the new intro-menu, the sprite for hovering was waaay off in 1280x1024. When I examined the file I discovered it was placed for all resolutions, but the sprite wasn't. The sprite was in pixel size like this:
`<image texture="ui_pregame_mainmenu_spbt_over.png" texture-size="0 0 256 256" size="0 0 152 143" />`
So okay, since the size should be adjusted to resolution too, it should be "0 0 100% 100%", OK? Yey, it's got the right size, but wait, "0 0 256 256" just doesn't work for this (well okay in 1024x768 still), it needs to be percent sized too. Wow, that would be a pain in the behind wouldn't it, and I - a servant of kings (looking up to the sky) - would not let my sirs have this pain in the behind!

So I added a little feature I think you'll enjoy quite a bit ;) I added a setting to <image> that enables you to tell the size of the *real* texture, not the texture file. This value is just "x1 y1 x2 y2", and of course no percent value because it's plain and simple the position and size in the file. This way you could actually store several texture within one file and just point out the area for each image (you could before too, but not at all as easily).

''Notice that it just processes the texture coordinates, it doesn't cut out the texture, so you can't tile a cut out texture, because the rest of that image will be shown too... understood? OK! :)''

The fun thing is I always write these kinds of posts after a 12 hour session of coding, so excuse my inability to explain things. Just to make sure we're on the same page on this subject, an example:

`<image texture="ui_pregame_mainmenu_background.png" texture-size="0 0 100% 133.333333333%" size="0 0 100% 100%" />`
changed to:
`<image texture="ui_pregame_mainmenu_background.png" real-texture-placement="0 0 1024 768" size="0 0 100% 100%" />`

Now isn't that neater? ;) Also notice texture-size="0 0 100% 100%" is omitted because it's default. (The name 'real-texture-placement' might be lame, give me a suggestion and I'll change it).

Moving on to some other side of the precision problem, I've changed *all* sizes and positions in the GUI from being stored as integers to floats. 
''No nooooo!! why crazy swede would you do this!!'' Relax! ;) You can still input them as integers, as a matter of fact, you will never notice the difference, except a much more precise and accurate result. Why? Well I don't want to get too technical, but let's say it's because of truncation and OpenGL blending. 

Notice also that you can specify placement of a fitted object with decimals: "5.23% 23.23% 94.34% 100%". This is very important for the pregame menu if it should work on ALL resolutions. Just take a look in hello.xml and you'll see the precision I use. Sure, it looks bloated, but fortunately this kind of placement will be rare in the game.

Moving on again (oh we're still on precision), so I finally got the image to be placed on the right spot on all resolutions, but there was this white edge around it! This is the edge of the texture wrapping around, maybe it'll go away using a more primitive filter, but that's for the graphics guys to experiment with. I, however, have come up with a solution (I'm not saying it's the best one, I'm saying it's *a* solution). The solution is making the texture 1 pixel larger than planned on all sides, and cut it out with my new cut-out feature, that way OpenGL won't nibble on any white area, but on texture that will blend excellently with the background. This works on all resolution, check sprite1.xml, or why not try running on different resolutions.

 * PUH* Sorry guys, I'm not sure that I could've minimized this post even if I tried to..............:indifferent:............. oh sure I could, but a man's gotta sleep sometime! *chuckle*  :banana: 

[size=1]Will be committed as soon as CVS is online again![/size]

== '''Er, Miscellaneous''' ==

(posted by Gustav, 14th October 2004)

Changes:

'''New icon option'''
Icons can now optionally specify a "displace" when using the [icon] tag. It doesn't change the technical position, but it changes the cosmetic position. A way of changing the technical size is on the TODO list.

Ex.
[icon="smiley" displace="-4 0"]

The 'displace' option is optional and can be omitted.


'''GUI Blocking world interactions'''
The GUI is no blocking real world interaction, which you can check out. You can no longer press trees and units when hovering GUI objects (that acknowledges mouse hovering). Henceforth, you all GUI guys need to be aware of the right things blocking. Right now empty space is blocking, and in the sibling thread I've pointed out why. So be aware, and play around with it.
I just remembered I've only blocked when pressing (and releasing), you will still be able to hover world objects, but I'll update that soon enough.

'''Empty object is now hollow'''
The 'empty' object does in no circumstances acknowledge mouse hovering. This is because the "0 0 100% 100%" empties were blocking the world interaction... Also there's no use for an 'empty' retrieve mouse hovering. If you need a hollow blocker, just use an 'image' object without a texture.

'''Progress bar'''
Basic progress bar is added. It is according to GUI TDD, although setting names have been renamed to 'sprite-background' and 'sprite-bar'.
A more advanced and versatile progress bar is being considered.


Also note that the input box is added, although don't use it, it's in the middle of development, and there's no need to settle in just yet.

== '''The issueCommmand Method''' ==

(posted by Simon, 25th April 2005)

It is now possible for JS to give network synchronized orders to entities by using the issueCommand method like this:
CODE
selection[0].issueCommand(NMT_Goto, X, Y);

or
CODE
selection[0].issueCommand(NMT_Gather, targetResourceEntity);


Sending to multiple entities is not yet possible, and I haven't even started on converting the input code to send JS events etc. I need to make some specs on what JS should be able to do and how it should do it - if nothing else to get a clear view of the new stuff. Well... tomorrow's problems -> tomorrow ;-)


== '''List and Dropdown Controls''' ==

(posted by Gustav, 25th April 2005)

I thought I'd just introduce some of the new settings for the '''list''' and the '''dropdown''' control.

In windows, the size of a dropdown is specified as the perimeter of the whole control when opened. And then the height when closed is set to one row. I want you to be able to specify that on your own, so the size of the dropdown is the size when closed. You then specify the length (correction: maximum length) of the drop-down part with '''dropdown_size'''. Now, to make it look good, you will probably need sprites that are a bit larger than it should be, just like for text-controls. This will force the dropdown part to be placed with a little buffer below the the main part. This is specified with '''dropdown_buffer'''. You might find it annoying that the program doesn't automatically decide these things, but since the question is what is aesthetically pleasing, the GUI cannot make that choice. Also, just put this value in the style and you will never have to specify this value manually. Another one is '''button_width''', specifies the width of the button next to the text in the control. Again, this could be set to be a square all the time, but that's not that flexible, for instance if you want a large dropdown with large texture images, then you probably want a slender button instead of a square that would double the control's size. Notice that even with the button, you can still press the whole control to open it.

Now, these things apply to both controls:
Which element is selected is easily retrieved and changed because it is a setting called '''selected'''. '''buffer_zone''' should be familiar by now, it is the distance between the text's bounding box and the edge of the control. Also applies to between elements.

Also, this is what I wrote in my task update:
[code]var list = obj.list;
list.push("New Element");
obj.list = list;![/code]
Do not simply put:
`obj.list.push("New Element");`
It does not work, but you scripters are probably well aware of that situation.


Again, these are BETA, changing color of text might not work, so don't be alarmed when such things happen.