AppObject < Main

App Object

Contents:

the app object asscoiated with each application.
- Description
- Member Functions

the app object asscoiated with each application.

Title	the app object asscoiated with each application.
Author(s)	LiXizhi
Date	2008/1/1
File	script/kids/3DMapSystemApp/app.lua

Description

Only included by AppManager. the app object contains an variety of methods, such as commands, app IO, app preferences functions etc.

Sample Code

NPL.load("(gl)script/kids/3DMapSystemApp/app.lua");
-- to get the app object of an given application, use 
local app = Map3DSystem.App.AppManager.GetApp(app_key)

Member Functions

Map3DSystem.App.AppManager.app:new

the app template
Map3DSystem.App.AppManager.app = {
------------------------------
-- following are data from registration database
------------------------------
-- string of app_key.
app_key = nil,
-- name
name = "unnamed",
-- description.
description = "application does not provide a description",
-- type of Map3DSystem.App.AppCategory
category = nil,
-- version can be nil or string of format "XX.XX.XX"
version = nil, -- "1.0.0",
-- an onload script. This is usually where the app's callbackfunction must be defined.
onloadscript = nil,
-- string name of the application callback function, such as "MyCompany.MyApp.MSGProc"
callbackfunction = nil,
-- default language
lang = "enUS",
-- nil or array containing local path of zip packages, such as {"Apps/Map_script_v1.zip", "Apps/Map_model_v1.zip"}
packageList = {},
-- boolean: whether this application is added by the local user. Some application is loaded by world dependency.
UserAdded = nil,
-- url. this is optional
url = nil,
-- an application profile box definition table, data fields not defined in this table is stripped by self:GetMCML function.
-- if this is nil, the MCML for the application will be returned by self:GetMCML() unchanged.
AppProfileDefinition = nil,
------------------------------
-- following are data set or get during application OnConnection message event.
------------------------------
-- whether this application is Loaded. see Map3DSystem.App.AppManager.ConnectionStatus: This parameter is automatically set by application manager.
ConnectionStatus = nil,
-- about text of this application
about = nil,
-- default icon path of the application
icon = nil,
-- boolean: whether the home icon button should be hidden by default.
HideHomeButton = nil,
-- text to be displayed next to in the homepage command.
HomeButtonText = nil,
-- boolean: whether this application needs a navigation link around the in-game mini-map.
HasNavigation = nil,
-- text to be displayed near the navigation button. This is usually tooltip.
NavigationButtonText = nil,
-- boolean: whether this application has quick action below a user profile.
HasQuickAction = nil,
-- text to be displayed in the quick action link command.
QuickActionText = nil,
-- the setting page(MCML) url, it is usually called setting.html in the same folder of onloadscript
SettingPage = nil,
-- text to be displayed on title of the setting page. if nil, the self.name is used.
SettingPageTitle = nil,
-- the Help page(MCML) url, it is usually called Help.html in the same folder of onloadscript
HelpPage = nil,
-- text to be displayed on title of the Help page. if nil, the self.name is used.
HelpPageTitle = nil,

------------------------------
-- following are privacy settings from the current user's profile: user can change them for each application.
------------------------------
-- do not allow this application to contact me via email
DenyEmail = nil,
-- only me and my friends can see profile data of this application. i.e. Strangers are denied from viewing.
DenyGuest = nil,
-- Deny profile action feed
DenyActionFeed = nil,
-- do not allow this application to show a homepage button in my application list on the mainmenu
DenyHomeButton = nil,
-- do not allow this application to show a quick action link under any profile.
DenyQuickAction = nil,
}

Create an application from a table. One needs to call AddApp() with the returned app object.

param o : table containing field in AppManager.app template table.

syntax

function Map3DSystem.App.AppManager.app:new(o)

parameters

o	table containing field in AppManager.app template table.

Map3DSystem.App.AppManager.app:IsHomepageCommand

application commands: prefined commands and developer defined commands

return whether a command name is some predefined command name.

syntax

function Map3DSystem.App.AppManager.app:IsHomepageCommand(commandName)

parameters

commandName

Map3DSystem.App.AppManager.app:IsNavigationCommand

return whether a command name is some predefined command name.

syntax

function Map3DSystem.App.AppManager.app:IsNavigationCommand(commandName)

parameters

commandName

Map3DSystem.App.AppManager.app:IsQuickActionCommand

return whether a command name is some predefined command name.

syntax

function Map3DSystem.App.AppManager.app:IsQuickActionCommand(commandName)

parameters

commandName

Map3DSystem.App.AppManager.app:CallCommand

execute a named command of this application. It will first query status and then call exec

param commandName : command name string. It can also be an internal name that is not added to Map3DSystem.App.Commands
param params : optional parameters
return __ : the msg is returned. msg.status contains the returned command status, other fields may contain optional data returned by the commands. in most cases, one can ignore the return message of the command.

syntax

function Map3DSystem.App.AppManager.app:CallCommand(commandName, params)

parameters

commandName	command name string. It can also be an internal name that is not added to Map3DSystem.App.Commands
params

| return | the msg is returned. msg.status contains the returned command status, other fields may contain optional data returned by the commands. in most cases, one can ignore the return message of the command. |

Map3DSystem.App.AppManager.app:OnRenderBox

render the application box in 3D using the mcml data table.

syntax

function Map3DSystem.App.AppManager.app:OnRenderBox(mcmlData)

parameters

mcmlData

Map3DSystem.App.AppManager.app:Navigate

navigate to an application in the current world

syntax

function Map3DSystem.App.AppManager.app:Navigate()

Map3DSystem.App.AppManager.app:GotoHomepage

go to the homapage of the application

syntax

function Map3DSystem.App.AppManager.app:GotoHomepage()

Map3DSystem.App.AppManager.app:DoQuickAction

do quite action to the world owner

syntax

function Map3DSystem.App.AppManager.app:DoQuickAction()

Map3DSystem.App.AppManager.app:Connect

message and connection functions.

connect to an installed application.

param connectMode : type of ConnectMode.

syntax

function Map3DSystem.App.AppManager.app:Connect(connectMode)

parameters

connectMode	type of ConnectMode.

Map3DSystem.App.AppManager.app:Disconnect

disconnect to an installed application.

syntax

function Map3DSystem.App.AppManager.app:Disconnect(disconnectMode)

parameters

disconnectMode

Map3DSystem.App.AppManager.app:SendMessage

send a message to the main window of a given application

param AppName : name of the application.
param msg : msg to be sent.
param wndName : if nil, it is sent to the default "main" window of the app. Otherwise it can be a sub window name created by the app.

syntax

function Map3DSystem.App.AppManager.app:SendMessage(msg, wndName)

parameters

msg
wndName	if nil, it is sent to the default "main" window of the app. Otherwise it can be a sub window name created by the app.

Map3DSystem.App.AppManager.app:openfile

IO functions

Open or create a file under the application directory.

return ParaFileObject : e.g. local file = app:openfile("test.txt", "w");

syntax

function Map3DSystem.App.AppManager.app:openfile(filename, mode)

parameters

filename
mode
return	e.g. local file = app:openfile("test.txt", "w");

Map3DSystem.App.AppManager.app:GetAppDirectory

get the application directory. it ends with '/'. the directory may not exist. but it will always return a path string.

syntax

function Map3DSystem.App.AppManager.app:GetAppDirectory()

Map3DSystem.App.AppManager.app:OpenInWinExplorer

open directory using external windows browser (windows explorer)

param directory : if nil, it will be the default application directory. e.g. "screenshot/"
param silentmode : if true, NO UI is shown.

syntax

function Map3DSystem.App.AppManager.app:OpenInWinExplorer(directory, silentmode)

parameters

directory	if nil, it will be the default application directory. e.g. "screenshot/"
silentmode

Map3DSystem.App.AppManager.app:WriteConfig

application configuration functions configuration can contain any name value pairs, and is stored locally on the temp application directory. the configuration file is usually empty on a newly installed application.

set a name, value pair to the configuration file. it saves immediately to file unless this is called after BeginConfig() it will only save if value is different with the one is the config. Note: attention should be pay if value is a table, u need to make a commonlib.copy() of the returned object in ReadConfig() otherwise the WriteConfig will not save to config, since the compare function will always be true.

param name : string name of the configuration field.
param value : can be any valid npl value. if it is a table, it must not contain recursive references.
return true : if change is made

syntax

function Map3DSystem.App.AppManager.app:WriteConfig(name, value)

parameters

name	string name of the configuration field.
value
return	if change is made

Map3DSystem.App.AppManager.app:ReadConfig

get a configuration field name,

param name : string name of the configuration field.
param defaultValue : nil or default value.
return __ : the field value is returned. If it is a table, the table reference is returned

syntax

function Map3DSystem.App.AppManager.app:ReadConfig(name, defaultValue)

parameters

name	string name of the configuration field.
defaultValue
return	the field value is returned. If it is a table, the table reference is returned

Map3DSystem.App.AppManager.app:BeginConfig

in case one wants to batch SetConfig without writing to disk file multiple times. Just make multiple WriteConfig() calls between BeginConfig() and EndConfig() pairs.

syntax

function Map3DSystem.App.AppManager.app:BeginConfig()

Map3DSystem.App.AppManager.app:EndConfig

in case one wants to batch SetConfig without writing to disk file multiple times. Just make multiple WriteConfig() calls between BeginConfig() and EndConfig() pairs.

return true : if saved, otherwise it means that the config file has not changed.

syntax

function Map3DSystem.App.AppManager.app:EndConfig()

parameters

return	if saved, otherwise it means that the config file has not changed.

Map3DSystem.App.AppManager.app:SaveConfig

save the config file.

syntax

function Map3DSystem.App.AppManager.app:SaveConfig()

Map3DSystem.App.AppManager.app:LoadConfig

load the config file from this application's temp directory. The config file is named "config"

syntax

function Map3DSystem.App.AppManager.app:LoadConfig()

Map3DSystem.App.AppManager.app:SetProfileDefinition

profile functions

Set an application profile box definition table. Data fields not defined in this table is stripped by self:GetMCML function. if this is nil, the MCML for the application will be returned by self:GetMCML() unchanged. the reason to use profile definition is that when an application changes the profile box format (data layout), it ensures that old stored profile fields are automatically cleared unpon next get call.

param AppProfileDefinition :_: each data member in definition file can be another table definition or true, 0, 1, or 2. true or 0 means that it is optional. 1 means that it is menditory. array or MCML (XML) node is always optional. e.g. app:SetProfileDefinition({version=true, photopath=true, profile = true})

syntax

function Map3DSystem.App.AppManager.app:SetProfileDefinition(AppProfileDefinition_)

parameters

| AppProfileDefinition | _: each data member in definition file can be another table definition or true, 0, 1, or 2. true or 0 means that it is optional. 1 means that it is menditory. array or MCML (XML) node is always optional. e.g. app:SetProfileDefinition({version=true, photopath=true, profile = true}) |

Map3DSystem.App.AppManager.app:GetProfileDefinition

get the current profile definition. if there is non definition, it will return nil.

syntax

function Map3DSystem.App.AppManager.app:GetProfileDefinition()

Map3DSystem.App.AppManager.app:ApplyProfileDefinition

apply the profile definition to the raw profile table. if raw_profile contains fields that does not exist in the current profile's definition file, that field is removed from the raw_profile the reason to apply profile definition is that when an application changes the profile box format (data layout), it ensures that old profile storage fields are automatically cleared unpon next get call. Hence, when an application upgrades, old formats will be discarded automatically. e.g. app:SetProfileDefinition({version=true, photopath=true, profile = true}) local profile = app:ApplyProfileDefinition({version=1, photopath="ABC", profile = {name="pe:profile"}, unkownfield = {}}), where unkownfield will be removed

param raw :_profile: to which the raw profile that the current profile definition is applied. if this is nil, raw_profile will be unchanged
return __ : the raw_profile is returned for convinence.

syntax

function Map3DSystem.App.AppManager.app:ApplyProfileDefinition(raw_profile)

parameters

raw	_profile: to which the raw profile that the current profile definition is applied. if this is nil, raw_profile will be unchanged
profile

Map3DSystem.App.AppManager.app:GetMCML

this is the wrapper of Map3DSystem.App.profiles.ProfileManager.GetMCML Gets an app MCML that is currently set for a user's profile. A user MCML profile includes the content for both the profile box. See the MCML documentation for a description of the markup and its role in various contexts.

param uid : for which user to get, if nil, the current user is used
param callbackFunc : nil or function to call whenever the data is ready, function(uid, app_key, bSucceed) end , where uid, app_key are forwarded.
param cache :_policy: nil or a cache policy object, such as Map3DSystem.localserver.CachePolicies["never"]
return return : true if it is fetching data or data is already available. it returns paraworld.errorcode, if web service can not be called at this time, due to error or too many concurrent calls.

syntax

function Map3DSystem.App.AppManager.app:GetMCML(uid, callbackFunc, cache_policy)

parameters

uid	for which user to get, if nil, the current user is used
callbackFunc
cache	_policy: nil or a cache policy object, such as Map3DSystem.localserver.CachePolicies["never"]
policy

Map3DSystem.App.AppManager.app:GetMCMLInMemory

it will return immediately the application's mcml profile data for the user. I assumes that GetMCML or the user profile is already downloaded and available in memory.

syntax

function Map3DSystem.App.AppManager.app:GetMCMLInMemory(uid)

parameters

uid

Map3DSystem.App.AppManager.app:SetMCML

this is the wrapper of Map3DSystem.App.profiles.ProfileManager.SetMCML, except that ApplyProfileDefinition is called prior to saving to remove unnecessary fields. set MCML for a given application of the current user. and it will GetMCML for the same app from server immediately after set is completed. This Get operation ensures that local server is also updated.

param uid : this must be nil and current user is used. In future, we will allow arbitrary id with app signature.
param profile : if this is table. it is serialized to string. If this is nil, the app MCML will be cleared.
param callbackFunc : nil or function to call whenever the data is ready, function(uid, app_key, bSucceed) end , where uid, app_key are forwarded.

syntax

function Map3DSystem.App.AppManager.app:SetMCML(uid, profile, callbackFunc)

parameters

uid	this must be nil and current user is used. In future, we will allow arbitrary id with app signature.
profile
callbackFunc	nil or function to call whenever the data is ready, function(uid, app_key, bSucceed) end , where uid, app_key are forwarded.

Map3DSystem.App.AppManager.app:SetSettingPage

Misc functions

set the setting page(MCML) url, it is usually called setting.html in the same folder of onloadscript

param filepath :; the file path, it can be relative to root folder, or relative to the same folder of self.onloadscript

syntax

function Map3DSystem.App.AppManager.app:SetSettingPage(filepath, SettingPageTitle)

parameters

filepath	; the file path, it can be relative to root folder, or relative to the same folder of self.onloadscript
SettingPageTitle

Map3DSystem.App.AppManager.app:GetSettingPage

Get the setting page(MCML) url, and title

return __ : two field is returned. the first is nil or page url. The page is always local. the second is page title or nil.

syntax

function Map3DSystem.App.AppManager.app:GetSettingPage()

parameters

return	two field is returned. the first is nil or page url. The page is always local. the second is page title or nil.

Map3DSystem.App.AppManager.app:SetHelpPage

set the Help page(MCML) url, it is usually called Help.html in the same folder of onloadscript

param filepath :; the file path, it can be relative to root folder, or relative to the same folder of self.onloadscript

syntax

function Map3DSystem.App.AppManager.app:SetHelpPage(filepath, HelpPageTitle)

parameters

filepath	; the file path, it can be relative to root folder, or relative to the same folder of self.onloadscript
HelpPageTitle

Map3DSystem.App.AppManager.app:GetHelpPage

Get the Help page(MCML) url, and title

return __ : two field is returned. the first is nil or page url. The page is always local. the second is page title or nil.

syntax

function Map3DSystem.App.AppManager.app:GetHelpPage()

parameters

return	two field is returned. the first is nil or page url. The page is always local. the second is page title or nil.

Topic revision: r1 - 2008-02-29 - LiXizhi