diff --git a/src/extensions/cp/apple/finalcutpro/export/ExportDialog.lua b/src/extensions/cp/apple/finalcutpro/export/ExportDialog.lua index fc47ae861..048c5bdd4 100644 --- a/src/extensions/cp/apple/finalcutpro/export/ExportDialog.lua +++ b/src/extensions/cp/apple/finalcutpro/export/ExportDialog.lua @@ -37,6 +37,12 @@ end --- cp.apple.finalcutpro.export.ExportDialogTitleText(parent) --- Constructor --- Creates a new Export [Dialog](cp.ui.Dialog.md) +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function ExportDialog:initialize(parent) Dialog.initialize(self, parent, parent.windowsUI:mutate(function(original) return cache(self, "_window", function() diff --git a/src/extensions/cp/apple/finalcutpro/inspector/BasePanel.lua b/src/extensions/cp/apple/finalcutpro/inspector/BasePanel.lua index 6b0c07603..52e71303c 100644 --- a/src/extensions/cp/apple/finalcutpro/inspector/BasePanel.lua +++ b/src/extensions/cp/apple/finalcutpro/inspector/BasePanel.lua @@ -18,11 +18,11 @@ local BasePanel = Element:subclass("cp.apple.finalcutpro.inspector.BasePanel") --- Constructs the panel, initialising the parent and the [UI](cp.ui.Element.md#UI). --- --- Parameters: ---- * parent - The parent [Element](cp.ui.Element.md). ---- * panelType - The panel type string, as defined in [Inspector.INSPECTOR_TABS](cp.apple.finalcutpro.inspector.Inspector.md#INSPECTOR_TABS). +--- * parent - The parent [Element](cp.ui.Element.md). +--- * panelType - The panel type string, as defined in [Inspector.INSPECTOR_TABS](cp.apple.finalcutpro.inspector.Inspector.md#INSPECTOR_TABS). --- --- Returns: ---- * The new `BasePanel` instance. +--- * The new `BasePanel` instance. function BasePanel:initialize(parent, panelType) local UI = parent.panelUI:mutate(function(original) return cache(self, "_ui", @@ -42,8 +42,11 @@ end --- Method --- Gets the type of panel this is. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The panel type identifier. +--- * The panel type identifier. function BasePanel:panelType() return self._panelType end diff --git a/src/extensions/cp/apple/finalcutpro/inspector/Inspector.lua b/src/extensions/cp/apple/finalcutpro/inspector/Inspector.lua index 6527810d0..93dd6ab04 100644 --- a/src/extensions/cp/apple/finalcutpro/inspector/Inspector.lua +++ b/src/extensions/cp/apple/finalcutpro/inspector/Inspector.lua @@ -269,8 +269,11 @@ end --- Method --- A [Statement](cp.rx.go.Statement.md) that attempts to show the `Inspector`. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The `Statement`, resolving to `true` if the Inspector was shown successfully, or an error if not. +--- * The `Statement`, resolving to `true` if the Inspector was shown successfully, or an error if not. function Inspector.lazy.method:doShow() return If(self.isShowing):Is(false) :Then(self:parent():doShow()) @@ -302,8 +305,11 @@ end --- Method --- A [Statement](cp.rx.go.Statement.md) that attempts to hide the `Inspector`. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The `Statement`, resolving to `true` if the Inspector was hidden successfully, or an error if not. +--- * The `Statement`, resolving to `true` if the Inspector was hidden successfully, or an error if not. function Inspector.lazy.method:doHide() return If(self.isShowing):Is(true) :Then(self:app().menu:doSelectMenu({"Window", "Show in Workspace", "Inspector"})) @@ -366,10 +372,10 @@ end --- Finds the named Inspector tab button, or sends an error if the type is unsupported. --- --- Parameters: ---- * type - the type of the button to return. (e.g. "Video") +--- * type - the type of the button to return. (e.g. "Video") --- --- Returns: ---- * A [Statement](cp.rx.go.Statement.md) to execute. +--- * A [Statement](cp.rx.go.Statement.md) to execute. --- --- Notes: --- * Valid strings for `type` are as follows: @@ -383,7 +389,7 @@ end --- * Title --- * Transition --- * Video ---- * Not all button types are available in all contexts. +--- * Not all button types are available in all contexts. function Inspector:doFindTabButton(type) local code = Inspector.INSPECTOR_TABS[type] if not code then @@ -406,10 +412,10 @@ end --- A Statement that selects the specified tab title. --- --- Parameters: ---- * title - The title of the tab to select. +--- * title - The title of the tab to select. --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md) +--- * The [Statement](cp.rx.go.Statement.md) function Inspector:doSelectTab(title) return Do(self:doShow()) :Then( diff --git a/src/extensions/cp/apple/finalcutpro/inspector/color/ColorWheel.lua b/src/extensions/cp/apple/finalcutpro/inspector/color/ColorWheel.lua index 5b87320bd..dff625a4e 100644 --- a/src/extensions/cp/apple/finalcutpro/inspector/color/ColorWheel.lua +++ b/src/extensions/cp/apple/finalcutpro/inspector/color/ColorWheel.lua @@ -150,6 +150,9 @@ end --- Method --- Shows the `ColorWheel`, if possible. --- +--- Parameters: +--- * None +--- --- Returns: --- * The same `ColorWheel` instance, for chaining. function ColorWheel:show() @@ -166,6 +169,9 @@ end --- Method --- A [Statement](cp.rx.go.Statement.md) that attempts to show the `ColorWheel`. --- +--- Parameters: +--- * None +--- --- Returns: --- * The `Statement`, resolving to `true` if shown, `false` if not. function ColorWheel.lazy.method:doShow() @@ -198,6 +204,9 @@ end --- Method --- A [Statement](cp.rx.go.Statement.md) that attempts to select this `ColorWheel`. --- +--- Parameters: +--- * None +--- --- Returns: --- * The `Statement`, resolving to `true` if selected, otherwise `false`. function ColorWheel.lazy.method:doSelect() diff --git a/src/extensions/cp/apple/finalcutpro/main/BackgroundTasksDialog.lua b/src/extensions/cp/apple/finalcutpro/main/BackgroundTasksDialog.lua index f882a8fbf..fcc7656af 100644 --- a/src/extensions/cp/apple/finalcutpro/main/BackgroundTasksDialog.lua +++ b/src/extensions/cp/apple/finalcutpro/main/BackgroundTasksDialog.lua @@ -20,10 +20,10 @@ local BackgroundTasksDialog = Dialog:subclass("cp.apple.finalcutpro.main.Backgro --- Checks if the element is an `BackgroundTasksDialog` instance. --- --- Parameters: ---- * element - The `axuielement` to check. +--- * element - The `axuielement` to check. --- --- Returns: ---- * `true` if it matches the pattern for a `BackgroundTasksDialog``. +--- * `true` if it matches the pattern for a `BackgroundTasksDialog``. function BackgroundTasksDialog.static.matches(element) if Dialog.matches(element) and #element == 6 then local backgroundTasksString = strings:find("FFTranscodeMissingOpticalFlowMessageText") @@ -38,6 +38,12 @@ end --- cp.apple.finalcutpro.main.BackgroundTasksDialog(cpApp) --- Constructor --- Creates a new Background Tasks [Dialog](cp.ui.Dialog.md) +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function BackgroundTasksDialog:initialize(cpApp) Dialog.initialize(self, cpApp, cpApp.UI:mutate(function(original) return cache(self, "_window", function() diff --git a/src/extensions/cp/apple/finalcutpro/main/FindAndReplaceTitleText.lua b/src/extensions/cp/apple/finalcutpro/main/FindAndReplaceTitleText.lua index 3d619c28c..49e62580a 100644 --- a/src/extensions/cp/apple/finalcutpro/main/FindAndReplaceTitleText.lua +++ b/src/extensions/cp/apple/finalcutpro/main/FindAndReplaceTitleText.lua @@ -37,6 +37,12 @@ end --- cp.apple.finalcutpro.main.FindAndReplaceTitleText(cpApp, upProp) --- Constructor --- Creates a new "Find and Replace Title Text" [Dialog](cp.ui.Dialog.md) +--- +--- Parameters: +--- * cpApp - The cpApp +--- +--- Returns: +--- * None function FindAndReplace:initialize(cpApp) Dialog.initialize(self, cpApp, cpApp.UI:mutate(function(original) return cache(self, "_window", function() @@ -169,6 +175,12 @@ end --- cp.apple.finalcutpro.main.FindAndReplaceTitleText:doShow() -> cp.rx.go.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will attempt to show the "Find And Replace Title Text" dialog. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function FindAndReplace.lazy.method:doShow() return If(self.isShowing):Is(false) :Then(self:app():doLaunch()) @@ -181,6 +193,12 @@ end --- cp.apple.finalcutpro.main.FindAndReplaceTitleText:doHide() -> cp.rx.go.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will attempt to hide the "Find And Replace Title Text" dialog. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function FindAndReplace.lazy.method:doHide() return If(self.isShowing) :Then(self:doClose()) @@ -232,6 +250,12 @@ end --- cp.apple.finalcutpro.main.FindAndReplaceTitleText:doFindAndReplaceAll(find, replace) -> cp.rx.go.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will attempt to find all titles containing `find` and replace them with `replace`. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function FindAndReplace:doFindAndReplaceAll(find, replace) return Do(self:app():doLaunch()) :Then( diff --git a/src/extensions/cp/apple/finalcutpro/main/LibrariesBrowser.lua b/src/extensions/cp/apple/finalcutpro/main/LibrariesBrowser.lua index e0dc680f8..a7d99f777 100644 --- a/src/extensions/cp/apple/finalcutpro/main/LibrariesBrowser.lua +++ b/src/extensions/cp/apple/finalcutpro/main/LibrariesBrowser.lua @@ -258,6 +258,12 @@ end --- cp.apple.finalcutpro.main.Browser.appearanceAndFiltering --- Method --- The Clip [AppearanceAndFiltering](cp.apple.finalcutpro.main.AppearanceAndFiltering.md) Menu Popover +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function LibrariesBrowser.lazy.value:appearanceAndFiltering() return AppearanceAndFiltering(self) end @@ -279,6 +285,12 @@ end --- cp.apple.finalcutpro.main.LibrariesBrowser.sidebar --- Method --- The [LibrariesSidebar](cp.apple.finalcutpro.main.LibrariesSidebar.md) Table +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function LibrariesBrowser.lazy.value:sidebar() return LibrariesSidebar(self) end diff --git a/src/extensions/cp/apple/finalcutpro/prefs/ImportPanel.lua b/src/extensions/cp/apple/finalcutpro/prefs/ImportPanel.lua index 1bd6c8a16..ae5dcba52 100644 --- a/src/extensions/cp/apple/finalcutpro/prefs/ImportPanel.lua +++ b/src/extensions/cp/apple/finalcutpro/prefs/ImportPanel.lua @@ -61,6 +61,12 @@ end --- cp.apple.finalcutpro.prefs.ImportPanel:toggleMediaLocation() -> boolean --- Method --- Toggles between the "Copy to library storage location" and "Leave files in place" options. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function ImportPanel:toggleMediaLocation() if self:show():isShowing() then if self:copyToLibraryStorageLocation():checked() then @@ -76,6 +82,12 @@ end --- cp.apple.finalcutpro.prefs.ImportPanel:toggleMediaLocation() -> cp.rx.go.Statement --- Method --- A `Statement` that toggles between the "Copy to library storage location" and "Leave files in place" options. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function ImportPanel.lazy.method:doToggleMediaLocation() return Do(self:doShow()) :Then( diff --git a/src/extensions/cp/apple/finalcutpro/timeline/AudioRole.lua b/src/extensions/cp/apple/finalcutpro/timeline/AudioRole.lua index 941c60c81..c7ed43924 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/AudioRole.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/AudioRole.lua @@ -20,6 +20,12 @@ local AudioRole = Role:subclass("cp.apple.finalcutpro.timeline.AudioRole") --- cp.apple.finalcutpro.timeline.AudioRole.matches(element) -> boolean --- Function --- Checks if the element is a "Audio" Role. +--- +--- Parameters: +--- * element - An element to check +--- +--- Returns: +--- * A boolean function AudioRole.static.matches(element) return Role.matches(element) and valueOf(element, "AXDisclosureLevel") == 0 @@ -73,6 +79,12 @@ end --- cp.apple.finalcutpro.timeline.AudioRole:doFocusInTimeline() -> cp.rx.go.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will attempt to focus on this audio role in the timeline. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function AudioRole.lazy.method:doFocusInTimeline() return self.focusedInTimeline:doCheck() end @@ -80,6 +92,12 @@ end --- cp.apple.finalcutpro.timeline.AudioRole:doUnfocusInTimeline() -> cp.rx.go.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will attempt to unfocus on this audio role in the timeline. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function AudioRole.lazy.method:doUnfocusInTimeline() return self.focusedInTimeline:doUncheck() end @@ -87,6 +105,12 @@ end --- cp.apple.finalcutpro.timeline.AudioRole:doShowSubroleLanes() -> cp.rx.go.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will attempt to show the subrole lanes on this audio role in the timeline. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function AudioRole.lazy.method:doShowSubroleLanes() return self.subroleLanes:doCheck() end @@ -94,6 +118,12 @@ end --- cp.apple.finalcutpro.timeline.AudioRole:doHideSubroleLanes() -> cp.rx.go.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will attempt to hide the subrole lanes on this audio role in the timeline. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function AudioRole.lazy.method:doHideSubroleLanes() return self.subroleLanes:doUncheck() end diff --git a/src/extensions/cp/apple/finalcutpro/timeline/AudioSubrole.lua b/src/extensions/cp/apple/finalcutpro/timeline/AudioSubrole.lua index 4de8a17fe..5af61b2b4 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/AudioSubrole.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/AudioSubrole.lua @@ -12,6 +12,12 @@ local AudioSubrole = Role:subclass("cp.apple.finalcutpro.timeline.AudioSubrole") --- cp.apple.finalcutpro.timeline.AudioSubrole.matches(element) -> boolean --- Function --- Checks if the element is a "Audio" Subrole. +--- +--- Parameters: +--- * element - An element to check +--- +--- Returns: +--- * A boolean function AudioSubrole.static.matches(element) return Role.matches(element) and AudioRole.matches(element:attributeValue("AXDisclosedByRow")) @@ -22,11 +28,11 @@ end --- Creates a new instance with the specified `parent` and `uiFinder`. --- --- Parameters: ---- * parent - the parent `Element`. ---- * uiFinder - a `function` or `cp.prop` containing the `axuielement` +--- * parent - the parent `Element`. +--- * uiFinder - a `function` or `cp.prop` containing the `axuielement` --- --- Returns: ---- * The new `Row`. +--- * The new `Row`. function AudioSubrole:initialize(parent, uiFinder) Role.initialize(self, parent, uiFinder, Role.TYPE.AUDIO) end diff --git a/src/extensions/cp/apple/finalcutpro/timeline/CaptionsRole.lua b/src/extensions/cp/apple/finalcutpro/timeline/CaptionsRole.lua index 612009bd8..93f555915 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/CaptionsRole.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/CaptionsRole.lua @@ -21,6 +21,12 @@ local CaptionsRole = Role:subclass("cp.apple.finalcutpro.timeline.CaptionsRole") --- cp.apple.finalcutpro.timeline.CaptionsRole.matches(element) -> boolean --- Function --- Checks if the element is a "Captions" Role. +--- +--- Parameters: +--- * element - The element to check +--- +--- Returns: +--- * A boolean function CaptionsRole.static.matches(element) return Role.matches(element) and valueOf(element, "AXDisclosureLevel") == 0 diff --git a/src/extensions/cp/apple/finalcutpro/timeline/CaptionsSubrole.lua b/src/extensions/cp/apple/finalcutpro/timeline/CaptionsSubrole.lua index f7ab338ce..3afeeca80 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/CaptionsSubrole.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/CaptionsSubrole.lua @@ -16,6 +16,12 @@ local CaptionsSubrole = Role:subclass("cp.apple.finalcutpro.timeline.CaptionsSub --- cp.apple.finalcutpro.timeline.CaptionsSubrole.matches(element) -> boolean --- Function --- Checks if the element is a "Captions" Subrole. +--- +--- Parameters: +--- * element - An element to check +--- +--- Returns: +--- * A boolean function CaptionsSubrole.static.matches(element) return Role.matches(element) and CaptionsRole.matches(element:attributeValue("AXDisclosedByRow")) @@ -26,11 +32,11 @@ end --- Creates a new instance with the specified `parent` and `uiFinder`. --- --- Parameters: ---- * parent - the parent `Element`. ---- * uiFinder - a `function` or `cp.prop` containing the `axuielement` +--- * parent - the parent `Element`. +--- * uiFinder - a `function` or `cp.prop` containing the `axuielement` --- --- Returns: ---- * The new `Row`. +--- * The new `Row`. function CaptionsSubrole:initialize(parent, uiFinder) Role.initialize(self, parent, uiFinder, Role.TYPE.CAPTION) end diff --git a/src/extensions/cp/apple/finalcutpro/timeline/Contents.lua b/src/extensions/cp/apple/finalcutpro/timeline/Contents.lua index 73f241a31..d04223e7a 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/Contents.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/Contents.lua @@ -157,6 +157,9 @@ end --- Method --- A [Statement](cp.rx.go.Statement.md) that will attempt to show the Timeline Contents. --- +--- Parameters: +--- * None +--- --- Returns: --- * The `Statement`. function Contents.lazy.method:doShow() @@ -173,6 +176,9 @@ end --- Method --- A [Statement](cp.rx.go.Statement.md) that will attempt to hide the Timeline Contents. --- +--- Parameters: +--- * None +--- --- Returns: --- * The `Statement`. function Contents.lazy.method:doHide() diff --git a/src/extensions/cp/apple/finalcutpro/timeline/Index.lua b/src/extensions/cp/apple/finalcutpro/timeline/Index.lua index 5cbfe2da3..511cf9abe 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/Index.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/Index.lua @@ -76,6 +76,12 @@ end --- cp.apple.finalcutpro.timeline.Index:doShow() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) which will show the Index if possible. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Statement function Index.lazy.method:doShow() return self:parent().toolbar.index:doCheck() end @@ -83,6 +89,12 @@ end --- cp.apple.finalcutpro.timeline.Index:doHide() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) which will hide the Index if possible. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Statement function Index.lazy.method:doHide() return self:parent().toolbar.index:doUncheck() end diff --git a/src/extensions/cp/apple/finalcutpro/timeline/IndexCaptions.lua b/src/extensions/cp/apple/finalcutpro/timeline/IndexCaptions.lua index 171603d21..c6f002061 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/IndexCaptions.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/IndexCaptions.lua @@ -55,8 +55,11 @@ end --- Method --- Returns a `table` containing the layout configuration for this class. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The layout configuration `table`. +--- * The layout configuration `table`. function IndexCaptions:saveLayout() return { showing = self:isShowing(), @@ -68,10 +71,10 @@ end --- Returns a [Statement](cp.rx.go.Statement.md) that will apply the layout provided, if possible. --- --- Parameters: ---- * layout - the `table` containing the layout configuration. Usually created via the [#saveLayout] method. +--- * layout - the `table` containing the layout configuration. Usually created via the [#saveLayout] method. --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md). +--- * The [Statement](cp.rx.go.Statement.md). function IndexCaptions:doLayout(layout) layout = layout or {} return If(layout.showing == true) diff --git a/src/extensions/cp/apple/finalcutpro/timeline/IndexClips.lua b/src/extensions/cp/apple/finalcutpro/timeline/IndexClips.lua index 963e75933..0f3ded1f0 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/IndexClips.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/IndexClips.lua @@ -1,6 +1,6 @@ --- === cp.apple.finalcutpro.timeline.IndexClips === --- ---- *Extends [IndexSection](cp.apple.finalcutpro.timeline.IndexSection.md)* +--- *Extends [IndexSection](cp.apple.finalcutpro.timeline.IndexSection.md)* --- --- Provides access to the 'Clips' section of the [Timeline Index](cp.apple.finalcutpro.timeline.Index.md) @@ -29,7 +29,7 @@ local IndexClips = IndexSection:subclass("cp.apple.finalcutpro.timeline.IndexCli --- Creates the `IndexClips` instance. --- --- Parameters: ---- * index - The [Index](cp.apple.finalcutpro.timeline.Index.md) instance. +--- * index - The [Index](cp.apple.finalcutpro.timeline.Index.md) instance. --- cp.apple.finalcutpro.timeline.IndexClips.activate --- Field @@ -92,10 +92,10 @@ end --- Checks if the `element` is the `IndexClips.Type` group. --- --- Parameters: ---- * element - The `axuielement` to check. +--- * element - The `axuielement` to check. --- --- Returns: ---- * `true` if it matches, otherwise `false`. +--- * `true` if it matches, otherwise `false`. function IndexClips.Type.static.matches(element) return RadioGroup.matches(element) and hasChild(element, function(child) @@ -172,6 +172,12 @@ end --- cp.apple.finalcutpro.timeline.IndexClips:doShowAll() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will set the clip index to "All" media types. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function IndexClips.lazy.method:doShowAll() return If(self:doShow()) :Then(self.all:doPress()) @@ -182,6 +188,12 @@ end --- cp.apple.finalcutpro.timeline.IndexClips:doShowVideo() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will set the clip index to "Video" media types. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function IndexClips.lazy.method:doShowVideo() return If(self:doShow()) :Then(self.video:doPress()) @@ -192,6 +204,12 @@ end --- cp.apple.finalcutpro.timeline.IndexClips:doShowAudio() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will set the clip index to "Audio" media types. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function IndexClips.lazy.method:doShowAudio() return If(self:doShow()) :Then(self.audio:doPress()) @@ -202,6 +220,12 @@ end --- cp.apple.finalcutpro.timeline.IndexClips:doShowTitles() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will set the clip index to "Titles" media types. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function IndexClips.lazy.method:doShowTitles() return If(self:doShow()) :Then(self.titles:doPress()) @@ -214,13 +238,13 @@ end --- Returns a [Statement](cp.go.rx.Statement.md) that will use the index to search for clips containing the specified text. --- --- Parameters: ---- * text - The text to search for. +--- * text - The text to search for. --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md) +--- * The [Statement](cp.rx.go.Statement.md) --- --- Notes: ---- * Because the `text` can change each time, this result is not cached automatically. However as long as you are searching for the same text the result can be safely cached. The [#toFindMissingMedia] method does this, for example. +--- * Because the `text` can change each time, this result is not cached automatically. However as long as you are searching for the same text the result can be safely cached. The [#toFindMissingMedia] method does this, for example. function IndexClips:doFindClipsContaining(text) return If(self:doShowClips()) :Then(function() @@ -235,6 +259,12 @@ end --- cp.apple.finalcutpro.timeline.IndexClips:doFindMissingMedia() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will use the index to search for all "Missing Media". +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function IndexClips.lazy.method:doFindMissingMedia() return self:doFindClipsContaining(strings:find("FFTimelineIndexMissingMediaSearch")) :Label("IndexClips:doFindMissingMedia") @@ -243,6 +273,12 @@ end --- cp.apple.finalcutpro.timeline.IndexClips:doFindAuditions() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will use the index to search for all "Auditions". +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function IndexClips.lazy.method:doFindAuditions() return self:doFindClipsContaining(strings:find("FFOrganizerFilterHUDClipTypeAudition")) :Label("IndexClips:doFindAuditions") @@ -251,6 +287,12 @@ end --- cp.apple.finalcutpro.timeline.IndexClips:doFindMulticams() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will use the index to search for all "Multicam" clips. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function IndexClips.lazy.method:doFindMulticams() return self:doFindClipsContaining(strings:find("FFOrganizerFilterHUDClipTypeMultiCam")) :Label("IndexClips:doFindMulticams") @@ -259,6 +301,12 @@ end --- cp.apple.finalcutpro.timeline.IndexClips:doFindCompoundClips() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will use the index to search for all "Compound Clips". +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function IndexClips.lazy.method:doFindCompoundClips() return self:doFindClipsContaining(strings:find("FFOrganizerFilterHUDClipTypeCompound")) :Label("IndexClips:doFindCompoundClips") @@ -267,6 +315,12 @@ end --- cp.apple.finalcutpro.timeline.IndexClips:doFindSynchronized() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will use the index to search for all "Synchronized" Clips. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function IndexClips.lazy.method:doFindSynchronized() return self:doFindClipsContaining(strings:find("FFOrganizerFilterHUDClipTypeSynchronized")) :Label("IndexClips:doFindSynchronized") @@ -276,8 +330,11 @@ end --- Method --- Returns a `table` containing the layout configuration for this class. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The layout configuration `table`. +--- * The layout configuration `table`. function IndexClips:saveLayout() return { showing = self:isShowing(), @@ -293,10 +350,10 @@ end --- Returns a [Statement](cp.rx.go.Statement.md) that will apply the layout provided, if possible. --- --- Parameters: ---- * layout - the `table` containing the layout configuration. Usually created via the [#saveLayout] method. +--- * layout - the `table` containing the layout configuration. Usually created via the [#saveLayout] method. --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md). +--- * The [Statement](cp.rx.go.Statement.md). function IndexClips:doLayout(layout) layout = layout or {} return If(layout.showing == true) diff --git a/src/extensions/cp/apple/finalcutpro/timeline/IndexRoles.lua b/src/extensions/cp/apple/finalcutpro/timeline/IndexRoles.lua index 1c191dece..d37477a5d 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/IndexRoles.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/IndexRoles.lua @@ -120,6 +120,12 @@ end --- cp.apple.finalcutpro.timeline.IndexRoles:doShowAudioLanes() -> cp.rx.go.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will show the Audio Lanes when executed. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function IndexRoles.lazy.method:doShowAudioLanes() local show = self.showAudioLanes return Do(self:doShow()) @@ -130,6 +136,12 @@ end --- cp.apple.finalcutpro.timeline.IndexRoles:doCollapseSubroles() -> cp.rx.go.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will collapse subroles, if they are currently expanded. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function IndexRoles.lazy.method:doCollapseSubroles() local collapse = self.collapseSubroles return Do(self:doShow()) @@ -140,6 +152,12 @@ end --- cp.apple.finalcutpro.timeline.IndexRoles:doHideAudioLanes() -> cp.rx.go.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will collapse subroles (if necessary) and hide the audio lanes. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function IndexRoles.lazy.method:doHideAudioLanes() local hide = self.hideAudioLanes return Do(self:doShow()) @@ -152,8 +170,11 @@ end --- Method --- Returns a `table` containing the layout configuration for this class. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The layout configuration `table`. +--- * The layout configuration `table`. function IndexRoles:saveLayout() return { showing = self:isShowing(), @@ -167,10 +188,10 @@ end --- Returns a [Statement](cp.rx.go.Statement.md) that will apply the layout provided, if possible. --- --- Parameters: ---- * layout - the `table` containing the layout configuration. Usually created via the [#saveLayout] method. +--- * layout - the `table` containing the layout configuration. Usually created via the [#saveLayout] method. --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md). +--- * The [Statement](cp.rx.go.Statement.md). function IndexRoles:doLayout(layout) layout = layout or {} return If(layout.showing == true) @@ -190,10 +211,10 @@ end --- Finds all Roles, optionally including all Subroles --- --- Parameters: ---- * includeSubroles - (defaults to `false`) if `true` include subroles. +--- * includeSubroles - (defaults to `false`) if `true` include subroles. --- --- Returns: ---- * The table of [Role](cp.apple.finalcutpro.timeline.Role.md)s, or `nil` if no UI is available. +--- * The table of [Role](cp.apple.finalcutpro.timeline.Role.md)s, or `nil` if no UI is available. function IndexRoles:allRoles(includeSubroles) return self.list:allRoles(includeSubroles) end @@ -203,10 +224,10 @@ end --- Finds all Video Roles, optionally including all Subroles --- --- Parameters: ---- * includeSubroles - (defaults to `false`) if `true` include subroles. +--- * includeSubroles - (defaults to `false`) if `true` include subroles. --- --- Returns: ---- * The table of [Role](cp.apple.finalcutpro.timeline.Role.md)s, or `nil` if no UI is available. +--- * The table of [Role](cp.apple.finalcutpro.timeline.Role.md)s, or `nil` if no UI is available. function IndexRoles:videoRoles(includeSubroles) return self.list:videoRoles(includeSubroles) end @@ -216,10 +237,10 @@ end --- Finds all Audio Roles, optionally including all Subroles --- --- Parameters: ---- * includeSubroles - (defaults to `false`) if `true` include subroles. +--- * includeSubroles - (defaults to `false`) if `true` include subroles. --- --- Returns: ---- * The table of [Role](cp.apple.finalcutpro.timeline.Role.md)s, or `nil` if no UI is available. +--- * The table of [Role](cp.apple.finalcutpro.timeline.Role.md)s, or `nil` if no UI is available. function IndexRoles:audioRoles(includeSubroles) return self.list:audioRoles(includeSubroles) end @@ -229,10 +250,10 @@ end --- Finds all Caption Roles, optionally including all Subroles --- --- Parameters: ---- * includeSubroles - (defaults to `false`) if `true` include subroles. +--- * includeSubroles - (defaults to `false`) if `true` include subroles. --- --- Returns: ---- * The table of [Role](cp.apple.finalcutpro.timeline.Role.md)s, or `nil` if no UI is available. +--- * The table of [Role](cp.apple.finalcutpro.timeline.Role.md)s, or `nil` if no UI is available. function IndexRoles:captionRoles(includeSubroles) return self.list:captionRoles(includeSubroles) end @@ -242,13 +263,13 @@ end --- Finds the [Role](cp.apple.finalcutpro.timeline.Role.md) with the specified title. --- --- Parameters: ---- * title - The title to match. +--- * title - The title to match. --- --- Returns: ---- * The [Role](cp.apple.finalcutpro.timeline.Role.md) with the title, or `nil`. +--- * The [Role](cp.apple.finalcutpro.timeline.Role.md) with the title, or `nil`. --- --- Notes: ---- * The title can be the English name (eg. "Video", "Titles", etc.) for default Roles, and it will find the correct role in the current FCPX language. +--- * The title can be the English name (eg. "Video", "Titles", etc.) for default Roles, and it will find the correct role in the current FCPX language. function IndexRoles:findRoleTitled(title) return self.list:findRoleTitled(title) end @@ -259,13 +280,13 @@ end --- This will automatically show and hide the Index if it is not currently visible. --- --- Parameters: ---- * The title of the [Role](cp.apple.finalcutpro.timeline.Role.md) to activate. +--- * The title of the [Role](cp.apple.finalcutpro.timeline.Role.md) to activate. --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md) +--- * The [Statement](cp.rx.go.Statement.md) --- --- Notes: ---- * The title can be the English name (eg. "Video", "Titles", etc.) for default Roles, and it will find the correct role in the current FCPX language. +--- * The title can be the English name (eg. "Video", "Titles", etc.) for default Roles, and it will find the correct role in the current FCPX language. function IndexRoles:doActivate(title) return Do(self.index:doStoreLayout("doActivate")) :Then(self:doShow()) @@ -280,13 +301,13 @@ end --- This will automatically show and hide the Index if it is not currently visible. --- --- Parameters: ---- * The title of the [Role](cp.apple.finalcutpro.timeline.Role.md) to activate. +--- * The title of the [Role](cp.apple.finalcutpro.timeline.Role.md) to activate. --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md) +--- * The [Statement](cp.rx.go.Statement.md) --- --- Notes: ---- * The title can be the English name (eg. "Video", "Titles", etc.) for default Roles, and it will find the correct role in the current FCPX language. +--- * The title can be the English name (eg. "Video", "Titles", etc.) for default Roles, and it will find the correct role in the current FCPX language. function IndexRoles:doDeactivate(title) return Do(self.index:doStoreLayout("doDeactivate")) :Then(self:doShow()) @@ -310,13 +331,13 @@ end --- This will automatically show and hide the Index if it is not currently visible. --- --- Parameters: ---- * The title of the [Role](cp.apple.finalcutpro.timeline.Role.md) to activate. +--- * The title of the [Role](cp.apple.finalcutpro.timeline.Role.md) to activate. --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md) +--- * The [Statement](cp.rx.go.Statement.md) --- --- Notes: ---- * The title can be the English name (eg. "Dialogue", "Music", etc.) for default Roles, and it will find the correct role in the current FCPX language. +--- * The title can be the English name (eg. "Dialogue", "Music", etc.) for default Roles, and it will find the correct role in the current FCPX language. function IndexRoles:doFocusInTimeline(title) return Do(self:_doStoreIndexLayout()) :Then(self:doShow()) @@ -331,13 +352,13 @@ end --- This will automatically show and hide the Index if it is not currently visible. --- --- Parameters: ---- * The title of the [Role](cp.apple.finalcutpro.timeline.Role.md) to activate. +--- * The title of the [Role](cp.apple.finalcutpro.timeline.Role.md) to activate. --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md) +--- * The [Statement](cp.rx.go.Statement.md) --- --- Notes: ---- * The title can be the English name (eg. "Dialogue", "Music", etc.) for default Roles, and it will find the correct role in the current FCPX language. +--- * The title can be the English name (eg. "Dialogue", "Music", etc.) for default Roles, and it will find the correct role in the current FCPX language. function IndexRoles:doUnfocusInTimeline(title) return Do(self:_doStoreIndexLayout()) :Then(self:doShow()) @@ -352,13 +373,13 @@ end --- This will automatically show and hide the Index if it is not currently visible. --- --- Parameters: ---- * The title of the [Role](cp.apple.finalcutpro.timeline.Role.md). +--- * The title of the [Role](cp.apple.finalcutpro.timeline.Role.md). --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md) +--- * The [Statement](cp.rx.go.Statement.md) --- --- Notes: ---- * The title can be the English name (eg. "Dialogue", "Music", etc.) for default Roles, and it will find the correct role in the current FCPX language. +--- * The title can be the English name (eg. "Dialogue", "Music", etc.) for default Roles, and it will find the correct role in the current FCPX language. function IndexRoles:doShowSubroleLanes(title) return Do(self:_doStoreIndexLayout()) :Then(self:doShow()) @@ -373,13 +394,13 @@ end --- This will automatically show and hide the Index if it is not currently visible. --- --- Parameters: ---- * The title of the [Role](cp.apple.finalcutpro.timeline.Role.md). +--- * The title of the [Role](cp.apple.finalcutpro.timeline.Role.md). --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md) +--- * The [Statement](cp.rx.go.Statement.md) --- --- Notes: ---- * The title can be the English name (eg. "Dialogue", "Music", etc.) for default Roles, and it will find the correct role in the current FCPX language. +--- * The title can be the English name (eg. "Dialogue", "Music", etc.) for default Roles, and it will find the correct role in the current FCPX language. function IndexRoles:doHideSubroleLanes(title) return Do(self:_doStoreIndexLayout()) :Then(self:doShow()) diff --git a/src/extensions/cp/apple/finalcutpro/timeline/IndexSection.lua b/src/extensions/cp/apple/finalcutpro/timeline/IndexSection.lua index da539a41a..995eadd7a 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/IndexSection.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/IndexSection.lua @@ -32,6 +32,12 @@ end --- cp.apple.finalcutpro.timeline.IndexSection:parent() -> cp.apple.finalcutpro.timeline.Index --- Method --- The parent index. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * The parent index. function IndexSection:parent() return self.index end @@ -39,6 +45,12 @@ end --- cp.apple.finalcutpro.timeline.IndexSection:app() -> cp.apple.finalcutpro --- Method --- The [Final Cut Pro](cp.apple.finalcutpro.md) instance. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * The [Final Cut Pro](cp.apple.finalcutpro.md) instance. function IndexSection:app() return self:parent():app() end @@ -81,6 +93,9 @@ end --- Method --- A [Statement](cp.rx.go.Statement.md) that will show the Clips section in the Timeline Index, if possible. --- +--- Parameters: +--- * None +--- --- Returns: --- * The [Statement](cp.rx.go.Statement.md) function IndexSection.lazy.method:doShow() @@ -98,6 +113,12 @@ end --- cp.apple.finalcutpro.timeline.IndexSection:doActivateSearch() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will show the Clips in the Timeline Index and focus on the Search field. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Returns a [Statement](cp.rx.go.Statement.md) function IndexSection.lazy.method:doActivateSearch() return If(self:doShow()) :Then(self.search:doFocus()) diff --git a/src/extensions/cp/apple/finalcutpro/timeline/IndexTags.lua b/src/extensions/cp/apple/finalcutpro/timeline/IndexTags.lua index c869f38ff..e0696f38e 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/IndexTags.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/IndexTags.lua @@ -69,10 +69,10 @@ IndexTags.static.Type = RadioGroup:subclass("cp.apple.finalcutpro.timeline.Index --- Checks if the `element` is the `IndexTags.Type` group. --- --- Parameters: ---- * element - The `axuielement` to check. +--- * element - The `axuielement` to check. --- --- Returns: ---- * `true` if it matches, otherwise `false`. +--- * `true` if it matches, otherwise `false`. function IndexTags.Type.static.matches(element) return RadioGroup.matches(element) and #element == 6 end @@ -194,6 +194,12 @@ end --- cp.apple.finalcutpro.timeline.IndexTags:doShowAll() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will set the tag index to "All" media types. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Statement function IndexTags.lazy.method:doShowAll() return If(self:doShow()) :Then(self.all:doPress()) @@ -204,6 +210,12 @@ end --- cp.apple.finalcutpro.timeline.IndexTags:doShowStandardMarkers() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will set the tag index to "Standard" markers. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Statement function IndexTags.lazy.method:doShowStandardMarkers() return If(self:doShow()) :Then(self.standardMarkers:doPress()) @@ -214,6 +226,12 @@ end --- cp.apple.finalcutpro.timeline.IndexTags:doShowKeywords() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will set the tag index to "Keywords". +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Statement function IndexTags.lazy.method:doShowKeywords() return If(self:doShow()) :Then(self.keywords:doPress()) @@ -224,6 +242,12 @@ end --- cp.apple.finalcutpro.timeline.IndexTags:doShowAnalysisKeywords() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will set the tag index to "Analysis Keywords". +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Statement function IndexTags.lazy.method:doShowAnalysisKeywords() return If(self:doShow()) :Then(self.analysisKeywords:doPress()) @@ -234,6 +258,12 @@ end --- cp.apple.finalcutpro.timeline.IndexTags:doShowIncompleteTodos() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will set the tag index to "Incomplete Todo Markers". +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Statement function IndexTags.lazy.method:doShowIncompleteTodos() return If(self:doShow()) :Then(self.incompleteTodos:doPress()) @@ -244,6 +274,12 @@ end --- cp.apple.finalcutpro.timeline.IndexTags:doShowCompleteTodos() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will set the tag index to "Complete Todos". +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Statement function IndexTags.lazy.method:doShowCompleteTodos() return If(self:doShow()) :Then(self.completeTodos:doPress()) @@ -254,6 +290,12 @@ end --- cp.apple.finalcutpro.timeline.IndexTags:doShowChapters() -> cp.rx.go.Statement --- Method --- Returns a [Statement](cp.rx.go.Statement.md) that will set the tag index to "Chapter" markers. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Statement function IndexTags.lazy.method:doShowChapters() return If(self:doShow()) :Then(self.chapters:doPress()) @@ -265,8 +307,11 @@ end --- Method --- Returns a `table` containing the layout configuration for this class. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The layout configuration `table`. +--- * The layout configuration `table`. function IndexTags:saveLayout() return { showing = self:isShowing(), @@ -285,10 +330,10 @@ end --- Returns a [Statement](cp.rx.go.Statement.md) that will apply the layout provided, if possible. --- --- Parameters: ---- * layout - the `table` containing the layout configuration. Usually created via the [#saveLayout] method. +--- * layout - the `table` containing the layout configuration. Usually created via the [#saveLayout] method. --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md). +--- * The [Statement](cp.rx.go.Statement.md). function IndexTags:doLayout(layout) layout = layout or {} return If(layout.showing == true) diff --git a/src/extensions/cp/apple/finalcutpro/timeline/Role.lua b/src/extensions/cp/apple/finalcutpro/timeline/Role.lua index 6a73b8dd4..188ae5952 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/Role.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/Role.lua @@ -89,6 +89,12 @@ end --- Checks if FCPX is not currently running in English, it will check if the title is one --- of the default English Role titles, and return the current language instead. If it's not found, --- unmodified `title` is returned. +--- +--- Parameters: +--- * title - A string to find. +--- +--- Returns: +--- * A string function Role.findTitle(title) local fcpLocale = fcpApp:currentLocale() if en:matches(fcpLocale) == 0 then -- not in english @@ -126,6 +132,12 @@ end --- cp.apple.finalcutpro.timeline.Role:type() -> cp.apple.finalcut.timeline.Role.TYPE --- Method --- Returns the type of Role this is. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Role Type function Role:type() return self._type end @@ -169,6 +181,12 @@ end --- cp.apple.finalcutpro.timeline.Role:doActivate() -> cp.rx.go.Statement.md --- Method --- A [Statement](cp.rx.go.Statement.md) that will activate the current role, if possible. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Statement function Role.lazy.method:doActivate() return self.active:doCheck() end @@ -176,6 +194,12 @@ end --- cp.apple.finalcutpro.timeline.Role:doDeactivate() -> cp.rx.go.Statement.md --- Method --- A [Statement](cp.rx.go.Statement.md) that will deactivate the current role, if possible. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Statement function Role.lazy.method:doDeactivate() return self.active:doUncheck() end diff --git a/src/extensions/cp/apple/finalcutpro/timeline/SpeedPopover.lua b/src/extensions/cp/apple/finalcutpro/timeline/SpeedPopover.lua index ef3567efd..a3ef6225d 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/SpeedPopover.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/SpeedPopover.lua @@ -1,6 +1,6 @@ --- === cp.apple.finalcutpro.timeline.SpeedPopover == --- ---- *Extends [Timeline](cp.apple.finalcutpro.timeline.md)* +--- *Extends [Timeline](cp.apple.finalcutpro.timeline.md)* --- --- Represents the Speed Popover. @@ -31,6 +31,12 @@ local SpeedPopover = Popover:subclass("cp.apple.finalcutpro.timeline.SpeedPopove --- cp.apple.finalcutpro.timeline.SpeedPopover.matches(element) -> boolean --- Function --- Checks if the element is a "Video" Role. +--- +--- Parameters: +--- * element - An element to check +--- +--- Returns: +--- * A boolean function SpeedPopover.static.matches(element) return Popover.matches(element) and childWith(element, "AXValue", strings:find("FFHeliumXFormCustomSpeed")) @@ -41,11 +47,11 @@ end --- Creates a new instance with the specified `parent` and `uiFinder`. --- --- Parameters: ---- * parent - the parent `Element`. ---- * uiFinder - a `function` or `cp.prop` containing the `axuielement` +--- * parent - the parent `Element`. +--- * uiFinder - a `function` or `cp.prop` containing the `axuielement` --- --- Returns: ---- * The new `SpeedPopover`. +--- * The new `SpeedPopover`. function SpeedPopover:initialize(timeline) local uiFinder = timeline.UI:mutate(function(original) return cache(self, "_ui", function() diff --git a/src/extensions/cp/apple/finalcutpro/timeline/Timeline.lua b/src/extensions/cp/apple/finalcutpro/timeline/Timeline.lua index c2e463f22..563949b7d 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/Timeline.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/Timeline.lua @@ -201,6 +201,12 @@ end --- cp.apple.finalcutpro.timeline.Timeline:doFocus() -> cp.rx.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will attempt to focus on the Timeline. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function Timeline.lazy.method:doFocus() return self:app().menu:doSelectMenu({"Window", "Go To", "Timeline"}) end diff --git a/src/extensions/cp/apple/finalcutpro/timeline/VideoRole.lua b/src/extensions/cp/apple/finalcutpro/timeline/VideoRole.lua index d99156966..4564e1461 100644 --- a/src/extensions/cp/apple/finalcutpro/timeline/VideoRole.lua +++ b/src/extensions/cp/apple/finalcutpro/timeline/VideoRole.lua @@ -21,6 +21,12 @@ local VideoRole = Role:subclass("cp.apple.finalcutpro.timeline.VideoRole") --- cp.apple.finalcutpro.timeline.VideoRole.matches(element) -> boolean --- Function --- Checks if the element is a "Video" Role. +--- +--- Parameters: +--- * element - An element to check +--- +--- Returns: +--- * A boolean function VideoRole.static.matches(element) return Role.matches(element) and valueOf(element, "AXDisclosureLevel") == 0 @@ -32,11 +38,11 @@ end --- Creates a new instance with the specified `parent` and `uiFinder`. --- --- Parameters: ---- * parent - the parent `Element`. ---- * uiFinder - a `function` or `cp.prop` containing the `axuielement` +--- * parent - the parent `Element`. +--- * uiFinder - a `function` or `cp.prop` containing the `axuielement` --- --- Returns: ---- * The new `Row`. +--- * The new `Row`. function VideoRole:initialize(parent, uiFinder) Role.initialize(self, parent, uiFinder, Role.TYPE.VIDEO) end @@ -46,7 +52,7 @@ end --- A [Button](cp.ui.Button.md) that toggles whether the sub-captions are visible. --- --- Note: ---- * This [Button](cp.ui.Button.md) is only visible when the pointer is hovering over the Role. +--- * This [Button](cp.ui.Button.md) is only visible when the pointer is hovering over the Role. function VideoRole.lazy.value:subrolesExpanded() return Button(self, self.cellUI:mutate(function(original) return childFromLeft(original(), 1, Button.matches) diff --git a/src/extensions/cp/commands/init.lua b/src/extensions/cp/commands/init.lua index f1d5a61be..e0fb8ee12 100644 --- a/src/extensions/cp/commands/init.lua +++ b/src/extensions/cp/commands/init.lua @@ -42,7 +42,7 @@ commands._groups = {} --- Returns an array of IDs of command groups which have been created. --- --- Parameters: ---- * None +--- * None --- --- Returns: --- * `table` - The array of group IDs. @@ -59,7 +59,7 @@ end --- Creates a collection of commands. These commands can be enabled or disabled as a group. --- --- Parameters: ---- * `id` - The ID to retrieve +--- * `id` - The ID to retrieve --- --- Returns: --- * `cp.commands` - The command group with the specified ID, or `nil` if none exists. @@ -72,7 +72,7 @@ end --- Returns a table with the set of commands. --- --- Parameters: ---- * `id` - The ID to retrieve +--- * `id` - The ID to retrieve --- --- Returns: --- * `cp.commands` - The command group with the specified ID, or `nil` if none exists. @@ -127,10 +127,10 @@ end --- Returns the unique ID of the command group. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * The command group ID string. +--- * The command group ID string. function commands.mt:id() return self._id end @@ -145,10 +145,10 @@ end --- ``` --- --- Parameters: ---- * `commandId` - The unique ID for the new command. +--- * `commandId` - The unique ID for the new command. --- --- Returns: ---- * The new `cp.commands.command` instance. +--- * The new `cp.commands.command` instance. function commands.mt:add(commandId) local cmd = command.new(commandId, self) self._commands[commandId] = cmd @@ -162,10 +162,10 @@ end --- Returns the command with the specified ID, or `nil` if none exists. --- --- Parameters: ---- * `commandId` - The command ID to retrieve. +--- * `commandId` - The command ID to retrieve. --- --- Returns: ---- * The `cp.commands.command`, or `nil`. +--- * The `cp.commands.command`, or `nil`. function commands.mt:get(commandId) return self._commands[commandId] end @@ -179,6 +179,12 @@ end --- ... --- end --- ``` +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A table function commands.mt:getAll() return self._commands end @@ -188,10 +194,10 @@ end --- Clears all commands and their shortcuts. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * The command group instance. +--- * The command group instance. function commands.mt:clear() self:deleteShortcuts() self._commands = {} @@ -203,10 +209,10 @@ end --- Clears all shortcuts associated with commands in this command group. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * The command group instance. +--- * The command group instance. function commands.mt:deleteShortcuts() for _,cmd in pairs(self._commands) do cmd:deleteShortcuts() @@ -219,10 +225,10 @@ end --- Enables the command group. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * The command group instance. +--- * The command group instance. function commands.mt:enable() self:isEnabled(true) return self @@ -233,10 +239,10 @@ end --- Disables the command group. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * The command group instance. +--- * The command group instance. function commands.mt:disable() self:isEnabled(false) return self @@ -247,17 +253,17 @@ end --- Adds an event watcher to the command group. --- --- Parameters: ---- * events - The table of events to watch for (see Notes). +--- * events - The table of events to watch for (see Notes). --- --- Returns: ---- * The command group instance. +--- * The command group instance. --- --- Notes: ---- * The table can have properties with the following functions, which will be called for the specific event: ---- ** `add(command)`: Called after the provided `cp.commands.command` instance has been added. ---- ** `activate()` Called when the command group is activated. ---- ** `enable()`: Called when the command group is enabled. ---- ** `disable()`: Called when the command group is disabled. +--- * The table can have properties with the following functions, which will be called for the specific event: +--- ** `add(command)`: Called after the provided `cp.commands.command` instance has been added. +--- ** `activate()` Called when the command group is activated. +--- ** `enable()`: Called when the command group is enabled. +--- ** `disable()`: Called when the command group is disabled. function commands.mt:watch(events) if not self.watchers then self.watchers = {} @@ -292,11 +298,11 @@ end --- command group is not enabled within 5 seconds. --- --- Parameters: ---- * successFn - the function to call if successfully activated. ---- * failureFn - the function to call if not activated after 5 seconds. +--- * successFn - the function to call if successfully activated. +--- * failureFn - the function to call if not activated after 5 seconds. --- --- Returns: ---- * Nothing. +--- * Nothing. commands._count = 0 function commands.mt:activate(successFn, failureFn) self:_notify('activate') @@ -326,10 +332,10 @@ end --- for all contained `cp.commands.command` instances. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * The table of shortcuts for commands. +--- * The table of shortcuts for commands. function commands.mt:saveShortcuts() local data = {} @@ -352,10 +358,10 @@ end --- The data should probably come from the `saveShortcuts` method. --- --- Parameters: ---- * data - The data table containing shortcuts. +--- * data - The data table containing shortcuts. --- --- Returns: ---- * Nothing +--- * Nothing function commands.mt:loadShortcuts(data) self:deleteShortcuts() for id,commandData in pairs(data) do @@ -371,6 +377,12 @@ end --- cp.commands.getShortcutsPath(name) -> string --- Function --- Returns the path to the named shortcut set. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A string function commands.getShortcutsPath(name) local shortcutsPath = config.userConfigRootPath .. "/Shortcuts/" @@ -392,10 +404,10 @@ end --- Loads a shortcut set from the standard location with the specified name. --- --- Parameters: ---- * name - The name of the shortcut set. E.g. "My Custom Shortcuts" +--- * name - The name of the shortcut set. E.g. "My Custom Shortcuts" --- --- Returns: ---- * `true` if the file was found and loaded successfully. +--- * `true` if the file was found and loaded successfully. function commands.loadFromFile(name) local groupData @@ -444,10 +456,10 @@ end --- Saves the current shortcuts for all groups to a file in the standard location with the provided name. --- --- Parameters: ---- * name - The name of the command set. E.g. "My Custom Commands" +--- * name - The name of the command set. E.g. "My Custom Commands" --- --- Returns: ---- * `true` if the shortcuts were saved successfully. +--- * `true` if the shortcuts were saved successfully. function commands.saveToFile(name) -------------------------------------------------------------------------------- -- Get the shortcuts: diff --git a/src/extensions/cp/rx.lua b/src/extensions/cp/rx.lua index 81c5c38e0..a2ad9edc5 100644 --- a/src/extensions/cp/rx.lua +++ b/src/extensions/cp/rx.lua @@ -4,8 +4,8 @@ --- --- RxLua gives Lua the power of Observables, which are data structures that represent a stream of values that arrive over time. They're very handy when dealing with events, streams of data, asynchronous requests, and concurrency. --- ---- * Originally forked from: https://github.com/bjornbytes/rxlua ---- * MIT License: https://github.com/bjornbytes/RxLua/blob/master/LICENSE +--- * Originally forked from: https://github.com/bjornbytes/rxlua +--- * MIT License: https://github.com/bjornbytes/RxLua/blob/master/LICENSE local require = require @@ -79,10 +79,10 @@ Reference.__tostring = util.constant('Reference') --- Creates a new Reference. --- --- Parameters: ---- * action - The action to run when the reference is canceld. It will only be run once. +--- * action - The action to run when the reference is canceld. It will only be run once. --- --- Returns: ---- * the [Reference](cp.rx.Reference.md). +--- * the [Reference](cp.rx.Reference.md). function Reference.create(action) local self = { action = action or util.noop, @@ -97,10 +97,10 @@ end --- Unsubscribes the reference, performing any necessary cleanup work. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * Nothing +--- * Nothing function Reference:cancel() if self.cancelled then return end self.action(self) @@ -119,10 +119,10 @@ Observer.__tostring = util.constant('Observer') --- Tests if the `thing` is an `Observer`. --- --- Parameters: ---- * thing - The thing to test. +--- * thing - The thing to test. --- --- Returns: ---- * `true` if the thing is an `Observer`, otherwise `false`. +--- * `true` if the thing is an `Observer`, otherwise `false`. function Observer.is(thing) return util.isa(thing, Observer) end @@ -132,12 +132,12 @@ end --- Creates a new Observer. --- --- Parameters: ---- * onNext - Called when the Observable produces a value. ---- * onError - Called when the Observable terminates due to an error. ---- * onCompleted - Called when the Observable completes normally. +--- * onNext - Called when the Observable produces a value. +--- * onError - Called when the Observable terminates due to an error. +--- * onCompleted - Called when the Observable completes normally. --- --- Returns: ---- * The new Observer. +--- * The new Observer. function Observer.create(onNext, onError, onCompleted) local self = { _onNext = onNext or util.noop, @@ -154,10 +154,10 @@ end --- Pushes zero or more values to the Observer. --- --- Parameters: ---- * ... - The list of values to send. +--- * ... - The list of values to send. --- --- Returns: ---- * Nothing +--- * Nothing function Observer:onNext(...) if not self.stopped then self._onNext(...) @@ -169,10 +169,10 @@ end --- Notify the Observer that an error has occurred. --- --- Parameters: ---- * message - A string describing what went wrong. +--- * message - A string describing what went wrong. --- --- Returns: ---- * Nothing +--- * Nothing function Observer:onError(message) if not self.stopped then self.stopped = true @@ -185,10 +185,10 @@ end --- Notify the Observer that the sequence has completed and will produce no more values. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * Nothing +--- * Nothing function Observer:onCompleted() if not self.stopped then self.stopped = true @@ -208,10 +208,10 @@ Observable.__tostring = util.constant('Observable') --- Checks if the thing is an instance of [Observable](cp.rx.Observable.md). --- --- Parameters: ---- * thing - The thing to check. +--- * thing - The thing to check. --- --- Returns: ---- * `true` if the thing is an `Observable`. +--- * `true` if the thing is an `Observable`. function Observable.is(thing) return util.isa(thing, Observable) end @@ -221,10 +221,10 @@ end --- Creates a new Observable. --- --- Parameters: ---- * onSubscription - The reference function that produces values. +--- * onSubscription - The reference function that produces values. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.create(onSubscription) local self = { _subscribe = onSubscription @@ -238,12 +238,12 @@ end --- Shorthand for creating an [Observer](cp.rx.Observer.md) and passing it to this Observable's [subscription](#subscri) function. --- --- Parameters: ---- * observer | onNext - Either an [Observer](cp.rx.Observer.md) or a `function` to be called when the Observable produces a value. ---- * onError - A `function` to be called when the Observable terminates due to an error. ---- * onCompleted - A 'function` to be called when the Observable completes normally. +--- * observer | onNext - Either an [Observer](cp.rx.Observer.md) or a `function` to be called when the Observable produces a value. +--- * onError - A `function` to be called when the Observable terminates due to an error. +--- * onCompleted - A 'function` to be called when the Observable completes normally. --- --- Returns: ---- * A [Reference](cp.rx.Reference.md) which can be used to cancel the subscription. +--- * A [Reference](cp.rx.Reference.md) which can be used to cancel the subscription. function Observable:subscribe(onNext, onError, onCompleted) if Observer.is(onNext) then return self._subscribe(onNext) @@ -257,10 +257,10 @@ end --- Returns an Observable that immediately completes without producing a value. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.empty() return Observable.create(function(observer) observer:onCompleted() @@ -272,10 +272,10 @@ end --- Returns an Observable that never produces values and never completes. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.never() return Observable.create(function(_) end) end @@ -285,11 +285,11 @@ end --- Returns an Observable that immediately produces an error. --- --- Parameters: ---- * message - The message to send. ---- * ... - The additional values to apply to the message, using `string.format` syntax. +--- * message - The message to send. +--- * ... - The additional values to apply to the message, using `string.format` syntax. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.throw(message, ...) if select("#", ...) > 0 then message = string.format(message, ...) @@ -304,10 +304,10 @@ end --- Creates an Observable that produces a set of values. --- --- Parameters: ---- * ... - The list of values to send as individual `onNext` values. +--- * ... - The list of values to send as individual `onNext` values. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.of(...) local args = {...} local argCount = select('#', ...) @@ -325,12 +325,12 @@ end --- Creates an Observable that produces a range of values in a manner similar to a Lua `for` loop. --- --- Parameters: ---- * initial - The first value of the range, or the upper limit if no other arguments are specified. ---- * limit - The second value of the range. Defaults to no limit. ---- * step - An amount to increment the value by each iteration. Defaults to `1`. +--- * initial - The first value of the range, or the upper limit if no other arguments are specified. +--- * limit - The second value of the range. Defaults to no limit. +--- * step - An amount to increment the value by each iteration. Defaults to `1`. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.fromRange(initial, limit, step) if not limit and not step then initial, limit = 1, initial @@ -352,12 +352,12 @@ end --- Creates an `Observable` that produces values from a table. --- --- Parameters: ---- * t - The `table` used to create the `Observable`. ---- * iterator - An iterator used to iterate the table, e.g. `pairs` or `ipairs`. Defaults to `pairs`. ---- * keys - If `true`, also emit the keys of the table. Defaults to `false`. +--- * t - The `table` used to create the `Observable`. +--- * iterator - An iterator used to iterate the table, e.g. `pairs` or `ipairs`. Defaults to `pairs`. +--- * keys - If `true`, also emit the keys of the table. Defaults to `false`. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.fromTable(t, iterator, keys) iterator = iterator or pairs return Observable.create(function(observer) @@ -378,10 +378,10 @@ end --- Creates an Observable that produces values when the specified coroutine yields. --- --- Parameters: ---- * fn - A `coroutine` or `function` to use to generate values. Note that if a coroutine is used, the values it yields will be shared by all subscribed [Observers](cp.rx.Observer.md) (influenced by the [Scheduler](cp.rx.Scheduler.md)), whereas a new coroutine will be created for each Observer when a `function` is used. +--- * fn - A `coroutine` or `function` to use to generate values. Note that if a coroutine is used, the values it yields will be shared by all subscribed [Observers](cp.rx.Observer.md) (influenced by the [Scheduler](cp.rx.Scheduler.md)), whereas a new coroutine will be created for each Observer when a `function` is used. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.fromCoroutine(fn, scheduler) scheduler = scheduler or util.defaultScheduler() return Observable.create(function(observer) @@ -411,10 +411,10 @@ end --- Creates an Observable that produces values from a file, line by line. --- --- Parameters: ---- * filename - The name of the file used to create the Observable. +--- * filename - The name of the file used to create the Observable. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.fromFileByLine(filename) return Observable.create(function(observer) local f = io.open(filename, 'r') @@ -437,10 +437,10 @@ end --- Creates an `Observable` that executes the `function` to create a new `Observable` each time an [Observer](cp.rx.Observer.md) subscribes. --- --- Parameters: ---- * fn - A function that returns an `Observable`. +--- * fn - A function that returns an `Observable`. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.defer(fn) return setmetatable({ subscribe = function(_, ...) @@ -455,12 +455,12 @@ end --- Creates an `Observable` that repeats a value a specified number of times. --- --- Parameters: ---- * value - The value to repeat. ---- * count - The number of times to repeat the value. If left unspecified, the value +--- * value - The value to repeat. +--- * count - The number of times to repeat the value. If left unspecified, the value --- is repeated an infinite number of times. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.replicate(value, count) return Observable.create(function(observer) while count == nil or count > 0 do @@ -478,11 +478,11 @@ end --- Subscribes to this Observable and prints values it produces. --- --- Parameters: ---- * name - Prefixes the printed messages with a name. ---- * formatter - A function that formats one or more values to be printed. Defaults to `tostring`. +--- * name - Prefixes the printed messages with a name. +--- * formatter - A function that formats one or more values to be printed. Defaults to `tostring`. --- --- Returns: ---- * A [Reference](cp.rx.Reference.md) for the subscription. +--- * A [Reference](cp.rx.Reference.md) for the subscription. function Observable:dump(name, formatter) name = name and (name .. ' ') or '' formatter = formatter or tostring @@ -499,10 +499,10 @@ end --- Determine whether all items emitted by an Observable meet some criteria. --- --- Parameters: ---- * predicate - The predicate used to evaluate objects. Defaults to the `identity`. +--- * predicate - The predicate used to evaluate objects. Defaults to the `identity`. --- --- Returns: ---- * A new `Observable`. +--- * A new `Observable`. function Observable:all(predicate) predicate = predicate or util.identity @@ -557,10 +557,10 @@ end --- Given a set of Observables, produces values from only the first one to produce a value or complete. --- --- Parameters: ---- * ... - list of [Observables](cp.rx.Observable.md) +--- * ... - list of [Observables](cp.rx.Observable.md) --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.firstEmitting(a, b, ...) if not a or not b then return a end @@ -634,8 +634,11 @@ end --- Method --- Returns an Observable that produces the average of all values produced by the original. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:average() return Observable.create(function(observer) local sum, count = 0, 0 @@ -666,10 +669,10 @@ end --- Returns an Observable that buffers values from the original and produces them as multiple values. --- --- Parameters: ---- * size - The size of the buffer. +--- * size - The size of the buffer. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:buffer(size) return Observable.create(function(observer) local buffer = {} @@ -725,11 +728,11 @@ end --- produced by a new Observable. --- --- Parameters: ---- * handler - An `Observable` or a `function` that returns an `Observable` to +--- * handler - An `Observable` or a `function` that returns an `Observable` to --- replace the source `Observable` in the event of an error. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:catch(handler) handler = handler and (type(handler) == 'function' and handler or util.constant(handler)) @@ -787,12 +790,12 @@ end --- are produced by the new `Observable`. --- --- Parameters: ---- * ... - One or more `Observables` to combine. ---- * combinator - A `function` that combines the latest result from each `Observable` and +--- * ... - One or more `Observables` to combine. +--- * combinator - A `function` that combines the latest result from each `Observable` and --- returns a single value. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:combineLatest(...) local sources = {...} local combinator = remove(sources) @@ -851,8 +854,11 @@ end --- Method --- Returns a new `Observable` that produces the values of the first with falsy values removed. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:compact() return self:filter(util.identity) end @@ -863,10 +869,10 @@ end --- the order they are specified. --- --- Parameters: ---- * ... - The list of `Observables` to concatenate. +--- * ... - The list of `Observables` to concatenate. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:concat(other, ...) if not other then return self end @@ -923,10 +929,10 @@ end --- specified value was produced by the original. --- --- Parameters: ---- * value - The value to search for. `==` is used for equality testing. +--- * value - The value to search for. `==` is used for equality testing. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:contains(value) return Observable.create(function(observer) local active, reference = true @@ -985,10 +991,10 @@ end --- by the source value that satisfy an optional predicate. --- --- Parameters: ---- * predicate - The predicate `function` used to match values. +--- * predicate - The predicate `function` used to match values. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:count(predicate) predicate = predicate or util.constant(true) @@ -1041,11 +1047,11 @@ end --- The timer resets on each emission. --- --- Parameters: ---- * time - The number of milliseconds. ---- * scheduler - The scheduler. Uses the [defaultScheduler](cp.rx.util#defaultScheduler) by default. +--- * time - The number of milliseconds. +--- * scheduler - The scheduler. Uses the [defaultScheduler](cp.rx.util#defaultScheduler) by default. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:debounce(time, scheduler) time = time or 0 scheduler = scheduler or util.defaultScheduler() @@ -1083,11 +1089,11 @@ end --- Returns a new `Observable` that produces a default set of items if the source `Observable` produces --- no values. --- ---- Patameters: ---- * ... - Zero or more values to produce if the source completes without emitting anything. +--- Parameters: +--- * ... - Zero or more values to produce if the source completes without emitting anything. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:defaultIfEmpty(...) local defaults = util.pack(...) @@ -1138,12 +1144,12 @@ end --- Returns a new `Observable` that produces the values of the original delayed by a time period. --- --- Parameters: ---- * time - An amount in milliseconds to delay by, or a `function` which returns +--- * time - An amount in milliseconds to delay by, or a `function` which returns --- this value. ---- * scheduler - The [Scheduler](cp.rx.Scheduler.md) to run the `Observable` on. +--- * scheduler - The [Scheduler](cp.rx.Scheduler.md) to run the `Observable` on. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:delay(time, scheduler) time = type(time) ~= 'function' and util.constant(time) or time scheduler = scheduler or util.defaultScheduler() @@ -1177,8 +1183,11 @@ end --- Method --- Returns a new `Observable` that produces the values from the original with duplicates removed. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:distinct() return Observable.create(function(observer) local values = {} @@ -1209,10 +1218,10 @@ end --- the previous value. --- --- Parameters: ---- * comparator - A `function` used to compare 2 values. If unspecified, `==` is used. +--- * comparator - A `function` used to compare 2 values. If unspecified, `==` is used. --- --- Returns: ---- * The new `Observable` +--- * The new `Observable` function Observable:distinctUntilChanged(comparator) comparator = comparator or util.eq @@ -1248,10 +1257,10 @@ end --- Returns an `Observable` that produces the `n`th element produced by the source `Observable`. --- --- Parameters: ---- * index - The index of the item, with an index of `1` representing the first. +--- * index - The index of the item, with an index of `1` representing the first. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:elementAt(index) return Observable.create(function(observer) local reference @@ -1287,10 +1296,10 @@ end --- Returns a new `Observable` that only produces values of the first that satisfy a predicate. --- --- Parameters: ---- * predicate - The predicate `function` used to filter values. +--- * predicate - The predicate `function` used to filter values. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:filter(predicate) predicate = predicate or util.identity @@ -1344,10 +1353,10 @@ end --- Switch to an alternate `Observable` if this one sends an `onCompleted` without any `onNext`s. --- --- Parameters: ---- * alternate - An `Observable` to switch to if this does not send any `onNext` values before the `onCompleted`. +--- * alternate - An `Observable` to switch to if this does not send any `onNext` values before the `onCompleted`. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:switchIfEmpty(alternate) return Observable.create(function(observer) local active, ref = true @@ -1399,10 +1408,10 @@ end --- when the source terminates on complete or error. --- --- Parameters: ---- * handler - The handler `function` to call when `onError`/`onCompleted` occurs. +--- * handler - The handler `function` to call when `onError`/`onCompleted` occurs. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:finalize(handler) return Observable.create(function(observer) local active, ref = true @@ -1453,10 +1462,10 @@ end --- predicate. --- --- Parameters: ---- * predicate - The predicate `function` used to find a value. +--- * predicate - The predicate `function` used to find a value. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:find(predicate) predicate = predicate or util.identity @@ -1509,11 +1518,14 @@ end --- Returns a new `Observable` that only produces the first result of the original. --- If no values are produced, an error is thrown. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. --- --- Note: ---- * This is similar to [#next], but will throw an error if no `onNext` signal is sent before `onCompleted`. +--- * This is similar to [#next], but will throw an error if no `onNext` signal is sent before `onCompleted`. function Observable:first() return self:take(1) end @@ -1523,8 +1535,14 @@ end --- Returns a new `Observable` that produces at most the first result from the original and then completes. --- Will not send an error if zero values are sent. --- +--- Parameters: +--- * None +--- +--- Returns: +--- * None +--- --- Note: ---- * This is similar to [#first], but will not throw an error if no `onNext` signal is sent before `onCompleted`. +--- * This is similar to [#first], but will not throw an error if no `onNext` signal is sent before `onCompleted`. function Observable:next() return Observable.create(function(observer) local active, ref = true @@ -1571,10 +1589,10 @@ end --- then flatten the emissions from those into a single `Observable`. --- --- Parameters: ---- * callback - The `function` to transform values from the original `Observable`. +--- * callback - The `function` to transform values from the original `Observable`. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:flatMap(callback) callback = callback or util.identity return self:map(callback):flatten() @@ -1586,10 +1604,10 @@ end --- the source, then produces values from the most recent of these `Observables`. --- --- Parameters: ---- @arg {function=identity} callback - The function used to convert values to Observables. Defaults to the [identity](cp.rx.util#identity) function. +--- * callback - The function used to convert values to Observables. Defaults to the [identity](cp.rx.util#identity) function. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:flatMapLatest(callback) callback = callback or util.identity return Observable.create(function(observer) @@ -1657,8 +1675,11 @@ end --- Returns a new `Observable` that subscribes to the `Observables` produced by the original and --- produces their values. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:flatten() local stopped = false local outerCompleted = false @@ -1731,8 +1752,11 @@ end --- Returns an `Observable` that terminates when the source terminates but does not produce any --- elements. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:ignoreElements() return Observable.create(function(observer) local function onError(message) @@ -1751,8 +1775,11 @@ end --- Method --- Returns a new `Observable` that only produces the last result of the original. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:last() return Observable.create(function(observer) local value @@ -1784,10 +1811,10 @@ end --- Returns a new `Observable` that produces the values of the original transformed by a `function`. --- --- Parameters: ---- * callback - The `function` to transform values from the original `Observable`. +--- * callback - The `function` to transform values from the original `Observable`. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:map(callback) return Observable.create(function(observer) callback = callback or util.identity @@ -1835,8 +1862,11 @@ end --- Method --- Returns a new `Observable` that produces the maximum value produced by the original. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:max() return self:reduce(math.max) end @@ -1847,10 +1877,10 @@ end --- the order they are produced. --- --- Parameters: ---- * ... - One or more `Observables` to merge. +--- * ... - One or more `Observables` to merge. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:merge(...) return Observable.of(self, ...):flatten() end @@ -1859,8 +1889,11 @@ end --- Method --- Returns a new `Observable` that produces the minimum value produced by the original. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:min() return self:reduce(math.min) end @@ -1869,8 +1902,11 @@ end --- Method --- Returns an `Observable` that produces the values of the original inside tables. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:pack() return self:map(util.pack) end @@ -1881,11 +1917,11 @@ end --- and another that produces values for which the predicate returns falsy. --- --- Parameters: ---- * predicate - The predicate `function` used to partition the values. +--- * predicate - The predicate `function` used to partition the values. --- --- Returns: ---- * The 'truthy' `Observable`. ---- * The 'falsy' `Observable`. +--- * The 'truthy' `Observable`. +--- * The 'falsy' `Observable`. function Observable:partition(predicate) return self:filter(predicate), self:reject(predicate) end @@ -1896,11 +1932,11 @@ end --- tables produced by the original. --- --- Parameters: ---- * ... - The key to extract from the `table`. Multiple keys can be specified to +--- * ... - The key to extract from the `table`. Multiple keys can be specified to --- recursively pluck values from nested tables. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:pluck(key, ...) if not key then return self end @@ -1931,13 +1967,13 @@ end --- running a `function` on each value produced by the original `Observable`. --- --- Parameters: ---- * accumulator - Accumulates the values of the original `Observable`. Will be passed +--- * accumulator - Accumulates the values of the original `Observable`. Will be passed --- the return value of the last call as the first argument and the --- current values as the rest of the arguments. ---- * seed - A value to pass to the accumulator the first time it is run. +--- * seed - A value to pass to the accumulator the first time it is run. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:reduce(accumulator, seed) return Observable.create(function(observer) local active, ref = true, nil @@ -1996,10 +2032,10 @@ end --- Returns a new `Observable` that produces values from the original which do not satisfy a predicate. --- --- Parameters: ---- * predicate - The predicate `function` used to reject values. +--- * predicate - The predicate `function` used to reject values. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:reject(predicate) predicate = predicate or util.identity @@ -2052,11 +2088,11 @@ function Observable:reject(predicate) --- Returns an `Observable` that restarts in the event of an error. --- --- Parameters: ---- * count - The maximum number of times to retry. If left unspecified, an infinite +--- * count - The maximum number of times to retry. If left unspecified, an infinite --- number of retries will be attempted. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:retry(count) return Observable.create(function(observer) local active, ref = true, nil @@ -2111,14 +2147,14 @@ end --- Returns an `Observable` that restarts in the event of an error. --- --- Parameters: ---- * count - The maximum number of times to retry. If left unspecified, an infinite +--- * count - The maximum number of times to retry. If left unspecified, an infinite --- number of retries will be attempted. ---- * delay - The `function` returning or a `number` representing the delay in milliseconds or a `function`. If left unspecified, defaults to 1000 ms (1 second). ---- * scheduler - The [Scheduler](cp.rx.Scheduler.md) to use. +--- * delay - The `function` returning or a `number` representing the delay in milliseconds or a `function`. If left unspecified, defaults to 1000 ms (1 second). +--- * scheduler - The [Scheduler](cp.rx.Scheduler.md) to use. --- If not specified, it will use the [defaultScheduler](cp.rx.util#defaultScheduler]. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:retryWithDelay(count, delay, scheduler) delay = type(delay) == "function" and delay or util.constant(delay or 1000) return Observable.create(function(observer) @@ -2178,10 +2214,10 @@ end --- produces a value. --- --- Parameters: ---- * sampler - The `Observable` that is used to sample values from this `Observable`. +--- * sampler - The `Observable` that is used to sample values from this `Observable`. --- --- Returns:. ---- * The new `Observable`. +--- * The new `Observable`. function Observable:sample(sampler) if not Observable.is(sampler) then error('Expected an Observable') end @@ -2244,14 +2280,14 @@ end --- `function` on each value produced by the original `Observable`. --- --- Parameters: ---- * accumulator - Accumulates the values of the original `Observable`. Will be passed +--- * accumulator - Accumulates the values of the original `Observable`. Will be passed --- the return value of the last call as the first argument and the --- current values as the rest of the arguments. Each value returned --- from this `function` will be emitted by the `Observable`. ---- * seed - A value to pass to the accumulator the first time it is run. +--- * seed - A value to pass to the accumulator the first time it is run. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:scan(accumulator, seed) return Observable.create(function(observer) local active, ref = true @@ -2309,10 +2345,10 @@ end --- and produces the rest. --- --- Parameters: ---- * n - The number of values to ignore. Defaults to `1`. +--- * n - The number of values to ignore. Defaults to `1`. --- --- Returns: ---- * The new `Observable` +--- * The new `Observable` function Observable:skip(n) n = n or 1 @@ -2372,10 +2408,10 @@ end --- Returns an `Observable` that omits a specified number of values from the end of the original `Observable`. --- --- Parameters: ---- * count - The number of items to omit from the end. +--- * count - The number of items to omit from the end. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:skipLast(count) return Observable.create(function(observer) -- cycling buffer @@ -2430,10 +2466,10 @@ end --- `Observable` produces a value. --- --- Parameters: ---- * other - The `Observable` that triggers the production of values. +--- * other - The `Observable` that triggers the production of values. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:skipUntil(other) return Observable.create(function(observer) local active, ref, otherRef = true @@ -2492,10 +2528,10 @@ end --- Returns a new `Observable` that skips elements until the predicate returns `falsy` for one of them. --- --- Parameters: ---- * predicate - The predicate `function` used to continue skipping values. +--- * predicate - The predicate `function` used to continue skipping values. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:skipWhile(predicate) predicate = predicate or util.identity @@ -2554,10 +2590,10 @@ end --- the source `Observable`. --- --- Parameters: ---- * values - The values to produce before the Observable begins producing values normally. +--- * values - The values to produce before the Observable begins producing values normally. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:startWith(...) local values = util.pack(...) return Observable.create(function(observer) @@ -2571,8 +2607,11 @@ end --- Returns an `Observable` that produces a single value representing the sum of the values produced --- by the original. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:sum() return self:reduce(function(x, y) return x + y end, 0) end @@ -2582,8 +2621,11 @@ end --- Given an `Observable` that produces `Observables`, returns an `Observable` that produces the values --- produced by the most recently produced `Observable`. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:switch() return Observable.create(function(observer) local active, ref, sourceRef = true @@ -2641,10 +2683,10 @@ end --- Returns a new `Observable` that only produces the first n results of the original. --- --- Parameters: ---- * n - The number of elements to produce before completing. Defaults to `1`. +--- * n - The number of elements to produce before completing. Defaults to `1`. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:take(n) n = n or 1 @@ -2710,10 +2752,10 @@ end --- `Observable`. --- --- Parameters: ---- * count - The number of elements to produce. +--- * count - The number of elements to produce. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:takeLast(count) return Observable.create(function(observer) local active, ref = true @@ -2765,10 +2807,10 @@ end --- Returns a new `Observable` that completes when the specified `Observable` fires. --- --- Parameters: ---- * other - The `Observable` that triggers completion of the original. +--- * other - The `Observable` that triggers completion of the original. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:takeUntil(other) return Observable.create(function(observer) local active, ref, otherRef = true @@ -2815,10 +2857,10 @@ end --- Returns a new `Observable` that produces elements until the predicate returns `falsy`. --- --- Parameters: ---- * predicate - The predicate `function` used to continue production of values. +--- * predicate - The predicate `function` used to continue production of values. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:takeWhile(predicate) predicate = predicate or util.identity @@ -2878,12 +2920,12 @@ end --- create a subscription. --- --- Parameters: ---- * onNext - Run when the `Observable` produces values. ---- * onError - Run when the `Observable` encounters a problem. ---- * onCompleted - Run when the `Observable` completes. +--- * onNext - Run when the `Observable` produces values. +--- * onError - Run when the `Observable` encounters a problem. +--- * onCompleted - Run when the `Observable` completes. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:tap(_onNext, _onError, _onCompleted) _onNext = _onNext or util.noop _onError = _onError or util.noop @@ -2948,12 +2990,12 @@ end --- Returns an `Observable` that will emit an error if the specified time is exceded since the most recent `next` value. --- --- Parameters: ---- * timeInMs - The time in milliseconds to wait before an error is emitted. ---- * next - If a `string`, it will be sent as an error. If an `Observable`, switch to that `Observable` instead of sending an error. ---- * scheduler - The scheduler to use. Uses the [defaultScheduler](cp.rx.util#defaultSubscriber) if not provided. +--- * timeInMs - The time in milliseconds to wait before an error is emitted. +--- * next - If a `string`, it will be sent as an error. If an `Observable`, switch to that `Observable` instead of sending an error. +--- * scheduler - The scheduler to use. Uses the [defaultScheduler](cp.rx.util#defaultSubscriber) if not provided. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:timeout(timeInMs, next, scheduler) timeInMs = type(timeInMs) == "function" and timeInMs or util.constant(timeInMs) scheduler = scheduler or util.defaultScheduler() @@ -3042,8 +3084,11 @@ end --- Method --- Returns an `Observable` that unpacks the `tables` produced by the original. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:unpack() return self:map(util.unpack) end @@ -3053,8 +3098,11 @@ end --- Returns an `Observable` that takes any values produced by the original that consist of multiple --- return values and produces each value individually. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:unwrap() return Observable.create(function(observer) local function onNext(...) @@ -3083,10 +3131,10 @@ end --- source `Observable` is used. --- --- Parameters: ---- * ... - The `Observables` to include the most recent values from. +--- * ... - The `Observables` to include the most recent values from. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable:with(...) local sources = {...} @@ -3168,10 +3216,10 @@ end --- fewest number of values. --- --- Parameters: ---- * ... - The `Observables` to zip. +--- * ... - The `Observables` to zip. --- --- Returns: ---- * The new `Observable`. +--- * The new `Observable`. function Observable.zip(...) local sources = util.pack(...) local count = #sources @@ -3279,8 +3327,11 @@ ImmediateScheduler.__tostring = util.constant('ImmediateScheduler') --- Constructor --- Creates a new `ImmediateScheduler`. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `ImmediateScheduler`. +--- * The new `ImmediateScheduler`. function ImmediateScheduler.create() return setmetatable({}, ImmediateScheduler) end @@ -3290,10 +3341,10 @@ end --- Schedules a `function` to be run on the scheduler. It is executed immediately. --- --- Parameters: ---- * action - The `function` to execute. +--- * action - The `function` to execute. --- --- Returns: ---- * The [Reference](cp.rx.Reference.md). +--- * The [Reference](cp.rx.Reference.md). function ImmediateScheduler:schedule(action) --luacheck: ignore action() return Reference.create() @@ -3312,10 +3363,10 @@ CooperativeScheduler.__tostring = util.constant('CooperativeScheduler') --- Creates a new `CooperativeScheduler`. --- --- Parameters: ---- * currentTime - A time to start the scheduler at. Defaults to `0`. +--- * currentTime - A time to start the scheduler at. Defaults to `0`. --- --- Returns: ---- * The new `CooperativeScheduler`. +--- * The new `CooperativeScheduler`. function CooperativeScheduler.create(currentTime) local self = { tasks = {}, @@ -3331,13 +3382,13 @@ end --- the action from running. --- --- Parameters: ---- * action - The `function` to execute. Will be converted into a coroutine. The +--- * action - The `function` to execute. Will be converted into a coroutine. The --- coroutine may yield execution back to the scheduler with an optional --- number, which will put it to sleep for a time period. ---- * delay - Delay execution of the action by a virtual time period. Defaults to `0`. +--- * delay - Delay execution of the action by a virtual time period. Defaults to `0`. --- --- Returns: ---- * The [Reference](cp.rx.Reference.md). +--- * The [Reference](cp.rx.Reference.md). function CooperativeScheduler:schedule(action, delay) local task = { thread = coroutine.create(action), @@ -3365,7 +3416,7 @@ end --- will run any coroutines that are due to be run. --- --- Parameters: ---- * delta - An amount of time to advance the clock by. It is common to pass in the +--- * delta - An amount of time to advance the clock by. It is common to pass in the -- time in seconds or milliseconds elapsed since this function was last -- called. Defaults to `0`. function CooperativeScheduler:update(delta) @@ -3398,8 +3449,11 @@ end --- Method --- Returns whether or not the `CooperativeScheduler`'s queue is empty. --- +--- Parameters: +--- * None +--- --- Returns: ---- * `true` if the scheduler is empty, otherwise `false`. +--- * `true` if the scheduler is empty, otherwise `false`. function CooperativeScheduler:isEmpty() return not next(self.tasks) end @@ -3415,8 +3469,11 @@ TimeoutScheduler.__tostring = util.constant('TimeoutScheduler') --- Method --- Creates a new `TimeoutScheduler`. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `TimeoutScheduler`. +--- * The new `TimeoutScheduler`. function TimeoutScheduler.create() return setmetatable({_timers = {}}, TimeoutScheduler) end @@ -3426,11 +3483,11 @@ end --- Schedules an action to run at a future point in time. --- --- Parameters: ---- * action - The action to run. ---- * delay - The delay, in milliseconds. Defaults to `0`. +--- * action - The action to run. +--- * delay - The delay, in milliseconds. Defaults to `0`. --- --- Returns: ---- * The [Reference](cp.rx.Reference.md). +--- * The [Reference](cp.rx.Reference.md). function TimeoutScheduler:schedule(action, delay) delay = delay or 0 local t = doAfter(delay/1000.0, action) @@ -3445,6 +3502,12 @@ end --- cp.rx.TimeoutScheduler:stopAll() -> nil --- Method --- Stops all future timers from running and clears them. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function TimeoutScheduler:stopAll() for t,_ in pairs(self._timers) do t:stop() @@ -3480,13 +3543,13 @@ end --- Creates a new [Observer](cp.rx.Observer.md) and attaches it to the Subject. --- --- Parameters: ---- * observer | onNext - Either an [Observer](cp.rx.Observer.md), or a `function` called +--- * observer | onNext - Either an [Observer](cp.rx.Observer.md), or a `function` called --- when the `Subject` produces a value. ---- * onError - A `function` called when the `Subject` terminates due to an error. ---- * onCompleted - A `function` called when the `Subject` completes normally. +--- * onError - A `function` called when the `Subject` terminates due to an error. +--- * onCompleted - A `function` called when the `Subject` completes normally. --- --- Returns: ---- * The [Reference](cp.rx.Reference.md) +--- * The [Reference](cp.rx.Reference.md) function Subject:subscribe(onNext, onError, onCompleted) local observer @@ -3528,7 +3591,7 @@ end --- Pushes zero or more values to the `Subject`. They will be broadcasted to all [Observers](cp.rx.Observer.md). --- --- Parameters: ---- * ... - The values to send. +--- * ... - The values to send. function Subject:onNext(...) if not self.stopped then local observer @@ -3544,7 +3607,7 @@ end --- Signal to all `Observers` that an error has occurred. --- --- Parameters: ---- * message - A string describing what went wrong. +--- * message - A string describing what went wrong. function Subject:onError(message) if not self.stopped then self.stopping = true @@ -3561,6 +3624,12 @@ end --- cp.rx.Subject:onCompleted() -> nil --- Method --- Signal to all [Observers](cp.rx.Observer.md) that the `Subject` will not produce any more values. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function Subject:onCompleted() if not self.stopped then self.stopping = true @@ -3591,8 +3660,11 @@ AsyncSubject.__tostring = util.constant('AsyncSubject') --- Constructor --- Creates a new `AsyncSubject`. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The new `AsyncSubject`. +--- * The new `AsyncSubject`. function AsyncSubject.create() local self = { observers = {}, @@ -3609,13 +3681,13 @@ end --- Creates a new [Observer](cp.rx.Observer.md) and attaches it to the `AsyncSubject`. --- --- Parameters: ---- * onNext | observer - A `function` called when the `AsyncSubject` produces a value +--- * onNext | observer - A `function` called when the `AsyncSubject` produces a value --- or an existing [Observer](cp.rx.Observer.md) to attach to the `AsyncSubject`. ---- * onError - A `function` called when the `AsyncSubject` terminates due to an error. ---- * onCompleted - A `funtion` called when the `AsyncSubject` completes normally. +--- * onError - A `function` called when the `AsyncSubject` terminates due to an error. +--- * onCompleted - A `funtion` called when the `AsyncSubject` completes normally. --- --- Returns: ---- * The [Reference](cp.rx.Reference.md). +--- * The [Reference](cp.rx.Reference.md). function AsyncSubject:subscribe(onNext, onError, onCompleted) local observer @@ -3651,7 +3723,7 @@ end --- Pushes zero or more values to the `AsyncSubject`. --- --- Parameters: ---- * ... - The values to send. +--- * ... - The values to send. function AsyncSubject:onNext(...) if not self.stopped then self.value = util.pack(...) @@ -3663,7 +3735,7 @@ end --- Signal to all [Observers](cp.rx.Observer.md) that an error has occurred. --- --- Parameters: ---- * message - A string describing what went wrong. +--- * message - A string describing what went wrong. function AsyncSubject:onError(message) if not self.stopped then self.errorMessage = message @@ -3680,6 +3752,12 @@ end --- cp.rx.AsyncSubject:onCompleted() -> nil --- Method --- Signal to all [Observers](cp.rx.Observers.md) that the `AsyncSubject` will not produce any more values. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function AsyncSubject:onCompleted() if not self.stopped then for i = 1, #self.observers do @@ -3710,10 +3788,10 @@ BehaviorSubject.__tostring = util.constant('BehaviorSubject') --- Creates a new `BehaviorSubject`. --- --- Parameters: ---- * ... - The initial values. +--- * ... - The initial values. --- --- Returns: ---- * The new `BehaviorSubject`. +--- * The new `BehaviorSubject`. function BehaviorSubject.create(...) local self = { observers = {}, @@ -3733,13 +3811,13 @@ end --- recent value to the [Observer](cp.rx.Observer.md). --- --- Parameters: ---- * observer | onNext - The [Observer](cp.rx.Observer.md) subscribing, or the `function` called when the +--- * observer | onNext - The [Observer](cp.rx.Observer.md) subscribing, or the `function` called when the --- `BehaviorSubject` produces a value. ---- * onError - A `function` called when the `BehaviorSubject` terminates due to an error. ---- * onCompleted - A `function` called when the `BehaviorSubject` completes normally. +--- * onError - A `function` called when the `BehaviorSubject` terminates due to an error. +--- * onCompleted - A `function` called when the `BehaviorSubject` completes normally. --- --- Returns: ---- * The [Reference](cp.rx.Reference.md) +--- * The [Reference](cp.rx.Reference.md) function BehaviorSubject:subscribe(onNext, onError, onCompleted) local observer @@ -3763,7 +3841,7 @@ end --- Pushes zero or more values to the `BehaviorSubject`. They will be broadcasted to all [Observers](cp.rx.Observer.md). --- --- Parameters: ---- * ... - The values to send. +--- * ... - The values to send. function BehaviorSubject:onNext(...) self.value = util.pack(...) return Subject.onNext(self, ...) @@ -3774,11 +3852,14 @@ end --- Returns the last value emitted by the `BehaviorSubject`, or the initial value passed to the --- constructor if nothing has been emitted yet. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The last value. +--- * The last value. --- --- Note: ---- * You can also call the `BehaviorSubject` as a function to retrieve the value. E.g. `mySubject()`. +--- * You can also call the `BehaviorSubject` as a function to retrieve the value. E.g. `mySubject()`. function BehaviorSubject:getValue() if self.value ~= nil then return util.unpack(self.value) @@ -3800,11 +3881,11 @@ ReplaySubject.__tostring = util.constant('ReplaySubject') --- Creates a new `ReplaySubject`. --- --- Parameters: ---- * bufferSize - The number of values to send to new subscribers. If `nil`, an infinite +--- * bufferSize - The number of values to send to new subscribers. If `nil`, an infinite --- buffer is used (note that this could lead to memory issues). --- --- Returns: ---- * The new `ReplaySubject. +--- * The new `ReplaySubject. function ReplaySubject.create(n) local self = { observers = {}, @@ -3824,13 +3905,13 @@ end --- Immediately broadcasts the most recent contents of the buffer to the Observer. --- --- Parameters: ---- * observer | onNext - Either an [Observer](cp.rx.Observer.md), or a +--- * observer | onNext - Either an [Observer](cp.rx.Observer.md), or a --- `function` to call when the `ReplaySubject` produces a value. ---- * onError - A `function` to call when the `ReplaySubject` terminates due to an error. ---- * onCompleted - A `function` to call when the ReplaySubject completes normally. +--- * onError - A `function` to call when the `ReplaySubject` terminates due to an error. +--- * onCompleted - A `function` to call when the ReplaySubject completes normally. --- --- Returns: ---- * The [Reference](cp.rx.Reference.md). +--- * The [Reference](cp.rx.Reference.md). function ReplaySubject:subscribe(onNext, onError, onCompleted) local observer @@ -3863,7 +3944,7 @@ end --- Pushes zero or more values to the `ReplaySubject`. They will be broadcasted to all [Observers](cp.rx.Observer.md). --- --- Parameters: ---- * ... - The values to send. +--- * ... - The values to send. function ReplaySubject:onNext(...) if not self.stopped then self.buffer:pushRight(util.pack(...)) diff --git a/src/extensions/cp/rx/go/Statement.lua b/src/extensions/cp/rx/go/Statement.lua index f150eb831..178812f42 100644 --- a/src/extensions/cp/rx/go/Statement.lua +++ b/src/extensions/cp/rx/go/Statement.lua @@ -386,6 +386,9 @@ end --- Method --- Returns the Statement name. --- +--- Parameters: +--- * None +--- --- Returns: --- * The Statement name. function Statement.mt:name() @@ -400,6 +403,9 @@ end --- Method --- Returns the Statement's full name. --- +--- Parameters: +--- * None +--- --- Returns: --- * The full Statement name. function Statement.mt:fullName() diff --git a/src/extensions/cp/spec.lua b/src/extensions/cp/spec.lua index 8ec9e63c5..7dd946997 100644 --- a/src/extensions/cp/spec.lua +++ b/src/extensions/cp/spec.lua @@ -569,6 +569,12 @@ local ID_SEARCH_PATTERN = "(.*)%.%*$" --- or if those don't exist it will see if there is a `foo/bar_test.lua` or `foo/bar/._test.lua` and load that via [test](#test) instead. --- However, if the pattern is "foo.bar.*", it will not only look for those specs, but will also check under that folder for other --- `_spec.lua` or `_test.lua` files to add to the collection to run. +--- +--- Parameters: +--- * idPattern - the ID pattern +--- +--- Returns: +--- * The spec or `nil` and an error message. local function find(idPattern) local id = idPattern:match(ID_SEARCH_PATTERN) local result, err diff --git a/src/extensions/cp/spec/DefaultHandler.lua b/src/extensions/cp/spec/DefaultHandler.lua index 5de19dd39..0daf901b1 100644 --- a/src/extensions/cp/spec/DefaultHandler.lua +++ b/src/extensions/cp/spec/DefaultHandler.lua @@ -1,3 +1,7 @@ +--- === cp.spec.DefaultHandler === +--- +--- Default Handler. + local Handler = require "cp.spec.Handler" local format = string.format @@ -18,6 +22,12 @@ local DefaultHandler = Handler:subclass("cp.spec.DefaultHandler") --- cp.spec.DefaultHandler:printSpacer() --- Method --- Prints a blank line if this is not the first time it has been called. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function DefaultHandler:printSpacer() if self.spacerSkipped then print() @@ -31,8 +41,11 @@ end --- optionally formatted with the provided parameters. --- --- Parameters: ---- * text - The message to print. ---- * ... - The parameters to interpolate into the text message. +--- * text - The message to print. +--- * ... - The parameters to interpolate into the text message. +--- +--- Returns: +--- * None function DefaultHandler:printf(text, ...) self:printSpacer() printf(text, ...) @@ -43,7 +56,10 @@ end --- If the handler or run is verbose, prints a "[START]" message. --- --- Parameters: ---- * run - the [run](cp.spec.Run.md) +--- * run - the [run](cp.spec.Run.md) +--- +--- Returns: +--- * None function DefaultHandler:start(run) if self:checkVerbose(run) then self:printf(" [START] %s", run) end end @@ -53,7 +69,10 @@ end --- If the handler or run is verbose, prints a "[STOP]" message. --- --- Parameters: ---- * run - the [run](cp.spec.Run.md) +--- * run - the [run](cp.spec.Run.md) +--- +--- Returns: +--- * None function DefaultHandler:stop(run) if self:checkVerbose(run) then self:printf(" [STOP] %s", run) end end @@ -63,8 +82,11 @@ end --- If the handler or run is verbose, prints a "[PASS]" message. --- --- Parameters: ---- * run - the [run](cp.spec.Run.md) ---- * msg - the message string. +--- * run - the [run](cp.spec.Run.md) +--- * msg - the message string. +--- +--- Returns: +--- * None function DefaultHandler:passed(run, msg) if self:checkVerbose(run) then local tag = msg and ": " .. msg or "" @@ -77,8 +99,8 @@ end --- Prints a "[FAIL]" message. --- --- Parameters: ---- * run - the [run](cp.spec.Run.md) ---- * msg - the message string. +--- * run - the [run](cp.spec.Run.md) +--- * msg - the message string. function DefaultHandler:failed(run, msg) self:printf(" [FAIL] %s: %s", run, msg) end @@ -88,8 +110,11 @@ end --- Prints an "[ABORT]" message. --- --- Parameters: ---- * run - the [run](cp.spec.Run.md) ---- * msg - the message string. +--- * run - the [run](cp.spec.Run.md) +--- * msg - the message string. +--- +--- Returns: +--- * None function DefaultHandler:aborted(run, msg) self:printf(" [ABORT] %s: %s", run, msg) end @@ -97,6 +122,12 @@ end --- cp.spec.DefaultHandler:waiting(run, timeout) --- Method --- Prints a "[WAIT]" message with the timeout value.. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function DefaultHandler:waiting(run, timeout) if self:checkVerbose(run) then local seconds = timeout == 1 and "second" or "seconds" @@ -109,8 +140,11 @@ end --- Prints a "[FILTER]" message. --- --- Parameters: ---- * run - the [run](cp.spec.Run.md) ---- * msg - the message string. +--- * run - the [run](cp.spec.Run.md) +--- * msg - the message string. +--- +--- Returns: +--- * None function DefaultHandler:filter(run, msg) self:printf("[FILTER] %s: %s", run, msg) end @@ -120,8 +154,11 @@ end --- If the handler or run is verbose, prints a "[RESULT]" message. --- --- Parameters: ---- * run - the [run](cp.spec.Run.md) ---- * report - the [report](cp.spec.Report.md) +--- * run - the [run](cp.spec.Run.md) +--- * report - the [report](cp.spec.Report.md) +--- +--- Returns: +--- * None function DefaultHandler:summary(run, report) self:printf("[RESULT] %s: %s", run, report) end diff --git a/src/extensions/cp/spec/Definition.lua b/src/extensions/cp/spec/Definition.lua index f20088d33..dd8a7a397 100644 --- a/src/extensions/cp/spec/Definition.lua +++ b/src/extensions/cp/spec/Definition.lua @@ -1,13 +1,13 @@ -local require = require - -local class = require "middleclass" - --- === cp.spec.Definition === --- --- A [Definition](cp.spec.Definition.md) is a superclass for a "runnable" specification. --- It doesn't do anything itself, but provides a common ancestor for all implementation --- classes like [Specification](cp.spec.Specification.md) and [Scenario](cp.spec.Scenario.md). +local require = require + +local class = require "middleclass" + local Definition = class("cp.spec.Definition") --- cp.spec.Definition(name[, doing]) -> cp.spec.Definition diff --git a/src/extensions/cp/spec/Error.lua b/src/extensions/cp/spec/Error.lua index 74bda36fc..0854b14df 100644 --- a/src/extensions/cp/spec/Error.lua +++ b/src/extensions/cp/spec/Error.lua @@ -9,6 +9,12 @@ local Error = Message:subclass("cp.spec.Error") --- cp.spec.Error.is(other) -> boolean --- Function --- Checks if the `other` is an instance of the `Error` class. +--- +--- Parameters: +--- * other - An object to check +--- +--- Returns: +--- * A boolean function Error.static.is(other) return other ~= nil and type(other) == "table" and other.isInstanceOf ~= nil and other:isInstanceOf(Error) end diff --git a/src/extensions/cp/spec/Handled.lua b/src/extensions/cp/spec/Handled.lua index 6c902dee2..6f2a1c86d 100644 --- a/src/extensions/cp/spec/Handled.lua +++ b/src/extensions/cp/spec/Handled.lua @@ -1,3 +1,7 @@ +--- === cp.spec.Handled === +--- +--- An synchronous/asynchronous test library for Lua. + local Message = require "cp.spec.Message" local Handled = Message:subclass("cp.spec.Handled") @@ -5,6 +9,12 @@ local Handled = Message:subclass("cp.spec.Handled") --- cp.spec.Handled.is(other) -> boolean --- Function --- Checks if the `other` is an instance of the `Handled` class. +--- +--- Parameters: +--- * other - An object to check. +--- +--- Returns: +--- * A boolean. function Handled.static.is(other) return other ~= nil and type(other) == "table" and other.isInstanceOf ~= nil and other:isInstanceOf(Handled) end diff --git a/src/extensions/cp/spec/Handler.lua b/src/extensions/cp/spec/Handler.lua index 0cc0dfceb..552b9ca50 100644 --- a/src/extensions/cp/spec/Handler.lua +++ b/src/extensions/cp/spec/Handler.lua @@ -1,10 +1,10 @@ - --- === cp.spec.Handler === --- --- Subclasses of this can customise how reports are handled. --- All methods do nothing. --- --- See [DefaultHandler](cp.spec.DefaultHandler.md). + local require = require local class = require "middleclass" @@ -37,6 +37,12 @@ end --- cp.spec.Handler() -> cp.spec.Handler --- Constructor --- Creates a new `Handler` +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function Handler.initialized() end --- cp.spec.Handler:verbose([isVerbose]) -> self @@ -58,6 +64,12 @@ end --- Method --- Indicates if either the handler or the individual [Run](cp.spec.Run.md) is --- "verbose". If so, more messages may be output by the handler. +--- +--- Parameters: +--- * run +--- +--- Returns: +--- * None function Handler:checkVerbose(run) return self._verbose or run and run:verbose() end diff --git a/src/extensions/cp/spec/Message.lua b/src/extensions/cp/spec/Message.lua index 754839006..ec6435557 100644 --- a/src/extensions/cp/spec/Message.lua +++ b/src/extensions/cp/spec/Message.lua @@ -9,6 +9,12 @@ local Message = class("cp.spec.Message") --- cp.spec.Message.is(other) -> boolean --- Function --- Checks if the `other` is an instance of the `Message` class. +--- +--- Parameters: +--- * other - The object to compare +--- +--- Returns: +--- * A boolean function Message.static.is(other) return other ~= nil and type(other) == "table" and other.isInstanceOf ~= nil and other:isInstanceOf(Message) end @@ -18,7 +24,10 @@ end --- Creates a new Message message. --- --- Parameters: ---- * message - the message to send. +--- * message - the message to send. +--- +--- Returns: +--- * A new message. function Message:initialize(msg, level) self.message = msg self.level = (level or 1) + 1 @@ -27,6 +36,12 @@ end --- cp.spec.Message:traceback() --- Method --- Stores the `debug.traceback` result at the present time. Can be retrieved via `stacktrace` +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function Message:traceback() if self._traceback == nil then self._traceback = debug.traceback(self.message or "", self.level) diff --git a/src/extensions/cp/spec/Report.lua b/src/extensions/cp/spec/Report.lua index 416fb9672..bb4fd27ea 100644 --- a/src/extensions/cp/spec/Report.lua +++ b/src/extensions/cp/spec/Report.lua @@ -1,3 +1,7 @@ +--- === cp.spec.Report === +--- +--- The results of a test [run](cp.spec.Run.md). + local require = require local class = require "middleclass" @@ -7,14 +11,17 @@ local Handler = require "cp.spec.Handler" local format = string.format ---- === cp.spec.Report === ---- ---- The results of a test [run](cp.spec.Run.md). local Report = class("cp.spec.Report") --- cp.spec.Report(run) -> cp.spec.Report --- Constructor --- Creates a new test report. +--- +--- Parameters: +--- * run +--- +--- Returns: +--- * A new `cp.spec.Report` object function Report:initialize(run) --- cp.spec.Report.run @@ -56,6 +63,12 @@ end --- cp.spec.Report:start() -> nil --- Method --- Logs the start time. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function Report:start() self.startTime = timer.secondsSinceEpoch() Handler.default():start(self.run) @@ -64,6 +77,12 @@ end --- cp.spec.Report:stop() -> nil --- Method --- Logs the end time. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function Report:stop() self.stopTime = timer.secondsSinceEpoch() self.totalTime = self.stopTime - self.startTime @@ -75,7 +94,10 @@ end --- Records a pass, with the specified message. --- --- Parameters: ---- * message - an optional additional message to output. +--- * message - an optional additional message to output. +--- +--- Returns: +--- * None function Report:passed(message) self.passes = self.passes + 1 Handler.default():passed(self.run, message) @@ -86,7 +108,10 @@ end --- Records a fail, with the specified message. --- --- Parameters: ---- * message - The related message to output. +--- * message - The related message to output. +--- +--- Returns: +--- * None function Report:failed(message) self.failures = self.failures + 1 Handler.default():failed(self.run, message) @@ -97,7 +122,10 @@ end --- Records an abort, with the specified message. --- --- Parameters: ---- * message - The related message to output. +--- * message - The related message to output. +--- +--- Returns: +--- * None function Report:aborted(message) self.aborts = self.aborts + 1 Handler.default():aborted(self.run, message) @@ -108,7 +136,10 @@ end --- Records that a run is waiting for up to the specified amount of time. --- --- Parameters: ---- * timeout - The timeout to wait for, in seconds. +--- * timeout - The timeout to wait for, in seconds. +--- +--- Returns: +--- * None function Report:waiting(timeout) Handler.default():waiting(self.run, timeout) end @@ -116,6 +147,12 @@ end --- cp.spec.Report:summary() --- Method --- Summarise the reports. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function Report:summary() Handler.default():summary(self.run, self) end @@ -125,7 +162,10 @@ end --- Adds the passes/failures/aborts from the other report into this one. --- --- Parameters: ---- * otherReport - The other report to add. +--- * otherReport - The other report to add. +--- +--- Returns: +--- * None function Report:add(otherReport) self.passes = self.passes + otherReport.passes self.failures = self.failures + otherReport.failures diff --git a/src/extensions/cp/spec/Run.lua b/src/extensions/cp/spec/Run.lua index 2a8f44f2e..279da22ef 100644 --- a/src/extensions/cp/spec/Run.lua +++ b/src/extensions/cp/spec/Run.lua @@ -1,3 +1,7 @@ +--- === cp.spec.Run === +--- +--- An individual run of a test [Definition](cp.spec.Definition.md) or [Specification](cp.spec.Specification.md). + local require = require local log = require "hs.logger" .new "spec" @@ -16,9 +20,6 @@ local Observer = require "cp.rx" .Observer local format = string.format local insert = table.insert ---- === cp.spec.Run === ---- ---- An individual run of a test [Definition](cp.spec.Definition.md) or [Specification](cp.spec.Specification.md). local Run = class("cp.spec.Run") --- === cp.spec.Run.This === @@ -32,7 +33,7 @@ Run.static.This = class("cp.spec.Run.This") --- A collection of states that a `Run.This` can be in. --- --- Notes: ---- * States include: +--- * States include: --- * running - The Run is currently running and will terminate at the end of the function (synchrnonous). --- * waiting - The Run is waiting, and will terminate when [done()](#done) is called. (asynchronous). --- * done - The Run is done. @@ -50,10 +51,10 @@ local asyncTimeout = 10 --- Defaults to 60 seconds. --- --- Parameters: ---- * timeout - (optional) the new timeout, in seconds. +--- * timeout - (optional) the new timeout, in seconds. --- --- Returns: ---- * The current default timeout, in seconds. +--- * The current default timeout, in seconds. function Run.This.static.defaultTimeout(timeout) if timeout then asyncTimeout = timeout @@ -66,12 +67,12 @@ end --- Creates a new `Run.This` instance for a [Run](cp.spec.Run.md). --- --- Parameters: ---- * run - The [Run](cp.spec.Run.md). ---- * actionFn - The action function to execute. ---- * index - The index of the action in the current phase. +--- * run - The [Run](cp.spec.Run.md). +--- * actionFn - The action function to execute. +--- * index - The index of the action in the current phase. --- --- Returns: ---- * The new `Run.This`. +--- * The new `Run.This`. function Run.This:initialize(run, actionFn, index) assert(run ~= nil, "The Run must be provided.") assert(type(run) == "table", "The Run must be a Run instance.") @@ -86,6 +87,12 @@ end --- cp.spec.Run.This:run() -> cp.spec.Run --- Method --- Returns the current [Run](cp.spec.Run.md) +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Returns the current [Run](cp.spec.Run.md) function Run.This:run() return self._run end @@ -99,10 +106,10 @@ end --- This should be called before the actual assert/fail would occur. --- --- Parameters: ---- * messagePattern - The pattern to check the fail message against. If not provided, any message will match. +--- * messagePattern - The pattern to check the fail message against. If not provided, any message will match. --- --- Returns: ---- * The same `Run` instance. +--- * The same `Run` instance. function Run:expectFail(messagePattern) self._expectFail = true self._expectFailPattern = messagePattern @@ -119,10 +126,10 @@ end --- This should be called before the actual assert/fail would occur. --- --- Parameters: ---- * messagePattern - The pattern to check the fail message against. If not provided, any message will match. +--- * messagePattern - The pattern to check the fail message against. If not provided, any message will match. --- --- Returns: ---- * The same `Run.This` instance. +--- * The same `Run.This` instance. function Run.This:expectFail(messagePattern) self:run():expectFail(messagePattern) return self @@ -134,11 +141,11 @@ end --- If so, it will return the expected message pattern, if specified. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * boolean - `true`, if a fail is expected. ---- * string - the message pattern, if specified. +--- * boolean - `true`, if a fail is expected. +--- * string - the message pattern, if specified. function Run:isExpectingFail() return self._expectFail == true, self._expectFailPattern end @@ -185,10 +192,10 @@ end --- This should be called before the actual abort/`error` would occur. --- --- Parameters: ---- * messagePattern - The pattern to check the fail message against. If not provided, any message will match. +--- * messagePattern - The pattern to check the fail message against. If not provided, any message will match. --- --- Returns: ---- * The same `Run` instance. +--- * The same `Run` instance. function Run:expectAbort(messagePattern) self._expectAbort = true self._expectAbortPattern = messagePattern @@ -205,10 +212,10 @@ end --- This should be called before the actual abort/`error` would occur. --- --- Parameters: ---- * messagePattern - The pattern to check the fail message against. If not provided, any message will match. +--- * messagePattern - The pattern to check the fail message against. If not provided, any message will match. --- --- Returns: ---- * The same `Run.This` instance. +--- * The same `Run.This` instance. function Run.This:expectAbort(messagePattern) self:run():expectAbort(messagePattern) return self @@ -220,11 +227,11 @@ end --- If so, it will return the expected message pattern as the second value, if specified. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * boolean - `true`, if a fail is expected. ---- * string - the message pattern, if specified. +--- * boolean - `true`, if a fail is expected. +--- * string - the message pattern, if specified. function Run:isExpectingAbort() return self._expectAbort == true, self._expectAbortPattern end @@ -269,9 +276,9 @@ end --- and `onCompleted` will trigger [done](#done). --- --- Parameters: ---- * onNext - The `next` handler. ---- * onError - The `error` handler. ---- * onCompleted - The `completed` handler. +--- * onNext - The `next` handler. +--- * onError - The `error` handler. +--- * onCompleted - The `completed` handler. function Run.This:toObserver(onNext, onError, onCompleted) onNext = onNext or function(value) self:log("onNext: %s", inspect(value)) end onError = onError or error @@ -283,8 +290,11 @@ end --- Method --- Checks if the this is in an active state - either `running` or `waiting`. --- +--- Parameters: +--- * None +--- --- Returns: ---- * `true` if isActive. +--- * `true` if isActive. function Run.This:isActive() return self.state == Run.This.state.running or self.state == Run.This.state.waiting end @@ -295,10 +305,10 @@ end --- be completed by calling [done](#done). --- --- Parameters: ---- * timeout - (optional) The number of seconds to wait before timing out. +--- * timeout - (optional) The number of seconds to wait before timing out. --- --- Notes: ---- * If not provided, [Run.This.defaultTimeout()](cp.spec.Run.This.md#defaultTimeout) is used. +--- * If not provided, [Run.This.defaultTimeout()](cp.spec.Run.This.md#defaultTimeout) is used. function Run.This:wait(timeout) self.state = Run.This.state.waiting timeout = timeout or Run.This.defaultTimeout() @@ -317,8 +327,11 @@ end --- Checks if the [Run](cp.spec.Run.md) is waiting for this execution to complete via the --- [done](cp.spec.Run.This.md#done) method. --- +--- Parameters: +--- * None +--- --- Returns: ---- * `true` if the waiting. +--- * `true` if the waiting. function Run.This:isWaiting() return self.state == Run.This.state.waiting end @@ -326,6 +339,12 @@ end --- cp.spec.Run.This:done() --- Method --- Indicates that the test is completed. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function Run.This:done() self:log("This: done") local expecting, pattern = self:run():isExpectingFail() @@ -364,16 +383,25 @@ end --- cp.spec.Run.This:isDone() -> boolean --- Method --- Returns `true` if this is done. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A boolean function Run.This:isDone() return self.state == Run.This.state.done end ---- cp.spec.Run.This:abort([message]) +--- cp.spec.Run.This:abort([message]) -> boolean --- Method --- Indicates the stage has aborted. --- --- Parameters: ---- * message - The optional message to output. +--- * message - The optional message to output. +--- +--- Returns: +--- * A boolean function Run.This:abort(message) self:log("This: abort: %s", message) local expecting, pattern = self:run():isExpectingAbort() @@ -389,12 +417,15 @@ function Run.This:abort(message) return true end ---- cp.spec.Run.This:fail([message]) +--- cp.spec.Run.This:fail([message]) -> boolean --- Method --- Indicates the run has failed. --- --- Parameters: ---- * message - The optional message to output. +--- * message - The optional message to output. +--- +--- Returns: +--- * A boolean function Run.This:fail(message) self:log("This: fail: %s", message) local expecting, pattern = self:run():isExpectingFail() @@ -439,12 +470,24 @@ end --- cp.spec.Run.This:prepare() --- Method --- Prepares this to run. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function Run.This.prepare() end --- cp.spec.Run.This:cleanup() --- Method --- Cleans up This after a step. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * None function Run.This:cleanup() self:run():timeoutCancelled() end @@ -491,7 +534,7 @@ end --- The list of phases a `run` can be in. --- --- Notes: ---- * Maybe one of: +--- * Maybe one of: --- * `start` - has been initiated, but not started any actual actions. --- * `before` - any `before` callbacks present are being processed. --- * `running` - the actual test is running. @@ -510,7 +553,7 @@ Run.static.phase = { --- A collection of result states for a `Run`. --- --- Notes: ---- * Report states include: +--- * Report states include: --- * running - The Run is currently running. Runs start in this state by default. --- * failed - An assertion failed. --- * aborted - An unexpected error happened. @@ -525,8 +568,11 @@ Run.static.result = { --- Creates a new test run. --- --- Parameters: ---- * name - The name of the run. ---- * source - The object (typically a [Definition](cp.spec.Definition.md)) that initiated the run. +--- * name - The name of the run. +--- * source - The object (typically a [Definition](cp.spec.Definition.md)) that initiated the run. +--- +--- Returns: +--- * cp.spec.Run function Run:initialize(name, source) --- cp.spec.Run.report @@ -619,10 +665,10 @@ end --- Enables debugging on this `Run`. Any calls to [#log] will be output to the console. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * The same `Run` instance. +--- * The same `Run` instance. function Run:debug() self._debug = true return self @@ -631,6 +677,12 @@ end --- cp.spec.Run:isDebugging() -> boolean --- Method --- Checks if `debug` has been enabled on this or any parent `Run`. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A boolean function Run:isDebugging() return self._debug or self._parent ~= nil and self._parent:isDebugging() end @@ -640,8 +692,11 @@ end --- When the current [Run](cp.spec.Run.md) is in [debug](#debug) mode, output the message to the console. --- --- Parameters: ---- * message - the text message to output. ---- * ... - optional parameters, to be injected into the message, ala `string.format`. +--- * message - the text message to output. +--- * ... - optional parameters, to be injected into the message, ala `string.format`. +--- +--- Returns: +--- * None function Run:log(message, ...) if self:isDebugging() then log.df("%s: " .. message, self, ...) @@ -653,8 +708,11 @@ end --- When the current [Run](cp.spec.Run.md) is in [debug](#debug) mode, output the message to the console. --- --- Parameters: ---- * message - the text message to output. ---- * ... - optional parameters, to be injected into the message, ala `string.format`. +--- * message - the text message to output. +--- * ... - optional parameters, to be injected into the message, ala `string.format`. +--- +--- Returns: +--- * None function Run.This:log(message, ...) return self:run():log(message, ...) end @@ -775,13 +833,13 @@ end --- Gets and/or sets the parent `Run` for this run. --- --- Parameters: ---- * parent - (optional) If set, will set the parent `Run`. +--- * parent - (optional) If set, will set the parent `Run`. --- --- Returns: ---- * The current parent `Run`. +--- * The current parent `Run`. --- --- Notes: ---- * If a `parent` is provided and there is already another Run set as a parent, an error is thrown. +--- * If a `parent` is provided and there is already another Run set as a parent, an error is thrown. function Run:parent(parent) if parent then if self._parent then @@ -800,10 +858,10 @@ end --- the current verbose status. --- --- Parameters: ---- * isVerbose - (optional) if `true` or `false` will update the verbose status and return this `Run`. +--- * isVerbose - (optional) if `true` or `false` will update the verbose status and return this `Run`. --- --- Returns: ---- * The current `verbose` status, or this `Run` if `isVerbose` is provided. +--- * The current `verbose` status, or this `Run` if `isVerbose` is provided. function Run:verbose(isVerbose) if isVerbose ~= nil then self._verbose = isVerbose ~= false @@ -823,7 +881,7 @@ end --- Adds a callback function to run prior to executing the actual test. --- --- Parameters: ---- * actionFn - The function to run, passed this `Run.This` as the first parameter. +--- * actionFn - The function to run, passed this `Run.This` as the first parameter. function Run:onBefore(beforeFn) return self:_addAction(Run.phase.before, beforeFn) end @@ -833,7 +891,7 @@ end --- Adds a callback function to run during the test. --- --- Parameters: ---- * runningFn - The function to run, passed [Run.This](cp.spec.Run.This.md) as the first parameter. +--- * runningFn - The function to run, passed [Run.This](cp.spec.Run.This.md) as the first parameter. function Run:onRunning(runningFn) return self:_addAction(Run.phase.running, runningFn) end @@ -843,7 +901,7 @@ end --- Adds a callback function to run after to executing the actual test, pass or fail. --- --- Parameters: ---- * actionFn - The function to run, passed this `Run` as the first parameter. +--- * actionFn - The function to run, passed this `Run` as the first parameter. function Run:onAfter(actionFn) return self:_addAction(Run.phase.after, actionFn) end diff --git a/src/extensions/cp/spec/Scenario.lua b/src/extensions/cp/spec/Scenario.lua index 011a19190..7d0a108ab 100644 --- a/src/extensions/cp/spec/Scenario.lua +++ b/src/extensions/cp/spec/Scenario.lua @@ -1,14 +1,3 @@ -local require = require - --- local log = require "hs.logger" .new "Scenario" - -local Definition = require "cp.spec.Definition" -local Handled = require "cp.spec.Handled" -local Run = require "cp.spec.Run" -local Where = require "cp.spec.Where" - -local format = string.format - --- === cp.spec.Scenario === --- --- A [Definition](cp.spec.Definition.md) which describes a specific scenario. @@ -77,6 +66,18 @@ local format = string.format --- --- **Note:** "where" parameters will not override built-in functions and fields in the [this](cp.spec.Run.This.md) --- instance (such as "async" or "done") so ensure that you pick names that don't clash. + +local require = require + +-- local log = require "hs.logger" .new "Scenario" + +local Definition = require "cp.spec.Definition" +local Handled = require "cp.spec.Handled" +local Run = require "cp.spec.Run" +local Where = require "cp.spec.Where" + +local format = string.format + local Scenario = Definition:subclass("cp.spec.Scenario") -- default `doing` function for Definitions. diff --git a/src/extensions/cp/spec/Specification.lua b/src/extensions/cp/spec/Specification.lua index 20ffe21cd..9fb0b19d8 100644 --- a/src/extensions/cp/spec/Specification.lua +++ b/src/extensions/cp/spec/Specification.lua @@ -1,12 +1,3 @@ -local require = require - --- local log = require "hs.logger" .new "Specification" - -local Definition = require "cp.spec.Definition" -local Run = require "cp.spec.Run" - -local insert = table.insert - --- === cp.spec.Specification === --- --- A Specification is a list of [definitions](cp.spec.Definition.md) which @@ -25,17 +16,27 @@ local insert = table.insert --- end), --- } --- ``` + +local require = require + +-- local log = require "hs.logger" .new "Specification" + +local Definition = require "cp.spec.Definition" +local Run = require "cp.spec.Run" + +local insert = table.insert + local Specification = Definition:subclass("cp.spec.Specification") --- cp.spec.Specification.is(instance) -> boolean --- Function --- Checks if the `instance` is an instance of `Specification`. --- ---- Presentation: ---- * instance - The instance to check +--- Parameters: +--- * instance - The instance to check --- --- Returns: ---- * `true` if it's a `Specification` instance. +--- * `true` if it's a `Specification` instance. function Specification.static.is(instance) return type(instance) == "table" and instance.isInstanceOf and instance:isInstanceOf(Specification) end @@ -43,6 +44,12 @@ end --- cp.spec.Specification(name) -> cp.spec.Specification --- Constructor --- Creates a new test suite. +--- +--- Parameters: +--- * name - The name os the specification. +--- +--- Returns: +--- * A `cp.spec.Specification` object function Specification:initialize(name) self.definitions = {} Definition.initialize(self, name) @@ -54,10 +61,10 @@ end --- The function will be passed the [Run.This](cp.spec.Run.This.md) for the current Run. --- --- Parameters: ---- * beforeEachFn - The function to run before each child runs. +--- * beforeEachFn - The function to run before each child runs. --- --- Returns: ---- * The same `cp.spec.Specification` instance. +--- * The same `cp.spec.Specification` instance. function Specification:onBeforeEach(beforeEachFn) self._beforeEach = beforeEachFn return self @@ -69,10 +76,10 @@ end --- The function will be passed the [Run.This](cp.spec.Run.This.md) for the current Run. --- --- Parameters: ---- * afterEachFn - The function to run after each child runs. +--- * afterEachFn - The function to run after each child runs. --- --- Returns: ---- * The same `cp.spec.Specification` instance. +--- * The same `cp.spec.Specification` instance. function Specification:onAfterEach(afterEachFn) self._afterEach = afterEachFn return self @@ -82,8 +89,11 @@ end --- Method --- Runs the specification, returning the [Run](cp.spec.Run.md) instance, already running. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The [Run](cp.spec.Run.md) instance. +--- * The [Run](cp.spec.Run.md) instance. function Specification:run() return Run(self.name, self) :onRunning(function(this) @@ -130,10 +140,10 @@ end --- May also pass a single `table` containing a list of definitions. --- --- Parameters: ---- * ... - the [definitions](cp.spec.Definition.md) to add. +--- * ... - the [definitions](cp.spec.Definition.md) to add. --- --- Returns: ---- * The same `Specification` instance, with the definitions added. +--- * The same `Specification` instance, with the definitions added. function Specification:with(...) local count = select("#", ...) if count == 1 then diff --git a/src/extensions/cp/spec/TestSuite.lua b/src/extensions/cp/spec/TestSuite.lua index 1dcd60999..b73025f85 100644 --- a/src/extensions/cp/spec/TestSuite.lua +++ b/src/extensions/cp/spec/TestSuite.lua @@ -1,3 +1,7 @@ +--- === cp.spec.TestSuite === +--- +--- Test Suite. + local require = require local Specification = require "cp.spec.Specification" diff --git a/src/extensions/cp/spec/Where.lua b/src/extensions/cp/spec/Where.lua index 95375cde9..be652ad88 100644 --- a/src/extensions/cp/spec/Where.lua +++ b/src/extensions/cp/spec/Where.lua @@ -1,3 +1,14 @@ +-- === cp.spec.RunWhere === +-- +-- Private implementation class. +-- +-- This will run the provided [Definition](cp.spec.Definition.cp) once for each +-- data row in the provided data table, where the first row are all `string` values +-- providing the property names, and subsequent rows contain the data for those +-- values for each run. +-- +-- Extends [Run](cp.spec.Run.md). + local require = require local inspect = require "hs.inspect" @@ -9,16 +20,6 @@ local insert = table.insert local WHERE_NAME = "[WHERE]" --- === cp.spec.RunWhere === --- --- Private implementation class. --- --- This will run the provided [Definition](cp.spec.Definition.cp) once for each --- data row in the provided data table, where the first row are all `string` values --- providing the property names, and subsequent rows contain the data for those --- values for each run. --- --- Extends [Run](cp.spec.Run.md). local RunWhere = Run:subclass("cp.spec.RunWhere") function RunWhere:initialize(where) diff --git a/src/extensions/cp/text/init.lua b/src/extensions/cp/text/init.lua index 42b15067d..844f1758a 100644 --- a/src/extensions/cp/text/init.lua +++ b/src/extensions/cp/text/init.lua @@ -277,6 +277,13 @@ end --- Returns the substring of this text that starts at `i` and continues until `j`; `i` and `j` can be negative. --- If `j` is absent, then it is assumed to be equal to `-1` (which is the same as the string length). --- In particular, the call `cp.text:sub(1,j)` returns a prefix of `s` with length `j`, and `cp.text:sub(-i)` (for a positive `i`) returns a suffix of s with length i. +--- +--- Parameters: +--- * i - See above +--- * j - See above +--- +--- Returns: +--- * None function text.mt:sub(i, j) j = j or -1 return text.fromCodepoints(getCodes(self), i, j) @@ -288,7 +295,7 @@ end --- --- If the pattern has captures, then in a successful match the captured values are also returned, after the two indices. --- ---- Preferences: +--- Parameters: --- * `pattern` - The pattern to find. --- * `init` - The index to start matching from. Defaults to `1`. --- * `plain` - If `true`, the pattern is treated as plain text. diff --git a/src/extensions/cp/time/flicks.lua b/src/extensions/cp/time/flicks.lua index 649e613b7..503acf622 100644 --- a/src/extensions/cp/time/flicks.lua +++ b/src/extensions/cp/time/flicks.lua @@ -290,6 +290,12 @@ setmetatable(flicks, { --- cp.time.flicks:toFrames(framerate) --> number --- Method --- Converts the flicks into a number for the specific framerate. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * the number of frames --- cp.time.flicks:toSeconds() -> number --- Method diff --git a/src/extensions/cp/ui/Cell.lua b/src/extensions/cp/ui/Cell.lua index 2eac9801b..434a6cc83 100644 --- a/src/extensions/cp/ui/Cell.lua +++ b/src/extensions/cp/ui/Cell.lua @@ -10,6 +10,12 @@ local Cell = Element:subclass("cp.ui.Cell") --- cp.ui.Cell.matches(element) -> boolean --- Function --- Checks if the `element` is an `AXCell`. +--- +--- Parameters: +--- * element - An element to check +--- +--- Returns: +--- * A boolean function Cell.static.matches(element) return Element.matches(element) and element:attributeValue("AXRole") == "AXCell" end diff --git a/src/extensions/cp/ui/CheckBox.lua b/src/extensions/cp/ui/CheckBox.lua index 314e94456..b939f735b 100644 --- a/src/extensions/cp/ui/CheckBox.lua +++ b/src/extensions/cp/ui/CheckBox.lua @@ -163,6 +163,12 @@ end --- cp.ui.CheckBox:doCheck() -> cp.rx.go.Statement --- Method --- Returns a `Statement` that will ensure the `CheckBox` is checked. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function CheckBox.lazy.method:doCheck() return Do(self:parent():doShow()) :Then( @@ -177,6 +183,12 @@ end --- cp.ui.CheckBox:doUncheck() -> cp.rx.go.Statement --- Method --- Returns a `Statement` that will ensure the `CheckBox` is unchecked. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function CheckBox.lazy.method:doUncheck() return Do(self:parent():doShow()) :Then( diff --git a/src/extensions/cp/ui/Column.lua b/src/extensions/cp/ui/Column.lua index 322671414..4ff712f68 100644 --- a/src/extensions/cp/ui/Column.lua +++ b/src/extensions/cp/ui/Column.lua @@ -13,10 +13,10 @@ local Column = Element:subclass("cp.ui.Column") --- Checks if the `axuielement` is a `Column`. --- --- Parameters: ---- * element - The `axuielement` to check. +--- * element - The `axuielement` to check. --- --- Returns: ---- * `true` if the element is a Column. +--- * `true` if the element is a Column. function Column.static.matches(element) return Element.matches(element) and element:attributeValue("AXRole") == "AXColumn" end @@ -39,8 +39,11 @@ end --- Method --- Returns a `table` of [Row](cp.ui.Row.md)s contained in the Column. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The `table`, or `nil` if the column's UI is not available. +--- * The `table`, or `nil` if the column's UI is not available. function Column:rows() local ui = self:UI() if ui then @@ -53,8 +56,11 @@ end --- Method --- Returns a `table` of [Row](cp.ui.Row.md)s which are currently visible on screen. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The `table`, or `nil` if the column's UI is not available. +--- * The `table`, or `nil` if the column's UI is not available. function Column:visibleRows() local ui = self:UI() if ui then diff --git a/src/extensions/cp/ui/DisclosureTriangle.lua b/src/extensions/cp/ui/DisclosureTriangle.lua index d007221a9..74410c308 100644 --- a/src/extensions/cp/ui/DisclosureTriangle.lua +++ b/src/extensions/cp/ui/DisclosureTriangle.lua @@ -163,6 +163,12 @@ end --- cp.ui.DisclosureTriangle:doOpen() -> cp.rx.go.Statement --- Method --- Returns a `Statement` that will ensure the `DisclosureTriangle` is opened. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function DisclosureTriangle.lazy.method:doOpen() return Do(self:parent():doShow()) :Then( @@ -177,6 +183,12 @@ end --- cp.ui.DisclosureTriangle:doClose() -> cp.rx.go.Statement --- Method --- Returns a `Statement` that will ensure the `DisclosureTriangle` is unopened. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function DisclosureTriangle.lazy.method:doClose() return Do(self:parent():doShow()) :Then( diff --git a/src/extensions/cp/ui/Element.lua b/src/extensions/cp/ui/Element.lua index db14eef88..6c6268ce6 100644 --- a/src/extensions/cp/ui/Element.lua +++ b/src/extensions/cp/ui/Element.lua @@ -3,9 +3,9 @@ --- A support class for `hs.axuielement` management. --- --- See: ---- * [Button](cp.ui.Button.md) ---- * [CheckBox](cp.rx.CheckBox.md) ---- * [MenuButton](cp.rx.MenuButton.md) +--- * [Button](cp.ui.Button.md) +--- * [CheckBox](cp.rx.CheckBox.md) +--- * [MenuButton](cp.rx.MenuButton.md) local require = require -- local log = require "hs.logger".new("Element") @@ -28,10 +28,10 @@ local Element = class("cp.ui.Element"):include(lazy) --- Matches to any valid `hs.axuielement`. Sub-types should provide their own `matches` method. --- --- Parameters: ---- * The element to check +--- * The element to check --- --- Returns: ---- * `true` if the element is a valid instance of an `hs.axuielement`. +--- * `true` if the element is a valid instance of an `hs.axuielement`. function Element.static.matches(element) return element ~= nil and type(element.isValid) == "function" and element:isValid() end @@ -47,11 +47,11 @@ end --- The `uiFinder` may be either a `function` that returns an `axuielement`, or a [cp.prop](cp.prop.md). --- --- Parameters: ---- * parent - The parent Element (may be `nil`) ---- * uiFinder - The `function` or `prop` that actually provides the current `axuielement` instance. +--- * parent - The parent Element (may be `nil`) +--- * uiFinder - The `function` or `prop` that actually provides the current `axuielement` instance. --- --- Returns: ---- * The new `Element` instance. +--- * The new `Element` instance. function Element:initialize(parent, uiFinder) self._parent = parent @@ -101,10 +101,10 @@ end --- Checks if the current value of this element is the provided value. --- --- Parameters: ---- * value - The value to compare to. +--- * value - The value to compare to. --- --- Returns: ---- * `true` if the current [#value] is equal to the provided `value`. +--- * `true` if the current [#value] is equal to the provided `value`. function Element:valueIs(value) return self:value() == value end @@ -131,6 +131,12 @@ end --- cp.ui.Element:doShow() -> cp.rx.go.Statement --- Method --- Returns a `Statement` that will ensure the Element is showing. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function Element.lazy.method:doShow() return If(function() return self:parent() end) :Then(function(parent) return parent.doShow and parent:doShow() end) @@ -269,8 +275,14 @@ end --- Method --- Returns a `table` containing the current configuration details for this Element (or subclass). --- +--- Parameters: +--- * None +--- +--- Returns: +--- * None +--- --- Notes: ---- * When subclassing, the overriding `saveLayout` method should call the parent's saveLayout method, +--- * When subclassing, the overriding `saveLayout` method should call the parent's saveLayout method, --- then add values to it, like so: --- ``` --- function MyElement:saveLayout() @@ -289,10 +301,13 @@ end --- provided by the `layout` table. This table should generally be generated via the [#saveLayout] method. --- --- Parameters: ---- * layout - a `table` of parameters that will be used to layout the element. +--- * layout - a `table` of parameters that will be used to layout the element. +--- +--- Returns: +--- * None --- --- Notes: ---- * When subclassing, the overriding `loadLayout` method should call the parent's `loadLayout` method, +--- * When subclassing, the overriding `loadLayout` method should call the parent's `loadLayout` method, --- then process any custom values from it, like so: --- ``` --- function MyElement:loadLayout(layout) @@ -314,14 +329,14 @@ end --- provided by the `layout` table. This table should generally be generated via the [#saveLayout] method. --- --- Parameters: ---- * layout - a `table` of parameters that will be used to layout the element. +--- * layout - a `table` of parameters that will be used to layout the element. --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md) to execute. +--- * The [Statement](cp.rx.go.Statement.md) to execute. --- --- Notes: ---- * By default, to enable backwards-compatibility, this method will simply call the [#loadLayout]. Override it to provide more optimal asynchonous behaviour if required. ---- * When subclassing, the overriding `doLayout` method should call the parent class's `doLayout` method, +--- * By default, to enable backwards-compatibility, this method will simply call the [#loadLayout]. Override it to provide more optimal asynchonous behaviour if required. +--- * When subclassing, the overriding `doLayout` method should call the parent class's `doLayout` method, --- then process any custom values from it, like so: --- ```lua --- function MyElement:doLayout(layout) diff --git a/src/extensions/cp/ui/Grid.lua b/src/extensions/cp/ui/Grid.lua index 27c7c0e7a..9714eef21 100644 --- a/src/extensions/cp/ui/Grid.lua +++ b/src/extensions/cp/ui/Grid.lua @@ -36,6 +36,12 @@ end --- cp.ui.Grid.matches(element) -> boolean --- Function --- Checks if the `element` is an `Grid`. +--- +--- Parameters: +--- * element - An element to check +--- +--- Returns: +--- * A boolean function Grid.static.matches(element) return Element.matches(element) and (element:attributeValue("AXRows") ~= nil or element:attributeValue("AXColumns") ~= nil) end @@ -45,11 +51,11 @@ end --- Creates a new `Grid` with the specified `parent` and `uiFinder`. --- --- Parameters: ---- * parent - The parent instance. ---- * uiFinder - A `function` or a `cp.prop` which will return the `axuielement`. +--- * parent - The parent instance. +--- * uiFinder - A `function` or a `cp.prop` which will return the `axuielement`. --- --- Returns: ---- * The new `Grid` instance. +--- * The new `Grid` instance. function Grid:initialize(parent, uiFinder) Element.initialize(self, parent, uiFinder) self._rowCache = ElementCache(self, self.createRow) @@ -59,6 +65,12 @@ end --- cp.ui.Grid:childrenUI() -> table of axuielements --- Method --- Provides a `table` containing the `axuielement`s which are children of the outline. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A table function Grid:childrenUI() return valueOf(self:UI(), "AXChildren") end @@ -66,6 +78,12 @@ end --- cp.ui.Grid:columnsUI() -> table of axuielements --- Method --- Provides a `table` containing the `axuielement`s which are columns of the outline. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A table function Grid:columnsUI() return valueOf(self:UI(), "AXColumns") end @@ -76,13 +94,13 @@ end --- If there is a problem, an `error` is thrown. --- --- Parameters: ---- * columnUI - the `AXColumn` `axuielement` to create a [Column](cp.ui.Column.md) for. +--- * columnUI - the `AXColumn` `axuielement` to create a [Column](cp.ui.Column.md) for. --- --- Returns: ---- * The [Column](cp.ui.Column.md) or an error if a problem occurred. +--- * The [Column](cp.ui.Column.md) or an error if a problem occurred. --- --- Notes: ---- * Subclasses which want to provide a custom [Column](cp.ui.Column.md) implementation should override this method. +--- * Subclasses which want to provide a custom [Column](cp.ui.Column.md) implementation should override this method. function Grid:createColumn(columnUI) assert(Column.matches(columnUI), "The provided columnUI is not an AXColumn") assert(columnUI:attributeValue("AXParent") == self:UI(), "The provided `columnUI` belongs to someone else.") @@ -92,6 +110,12 @@ end --- cp.ui.Grid:columns() -> table of cp.ui.Columns --- Method --- Returns the list of [Column](cp.ui.Column.md)s. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A table function Grid:columns() return self:fetchColumns(self:columnsUI()) end @@ -99,6 +123,12 @@ end --- cp.ui.Grid:column(index) -> cp.ui.Column or nil --- Method --- Provides the [Column](cp.ui.Column.md) at the specified index, or `nil` if it's not available. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * cp.ui.Column or nil function Grid:column(index) local columns = self:columns() return columns and columns[index] @@ -109,10 +139,10 @@ end --- Returns the [Column](cp.ui.Column.md) that represents the provided `columnUI`, if it is actually present. --- --- Parameters: ---- * columnUI - The `axuielement` for the `AXColumn` to find a [Column](cp.ui.Column.md) for. +--- * columnUI - The `axuielement` for the `AXColumn` to find a [Column](cp.ui.Column.md) for. --- --- Returns: ---- * The [Column](cp.ui.Column.md), or `nil` if the `columnUI` is not available. +--- * The [Column](cp.ui.Column.md), or `nil` if the `columnUI` is not available. function Grid:fetchColumn(columnUI) return self._columnCache:fetchElement(columnUI) end @@ -124,10 +154,10 @@ end --- Note that this will break the standard `#`/looping behaviour for tables at that point. --- --- Parameters: ---- * columnsUI - The list of `AXColumn` `axuielement`s to find. +--- * columnsUI - The list of `AXColumn` `axuielement`s to find. --- --- Returns: ---- * A `table` with the same number of elements, containing the matching [Column](cp.ui.Column.md) instances. +--- * A `table` with the same number of elements, containing the matching [Column](cp.ui.Column.md) instances. function Grid:fetchColumns(columnsUI) return self._columnCache:fetchElements(columnsUI) end @@ -135,6 +165,12 @@ end --- cp.ui.Grid:rowsUI() -> table of axuielement --- Method --- Provides a `table` containing the `axuielement`s which are rows in the outline. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A table function Grid:rowsUI() return valueOf(self:UI(), "AXRows") end @@ -145,13 +181,13 @@ end --- If there is a problem, an `error` is thrown. --- --- Parameters: ---- * rowUI - the `AXRow` `axuielement` to create a [Row](cp.ui.Row.md) for. +--- * rowUI - the `AXRow` `axuielement` to create a [Row](cp.ui.Row.md) for. --- --- Returns: ---- * The [Row](cp.ui.Row.md) or an error if a problem occurred. +--- * The [Row](cp.ui.Row.md) or an error if a problem occurred. --- --- Notes: ---- * Subclasses which want to provide a custom [Row](cp.ui.Row.md) implementation should override this method. +--- * Subclasses which want to provide a custom [Row](cp.ui.Row.md) implementation should override this method. function Grid:createRow(rowUI) assert(rowUI:attributeValue("AXParent") == self:UI(), "The provided `rowUI` not from here.") return Row(self, prop.THIS(rowUI)) @@ -161,8 +197,11 @@ end --- Method --- Provides a `table` with the list of `cp.ui.Row` elements for the rows. --- +--- Parameters: +--- * None +--- --- Returns: ---- * A table containing the list of [Row](cp.ui.Row.md)s, or `nil` if not presently available. +--- * A table containing the list of [Row](cp.ui.Row.md)s, or `nil` if not presently available. function Grid:rows() return self:fetchRows(self:rowsUI()) end @@ -170,6 +209,12 @@ end --- cp.ui.Grid:row(index) -> cp.ui.Row or nil --- Method --- Provides the [Row](cp.ui.Row.md) at the specified index, or `nil` if it's not available. +--- +--- Parameters: +--- * index - The index +--- +--- Returns: +--- * The [Row](cp.ui.Row.md), or `nil` if the `rowUI` is not available. function Grid:row(index) local rows = self:rows() return rows and rows[index] @@ -180,10 +225,10 @@ end --- Returns the [Row](cp.ui.Row.md) that represents the provided `rowUI`, if it is actually present. --- --- Parameters: ---- * rowUI - The `axuielement` for the `AXRow` to find a [Row](cp.ui.Row.md) for. +--- * rowUI - The `axuielement` for the `AXRow` to find a [Row](cp.ui.Row.md) for. --- --- Returns: ---- * The [Row](cp.ui.Row.md), or `nil` if the `rowUI` is not available. +--- * The [Row](cp.ui.Row.md), or `nil` if the `rowUI` is not available. function Grid:fetchRow(rowUI) return self._rowCache:fetchElement(rowUI) end @@ -195,10 +240,10 @@ end --- Note that this will break the standard `#`/looping behaviour for tables at that point. --- --- Parameters: ---- * rowsUI - The list of `AXRow` `axuielement`s to find. +--- * rowsUI - The list of `AXRow` `axuielement`s to find. --- --- Returns: ---- * A `table` with the same number of elements, containing the matching [Row](cp.ui.Row.md) instances. +--- * A `table` with the same number of elements, containing the matching [Row](cp.ui.Row.md) instances. function Grid:fetchRows(rowsUI) return self._rowCache:fetchElements(rowsUI) end @@ -209,10 +254,10 @@ end --- The function is passed the row and returns a boolean. --- --- Parameters: ---- * matcherFn - the `function` that will accept a [Row](cp.ui.Row.md) and return a `boolean`. +--- * matcherFn - the `function` that will accept a [Row](cp.ui.Row.md) and return a `boolean`. --- --- Returns: ---- * A `table` of [Row](cp.ui.Row.md)s, or `nil` if no UI is currently available. +--- * A `table` of [Row](cp.ui.Row.md)s, or `nil` if no UI is currently available. function Grid:filterRows(matcherFn) local rows = self:rows() return rows and ifilter(rows, matcherFn) @@ -224,10 +269,10 @@ end --- or `nil` if none was matched. --- --- Parameters: ---- * matcherFn - The function to check the [Row](cp.ui.Row.md) with. +--- * matcherFn - The function to check the [Row](cp.ui.Row.md) with. --- --- Returns: ---- * The matching [Row](cp.ui.Row.md) or `nil`. +--- * The matching [Row](cp.ui.Row.md) or `nil`. function Grid:findRow(matcherFn) local rows = self:rows() return rows and find(rows, matcherFn) @@ -312,10 +357,10 @@ end --- Selects the row at the sub-level named in the `path` table. --- --- Parameters: ---- * path - A `table` of names to navigate through to find the [Row](cp.ui.Row.md) to select. +--- * path - A `table` of names to navigate through to find the [Row](cp.ui.Row.md) to select. --- --- Returns: ---- * The selected [Row](cp.ui.Row.md), or `nil` if not found. +--- * The selected [Row](cp.ui.Row.md), or `nil` if not found. function Grid:selectRow(path) return self:visitRow(path, function(row) row:selected(true) end) end @@ -325,10 +370,10 @@ end --- Selects the row at the sub-level named in the `path` table. --- --- Parameters: ---- * path - A `table` of names to navigate through to find the [Row](cp.ui.Row.md) to select. +--- * path - A `table` of names to navigate through to find the [Row](cp.ui.Row.md) to select. --- --- Returns: ---- * The selected [Row](cp.ui.Row.md), or `nil` if not found. +--- * The selected [Row](cp.ui.Row.md), or `nil` if not found. function Grid:doSelectRow(path) return Do(function() return self:visitRow(path, function(row) row:selected(true) end) @@ -340,7 +385,7 @@ end --- Contains the list of currently-selected row `axuilements`. Can be set. --- --- Notes: ---- * Also see [#selectedRows] +--- * Also see [#selectedRows] function Grid.lazy.prop:selectedRowsUI() return axutils.prop(self.UI, "AXSelectedRows", true) end diff --git a/src/extensions/cp/ui/List.lua b/src/extensions/cp/ui/List.lua index a68dc8933..56efd9e16 100644 --- a/src/extensions/cp/ui/List.lua +++ b/src/extensions/cp/ui/List.lua @@ -50,6 +50,12 @@ end --- cp.ui.List:items() -> table of values --- Method --- Returns the children as items, as adapted by the `itemAdaptor` in the constructor +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A table function List:items() local items = {} local childrenUI = self:childrenUI() diff --git a/src/extensions/cp/ui/Outline.lua b/src/extensions/cp/ui/Outline.lua index 15e42c3b5..81471a91a 100644 --- a/src/extensions/cp/ui/Outline.lua +++ b/src/extensions/cp/ui/Outline.lua @@ -89,6 +89,12 @@ end --- cp.ui.Outline.matches(element) -> boolean --- Function --- Checks if the `element` is an `Outline`. +--- +--- Parameters: +--- * element - An element to check +--- +--- Returns: +--- * A boolean function Outline.static.matches(element) return Element.matches(element) and element:attributeValue("AXRole") == "AXOutline" end @@ -98,11 +104,11 @@ end --- Creates a new `Outline` with the specified `parent` and `uiFinder`. --- --- Parameters: ---- * parent - The parent instance. ---- * uiFinder - A `function` or a `cp.prop` which will return the `AXOutline` `axuielement`. +--- * parent - The parent instance. +--- * uiFinder - A `function` or a `cp.prop` which will return the `AXOutline` `axuielement`. --- --- Returns: ---- * The new `Outline` instance. +--- * The new `Outline` instance. function Outline:initialize(parent, uiFinder) Element.initialize(self, parent, uiFinder) self._rowCache = {} @@ -112,6 +118,12 @@ end --- cp.ui.Outline:childrenUI() -> table --- Method --- Provides a `table` containing the `axuielement`s which are children of the outline. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A table function Outline:childrenUI() return valueOf(self:UI(), "AXChildren") end @@ -119,6 +131,12 @@ end --- cp.ui.Outline:columnsUI() -> table --- Method --- Provides a `table` containing the `axuielement`s which are columns of the outline. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Table function Outline:columnsUI() return valueOf(self:UI(), "AXColumns") end @@ -129,13 +147,13 @@ end --- If there is a problem, an `error` is thrown. --- --- Parameters: ---- * columnUI - the `AXColumn` `axuielement` to create a [Column](cp.ui.Column.md) for. +--- * columnUI - the `AXColumn` `axuielement` to create a [Column](cp.ui.Column.md) for. --- --- Returns: ---- * The [Column](cp.ui.Column.md) or an error if a problem occurred. +--- * The [Column](cp.ui.Column.md) or an error if a problem occurred. --- --- Notes: ---- * Subclasses which want to provide a custom [Column](cp.ui.Column.md) implementation should override this method. +--- * Subclasses which want to provide a custom [Column](cp.ui.Column.md) implementation should override this method. function Outline:createColumn(columnUI) assert(Column.matches(columnUI), "The provided columnUI is not an AXColumn") assert(columnUI:attributeValue("AXParent") == self:UI(), "The provided `columnUI` is not in this Outline.") @@ -145,6 +163,12 @@ end --- cp.ui.Outline:columns() -> table of cp.ui.Columns --- Method --- Returns the list of [Column](cp.ui.Column.md)s in this `Outline`. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A table function Outline:columns() return self:fetchColumns(self:columnsUI()) end @@ -155,10 +179,10 @@ end --- in the `Outline`. --- --- Parameters: ---- * columnUI - The `axuielement` for the `AXColumn` to find a [Column](cp.ui.Column.md) for. +--- * columnUI - The `axuielement` for the `AXColumn` to find a [Column](cp.ui.Column.md) for. --- --- Returns: ---- * The [Column](cp.ui.Column.md), or `nil` if the `columnUI` is not in this `Outline`. +--- * The [Column](cp.ui.Column.md), or `nil` if the `columnUI` is not in this `Outline`. function Outline:fetchColumn(columnUI) return _fetchElement(self._columnCache, columnUI, self, self.createColumn) end @@ -170,10 +194,10 @@ end --- Note that this will break the standard `#`/looping behaviour for tables at that point. --- --- Parameters: ---- * columnsUI - The list of `AXColumn` `axuielement`s to find. +--- * columnsUI - The list of `AXColumn` `axuielement`s to find. --- --- Returns: ---- * A `table` with the same number of elements, containing the matching [Column](cp.ui.Column.md) instances. +--- * A `table` with the same number of elements, containing the matching [Column](cp.ui.Column.md) instances. function Outline:fetchColumns(columnsUI) return _fetchElements(self._columnCache, columnsUI, self, self.createColumn) end @@ -181,6 +205,12 @@ end --- cp.ui.Outline:rowsUI() -> table of axuielement --- Method --- Provides a `table` containing the `axuielement`s which are rows in the outline. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A table function Outline:rowsUI() return valueOf(self:UI(), "AXRows") end @@ -191,13 +221,13 @@ end --- If there is a problem, an `error` is thrown. --- --- Parameters: ---- * rowUI - the `AXRow` `axuielement` to create a [Row](cp.ui.Row.md) for. +--- * rowUI - the `AXRow` `axuielement` to create a [Row](cp.ui.Row.md) for. --- --- Returns: ---- * The [Row](cp.ui.Row.md) or an error if a problem occurred. +--- * The [Row](cp.ui.Row.md) or an error if a problem occurred. --- --- Notes: ---- * Subclasses which want to provide a custom [Row](cp.ui.Row.md) implementation should override this method. +--- * Subclasses which want to provide a custom [Row](cp.ui.Row.md) implementation should override this method. function Outline:createRow(rowUI) assert(rowUI:attributeValue("AXParent") == self:UI(), "The provided `rowUI` is not in this Outline.") return Row(self, prop.THIS(rowUI)) @@ -207,8 +237,11 @@ end --- Method --- Provides a `table` with the list of `cp.ui.Row` elements for the rows. --- +--- Parameters: +--- * None +--- --- Returns: ---- * A table containing the list of [Row](cp.ui.Row.md)s in the `Outline`, or `nil` if the `Outline` is not presently available. +--- * A table containing the list of [Row](cp.ui.Row.md)s in the `Outline`, or `nil` if the `Outline` is not presently available. function Outline:rows() return self:fetchRows(self:rowsUI()) end @@ -219,10 +252,10 @@ end --- in the `Outline`. --- --- Parameters: ---- * rowUI - The `axuielement` for the `AXRow` to find a [Row](cp.ui.Row.md) for. +--- * rowUI - The `axuielement` for the `AXRow` to find a [Row](cp.ui.Row.md) for. --- --- Returns: ---- * The [Row](cp.ui.Row.md), or `nil` if the `rowUI` is not in this `Outline`. +--- * The [Row](cp.ui.Row.md), or `nil` if the `rowUI` is not in this `Outline`. function Outline:fetchRow(rowUI) return _fetchElement(self._rowCache, rowUI, self, self.createRow) end @@ -234,10 +267,10 @@ end --- Note that this will break the standard `#`/looping behaviour for tables at that point. --- --- Parameters: ---- * rowsUI - The list of `AXRow` `axuielement`s to find. +--- * rowsUI - The list of `AXRow` `axuielement`s to find. --- --- Returns: ---- * A `table` with the same number of elements, containing the matching [Row](cp.ui.Row.md) instances. +--- * A `table` with the same number of elements, containing the matching [Row](cp.ui.Row.md) instances. function Outline:fetchRows(rowsUI) return _fetchElements(self._rowCache, rowsUI, self, self.createRow) end @@ -248,10 +281,10 @@ end --- The function is passed the row and returns a boolean. --- --- Parameters: ---- * matcherFn - the `function` that will accept a [Row](cp.ui.Row.md) and return a `boolean`. +--- * matcherFn - the `function` that will accept a [Row](cp.ui.Row.md) and return a `boolean`. --- --- Returns: ---- * A `table` of [Row](cp.ui.Row.md)s, or `nil` if no UI is currently available. +--- * A `table` of [Row](cp.ui.Row.md)s, or `nil` if no UI is currently available. function Outline:filterRows(matcherFn) local rows = self:rows() return rows and ifilter(rows, matcherFn) diff --git a/src/extensions/cp/ui/PropertyRow.lua b/src/extensions/cp/ui/PropertyRow.lua index 2104fdb38..8f054ccf8 100644 --- a/src/extensions/cp/ui/PropertyRow.lua +++ b/src/extensions/cp/ui/PropertyRow.lua @@ -295,8 +295,11 @@ end --- Method --- A [Statement](cp.rx.go.Statement.md) that will attempt to hide the `PropertyRow`. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The `Statement`. +--- * The `Statement`. function PropertyRow.lazy.method:doHide() return self:parent():doHide():Label("PropertyRow:doHide") end diff --git a/src/extensions/cp/ui/RadioButton.lua b/src/extensions/cp/ui/RadioButton.lua index 0e519734a..89a32de7b 100644 --- a/src/extensions/cp/ui/RadioButton.lua +++ b/src/extensions/cp/ui/RadioButton.lua @@ -34,10 +34,10 @@ local RadioButton = Element:subclass("cp.ui.RadioButton") --- Checks if the provided `hs.axuielement` is a RadioButton. --- --- Parameters: ---- * element - The `axuielement` to check. +--- * element - The `axuielement` to check. --- --- Returns: ---- * `true` if it's a match, or `false` if not. +--- * `true` if it's a match, or `false` if not. function RadioButton.static.matches(element) return Element.matches(element) and element:attributeValue("AXRole") == "AXRadioButton" end @@ -47,11 +47,11 @@ end --- Creates a new RadioButton. --- --- Parameters: ---- * parent - The parent object. ---- * finderFn - A function which will return the `hs.axuielement` when available. +--- * parent - The parent object. +--- * finderFn - A function which will return the `hs.axuielement` when available. --- --- Returns: ---- * The new `RadioButton`. +--- * The new `RadioButton`. function RadioButton:initialize(parent, finderFn) Element.initialize(self, parent, finderFn) end @@ -80,10 +80,10 @@ end --- Toggles the `checked` status of the button. --- --- Parameters: ---- * None +--- * None --- --- Returns: ---- * The `RadioButton` instance. +--- * The `RadioButton` instance. function RadioButton:toggle() self.checked:toggle() return self @@ -146,7 +146,7 @@ end --- Attempts to press the button. May fail if the `UI` is not available. --- --- Parameters: ---- * None +--- * None --- --- Returns: --- The `RadioButton` instance. @@ -183,8 +183,11 @@ end --- Returns a `table` with the button's current state. This can be passed to [#loadLayout] --- later to restore the original state. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The table of the layout state. +--- * The table of the layout state. function RadioButton:saveLayout() local layout = Element.saveLayout(self) layout.checked = self:checked() @@ -196,7 +199,7 @@ end --- Processes the `layout` table to restore this to match the provided `layout`. --- --- Parameters: ---- * layout - the table of state values to restore to. +--- * layout - the table of state values to restore to. function RadioButton:loadLayout(layout) Element.loadLayout(self, layout) if layout then @@ -209,10 +212,10 @@ end --- Returns a [Statement](cp.rx.go.Statement.md) that will apply the layout provided, if possible. --- --- Parameters: ---- * layout - the `table` containing the layout configuration. Usually created via the [#saveLayout] method. +--- * layout - the `table` containing the layout configuration. Usually created via the [#saveLayout] method. --- --- Returns: ---- * The [Statement](cp.rx.go.Statement.md). +--- * The [Statement](cp.rx.go.Statement.md). function RadioButton:doLayout(layout) layout = layout or {} return Do(Element.doLayout(self, layout)) diff --git a/src/extensions/cp/ui/Row.lua b/src/extensions/cp/ui/Row.lua index 0a36f8f1e..154a48001 100644 --- a/src/extensions/cp/ui/Row.lua +++ b/src/extensions/cp/ui/Row.lua @@ -2,9 +2,8 @@ --- --- Represents an `AXRow` `axuielement`. -local axutils = require "cp.ui.axutils" -local Element = require "cp.ui.Element" - +local axutils = require "cp.ui.axutils" +local Element = require "cp.ui.Element" local Row = Element:subclass("cp.ui.Row") @@ -13,10 +12,10 @@ local Row = Element:subclass("cp.ui.Row") --- Checks if the element is a `Row`. --- --- Parameters: ---- * element - the `axuielement` to check. +--- * element - the `axuielement` to check. --- --- Returns: ---- * `true` if it matches, otherwise `false`. +--- * `true` if it matches, otherwise `false`. function Row.static.matches(element) return Element.matches(element) and element:attributeValue("AXRole") == "AXRow" end @@ -26,11 +25,11 @@ end --- Creates a new `Row` instance with the specified `parent` and `uiFinder`. --- --- Parameters: ---- * parent - the parent `Element`. ---- * uiFinder - a `function` or `cp.prop` containing the `axuielement` +--- * parent - the parent `Element`. +--- * uiFinder - a `function` or `cp.prop` containing the `axuielement` --- --- Returns: ---- * The new `Row`. +--- * The new `Row`. --- cp.ui.Row.disclosing --- Field @@ -49,6 +48,12 @@ end --- cp.ui.Row:disclosedByRow() -> cp.ui.Row --- Method --- The `Row` which is disclosing this `Row`. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A `cp.ui.Row` object function Row.lazy.prop:disclosedByRow() return axutils.prop(self.UI, "AXDisclosedByRow"):mutate(function(original) return self:parent():fetchRow(original()) @@ -60,8 +65,11 @@ end --- If available, returns a table of [Row](cp.ui.Row.md)s that are disclosed by this `Row`. --- If this row is currently unavailable, `nil` is returned. --- +--- Parameters: +--- * None +--- --- Returns: ---- * The `table` of Rows, or `nil`. +--- * The `table` of Rows, or `nil`. function Row:disclosedRows() local ui = self:UI() if ui then diff --git a/src/extensions/cp/ui/ScrollBar.lua b/src/extensions/cp/ui/ScrollBar.lua index e0d5fe80f..04a868ad1 100644 --- a/src/extensions/cp/ui/ScrollBar.lua +++ b/src/extensions/cp/ui/ScrollBar.lua @@ -22,10 +22,10 @@ ScrollBar.static.HORIZONTAL_ORIENTATION = "AXHorizontalOrientation" --- Checks if the element is a `ScrollBar`. --- --- Parameters: ---- * element - The `axuielement` being matched. +--- * element - The `axuielement` being matched. --- --- Returns: ---- * `true` if matches, otherwise `false`. +--- * `true` if matches, otherwise `false`. function ScrollBar.static.matches(element) return Element.matches(element) and element:attributeValue("AXRole") == "AXScrollBar" end @@ -35,11 +35,11 @@ end --- Creates a new `ScrollBar` instance with the specified `parent` and `uiFinder`. --- --- Parameters: ---- * parent - the parent object. ---- * uiFinder - a `function` or `cp.prop` that provides the `AXScrollBar` `axuielement`. +--- * parent - the parent object. +--- * uiFinder - a `function` or `cp.prop` that provides the `AXScrollBar` `axuielement`. --- --- Returns: ---- * The new `ScrollBar`. +--- * The new `ScrollBar`. --- cp.ui.ScrollBar.orientation --- Field @@ -101,8 +101,11 @@ end --- Method --- Saves the `ScrollBar` layout configuration. --- +--- Parameters: +--- * None +--- --- Returns: ---- * a `table` with the configuration parameters. +--- * a `table` with the configuration parameters. function ScrollBar:saveLayout() local layout = Element.saveLayout(self) layout.value = self:value() @@ -114,7 +117,7 @@ end --- Loads the provided `layout` table of configuration parameters. --- --- Parameters: ---- * layout - the table of parameters. +--- * layout - the table of parameters. function ScrollBar:loadLayout(layout) layout = layout or {} if layout.value then diff --git a/src/extensions/cp/ui/TextField.lua b/src/extensions/cp/ui/TextField.lua index d6a2f74fe..27bc83b39 100644 --- a/src/extensions/cp/ui/TextField.lua +++ b/src/extensions/cp/ui/TextField.lua @@ -99,6 +99,12 @@ end --- Method --- Configures the TextField to force a focus on the field before editing. --- Some fields seem to require this to actually update the +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Self function TextField:forceFocus() self._forceFocus = true return self @@ -148,6 +154,12 @@ end --- cp.ui.TextField:doConfirm() -> cp.rx.go.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will confirm the current text value. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function TextField.lazy.method:doConfirm() return If(self.UI) :Then(function(ui) @@ -162,6 +174,12 @@ end --- cp.ui.TextField:doFocus() -> cp.rx.go.Statement --- Method --- A [Statement](cp.rx.go.Statement.md) that will attempt to focus on the current `TextField`. +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * A Statement function TextField.lazy.method:doFocus() return If(self.focused):Is(false) :Then(function() diff --git a/src/extensions/cp/ui/Window.lua b/src/extensions/cp/ui/Window.lua index acc37f5df..319d0f7b2 100644 --- a/src/extensions/cp/ui/Window.lua +++ b/src/extensions/cp/ui/Window.lua @@ -24,6 +24,12 @@ local Window = class("cp.ui.Window"):include(lazy) --- cp.ui.Window.matches(element) -> boolean --- Function --- Checks if the provided element is a valid window. +--- +--- Parameters: +--- * element - An element to check +--- +--- Returns: +--- * A boolean function Window.static.matches(element) return element ~= nil and element:attributeValue("AXRole") == "AXWindow" end diff --git a/src/extensions/cp/ui/axutils.lua b/src/extensions/cp/ui/axutils.lua index b9c3afb15..beec511a8 100644 --- a/src/extensions/cp/ui/axutils.lua +++ b/src/extensions/cp/ui/axutils.lua @@ -459,9 +459,9 @@ end --- Function --- Returns `true` if element `a` is left of element `b`. May be used with `table.sort`. --- ---- Parameters ---- * a - The first element ---- * b - The second element +--- Parameters: +--- * a - The first element +--- * b - The second element --- --- Returns: --- * `true` if `a` is left of `b`. @@ -474,9 +474,9 @@ end --- Function --- Returns `true` if element `a` is right of element `b`. May be used with `table.sort`. --- ---- Parameters ---- * a - The first element ---- * b - The second element +--- Parameters: +--- * a - The first element +--- * b - The second element --- --- Returns: --- * `true` if `a` is right of `b`. @@ -489,9 +489,9 @@ end --- Function --- Returns `true` if element `a` is above element `b`. May be used with `table.sort`. --- ---- Parameters ---- * a - The first element ---- * b - The second element +--- Parameters: +--- * a - The first element +--- * b - The second element --- --- Returns: --- * `true` if `a` is above `b`. @@ -504,9 +504,9 @@ end --- Function --- Returns `true` if element `a` is below element `b`. May be used with `table.sort`. --- ---- Parameters ---- * a - The first element ---- * b - The second element +--- Parameters: +--- * a - The first element +--- * b - The second element --- --- Returns: --- * `true` if `a` is below `b`. diff --git a/src/extensions/cp/ui/notifier.lua b/src/extensions/cp/ui/notifier.lua index cb8189dfb..7280e5196 100644 --- a/src/extensions/cp/ui/notifier.lua +++ b/src/extensions/cp/ui/notifier.lua @@ -580,6 +580,12 @@ end --- cp.ui.notifier:reset() -> self --- Method --- Resets the notifier +--- +--- Parameters: +--- * None +--- +--- Returns: +--- * Self function mod.mt:reset() self:_stopObserving()