sd_window Guide
Contents
- Introduction
- sd_window Features
- Enhanced vs. Unenhanced sd_windows
- Using sd_window
- Creating sd_windows
- Basic sd_windows
- Timed sd_windows
- Positioning sd_windows
- Sizing sd_windows
- Other sd_window Options
- Persistent sd_windows
- Displaying and Closing Persistent sd_windows
- Changing an sd_window's Display
- sd_window Hooks
- sd_windows with Extra Resources
- Getting Input From sd_windows
- Detecting the Client's Browser
- Demo Program
- sd_window Reference
sd_window provides special popup dialog windows with several controls that normal BYOND
browse() windows lack. sd_window lets you control the position of the window on screen and
triggers a proc when the window is closed.
The windows are controlled by the /sd_window datum. In its simplest form, you can display a
window with a single line of code just by creating the window with the content and target
arguments.
All sd_windows:
- Open sd_windows without stealing keyboard focus from the Dream Seeker map.
- Improved scrollbar display. When the scroll bar is turned on, it doesn't leave an ugly blank band on the right of
a display that fits within the window.
- Program hooks that allow your software to react when someone closes a window and/or when no one is
looking at a particular window anymore.
- Timed sd_windows close automatically after a given period of time.
- When the sd_window datum is deleted, it closes all the browser windows it created.
- Track who is looking at a particular window.
- Track which windows a client is viewing.
Enhanced sd_windows:
- Control the position where the window pops up on screen.
- Never places windows off screen.
- Display with or without a sunken border.
- Display a status bar on the window.
- Add a context sensitive help button. (Only available on clients using IE 6).
Enhanced vs. Unenhanced sd_windows
Let's face it. Most of you are reading this because you want positional control over your windows. Why would you
ever want to use unenhanced sd_windows? Well, enhanced sd_windows uses a modeless dialog window and it causes errors
on some systems. I'm still trying to track down and eliminate these errors, but in the mean time you can prevent the
errors by using the unenhanced windows.
sd_window adds a number of powerful features to browser windows. Displaying data at a particular location is as easy
as sending a single line of code. It can be a little tricky to get data back from the window, but I'll show you a
script that will handle it. All you have to do is remember to call the script instead of trying to pass information
directly back to BYOND.
New sd_windows have 8 arguments that you can use to customize the window to suit your needs:
New(content, target, timer, x, y, width, height, flags)
Each of these arguments, except target, sets the sd_window var of the same name. These vars will be explained in
detail below.
sd_windows that are just for information display are extremely easy. You can fire them off with a single line of code
that specifies the content and target(s).
The following example displays a very simple window to the verb user:
mob/verb/simple_window()
new /sd_window("This is a simple window.", src)
"This is a simple window." becomes the content of the sd_window. The content is HTML format text and
can include anything that Internet Explorer on the client's computer can handle (see Detecting the
Client's Browser.) You don't have to specify content when the window is created and it may be modified at
any time, but the changes you make to content will not be seen by a client until you display it again.
The target in the example is src, the mob that the verb belongs to. If the target is specified when
the window is created, it will be displayed immediately to that target. The target can be a mob, a client, or even
a list full of mobs and clients.
The timer var allows you to specify a specific time limit for the sd_window. If timer is set, the window will
close automatically that many ticks (1/10 of a second) after it is displayed to a particular target. If timer is
omitted or zero (0), the sd_window will remain open indefinitely until something else closes it.
mob/verb/timed_window()
new /sd_window("This window will automatically close in 45 seconds.", src, 450)
Position controls only apply to enhanced sd_windows. Unenhanced sd_windows will open wherever the client's last
popup browser window was closed.
x and y control the position of the window on the client's screen. If either value is
negative, the window will be centered onscreen with respect to that axis. Enhanced sd_windows will never extend
beyond the screen borders, so you can force a window to the right or bottom edge by specifying extremely large
values.
mob/verb/bottomright_window()
new /sd_window("This window opens in the bottom right of the screen.", src,,5000,5000)
mob/verb/topcenter_window()
new /sd_window("This window opens in the top center of the screen.", src,,-1,0)
These values only control the window position when the window is opened. If you want to force the window to move
somewhere else on a client's screen, you should close the sd_window and then display it again.
width and height control the size of the window. The size defaults to 300 by 300.
These values only control the window size when the window is opened. If you want to force the window to a different
size on a client's screen, you should close the sd_window and then display it again.
The flags var controls several display options for sd_windows and are defined as bit flags. That means you may
combine multiple flags using the bitwise or operator (|). The following flags are supported:
- SDW_FOCUS
- If not set, window restores focus to Dream Seeker after the window is opened. That means
your keyboard will continue interacting with the DreamSeeker map and command line instead of being trapped in the
popup window.
- SDW_RESIZE
- If set, the window may be resized by the client. (Unenhanced windows may also be minimized, if
this flag is set.)
- SDW_STATUS
- Display the status bar on an enhanced sd_window. I'm not really sure why you'd want to
since I have yet to find a way to display anything useful on it, but the option is still there.
- SDW_SCROLL
- If set, display scroll bars if the content is large enough to require them.
- SDW_SUNKEN
- If set, show a sunken window edge for enhanced windows.
- SDW_HELP
- If set, display context sensitive help icon for enhanced windows. This feature has been
removed from Internet Explorer 7. It wasn't that great anyway.
The default value of flags is SDW_RESIZE|SDW_SCROLL, which means to allow resizing and scroll bars.
If you want to reuse an sd_window or monkey around with its values, you will have to store it as a variable.
mob
var/sd_window/my_window
verb
new_persistent()
set desc = "Create a new persistent sd_window."
my_window = new("I made a fresh window", src)
my_window_content(T as text)
set desc = "(new content) Enter new content for your sd_window."
if(!my_window) // oops! better make one then
my_window = new()
my_window.content = T
my_window.Display(src)
If you looked closely at that last example, you noticed the sd_window Display() proc. This proc will display the
window to the targets specified by the proc argument. As everywhere else in sd_window, the target can be a mob,
client, or list of mobs and clients.
If you want your program to close the window automatically, you have a few options: set timer before displaying the
sd_window, delete the sd_window, or use the sd_window Close() proc. Using a timer was described above in
Timed sd_windows. If you delete an sd_window, it automatically closes the popup for all the
clients viewing that window. The Close() proc is provided so you can close the window to specific targets and/or
close the window without triggering the Closed() or NoViewers() hooks. Closed() and NoViewers() are explained in
sd_window Hooks.
The format for Close() is:
Close(target, report = 1, remove = 1)
target is the mob, client, or list of mobs and clients that you want to close the window.
report determines if the Closed() hook is called. If report is null, 0 or
"" then Closed() is not called. Any other value will call Closed().
remove determines if the target is removed from the sd_window's viewers list. This list lets the window keep
track of every client viewing the window. If it becomes empty, NoViewers() will be called.
mob
verb
display_my_window()
set desc = "Re-display your sd_window."
if(!my_window) // oops! better make one then
my_window = new()
my_window.Display(src)
delete_my_window()
set desc = "Delete the persistent sd_window."
del(my_window)
close_my_window()
set desc = "Close the persistent sd_window without deleting it."
if(!my_window) return
my_window.Close(src, 0, 0)
Several of the sd_window options (position, size, and many flags) only apply when the popup is first created. If you
change these settings and display the window again, there will be no apparent change. You can force the display to
update by closing the window, then displaying it again. You should be sure to call Close() with 0 for the second and
third arguments so the Closed() proc is not called and the viewers list does not change.
mob
verb
toggle_my_window_sunken()
set desc = "Toggle the SDW_SUNKEN flag for your persistent window."
if(!my_window) // oops! better make one then
my_window = new()
my_window.Close(src, 0, 0)
my_window.flags ^= SDW_SUNKEN
my_window.Display(src)
sd_windows provide two special procs that are provided so that your program can react to things that happen to your
window: Closed() and NoViewers(). Override these procs to do whatever you want them to.
Closed() is called whenever the popup is closed (except when it is closed by the Close() command with the report
flag off.) It has no default action. The only argument to this proc is the mob, client, or list of mobs and clients
that have closed the popup.
NoViewers() is called when no one is viewing the window anymore. There is no argument. The default action of
NoViewers() is to delete the sd_window datum.
mob/verb/hooked_window()
set desc = "Open a window that tells you when its program hooks are called."
new/sd_window/hooked("I report dutifully when closed.", src)
sd_window/hooked
// our
Close(target)
world << "[target] closed me!"
NoViewers()
world << "No one is looking at me."
..() // this calls the default NoViewers()
If you want to include extra resources like images, script files, or css files, you have to let the
sd_window know beforehand so it can send all those resources to every target before it displays the window. you
use the AddResource() proc to do this.
The format is:
AddResource(resource, filename)
Resource is the BYOND resource. It can be an image, a file, a sound, or anything else that you need.
Filename if the filename used to store the resource in the client's cache. You will use this filename in your
HTML content to access the resource.
mob/verb/resource_window()
set desc = "Open a window with external resources."
var/sd_window/S = new("Don't look! I'm naked! <img src=nudie.png width=96 height=96>")
S.AddResource('naked.dmi', "nudie.png")
S.Display(src)
There is also a SendResources() sd_window proc, but it is called automatically by Display() and you never need to
worry about it. If for some reason you want to transmit the resources ahead of time, you use SendResources() with the
target as its only argument. Just in case you've forgotten, the target can be a mob, client, or a list of mobs and
clients.
So far sd_windows have been great for displaying things, but there is a problem if you use an enhanced sd_window
with BYOND links. It won't recognize the BYOND protocol and tries to open a new browser window. Yuck! We need a
little bit of javascript to send information back to BYOND from an enhanced sd_window. Unenchanced sd_windows
recognize BYOND links just fine, but it's best to make a flexible javascript to report for either type of window, that
way you can send the same content to popups of either type. Lucky for you, I've already done that.
<script TYPE="text/javascript" LANGUAGE="JavaScript">
function BYOND(X) {
var wndw = window;
if(top==self) wndw = dialogArguments;
wndw.document.location.href = 'BYOND://?src=\ref[WINDOW_REFERENCE]&'+X;
}
</script>
This defines the javascript function BYOND() which accepts an argument to report back to the BYOND server. You can
shorten that first line to just <script> if you like, but the HTML nazis will get you if you do.
Now that we know how to send the data to BYOND, your code has to know how to catch it. The data will go though
client.Topic(), and if it finds a src parameter like the one above, it will send it to the Topic() proc of whatever
that src is, the sd_window datum in this case. You should call ..() at the end of the Topic() override, so the
sd_window can detect when it is closed manually.
mob/verb/input_window()
set desc = "Open an input window that tells you what your input is."
var/sd_window/input_window/I = new() // no content now, so we can \ref this sd_window for content
I.content = {"<head><title>Input your name</title><script>
function BYOND(X) {
var wndw = window;
if(top==self) wndw = dialogArguments;
wndw.document.location.href = 'BYOND://?src=\ref[I]&'+X;
}
</script>
</head><body>
<input ID=Name value="[usr.name]" size=30>
<input type=BUTTON onClick="BYOND('name='+Name.value);" value="Submit">
<body>"}
I.Display(src)
sd_window/input_window
// reports everything sent to Topic
Topic(href, hlist[])
if("name" in hlist)
world << "[usr] entered '[hlist["name"]]'."
..() // so that the "CLOSED" message can go through
Since a lot of sd_window depends on the client's browser, the library provides a method to detect the client's
browser, version information, and operating system.
The detect_navigator datum opens an invisible browser window on a client's computer and reports back to the server
to populate the sd_OS,
sd_browser_name, sd_browser_version, and
sd_browser_minor_version client vars.
A detect_navigator automatically deletes itself when finished. (Usually within a couple of ticks of creation.)
To use a detect_navigator datum, just create a new one with a client as the argument of the new() call.
Example:
client
New()
..()
// detect navigator settings as soon as the client connects
new/sd_window/detect_navigator(src)
The library includes two demo source files. These demo files will not be included in your own projects when
you include the library. Either demo can stand alone or you can compile them both together.
sd_window_Guide_demo contains code from the examples in this document.
sd_window_Extra_demo.dm gives a brief demonstration of sd_window's capabilities.
sd_window_Extra_demo.dm has the following commands:
- Background
- Display a window with a background image. This command illustrates the use of the
sd_window AddResource proc.
- Close_All
- Close all your open windows.
- Dialog_Close
- Close the demo interactive dialog window, but preserve its data. This window can
be recalled with the Dialog_Open command. Note that closing the window through any other means (the window's
close button or the Class_All command) will delete the window and any data it has.
- Dialog_Delete
- Delete the demo interactive dialog window. If it is open, this command will close it
automatically, without any special code.
- Dialog_Open
- Opens the demo interactive dialog window. You can use the Dialog_Close and Dialog_Delete
to interact with this specific window.
- Enhanced
- Toggle whether sd_window displays enhanced windows to your client. Enhanced windows are
capable of positional control and have a few extra display options, but also require special effort to report
data back to the server.
- Limits
- Display a demo window describing and demonstrating some limits of sd_windows.
- Random number
- Open a number of randomly positioned sd_windows.
-
- Say message
- Broadcast a message to other users.
- Simple
- This simple window only requires one line of code to create and display.
- Timed
- Open a timed window that closes automatically in 45 seconds.