| Type | Title | Author |
|---|---|---|
| Forum topic | WebEx Connect Integration Availability | kreester |
| Notebook entry | Day One Dream Factory | chuckbrady |
| Notebook entry | how to animate a sprite | butcher |
| Type | Title | Author |
|---|---|---|
| Forum topic | WebEx Connect Integration Availability | kreester |
| Notebook entry | Day One Dream Factory | chuckbrady |
| Notebook entry | how to animate a sprite | butcher |
Welcome to the DreamFactory Reference Manual. To get a broad overview of all of the main issues first take a look at the Getting Started Manual and the DreamFactory Tutorial in that order. This document provides reference materials for the following topics:
|
Throughout this document you will see sections labeled as an "Important Note" in bold type. Read these sections carefully, they identify important issues for the DreamFactory author.
DreamFactory Runtime is either an ActiveX Control or Netscape plug-in for the browser-based delivery of projects. DreamFactory Professional is a stand-alone application for running projects on the desktop. The browser-based version normally operates in a strict security sandbox; see the Security White Paper for more details. The stand-alone version usually has less restrictive security settings and is given wide access to the client computer. This means that local assets and network connections will be available for use. The stand-alone version also has System Menus at the top of the screen like other applications, and these are documented below. You have access to all of these menus in the browser-based version as well. They are hidden in a pop-up behind the small "Menu" symbol in the Message Box, Scripting Windows, and Debugger.
Important Note: On the Macintosh, menu keys are invoked by holding down the command key and typing a letter; for example, Command-X for Cut. On the Microsoft Windows platform, the control key is used, for example Control-X for Cut. The control key will also work for menus on the Macintosh in DreamFactory. The Windows world uses the alt key to automatically select menus; there is no alt key on Macintosh.
|
|
|
DreamFactory editing takes place against a single Background Desktop Window, and various nodes (even nodes that look like windows and menus) can be part of the DreamFactory Project. Floating on top of that, various System Windows can appear for editing these nodes. The System Windows can move outside of the Background Desktop, and they are not really "part" of your project but instead helper windows for editing. This is an extremely useful way to work on a project, but could be confusing if, for example, the project has a blinking insertion point in a rich text object and the Message Box also has a blinking insertion point. The reason for this is that the Project is a carefully controlled animation limited to the Background Desktop Window, and the System Windows are part of DreamFactory's editing infrastructure. Likewise, you might have a DreamFactory Palette over a DreamFactory Window, but these could both be under one of the System Windows. This is also true with interface style: DreamFactory nodes can be any style on any platform but the System Windows are true platform specific windows only there to help with editing.
Important Note: On the Macintosh, a right-click is accomplished by holding down the option key and using the mouse. In some other Macintosh programs this is done with a control-click, but there is a control key used in the Microsoft Windows world, so DreamFactory uses an option-click for a right-click on Macintosh. The control key is handled in a consistent manner on both platforms. You can use a multi-button mouse on OS X for right-clicking.
The following System Windows are discussed below: Script Editing Windows, The Message Box, The Debugger, and The Background Desktop. Each section is followed by useful keyboard and mouse shortcuts for that window.
The Script Editing Window is where DreamFactory scripts are edited; usually you can shift-click on a node and bring up this window. One easy way to identify everything in the window and on the screen is by scanning the mouse and watching the message bar at the top of the window. Holding down the control key will reveal even more information, including the names of DreamFactory nodes outside the window. Here's a nice trick: when you control-key-scan the mouse outside the window the long names of the nodes are displayed in the message bar. If you click on a long name in the message bar, the short name will be inserted at the current text selection. Shift-click to insert the long name if needed.
Important Note: When you script you may notice that the spelling of some items can change as you are typing. This is because DreamFactory watches what you type and tries to change each word to an existing variable name or handler name. Therefore you should declare variables and subroutines before referencing them. The variables should be at the top of the current code/endcode handler; the subroutine names can be anywhere in the current script or hierarchy below. Given these simple requirements, DreamFactory will automatically correct all spelling errors as you type. If this is annoying (perhaps you type more accurately than I do) turn off the Type Ahead option in the Edit menu.
Across the top of the window are icons for commonly used functions. The disk icon will save your changes. You can easily open many scripting windows, one for each node, as a result of searches or shift clicking on nodes. Scripts can be copied and pasted between windows. Try command-closing a window to save changes and/or close multiple open scripts. The next two icons are folders to get or put snippets of text to or from the window. If you select some text and save it, the text will go to a file. If nothing is selected the entire script is saved. If you have some text selected and you load some text, the selected text is replaced; otherwise the new text is inserted at the insertion point. The next four icons handle undo, cut, copy, and paste as usual. The spider calls the Debugger, discussed below. The mailbox brings up the Message Box, discussed below. The boot brings up the project script, and the question mark invokes the Help System. The scroll icon will flip the scripting language from VBScript to JavaScript to DFScript on the fly, even in the middle of editing a script.
The small "Menu" button to the right of the message bar will bring up the entire menu system. This is useful for browser installations where the menu bar may not be available. There is a similar button on the Message Box and Debugger System Windows.
At any time you can use the Find Dialog to look for text in a script, the current hierarchy, a branch of the project tree, or the entire project. The Find Dialog can be invoked by typing Control-F (Command-F on the Macintosh). The "This hierarchy down to the libraries" option limits the search to the current script, the parent of that script, and so on down the hierarchy to the desktop, root, and library scripts. This is very useful because the current script has access to all these handlers down the hierarchy which can be called as subroutines. The "This script and all connected children" option limits the search to the current script and all children of that script in the project tree branch. This is very useful because all of the children will have access to handlers in the current script, and because sometimes you need to limit your search to a certain branch of the project tree. The Find Dialog can also search the entire project, which will include the project script and all libraries.
Another useful feature is the Help System. Simply select a line of text in any script and hit Control-Slash (or Command-Slash on the Macintosh) and the Help System will come up with information about that line.
The Help System is also available from the Message Box, and can also be invoked from the scripting language with the DialogHelp(name $) command.
|
The Message Box is the place to try out commands and functions immediately. You can also type in partial expressions. The scripting language can use the messageboxdisplay() system command to print output into the message box. You can use the arrows on the right hand side of the box to review previous input and output.
One useful feature of the Message Box is to right click on a node and select the "Target" option from the pop-up menu. This uses the messageboxtargetset() command to send all handler calls from the Message Box to that node. In other words, if the target has a handler called "foobar(arg)" then you could type "foobar(3)" into the Message Box and that function will be called in the script. You can also see Regional variables and make use of the "me" reserved word. This is a useful way to test scripts and functionality in a specific node.
Scanning with the mouse with control-key down will display the names of all the nodes in the Message Box information bar. If you click on the information bar the node name will be inserted into the current input string.
|
DreamFactory has a simple, easy to use Debugger that is very useful for tracking the flow of messages, watching scripts execute, setting breakpoints on scripts and variables, and looking at the node tree. In general, whenever you wonder where a message is going or why something is happening, you should set a breakpoint on that script and follow execution with the Debugger.
In Scripting Windows, the dotted box at left is a place to set breakpoints. In the debugger you can also set breakpoints. When a breakpoint is encountered the Debugger window will appear. Follow script execution with the "Step" and "Step In" and "Step Out" buttons, click "Run" when you want to dismiss the Debugger and continue execution. There is also a debugger() system command which will always bring up the debugger; this is useful because breakpoints are lost when the project is closed to prevent deployed projects from breaking in to the debugger. Be aware that the debugger() command will have no effect and the Debugger cannot be used when the project is in runtime mode. The Debugger is also only able to view the nodes, scripts, and variables of the current project for project privacy.
The Debugger has the following buttons, see the illustration below. The buttons at left are for looking at the Locals, Regionals, and Globals in the projects. Locals are for the currently displayed handler; Regionals are for the currently displayed script. There is more information about the current node to the right of the buttons (partially hidden in our illustration).
DreamFactory can also set breakpoints on individual variables. Select "Global", "Local", or "Regional" from the window above and you will see a listing of those variables. Select one, and the following dialog will appear:
This dialog will let you set a breakpoint on a variable and break into the debugger at the appropriate time. All breakpoints are forgotten when the project is closed. This prevents them from inadvertently stopping execution in a deployed project.
The next three buttons are "Nodes", "Hier" and "Script." The "Nodes" button will show you an outline list of all nodes in the current project. Note that you can see even the Utility Palettes and Properties Dialogs in this list; the Project Manager artificially hides these nodes. By selecting a node you can look at the script. The "Hier" button shows you the current scripts hierarchy, from caller to target to the last library.
The last three buttons on the right are "Run", "Edit", and "Clear." The "Run" button has been discussed this continues execution and dismisses the debugger. The "Edit" button will edit the current script. If you change the current script the changes will only be applied once the current handler finishes. DreamFactory marks the script as changed but does not currently support editing the currently executing handler. The last button "Clear" clears all breakpoints.
|
The Background Desktop, discussed in the introduction to this section, is the large window behind all the other System Windows with a menu bar at the top. In the browser-based version, the Background Desktop is embedded in an HTML page or the entire browser window if you are using a full screen MIME type for DreamFactory. Everything in the Background Desktop is part of your DreamFactory Project.
|
DreamFactory implements a standard series of Floating Palettes and Dialog Boxes that help with project editing. These assets live on the Background Desktop and can be loaded or unloaded from any project. These assets are originally stored in the file "dialogs.dfac" in the "downloads" folder. By right clicking the desktop of your project, you will see options to remove the standard palettes and/or dialogs, and if they are not loaded, there is an option to load the dialogs or palettes. One strategy is to remove the editing tools when the project is ready for deployment; this saves about 200K in the download.
|
Important Note: All of the palette windows can be expanded to expose more controls and capabilities by clicking the zoom box in the title bar.
DreamFactory implements a large number of Property Dialogs for just about every type of plug-in. These dialogs, like the Utility Palettes, are also written in DreamFactory and can be modified if necessary. Most of the Property Dialogs have a proxy editing object that represents the node being edited. The proxy shows the changes that will occur if you select the OK button. In some cases the proxy is not an exact match for the object being edited but still is very helpful. Here is a list of the standard Properties Dialogs.
|
The Web Services Wizard and Document Exchange Wizard are of special interest,
because they provide powerful methods of connecting user interfaces to web services.
There is more information about these dialogs in the DreamFactory
Tutorial . The illustration below shows the XML Properties dialog.
The
has details about security on the server side and the DreamFactory sandbox. This section covers Project Level Security in more detail from a usability standpoint. First, the security controls can be opened by clicking the zoom box on the Utility Palette title bar, below. Every feature on this panel is scripted, the panel simply provides access to various system commands and functions.
First, the "No Script Errors" button gets and sets the error mode of the project, allowing or stopping script errors. Authors could also script:
errormodeset(false)
The command above will stop all scripting errors from being reported. The commands errorstatus() and erroraction() can be used to get information about scripting errors and take some kind of alternative action.
The "Locked Mode" checkbox invokes the projectlockedset() system command, saving all changes to the project and internally locking it so that changes to the file are stopped. It will still be possible for the current runtime setting of various buttons to change temporarily, but not for new objects to be created or deleted. Set this option before setting the "No Script Errors" or "Hide All Palettes" checkboxes.
The "Runtime Mode" checkbox will put the current project in runtime mode by using the scripting command projectruntimeset(). This prevents all script editing, project debugging, access to system menus and the Message Box. Use this setting for deployment where the end-user should not have access to these capabilities, or would be confused by them. If a project is in runtime mode all right-click pop-up menus are disabled, except a right-click on the desktop, which pops-up a menu to show the Utility Palette above. This can be used to get back in to a project, turn off runtime mode, etc. The "Privacy Mode" checkbox can put the project in privacy mode by using the scripting command projectprivacyset(). This means that if this project is opened by another project with projectopenfile(), or if another project calls projectviewset() bringing the current project to the foreground, then all handlers will exit at that point, preventing the calling project from having access to the private project's variables or node information. The "Hide All Palettes" checkbox makes sure that the utility palettes are not visible at runtime. This is useful for a deployed project where the end user will not be using the utility palettes.
The "Password Protection" group of radio buttons allows a system level password to be placed on the ability to open the project at all, go in our out of locked mode, go in our out of runtime mode, and go in or out of privacy mode. These security settings are arranged from high to low security, and correspond to the checkboxes at left. The security password will generate a low level password check when the scripting commands projectopenfile(), projectlockedset(), projectruntimeset() and projectprivacyset() are executed. You also need the password to change the security level. If you are at the "No Password" level of security (the lowest level where all projects start out) then you will be prompted for a password when you try to set a higher security level.
The "Security Policy" button invokes the Security Policy Dialog, which controls the DreamFactory virtual machine sandbox. This allows an IT professional to dictate security policy for the virtual machine, or for an individual user to control DreamFactory access to the client machine. There is much more information about this dialog in the
.
The FTP login name and URL are used by the "Upload Project" button. This button runs a simple script that will save and FTP the current project back to the originating host. In general, you can put a DreamFactory document (a file with the extension ".dfac") on a deployment server, and download it directly. However DreamFactory documents are designed to be zipped in the popular zip file format, which dramatically reduces their size. In fact zipfile() and unzipfile() are system commands. So the "Upload Project" button saves the current file, zips it, and uploads it to the given directory. This issue is discussed in greater detail below.
DreamFactory projects are easy to deploy from a web server. First, create
a new folder on your server. Next, copy your project file and an HTML page for
embedding to this destination. Lastly, navigate to the HTML page and the project
will play in the browser. Installing DreamFactory for your entire company can
be more difficult for a variety of reasons. The
product distribution contains everything you need to deploy DreamFactory
media in the enterprise environment. The Enterprise
Installation Guide provides information on MSI installers as well as documentation
about registry entry and file system changes that occur during installation.
The rest of this section presents a high-level overview of basic deployment
issues, the developer certificate, project compression, full-screen MIME types,
and sandbox security.
DreamFactory Software sells a developer certificate to identify the author of a
project to the end user. The certificate information is shown during project
download and when any security request is presented to the end user. The "certificate.dfdc"
file can be obtained from DreamFactory Sales and should be placed in your server
deployment folder. The sales department can be reached at:
You will need the URL to your deployment folder to generate the certificate.
The certificate is evaluated at the client, no code is executed at the server
level; every aspect of server deployment is completely passive. This guarantees
that DreamFactory can be successfully deployed on any server, regardless of
installed software.
DreamFactory projects should be compressed before they are placed in the deployment
folder. This makes the project file much smaller. DreamFactory projects are
designed to work with the popular zip file format as a transport vehicle to
and from the Internet. You can use the File Menu option "Zip Project File..."
to convert any DreamFactory project to a zipped file with the same name. The
File Menu option "Zip And Lock Project..." does the same thing, but locks the
project, which allows deployment as multiple instances. DreamFactory automatically
recognizes such files, then unzips and opens them like regular projects. You
can also use one of the many zip file compression utilities available for Windows
to do the same thing and automate project compression. On the Macintosh you
can use the Stuffit File Compression Utility from Aladdin Systems. DreamFactory
can also zip and unzip files from the scripting language.
Important Note: When zipping a DreamFactory project with some third party compression
utility be sure not to use folder paths, because when the project is unzipped the file will be hidden
inside a newly created folder. This is easy to avoid, just make sure the zip folder path is empty.
Open the project with your zip utility program and check the folder path to the file.
You can also set up your deployment folder for FTP access if you want to take
advantage of automatic uploading in the Project Security Control Panel. When
you click on the "upload" button on the Project Security panel, the script saves
the current project, zips up the file, and FTP's the file back to the desired
web server. You will need to type the correct URL and username into the appropriate
field on the project Security Panel. All of the FTP functionality is just a
script under the "upload" button: you can modify the way this works as much
as desired, the current functionality is provided for your convenience.
When you select the File Menu option to "Zip Project File..." you will be presented
with a dialog to create an HTML file with the proper syntax to embed the project.
You will need to fill in the name of your website, project width and height,
the deployment folder, and other information necessary to create the HTML file.
If you click the "skip" button you do not have to create the HTML
file, this is useful if you have one already. Place the HTML page in your server
deployment folder next to the project file.
The next section presents a brief discussion about running DreamFactory projects
as full-screen MIME types, embedded HTML controls, and full-screen embedded HTML
controls. Most of this information is generally applicable to other MIME types like Acrobat,
Flash, or Quicktime. There are many excellent references available on the Internet that cover
certail details in more depth. More information is also available from the manufacturer of your
web browser and server. The following sections present a brief overview of the basic information
necessary to deploy a MIME type and various issues of particular interest to DreamFactory projects.
To view a DreamFactory project as a full-screen MIME type, place the compressed
project file in the deployment folder, and construct a URL that directly references
the file by name with the ".dfac" file extension. The full-screen MIME type
will "take over" the entire browser screen and can be resized along with the
browser window. You will need to configure your server to associate the file
extension ".dfac" with the registered IANA MIME type "application/dreamfactory."
The file ".htaccess" included in the DreamFactory Enterprise product deployment
package will do this for Apache web servers, simply place the file in your deployment
folder.
Important Note: In order to deploy projects as full-screen MIME types,
the ActiveX control or browser plug-in must already be installed. There is no
way to automatically trigger the installation or update of the DreamFactory
Runtime control. If the control is not installed, your browser will display
a "red X" or "broken link" in place of the project. Also, some browsers experience
a delay when loading a full-screen MIME type project for the first time, perhaps
because of security checks. See the discussion below about embedded full-screen
HTML controls to avoid these problems.
DreamFactory projects can also run embedded in an HTML page, or in a browser frame as part of a portal, or even as multiple instances on a single web page. Internet Explorer is capable of automatically triggering the installation and update of the the DreamFactory Runtime control from an HTML web page, after which the desired project is run immediately. Netscape Navigator and Mozilla support the first-time installation of a plug-in from a web page, but do not support automatic updates for plug-ins. Internet Explorer for Macintosh also uses the Netscape plug-in format for embedded controls instead of ActiveX, and therefore does not support automatic updating either. DreamFactory Software provides installation programs for these situations, as well as for Internet Explorer ActiveX control installation, at these links:
Windows Internet Explorer ActiveX Control
Windows Firefox/Mozilla Plug-In
Macintosh Firefox/Mozilla Plug-In
The DreamFactory Enterprise project deployment package includes the file "demo.html"
as an example of how to embed DreamFactory in an HTML page. This file can also
be used by customers to install the control for the first time. The HTML example
below shows how to embed a DreamFactory project with a width of 640 and a height
of 480. Notice that the URL for the "bootfile.dfac" project needs to be edited
for your deployment server and folder name. Simply go to a web page with this
snippet of code and your project will be embedded there, DreamFactory will be
installed if necessary.
<object
classid="clsid:226906C8-B911-11D5-82A3-0000F81A655B"
codebase="http://www.dreamfactory.com/codebase/dfacactx.cab#Version=6,37,0,1"
id="dfacinst"
width=640
height=480>
<param
name="openfile"
value="http://www.mywebsite.com/installation/bootfile.dfac">
<embed
type="application/dreamfactory"
pluginspage="http://www.dreamfactory.com/codebase/winplug.exe"
width=640
height=480
openfile="http://www.mywebsite.com/installation/bootfile.dfac">
</embed>
</object>
The example above gives the DreamFactory project a width of 640 and a height
of 480, but embedded HTML projects can also be run full-screen. This deployment
option avoids the drawbacks of MIME type deployment discussed earlier. The DreamFactory
Enterprise project deployment package includes the file "full.html" as an example
of how to load a project just like an embedded control but then resize the project
to the full browser window. This is the preferred method of deploying full-screen
projects. Simply put the HTML file and the project in the deployment folder,
and point your browser to the HTML file to run the project. Using this method,
you can control the version number in the HTML file, and choose when and under
what circumstances to require upgrade for your customers to the latest version
of the DreamFactory Runtime control.
There is one last issue to discuss about deployment and security. The browser-based version of DreamFactory keeps downloaded files in a directory structure that mirrors the web server directory folders. For example, if you go to the URL:
http://www.dreamfactory.com/projects/bootfile.dfac
Then the "downloads" folder in the DreamFactory installation on the client machine will store the file in the following directory:
DreamFactory:downloads:dreamfactory.com:projects:bootfile.dfac
This is part of the "cookie" security system so that projects are kept in a private sandbox and unable to look into or access each other. However if there are multiple files in the same server directory, they will end up together in the same sandbox, and will be able to share resources or call each other. The only exception to this is if any of these projects have their project privacy attribute set, in which case it will be launch-able, close-able, etc. by a brother project, but not inspect-able. This ability to share or hide projects from each other is extremely useful and easy to take advantage of. If you have projects that you want to use together then store them in the same server folder, and they will end up in the same sandbox. For projects that desire privacy, put them in a separate folder and they will have their own sandbox.
There's another useful trick you should know about. Sometimes you want a set of shared projects or media files that various projects need access to, but you don't want the projects to have access to each other. This is also easy to set up. Simply put the shared assets immediately down-tree from the projects that use them. This is analogous to the way scripts work in the hierarchy at runtime.
The picture above shows a DreamFactory downloads folder set up for this situation. The "dreamfactory.com" website folder has the media asset "logo.bmp" and the project folder "private" and the project folder "shared" all at the root level. projects in the "private" and "shared" folders will have access to "logo.bmp", but they will not have access to each other, because they are in separate sandboxes.
To re-cap, there are two rules for project access. First, projects have access to everything in their own sandbox including sub-folders, media files, and other projects. Second, projects have access to anything at the root level of their parent's folder, and their grand-parents folder, and so on, stopping at the root of the "downloads" folder itself. You may, of course, limit all file access with the DreamFactory Security Policy dialog discussed in the
.
Whenever DreamFactory creates a new node the object is initialized with a "default script." The default scripts are stored in the scripts folder inside the DreamFactory folder. All of these scripts are pretty similar, and they are intended for easy modification depending on the purpose of the object. Sometimes an objects script will be screwed up and the author may want to start over again with the default script. This is easy to do, select the "Load Text From File" menu option, find the scripts folder, and select the script for the current object. Here is an example of a typical default script with each handler explained.
code mycontent(hor, ver) // add your content handler code here // the mouse was released at hor and ver endcode
The "mycontent" handler is called if the button is clicked. In the case of a radio button or check box, DreamFactory sets or clear the check and calls the handler. So you might want to check the current status of the button and take some appropriate action. This is easy to figure out but varies slightly node by node.
code mousedown(which, hor, ver) if hijackmousedown(me, which, hor, ver) exitcode endif hor = globaltolocalhor(me, hor) ver = globaltolocalver(me, ver) trackbutton(me, hor, ver) endcode
The "mousedown" message is sent directly from the project script to a node that has been clicked in. The "hijackmousedown" handler is part of Dreamfactory's Standard Library scripting software. This handler tests if this object is being shift-clicked, right-clicked, reshaped, or dragged. If so, "hijackmousedown" handles the event and exits. This handler tests the shift key so that a shift click will edit the node's script. In runtime mode scripts cannot be edited. The handler also tests if the right mouse button is being used, in which case a pop-up menu with additional editing commands is displayed. In runtime mode there is no right-click editing. If you remove the "hijackmousedown" handler you will not be able to edit the object easilly. Next, the global horizontal and vertical mouse positions (sent by the project script) are converted to local coordinates for this node. Lastly, the "trackbutton" handler calls a function in Dreamfactory's Standard Library that highlights the button as the mouse is tracked in and out. If released in an active button, the "mycontent" handler above is called in response to the mouse click.
code mousemove(which, hor, ver)
if hijackmousemove(me, which, hor, ver)
exitcode
endif
if not button.activeget(me)
cursorset("arrow")
exitcode
endif
if basictypebutton(me) = "button"
cursorset("touch")
exitcode
endif
cursorset("arrow")
endcode
The "mousemove" handler is called when the mouse has moved and is in this node. Normally you will need to set the cursor. The "hijackmousemove" handler tests if the mouse is over reshaping handles, in which case standard cursors are set and the handler exits. Next, if the button is inactive the arrow cursor is set. Lastly, the appropriate cursor for a button is called, either the "touch" finger cursor for a button or the arrow for everything else. All of this can be customized.
code mousedoubleclick(which, hor, ver) takeactionbutton(me, "Button Properties") endcode
And finally the "mousedoubleclick" handler is called when there are 2 quick clicks next to each other. This is always the second click after a standard mouse click has been handled. The "takeactionbutton" is the same handler that the "rightclickbutton" handler calls with the selected pop-up menu item. If you want to remove double-click behavior this can be removed or changed. For example, scrolling borders do not implement the propertied dialog here because of the tendency to click on scroll bars and trigger the editing dialog.
When you use the tool palette to create an XML window, two nodes are actually created: a parent Window along with an XML child node. Special handlers are added to the bottom of each default script. By learning what these handlers do, you can make any child node work correctly with scrollbars inside any parent window or border. Here are the handlers added to the bottom of the XML node:
code nodemove() fixmyparent(me, 4000, 0) endcode code nodechange() anyreset(me) endcode
When anything about the XML changes, such as new text for an element or attribute, the "nodechange" handler is called, and "anyreset" recalculates the boundary rectangle of the node. This in turn triggers the "nodemove" message, which calls the library handler "fixmyparent", which calculates the pagesize of the parent window based on the new size of the child.
The parent window is also given a nodemove handler, which is called when the window is resized, etc. The "fixmychild" handler calculates the new size of the child node based on the window:
code nodemove() fixmychild(me, 4000, 0) endcode
The 2 parameters to "fixmyparent" and "fixmychild" are for the horizontal and vertical scroll settings of the window or border. In this case, the XML node has a fixed horizontal size of 4000, and a vertical size determined by the native height of the XML node. A negative horizontal or vertical argument will set the childs width or height to be the same as the parent. See the following section on the Standard Libraries for more information.
DreamFactory sends most system event messages directly to the Project Script. This is a special script in every project that is NOT a part of the regular hierarchy. The most important messages sent to the project script are mouse and keyboard events and project idle. The goal of the project script is to parcel these messages out to the various nodes and is seldom necessary. The following section examines the standard project script handler by handler and is useful for an overall understanding of how DreamFactory works and for situations where something needs to be changed.
code projectidle() update() endcode
The "projectidle" handler calls the update system command, which is the heartbeat function for DreamFactory. The update function takes care of screen update and runs threads. Any tight animated loop (for example, tracking a button) should call the update function.
code projectclose() endcode code projectopen() local new global curfocus curfocus = "" framerateset(0) if nodecountnames(nodefirst()) <= 0 new = nodenew(nodefirst(), "desktop") nodevisibleset(new, true) desktop.fillpatternset(new, "black") desktop.fillforecolorset(new, "light gray") nodemessage(new, dialogload()) nodemessage(new, palletteload()) nodenameset(new, "mydesk") endif endcode
The "projectopen" and "projectclose" handler are called when the project starts
and stops. The "projectopen" handler will also do some special initializations
if the project is completely new, such as creating a desktop and copying all
of the standard editing Palettes and Dialogs into the new project.
code keydown(arg) // etc, etc endcode code keyrepeat(arg) // etc, etc endcode
The "keydown" and "keyrepeat" handler receive and parcel out physical key down messages for the system. Key repeat is sent when the key remains down after a certain delay. The parameter is the name of the key or the actual ASCII key itself. Key names are used for virtual keys like "F1", "Tab", "Backspace", "Enter", etc. These are sent on to the nodes. Here is a complete list of virtual key names for the Macintosh and Windows, If the key parameter is a single character in length that will be one of the ASCII codes. There are some additional Windows virtual keys that are rarely used, to test for them simply set a breakpoint at this handler and try the key.
|
The "keydata" handler is sent when unicode text content has been received
by the operating system. So unlike "keydown", which is a message about a physical
key event, "keydata" should be used for actual text input for the project.
Probably the most frequently used handlers are "mousedown" and "mousemove". These handlers receive and parcel out the mouse messages received from the project script.
code mousedown(which, hor, ver) // etc, etc endcode code mousemove(which, hor, ver) // etc, etc endcode
The "which" argument is "left", "center", or "right" depending on which button is down. Mousemove is sent when the cursor moves. The standard project script does not handle "mouseup" messages, but these are also sent by the project script. The Advanced Scripting Issues below covers all of the various system messages available.
DreamFactory supplies 6 standard library files. These files sit at the bottom
of the scripted message hierarchy and are available to all scripts. Authors
can add their own libraries above the standard ones, see system commands beginning
with the "library" key word. These author-defined libraries should be above
the DreamFactory libraries in the hierarchy. Also be careful of nodes that call
any author-defined libraries, if these objects are copied to a new project the
libraries will not be available unless specifically copied and migrated along
with the object. The following section discusses the content and handlers of
the 6 standard libraries. To view (for example) Library1, type this in the
message box:
LibraryScriptEdit(1)
This command opens Library1 in a script editing window. The standard libraries are also visible in the Project Manager and can be opened from there as well. Of course you could change the standard libraries, but this is not really recommended. A better option is to use the Root Script or a user-defined library script to implement your own globally available handlers. Any handler above a given library script in the hierarchy will of course intercept messages for lower handlers with the same name.
Important Note: Sometimes the Library files are updated with a new version of DreamFactory. If so, you may right click on the desktop and there will be a menu option "Update Library Script" or "Update Project Script" available. If you select this option DreamFactory will copy the newest Library Script and/or Project Script out of the Scripts folder. These options can also appear if you have customized your Project or Library Script, because they appear different than the originals. The Utility Palette has an "Update Libraries" option on the right of the tool bar which will automatically update all library scripts and tool palettes.
Library1 sits at the very bottom of the hierarchy and contains subroutines
of general use. The first set of functions begins with the key word "any". For
example:
anyboundset(who, newbounds)
This handler will set the boundary rectangle of any plug-in object that supports
the "boundsset" method, as in window.boundsset("fred", "100, 100, 200, 300")
The "any" routines handle the gray area between the system "node" functions
that work with all objects (like nodevisibleset()) and the more specific plug-in
function that handle very specific functionality. The "any" functions do nothing
in cases where the given plug-in does not support the command. This makes it
easy to apply certain operations to all nodes types. The categories covered
by the "any" functions are:
|
The next set of routines in Library1 are simple rectangle handlers for dealing
with rectangles. In DreamFactory, rectangles are simple text lists of four numbers,
such as "121, 35, 428, 512". Here are the rectangle handlers:
|
All of these functions return the new rectangle. The next set of functions drag or resize a set of nodes with their handles turned on. The dragbrothers() handler will drag all objects currently with handles, and (especially useful) dragany() will drag any object, with or without handles. For example:
code mycontent(hor, ver) dragany(me, hor, ver) endcode
Is a simple way to make any object drag-able, simply add this to the default handler at the top of the script. The next function is also very useful: centerwindow() will bring a node to the center of the node's parent, such as a window on the desktop.
The next set of functions in Library1 are for compatibility with VBScript.
These are all the popular string handling functions. They also are a good tutorial
on DreamFactory string handling. Here are the functions implemented:
|
Library2 implements all of the right-click handlers. Each plug-in has a "rightclick" handler, and a "takeaction" handler. For example, the rightclickborder() is called to present the right click menu on a border, and takeactionborder() implements those various commands and can be called separately as desired. For example, some mousedoubleclick() handlers will call the "takeaction" functions directly top bring up the property dialogs.
Library3 supports object creation in conjunction with the Tools Palette. At the top of the file are the hijackmousedown() and hijackmousemove() which are called by all of the Default Scripts. There are some utilities at the end of Library3 for drawing gray rectangles and gray polygons for object creation tools. Each of the plug-ins has a creation function like newborder(), newlist(), etc. Some of the default scripts are customized for certain objects as they are created.
Library4 implements a number of plug-in utilities to support the mousedown() message and other plug-in specific functions. Each of the plug-ins has a section of function calls specific to that type of object. For example, the standard button script calls trackbutton() to handle mouse interaction. If the mouse is released in the button, the trackbutton() handler calls the mycontent() handler in the default button script, that is where you usually would take the appropriate action for the button click. Search for trackbutton() with the Find Dialog, use the "This Hierarchy" option, and you will find the trackbutton() handler in Library4. Find there the setradiobuttons() handler which sets a single radio button to checked and clears all brother radio buttons.
Important Note: There are cases where you might wish to customize the mouse down or tracking behavior of a plug-in. This is easily accomplished. Find the tracking function that you wish to modify (a good way to do this is with the Find Dialog, look in the current hierarchy for the handler you wish to modify, you will probably find it in Library4). Next copy the handler and paste it back into your node script. Now the node will find that handler locally first, where it can be safely modified. Modifying the Libraries themselves should only be done in rare circumstances, because if an object is pasted into another project or the Libraries are updated the changes will be lost. A better approach is to use the Desktop or Root Script of your project to add new routines that supercede the library function.
The functions in Library5 are for opening WSDL's and generating SOAP. Given a WSDL, these routines will return a list of function names, and given a WSDL and a function name, these routines will return the input or output arguments. Here are the functions implemented:
|
The functions in Library6 are for automatically generating user interfaces given a WSDL, port, and function. These are the routines used by the Document Exchange Wizard.
In general, you should use the online help system to find out about additional functionality. This is easy: if you are interested in a special type of node, look down the list of plug-in types and find a node that can implement your feature. Read the various node capabilities, create one of those nodes, and try some things out with the message box. If the capability is a System Command or function, read through the grouped explanations of the System Functions. Much of the information below is just more detail on the groups of functions documented in the Help System.
Many system and most plug-in commands and functions can also be used as methods and properties. A method can be used when the first argument is a node name. A property can be used when there is a matched pair of "get" and "set" commands and functions that return and take a single value. The examples below show how regular system and plug-in commands and functions can also be used as methods and properties:
nodevisibleset(me, myvar) // regular old system myvar = nodevisibleget(me) // command and function me.nodevisibleset(myvar) // same system routines myvar = me.nodevisibleget() // used as methods me.nodevisible = myvar // matched get and set myvar = me.nodevisible // used as properties styleset(me, myvar) // loosely bound plug-in myvar = styleget(me) // command and function me.styleset(myvar) // loosely bound plug-in myvar = me.styleget() // used as methods me.style = myvar // loosely bound plug-in myvar = me.style // used as properties draw.styleset(me, myvar) // tightly bound plug-in myvar = draw.styleget(me) // command and function me.draw.styleset(myvar) // tightly bound plug-in myvar = me.draw.styleget() // used as methods me.draw.style = myvar // tightly bound plug-in myvar = me.draw.style // used as properties
The plug-in methods and properties optionally take an explicit plug-in name, which tightly pre-binds the scripting language to the desired plug-in for speed. This also has the advantage of providing syntax hiliting and type-ahead name prompting. In this case the declared plug-in must agree with the actual target node, or a scripting error will be generated.
In the case of loosely bound plug-in properties, DreamFactory will dynamically figure out which plug-in to use. This is useful in cases where you would like to generically set a common plug-in property for any given node; for example, the boundsget/boundsset property pair. Be aware that some plug-ins might not implement a specific property. In this particular case you cannot set the bounds of the desktop node, and the call would generate a scripting error.
If a method is used, the node's script is checked for the handler first, and then the message is sent along to the plug-in. Here is an example:
mynodename.styleset("oval")
mynodename.myfunction(34, "fred")
In the first case, DreamFactory will check the "mynodename" script for the styleset() handler, and if this does not exists, will try the plug-in command by the same name. In the second case, DreamFactory will just send the message myfunction() to "mynodename" with the requisite arguments; there is no plug-in function named myfunction(). This is very useful for overriding plug-in commands and functions with handlers in the node script, and for addressing handlers as node methods. This searching behavior can be avoided by tightly binding the plug-in name to the method call.
In all properties and method calls the first argument specifies the object to receive the message. The argument can be a raw node name or a variable containing a partial or full path name to a node. The reserved words "me", "target", "hit" and "this" are also valid first arguments. The "hit" reserved word is intended for use in the message box: simply point the mouse to the desired node and get or set various properties.
DreamFactory properties are especially powerful, and can be seamlessly combined with variables. Properties end up being a chain of values that can get or set plug-in attributes in very complex, single line expressions. Every node also implements the "info" and "full" properties. These routines get or set a complete XML description of every node attribute. The fullget and fullset routines have a header element with appropriate namespaces, infoget and infoset are an XML snippet for access as a property. Here are some examples:
hit.value ++ // point to a slider myvar.property.value ++ // slider value set mybutton.bounds.width = 60 // button width set myxml.data.envelope.body.result ++ // tweak XML data mylist.info.items[3].itemname = "fred" // set a list item title
The Help System is very useful in discovering the appropriate methods and properties available for a given command or function. The bottom two lines of the screen show the equivalent methods and properties for the given routine. The information bar also lists information about available properties and methods in context. If in doubt include the desired plug-in name and this lets DreamFactory know to provide all available information and tightly bind to the specified plug-in.
DreamFactory implements a number of built-in properties that can be used for the basic types: rectangle, point, color, and string. These are normally used as extensions to node properties or variables. Note that these built-in properties are NOT implemented as XML (like other properties) because of speed considerations and the difficulty in reading XML data for these very simple types. Here are the built-in properties:
|
DreamFactory implements associative arrays using syntax consistent with VBScript and JavaScript. These languages allow you to create complex data structures and arrays that store structured information. Here is an example:
var mycar mycar.make = "Ford" mycar.year = 1998 mycar.owner[1] = "Bob" mycar.owner[2] = "Jim"
In this case above the variable "mycar" is just:
<make>Ford</make> <year>1998</year> <owner> <item_1>Bob</item_1> <item_2>Jim</item_2> </owner>
Next we cover some helpful details about arrays and structures. First, you can reference any element with array notation. So in the case above:
mycar[2] = 1998
Next, the length property is implemented in all cases and at all levels. So you can get or set the number of elements in an array or members in a structure. Arrays in JavaScript are sparse, so you can arbitrarily create elements or set the length to manage your arrays. If you reference an element or array member that does not exists, the empty string is returned, just like JavaScript.
Next, all attributes and namespaces are preserved in XML native structures and arrays. This is so that you can take raw XML and use it immediately as a variable. There is currently no way however to create new attributes in variables, use the XML DOM node for advanced XML manipulation or visual display.
Next, you can access any element dynamically with brackets. This is also useful in the extremely rare case where you have a plug-in name or method that collides with a field in a variable: arguments in brackets are always a simple name and will never bind to a system or plug-in method or property. These expressions are equivalent:
myvar["field" @ 3] myvar.field3
Next, DreamFactory implements a double-dot to search for the next matching element in a structure. The double-dot can be used at any position in a property string, and finds the next matching element from that point. This is a useful short cut for finding elements in complex XML data.
xmlnode.data..result = "BEA"
Lastly, use the "dumplocal", "dumpregional", and "dumpglobal" reserved words to delete elements in variables, or the entire variables themselves. These reserved words do NOT work with properties in other nodes or the XML DOM, just variables.
DreamFactory implements objects in variables like JavaScript. Our implementation covers usage of the "this" and "new" key words with methods and properties, but does not extend all the way to object prototypes, because DreamFactory already has a very complete object-oriented programming environment with nodes, plug-ins, and scripts. But inside a given script, the JavaScript implementation for objects is still a useful programming device for advanced scripters who may need to port routines from other JavaScript implementations:
function areafx() {
return this.w * this.h
}
function rectangle(w, h) {
this.w = w
this.h = h
this.area = "areafx"
}
var myrect = new Rectangle(3, 4)
var myvar = myrect.area()
This example uses the "new" keyword to declare a constructor function, and the "this" keyword to refer to the calling object. After execution "myvar" will equal 12, and the object "myrect" will contain the properties and methods:
<w>3</w> <h>4</h> <area>areafx</area>
The "myrect" object variable used in this example could be replaced with the XML, list, or text node. For example, given the constructor and method above, you could write:
myxml.data = new Rectangle(3, 4) var myvar = myxml.data.area()
This allows you to build persistent and human editable objects out of pure XML and watch them execute. Objects or even structures or arrays can be created and maintained inside text edit records or scrolling lists.
The update functions show any changes to the screen and run all threads. The projectidle() handler in the project script is called continuously, and that must call update() for DreamFactory to have a heartbeat. In other animated loops, for example dragging an object, you must move the object, highlight the button, etc. and call update(), The updatefx() function is similar, except that you can specify a node to update an effect name and a millisecond delay. The effects available are listed below:
|
DreamFactory sends system Messages automatically to certain nodes or scripts. Most of the messages are targeted at the Project Script discussed above. Nodeopen(), nodeclose(), nodeshow(), and nodehide() are especially important. These handlers are the main place to initialize and shut down various activities on a node-by-node basis. The two messages webtransferdone() and servertransaction() are special notifiers about Internet events. Here is a list of all system messages:
|
DreamFactory sends the nodeopen/nodeclose messages to a node when it is created or when the project opens. The nodeshow/nodehide messages are sent when the nodevisibleset system command is used, after a paste, etc. The plug-in messages between nodestart and nodestop are sent under varying circumstances, check the Help System for more information.
Some system messages are only sent if there is a corresponding handler to
receive that message. The reason for this is to prevent "message storms"
of common messages that are not being used. This can cause problems if the node's
father is expecting to receive and handle the message. In this case you need
a stub for the message in the target node that has a passcode statement to send
the message along to the father. This lets DreamFactory know to send the message
to the target, but also lets the father handle the message. Here are the system
messages that are only sent if there is a corresponding handler in the target:
|
Lastly, be careful about calling system messages recursively. For example, if on nodehide() you try to hide the current node, this will trigger recursive messages, and cause a scripting error for too much recursion. Another example is calling a plug-in reset() during the nodemove() message. Reset will trigger another nodemove(), and so on. If you must do this, the system command broadcastset() can turn on or off automatically generated system messages, allowing you to call these routines without recursion. Be sure to turn them back on before your handler exits, or other nodes that expect system messages will be stranded.
DreamFactory has a relatively simple but powerful thread mechanism for any node to receive a slice of time right before update. The threadstart() function lets you specify a node to receive the time, the number of frames or milliseconds before the thread is started, and the function and arguments to send to the thread. The function can have any multiple arguments, but these are calculated when threadstart() is run. The thread function generally will call ThreadStart again to continue operation. Threads are NOT saved and restored with Projects, usually they are started up on nodeopen() or nodeshow(). There are a full compliment of functions to test, pause, start, and stop threads. Because threads run right before update(), the thread function itself should not call update(), or things can get confusing.
|
DreamFactory has some simple and powerful Internet access functions. First,
for small transactions, webdownloadimmediate() and webuploadimmediate() will
read or write directly to or from a variable, skipping any type of file transfer.
For longer transactions, or if you want to implement multiple simultaneous transactions,
webuploadstart() and webdownloadstart() will start data from a file uploading
or downloading. You can check on the status of the file with the webtransferstatus()
function, or abort the file transfer with the webtransferabort() command. When
the transfer is finished, you will be sent the webtransferdone() system messaged,
at which point you can take additional actions. Once started, an FTP file upload
cannot be aborted, and will even "hang" the browser momentarily to finish. This
avoids partially uploaded files on an FTP server.
|
DreamFactory has a nifty micro-server available in the stand-alone application mode. The micro-server can be started or stopped at any time and receives incoming HTTP messages on the designated port. The server handler should investigate the header and decide what to do. An entire web server can be written in a line or two. This is especially helpful for web services callbacks from a server.
|
DreamFactory has powerful functions to manipulate strings. Often strings are a series of words separated by commas or some other delimiter, as in "fred,bob,jane,tim." DreamFactory also supports the concept of an "empty" delimiter, which views the string on a character-by-character basis. So our first two string functions stringlistget() and stringlistset() either retrieve a string from a delimited list or adds a string to a delimited list. The next two functions stringitemget() and stringitemset() either return the number of items in a string or sets the number of items. In every case, if the delimiter is "empty" (there is an "empty" reserved word for your convenience) then the strings are handled on a per-character basis. Lastly the stringchartoascii() and stringasciitochar() system commands can change strings back and forth to their ascii equivalents, this will be Unicode values in the final version of DreamFactory. Check out the VBScript string library at the end of Library Script #1, they are useful in themselves and examples of how to build new string functions.
|
Strings can also be manipulated directly on a character-by-character basis using brackets to index into the string. The "length" property is also implemented. If you set the length of a string longer than the current length, spaces are appended to the string. Here is an example:
var mystring = "abcdef" for count = 1 to mystring.length var onechar = mystring[count] next
DreamFactory normally runs with traditional system software supporting the
graphics displayed on the screen. For example, on Windows GDI will draw in the
browser-based or stand-alone version, and on the Macintosh Quickdraw will update
the screen. However, we also support buffer modes, where the video display hardware
can be accessed for extra performance. This allows the Project to specify the
exact number of pixels on the screen and take over the entire monitor. Single
buffer mode maintains an offscreen buffer on the display card that is rapidly
blitted to the main display. In double buffer mode, there are 2 buffers maintained
on the video card, and DreamFactory draws on one and then flips to the other
for flicker free performance. On Windows this is accomplished with the DirectX
graphics hardware drivers, on Macintosh single buffer is emulated with direct-to-screen
software, double buffer will fail. After going in to either single or double
buffer mode, always test with bufferstate() to see if the call was successful;
for example, double buffer is more likely to fail than single buffer because
of limited RAM on the display card. Also, either buffer mode may not work for
certain unusual display sizes: 640 X 480, or 1024 X 768, etc. almost always
work.
|
The
Manual provides a detailed picture of the message hierarchy. Messages are usually sent to the Project Script, which parcels them out to the appropriate leaf node of the Project hierarchy. The messages are either then handled or passed on down the tree to the desktop, root, and then various library scripts.
There is, however, another mechanism for sending messages directly to any node or scripts anywhere in the hierarchy. The most common mechanism is nodemessage() or nodemessagefx() as follows in these examples:
nodemessage("anynode", somecommand(arg1, arg2))
myvar = nodemessagefx("anynode", somefunction(arg1, arg2))
When the receiving node gets the message, it will follow down the message hierarchy until handled, at which point it will return to the calling hierarchy, and continue down that hierarchy as normal. Calls to projectmessage() do not take extra arguments (there is only one project) and calls to librarymessage() only need a library number to specify th target. Speaking of which, the reserved words me and target always tell the current script's node, and the original target \of the message.
|
DreamFactory automatically finds the closest node to the referring node. This
allows entire trees of nodes to be copied from project to project and still
stay linked. The Getting Started Manual has lots
of information about full and partial node names. But there is one case where
loose binding can have unexpected consequences. If you pass a node name down
to a function in a library or across to some other node, then the name will
be evaluated in the new context where it is used. Here is an example: if you
pass the node name "fred" to a script somewhere else in the tree, then that
node will find the "fred" closest to itself, not the "fred" closest to the original
caller. The simple answer to this is to use the "me" reserved word, which is
always a fully specified path. Another answer is to use the system function
nodelongname("fred") which will find the local "fred" and convert the name to
a fully specified path which can be sent anywhere.
DreamFactory provides some very powerful methods of dealing with errors. First, errormodeset() can turn error handling on or off entirely. This is useful when (1) you want to hide an inadvertent error from the user or (2) you know that a function might fail, and you want to handle the error yourself. Erroraction() can take a variety of actions to handle and / or clear an error. Errorstatus() will tell you if there is a pending error. Here is a simple example of using these functions:
code safewebdownload(urlname) local saverr, newtext newtext = "" saverr = errormodeget() errormodeset(false) newtext = webdownloadimmediate(urlname, "", "") errormodeset(saverr) return newtext endcode
This function (located in Library1) will quickly download data from a URL but simply return nothing (the empty string) if the server is down or the file is not available.
|
DreamFactory provides a full set of easy to use modal platform-specific dialogs. The purpose of these dialogs is a "quick and dirty" way to get information from the user or supply a message. The appearance of these dialogs will vary by platform, of course you can use DreamFactory nodes to construct very detailed dialogs that will be identical on every platform and offer great control over the user interface.
|
An important consideration when rendering densely packed user-interface controls
is the characteristics of the text font: name, size, ascent, style, leading,
and width. This must be absolutely consistent no matter where the document is
displayed, or small changes in, say the width of a string can lead to big changes
in screen layout. A related issue is that system font display software varies
widely in capability and speed. In order to accomplish this, DreamFactory captures
and compresses system fonts into a native format that can be incorporated into
your project file. The standard Font Dialog will show all of the"DreamFactory
Fonts" that have been captured by the current project, and provides a button
to incorporate new system fonts available locally. Both black and white and
8-bit grayscale fonts are supported, the grayscale fonts will be somewhat larger
in size, but are better in appearance.
|
DreamFactory documents are hierarchical. The underlying metaphor is XML: each node is like an element, and the properties of the node are like attributes. Indeed DreamFactory can serialize and un-serialize the node hierarchy into XML quite easily. There are nice sets of node functions that operate almost like a DOM on the DreamFactory project file itself.
|
DreamFactory memory management maintains heaps for fonts, sounds, variables,
scripts, and node data. These heaps provide automatic feedback and / or object
cleanup when their memory runs low. The sound heap will refuse to play new sounds
when full. The font heap and script heap automatically purge old objects. The
node heap caches changed objects and can be contracted when more memory is needed.
The variable heap can actually run out of memory and generate a scripting error,
this protects against runaway variable allocation.
All of this is handled automatically; in general the project does not need
to worry about memory management. Some projects may wish to violate heap limits,
and can use the memcheckset() system command to remove memory limits on variables
or sound allocations. This will not work on some fixed memory platforms, like
Macintosh System 9. Use this option with caution; you could potentially crash
the virtual machine with runaway memory usage. The memory commands below provide
feedback on system, memory conditions.
|
These reserved words all return information relative to the currently executing script. The "me" word always returns the fully specified path name to the node whose script is currently executing. The "target" reserved word always returns the path to the original target of the message that caused the current script to execute. So for example, if the Project Script sends "mousedown" to a node that passes that message on down to a window, then at that moment in the window's script "me" will be the window name and "target" will be the name of the button.
The "myid" reserved word returns the permanent ID number for the current script. The "myproject" reserved word returns the full path name to the project of the current script. The "myprojectid" reserved word returns a unique ID number for the project that is re-assigned anytime the project closes and re-opens.
One final issue: both "me" and "target" and "myid" might not represent currently available nodes or even nodes that currently exists. A node can delete itself, delete its father, or even delete it's own project and continue running happily until the script execution stops at which point it is gone. So if there is any question about this unusual situation use nodeexists() or something to be sure. Lastly, "myproject" is slightly different in that it returns the name of the current project but if this file has been closed, closed and re-opened, or deleted "myproject" returns an empty string.
DreamFactory supports the concept of a currently viewed project. This is just the project in the view menu at the moment and can be found with the projectviewget() system function. The current project can also be set, which flips the currently viewed project to another one. All of the current projects that are opened can be viewed an examined.
Projects can work together, in that one project can set another to be currently viewed. At that moment, all global variables and node tree queries relate to the new current project. The reserved word "myproject" always returns the path to the project for the current script. This is incredibly useful, because you can open multiple projects, or they can open each other, and copy and paste nodes between projects.
There is an important limitation to this. If a project is marked as private with projectprivateset() then any attempt to switch to that project by another project will result in an immediate exit of all running handlers to maintain project privacy. In other words, a foreign project cannot examine anything about a protected project but can at least make it the currently viewed project.
Draw bitmaps are highly compressed 8-bit color images that are automatically created with an optimized palette. This is equivalent to GIF images on the web, but much, much faster to display. Draw bitmaps take a moment to compress, and are mainly useful as user interface graphics. They can be masked, scaled and rotated, see: draw.bitsmaskset() and draw.rotateset() for the details.
Pictures are based on the JPEG data format and are mainly good for photographic images that require 32-bit color. Pictures can be scaled and rotated but cannot be masked. Pictures are memory and processor intensive to display. The picturelockedset() command can be used to lock the picture bitmap in memory, which really speeds up display, but be aware that any off-screen 32-bit color image can take up quite a large amount of memory. The width times the height times four will produce the size of the off-screen image.
Sprites are 8-bit color images that are automatically created with an optimized
palette. Multiple images can be included in a single sprite for automatic or
scripted animation. The sprites are arranged in a row-and-column pattern that
is very useful for complex animation control and buttons. Sprites can be scaled
and masked but cannot be rotated. Use draw bitmaps for things that need to be
rotated, sprites are designed for scaling and display speed. Sprites also have
special inks that control their transparency.
Icons are true 32-bit color fields with full alpha channel transparency. They
can be any size, but large ones can take up substantial memory. There is a separate
plugin for Icons that implements many different features, the Help System has
more information. The binary icon data format can be transferred between windows,
lists, buttons, and menus.
Here is a complete listing of all DreamFactory error messages.
|