From 9bb4e025caddd16e3cd79f0160ae444bb2c1b2b5 Mon Sep 17 00:00:00 2001 From: ed Date: Thu, 28 Dec 2017 17:02:58 +0000 Subject: [PATCH] Made the documentation of some classes clearer regarding when a notification will be sent --- .../filebrowser/juce_FilenameComponent.h | 3 ++- .../juce_gui_basics/layout/juce_ScrollBar.h | 27 +++++++++++++++++++ modules/juce_gui_basics/widgets/juce_Slider.h | 12 ++++++--- .../juce_gui_basics/widgets/juce_TreeView.h | 2 +- .../juce_gui_extra/misc/juce_ColourSelector.h | 7 ++++- 5 files changed, 44 insertions(+), 7 deletions(-) diff --git a/modules/juce_gui_basics/filebrowser/juce_FilenameComponent.h b/modules/juce_gui_basics/filebrowser/juce_FilenameComponent.h index 72706db6d3..9463d8aaec 100644 --- a/modules/juce_gui_basics/filebrowser/juce_FilenameComponent.h +++ b/modules/juce_gui_basics/filebrowser/juce_FilenameComponent.h @@ -112,7 +112,8 @@ public: @param newFile the new filename to use @param addToRecentlyUsedList if true, the filename will also be added to the drop-down list of recent files. - @param notification whether to send a notification of the change to listeners + @param notification whether to send a notification of the change to listeners. + A notification will only be sent if the filename has changed. */ void setCurrentFile (File newFile, bool addToRecentlyUsedList, diff --git a/modules/juce_gui_basics/layout/juce_ScrollBar.h b/modules/juce_gui_basics/layout/juce_ScrollBar.h index c52efa5dd3..c4d7ec7878 100644 --- a/modules/juce_gui_basics/layout/juce_ScrollBar.h +++ b/modules/juce_gui_basics/layout/juce_ScrollBar.h @@ -95,6 +95,10 @@ public: The bar's thumb will always be constrained so that the entire thumb lies within this range. + @param newRangeLimit the new range. + @param notification whether to send a notification of the change to listeners. + A notification will only be sent if the range has changed. + @see setCurrentRange */ void setRangeLimits (Range newRangeLimit, @@ -105,6 +109,11 @@ public: The bar's thumb will always be constrained so that the entire thumb lies within this range. + @param minimum the new range minimum. + @param maximum the new range maximum. + @param notification whether to send a notification of the change to listeners. + A notification will only be sent if the range has changed. + @see setCurrentRange */ void setRangeLimits (double minimum, double maximum, @@ -208,6 +217,11 @@ public: A positive value here will move the bar down or to the right, a negative value moves it up or to the left. + + @param howManySteps the number of steps to move the scrollbar + @param notification whether to send a notification of the change to listeners. + A notification will only be sent if the position has changed. + @returns true if the scrollbar's position actually changed. */ bool moveScrollbarInSteps (int howManySteps, @@ -220,6 +234,11 @@ public: A positive value here will move the bar down or to the right, a negative value moves it up or to the left. + + @param howManyPages the number of pages to move the scrollbar + @param notification whether to send a notification of the change to listeners. + A notification will only be sent if the position has changed. + @returns true if the scrollbar's position actually changed. */ bool moveScrollbarInPages (int howManyPages, @@ -227,12 +246,20 @@ public: /** Scrolls to the top (or left). This is the same as calling setCurrentRangeStart (getMinimumRangeLimit()); + + @param notification whether to send a notification of the change to listeners. + A notification will only be sent if the position has changed. + @returns true if the scrollbar's position actually changed. */ bool scrollToTop (NotificationType notification = sendNotificationAsync); /** Scrolls to the bottom (or right). This is the same as calling setCurrentRangeStart (getMaximumRangeLimit() - getCurrentRangeSize()); + + @param notification whether to send a notification of the change to listeners. + A notification will only be sent if the position has changed. + @returns true if the scrollbar's position actually changed. */ bool scrollToBottom (NotificationType notification = sendNotificationAsync); diff --git a/modules/juce_gui_basics/widgets/juce_Slider.h b/modules/juce_gui_basics/widgets/juce_Slider.h index fb15579197..08dcd55232 100644 --- a/modules/juce_gui_basics/widgets/juce_Slider.h +++ b/modules/juce_gui_basics/widgets/juce_Slider.h @@ -377,7 +377,8 @@ public: nearest interval if one has been set @param notification can be one of the NotificationType values, to request a synchronous or asynchronous call to the valueChanged() method - of any Slider::Listeners that are registered. + of any Slider::Listeners that are registered. A notification will + only be sent if the Slider's value has changed. */ void setValue (double newValue, NotificationType notification = sendNotificationAsync); @@ -460,7 +461,8 @@ public: interval if one has been set. @param notification can be one of the NotificationType values, to request a synchronous or asynchronous call to the valueChanged() method - of any Slider::Listeners that are registered. + of any Slider::Listeners that are registered. A notification will + only be sent if this value has changed. @param allowNudgingOfOtherValues if false, this value will be restricted to being below the max value (in a two-value slider) or the mid value (in a three-value slider). If true, then if this value goes beyond those values, @@ -500,7 +502,8 @@ public: interval if one has been set. @param notification can be one of the NotificationType values, to request a synchronous or asynchronous call to the valueChanged() method - of any Slider::Listeners that are registered. + of any Slider::Listeners that are registered. A notification will + only be sent if this value has changed. @param allowNudgingOfOtherValues if false, this value will be restricted to being above the min value (in a two-value slider) or the mid value (in a three-value slider). If true, then if this value goes beyond those values, @@ -523,7 +526,8 @@ public: nearest interval if one has been set. @param notification can be one of the NotificationType values, to request a synchronous or asynchronous call to the valueChanged() method - of any Slider::Listeners that are registered. + of any Slider::Listeners that are registered. A notification will + only be sent if one or more of the values has changed. @see setMaxValue, setMinValue, setValue */ void setMinAndMaxValues (double newMinValue, double newMaxValue, diff --git a/modules/juce_gui_basics/widgets/juce_TreeView.h b/modules/juce_gui_basics/widgets/juce_TreeView.h index 1db4dacd37..8cd0a20f48 100644 --- a/modules/juce_gui_basics/widgets/juce_TreeView.h +++ b/modules/juce_gui_basics/widgets/juce_TreeView.h @@ -182,7 +182,7 @@ public: /** Selects or deselects the item. If shouldNotify == sendNotification, then a callback will be made - to itemSelectionChanged() + to itemSelectionChanged() if the item's selection has changed. */ void setSelected (bool shouldBeSelected, bool deselectOtherItemsFirst, diff --git a/modules/juce_gui_extra/misc/juce_ColourSelector.h b/modules/juce_gui_extra/misc/juce_ColourSelector.h index 83c2fe622d..fab177e9a5 100644 --- a/modules/juce_gui_extra/misc/juce_ColourSelector.h +++ b/modules/juce_gui_extra/misc/juce_ColourSelector.h @@ -80,7 +80,12 @@ public: */ Colour getCurrentColour() const; - /** Changes the colour that is currently being shown. */ + /** Changes the colour that is currently being shown. + + @param newColour the new colour to show + @param notification whether to send a notification of the change to listeners. + A notification will only be sent if the colour has changed. + */ void setCurrentColour (Colour newColour, NotificationType notificationType = sendNotification); //==============================================================================