This directory contains all the objects needed for the Online Creation
System.  This provides a GUI menu for builders/admins to create and
edit different game objects instead of using the shorthand @edit and @set
methods.

The Olc Class is the base class.  It uses several menu classes such as
OlcMenu and OlcMenuOption.  90% of the time you simply want to inherit
the Oedit object and build from there.  Oedit has everything you need to
edit a GameObject class and odds are your new object is based off of this
class.  There are many examples to base off of but here is a rundown of
some common functionality and how it works.

o - Starting out building an object editor

You probably want to start by copying an initialize and is_valid?
function from an existing simple editor (Such as foodedit.rb)

This basically just sets up some default Class values such as the objects
name, the owner etc.  The base OLC class takes care of checking permissions
and some other things for you, you just want to override is_valid? to
check for your specific object type.

* NOTE: You will also want to change the case statment in cmd_oedit.rb to
match your new object class as well.

o - Adding default attributes and attribute values

To add default attributes to your new object class use:

self.default_attr.concat(["new_option1","new_option2","etc.."])

To add attribute values to the menu system use a similar method but
specify the attribute value key as well as an array of default values.

self.default_hash.merge!({ "valkey" => [ "value1", "value2", "etc..." ] })

The menu system will then append these options to the Oedit Menu system.

o - Modifying the main menu system

The main menu method is called setup_main(m=nil)  You can simply add
menu options to the main system by calling super then your additional menu
choices.  Example

def setup_main(m=nil)
   super(m)
   menu.add_text_option(nil,"My new Option", self, :my_opt_menu, obj.newopts)
end

The m argument is passed by the menu engine.  This is either input from the
user or the keyword "reset".  You will not have to worry about the "reset"
keyword because that is handled by the core Olc engine but you should know
it exists.  add_text_option(...) is a OlcMenuOption and those are discussed
later.

menu is the core menu object.

o - Overriding the main meny system

If you want to override the core GameObjects menu system (Oedit) then
don't call super when overriding setup_main().  You can however copy
the lines you want to use from Oedit's setup_main() and not the functions
because those will be called from the inherited Oedit.  See Redit for
examples of doing this.

o - Submenu system

The Olc System can take an infinite number of submenus.  These work as a
stack.  They require two calls

*  olc_basemenu()
*  submenu()

olc_basemenu() is a core Olc menu method call.  It just sets up a base Menu
object and the title information.  It also returns a working Menu object and
adds a 'Q' - Quit option for you.  The call looks like this:

def setup_mymenu(m=nil)
  smenu = olc_basemenu("My Menu", self, :setup_mymenu, m)
  ...

The first argument is the title of the Menu.  2nd is the calling object.
3rd is the name of the method (In this case setup_mymemnu()).  You pass
m to the olc_basemenu call because the Olc core class will check that
for the "reset" keyword to see if the menu system should be flushed and
reloaded using self.setup_mymenu()

submenu() takes two arguments, the Menu class you created and 'm'.

submenu(smenu,m)

this pushes your new menu you created onto the menu stack as well as
any special menu calls.

o - OlcMenuOptions

Now that you understand the existance of the menu class the next big thing
is to understand how to add your own options to it.  If you just want
to add attribute/attribute values to the core GameObject class you don't need
to this this part (see above).  But if you have a special thing you
are trying to accomplish then you will want to make your own menus (Like
for an Exit editor...)

Before we get started on each option a common first argument is a
'pick' option.  If you want a certain letter to be used (or number) as
the pick option for this choice specify it here.  If you leave this as
a nil one will automatically be assigned.  This 'pick' option can be more
than one character/number.  If you specify a '#' symbol it will be ignored
when matching but will show up in the menu.  Using D# to delete a number
is a common menu option.

* add_std_option

  add_std_option(pick,"StringOpt", obj.value, self, :callback)

  This is a simple callback option.  This will show "StringOpt: obj.value.inspect" in the menu.  When you choose this option it will prompt the user
  
  "Enter new StringOpt:"

   Once the user has entered something then self.callback(m) is called.
   :callback MUST be a symbol of the function name.  m = the users input.

* add_text_option

  add_text_option(pick,"StringOpt",self,:callback,<obj.values>)

  This is just a standard text based menu option.  This typically just
  calls the callback function to setup another submenu.  <obj.values> is
  an optional value to display.  If not passed or left nil then it will
  only display text.

* add_editor_option

  add_editor_option(pick,"StringOpt",obj.text,self,:callback)

  This allows for the fullblown text editor with word wrapping to be
  used on obj.text.  When editing is completed the new text is passed
  to self.callback(m).  Where m = the new text.

* add_numbered_option

  add_numberd_option(Array,<self>,<:callback>)

  Creates a numbered list from an Array.  <self> and <:callback> are
  optional.  If not specified the list is just there for viewing purposes
  but if they ARE specified then a user may choose an option from the list
  and self.callback(m) will be displayed and m=the index+1 of the array index.

* add_named_numbered_option

This is identical to add_numbered_option above but the array is expected to 
be Oids and the menu will also show the shortname next to the Oid.  Eg.

  1) 155  (a battery pack)
  2) 269  (a bloody axe)

* add_toggled_numbered_options

  add_toggled_numbered_options(self, :callback)

  This method uses two additional menu methods and they MUST be set before
  displaying this menu.  You need to set an array of Default values as well
  as an Array of what is currently set by the object you are editing.

  * To add to the default array there are two methods:

   1) menu.add_default_item("string")
   2) menu.default_array = ["string1", "string2", "etc"]

  * You should also set the objects currently set options

   1) menu.set_array = obj.array_values

  When this option is displayed it will show a numbered list but for each
  entry where the object already has this array option an '*' will appear
  before the String to denote that it is already selected.  When a user
  selects this option it calls self.callback(m) with the index+1 of the
  array option to toggle.

* add_hash_numbered_options

  add_hash_numbered_options(obj.hash, self, :callback)

  This is similar to the toggled_numbered_options but you will only have
  to set a default hash method, like so:

  menu.add_default_hash(default_hash)

  This simply merges the existing hash items for this object with
  the default for this object class and presents them as a numbered list
  of keys.

  You will have to make self.callback(m) figure out what number was selected
  and present another menu for a list of default values.

o - Making your own callback functions

The most basic of call backs simply sets a value, redisplays the menu and
returns the modified entry.  Example:

def set_name(m)
  obj.name = m if m.size > 0
  show_menu
  obj.name
end

This function will set the objects name to whatever the user typed in if
the size is > 0 (not just hitting Enter).  If they just hit Enter then
this operation is effectively canceled.  The menu is redisplayed and
the new value is returned to the Menu class for further updating.

show_menu is a builtin Olc method.

You can do more complex checks and what not.  See other editors for
examples.