DgsAddPropertyListener

This function enables monitoring of property changes on DGS elements. When a property that has been added to the listener list changes via dgsSetProperty, it triggers the onDgsPropertyChange event.

[[{{{image}}}|link=|]]	Note: Property listeners only trigger when using dgsSetProperty, not when using specific setter functions

[[{{{image}}}|link=|]]	Note: The onDgsPropertyChange event is only triggered for properties that have been explicitly added to the listener

[[{{{image}}}|link=|]]	Tip: Property listeners persist until explicitly removed using dgsRemovePropertyListener or the element is destroyed

Syntax

bool dgsAddPropertyListener ( element dgsElement, string/table propertyNames )
bool dgsAddPropertyListener ( table dgsElements, string/table propertyNames )

Required Arguments

• dgsElement: A DGS element or table of DGS elements to monitor.
• propertyNames: A property name (string) or table of property names to listen for changes.

Returns

Returns true if the property listener was added successfully, false otherwise.

Examples

Example 1: Basic Property Monitoring

loadstring(exports.dgs:dgsImportFunction())()-- load functions

-- Create a DGS window
local window = dgsCreateWindow(200, 200, 400, 300, "Property Monitor Demo", false)

-- Add listener for position changes
dgsAddPropertyListener(window, "absPos")

-- Set up event handler
addEventHandler("onDgsPropertyChange", window, function(propertyName, newValue, oldValue)
if propertyName == "absPos" then
outputChatBox("Window moved from " .. tostring(oldValue[1]) .. "," .. tostring(oldValue[2]) ..
" to " .. tostring(newValue[1]) .. "," .. tostring(newValue[2]))
end
end)

-- Test the listener
setTimer(function()
dgsSetProperty(window, "absPos", {300, 250})
end, 2000, 1)

Example 2: Multiple Property Monitoring

loadstring(exports.dgs:dgsImportFunction())()-- load functions

-- Create a DGS button
local button = dgsCreateButton(50, 50, 200, 100, "Monitor Me", false)

-- Monitor multiple properties
dgsAddPropertyListener(button, {"text", "color", "size"})

-- Handle property changes
addEventHandler("onDgsPropertyChange", button, function(propertyName, newValue, oldValue)
outputChatBox("Property '" .. propertyName .. "' changed!")

    if propertyName == "text" then
        outputChatBox("Text changed from '" .. tostring(oldValue) .. "' to '" .. tostring(newValue) .. "'")
    elseif propertyName == "color" then
        outputChatBox("Color changed")
    elseif propertyName == "size" then
        outputChatBox("Size changed to " .. tostring(newValue[1]) .. "x" .. tostring(newValue[2]))
    end

end)

-- Test the listeners
setTimer(function()
dgsSetProperty(button, "text", "Changed Text!")
end, 1000, 1)

setTimer(function()
dgsSetProperty(button, "color", {tocolor(255, 0, 0, 255), tocolor(200, 0, 0, 255), tocolor(150, 0, 0, 255)})
end, 2000, 1)

Example 3: Monitoring Multiple Elements

loadstring(exports.dgs:dgsImportFunction())()-- load functions

-- Create multiple elements
local elements = {}
elements[1] = dgsCreateButton(100, 100, 150, 50, "Button 1", false)
elements[2] = dgsCreateButton(100, 200, 150, 50, "Button 2", false)
elements[3] = dgsCreateButton(100, 300, 150, 50, "Button 3", false)

-- Add property listeners to all elements at once
dgsAddPropertyListener(elements, "visible")

-- Handle visibility changes for all elements
for i, element in ipairs(elements) do
addEventHandler("onDgsPropertyChange", element, function(propertyName, newValue, oldValue)
if propertyName == "visible" then
local elementName = "Element " .. i
outputChatBox(elementName .. " visibility changed to " .. tostring(newValue))
end
end)
end

-- Test visibility changes
setTimer(function()
for i, element in ipairs(elements) do
dgsSetProperty(element, "visible", math.random() > 0.5)
end
end, 3000, 1)

Example 4: Real-time Position Tracking

loadstring(exports.dgs:dgsImportFunction())()-- load functions

-- Create a movable window
local trackingWindow = dgsCreateWindow(100, 100, 250, 200, "Position Tracker", false)
local positionLabel = dgsCreateLabel(10, 30, 230, 20, "Position: 100, 100", false, trackingWindow)
local sizeLabel = dgsCreateLabel(10, 60, 230, 20, "Size: 250 x 200", false, trackingWindow)

-- Monitor position and size changes
dgsAddPropertyListener(trackingWindow, {"absPos", "absSize"})

-- Update labels when properties change
addEventHandler("onDgsPropertyChange", trackingWindow, function(propertyName, newValue, oldValue)
if propertyName == "absPos" then
dgsSetProperty(positionLabel, "text", "Position: " .. newValue[1] .. ", " .. newValue[2])
elseif propertyName == "absSize" then
dgsSetProperty(sizeLabel, "text", "Size: " .. newValue[1] .. " x " .. newValue[2])
end
end)

-- Make window movable and resizable for testing
dgsSetProperty(trackingWindow, "movable", true)
dgsSetProperty(trackingWindow, "sizable", true)

Author

Mohab.

See Also

_dgsRemovePropertyListener _dgsGetListenedProperties _dgsSetProperty _dgsGetProperty