===== ScriptedOSD Reference =====

Scripts run on the server can create an OSD layout that is transmitted to then executed by the client. See the [[scripting:scriptedosd|ScriptedOSD Overview]] for a general description of how this system is used.

===== ScriptedOSD Commands =====

==== OSDCreate ====
^ Parameters | ''OSD_TYPE'', ''Name'', ''Title'', ''[Expiry Time]'' | 
^ Example | ''osdcreate(OSDBUILDING,"Main", "" )'' |
^ Description | This function is used to start a new osd block. | 

OSD_TYPE determine the location and appearance of the OSD background (See list below).
The ''Name'' of the OSD is used to identify its components : See [Responding to OSD Button Presses].
''Expiry Time'' is optional - if used, it specifies the number of seconds the OSD will appear for before automatically closing.

OSD_TYPE can be one of :\\
- OSDWINDOW \\
- OSDBUILDING\\
- OSDPOPUP\\
- OSDBLANK \\
- OSDLOWER\\
- OSDTUTORIAL\\
- OSDNOTIFICATION1 .. OSDNOTIFICATION6\\
- OSDSPEC\\
- OSDSPECLOWER \\
- OSDBLANKCENTER \\
- OSDSCRIPTEDBUILDING \\

Each type has a different default setup and use case, e.g. ''OSDWINDOW'' creates a 400x300 background window positioned in the center of the screen. For ''OSDBUILDING'', the OSD is displayed within the region of the building access window. See [OSD Types Reference] for details of each type.

==== OSDText / OSDTextRight / OSDTextCenter ====
^ Parameters | ''[TEXTYPE]'', X, Y, ''Text'' |
^ Example | ''OSDText( SMALL, 100, 100, "Hello World" )'' |
^ Description | Adds text to an OSD at the specified coordinate.  |
Note TEXTTYPE can be ommitted (text defaults to 'NORMAL') so  OSDText( 10, 10, "Hello" ) is valid. 
Full list of supported types below..

==== OSDAdd ====
^ Parameters | ''OSD_ITEMTYPE'', X, Y, W, H, ''Name'', ''Title'' |
^ Example | ''OsdAdd( BUTTON, 100, 100, 200, 20, "Option1", "Press me" )'' |
^ Description | Adds individual elements to an OSD at a specific location.  |

==== OSDAddAuto ====
^ Parameters | ''OSD_ITEMTYPE'', ''Name'', ''Text'' | 
^ Example | ''OsdAddAuto( IMAGE, "", "http://myweb.com/image.jpg" )'' |
^ Description | This is a basic function to add an OSD item to the screen. Each item appears below any previously added items. If you want more control of the layout of your OSD then you would use the OSDAdd command. | 
 
==== OSDSet ====
^ Parameters | ''Flag to set'' | 
^ Example | ''osdset( "BlockEscape" )'' |
^ Description | This function is used to set a specific OSD behaviour flag. | 

Currently, "BlockEscape" is the only valid flag and is used to remove the user control to press escape to close an osd screen.
//Example//
<code>
osdcreate( OSDLOWER, "Help", "Help Guide" )
osdset( "BlockEscape" )
osdadd( TEXT, 100,0, 400, 100, "", "Welcome to my world, press the button to start" )
osdadd( BUTTON, 200, 70, 200, 35, "", "Start Game" )
osdactivate()
</code>

==== OSDActivate ====
Parameters : None
Example : ''OsdActivate()'' \\
Description : Triggers the actual transmission of the OSD layout to the client.

==== sysGetTextEntry====
Parameters : None
Example : ''$text = sysGetTextEntry()'' \\
Description : Related but separate from the OSD functions, this call is used in an OSDSelect event to retrieve the text the user entered in a TEXTENTRY box.\\



===== ScriptedOSD Item Types =====

==== Button Types ====

  * BUTTON
  * EXITBUTTON
  * FADEDBUTTON
  * APPLYBUTTON
  * APPLYEXITBUTTON

==== Image Types ====

  * IMAGE
  * FADEDIMAGE
  * EXITIMAGE

==== Graphic Types ====

  * RECT
  * LINE
  * BOX
  * LAYERRECT
  * COUNTDOWN
==== User Input Types ====

  * TEXTENTRY
  * VALUE
  * CASHVALUE
  * EXITIMAGE
  * SLIDER
  * AMOUNTPRICEVALUECONTROL

==== Display Control Types ====

  * HTTPSET
  * BUTTONMINWIDTH
  * MINHEIGHT

==== Other OSD Types ====

  * LISTBUTTON 
  * DATE

===== ScriptedOSD Text Types =====

Text can be added to your OSD using various text types, that specify the size and colour of the text to be displayed.
If the text type is ommitted, standard text formatting will be used, otherwise valid text types are as follows :\\

  * BIG
  * FADED
  * SMALL
  * BOLD
  * SMALLFADED
  * BIGFADED
  * WARNING
  * BIGWARNING
  * FONT2
  * FADEDFONT2
  * GIANT
  * GIANTFADED
  * BLINKINGWARNING
  * BULLET
  * GOLD
  * SILVER
  * BRONZE
  * BIGGOLD
  * BIGSILVER
  * BIGBRONZE