Merge pull request #26524 from MurtazaSaherwala:DocumentationUpdation

Updated trackbar callback function and improved documentation #26524

This Fixes #26467

Description:
This pull request improve the OpenCV documentation regarding the Trackbar functionality. The current documentation does not provide clear guidance on certain aspects, such as handling the value pointer deprecation and utilizing callback arguments in C. This update addresses those gaps and provides an updated example for better clarity.

Changes:
Updated Documentation:

Clarified the usage of the value pointer and explained how to pass an initial value, since the value pointer is deprecated.
Added more detailed explanations about callback arguments in C, ensuring that users understand how to access and use them in Trackbar callbacks.
Added a note on how to properly handle initial value passing without relying on the deprecated value pointer.
Updated Tutorial Example:

Renamed and used callback function parameters to make them more understandable.
Included a demonstration on how to utilize userdata in the callback function.
Additional Notes:

Removed reliance on the value pointer for updating trackbar values. Users are now encouraged to use other mechanisms as per the current implementation to avoid the runtime warning.

### Pull Request Readiness Checklist

See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request

- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
      Patch to opencv_extra has the same branch name.
- [] The feature is well documented and sample code can be built with the project CMake

apps/createsamples/utility.cpp

@@ -766,7 +766,6 @@ CvBackgroundData* icvCreateBackgroundData( const char* filename, Size winsize )
         }
         if( count > 0 )
         {
-            //rewind( input );
             fseek( input, 0, SEEK_SET );
             datasize += sizeof( *data ) + sizeof( char* ) * count;
             data = (CvBackgroundData*) fastMalloc( datasize );
@@ -872,8 +871,6 @@ void icvGetNextFromBackgroundData( CvBackgroundData* data,
 
     reader->src = img;
 
-    //reader->offset.x = round % data->winsize.width;
-    //reader->offset.y = round / data->winsize.width;
     reader->offset = offset;
     reader->point = reader->offset;
     reader->scale = MAX(

modules/highgui/include/opencv2/highgui.hpp

@@ -531,16 +531,20 @@ control panel.
 Clicking the label of each trackbar enables editing the trackbar values manually.
 
 @param trackbarname Name of the created trackbar.
-@param winname Name of the window that will be used as a parent of the created trackbar.
-@param value Optional pointer to an integer variable whose value reflects the position of the
-slider. Upon creation, the slider position is defined by this variable.
-@param count Maximal position of the slider. The minimal position is always 0.
-@param onChange Pointer to the function to be called every time the slider changes position. This
-function should be prototyped as void Foo(int,void\*); , where the first parameter is the trackbar
-position and the second parameter is the user data (see the next parameter). If the callback is
-the NULL pointer, no callbacks are called, but only value is updated.
-@param userdata User data that is passed as is to the callback. It can be used to handle trackbar
-events without using global variables.
+@param winname Name of the window that will contain the trackbar.
+@param value Pointer to the integer value that will be changed by the trackbar.
+Pass `nullptr` if the value pointer is not used. In this case, manually handle
+the trackbar position in the callback function.
+@param count Maximum position of the trackbar.
+@param onChange Pointer to the function to be called every time the slider changes position.
+This function should have the prototype void Foo(int, void\*);, where the first parameter is
+the trackbar position, and the second parameter is the user data (see the next parameter).
+If the callback is a nullptr, no callbacks are called, but the trackbar's value will still be
+updated automatically.
+@param userdata Optional user data that is passed to the callback.
+@note If the `value` pointer is `nullptr`, the trackbar position must be manually managed.
+Call the callback function manually with the desired initial value to avoid runtime warnings.
+@see #tutorial_trackbar
  */
 CV_EXPORTS int createTrackbar(const String& trackbarname, const String& winname,
                               int* value, int count,

samples/cpp/tutorial_code/HighGUI/AddingImagesTrackbar.cpp

@@ -27,9 +27,9 @@ Mat dst;
  * @function on_trackbar
  * @brief Callback for trackbar
  */
-static void on_trackbar( int, void* )
-{
-   alpha = (double) alpha_slider/alpha_slider_max ;
+static void on_trackbar(int pos, void* userdata) {
+    (void) userdata;
+    alpha = (double)pos / alpha_slider_max;
     beta = (1.0 - alpha);
     addWeighted(src1, alpha, src2, beta, 0.0, dst);
     imshow("Linear Blend", dst);
@@ -43,7 +43,7 @@ static void on_trackbar( int, void* )
 int main(void)
 {
     //![load]
-   /// Read images ( both have to be of the same size and type )
+    /// Read images (both must be of the same size and type)
     src1 = imread(samples::findFile("LinuxLogo.jpg"));
     src2 = imread(samples::findFile("WindowsLogo.jpg"));
     //![load]
@@ -51,7 +51,7 @@ int main( void )
     if (src1.empty()) { cout << "Error loading src1 \n"; return -1; }
     if (src2.empty()) { cout << "Error loading src2 \n"; return -1; }
 
-   /// Initialize values
+    // Initialize trackbar value
     alpha_slider = 0;
 
     //![window]
@@ -61,13 +61,14 @@ int main( void )
     //![create_trackbar]
     char TrackbarName[50];
     snprintf(TrackbarName, sizeof(TrackbarName), "Alpha x %d", alpha_slider_max);
+    // Example userdata: Pass a pointer to an integer as userdata
     createTrackbar(TrackbarName, "Linear Blend", &alpha_slider, alpha_slider_max, on_trackbar);
     //![create_trackbar]
 
-   /// Show some stuff
-   on_trackbar( alpha_slider, 0 );
+    /// Show initial result
+    on_trackbar(alpha_slider, nullptr);
 
-   /// Wait until user press some key
+    /// Wait for user input
     waitKey(0);
     return 0;
 }