cluaupp 1.0.0 → 1.3.0

package/templates/game/libs/TopbarPlus/_impl/init.lua

@@ -0,0 +1,1249 @@
+--!nonstrict
+--[[
+	
+	The majority of this code is an interface designed to make it easy for you to
+	work with TopbarPlus (most methods for instance reference :modifyTheme()).
+	The processing overhead mainly consists of applying themes and calculating 
+	appearance (such as size and width of labels) which is handled in about
+	200 lines of code here and the Widget UI module. This has been achieved
+	in v3 by outsourcing a majority of previous calculations to inbuilt Roblox
+	features like UIListLayouts.
+
+
+	v3 provides inbuilt support for controllers (simply press DPadUp),
+	touch devices (phones, tablets , etc), localization (automatic resizing
+	of widgets, autolocalize for relevant labels), backwards compatability
+	with the old topbar, and more.
+
+
+	My primary goals for the v3 re-write have been to:
+		
+	1. Improve code readability and organisation (reduced lines of code within
+	   Icon+IconController from 3200 to ~950, separated UI elements, etc)
+		
+	2. Improve ease-of-use (themes now actually make sense and can account
+	   for any modifications you want, converted to a package for
+	   quick installation and easy-comparisons of new updates, etc)
+	
+	3. Provide support for all key features of the new Roblox topbar
+	   while improving performance of the module (deferring and collecting
+	   changes then calling as a singular, utilizing inbuilt Roblox features
+	   such as UILIstLayouts, etc)
+
+--]]
+
+
+
+-- SERVICES
+local UserInputService = game:GetService("UserInputService")
+local ContentProvider = game:GetService("ContentProvider")
+local StarterGui = game:GetService("StarterGui")
+local Players = game:GetService("Players")
+local Types = require(script.Types)
+
+
+
+-- TYPES
+export type Icon = Types.Icon
+
+
+
+-- REFERENCE HANDLER
+-- Multiple Icons packages may exist at runtime (for instance if the developer additionally uses HD Admin)
+-- therefore this ensures that the first required package becomes the dominant and only functioning module
+local iconModule = script
+local Reference = require(iconModule.Reference)
+local referenceObject = Reference.getObject()
+local leadPackage = referenceObject and referenceObject.Value
+if leadPackage and leadPackage ~= iconModule then
+	return require(leadPackage) :: Types.StaticIcon
+end
+if not referenceObject then
+	Reference.addToReplicatedStorage()
+end
+
+
+
+-- MODULES
+local Signal = require(iconModule.Packages.GoodSignal)
+local Janitor = require(iconModule.Packages.Janitor)
+local Utility = require(iconModule.Utility)
+local Themes = require(iconModule.Features.Themes)
+local Gamepad = require(iconModule.Features.Gamepad)
+local Overflow = require(iconModule.Features.Overflow)
+local Icon = {}
+Icon.__index = Icon
+
+
+
+--- LOCAL
+local localPlayer = Players.LocalPlayer
+local themes = iconModule.Features.Themes
+local iconsDict = {}
+local anyIconSelected = Signal.new()
+local elements = iconModule.Elements
+local totalCreatedIcons = 0
+local preferredInput = {
+	mobile = Enum.PreferredInput.Touch,
+	desktop = Enum.PreferredInput.KeyboardAndMouse,
+	console = Enum.PreferredInput.Gamepad
+}
+
+
+
+-- PUBLIC VARIABLES
+Icon.baseDisplayOrderChanged = Signal.new()
+Icon.baseDisplayOrder = 10
+Icon.baseTheme = require(themes.Default)
+Icon.isOldTopbar = false -- Logic has been moved to Container
+Icon.iconsDictionary = iconsDict
+Icon.insetHeightChanged = Signal.new()
+Icon.container = require(elements.Container)(Icon)
+Icon.topbarEnabled = true
+Icon.iconAdded = Signal.new()
+Icon.iconRemoved = Signal.new()
+Icon.iconChanged = Signal.new()
+
+
+
+-- PUBLIC FUNCTIONS
+function Icon.getIcons()
+	return Icon.iconsDictionary
+end
+
+function Icon.getIconByUID(UID)
+	local match = Icon.iconsDictionary[UID]
+	if match then
+		return match
+	end
+	return nil
+end
+
+function Icon.getIcon(nameOrUID)
+	local match = Icon.getIconByUID(nameOrUID)
+	if match then
+		return match
+	end
+	for _, icon in pairs(iconsDict) do
+		if icon.name == nameOrUID then
+			return icon
+		end
+	end
+	return nil
+end
+
+function Icon.setTopbarEnabled(bool, isInternal)
+	if typeof(bool) ~= "boolean" then
+		bool = Icon.topbarEnabled
+	end
+	if not isInternal then
+		Icon.topbarEnabled = bool
+	end
+	for _, screenGui in pairs(Icon.container) do
+		screenGui.Enabled = bool
+	end
+end
+
+function Icon.modifyBaseTheme(modifications)
+	modifications = Themes.getModifications(modifications)
+	for _, modification in pairs(modifications) do
+		for _, detail in pairs(Icon.baseTheme) do
+			Themes.merge(detail, modification)
+		end
+	end
+	for _, icon in pairs(iconsDict) do
+		icon:setTheme(Icon.baseTheme)
+	end
+end
+
+function Icon.setDisplayOrder(int)
+	Icon.baseDisplayOrder = int
+	Icon.baseDisplayOrderChanged:Fire(int)
+end
+
+
+
+-- SETUP
+task.defer(Gamepad.start, Icon)
+task.defer(Overflow.start, Icon)
+task.defer(function()
+	local playerGui = localPlayer:WaitForChild("PlayerGui")
+	for _, screenGui in pairs(Icon.container) do
+		screenGui.Parent = playerGui
+	end
+	require(iconModule.Attribute)
+end)
+
+
+
+-- CONSTRUCTOR
+function Icon.new()
+	local self = {}
+	setmetatable(self, Icon)
+
+	--- Janitors (for cleanup)
+	local janitor = Janitor.new()
+	self.janitor = janitor
+	self.themesJanitor = janitor:add(Janitor.new())
+	self.singleClickJanitor = janitor:add(Janitor.new())
+	self.captionJanitor = janitor:add(Janitor.new())
+	self.joinJanitor = janitor:add(Janitor.new())
+	self.menuJanitor = janitor:add(Janitor.new())
+	self.dropdownJanitor = janitor:add(Janitor.new())
+
+	-- Register
+	local iconUID = Utility.generateUID()
+	iconsDict[iconUID] = self
+	janitor:add(function()
+		iconsDict[iconUID] = nil
+	end)
+
+	-- Signals (events)
+	self.selected = janitor:add(Signal.new())
+	self.deselected = janitor:add(Signal.new())
+	self.toggled = janitor:add(Signal.new())
+	self.viewingStarted = janitor:add(Signal.new())
+	self.viewingEnded = janitor:add(Signal.new())
+	self.stateChanged = janitor:add(Signal.new())
+	self.notified = janitor:add(Signal.new())
+	self.noticeStarted = janitor:add(Signal.new())
+	self.noticeChanged = janitor:add(Signal.new())
+	self.endNotices = janitor:add(Signal.new())
+	self.toggleKeyAdded = janitor:add(Signal.new())
+	self.fakeToggleKeyChanged = janitor:add(Signal.new())
+	self.alignmentChanged = janitor:add(Signal.new())
+	self.updateSize = janitor:add(Signal.new())
+	self.resizingComplete = janitor:add(Signal.new())
+	self.joinedParent = janitor:add(Signal.new())
+	self.menuSet = janitor:add(Signal.new())
+	self.dropdownSet = janitor:add(Signal.new())
+	self.updateMenu = janitor:add(Signal.new())
+	self.startMenuUpdate = janitor:add(Signal.new())
+	self.childThemeModified = janitor:add(Signal.new())
+	self.indicatorSet = janitor:add(Signal.new())
+	self.dropdownChildAdded = janitor:add(Signal.new())
+	self.menuChildAdded = janitor:add(Signal.new())
+
+	-- Properties
+	self.iconModule = iconModule
+	self.UID = iconUID
+	self.isEnabled = true
+	self.enabled = self.isEnabled -- Backwards compatability
+	self.isSelected = false
+	self.isViewing = false
+	self.joinedFrame = false
+	self.parentIconUID = false
+	self.deselectWhenOtherIconSelected = true
+	self.totalNotices = 0
+	self.activeState = "Deselected"
+	self.alignment = ""
+	self.originalAlignment = ""
+	self.appliedTheme = {}
+	self.appearance = {}
+	self.cachedInstances = {}
+	self.cachedNamesToInstances = {}
+	self.cachedCollectives = {}
+	self.bindedToggleKeys = {}
+	self.customBehaviours = {}
+	self.toggleItems = {}
+	self.bindedEvents = {}
+	self.notices = {}
+	self.menuIcons = {}
+	self.dropdownIcons = {}
+	self.childIconsDict = {}
+	self.creationTime = os.clock()
+
+	-- Widget is the new name for an icon
+	local widget = janitor:add(require(elements.Widget)(self, Icon))
+	self.widget = widget
+	self:setAlignment()
+	
+	-- It's important we set an order otherwise icons will not align
+	-- correctly within menus
+	totalCreatedIcons += 1
+	local ourOrder = 1+(totalCreatedIcons*0.01)
+	self:setOrder(ourOrder, "deselected")
+	self:setOrder(ourOrder, "selected")
+
+	-- This applies the default them
+	self:setTheme(Icon.baseTheme)
+
+	-- Button Clicked (for states "Selected" and "Deselected")
+	local clickRegion = self:getInstance("ClickRegion")
+	local hasUsedMouseButton1Click = false
+	local lastToggleTime = 0
+	local DEBOUNCE_TIME = 0.1 -- 100ms debounce to prevent rapid toggles
+
+	local function handleToggle()
+		if self.locked then
+			return
+		end
+
+		-- Debounce logic to prevent rapid toggling
+		local currentTime = tick()
+		if currentTime - lastToggleTime < DEBOUNCE_TIME then
+			return
+		end
+		lastToggleTime = currentTime
+
+		if self.isSelected then
+			self:deselect("User", self)
+		else
+			self:select("User", self)
+		end
+	end
+
+	clickRegion.MouseButton1Click:Connect(function()
+		hasUsedMouseButton1Click = true
+		handleToggle()
+	end)
+
+	clickRegion.TouchTap:Connect(function()
+		-- This resolves the bug report by @28Pixels:
+		-- https://devforum.roblox.com/t/topbarplus/1017485/1104
+		-- Only use TouchTap if MouseButton1Click has never fired
+		-- This handles edge cases where ONLY TouchTap works
+		-- Also prevents double-toggle bug with multi-touch on mobile
+		-- Credit to @sayer80 for this fix
+		if not hasUsedMouseButton1Click then
+			handleToggle()
+		end
+	end)
+
+	-- Keys can be bound to toggle between Selected and Deselected
+	janitor:add(UserInputService.InputBegan:Connect(function(input, touchingAnObject)
+		if self.locked then
+			return
+		end
+		if self.bindedToggleKeys[input.KeyCode] and not touchingAnObject then
+			handleToggle()
+		end
+	end))
+
+	-- Button Hovering (for state "Viewing")
+	-- Hovering is a state only for devices with keyboards
+	-- and controllers (not touchpads)
+	local function viewingStarted(dontSetState)
+		if self.locked then
+			return
+		end
+		self.isViewing = true
+		self.viewingStarted:Fire(true)
+		if not dontSetState then
+			self:setState("Viewing", "User", self)
+		end
+	end
+	local function viewingEnded()
+		if self.locked then
+			return
+		end
+		self.isViewing = false
+		self.viewingEnded:Fire(true)
+		self:setState(nil, "User", self)
+	end
+	self.joinedParent:Connect(function()
+		if self.isViewing then
+			viewingEnded()
+		end
+	end)
+	clickRegion.MouseEnter:Connect(function()
+		local dontSetState = UserInputService.PreferredInput ~= preferredInput.desktop
+		viewingStarted(dontSetState)
+	end)
+	local touchCount = 0
+	janitor:add(UserInputService.TouchEnded:Connect(viewingEnded))
+	clickRegion.MouseLeave:Connect(viewingEnded)
+	clickRegion.SelectionGained:Connect(viewingStarted)
+	clickRegion.SelectionLost:Connect(viewingEnded)
+	clickRegion.MouseButton1Down:Connect(function()
+		if not self.locked and UserInputService.PreferredInput == preferredInput.mobile then
+			touchCount += 1
+			local myTouchCount = touchCount
+			task.delay(0.2, function()
+				if myTouchCount == touchCount then
+					viewingStarted()
+				end
+			end)
+		end
+	end)
+	clickRegion.MouseButton1Up:Connect(function()
+		touchCount += 1
+	end)
+
+	-- Handle overlay on viewing
+	local iconOverlay = self:getInstance("IconOverlay")
+	self.viewingStarted:Connect(function()
+		iconOverlay.Visible = not self.overlayDisabled
+	end)
+	self.viewingEnded:Connect(function()
+		iconOverlay.Visible = false
+	end)
+
+	-- Deselect when another icon is selected
+	janitor:add(anyIconSelected:Connect(function(incomingIcon)
+		if incomingIcon ~= self and self.deselectWhenOtherIconSelected and incomingIcon.deselectWhenOtherIconSelected then
+			self:deselect("AutoDeselect", incomingIcon)
+		end
+	end))
+
+	-- This checks if the script calling this module is a descendant of a ScreenGui
+	-- with 'ResetOnSpawn' set to true. If it is, then we destroy the icon the
+	-- client respawns. This solves one of the most asked about questions on the post
+	-- The only caveat this may not work if the player doesn't uniquely name their ScreenGui and the frames
+	-- the LocalScript rests within
+	local source =  debug.info(2, "s")
+	local sourcePath = string.split(source, ".")
+	local origin = game
+	local originsScreenGui
+	for i, sourceName in pairs(sourcePath) do
+		origin = origin:FindFirstChild(sourceName)
+		if not origin then
+			break
+		end
+		if origin:IsA("ScreenGui") then
+			originsScreenGui = origin
+		end
+	end
+	if origin and originsScreenGui and originsScreenGui.ResetOnSpawn == true then
+		self.originsScreenGui = originsScreenGui
+		Utility.localPlayerRespawned(function()
+			self:destroy()
+		end)
+	end
+
+	-- Additional children behaviour when toggled (mostly notices)
+	self.toggled:Connect(function(isSelected)
+		self.noticeChanged:Fire(self.totalNotices)
+		for childIconUID, _ in pairs(self.childIconsDict) do
+			local childIcon = Icon.getIconByUID(childIconUID)
+			childIcon.noticeChanged:Fire(childIcon.totalNotices)
+			if not isSelected and childIcon.isSelected then
+				-- If an icon within a menu or dropdown is also
+				-- a dropdown or menu, then close it
+				for _, _ in pairs(childIcon.childIconsDict) do
+					childIcon:deselect("HideParentFeature", self)
+				end
+			end
+		end
+	end)
+	
+	-- This closes/reopens the chat or playerlist if the icon is a dropdown
+	-- In the future I'd prefer to use the position+size of the chat
+	-- to determine whether to close dropdown (instead of non-right-set)
+	-- but for reasons mentioned here it's unreliable at the time of
+	-- writing this: https://devforum.roblox.com/t/here/2794915
+	-- I could also make this better by accounting for multiple
+	-- dropdowns being open (not just this one) but this will work
+	-- fine for almost every use case for now.
+	self.selected:Connect(function()
+		local isDropdown = #self.dropdownIcons > 0
+		if isDropdown then
+			if StarterGui:GetCore("ChatActive") and self.alignment ~= "Right" then
+				self.chatWasPreviouslyActive = true
+				StarterGui:SetCore("ChatActive", false)
+			end
+			if StarterGui:GetCoreGuiEnabled("PlayerList") and self.alignment ~= "Left" then
+				self.playerlistWasPreviouslyActive = true
+				StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)
+			end
+		end
+	end)
+	self.deselected:Connect(function()
+		if self.chatWasPreviouslyActive then
+			self.chatWasPreviouslyActive = nil
+			StarterGui:SetCore("ChatActive", true)
+		end
+		if self.playerlistWasPreviouslyActive then
+			self.playerlistWasPreviouslyActive = nil
+			StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, true)
+		end
+	end)
+	
+	-- There's a rare occassion where the appearance is not
+	-- fully set to deselected so this ensures the icons
+	-- appearance is fully as it should be
+	task.delay(0.1, function()
+		if self.activeState == "Deselected" then
+			self.stateChanged:Fire("Deselected")
+			self:refresh()
+		end
+	end)
+	
+	-- Call icon added
+	Icon.iconAdded:Fire(self)
+
+	return self
+end
+
+
+
+-- METHODS
+function Icon:setName(name)
+	self.widget.Name = name
+	self.name = name
+	return self
+end
+
+function Icon:setState(incomingStateName, fromSource, sourceIcon)
+	-- This is responsible for acknowleding a change in stage (such as from "Deselected" to "Viewing" when
+	-- a users mouse enters the widget), then informing other systems of this state change to then act upon
+	-- (such as the theme handler applying the theme which corresponds to that state).
+	if not incomingStateName then
+		incomingStateName = (self.isSelected and "Selected") or "Deselected"
+	end
+	local stateName = Utility.formatStateName(incomingStateName)
+	local previousStateName = self.activeState
+	if previousStateName == stateName then
+		return
+	end
+	local currentIsSelected = self.isSelected
+	self.activeState = stateName
+	if stateName == "Deselected" then
+		self.isSelected = false
+		if currentIsSelected then
+			self.toggled:Fire(false, fromSource, sourceIcon)
+			self.deselected:Fire(fromSource, sourceIcon)
+		end
+		self:_setToggleItemsVisible(false, fromSource, sourceIcon)
+	elseif stateName == "Selected" then
+		self.isSelected = true
+		if not currentIsSelected then
+			self.toggled:Fire(true, fromSource, sourceIcon)
+			self.selected:Fire(fromSource, sourceIcon)
+			anyIconSelected:Fire(self, fromSource, sourceIcon)
+		end
+		self:_setToggleItemsVisible(true, fromSource, sourceIcon)
+	end
+	self.stateChanged:Fire(stateName, fromSource, sourceIcon)
+end
+
+function Icon:getInstance(name)
+	-- This enables us to easily retrieve instances located within the icon simply by passing its name.
+	-- Every important/significant instance is named uniquely therefore this is no worry of overlap.
+	-- We cache the result for more performant retrieval in the future.
+	local instance = self.cachedNamesToInstances[name]
+	if instance then
+		return instance
+	end
+	local function cacheInstance(childName, child)
+		local currentCache = self.cachedInstances[child]
+		if not currentCache then
+			local collectiveName = child:GetAttribute("Collective")
+			local cachedCollective = collectiveName and self.cachedCollectives[collectiveName]
+			if cachedCollective then
+				table.insert(cachedCollective, child)
+			end
+			self.cachedNamesToInstances[childName] = child
+			self.cachedInstances[child] = true
+			child.Destroying:Once(function()
+				self.cachedNamesToInstances[childName] = nil
+				self.cachedInstances[child] = nil
+			end)
+		end
+	end
+	local widget = self.widget
+	cacheInstance("Widget", widget)
+	if name == "Widget" then
+		return widget
+	end
+
+	local returnChild
+	local function scanChildren(parentInstance)
+		for _, child in pairs(parentInstance:GetChildren()) do
+			local widgetUID = child:GetAttribute("WidgetUID")
+			if widgetUID and widgetUID ~= self.UID then
+				-- This prevents instances within other icons from being recorded
+				-- (for instance when other icons are added to this icons menu)
+				continue
+			end
+			-- If the child is a fake placeholder instance (such as dropdowns, notices, etc)
+			-- then its important we scan the real original instance instead of this clone
+			local realChild = Themes.getRealInstance(child)
+			if realChild then
+				child = realChild
+			end
+			-- Finally scan its children
+			scanChildren(child)
+			if child:IsA("GuiBase") or child:IsA("UIBase") or child:IsA("ValueBase") then
+				local childName = child.Name
+				cacheInstance(childName, child)
+				if childName == name then
+					returnChild = child
+				end
+			end
+		end
+	end
+	scanChildren(widget)
+	return returnChild
+end
+
+function Icon:getCollective(name)
+	-- A collective is an array of instances within the Widget that have been
+	-- grouped together based on a given name. This just makes it easy
+	-- to act on multiple instances at once which share similar behaviours.
+	-- For instance, if we want to change the icons corner size, all corner instances
+	-- with the attribute "Collective" and value "WidgetCorner" could be updated
+	-- instantly by doing Themes.apply(icon, "WidgetCorner", newSize)
+	local collective = self.cachedCollectives[name]
+	if collective then
+		return collective
+	end
+	collective = {}
+	for instance, _ in pairs(self.cachedInstances) do
+		if instance:GetAttribute("Collective") == name then
+			table.insert(collective, instance)
+		end
+	end
+	self.cachedCollectives[name] = collective
+	return collective
+end
+
+function Icon:getInstanceOrCollective(collectiveOrInstanceName)
+	-- Similar to :getInstance but also accounts for 'Collectives', such as UICorners and returns
+	-- an array of instances instead of a single instance
+	local instances = {}
+	local instance = self:getInstance(collectiveOrInstanceName)
+	if instance then
+		table.insert(instances, instance)
+	end
+	if #instances == 0 then
+		instances = self:getCollective(collectiveOrInstanceName)
+	end
+	return instances
+end
+
+function Icon:getStateGroup(iconState)
+	local chosenState = iconState or self.activeState
+	local stateGroup = self.appearance[chosenState]
+	if not stateGroup then
+		stateGroup = {}
+		self.appearance[chosenState] = stateGroup
+	end
+	return stateGroup
+end
+
+function Icon:refreshAppearance(instance, specificProperty)
+	Themes.refresh(self, instance, specificProperty)
+	return self
+end
+
+function Icon:refresh()
+	self:refreshAppearance(self.widget)
+	self.updateSize:Fire()
+	return self
+end
+
+function Icon:updateParent()
+	local parentIcon = Icon.getIconByUID(self.parentIconUID)
+	if parentIcon then
+		parentIcon.updateSize:Fire()
+	end
+end
+
+function Icon:setBehaviour(collectiveOrInstanceName, property, callback, refreshAppearance)
+	-- You can specify your own custom callback to handle custom logic just before
+	-- an instances property is changed by using :setBehaviour()
+	local key = collectiveOrInstanceName.."-"..property
+	self.customBehaviours[key] = callback
+	if refreshAppearance then
+		local instances = self:getInstanceOrCollective(collectiveOrInstanceName)
+		for _, instance in pairs(instances) do
+			self:refreshAppearance(instance, property)
+		end
+	end
+end
+
+function Icon:modifyTheme(modifications, customModificationUID)
+	local modificationUID = Themes.modify(self, modifications, customModificationUID)
+	return self, modificationUID
+end
+
+function Icon:modifyChildTheme(modifications, modificationUID)
+	-- Same as modifyTheme except for its children (i.e. icons
+	-- within its dropdown or menu)
+	self.childModifications = modifications
+	self.childModificationsUID = modificationUID
+	for childIconUID, _ in pairs(self.childIconsDict) do
+		local childIcon = Icon.getIconByUID(childIconUID)
+		childIcon:modifyTheme(modifications, modificationUID)
+	end
+	self.childThemeModified:Fire()
+	return self
+end
+
+function Icon:removeModification(modificationUID)
+	Themes.remove(self, modificationUID)
+	return self
+end
+
+function Icon:removeModificationWith(instanceName, property, state)
+	Themes.removeWith(self, instanceName, property, state)
+	return self
+end
+
+function Icon:setTheme(theme)
+	Themes.set(self, theme)
+	return self
+end
+
+function Icon:setEnabled(bool)
+	self.isEnabled = bool
+	self.enabled = self.isEnabled
+	self.widget.Visible = bool
+	self:updateParent()
+	return self
+end
+
+function Icon:select(fromSource, sourceIcon)
+	self:setState("Selected", fromSource, sourceIcon)
+	return self
+end
+
+function Icon:deselect(fromSource, sourceIcon)
+	self:setState("Deselected", fromSource, sourceIcon)
+	return self
+end
+
+function Icon:notify(customClearSignal, noticeId)
+	-- Generates a notification which appears in the top right of the icon. Useful for example for prompting
+	-- users of changes/updates within your UI such as a Catalog
+	-- 'customClearSignal' is a signal object (e.g. icon.deselected) or
+	-- Roblox event (e.g. Instance.new("BindableEvent").Event)
+	local notice = self.notice
+	if not notice then
+		notice = require(elements.Notice)(self, Icon)
+		self.notice = notice
+	end
+	self.noticeStarted:Fire(customClearSignal, noticeId)
+	return self
+end
+
+function Icon:clearNotices()
+	self.endNotices:Fire()
+	return self
+end
+
+function Icon:disableOverlay(bool)
+	self.overlayDisabled = bool
+	return self
+end
+Icon.disableStateOverlay = Icon.disableOverlay
+
+function Icon:setImage(imageId, iconState)
+	self:modifyTheme({"IconImage", "Image", imageId, iconState})
+	
+	-- This code ensures icon images are preloaded if they haven't been fetched yet
+	task.spawn(function()
+		local newIdContent = if tonumber(imageId) then `rbxassetid://{imageId}` else imageId
+		local initialAssetFetchStatus = ContentProvider:GetAssetFetchStatus(newIdContent)
+	
+		if initialAssetFetchStatus ~= Enum.AssetFetchStatus.Success then
+			pcall(ContentProvider.PreloadAsync, ContentProvider, { newIdContent })
+		end
+	end)
+		
+	return self
+end
+
+function Icon:setLabel(text, iconState)
+	self:modifyTheme({"IconLabel", "Text", text, iconState})
+	return self
+end
+
+function Icon:setOrder(int, iconState)
+	-- We multiply by 100 to allow for custom increments inbetween
+	-- (.01, .02, etc) as LayoutOrders only support integers
+	local newInt = int*100
+	self:modifyTheme({"IconSpot", "LayoutOrder", newInt, iconState})
+	self:modifyTheme({"Widget", "LayoutOrder", newInt, iconState})
+	return self
+end
+
+function Icon:setCornerRadius(udim, iconState)
+	self:modifyTheme({"IconCorners", "CornerRadius", udim, iconState})
+	return self
+end
+
+function Icon:align(leftCenterOrRight, isFromParentIcon)
+	-- Determines the side of the screen the icon will be ordered
+	local direction = tostring(leftCenterOrRight):lower()
+	if direction == "mid" or direction == "centre" then
+		direction = "center"
+	end
+	if direction ~= "left" and direction ~= "center" and direction ~= "right" then
+		direction = "left"
+	end
+	local screenGui = (direction == "center" and Icon.container.TopbarCentered) or Icon.container.TopbarStandard
+	local holders = screenGui.Holders
+	local finalDirection = string.upper(string.sub(direction, 1, 1))..string.sub(direction, 2)
+	if not isFromParentIcon then
+		self.originalAlignment = finalDirection
+	end
+	local joinedFrame = self.joinedFrame
+	local alignmentHolder = holders[finalDirection]
+	self.screenGui = screenGui
+	self.alignmentHolder = alignmentHolder
+	if not self.isDestroyed then
+		self.widget.Parent = joinedFrame or alignmentHolder
+	end
+	self.alignment = finalDirection
+	self.alignmentChanged:Fire(finalDirection)
+	Icon.iconChanged:Fire(self)
+	return self
+end
+Icon.setAlignment = Icon.align
+
+function Icon:setLeft()
+	self:setAlignment("Left")
+	return self
+end
+
+function Icon:setMid()
+	self:setAlignment("Center")
+	return self
+end
+
+function Icon:setRight()
+	self:setAlignment("Right")
+	return self
+end
+
+function Icon:setWidth(offsetMinimum, iconState)
+	-- This sets a minimum X offset size for the widget, useful
+	-- for example if you're constantly changing the label
+	-- but don't want the icon to resize every time
+	self:modifyTheme({"Widget", "DesiredWidth", offsetMinimum, iconState})
+	return self
+end
+
+function Icon:setImageScale(number, iconState)
+	self:modifyTheme({"IconImageScale", "Value", number, iconState})
+	return self
+end
+
+function Icon:setImageRatio(number, iconState)
+	self:modifyTheme({"IconImageRatio", "AspectRatio", number, iconState})
+	return self
+end
+
+function Icon:setTextSize(number, iconState)
+	self:modifyTheme({"IconLabel", "TextSize", number, iconState})
+	return self
+end
+
+function Icon:setTextFont(font, fontWeight, fontStyle, iconState)
+	fontWeight = fontWeight or Enum.FontWeight.Regular
+	fontStyle = fontStyle or Enum.FontStyle.Normal
+	local fontFace
+	local fontType = typeof(font)
+	if fontType == "number" then
+		fontFace = Font.fromId(font, fontWeight, fontStyle)
+	elseif fontType == "EnumItem" then
+		fontFace = Font.fromEnum(font)
+	elseif fontType == "string" then
+		if not font:match("rbxasset") then
+			fontFace = Font.fromName(font, fontWeight, fontStyle)
+		end
+	end
+	if not fontFace then
+		fontFace = Font.new(font, fontWeight, fontStyle)
+	end
+	self:modifyTheme({"IconLabel", "FontFace", fontFace, iconState})
+	return self
+end
+
+function Icon:setTextColor(Color, iconState)
+	if Color == nil or Color == "" or (type(Color) ~= "userdata" or typeof(Color) ~= "Color3") then
+		if Color ~= nil and Color ~= "" then
+			warn("setTextColor item must be a Color3 value! Changed the color to white.")
+		end
+		Color = Color3.fromRGB(255, 255, 255)
+	end
+
+	self:modifyTheme({"IconLabel", "TextColor3", Color, iconState})
+	return self
+end
+
+function Icon:bindToggleItem(guiObjectOrLayerCollector)
+	if not guiObjectOrLayerCollector:IsA("GuiObject") and not guiObjectOrLayerCollector:IsA("LayerCollector") then
+		error("Toggle item must be a GuiObject or LayerCollector!")
+	end
+	self.toggleItems[guiObjectOrLayerCollector] = true
+	self:_updateSelectionInstances()
+	return self
+end
+
+function Icon:unbindToggleItem(guiObjectOrLayerCollector)
+	self.toggleItems[guiObjectOrLayerCollector] = nil
+	self:_updateSelectionInstances()
+	return self
+end
+
+function Icon:_updateSelectionInstances()
+	-- This is to assist with controller navigation and selection
+	-- It converts the value true to an array
+	for guiObjectOrLayerCollector, _ in pairs(self.toggleItems) do
+		local buttonInstancesArray = {}
+		for _, instance in pairs(guiObjectOrLayerCollector:GetDescendants()) do
+			if (instance:IsA("TextButton") or instance:IsA("ImageButton")) and instance.Active then
+				table.insert(buttonInstancesArray, instance)
+			end
+		end
+		self.toggleItems[guiObjectOrLayerCollector] = buttonInstancesArray
+	end
+end
+
+function Icon:_setToggleItemsVisible(bool, fromSource, sourceIcon)
+	for toggleItem, _ in pairs(self.toggleItems) do
+		if not sourceIcon or sourceIcon == self or sourceIcon.toggleItems[toggleItem] == nil then
+			local property = "Visible"
+			if toggleItem:IsA("LayerCollector") then
+				property = "Enabled"
+			end
+			toggleItem[property] = bool
+		end
+	end
+end
+
+function Icon:bindEvent(iconEventName, eventFunction)
+	local event = self[iconEventName]
+	assert(event and typeof(event) == "table" and event.Connect, "argument[1] must be a valid topbarplus icon event name!")
+	assert(typeof(eventFunction) == "function", "argument[2] must be a function!")
+	self.bindedEvents[iconEventName] = event:Connect(function(...)
+		eventFunction(self, ...)
+	end)
+	return self
+end
+
+function Icon:unbindEvent(iconEventName)
+	local eventConnection = self.bindedEvents[iconEventName]
+	if eventConnection then
+		eventConnection:Disconnect()
+		self.bindedEvents[iconEventName] = nil
+	end
+	return self
+end
+
+function Icon:bindToggleKey(keyCodeEnum)
+	assert(typeof(keyCodeEnum) == "EnumItem", "argument[1] must be a KeyCode EnumItem!")
+	self.bindedToggleKeys[keyCodeEnum] = true
+	self.toggleKeyAdded:Fire(keyCodeEnum)
+	self:setCaption("_hotkey_")
+	return self
+end
+
+function Icon:unbindToggleKey(keyCodeEnum)
+	assert(typeof(keyCodeEnum) == "EnumItem", "argument[1] must be a KeyCode EnumItem!")
+	self.bindedToggleKeys[keyCodeEnum] = nil
+	return self
+end
+
+function Icon:call(callback, ...)
+	local packedArgs = table.pack(...)
+	task.spawn(function()
+		callback(self, table.unpack(packedArgs))
+	end)
+	return self
+end
+
+function Icon:addToJanitor(callback, methodName, index)
+	self.janitor:add(callback, methodName, index)
+	return self
+end
+
+function Icon:lock()
+	-- This disables all user inputs related to the icon (such as clicking buttons, pressing keys, etc)
+	local clickRegion = self:getInstance("ClickRegion")
+	clickRegion.Visible = false
+	self.locked = true
+	return self
+end
+
+function Icon:unlock()
+	local clickRegion = self:getInstance("ClickRegion")
+	clickRegion.Visible = true
+	self.locked = false
+	return self
+end
+
+function Icon:debounce(seconds)
+	self:lock()
+	task.wait(seconds)
+	self:unlock()
+	return self
+end
+
+function Icon:autoDeselect(bool)
+	-- When set to true the icon will deselect itself automatically whenever
+	-- another icon is selected
+	if bool == nil then
+		bool = true
+	end
+	self.deselectWhenOtherIconSelected = bool
+	return self
+end
+
+function Icon:oneClick(bool)
+	-- When set to true the icon will automatically deselect when selected, this creates
+	-- the effect of a single click button
+	local singleClickJanitor = self.singleClickJanitor
+	singleClickJanitor:clean()
+	if bool or bool == nil then
+		singleClickJanitor:add(self.selected:Connect(function()
+			self:deselect("OneClick", self)
+		end))
+	end
+	self.oneClickEnabled = true
+	return self
+end
+
+function Icon:setCaption(text)
+	if text == "_hotkey_" and (self.captionText) then
+		return self
+	end
+	local captionJanitor = self.captionJanitor
+	self.captionJanitor:clean()
+	if not text or text == "" then
+		self.caption = nil
+		self.captionText = nil
+		return self
+	end
+	local caption = captionJanitor:add(require(elements.Caption)(self))
+	caption:SetAttribute("CaptionText", text)
+	self.caption = caption
+	self.captionText = text
+	return self
+end
+
+function Icon:setCaptionHint(keyCodeEnum)
+	assert(typeof(keyCodeEnum) == "EnumItem", "argument[1] must be a KeyCode EnumItem!")
+	self.fakeToggleKey = keyCodeEnum
+	self.fakeToggleKeyChanged:Fire(keyCodeEnum)
+	self:setCaption("_hotkey_")
+	return self
+end
+
+function Icon:leave()
+	local joinJanitor = self.joinJanitor
+	joinJanitor:clean()
+	return self
+end
+
+function Icon:joinMenu(parentIcon)
+	Utility.joinFeature(self, parentIcon, parentIcon.menuIcons, parentIcon:getInstance("Menu"))
+	parentIcon.menuChildAdded:Fire(self)
+	return self
+end
+
+function Icon:setMenu(arrayOfIcons)
+	self.menuSet:Fire(arrayOfIcons)
+	return self
+end
+
+function Icon:setFixedMenu(arrayOfIcons)
+	self:freezeMenu(arrayOfIcons)
+	self:setMenu(arrayOfIcons)
+end
+Icon.setFrozenMenu = Icon.setFixedMenu
+
+function Icon:freezeMenu()
+	-- A frozen menu is a menu which is permanently locked in the
+	-- the selected state (with its toggle hidden)
+	self:select("FrozenMenu", self)
+	self:bindEvent("deselected", function(icon)
+		icon:select("FrozenMenu", self)
+	end)
+	self:modifyTheme({"IconSpot", "Visible", false})
+end
+
+function Icon:joinDropdown(parentIcon)
+	parentIcon:getDropdown()
+	Utility.joinFeature(self, parentIcon, parentIcon.dropdownIcons, parentIcon:getInstance("DropdownScroller"))
+	parentIcon.dropdownChildAdded:Fire(self)
+	return self
+end
+
+function Icon:getDropdown()
+	local dropdown = self.dropdown
+	if not dropdown then
+		dropdown = require(elements.Dropdown)(self)
+		self.dropdown = dropdown
+		self:clipOutside(dropdown)
+	end
+	return dropdown
+end
+
+function Icon:setDropdown(arrayOfIcons)
+	self:getDropdown()
+	self.dropdownSet:Fire(arrayOfIcons)
+	return self
+end
+
+function Icon:clipOutside(instance)
+	-- This is essential for items such as notices and dropdowns which will exceed the bounds of the widget. This is an issue
+	-- because the widget must have ClipsDescendents enabled to hide items for instance when the menu is closing or opening.
+	-- This creates an invisible frame which matches the size and position of the instance, then the instance is parented outside of
+	-- the widget and tracks the clone to match its size and position. In order for themes, etc to work the applying system checks
+	-- to see if an instance is a clone, then if it is, it applies it to the original instance instead of the clone.
+	local instanceClone = Utility.clipOutside(self, instance)
+	self:refreshAppearance(instance)
+	return self, instanceClone
+end
+
+function Icon:setIndicator(keyCode)
+	-- An indicator is a direction button prompt with an image of the given keycode. This is useful for instance
+	-- with controllers to show the user what button to press to highlight the topbar. You don't need
+	-- to set an indicator for controllers as this is handled internally within the Gamepad module
+	local indicator = self.indicator
+	if not indicator then
+		indicator = self.janitor:add(require(elements.Indicator)(self, Icon))
+		self.indicator = indicator
+	end
+	self.indicatorSet:Fire(keyCode)
+end
+
+function Icon:convertLabelToNumberSpinner(numberSpinner, callback)
+	task.defer(function()
+		
+		local label = self:getInstance("IconLabel")
+		label.Transparency = 1
+		numberSpinner.Parent = label.Parent
+		numberSpinner.Size = UDim2.fromScale(1, 1)
+		numberSpinner.AnchorPoint = Vector2.new(0.5, 0.5)
+		numberSpinner.Position = UDim2.new(0.5, 0, 0.5, 0)
+		numberSpinner.TextXAlignment = Enum.TextXAlignment.Center
+		numberSpinner.ClipsDescendants = false
+
+		local propertiesToChangeLabel = {
+			"FontFace",
+			"BorderSizePixel",
+			"BorderColor3",
+			"Rotation",
+			"TextStrokeTransparency",
+			"TextStrokeColor3",
+			"TextStrokeTransparency",
+			"TextColor3",
+		}
+		for _, property in ipairs(propertiesToChangeLabel) do
+			numberSpinner[property] = label[property]
+			self:addToJanitor(label:GetPropertyChangedSignal(property):Connect(function()
+				numberSpinner[property] = label[property]
+			end))
+		end
+
+		local minDigits = 0
+		local maxDigits = 8
+		local function getSpinnerSizeAndDigitCount()
+			local TotalSize = 0
+			local numOfDigits = 0
+			for i, child in numberSpinner.Frame:GetChildren() do
+				local name = string.lower(child.Name)
+				if name == "digit" then
+					TotalSize += child.AbsoluteSize.X
+					numOfDigits += 1
+				elseif name == "prefix" or name == "suffix" or name == "comma" then
+					if child.Text ~= "" then
+						TotalSize += child.AbsoluteSize.X
+						numOfDigits += 1
+					end
+				end
+			end
+			return TotalSize, numOfDigits
+		end
+		
+		local function getLabelParentContainerXSize()
+			local firstParent = label.Parent
+			local nextParent = firstParent and firstParent.Parent
+			if nextParent == nil then
+				return 0
+			end
+			if nextParent.IconImage.Visible == true then
+				return numberSpinner.Frame.AbsoluteSize.X + label.Parent.Parent.IconImage.AbsoluteSize.X
+			else
+				return nextParent.AbsoluteSize.X
+			end
+		end
+		local function getNumberSpinnerXSize()
+			return numberSpinner.Frame.AbsoluteSize.X
+		end
+
+		local function adjustSize()
+			local totalDigitXSize, numOfDigits = getSpinnerSizeAndDigitCount()
+			if numOfDigits < 18 then
+				self:setLabel(numberSpinner.Value)
+			end
+
+			local NumberSpinnerXSize = getNumberSpinnerXSize()
+
+			while totalDigitXSize < NumberSpinnerXSize and self.isDestroyed ~= true do
+				task.wait(0.05)
+				if numOfDigits > minDigits and numOfDigits < maxDigits then
+					numberSpinner.TextSize = label.TextSize
+					break
+				else
+					numberSpinner.TextSize += 1
+				end
+
+				NumberSpinnerXSize = getNumberSpinnerXSize()
+				totalDigitXSize, numOfDigits = getSpinnerSizeAndDigitCount()
+			end
+
+			local labelParentContainerXSize = getLabelParentContainerXSize()
+			while totalDigitXSize > labelParentContainerXSize and self.isDestroyed ~= true do
+				task.wait(0.05)
+				if numOfDigits < maxDigits and numOfDigits > minDigits then
+					numberSpinner.TextSize = label.TextSize
+					break
+				else
+					numberSpinner.TextSize -= 1
+				end
+
+				labelParentContainerXSize = getLabelParentContainerXSize()
+				totalDigitXSize, numOfDigits = getSpinnerSizeAndDigitCount()
+			end
+		end
+
+		self:addToJanitor(numberSpinner.Frame.ChildAdded:Connect(adjustSize))
+		self:addToJanitor(numberSpinner.Frame.ChildRemoved:Connect(adjustSize))
+		self:addToJanitor(self.iconAdded:Connect(function()
+			task.wait(1)
+			adjustSize()
+		end))
+
+		self:updateParent()
+
+		-- This corrects text to the size of a normal label
+		numberSpinner.Name = "LabelSpinner"
+		numberSpinner.Prefix = "$"
+		numberSpinner.Commas = true
+		numberSpinner.Decimals = 0
+		numberSpinner.Duration = 0.25
+		numberSpinner.Value = 10
+		task.wait(0.2)
+		
+		if typeof(callback) == "function" then
+			callback()
+		end
+		
+	end)
+	return self
+end
+
+
+
+-- DESTROY/CLEANUP
+function Icon:destroy()
+	if self.isDestroyed then
+		return
+	end
+	self:clearNotices()
+	if self.parentIconUID then
+		self:leave()
+	end
+	self.isDestroyed = true
+	self.janitor:clean()
+	Icon.iconRemoved:Fire(self)
+end
+Icon.Destroy = Icon.destroy
+
+return Icon :: Types.StaticIcon