Read Me for the "DropList.dcr" linked movie member __________________________________________________ Contents: 1: Overview 2: Behavior parameters 3: Advanced interactions 4: Changing the appearance of the dropdown list OVERVIEW -------- "DropList.dcr" and the demonstration movie "HostMovie.dir" are provided free of charge as an example of how a Linked Director Movie (LDM) can be used to provide complex interactions within a single sprite. You can import the "DropList.dcr" into your own movies. This will create a #movie member in your castLib. When you drop the member onto the Stage, it will appear as an open dropdown list with the dimensions 320x240 pixels. You can alter the width and height of the sprite to your own convenience. When the movie is run, the width of the sprite will remain as you set it, but the height will be set automatically so as to display a closed list. The linked movie sprite will not function unless you drop the "Linked Movie Behavior" onto it. You can find this behavior in "HostMovie.dir". Certain properties of the #movie member need to be set for it to appear correctly: the #crop and the #scriptsEnabled properties must be set to TRUE. When you drop the "Linked Movie Behavior" on the sprite, you will be given a chance to set these properties automatically. You can customize the dropdown list in a number of ways. You can define its contents either once and for all or dynamically; you can determine what happens when the user selects an item; you can modify certain aspects of the sprite's appearance; and you can enable or disable an auto-typing feature. The parameters are described in more detail below. The "Advanced interactions" section explains how to modify the settings on the fly. Note that the Behavior Parameters dialog that allows you to customize the sprite is generated by the "DropList.dcr" itself: the "Linked Movie Behavior" contains a generic "on getPropertyDescriptionList()" handler which simply asks the linked movie for information. Other linked movies could use the same behavior to create a completely different set of parameters. Developers who are looking for a way to make their work available to the Director community without revealing their source code may wish to build Linked Director Movies using the same model. For further details, please contact James Newton at ===================================================================================== BEHAVIOR PARAMETERS ------------------- List items are defined by: * a handler in a Movie Script * a handler in a behavior on the same sprite -- Default if no text or field members * a handler in an instance on the actorList * {list of text or field members} -- Default if present The list items can be either a RETURN-delimited string, with a separate item on each line, or a list of items. Examples: "item 1"&RETURN&"item 2"&RETURN&"item 3" item 1 item 2 item 3 ["item 1", "item 2", "item 3"] [1: "item 1", 2: "item 2", 3: "item 3"] If a list is used, items which are not strings will be coerced to strings. If a property list is used, properties will be ignored, except in the following cases: [#items: ["item 1", "item 2", "item 3"], #selection: 3] [#items: ["item 1", "item 2", "item 3"], #selection: "item 3"] [#items: [1: "item 1", 2: "item 2", 3: "item 3"], #selection: 3] [#items: [1: "item 1", 2: "item 2", 3: "item 3"], #selection: "item 3"] [#items: "item 1"&RETURN&"item 2"&RETURN&"item 3", #selection: 3] [#items: "item 1"&RETURN&"item 2"&RETURN&"item 3", #selection: "item 3"] If this format is used, the default item will be selected automatically. Note that both #items and #selection properties must be present for this format to have an effect. #items can be a string, a list or a propList. #selection can be an integer or one of the string items present in #items. If the value for #selection is less than 1, greater than the number of items in the #items list, or if it does not correspond to one of the items in the #items list, then no automatic selection will be made. Note also that you can store a list in a text or field member. If the list items are provided in the form... member("List Items").text = string(["item 1", "item 2", "item 3"]) SELECTION IN BEHAVIOR PARAMETERS DIALOG = member(x, y): "List Items" ... the dropdown list Linked Movie will convert this back to a list via listItems = listItems.text listItems = value(listItems) If the value provided for the list items is void, or cannot be converted to a list or a string, then the default value of "< No items available >" will be used instead. _________________________________ Handler to call (unless a field is selected above): (default: #getListItems) If you choose a field or text member as the first parameter then this information is ignored. If you choose one of the first three options for the first parameter ("a handler in a Movie Script", "a handler in a behavior on the same sprite" or "a handler in an instance on the actorList") then this entry will determine which handler to call in the chosen location. Example: on getListItems(me) return ["item 1", "item 2", "item 3"] end _________________________________ Reset list items every time the list is opened (time-consuming): * TRUE or FALSE (default: FALSE) If the contents of your dropdown list may change according to the user's actions, you may wish to reset the list each time the list is opened. However, if there are many items, this process can cause a noticeable delay before the list opens. If you are using a long, dynamically-determined list, then you might prefer to use the linkedMovie(#setSelection, ...) command detailed below. _________________________________ When an item is selected, call the handler... (default: #itemSelected) When the user selects an item in your dropdown list, you probably wish to perform some sort of action. You can do this by setting a handler to call, and by telling the Linked Movie where this handler appears (see below). _________________________________ ... which appears in: * a Movie Script -- Default * a behavior on the same sprite * behaviors on other sprites * an instance on the actorList * the Member Script of Here you tell the Linked Movie where to find the handler defined above. Certain options are not available: for example, you cannot directly define a global object instance. If you need to do this, use a handler in a behavior or a Movie Script to redirect the call. The handler will receive the following parameters: on #itemSelected(me, itemText, itemNumber) Note that even a handler in a Movie Script will receive the parameter: this will contain the name of the handler called (e.g. #itemSelected), rather than the reference to an object instance. If the chosen handler does not in fact appear in the chosen location, no error will occur. The display of the closed dropdown list will change, but no action will be executed. _________________________________ Show custom cursor over the menu button and open list? * TRUE or FALSE (default: TRUE) Generally, the cursor does not change when the mouse rolls over a dropdown list button in a Window application. The DropList.dcr uses a Finger cursor by default to indicate when a mouse click will have an effect on the dropdown list. _________________________________ Field sprite for auto-typing (list will be sorted if this is enabled): * < Disable auto-typing feature > -- Default * {list of field members in the current frame } An auto-typing feature is available if you have at least one field member on the Stage in the same frame. If the mouse passes over the selected text display, the cursor will change to a I-bar insertion cursor. A click on the selected text display will open the dropdown list and select the text. The user can now type the first few letters of an item in the list to scroll to the appropriate item, then press RETURN, ENTER or TAB to select that item. The auto-scrolling feature requires that the items appear in alphabetical order. If auto-typing is activated, the order of the items in the dropdown list may be different from the order provided by the list items field or handler. The user can also use the BACKSPACE and Delete keys to cut text. However, if the text displayed in the selection field does not correspond to an item in the dropdown list, RETURN, ENTER and TAB will have no effect, and a click outside the dropdown list will revert to the previously selected item. Do not try to use the chosen field member to display any other text: the dropdown list will modify its contents, then place it off-stage. _________________________________ Text to show when dropdown list is closed (blank = first item): (default: "Select item...") When the dropdown list is closed, you can display a prompt string. This prompt string may be replaced by the user's selection if you choose to "Replace the current text with the new selection" (see below). If you leave this entry blank, the first item in the list will be displayed, even if it has not been selected. In order to force the selection of the first (or any other) item, use the [#items: , #selection: ] format for defining the list items (see "List items are defined by:" above). If you want to display a blank entry, use a space (" "). _________________________________ Replace the current text with the new selection: * TRUE or FALSE (default: TRUE) You may wish to display the same text at all times when the dropdown list is closed. If so, uncheck this entry. If the entry is checked, the item that the user last selected will appear in the closed dropdown list display. ===================================================================================== ADVANCED INTERACTIONS --------------------- Standard interactions with Linked Movie Members are regulated automatically by the "Linked Movie Behavior". For more advanced interactions, you can use the syntax: tell result = linkedMovie(#instruction, data) end tell The Dropdown List Linked Movie Member recognizes 5 instructions: * linkedMovie(#forceDisplay, "any string (other types will be coerced to a string") This allows you to change the "current selection" display. It does not alter the current selection. If the user then makes a choice this forced display will be replaced either by the new selection, the default text or the previous selection (depending on the way the parameters are set). _________________________________ * linkedMovie(#getSelection) This returns a list of the format: [#text: "text of currently selected item", #item: 1] _________________________________ * linkedMovie(#getSelectionList) This returns a linear list of the items currently available for selection. _________________________________ * linkedMovie(#setSelection, itemData) can be of four types: #integer: a positive integer less than or equal to the number of items of the current dropdown list #string: the string must match one of the items in the current dropdown list #symbol: the symbol must match one of the items in the current dropdown list #list: the list should have the format: [#items: < list | string >, #selection: < integer | string | symbol >, #activate: < 1 | any other value considered to be 0 >] Not all the properties need be present. * The #items property allows you to change the items available for selection. If it is left void, the current set of items is maintained. * The #selection property allows you to change the currently selected item. If it is void, the current item is maintained, if possible. If not, it defaults to 1. * The #activate property has no effect unless it is set to 1 (TRUE). In this case, the callback handler for the dropdown list is called. The effect of a #setSelection([#activate: 1]) instruction is exactly the same effect as if the user had made the selection manually. In all cases, the call returns either a positive integer, indicating the number of the item selected, or a self-explanatory error symbol. Examples: tell sprite(1) to put linkedMovie(#setSelection, 1) -- 1 tell sprite(1) to put linkedMovie(#setSelection, "invalid item string") -- #invalidItemString tell sprite(1) to put linkedMovie(#setSelection, [#items: ["one", "two"]]) -- 1 itemData = [#items: ["one", "two", "three"], #selection: #three] tell sprite(1) to put linkedMovie(#setSelection, itemData) -- 3 Note that the order of items may be altered if the auto-typing feature is used. Setting the items available for selection may have no effect if the dropdown list is set to "Reset the list items every time the list is opened". (In other words, the parameter #dynamicItems must be FALSE: see below for details). _________________________________ * linkedMovie(#setParameters, parametersList) The should contain one or more of the following property/value pairs: [#itemsSource: #movie | "a handler in a Movie Script" #behavior | "a handler in a behavior on the same sprite" #actorList | "a handler in an instance on the actorList" #itemsHandler: , #dynamicItems: , #callBackScript: #movie | "a Movie Script" #behavior | "a behavior on the same sprite" #sendAllSprites | "behaviors on other sprites" #actorList | "an instance on the actorList" #member | "the Member Script" #callBackHandler: , #useRolloverCursor: , #autoTypeSprite: <0 | number of a sprite containing an editable field>, #defaultText: , #updateSelection: ] This instruction is equivalent to resetting the Behavior Parameters via the standard authoring dialog. The parameters appear in the same order above as in the Behavior Parameters dialog. Note that, if you use #updateSelection, changes to the display will not take effect until the next time the dropdown list is used. You may wish to use ... tell to linkedMovie(#setSelection, [:]) ... immediately afterwards, in order to force the display to refresh. Note also that changes to the #itemsSource and #itemsHandler will be ignored if #dynamicItems is not set to TRUE. (In contrast, changing the itemsList via the #setSelection instruction will have no effect unless #dynamicItems is set to FALSE). ===================================================================================== CHANGING THE APPEARANCE OF THE DROPDOWN LIST -------------------------------------------- The DropList.dcr uses a standard gray frame and button, and the fonts MS Sans Serif on Windows, Geneva on Macintosh. Neither the font nor the width, form and color of the various elements cannot be modified in the .dcr version. You can however modify the width of the dropdown list when it is closed. (When the list is open, the width of the list will adjust automatically according to the longest item). When your movie is halted, the dropdown list may appear somewhat differently: the display is corrected as soon as the movie is run. If you want to create a dropdown list with a different appearance, you will need to modify the source DropList.dir movie. Please contact James Newton at for details.