Lua State Entry Points

Table of Contents

• Background Service Entry Points
  • OnBackgroundStartup
  • OnXmlExport
  • OnOptionsChanged
  • OnPrepareXML
• Window Functions
  • OnCreate
  • OnDraw
  • OnDestroy
  • OnMeasure
  • OnSizeChanged
  • PopulateMenu

Background Service Entry Points

OnBackgroundStartup

Called when all plugins have been parsed and loaded, but before the connection to the server is initiated.

Parameters

none

OnXmlExport

When the BlowTorch core has initiated a settings serialization (saves the settings) this will be called to notify the plugin that it needs to serialize any data that it needs to, and provides an android.xml.XMLSerializer that is set up to be either to the main settings wad or the external plugin's descriptor file.

Parameters

out	android.xml.XmlSerialzer represent the output serializer object.

Note

Please check the documentation of the android java class or the examples for saving data for details of what the body of this function should look like.

OnOptionsChanged

This function is called whenever a plugin defined option has changed through the user activating the options menu UI.

Parameters

key	string the key value of the option that changed
value	string the new value of the option

Note

There are a few demonstrations on how to use this function in the button window and chat window plugins.

OnPrepareXML

This function is called during the loading process when scripts attach xml element listeners. These are used in order to parse custom data that is saved in the descriptor file.

Parameters

none

Note

This is not the best way to do this, it came out of a necessity for dealing with legacy button data in the new button plugin. It is advantageous to save custom data in a separate file, and saving it using the Android xml suites is relatively easy using the luajava api.

Window Functions

OnCreate

Called during window creation. After the main script has been loaded and the actual backing android View is created and shown.

Parameters

none

Note

General initialization of code can be done when the script is loaded. But certain graphical subsystems will be unavailable until this callback is called.

OnDraw

This function is called whenever the window is dirty and needs to redraw custom content.

Parameters

canvas

Note

It is difficult to know exactly what needs to be freed for garbage collection, how to do it, and weather or not it worked. A good example is the button window, it has many custom resources and I had run into memory issues with it when closing/opening the window a few times. It may never happen, it may happen after 100 open/close cycles, or 5, but the general trend of running the foreground process out of memory is an immediate termination of the window. So if you are in a case where you are coming back into the appliation after a phone call or web browser and it immediatly exits, this may be the culprit.

OnDestroy

When the foreground process is being terimnated normally; used for memory management (freeing custom bitmaps, data, stuff that needs to be garbage collected).

Parameters

none

Note

It is difficult to know exactly what needs to be freed for garbage collection, how to do it, and wheather or not it worked. See the button window script for an example demonstrating use. The button window has many custom resources and I had run into memory issues with it when closing/opening the window a few times. It may never happen, it may happen after 100 open/close cycles, or 5, but the general trend of running the foreground process out of memory is an immediate termination of the window. So if you are in a case where you are coming back into the BlowTorch after a phone call or web browser session and it immediatly exits, this may be the culprit.

OnMeasure

Whenever the layout hierarchy initiates re-measuring (window hierarchy changed) this function is called, many times. There is much to know about this function. More documentation will come, but the information passed in the variables is called a measure spec. It contains the target dimension and the measurement mode. More information can be found here. <insert link>="">

Parameters

widthspec
heightspec

Returns

width and height, see note

Example

function OnMeasure(wspec,hspec)  
   if(wspec == measurespec_width and hspec == measurespec_height) then return measured_width,measured_height end
   --Note(string.format("measurespecs: %d, %d\n",wspec,hspec))
   measurespec_width = wspec
   measurespec_height = hspec
   measured_width = MeasureSpec:getSize(wspec)
   --local wmode = MeasureSpec:getMode(wspec)
   
   measured_height = MeasureSpec:getSize(hspec)
   --local hmode = MeasureSpec:getMode(hspec)
   
   function test()
      local orientation = view:getParent():getOrientation()
   end
   local ret,err = pcall(test,debug.traceback)
   if(not ret) then
      --there was a problem, but do we care
      --Note("stat widget is relative, width:"..measured_width.." height:"..measured_height.."\n")
      return measured_width,measured_height
   end
   
   
   local orientation = view:getParent():getOrientation()
   if(orientation == LinearLayout.VERTICAL) then
      view:fitFontSize(36)
      view:doFitFontSize(measured_width)
      measured_height = view:getLineSize()*view:getBuffer():getBrokenLineCount()
      
      --Note("stat widget is vertical, width:"..measured_width.." height:"..measured_height.."\n")
      return measured_width,measured_height
   else
      view:setCharacterSizes((measured_height-6)/3,2)
      measured_width = 37*view:measure("a")
      view:fitFontSize(-1)
      measured_height = view:getLineSize()*view:getBuffer():getBrokenLineCount()
      --Note("stat widget is horizontal, width:"..measured_width.." height:"..measured_height.."\n")
      return measured_width,measured_height
   end
   --end
   
   

end
 

Note

This function expects a measured width and height value returned, e.g. return width,height is expected. If it is not supplied the window will not appear.

OnSizeChanged

If the window's size changes this function is called.

Parameters

new	width
new	height
old	width
old	height

Returns

none

Example

function OnSizeChanged(w,h,oldw,oldh)
   Note("Window starting OnSizeChanged()")
   if(w == 0 and h == 0) then
      draw = false
   end
end
 

PopulateMenu

Called during the activity creation process. [I think] Before OnCreate is called, but after the plugin windows have been loaded and the script bodies run.

Parameters

menu	android.menu.Menu that is the menu for the foreground window activity.

Example

menucallback = {}

function menucallback.onMenuItemClick(item)
   Note("menu item clicked")
   
   --this function must return true if it consumes the click event.
   return true
end
menucallback_cb = luajava.createProxy("android.view.MenuItem$OnMenuItemClickListener",menucallback)

 
function PopulateMenu(menu)
   --see android Menu documentation, menu:add() returns an android.menu.MenuItem
   --that can be manipulated to have a drawable (more sample code coming soon)
   --and can be configured for Android 4.0 (ICS)+ features.
   item = menu:add(0,401,401,"Ex Button Sets")
   item:setOnMenuItemClickListener(buttonsetMenuClicked_cb)
end
 

Note

Need some example code. It is necessary to create and attach menu items to the top level menu. This is how the button window script attaches its menu item into the top level list.