---++!! !App Object %TOC{title="Contents:"}% %STARTINCLUDE% ---++ 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. %T% __Sample Code__ <verbatim> 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) </verbatim> ---+++ Member Functions ---++++ !Map3DSystem.App.AppManager.app:new <verbatim> 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, }</verbatim> Create an application from a table. One needs to call AddApp() with the returned app object. * _param_ __o__ : table containing field in Map3DSystem.App.AppManager.app template table. __syntax__ <verbatim>function Map3DSystem.App.AppManager.app:new(o)</verbatim> __parameters__ | *o* | table containing field in Map3DSystem.App.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__ <verbatim>function Map3DSystem.App.AppManager.app:IsHomepageCommand(commandName)</verbatim> __parameters__ | *commandName* | | ---++++ !Map3DSystem.App.AppManager.app:IsNavigationCommand return whether a command name is some predefined command name. __syntax__ <verbatim>function Map3DSystem.App.AppManager.app:IsNavigationCommand(commandName)</verbatim> __parameters__ | *commandName* | | ---++++ !Map3DSystem.App.AppManager.app:IsQuickActionCommand return whether a command name is some predefined command name. __syntax__ <verbatim>function Map3DSystem.App.AppManager.app:IsQuickActionCommand(commandName)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:CallCommand(commandName, params)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:OnRenderBox(mcmlData)</verbatim> __parameters__ | *mcmlData* | | ---++++ !Map3DSystem.App.AppManager.app:Navigate navigate to an application in the current world __syntax__ <verbatim>function Map3DSystem.App.AppManager.app:Navigate()</verbatim> ---++++ !Map3DSystem.App.AppManager.app:GotoHomepage go to the homapage of the application __syntax__ <verbatim>function Map3DSystem.App.AppManager.app:GotoHomepage()</verbatim> ---++++ !Map3DSystem.App.AppManager.app:DoQuickAction do quite action to the world owner __syntax__ <verbatim>function Map3DSystem.App.AppManager.app:DoQuickAction()</verbatim> ---++++ !Map3DSystem.App.AppManager.app:Connect ------------------------------------------------ message and connection functions. ------------------------------------------------ connect to an installed application. * _param_ __connectMode__ : type of Map3DSystem.App.ConnectMode. __syntax__ <verbatim>function Map3DSystem.App.AppManager.app:Connect(connectMode)</verbatim> __parameters__ | *connectMode* | type of Map3DSystem.App.ConnectMode. | ---++++ !Map3DSystem.App.AppManager.app:Disconnect disconnect to an installed application. __syntax__ <verbatim>function Map3DSystem.App.AppManager.app:Disconnect(disconnectMode)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:SendMessage(msg, wndName)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:openfile(filename, mode)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:GetAppDirectory()</verbatim> ---++++ !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__ <verbatim>function Map3DSystem.App.AppManager.app:OpenInWinExplorer(directory, silentmode)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:WriteConfig(name, value)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:ReadConfig(name, defaultValue)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:BeginConfig()</verbatim> ---++++ !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__ <verbatim>function Map3DSystem.App.AppManager.app:EndConfig()</verbatim> __parameters__ | *return* | if saved, otherwise it means that the config file has not changed. | ---++++ !Map3DSystem.App.AppManager.app:SaveConfig save the config file. __syntax__ <verbatim>function Map3DSystem.App.AppManager.app:SaveConfig()</verbatim> ---++++ !Map3DSystem.App.AppManager.app:LoadConfig load the config file from this application's temp directory. The config file is named "config" __syntax__ <verbatim>function Map3DSystem.App.AppManager.app:LoadConfig()</verbatim> ---++++ !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__ <verbatim>function Map3DSystem.App.AppManager.app:SetProfileDefinition(AppProfileDefinition_)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:GetProfileDefinition()</verbatim> ---++++ !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__ <verbatim>function Map3DSystem.App.AppManager.app:ApplyProfileDefinition(raw_profile)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:GetMCML(uid, callbackFunc, cache_policy)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:GetMCMLInMemory(uid)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:SetMCML(uid, profile, callbackFunc)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:SetSettingPage(filepath, SettingPageTitle)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:GetSettingPage()</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:SetHelpPage(filepath, HelpPageTitle)</verbatim> __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__ <verbatim>function Map3DSystem.App.AppManager.app:GetHelpPage()</verbatim> __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. | %STOPINCLUDE%
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r1
|
B
acklinks
|
V
iew topic
|
Ra
w
edit
|
M
ore topic actions
Topic revision: r1 - 2008-02-29
-
LiXizhi
Home
Site map
CCWeb web
HaqiTeen web
Main web
ParaEngine web
TWiki web
Main Web
Users
Groups
Index
Search
Changes
Notifications
RSS Feed
Statistics
导航页WebTopMenu
Preferences
开发指南
Getting Started
ParacraftSDK
NPL
MCML
NPL Reference Manual
美术Mod
Account
Log In
English
简体中文
簡體中文
E
dit
A
ttach
Copyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki?
Send feedback