Revision 2946 (by dsb, 2017-06-22 22:57:54) Oops, got that wrong; the 'name' field can be a function in the talent
callback setup, not in the object callback setup.
$Id: use-item-dialog.txt 2946 2017-06-22 22:57:54Z dsb $

Adding Actions to UseItemDialog
===============================

The T2 module supports several methods for adding choices to the
UseItemDialog for various items:


By Hook
-------
The most general mechanism for influencing UseItemDialog is the T2 module's
"UseItemMenu:generate" hook.  See <http://te4.org/wiki/Hooks> for general
information on the T-Engine's hooks mechanism, and the file 'hooks.txt' in
this directory for the specifics of this hook.  This mechanism is
recommended when you want to add new action choices to existing objects, or
an action that applies to several types of objects.


By Object Callback
------------------
If the UseItemDialog's target object defines a method named
on_use_item_dialog(), it will be invoked to add actions to the dialog list.
The method should be defined as follows:

  on_use_item_dialog(self, actor, inven, item, floor, menu, callbacks)
    self:	The Object for which the dialog is being created.
    actor:	The Actor on whose behalf the dialog is being created.
    inven:	The actor inventory that contains the object, or nil if the
		object is on the floor.
    item:	The index into the inventory (or floor object stack) at
		which the object resides.
    floor:	True if the object is on the floor.
    menu:	The action list being generated (see below).

To add an entry to the dialog, the method should append a table entry to
the menu{} list parameter with the following fields:

  name:		The entry name to show in the dialog list.
  callback:	A callback function implementing this entry's action, as
		described below.

The entry's callback() function will be called with the following
arguments:

  actor:	The Actor that is using the object.
  object:	The Object being used
  inven:	The actor inventory that contains the object, or nil if the
		object is on the floor.
  item:		The index into the inventory (or floor object stack) at
		which the object resides.
  floor:	True if the object is on the floor.
  on_use:	A finishing callback from UseItemDialog.  Your action
		callback should call this function after it is finished,
		with the following parameters:
		  inven:	As passed to your action callback.
		  floor:	As passed to your action callback.
		  item:		As passed to your action callback.
		  object:	As passed to your action callback.
		  stop:		True if the inventory dialog that generated
				this UseItemDialog should be closed by the
				finishing callback.


By Talent Callback
------------------
A talent that selects an object from an inventory dialog and does something
with it can arrange to have an action added to the UseItemDialog that
invokes the talent on the object.  To do so, the talent definition should
include a use_item{} subtable containing the following methods and fields:

  use_item.filter(o)
    Called with the UseItemDialog's target object.  Should return true if
    the talent can be applied to this object.  Often this method will also
    be suitable to be passed as the 'filter' parameter to the inventory
    dialog normally invoked by the talent.

  use_item.action(self, t, o, inven, item, floor)
    Called by the UseItemDialog when the talent's associated action is
    selected.  Should do everything done by the talent's action() method
    after it returns from its inventory dialog; in fact, frequently the
    action() method will be able to simply forward to this method.
    Parameters are:
      self:	The Actor using the talent.
      t:	The talent definition.
      o:	The Object on which the talent is being invoked.
      inven:	The actor inventory that contains the object, or nil if the
		object is on the floor.
      item:	The index into the inventory (or floor object stack) at
		which the object resides.
      floor:	True if the object is on the floor.
    The method should return the same value(s) as the action() method.

  use_item.name
    An optional string field that will be used as the text of the entry
    added to the UseItemDialog.  The field may also be a function taking
    the same parameters as use_item.action() above.  If absent, the
    talent's name will be used.

  use_item.close_before
    If present and true, the associated inventory dialog will be closed
    before use_item.action() is called.  This may be necessary if, for
    instance, use_item.action() uses targeting.

  use_item.close_after
    If present and true, the associated inventory dialog will be closed
    after use_item.action() is called.  Superceded by use_item.close_before
    if present.

  use_item.allow_from
    An optional table specifying where the object may be to use the talent
    on it.  Will be checked for fields 'inven', 'equip' and 'floor', with
    the expected respectives meanings.  If absent, no restriction is placed
    on object location.