Add support for running functions when text is clicked

CHANGELOG.md

@@ -0,0 +1,9 @@
+## CHANGELOG
+
+### v0.2 (2015-10-04)
+
+* Implemented the ability to run a callback function when the user clicks on specific text. This can be used to implement hyperlinks, among other things.
+
+### v0.1 (2015-09-27)
+
+* Initial Release. Did not have a version number.

README.md

@@ -20,6 +20,7 @@ A Scribe object is returned, which acts as a Factory. Using this object, you can
   * [Fonts and Colors](#fonts-and-colors)
   * [Text-Modifying Functions](#text-modifying-functions)
   * [Images](#images)
+  * [Clicks](#clicks)
   * [Setting the Background](#setting-the-background)
   * [Setting a Name](#setting-a-name)
   * [Adding or Replacing Text](#adding-or-replacing-text)
@@ -47,6 +48,11 @@ end
 function love.draw()
     textbox:draw()
 end
+
+-- Optional, only necessary if you want to use click functions.
+function love.mousepressed( x, y, b )
+	textbox:mousepressed( x, y, b )
+end
 ```
 
 ![ex1](http://i.imgur.com/bbX3GVq.gif)
@@ -146,6 +152,45 @@ textbox = Scribe({
 
 Note that images are not automatically resized in any way. It is up to you to ensure that enough space is reserved for the image, and that it is no bigger than the height of a single row of text.
 
+### Clicks
+
+SCRÏBE allows you to run a callback function when clicking on a particular piece of text. The default callback function allows you to create hyperlinks, and works like this:
+
+```lua
+textbox = Scribe({
+    text = '[Hello, World!](onclick: "link", "http://www.google.ca")',
+    font = love.graphics.newFont( 'animeace2_reg.ttf', 24 )
+})
+```
+
+Clicking on the "Hello, World!" text will launch Google in your system default web browser.
+
+You can override the default callback function when creating the textbox object, by setting the `click_callback` parameter. The function you provide takes five values as input:
+
+* `x` - The absolute x coordinate of where the click occurred
+* `y` - The absolute y coordinate of where the click occurred
+* `button` - The mouse button pressed - `l` for left or `r` for right
+* `op` - The operation to perform, so that your callback function may perform many different operations.
+* `param` - The parameter required to execute the operation.
+
+For example, here's how you could implement both hyperlinks and a simple logger:
+
+```lua
+function hyperlinksAndLogger( x, y, button, op, param )
+    if op == 'link' and button == 'l' then
+        love.system.openURL( param )
+    elseif op == 'log' and button == 'l' then
+        print( param )
+    end
+end
+textbox = Scribe({
+    text = '[Hello](onclick: "log", "Hello, Log!"), [World!](onclick: "link", "http://www.google.ca")',
+    font = love.graphics.newFont( 'animeace2_reg.ttf', 24 ),
+    click_callback = hyperlinksAndLogger
+})
+```
+
+
 ### Setting the Background
 
 SCRÏBE supports two different methods of setting the textbox background. The first is to write your own function to draw it. The function must accept four parameters - `x`, `y`, `w`, and `h` - so that SCRÏBE can tell it what size box to draw and where to draw it. The function then needs to be passed into the `bg` parameter when creating the textbox:

Scribe.lua

@@ -1,4 +1,5 @@
 --- SCRÏBE: A message box library for Love2D 
+-- @version 0.2
 -- @license MIT https://github.com/smallsco/scribe/blob/master/LICENSE
 local Scribe = {}
 Scribe.__index = Scribe
@@ -11,6 +12,22 @@ local require_path = (...):match( "(.-)[^%.]+$" )
 local popo = require( require_path .. '.popo.Text' )
 
 
+--- The default click callback function. Creates a "link" operation that opens the "param"
+--- as a URL (i.e. using your web browser) if the left mouse button is pressed.
+-- @param number x The absolute x coordinate of the click
+-- @param number y The absolute y coordinate of the click
+-- @param string button The left "l" or right "r" mouse button pressed
+-- @param string op The operation to perform
+-- @param string param The parameter to use with the operation
+local function defaultClickCallback( x, y, button, op, param )
+
+    if op == 'link' and button == 'l' then
+        love.system.openURL( param )
+    end
+
+end
+
+
 --- Gets the x/y scale factors required to resize a source image to a target size.
 -- @see https://love2d.org/forums/viewtopic.php?f=4&t=79756
 -- @param userdata image The source Image object
@@ -62,6 +79,7 @@ function Scribe.new( opt )
     self.h = opt.h or ( self.font:getHeight() * 4 ) + ( self.ypad * 2 )
     self.bg = opt.bg or renderDefaultContainer
     self.scale_bg = ( opt.scale_bg == nil ) and true or opt.scale_bg
+    self.click_callback = ( opt.click_calback == nil ) and opt.click_callback or defaultClickCallback
     self.color = opt.color or { 255, 255, 255 }
     self.name = opt.name
     self.name_color = opt.name_color or { 255, 255, 0 }
@@ -117,6 +135,12 @@ function Scribe:regenerate( append )
         color = function( dt, c, r, g, b )
             love.graphics.setColor( r, g, b )
         end,
+        onclick = function( dt, c, op, param )
+            if not c.click_op then
+                c.click_op = op
+                c.click_param = param
+            end
+        end,
         customDraw = function( x, y, c )
             love.graphics.print(
                 c.character,
@@ -185,13 +209,44 @@ function Scribe:regenerate( append )
 end
 
 
+
+function Scribe:mousepressed( x, y, button )
+    for _, v in ipairs( self.popo.characters ) do
+        if v.click_op ~= nil then
+
+            -- translate the localized x, y into absolute coordinates
+            local tx = v.x + self.x + self.xpad
+            local ty = v.y + self.y + 10
+
+            if x >= tx and x < self.popo.font:getWidth( v.character ) + tx then
+                if y >= ty and y < self.popo.font:getHeight() + ty then
+                    self.click_callback( x, y, button, v.click_op, v.click_param )
+                end
+            end
+
+        end
+    end
+end
+
+
 --- Updates the background of the message box.
 -- @param mixed bg The new background of the message box. Can be an image or a function.
 function Scribe:setBackground( bg )
     self.bg = bg or renderDefaultContainer
 end
 
 
+--- Updates the click callback function.
+-- @param function f The new click callback function
+function Scribe:setClickCallback( f )
+    if type( f ) == 'function' then
+        self.click_callback = f
+    else
+        error( 'Click callback must be a function' )
+    end
+end
+
+
 --- Updates the default text color of the message box.
 -- @param table color The new default color for text in the message box
 function Scribe:setColor( color )