Debian Codegraph @

src/Graphics/UI/GLUT/Window.hs

raw
1 --------------------------------------------------------------------------------
2 -- |
3 -- Module : Graphics.UI.GLUT.Window
4 -- Copyright : (c) Sven Panne 2002-2018
5 -- License : BSD3
6 --
7 -- Maintainer : Sven Panne <[email protected]>
8 -- Stability : stable
9 -- Portability : portable
10 --
11 -- GLUT supports two types of windows: top-level windows and subwindows. Both
12 -- types support OpenGL rendering and GLUT callbacks. There is a single
13 -- identifier space for both types of windows.
14 --
15 --------------------------------------------------------------------------------
16
17 module Graphics.UI.GLUT.Window (
18 -- * Window identifiers
19 Window,
20
21 -- * Creating and destroying (sub-)windows
22
23 -- $CreatingAndDestroyingSubWindows
24 createWindow, createSubWindow, destroyWindow,
25 parentWindow, numSubWindows,
26
27 -- * Manipulating the /current window/
28 currentWindow,
29
30 -- * Re-displaying and double buffer management
31 postRedisplay, swapBuffers,
32
33 -- * Changing the window geometry
34
35 -- $ChangingTheWindowGeometry
36 windowPosition, windowSize, fullScreen, fullScreenToggle, leaveFullScreen,
37
38 -- * Manipulating the stacking order
39
40 -- $ManipulatingTheStackingOrder
41 pushWindow, popWindow,
42
43 -- * Managing a window\'s display status
44 WindowStatus(..), windowStatus,
45
46 -- * Changing the window\/icon title
47
48 -- $ChangingTheWindowIconTitle
49 windowTitle, iconTitle,
50
51 -- * Cursor management
52 Cursor(..), cursor, pointerPosition
53 ) where
54
55 import Control.Monad.IO.Class ( MonadIO(..) )
56 import Data.StateVar ( GettableStateVar, makeGettableStateVar
57 , SettableStateVar, makeSettableStateVar
58 , StateVar, makeStateVar )
59 import Foreign.C.String ( withCString )
60 import Foreign.C.Types ( CInt )
61 import Graphics.Rendering.OpenGL ( Position(..), Size(..) )
62
63 import Graphics.UI.GLUT.QueryUtils
64 import Graphics.UI.GLUT.Raw
65 import Graphics.UI.GLUT.Types
66
67 --------------------------------------------------------------------------------
68
69 -- $CreatingAndDestroyingSubWindows
70 -- Each created window has a unique associated OpenGL context. State changes to
71 -- a window\'s associated OpenGL context can be done immediately after the
72 -- window is created.
73 --
74 -- The /display state/ of a window is initially for the window to be shown. But
75 -- the window\'s /display state/ is not actually acted upon until
76 -- 'Graphics.UI.GLUT.Begin.mainLoop' is entered. This means until
77 -- 'Graphics.UI.GLUT.Begin.mainLoop' is called, rendering to a created window is
78 -- ineffective because the window can not yet be displayed.
79 --
80 -- The value returned by 'createWindow' and 'createSubWindow' is a unique
81 -- identifier for the window, which can be used with 'currentWindow'.
82
83 -- | Create a top-level window. The given name will be provided to the window
84 -- system as the window\'s name. The intent is that the window system will label
85 -- the window with the name.Implicitly, the /current window/ is set to the newly
86 -- created window.
87 --
88 -- /X Implementation Notes:/ The proper X Inter-Client Communication Conventions
89 -- Manual (ICCCM) top-level properties are established. The @WM_COMMAND@
90 -- property that lists the command line used to invoke the GLUT program is only
91 -- established for the first window created.
92
93 createWindow
94 :: MonadIO m
95 => String -- ^ The window name
96 -> m Window -- ^ The identifier for the newly created window
97 createWindow name = liftIO $ fmap Window $ withCString name glutCreateWindow
98
99 --------------------------------------------------------------------------------
100
101 -- | Create a subwindow of the identified window with the given relative
102 -- position and size. Implicitly, the /current window/ is set to the
103 -- newly created subwindow. Subwindows can be nested arbitrarily deep.
104
105 createSubWindow
106 :: MonadIO m
107 => Window -- ^ Identifier of the subwindow\'s parent window.
108 -> Position -- ^ Window position in pixels relative to parent window\'s
109 -- origin.
110 -> Size -- ^ Window size in pixels
111 -> m Window -- ^ The identifier for the newly created subwindow
112 createSubWindow (Window win) (Position x y) (Size w h) = do
113 s <- glutCreateSubWindow win
114 (fromIntegral x) (fromIntegral y)
115 (fromIntegral w) (fromIntegral h)
116 return $ Window s
117
118 --------------------------------------------------------------------------------
119
120 -- | Contains the /current window\'s/ parent. If the /current window/ is a
121 -- top-level window, 'Nothing' is returned.
122
123 parentWindow :: GettableStateVar (Maybe Window)
124 parentWindow =
125 makeGettableStateVar $
126 getWindow (simpleGet Window glut_WINDOW_PARENT)
127
128 --------------------------------------------------------------------------------
129
130 -- | Contains the number of subwindows the /current window/ has, not counting
131 -- children of children.
132
133 numSubWindows :: GettableStateVar Int
134 numSubWindows =
135 makeGettableStateVar $
136 simpleGet fromIntegral glut_WINDOW_NUM_CHILDREN
137
138 --------------------------------------------------------------------------------
139
140 -- | Destroy the specified window and the window\'s associated OpenGL context,
141 -- logical colormap (if the window is color index), and overlay and related
142 -- state (if an overlay has been established). Any subwindows of the destroyed
143 -- window are also destroyed by 'destroyWindow'. If the specified window was the
144 -- /current window/, the /current window/ becomes invalid ('currentWindow' will
145 -- contain 'Nothing').
146
147 destroyWindow :: MonadIO m => Window -> m ()
148 destroyWindow (Window win) = glutDestroyWindow win
149
150 --------------------------------------------------------------------------------
151
152 -- | Controls the /current window/. It does /not/ affect the /layer in use/ for
153 -- the window; this is done using 'Graphics.UI.GLUT.Overlay.layerInUse'.
154 -- Contains 'Nothing' if no windows exist or the previously /current window/ was
155 -- destroyed. Setting the /current window/ to 'Nothing' is a no-op.
156
157 currentWindow :: StateVar (Maybe Window)
158 currentWindow =
159 makeStateVar
160 (getWindow (fmap Window glutGetWindow))
161 (maybe (return ()) (\(Window win) -> glutSetWindow win))
162
163 getWindow :: IO Window -> IO (Maybe Window)
164 getWindow act = do
165 win <- act
166 return $ if win == Window 0 then Nothing else Just win
167
168 --------------------------------------------------------------------------------
169
170 -- | Mark the normal plane of given window (or the /current window/, if none
171 -- is supplied) as needing to be redisplayed. The next iteration through
172 -- 'Graphics.UI.GLUT.Begin.mainLoop', the window\'s display callback will be
173 -- called to redisplay the window\'s normal plane. Multiple calls to
174 -- 'postRedisplay' before the next display callback opportunity generates only a
175 -- single redisplay callback. 'postRedisplay' may be called within a window\'s
176 -- display or overlay display callback to re-mark that window for redisplay.
177 --
178 -- Logically, normal plane damage notification for a window is treated as a
179 -- 'postRedisplay' on the damaged window. Unlike damage reported by the window
180 -- system, 'postRedisplay' will /not/ set to true the normal plane\'s damaged
181 -- status (see 'Graphics.UI.GLUT.State.damaged').
182 --
183 -- Also, see 'Graphics.UI.GLUT.Overlay.postOverlayRedisplay'.
184
185 postRedisplay :: MonadIO m => Maybe Window -> m ()
186 postRedisplay = maybe glutPostRedisplay (\(Window win) -> glutPostWindowRedisplay win)
187
188 -- | Mark the normal plane of the given window as needing to be redisplayed,
189 -- otherwise the same as 'postRedisplay'.
190 --
191 -- The advantage of this routine is that it saves the cost of using
192 -- 'currentWindow' (entailing an expensive OpenGL context switch), which is
193 -- particularly useful when multiple windows need redisplays posted at the same
194 -- time.
195
196 --------------------------------------------------------------------------------
197
198 -- | Perform a buffer swap on the /layer in use/ for the /current window/.
199 -- Specifically, 'swapBuffers' promotes the contents of the back buffer of the
200 -- /layer in use/ of the /current window/ to become the contents of the front
201 -- buffer. The contents of the back buffer then become undefined. The update
202 -- typically takes place during the vertical retrace of the monitor, rather than
203 -- immediately after 'swapBuffers' is called.
204 --
205 -- An implicit 'Graphics.Rendering.OpenGL.GL.FlushFinish.flush' is done by
206 -- 'swapBuffers' before it returns. Subsequent OpenGL commands can be issued
207 -- immediately after calling 'swapBuffers', but are not executed until the
208 -- buffer exchange is completed.
209 --
210 -- If the /layer in use/ is not double buffered, 'swapBuffers' has no effect.
211
212 swapBuffers :: MonadIO m => m ()
213 swapBuffers = glutSwapBuffers
214
215 --------------------------------------------------------------------------------
216
217 -- $ChangingTheWindowGeometry
218 -- Note that the requests by 'windowPosition', 'windowSize', and 'fullScreen'
219 -- are not processed immediately. A request is executed after returning to the
220 -- main event loop. This allows multiple requests to the same window to be
221 -- coalesced.
222 --
223 -- 'windowPosition' and 'windowSize' requests on a window will disable the full
224 -- screen status of the window.
225
226 --------------------------------------------------------------------------------
227
228 -- | Controls the position of the /current window/. For top-level windows,
229 -- parameters of 'Position' are pixel offsets from the screen origin. For
230 -- subwindows, the parameters are pixel offsets from the window\'s parent window
231 -- origin.
232 --
233 -- In the case of top-level windows, setting 'windowPosition' is considered only
234 -- a request for positioning the window. The window system is free to apply its
235 -- own policies to top-level window placement. The intent is that top-level
236 -- windows should be repositioned according to the value of 'windowPosition'.
237
238 windowPosition :: StateVar Position
239 windowPosition = makeStateVar getWindowPosition setWindowPosition
240
241 setWindowPosition :: Position -> IO ()
242 setWindowPosition (Position x y) =
243 glutPositionWindow (fromIntegral x) (fromIntegral y)
244
245 getWindowPosition :: IO Position
246 getWindowPosition = do
247 x <- simpleGet fromIntegral glut_WINDOW_X
248 y <- simpleGet fromIntegral glut_WINDOW_Y
249 return $ Position x y
250
251 --------------------------------------------------------------------------------
252
253 -- | Controls the size of the /current window/. The parameters of 'Size' are
254 -- size extents in pixels. The width and height must be positive values.
255 --
256 -- In the case of top-level windows, setting 'windowSize' is considered only a
257 -- request for sizing the window. The window system is free to apply its own
258 -- policies to top-level window sizing. The intent is that top-level windows
259 -- should be reshaped according to the value of 'windowSize'. Whether a reshape
260 -- actually takes effect and, if so, the reshaped dimensions are reported to the
261 -- program by a reshape callback.
262
263 windowSize :: StateVar Size
264 windowSize = makeStateVar getWindowSize setWindowSize
265
266 setWindowSize :: Size -> IO ()
267 setWindowSize (Size w h) =
268 glutReshapeWindow (fromIntegral w) (fromIntegral h)
269
270 getWindowSize :: IO Size
271 getWindowSize = do
272 w <- simpleGet fromIntegral glut_WINDOW_WIDTH
273 h <- simpleGet fromIntegral glut_WINDOW_HEIGHT
274 return $ Size w h
275
276 --------------------------------------------------------------------------------
277
278 -- | Request that the /current window/ be made full screen. The exact semantics
279 -- of what full screen means may vary by window system. The intent is to make
280 -- the window as large as possible and disable any window decorations or borders
281 -- added the window system. The window width and height are not guaranteed to be
282 -- the same as the screen width and height, but that is the intent of making a
283 -- window full screen.
284 --
285 -- 'fullScreen' is defined to work only on top-level windows.
286 --
287 -- /X Implementation Notes:/ In the X implementation of GLUT, full screen is
288 -- implemented by sizing and positioning the window to cover the entire screen
289 -- and posting the @_MOTIF_WM_HINTS@ property on the window requesting
290 -- absolutely no decorations. Non-Motif window managers may not respond to
291 -- @_MOTIF_WM_HINTS@.
292
293 fullScreen :: MonadIO m => m ()
294 fullScreen = glutFullScreen
295
296 --------------------------------------------------------------------------------
297
298 -- | (/freeglut only/) Toggle between windowed and full screen mode.
299
300 fullScreenToggle :: MonadIO m => m ()
301 fullScreenToggle = glutFullScreenToggle
302
303 --------------------------------------------------------------------------------
304
305 -- | (/freeglut only/) If we are in full screen mode, resize the current window
306 -- back to its original size.
307
308 leaveFullScreen :: MonadIO m => m ()
309 leaveFullScreen = glutLeaveFullScreen
310
311 --------------------------------------------------------------------------------
312
313 -- $ManipulatingTheStackingOrder
314 -- 'pushWindow' and 'popWindow' work on both top-level windows and subwindows.
315 -- The effect of pushing and popping windows does not take place immediately.
316 -- Instead the push or pop is saved for execution upon return to the GLUT event
317 -- loop. Subsequent pop or push requests on a window replace the previously
318 -- saved request for that window. The effect of pushing and popping top-level
319 -- windows is subject to the window system\'s policy for restacking windows.
320
321 -- | Change the stacking order of the /current window/ relative to its siblings
322 -- (lowering it).
323
324 pushWindow :: MonadIO m => m ()
325 pushWindow = glutPushWindow
326
327 -- | Change the stacking order of the /current window/ relative to its siblings,
328 -- bringing the /current window/ closer to the top.
329
330 popWindow :: MonadIO m => m ()
331 popWindow = glutPopWindow
332
333 --------------------------------------------------------------------------------
334
335 -- | The display status of a window.
336
337 data WindowStatus
338 = Shown
339 | Hidden
340 | Iconified
341 deriving ( Eq, Ord, Show )
342
343 -- | Controls the display status of the /current window/.
344 --
345 -- Note that the effect of showing, hiding, and iconifying windows does not take
346 -- place immediately. Instead the requests are saved for execution upon return
347 -- to the GLUT event loop. Subsequent show, hide, or iconification requests on a
348 -- window replace the previously saved request for that window. The effect of
349 -- hiding, showing, or iconifying top-level windows is subject to the window
350 -- system\'s policy for displaying windows. Subwindows can\'t be iconified.
351
352 windowStatus :: SettableStateVar WindowStatus
353 windowStatus = makeSettableStateVar setStatus
354 where setStatus Shown = glutShowWindow
355 setStatus Hidden = glutHideWindow
356 setStatus Iconified = glutIconifyWindow
357
358 --------------------------------------------------------------------------------
359
360 -- $ChangingTheWindowIconTitle
361 -- 'windowTitle' and 'iconTitle' should be set only when the /current
362 -- window/ is a top-level window. Upon creation of a top-level window, the
363 -- window and icon names are determined by the name given to 'createWindow'.
364 -- Once created, setting 'windowTitle' and 'iconTitle' can change the window and
365 -- icon names respectively of top-level windows. Each call requests the window
366 -- system change the title appropriately. Requests are not buffered or
367 -- coalesced. The policy by which the window and icon name are displayed is
368 -- window system dependent.
369
370 -- | Controls the window title of the /current top-level window/.
371
372 windowTitle :: SettableStateVar String
373 windowTitle =
374 makeSettableStateVar $ \name ->
375 withCString name glutSetWindowTitle
376
377 -- | Controls the icon title of the /current top-level window/.
378
379 iconTitle :: SettableStateVar String
380 iconTitle =
381 makeSettableStateVar $ \name ->
382 withCString name glutSetIconTitle
383
384 --------------------------------------------------------------------------------
385
386 -- | The different cursor images GLUT supports.
387
388 data Cursor
389 = RightArrow -- ^ Arrow pointing up and to the right.
390 | LeftArrow -- ^ Arrow pointing up and to the left.
391 | Info -- ^ Pointing hand.
392 | Destroy -- ^ Skull & cross bones.
393 | Help -- ^ Question mark.
394 | Cycle -- ^ Arrows rotating in a circle.
395 | Spray -- ^ Spray can.
396 | Wait -- ^ Wrist watch.
397 | Text -- ^ Insertion point cursor for text.
398 | Crosshair -- ^ Simple cross-hair.
399 | UpDown -- ^ Bi-directional pointing up & down.
400 | LeftRight -- ^ Bi-directional pointing left & right.
401 | TopSide -- ^ Arrow pointing to top side.
402 | BottomSide -- ^ Arrow pointing to bottom side.
403 | LeftSide -- ^ Arrow pointing to left side.
404 | RightSide -- ^ Arrow pointing to right side.
405 | TopLeftCorner -- ^ Arrow pointing to top-left corner.
406 | TopRightCorner -- ^ Arrow pointing to top-right corner.
407 | BottomRightCorner -- ^ Arrow pointing to bottom-left corner.
408 | BottomLeftCorner -- ^ Arrow pointing to bottom-right corner.
409 | Inherit -- ^ Use parent\'s cursor.
410 | None -- ^ Invisible cursor.
411 | FullCrosshair -- ^ Full-screen cross-hair cursor (if possible, otherwise 'Crosshair').
412 deriving ( Eq, Ord, Show )
413
414 marshalCursor :: Cursor -> CInt
415 marshalCursor x = case x of
416 RightArrow -> glut_CURSOR_RIGHT_ARROW
417 LeftArrow -> glut_CURSOR_LEFT_ARROW
418 Info -> glut_CURSOR_INFO
419 Destroy -> glut_CURSOR_DESTROY
420 Help -> glut_CURSOR_HELP
421 Cycle -> glut_CURSOR_CYCLE
422 Spray -> glut_CURSOR_SPRAY
423 Wait -> glut_CURSOR_WAIT
424 Text -> glut_CURSOR_TEXT
425 Crosshair -> glut_CURSOR_CROSSHAIR
426 UpDown -> glut_CURSOR_UP_DOWN
427 LeftRight -> glut_CURSOR_LEFT_RIGHT
428 TopSide -> glut_CURSOR_TOP_SIDE
429 BottomSide -> glut_CURSOR_BOTTOM_SIDE
430 LeftSide -> glut_CURSOR_LEFT_SIDE
431 RightSide -> glut_CURSOR_RIGHT_SIDE
432 TopLeftCorner -> glut_CURSOR_TOP_LEFT_CORNER
433 TopRightCorner -> glut_CURSOR_TOP_RIGHT_CORNER
434 BottomRightCorner -> glut_CURSOR_BOTTOM_RIGHT_CORNER
435 BottomLeftCorner -> glut_CURSOR_BOTTOM_LEFT_CORNER
436 Inherit -> glut_CURSOR_INHERIT
437 None -> glut_CURSOR_NONE
438 FullCrosshair -> glut_CURSOR_FULL_CROSSHAIR
439
440 unmarshalCursor :: CInt -> Cursor
441 unmarshalCursor x
442 | x == glut_CURSOR_RIGHT_ARROW = RightArrow
443 | x == glut_CURSOR_LEFT_ARROW = LeftArrow
444 | x == glut_CURSOR_INFO = Info
445 | x == glut_CURSOR_DESTROY = Destroy
446 | x == glut_CURSOR_HELP = Help
447 | x == glut_CURSOR_CYCLE = Cycle
448 | x == glut_CURSOR_SPRAY = Spray
449 | x == glut_CURSOR_WAIT = Wait
450 | x == glut_CURSOR_TEXT = Text
451 | x == glut_CURSOR_CROSSHAIR = Crosshair
452 | x == glut_CURSOR_UP_DOWN = UpDown
453 | x == glut_CURSOR_LEFT_RIGHT = LeftRight
454 | x == glut_CURSOR_TOP_SIDE = TopSide
455 | x == glut_CURSOR_BOTTOM_SIDE = BottomSide
456 | x == glut_CURSOR_LEFT_SIDE = LeftSide
457 | x == glut_CURSOR_RIGHT_SIDE = RightSide
458 | x == glut_CURSOR_TOP_LEFT_CORNER = TopLeftCorner
459 | x == glut_CURSOR_TOP_RIGHT_CORNER = TopRightCorner
460 | x == glut_CURSOR_BOTTOM_RIGHT_CORNER = BottomRightCorner
461 | x == glut_CURSOR_BOTTOM_LEFT_CORNER = BottomLeftCorner
462 | x == glut_CURSOR_INHERIT = Inherit
463 | x == glut_CURSOR_NONE = None
464 | x == glut_CURSOR_FULL_CROSSHAIR = FullCrosshair
465 | otherwise = error ("unmarshalCursor: illegal value " ++ show x)
466
467 --------------------------------------------------------------------------------
468
469 -- | Change the cursor image of the /current window/. Each call requests the
470 -- window system change the cursor appropriately. The cursor image when a window
471 -- is created is 'Inherit'. The exact cursor images used are implementation
472 -- dependent. The intent is for the image to convey the meaning of the cursor
473 -- name. For a top-level window, 'Inherit' uses the default window system
474 -- cursor.
475 --
476 -- /X Implementation Notes:/ GLUT for X uses SGI\'s @_SGI_CROSSHAIR_CURSOR@
477 -- convention to access a full-screen cross-hair cursor if possible.
478
479 cursor :: StateVar Cursor
480 cursor = makeStateVar getCursor setCursor
481
482 setCursor :: Cursor -> IO ()
483 setCursor = glutSetCursor . marshalCursor
484
485 getCursor :: IO Cursor
486 getCursor = simpleGet unmarshalCursor glut_WINDOW_CURSOR
487
488 --------------------------------------------------------------------------------
489
490 -- | Setting 'pointerPosition' warps the window system\'s pointer to a new
491 -- location relative to the origin of the /current window/ by the specified
492 -- pixel offset, which may be negative. The warp is done immediately.
493 --
494 -- If the pointer would be warped outside the screen\'s frame buffer region, the
495 -- location will be clamped to the nearest screen edge. The window system is
496 -- allowed to further constrain the pointer\'s location in window system
497 -- dependent ways.
498 --
499 -- Good advice from Xlib\'s @XWarpPointer@ man page: \"There is seldom any
500 -- reason for calling this function. The pointer should normally be left to the
501 -- user.\"
502
503 pointerPosition :: SettableStateVar Position
504 pointerPosition =
505 makeSettableStateVar $ \(Position x y) ->
506 glutWarpPointer (fromIntegral x) (fromIntegral y)