Template:Op presentations

Presentations
Presentations are a complex subject, because of their flexibility. Each presentation is nothing more but a number of screen control elements, called overlays. There are many types of overlays, each coming with it's own behavior and looks. For as long as the presentation is running, you can monitor the status of those overlays and change their looks, contents and position on the screen.

Presentation is nothing but a set of triggers. There are only five triggers that the presentation can have, but skillful control of them allows you to do nearly everything you can think of.

ti_on_presentation_load fires only once when the presentation is started. his is the place where you will usually create all overlays that your resentation needs, initialize their looks and contents and put them to heir positions on the screen.

ti_on_presentation_event_state_change is probably the most important and easy one. It fires every time some overlay in your presentation changes state. For each type of overlay this means something. For a button overlay, this means that the user has clicked the button. In this case, you will want to run the code responsible for that button effects. So you can put a "Win" button on your presentation, and when it's clicked, you can run the code which will give all castles and towns in the game to you.:-)

ti_on_presentation_mouse_press trigger fires every time user clicks a mouse button on one of presentation overlays, even if the overlay did not change it's state as the result.

ti_on_presentation_mouse_enter_leave trigger fires when the mouse pointer moves over one of presentation's overlays, or moves out of it. This might be useful if you want your presentation to react to user's mouse movements, not only clicks.

ti_on_presentation_run trigger will fire every frame (in other words, with the frequency of your game FPS). You can put some code in this trigger if you want your presentation to constantly do something even if the user is passive.

Note that while a running presentation will usually pause your game until you stop it, it is also possible to write presentations which will not stop the game, but will run as the time goes. To see an example, go into any battle in Warband and press Backspace. You will see the interface which displays the mini-map of the battle, positions of all troops, and elements that you can use to issue orders to your companions (if you have any). All this is a presentation as well, called "prsnt_battle". And if you have played multiplayer, then you might be interested to know that all menus, including equipment selection for your character, are presentations as well.

Conditional operations
is_presentation_active = 903
 * (is_presentation_active, ),
 * Starts the specified presentation.

start_background_presentation = 901
 * (start_background_presentation, ),
 * Apparently allows you to start a presentation in background but stay in the menu. 4research.
 * Official: can only be used in game menus

presentation_set_duration = 902
 * (presentation_set_duration, ),
 * Sets presentation duration time, in 1/100th of second. Must be called when a presentation is active. If several presentations are active, duration will be set for all of them.

Creating overlays
create_text_overlay = 910
 * (create_text_overlay,, , [style_flags]),
 * Creates a text label overlay and returns it's overlay_id.

create_mesh_overlay = 911
 * (create_mesh_overlay,, ),
 * Creates a mesh overlay and returns it's overlay_id.

create_mesh_overlay_with_item_id = 944
 * (create_mesh_overlay_with_item_id,, ),
 * Creates a mesh overlay, using the specified item mesh. Returns overlay_id.

create_mesh_overlay_with_tableau_material = 939
 * (create_mesh_overlay_with_tableau_material,, , , ),
 * Creates a mesh overlay, using the specified tableau_material. When mesh_id = -1, it is generated automatically. Value is passed as the parameter for tableau_material script. Returns overlay_id.

create_button_overlay = 912
 * (create_button_overlay,, ),
 * Creates a generic button overlay and returns it's overlay_id. The only difference between this and subsequent two operations is that they use different button meshes.

create_game_button_overlay = 940
 * (create_game_button_overlay,, ),
 * Creates a game button overlay and returns it's overlay_id.

create_in_game_button_overlay = 941
 * (create_in_game_button_overlay,, ),
 * Creates an in-game button overlay and returns it's overlay_id.

create_image_button_overlay = 913
 * (create_image_button_overlay,, , ),
 * Creates an image button, using two meshes for normal (1st mesh) and pressed (2nd mesh) status. Button does not have a textual label. Returns button overlay_id.

create_image_button_overlay_with_tableau_material = 938
 * (create_image_button_overlay_with_tableau_material,, , , ),
 * Creates an image button from the specified mesh, using tableau_material as the image. When mesh = -1, it is generated automatically. Value is passed as the parameter to the tableau_material script. Returns overlay_id.

create_slider_overlay = 914
 * (create_slider_overlay,, , <max_value>),
 * Creates horizontal slider overlay, with positions of the slider varying between min and max values. Current value of the slider can be changed with (overlay_set_val). Returns slider's overlay_id.

create_progress_overlay = 915
 * (create_progress_overlay,, <min_value>, <max_value>),
 * Creates progress bar overlay, with positions of the bar varying between min and max values. Current value of the progress bar can be changed with (overlay_set_val). Returns bar's overlay_id.

create_number_box_overlay = 942
 * (create_number_box_overlay,, <min_value>, <max_value>),
 * Creates a number box overlay (a small field for numeric value and small increase/decrease buttons to the right) with specified min and max values. Returns number box overlay_id.

create_text_box_overlay = 917
 * (create_text_box_overlay, ),
 * Apparently deprecated. No longer used in Native.

create_simple_text_box_overlay = 919
 * (create_simple_text_box_overlay, ),
 * Creates a text field overlay, where user can enter any text. Returns text field's overlay_id. Text contents of the field can be retrieved from s0 trigger in ti_on_presentation_event_state_change event for the text field.

create_check_box_overlay = 918
 * (create_check_box_overlay,, <checkbox_off_mesh>, <checkbox_on_mesh>),
 * Creates a checkbox overlay. Returns checkbox overlay_id.

create_listbox_overlay = 943
 * (create_list_box_overlay, ),
 * Creates a listbox overlay. Individual items can be added with (overlay_add_item) and index of currently selected item can be set with (overlay_set_val). Returns listbox overlay_id.
 * Old syntax (does it changed?): (create_list_box_overlay,, , ),

create_combo_label_overlay = 948
 * (create_combo_label_overlay, ),
 * Creates a combo label overlay. Looks like plain text label. Individual items can be added with (overlay_add_item) and currently selected item can be set with (overlay_set_val). Returns combo block's overlay_id.

create_combo_button_overlay = 916
 * (create_combo_button_overlay, ),
 * Creates a combo button overlay. For example see "Screen Resolution" dropdown in Settings menu. Individual items can be added with (overlay_add_item) and currently selected item can be set with (overlay_set_val). Returns combo block's overlay_id.

overlay_add_item = 931
 * (overlay_add_item, <overlay_id>, <string_id>),
 * Adds an item to the listbox or combobox. Items are indexed from 0. Note the order in which items appear in the dropdown is reverse to the order in which they're added.

Overlays hierarchy manipulation
set_container_overlay = 945
 * (set_container_overlay, <overlay_id>),
 * Defines the specified overlay as the container. All subsequently created overlays will be placed inside the container, and their coordinates will be based on container's position. All containers with their contents will be displayed *above* any non-container overlays. Use -1 to stop placing overlays to current container and resume normal behavior.

overlay_set_container_overlay = 951
 * (overlay_set_container_overlay, <overlay_id>, <container_overlay_id>),
 * Allows you to put one overlay into a container, or remove it from container (if container_overlay_id = -1) without setting current overlay. May be unreliable.

Overlay manipulation
overlay_get_position = 946
 * (overlay_get_position,, <overlay_id>),
 * Retrieves overlay current position to specified position trigger, using position's X and Y coordinates. Note that the screen size in Warband is (1.00,0.75), further modified by fixed point multiplier.

overlay_set_val = 927
 * (overlay_set_val, <overlay_id>, ),
 * Sets the value of the overlays which have numeric values.
 * Official: can be used for sliders, combo buttons and check boxes

overlay_set_text = 920
 * (overlay_set_text, <overlay_id>, <string_id>),
 * Changes the overlay text (if it has any). Works for labels, text fields, buttons with text labels...

overlay_set_boundaries = 928
 * (overlay_set_boundaries, <overlay_id>, <min_value>, <max_value>),
 * Changes the value boundaries for the overlays that have them.

overlay_set_position = 926
 * (overlay_set_position, <overlay_id>, ),
 * Sets the overlay position on the screen, using position's X and Y coordinates. Note that the screen size in Warband is (1.00,0.75), further modified by fixed point multiplier.

overlay_set_size = 925
 * (overlay_set_size, <overlay_id>, ),
 * Sets the overlay size, using position's X and Y coordinates. Note that the screen size in Warband is (1.00,0.75), further modified by fixed point multiplier. Also see (overlay_set_area_size).

overlay_set_area_size = 929
 * (overlay_set_area_size, <overlay_id>, ),
 * Defines the actual area on the screen used to display the overlay. If it's size is greater than area size, it will create a scrollable area with appropriate scrollbars. Can be used to create scrollable areas for large text, or scrollable containers with many children elements (see Host Game screen for a typical example).

overlay_set_additional_render_height = 952
 * (overlay_set_additional_render_height, <overlay_id>, <height_adder>),
 * Version 1.153+. Effects uncertain. 4research.

overlay_animate_to_position = 937
 * (overlay_animate_to_position, <overlay_id>, <duration-in-1/1000-seconds>, ),
 * Moves overlay to specified position during a specified timeframe, specified in 1/1000th of second.

overlay_animate_to_size = 936
 * (overlay_animate_to_size, <overlay_id>, <duration-in-1/1000-seconds>, ),
 * Changes overlay size to specified value during a specified timeframe, specified in 1/1000th of second.

overlay_set_mesh_rotation = 930
 * (overlay_set_mesh_rotation, <overlay_id>, ),
 * Despite the name, works with any overlay, allowing you to put it on the screen in rotated position. To determine the angles, position's rotation values are used (not coordinates!). Usually you will want to only use rotation around Z axis (which results in clockwise or anti-clockwise rotation as seen by user). Note that rotating overlays which are placed inside a container may cause strange results, so some trial and error will be necessary in such situation.

overlay_set_material = 956
 * (overlay_set_material, <overlay_id>, <string_no>),
 * Version 1.161+. Replaces the material used for rendering specified overlay.

overlay_set_color = 921
 * (overlay_set_color, <overlay_id>, ),
 * Changes the overlay color (hexadecimal value 0xRRGGBB). May not work with some overlay types.

overlay_set_alpha = 922
 * (overlay_set_alpha, <overlay_id>, ),
 * Changes the overlay alpha (hexadecimal value in 0x00..0xFF range). May not work with some overlay types.

overlay_set_hilight_color = 923
 * (overlay_set_hilight_color, <overlay_id>, ),
 * Highlights the overlay with specified color. May not work with some overlay types.

overlay_set_hilight_alpha = 924
 * (overlay_set_hilight_alpha, <overlay_id>, ),
 * Highlights the overlay with specified alpha. May not work with some overlay types.

overlay_animate_to_color = 932
 * (overlay_animate_to_color, <overlay_id>, <duration-in-1/1000-seconds>, ),
 * Changes overlay's color during a specified timeframe, specified in 1/000th of second.

overlay_animate_to_alpha = 933
 * (overlay_animate_to_alpha, <overlay_id>, <duration-in-1/1000-seconds>, ),
 * Changes overlay's alpha during a specified timeframe, specified in 1/000th of second.
 * Doesn't work with text overlays using <tf_with_outline>.
 * overlay_set_alpha doesn't work when animating is processed. Use overlay_animate_to_alpha with 0 msec.

overlay_animate_to_highlight_color = 934
 * (overlay_animate_to_highlight_color, <overlay_id>, <duration-in-1/1000-seconds>, ),
 * Highlights overlay to specified color during a specified timeframe, specified in 1/000th of second.

overlay_animate_to_highlight_alpha = 935
 * (overlay_animate_to_highlight_alpha, <overlay_id>, <duration-in-1/1000-seconds>, ),
 * Highlights overlay to specified alpha during a specified timeframe, specified in 1/000th of second.

overlay_set_display = 947
 * (overlay_set_display, <overlay_id>, ),
 * Shows (value = 1) or hides (value = 0) the specified overlay.

overlay_obtain_focus = 949
 * (overlay_obtain_focus, <overlay_id>),
 * Makes the specified overlay obtain input focus. Only works for textboxes.

overlay_set_tooltip = 950
 * (overlay_set_tooltip, <overlay_id>, <string_id>),
 * Defines a text which will be displayed as a tooltip when mouse pointer will hover over the specified overlay. Unreliable, always test how it works.

Popups and some esoteric stuff
show_item_details = 970
 * (show_item_details, <item_id>,, <price_multiplier_percentile>),
 * Shows a popup box at the specified position, containing standard game information for the specified item. Last parameter determines price percentile multiplier. Multiplier value of 100 will display item standard price, value of 0 will display "Default Item" instead of price (used in multiplayer equipment selection presentation).
 * Official: price_multiplier is percent, usually returned by script_game_get_item_[buy/sell]_price_factor

show_item_details_with_modifier = 972
 * (show_item_details_with_modifier, <item_id>, <item_modifier>,, <price_multiplier_percentile>),
 * Same as above, but displays stats and price information for an item with a modifier.

close_item_details = 971
 * (close_item_details),
 * Closes the item details popup box.

show_troop_details = 2388
 * (show_troop_details, <troop_id>,, <troop_price>),
 * Version 1.153+. Supposedly displays a popup with troop information at specified place. 4research.