modules/highgui/doc/user_interface.rst

   1 User Interface
   2 ==============
   3
   4 .. highlight:: cpp
   5
   6 createTrackbar
   7 ------------------
   8 Creates a trackbar and attaches it to the specified window.
   9
  10 .. ocv:function:: int createTrackbar( const string& trackbarname, const string& winname, int* value, int count, TrackbarCallback onChange=0, void* userdata=0)
  11
  12 .. ocv:cfunction:: int cvCreateTrackbar( const char* trackbar_name, const char* window_name, int* value, int count, CvTrackbarCallback on_change=NULL )
  13
  14 .. ocv:pyoldfunction:: cv.CreateTrackbar(trackbarName, windowName, value, count, onChange) -> None
  15
  16     :param trackbarname: Name of the created trackbar.
  17
  18     :param winname: Name of the window that will be used as a parent of the created trackbar.
  19
  20     :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.
  21
  22     :param count: Maximal position of the slider. The minimal position is always 0.
  23
  24     :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.
  25
  26     :param userdata: User data that is passed as is to the callback. It can be used to handle trackbar events without using global variables.
  27
  28 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 synchronized with the trackbar and specifies the callback function ``onChange`` to be called on the trackbar position change. The created trackbar is displayed in the specified window ``winname``.
  29
  30 .. note::
  31
  32     **[Qt Backend Only]** ``winname`` can be empty (or NULL) if the trackbar should be attached to the control panel.
  33
  34 Clicking the label of each trackbar enables editing the trackbar values manually.
  35
  36 getTrackbarPos
  37 ------------------
  38 Returns the trackbar position.
  39
  40 .. ocv:function:: int getTrackbarPos( const string& trackbarname, const string& winname )
  41
  42 .. ocv:pyfunction:: cv2.getTrackbarPos(trackbarname, winname) -> retval
  43
  44 .. ocv:cfunction:: int cvGetTrackbarPos( const char* trackbar_name, const char* window_name )
  45
  46 .. ocv:pyoldfunction:: cv.GetTrackbarPos(trackbarName, windowName) -> retval
  47
  48     :param trackbarname: Name of the trackbar.
  49
  50     :param winname: Name of the window that is the parent of the trackbar.
  51
  52 The function returns the current position of the specified trackbar.
  53
  54 .. note::
  55
  56     **[Qt Backend Only]** ``winname`` can be empty (or NULL) if the trackbar is attached to the control panel.
  57
  58 imshow
  59 ----------
  60 Displays an image in the specified window.
  61
  62 .. ocv:function:: void imshow( const string& winname, InputArray mat )
  63
  64 .. ocv:pyfunction:: cv2.imshow(winname, mat) -> None
  65
  66 .. ocv:cfunction:: void cvShowImage( const char* name, const CvArr* image )
  67
  68 .. ocv:pyoldfunction:: cv.ShowImage(name, image) -> None
  69
  70     :param winname: Name of the window.
  71
  72     :param image: Image to be shown.
  73
  74 The function ``imshow`` displays an image in the specified window. If the window was created with the ``CV_WINDOW_AUTOSIZE`` flag, the image is shown with its original size. Otherwise, the image is scaled to fit the window. The function may scale the image, depending on its depth:
  75
  76     * If the image is 8-bit unsigned, it is displayed as is.
  77
  78     * If the image is 16-bit unsigned or 32-bit integer, the pixels are divided by 256. That is, the value range [0,255*256] is mapped to [0,255].
  79
  80     * 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].
  81
  82
  83 namedWindow
  84 ---------------
  85 Creates a window.
  86
  87 .. ocv:function:: void namedWindow( const string& winname, int flags=WINDOW_AUTOSIZE )
  88
  89 .. ocv:pyfunction:: cv2.namedWindow(winname[, flags]) -> None
  90
  91 .. ocv:cfunction:: int cvNamedWindow( const char* name, int flags=CV_WINDOW_AUTOSIZE )
  92
  93 .. ocv:pyoldfunction:: cv.NamedWindow(name, flags=CV_WINDOW_AUTOSIZE)-> None
  94
  95     :param name: Name of the window in the window caption that may be used as a window identifier.
  96
  97     :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  :ocv:func:`imshow` ), and you cannot change the window size manually.
  98
  99 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.
 100
 101 If a window with the same name already exists, the function does nothing.
 102
 103 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.
 104
 105 .. note::
 106
 107     Qt backend supports additional flags:
 108
 109         * **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.
 110
 111         * **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.
 112
 113         * **CV_GUI_NORMAL or CV_GUI_EXPANDED:**   ``CV_GUI_NORMAL``  is the old way to draw the window without statusbar and toolbar, whereas  ``CV_GUI_EXPANDED``  is a new enhanced GUI.
 114
 115     By default, ``flags == CV_WINDOW_AUTOSIZE | CV_WINDOW_KEEPRATIO | CV_GUI_EXPANDED``
 116
 117
 118 destroyWindow
 119 -------------
 120 Destroys a window.
 121
 122 .. ocv:function:: void destroyWindow( const string& winname )
 123
 124 .. ocv:pyfunction:: cv2.destroyWindow(winname) -> None
 125
 126 .. ocv:cfunction:: void cvDestroyWindow( const char* name )
 127
 128 .. ocv:pyoldfunction:: cv.DestroyWindow(name)-> None
 129
 130     :param winname: Name of the window to be destroyed.
 131
 132 The function ``destroyWindow`` destroys the window with the given name.
 133
 134
 135 destroyAllWindows
 136 -----------------
 137 Destroys all of the HighGUI windows.
 138
 139 .. ocv:function:: void destroyAllWindows()
 140
 141 .. ocv:pyfunction:: cv2.destroyAllWindows() -> None
 142
 143 .. ocv:cfunction:: void cvDestroyAllWindows()
 144
 145 .. ocv:pyoldfunction:: cv.DestroyAllWindows()-> None
 146
 147 The function ``destroyAllWindows`` destroys all of the opened HighGUI windows.
 148
 149
 150 MoveWindow
 151 ----------
 152 Moves window to the specified position
 153
 154 .. ocv:function:: void moveWindow( const string& winname, int x, int y )
 155
 156 .. ocv:pyfunction:: cv2.moveWindow(winname, x, y) -> None
 157
 158 .. ocv:cfunction:: void cvMoveWindow( const char* name, int x, int y )
 159
 160 .. ocv:pyoldfunction:: cv.MoveWindow(name, x, y)-> None
 161
 162     :param winname: Window name
 163
 164     :param x: The new x-coordinate of the window
 165
 166     :param y: The new y-coordinate of the window
 167
 168
 169 ResizeWindow
 170 ------------
 171 Resizes window to the specified size
 172
 173 .. ocv:function:: void resizeWindow( const string& winname, int width, int height )
 174
 175 .. ocv:pyfunction:: cv2.resizeWindow(winname, width, height) -> None
 176
 177 .. ocv:cfunction:: void cvResizeWindow( const char* name, int width, int height )
 178
 179 .. ocv:pyoldfunction:: cv.ResizeWindow(name, width, height)-> None
 180
 181     :param winname: Window name
 182
 183     :param width: The new window width
 184
 185     :param height: The new window height
 186
 187 .. note::
 188
 189    * The specified window size is for the image area. Toolbars are not counted.
 190
 191    * Only windows created without CV_WINDOW_AUTOSIZE flag can be resized.
 192
 193
 194 SetMouseCallback
 195 ----------------
 196 Sets mouse handler for the specified window
 197
 198 .. ocv:function:: void setMouseCallback( const string& winname, MouseCallback onMouse, void* userdata=0 )
 199
 200 .. ocv:cfunction:: void cvSetMouseCallback( const char* window_name, CvMouseCallback on_mouse, void* param=NULL )
 201
 202 .. ocv:pyoldfunction:: cv.SetMouseCallback(windowName, onMouse, param=None) -> None
 203
 204     :param winname: Window name
 205
 206     :param onMouse: Mouse callback. See OpenCV samples, such as  http://code.opencv.org/projects/opencv/repository/revisions/master/entry/samples/cpp/ffilldemo.cpp, on how to specify and use the callback.
 207
 208     :param userdata: The optional parameter passed to the callback.
 209
 210
 211 setTrackbarPos
 212 ------------------
 213 Sets the trackbar position.
 214
 215 .. ocv:function:: void setTrackbarPos( const string& trackbarname, const string& winname, int pos )
 216
 217 .. ocv:pyfunction:: cv2.setTrackbarPos(trackbarname, winname, pos) -> None
 218
 219 .. ocv:cfunction:: void cvSetTrackbarPos( const char* trackbar_name, const char* window_name, int pos )
 220
 221 .. ocv:pyoldfunction:: cv.SetTrackbarPos(trackbarName, windowName, pos)-> None
 222
 223     :param trackbarname: Name of the trackbar.
 224
 225     :param winname: Name of the window that is the parent of trackbar.
 226
 227     :param pos: New position.
 228
 229 The function sets the position of the specified trackbar in the specified window.
 230
 231 .. note::
 232
 233     **[Qt Backend Only]** ``winname`` can be empty (or NULL) if the trackbar is attached to the control panel.
 234
 235 waitKey
 236 -----------
 237 Waits for a pressed key.
 238
 239 .. ocv:function:: int waitKey(int delay=0)
 240
 241 .. ocv:pyfunction:: cv2.waitKey([delay]) -> retval
 242
 243 .. ocv:cfunction:: int cvWaitKey( int delay=0 )
 244
 245 .. ocv:pyoldfunction:: cv.WaitKey(delay=0)-> int
 246
 247     :param delay: Delay in milliseconds. 0 is the special value that means "forever".
 248
 249 The function ``waitKey`` waits for a key event infinitely (when
 250 :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.
 251
 252 .. note::
 253
 254     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.
 255
 256 .. note::
 257
 258     The function only works if there is at least one HighGUI window created and the window is active. If there are several HighGUI windows, any of them can be active.