AppTaskBar

Contents:

Application Task Bar for paraworld

Title Application Task Bar for paraworld
Author(s) LiXizhi
Date 2008/5/13
File script/kids/3DMapSystemUI/Desktop/AppTaskBar.lua

Description

App task bar is docked at the bottom of the screen and has four functional area from left to right.
  1. App start icon: It will toggle on/off the application lists at the bottom of the display. When application list is displayed, users can also drag applications to the quick launch bar.
  2. App quick launch bar: Users can quickly switch to a frequently used application exclusive desktop mode. application exclusive desktop mode is a mode where only windows of the given application are shown and application specific toolbars are displayed on the task bar. This allows the applications to make full use of the entire rectangle display area without worrying about UI overlay from other applications' windows. Content is left aligned. overflow toolbar items can be accessed via extension button ">>".
  3. App toolbar: When in an application desktop mode, it displays the application specific toolbar. Application specific toolbar icons are by default displayed with text and an optional icon to help both new and old user to quickly identify the most important tasks relavent to an application. The app toolbar will by default display all application menu items, unless an application explicitly specifies its display content via AddCommand in its APP_ACTIVATE_DESKTOP message handler. The app toolbar is by default a fixed-width (512px) region and centered (or float to the left of quick launch bar). Content is left aligned. overflow toolbar items can be accessed via extension button ">>".
  4. CommonStatusBar: This section on the task bar provides a place to place common icons (functions) that are always shown regardless of the current application desktop. E.g. social content, chat users, mini-feed. Content is right aligned. overflow toolbar items can be accessed via extension button "<<".

TIP Sample Code 

NPL.load("(gl)script/kids/3DMapSystemUI/Desktop/AppTaskBar.lua");
Map3DSystem.UI.AppTaskBar.InitAppTaskBar();
Map3DSystem.UI.AppTaskBar.SendMessage({type = Map3DSystem.UI.AppTaskBar.MSGTYPE.SHOW_TASKBAR, bShow = true});
Map3DSystem.UI.AppTaskBar.SendMessage({type = Map3DSystem.UI.AppTaskBar.MSGTYPE.SWITCH_APP_DESKTOP, appKey = Map3DSystem.App.AppKeys["worlds"]});
--Map3DSystem.UI.AppTaskBar.SendMessage({type = Map3DSystem.UI.AppTaskBar.MSGTYPE.SWITCH_APP_DESKTOP, appKey = Map3DSystem.App.AppKeys["profiles"]});

Member Functions

AppTaskBar.InitAppTaskBar 

 automaticly load the status bar
NPL.load("(gl)script/kids/3DMapSystemUI/Desktop/StatusBar.lua");

 the start app page. 
NPL.load("(gl)script/kids/3DMapSystemUI/Desktop/StartAppPage.lua");

-- attributes


-- the default app to load at start up. 
AppTaskBar.DefaultApp = Map3DSystem.App.AppKeys["MyDesktop"];
 app_key of the current app desktop. 
AppTaskBar.CurrentAppDesktop = AppTaskBar.DefaultApp;
 app list window name
AppTaskBar.AppListName = libName..".applist";

 some theme related things, replace this table to change theme. 
local theme = {
   -- left most start bar background. it just contains the start app button
   StartBar = "Texture/3DMapSystem/Desktop/AppTaskBar.png;0 15 80 49",
   -- the start button on start bar
   StartBarButton = "Texture/3DMapSystem/Desktop/AppTaskBar.png;216 24 40 40",
   -- quick action bar bg
   QuickActionBar = "Texture/3DMapSystem/Desktop/AppTaskBar.png;81 32 58 32:19 0 37 0",
   -- application tool bar bg
   AppToolBar = "Texture/3DMapSystem/Desktop/AppTaskBar.png;140 26 41 38:17 0 17 0",
   -- application toolbar button hover style.
   ToolBarBtnHoverBG = "Texture/3DMapSystem/common/href.png:2 2 2 2";
   -- right most common status bar bg
   CommonStatusBar = "Texture/3DMapSystem/Desktop/AppTaskBar.png;182 32 34 32:31 0 2 0",
   -- The app start page bg. 
   AppStartPage = "Texture/3DMapSystem/Desktop/AppStartPage.png:13 85 13 13",
   -- default application icon if none is provided. 
   DefaultAppIcon = "Texture/3DMapSystem/common/info.png";
   -- whether to play animation to popup application list and fade the background. 
   bUseAnimation = false,
   -- if bUseAnimation is true, this is the background fade animation file 
   BackgroundGreyOutSlowMotionData = "script/kids/3DMapSystemUI/styles/BackgroundGreyOutSlowMotionData.xml",
   -- if bUseAnimation is true, this is the start page popup animation file
   TaskBarAppListPopupMotionData = "script/kids/3DMapSystemUI/styles/TaskBarAppListPopupMotionData.xml",
};

 messge types
AppTaskBar.MSGTYPE = {
   -- toggle on/off the application lists at the bottom of the display. When application list is displayed, users can also drag applications to the quick launch bar. 
   -- msg = {bShow = true, bUseAnim = true}
   SHOW_APP_LIST = 1000,
   -- show/hide the task bar, 
   -- msg = {bShow = true}
   SHOW_TASKBAR = 1001,
   -- switch to an given application exclusive desktop, we can save last screen to buffer for switching back.
   -- msg = {appKey = "XXX", bSaveLastScreen = false, }
   SWITCH_APP_DESKTOP = 1002,
};

 default quick launch bar app_keys, we will only show quick launch icons if their app_key is installed on the target computer. 
AppTaskBar.DefaultQuickLaunchApps = {
   { nLineIndex=1, app_key = Map3DSystem.App.AppKeys["Creator"],},
   { nLineIndex=1, app_key = Map3DSystem.App.AppKeys["MyDesktop"],},
   { nLineIndex=1, app_key = Map3DSystem.App.AppKeys["Env"],},
   { nLineIndex=1, app_key = Map3DSystem.App.AppKeys["CCS"],},
   { nLineIndex=1, app_key = Map3DSystem.App.AppKeys["chat"],},
   --{ nLineIndex=1, app_key = Map3DSystem.App.AppKeys["profiles"],},
   
   { nLineIndex=2, app_key = Map3DSystem.App.AppKeys["profiles"],},
   { nLineIndex=2, app_key = Map3DSystem.App.AppKeys["worlds"],},
   --{ nLineIndex=2, app_key = Map3DSystem.App.AppKeys["EBook"],},
   { nLineIndex=2, app_key = Map3DSystem.App.AppKeys["Blueprint"],},
   { nLineIndex=2, app_key = Map3DSystem.App.AppKeys["screenshot"],},
   { nLineIndex=2, app_key = Map3DSystem.App.AppKeys["Developers"],},
}
;

call this only once at the beginning of the game. init main bar: this does not show the task bar, it just builds the data structure and messaging system.

syntax 

function AppTaskBar.InitAppTaskBar()

AppTaskBar.AddCommand

add a task bar command at given position. the parent folders must be created beforehand, otherwise it will be inserted to the first unfound folder. if there is already an object at the position, the add command will do nothing.

  • param command :; type of Map3DSystem.App.Command, or it can be string of existing command name.
  • param position : this is a tree path string of folder names separated by dot. There are some predefined categories which correspond to the four display sections on the task bar. See following. e.g. "applist.APP_GUID", "quicklaunchbar.APP_GUID", "toolbar.CreateWorld", "statusbar.minifeed". If this is nil, it will be the same as "toolbar." plus the last name of command.name.
  • param posIndex : if position is a item in another folder, this is the index at which to add the item. if nil, it is added to end, if 1 it is the beginning. Please note, for right aligned section(common status bar), the first position is the right most position.
  • return __ : return the command object if added successfully.

syntax 

function AppTaskBar.AddCommand(command, position, posIndex)

parameters

command ; type of Map3DSystem.App.Command, or it can be string of existing command name.
position  
| posIndex | if position is a item in another folder, this is the index at which to add the item. if nil, it is added to end, if 1 it is the beginning. Please note, for right aligned section(common status bar), the first position is the right most position. |

AppTaskBar.GetItemIndex

return a task item index by its position. This function is mosted called before AddMenuCommand to determine where to insert a new command.

  • param position : this is a tree path string of folder names separated by dot. There are some predefined categories which correspond to the four display sections on the task bar. See following. e.g. "applist.APP_GUID", "quicklaunchbar.APP_GUID", "toolbar.CreateWorld", "statusbar.minifeed"
  • return nil : if not found, other the item index integer is returned. please note that the index may change when new items are added later on.

syntax 

function AppTaskBar.GetItemIndex(position)

parameters

| position | this is a tree path string of folder names separated by dot. There are some predefined categories which correspond to the four display sections on the task bar. See following. e.g. "applist.APP_GUID", "quicklaunchbar.APP_GUID", "toolbar.CreateWorld", "statusbar.minifeed" |

AppTaskBar.OnClickCommand

call the task bar command

syntax 

function AppTaskBar.OnClickCommand(treeNode)

parameters

treeNode  

AppTaskBar.SendMessage

send a message to AppTaskBar:main window handler SendMessage({type = AppTaskBar.MSGTYPE.MENU_SHOW});

syntax 

function AppTaskBar.SendMessage(msg)

parameters

msg  

AppTaskBar.MSGProc

AppTaskBar window handler

syntax 

function AppTaskBar.MSGProc(window, msg)

parameters

window  
msg  

AppTaskBar.Show

protected
the alpha value of all task bar backgrounds AppTaskBar.BG_alpha = "220";

show or hide task bar UI

syntax 

function AppTaskBar.Show(bShow)

parameters

bShow  

AppTaskBar.SwitchAppDesktop

switch to a given application exclusive desktop mode. We can optionally save last screen to texture for switching back display. internally it just send APP_DEACTIVATE_DESKTOP message to the old app, and APP_ACTIVATE_DESKTOP message to the new application. The new application is expected to add commands to app toolbar via AddCommand() before the message returns. Note1: The app toolbar will by default display all application menu items, unless an application explicitly specifies its toolbar content inside APP_ACTIVATE_DESKTOP message handler. Note2: The application can change the toolbar content at any time, by calling ClearToolBar(), adding new commands and then calling RefreshToolbar()

  • param appKey : the application key. if key is the same as current, it will refresh anyway. if nil, it will clear desktop(but not refreshing its UI).
  • param bSaveLastScreen : whether saving screen to texture

syntax 

function AppTaskBar.SwitchAppDesktop(appKey, bSaveLastScreen)

parameters

appKey the application key. if key is the same as current, it will refresh anyway. if nil, it will clear desktop(but not refreshing its UI).
bSaveLastScreen  

AppTaskBar.AddAppMenuItemsToToolBar

extract all menu commands related to this application and add them to toolbar. this function can be called to automatically add the menu items to toolbar for the given app.

  • param appKey : it will search the current menu and append all menu items whose application key is appKey to the current app toolbar.

syntax 

function AppTaskBar.AddAppMenuItemsToToolBar(appKey)

parameters

appKey it will search the current menu and append all menu items whose application key is appKey to the current app toolbar.

AppTaskBar.ToggleAppList

toggle on/off the application lists at the bottom of the display. When application list is displayed, users can also drag applications to the quick launch bar.

  • param bShow : toggle on/off the application lists
  • param bUseAnim : true to play a popup animation.
  • param destoryUI :_ID: ui object to destroy. only used when bShow is false.

syntax 

function AppTaskBar.ToggleAppList(bShow, bUseAnim, destoryUI_ID)

parameters

bShow toggle on/off the application lists
bUseAnim  
destoryUI _ID: ui object to destroy. only used when bShow is false.
ID  

AppTaskBar.CancelAppList

toggle off app list

  • param destoryUIID : nil or the id of the UI object to delete

syntax 

function AppTaskBar.CancelAppList(destoryUI_ID)

parameters

destoryUI  
ID  

AppTaskBar.ClearAppList

it simply clear application list causing the next ToggleAppList() method to rebuilt its UI this function is rarely used, unless user has newly installed applications and do not want to restart ParaEngine to see it takes effect.

syntax 

function AppTaskBar.ClearAppList()

AppTaskBar.ClearToolBar

methods
clear the tool bar. The application can change the toolbar content at any time, by adding commands and then calling RefreshToolbar()
  • param ClearToolBar : if true, UI is refreshed.

syntax 

function AppTaskBar.ClearToolBar(bRefreshUI)

parameters

bRefreshUI  

AppTaskBar.RefreshToolbar

refresh application toolbar according to the current toolbar data a toolbar item may contain icon, text or both.

syntax 

function AppTaskBar.RefreshToolbar()

Map3DSystem.UI.AppTaskBar.OnClickToolbar

clicks a toolbar item.

syntax 

function Map3DSystem.UI.AppTaskBar.OnClickToolbar(index)

parameters

index  

AppTaskBar.RefreshQuickLaunchBar

this function is called when quick launch bar is recreated or new item is added to it. TODO: If user made changes to it, remember to save to "MyDesktop" app's config file.

syntax 

function AppTaskBar.RefreshQuickLaunchBar()

AppTaskBar.OnClickQuickLaunchBar

callback

syntax 

function AppTaskBar.OnClickQuickLaunchBar(nLineIndex, index)

parameters

nLineIndex  
index  

AppTaskBar.AddStatusBarCommand

DEPARACATED ------------ add a status bar item.
  • param command :; type of Map3DSystem.App.Command
  • param priority : number Priority defines the position of the given command in the status bar. Higher priority shown on the right. For those items with the same priority, the more recent added has lower priority which shows on the left. Here are some default priorities for official applications:
    Feed
    10, ChatWindow: 3, OfficalAppStatus: 8, DefaultPriority: 5

syntax 

function AppTaskBar.AddStatusBarCommand(command, priority)

parameters

command ; type of Map3DSystem.App.Command
priority  

AppTaskBar.RemoveStatusBarCommand

remove command from the status bar

  • param command : the command to be removed from the status bar

syntax 

function AppTaskBar.RemoveStatusBarCommand(command)

parameters

command the command to be removed from the status bar

AppTaskBar.ClearStatusBarCommands

remove all commands in status bar

syntax 

function AppTaskBar.ClearStatusBarCommands()

AppTaskBar.RefreshStatusBar

DEPARACATED ------------ this function is called when status bar is recreated or new item is added to it.

syntax 

function AppTaskBar.RefreshStatusBar()

AppTaskBar.ShowQuickLaunchExtensionMenu

bring up a context menu for selecting extension items.

syntax 

function AppTaskBar.ShowQuickLaunchExtensionMenu(nLineIndex)

parameters

nLineIndex  

AppTaskBar.ShowToolbarExtensionMenu

bring up a context menu for selecting extension items.

syntax 

function AppTaskBar.ShowToolbarExtensionMenu()

AppTaskBar.ShowStatusBarExtensionMenu

bring up a context menu for selecting extension items.

syntax 

function AppTaskBar.ShowStatusBarExtensionMenu()
Topic revision: r1 - 2008-02-29 - LiXizhi
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 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