/vg/UI public API draft.

vgui_server_draft.dm

///// /datum LEVEL.
// PUBLIC API.

/*
This is the proc used to open a UI on a datum. No exceptions.
Arguments:
	- user:         Mob to open the UI for.
	- force_reopen: Whether to forcefully reopen the UI instead of updating it if it is already open.
	- exargs:       Extra arguments to pass to ui_config(). See below.
Returns:
	Nothing.
*/
/datum/proc/ui_interact(var/mob/user, var/bool/force_reopen = FALSE, var/list/exargs)


/*
Causes an interface with the provided key to update.
Arguments:
	- user: The player for which the interface should update. If left out will result in every player receiving an update.
	- key:  The UI key of the interface to update. If left out will result in every UI being updated.
Returns:
	Nothing.
*/
/datum/proc/ui_update(var/mob/user, var/string/key)


/*
Returns the internal UI object for a specific user and UI key.
If you are actually using this then you should probably just be making a better datum-level proc dear god.
Arguments:
	- user: The player for which to get the internal UI object.
	- key:  The UI key of the interface to get.
Returns:
	The UI object for the player and key. Returns null if the UI is not open.
*/
/datum/proc/ui_get(var/mob/user, var/string/key)


/*
Sends a message to the client side window of an interface.
This message can be accessed by global events in the Javascript code.
Arguments:
	- user: The player to send a message to.
	- key:  The UI key of the interface to send the message to.
	- id:   A string identifying the purpose of the message.
	- message: The actual message to send.
Returns:
	Nothing.
*/
/datum/proc/ui_message(var/mob/user, var/string/key, var/string/id, var/message)


/*
Directly calls a Javascript function on an interface with supplied arguments.
Strings and numbers work natively as arguments. Lists are sent as JSON. Other data types / structures will require added serialization on your part.
Arguments:
	- user:      The player to send a message to.
	- key:       The UI key of the interface to send the message to.
	- name:      The name of the Javascript function on the client. This must be accessible in the global scope.
	- arguments: A list of of arguments to send to pass to the Javascript function.
	- status:    The minimum UI status needed for the Javascript call to go through.
*/
/datum/proc/ui_javascript(var/mob/user, var/string/key, var/string/name, var/list/arguments, var/status = VGUI_STAT_INTERACTIVE)

// PUBLIC VIRTUAL - CAN be overriden and may also be called directly.

/*
Gets the status of an interface. This is either VGUI_STAT_INTERACTIVE, VGUI_STAT_UPDATE, VGUI_STAT_DISABLED or VGUI_STAT_CLOSE.
If VGUI_STAT_CLOSE is returned, this means that the interface is not actually open.
Arguments:
	- user: The player which the UI belongs to.
	- key:  The UI key of the relevant UI.
Should return:
	- One of the following:
		- VGUI_STAT_INTERACTIVE
		- VGUI_STAT_UPDATE
		- VGUI_STAT_DISABLED
		- VGUI_STAT_CLOSE	
*/
/datum/proc/ui_status(var/mob/user, var/string/key)



// PROTECTED VIRTUAL API - should be overriden by types but not directly called.

/*
This proc gets called by the /vg/UI system to get the configuration of an interface for this object.
This includes stuff like which UI accessibility state to use, which ID to use for the window, etc...
Left out configuration values will default to default values.
UI configuration options:
	- VGUI_CFG_KEY:          Used to separate interfaces, giving a different key based on arguments (see exargs) will result in a secondary, potentially completely different, interface being opened.
	- VGUI_CFG_STATE:        UI state used to determine accessibility of this UI to a certain player. See UI states for more info. This must be a type.
	- VGUI_CFG_TITLE:        Title used at the top of the interface (or the window name).
	- VGUI_CFG_MODULES:      List of additional UI modules to load. By default no extra modules are loaded.
	- VGUI_CFG_SCRIPTS:      A list of additional Javascript script files to load. Script files are automatically sent from the asset cache.
	- VGUI_CFG_EXTRA_STYLES: A list of extra CSS files to load. The files are automatically sent from the asset cache.
	- VGUI_CFG_STYLESHEET:   /vg/UI stylesheet datum to use for this interface. Must be subtype of /datum/vgui_style
	- VGUI_CFG_AUTOUPDATE:   Whether the interface should automatically update.
	- VGUI_CFG_X:            Horizontal size of the interface.
	- VGUI_CFG_Y:            Vertical size of the interface.
Arguments:
	- user: Mob to open the UI for.
	- exargs: Extra arguments passed down from ui_interact(). This could potentially be null if none were passed.
Should return:
	An associative list of the keys above with the wanted configuration values.
*/
/datum/proc/ui_config(var/mob/user, var/list/exargs)


/*
Gets the data for the specific interface object.
Arguments:
	- user:      The player for which updated UI data should be sent.
	- interface: The interface object that should be updated. This allows access to all relevant date.
Should return:
	- A list of data to send to the client side template.
*/
/datum/proc/ui_data(var/mob/user, var/datum/vgui/interface)


/*
Called when a href action is executed on the client. For the most part this is basically buttons getting pushed.
This is only called if the state confirms that the user is still able to interact with the src.
This is essentially the /vg/UI equivalent of Topic().
Arguments:
	- user:      The player for which updated UI data should be sent.
	- href_list: An associative list expanded from the href action. This is the same as in BYOND's native Topic() system.
	- href:      The raw href string used. This is the same as in BYOND's native Topic() system.
	- interface: The interface object that should be updated. This allows access to all relevant date.
Should return:
	- A combination of the following bitflags to control the UI directly:
		- VGUI_ACT_UPDATE:     Update the UI for all viewing players.
		- TODO: More bitflags?
*/
/datum/proc/ui_act(var/mob/user, var/string/action, var/list/href_list, var/string/key, var/datum/vgui/interface)


/*
Gets the "Host" of the specific interface. This is the object that a state validates for.
This can be useful for objects embedded into other objects, like a traitor uplink in a PDA.
Arguments:
	- user: The player for which to get the host.
	- key:  The UI key of the relevant interface.
Should return:
	- An object which can be used by the assigned UI state to determine whether the UI is accessible to the player.
*/
/datum/proc/ui_host(var/mob/user, var/string/key)


/*
An object-specific check for UI state. For example: machines without power cannot be used.
Arguments:
	- user: The player for which to get the UI state.
	- key:  The UI key of the relevant interface.
Should return:
	- One of the following:
		- VGUI_STAT_INTERACTIVE
		- VGUI_STAT_UPDATE
		- VGUI_STAT_DISABLED
		- VGUI_STAT_CLOSE
*/
/datum/proc/ui_available(var/mob/user, var/string/key)

///// /datum/vgui LEVEL.
/*
The /datum/vgui object is an object to track the individual instances of interfaces per client.
All variables and data can be unique per UI object. This is to allow complete modularity on a per-player basis. Example: If airlocks had some interface for humans, the AI's interface could be drastically different enough that it might not even use the templating module, and a different state.
These are intended to be pooled and such.
*/

// PUBLIC API.

// ALL PUBLIC /datum level API (except interact) is available in /datum/vgui, without the "ui_" prefix on the procs. All player & key arguments on these are removed, as they are not necessary.

/*
The owner datum of this UI object.
*/
/datum/vgui/var/datum/owner


/*
The UI key for this UI object.
UI keys are used to distinguish between multiple UIs originating from the same object for a single player.
This is equal to the value of VGUI_CFG_KEY as returned by ui_config() on UI creation.
*/
/datum/vgui/var/datum/key


/*
The UI state. UI states are objects that define rules for whether a UI is accessible to a player or not. For example: a certain UI needs to be only accessible to people who are adjacent to the host object.
Note that this variable references global objects. These are not unique.
*/
/datum/vgui/var/datum/vgui_state/state


/*
Horizontal size of the interface window in pixels.
This is equal to the value of VGUI_CFG_X as returned by ui_config().
*/
/datum/vgui/var/int/x


/*
Vertical size of the interface window in pixels.
This is equal to the value of VGUI_CFG_Y as returned by ui_config().
*/
/datum/vgui/var/int/y


/*
Title of the interface window.
This is equal to the value of VGUI_CFG_TITLE as returned by ui_config().
*/
/datum/vgui/var/string/title


/*
List of additional modules that have been loaded.
Modules do stuff like provide DoT templating like NanoUI.
This is equal to the value of VGUI_CFG_MODULES as returned by ui_config().
*/
/datum/vgui/var/list/datum/vgui_module/modules


/*
List of additional Javascript files that should be loaded into the interface after modules have finished loading.
Scripts must be available in the asset cache. If this is not the case an exception will be thrown due to incorrect configuration in ui_config().
This is equal to the value of VGUI_CFG_SCRIPTS as returned by ui_config().
*/
/datum/vgui/var/list/string/scripts


/*
List of additional CSS files that should be loaded into the interface. The CSS files are loaded after the main stylesheet's CSS files.
CSS files must be available in the asset cache. If this is not the case an exception will be thrown due to incorrect configuration in ui_config().
This is equal to the value of VGUI_CFG_EXTRA_STYLES as returned by ui_config().
*/
/datum/vgui/var/list/string/extra_styles


/*
The stylesheet type to use for this interface.
Stylesheet objects control the look & feel of the interface.
This is equal to the value of VGUI_CFG_STYLESHEET as returned by ui_config().
Just like states, these are not unique.
*/
/datum/vgui/var/datum/vgui_style/stylesheet


/*
Whether this interface automatically updates every process tick.
This is equal to the value of VGUI_CFG_AUTOUPDATE as returned by ui_config().
*/
/datum/vgui/var/bool/autoupdate


/*
The exargs passed down from ui_intact().
*/
/datum/vgui/var/list/exargs



///// /datum/vgui_style LEVEL

/*
Style objects are used to change the styling of an interface.
For example: syndicate style for the uplink vs regular NT styling for most things.
*/



///// /datum/vgui_state LEVEL

/*
States control whether a UI is interactable by a player.
On top of states, objects can also add another layer via ui_status().
States work in a hierachial system. For example: 
	- There is a basic state to check whether the user is conscious. Higher level states check this lower level one, alongside other things like adjacency, etc...
*/