All | Window (Main) | Label | Button | Input | Output | Browser | Map | Info | Child | Tab | Grid | Bar | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Size & position | pos size anchor1 anchor2 |
can-minimize can-resize is-minimized is-maximized |
view-size | lock | cells cell-span is-list |
width | |||||||
General appearance | is-visible is-transparent border flash |
alpha statusbar |
is-flat | multi-line | style max-lines |
style | multi-line | is-vert | multi-line | show-lines style |
dir angle1 angle2 |
||
Color | text-color background-color |
transparent-color | link-color visited-color |
highlight-color tab-text-color tab-background-color prefix-color suffix-color |
line-color link-color visited-color |
bar-color | |||||||
User interaction | is-default is-disabled focus drop-zone right-click |
can-close | is-checked group button-type |
is-password no-command |
show-history show-url |
splitter show-splitter |
current-tab | current-cell | is-slider value |
||||
Text & title | font-family font-size font-style |
title titlebar |
text align text-wrap |
text | text | use-title | text-mode | allow-html tab-font-family tab-font-size tab-font-style |
show-names | ||||
Images | icon image image-mode keep-aspect |
image image-mode keep-aspect |
image | image enable-http-images |
auto-format | icon-size letterbox zoom |
small-icons enable-http-images |
||||||
Commands | on-size | macro menu on-close |
command | command | on-show on-hide |
on-show on-hide |
on-show on-hide on-tab |
on-tab | on-change | ||||
Panes | can-scroll is-pane |
left right |
tabs |
Parameter | Format | Supported by | Default | Misc. info |
---|---|---|---|---|
align | center or left or right or top or bottom or top-left or top-right or bottom-left or bottom-right | Label | center | Default alignment of text/image, both horizontal and vertical. A BYOND direction flag like WEST may be assigned to this parameter, or 0 for center alignment. |
allow-html | true or false | Info | false | Allow HTML tags to be used in stat() info. The same limitations apply as to the Grid control. |
alpha | 0 to 255 | Main | 255 | Opacity; 255=opaque, 0=invisible. |
anchor1 | [x%],[y%] or none | All | none | Anchors the control within the window/pane. 0,0 is the upper left, 100,100 the lower right. Use one anchor to manage the control's position only, or two to stretch it. |
anchor2 | [x%],[y%] or none | All | none | |
angle1 | [angle] | Bar | 0 | The angle where the bar's arc starts, if dir is clockwise or counterclockwise. 0 is due north, 90 is east, etc. |
angle2 | [angle] | Bar | 180 | The angle where the bar's arc ends, if dir is clockwise or counterclockwise. 0 is due north, 90 is east, etc. |
auto-format | true or false | Browser | true | Adds formatting to the HTML header so Internet Explorer can properly display PNG files with transparency. IE7 does not require this. |
background-color | #RRGGBB or #RGB or none | All | #fff | Affects background color. May not work the same in all controls. |
bar-color | #RRGGBB or #RGB or none | Bar | none | The color of the bar or slider. |
border | none or line or sunken | All | none | Border type around the control or window. May not work the same in all controls. |
button-type | pushbutton or pushbox or checkbox or radio | Button | pushbutton | Changes the type of button. A pushbox is a regular button that can be pushed in (used as a checkbox or radio control). A value of checkbox or radio will make it look like a simple checkbox or radio button. |
can-check | true or false | Menu | false | Toggle the check on a menu item automatically (or treat it as a radio button, if group is specified) when it is clicked. |
can-close | true or false | Main | true | Allow the window to be closed. |
can-minimize | true or false | Main | true | Allow the window to be minimized. |
can-resize | true or false | Main | true | Allow the window to be resized or maximized. |
can-scroll | none or horizontal or vertical or both | Main | none | If the window is a pane, it will retain its horizontal and/or vertical size and show scrollbars if necessary, instead of shrinking to fit the container. |
command | "[verb]" | Button, Input, Menu, Macro | "" | Command executed when the button, menu item, or macro is activated; or the default command for an Input control. If used for Input, this command is followed by whatever the user types in. For input controls, if your command starts with an exclamation point (!), everything after the ! is shown as a default prompt that may be cleared by the user. |
cell-span | [columns]x[rows] | Grid | 1x1 | The span of the current grid cell; it can be merged with cells to the right and down. If is-list is true, this setting is ignored. This setting is only available at runtime. |
cells | [columns]x[rows] | Grid | 0x0 | The number of columns and rows in the grid. If is-list is true, this sets the maximum number of items in the list; it can be set to just a single value [items]. Setting the number of rows or columns to -1 means that value will not change. |
current-cell | [column],[row] | Grid | 0x0 | The active cell. Any output sent to the grid will go into this cell. If is-list is true, this can be set to |
current-tab | "[name]" | Tab | "" | The name the active/default tab. If set to a tab that is not currently available, the pane by that name will be added as another tab. |
dir | north or south or east or west or clockwise or counterclockwise | Bar | east | The direction of the bar; as the value increases the bar will move further in this direction. The clockwise and counterclockwise directions will let you make an arc from angle1 to angle2. You can use cw and ccw as shorthand for clockwise or counterclockwise. |
drop-zone | true or false | All | varies | True if dragged objects may be dropped here. Default is true for Map, Info, and Grid controls, false for others. |
enable-http-images | true or false | Output, Grid | false | Allows images to be pulled from the Web when using the <img> tag; otherwise only locally stored images can be shown. |
flash | [times] or -1 | All | 0 | Set to a value above 0 to make the control flash, 0 to stop flashing, or -1 to flash indefinitely. Currently this is only implemented for window controls even though the param exists for all controls. |
focus | true or false | All | false | True if this control has focus; set to true to give it focus. |
font-family | "[font name]" | All | "" | Leave blank to use the default font. This can be used for CSS-style fallback fonts, e.g. "Arial,Helvetica". |
font-size | [point size] | All | 0 | Leave 0 to use the default font size. |
font-style | "bold" or "italic" or "underline" or "strike" or any combination | All | "" | Sets the font style. Values can be combined if separated by spaces or commas. |
group | "[name]" or "" | Button, Menu | "" | If the button or menu item should be treated as part of a radio button group, this is the name of the group; otherwise group should be blank. Buttons in different windows, or menu items in another menu or submenu, are always treated as a different group. |
highlight-color | #RRGGBB or #RGB | Info | #0f0 | The color used to highlight moused-over statpanel items or verbs. |
icon | '[file]' | Main | "" | Custom icon used for the window. If this is a pane, its icon will appear on the tab if the pane is inside a tab control. (The Windows .ico format is not used. Only image formats BYOND can already use are supported.) |
icon-size | 0 or [size] | Map | 0 | Size, in pixels, of icons on map. 0 stretches to fit available space; 32 is the BYOND standard icon size. Use zoom if you'd rather go by a ratio instead of pixels. |
id | "[name]" | All | no default | The name of this control. If this is a Main control, (a window or pane) the name should be unique. Other controls can be referenced by [windowname].[controlname] at runtime. Read-only. |
image | '[file]' | Main, Label, Button, Output | "" | Image shown in label/button, or background image for window/pane or output. (Output control: See notes.) |
image-mode | center or stretch or tile | Main, Label | stretch | If using a background image, this decides how the image will fit the window/pane or label. |
index | [N] or 0 | Menu | 1000 | Moves the menu item to the Nth position among its siblings. 0 or less is no change. |
is-checked | true or false | Button, Menu | false | True if the button or menu item is currently checked. (Set button-type to use this with buttons, or can-check for menus.) Menu items allow manual checking even if can-check is false. |
is-default | true or false | All | false | Specifies a default control. This should be set to true for your main window, map, info, and main output, input, and browser controls. |
is-disabled | true or false | All, Menu, Macro | false | Disables the control, menu item, or macro. |
is-flat | true or false | Button | false | Do not give this button a 3D appearance. |
is-list | true or false | Grid | false | True if the grid is used for a list of items; the number of columns and rows may change to fit them. |
is-minimized | true or false | Main | false | Minimize the window. |
is-maximized | true or false | Main | false | Maximize the window. |
is-pane | true or false | Main | false | Make this a pane that will be used in Child or Tab controls, not a regular window. Read-only. |
is-password | true or false | Input | false | Hide text with asterisks. Copy to clipboard is not available in this mode, but the text parameter can still read the control's contents. |
is-slider | true or false | Bar | false | The bar is an adjustable slider instead of a progress bar. |
is-transparent | true or false | All | false | May not work for all controls. (See notes.) |
is-vert | true or false | Child | false | The splitter, if it appears, is vertical. |
is-visible | true or false | All | true | The main window should usually be made visible. |
keep-aspect | true or false | Main, Label | false | If stretching an image, preserve its aspect ratio. |
left | "[pane name]" or none | Child | none | The name of the pane that will appear on the left/top side of this Child. If none, the right/bottom side fills the whole space. |
letterbox | true or false | Map | true | If map auto-scales its icons, make sure the entire map fits, and fill excess space with blackness. If letterbox is not enabled, zoom to fill the entire available space; any excess will be cut off. |
line-color | #RRGGBB or #RGB | Grid | #c0c0c0 | The color of grid lines. |
link-color | #RRGGBB or #RGB | Output, Grid | #00f | Affects unvisited links. |
lock | none or left or right | Child | none | Allows one pane to "lock" the splitter so if the Child control is resized, the splitter will stay put on that side. |
macro | "[name]" | Main | "" | Macro set to use, if any. Use the name of a macro set defined in the skin file. Not valid for panes. |
max-lines | [lines] or 0 | Output | 1000 | Maximum number of lines before the control drops old text to make room for more. (Extra lines may be allowed to prevent flickering between trims.) 0 is no limit. |
menu | "[name]" | Main | "" | Menu to use, if any. Use the name of a menu defined in the skin file. Not valid for panes. |
multi-line | true or false | Input, Info, Tab | varies | Info and Tab: Show tabs in multiple rows if there are too many to fit in a single row; true by default. Input: Create a multi-line input control; false by default. Changing this at runtime will not affect an input control. |
name | "[label]" or "[key]" or "" | Menu, Macro | no default | For menus, this is the enu item label. A tab character can be used between the name and a keyboard shortcut, like "Help\tF1". (Keyboard shortcuts must be made as macros in order to work.) A blank name shows just a separator. For macros, the name is the key combination such as R+REP or CTRL+Northwest. |
no-command | true or false | Input | false | If true, this input control is for typing only; hitting Enter will not run a command. |
on-close | "[verb]" | Main | "" | Command executed when the window is closed. Not valid for panes. |
on-change | "[verb]" | Bar | "" | Command executed when the value of the bar/slider is changed. If you drag the slider around, the command will not run until you let go. |
on-hide | "[verb]" | Map, Browser, Info | "" | Command executed when the default map, browser, or info control is hidden by the game. Usually a .winset command. (Not editable in Dream Maker.) |
on-show | "[verb]" | Map, Browser, Info | "" | Command executed when the default map, browser, or info control is shown by the game. Usually a .winset command. (Not editable in Dream Maker.) |
on-size | "[verb]" | All | "" | Command executed when the control is resized. If you are dragging a window edge or splitter, the command won't run until you finish. No command will be sent in response to size or splitter changes made by winset(). |
on-tab | "[verb]" | Info, Tab | "" | Command executed when the current tab is changed. |
pos | [x],[y] or none | All | 0,0 | Position of upper left corner. |
prefix-color | #RRGGBB or #RGB or none | Info | none | The color used in the prefix/header column, to the left of atoms in the statpanel. If no color is specified, the normal text-color is used. |
right | "[pane name]" or none | Child | none | The name of the pane that will appear on the right/bottom side of this Child. If none, the left/top side fills the whole space. |
right-click | true or false | All | false | True if this control should allow right-clicks to behave like any other click instead of opening up popup menus or similar special behavior. |
size | [width]x[height] | All | 0x0 | Setting 0 for width or height uses up any available space right/downward. If the control is a window, this refers to its interior size, not counting borders, titlebar, menu, or statusbar. |
show-history | true or false | Browser | false | Show forward/back navigation buttons. |
show-lines | none or horizontal or vertical or both | Grid | both | Which grid lines are shown. |
show-names | true or false | Grid | true | If atoms are output to the grid, show the atom's name next to the icon. If the atom has no icon and show-names is false, the grid cell will be blank. |
show-splitter | true or false | Child | true | Show a splitter if both the left and right panes are in use. If shown the splitter allows the user to resize the two panes. |
show-url | true or false | Browser | false | Show URL address bar. |
small-icons | true or false | Grid | false | When output(object,grid) is sent, show smaller icons (16×16) in this control instead of larger ones (32×32). |
splitter | 0 to 100 | Child | 50 | Percent distance of the splitter, if it appears, from the left/top of the Child control. 50% is an equal split. |
suffix-color | #RRGGBB or #RGB or none | Info | none | The color used in the suffix column, to the right of atoms in the statpanel that have a suffix. If no color is specified, the normal text-color is used. |
statusbar | true or false | Main | false | Show a statusbar (unless this is a pane). |
stretch | true or false | Label | false | Stretch the image for this label. (Deprecated. Use image-mode instead.) |
style | "[css]" | Output, Map, Grid | "" | Custom stylesheet used for the control. For maps, this affects any maptext drawn. In a grid, changing this will not immediately affect the existing cells, which will need to be updated. |
tab-background-color | #RRGGBB or #RGB or none | Info | none | Affects background color for tabs. |
tab-font-family | "[font name]" | Info | "" | Same as font-family, but for tabs. |
tab-font-size | [point size] | Info | 0 | Same as font-size, but for tabs. |
tab-font-style | "bold" or "italic" or "underline" or "strike" or any combination | Tab | "" | Same as font-style, but for tabs. |
tab-text-color | #RRGGBB or #RGB or none | Info | none | Affects foreground text for tabs. |
tabs | "[tab names, comma-separated]" or "+[new tab name]" or "-[tab to remove]" | Tab | "" | The names of the panes that will appear as tabs, in order, separated by commas. Precede with "+" to add tabs to the current list without removing any, or "-" to remove only the tabs you specify. |
text | "[label]" | Label, Button, Input | "" | Text shown in label/button/input. For input controls this setting is only available at runtime. |
text-color | #RRGGBB or #RGB or none | All | #000 | Affects foreground text. |
text-mode | true or false | Map | false | Show text mode even if icons are available. Text mode will be used if no icons are present, regardless of this setting. |
text-wrap | true or false | Label | false | Wrap text within the label. |
title | "[title]" | Main | "" | The title that would be shown in a titlebar, or in a tab if this is a pane. |
titlebar | true or false | Main | true | Show a titlebar (unless this is a pane). |
transparent-color | #RRGGBB or #RGB or none | Main | none | Color in background image to make transparent; this will affect all controls. |
type | [TYPE] | All | no default | The type of control. Read-only. |
use-title | true or false | Browser | false | Use the browser's title to override the title of the window/pane holding it. |
value | 0 to 100 | Bar | 0 | The "fullness" of the bar or slider, as a percentage. |
view-size | [size] | Map | 0 | Size, in pixels, the area the map is using (or trying to use) for display, not including any of the "letterboxing". If icon-size is not 0, this value may be bigger than the control's actual size. Read-only. |
visited-color | #RRGGBB or #RGB | Output, Grid | #f0f | Affects visited links. |
width | [width] | Bar | 10 | Width, in pixels, of the bar or slider. 0 uses all available width. |
zoom | 0 or [size] | Map | 0 | Zoom factor for icons on map. 0 stretches to fit available space; 1 will show the icons at their normal size, 2 at double size, 0.5 at half size, and so on. This is a companion to icon-size, which does the same thing but uses an exact pixel size instead of a ratio. |
Each window, pane, or control has an ID. This is used for winset(), winget(), winclone(), winshow(), winexists(), and output().
The ID needs to be unique for a window or pane, but other controls don't have this restriction. If a control ID is unique, you can interact with it by just using that ID; otherwise, you'll need to use "[window_id].[control_id]" to reference it.
For regular input/output, when a control isn't named specifically, BYOND will use whatever controls you specify as defaults.
If two controls of the same type are marked as defaults, the first one in the skin is considered the true default.
It is generally not a good idea to change is-default at runtime. Instead, default controls can be more easily placed in a pane that can be moved around. If you want swappable window layouts for the main window, the easiest way to handle that is to use panes as well, and just put a Child control in the main window.
By using one anchor, you can hold your control in the same relative position in the window/pane as it resizes. Using two anchors, you can stretch it.
anchor1 is meant to be the top left anchor, and anchor2 is the bottom right. If you set up anchors in the wrong order, weird things can happen.
Several commands can be executed at runtime that are not verbs, but raw instructions for Dream Seeker.
You can change the default font of almost any control by changing the following parameters:
The font-family paremeter can be a list of fonts separated by commas, like "Tahoma,Arial,sans-serif", and you can put double or single quotes around a font name if it includes a space, such as: "\"Tempus Sans ITC\",\"Comic Sans MS\",sans-serif".
The list of fonts is done in "first-choice" order just like in CSS, so that if the user does not have the first font on the list installed, the next one will be tried, and then the next, and so on. There are some generic fonts that will always be accepted: sans-serif (a friendly, basic font), serif (like what you see in most books), and monospace (a fixed-width, typewriter-like font).
If you include any .ttf font files in your resources by putting them in single quotes in your source code, they will be temporarily installed on the user's system so they are available to your interface. It is a good idea not to do this with common fonts that most people have, because font files can be large. Also you should be sure the font is OK to distribute. Many freeware fonts can be found online.
var/list/extra_resources = list(\ 'myfont.ttf', 'myfont_bold.ttf')
Use font-size to specify a point size for the font. 0 is the default value, which will just use whatever size the control would normally use.
The font-style parameter can change some of the font's attributes to alter the way it looks. You can choose from bold, italic, underline, and strike as styles. To use more than one, combine them with spaces or commas like "bold,italic". This parameter isn't very picky, so it can accept things like "italics" and "strikeout" and still understand what you mean. It isn't case-sensitive either, so caps are OK.
Some controls have special behavior regarding fonts:
Normally winset() is used to modify one control at a time. The list of parameters to change is in the same format used by list2params():
winset(usr, "tinypane.output", "text-color=#000000;background-color=#ffffff")
Calling the winset() proc with a blank or null control ID lets you modify more than one control at once, just like the .winset command does. To use this feature, each parameter should be listed with its full control_id.parameter name.
winset(usr, null, "tinypane.output.text-color=#000000;tinypane.input.text-color=#000000")
You can use the .winset command or the winset() proc to execute a verb, like so:
.winset "command=\"jump\""
winset(usr, null, "command=\"jump\"")
No window or control name is supplied, only the command parameter. Some commands cannot be executed this way, but can only be typed manually or run from Dream Seeker's Options & Messages box.
Another option you have is resetting the skin:
.winset "reset=true"
winset(usr, null, "reset=true")
When resetting the skin, any saved settings (like window position and size) are still kept. Controls created at runtime, including windows made via winclone(), are destroyed. The reset option is provided so that you can reset a user's skin when they reconnect or when they are brought in via link() from another server. Normally the skin will not reset.
Conditonals are also supported, but only for the .winset command used in DS or in skins. The winset() proc in DM does not technically support them. The format is like so:
condition?choice1:choice2
The condition is the same as any other parameter you might use in .winset, but instead of setting the parameter, it checks to see if it's true. If so, then the parameters in choice1 will be set. Otherwise, the parameters in choice2 are set. This example makes the window background red if bigbutton is checked.
.winset "bigbutton.is-checked=true ? window.background-color=#ff0000 : window.background-color=none"
If you want to look for values that don't match instead of values that do, use != instead of = in the condition.
.winset "bigbutton.is-checked!=false ? window.background-color=#ff0000 : window.background-color=none"
The choice2 item is optional.
.winset "bigbutton.is-checked=true ? window.background-color=#ff0000"
Because it's often useful to do more than one thing at a time, choice1 and choice2 don't have to be just one parameter. You can use multiple parameters, but separate them with a space instead of a semicolon.
.winset "bigbutton.is-checked=true ? window.text-color=#ffffff window.background-color=#ff0000 : window.text-color=none window.background-color=none"
Calling the winget() proc with a blank or null control ID can return some values that belong to the whole program.
To retrieve more than one parameter at a time, separate them with semicolons:
var/buttons = winget(player, "mainwindow", "pos;size")
The result looks like this:
pos=0%2c0;size=500x500
...and can be decoded using params2list(). That will give you an associative list where list["pos"] is "0,0" and list["size"] is "500x500".
To retrieve the parameters of more than one control at a time, separate the control IDs with semicolons:
var/buttons = winget(player, "button1;button2", "is-checked")
Again the result can be decoded using params2list(). The name of each parameter in the result would be button1.is-checked and button2.is-checked. If you mix two types of controls where one has a parameter that the other doesn't, only the parameters that are available are included in the result. For instance, if you have a window with an Input and two Buttons:
var/form = winget(player, "age;male;female", "text;is-checked")
Your result might look like so:
age.text=21;male.is-checked=false;female.is-checked=true
You can use a wildcard after a window name in winget() to retrieve info about all the controls in a window (including the window itself). winget(player, "mainwindow.*", "image") will return the image parameter (where available) for mainwindow and any controls that are a part of mainwindow. The result would look something like this:
mainwindow.image=background.png;mainwindow.button1.image=;mainwindow.button2.image=smiley.png
More than one parameter can be used at a time, so if you use winget(player, "mainwindow.*", "size;image"), you will also receive size info about all the controls.
This wildcard format also works with menus and macros. For a macro, it will retrieve info on every individual macro in the set that has an ID associated (so it can be disabled, changed at runtime, etc.). For a menu, it will retrieve info on any menu item with an ID, and also anything in sub-menus.
(Note: The wildcard format is not recursive, except with menus. If you use winget() on all the controls in a window and that window includes a Child control, the Child's panes are not included in the result.)
A wildcard is also allowed for the parameters. If used, it will retrieve all parameters belonging to a control. To conserve bandwidth, this should be avoided; it is mostly intended for special occasions or for working with JavaScript (below)
Some games use browser interfaces and want them to interact with the rest of the skin. In the past the only way to do this was by making the JavaScript call a byond: URL and interpreting it in client/Topic(), which made it work like a verb. To read any parameter values, the server had to call winget() which would then have to wait for a reply from the client, all to do things that JavaScript could have done locally if it had a way to communicate directly.
To improve on this and allow better access to the skin via JavaScript, two new URL formats have been added. If window.location is set to these from JavaScript in a browser control, they can be used to interact directly.
Winset URL: byond://winset?id=[element ID]&[property]=[value]&...
This works like an ordinary winset() call from the server, where the id field is the ID of the element to change, and all of the other properties listed in the URL are items to change.
Any text you use other than letters, numbers, hyphens, commas, and periods should be encoded via the encodeURIComponent() function in JavaScript.
As with normal winset(), you can leave the ID blank and specify each property fully, such as mybutton.is-clicked.
Winget URL: byond://winget?callback=[callback function]&id=[element ID/list]&property=[property/list]
In this winget, the IDs and properties you want can be separated by commas if you want to retrieve more than one.
The winget operation works via a callback function you must define in JavaScript. The callback is given just one argument, a JavaScript object with all of the properties you requested. For example, this URL:
byond://winget?callback=wgcb&id=button1&property=is-checked,size,background-color
...might send this to the callback function wgcb:
{ 'is-checked': true, 'size': { x: 60, y: 20 }, 'background-color': { value: 'none', isDefault: true, red: 236, green: 233, blue: 216, alpha: 255, css: '#ece9d8' } }
The property names will be in the same format you would expect from winget(), so when you're looking at multiple elements' properties, you'll get the full names in id.property format. The values are always sent back in a convenient form for JavaScript to work with; in the case of size, position, and color these will always be objects.
An optional "control" parameter for the winget call can be used if you want to send data to a callback in a different browser control.
When you use winexists() to check on whether a control exists, it will return one of the following values as text:
At this time, a Main control is either a window or a pane, and stays that way for life. Panes do not have most of the options a window does; those settings, such as statusbar, are irrelevant for the pane. Only panes can be selected into Child or Tab controls.
Windows or panes may be copied via the winclone() proc, and windows can be shown or hidden via winshow().
Any window or pane in your skin file is loaded immediately, even if it is invisible and not used yet.
Menus can be changed at runtime just like controls. They support a more limited set of parameters. To alter a menu item or add items under it, it needs to have an ID. These are the parameters that can be changed using winset():
A new item can be added to a menu at runtime by including a parent parameter, which points to the ID of a menu or one of the items in it. If you have a menu with an ID of "mainmenu", for instance, this will add a Players menu beneath it:
winset(usr, "playersmenu", "parent=mainmenu;name=Players") for(var/client/C) var/itemname = "playermenu_[C.ckey]" var/command = "view [C.ckey]" winset(usr, itemname,\ "parent=playersmenu;name=[url_encode(C.key)];command=[url_encode(command)]")
Menu items that were added this way can also be deleted again by setting their parent to a blank value.
A menu can also be cloned with winclone. To use the menu, use winset() to assign it to a window.
Macros can also be changed at runtime. If a macro does not have an ID, you can refer to it by its key combination. If you have a macro set named macro1 and have a Ctrl+E macro for instance, you could use winset() with "macro1.Ctrl+E". These are the parameters that can be changed using winset():
The name is actually the full key combination as it would appear in the macro editor, like CTRL+E, Space+REP, or Alt+Shift+F1. This is not case-specific and it doesn't matter where you put modifiers like CTRL+, SHIFT+, etc.
A new macro can be added to a macro set at runtime by including a parent parameter, which points to the ID of an existing macro set. Using the example above, Ctrl+E could be added as a macro at runtime like so:
winset(usr, "myCtrlEmacro", "parent=macro1;name=Ctrl+E;command=exit")
Macros that were added this way can also be deleted again by setting their parent to a blank value.
winset(usr, "macro1.myCtrlEmacro", "parent=")
A macro set can also be cloned with winclone. To use the macros, use winset() to assign the macro set to a window.
The winclone() proc can copy a window, pane, menu, or macro set from the skin file. It takes three arguments: The user, the name of the skin element to copy, and the name of the new clone.
winclone(player, "helpwindow", "helpwindow_howtoplay")
When you copy an item that exists in the skin file, any items that belong to it are also copied. If the helpwindow element in this example had a browser control called helpwindow.browser, then the new window would have a control called helpwindow_howtoplay.browser just like it. This would be useful if you had several different kinds of help topics the user might want to look at at the same time.
You can also use winclone() to create a brand new element. If the name of the original is "window", "pane", "menu", or "macro" and an element by that name does not already exist in the skin file, an element of that type is created. So for instance, you can create a brand new menu:
winclone(usr, "menu", "newmenu") winset(usr, "newmenu_file", "parent=newmenu;name=File") winset(usr, "newmenu_quit", "parent=newmenu_file;name=Quit;command=.quit")
You can also create a new window or pane this way.
// Create the pane winclone(usr, "pane", "newpane") // Give it a size so we can figure out where to put controls winset(usr, "newpane", "size=100x100") // Add controls winset(usr, "newpane_label", \ "parent=newpane;pos=0,0;size=100x100;anchor1=0,0;anchor2=100,100") // Put the pane in a child control where it can be seen winset(usr, "a_child", "left=newpane") usr << output("newpane_label", "New label")
After you have cloned something or created a control at runtime, you can delete it like so:
winset(usr, "clonedwindow1", "parent=none")
The grid and info controls support limited formatting using HTML and CSS. Specifically, those limits are:
You can send output to a particular grid cell without having to use winset() first to change the current-cell. Instead of just using the grid's ID in output(), use "[id]:[column],[row]" instead. Or if the grid is using is-list, "[id]:[item]" will do.
usr << output("This is cell 3,2", "mygrid:3,2")
Very important: If you send an atom to a grid like you would with a statpanel, keep that object in a list or make sure it actually exists somewhere in the world. Do not use a temporary object that will be deleted when the proc ends, or it can disappear/change in the grid when a new object is created. Statpanels don't have this problem because of the way they update, but it's a good idea even there not to use temporary atoms.
Any atom that you have made draggable can be dragged from wherever it appears: the map, the info control, or a grid. Those same controls are set up as drop zones by default, meaning you can drop the atom there and get MouseDrag() and MouseDrop() messages.
When drag or drop involves the map, src_location or over_location will be a turf, or null.
When drag or drop involves the info control, src_location or over_location will be the name of that statpanel.
When drag or drop involves the grid, src_location or over_location will be "[column],[row]", or just a blank "" string if no cell is involved. If the grid has is-list turned on, then "[item]" is the location instead.
Clicking or double-clicking an object will also send the same kind of information.
The new mouse commands are formatted like so:
(Note: In BYOND 3.5, MouseDown() and MouseUp() included icon_x and icon_y arguments. These now belong to params. Old game files will still run as expected, but if you recompile an old project that uses these, you will need to make changes.)
The params argument is a text string which can be decoded using params2list(). Mouse parameters may include:
Controls in a window or pane can be added or deleted at runtime. (Only controls you add at runtime can be deleted.) To create a control, you need to supply a parent parameter with the ID of the window or pane that will hold the control, and type which is one of the available control types.
var/list/params = new params["parent"] = "mywindow" params["type"] = "button" params["text"] = "New button" params["command"] = "say \"This is a new button.\"" params["pos"] = "10,10" params["size"] = "80x20" params["anchor1"] = "0,0" winset(usr, "newbutton", list2params(params))
The ID of this button will be newbutton, which in full form is mywindow.newbutton.
Note: At the present time, adding a control will not work through the .winset command that can be used in macros or menus, or typed in an input box. Only using the winset() proc inside the program's code will work.
Controls that were added this way can also be deleted again by setting their parent to a blank value.
All |
Anchors currently can't be changed at runtime. Changing is-default at runtime may cause unpredictable results. The is-transparent setting has very limited support. At present, only the label control supports this, and it will not repaint properly if placed on top of another control except for bar controls or another transparent label. If transparent-color is in use for the window housing this label and that color is the label's background (or foreground), ClearType font rendering in Windows will cause drawing artifacts. |
---|---|
Main |
The default window's title is not used; the current world.name value is used instead. can-close should be left on for the default window, even if you don't use a titlebar, to allow easy access to Options & Messages from the taskbar and allow the window to close. It will not make a close box appear if titlebar is false. Non-default values for transparent-color or alpha trigger drawing bugs when the map is drawn with hardware rendering turned on. Because this setting only works on one color and affects all controls, it may cause other unexpected display issues. Transparent or translucent windows over a map may cause flickering with hardware rendering on. If can-scroll is used in a pane, the size parameter refers to the full scrollable area, not the size seen on the screen. If a 2000x2000 pane is scrunched into a 400x400 space and can-scroll is set to both so vertical and horizontal scrollbars appear, size still reports 2000x2000. If a window does not set icon, the Dream Seeker icon is used by default. However if the default window has an icon set, that will be used as the default icon for all windows. |
Input |
Built-in verbs like .click, and local commands like .winset, are not accepted when typed in by the user. This kind of command can still be entered through the Client menu in the Options & Messages window. |
Output |
An overflow of 5% of max-lines is allowed, to reduce flicker. If a background image is used, it will not show up beneath any images that appear in your text output; instead, the background color will be shown there. |
Child |
background-color affects the splitter color only. top and bottom can substitute for left and right. |