chris.advancelcd: Functions Types Source  

AdvanceLcd

This module provides the ability to write applets for Logitech LCD devices.

Information
You don't need real hardware to develop applets. Just right-click on the LCD Manager icon in the system tray while holding down Ctrl+Shift to open the extended menu where you can start emulators for both monochrome and color devices.

License
This work is licensed under the Creative Commons Attribution-No Derivative Works 3.0 United States License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nd/3.0/us/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.

Functions Summary

LcdDeInitialize Deinitializes the library.
LcdInitialize Initializes the library.

Types Summary

TLcdApplet Represents an applet that runs on an LCD device.
TLcdException Represents an exception thrown by an AdvanceLcd function.
TLcdFont Represents a font loaded from the system or a file.
TLcdPixmap Represents a pixmap loaded from a file or created programmatically.

Functions

Function LcdDeInitialize:Int()
DescriptionDeinitializes the library.
InformationCalling this function while applets, pixmaps or fonts are still in use may result in undefined behaviour. You should therefore delete all objects with their respective Dispose methods.

Function LcdInitialize:Int()
ReturnsLCD_OK if initialization was successful, otherwise LCD_ERROR.
DescriptionInitializes the library.
InformationYou need to call this function before creating an applet, pixmap or font. If this function does not succeed you should assume that the Logitech software is not installed and therefore disable all LCD-related functionality.

Types

Type TLcdApplet
DescriptionRepresents an applet that runs on an LCD device.
Methods Summary
Active Checks if the applet is active.
ButtonState Determines the button status.
Clear Deletes the content of the current render target.
ConfigState Determines the configuration status.
Dispose Deletes the applet.
DrawLine Draws a line.
DrawOval Draws an oval.
DrawPixmap Draws a pixmap.
DrawPixmapRect Draws a rectangular area of a pixmap.
DrawRect Draws a rectangle.
DrawText Draws a text string.
EnableAntiAlias Enables or disables anti-aliasing.
Enabled Checks if the applet is currently enabled.
Init Creates a new applet.
Opened Checks if the applet is opened on the currently selected device.
SelectDevice Determines the target of subsequent, device-specific operations.
SetColor Sets the current drawing color.
SetEventHandler Sets the event handler for configuration and button events.
SetFont Sets the current font.
SetLineWidth Sets the current line width.
SetPriority Sets the applets' priority and foreground status.
SetRotation Sets the current rotation.
SetTarget Sets the current render target.
StringHeight Calculates the height of a string.
StringWidth Calculates the width of a string.
Update Shows the content of the back-buffer render target on the LCD.
WaitActivation Waits until the applet gets activated.
Method Active()
ReturnsTrue if the applet is both enabled and opened, otherwise False or LCD_DEVICE_INVALID if the LCD Manager is no longer avaliable.
DescriptionChecks if the applet is active.
InformationYou should suspend rendering until the applet is active. You can also use WaitActivation to block the calling thread until the applet gets activated.

[This method is device-specific.]

Method ButtonState(button:Int)
ReturnsTrue if button is currently pressed, otherwise False.
DescriptionDetermines the button status.
InformationYou can also use SetEventHandler for asynchronous event handling. See constants.bmx for valid button identifiers.

[This method is device-specific.]

Method Clear(color:Int)
DescriptionDeletes the content of the current render target.
InformationParameter color specifies the color in RGB format. Note that any alpha component of the color will be ignored.

[This method is device-specific.]

Method ConfigState()
ReturnsTrue if the user pressed the 'Configure...' button in the LCD Manager since the last call of this method, otherwise False.
DescriptionDetermines the configuration status.
InformationYou can also use SetEventHandler for asynchronous event handling.
Method Dispose()
DescriptionDeletes the applet.
InformationYou should delete all applets before you call LcdDeInitialize.
Method DrawLine(x1:Int, y1:Int, x2:Int, y2:Int)
DescriptionDraws a line.
Information[This method is device-specific.]
Method DrawOval(x:Int, y:Int, width:Int, height:Int, fill:Int = True)
DescriptionDraws an oval.
InformationSet fill to False in order to draw only the outline of the oval.

[This method is device-specific.]

Method DrawPixmap(pixmap:TLcdPixmap, x:Int, y:Int, frame:Int = 0)
DescriptionDraws a pixmap.
InformationParameter frame specifies the frame number if the pixmap was created with the TLcdPixmap.FromAnimFile method.

[This method is device-specific.]

Method DrawPixmapRect(pixmap:TLcdPixmap, x:Int, y:Int, sx:Int, sy:Int, width:Int, height:Int, frame:Int = 0)
DescriptionDraws a rectangular area of a pixmap.
InformationParameters sx, sy, width and height specify the source rectangle of pixmap to be drawn.

[This method is device-specific.]

Method DrawRect(x:Int, y:Int, width:Int, height:Int, fill:Int = True)
DescriptionDraws a rectangle.
InformationSet fill to False in order to draw only the outline of the rectangle.

[This method is device-specific.]

Method DrawText(text:String, x:Int, y:Int)
DescriptionDraws a text string.
Information[This method is device-specific.]
Method EnableAntiAlias(enable:Int)
DescriptionEnables or disables anti-aliasing.
InformationNote that anti-aliasing is only avaliable for color devices.

[This method is device-specific.]

Method Enabled()
ReturnsTrue if the applet is enabled in the LCD Manager, otherwise False.
DescriptionChecks if the applet is currently enabled.
Method Init:TLcdApplet(name:String, devices:Int, configurable:Int, autostart:Int)
DescriptionCreates a new applet.
InformationParameter devices specifies the device types and can be a combination of the following values.

Device typeDescription
LCD_DEVICE_MONOSupport for monochrome displays (G13, G15 and Z-10)
LCD_DEVICE_COLORSupport for color displays (G19)

If the applet supports both device types, all information (e.g. current color, font, render target, etc.) is stored separately for each device. Use the SelectDevice method to select the target device for all subsequent device-specific operations. Methods that affect only the current device are marked as [device-specific] in this documentation.

If configurable is True, the 'Configure...' button in the LCD Manager will be enabled and the applet will receive an LCD_EVENT_CONFIGURE event through its event handler when the user clicks on in. If autostart is True, the applet can automatically be launched by the LCD Manager, otherwise the user has to start it manually.

Throws a TLcdException if the applet could not be created. You should delete the applet with its Dispose method if it is no longer needed and before you call LcdDeInitialize.

Method Opened()
ReturnsTrue if the applet is opened on the device, otherwise False.
DescriptionChecks if the applet is opened on the currently selected device.
InformationUse SelectDevice to specify the current device.

[This method is device-specific.]

Method SelectDevice(device:Int)
DescriptionDetermines the target of subsequent, device-specific operations.
InformationYou only need to call this method if the applet supports both monochrome and color devices. If only one device type is supported the device will be selected automatically.
Method SetColor(color:Int)
DescriptionSets the current drawing color.
InformationParameter color specifies the color in RGB format. Note that any alpha component of the color will be ignored. You can also use the following color constants for monochrome displays.

ConstantDescription
LCD_COLOR_VISIBLEMakes pixels visible (similar to white on color displays).
LCD_COLOR_INVISIBLEMakes pixels invisible (similar to black on color displays).

The default color is white or LCD_COLOR_VISIBLE.

[This method is device-specific.]

Method SetEventHandler(eventhandler:Int(sender:TLcdApplet, event:Int, data:Int))
DescriptionSets the event handler for configuration and button events.
InformationThe event type is indicated by the event parameter which can be one of the following values.

Event typeDescription
LCD_EVENT_CONFIGUREThe user pressed the 'Configure...' button in the LCD Manager.
LCD_EVENT_BUTTONThe user pressed or released a soft button. Parameter data contains a bitmask of buttons. See constants.bmx for valid button identifiers.

Note that the event handler is executed in the context of the LCD Manager and is therefore running in a different thread. You need to build in 'threaded mode' and ensure thread safety if the event handler shares resources with threads in your application.

Method SetFont(font:TLcdFont)
DescriptionSets the current font.
InformationThis method affects all subsequent calls to DrawText.

[This method is device-specific.]

Method SetLineWidth:Float(width:Float)
DescriptionSets the current line width.
InformationThe line width affects the DrawLine method as well as DrawRect and DrawOval if the fill parameter is False.

[This method is device-specific.]

Method SetPriority(priority:Int, foreground:Int)
DescriptionSets the applets' priority and foreground status.
InformationParameter priority can be one of the following values.

LCD_PRIORITY_LOW
LCD_PRIORITY_NORMAL
LCD_PRIORITY_HIGH

Specify True for foreground to stop the LCD Manager from automatically switching between all running applets or False to continue with automatic switching. Note that an applet can easily lose its foreground status when the user manually switches between different applets or returns to the applet menu.

Method SetRotation:Float(rotation:Float, x:Int = 0, y:Int = 0)
DescriptionSets the current rotation.
InformationYou can also specify the center of the rotation using x and y. This method affects all subsequent calls to DrawLine, DrawRect and DrawOval. Note that pixmaps and text cannot be rotated.

[This method is device-specific.]

Method SetTarget(pixmap:TLcdPixmap)
DescriptionSets the current render target.
InformationParameter pixmap specifies the pixmap that will be used as render target. Note that only pixmaps created by TPixmap.Init are suitable render targets. Drawing to pixmaps that are loaded from image files is not supported. Specify Null for pixmap to reset the render target.

[This method is device-specific.]

Method StringHeight(text:String)
DescriptionCalculates the height of a string.
InformationThis method uses the currently selected font to measure the string's height.

[This method is device-specific.]

Method StringWidth(text:String)
DescriptionCalculates the width of a string.
InformationThis method uses the currently selected font to measure the string's width.

[This method is device-specific.]

Method Update(sync:Int = False)
DescriptionShows the content of the back-buffer render target on the LCD.
InformationNote that the applet only becomes visible after the first call to this method. That way you can do applet-specific initializations without the applet being displayed on the device. If sync is True this method will return immediately after sending the buffer data to the LCD Manager, otherwise it will wait until the data is actually displayed which takes about 30 milliseconds or more.

[This method is device-specific.]

Method WaitActivation()
ReturnsThe devices that are currently active or LCD_DEVICE_INVALID if the LCD Manager is no longer avaliable.
DescriptionWaits until the applet gets activated.
InformationIf the return value is LCD_DEVICE_INVALID the connection to the LCD Manager is lost and cannot be restored. In this case, the applet should stop all of its LCD-related functionality or exit.

Type TLcdException Extends TBlitzException
DescriptionRepresents an exception thrown by an AdvanceLcd function.

Type TLcdFont
DescriptionRepresents a font loaded from the system or a file.
Methods Summary
Dispose Deletes the font.
Init Loads a font from the system or a font file.
Method Dispose()
DescriptionDeletes the font.
InformationYou should delete all fonts before you call LcdDeInitialize.
Method Init:TLcdFont(family:String, height:Int, flags:Int = LCD_FONT_DEFAULT, file:String = Null)
DescriptionLoads a font from the system or a font file.
InformationThe font is loaded from the system by default. If you want to load it from a TTF or OTF file, specify the relative path and filename for parameter file.

Parameter flags can be LCD_FONT_DEFAULT or a combination of the following values.

LCD_FONT_BOLD
LCD_FONT_ITALIC
LCD_FONT_UNDERLINE

Throws a TLcdException if the font could not be loaded. You should delete the font with its Dispose method if it is no longer needed and before you call LcdDeInitialize.


Type TLcdPixmap
DescriptionRepresents a pixmap loaded from a file or created programmatically.
Methods Summary
Dispose Deletes the pixmap.
FromAnimFile Loads an animated pixmap from an image file.
FromFile Loads a pixmap from an image file.
Height Returns the height of the pixmap.
Init Creates a new render target pixmap.
Width Returns the width of the pixmap.
Method Dispose()
DescriptionDeletes the pixmap.
InformationYou should delete all pixmaps before you call LcdDeInitialize.
Method FromAnimFile:TLcdPixmap(file:String, framewidth:Int, frameheight:Int, frames:Int)
DescriptionLoads an animated pixmap from an image file.
InformationSupported file formats are PNG, JPEG, BMP, TIFF, GIF.

Parameters framewidth and frameheight indicate the size of a single frame in the pixmap. The pixmap has to be framewidth * frame pixels wide and frameheight pixels high, because the size of all frames has to be equal.

Throws a TLcdException if the pixmap could not be loaded. You should delete the pixmap with its Dispose method if it is no longer needed and before you call LcdDeInitialize.

Method FromFile:TLcdPixmap(file:String)
DescriptionLoads a pixmap from an image file.
InformationSupported file formats are PNG, JPEG, BMP, TIFF and GIF.

Throws a TLcdException if the pixmap could not be loaded. You should delete the pixmap with its Dispose method if it is no longer needed and before you call LcdDeInitialize.

Method Height()
DescriptionReturns the height of the pixmap.
Method Init:TLcdPixmap(width:Int, height:Int, device:Int)
DescriptionCreates a new render target pixmap.
InformationParameter device indicates the device type of the pixmap. You should use the pixmap only with the device type that it was created for. See TLcdApplet.Init for valid device types. Throws a TLcdException if the pixmap could not be created. You should delete the pixmap with its Dispose method if it is no longer needed and before you call LcdDeInitialize.
Method Width()
DescriptionReturns the width of the pixmap.