$Id: hooks.txt 4547 2023-05-26 01:44:21Z dsb $

Inventory Sort Order Hooks
==========================
If your addon creates new object types that you'd like to have sorted in a
particular order by Inventory Sort Order, well, first off, thanks for
helping to make this addon more useful. ;)  The addon provides two hooks
that your addon can use to advise the addon's sort-order method:

InvOrder:sortWithinType
-----------------------
  Invoked by Actor:sortInven() after objects have been sorted by type.  At
  the time of the call, both objects to be sorted will have the same type
  (or nil type, which your hook should check for if necessary), and both
  will have a non-nil subtype, which may or may not be equal.
  self is:	The Actor whose inventory is being sorted.
  data{} fields:
    o1, o2:	The two objects being compared.
    compare:	A utility function used internally by Actor:sortInven(), 
		described below.
    before:	If your hook can determine how the two provided objects
		should be sorted, it should set this field to true if
		o1 should be sorted before o2 or false if o2 should be
		sorted before o1.  If your hook cannot determine the
		correct sort order for these objects, it should leave this
		field unchanged.  [If some other hook has already set this
		field, you may leave it or override it, as you choose.]

InvOrder:sortWithinSubtype
--------------------------
  Invoked by Actor:sortInven() after objects have been sorted by subtype.
  At the time of the call, both objects to be sorted will have the same
  type (or nil type, which your hook should check for if necessary) and the
  same subtype (or nil subtype).
  self is:	The Actor whose inventory is being sorted.
  data{} fields:
    Same as for the InvOrder:sortWithinType method.

data.compare(o1, o2, field)
---------------------------
The InvOrder:sortWithinType and InvOrder:sortWithinSubtype hooks provide
a convenience function data.compare() for comparing two values.  If the
'field' argument is passed, the method compares o1[field] and o2[field];
otherwise it compares o1 and o2.  The two values are compared with their
default comparator, and if they are not equal, or if one of them is nil,
data.compare() returns true and the value that should go in data.before.
If the values are equal (or both nil), data.compare() returns false.  For
instance, to sort the provided values by silliness, your hook could use
code like:

  local ok, order = data.compare(data.o1, data.o2, 'silliness')
  if ok then
    data.before = order
    return
  end
