Changeset 7399 for code/branches/notifications/data/gui/scripts

Timestamp:

Sep 10, 2010, 11:17:02 PM (14 years ago)

Author:

dafrick

Message:

Some cleanup and documenting.
After some more extensive testing it seems to work, the code looks ok as well…

File:

• code/branches/notifications/data/gui/scripts/NotificationLayer.lua (modified) (32 diffs)

code/branches/notifications/data/gui/scripts/NotificationLayer.lua

@@ -8 +8 @@
 P.sampleWindow = nil
 
+-- Loads the queues from the NotificationManager and creates the sample window, that is used to measure the width various strings need.
 function P.onLoad()
     orxonox.NotificationManager:getInstance():loadQueues()
@@ -13 +14 @@
 end
 
+-- Creates a queue in the GUI.
 function P.createQueue(name, size)
     local root = winMgr:getWindow("orxonox/NotificationLayer/Root")
     local queue = winMgr:createWindow("MenuWidgets/Listbox", "orxonox/NotificationLayer/Root/Queue/" .. name)
-    queue:setProperty("BackgroundColor", "00FFFFFF")
+    queue:setProperty("BackgroundColor", "00FFFFFF") -- Set background to be fully transparent.
     root:addChildWindow(queue)
 
@@ -31 +33 @@
 
     P.queueList[name] = queueTuple -- name access
-    P.setVisible(queueTuple, false)
-end
-
-function P.removeQueue(name)
-    local queue = P.queueList[name]
+    P.setVisible(queueTuple, false) -- Set the queue to invisible as long as there are no notifications in it.
+end
+
+-- Removes a queue from the GUI.
+function P.removeQueue(queueName)
+    local queue = P.queueList[queueName]
 
     if queue ~= nil then
         winMgr:destroyWindow(queue.window)
     end
-    P.queueList[name] = nil
-end
-
+    P.queueList[queueName] = nil
+end
+
+-- Pushes an input notification to the input queue. 
 function P.pushNotification(queueName, notification)
     local queue = P.queueList[queueName]
     if queue == nil then
-        cout(0, "0Queue is nil! " .. queueName)
         return
     end
     item = CEGUI.createListboxTextItem(notification)
     local listbox = CEGUI.toListbox(queue.window)
+    -- Add the item to the top of the listbox.
     if listbox:getItemCount() == 0 then
         listbox:addItem(item)
@@ -57 +61 @@
     end
 
+    -- If the queue has been invisible, set it to visible.
     if queue.visible == false then
         P.setVisible(queue, true)
@@ -62 +67 @@
 end
 
+-- Pops the least recently added notification from the queue.
 function P.popNotification(queueName)
     local queue = P.queueList[queueName]
     if queue == nil then
-        cout(0, "1Queue is nil! " .. queueName)
         return
     end
     local listbox = CEGUI.toListbox(queue.window)
+    -- Removes the item from the bottom of the listbox.
     listbox:removeItem(listbox:getListboxItemFromIndex(listbox:getItemCount()-1))
 
+    -- Sets the queue to invisible if there are no more notifications in it.
     if listbox:getItemCount() == 0 then
         P.setVisible(queue, false)
@@ -76 +83 @@
 end
 
+-- Removes a notification at a given index from the queue.
 function P.removeNotification(queueName, index)
     local queue = P.queueList[queueName]
     if queue == nil then
-        cout(0, "2Queue is nil! " .. queueName)
         return
     end
     local listbox = CEGUI.toListbox(queue.window)
+    -- Removes the item.
     listbox:removeItem(listbox:getListboxItemFromIndex(tonumber(index)))
 
+    -- Sets the queue to invisible if there are no more notifications in it.
     if listbox:getItemCount() == 0 then
         P.setVisible(queue, false)
@@ -90 +99 @@
 end
 
-function P.clearQueue(name)
-    local queue = P.queueList[name]
-    if queue == nil then
-        cout(0, "3Queue is nil! " .. name)
+-- Clears the queue. Removes all notifications from it.
+function P.clearQueue(queueName)
+    local queue = P.queueList[queueName]
+    if queue == nil then
         return
     end
@@ -99 +108 @@
     CEGUI.toListbox(queue.window):resetList()
 
+    -- Sets the queue to invisible.
     P.setVisible(queue, false)
 end
 
-function P.changeSize(name, size)
-    local queue = P.queueList[name]
-    if queue == nil then
-        cout(0, "5Queue is nil! " .. name)
-        return
-    end
-    queue.window:setHeight(CEGUI.UDim(0, P.queueHeightHelper(queue.window, size)))
-end
-
+-- Sets the visibility of the queue.
 function P.setVisible(queue, visible)
     if queue == nil then
-        cout(0, "6Queue is nil! " .. queue.name)
         return
     end
@@ -120 +121 @@
 end
 
+-- Enter the edit mode of the notification layer.
 function P.enterEditMode()
     P.editMode = true
@@ -139 +141 @@
     vertOffset = 0
     horzOffset = 0
+    -- Line to be able to create a new queue.
     local newQueueTitle = winMgr:createWindow("MenuWidgets/StaticText", "orxonox/NotificationLayer/Root/EditMode/ControlWindow/NewQueueTitle")
     newQueueTitle:setText("Create a new NotificationQueue:")
@@ -165 +168 @@
 
     horzOffset = 0
+    -- Button to leave the edit mode.
     local leave = winMgr:createWindow("MenuWidgets/Button", "orxonox/NotificationLayer/Root/EditMode/ControlWindow/LeaveEditModeButton")
     leave:setText("leave Edit Mode")
@@ -180 +184 @@
         if v ~= nil then
             local queue = P.queueList[k]
-            root:removeChildWindow(queue.window)
-            
-            local window = P.createQueueEditFrame(queue.name)
-            window:setArea(queue.window:getArea())
-            
-            queue.edit = window
+            -- Remove the window that displays the queue from the root window such that it is no longer displayed.
+            root:removeChildWindow(v.window)
+
+            -- Create the frame window, with options to edit the queue, that is displayed instead of the queue.
+            local window = P.createQueueEditFrame(v.name)
+            window:setArea(v.window:getArea()) -- Set the frame window size and position to the same as the queue.
+
+            v.edit = window
         end
     end
 end
 
-function P.createQueueEditFrame(name)
+-- Helper function. Creates a frame for the input queue.
+function P.createQueueEditFrame(queueName)
     local root = winMgr:getWindow("orxonox/NotificationLayer/Root")
-    window = winMgr:createWindow("MenuWidgets/FrameWindow", "orxonox/NotificationLayer/Root/EditMode/" .. name)
+
+    window = winMgr:createWindow("MenuWidgets/FrameWindow", "orxonox/NotificationLayer/Root/EditMode/" .. queueName)
     local frame = tolua.cast(window, "CEGUI::FrameWindow")
     frame:setCloseButtonEnabled(true)
     orxonox.GUIManager:subscribeEventHelper(frame, "CloseClicked", P.name .. ".closeQueue_clicked")
-    frame:setText("NotificationQueue \"" .. name .. "\"")
+    frame:setText("NotificationQueue \"" .. queueName .. "\"")
     root:addChildWindow(window)
-    local pane = winMgr:createWindow("MenuWidgets/ScrollablePane", "orxonox/NotificationLayer/Root/EditMode/" .. name .. "/ScrollingPane")
+    local pane = winMgr:createWindow("MenuWidgets/ScrollablePane", "orxonox/NotificationLayer/Root/EditMode/" .. queueName .. "/ScrollingPane")
     pane:setSize(CEGUI.UVector2(CEGUI.UDim(1,-20), CEGUI.UDim(1,-30)))
     pane:setPosition(CEGUI.UVector2(CEGUI.UDim(0, 10), CEGUI.UDim(0, 26)))
@@ -206 +214 @@
     local vertOffset = 0
 
-    local targetsTitle = winMgr:createWindow("MenuWidgets/StaticText", "orxonox/NotificationLayer/Root/EditMode/" .. name .. "/TargetsTitle")
+    -- The line that lets you edit the targets of the queue.
+    local targetsTitle = winMgr:createWindow("MenuWidgets/StaticText", "orxonox/NotificationLayer/Root/EditMode/" .. queueName .. "/TargetsTitle")
     targetsTitle:setText("Targets:")
     local size = getMinTextSize(targetsTitle)
@@ -214 +223 @@
     pane:addChildWindow(targetsTitle)
     horzOffset = horzOffset + size[2] + 5
-    local targets = winMgr:createWindow("MenuWidgets/Editbox", "orxonox/NotificationLayer/Root/EditMode/" .. name .. "/Targets")
+    local targets = winMgr:createWindow("MenuWidgets/Editbox", "orxonox/NotificationLayer/Root/EditMode/" .. queueName .. "/Targets")
     targets:setProperty("ReadOnly", "set:False")
-    local targetsText = orxonox.NotificationManager:getInstance():getQueue(name):getTargets()
+    local targetsText = orxonox.NotificationManager:getInstance():getQueue(queueName):getTargets()
     targets:setText(targetsText)
     P.sampleWindow:setText(targetsText)
@@ -224 +233 @@
     horzOffset = horzOffset + size[2]*2+20 + 5
     pane:addChildWindow(targets)
-    local save = winMgr:createWindow("MenuWidgets/Button", "orxonox/NotificationLayer/Root/EditMode/" .. name .. "/Targets/Save")
+    local save = winMgr:createWindow("MenuWidgets/Button", "orxonox/NotificationLayer/Root/EditMode/" .. queueName .. "/Targets/Save")
     save:setText("save")
     P.sampleWindow:setText("save")
@@ -237 +246 @@
 
     horzOffset = 0
-    local sizeTitle = winMgr:createWindow("MenuWidgets/StaticText", "orxonox/NotificationLayer/Root/EditMode/" .. name .. "/SizeTitle")
+    -- The line that lets you edit the size of the queue.
+    local sizeTitle = winMgr:createWindow("MenuWidgets/StaticText", "orxonox/NotificationLayer/Root/EditMode/" .. queueName .. "/SizeTitle")
     sizeTitle:setText("Size:")
     size = getMinTextSize(sizeTitle)
@@ -244 +254 @@
     pane:addChildWindow(sizeTitle)
     horzOffset = horzOffset + size[2] + 5
-    local queueSize = winMgr:createWindow("MenuWidgets/Editbox", "orxonox/NotificationLayer/Root/EditMode/" .. name .. "/Size")
+    local queueSize = winMgr:createWindow("MenuWidgets/Editbox", "orxonox/NotificationLayer/Root/EditMode/" .. queueName .. "/Size")
     queueSize:setProperty("ReadOnly", "set:False")
-    local maxSize = orxonox.NotificationManager:getInstance():getQueue(name):getMaxSize()
+    local maxSize = orxonox.NotificationManager:getInstance():getQueue(queueName):getMaxSize()
     queueSize:setText(maxSize)
     P.sampleWindow:setText(maxSize)
@@ -254 +264 @@
     horzOffset = horzOffset + size[2]*2+20 + 5
     pane:addChildWindow(queueSize)
-    save = winMgr:createWindow("MenuWidgets/Button", "orxonox/NotificationLayer/Root/EditMode/" .. name .. "/Size/Save")
+    save = winMgr:createWindow("MenuWidgets/Button", "orxonox/NotificationLayer/Root/EditMode/" .. queueName .. "/Size/Save")
     save:setText("save")
     P.sampleWindow:setText("save")
@@ -267 +277 @@
 
     horzOffset = 0
-    local displayTimeTitle = winMgr:createWindow("MenuWidgets/StaticText", "orxonox/NotificationLayer/Root/EditMode/" .. name .. "/DisplayTimeTitle")
+    -- The line that lets you edit the display time of the queue.
+    local displayTimeTitle = winMgr:createWindow("MenuWidgets/StaticText", "orxonox/NotificationLayer/Root/EditMode/" .. queueName .. "/DisplayTimeTitle")
     displayTimeTitle:setText("Display time:")
     size = getMinTextSize(displayTimeTitle)
@@ -274 +285 @@
     pane:addChildWindow(displayTimeTitle)
     horzOffset = horzOffset + size[2] + 5
-    local displayTime = winMgr:createWindow("MenuWidgets/Editbox", "orxonox/NotificationLayer/Root/EditMode/" .. name .. "/DisplayTime")
+    local displayTime = winMgr:createWindow("MenuWidgets/Editbox", "orxonox/NotificationLayer/Root/EditMode/" .. queueName .. "/DisplayTime")
     displayTime:setProperty("ReadOnly", "set:False")
-    local time = orxonox.NotificationManager:getInstance():getQueue(name):getDisplayTime()
+    local time = orxonox.NotificationManager:getInstance():getQueue(queueName):getDisplayTime()
     displayTime:setText(time)
     P.sampleWindow:setText(time)
@@ -284 +295 @@
     horzOffset = horzOffset + size[2]*2+20 + 5
     pane:addChildWindow(displayTime)
-    save = winMgr:createWindow("MenuWidgets/Button", "orxonox/NotificationLayer/Root/EditMode/" .. name .. "/DisplayTime/Save")
+    save = winMgr:createWindow("MenuWidgets/Button", "orxonox/NotificationLayer/Root/EditMode/" .. queueName .. "/DisplayTime/Save")
     save:setText("save")
     P.sampleWindow:setText("save")
@@ -299 +310 @@
 end
 
+-- Leave the edit mode.
 function P.leaveEditMode()
     P.editMode = false
@@ -306 +318 @@
     for k,v in pairs(P.queueList) do
         if v ~= nil then
+            -- Add the queue window to the root window to have it displayed again.
             root:addChildWindow(v.window)
+            -- Set the size and position of the queue window to the size and position of the queue edit frame.
             v.window:setArea(v.edit:getArea())
+            -- Destroy the edit frame.
             winMgr:destroyWindow(v.edit)
             v.edit = nil
@@ -317 +332 @@
 end
 
+-- Is called after the sheet has been hidden.
 function P.afterHide()
+    -- If we leave the edit mode we show the sheet again.
     if P.editMode then
         P.leaveEditMode()
@@ -324 +341 @@
 end
 
+-- If the button to save the targets of a queue has been clicked.
 function P. saveTargets_clicked(e)
     local we = CEGUI.toWindowEventArgs(e)
@@ -337 +355 @@
 
     local queue = orxonox.NotificationManager:getInstance():getQueue(queueName)
+    -- Set the new targets.
     queue:setTargets(window:getText())
     local targets = queue:getTargets()
@@ -343 +362 @@
     P.sampleWindow:setText(targets)
     local size = getMinTextSize(P.sampleWindow)
+    -- Adjust the width of the targets field.
     window:setWidth(CEGUI.UDim(0, size[2]*2+20))
+    -- Adjust the position of the save button after the targets field.
     save:setXPosition(CEGUI.UDim(0, save:getXPosition():asAbsolute(1)-width+window:getWidth():asAbsolute(1)))
 end
 
+-- If the button to save the size if a queue has been clicked.
 function P. saveSize_clicked(e)
     local we = CEGUI.toWindowEventArgs(e)
@@ -360 +382 @@
 
     local queue = orxonox.NotificationManager:getInstance():getQueue(queueName)
+    -- Set the new size.
     queue:setMaxSize(tonumber(window:getText()))
     local maxSize = queue:getMaxSize()
@@ -366 +389 @@
     P.sampleWindow:setText(maxSize)
     local size = getMinTextSize(P.sampleWindow)
+    -- Adjust the width of the size field.
     window:setWidth(CEGUI.UDim(0, size[2]*2+20))
+    -- Adjust the position of the save button after the size field.
     save:setXPosition(CEGUI.UDim(0, save:getXPosition():asAbsolute(1)-width+window:getWidth():asAbsolute(1)))
 end
 
+-- If the button to save the display time if a queue has been clicked.
 function P. saveDisplayTime_clicked(e)
     local we = CEGUI.toWindowEventArgs(e)
@@ -383 +409 @@
 
     local queue = orxonox.NotificationManager:getInstance():getQueue(queueName)
+    -- Set the new display time.
     queue:setDisplayTime(tonumber(window:getText()))
     local time = queue:getDisplayTime()
@@ -389 +416 @@
     P.sampleWindow:setText(time)
     local size = getMinTextSize(P.sampleWindow)
+    -- Adjust the width of the display time field.
     window:setWidth(CEGUI.UDim(0, size[2]*2+20))
+    -- Adjust the position of the save button after the display time field.
     save:setXPosition(CEGUI.UDim(0, save:getXPosition():asAbsolute(1)-width+window:getWidth():asAbsolute(1)))
 end
 
+-- if the button to create a new queue has been clicked.
 function P.createNewQueue_clicked(e)
     local window = winMgr:getWindow("orxonox/NotificationLayer/Root/EditMode/ControlWindow/NewQueueName")
     local name = window:getText()
+    -- Creates the new queue.
     orxonox.NotificationManager:getInstance():createQueue(name)
 
     local queue = P.queueList[name]
     if queue == nil then
-        cout(0, "7Queue is nil! " .. name)
-        return
-    end
-    
+        return
+    end
+
+    -- Create the frame that represents the queue in edit mode, since that's what we're in.
     local frame = P.createQueueEditFrame(name)
     local root = winMgr:getWindow("orxonox/NotificationLayer/Root")
+    -- Remove the queue window from the root window, since we're in edit mode.
     root:removeChildWindow(queue.window)
+    -- Set the frame window size and position to that of the queue window.
     frame:setArea(queue.window:getArea())
     queue.edit = frame
-    
+
+    -- Reset the text to create a new queue.
     window:setText("")
 end
 
+-- If the button to leave the edit mode has been clicked.
 function P.leaveEditMode_clicked(e)
     hideMenuSheet(P.name)
 end
 
+-- If the button to close the queue has been clicked.
 function P.closeQueue_clicked(e)
     local we = CEGUI.toWindowEventArgs(e)
@@ -425 +461 @@
     local queueName = string.sub(nameStr, 10, string.len(nameStr))
 
+    -- Destroy the frame window,
     winMgr:destroyWindow(P.queueList[queueName].edit)
     P.queueList[queueName].edit = nil
+    -- Destroy the queue.
     orxonox.NotificationManager:getInstance():getQueue(queueName):destroy()
 end
 
+-- Helper function. Returns height a queue needs to have to display 'size' items.
 function P.queueHeightHelper(queue, size)
     local listbox = CEGUI.toListbox(queue)