App Object

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.

TIP 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.

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
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback