6C - Custom Menus

There is a number of improvements to the custom menus allowing you to add a lot more into them, making them look closer to vanilla style menus.

• • • Column System
    • Custom Menu Items
    • Custom Menu Strings
    • Custom Menu Options
    • 
      Custom Menu Line Options
    • Notes
    • Tradebar
    • Custom Tradebar Texts

Column System

There is a new way to create columns, using the command:

The text can be a normal string, any object type, or a string array like the various drawing routines (see below).
The old column method, the menu would automatically setup the column sizes by ordering each column entry by their start position. This can cause issues when mixing left and right aligned columns that can overlap.
The new method doesn't attempt to do anything automatically, instead you explicitly state the positions and sizes. This also means columns can end up overlapping with each other (this can be useful when drawing rectangles and other things that might overlap, like a trade bar with the values drawn on top).

The text will be capped at the column length (adding the ... if its too long). The length can be 0 which will set it to the size of the text. The position can be negative to set it from the right side of the menu. The right align option is a boolean that will draw the text from the right edge of the column (position + length - actual text length). The colour value is one of the menu colour constants that allows you set a different colour for each column (see colouring below).

Custom Menu Items

Tabs: You can now add tabs to a custom menu using

The text is the title in the tab. When adding tabs, the position they are added in the menu array matters, everything added after the tab will be added into that tab. So when setting up multiple tabs, you add the tab first, then everything that will appear in that tab after. The first tab is the exception, as everything that's added before any tab will be added to in the first tab. So the first tab will contain everything before and after the first tab entry, but before the second tab entry.

If you prefer, you can also just add the data only for the current tab, this is useful if you have large or very complex menus, to reduce the amount of data in your menu arrays. Using the callback option, [i]Callback.TabChanged[/i], and adjusting the menu array for the current tab each time the you receive "tabchanged" event. You will still need to add all the tabs in the correct order so they are displayed on the tab bar though

NOTE: when adding a tab bar you need to be careful about how you use value selections. The value selection command now includes an "allowtabs" argument. When set to TRUE, it means when you press left or right while in this value selection, it switches the tabs, instead of the value (you have to use enter to cycle between them). Otherwise left/right will change the value rather than change the tab

Multi Line Selections: You can now create multi line selections by using the command:

This must be added directly under the select line to increase the size of the select line. The text value can also be setup into columns. The more extra lines you add, the bigger the selection bar will be.

Custom Menu Strings

There are a number of new string types for custom menus, these create a string array that can draw various items and can be used anywhere you will use normal text. You can set the x position within the line via the columns system.

Progress Bar:

This displays a progress/ware bar in the menu. The width is the full width of the bar and the progress is how full the bar should be, 0-100%.

Shield/Hull Bars:

This adds a shield and hull bar to the menu (blue bar on top for shield, green bar underneath for hull).

Similar to the other shield/hull command, but sets the shield and hull values directly from the object (this is also dynamically updated).

Rectangle:

This draws a coloured rectangle. The y value is the offset within its current line.
The menu colour is one of the menu colour constants and the raw colour is an RGB integer value you can create use the colour commands.

Icons:

This draws an icon for the ship or station type (ie the icon that is displays in Property Owned menu).

Similar to the type icon, but takes the type from the object, this will also colour the icon based on owner, i.e. green for player ships/stations.

This draws an icon, similar to the previous type and object, but you can specify the exact icon you want to use, as well as control the size of it. The type is what set of icons the id matches too, there are constant for these, but include GUI, Weapons and HUD.

This is the same as the above command when using the GUI constant.

Weapons Mask:

This draws the compatibility weapons bar, with the different colours for each weapon, as seen in the ships info menu. The weapons argument is an array that contains all the laser types you want it to highlight. You could also draw this manually by drawing each individual rectangle.

Marine Stars:

This will display the marine stars based on the skill level. The skill level is between 0 and 100. The partial flag allows the drawing of partial stars, i.e. 4 1/2 stars instead of just whole stars. The spacer is the gap between the stars, using 0 will set it to the default value. You can also draw the stars manually using the draw icon commands.

Notoriety Bar:

This will display the notoriety bar (similar to that in the player status menu). The level is between -5 and 10, show empty will display all the empty blocks as well.

Custom Menu Options

There are a number of options you can set in custom menu to control how things work. These can be added anywhere in the menu array, there are a few that existed in Albion Prelude, many more have been added.

This sets the main icon for the menu (displayed in the top left corner).

This changes the description text in the menu, this is the text that is at the top above the first heading (right aligned)

This changes the main title text (could also effect the first heading if one hasn't been added).

This set the width of the menu. The widths are available in the constant, and there are 3. Normal, Big and Huge. Normal is the one that standard custom menus use and huge is the one that custom info menus use by default.

This sets if you want to use the new search bar, that many menus use. When enabled, you can use the normal search hotkey to open the search. The event script will receive the "search" event with the current search value, allowing you to filter your list. Return the new filtered menu array to adjust the display.

This allows you to set the voice to be said when the menu is open, i.e. like how the ship info and encyclopaedia pages work.

This sets which value selection is the default. The string is the id of the value selection. This means when ever you use left or right it will change the default value even if its not the selected line (doesn't work if you have tabs as well).

This displays a portraint window to the left showing a certain face id. The mood value is set via constants. The name is what is displays in the window title.

This simply removes any select line, turning the menu into a pure info display menu. Any select lines you have added to the menu array will be ignored.

This allows you to register a hotkey that can be used in the menu. The hotkey can be the character you wise to use, or the id of the hotkey type. When pressed, the event script will receive "hotkey" with the id as its value.

Custom Menu Line Options

As well as the menu options, there are now line options. These options are defined for each individual selection lines and can control the menu based on the current selection. Allows you to make some changes without needing to use the "selection" event and rebuilding the menu array every time.

These options must be added before the selection line you want to use them for.

This changes the selection colour. This is the colour of the selection bar when highlighting the option. IE you can display a green bar when selecting player items, like in the properties menu, or red bars like in the trade menu.

This sets the text colour of the whole line (will be overridden by the colour text colour if set). See Note below.

This sets the hotkey that can be used for this item (hotkeys can be a character or hotkey id). When setting jumpto, then pressing the hotkey simply highlights this line, if FALSE, then it selects it as if you pressed enter on it.

This sets the voices description of each line, when you highlight the line, the voice will be started after a small delay. This works similar to the trade menu when highlighting different wares.

This displays the ware video to the right comms window (similar to trade menu). The ware can be weapons, ships or other wares. When ships, the ship stats will be displayed instead.

This displays the video to the right comms window based on object, can be used on marines to display the marine stats.

This displays a comm window to the right with a race portrait.

This changes the description text when highlighted. Selection lines that dont have this set will just display the global description.

Notes

When using text colours, it will be better to use the line options for text and selection colour rather than using the colour codes in the text themselves. The reason for this is that when setting the line options, the select colour will be automatically inverted making it clear. IE, if you use the red code in the string to have red text, then have a red selection colour. When the item is selected, it'll appear as red on red. When using the line option instead, and setting both selection and text to red, then the text will be red normally, but when highlighted, the highlight will be red, but the text will be inverted to normal.

The hotkey ids are the number code of the registered hotkeys. There are a few available constants for some of the build in hotkeys, you can also use the id codes from custom hotkeys.  For custom hotkeys, you need to register them as menu hotkeys, so they work when the menus are open

Tradebar

There are new commands for different types of trade bars depending on what function you require

Similar to the original command, but allows you to set the volume and used amounts for the trade bar. The used amount is the red part that appears at the beginning.

This adds a trade bar for changing prices. This works similar to when you adjust prices in your stations for wares.

These make a trade bar for transferring ware amounts between ship/station, similar to your HQ/Dock menu when moving goods between the station and docked ship.
You can either use the objects themselves, where the values will be pulled from them directly, or pass the data on manually.

This trade bar works backwards for selling, ie starts full, and left will increase the value while emptying the bar.

IF none of the other trade bar commands suit your needs, then you can use the custom trade bar instead. Unlike the others, it has no minimum/maximum values. So you have to control how far you want it to move yourself.
Using the "tradebar_changed" event you can check if the current value is correct. If its not, you can built a new menu setting the tradebar value to your minimum or maximum value.
You will also receive 2 additional events, "tradebar_full" and "tradebar_empty". This are when home or end keys are pressed to fill or empty the trade bar (setting it to minimum or maximum value). You simply need to return the value you want it set to. The custom tradebar will also not displaying anything other than the tradebar itself, unlike the others. You will need to manually add texts for these.

Custom Tradebar Texts

You can control the texts that are displayed along with the tradebar. The default texts depend on the type of tradebar item you are using.
But there are 8 sets of texts you can define. There are commands available to add these texts onto the end of a tradebar array. This can be used in the "tradebar" to update dynamic texts, or added when you created the menu.

if you added the tradebar to a menu array, then you will need to get that entry first, rather than adding to the menu array itself

then use the command

You can call this command to add each entry you want to override.
The <array> is the tradebar array (Not the Menu Array).

The id is one of the 8 types, these are available in the constants.

The Left/Right entries are the left and right of the tradebar itself, 1 is the top entry, 2 is the bottom entry.
Info is underneath the tradebar at the end of the menu on the left or right (this is the text you can set the in left and right arguments of the various tradebar commands)
The Noto text is the notoriety text that appears directly below the Info Text

You can also use some variables within these texts that can be dynamically changed without needing to create a dynamic tradebar itself.
NOTE: some of these wont be able in all trade bar types

%CURRENT% - The current value
%CURRENTVOL% - The current volume (current value * ware volume)
%ORIGINAL% - The original value, this is the current value you set initially
%MIN% - The minimum value
%MAX% - The maximum value
%PRICE% - The current price value (for price tradebars)
%FREIGHT% - The current ship frieght value (only in move tradebars)