Purpose: 2nd review cycle.

modules/highgui/doc/user_interface.rst

@@ -3,14 +3,15 @@ User Interface
 
 .. highlight:: cpp
 
+.. index:: createTrackbar
+
+.. _createTrackbar:
+
 createTrackbar
 ------------------
-Creates a trackbar and attaches it to the specified window.
-
 .. ocv:function:: int createTrackbar( const string& trackbarname, const string& winname, int* value, int count, TrackbarCallback onChange=0, void* userdata=0)
 
-.. ocv:cfunction:: int cvCreateTrackbar( const char* trackbarName, const char* windowName, int* value, int count, CvTrackbarCallback onChange )
-.. ocv:pyoldfunction:: CreateTrackbar(trackbarName, windowName, value, count, onChange) -> None
+    Creates a trackbar and attaches it to the specified window.
 
     :param trackbarname: Name of the created trackbar.
 
@@ -24,7 +25,7 @@ Creates a trackbar and attaches it to the specified window.
 
     :param userdata: User data that is passed as is to the callback. It can be used to handle trackbar events without using global variables.
 
-The function ``createTrackbar`` creates a trackbar (a.k.a. slider or range control) with the specified name and range, assigns a variable ``value`` to be syncronized with the trackbar position and specifies the callback function ``onChange`` to be called on the trackbar position change. The created trackbar is displayed on top of the given window.
+The function ``createTrackbar`` creates a trackbar (a slider or range control) with the specified name and range, assigns a variable ``value`` to be a position syncronized with the trackbar and specifies the callback function ``onChange`` to be called on the trackbar position change. The created trackbar is displayed on top of the given window.
 
 
 **[Qt Backend Only]**
@@ -40,14 +41,13 @@ is NULL.
 
 Clicking the label of each trackbar enables editing the trackbar values manually for a more accurate control of it.
 
+.. index:: getTrackbarPos
+
 getTrackbarPos
 ------------------
-Returns the trackbar position.
-
 .. ocv:function:: int getTrackbarPos( const string& trackbarname, const string& winname )
 
-.. ocv:cfunction:: int cvGetTrackbarPos( const char* trackbarName, const char* windowName )
-.. ocv:pyoldfunction:: GetTrackbarPos(trackbarName, windowName)-> None
+    Returns the trackbar position.
 
     :param trackbarname: Name of the trackbar.
 
@@ -61,12 +61,16 @@ Qt-specific details:
 
     * **winname** Name of the window that is the parent of the trackbar. It can be NULL if the trackbar is attached to the control panel.
 
+.. index:: imshow
+
+.. _imshow:
+
 imshow
 ----------
-Displays an image in the specified window.
-
 .. ocv:function:: void imshow( const string& winname, InputArray image )
 
+    Displays an image in the specified window.
+
     :param winname: Name of the window.
 
     :param image: Image to be shown.
@@ -82,25 +86,25 @@ The function ``imshow`` displays an image in the specified window. If the window
 *
     If the image is 32-bit floating-point, the pixel values are multiplied by 255. That is, the value range [0,1] is mapped to [0,255].
 
+.. index:: namedWindow
+
+.. _namedWindow:
 
 namedWindow
 ---------------
-Creates a window.
-
 .. ocv:function:: void namedWindow( const string& winname, int flags )
 
-.. ocv:cfunction:: int cvNamedWindow( const char* name, int flags )
-.. ocv:pyoldfunction:: NamedWindow(name, flags=CV_WINDOW_AUTOSIZE)-> None
+    Creates a window.
 
     :param name: Name of the window in the window caption that may be used as a window identifier.
 
-    :param flags: Flags of the window. Currently the only supported flag is  ``CV_WINDOW_AUTOSIZE`` . If this is set, the window size is automatically adjusted to fit the displayed image (see  :ref:`imshow` ), and you cannot change the window size manually.
+    :param flags: Flags of the window. Currently the only supported flag is  ``CV_WINDOW_AUTOSIZE`` . If it is set, the window size is automatically adjusted to fit the displayed image (see  :ocv:func:`imshow` ), and you cannot change the window size manually.
 
 The function ``namedWindow`` creates a window that can be used as a placeholder for images and trackbars. Created windows are referred to by their names.
 
 If a window with the same name already exists, the function does nothing.
 
-You can call :cpp:func:`destroyWindow` or :cpp:func:`destroyAllWindows` to close the window and de-allocate any associated memory usage. For a simple program, you do not really have to call these functions because all the resources and windows of the application are closed automatically by the operating system upon exit.
+You can call :ocv:func:`destroyWindow` or :ocv:func:`destroyAllWindows` to close the window and de-allocate any associated memory usage. For a simple program, you do not really have to call these functions because all the resources and windows of the application are closed automatically by the operating system upon exit.
 
 
 **[Qt Backend Only]**
@@ -108,7 +112,7 @@ Qt-specific details:
 
     * **flags** Flags of the window. Currently the supported flags are:
 
-            * **CV_WINDOW_NORMAL or CV_WINDOW_AUTOSIZE:**   ``CV_WINDOW_NORMAL``  enables you to resize the window, whereas   ``CV_WINDOW_AUTOSIZE``  adjusts automatically the window size to fit the displayed image (see  :ref:`imshow` ), and you cannot change the window size manually.
+            * **CV_WINDOW_NORMAL or CV_WINDOW_AUTOSIZE:**   ``CV_WINDOW_NORMAL``  enables you to resize the window, whereas   ``CV_WINDOW_AUTOSIZE``  adjusts automatically the window size to fit the displayed image (see  :ocv:func:`imshow` ), and you cannot change the window size manually.
 
             * **CV_WINDOW_FREERATIO or CV_WINDOW_KEEPRATIO:** ``CV_WINDOW_FREERATIO``  adjusts the image with no respect to its ratio, whereas  ``CV_WINDOW_KEEPRATIO``  keeps the image ratio.
 
@@ -120,46 +124,52 @@ Qt-specific details:
 
         ::
 
-            namedWindow( "myWindow", CV_WINDOW_NORMAL | CV_GUI_NORMAL );
+            namedWindow( ``myWindow'', ``CV_WINDOW_NORMAL``   textbar   ``CV_GUI_NORMAL`` );
 
         ..
 
 
+.. index:: destroyWindow
+
+.. _destroyWindow:
+
 destroyWindow
 -------------
-Destroys a window.
-
 .. ocv:function:: void destroyWindow( const string &winname )
-            
-.. ocv:cfunction:: void cvDestroyWindow( const char* name )
-.. ocv:pyoldfunction:: DestroyWindow(name)-> None
 
+    Destroys a window.
+            
     :param winname: Name of the window to be destroyed. 
                                            
 The function ``destroyWindow`` destroys the window with the given name.
 
 
+.. index:: destroyAllWindows
+
+.. _destroyAllWindows:
+
 destroyAllWindows
 -----------------
-Destroys all of the HighGUI windows.
-
 .. ocv:function:: void destroyAllWindows()
 
+    Destroys all of the HighGUI windows.
+
 The function ``destroyAllWindows`` destroys all of the opened HighGUI windows.
 
 
+.. index:: setTrackbarPos
+
+.. _setTrackbarPos:
+
 setTrackbarPos
 ------------------
-Sets the trackbar position.
-
 .. ocv:function:: void setTrackbarPos( const string& trackbarname, const string& winname, int pos )
 
-.. ocv:cfunction:: void cvSetTrackbarPos( const char* trackbarName, const char* windowName, int pos )
-.. ocv:pyoldfunction:: SetTrackbarPos(trackbarName, windowName, pos)-> None
+    Sets the trackbar position.
 
     :param trackbarname: Name of the trackbar.
 
-    :param winname: Name of the window that is the parent of trackbar.
+    :param winname: Name of the window that is the parent of the trackbar.
 
     :param pos: New position.
 
@@ -171,21 +181,22 @@ Qt-specific details:
 
     * **winname** Name of the window that is the parent of the trackbar. It can be NULL if the trackbar is attached to the control panel.
 
+.. index:: waitKey
+
+.. _waitKey:
+
 waitKey
 -----------
-Waits for a pressed key.
-
 .. ocv:function:: int waitKey(int delay=0)
 
-.. ocv:cfunction:: int cvWaitKey( int delay=0 )
-.. ocv:pyoldfunction:: WaitKey(delay=0)-> int
+    Waits for a pressed key.
 
     :param delay: Delay in milliseconds. 0 is the special value that means "forever".
 
 The function ``waitKey`` waits for a key event infinitely (when
-:math:`\texttt{delay}\leq 0` ) or for ``delay`` milliseconds, when it is positive. Since the OS has a minimum time between switching threads, the function will not wait exactly ``delay`` ms, it will wait at least ``delay`` ms, depending on what else is running on your computer at that time. It returns the code of the pressed key or -1 if no key was pressed before the specified time had elapsed.
+:math:`\texttt{delay}\leq 0` ) or for ``delay`` milliseconds, when it is positive. It returns the code of the pressed key or -1 if no key was pressed before the specified time had elapsed.
 
-**Notes:**
+.. note::
 
 * This function is the only method in HighGUI that can fetch and handle events, so it needs to be called periodically for normal event processing unless HighGUI is used within an environment that takes care of event processing.