Popup Xtra User Guide

Table of Contents

Sales and technical support

Credits

What Popup Xtra does

Getting started

Defining menu contents

Defining menu behavior with the menuItemSelected handler

Event handling

Properties at a glance

Methods at a glance

Properties doc

Methods doc

Popup sprites

Shockwave

Limitations

Version history

Updating from previous versions IMPORTANT

Standard legal disclaimer

Sales and technical support

All licensing, pricing information and technical inquiries regarding Popup Xtra should be directed to updateStage which can be reached in the following ways:

e-mail sales: sales@updatestage.com

e-mail support: support@updatestage.com

phone: (781) 641-6043

web site: www.updatestage.com

You can download a demonstration version of Popup Xtra at:

ftp://ftp.shore.net/members/update/xtras/PopupX.zip

Credits

Popup Xtra was developed by Scott Kildall of Red Eye Software

Popup Xtra is a registered copyright of Red Eye Software. Copyright 1996-1999, Red Eye Software.

This user guide was written by Gretchen Macdowall

What Popup Xtra does

Popup Xtra, formerly sold as PopMenu Xtra(TM), creates hierarchical popup menus with customizeable properties such as font and submenu indicator. The menu contents can be changed at any time with Lingo to provide the user with context-sensitive menu choices. The menu position can also be set at runtime, so that you can display a menu anywhere on the stage when the user holds down the mouse.

Popup Xtra is Shockwave-safe and downloadable. If you create a Shockwave movie with the option checked for Popup Xtra to "download as needed" the Shockwave movie will automatically download and install Popup Xtra on the user's hard drive.

Getting started

There are 6 Popup Xtra files covering the various platforms:

Filename	Platform	When to use
Popup Xtra	Mac	Authoring
Popup Xtra Runtime	Mac	Projector, Shockwave
Popup.x32	32-bit Windows (Windows 95,98,NT)	Authoring
PopupR.x32	32-bit Windows	Projector, Shockwave
Popup.x16	16- bit Windows (Windows 3.1)	No runtime. Same version works in authoring and in projectors. No Shockwave version.
popuppack.ppc	Mac	Packaged Mac Xtra to store on web server for Shockwave users
popuppack.w32	32-bit Windows	Packaged Mac Xtra to store on web server for Shockwave users

 

In authoring, place the correct authoring Popup Xtra for your platform in Director's Xtras folder. For delivery with your projector, place the correct runtime Popup Xtra for your projector type in the Xtras folder next to your projector. You cannot use the runtime version in the authoring environment.

For Shockwave delivery, upload the two "popuppack" files to the same directory on your web server. Be sure to use a "binary" or "raw" transfer, not a text transfer. Edit xtrainfo.txt to point to the directory on your server that stores the files. Do this before creating any Shockwave files that make use of Popup Xtra, because when you add the "Download as needed" option the system will dial out to check for the packages at the specified location.

Ignore the blue section if you have not yet purchased Popup Xtra.

To register Popup Xtra, choose "Popup Xtra >> Register" from the Xtras menu. You will be shown a registration dialog box and should type in your serial number here.

Demo limitations

If you are working with the demonstration version of Popup Xtra you can create Popup members, set some of their properties, and play a movie containing the Popup members you have created, but you will not be able to save any of the Popup members. The following functions and properties are not available for Lingo control in the demo:

AppendItem() 
InsertItem, 
SetMenu() 
SetMenuField()
set the menu of member
set the menuField of member

You will also not be able to open movies containing Popup members created by other registered users directly. You can play movies containing Popup cast members by opening them as MIAW's (Movie in a Window). To open a movie as an MIAW, place it in your Director Xtras folder and restart Director. The movie name will appear in your Xtras menu Choose it from the menu to play it.

Creating a Popup cast member

To create a Popup castmember, choose "Red Eye Xtras >> Popup" from the Insert menu. This will add a generic Popup castmember to your cast with a default size, font and other properties and no menu text. The characteristics of a Popup cast member are called properties. You can set the properties of a Popup member manually through its property dialog or on the fly with Lingo. To display the property dialog pictured below, double-click on the Popup member or click the Options button in the Popup member's Get Info dialog.

The most important Popup castmember property is the menu field containing the text to display in the popup menu. Use the Castlib and Member pulldowns in the top/left of the properties dialog to link the popup to a field member. The simplest way to specify menu contents is to enter the menu items, one per line, in the field you have specified.

The cast member script of a Popup castmember contains its menuItemSelected handler, which is called when the user makes a selection from the popup menu.

on menuItemSelected me, menuSpec, menuText, memberRef
  -- your Lingo code goes here
end 

The variable menuText is passed in to the handler by Director when the user makes a selection. It contains the text of the selection the user made. Your Lingo can examine the contents of menuText and take action depending on what it contains.

on menuItemSelected me, menuSpec, menuText, memberRef
  if menuText = "Impressionists" then go "IMP01"
end 

Defining menu contents

A Popup member's menu field contains the text of the menu items that display when the user clicks on the popup menu on stage. You create a new field member by choosing Insert -> Control -> Field from Director's menu bar.

You can define a basic menu with no submenus simply by entering each menu item on a new line in the field like this:

Item A
Item B
Item C

Item separator

You can also use a semi-colon to separate menu items instead of placing each item on a separate line. Here is the same 3-item menu specified using semi-colons instead of newlines:

Item A;Item B;Item C

You cannot include semi-colons inside menu text. A semi-colon will always be interpreted as the start of a new menu line.

Submenus

The left and right bracket characters, placed after a menu item, specify a submenu. The following text in a field will create a popup menu that displays a 2-item submenu when the user holds the mouse down on the menu item "Animals"

Animals[dog;cat]
Minerals
Vegetables

Another way to specify the menu above, would be to use semi-colons instead of newlines for all item separation. The same menu choices would then look like the following:

Animals[dog;cat];Minerals;Vegetables

You can nest submenus inside of submenus. To add a submenu inside the "cat" submenu, with breeds of cats, you would do the following:

Animals[dog;cat[Persian;Tabby;Siamese]]
Minerals
Vegetables

You cannot include brackets inside of menu text. A bracket will always be interpreted as the start of a submenu.

Item styles (Mac only)

Meta characters at the beginning of a menu item specify the style of a menu item or create a menu separator line. The meta characters themselves do not display in the menu text.

Meta character	Effect
<B	Bold text style EX: <BMakes this item bold
<I	Italic text style EX: <IBMakes this item italic and bold
<O	Outline text style EX: <OMakes this item outline style
<U	Underline text style EX: <UBMakes this item underlined and bold
<S	Shadow text style EX: <SMakes this item shadow style
hyphen -	Creates a menu separator EX: Introduction Table of Contents - Chapter 1 Chapter 2

You must use capital letters for the text style specification. You can pair more than one together like so:

<SIMake this item shadow style and italic

If your menu item text starts with a capital letter that is the same as a style letter, and you are using a meta character for another style at the beginning of the menu entry, leave a space between the meta character and the menu item to prevent the first character of the menu text from being treated as an additional style, like so:

<B Send in the clowns

You can use < as a character at the beginning of your menu text instead of as a meta character by doubling the character up like so:

<<This text is in greater than/less than signs>

You cannot use a hyphen at the beginning of a menu item.

Item styles in cross-platform movies will display on the Mac and will simply be ignored on Windows, which does not support them.

Important: When a Popup Xtra castmember is saved to disk, the meta character information does not get saved along with it. Call RefreshMenu() in the startMovie handler for all of the castmembers using meta characters, to display item styles correctly.

Defining menu behavior with the menuItemSelected handler

1. The menuItemSelected event contains information about which sprite was clicked and what item was chosen. You need a menuItemSelected handler to trap the event and act on the selection made by the user. Popup cast members automatically contain an empty menuItemSelected handler in their cast script. It looks like this:
   

   on menuItemSelected me, menuSpec, menuText, memberRef
     -- your Lingo code goes here
   end 
    

   
   

   Every time the user makes a menu choice from a Popup menu, Director calls your menuItemSelected handler and passes it the following 4 pieces of information, which you can use in your Lingo code:

   me

   The sprite reference (always zero with Director 5). This indicates the sprite number, if any that the user clicked on stage. If you are using activateMenu() to place a menu on stage with Lingo, the sprite number will be 0.

   EX: (sprite 5)

   
   

   menuSpec

   A string containing the number of the selected menu item. If the item is in a submenu, then the numbers of each item chosen, in order, appear in the menuSpec, separated by semi-colons.

   EX: "3;2;4"

   
   

   The user chose item 3 of the initial menu, which displayed a submenu. The user chose item 2 of the submenu which displayed another 4-item submenu. The user let the mouse up on item 4 of the second submenu.

   Some Popup calls require you to pass a menuSpec as one of the parameters. Make sure to pass the menuSpec as a string (enclosed by quotes) - not an integer.

   More examples

   menu spec	description
   "2"	The second item of the main menu
   "3;1"	The first item in the submenu attached to the third menu item of the main menu
   "1;2;1"	The first item in the submenu attached to the second item of submenu attached to the first item in the main menu

   menuText

   The text of the selected menu item

   EX: "School Supplies" 

   
   

   The user selected the menu item with the text "School Supplies"

   memberRef

   The member reference for the Popup member

   EX: (member 2 of castlib 3)

   
   

   The user clicked on a Popup sprite whose cast member is member 2 of cast library 3

   Attach the following code to a Popup member's cast script to see what happens when a user selects an item:

   on menuItemSelected me, menuSpec, menuText, memberRef
      put "sprite is" && me
      put "menu item text is" && menuText
      put "menu spec selected is" && menuSpec
      put "member is" && memberRef
   end

   
   

   You will see output in the Message Window that looks something like this:

   -- "sprite is (sprite 2)"
   -- "menu item text is Minerals"
   -- "menu spec selected is 2"
   -- "member is (member 1 of castLib 1)"

   
   

   Make sure that the Popup member is associated with a field containing the text for the menu, then drag it onto the stage. Look at the output in the message window and you will see your selections reflected there.

   Play and "go movie"

   If you issue a "play" from within the Popup member's menuItemSelected handler you will get a bogus "handler not defined" error message. If you issue a "go" from within the Popup member's menuItemSelected handler, to go to another movie, the projector may crash. The workaround for both situations is to avoid navigating directly from within the menuItemSelected handler. Set a global to the user's menu choice and have a frame script poll the global and do the actual play like this:

   on exitFrame
     global nextFrame
     if nextFrame > "" then
       play nextFrame
       -- or go movie nextFrame
       set nextFrame = ""
     else
       go the frame
     end if
   end
       

   
   

   Popup castmember code would be:

   on menuItemSelected me, menuSpec, menuText, memberRef
     global nextFrame
     set nextFrame = menuText
   end

   
   

   Going to a new frame with a transition

   If you issue a "go" from within the Popup member's menuItemSelected handler and the new frame has a score or puppetTransition, the transition will not execute. The workaround is to set a global to the user's menu choice and have a frame script poll the global and do the actual go like this:

   on exitFrame
     global nextFrame
     if nextFrame > "" then
       go nextFrame
       set nextFrame = ""
     else
       go the frame
     end if
   end

   
   

   Popup castmember code would be:

   on menuItemSelected me, menuSpec, menuText, memberRef
     global nextFrame
     set nextFrame = menuText
   end

   
   

Event handling

When a user clicks on a Popup sprite, Popup sends events, in the following order, to Director:

1. mouseDown: user clicked on menu
2. menuItemSelected: user selected an item or let the mouse up outside of the menu
3. mouseUp: user let the mouse up

1. Sprite, cast, frame or movie level mouseUp and mouseDown handlers can interfere with the operation of Popup members. If you are getting unexpected results, remove mouseDown or mouseUp handlers that are triggered by a click on the Popup sprite. Move any code specific to the Popup sprite into the menuItemSelected handler instead.

   The menuItemSelected event is sent to the following script types in order. It proceeds down the hierarchy until it gets to a script at that level that has a menuItemSelected handler to handle it.

   1. Sprite script of the Popup sprite clicked on
   2. Castmember script of the Popup sprite clicked on
   3. Frame script of the current frame
   4. Movie script - intercepted by first movie script containing menuItemSelected handler

   
   

   You do not have to place the menuItemSelected handler in a Popup cast member script, although that's the most likely place for it. If you have created several sprites from the same Popup member you can give them all different menuItemSelected sprite scripts to make them all behave differently. Or you could comment out the handlers of all of your Popup cast members and instead have one central menuItemSelected movie script handler. In that case, no matter what menu the user clicked, the menuItemSelected event would go to your central movie script. That code could use the variable memberRef to determine which Popup member was clicked on

   A Popup sprite will not receive any events, and therefore won't work, on a frame stalled by pause. To keep your movie on the same frame use this in a frame script instead. The playback head must be moving for Popup sprites to react to the user.

   on exitFrame
      go the frame
   end

   
   

Properties at a glance

Property name	Get/Set	Description		Type
version	Get	Version number of Popup Xtra		string
language	Get	Language of this Xtra (#english or #japanese)		symbol
menu	Get/Set	Contents of popup menu		string
menuField	Get/Set	Field associated with the Popup castmember		memberRef
menuDisplayText	Get/Set	Text displayed by a Popup Xtra sprite		string
menuFont	Get/Set	Font name of the text displayed in the sprite and of the text displayed in the menu		string
menuFontSize	Get/Set	Font size of the text displayed in the sprite and of the text displayed in the menu		integer
selectedSpec	Get/Set	A menuSpec describing the menu item number of the last selection made by the user		string
selectedText	Get/Set	Text of the menu item last selected by the user		string
trapEvents	Get/Set	Whether or not the Popup Xtra will automatically dispatch mouse down events to the menu when the user clicks on the sprite		integer
menuAutoMark	Get/Set	Whether or not the Popup Xtra will automatically put a mark next to the user's selection		integer
menuAutoText	Get/Set	Whether or not the display text will automatically be updated to reflect the last selection made		integer
menuIndicator	Get/Set	The type of selected-item indicator displayed by the sprite		integer
menuLook	Get/Set	The type of menu sprite that will be drawn		integer
menuMarkType	Get/Set	The type of mark (e.g. check, bullet) that will be drawn next to selected items		integer
menuLoc	Get/Set	Where the menu will be displayed relative to the Popup sprite		integer
menuAutoAlign	Get/Set	Whether or not the last selection made by the user will appear next to the mouse when the menu is clicked		integer
help	Get	Text describing how to get started with Popup Xtra		string
propertyNames	Get	Text describing all of the properties of Popup Xtra		string
functionNames	Get	Text describing all of the functions of Popup Xtra		string
autoRedrawWindow	Get/Set	Whether the window containing the Popup Xtra sprite will automatically be redrawn when a menu selection is made.		integer

Methods at a glance

Function name	Description
ClearMenu( member "popupMem")		Erases the menu definition completely for a Popup castmember
Activate(member "popupMem", locH, locV)		Displays the menu through Lingo control
AppendItem(member "popupMem", menuText, menuSpec)		Adds a menu item to the end of a one-level menu
InsertItem(member "popupMem", menuText, menuSpec)		Adds a menu item to a specific location in a menu
DeleteItem(member "popupMem", menuSpec)		Deletes a menu item from a menu
SetItem(member "popupMem", menuSpec, menuText)		Sets the text of a menu item
GetItem(member "popupMem",menuSpec)		Returns the text of a menu item
RefreshMenu(member "popupMem")		Updates the menu if the contents of its menu field have changed
Redraw(member "popupMem")		Forces a redraw of the sprite on the stage
ClearMarks(member "popupMem")		Erases all marks from menu items
SetItemMark(member "popupMem", menuSpec, markType)		Places a mark (e.g. a check) next to a menu item
GetItemMark(member "popupMem", menuSpec)		Returns the mark type next to a menu item
SetForecolor(member "popupMem", indexColor) SetForecolor(member "popupMem", redColor, greenColor, blueColor)		Specifies the foreground color of a Popup castmember
GetForecolor(member "popupMem")		Returns the foreground color of a Popup castmember
SetBackcolor(member "popupMem", indexColor) SetBackcolor(member "popupMem", redColor, greenColor, blueColor)		Specifies the background color of a Popup castmember
GetBackcolor(member "popupMem")		Returns the background color of a Popup castmember
SetItemStyle(member "popupMem", menuSpec, styleCode)		Specifies the text style of an item (Mac only)
GetItemStyle(member "popupMem", menuSpec)		Returns the text style of an item
EnableItem(member "popupMem", menuSpec)		Enables a menu item
DisableItem(member "popupMem", menuSpec)		Disables a menu item

Properties doc

The general syntax for setting any Popup property is:

set the propertyName of member "popup member name" to propertyValue

EX: set the menuDisplayText of member "myPop" to "School supplies"

The general syntax for getting any Popup property is:

set varName = the propertyName of member "popup member name"

EX: set myVar = the menuAutoMark of member "myPop"

Most properties that can be set via Lingo can also be set by using the castmember properties dialog.

version

Returns the version number of Popup Xtra.

Example:

put the version of member "myPop"
-- "3.1.2"

language

Returns a symbol indicating the language of Popup Xtra, either #English or #Japanese.

Example:

put the language of member "myPop"
-- #English

menu

Returns the current menu contents if you query the property, or creates new menu contents if you set it.

Examples:

-- Creates a menu with four items, each being a tasty fruit
set the menu of member "fruity popup" = "Banana;Apple;Kiwi;Mango"

 
-- This will tell us whether a "Strawberry" is in one of the menu items
if the menu of member "fruity popup" contains "Strawberry" then
   alert "Strawberry is a menu item!"
end if

menuField

Returns the member reference of the current field associated with the Popup member if you query the property, or associates a new field with the menu, changing its menu contents, if you set it. Call RefreshMenu() after setting this property to install the new menu contents.

Examples:

set the menuField of member "myPop" = member "newMenu"
put the menuField of member "myPop"
   -- (member 3 of castlib 4)

menuDisplayText

Returns the text displayed in the Popup sprite on stage when it is inactive - typically the text of the last selection made. Changes the display text if you set it. If the menu is invisible (see the menuLook property), this property is irrelevant.

Example:

if the menuDisplayText of member "myPop" = "candy"  then
   set the menuDisplayText of member "myPop" = "Invalid choice" 
end if

menuFont

Returns the current font used by the menu to display text if queried, or causes the menu to use a new font if set.

Example:

if the machinetype = 256 then
   -- Windows font
   set the menuFont of member "myPop" = "CourierNew"
else
   -- Mac font
   set the menuFont of member "myPop" = "Charcoal"
end if

Setting the font for a Popup member manually by using the properties dialog sets it for the platform you are authoring on. To set the font for a Popup member manually for both platforms you must open the movie in Director authoring on both platforms and set the font. The font you choose must be on the playback system. If you have not set the font manually for a platform the movie is playing on, or if the font is not resident on the playback system, the menu will display using the default system font. It is easier to set the fonts for Popup members in a setup handler using Lingo.

menuFontSize

Returns the current font size used by the menu to display text if queried, or causes the menu to use a new font size if set.

Example:

if the machinetype = 256 then
   -- Windows
   set the menuFontSize of member "myPop" = 14
else
   -- Mac
   set the menuFontSize of member "myPop" = 12
end if

Setting the font size for a Popup member manually by using the properties dialog sets it for the platform you are authoring on. To set the font size for a Popup member manually for both platforms you must open the movie in Director authoring on both platforms and set the font size. It is easier to set the font sizes for Popup members in a setup handler using Lingo.

The Windows operating system itself will not allow text in menus to display if it is below a certain pixel height. If you set the pointsize of a menu font in Popup below approx. 12-points (varies by font) the text size in the menu will not get any smaller, although the menu box itself will get smaller. There is no such pointsize limitation on the Mac. There is not much that can be done about this system difference.

selectedSpec

Returns the last item the user selected, in menuSpec format if queried. Setting the selectedSpec will have the same results as if the user made a menu selection. Changes the display text and possibly other behavior of the Popup sprite depending on the following properties:

menuAutoText: If this property is true, then the menu display text will be changed to the text that corresponds to the passed menu spec.

menuAutoMark: If this property is true, then the menu item specified by the passed spec will be checked and all others on the same menu will be unchecked.

menuAutoAlign: if this property is set to true, then the menu will align to the menu item described by the spec. Passing a selectedSpec of "" (empty string) will clear the menu display text, set the alignment to the first item and clear all check marks (if the corresponding properties are set to true).

Example:

-- button that sets menu back to a default
on mouseUp
   set the selectedSpec of member "myPop" = "1"
end 

selectedText

Returns the text of the last item the user selected.

Example:

put the selectedText of member "myPop" into field "menuChoice"

trapEvents

Returns TRUE or FALSE if queried. Governs how a Popup sprite handles mouseUp and mouseDown events. It is on by default. A Popup sprite with trapEvents on will always respond to a mouseDown on it by displaying a menu and will respond to a mouseUp on it by making a menu selection. Unless you are going to display Popup menus under Lingo control using the Activate() feature, leave it on.

Turn it off to use the activate() feature. Otherwise, a Popup sprite on stage underneath a menu created from the same member and displayed by the activate() command, will process the mouseUp and mouseDown event twice.

Example:

-- this member is going to be controlled with Activate()
set the trapEvents of member "myPop" = FALSE

menuAutoMark

Returns TRUE or FALSE indicating whether or not the Popup Xtra will automatically place a check mark next to the last selected menu item. If this is set to true, there will always be one check mark per menu. If you set it to FALSE you can have multiple check marks, but you must control the check marks yourself by using the setItemMark function. Corresponds to "Auto-Mark Selections" check box in Popup member properties dialog.

Example:

-- we want to set multiple check marks with Lingo
set the menuAutoMark of member "myPop" = FALSE

menuAutoText

Returns TRUE or FALSE indicating whether or not the Popup Xtra will automatically show the last selected menu item text in the display area of the Popup sprite. If the menuLook is invisible, then this property is not relevant. Corresponds to "Auto-Select Text" check box in Popup member properties dialog.

Example:

-- we want the display text always blank
set the menuAutoText of member "myPop" = FALSE
set the menuDisplayText of member "myPop" = ""

menuIndicator

Returns an integer for the graphic used to show that there is a submenu for a menu item. Set the property to select the graphic type for a submenu arrow or to have no indicator. Corresponds to "Menu Indicator" in the properties dialog.

Indicator Type	Value
None	0
Down Arrow	1
Diagonal Arrow	2

Example:

set the menuIndicator of member "sample popup" = 0

No indicator will display for an item with a submenu.

If the menuLook is invisible, then this property is not relevant.

menuLook

Returns an integer representing the appearance of the menu. Corresponds to "Look" in the properties dialog. Currently, there are only two types of looks: Macintosh standard and invisible. The values for each are as follows:

Look Type	Value
Invisible	1
Macintosh standard	2

There is no reason to set this property via Lingo currently. Manipulating visibility via the menuLook can cause display problems and is not recommended. Also when you toggle visibility off with Lingo the sprite size is reset by Director. If the sprite is too close to the edge of the screen, it may go beyond the screen bounds. A popup sprite that extends beyond the screen bounds will not respond to a user click. This kind of problem is hard to diagnose because the sprite is invisible so you can't see that it extends beyond the stage.

Use the normal Lingo "visibility of sprite" or move the sprite off stage if you need to make a popup sprite disappear at runtime. If you do set the menuLook to invisible and later set it back to Mac standard, you will have to call Redraw() to make it visible again under Director 7.

So what is menuLook for? A menu sprite set to invisible via "Look" in the properties dialog will still operate normally when clicked on. This enables you to create a graphic sprite to put over the invisible popup sprite and create any look you want for the popup menu. The pulldown part of the menu will still be visible when the user clicks on the invisible menu sprite. You can put the graphic sprite over the invisible popup sprite, making sure not to give it a mouseUp script which would stop the popup sprite from getting the mouseUp. Or you can put the graphic sprite "under" the popup sprite since the popup sprite is invisible.

A popup member with a menuLook of invisible will appear as a white square under 8-bit color if it is on the first frame of a movie played in a projector. There is nothing that can be done about this inside the Popup Xtra code. The workaround is to have your invisible popup sprite start on the second frame rather than the first frame, or to place it off stage or under another graphic on the first frame.

menuMarkType

Returns an integer indicating what type of mark will be placed next to a selected menu item. Set this property to change the type of mark the last selected item will display. The symbol for the mark must reside in the font selected for the menu. Try the symbol under both Mac and Windows to make sure the menu font on both platforms can display it. Corresponds to "Mark Type" in the properties dialog.

Mark Type	Value
No mark	0
Check	1
Filled Diamond	2
Command	3
Bullet	4
Serif Check	5
Prompt	6
Open Diamond	7

Example:

set the menuMarkType of member "myPop" = 1

menuLoc

Returns an integer indicating where on the screen the menu will be displayed relative to the Popup sprite. Set this property to change how the menu aligns with the sprite when the menu displays. Corresponds to "Menu Location" in the properties dialog.

Menu location	Value
Where the mouse was clicked	0
Center of the sprite	1
Upper-left corner of the sprite	2
Upper-right corner of the sprite	3
Lower-left corner of the sprite	4
Lower-right corner of the sprite	5

Example:

set the menuLoc of member "myPop" = 1

menuAutoAlign

Returns TRUE or FALSE indicating whether or not the menu will be adjusted so that the last selected item appears under the mouse instead of the first item in the menu. Set menuAutoAlign to TRUE to make the last selected item display under the mouse. Corresponds to "Auto-Align Menu" check box in Popup member properties dialog.

Under Windows 98 this property has no effect because the native single-column scrolling menu does not support it. The Windows 98 scrolling menu will always display the section of the menu the user last chose from, although it won't line up the actual selection line with the user's mouse.

Example:

set the menuAutoAlign of member "myPop" = TRUE

autoRedrawWindow

Returns TRUE or FALSE. If it is TRUE, when a menu selection is made, the window that has the Popup Xtra sprite in it will automatically be redrawn. The default is on. Leaving it on will fix some palette and transition related Popup display problems, but will erase all trails inks and may affect other sprites that are rendered Direct-to-Stage. It is recommended that you leave it on. Corresponds to the "Auto-Redraw Window" check box in Popup member properties dialog.

help

Returns basic help text for Popup Xtra. Available in authoring Xtra only.

put the help of member "myPop"
-----------------------
Purchasing Popup Xtra
-----------------------
 
To license Popup Xtra
...

propertyNames

Returns a list of Popup Xtra's properties. Available in authoring Xtra only.

put the propertyNames of member "myPop"
-- "Popup Xtra castmember properties:
 
type
media
 
help
propertyNames
functionNames
 
language
version
...

functionNames

Returns a list of Popup Xtra's functions. Available in authoring Xtra only.

put the functionNames of member "myPop"
-- "Popup Xtra castmember functions:
 
setMenu (member memberID, string menuText)
   set the text of the menu definition
 
getMenu (member memberID)
   get the text of the current menu
...

Methods doc

All functions of Popup Xtra take, as their first parameter, a member reference.

Examples

clearMenu( member "my popup" )

clearMenu( member 1 )

clearMenu( member "my popup" of castlib "bud" )

ClearMenu( member "popup member name" )

Erases the menu contents. A Popup sprite with no contents will not do anything if the user clicks on it. You cannot use activate() on a Popup member with no contents.

Example:

clearMenu(member "myPop")

Activate( member "popup member name", locH, locV)

locH: integer, horizontal position where menu should appear

locV: integer, vertical position where menu should appear

Displays a menu under Lingo control. The trapEvents property must be set to false for this function to work properly. Otherwise, the menu may respond to mouseUp and mouseDown events twice. This function was designed to be triggered by a mouseDown script. It can be triggered from other Lingo events as well, but since the user's mouse has to physically be down for the popup to display, practically-speaking you must use a mouseDown script to call it. The cast member script of a Popup menu displayed by Activate() does not receive mouseUp or mouseDown messages.

A menu displayed with Activate does not have a sprite script or a sprite number because it is not a sprite. Its menuItemSelected handler will report (sprite 0) for the "me" parameter.

Example

The following script on a popup sprite with its cast member trapEvents property set to FALSE will cause the popup to only display a menu when clicked on if the user is also holding down the control key.

on mouseDown
   if the controlDown = true then
      Activate(member "my popup", the mouseH, the mouseV )
   end if
end

AppendItem( member "popup member name", menuText, "1" )

menuText: string, text of item to add

"1": string, always 1

This will add an item to the end of the main menu. Use insertItem to alter submenus.

Example:

The following code will add the item "New Item" to the end of the main menu.

appendItem(member "myPop","New Item","1")

InsertItem( member "popup member name", menuText, menuSpec )

menuText: string, text of item to insert

menuSpec: string, where to insert this item, in menuSpec form

This will put an item into the specified position in a menu.

Example:

The following code will insert the item "Dogs" into position 2 of the submenu of item 1 of the main menu.

InsertItem(member "myPop","Dogs","1;2")

DeleteItem( member "popup member name", menuSpec )

menuSpec: string, which item to delete, in menuSpec form

Deletes an menu item..

Example:

The following code will delete the item at position 2 of the submenu of item 3 of the main menu.

DeleteItem(member "myPop","3;2")

SetItem( member "popup member name", menuSpec, menuText)

menuSpec: string, which item to change, in menuSpec form

menuText: string, new text for item

Changes the text of a menu item..

Example:

The following code will change the text of the item at position 2 of the submenu of item 3 of the main menu to "happy"

SetItem(member "myPop","3;2","happy")

GetItem( member "popup member name", menuSpec,)

menuSpec: string, which item to get the text of, in menuSpec form

Returns the text of a menu item..

Example:

The following code will retrieve the text of the item at position 2 of the submenu of item 3 of the main menu and put it into field "Show"

put GetItem(member "myPop","3;2") into field "Show"

EnableItem( member "popup member name", menuSpec, )

menuSpec: string, which item to enable, in menuSpec form

Enables a menu item that has previously been disabled with DisableItem()

Example:

The following code will enable the item at position 2 of the submenu of item 3 of the main menu

EnableItem(member "myPop","3;2")

DisableItem( member "popup member name", menuSpec, )

menuSpec: string, which item to disable, in menuSpec form

Disables a menu item. Disabled items appear dimmed in the menu and will not display any submenus attached to them. The user will not be able to select a disabled menu item.

Example:

The following code will disable the item at position 2 of the submenu of item 3 of the main menu

DisableItem(member "myPop","3;2")

RefreshMenu( member "popup member name" )

Rebuilds the menu based on the associated menu field. This should only be called if the text of the menu field has been changed.

Example:

RefreshMenu(member "myPop")

Redraw( member "popup member name" )

Forces a redraw of the Popup sprite. This will only need to be called under Director 5 if the palette changes or under Director 7 if you have set the menuLook of the menu to invisible and you want to make it visible again.

Example:

Redraw(member "myPop")

ClearMarks( member "popup member name" )

Removes the marks from all menu items.

Example:

ClearMarks(member "myPop")

SetItemMark( member "popup member name", menuSpec, markType )

menuSpec: string, which item to mark, in menuSpec form

markType: integer, type of mark to display.

This will change the mark next to a menu item. Refer to the menuMarkType property for a listing of which numbers represent which mark types.

On Windows, the markType parameter for this function has no effect. The item will be marked, but it will display the current menu mark as set for the menu as a whole, in the properties dialog or with the menuMarkType property. On Mac, you can use this param to set a different mark type for every item regardless of the menuMarkType for the menu as a whole.

Example:

The example marks item 2 of the submenu from item 1 with a bullet.

SetItemMark(member "myPop","1;2", 4)

GetItemMark( member "popup member name", menuSpec )

menuSpec: string, which item to return the mark type of, in menuSpec form

Returns the mark type of a menu item. Refer to the menuMarkType property for a listing of which numbers represent which mark types.

Example:

The example returns the item mark number of item 2 of the submenu from item 1.

GetItemMark(member "myPop","1;2")

SetForecolor( member "popup member name", indexedColor )

indexedColor: integer, number from 0 to 255 representing palette position of color

SetForecolor( member "popup member name", redColor, greenColor, blueColor )

redColor: integer, number from 0 to 255 representing red value of RGB color

greenColor: integer, number from 0 to 255 representing green value of RGB color

blueColor: integer, number from 0 to 255 representing blue value of RGB color

Set the foreground color of a menu and of the Popup sprite. There are two forms of this function. The first takes an indexed palette color. The second is more accurate and uses an RGB color with each integer argument representing a color channel that has a value between 0-255. Use RGB color if your project will display under color depths higher than 8-bit to avoid inaccurate color remapping at the higher color depths.

Consider the limitations of this function on various platforms before using it.

Examples

-- This requests a black indexed color
setForecolor( member "popup", 255 )

-- This requests a red RGB color value
setForecolor( member "popup", 255, 0, 0 )

SetBackcolor( member "popup member name", indexedColor )

indexedColor: integer, number from 0 to 255 representing palette position of color

SetBackcolor( member "popup member name", redColor, greenColor, blueColor )

redColor: integer, number from 0 to 255 representing red value of RGB color

greenColor: integer, number from 0 to 255 representing green value of RGB color

blueColor: integer, number from 0 to 255 representing blue value of RGB color

Set the background color of a menu and of the Popup sprite. There are two forms of this function. The first takes an indexed palette color. The second is more accurate and uses an RGB color with each integer argument representing a color channel that has a value between 0-255. Use RGB color if your project will display under color depths higher than 8-bit to avoid inaccurate color re mapping at the higher color depths.

Consider the limitations of this function on various platforms before using it.

Examples

-- This requests a white indexed color
SetBackcolor( member "popup", 0 )

-- This requests a green RGB color value
SetBackcolor( member "popup", 0, 255, 0 )

GetForecolor( member "popup member name" )

Returns the indexed foreground color.

Example:

set color = GetForecolor(member "myPop")

GetBackcolor( member "popup member name" )

Returns the indexed background color.

Example:

set color = GetBackcolor(member "myPop")

SetItemStyle( member "popup member name", menuSpec, styleCode )

menuSpec: string, which item to set the text style of, in menuSpec form

styleCode: integer, sum of text styles to apply

Sets the item style - bold, for instance, of a menu item. This function applies to the Macintosh only.

The following table contains the possible item styles. Several styles can be applied to the same item by adding the style values for the desired styles and using the sum for the styleCode argument.

Item Style	Value
Plain text	0
Bold	1
Italic	2
Underline	4
Outline	8
Shadow	16
Condense	32
Extend	64

Example

The following example sets the style of item 2 of the menu to bold and italic. ( 1 + 2 )

setItemStyle( member "my popup", "2", 3 )

GetItemStyle( member "popup member name", menuSpec, )

menuSpec: string, which item to get the text style of, in menuSpec form

Returns the item style number of a menu item

Example

The following example stores the style of item 2 of the menu in variable "itemStyle"

set itemStyle = GetItemStyle( member "my popup", "2" )

Popup sprites

Sprites created by an Xtra can either draw themselves into Director's offscreen buffer or draw themselves right on to the stage. The images of sprites drawn to the offscreen buffer can be layered by Director, can have inks applied to them, and redraw themselves if other sprites pass over them. Sprites drawn direct-to-stage, on the other hand always appear over other sprites that are not themselves drawn direct-to-stage. Direct-to-stage sprites cannot have inks applied to them and do not refresh themselves if another sprite moves over them.

To remain compatible with Director 7, Popup Xtra v 3.1.3 and above draws Popup sprites direct-to-stage under Director 7, but still uses Director's offscreen buffer under Director 5 and 6. Use the Redraw method to refresh a direct-to-stage Popup sprite if its image is changed by another sprite moving over it.

Shockwave

This section assumes that you are generally familiar with how Shockwave 7 handles Xtras and understand the terms Shockwave support folder, Shockwave-safe, and packaged Xtra. If not, please first read the Using Xtras with Shockwave 7 tech note.

You must use Director 7 to create Shockwave movies that autodownload Xtras. You can create Shockwave movies with any version of Director, that will recognize Popup Xtra runtime (v. 3.2 and above) if the user manually places it in the Shockwave support folder. The rest of this section explains how to create Shockwave 7 movies that autodownload the Xtra.

To create a Shockwave movie containing Popup cast members that will auto-download the Xtra to the user's hard drive you must do the following, in this order:

1. Upload the packaged Xtra files to your web server
2. Modify the entry for Popup Xtra in file xtrainfo.txt in your D7 authoring directory to point to the packaged Xtra files on your server
3. Do Modify -> Movie -> Xtras, select Popup Xtra, and check the "Download if Needed" option

   Once you have completed steps 1 and 2, you can create other Shockwave movies by doing only step 3.

   Packaged files

   Your Popup Xtra archive contains a subfolder called "Shockwave packages". There are two files inside it:

   popuppack.w32 - Win 32 packaged Popup Xtra
   popuppack.ppc - Mac packaged Popup Xtra
   

   Both packages contain the Popup runtime Xtra for that platform. Depending on the user's platform, a package autodownloaded to the user's hard drive will install one of these two Shockwave-safe files:

   popupr.x32 - Win32 runtime version of Popup
   Popup Xtra Runtime - Mac runtime version of Popup
   

   If, for some reason, you choose not to make your Shockwave movies autodownload the package files, you can have the user install the right runtime version for their platform into the Shockwave support folder manually.

   Upload both package files to the same directory on your web server. Use a "binary" or "raw", not "text" transfer. If the packages are uploaded to two different directories autodownloading will not work. Do not rename the packages files.

   If you are going to distribute Popup Xtra with Shockwave movies, you must use your own web server to do so. updateStage reserves the right to refuse access, without notice, to any referring URL that generates excessive traffic.

   Popup Xtra packages have been signed and packaged by updateStage. You may choose to repackage Popup Xtra and sign it with your own Verisign certificate. You might want to do this if you want your own company name to appear in the auto-download dialog box the user sees when an auto-download is initiated. Macromedia is the best source of information on applying for a Verisign certificate and packaging files.

   Xtrainfo.txt

   The text file xtrainfo.txt resides in your Director authoring directory. It contains information about Xtras such as file version names for an Xtra on both platforms and the URL for the packages. The information contained in xtrainfo.txt is saved with each movie you create and used by projectors and Shockwave. The line for Popup Xtra in your xtrainfo.txt file probably looks like this:

   [#namePPC:"Popup Xtra", #nameW32:"POPUP.X32"]
   

   Add a #package entry that specifies the URL on your server for the package files. The last part of the path will always be "popuppack". That specifies the filename of the packages within the directory without the file extension. Do not include a file extension at the end of the path.

   [#namePPC:"Popup Xtra", #nameW32:"POPUP.X32", #package:"http://www.domain.com/folder/popuppack"]

    

   If you edit xtrainfo.txt while Director is open you should quit and restart Director to read in the changed information in xtrainfo.

   Editing the movie's Xtras list

   Open the Director movie containing Popup cast members that you want to save as Shockwave. Choose Modify -> Movie -> Xtras. There should be an entry for Popup Xtra. Select Popup Xtra from the list and check the "Download if needed" option. Director will initiate an internet connection and look for the packages at the URL you specified in xtrainfo.txt.

   If Director finds the packages, it will transfer information about the package contents for both platforms such as file names and version numbers and embed the information into your Director movie. An informational dialog box will appear that tells you that the packages for both platforms are "downloading". The packages themselves are not downloading, just information about them that the Shockwave movie will need later to compare the version of the Xtra the user possibly already has to the version currently on the server in order to determine if autodownloading is necessary. The Director movie needs information about both platforms because it may find itself running on either platform once it is on the web.

   Once "downloading" of the packages has finished, save the movie, then save it as Shockwave. The finished Shockwave movie can reside at any URL. It does not have to be in the same directory or even on the same server as the packaged Xtras.

   If a connection cannot be opened, or the packages cannot be found at the specified location, Director will uncheck the "Download as needed" option automatically. You must have a successful connection for the box to remain checked. A Shockwave made out of a Director movie with the "Download as needed" button unchecked will not autodownload Popup Xtra.

Limitations

Forecolor and backcolor

Due to idiosyncrasies of various operating systems, custom forecolors and backcolors will not display identically on every system. Known limitations are:

Mac, System 8: In System 8 and above, menus display with either a platinum appearance (solid silver background) or a custom appearance specified by a theme. Popup Xtra's menus cannot override the system setting for appearance of menus. The sprite will be able to display custom forecolor and backcolor, but when the user pulls down the menu, the menu will display with the system-specified appearance.

Windows NT: It is not technically possible for Popup Xtra to display custom forecolor and backcolor properties reliably for Popup menus under 8-bit color depth on Windows NT. After much development effort to try to make it work, which resulted in instability on other platforms, this feature has been turned off on Windows NT with Popup version 3.1.2 and above. Custom forecolor and backcolor Popup menus now purposely display the forecolor and backcolor only on the sprite shown onstage. The menus themselves display in black and white under Windows NT at 8-bit color depth. Popup menus do display with custom fore and back colors under Windows NT at higher color depths.

Custom palettes under Windows

Windows

A Popup Xtra castmember will remember the palette in effect the first time it is displayed on the stage. If you go to a frame that uses a different palette and the Popup member is also in that frame, the menu will display as completely black under certain video cards.

The rule is simple: one palette per Popup Xtra castmember. If you need to have the same popup menu displayed on screens with different palettes, create duplicates of the Popup Xtra castmember for each palette it will display under.

In authoring under Windows 98 and Windows 95, the second time you bring up a popup cast member's property dialog, all of the fields will display completely black or dark blue, making them impossible to edit. This happens under 8-bit color depth if the stage palette is the Windows system palette. The workaround is to set the stage palette to another palette such as greyscale or rainbow temporarily while you edit the popup properties.

Windows and Mac

If you move from a frame with one custom palette with popup sprites to another frame with a second custom palette that also has popup sprites on stage, the stage color will not remap correctly to the new palette. The workaround is to make a small solid color bitmap cast member of the same color as the stage and stretch it to cover the stage in channel 1. The bitmap will remap correctly.

External castlibs

It strongly recommended that you keep Popup members in internal castlibs. If you do decide to store Popup members in external castlibs you should be aware of the following issues.

Switching castlibs on the fly

Switching a castlib containing Popup members with "set the filename of castlib" crashes under Director 5. If the user is holding down the mouse on a Popup member on stage when the filename of the castlib is switched, it will also crash under Director 6. Both of these issues were resolved in Director 7.

Alt-Tab on Win 3.1

If more than one Popup cast member is in an external castlib attached to a movie running under a Win 3.1 projector, the user will not be able to Alt-Tab to switch out of the Director application. Alt-Tab will hang the machine. This is not a problem on 32-bit platforms even when running 16-bit projectors and it is not a problem on the Mac.

If you are creating a project that must run on Windows 3.1, keep Popup cast members in an internal castlib.

Castlib numbers

If a Popup member resides in an external castlib attached to two movies, the castlib must be in the same position in both movies. In other words if castlib "Media" contains a Popup member and it is attached to Movie A as castlib 3, castlib "Media" must also be attached to Movie B as castlib 3. Otherwise, if you navigate to movie B after Movie A, you will not be able to set the properties of the Popup member from Lingo once you are in Movie B.

Protected castlib in Xtras folder

In Director 6.5, if your projector is linked to a protected castlib (.cxt) that is located in the Xtras folder and the projector is made out of a movie that includes Popup cast members or the projector later opens a movie with Popup cast members, the projector may crash. Workaround is to use an unprotected castlib or to upgrade to Director 7.

Limits on number of menu items

The calls into the operating system that Popup uses impose some limits that affect Popup

Number of items in a menu

There is about a 2K limit on the total amount of text that one menu can hold. This results in an effective limit of about 120 menu items depending on how much text you have per item and how many submenus there are. If you have a menu this big you REALLY ought to rethink your user interface design.

Number of items that will display as disabled

On the Mac there is a limit of 31 menu items that can display as disabled in any one menu. If you need more disabled, rethink the interface. Try grouping like items into submenus instead.

Behavior of large menus

A menu containing more items than will fit vertically on the screen displays as multiple tiled panels under Win 3.1 and Win 95 and as one vertical scrolling panel under Win98 and Mac.

If you cause a menu that originally fit inside the screen bounds to exceed the screen bounds by adding items with either appendItem or insertItem the menu may not convert correctly to a scrolling menu and the user may not have access to all of the items in the menu. If you think you might create a menu on the fly that will exceed the stage bounds, instead of using append or insert you should create the new menu contents in a field and use refreshMenu to reset the popup member's contents.

16-bit projectors under Win 3.1

• A movie containing Popup cast members cannot be included inside a 16-bit projector. The projector will work fine if run under a 32-bit environment such as Win 98 but hang on launch or crash immediately on Win 3.1.

  Make a stub projector instead and use the syntax:

  go movie "mymovie"

  
  

  You can protect the Director movie to keep the code private.

• Under 8-bit color only, if you dynamically change the font or font size of a popup member and then alter the menu contents repeatedly on the fly, a 16-bit projector running under Win 3.1 may crash. To prevent this, it is recommended that the font of a menu with dynamic contents not be changed at runtime.

  Editing the cast member script

  If you resize the right margin of any asset cast member's cast script, including Popup members, Director 5 and 6 crash immediately under Windows. Fixed in Director 7.

  Memory

• If you have many Popup cast members in a movie a projector made from the movie may not have enough memory to launch and crash on the Mac. Workaround is to use GetInfo to change the default memory partition size for the projector.
• If you have many Popup cast members in a Shockwave movie Internet Explorer may display an "Invalid cast member" error message and crash or say that it is running low on memory.. Workaround is to use GetInfo to change the default memory partition size for Internet Explorer.

Version history

Current Version: 3.2

v3.2 released 4/10/99

Feature release

Made Popup Xtra Shockwave-safe and downloadable

v3.1.3 released 1/10/99

Compatibility release

• Made Popup Xtra compatible with Macintosh OS 8.5. In pre-3.1.3 versions, the properties dialog for a Popup cast member would not display under OS 8.5.
• Made Popup Xtra compatible with Windows 98. In pre-3.1.3 versions, a menu that exceeded the length of the screen would not display under some circumstances. Now Popup Xtra uses Windows 98-style single-column scrolling menus.
• Made Popup Xtra compatible with Director 7. In pre-3.1.3 versions, a number of incompatibilities arose with Director 7 and Popup Xtra. The most obvious one is that the menu items would not be drawn onto the menu when it was activated and instead would be rendered onto the stage directly. These problems have been fixed. To make Popup Xtra Director 7-compatible, Popup Xtra sprites now render themselves direct-to-stage.
• Fixed a bug where style metacharacters were not being processed properly for top-level menu items beyond the very first menu item.
• Fixed a bug where clearMarks would not erase a mark on an item following an item with a submenu

  v3.1.2 released 8/18/98

  Maintenance release

• Made some general palette fixes under Windows which fixed bugs where switching from one palette to another was causing blackened menu items. Devised a workaround to enable custom menu palettes to work with varying video cards on Windows.
  
• DeleteItem() command no longer causes display problems on the PC
  
• ClearMarks() command no longer errors out on PC
  
• Using a style indicator such as <B in front of the first submenu item no longer causes it to show up in the text
  
• Doc error, listing incorrect values for the menulook property, was fixed

  v3.1.1 released 7/1/98

  Maintenance release

• If you have a menu item that does a "go" to a new frame, the frame will now redraw without the programmer having to explicitly use "set the stagecolor to the stagecolor". See doc on the new property autoRedraw for more details.
  
• Quitting Director or jumping to another frame within the same movie from a popup menu selection no longer crashes Director
  
• Setting the forecolor and backcolor for popup menus on Windows under 8-bit color depth now works reliably. Fixes the problem of the wrong colors displaying and the problem of the menu sometimes displaying in black and white on Windows with some video cards.
  
• You can now play the example movie intact using the demo version of Popup if you open the movie as an MIAW. With the previous version of Popup Xtra it was impossible to use the demo movie.
  
• Menu separators no longer cause the menu items below them to disappear
  
• Menu separators no longer display discolored if the user has chosen a custom menu color in the Windows control panel
  
• Scrolling arrows now appear in platinum if the user has "System-wide platinum appearance" checked in the Appearance control panel. Fixes problem where menu would display as platinum but scrolling arrows would take on specified forecolor.

  v3.1

  Enhancements

• A new property has been added, called trapEvents which will let prevent the menu from always getting activated when the user clicks on the sprite.
• A function, Activate(), has been added which will let you display a menu through Lingo anywhere on the screen.
• The mouseDown/mouseUp event model has changed. Instead a new event and event handler - menuItemSelected, handles the action when a user selects a menu item.
• The selectedSpec can now be set instead of just queried.
• The meta character support has improved so that you can use backslashes, carets and similar characters in the menus themselves.
• A new property called "language" has been added which will return a symbol describing the language type of the Xtra. Currently, we have only English (which should work for all Roman character systems) and Japanese.
• Popup sprites get automatically redrawn when the palette is changed in Director 6 and later.
• Popup Xtra now has a separate runtime Xtra build for each platform which is significantly smaller that the authoring Xtra.
• The hierarchical scrolling triangle (applies to Macintosh only) is smaller.
• The Japanese builds have all of their dialog boxes and alert boxes localized

  Bug Fixes (a partial list)

• A menu with many menu items no longer has a delay when first clicking on the menu, nor is there a delay with the redraw of each menu item. This previously occurring only under Windows.
• AppendItem() and InsertItem() can now add unlimited submenus under Windows.
• If the castlib reference of the menu field for a Popup castmember was higher than the number of available cast libraries, Popup would crash when opening the properties dialog. This no longer happens. Japanese version bug.
• For the Macintosh, Japanese version, the display text and the menu field text will now display Japanese characters.
• The Macintosh 68K Japanese build no longer crashes when creating a new castmember.
• Calling InsertItem() or AppendItem() now works properly with all Japanese characters .

Updating from previous versions

Updating from any 3.1.* release to 3.2

The Shockwave-safe and downloadable version of Popup differs from previous upgrades is a purchased upgrade, so you receive a new serial number and must register again with the new serial number.

You must resave Shockwave movies under the 3.2 version of Popup for the 3.2 Shockwave Xtra to recognize and play them. The Shockwave 7 version of Popup Xtra was engineered solely for use with Shockwave 7 and above. Previous versions of Shockwave do not offer auto-downloading.

Updating from PopMenu Xtra(tm) v.3.0 or earlier

1. Popup Xtra v. 3.1 and above, differs significantly from PopMenu Xtra v. 3.0 and earlier, originally sold by g/matter. The way Popup members store their properties, the way you write Popup scripts and the serial numbers have all changed. For the smoothest upgrade, follow this procedure:

   1. Remove old versions of PopMenu

   Search your Xtras folder for all older versions of PopMenu Xtra and remove them. A demo version of PopMenu was distributed with Director 6 and demo versions were also included with other g/matter products. It is possible for one Xtras folder to contain several copies of PopMenu Xtra lurking in sub folders.

   It is very important to search for and delete all copies of PopMenu before installing Popup Xtra because editing a movie containing the newer Popup members with an older copy of PopMenu in your Xtras menu will cause "cannot read member" error messages in Director authoring. The older PopMenu does not understand the newer Popup file structure.

   2. Install and register Popup Xtra

   Put the authoring version of the Xtra for your platform in Director's Xtras folder. Choose Xtras -> Popup Xtra -> Register and enter the serial number you received from updateStage when you purchased Popup Xtra.

   3. Update Popup members created with the old version

   Open old movies containing PopMenu members and double-click each PopMenu member to bring up the properties dialog box. Click OK to dismiss the box. This process converts the old PopMenu member to the new Popup format. The member will retain all of the properties that were set for it under the old version.

   4. Change scripts written for the old version

   There was no menuItemSelected event in PopMenu v3.0 or earlier. The user's actions were trapped in mouseUp and mouseDown handlers, where old code would examine a property called "the selectedSpec". The old code will not work with Popup v3.1 and above. Old code causes the following symptoms:

• The user's selections seem to reflect the last selected item, not the currently selected item
• The menu does not trap all of the menu selections
• The menu displays really slowly.

  Mousedown handlers in versions 3.0 and earlier were called AFTER a menu selection was made by the user. In version 3.1 on, mouseDown handlers are called BEFORE the user makes a menu selection.

  Move the code that was in a mouseDown or mouseUp handler to the Popup castmember's menuItemSelected handler instead.

  1. Open the castmember script for each member and add the following handler:

     on menuItemSelected me, menuSpec, menuText, memberRef

end menuItemSelected

  2. Cut the script from the on mouseDown handler or the on mouseUp handler (whichever one you were using) where you would examine the selectedSpec or the selectedText.
  3. Copy the script into the menuItemSelected handler.

     For example, if your code was:

     on mouseDown
        if the selectedSpec = "1" then 
           go to frame "Alex"
        else if the selectedSpec = "2" then 
           go to frame "Edgar"
        end if
     end

     
     

     It should be changed to:

     on menuItemSelected me, menuSpec, menuText, memberRef
        if menuSpec = "1" then 
           go to frame "Alex"
        else if menuSpec = "2" then 
           go to frame "Edgar"
        end if
     end

     
     

     There should be nothing in the mouseDown script or the mouseUp script now.

  4. Change previous code references of "the selectedSpec" and "the selectedText" to menuSpec.and menuText.

Standard legal disclaimer

This software is provided "as is", without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability or fitness for a particular purpose. The software or its documentation or samples may include errors or technical inaccuracies. Changes are periodically made to this software, its documentation and samples, and may be incorporated in new versions. Red Eye Software and updateStage may improve or change their products at any time without notice. Neither Red Eye Software nor updateStage assume responsibility for, and disclaim all liability for, errors in this software or its documentation and samples. Neither Red Eye Software not updateStage will be responsible for any damages of any sort under any conditions. While the software contains no known bugs, use it at your own risk. As always, you should make frequent backups of important information.

Some jurisdictions do not allow the exclusion of implied warranties, so the above exclusion may not apply to you.