UI Overview

[giraffe 803]

UI Menu Overview
 
To start off I'd like to mention programs you would probably find useful.

• Halo Editing Kit (HEK)
• Halo Editing Kit Plus (HEK+)
• Kornman's Guerilla V2 (needed to edit UI widgets)
• Widget Editor V.01 (optional, if you cannot get Kornman to work, but not recommended)
• A unicode strings list tag editor
• An image editor (Photoshop, Gimp, etc) if you plan on creating custom bitmaps

Before I get into anything else, I'd like to mention the main types of widgets:
 
Containers - this is where everything starts off. It usually contains the pause menu background and list widget.
Lists - this is referenced by the container widget.  It usually contains button widgets.
Buttons - this is usually the last thing referenced in a menu.  It can either perform a function, wake a dormant/static void script, or open a new container.  If it opens a new container, this process restarts, until a button either performs a function, or wakes a dormant/static void script.
 
NOTE: It is helpful to be organized by naming your widgets accordingly. Example, if the theme of your menu is extras, then you should name the button "extras_button", the container "extras", and the list "extras_list".
 
 
Details to where in a particular widget you should edit:
 
Containers - Most of the time, all you should have to do is add the pause menu background and list widget, at the bottom of the tag for 'CHILD WIDGETS'.
Lists - Similar to containers, at the bottom of the tag for 'CHILD WIDGETS', you should add references to the buttons you want the list to show.
Buttons - For the most part, you would either have the tag wake a script or perform a function.  Unless, you want this button to open another menu, you would have it reference a container that you want it to open, under event handlers.
 
NOTE: At the top of the a widget tag, is the widget type.  This determines the type of widget it will be. Containers have the container widget type, lists usually have the column list widget type, and buttons have the text box widget type.
 
 
What are bounds and why should I care?
 
Bounds set the scale for a widget. On the values you enter for it, determines the width and height for where the widget will be accessible. It also sets the scale of the background bitmap to fit within the bounds given.  The letters near bounds represent top, left, bottom, and right.  Most of the time you would only enter bounds for bottom (height) and right (width).  The values are most of the time related to the pixels of the background bitmap, unless of course you were scaling it to be larger. On a side note, unrelated to bounds, is the vertical and horizontal offsets which can be set at 'CHILD WIDGETS'.  These set the position of the widget that is referenced.
 
 
Event Handlers
 
Event handlers usually determine if the widget is supposed to do something when it is open.  The majority of container widgets, do not need an event handler because they just open the pause menu background and the list.  Same goes for list widgets; they usually just show button widgets. Event handlers are needed for a button, because it will determine what the button will do.  Whether that is to run a function and close all widgets, to wake a script and close all widgets, or to open another container widget.  There are many other flags for event handlers, but I'm not going over them.  For the most part, you can usually figure things out by looking at stock widgets.
 
 
Adjusting a button's parameters
 
If you have noticed, at the center of a widget is where you can change text box parameters.  This includes the text of the button, the font used for the text, the text color, and the justification of the text.  For the text, you would reference a unicode strings list (you can create/edit one with a strings list editor). Underneath 'more text box parameters', you will see string list index. The value entered correlates to the number that represents your string.  The font for most of the buttons for a multiplayer map is large_ui.  The text color is usually sky blue.  And the justification for the text is usually centered.  There is also extra settings that you can apply, under flags.  Just to make sure you remember, text box parameters are for text box widgets.  Most of the time, text box widgets are for button widgets.  However, sometimes text box widgets are used for headers of a pause menu.  I won't be going into that because I don't have to, and besides it's easy enough to figure out by looking at stock button widgets.
 
 
So how can I start?
 
To start off you can make a button widget, which will be referenced in one of the stock list widgets. If you want to add the button to the main menu of a multiplayer map, you would add it into the 'tags\ui\shell\multiplayer_game\pause_game\mp_pause_list.ui_widget_definition' tag. Notice under 'CHILD WIDGETS' that each button is spaced 35 for the vertical offset.  That is because the bottom bound for those buttons are 27, making each button spaced apart by 8 pixels.  To add a button to the bottom of the list, assuming the bounds of it are the same as the others, you would add 35 to the vertical offset of the last button on the list which is 105.  This would make the vertical offset for your new button 140.  If you noticed, that is also the value of bottom bounds for this tag. So you must increase the bottom bounds by 35 as well because you need to make the the button you added accessible.
 
NOTE: If you want to insert a button above a default button, you would use the vertical offset of the default for the inserted button.  You would then add 35 to the vertical offset of the default buttons, below the button you inserted.
 
That was just to add a button, however, you still might need to adjust the scale of the pause menu background, and placement of the list.  You can edit this from the 'tags\ui\shell\multiplayer_game\pause_game\1p_pause_menu.ui_widget_definition' tag.  Since you've only adjusted the bounds and vertical offsets of the list, you will only need to adjust the vertical offset for the list in the 1p_pause_menu widget.  To get the list centered again, you would divide half of the bounds of the button in the list. So, half of 27 is 13.5, but you can round that to 14 because you should always try to keep offsets even numbers. The vertical offset for the mp_pause_list is originally 192.  To get the new vertical offset you would subtract 14 from 192, giving you 178.  Now, your list should be centered.  As for the pause menu background, for multiplayer maps, it is already at a scale in which you can add an extra button, and not have to change anything.  I'm not going to go into adjusting the scale of the pause menu background because it's easy enough to figure out on your own.  However, I would like to mention that when you are scaling the menu background, you should adjust the bounds of it, unless of course there isn't a background bitmap for it.  In which case you would adjust the bounds of it's child widgets.  Lastly, when adjusting a menu's background, be sure to save it with a different name than the original otherwise it will change any other menu that is using that background.  This includes for saving the child widgets of the menu background as well.  So, be sure to save them with different names, and to reference any widget that has been saved as something else, from the original to the altered one.
 

Creating and compiling bitmaps

This is if you are interested in creating your own bitmaps, rather than using stock ones. I'm assuming that you already know how to create and compile bitmaps. Most UI bitmaps also contain an alpha channel, which are used to set the bitmap's transparency. Alpha channels are grayscale, where brightness makes parts more opaque and darkness makes parts more transparent. You can add an alpha channel to your tif with an image editing program (Photoshop, Gimp, etc). I'm not going to teach you how to make an alpha channel, but basically you want it to overlay with your bitmap properly. After you compile a bitmap (you may get an error), you'll want to open the bitmap's tag in Guerilla/Kornman, then set the bitmap type from 2D texture to interfaced bitmaps and the format to 16-bit or 32-bit color. Then you can close and save the tag, recompile the bitmap through tool and it should be ready for use.

NOTE: Button bitmaps should have 2 bitmaps in one tif. The first bitmap is for when the button is unfocused and the second bitmap is for when the button is focused (when mouse hovers over). You will need to create a completely blue (Red=0,Green=0,Blue=255) border separating the bitmaps. They also need to be side by side, not one above the other.

Here are some example TIF bitmaps that are ready to be compiled:

Example dialog box - Download TIF


Example button - Download TIF



So this is how it ends...
 
Last thing, I'd like to give you a multiplayer button widget.  It is meant to run a dormant or static void script, and mostly everything is set up, except the text box parameters and the script name in the event handler.
https://www.dropbox.com/s/m5moqvifdzop2uj/custom_button.ui_widget_definition?dl=1

If you have any questions or need help, leave a post below.

[NeX 1756]

Nice write-up! 

[TCK 2164]

Late reply but I need to make a correction: a UI button cannot wake a dormant script, they can only run static scripts.

 

This goes for event handlers in general, of course, not just if the widget is a button. If the event handler is given a script, it must be a static script to work.

 

Not sure how I missed this before but good tut.

Edited October 6, 2015 by TCK

[giraffe 803]

Late reply but I need to make a correction: a UI button cannot wake a dormant script, they can only run static scripts.

 

This goes for event handlers in general, of course, not just if the widget is a button. If the event handler is given a script, it must be a static script to work.

I've been waking dormant scripts via widgets since 2009.

Here are some examples of maps that wake dormant scripts through widgets:

http://hce.halomaps.org/index.cfm?fid=4428

http://hce.halomaps.org/index.cfm?fid=4693

http://hce.halomaps.org/index.cfm?fid=4771

If you are having problems waking dormant scripts through widgets then you can see if moving them to their own HSC file helps.

[TCK 2164]

Post an example dormant script from the raw .hsc which you know has been successfully woken by a UI event handler and let me look real quick, if you would. There are a couple things I'm curious about now.

Edited October 6, 2015 by TCK

[giraffe 803]

Post an example dormant script from the raw .hsc which you know has been successfully woken by a UI event handler and let me look real quick, if you would. There are a couple things I'm curious about now.

(script dormant disco
    (fade_in 14.00 200.00 250.00 150)
)

[TCK 2164]

I was hoping yours would have a void return value specified, or some other quirk which would mean that's why it was overlooking mine. Hm.

 

I have no idea then. All I know is back on Modhalo I tried it a dozen different ways with dormant scripts before trying a static, only to have it work instantly and smack myself for it. And then right after, when Deadhamster wrote a tut for it (http://www.modhalo.net/index.php?/topic/29036-linking-scripts-to-ui-buttons/) he and I were talking about it on Xfire as he was writing it. Right before he posts it, he sends me a copy and asks me to proofread it; and I say, "hey this part about dormant scripts is gonna frustrate the shit outta some kids, because it won't work unless it's a static." So he changed it to a static before posting it.

Edited October 6, 2015 by TCK

[NeX 1756]

So he changed it to a static before posting it.

 

Way to go, jackass.

 

Hindering the entirety of UI development for years

[TCK 2164]

Hey.

 

...I STILL can't get the UI to wake dormant scripts.

 

If what he's saying is the cause, that they need their own .hsc, then I suppose that would explain it since I've got a raging habit of making one large .hsc per scenario and just commenting off sections for different purposes. Still, I maintain that a static is 9/10 times the better choice for a button.

Edited October 6, 2015 by TCK

[NeX 1756]

If what he's saying is the cause, that they need their own .hsc, then I suppose that would explain it since I've got a raging habit of making one large .hsc per scenario and just commenting off sections for different purposes.

 

That's a pretty good idea; isn't there a limit to the number of individual .hsc files you can compile in a single scenario?