mirror of https://github.com/adamdruppe/arsd.git
saner pulse
This commit is contained in:
Adam D. Ruppe
parent
828a97134c
commit
847903e443
113
simpledisplay.d
113
simpledisplay.d
|
|
@ -46,7 +46,7 @@
|
|||
of working efficiently over a remote X link (at least as far as Xlib
|
||||
reasonably allows.)
|
||||
|
||||
simpledisplay depends on `color.d`, which should be available from the
|
||||
simpledisplay depends on [arsd.color|color.d], which should be available from the
|
||||
same place where you got this file. Other than that, however, it has
|
||||
very few dependencies and ones that don't come with the OS and/or the
|
||||
compiler are all opt-in.
|
||||
|
|
@ -58,24 +58,24 @@
|
|||
and may add new features and fix bugs, but It do not expect to
|
||||
significantly change the API. It has been stable a few years already now.
|
||||
|
||||
Jump_list:$(BR)
|
||||
Jump_list:
|
||||
|
||||
Don't worry, you don't have to read this whole documentation file!
|
||||
|
||||
Check out the $(M Event-example) and $(M Pong-example) to get started quickly.
|
||||
Check out the [#Event-example] and [#Pong-example] to get started quickly.
|
||||
|
||||
The main classes you may want to create are $(M SimpleWindow), $(M Timer),
|
||||
$(M Image), and $(M Sprite).
|
||||
The main classes you may want to create are [SimpleWindow], [Timer],
|
||||
[Image], and [Sprite].
|
||||
|
||||
The main functions you'll want are $(M setClipboardText) and $(M getClipboardText).
|
||||
The main functions you'll want are [setClipboardText] and [getClipboardText].
|
||||
|
||||
There are also platform-specific functions available such as $(M XDisplayConnection)
|
||||
and $(M GetAtom) for X11, among others.
|
||||
There are also platform-specific functions available such as [XDisplayConnection]
|
||||
and [GetAtom] for X11, among others.
|
||||
|
||||
See the examples and topics list below to learn more.
|
||||
|
||||
|
||||
<h2>About this documentation</h2>
|
||||
$(H2 About this documentation)
|
||||
|
||||
The goal here is to give some complete programs as overview examples first, then a look at each major feature with working examples first, then, finally, the inline class and method list will follow.
|
||||
|
||||
|
|
@ -276,10 +276,10 @@
|
|||
|
||||
---
|
||||
|
||||
<h2>Topics</h2>
|
||||
$(H2 Topics)
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-windows) Windows</h3>
|
||||
The $(M SimpleWindow) class is simpledisplay's flagship feature. It represents a single
|
||||
$(H3 $(DDOC_ANCHOR topic-windows) Windows)
|
||||
The $(LREF SimpleWindow) class is simpledisplay's flagship feature. It represents a single
|
||||
window on the user's screen.
|
||||
|
||||
You may create multiple windows, if the underlying platform supports it. You may check
|
||||
|
|
@ -293,7 +293,7 @@
|
|||
draw function
|
||||
title property
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-event-loops) Event loops</h3>
|
||||
$(H3 $(DDOC_ANCHOR topic-event-loops) Event loops)
|
||||
The simpledisplay event loop is designed to handle common cases easily while being extensible for more advanced cases, or replaceable by other libraries.
|
||||
|
||||
The most common scenario is creating a window, then calling `window.eventLoop` when setup is complete. You can pass several handlers to the `eventLoop` method right there:
|
||||
|
|
@ -317,14 +317,14 @@
|
|||
|
||||
It should be possible to integrate simpledisplay with vibe.d as well, though I haven't tried.
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-notification-areas) Notification area (aka systray) icons</h3>
|
||||
$(H3 $(DDOC_ANCHOR topic-notification-areas) Notification area (aka systray) icons)
|
||||
Notification area icons are currently only implemented on X11 targets. Windows support will come when I need it (or if someone requests it and I have some time to spend on it).
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-input-handling) Input handling</h3>
|
||||
$(H3 $(DDOC_ANCHOR topic-input-handling) Input handling)
|
||||
There are event handlers for low-level keyboard and mouse events, and higher level handlers for character events.
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-2d-drawing) 2d Drawing</h3>
|
||||
To draw on your window, use the `window.draw` method. It returns a $(M ScreenPainter) structure with drawing methods.
|
||||
$(H3 $(DDOC_ANCHOR topic-2d-drawing) 2d Drawing)
|
||||
To draw on your window, use the `window.draw` method. It returns a $(LREF ScreenPainter) structure with drawing methods.
|
||||
|
||||
Important: `ScreenPainter` double-buffers and will not actually update the window until its destructor is run. Always ensure the painter instance goes out-of-scope before proceeding. You can do this by calling it inside an event handler, a timer callback, or an small scope inside main. For example:
|
||||
|
||||
|
|
@ -348,7 +348,7 @@
|
|||
|
||||
At this time, the 2d drawing does not support alpha blending. If you need that, use a 2d OpenGL context instead.
|
||||
FIXME add example of 2d opengl drawing here
|
||||
<h3>$(DDOC_ANCHOR topic-3d-drawing) 3d Drawing (or 2d with OpenGL)</h3>
|
||||
$(H3 $(DDOC_ANCHOR topic-3d-drawing) 3d Drawing (or 2d with OpenGL))
|
||||
simpledisplay can create OpenGL contexts on your window. It works quite differently than 2d drawing.
|
||||
|
||||
Note that it is still possible to draw 2d on top of an OpenGL window, using the `draw` method, though I don't recommend it.
|
||||
|
|
@ -381,7 +381,7 @@
|
|||
}
|
||||
---
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-images) Image Displaying</h3>
|
||||
$(H3 $(DDOC_ANCHOR topic-images) Displaying images)
|
||||
You can also load PNG images using my `png.d`.
|
||||
|
||||
---
|
||||
|
|
@ -399,16 +399,16 @@
|
|||
|
||||
If you find an image file which is a valid png that `arsd.png` fails to load, please let me know. In the mean time of fixing the bug, you can probably convert the file into an easier-to-load format. Be sure to turn OFF png interlacing, as that isn't supported. Other things to try would be making the image smaller, or trying 24 bit truecolor mode with an alpha channel.
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-sprites) Sprites</h3>
|
||||
The $(M Sprite) class is used to make images on the display server for fast blitting to screen. This is especially important to use to support fast drawing of repeated images on a remote X11 link.
|
||||
$(H3 $(DDOC_ANCHOR topic-sprites) Sprites)
|
||||
The $(LREF Sprite) class is used to make images on the display server for fast blitting to screen. This is especially important to use to support fast drawing of repeated images on a remote X11 link.
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-clipboard) Clipboard</h3>
|
||||
The free functions $(M getClipboardText) and $(M setClipboardText) consist of simpledisplay's cross-platform clipboard support at this time.
|
||||
$(H3 $(DDOC_ANCHOR topic-clipboard) Clipboard)
|
||||
The free functions $(LREF getClipboardText) and $(LREF setClipboardText) consist of simpledisplay's cross-platform clipboard support at this time.
|
||||
|
||||
It also has helpers for handling X-specific events.
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-timers) Timers</h3>
|
||||
There are two timers in simpledisplay: one is the pulse timeout you can set on the call to `window.eventLoop`, and the other is a customizable class, $(M Timer).
|
||||
$(H3 $(DDOC_ANCHOR topic-timers) Timers)
|
||||
There are two timers in simpledisplay: one is the pulse timeout you can set on the call to `window.eventLoop`, and the other is a customizable class, $(LREF Timer).
|
||||
|
||||
The pulse timeout is used by setting a non-zero interval as the first argument to `eventLoop` function and adding a zero-argument delegate to handle the pulse.
|
||||
|
||||
|
|
@ -436,7 +436,7 @@
|
|||
|
||||
The `Timer` class works similarly, but is created separately from the event loop. (It still fires through the event loop, though.) You may make as many instances of `Timer` as you wish.
|
||||
|
||||
The pulse timer and instances of the $(M Timer) class may be combined at will.
|
||||
The pulse timer and instances of the $(LREF Timer) class may be combined at will.
|
||||
|
||||
---
|
||||
import simpledisplay;
|
||||
|
|
@ -454,20 +454,20 @@
|
|||
|
||||
Timers are currently only implemented on Windows, using `SetTimer` and Linux, using `timerfd_create`. These deliver timeout messages through your application event loop.
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-os-helpers) OS-specific helpers</h3>
|
||||
$(H3 $(DDOC_ANCHOR topic-os-helpers) OS-specific helpers)
|
||||
simpledisplay carries a lot of code to help implement itself without extra dependencies, and much of this code is available for you too, so you may extend the functionality yourself.
|
||||
|
||||
See also: `xwindows.d` from my github.
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-os-extension) Extending with OS-specific functionality</h3>
|
||||
$(H3 $(DDOC_ANCHOR topic-os-extension) Extending with OS-specific functionality)
|
||||
`handleNativeEvent` and `handleNativeGlobalEvent`.
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-integration) Integration with other libraries</h3>
|
||||
$(H3 $(DDOC_ANCHOR topic-integration) Integration with other libraries)
|
||||
Integration with a third-party event loop is possible.
|
||||
|
||||
On Linux, you might want to support both terminal input and GUI input. You can do this by using simpledisplay together with eventloop.d and terminal.d.
|
||||
|
||||
<h3>$(DDOC_ANCHOR topic-guis) GUI widgets</h3>
|
||||
$(H3 $(DDOC_ANCHOR topic-guis) GUI widgets)
|
||||
simpledisplay does not provide GUI widgets such as text areas, buttons, checkboxes, etc. It only gives basic windows, the ability to draw on it, receive input from it, and access native information for extension. You may write your own gui widgets with these, but you don't have to because I already did for you!
|
||||
|
||||
Download `minigui.d` from my github repository and add it to your project. minigui builds these things on top of simpledisplay and offers its own Window class (and subclasses) to use that wrap SimpleWindow, adding a new event and drawing model that is hookable by subwidgets, represented by their own classes.
|
||||
|
|
@ -476,7 +476,7 @@
|
|||
|
||||
minigui still needs a lot of work to be finished at this time, but it already offers a number of useful classes.
|
||||
|
||||
<h2>$(DDOC_ANCHOR developer-notes) Developer notes</h2>
|
||||
$(H2 $(DDOC_ANCHOR developer-notes) Developer notes)
|
||||
|
||||
I don't have a Mac, so that code isn't maintained. I would like to have a Cocoa
|
||||
implementation though.
|
||||
|
|
@ -508,7 +508,7 @@
|
|||
declaration you're interested in, like `class SimpleWindow` using your editor's search
|
||||
function, then look at one piece at a time.
|
||||
|
||||
<h2>$(DDOC_ANCHOR about-the-author) Meta</h2>
|
||||
$(H2 $(DDOC_ANCHOR about-the-author) Meta)
|
||||
|
||||
Authors: Adam D. Ruppe with the help of others. If you need help, please email me with
|
||||
destructionator@gmail.com or find me on IRC. Our channel is #d on Freenode. I go by
|
||||
|
|
@ -517,7 +517,7 @@
|
|||
I live in the eastern United States, so I will most likely not be around at night in
|
||||
that US east timezone.
|
||||
|
||||
License: Copyright Adam D. Ruppe, 2011-2015. Released under the Boost Software License.
|
||||
License: Copyright Adam D. Ruppe, 2011-2016. Released under the Boost Software License.
|
||||
|
||||
Building documentation: You may wish to use the `arsd.ddoc` file from my github with
|
||||
building the documentation for simpledisplay yourself. It will give it a bit more style.
|
||||
|
|
@ -647,7 +647,7 @@ else
|
|||
static assert(0);
|
||||
|
||||
/++
|
||||
After selecting a type from $(M WindowTypes), you may further customize
|
||||
After selecting a type from $(LREF WindowTypes), you may further customize
|
||||
its behavior by setting one or more of these flags.
|
||||
|
||||
|
||||
|
|
@ -719,15 +719,15 @@ class SimpleWindow : CapableOfHandlingNativeEvent {
|
|||
|
||||
width = the width of the window's client area, in pixels
|
||||
height = the height of the window's client area, in pixels
|
||||
title = the title of the window (seen in the title bar, taskbar, etc.). You can change it after construction with the $(M SimpleWindow._title) property.
|
||||
opengl = $(M OpenGlOptions) are yes and no. If yes, it creates an OpenGL context on the window.
|
||||
title = the title of the window (seen in the title bar, taskbar, etc.). You can change it after construction with the $(LREF SimpleWindow._title) property.
|
||||
opengl = $(LREF OpenGlOptions) are yes and no. If yes, it creates an OpenGL context on the window.
|
||||
$(TIP On Windows, you need to compile with `-version=with_opengl` to enable `OpenGlOptions.yes`)
|
||||
resizable = $(M Resizablity) has three options:
|
||||
resizable = $(LREF Resizablity) has three options:
|
||||
$(P `allowResizing`, which allows the window to be resized by the user. The `windowResized` delegate will be called when the size is changed.)
|
||||
$(P `fixedSize` will not allow the user to resize the window.)
|
||||
$(P `automaticallyScaleIfPossible` will allow the user to resize, but will still present the original size to the API user. The contents you draw will be scaled to the size the user chose. If this scaling is not efficient, the window will be fixed size. The `windowResized` event handler will never be called. This is the default.)
|
||||
windowType = The type of window you want to make.
|
||||
customizationFlags = A way to make a window without a border, always on top, skip taskbar, and more. Do not use this if one of the pre-defined $(M WindowTypes), given in the `windowType` argument, is a good match for what you need.
|
||||
customizationFlags = A way to make a window without a border, always on top, skip taskbar, and more. Do not use this if one of the pre-defined $(LREF WindowTypes), given in the `windowType` argument, is a good match for what you need.
|
||||
parent = the parent window, if applicable
|
||||
+/
|
||||
this(int width = 640, int height = 480, string title = null, OpenGlOptions opengl = OpenGlOptions.no, Resizablity resizable = Resizablity.automaticallyScaleIfPossible, WindowTypes windowType = WindowTypes.normal, int customizationFlags = WindowFlags.normal, SimpleWindow parent = null) {
|
||||
|
|
@ -747,7 +747,7 @@ class SimpleWindow : CapableOfHandlingNativeEvent {
|
|||
|
||||
|
||||
/++
|
||||
Creates a window based on the given $(M Image). It's client area
|
||||
Creates a window based on the given $(LREF 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.)
|
||||
|
||||
|
|
@ -882,7 +882,7 @@ class SimpleWindow : CapableOfHandlingNativeEvent {
|
|||
Be sure to call this in a limited scope because your changes will not
|
||||
actually appear on the window until ScreenPainter's destructor runs.
|
||||
|
||||
Returns: an instance of $(M ScreenPainter), which has the drawing methods
|
||||
Returns: an instance of $(LREF ScreenPainter), which has the drawing methods
|
||||
on it to draw on this window.
|
||||
+/
|
||||
ScreenPainter draw() {
|
||||
|
|
@ -1719,11 +1719,11 @@ version(Windows) {
|
|||
|
||||
|
||||
/++
|
||||
$(M ScreenPainter) operations can use different operations to combine the color with the color on screen.
|
||||
$(LREF ScreenPainter) operations can use different operations to combine the color with the color on screen.
|
||||
|
||||
See_Also:
|
||||
$(M ScreenPainter)
|
||||
$(M ScreenPainter.rasterOp)
|
||||
$(LREF ScreenPainter)
|
||||
$(LREF ScreenPainter.rasterOp)
|
||||
+/
|
||||
enum RasterOp {
|
||||
normal, /// Replaces the pixel.
|
||||
|
|
@ -1826,19 +1826,19 @@ public import arsd.color; // no longer stand alone... :-( but i need a common ty
|
|||
Keyboard press and release events
|
||||
+/
|
||||
struct KeyEvent {
|
||||
/// see table below. Always use the symbolic names, even for ASCII characters, since the actual numbers vary across platforms. See $(M Key)
|
||||
/// see table below. Always use the symbolic names, even for ASCII characters, since the actual numbers vary across platforms. See $(LREF Key)
|
||||
Key key;
|
||||
uint hardwareCode; /// A platform and hardware specific code for the key
|
||||
bool pressed; /// true if the key was just pressed, false if it was just released. note: released events aren't always sent...
|
||||
|
||||
dchar character; ///
|
||||
|
||||
uint modifierState; /// see enum $(M ModifierState). They are bitwise combined together.
|
||||
uint modifierState; /// see enum $(LREF ModifierState). They are bitwise combined together.
|
||||
|
||||
SimpleWindow window; /// associated Window
|
||||
}
|
||||
|
||||
/// Type of a $(M MouseEvent)
|
||||
/// Type of a $(LREF MouseEvent)
|
||||
enum MouseEventType : int {
|
||||
motion = 0, /// The mouse moved inside the window
|
||||
buttonPressed = 1, /// A mouse button was pressed or the wheel was spun
|
||||
|
|
@ -1850,7 +1850,7 @@ enum MouseEventType : int {
|
|||
Listen for this on your event listeners if you are interested in mouse action.
|
||||
+/
|
||||
struct MouseEvent {
|
||||
MouseEventType type; /// movement, press, release, double click. See $(M MouseEventType)
|
||||
MouseEventType type; /// movement, press, release, double click. See $(LREF MouseEventType)
|
||||
|
||||
int x; /// Current X position of the cursor when the event fired, relative to the upper-left corner of the window, reported in pixels. (0, 0) is the upper left, (window.width - 1, window.height - 1) is the lower right corner of the window.
|
||||
int y; /// Current Y position of the cursor when the event fired.
|
||||
|
|
@ -1858,8 +1858,8 @@ struct MouseEvent {
|
|||
int dx; /// Change in X position since last report
|
||||
int dy; /// Change in Y position since last report
|
||||
|
||||
MouseButton button; /// See $(M MouseButton)
|
||||
int modifierState; /// See $(M ModifierState)
|
||||
MouseButton button; /// See $(LREF MouseButton)
|
||||
int modifierState; /// See $(LREF ModifierState)
|
||||
|
||||
SimpleWindow window; /// The window in which the event happened.
|
||||
}
|
||||
|
|
@ -1868,7 +1868,7 @@ struct MouseEvent {
|
|||
struct Pen {
|
||||
Color color; /// the foreground color
|
||||
int width = 1; /// width of the line
|
||||
Style style; /// See $(M Style) FIXME: not implemented
|
||||
Style style; /// See $(LREF Style) FIXME: not implemented
|
||||
/+
|
||||
// From X.h
|
||||
|
||||
|
|
@ -1922,7 +1922,7 @@ struct Pen {
|
|||
|
||||
Drawing an image to screen is not necessarily fast, but applying algorithms to draw to the image itself should be fast. An `Image` is also the first step in loading and displaying images loaded from files.
|
||||
|
||||
If you intend to draw an image to screen several times, you will want to convert it into a $(M Sprite).
|
||||
If you intend to draw an image to screen several times, you will want to convert it into a $(LREF Sprite).
|
||||
|
||||
$(IMPORTANT `Image` may represent a scarce, shared resource that persists across process termination, and should be disposed of properly. On X11, it uses the MIT-SHM extension, if available, which uses shared memory handles with the X server, which is a long-lived process that holds onto them after your program terminates if you don't free it.
|
||||
|
||||
|
|
@ -4842,10 +4842,15 @@ version(X11) {
|
|||
long expirationCount;
|
||||
// if we go over the count, I ignore it because i don't want the pulse to go off more often and eat tons of cpu time...
|
||||
|
||||
// read just to clear the buffer so poll doesn't trigger again
|
||||
unix.read(pulseFd, &expirationCount, expirationCount.sizeof);
|
||||
|
||||
handlePulse();
|
||||
|
||||
// read just to clear the buffer so poll doesn't trigger again
|
||||
// BTW I read AFTER the pulse because if the pulse handler takes
|
||||
// a lot of time to execute, we don't want the app to get stuck
|
||||
// in a loop of timer hits without a chance to do anything else
|
||||
//
|
||||
// IOW handlePulse happens at most once per pulse interval.
|
||||
unix.read(pulseFd, &expirationCount, expirationCount.sizeof);
|
||||
} else {
|
||||
// some other timer
|
||||
version(sdddd) { import std.stdio; writeln("unknown fd: ", fd); }
|
||||
|
|
|
|||
Loading…
Reference in New Issue