Interface

by Forum_account
Provides a better way to interact with interface controls than the built-in winset/winget procs. [More]
To download this library for your Linux/Mac installation, enter this on your command line:

DreamDownload byond://Forum_account.Interface##version=10

Emulator users, in the BYOND pager go to File | Open Location and enter this URL:

byond://Forum_account.Interface##version=10

1925 downloads
Version 2.7
Date added: Aug 17 2010
Last updated: Jul 12 2012
15 fans
Version 2.7 (posted 07-12-2012)
  • Fixed some bugs with the Window control. Previously it wouldn't work because the library assumed that all controls had both a control_id and window_id, but windows only have a window_id.
  • Modified the list parsing object to also support the syntax for hashtables.
  • Added the ability to pass associative lists between DM and JavaScript. Unfortunately this requires checking to see if a list is an associative list and the only way I've found to do that causes a runtime error if the list is not associative. The code still functions - it expects that this error can happen - but it still prints a "bad index" error to your output console.
  • Updated the javascript-demo to include examples of passing hashtables back and forth between DM and JS. Also cleaned up the code a little.
Version 2.6 (posted 03-13-2012)
  • Added the Link() and Browse() procs to the /Browser object. This proc takes a single parameter, a URL, and redirects the browser control to that URL.
  • Updated the New() proc for all controls to be more flexible. The arguments are a window ID, control ID, and a mob. The window and control IDs can be passed as separate strings or as one string of the form "window.control". If they're separate strings, the first string is assumed to be the window ID.
  • Added support for nested lists to be passed from JavaScript to DM.
  • Fixed a bug with object references being parsed incorrectly when they were part of a list.
  • Removed some procs from base.dm and made the library require the Forum_account.Text library.
  • Changed the name of "html-demo" to "browser-demo" and updated the demo a little.
  • Removed the following demos: lesson-2, lesson-4, stat-demo, and window-demo.

Version 2.5 Posted!
  • Created the JS2DM proc which is an alias of BROWSER_UPDATE_SCRIPT. It does the exact same thing, it just has a shorter name. The BROWSER_UPDATE_SCRIPT proc is still in the library for backwards compatibility.
  • Documented the code in the library - added headers to each file and some inline comments.
  • Added a list parser (list-parsing.dm) so you can now pass JavaScript arrays to DM procs and they'll automatically be converted to DM lists. It doesn't handle nested lists or associative arrays (JS objects/hashtables).
  • Added the js-hello-world demo which is a very basic example of calling a DM proc from JS.
  • Split the demo that was previously called "demo" into controls-demo and window-demo. They're essentially the same. window-demo uses the library to generate code for the window based on the .dmf file. controls-demo doesn't do this, it just instantiates the /Control objects (/Browser, /Info, /Label, etc.) directly.
  • Added javascript-demo which shows examples of passing different data types from JavaScript to DM and from DM to JavaScript.


Version 2.4.1 Posted!

This is a minor update that adds type checking to JavaScript-to-DM function calls. Previously when calling a DM function from JavaScript all arguments would be text strings (calling src.build(3) from JS would pass "3" to the player's build proc). This now properly handles numbers, strings, and object references (sorry lists, you'll have to wait).

html-demo was updated to showcase this new feature. When you click on a link to build it calls src.build(my_turf, 'wood');. The JavaScript code passes a DM object reference to the player's build proc.

I also added the List proc for grid controls. This is just a shortcut for displaying a list.

About the Library

This library started as a way to abstract out the details of calling winset and winget to create a better API but quickly grew. The library also introduces some shortcut functions for dealing with certain controls. For example, here's how you set the contents of a cell in a grid control with and without the library:

// without the library this is what you have to do:
winset(src, "window.gridcontrol", "current-cell=1,3")
src << output(src.weapon, "window.gridcontrol")

// with the library:
var/Grid/g = new("window","gridcontrol",src)
g.Cell(1,3,src.weapon)


You can store a reference to the grid control on the mob so you can always easily update their interface.

The library grew to include functions to facilitate interaction between JavaScript running in a browser control and the DM program running on the server. The Browser object lets you easily call JavaScript functions and you can even call DM functions from JavaScript!

Version 2.2.0

I created a demo that is separate from the library. It uses the library to handle interaction between a jQuery plugin and the DM program. download the demo

Added support for calling procs of the owner and global procs from JavaScript. The html-demo example shows how to call procs of the owner. To call a global proc named "myproc" you'd use the JS function world.myproc().

Added better JavaScript-to-DM support. Arguments can now be passed from JS to DM also. There is still some work to do here (all arguments end up as text strings in DM). Future updates will address this (version 2.4.1 fixed this).

Also added the Browser.Cache proc to eliminate use of browse_rsc. If you pass only a filename as the argument it will be cached by that name. If you pass an icon and icon state as arguments it will cache a .png image of that icon. For example:

// This puts the file icons.mob.png in the client's cache so you can reference it in HTML.
browser.Cache('icons.dmi', "mob")


Version 2.1

Two demos were added showing how to implement Lesson 2 and Lesson 4 of Lummox's skin tutorials. Some features were added to accommodate these new demos:

• The Grid.Cell(x,y,value) proc was added to handle the details of setting the value of a single cell.

• The Output.Output proc was added to handle outputting text. It takes two parameters. One is the text to output, the other is who you want to output to (src, world, view, etc.). If the target is omitted it defaults to the control's owner.

• Support for the Child type of control was added.

Version 2.0

Version 2 adds some neat features for browser controls. To output HTML to a browser control you can do this:

var/Browser/browser = new("window1","browser",src)
browser.HTML("put your HTML code here")


With that Browser object you can also call JavaScript functions:

browser.JavaScript("update_loc", loc)


This example calls the "update_loc" JavaScript function and passes it your location as a parameter. The library encodes the DM object as a JavaScript object so you can reference your location's properties in JavaScript just like in DM. You can even call DM procs from JavaScript!

// In JavaScript:
function update_loc(turf)
{
    coords.innerHTML = turf.x + ", " + turf.y;
    turf.test();
}


Old Notes

This library provides a layer of abstraction between you and the awful winset/winget procs. Instead of commands like this:

winset(player, "window1.label1", "text=Hello+world!")
winset(src, "window1.indicator", "is-visible=[status_ailment ? "true" : "false"]")
winset(src, "window1.button1", "command=button_click")
var/font_style = winget(src, "window1.label1", "font-style")


You can do this:

window1.label1.Text("Hello world!")
window1.indicator.IsVisible(status_ailment)
window1.button1.Command(/mob/proc/button_click)
var/list/font_style = window1.label1.FontStyle()


These procs handle the details of generating and parsing the parameter strings that winset/winget use. They also create objects to represent data when appropriate (for colors, positions, sizes, and lists).

The library does make some sacrifices. To speed things up it caches the values of certain properties. If you use a client-side command to update a property the server won't know about it and won't request the new value. Because client-side commands are ugly to deal with, I've sacrificed them to create a decent interface API.

Comments

Elochai: (Nov 27 2011, 10:06 am)
good