sd_window Guide

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.

back to Contents

sd_window Features

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.

back to Contents

Using sd_window

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.

Creating sd_windows

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.

back to Contents

Basic sd_windows

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.

back to Contents

Timed sd_windows

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)

back to Contents

Positioning sd_windows

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.

back to Contents

Sizing sd_windows

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.

back to Contents

Other sd_window Options

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.

back to Contents

Persistent sd_windows

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)

Displaying and Closing Persistent sd_windows

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)

Changing an sd_window's Display

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)

back to Contents

sd_window Hooks

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()

back to Contents

sd_windows with Extra Resources

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.

back to Contents

Getting Input From sd_windows

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.

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

back to Contents

Detecting the Client's Browser

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)

back to Contents

Demo Program

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.

back to Contents