The SkyLight Pro control allows easy integration of QuickTime* for applications developed in Visual Basic, MFC and many other development environments which support COM (ActiveX) controls. It provides full support for QuickTimeVR.
Putting a QuickTime movie into your application is now as simple as placing a SkyLight Pro control on your form, calling the QTML_Initialize method to make the connection to QuickTime, and setting the FileName property to load a movie. And remember you can also load pictures - PICT, GIF, BMP, JPEG and sounds - WAV.
SkyLight Pro 1.2 brings the following new features:
plus a bundle of useful new methods and properties - see below.
Example:
Private Sub Form_Load()
Dim e&
e& = SkyLight1.QTML_Initialize
If e& <> 0 Then MsgBox "Unable to Initialize QuickTime!" & Chr$(13) & CStr(e&)End Sub
Private Sub Command1_Click()
SkyLight1.FileName = "c:\windows\sample.mov"
End Sub
Private Sub Form_Unload()
SkyLight1.FileName = ""
DoEvents
SkyLight1.QTML_TerminateEnd Sub
A number of sample applications are included in the Samples folder:
Copies the current selection in a movie to the clipboard.
Cuts the current selection out of a movie to the clipboard.
Draws the current image or movie frame into device context theHDC at location (x,y), width w and height h.
This method is useful if you want to draw the current frame into another window (e.g. a PictureBox in VB)
For example, you can load a movie into a hidden SkyLight control, and use DrawPicture to draw the frames wherever you like on a drawing surface.
Finds a string in a text track of the movie, and returns the movie time at which the text was found, or -1 if not found.
SearchString - The text string to be found
TrackIndex - Index into the text tracks of the track to be searched. First text track = 1, etc.
StartTime - Movie time from which the search will start
HiliteColor - RGB color to highlight the found text if kSkyFindTextHiliteText flag is used
SearchFlags - Flags which can be combined to determine how the search will operate
kFindTextEdgeOK &H0 Okay to find text at specified sample time kFindTextCaseSensitive &H2 Case sensitive search kFindTextReverseSearch &H4 Search from sampleTime backwards kFindTextWrapAround &H8 Wrap search when beginning or end of movie is hit kFindTextUseOffset &H10 Begin search at the given character offset into sample rather than edge kSkyFindTextGoToTime &H100000 If found, jump to this position in the movie kSkyFindTextHiliteText &H200000 Hilite the text which was found
Loads a particular track or part of a track into RAM.
TrackIndex - Index number of the track to be loaded into RAM
Time, Duration - Allows you to specify a portion of the track to load. The time parameter contains the starting time of the track segment to load. The duration parameter specifies the length of the segment to load.
Flags - Gives you explicit control over what is loaded into memory and how long to keep it around.
kKeepInRam &H0 Renders all data loaded with this flag set as nonpurgeable kUnkeepInRam &H2 Renders all indicated data purgeable kFlushFromRam &H4 Purges all indicated data from memory, unless currently in use kLoadForwardTrackEdits &H8 Load only the data around edits for playing forwards kLoadBackwardTrackEdits &H10 Load only the data around edits for playing backwards
Creates a new empty movie together with a movie controller bar of the same width as the control.
Selections from other movies, images, sounds or text can then be pasted into this new movie.
The ErrorCode property will be 0 if the movie was created successfully, or will contain an error code if not.
Saves the currently loaded movie to a new movie
file, complete with any edits which may have taken place. Use the MovieChanged property to determine if the movie has
been edited and needs to be saved. FileName should
contain a full path.
The ErrorCode property will be 0 if the movie was
saved successfully, or will contain an error code if not.
Pastes the contents of the clipboard into the movie at the current location.
Starts to play a movie from its current position. Equivalent to setting PlayRate = 1.0.
Same as play, except the movie is prerolled (i.e. prepared for playback) first.
Initializes the connection with QuickTime and returns 0 if successful, or an error code otherwise.
This function need only be called once in your application, for all instances of the SkyLight control. It is normally called in your application initialization code - e.g. in your Form_Load or Main routine - and must be called before any QuickTime related methods and properties of the control are used.
Terminates the connection with QuickTime. Should be called before your application quits. It is good practice to unload all files before calling QTML_Terminate by setting FileName = "" for each control.
Initializes the connection with QuickTimeVR and returns TRUE if successful.
This function need only be called once in your application, for all instances of the SkyLight control. It is normally called in your application initialization code - e.g. in your Form_Load or Main routine - and must be called after QTML_Initialize and before any QuickTimeVR related methods and properties of the control are used.
Terminates the connection with QuickTimeVR. Should be called before your application quits and before QTML_Terminate. It is good practice to unload all files before calling QTVR_Terminate by setting FileName = "" for each control.
Enables/Disables one or more QTVR hot spots. Returns TRUE if successful.
EnableFlag The kind of hot spot or hot spots to enable or disable.
kQTVRHotSpotID 0 Select a single hot spot by its hot spot ID (specified by the
HotSpotValue parameter)kQTVRHotSpotType 1 Select all hot spots of a hot spot type (specified by the
hotSpotValue parameter).kQTVRAllHotSpots 2 Select all hot spots in the current node.
HotSpotValue The desired hot spot or spots, relative to the specified enabled flag. If enableFlag is kQTVRHotSpotID, this parameter specifies a hot spot ID. If enableFlag is kQTVRHotSpotType, this parameter specifies a hot spot type. If enableFlag is kQTVRAllHotSpots, this parameter should be set to zero.
State A Boolean value that indicates whether the specified hot spots are to be enabled (TRUE) or disabled (FALSE).
Jump to any valid QTVR node within a multi-node movie. Returns TRUE if successful. Will also trigger a
NodeID The ID of the node to jump to or one of the following constants:
kQTVRCurrentNode The current node. (Moving to the current node has the effect
of restoring the default view in that node.)kQTVRPreviousNode The previous node. The QuickTime VR Manager maintains a list
(which is limited only by the available memory) of the nodes visited.kQTVRDefaultNode The default node in the scene.
Trigger any hot spot within a QTVR scene. Returns TRUE if successful. Will also trigger a
HotSpotID The ID of the hot spot to trigger. This hot spot must be in the current node.
Selects the entire movie. This is the same as setting StartTime = 0 and StopTime = Duration
Step forward (Frames = positive) or backward (Frames = negative) in a movie by a certain number of frames. Equivalent to clicking on the step forward and step backward buttons on the movie-controller.
Undoes the last edit operation - Cut, Copy or Paste.
Sets the background color of the control whenever a movie or image is not loaded.
Read/Write - Design mode and Run mode.
Sets the color of the single pixel wide border around the control.
Read/Write - Design mode and Run mode.
Determines whether the single pixel wide border around the control is visible.
It is usually a good idea to explicitly set this property before loading a file into the control.
Read/Write - Design mode and Run mode.
Gets the duration of the currently loaded movie in units of the movie TimeScale.
Read Only - Run mode when a movie is loaded.
Returns the error code from the last action. For example, after setting the FileName property, you can check if the file loaded successfully.
Read Only - Run mode.
Some common error codes are listed below. See QuickTime documentation (e.g. errors.h) for error codes.
-43 File not Found -2048 Invalid file - can't be loaded by QuickTime -2093 Unable to load QuickTime -2095 QuickTime not initialized
Sets the name of a file to load into the control. FileName can be either the full path to a local file or a URL. URL's must begin with "http:", "ftp:" or "rtsp:".
After setting the FileName property you should check the ErrorCode property, which will be 0 if the file was loaded successfully, or will contain an error code if not.When a file is loaded, the control is automatically resized to match the size of the loaded file. If a movie has no natural width - e.g. a sound-only movie - a default width equal to the current width of the control will be used.
Gets the full path and filename or URL of the currently loaded movie.
Read/Write - Run mode.
Returns the type of the currently loaded file.
0 No file loaded 1 File loaded as an image 2 File loaded as a QuickTime movie Read Only - Run mode when a movie is loaded.
Used to determine whether the various components which make up QuickTime, such as QuickTime VR are installed and also to obtain their version numbers. For example, before loading a QTVR movie, it would be a good idea to check if the QTVR component of QuickTime is installed:
bQTVR_Installed = (SkyLight1.Gestalt("qtvr") > 0)
Some useful Selector values are shown below. See QuickTime documentation (e.g. gestalt.h) for more options and information.
Selector QuickTime constant Use qtim gestaltQuickTimeVersion Returns the version number of QuickTime in upper word qtvr gestaltQTVRMgrAttr > 0 if QTVR is installed qtvv gestaltQTVRMgrVers Returns the version number of QuickTime VR in upper word icmp gestaltCompressionMgr Returns version of the Image Compression Manager
Read Only - Run mode
Used to set a specific palette (HPALETTE) for rendering images in 256 colour mode.
Read/Write.Can be set as follows, if there is an 256 colour image loaded into Picture1:
SkyLight1.hPal = Picture1.Picture.hPal
Gets the codec of the loaded image. Typical codecs are: 'jpeg', 'tiff', 'gif ', etc.
Read Only - when an image is loaded.
Gets the color depth of the loaded image - 2, 4, 8, 16, 24 or 32 bits.
Read Only - when an image is loaded.
Returns TRUE if the movie is Interactive like a QTVR movie and doesn't make sense to play.
Read Only - Run mode when a movie is loaded.
If Looping = True, the movie or sound will loop continually. If a selection is defined, and PlaySelectionOnly = True, this selection will loop.
Read/Write - Run mode when a movie is loaded. Default = False.
Returns TRUE if the movie has been edited in any way. Useful for knowing whether to prompt to save changes.
Read Only - Run mode when a movie is loaded.
Determines whether clicking on the movie starts/stops the movie playing.
Read/Write - Run mode. Default = True.
Get/Set flags which control certain aspects of the Movie Controller.
Read/Write - Run mode. Default = True.
mcFlagSuppressMovieFrame &H0 mcFlagSuppressStepButtons &H2 Controls whether the movie controller displays the step buttons. If this flag is set to 1, the controller does not display the step buttons. By default, this flag is set to 0. mcFlagSuppressSpeakerButton &H4 Controls whether the controller displays the speaker button. If this flag is set to 1, the controller does not display the speaker button. By default, this flag is set to 0. mcFlagsUseWindowPalette &H8 Determines whether the movie controller constructs a custom color palette, based on the color values found in the movie. This flag only works with display drivers that support palettes, typically those drivers that handle colors at pixel depth eight. By default, this flag is set to 0. mcFlagsDontInvalidate &H10 Controls whether the controller boundary rectangle is invalidated (and hence updated when an update event occurs). If this flag is set to 1, the controller does not invalidate the controller boundary rectangle. By default, this flag is set to 0. mcFlagsUseCustomButton &H20 Requests a custom button in the movie controller if set to 1. In the movie controller provided with QuickTime, this button is a downward-pointing arrow. When its custom button is clicked, the movie controller generates the mcActionCustomButtonClick action. By default, this flag is set to 0. mcFlagQTVRSuppressBackBtn &H10000 Controls whether the controller displays the go-back button. If this flag is set to 1, the controller does not display the go-back button. By default, this flag is set to 0. mcFlagQTVRSuppressZoomBtns &H20000 Controls whether the controller displays the zoom-in and zoom-out buttons. If this flag is set to 1, the controller does not display the zoom buttons. By default, this flag is set to 0. mcFlagQTVRSuppressHotSpotBtn &H40000 Controls whether the controller displays the hot spot display button. If this flag is set to 1, the controller does not display the hot spot display button. By default, this flag is set to 0. mcFlagQTVRSuppressTranslateBtn &H80000 Controls whether the controller displays the translate mode button. If this flag is set to 1, the controller does not display the translate mode button. By default, this flag is set to 0. mcFlagQTVRSuppressHelpText &H100000 Controls whether the controller displays help text in the label display area. If this flag is set to 1, the controller does not display help text. By default, this flag is set to 0. mcFlagQTVRSuppressHotSpotNames &H200000 Controls whether the controller displays hot spot names in the label display area. If this flag is set to 1, the controller does not display hot spot names. By default, this flag is set to 0.
Example - toggle Speaker Button on and off:
Dim SpeakerButtonVisible As Boolean
SpeakerButtonVisible = Not ((SkyLight1.MovieControllerFlags And mcFlagSuppressSpeakerButton) <> 0)If SpeakerButtonVisible Then
SkyLight1.MovieControllerFlags = SkyLight1.MovieControllerFlags Or mcFlagSuppressSpeakerButton
Else
SkyLight1.MovieControllerFlags = SkyLight1.MovieControllerFlags Xor mcFlagSuppressSpeakerButton
End If
Determines whether the movie controller is visible or not.
It is usually a good idea to explicitly set this property before loading a file into the control.
Read/Write - Run mode. Default = False.
Returns the amount of the movie already loaded, in movie time units, for a streaming movie. Once the movie is fully loaded, MaxLoadedTime will equal Duration.
Read Only - Run mode when a movie is being loaded.
Gets/Sets the location, in movie time units, of the movie poster frame.
Read/Write - Run mode when a movie is loaded.
Returns the Movies Sticky Error code. See QuickTime documentation for details.
Read Only - Run mode.
Gets/Sets the contents of a user data item in a movie. Text user data items can be used for storing all kinds of useful data in a movie, such as a copyright notice or description of the movie. Each user data item is identified by a 4-character identifier (e.g. "©cpy"). A number of identifiers beginning with "©" are already defined by Apple, and are used to display information about the movie in the QuickTime Player application:
©inf Information ©des Description ©cpy Copyright statement ©com Comment ©day Date the movie content was created ©nam Movie’s name Apple has reserved all lowercase user data type values. You are free to create user data type values using uppercase letters. Apple recommends using type values that begin with the '©' character to specify user data items that store text data. See QuickTime documentation for full details.
Read/Write - Run mode when a movie is loaded.
Returns the natural height/width of the movie or image in pixels.
If the movie has no natural width, e.g. a sound-only movie, the width returned will be the default width assigned when the movie was loaded.
Read Only - Run mode when a movie is loaded.
Gets/Sets the horizontal/vertical offset in pixels used to display images.
Read/Write - Run mode when an image is loaded.
Gets/Sets the rate at which the movie plays.
A PlayRate of 1.0 is normal, 0.5 is half-speed, 2.0 is double-speed, etc.
Read/Write - Run mode when a movie is loaded.
If this property is True, then the Play method will only play the selection. A selection may be set using the StartTime and StopTime properties, or may be set manually by holding the Shift key down while moving the progress bar in the movie controller.
Read/Write - Run mode when a movie is loaded. Default = False.
Returns the version number of QuickTime. Currently 300 for QuickTime 3 or 400 for QuickTime 4.
Read Only - Run mode after QTML_Initialize is called.
Returns the ID of the current node of a QTVR movie.
Read Only - Run mode when a QTVR movie is loaded.
Get/Set the enabled state of QTVR events from a QTVR movie.
If True, a QTVREvent is triggered whenever various actions occur within a QTVR scene,
such as clicking on a hot spot, or panning to a new direction. See QTVREvent for details.
Read/Write - Run mode when a QTVR movie is loaded. Default = True.
Gets/Sets the vertical field of view (FOV) of a QTVR movie in degrees.
Reduce FOV to zoom in, increase FOV to zoom out.
Read/Write - Run mode when a QTVR movie is loaded.
Returns the four-letter type code of a QTVR hot spot. For example, link hot spots usually
have the type-code "link". Returns an empty string if unsuccessful.
Read Only - Run mode when a QTVR movie is loaded.
Returns the four-letter type code of a QTVR node or an empty string if unsuccessful.
Read Only - Run mode when a QTVR movie is loaded.
Gets/Sets the pan angle of a QTVR scene in degrees - 0 to 360.
Read/Write - Run mode when a QTVR movie is loaded.
Gets/Sets the tilt angle of a QTVR scene in degrees.
Read/Write - Run mode when a QTVR movie is loaded.
Gets/Sets the physical scale factor which is applied to the movie or image.
For example, to play a movie at double-size, set the ScaleFactor = 2.0.
Read/Write - Design mode and Run mode. Default = 1.
Gets/Sets the start and stop times of the selection. Use to define a selection, which will be played if PlaySelectionOnly = True
Read/Write - Run mode when a movie is loaded.
This property provides control over the Streaming Proxy settings as found in the QuickTime Control Panel, and is useful when using the SkyLight control to access URL's via a proxy server.
Setting the Protocol parameter to "SOCKS", "HTTP" or "RTSP" allows setting/retrieval of the appropriate settings in the form of a colon delimited string as follows:
<proxy server>:<port number>:<flags>
flags: 0 = disable, 1 = enable
For example, to set the HTTP proxy settings to use proxy.skylark.ie as the proxy server on port 8080 and Enabled:
SkyLight1.StreamingProxySettings("HTTP") = "proxy.skylark.ie:8080:1"
The other proxy settings can be accessed by passing an empty string in the Protocol parameter. In this case the colon delimited string is follows:
<list of proxy bypass domains>:<flags>
flags: 0 = use QT settings, 1 = use system settings
SkyLight1.StreamingProxySettings("") = "*.mydomain.com:1"
Read/Write - Run mode.
Gets/Sets the current time position of the currently loaded movie.
Read/Write - Run mode when a movie is loaded.
Returns the TimeScale of the currently loaded movie.
Read Only - Run mode when a movie is loaded.
Get/Set the left/right balance of an audio track. The first track has a TrackIndex of 1, etc.
The balance value has a valid range from -128 (Left) to 128 (Right) - 0 is neutral.
Read/Write - Run mode when a movie is loaded.
Returns the duration of a movie track. The first track has a TrackIndex of 1, etc.
Read Only - Run mode when a movie is loaded.
Get/Set the enabled state of a track. The first track has a TrackIndex of 1, etc.
Read/Write - Run mode when a movie is loaded.
Returns the offset of the start of a track from the start of the movie.
Read Only - Run mode when a movie is loaded.
Returns the number of tracks in a movie.
Read Only - Run mode when a movie is loaded.
Returns the four-letter type code of a track. For example, a video track is "vide", a sound track "soun", and a text track is "text".
Read Only - Run mode when a movie is loaded.
Enable/Disable re-painting of images after updates.
It can be useful to prevent re-painting of images at certain times.
Read/Write - Run mode when an image is loaded.
Get/Set the volume level for movie sound-track play-back - 0(min.) to 255(max.).
Read/Write - Run mode when a movie is loaded.
Occurs whenever the mouse is clicked on the control.
Occurs whenever the mouse is double-clicked on the control.
Occurs whenever the movie controller is moved to a certain position, either manually or by setting the Time property or using the Rewind method.
Occurs whenever a mouse button is pressed within the control, or when the mouse is moved over the control.
Button - indicates which button triggered the event - see Visual Basic documentation for details.
Shift - indicates the state of the CTRL, ALT and SHIFT keys - see Visual Basic documentation for details.
x, y - location of event in pixels
Occurs immediately prior to an image being re-painted. By placing some code in the Paint event, you can use the supplied hDC with suitable Windows GDI functions to overlay text or graphics onto an image each time it is redrawn.
Occurs whenever the movie starts or stops or changes PlayRate whether caused manually by the movie controller or by using various Properties or Methods.
PlayRate is the new rate at which the movie is playing.
Occurs whenever a QTVR event such as clicking on a hot spot occurs. By trapping QTVR events you can respond to much of what is going on when a user is navigating their way around a QTVR movie.
EventType Value Parameters Occurs whenever... kQTVREventSetPanAngle Param1 = Pan angle ...a new pan angle is set kQTVREventSetTiltAngle Param1 = tilt angle ...a new tilt angle is set kQTVREventSetFieldOfView Param1 = FOV ...a new FOV is set (zoom-in/zoom-out) kQTVREventMouseDown ...the mouse button is pressed within a hot spot kQTVREventMouseUp Param1 = x in pixels
Param2 = y in pixels...the mouse button is raised within a hot spot kQTVREventTriggerHotSpot Param1 = hot spot ID ...a hot spot is triggered kQTVREventEnteringNode Param1 = to node ID ...a node is entered kQTVREventLeavingNode Param1 = from node ID
Param2 = to node ID...a node is left kQTVREventMouseEnterHotSpot Param1 = hot spot ID ...the mouse entered a hotspot kQTVREventMouseLeaveHotSpot Param1 = hot spot ID ..the mouse left a hot spot
The SkyLight Pro interface is designed to simplify the process of using QuickTime within your application. A deeper understanding of the QuickTime API will be of great benefit in getting the most out of this control - see the QuickTime API Documentation on the Apple Developer site.
Skylark Associates
Ltd.
The Old Woollen Mill,
CONVOY,
Co.
Donegal,
Ireland.
Tel. +353-74-47600
FAX +353-74-47626
Email: john@skylark.ie
© 1998-2002 Skylark Associates Ltd.
Portions of documentation © Apple Computer Inc.
* QuickTime is a registered trademark of Apple Computer Inc.