SimpleWindow

The flagship window class.

More...
class SimpleWindow : CapableOfHandlingNativeEvent , CapableOfBeingDrawnUpon {
version(X11)
bool stateDiscarded;
version(X11)
void delegate() discardAdditionalConnectionState;
version(X11)
void delegate() recreateAdditionalConnectionState;
SimpleWindow _parent;
bool beingOpenKeepsAppOpen;
void delegate() visibleForTheFirstTime;
version(OSXCocoa)
__gshared
SimpleWindow[void*] nativeMapping;
version(!OSXCocoa)
__gshared
SimpleWindow[NativeWindowHandle] nativeMapping;
bool _suppressDestruction;
}

Constructors

this
this(int width, int height, string title, OpenGlOptions opengl, Resizability resizable, WindowTypes windowType, int customizationFlags, SimpleWindow parent)
this(int width, int height, string title, Resizability resizable, OpenGlOptions opengl, WindowTypes windowType, int customizationFlags, SimpleWindow parent)

This creates a window with the given options. The window will be visible and able to receive input as soon as you start your event loop. You may draw on it immediately after creating the window, without needing to wait for the event loop to start if you want.

this
this(Size size, string title, OpenGlOptions opengl, Resizability resizable)
this(Size size, string title, Resizability resizable, OpenGlOptions opengl)

Same as above, except using the Size struct instead of separate width and height.

this
this(Image image, string title)

Creates a window based on the given Image. It's client area width and height is equal to the image. (A window's client area is the drawable space inside; it excludes the title bar, etc.)

this
this(NativeWindowHandle nativeWindow)

Wraps a native window handle with very little additional processing - notably no destruction this is incomplete so don't use it for much right now. The purpose of this is to make native windows created through the low level API (so you can use platform-specific options and other details SimpleWindow does not expose) available to the event loop wrappers.

Destructor

A destructor is present on this object, but not explicitly documented in the source.

Members

Functions

actualDpi
int actualDpi()

Returns the actual logical DPI for the window on its current display monitor. If the window straddles monitors, it will return the value of one or the other in a platform-defined manner.

addEventListener
uint addEventListener(void delegate(ET) dg)

Add listener for custom event. Can be used like this:

beep
void beep()

Emit a beep to get user's attention.

close
void close()

Closes the window. If there are no more open windows, the event loop will terminate.

close
void close()

close is one of the few methods that can be called from other threads. This shared overload reflects that.

draw
ScreenPainter draw()
ScreenPainter draw(bool manualInvalidations)

This lets you draw on the window (or its backing buffer) using basic 2D primitives.

eventLoop
int eventLoop(long pulseTimeout, T eventHandlers)
int eventLoop(T eventHandlers)

The event loop automatically returns when the window is closed pulseTimeout is given in milliseconds. If pulseTimeout == 0, no pulse timer is created. The event loop will block until an event arrives or the pulse timer goes off.

eventLoopWithBlockingMode
int eventLoopWithBlockingMode(BlockingMode blockingMode, long pulseTimeout, T eventHandlers)

This is the function eventLoop forwards to. It, in turn, forwards to EventLoop.get.run.

focus
void focus()

Sets the input focus to this window.

fullscreen
void fullscreen(bool yes)

not fully implemented but planned for a future release

getRealTitle
string getRealTitle()

Get the title as set by the window manager. May not match what you attempted to set.

grabInput
void grabInput(bool keyboard, bool mouse, bool confine)

Grabs exclusive input from the user until you release it with releaseInputGrab.

hide
void hide()

Alias for hidden = true

hideCursor
void hideCursor()

Hide cursor when it enters the window.

maximize
void maximize()
minimize
void minimize()

Note: only implemented on Windows. No-op on other platforms. You may want to use hide instead.

move
void move(int x, int y)
void move(Point p)

Move window.

moveResize
void moveResize(int x, int y, int w, int h)

Move and resize window (this can be faster and more visually pleasant than doing it separately).

mtLock
void mtLock()

"Lock" this window handle, to do multithreaded synchronization. You probably won't need to call this, as it's not recommended to share window between threads.

mtUnlock
void mtUnlock()

"Unlock" this window handle, to do multithreaded synchronization. You probably won't need to call this, as it's not recommended to share window between threads.

nativeWindowHandle
NativeWindowHandle nativeWindowHandle()

Returns the native window.

opacity
void opacity(double opacity)

Sets the window opacity. On X11 this requires a compositor to be running. On windows the WindowFlags.extraComposite must be set at window creation.

postEvent
bool postEvent(ET evt, bool replace)

Post event to queue. It is safe to call this from non-UI threads. if replace is true, replace all existing events typed ET with the new one (if evt is empty, remove 'em all) Returns true if event was queued. Always returns false if evt is null.

postTimeout
bool postTimeout(ET evt, uint timeoutmsecs, bool replace)

Post event to queue. It is safe to call this from non-UI threads. If timeoutmsecs is greater than zero, the event will be delayed for at least timeoutmsecs milliseconds. if replace is true, replace all existing events typed ET with the new one (if evt is empty, remove 'em all) Returns true if event was queued. Always returns false if evt is null.

redrawOpenGlSceneNow
void redrawOpenGlSceneNow()

call this to invoke your delegate. It automatically sets up the context and flips the buffer. If you need to redraw the scene in response to an event, call this.

redrawOpenGlSceneSoon
void redrawOpenGlSceneSoon()

Queues an opengl redraw as soon as the other pending events are cleared.

releaseCurrentOpenGlContext
bool releaseCurrentOpenGlContext()

Releases OpenGL context, so it can be reused in, for example, different thread. This is only valid if you passed OpenGlOptions.yes to the constructor. This doesn't throw, returning success flag instead.

releaseInputGrab
void releaseInputGrab()

Releases the grab acquired by grabInput.

removeEventListener
void removeEventListener(uint id)

Remove event listener. It is safe to pass invalid event id here.

Don't use this method in object destructors!
requestAttention
void requestAttention()

Requests attention from the user for this window.

resize
void resize(int w, int h)

Resize window.

sendDummyEvent
void sendDummyEvent()

Send dummy window event to ping event loop. Required to process NotificationIcon on X11, for example.

setAsCurrentOpenGlContext
void setAsCurrentOpenGlContext()

Makes all gl* functions target this window until changed. This is only valid if you passed OpenGlOptions.yes to the constructor.

setAsCurrentOpenGlContextNT
bool setAsCurrentOpenGlContextNT()

Makes all gl* functions target this window until changed. This is only valid if you passed OpenGlOptions.yes to the constructor. This doesn't throw, returning success flag instead.

setEventHandlers
void setEventHandlers(T eventHandlers)

Sets your event handlers, without entering the event loop. Useful if you have multiple windows - set the handlers on each window, then only do eventLoop on your main window or call EventLoop.get.run();.

setIMEFocused
void setIMEFocused(bool value)

Tells the IME whether or not an input field is currently focused in the window.

setIMEPopupLocation
void setIMEPopupLocation(Point location)
void setIMEPopupLocation(int x, int y)

Sets the location for the IME (input method editor) to pop up when the user activates it.

setMaxSize
void setMaxSize(int maxwidth, int maxheight)

Set window maximal size.

setMinSize
void setMinSize(int minwidth, int minheight)

Set window minimal size.

setResizeGranularity
void setResizeGranularity(int granx, int grany)

Set window resize step (window size will be changed with the given granularity on supported platforms). Currently only supported on X11.

show
void show()

Alias for hidden = false

showCursor
void showCursor()

Don't hide cursor when it enters the window.

swapOpenGlBuffers
void swapOpenGlBuffers()

simpledisplay always uses double buffering, usually automatically. This manually swaps the OpenGL buffers.

takeScreenshot
TrueColorImage takeScreenshot()

Copies the window's current state into a TrueColorImage.

warpMouse
bool warpMouse(int x, int y)

"Warp" mouse pointer to coordinates relative to window top-left corner. Return "success" flag.

Mixins

impl
mixin NativeSimpleWindowImplementation!() impl

The native implementation is available, but you shouldn't use it unless you are familiar with the underlying operating system, don't mind depending on it, and know simpledisplay.d's internals too. It is virtually private; you can hopefully do what you need to do with handleNativeEvent instead.

Properties

actualWindowSize
Size actualWindowSize [@property getter]

Returns the actual size of the window, bypassing the logical illusions of Resizability.automaticallyScaleIfPossible.

closed
bool closed [@property getter]

Returns true if the window has been closed.

cursor
MouseCursor cursor [@property setter]

Changes the cursor for the window. If the cursor is hidden via hideCursor, this has no effect.

eventQueueEmpty
bool eventQueueEmpty [@property getter]

Is our custom event queue empty? Can be used in simple cases to prevent "spamming" window with events it can't cope with. It is safe to call this from non-UI threads.

eventQueued
bool eventQueued [@property getter]

Does our custom event queue contains at least one with the given type? Can be used in simple cases to prevent "spamming" window with events it can't cope with. It is safe to call this from non-UI threads.

focused
bool focused [@property getter]

Returns true if the window is focused.

height
int height [@property getter]

Height of the window's drawable client area, in pixels.

hidden
bool hidden [@property getter]

Returns true if the window is hidden.

hidden
bool hidden [@property setter]

Shows or hides the window based on the bool argument.

icon
MemoryImage icon [@property setter]

Set the icon that is seen in the title bar or taskbar, etc., for the user. If passed null, does nothing.

image
Image image [@property setter]

Draws an image on the window. This is meant to provide quick look of a static image generated elsewhere.

isOpenGL
bool isOpenGL [@property getter]

true if OpenGL was initialized for this window.

title
string title [@property setter]

Set the window title, which is visible on the window manager title bar, operating system taskbar, etc.

title
string title [@property getter]

Gets the title

visible
bool visible [@property getter]

Returns true if the window is visible (mapped).

vsync
bool vsync [@property setter]

This will allow you to change OpenGL vsync state.

width
int width [@property getter]

Width of the window's drawable client area, in pixels.

Static variables

handleNativeGlobalEvent
NativeEventHandler handleNativeGlobalEvent;

This is the same as handleNativeEvent, but static so it can hook ALL events in the loop. If you used to use handleNativeEvent depending on it being static, just change it to use this instead and it will work the same way.

Variables

closeQuery
void delegate() closeQuery;

This will be called when WM wants to close your window (i.e. user clicked "close" icon, for example). You'll have to call close() manually if you set this delegate.

eventUncaughtException
void delegate(Exception e) nothrow eventUncaughtException;

Event listeners added with addEventListener have their exceptions swallowed by the event loop. This delegate can handle them again before it proceeds.

handleCharEvent
void delegate(dchar c) handleCharEvent;

Handles a higher level keyboard event - c is the character just pressed. Settable through setEventHandlers.

handleExpose
bool delegate(int x, int y, int width, int height, int eventsLeft) handleExpose;

Called when Expose event comes. See Xlib manual to understand the arguments. * Return false if you want Simpledisplay to copy backbuffer, or true if you did it yourself. * You will probably never need to setup this handler, it is for very low-level stuff. * * WARNING! Xlib is multithread-locked when this handles is called!

handleKeyEvent
void delegate(KeyEvent ke) handleKeyEvent;

What follows are the event handlers. These are set automatically by the eventLoop function, but are still public so you can change them later. wasPressed == true means key down. false == key up. Handles a low-level keyboard event. Settable through setEventHandlers.

handleMouseEvent
void delegate(MouseEvent) handleMouseEvent;

Mouse event handler. Settable through setEventHandlers.

handleNativeEvent_
NativeEventHandler handleNativeEvent_;

Platform specific - handle any native message this window gets.

handlePulse
void delegate() handlePulse;

Handles a timer pulse. Settable through setEventHandlers.

onClosing
void delegate() onClosing;

Called inside close() method. Our window is still alive, and we can free various resources. * Sometimes it is easier to setup the delegate instead of subclassing.

onDestroyed
void delegate() onDestroyed;

Called when we received destroy notification. At this stage we cannot do much with our window * (as it is already dead, and it's native handle cannot be used), but we still can do some * last minute cleanup.

onDpiChanged
void delegate() onDpiChanged;

Sent when the window is moved to a new DPI context, for example, when it is dragged between monitors or if the window is moved to a new remote connection or a monitor is hot-swapped.

onFocusChange
void delegate(bool) onFocusChange;

Called when the focus changes, param is if we have it (true) or are losing it (false).

paintingFinished
void delegate() paintingFinished;

use to redraw child widgets if you use system apis to add stuff

redrawOpenGlScene
void delegate() redrawOpenGlScene;

Put your code in here that you want to be drawn automatically when your window is uncovered. Set a handler here *before* entering your event loop any time you pass OpenGlOptions.yes to the constructor. Ideally, you will set this delegate immediately after constructing the SimpleWindow.

setRequestedInputFocus
SimpleWindow delegate() setRequestedInputFocus;

Used iff WindowFlags.managesChildWindowFocus is set when the window is created. The delegate will be called when the window manager asks you to take focus.

suppressAutoOpenglViewport
bool suppressAutoOpenglViewport;

When in opengl mode and automatically resizing, it will set the opengl viewport to stretch.

useGLFinish
bool useGLFinish;

Set this to false if you don't need to do glFinish() after swapOpenGlBuffers(). Note that at least NVidia proprietary driver may segfault if you will modify texture fast enough without waiting 'em to finish their frame business.

visibilityChanged
void delegate(bool becomesVisible) visibilityChanged;

This will be called when window visibility was changed.

windowResized
void delegate(int width, int height) windowResized;

handle a resize, after it happens. You must construct the window with Resizability.allowResizing for this to ever happen.

Inherited Members

From CapableOfBeingDrawnUpon

draw
ScreenPainter draw()
width
int width()
height
int height()
takeScreenshot
TrueColorImage takeScreenshot()

Be warned: this can be a very slow operation

Detailed Description

SimpleWindow tries to make ordinary windows very easy to create and use without locking you out of more advanced or complex features of the underlying windowing system.

For many applications, you can simply call new SimpleWindow(some_width, some_height, "some title") and get a suitable window to work with.

From there, you can opt into additional features, like custom resizability and OpenGL support with the next two constructor arguments. Or, if you need even more, you can set a window type and customization flags with the final two constructor arguments.

If none of that works for you, you can also create a window using native function calls, then wrap the window in a SimpleWindow instance by calling new SimpleWindow(native_handle). Remember, though, if you do this, managing the window is still your own responsibility! Notably, you will need to destroy it yourself.

Suggestion Box / Bug Report