Logitech G15 Gamers Keyboard interface for MUSHclient

 Author: Nick Gammon
 Date:   16th June 2006
 Version: 1.1
 License: This software is distributed subject to the license agreement at the foot of this page.

Developed using LCDSDK_1.02.218 as distributed by Logitech. If you want to compile it yourself you will need to obtain a copy of that. An earlier version is distributed with the keyboard CD (as purchased) however I recommend upgrading the keyboard software to obtain the latest version.


Files included in this distribution:

DLL:

G15_Display.dll - use this from Lua in MUSHclient

Source files:

G15_Display.cpp - source for the interface
G15_Display.dsp - Microsoft Visual Studio project file
G15_Display.dsw - Microsoft Visual Studio workspace file

Documentation:

readme.txt - this file

HOW TO USE
----------

You need to load the DLL from inside MUSHclient, within a Lua scripting environment (main program or plugin):

  assert (loadlib ("G15_Display.dll", "luaopen_g15")) ()  -- install
  g15.SetAsForeground (true)  -- bring to foreground
  
This installs the "g15" table with the following functions:

IsOpen - check if the keyboard interface loaded OK.

  eg.  assert (g15.IsOpen ())

IsConnected - check if the keyboard is connected OK. 

  eg.  assert (g15.IsConnected ())

Update - force an update of the LCD screen - done automatically after setting text but you can do it manually if you are using scrolling text, say every second or so.

  eg. g15.Update ()


AddText - adds a new "text" object, returning a userdata which can be used to change the text in it.

  All arguments have defaults.
  
  Syntax: g15.addtext (type, size, align, pixels, x, y)
  
    type = one of:  static/scrolling  (default: static)
    size = one of:  small/medium/big  (default: small)
    align = one of: left/center/right (default: left)
    pixels = maximum width in pixels (eg. up to 160)  (default: 80)
    x = X-position (0 = left)  (default: 0)
    y = Y-position (0 = top)   (default: 0)
  
  eg. hp_text = g15.AddText ("static", "small", "right", 40, 0, 0)

    Small text is 7 point, medium is 8 point, big is 12 point.
        
AddProgressBar - adds a new "progress bar" object, returning a userdata which can be used to change the progress amount in it.  

  All arguments have defaults.

  Syntax: g15.AddProgressBar (type, sizeX, sizeY, x, y)
  
    type = one of:  cursor/filled/dot  (default: cursor)
    sizeX = width in pixels   (default: 120)
    sizeY = height in pixels  (default: 5)
    x = X-position (0 = left) (default: 0)
    y = Y-position (0 = top)  (default: 0)
  
  eg.  hp_bar  = g15.AddProgressBar ("filled", 100, 8, 50, 0) 
  
SetAsForeground - brings that page on the LCD screen to the front or back.

  eg. g15.SetAsForeground (true)  -- make foreground

ButtonTriggered - returns true if the corresponding button is triggered

  eg. print (g15.ButtonTriggered (2))
  
ButtonReleased - returns true if the corresponding button is released

  eg. print (g15.ButtonReleased (3))
 
ButtonIsPressed - returns true if the corresponding button is pressed right now

  eg. print (g15.ButtonIsPressed (4))
  
TEXT METHODS

Once you have created a text object with g15.AddText you can do the following things to it:

set - set the text

  eg. hp_text:set ("Your health is low")
  
  Note the colon after the userdata, which makes it supply the userdata itself as the first argument (the "self" parameter).
  
visible - make visible or invisible

  eg. hp_text:visible (true)  -- make visible
  
PROGRESS BAR METHODS

Once you have created a progress bar object with g15.AddProgressBar you can do the following things to it:

percent - set the percentage filled

  eg. hp_bar:percent (45)  -- make 45% filled
  
  Note the colon after the userdata, which makes it supply the userdata itself as the first argument (the "self" parameter).
  
  If the argument is outside the range 0 to 100 it is forced into that range.
  
visible - make visible or invisible

  eg. hp_bar:visible (false)  -- make invisible
    
  
NOTES

The LCD screen size currently is 160 x 43 pixels.

  
LICENSE AGREEMENT

Copyright  2006 Nick Gammon.

Permission is hereby granted, free of charge, to any person obtaining a copy 
of this software and associated documentation files (the "Software"), to deal 
in the Software without restriction, including without limitation the rights 
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
copies of the Software, and to permit persons to whom the Software 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 Software.    

The software 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 software or the use or other dealings in the 
software. 
