Echo Hollow

Gender-Bending Interactive Stories! :D

User Tools

Site Tools

Trace:
smutbook:classes:inventory:generalinventory

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
smutbook:classes:inventory:generalinventory [2023/08/08 18:08] – created leesmutbook:classes:inventory:generalinventory [2023/08/08 19:16] (current) – lee
Line 1: Line 1:
 ====== GeneralInventory ====== ====== GeneralInventory ======
  
 +**Extends:** [[smutbook:classes:persistence:persistentobject]]
  
 +GeneralInventory is the base Inventory implementation from which all other Inventory types are derived.  It provides default functionality which can be overridden in derived classes.
  
 +===== Usage Notes =====
  
 +STUFF
  
 +===== Static Properties/Functions =====
  
 +==== .move( item, srcInventory, destInventory, actor ) ====
 +As //actor//, try to move //item// from //srcInventory// to //destInventory//.  This will call .remove() and .add() on the given inventories.  If the move fails for some reason, the source and destination inventories will be left in the state they started in.
  
 +  * **Type:** Function
 +  * **Arguments:** 
 +    * //item//: The PersistentObject (or subclass) to be moved.
 +    * //srcInventory//: The source GeneralInventory (or subclass) from which //item// is moved.  FIXME What if srcInventory is undefined/null?
 +    * //destInventory//: The destination GeneralInventory (or subclass) to which //item// is moved.
 +    * //actor//: The Person doing the moving.  FIXME What is actor is undefined/null?
 +  * **Returns:** true if the move was successful, or false if it was not.
 +  * **Throws:** Nothing
  
  
 +===== Constructor( id ) =====
  
 +//**Do not ever use "new" to instantiate a PersistentObject (or subclass thereof).  Instead, store the result of PersistentObject.define() somewhere and reference it when needed, or fetch the object by its 'id' with PersistentObject.fetch().**//
  
 +===== Properties/Functions =====
  
 +==== .contents ====
 +An array of the id fields of all the things (PersistentObjects and subclasses) contained in this inventory.  Duplicates are not allowed.  Order does not matter.
  
 +  * **Type:** Array of strings, or empty array
  
 +==== .add( item, actor=undefined, force=false ) ====
 +Adds the given item to the inventory.
  
 +It **does not** remove it from any other inventories that might already contain it.  You probably usually want to use InventoryUI or .move() instead.
  
 +Before the item is added to the inventory, preAdd(item,thisInventory,actor) (if such a function exists) is called on the actor, the item, and the inventory, in that order, to ask permission for the item to be added to the inventory.  If any of these return false, the item is not added to the inventory and nothing else is done.
  
 +However, if the item was successfully added to the inventory, postAdd(item,thisInventory,actor) is called on the actor, the item, and the inventory, in that order, to notify everything involved that the item was placed in the inventory so that they can react to it if needed.
  
 +  * **Type:** Function
 +  * **Arguments:** 
 +    * //item//: the thing to be added to the Inventory.
 +    * //actor//: the (optional) Person that is doing the adding.
 +    * //force//: if true, the pre- and post- functions will not be called, and item will be added regardless.
 +  * **Returns:** true if the item was added or was already in the inventory, or false if the item could not be added to the inventory.
 +  * **Throws:** Nothing
  
-  * Inherits from: PersistentObject+==== .remove( item, actor=undefined, force=false ) ==== 
 +Removes the given item from the inventory.
  
-GeneralInventory is the base Inventory implementation from which all other Inventory types are derived.  It provides default functionality which can be overridden in derived classes.+Before the item is removed from the inventory, preRemove(item,thisInventory,actor) (if such a function exists) is called on the actor, the item, and the inventory, in that order, to ask permission for the item to be removed from the inventory.  If any of these return false, the item is not removed from the inventory and nothing else is done.
  
-==== Properties ====+However, if the item was successfully removed from the inventory, postRemove(item,thisInventory,actor) is called on the actor, the item, and the inventory, in that order, to notify everything involved that the item was removed from the inventory so that they can react to it if needed.
  
-=== .contents === +  * **Type:** Function 
-An array of the id fields of all the things (PersistentObjects and subclasses) contained in this inventory.  Duplicates are not allowed.  Order does not matter.+  * **Arguments:**  
 +    * //item//: the thing to be removed from the Inventory. 
 +    * //actor//: the (optional) Person that is doing the removal. 
 +    * //force//: if true, the pre- and post- functions will not be called, and item will be removed regardless. 
 +  * **Returns:** true if the item was removed or was not in the inventory to begin with, or false if the item could not be removed from the inventory. 
 +  * **Throws:** Nothing
  
-  * Type: Array of strings, or empty array +==== .has( item ) ==== 
-  * Required+Checks to see if the inventory contains the given item.
  
-=== .add( item, actor=null, force=false ) === +  * **Type:** Function 
-This method adds the given item to the inventory. It **does not** remove it from any other inventories that might already contain it.  You probably usually want to use InventoryUI or .move() instead.+  * **Arguments:**  
 +    * //item//: the thing to be checked for in the Inventory. 
 +  * **Returns:** true if the inventory contains the specified item, or false if it does not. 
 +  * **Throws:** Nothing
  
-  * item: the thing to be added to the Inventory. +==== .isEmpty() ====
-  * actor: the (optional, can be null) Person that is doing the adding. +
-  * force: if true, the pre- and post- functions will not be called, and item will be added regardless. +
- +
-  * Returns: true if the item was added or was already in the inventory, or false if the item could not be added to the inventory. +
-  * Throws: nothing. +
- +
-=== .remove( item, actor=null, force=false ) === +
-This method removes the given item from the inventory. +
- +
-  * item: the thing to be removed from the Inventory. +
-  * actor: the (optional, can be null) Person that is doing the removal. +
-  * force: if true, the pre- and post- functions will not be called, and item will be removed regardless. +
- +
-  * Returns: true if the item was removed or was not in the inventory to begin with, or false if the item could not be removed from the inventory. +
-  * Throws: nothing. +
- +
-=== .has( item ) === +
-This method checks to see if the inventory contains the given item. +
- +
-  * item: the thing to be checked for in the Inventory. +
- +
-  * Returns: true if the inventory contains the specified item, or false if it does not. +
-  * Throws: nothing. +
- +
-=== .isEmpty() ===+
 Check if the inventory is empty. Check if the inventory is empty.
  
-  * Returns: true if the inventory contains no items. +  * **Type:** Function 
-  * Throws: nothing.+  * **Arguments:** None 
 +  * **Returns:** true if the inventory contains no items, false otherwise. 
 +  * **Throws:** Nothing
  
-=== .get( filterClass=undefined, filterFunction=undefined ) ===+==== .get( filterClass=undefined, filterFunction=undefined ) ====
 Returns the fully-instantiated contents of the Inventory. Returns the fully-instantiated contents of the Inventory.
  
 If a class is passed to filterClass, only items that are of that class (or a subclass thereof) will be included in the returned array. If a class is passed to filterClass, only items that are of that class (or a subclass thereof) will be included in the returned array.
  
-If a function is passed to filterFunction, that function will be called once for every item in the inventory.  If this function returns true, the item will be included in the returned array.  If the function returns false, the item will not be included.+If a function is passed to filterFunction, that function will be called once on every item in the inventory.  If this function returns true, the item will be included in the returned array.  If the function returns false, the item will not be included.
  
-  * filterClass: an optional filter class. +  * **Type:** Function 
-  * filterFunction: an optional filter function.+  * **Arguments:**  
 +    * //filterClass//: an optional filter class. 
 +    * //filterFunction(item)//: an optional filter function. 
 +  * **Returns:** an array containing the fully instantiated contents of the inventory, less those filtered out.  This array will be sorted alphabetically by item.name, and further sorted by any .sort() function defined on the inventory (see below). 
 +  * **Throws:** Nothing
  
-  * Returns: an array containing the fully instantiated contents of the inventory, less those filtered out. +==== .sort( a, b ) ==== 
-  * Throws: nothing.+An optional function used by .get() to sort the inventory contents. It follows the rules of Javascript's (Array).sort().  This function is not defined on GeneralInventory, but can be defined by subclasses to alter the inventory sort order.
  
-=== .override === +//This function is generally only used by derived classes that need to sort differently. Unless you are extending the library, you'll probably never need to define or call it.//
-When not undefined, the override value sets the value that .toString() returns, ignoring the actual contents (if any) of the inventory.+
  
-This is useful for minor characters and objects who do not actually need a fully-featured inventory, as it avoids all the hassle of defining flavor objects to populate the inventory with, that the protagonist will otherwise never be able to interact with.  See the [[Tutorial]] for details.+  * **Type:** Function 
 +  * **Arguments:**  
 +    * //a//: a thing in the inventory. 
 +    * //b//: another thing in the inventory. 
 +  * **Returns:** <0 if a<b, >0 if a>b, or 0 if a==b. 
 +  * **Throws:** Nothing
  
-  * Type: String +==== .override ==== 
-  * Optional+When defined, the override value sets the value that .toString() returns, ignoring the actual contents (if any) of the inventory.  When set to undefined, toString() returns the actual inventory contents as normal.
  
-=== .toString() === +This is useful for minor characters and objects who do not actually need a fully-featured inventory, as it avoids all the hassle of defining flavor objects to populate the inventory with, that the protagonist will otherwise never be able to interact with.  See the [[Tutorial]] for details.
-Overridden +
- +
-  * Returns: a serial-comma-separated-list of the inventory's contents' .aName fields. +
- +
-=== .theString() === +
-  * Returns: a serial-comma-separated-list of the inventory's contents' .theName fields. +
- +
-=== .sort( a, b ) === +
- +
-This is the function used by .get() to sort the inventory contents. It follows the rules of Javascript's (Array).sort(). The default implementation sorts alphabetically, ignoring case. +
- +
-//This function is generally only used by derived classes that need to sort the {@link LibEcho.Inventory|Inventory} differently. Unless you are extending the library, you'll probably never need to use it.// +
- +
-  * a: a thing in the inventory. +
-  * b: another thing in the inventory. +
- +
-  * Returns: <0 if a<b, >0 if a>b, or 0 if a==b. +
- +
-===== LibEcho.Inventory.InventoryUI ===== +
- +
-InventoryUI is a static container holding functions to render the inventory UI, as well as the object details UI (FIXME). +
- +
-==== InventoryUI.render( config ) ==== +
- +
-Given a configuration object, this function renders the inventory UI into a DOM container (which is passed as part of the config object). +
- +
-This function is called by the InventoryUI macro (see the [[Macro]] documentation for more details).  You probably don't want to use this function directly unless you are extending LibEcho itself. +
- +
-==== The Configuration Object ==== +
- +
-The configuration object can contain a number of fields.  The values of some of these fields can be a literal or a function.  In the case of a function it is called with the listed arguments and the return value is used as the configuration value. +
- +
-For more information, see the InventoryUI Macro source code. +
- +
-=== parentElement === +
-The parent element to render the UI into. +
-  * Type: jQuery DOM Element +
-  * Default: DEFAULT +
-  * Optional +
- +
-=== leftInventory === +
-The GeneralInventory (or subclass) or Person that appears on the left side of the inventory UI.  This is conventionally the inventory of the person who is picking things up, or the inventory that things are being picked up and put into, but it can actually be any inventory or person. +
-  * Type: GeneralInventory or Person +
-  * Default: None +
-  * Required +
- +
-=== rightInventory === +
-The GeneralInventory (or subclass) or Person that appears on the right side of the inventory UI.  This is conventionally the inventory from which things are being taken, but it can actually be any inventory or person. +
-  * Type: GeneralInventory or Person +
-  * Default: None +
-  * Required +
- +
-=== onClose( config ) === +
-Function to be called when inventory UI is closed.  The InventoryUI macro uses this to evaluate the tweecode in the contents of the macro body when the InventoryUI dialog is closed. +
-  * Type: Function +
-  * Returns: Void +
-  * //config//: The config object that was passed to InventoryIU.render(). +
-  * Default: undefined +
-  * Optional +
- +
-=== allowClose( config ) === +
-If this function returns a String, that value will be printed in place of the "Done" link at the bottom of the inventory modal (preventing the modal from being closed).  This can be used to prevent the inventory from being able to be closed until certain items have been taken or dropped, for example.  If the return value is a falsy value, the regular "Done" link will be displayed, allowing the modal to be closed. +
-  * Type: Function +
-  * Returns: String +
-  * Default: undefined +
-  * Optional +
- +
-=== actor === +
-The Person interacting with the inventory. +
-  * Type: Person | or Function(config) returning Person +
-  * Default: undefined +
-  * Optional +
- +
-=== leftAction === +
-The action label for moving item from left inventory. +
-  * Type: String | Function(config) returning String +
-  * Default: "Drop" +
-  * Optional +
- +
-=== leftActioned === +
-The left action success word.  "ObjectName: dropped." +
-  * Type: String | Function(config) returning String +
-  * Default: "dropped" +
-  * Optional +
- +
-=== rightAction === +
-The action label for moving item from right inventory. +
-  * Type: String | Function(config) returning String +
-  * Default: "Take" +
-  * Optional +
- +
-=== rightActioned === +
-The left action success word.  "ObjectName: taken." +
-  * Type: String | Function(config) returning String +
-  * Default: "taken" +
-  * Optional +
- +
-=== canShowOnLeft( item, config ) === +
-Called to check if the object will be displayed in left inventory at all. +
-  * Type: Function +
-  * Returns: Boolean +
-  * //item//: The item which we are checking whether or not we should show. +
-  * //config//: The config object that was passed to InventoryIU.render(). +
-  * Default: true +
-  * Optional +
- +
-=== canShowOnRight( item, config ) === +
-Called to check if the object will be displayed in right inventory at all. +
-  * Type: Function +
-  * Returns: Boolean +
-  * //item//: The item which we are checking whether or not we should show. +
-  * //config//: The config object that was passed to InventoryIU.render(). +
-  * Default: true +
-  * Optional +
- +
-=== canMoveFromLeft( item, config ) === +
-The item will be shown in the left inventory, but will we show the control to move it to the right inventory? +
-  * Type: Function +
-  * Returns: Boolean +
-  * //item//: The item which we are checking whether or not we should show. +
-  * //config//: The config object that was passed to InventoryIU.render(). +
-  * Default: true +
-  * Optional +
- +
-=== canMoveFromRight( item, config ) === +
-The item will be shown in the right inventory, but will we show the control to move it to the right inventory? +
-  * Type: Function +
-  * Returns: Boolean +
-  * //item//: The item which we are checking whether or not we should show. +
-  * //config//: The config object that was passed to InventoryIU.render(). +
-  * Default: true +
-  * Optional +
- +
-=== getSortCategory( item, inventory, config ) === +
-Return object category for the sort selector. +
-  * Type: Function +
-  * Returns: String +
-  * //item//: The item which we are checking whether or not we should show. +
-  * //inventory//: The item which we are checking whether or not we should show. +
-  * //config//: The config object that was passed to InventoryIU.render(). +
-  * Default: item.inventoryCategory | "Other" +
-  * Optional +
- +
-=== canShowLeftSelector === +
-Will the left selector be shown? +
-  * Type: Boolean | or Function(config) returning Boolean +
-  * Default: true +
-  * Optional +
- +
-=== canShowRightSelector === +
-Will the right selector be shown? +
-  * Type: Boolean | or Function(config) returning Boolean +
-  * Default: true +
-  * Optional +
- +
-=== moveFromLeft( item, config ) === +
-Function to call to move item from left to right inventory. If undefined, the built-in implementation will be used. +
-  * Type: Function +
-  * Returns: Void +
-  * //item//: The item which we are checking whether or not we should show. +
-  * //config//: The config object that was passed to InventoryIU.render(). +
-  * Default: the builtin implementation is used if none is defined in the config object +
-  * Optional +
- +
-=== moveFromRight( item, config ) === +
-Function to call to move item from right to left inventory. If undefined, the built-in implementation will be used. +
-  * Type: Function +
-  * Returns: Void +
-  * //item//: The item which we are checking whether or not we should show. +
-  * //config//: The config object that was passed to InventoryIU.render(). +
-  * Default: the builtin implementation is used if none is defined in the config object +
-  * Optional +
- +
-=== leftTitle === +
-Override the left title. +
-  * Type: String | Function(config) returning String +
-  * Default: if the left inventory is a Person then "Soandso (Inventory)", otherwise leftInventory.AName. +
-  * Optional +
- +
-=== rightTitle === +
-Override the right title. +
-  * Type: String | Function(config) returning String +
-  * Default: if the right inventory is a Person then "Soandso (Inventory)", otherwise rightInventory.AName. +
-  * Optional +
- +
-=== leftName( item, config ) === +
-Override the left label for item. +
-  * Type: Function +
-  * Returns: String +
-  * //item//: The item which we are checking whether or not we should show. +
-  * //config//: The config object that was passed to InventoryIU.render(). +
-  * Default: the item's AName +
-  * Optional+
  
-=== rightName( item, config ) === +  * **Type:** string (or undefined)
-Override the right label for item. +
-  * Type: Function +
-  * Returns: String +
-  * //item//: The item which we are checking whether or not we should show. +
-  * //config//: The config object that was passed to InventoryIU.render(). +
-  * Default: the item's AName +
-  * Optional+
  
-=== outerTpl === +==== .toString() ==== 
-Override the builtin outer HTML template. +Overridden.
-  * Type: String | Function(config) returning String +
-  * Default: undefined +
-  * Optional+
  
-=== listitemTplLeft === +  * **Type:** Function 
-Override the builtin left list item HTML template. +  * **Arguments:** None 
-  * Type: String | Function(config) returning String +  * **Returns:** a serial-comma-separated-list of the inventory's contents' .aName fields. 
-  * Default: undefined +  * **Throws:** Nothing
-  * Optional+
  
-=== listitemTplRight === +==== .theString() ==== 
-Override the builtin right list item HTML template. +Description.
-  * Type: String | Function(config) returning String +
-  * Default: undefined +
-  * Optional+
  
-=== detailsTpl === +  * **Type:** Function 
-Override the builtin item details HTML template. +  * **Arguments:** None 
-  * Type: String | Function(config) returning String +  * **Returns:** a serial-comma-separated-list of the inventory's contents' .theName fields. 
-  * Default: undefined +  * **Throws:** Nothing
-  * Optional+
  
smutbook/classes/inventory/generalinventory.1691543285.txt.gz · Last modified: 2023/08/08 18:08 by lee

Page Tools

© 2024 Echo Hollow