View source for Verbcoin (module)

''This page is about the [[Verbcoin (module)]]/template by [[monkey_05_06]]. For other uses of '''Verbcoin''' see [[Verbcoin]].''

==Verbcoin Module/Template==

The Verbcoin module (also included in the Verbcoin template) provides a generic framework for implementing a [[Verbcoin (interface)]] in your game.

===Downloads===
====Latest Versions====

[http://sites.google.com/site/monkey0506/Verbcoin_Template_1.1.rar Verbcoin template v1.1] (For AGS 3.1.1+) (Includes module v1.1)

[http://sites.google.com/site/monkey0506/Verbcoin_1.1.rar Verbcoin module v1.1] (For AGS 3.0+)

[http://meleepta.x10hosting.com/Verbcoin_Demo_1.0a.rar Verbcoin demo v1.0a] (Includes module v1.0a, but not template) (This is the same as the compiled version of the template v1.0a)

====Compatibility Versions====

[http://meleepta.x10hosting.com/Verbcoin_Template_1.0c.rar Verbcoin template v1.0c] (For AGS 3.0+) (No native coordinates, uses low-res coordinates*) (Includes module v1.0b)

[http://meleepta.x10hosting.com/Verbcoin_Template_1.0a.rar Verbcoin template v1.0a] (For AGS 3.1+) (No "normal" dialog scripting, uses run-script*) (Includes module v1.0a)


{{smalltext|*This shouldn't make any difference in your own game if using a higher version of AGS, and would then only to the template files themselves.}}

====Older Versions====

[http://meleepta.x10hosting.com/Verbcoin_Template_1.0b.rar Verbcoin template v1.0b] (For AGS 3.1.1+) (Includes module v1.0a)

[http://meleepta.x10hosting.com/Verbcoin_1.0b.rar Verbcoin module v1.0b] (For AGS 3.0+)

[http://meleepta.x10hosting.com/Verbcoin_Template.rar Verbcoin template v1.0] (Requires AGS 3.2.1+)

[http://meleepta.x10hosting.com/Verbcoin_1.0.rar Verbcoin module v1.0] (Requires AGS 3.2+)

[http://meleepta.x10hosting.com/Verbcoin_Demo.rar Verbcoin demo v1.0] (Includes module v1.0)

===Help and Support===

If you need further help or support beyond the included documentation, contact {{link|monkey_05_06|me}} by posting in {{thread|the Verbcoin module thread|42868.0}} on the forums.

===Getting started with the Verbcoin module===

Getting started with the Verbcoin module is relatively simple. Import the module into your project, and set up your GUI
however you would like. We'll use Button controls to determine where our "verbs" are at, so be sure that you add these
controls where appropriate. Once you've got that taken care of, you'll need to add a few lines to your script to finish
setting up the interface.

{{textcolor|red|Example:}}

  // GlobalScript.asc
  
  function game_start()
  {
    Verbcoin.CoinGUI = gVerbcoin; // tell the module which GUI we will be using for our verbcoin
    Verbcoin.XOffset = gVerbcoin.Width / 2; // set the offset for displaying our GUI
    Verbcoin.YOffset = gVerbcoin.Height / 2; // here we'll just centre it
    Verbcoin.AddButton(btnLook, "Look at", eModeLookat); // add our buttons that the verbcoin will use
    Verbcoin.AddButton(btnTalk, "Talk to", eModeTalkto); // we tell the module what text we want associated with the button
    Verbcoin.AddButton(btnUse, "Use", eModeInteract); // as well as what CursorMode we want to associate the button with
  }

And that's it! This is a fairly basic setup for a verbcoin interface, with three buttons for Look, Talk, and Use. There
are other settings that you may want to look at such as Verbcoin.DefaultMode or Verbcoin.Delay, but this should be
enough to get you started. A full function list, complete with example code, is provided below.

===Enumerated values and macros===

====VerbcoinSettings====
{{smalltext|eVerbcoinDefaultButtonCount}}

Sets the number of buttons to allocate memory for at the start of the game. You may add or remove buttons at runtime, but the closer this is to your initial GUI configuration the less impacting it will be on the start of your game.

{{smalltext|eVerbcoinDefaultDelay}}

Sets the default number of game loops used to determine if the user is holding the mouse down, or has double-clicked, after an initial mouse-click.

{{smalltext|eVerbcoinMaxStateSavingRooms}}

Sets the maximum number of rooms the module will persist data for. Other rooms will be able to take advantage of all module functions, but any data from those rooms will be purged when the next room is loaded.

====Verbcoin_VERSION====

Defines the current version of the module, formatted as a float.

====Verbcoin_VERSION_110====

Defines version 1.1 of the module.

====Verbcoin_VERSION_100====

Defines version 1.0 of the module.

====Verbcoin_UnhandledEventHandler====

This macro is '''NOT''' defined by the module, but it is used if it is defined. See the section below for more information on how this macro is defined and used.

===About the Verbcoin_UnhandledEventHandler macro===

The Verbcoin_UnhandledEventHandler macro is one that is not actually defined by the module, yet is provided to help
future-proof the module's UnhandledEvent function. The module provides the function Verbcoin.UnhandledEvent which is
automatically called by the built-in AGS unhandled_event function, and can be called by the user as needed. However,
since the function belongs to the Verbcoin struct, and it is used internally within the module, this function has to be
defined within the module script.

This isn't necessarily a problem for the module author, but for the end-user it could potentially pose a problem in the
future. If you manually edit the Verbcoin.asc module script file to include your own interactions for unhandled events,
and then later were to upgrade to a newer version of the Verbcoin module, you would lose the modifications you had made
to the module scripts! That's where the Verbcoin_UnhandledEventHandler macro comes in.

As we already said, this macro is ''not'' defined by the module, so how then do you make use of it? This particular macro is
one that ''you'', the user must define to take advantage of it. It is provided with the idea that you're going to be adding
your interactions in a separate script. For the purposes of an example, we'll assume that you have a script, above the
Verbcoin script, called "UnhandledEvent". We'll take a look at what you would want to put in that script to give you an
idea of how this macro is used.

First we'll set up a function in {{smalltext|UnhandledEvent.asc}} where we will actually define our interactions:

  // UnhandledEvent.asc
  
  void UnhandledEventHandler(CursorMode mode, LocationType locType, InventoryItem *theItem)
  {
    if (mode == eModeInteract)
    {
      player.Say("I can't use that.");
    }
    else if (mode == eModeLookat)
    {
      player.Say("I don't see what's so special about it.");
    }
    else if (mode == eModePickup)
    {
      player.Say("I can't pick that up!");
    }
    else if (mode == eModeTalkto)
    {
      player.Say("I can't talk to that.");
    }
    else if (mode == eModeUseinv)
    {
      if (player.ActiveInventory != null)
      {
        if (theItem == null) player.Say("I can't use the %s on that.", player.ActiveInventory.Name);
        else player.Say("I can't use the %s on the %s.", player.ActiveInventory.Name, theItem.Name);
      }
      else player.Say("I can't use that.");
    }
  }

Note that the parameter list for our new function is the same as Verbcoin.UnhandledEvent. If you would like to add any
additional parameters to this function you can, but they '''MUST''' be optional if you do, and these first three parameters
'''MUST''' be the same. Since we've defined this function in UnhandledEvent.asc, upgrading the Verbcoin module will no longer
mean losing our interactions for unhandled events.

Now that we've established our interactions, we need to link these functions together. This is where we actually get
around to defining the macro:

  // UnhandledEvent.ash
  
  #define Verbcoin_UnhandledEventHandler UnhandledEventHandler // $AUTOCOMPLETEIGNORE$
  import void Verbcoin_UnhandledEventHandler(CursorMode, LocationType, InventoryItem*=0);

This is a little more complex than your typical macro, so I'll try to help you understand what's going on here. We
define the macro to have the value of {{smalltext|UnhandledEventHandler}}. This is the name of the function we defined previously.
What this means is that any time we type {{smalltext|Verbcoin_UnhandledEventHandler}}, AGS is going to instead see the name of our
function, {{smalltext|UnhandledEventHandler}}. The comment {{smalltext|$AUTOCOMPLETEIGNORE$}} is a special tag that tells the autocomplete to ignore
this line in our script. We don't actually want the macro itself showing up in the autocomplete list.

The second line is a normal function import, but with a couple things that we're going to look at. We're importing the
function Verbcoin_UnhandledEventHandler, but we haven't defined a function with that name anywhere! But remember, the
macro is telling AGS that what we really mean is UnhandledEventHandler, which is a function that we've defined already.
So, thanks to the macro, we're really importing our function that we defined in the script. I also want to point out
that the InventoryItem parameter is made optional by setting it equal to '''0'''. Normally you can't use integer values like 0
with pointers, but when we're importing a function we are allowed to use the value of 0 as a ''substitute'' for '''null'''.

And that's it. With that set up, the module can now call your custom function automatically when appropriate. This macro
allows the module to check whether you have defined a custom function for processing these unhandled events. Either way
the module function will still be called by the built-in AGS function.

===Global functions and properties===
====Verbcoin functions====
=====Verbcoin.ActionText=====
{{smalltext|readonly String Verbcoin.ActionText}}

Returns the interaction text of the selected verb button for the item last clicked on. This is useful in conjunction
with {{link||Verbcoin.LocationName|LocationName}} for display on a label. If the verbcoin is not shown or the mouse is not over one of the used
buttons, this returns '''null'''.

{{textcolor|red|Example:}}

  lblLocation.Text = String.Format("%s %s", Verbcoin.ActionText, Verbcoin.LocationName);

That would set the text on the label to the current action and location. So if you had clicked on Roger and had the
mouse over the "Look at" button then the text on the label would be "Look at Roger". Keep in mind that this may be
null, so you would want to check that before using it.

''See Also:'' {{link||Verbcoin.ActiveInventoryActionFormat}}, {{link||Verbcoin.ButtonActionText}}, {{link||Verbcoin.LocationName}},
{{link||GetActionText functions}}, {{link||SetActionText functions}}

=====Verbcoin.ActiveInventoryActionFormat=====
{{smalltext|String Verbcoin.ActiveInventoryActionFormat}}

Used to get or set the format string for when the player has an active inventory item. This format should contain one
"{{smalltext|%s}}" modifier to have the name of the inventory item inserted. You won't normally need to read this value once it's
set as the {{link||Verbcoin.ActionText|ActionText}} will be properly updated when there is an active inventory item. The default value is simply
"{{smalltext|Use %s with}}".

{{textcolor|red|Example:}}

  Verbcoin.ActiveInventoryActionFormat = "Give %s to";

This would change the formatting of the ActionText when there is an active inventory item. This particular example
might be useful if the mouse is over a Character.

''See Also:'' {{link||Verbcoin.ActionText}}

=====Verbcoin.AddButton=====
{{smalltext|bool Verbcoin.AddButton(Button*, String actionText, CursorMode)}}

Attempts to add the specified button to the verbcoin with the given interaction text and mouse mode. This can fail if
the {{link||Verbcoin.CoinGUI|CoinGUI}} isn't set yet or an invalid button is specified. Returns '''true''' upon success, '''false''' upon failure.

{{textcolor|red|Example:}}

  Verbcoin.AddButton(btnLook, "Look at", eModeLookat);

You might do this to set up your GUI in {{smalltext|game_start}}, or if you add more options later in the game.

''See Also:'' {{link||Verbcoin.ButtonCount}}, {{link||Verbcoin.Buttons}}, {{link||Verbcoin.CoinGUI}}, {{link||Verbcoin.MaxButtonCount}}, {{link||Verbcoin.RemoveButton}}

=====Verbcoin.ButtonActionText=====
{{smalltext|String Verbcoin.ButtonActionText[int index]}}

Used to get or set the interaction text for the button at {{smalltext|INDEX}}. This is the default action that will be supplied to
{{link||Verbcoin.ActionText|ActionText}} when the mouse is over this button. To determine which {{smalltext|INDEX}} you need for a given button, use {{link||Verbcoin.GetButtonID|GetButtonID}}.

{{textcolor|red|Example:}}

  int bID = Verbcoin.GetButtonID(btnLook);
  Verbcoin.ButtonActionText[bID] = "Examine";

This changes the text supplied when the button was added to the Verbcoin to "Examine".

''See Also:'' {{link||Verbcoin.ActionText}}, {{link||Verbcoin.AddButton}}, {{link||Verbcoin.ButtonCount}}, {{link||Verbcoin.ButtonMode}}, {{link||Verbcoin.Buttons}},
{{link||Verbcoin.GetButtonID}}, {{link||Verbcoin.SetButtonActionText}}, {{link||GetActionText functions}}, {{link||SetActionText functions}}

=====Verbcoin.ButtonCount=====
{{smalltext|readonly int Verbcoin.ButtonCount}}

Returns the number of buttons currently in use by the verbcoin. This can help you determine whether or not you can add
more buttons to the verbcoin, as well as giving the size of the Button arrays.

{{textcolor|red|Example:}}

  int i = 0;
  while (i < Verbcoin.ButtonCount)
  {
    Display("Button\[%d] action: %s", i, Verbcoin.ButtonActionText[i]);
    i++;
  }

This would display the interaction text for every button currently in-use by the module.

''See Also:'' {{link||Verbcoin.AddButton}}, {{link||Verbcoin.ButtonActionText}}, {{link||Verbcoin.ButtonMode}}, {{link||Verbcoin.Buttons}},
{{link||Verbcoin.MaxButtonCount}}, {{link||Verbcoin.RemoveButton}}

=====Verbcoin.ButtonMode=====
{{smalltext|CursorMode Verbcoin.ButtonMode[int index]}}

Used to get or set the interaction mode for the button at {{smalltext|INDEX}}. This is the mode that will be used when the mouse is
released over the button on the verbcoin. To determine which {{smalltext|INDEX}} you need for a given button, use {{link||Verbcoin.GetButtonID|GetButtonID}}.

{{textcolor|red|Example:}}

  int bID = Verbcoin.GetButtonID(btnLook);
  Verbcoin.ButtonMode[bID] = eModeUsermode1;

This changes all future uses of btnLook on the verbcoin to use eModeUsermode1.

''See Also:'' {{link||Verbcoin.ButtonActionText}}, {{link||Verbcoin.ButtonCount}}, {{link||Verbcoin.Buttons}}, {{link||Verbcoin.GetButtonID}},
{{link||Verbcoin.SetButtonMode}}

=====Verbcoin.Buttons=====
{{smalltext|readonly Button* Verbcoin.Buttons[int index]}}

Returns the button at the specified {{smalltext|INDEX}} from those currently in use by the verbcoin. These cannot be set directly
since they are directly tied to both the interaction text and mode. To get the index for a given button, use
{{link||Verbcoin.GetButtonID|GetButtonID}} instead.

{{textcolor|red|Example:}}

  if (Verbcoin.Buttons[2] == btnLook) Display("btnLook is at index 2!");

Of course you would probably want to use GetButtonID for this instead anyway.

''See Also:'' {{link||Verbcoin.AddButton}}, {{link||Verbcoin.ButtonActionText}}, {{link||Verbcoin.ButtonCount}}, {{link||Verbcoin.ButtonMode}},
{{link||Verbcoin.GetButtonID}}, {{link||Verbcoin.RemoveButton}}

=====Verbcoin.ClickedX=====
{{smalltext|readonly int Verbcoin.ClickedX}}

Returns the X coordinate of the last mouse-click registered by the module. You won't normally need this, and it will
be reset to -1 when not in use by the module.

{{textcolor|red|Example:}}

  Display("Clicked at (%d,%d)!", Verbcoin.ClickedX, Verbcoin.ClickedY);

Would display the coordinates of the last click. As noted however, this isn't really a practical example, but you
might be able to find some use of the information.

''See Also:'' {{link||Verbcoin.ClickedY}}

=====Verbcoin.ClickedY=====
{{smalltext|readonly int Verbcoin.ClickedY}}

Returns the Y coordinate of the last mouse-click registered by the module. You won't normally need this, and it will
be reset to -1 when not in use by the module.

{{textcolor|red|Example:}}

  Display("Clicked at (%d,%d)!", Verbcoin.ClickedX, Verbcoin.ClickedY);

Once again, you might be able to find some reason to want this information, but you probably shouldn't need it.

''See Also:'' {{link||Verbcoin.ClickedX}}

=====Verbcoin.CoinGUI=====
{{smalltext|GUI* Verbcoin.CoinGUI}}

Used to get or set the GUI used as the "coin" of the verbcoin. This GUI '''must''' be the OwningGUI of any Buttons that
you want to use on the verbcoin.

{{textcolor|red|Example:}}

  Verbcoin.CoinGUI = gVerbcoin;

You would do something like this in {{smalltext|game_start}} to set up your GUI for the first time, and of course it can be changed
at runtime if needed.
  
'''NOTE:''' Since all interaction text and mouse modes are linked to their respective Button controls, if the CoinGUI is
changed at runtime, '''ALL''' of this information will be '''LOST'''. If you are using more than one GUI in your game, consider
this carefully when setting up your game. You may want to just rearrange the existing GUI, or possibly use a custom
function to switch between the GUIs.

''See Also:'' {{link||Verbcoin.AddButton}}, {{link||Verbcoin.RemoveButton}}, {{link||Verbcoin.XOffset}}, {{link||Verbcoin.YOffset}}

=====Verbcoin.DefaultMode=====
{{smalltext|CursorMode Verbcoin.DefaultMode}}

Used to get or set the default interaction mode, when the mouse is just clicked instead of held. The default value for
this is eModeWalkto.

{{textcolor|red|Example:}}

  Verbcoin.DefaultMode = eModeInteract;

Changes the normal interaction mode to eModeInteract.

''See Also:'' {{link||Verbcoin.Delay}}

=====Verbcoin.Delay=====
{{smalltext|int Verbcoin.Delay}}

Gets or sets the delay used in determining whether the mouse is held down, or double-clicked, after a mouse-click.

{{textcolor|red|Example:}}

  Verbcoin.Delay = GetGameSpeed() / 4;

Sets the delay to 1/4 of a second.

'''NOTE:''' Verbcoin functions may be intercepted by {{smalltext|Game.IgnoreUserInputAfterTextTimeoutMs}}. This is ''NOT'' a bug in the
module, but is rather by design.

''See Also:'' {{link||Verbcoin.DoubleClicked}}

=====Verbcoin.DoubleClicked=====
{{smalltext|readonly bool Verbcoin.DoubleClicked}}

Returns whether the user clicked the mouse twice within the specified {{link||Verbcoin.Delay|delay}} time.

Example:

  if (Verbcoin.DoubleClicked)
  {
    Verbcoin.IgnoreLastClickOrDoubleClick();
    // ..do something else here..
  }

That would override the normal module handling of the mouse-click, providing you the opportunity to do something else
with the double-click.

'''NOTE:''' The Verbcoin module does ''NOT'', by default, provide any "default interaction" methods for use with a double-click.
If you want to do something with a double-click, this is provided so you can use it as you wish, but there is nothing
built-in of this nature.

'''NOTE:''' By default double-clicking is treated the same as single-clicking twice. You must set {{link||Verbcoin.UseDoubleClicks}}
yourself if you want this to ever return true.

'''NOTE:''' Prior to Verbcoin v1.1 this value would only return true ONCE per double-click. After it has returned true, the
value would be cleared. If you are using v1.0 of the module, be sure to store this value separately if you need to use
it more than once per double-click.

'''NOTE:''' Prior to Verbcoin v1.1 you had to call {{link||Verbcoin.IgnoreLastClickOrDoubleClick|IgnoreLastClickOrDoubleClick}} to prevent a double-click from being processed
as two single-clicks (even if double-clicks were enabled). You no longer have to call this function to stop the single-
clicks from being processed, but this value will remain set to true until the function is called.

''See Also:'' {{link||Verbcoin.Delay}}, {{link||Verbcoin.IgnoreLastClickOrDoubleClick}}, {{link||Verbcoin.UseDoubleClicks}}

=====Verbcoin.Enabled=====
{{smalltext|bool Verbcoin.Enabled}}

Used to enable or disable the verbcoin module functions. This can be useful if you want to temporarily disable the
verbcoin.

{{textcolor|red|Example:}}

  Verbcoin.Enabled = false;

This disables the module functions without purging any of the module data.

=====Verbcoin.GetButtonID=====
{{smalltext|int Verbcoin.GetButtonID(Button*)}}

Returns the index for the specified button that can be used with the Button arrays, or -1 if the button is not in-use
by the module.

{{textcolor|red|Example:}}

  int bID = Verbcoin.GetButtonID(btnLook);
  Verbcoin.ButtonActionText[bID] = "Examine";

Changes the interaction text for btnLook to "Examine".

''See Also:'' {{link||Verbcoin.ButtonActionText}}, {{link||Verbcoin.ButtonCount}}, {{link||Verbcoin.ButtonMode}}, {{link||Verbcoin.Buttons}}

=====Verbcoin.Hotspot0Name=====
{{smalltext|String Verbcoin.Hotspot0Name}}

Used to get or set the name, as used by {{link||Verbcoin.LocationName|LocationName}}, for hotspot 0. By default this is set to '''null''' and is not used.
The value is reset upon entering a new room, or if IgnoreHotspot0 is set to true.

{{textcolor|red|Example:}}

  Verbcoin.Hotspot0Name = "nothing";

This would set the name to "nothing" so that whenever the mouse is over hotspot 0 (but not over anything else such as
a character or object) then LocationName would be set to "nothing".

''See Also:'' {{link||Verbcoin.IgnoreHotspot0}}, {{link||Verbcoin.LocationName}}

=====Verbcoin.IgnoreHotspot0=====
{{smalltext|bool Verbcoin.IgnoreHotspot0}}

Used to control whether hotspot 0 is ignored by the module. If this is '''true''' then the verbcoin will not be activated by
clicking on hotspot 0 at all; otherwise hotspot 0 will be treated as a normal hotspot. This value is automatically
updated if {{link||Verbcoin.Hotspot0Name|Hotspot0Name}} is changed (if Hotspot0Name is set to '''null''' then this is set to true, any other value for
Hotspot0Name will set this to false).

{{textcolor|red|Example:}}

  Verbcoin.IgnoreHotspot0 = false;
  Verbcoin.Hotspot0Name = "nothing";

This will enable the usage of hotspot 0 by the module, and update the name to use for the hotspot. Since this value is
automatically updated, this isn't a necessary step.

=====Verbcoin.IgnoreInventoryClicks=====
{{smalltext|bool Verbcoin.IgnoreInventoryClicks}}

Used to get or set whether the module should ignore clicks on the inventory. By default, inventory items are treated the
same as characters, objects, and hotspots with regards to the verbcoin functions (meaning, you use the verbcoin to
interact with them). You can use this value if you want to handle inventory clicks a different way (without the verbcoin).

{{textcolor|red|Example:}}

  Verbcoin.IgnoreInventoryClicks = true;

This would tell the module to ignore any mouse-clicks on an inventory item, so that you could process it yourself.

'''Compatibility:''' Supported by Verbcoin v1.1 and higher.

=====Verbcoin.IgnoreLastClickOrDoubleClick=====
{{smalltext|void Verbcoin.IgnoreLastClickOrDoubleClick()}}

Tells the module to ignore the last click or double-click, and cancels any module processing of it. This might be
useful if you want to use double-clicks for something, since the module does not provide any methods for using them.

{{textcolor|red|Example:}}

  if (Verbcoin.DoubleClicked)
  {
    Verbcoin.IgnoreLastClickOrDoubleClick();
    // ..do something here..
  }

How you might want to use double-clicks is up to you,  but this function will override the verbcoin functions for you.
  
'''NOTE:''' Prior to Verbcoin v1.1 you had to call this function to prevent a double-click from being processed as two single-
clicks (even if double-clicks were enabled). You no longer have to call this function to stop the single-clicks from
being processed, but DoubleClicked will remain set to true (for double-clicks) until this function is called.

''See Also:'' {{link||Verbcoin.DoubleClicked}}, {{link||Verbcoin.Enabled}}, {{link||Verbcoin.UseDoubleClicks}}

=====Verbcoin.LocationName=====
{{smalltext|readonly String Verbcoin.LocationName}}

Returns the name of whatever the mouse is over. If the mouse-button is held down and the verbcoin is displayed, then
this will display the name of what the user clicked on.

{{textcolor|red|Example:}}

  if (Verbcoin.ActionText == null) lblLocation.Text = Verbcoin.LocationName;
  else lblLocation.Text = String.Format("%s %s", Verbcoin.ActionText, Verbcoin.LocationName);

This would update the text on the label to show the current action and location.

''See Also:'' {{link||Verbcoin.ActionText}}

=====Verbcoin.MaxButtonCount=====
{{smalltext|readonly int Verbcoin.MaxButtonCount}}

Returns the maximum number of buttons that the module supports using at once. This is determined partially by the
number of characters and inventory items in your game, the value of {{smalltext|AGS_MAX_HOTSPOTS}}, and the value of
{{smalltext|AGS_MAX_OBJECTS}}. Additionally, this value will never be higher than {{smalltext|AGS_MAX_CONTROLS_PER_GUI}} since all the buttons
must be on the {{link||Verbcoin.CoinGUI|CoinGUI}}.

{{textcolor|red|Example:}}

  if (Verbcoin.ButtonCount < Verbcoin.MaxButtonCount) Verbcoin.AddButton(btnTalk, "Talk to", eModeTalkto);

Of course you don't need to check this yourself normally as the {{link||Verbcoin.AddButton|AddButton}} function will simply return false if there
are too many buttons in use.

''See Also:'' {{link||Verbcoin.AddButton}}, {{link||Verbcoin.ButtonCount}}, {{link||Verbcoin.Buttons}}, {{link||Verbcoin.RemoveButton}}

=====Verbcoin.MouseButtonToUse=====
{{smalltext|MouseButton Verbcoin.MouseButtonToUse}}

Used to get or set which MouseButton you want to use to activate the Verbcoin. The default is eMouseLeft.

{{textcolor|red|Example:}}

  Verbcoin.MouseButtonToUse = eMouseRight;

This would set the module to use the right mouse button for the verbcoin instead of the left.
  
'''Compatibility:''' Supported by Verbcoin v1.1 and higher.

=====Verbcoin.RemoveButton=====
{{smalltext|bool Verbcoin.RemoveButton(Button*)}}

Removes the specified button from the verbcoin. This also removes any interaction text associated with the button,
so just keep that in mind. Returns false if the verbcoin was not using the button, or true if it was removed.

{{textcolor|red|Example:}}

  Verbcoin.RemoveButton(btnTalk);

This would remove the btnTalk button from the verbcoin. Useful, perhaps, if your player gets his mouth removed.

''See Also:'' {{link||Verbcoin.AddButton}}

=====Verbcoin.SetButtonActionText=====
{{smalltext|bool Verbcoin.SetButtonActionText(Button*, String actionText)}}

Changes the interaction text for the specified button to {{smalltext|ACTIONTEXT}}. This is used when you want to permanently change
the default value for the button. If you instead want to supply an alternate value for a Character, Object, etc. then
use the {{link||SetActionText functions}} instead.

{{textcolor|red|Example:}}

  Verbcoin.SetButtonActionText(btnLook, "Examine");

Changes the action text for btnLook to "Examine".

'''NOTE:''' You can do this for buttons already in-use by the verbcoin by setting {{link||Verbcoin.ButtonActionText|ButtonActionText}} directly. This function
will add a button that is not already in-use to the verbcoin. For adding buttons it is recommended however that you
use {{link||Verbcoin.AddButton|AddButton}} instead since that will allow you to specify the button mode at the same time.

''See Also:'' {{link||Verbcoin.AddButton}}, {{link||Verbcoin.ButtonActionText}}, {{link||Verbcoin.SetButtonMode}}

=====Verbcoin.SetButtonMode=====
{{smalltext|bool Verbcoin.SetButtonMode(Button*, CursorMode)}}

Changes the interaction mode for the specified button. This is the mode that will be processed when the mouse is
released over the button on the verbcoin.

{{textcolor|red|Example:}}

  Verbcoin.SetButtonMode(btnTalk, eModeUsermode1);

Changes the cursor mode for btnTalk to eModeUsermode1.

'''NOTE:''' You can do this for buttons already in-use by the verbcoin by setting {{link||Verbcoin.ButtonMode|ButtonMode}} directly. This function will
add a button that is not already in-use to the verbcoin. For adding buttons it is recommended however that you use
{{link||Verbcoin.AddButton|AddButton}} instead since that will allow you to specify the action text at the same time.

''See Also:'' {{link||Verbcoin.AddButton}}, {{link||Verbcoin.ButtonMode}}, {{link||Verbcoin.SetButtonActionText}}

=====Verbcoin.UnhandledEvent=====
{{smalltext|void Verbcoin.UnhandledEvent(CursorMode, LocationType, optional InventoryItem*)}}

Processes an unhandled interaction. The {{smalltext|CursorMode}} and {{smalltext|LocationType}} determine what type of interaction, and with
what. The optional InventoryItem parameter is used if LocationType is eLocationNothing but the mouse was over an
InventoryItem. This function will automatically be called via the built-in AGS {{smalltext|unhandled_event}}, and comes with some
generic default responses.
  
If you want to specify your own interactions, it is recommended '''NOT''' to change the module code, but to use the
{{link||About the Verbcoin_UnhandledEventHandler macro|Verbcoin_UnhandledEventHandler macro}} instead. Read about that macro for more information on how it is used. Using
the macro will prevent you losing your code if you ever upgrade to a higher version of the Verbcoin module.

{{textcolor|red|Example:}}

  Verbcoin.UnhandledEvent(eModeUseinv, eLocationNothing, InventoryItem.GetAtScreenXY(mouse.x, mouse.y);

This would process the assigned interactions for an otherwise unhandled usage of an active inventory item on another
inventory item. Of course, this would already be handled automatically, but you can call the function yourself if you
need it, for example if you are using keyboard controls to simulate using the mouse.

=====Verbcoin.UseDoubleClicks=====
{{smalltext|bool Verbcoin.UseDoubleClicks}}

Used to get or set whether double-clicks of the mouse should be detected. This is '''FALSE''' by default as double-clicks
are not used by the module. If this is false, then {{link||Verbcoin.DoubleClicked|DoubleClicked}} will never be true.

{{textcolor|red|Example:}}

  Verbcoin.UseDoubleClicks = true;

Activates detection of double-clicks. Again, double-clicks are not used by the module, but you must set this value
if you want to make use of DoubleClicked.

''See Also:'' {{link||Verbcoin.DoubleClicked}}

=====Verbcoin.XOffset=====
{{smalltext|int Verbcoin.XOffset}}

Used to get or set the x-offset of the {{link||Verbcoin.CoinGUI|coin GUI}}. This is used to position the GUI, relative to the position of where
you last clicked.

{{textcolor|red|Example:}}

  Verbcoin.XOffset = Verbcoin.CoinGUI.Width / 2;
  Verbcoin.YOffset = Verbcoin.CoinGUI.Height / 2;

This would position the coin GUI to be directly centred around the point at which you click the mouse.

''See Also:'' {{link||Verbcoin.CoinGUI}}, {{link||Verbcoin.YOffset}}

=====Verbcoin.YOffset=====
{{smalltext|int Verbcoin.YOffset}}

Used to get or set the y-offset of the {{link||Verbcoin.CoinGUI|coin GUI}}. This is used to position the GUI, relative to the position of where
you last clicked.

{{textcolor|red|Example:}}

  Verbcoin.XOffset = Verbcoin.CoinGUI.Width / 2;
  Verbcoin.YOffset = Verbcoin.CoinGUI.Height / 2;

This would position the coin GUI to be directly centred around the point at which you click the mouse.

''See Also:'' {{link||Verbcoin.CoinGUI}}, {{link||Verbcoin.XOffset}}

====GetActionText functions====
=====Character.GetActionText=====
{{smalltext|String Character.GetActionText(Button*)}}
=====Hotspot.GetActionText=====
{{smalltext|String Hotspot.GetActionText(Button*)}}
=====InventoryItem.GetActionText=====
{{smalltext|String InventoryItem.GetActionText(Button*)}}
=====Object.GetActionText=====
{{smalltext|String Object.GetActionText(Button*)}}

These four extender methods are provided by the module so that you can retrieve the appropriate action text for the
given item. If the specified button is not in-use by the module then this will return '''null'''; otherwise if there is a
custom value given for the specified item, that custom value will be returned. If the button is valid but no custom
value has been supplied, this function will return the default action text for the given button.

{{textcolor|red|Example:}}

  Display(player.GetActionText(btnLook));

This would display the action text associated with the player character for the btnLook button.

''See Also:'' {{link||Verbcoin.ActionText}}, {{link||Verbcoin.ButtonActionText}}, {{link||Verbcoin.SetButtonActionText}}, {{link||SetActionText functions}}

====SetActionText functions====
=====Character.SetActionText=====
{{smalltext|void Character.SetActionText(Button*, String actionText)}}
=====Hotspot.SetActionText=====
{{smalltext|void Hotspot.SetActionText(Button*, String actionText)}}
=====InventoryItem.SetActionText=====
{{smalltext|void InventoryItem.SetActionText(Button*, String actionText)}}
=====Object.SetActionText=====
{{smalltext|void Object.SetActionText(Button*, String actionText)}}

These four extender methods are provided by the module so that you can set custom interaction text for individual
items. If the specified button is not in-use by the module then this function is ignored. To disable the custom
interaction text and use the default instead, simply pass '''null''' as the second parameter.

{{textcolor|red|Example:}}

  iCracker.SetActionText(btnTalk, "Taste");

Changes the interaction text for the iCracker inventory item to "Taste". This doesn't affect the default interaction
text, so other items will still use "Talk to" as the action text, unless they have a custom value supplied.

''See Also:'' {{link||Verbcoin.ActionText}}, {{link||Verbcoin.ButtonActionText}}, {{link||Verbcoin.SetButtonActionText}}, {{link||GetActionText functions}}

====Advanced functions====
In addition to the functions listed above, there are some functions provided that are intended for '''ADVANCED''' users '''ONLY'''.
If you are not familiar with scripting in AGS, it is recommended that you ''do not'' use these functions as they are not
typically required for use. These functions should not cause major issues if you do use them, but they can create
problems if you don't understand what they are for. For these reasons, these functions will '''NOT''' appear in autocomplete.

=====Verbcoin.AllocateButtonMemory=====
{{smalltext|void Verbcoin.AllocateButtonMemory(int buttonCount)}}

Attempts to allocate memory for {{smalltext|BUTTONCOUNT}} buttons. If {{smalltext|BUTTONCOUNT}} is less than the number of buttons for which
memory is already allocated, this function is ignored. This will not allocate memory for more than {{link||Verbcoin.MaxButtonCount|MaxButtonCount}}
buttons, though if {{smalltext|BUTTONCOUNT}} is higher than this, it will be adjusted appropriately. This function is provided
because it is faster to reallocate any existing memory once than to have to resize the arrays several times.
  
This function is automatically called by the module with the value of {{link||VerbcoinSettings|eVerbcoinDefaultButtonCount}}. You should try to
set that enumerated value as close as possible to the actual '''MAXIMUM''' number of buttons you will use on your verbcoin
in-game. Setting this number too high will only use up system resources unnecessarily, but setting it too low will
cause slower processing when the buttons are actually added to your verbcoin.

{{textcolor|red|Example:}}

  Verbcoin.AllocateButtonMemory(6);

If you wanted to have a total of 6 buttons on your verbcoin GUI, this would allocate the memory for all 6 buttons at
once.

'''NOTE:''' Even if you do not use this function, you can still add more buttons at runtime, up to MaxButtonCount. The
purpose of this function is to prevent having to reallocate the existing memory multiple times when the buttons are
added.

''See Also:'' {{link||Verbcoin.AddButton}}, {{link||Verbcoin.MaxButtonCount}}, {{link||Verbcoin.RemoveButton}}, {{link||Verbcoin.DeallocateButton}},
{{link||Verbcoin.DeallocateButtonMemory}}

=====Verbcoin.DeallocateButton=====
{{smalltext|bool Verbcoin.DeallocateButton(Button*)}}

Attempts to remove a button from the verbcoin, and deallocate any memory associated with that button. This is
essentially the same as the {{link||Verbcoin.RemoveButton|RemoveButton}} function with the exception of deallocating the memory. Unless you are not
going to adding any more buttons for the remainder of the game, it is best to use RemoveButton instead so additional
memory allocation is not required.

{{textcolor|red|Example:}}

  Verbcoin.DeallocateButton(btnTalk);

Deallocates btnTalk from the module's memory, and removes it from the verbcoin. Again, you normally would ''NOT'' want or
need to use this, but if you are certain you are not going to be adding any more buttons to the verbcoin then it can
release the memory that was allocated by the button.

''See Also:'' {{link||Verbcoin.RemoveButton}}, {{link||Verbcoin.AllocateButtonMemory}}, {{link||Verbcoin.DeallocateButtonMemory}}

=====Verbcoin.DeallocateButtonMemory=====
{{smalltext|void Verbcoin.DeallocateButtonMemory()}}

Completely deallocates all memory associated with the verbcoin's buttons. This will effectively therefore remove all
buttons from the verbcoin, and will also erase any custom interaction text set by the {{link||SetActionText functions}}.
Consider this carefully before calling this function, because even if you allocate the memory again later, all prior
data will be lost.

{{textcolor|red|Example:}}

  Verbcoin.DeallocateButtonMemory();

This would completely and totally obliterate the data the module was using to keep track of the relations between your
buttons and the items in your game. Useful perhaps if you're permanently disabling the module.

''See Also:'' {{link||Verbcoin.AllocateButtonMemory}}, {{link||Verbcoin.DeallocateButton}}

===License===
Permission is hereby granted, free of charge, to any person obtaining a copy of this script module and associated
documentation files (the "Module"), to deal in the Module without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Module, and to permit persons to whom
the Module is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
Module.

No copy or substantial portion of the Module shall be sold with the exception of those copies or portions which are a
compiled portion of other software. The Module shall not be sold in the form of non-compiled script.

'''THE MODULE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE'''
'''WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR'''
'''COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR'''
'''OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE MODULE OR THE USE OR OTHER DEALINGS IN THE MODULE.'''

===Changelog===
====Version 1.1====
  Version:      1.1
  Author:       monkey_05_06
  Date:         19 April 2011
  Description:  Added Verbcoin.MouseButtonToUse and Verbcoin.IgnoreInventoryClicks to make the module more customizable, revised behavior of the DoubleClicked property to something more sensible, optimized the way in which MaxButtonCount is set, and corrected documentation for IgnoreHotspot0.

====Version 1.0b====
  Version:      1.0b
  Author:       monkey_05_06
  Date:         03 March 2011
  Description:  Removed references to String.IsNullOrEmpty to allow full backwards-compatibility to AGS 3.0. Module is now fully compatible with AGS 3.0+. No further changes made.

====Version 1.0a====
  Version:      1.0a
  Author:       monkey_05_06
  Date:         13 February 2011
  Description:  Fixed a line which required AGS 3.2 to fix compatibility with prior AGS versions. No other changes made.

====Version 1.0====
  Version:      1.0
  Author:       monkey_05_06
  Date:         12 February 2011
  Description:  First public release.

[[Category:Design resources]]