OBJECT
	/obj/book


SYNOPSIS
	#include <properties.h>
	inherit "/obj/book";

	  OR

	clone_object ("/obj/book");

LAST UPDATE
	Magictcs, 26-Mar-98 20:20 MET


DESCRIPTION
	The /obj/book is a simple generic book. It can be opened,
	closed, and even configured to be lockable using the standard
	lock. The lock is here the combination of 'true' lock and the
	book's lid.
        It is not possible to drop any items into the book. To enable
        this (to drop a feather into it...) you have to overload
        allow-enter() - see man moving.

	If /obj/book is just cloned, it's preconfigured to be a
	'book' of 200 coins worth, 1 kg weight. You cannot see the content
        of the book (remember it inherits a container object).
        Transparency of the book is equal to zero!
        (But it is possible to allow entering of items by overloading
        allow_enter() and setting SetTransparency() - but it is not
        recommended!)

	The book may be opened and closed:

	  open book
	  close book
          turn to next page in book
          turn to first page in book
          turn to last page in book
          turn to page <number> in book

        The turn command is available for books with more than one page
        and only if the book is opened! The command 'turn' is available as
        short command if there is the first book in your inventory the one
        that should be turned:
          turn to next page
          turn to first page
          turn to last page
          turn to page <number>

        Opening of the book will set the actual page to 1 to start reading
        at page 1.

        The book has an 'auto turn page' feature. Each read will turn to
        the next page (except the first after 'open' or the first read
        after turning to a special page). So you can continually read
        the book just by simple "do 10#read book" (for example).


	If it is lockable, it may also be locked and unlocked:

	  lock book with <key>
	  unlock book with <key>

	If an open book is locked, it is closed first.
	The commands

	  open book with <key>
	  close book with <key>

	would unlock&open, or close&lock the book.

	In all cases, the book must be visible to the player (visible
	in its environment, or carried in its inventory). The key is
	searched in the inventory only.

	The book utilizes just the functions from /std/lock for the
	commands.

	The book is a upright descendant of /obj/chest.


        The page handling is done by the following functions:

        int QueryPage()
          The number of the page to read is returned.
          The value should be greater than or equal than 1 and less than
          QueryMaxPage()  (see below)

        int SetPage(int page)
          Set the actual shown page to the new value.
          Default value is 1.

        int QueryMaxPage()
          It return the number of pages the book contains.

        int SetMaxPage(int maxpage)
          Set the maximum of available pages the book contains.
          Default value is 1.


        Two different ways for the contents of the book are available.
        The content of pages is handled by the following functions:

        mixed SetPageContent (string|closure content)
          Set the content of a book directly to string or set it as a closure
          to evaluate 'content' every time the book is read (it must be opened
          before).
          Other values than closure or string are discarded!

        string QueryPageContent ()
          Return the string given by SetContent() or evaluate the closure
          given by SetContent() and return their return-value or find the
          actual page and check the book-file given by SetBookFile()
          (see below).

        string QueryBookFile()
          return the file name of the book-file (if given)
          default is an empty string.

        string SetBookFile(string bookfile)
          Set the book file to the given value. This implifies that the book
          has more than one pages. The book is able to handle more than one
          page inside the book. Each page inside the book fiel starts with
          a page counter like the following:

          #<any spaces><number>      or
          #<any spaces>page<any spaces>number

          example:
          #1
          #         23
          #    page             45
          and so on

          After that page haeder the content of the page will follow as
          normal ASCII text. The page number is only used to check if that
          page is existing or not. See example files to understnad the book
          file.

        Either SetBookFile() or SetPageContent() has to be set to enable
        reading of the book (or use overloading of QueryPageContent()).
        If none is set, the reading of the book will fail with an error
        message!

	The following functions of /std/chest are overloaded:

	int allow_enter (int method, mixed extra)
          No item is able to enter the book even if it is opened or closed!

        int fopen (string str,int where)
          If the book is opened, the page counter is set back to 1 to start
          reading on page 1.

        string QueryIntShort
          Our object is a simple container, but it has no internal
          descriptions at all, because no object is allowed to enter it!
          The internal short desacription is set to the external short
          description (to Short() ).

        string SetHelpMsg()
          The help msg varies, if the QueryMaxPage is greater than 1 or not.
          For books (max-page>1) the 'turn page' command is added.
          For scrolls (max-page==1) 'turn page' command is supressed.
          Normally you haven't to overload the standard help message.

        SetReadMsg()
          It is not possible (!) to set the read message of the book using:
          SetReadMsg(string str). A call to this function will raise an
          compile error.

        QueryReadMsg()
          It is not possible to overload QueryReadMsg(). This function is
          set to nomask to prevent overloading. The function handles the
          open/close of the book.

        Use the functions SetPageContent(), QueryPageContent(),
          SetBookFile(), QueryBookFile() instead of SetReadMsg(),
          QueryReadMsg() !


INHERITANCE TREE
	book
          `-obj/chest
      	      |-std/room/items
	      |-std/lock
	      `-std/container
	          |-std/container
		      |-std/base
		      |-std/thing/properties
		      |-std/room/description
		      |-std/thing/description
		      |-std/thing/moving
		      `-std/container/restrictions
		          |-std/thing/restrictions
		          `-std/room/restrictions


EXAMPLES
        /d/sykorath/example/tome    - a book with 4 pages (1,2,3,10)
                                      some pages are missing
        /d/sykorath/example/scroll1 - a simple scroll with only one page
                                      and without 'turn page' command
        /d/sykorath/example/scroll2 - demonstrate overloading of
                                      QueryPageContent()

SEE ALSO
	chest(O), locks(C), container(S), lock(S), room(S), thing(S), door(O)
