Ldoc+ Lingo Group:
USER INTERACTION / MOUSEinfo D5/601: clickOn cursor rollOver 6 5 elements new in Director 6.0, ! MANY with Dictionary fixes 601 & 501, + 10 miss from the 'Appendix' 6.0 for USER INTERACTION. Mixed User Elements (7): !+ editable of member ! editable of sprite ! loc of sprite ! locH of sprite ! locV of sprite ! moveableSprite of sprite lastEvent ...see also the 'Menu Elements' in the INTERFACE Lingo Group. Keyboard Elements (13): commandDown controlDown key keyCode keyDownScript keyPressed keyUpScript lastKey on keyDown on keyUp optionDown shiftDown + timeoutKeyDown Mouse Properties (10): ! cursor ! cursor of sprite doubleClick emulateMultiButtonMouse lastClick lastRoll !+ mouseDown !+ mouseUp stillDown + timeoutMouse Mouse Locations (12): ! clickLoc clickOn mouseH mouseV + point(the mouseH,the mouseV) x6!+ mouseCast (outdated -> mouseMember) 6! mouseMember !+ mouseChar ! mouseItem !+ mouseLine ! mouseWord !+ rollover(sprite) = the rollOver Mouse Event Handlers (10): mouseDownScript mouseUpScript ! on mouseDown [me] 6 on mouseEnter [me] 6 on mouseLeave [me] ! on mouseUp [me] 6 on mouseUpOutside [me] 6 on mouseWithIn [me] on rightMouseDown [me] on rightMouseUp [me] -- 6.0 'Appendix' errors for USER INTERACTION: Many elements are missing, see (+) above, 'editableText of sprite' should read: 'editable of sprite'. -- Outdated USER Lingo (1): 6 mouseCast -> mouseMember
[index] _ D5/601 _ 971218:
clickLoc
mouse click location function
6.0 Dictionary Errors, same in 5.0:
"The location is given as a point" = Missing: "The location is given as a point relative to the upper left corner of the movie's stage or window. The 'clickLoc' can be tested but not set. Its default value is 'point(0,0)' as long as no click has yet occured on the stage area. Also works correct on sprites without any scripts and on empty stage areas. The 'clickLoc' doesn't react to mouse clicks outside of the stage or window area in full screen projectors. Doesn't update its value inside a Lingo repeat loop." = Missing: "See Also: the clickOn, rect of the stage, rect of window, point(), the mouseDown, the mouseUp, on mouseDown, on mouseUp" --1. TIP: You can test, but NOT set 'the clickLoc', which returns the location on stage where the mouse was last clicked, relative to the upper left corner of the movie's stage or window (0,0). It returns 'point(0, 0)' with the starting of your movie and as long as no click has yet occured on the stage area. The 'clickLoc' also functions properly if NO sprite channel at all has a script (although some people might give other information). It also returns the correct location 'point(h,v)' when an empty part of the stage is clicked (with 'the clickOn = 0'), but does not reflect mouse clicks outside of the stage or window area in full screen projectors.
2. TIP: You can test, but NOT set the 2 values of 'the clickLoc', which is a 'point(h,v)', by using the undocumented properties 'the locH of the clickLoc' and 'the locV of the clickLoc'.
3. TIP: Remember: The 'clickLoc' will keep its value until the next click location is registered. So if you test 'the clickLoc' multiple times, but the user doesn't click the mouse, you will always get the same old location returned from the last click that happened.
4. TIP: From the '501 ReadMe' and the 6.0 Dictionary: You CANNOT have a Lingo repeat loop checking for a changing return value from 'the clickLoc' function, because during a repeat loop, all occuring 'clickLoc' (and 'clickOn') events and their locations on stage are stored and queued in memory, but NOT served instantly. You will only get the 'clickLoc' value from before the repeat loop started. Once the Lingo repeat loop has finished, the next (stored) 'clickLoc' from the event queue will be delivered and can then be tested. Workaround: Use 'set x=0 .. if (the mouseDown) then set x = point(the mouseH, the mouseV)', and then test 'if listP(x)...' and use 'the locH/locV of x'.
[index] _ D5/601 _ 971218:
clickOn
mouse click sprite function
1. TIP: You can test, but NOT set 'the clickOn', which returns the channel number of the last clicked sprite, provided that either the sprite channel or the sprite's castMember has a script associated with it. The 'clickOn' returns 0, if no click on any sprite has yet occured in your movie, or if the user clicked on sprites without any scripts or on a plain part of the stage.
2. TIP: Remember: The 'clickOn' only detects a sprite click if you have at least an empty script (a dummy '--') in the sprite's or its castMember's script.
3. TIP: Remember: The 'clickOn' will keep its value until the next sprite click event is registered. So if you test 'the clickOn' multiple times, but the user doesn't click on any other sprite, you will always get the same old sprite number returned from the last click that happened.
4. TIP: From the '501 ReadMe' and the 6.0 Dictionary: You CANNOT have a Lingo repeat loop checking for a changing return value from 'the clickOn' function, because during the Lingo repeat loop, all occuring 'clickOn' (and 'clickLoc') events and the numbers of the clicked sprites are stored and queued in memory, but NOT served instantly. You will only get the 'clickOn' value from before the repeat loop started. Once the Lingo repeat loop has finished, the next (stored) 'clickOn' from the event queue will be delivered and can then be tested. Workaround: Use 'set x=0 .. if (the mouseDown) then set x = the rollOver/the mouseCast/the mouseMember', and then test 'if (x > 0)...'.
5. TIP: Important: Windows queues up mouse clicks during the execution of your Lingo handlers, and then sends them straight away to the according sprite(s) after Lingo has finished and returns the control to the score. This can be a problem if the user clicks multiple times or on multiple sprites while Lingo is still reacting to the first click, because any event handlers for those following clicks will be activated one after the other when your first round of Lingo finishes. But your Lingo might have changed castMembers, or the frame, and the delivery of the queued clicks might not be wanted and will most likely trigger the wrong things in the wrong place. One way to minimalize this problem is to include a 'if (the doubleClick) then exit' in all your mouse handlers.
--
EXAMPLEs and workaround:
To avoid your handlers reacting to queued up mouse clicks on Windows (and in 6.0: on Macintosh too!), you can use three techniques: The first one would be to jump to a frame in which all your sprite channels just have a dummy script ('-- dummy') on them to swallow additional mouse clicks; a frame script in that frame would then go to your target frame. The second technique sets Director's primary event handlers for mouse clicks to 'dontPassEvent' (in 6.0: 'stopEvent') and then later releases them. The third technique sets a global 'gClickStop' flag variable to TRUE until you set it back to FALSE in an 'on exitFrame' handler. But you have to keep track and make sure that you don't forget to free the 'gClickStop'! The following three handlers combine all possibilities:
--> This first handler goes into your sprite or cast script: -- on mouseDown -- if clickStop() then exit -- --> do your things here... -- end mouseDown --> This second part goes into your frame script: -- on exitFrame -- clickStop(FALSE) -- --> go to the frame (loop if wanted) -- end exitFrame --> This third handler goes into a movieScript: -- on clickStop param1 -- global gClickStop, gOldDownScript,gOldUpScript -- if voidP(param1) then --> check out the status of gClickStop... -- if (the doubleClick) OR (gClickStop) then return(TRUE) -- set gClickStop = TRUE -- set gOldDownScript = the mouseDownScript set gOldUpScript = the mouseUpScript -- if (version starts "5") then set the mouseDownScript = "dontPassEvent" set the mouseUpScript = "dontPassEvent" -- else if (version starts "6") then set the mouseDownScript = "stopEvent" set the mouseUpScript = "stopEvent" end if -- return(FALSE) -- end if --- set gClickStop = FALSE -- set the mouseDownScript = gOldDownScript set the mouseUpScript = gOldUpScript -- end clickStop
[index] _ D5/601 _ 971218:
cursor
system mouse pointer command
6.0 Dictionary Errors, partly the same in 5.0:
"This command changes the cast member that is used for a cursor." = Should read: "This command changes THE PROJECTOR'S CURSOR NUMBER or the castMember(s) used for Director's MAIN cursor." "...turn it off by setting the cursor to zero." = Not enough; should read: "...turn it off by setting the cursor to 0 or FALSE, which will show the default (or customized) System cursor." = Missing: "You can set, but not test 'cursor', but you can test and set Director's main system cursor by using 'the cursor of sprite 0'." = Missing: "Instead of castMember numbers, you can use member expressions, like 'cursor [member "name"]'." "0 no cursor set" = Not exact; should read: "0 no cursor set; uses system default" "4 watch cursor (Macintosh only)" = True also for Windows! Should read: "4 watch cursor" = Missing: "Director 6.0 projectors include some new cursors, like the Finger (cursor 280), Zoom-In (cursor 302) etc." "On the Macintosh, this statement changes the cursor...cursor 4." = The Example is also for Windows; should read: "This statement changes the cursor...cursor 4." The Example has problems with the proper format of Lingo lines. -- From the '601 ReadMe': Setting the cursor to a bitmap no longer leaks memory. --1. TIP: You CANNOT test Director's main system cursor (like 'cursor 4'), but you CAN use 'the cursor of sprite 0' to test AND set the main cursor in Director 5 and 6.
2. TIP: No stage update is needed when setting Director's main cursor, but it's slightly time consuming.
3. TIP: A valid cursor is either one of Director's built-in cursors (see TIP 21 below) or a LINEAR list with one or two entries: One castMember with the picture of the cursor, and optionally one for the mask of that picture. The list must either contain the 1-bit castMember numbers ('the number of cast 1bitNameOrNumber') or their member IDs ('member nameOrNumber [of castLib x]').
4. TIP: Remember: On Windows, Director's cursors are only 16x16 bits in size (like on Macintosh), but usually Windows allows cursors up to the size of 32x32.
5. TIP: Remember: Director can only use black and white castMembers for cursors, and if you use your own cursor castMembers, occasionally check if all of them have a 'depth of member' of 1-bit (black & white) by selecting them and choosing 'Modify - Transform Bitmap...' to see, if Director shows 'Color Depth: 1 Bit'. Sometimes when you use 'Transform Bitmap...' for some 8-bit castMembers, and by mistake include 1-bit members, those will be transformed to 8-bit as well and won't be valid cursors anymore. Director just doesn't display a cursor that has a castMember in its list with more than 1-bit color depth.
6. TIP: When creating custom cursor members, it's best to have a black and white template with a centered registration point to start with. Create such a 1-bit template member by drawing an empty rectangle box with a 1 pixel border of 18x18. Now cut away the left line and the top line of pixels, leaving a half open box of 17x17. Then place your cursor graphics into the free 16x16 area and adjust their registration points (the cursor's hot spot). This method ensures that Director will take the whole 16x16 area for your cursor (Director crops the overstanding bottom and right line of black pixels), and overwrite all of the old cursor's graphic with it in memory.
7. TIP: If you use custom cursors (lists of castMembers), and you only supply one castMember, the cursor's picture will be transparent on stage, and its black parts will have a kind of 'reverse' ink effect. If you don't want this cursor appearance, you need a second 1-bit castMember that acts as a 'mask background' for the black and white cursor picture. The black parts in the mask bitmap will serve as the 'background' for your cursor picture: any black or white pixel in your cursor picture will be displayed as it is, if the mask has a black pixel in the same place.
8. TIP: On Macintosh, Director always assignes 1-bit castMembers, including cursor casts, the 'System Mac' palette, but don't worry: Director automatically manages the 'black & white' for you on Windows.
9. TIP: Unless you manage to get hold of a special Xtra for Director, you CANNOT have colored cursors. The workaround for this is to use the highest sprite channel for your own (small) 8-bit cursor graphic, hide the system cursor with 'cursor 200', puppetize the sprite channel, and then frequently 'set the loc of sprite x = point(the mouseH, the mouseV)', to move your custom coursor picture around with the mouse. You can include such a line in your global 'on idle' event handler. Or even better to create an object which manages this, and then add it to Lingo's 'the actorList', and use Director's 'stepFrame' events to update the cursor position (see 'the actorList' and 'on stepFrame').
10. TIP: It's best to store cursors (list of cursor castMember numbers) that you frequently use into global variables, or even into a global property list, for an example see 'cursor of sprite'.
11. TIP: Remember to have at least one (dummy) sprite script on one of your sprites in a frame to show any cursor at all; such a dummy script must be of type '#score' and only needs a comment in it: '--', but better use an 'on mouseDown' handler which will swallow any unwanted mouse click as well: 'on mouseDown..dontPassEvent/stopEvent..end'.
12. TIP: If a changed cursor doesn't display properly in your movie, add a 'cursor 200' into your code just before setting the new cursor, because that will set the cursor to 16x16 white on white (nothing) and thus erase the mask of the old cursor in memory.
13. TIP: If you want to hide the cursor with 'cursor 200', but it doesn't disappear, issue a 'cursor -1' (normal arrow cursor) before.
14. TIP: You CANNOT change the cursor to a new list, which contains the same picture, but a different mask for the cursor, because Director won't update the cursor at all then (at least on Macintosh). But you can set cursors to a list containing a new picture and the same mask member as before (which is nice for cursor animations <g>).
15. TIP: Remember: 'the mouseMember' and 'the rollOver' react to the position of the 'regPoint' of your cursor's black and white member on stage (you can set the 1-bit cursor member's registration point yourself in Director's Paint window), but 'the mouseChar', 'the mouseItem', 'the mouseWord', and 'the mouseLine' all test the absolute center of the cursor.
16. TIP: It's a good habit to have the line 'cursor 4' in the LINGO.INI file for every projector, to keep the system's watch cursor up until your first movie starts playing (also add 'set the centerStage = TRUE' into the LINGO.INI <g>).
17. TIP: When jumping to another movie, it's best to turn the 'puppet' and 'cursor' of all sprites off (and display a watch 'cursor 4' to communicate a waiting time), as there have been problem reports when puppets and cursors are still active (see 'on stopMovie').
18. TIP: For myself, I experienced some unreliable behavior when setting the system 'cursor'. My workaround is to have a full-screen background graphic or colored filled shape in sprite channel one, and then set 'the cursor of sprite 1' to the same cursor as my system 'cursor' (or even leave a 'cursor 4' in the background). The full-screen sprite in channel one will always have an 'on mouseDown..dontPassEvent/topEvent..end mouseDown' script on it to make sure a cursor is shown at all in that frame, and also to swallow up all user clicks on the background area. If the background is a colored shape, I can also change 'the foreColor of sprite 1' to change the overall color of my stage without setting 'the stageColor', because the new color will not affect the screen color around my projector if I run my projector 'Full Screen'. For a problem with shapes in 16-bit, please see 'foreColor of sprite'.
19. TIP: During author-time, any custom cursor in movies-in-a-window (MIAWs) will flicker, but no problem during run-time. See Gretchen's 501 BugList for the problems with cursors in MIAW's.
20. TIP: On Windows only, when a digital AVI video playing has reached its end, the System will bring up the watch cursor (big hour glass). This is one of the situations where the system overrides Director's control of its own cursors. The workaround is to set 'the movieRate of sprite' to 0/FALSE for the video sprite when its 'movieTime of sprite' has almost reached its 'stopTime of sprite' or the 'duration of member'. This will give the cursor control back to your projector or Shockwave.
21. TIP: Here is the list of additional (16x16) cursors that are available in 6.0 projectors:
no cursor set = 0 (shows default/customized system cursor) Arrow Pointer = -1 (black arrow with white border) I-Beam = 1 (text insertion caret) Crosshair = 2 (very thin big cross) Crossbar = 3 (fat cross + white border + middle hole) Watch = 4 (small wrist watch at 9 o'clock) Blank = 200 (hidden cursor, invisible) Help = 254 (question mark + cross in left corner) Finger = 280 (pointing hand) Hand = 260 (open hand) Closed Hand = 290 (fist, seen from above) No Drop Hand = 291 (closed hand with no-entry sign on it) Copy Closed Hand = 292 (closed hand with plus sign on it) Pencil = 256 (thin pencil) Eraser = 257 (bordered square) Select = 258 (thin cross) Bucket = 259 (paint bucket) Lasso = 272 (thin round lasso) Dropper = 281 (eye dropper, pipette) Air Brush = 301 (fountain-pen) Zoom In = 302 (lense with plus sign in it) Zoom Out = 303 (lense with minus sign in it) Vertical Size = 284 (move up/down) Horizontal Size = 285 (move left/right) Diagonal Size = 286 (big doubled cross) Arrow Down = 282 (thin arrow down) Wait Mouse Click = 283 (thin arrow down with 3 beams on top) White Arrow = 293 (same as the normal black arrow cursor) Watch Hands = 300 (two thin lines to left and right) Zoom = 304 (plain lense)22. TIP: On Macintosh only, you can add external cursor resources into the projector file with the program 'ResEdit'.
23. TIP: For examples, see 'cursor of sprite' below.
[index] _ D5/601 _ 971218:
cursor of sprite
sprite mouse pointer property
6.0 Dictionary Errors, partly the same in 5.0:
"On the Macintosh, this sprite property determines the cursor resource that is used..." = Includes Windows! Should read: "This sprite property determines THE PROJECTOR'S CURSOR NUMBER or the castMember(s) used..." "...you turn it off by setting the cursor to 0." = Not exact; should read: "...you turn it off by setting 'the cursor OF SPRITE' to 0, which will show either the cursor from a sprite underneath the specified sprite, or Director's main cursor, or the default (or customized) System cursor." = Missing: "Instead of castMember numbers, you can use member expressions, like 'set the cursor of sprite x = [member "name"]." = Missing: "You can test and set Director's main system cursor by using the expression 'the cursor of sprite 0'." "The 'cursor of sprite' property is an integer..." = Not exact; should read: "The 'cursor of sprite' property CAN ALSO BE an integer..." = Missing: "Director 6.0 projectors include some new cursors, like the Finger (cursor 280), Zoom-In (cursor 302) etc." "To hide the cursor, set 'the cursor' to 200..." = Not exact; should read: "To hide the cursor, set 'the cursor OF SPRITE' to 200..." -- From the '601 ReadMe': Setting the cursor to a bitmap no longer leaks memory. Sprite cursors are now ignored for invisible sprites. -- "To use custom cursors, set the cursor of sprite property to an external resource that contains the cursor." = The 5.0 Dictionary should read: "To use custom cursors, set the cursor of sprite property to a list containing one or two 1-bit cursor castMembers." = Also the 5.0 Dictionary uses a 'cursor' command in its Example. --1. TIP: You can use 'the cursor of sprite 0' to test AND set the main (system) cursor in Director 5 and 6.
2. TIP: With the new behaviors and sprite events in 6.0, you can very easily apply cursors to sprites by using a script containing two handlers: 'on beginSprite me .. set the cursor of the spriteNum of me = someCursor .. end', plus 'on endSprite me .. set the cursor of the spriteNum of me = 0 .. end'. Just make sure that the sprite is joined across it's life span.
3. TIP: No stage update or puppet is needed when setting the 'cursor of sprite': It will have an immediate and persistent display on stage, but it's slightly time consuming.
4. TIP: The 'cursor of sprite' is the only SPRITE property that takes effect on stage immediately, even in a tight Lingo repeat loop (and the 'cursor of sprite' and the 'visible of sprite' are the only two sprite properties that persist when you change them, without the sprite needing to be puppetized).
5. TIP: Remember to have at least one (dummy) sprite script on one of your sprites in a frame to show any cursor at all.
6. TIP: You can also set a 'cursor of sprite' for a channel that has no member in it, but best to avoid this: That channel's cursor might appear all over the place... ;-)
7. TIP: If a changed sprite cursor doesn't display properly, use a quick 'set the cursor of sprite x = 200' before setting the new cursor, because that will also erase the mask of the old sprite cursor in memory.
8. TIP: If you want to hide a sprite's cursor with 'set the cursor of sprite x = 200', but it doesn't disappear, issue a 'set the cursor of sprite x = -1' (normal arrow) before.
9. TIP: On Macintosh, you CANNOT change 'the cursor of sprite' to a new list, which contains the same picture, but a different mask for the cursor, because Director won't update the cursor at all then.
10. TIP: When jumping to another movie, it's best to turn the 'puppet' and 'cursor' of all sprites off and display a watch 'cursor 4' to communicate a waiting time, as there have been problem reports (in 5.0) when puppets and cursors are still active (see 'on stopMovie').
11. TIP: The 'cursor of a sprite' will still show in the rectangle of that sprite, even if the sprite is NOT THERE anymore and the sprite channel is empty -- or if 'the visible' of that sprite has been set to FALSE (not anymore in 6.0). Check out the entry on 'rollOver' in the Dictionary for more info, and possibly this might have changed in 5.01/6.0. Workarounds for this problem: Set the 'puppet' for that sprite to TRUE while it's still on stage, then either set the locV of that sprite above the menu bar: 'set V = the locV of sprite x .. if (V > -1) then set the locV of sprite x = V - 500 .. updateStage', or change the member of that sprite to a one-pixel bitmap, which has its 'regPoint' way below it, so the dot will actually appear outside above the stage area. Then go to some other frame and possibly turn the 'puppetSprite' off after arriving. I usually add single pixel sprites all over the score into the channels, where sprites with cursors only appear sometimes. This way I don't have to turn 'the cursor of sprite x' on and off repeatedly. With the new Behavior concept in 6.0, you can use the 'on beginSprite me' and 'on endSprite me' event handlers to set and reset a sprite's cursor.
12. TIP: For more info and problems, see the Ldoc+ entry on 'cursor' above.
--
EXAMPLEs:
The following lines will change the general cursor and a sprite cursor to custom made cursors, which consist of a list with two castMember number entries: a 1-bit member serving as black and white picture, and a 1-bit mask for your cursor:
cursor [member "myCursor", member "myCursorMask"] -- set myHand = [member "myHand", member "myHandMask"] --> ...or if your 1-bit cursor mask member is in the castLib --> right behind the cursor's black & white picture member: -- set myHand = the number of member "myHand" set myHand = [myHand, myHand + 1] -- set the cursor of sprite 101 = myHand --> ...or create a global cursor property list: -- global gCursorList if voidP(gCursorList) then set gCursorList = [:] -- if NOT (getaProp(gCursorList, #Hand) then setaProp(gCursorList, #Hand, myHand) -- set the cursor of sprite 101 = the Hand of gCursorList -- put listP(the cursor of sprite 101) -- 1 put ilk(the cursor of sprite 101, #linearList) -- 1
[index] _ D5/601 _ 971218:
mouseCast
mouse rollover function
6.0 Dictionary Error:
= Missing from the docs: "This is obsolete, use 'mouseMember' instead." --1. TIP: The 'mouseCast' function used to return the 'number of member' under the mouse, or -1 when the mouse is not over any sprite (just over a plain part of the stage), because then it's also not over any castMember. The returning value of -1 has been re-installed with the 501 update. In Director 5.00, it temporarily returned 0 in such a case. To be prepared for any future changes, just test 'if (the mouseCast < 1)' and 'if (the mouseCast > 0)'.
2. TIP: In 6.0, the 'mouseCast' is outdated. The new 'mouseMember' function returns the member expression of the HIGHEST sprite under the cursor, in the format '(member 57 of castLib 2)', or 'Void' if there is NO sprite under the cursor.
[index] _ D5/601 _ 971218:
mouseChar / mouseItem / mouseLine / mouseWord
mouse text rollover functions
6.0 Dictionary Errors in 'mouseChar', partly the same in 5.0:
'...set member "Instructions" = "Please..." ' = Wrong syntax, doesn't work! Example 1 should read: '...set THE TEXT OF member "Instructions" = "Please..." ' "set currentChar = char (the mouseChar) of member (the mouseMember)" = No work! Example 2 should read: "set currentChar = char (the mouseChar) of THE TEXT OF the mouseMember" "set thisField to the member of sprite (the clickOn)" = Example 3 should read: "set thisField to the mouseMember" ...'repeat while the stillDown' does NOT work for a quick mouse click! Better use: 'repeat while TRUE...', and then later test: 'if (the mouseUp) then exit repeat'. "...hilite word MC of field thisField..." = Wrong Example 3 for 'mouseChar'; should read: "...hilite CHAR MC of field thisField..." --6.0 Dictionary Errors in 'mouseItem', partly the same in 5.0:
"...number of the item that is under the pointer..." = Should read: "...number of the item that is under the center of the CURSOR..." "If the mouse is not over a field..." = Not exact; should read: "If the mouse is not over a field or is in the gutter of a field..." "if the mosueItem = - 1 then ... endif" = Example 1 should read: "if the mosueItem = - 1 then ... end if" "set currentItem = item (the mouseItem) of member (the mouseMember)" = No work! Example 2 should read: "set currentItem = item (the mouseItem) of THE TEXT OF the mouseMember" "set thisField to the member of sprite (the clickOn)" = Example 3 should read: "set thisField to the mouseMember" ...'repeat while the stillDown' does NOT work for a quick mouse click! Better use: 'repeat while TRUE...', and then later test: 'if (the mouseUp) then exit repeat'. "set MI to the mouseWord" = Wrong Example 3 for 'mouseItem'; should read: "set MI to the mouseItem" "if MI <> lastWord then..." = Wrong Example 3 for 'mouseItem'; should read: "if MI <> lastItem then..." --6.0 Dictionary Errors in 'mouseLine', partly the same in 5.0:
"...number of the line that is under the pointer..." = Should read: "...number of the line that is under the center of the CURSOR..." "If the mouse is not over a field..." = Not exact; should read: "If the mouse is not over a field or is in the gutter of a field..." = Missing: "A line is a sequence of characters delimited by a RETURN." "This statement assigns the number of the item under the cursor..." = Example 2 should read: "This statement assigns the number of the LINE under the cursor..." "set currentLine = line (the mouseLine) of member (the mouseMember)" = No work! Example 2 should read: "set currentLine = line (the mouseLine) of THE TEXT OF the mouseMember" "set thisField to the member of sprite (the clickOn)" = Example 3 should read: "set thisField to the mouseMember" ...'repeat while the stillDown' does NOT work for a quick mouse click! Better use: 'repeat while TRUE...', and then later test: 'if (the mouseUp) then exit repeat'. "...hilite word ML of field thisField..." = Wrong Example 3 for 'mouseLine'; should read: "...hilite LINE ML of field thisField..." --6.0 Dictionary Errors in 'mouseWord', partly the same in 5.0:
"If the mouse is not over a field..." = Not exact; should read: "If the mouse is not over a field or is in the gutter of a field..." = Missing: "A word is a sequence of characters delimited by spaces." "set currentWord = word (the mouseWord) of member (the mouseMember)" = No work! Example 2 should read: "set currentWord = word (the mouseWord) of THE TEXT OF the mouseMember" "set thisField to the member of sprite (the clickOn)" = Example 3 should read: "set thisField to the mouseMember" ...'repeat while the stillDown' does NOT work for a quick mouse click! Better use: 'repeat while TRUE...', and then later test: 'if (the mouseUp) then exit repeat'. --1. TIP: Use these mouse functions to get the NUMBER of the chunk (char, item, line, word) of the field sprite the mouse is over. All 4 of these functions return -1, if the cursor is not over ANY chunk of a field on stage, or if the mouse is over some inappropriate part of a field like the border or scroll bar.
2. TIP: If the mouse is over empty space beyond the LAST chunk of the field, these functions return the number of the last chunk of that field.
3. TIP: 5.0: All these functions react to the center of your cursor, and NOT to its 'regPoint' (its hot spot).
4. TIP: To get the content of the text chunk under the mouse (the char, item, line, or word itself), retrieve that chunk from the field by using its number, e.g. 'set x = word (the mouseWord) of the text of the mouseMember'.
5. TIP: Test 'the mouseMember', 'the type of the mouseMember', 'the name of the mouseMember', or 'the number of the mouseMember' to see if and which field the mouse is over. Use 'the text of the mouseMember' to work with its text.
6. TIP: Gretchen's 601 BugList mentions that left or center justified fields report the wrong 'mouseLine' if the user clicks on the blank space to the left of the text, between two lines. (Mac)
7. TIP: Although the 6.0 Dictionary states that the term 'field' is outdated and recommends to use 'member' instead, the 'hilite' command does NOT work with 'member': It still expects 'field nameOrNumber'.
[index] _ D5/601 _ 971218:
mouseDown
mouse state function
6.0 Dictionary Errors, partly the same in 5.0:
= Missing: "Can be tested, but not set. Its default value is FALSE (0). The 'mouseDown' functions updates in a Lingo repeat loop." "repeat while the mouseDown = FALSE .. beep ..." = Example 1 is stupid: On a Macintosh, this will cue up the System beeps and drive another Lingoist crazy...! "...instructs Lingo to exit the repeat loop or handler... 'if the mouseUp then exit' " = Example 2 will exit the handler! Should read: "...'if the mouseDown then exit repeat' " = Missing: "See Also: ... the stillDown, the clickOn, the clickLoc" --1. TIP: Take into consideration that the default value for 'the mouseDown' is FALSE (0), as it constantly reflects the status of the (left) mouse button, and it's only TRUE (1) as long as the mouse is being pressed. For important info from the '6.0 ReadMe' see 'on mouseDown [me]'.
2. TIP: When using 'repeat while (the mouseDown)' or 'repeat while (the stillDown)' to do something on mouse click and while the mouse is pressed, consider that the mouse click could have been a very quick one, and by the time you test 'the mouseDown' or 'the stillDown' for the first time the mouse is up again. It's ALWAYS better to use: 'repeat while TRUE...', and then later test: 'if (the mouseUp) then exit repeat'.
3. TIP: Remember: You CANNOT test 'the stillDown' inside a Lingo repeat loop, as the docs mention. But you can use it in the test area of a loop: 'repeat while (the stillDown)' is ok. But I would suggest to NEVER test 'the stillDown', but to use the construction from the 2nd TIP above instead.
--
EXAMPLEs:
repeat while TRUE -- --> do something... --> updateStage -- if (the mouseUp) then exit repeat -- end repeat
[index] _ 601 _ 971218:
mouseMember
6.0 mouse rollover function
6.0 Dictionary Errors:
"...the cast member assigned to the sprite that is under the cursor..." = Not exact; should read: "...the cast member assigned to the HIGHEST sprite that is under the cursor..." "...replaces 'mouseCast'..." = Missing: "The 'mouseCast' returned the 'number of member' under the cursor, or -1 if none." "...to use this function multiple times in handler..." = Typo: "...to use this function multiple times in A handler..." "...does not distinguish between the cast member and the cast number..." = Works differently than this whole darn stupid paragraph describes: "...indicates the member in the format '(member x of castLib y)'..." "set lastMember = the mouseMember(the mouseMember)" = Example 2 should read: "set lastMember = the mouseMember" --TIP: The 'mouseCast' function used to return the 'number of member' under the mouse, or -1 when the mouse is not over any sprite (just over a plain part of the stage), because then it's also not over any castMember. The returning value of -1 has been re-installed with the 501 update. In Director 5.00, it temporarily returned 0 in such a case. To be prepared for any future changes, just test 'if (the mouseCast < 1)' and 'if (the mouseCast > 0)'. In 6.0, the 'mouseCast' is outdated. The new 'mouseMember' function returns the member expression of the HIGHEST sprite under the cursor, in the format '(member 57 of castLib 2)', or 'Void' if there is NO sprite under the cursor.
[index] _ D5/601 _ 971218:
mouseUp
mouse status function
6.0 Dictionary Errors, partly the same in 5.0:
= Missing: "Can be tested, but not set. Its default value is TRUE (1). The 'mouseUp' functions updates in a Lingo repeat loop." "The beep stops when the user clicks the mouse button: ..." = Example 1 should read: "The BEEPING stops when the user RELEASES the mouse button: ..." "repeat while the mouseUp = FALSE .. beep ..." = Example 1 is stupid: On a Macintosh, this will cue up the System beeps and drive another Lingoist crazy...! "...instructs Lingo to exit the repeat loop or handler... 'if the mouseUp then exit'" = Example 2 will exit the handler! Should read: "...'if the mouseUp then exit repeat'" = Missing: "See Also: ... the stillDown, the clickOn, the clickLoc" --TIP: Take into consideration that the default value for 'the mouseUp' is TRUE (1), as it constantly reflects the status of the (left) mouse button, and it's only FALSE (0) as long as the mouse is being pressed. For important info from the '6.0 ReadMe' see 'on mouseDown [me]'. See 'mouseDown' for additional advice.
[index] _ D5/601 _ 971218:
on mouseDown [me]
mouse event handler
6.0 Dictionary Errors, partly the same in 5.0:
"Syntax: on mouseDown ..." = Not exact; should read: "Syntax: on mouseDown me ..." "Lingo searches these locations...for an 'on mouseDown' handler: primary event handler, sprite script, script of a cast member,..." = Not exact; should read: "If 'the mouseDownScript' is set, Lingo sends the event there, otherwise Lingo searches these locations...for an 'on mouseDown' handler: sprite script, script of the sprite's castMember,..." "See Also: on enterFrame ... on stepMovie ... keyDownScript..." = What's this stupid assortment? Should read: "See Also: the mouseDownScript, the mouseDown, the mouseUpScript, on mouseUp, the mouseUp, the stillDown, the clickOn, the clickLoc, the spriteNum of me, the currentSpriteNum" -- From the '6.0 ReadMe': When the mouse is clicked, the topmost sprite under the cursor (in terms of channel number) which has a mouse opaque behavior attached to it "eats" the event. A mouse opaque behavior is a score script which either contains no handlers, or which contains a handler for mouseUp, mouseDown, rightMouseUp, or rightMouseDown. This is different behavior than Director 5. In Director 5, the first sprite under the mouse with ANY script would "eat" the event. To accommodate attaching scripts to sprites explicitly to create mouse-opaque screen areas, we allow handlerless scripts to eat mouse up/down events. If a behavior handling a mouseUp/Down event issues a "pass", then the message is NOT forwarded to the next sprite under the mouse with a mouse opaque handler, but rather to the sprite's cast member (and then on to the frame script, and then the movie script). This means multiple sprites will not receive the same mouseUp/Down message automatically. Of course, it is possible to write lingo code to get around this. -- From the '601 ReadMe': Rollover and mouse messages are no longer sent to sprites while the mouse is over parts of the sprite that are off the stage. --TIP: See 'on mouseUp [me]' for some problems with combinations of 'on mouseDown' and 'on mouseUp' handlers in the same script.
--
EXAMPLE:
The following is a rollOver behavior for Director 5.0, but it's also good for 6.0. Everything is done in one single 'on mouseDown' handler, where the member of the sprite is switched to the next member in the same castLib. If you'd like to enhance this handler then isolate the rollOver testing in a seperate handler which returns 'myRollOn' as soon as the mouse is up, and make your actions depending on a return value of TRUE:
on mouseDown -- puppetSound 3, "aClickSound" -- set mySprite = the clickOn set myOldNum = the memberNum of sprite (mySprite) set myRollOn = FALSE --- repeat while TRUE ---- if rollOver(mySprite) then -- if NOT (myRollOn) then set myRollOn = TRUE set the memberNum of sprite (mySprite) = myOldNum + 1 updateStage end if --- else if (myRollOn) then set myRollOn = FALSE set the memberNum of sprite (mySprite) = myOldNum updateStage end if -- if (the mouseUp) then exit repeat -- end repeat ---------- if (myRollOn) then set the memberNum of sprite (mySprite) = myOldNum updateStage end if -- if NOT (myRollOn) then return(FALSE) -- --> ...your actions here... -- end mouseDown
[index] _ D5/601 _ 971218:
on mouseUp [me]
mouse event handler
6.0 Dictionary Errors, partly the same in 5.0:
"Syntax: on mouseUp ..." = Not exact; should read: "Syntax: on mouseUp me ..." "Lingo searches these locations...for an 'on mouseUp' handler: primary event handler, sprite script, script of a cast member,..." = Not exact; should read: "If 'the mouseUpScript' is set, Lingo sends the event there, otherwise Lingo searches these locations...for an 'on mouseUp' handler: sprite script, script of the sprite's castMember,..." "...put the handler in a sprite script." = Missing: "Note: When the user clicks the mouse on one sprite, then pulls the mouse away and releases the mouse over another sprite, that different sprite will receive the 'mouseUp' event message. To activate a mouseUp action only when the user has also clicked the sprite before, test 'if (the clickOn = the spriteNum of me)'." "on mouseUp puppetSprite 10, true set the memberNum of sprite 10 ¬ to the number of member "Dimmed" end mouseUp" = Example 1 is buggy; should read: "on mouseUp me set the member of sprite (the spriteNum of me) = member "Dimmed" end mouseUp" ...NEVER use the 'memberNum of sprite' together with a 'number of member' if you have multiple castLibs! "See Also: on enterFrame ... on stepMovie ... keyDownScript..." = What's this stupid assortment? Should read: "See Also: the mouseUpScript, the mouseUp, the mouseDownScript, on mouseDown, the mouseDown, the stillDown, the clickOn, the clickLoc, the spriteNum of me, the currentSpriteNum" -- From the '6.0 ReadMe': See 'on mouseDown' above for important info. -- From the '601 ReadMe': Rollover and mouse messages are no longer sent to sprites while the mouse is over parts of the sprite that are off the stage. --1. TIP: Do NOT use 'on mouseDown' and 'on mouseUp' handlers together in one sprite or cast script, especially not if your 'mouseUp' handler is supposed to reset things that were changed during the 'mouseDown' handler before, because the user might release the mouse over a different sprite than the one he clicked on. When the user presses the mouse, moves it away from the sprite, and then releases the mouse button over another sprite, the original sprite will NOT receive that 'mouseUp' event. The 'mouseUp' will be sent to the script of the new sprite under the mouse pointer (even in a different frame, if the 'mouseDown' handler took him there), which might NOT be what you want to have activated at that point. Instead, use a 'repeat while (the mouseDown) .. end repeat' in your 'on mouseDown' handlers to wait for the release of the mouse button, and place your code for mouseUp actions there. See 'on mouseDown [me]' for an EXAMPLE.
2. TIP: If you want to have a modern rollOver button behavior for a sprite (depress on click, and adjust to if the mouse is over it or not), you need to have your actions take place in an 'on mouseDown' handler instead of 'on mouseUp', or you have to check if the sprite recieving the 'mouseUp' and other mouse events is the same sprite as the one the user has originally clicked. Macromedia's rollover behavior example from the external behavior library is not worth a cent: You click a sprite, roll off to another sprite while keeping the mouse pressed, and other sprites react to 'mouseEnter' and other mouse events! Finally when you release the mouse over a different sprite, that sprite will react to 'mouseUp' and its action will take place, although the sprite itself was never clicked! So before having actions in 'on mouseUp' handlers: ALWAYS test something like 'if NOT (the clickOn = the spriteNum of me) then exit'...
[index] _ D5/601 _ 971218:
rollOver()
mouse sprite function
6.0 Dictionary Error:
"When the cursor is currently over the sprite, 'rollOver' returns TURE (1)." etc. = The first and second bullet should read: "When the cursor is currently over sprite whichSprite, 'rollOver(whichSprite)' returns TURE (1)." etc. "set currentLocation = the rollover case rollover(currentLocation) of... " = Who ever writes these stupid examples which CANNOT work: 'rollOver(currentLocation)' can either be TRUE or FALSE. Example 2 should read: "set currentLocation = the rollOver case (currentLocation) of... " -- From the '601 ReadMe': Rollover and mouse messages are no longer sent to sprites while the mouse is over parts of the sprite that are off the stage. --1. TIP: Used without an argument, the 'rollOver()' function as well as 'the rollOver' property returns the number of the HIGHEST sprite channel the cursor is over, or 0 if the mouse it over a plain part of the stage. This makes the handling of rollovers easy by first setting a variable to 'the rollOver' and then testing that variable instead.
2. TIP: A sprite's rollover can be detected, whithout the sprite having a sprite or cast script assigned to it (as opposed to 'the clickOn').
3. TIP: Testing 'rollOver(channelNumber)' will return TRUE for all sprites that are under the mouse at the same time. If you have a button over a full-screen background, then 'rollOver(buttonChannel)' as well as 'rollOver(backgroundChannel)' will return TRUE. If you have to use a Lingo repeat loop to test 'rollOver(i)', then be sure to test from the top channel down to the lower channel (and exit the repeat loop when you found the rolled over sprite), example: 'repeat with i = 48 down to 1...'. Using the 'rollOver()' function issues a system call, which is a little time-consuming. Avoid calling 'rollOver(whichSprite)' too many times in a repeat loop, exit the loop as soon as your rollover is detected, or better use 'set x = the rollOver' instead, which straight away gives you the highest sprite under the cursor.
4. TIP: Remember: The 'rollOver' returns TRUE for the whole of the bounding rectangle of sprites, not just their pixels or matte area, in opposition to 'the mouseCast'. (Although in 501, I have seen a rollOver react only to the matte area of a sprite. Possibly in this case 'rollOver(channelNumber)' and 'set x = the rollOver' act different...)
5. TIP: Remember: If you use your own cursor castMembers, 'rollOver' checks the position of the 'regPoint' of your cursor's black and white member on stage, and you can set the 1-bit cursor member's registration point yourself in the 'Paint Window'.
6. TIP: The 'rollOver(channelNumber)' for a sprite will still return TRUE in the whole of the bounding rectangle of that sprite, even if the sprite is NOT there anymore and the sprite channel is empty -- or if 'the visible' of that sprite has been set to FALSE (again: might have changed in 501). Workarounds for that problem:
--
(a) Test if 'the memberNum' and/or 'the visible' of the sprite in question is > 0.
(b) Set the 'puppet' for that sprite to TRUE while it's still on stage, then either set the locV of that sprite above the menu bar: 'set V = the locV of sprite x..if (V > -1) then set the locV of sprite x = V - 500..updateStage', or change the member of that sprite to a one-pixel bitmap, which has its 'regPoint' way below it, so the dot will actually appear outside above the stage area. This will also move the sprite's script and its cursor out of reach. Then go to some other frame and possibly turn the 'puppetSprite' off after arriving.
EXAMPLEs:
Also see 'on mouseDown [me]' for an EXAMPLE. Following are some results when the 'regPoint' of the cursor is over the bounding box of the sprite in channel 41:
set mySprite = the rollOver put mySprite -- 41 put the rollOver -- 41 --> ...or use: -- repeat with mySprite = 48 down to 1 -- if rollOver(mySprite) then --> ...possibly do something... exit repeat end if -- end repeat -- put (mySprite = 41) -- 1
[index] _ 601 in 1/97:
stillDown
mouse evaluation function
TIP: Remember: You CANNOT test 'the stillDown' INSIDE a repeat loop (see 'mouseDown').
|
