USING
CUSTOM ACTIVEX COMPONENTS WITH ADVENTURE MAKER (FOR ADVANCED USERS) (FULL EDITION ONLY,
WINDOWS ONLY)
The advanced users
can greatly expand the power of Adventure Maker by using custom ActiveX components (OCX
files) inside their projects.
I.QUESTIONS AND ANSWERS
- Where to find the components
- How to install the
components on my computer
- How to install
the components on the end-user computer
- How to use a component inside
Adventure Maker
- How to modify a
component property
- How to call a component
method
- How to intercept
the events of a component inside Adventure Maker
- How to know the ProgID that
corresponds to a given OCX?
II.
DESCRIPTION OF EACH FUNCTION
- Action.AddComponent
- Action.RemoveComponent
- Action.IsComponentInstalled
- Action.DoesComponentExist
I.
QUESTIONS AND ANSWERS
Where
to find the components:
The activeX components that you can use in Adventure Maker are files that
have the .ocx extension. They are usually located inside your c:\Windows\System32 folder
(or c:\Windows\System if you are using Windows9x), but they can be located anywhere
on your hard disk (if you open the System32 folder with Explorer, you will see that there
are a lot of them).
You can either use
existing components (some are free, others are very expensive), or
you can create your own (most object-oriented Windows programming languages allow doing so). If you download some components from the Internet, make sure NOT
to download ActiveX components for web pages, because they are usually not suited for
applications or games. If you don't know, just download components that work with Visual
Basic 5 or 6, which are fully compatible with Adventure Maker.
How to install the components on my computer:
In order to be able to use them, the components must be installed on your
computer. Some components are probably already installed (like the Flash component), but
others may require you to install them manually. For example, if you download an OCX file
from the Internet, it is very likely that you need to install it manually.
The are two ways to
install a component:
1. First way: just
copy the ocx component that you wish to install into the "Plugins" sub-folder of
the Adventure Maker folder, and then restart Adventure Maker. The program will
automatically install all the ocx components that are located inside the
"Plugins" sub-folder.
2. Second way: click
the Start Menu, click "Run...", type the following code and then click OK:
regsvr32 "FULLPATH"
where you must replace FULLPATH with the path of your OCX file (e.g.
c:\Windows\System32\MyComponent.ocx). If it works, you should get a message like
"DllRegisterServer succeeded". Otherwise, if you get a different message, there
are three main possibilities and solutions:
- The file was not found -> double-check the FULLPATH.
- The file has been already registered -> good news, it's ok.
- The file does not need to be registered -> bad news, it is likely
that you cannot use that component with Adventure Maker.
How to install the components on the end-user
computer:
When you distribute your project, you must make sure that the components are
installed on the end-user computer. Adventure Maker allows you to include the components
in the distribution package of your projects. To do so, just add the corresponding OCX
files to the list of files that is under the "System Files" tab
of the "Distribution Options" window of Adventure Maker. At the end of the
installation, the OCX files will be automatically copied to the Windows\System32 folder
and registered.
How to use a component inside Adventure Maker:
First of all you need to know the ProgID that corresponds to the ActiveX component
that you have installed. For example, the ProgID of the Flash component is "ShockwaveFlash.ShockwaveFlash". If the component has been
developed by you with Visual Basic, the ProgID will follow the PROJECTNAME.CONTROLNAME
convention.
Once you know the
ProgID, you can load the control by executing the following VBScript code (from everywhere
in your project):
Action.AddComponent "PROGID",
"COMPONENTNAME"
where you must replace PROGID with the actual ProgID, and COMPONENTNAME with any
string of your choice (it will be used to identify the component), provided that it does
not contain any spaces or special characters.
To make the control
become visible (default is hidden), you can then use the following code:
Component("COMPONENTNAME").Visible
= True
To change the size
of your component, you can use the following code:
Component("COMPONENTNAME").Move
LEFT*15, TOP*15, WIDTH*15, HEIGHT*15
where you must replace LEFT, TOP, WIDTH and HEIGHT with the actual values in pixels
(note that those values are multiplied my 15 in order to be expressed in
"twips": 1pixel=15twips).
If you are familiar
with Visual Basic, you will notice that you can modify the properties or call the methods
of a component in the very same way as you modify the properties or call the methods of a
Visual Basic object (like the Label, TextBox, PictureBox, etc.).
To remove the
component, you can use the following code:
Action.RemoveComponent
"COMPONENTNAME"
How to modify a component property:
To modify a property of a component (such as its color, position, etc.), just use the
following syntax:
Component("COMPONENTNAME").PROPERTYNAME
= NEWVALUE
Here are some examples of properties
that you can usually modify in that way:
Align, Cancel, CausesValidation, Container, Default, DragIcon, DragMode, Enabled, Height,
HelpContextID, Left, Name, Parent, Tag, ToolTipText, Top, Visible, WhatsThisHelpID, Width
For example, if you want to change the position of the component named
"MyComponent" to x=100, y=230, you should type the following code (note that you
must always multiply the numbers by 15, because of the units system that is not in
pixels):
Component("MyComponent").Left
= 100 * 15
Component("MyComponent").Top = 230 * 15
Important:
if you want to modify a property that belongs to
the component only (i.e. a property that is not listed above), you must use the
".Object" keyword, as shown in the following example:
Component("COMPONENTNAME").Object.PROPERTYNAME
= NEWVALUE
For example, some of the properties
that belong to the Flash component are: FlashVars, FrameNum, Loop, Menu, Movie, Playing,
Quality, Quality2, ReadyState, SAlign, SWRemote, TotalFrames, WMode.
How to call a component method:
To call a method of a component, just use the following syntax (note that the number of
parameters depends on the concerned method):
Component("COMPONENTNAME").METHODNAME
PARAMETER1,PARAMETER2
In case the method has a return
value, use the following syntax instead:
RetValue =
Component("COMPONENTNAME").METHODNAME(PARAMETER1, PARAMETER2)
Some of the available methods are: Drag, Move, SetFocus, ShowWhatsThis, ZOrder
Again, if the method belongs to the particular component, you must use the
".Object" keyword, as shown below:
Component("COMPONENTNAME").Object.METHODNAME
PARAMETER1, PARAMETER2
or, if the method has a return value:
RetValue =
Component("COMPONENTNAME").Object.METHODNAME(PARAMETER1, PARAMETER2)
For example, if you want to call the "LoadMovie" method of the Flash component
named "Flash1", you should type:
Component("Flash1").Object.LoadMovie
0, "c:\filename.swf"
Some of the methods that belong to the flash component are: Back, CurrentFrame,
FlashVersion, Forward, FrameLoaded, GetVariable, GoToFrame, IsPlaying, LoadMovie, Pan,
PercentLoaded, Play, Rewind, SetZoomRect, Stop, StopPlay, Zoom
Read the Flash component documentation for details on each of those methods.
How to intercept the events of a component inside
Adventure Maker:
To intercept the events of a component, just add the following code to the VBScript
Global Procedures:
Sub
COMPONENTNAME_EVENTNAME(p)
CODE
End Sub
where you must replace COMPONENTNAME
with the name that identifies the instance of the component (read the description of the
AddComponent function for details), EVENTNAME with the name of the event that you wish to
intercept and CODE with the code that you wish to execute when the event is intercepted.
For example, if you want to say
"Hello" every time that the player clicks on the component created under the
name of "MyComponent", you should add the following procedure to your
VBScript Global Procedures:
Sub MyComponent_Click(p)
MsgBox "Hello"
End Sub
Another example: if you have created
a Flash component under the name of "Flash1" and you want to trap the
"FSCommand" event that it raises, you should add the following procedure to your
VBScript Global Procedures:
Sub
MyComponent1_FSCommand(p)
Msgbox p(0).Value & NEWLINE & p(1).Value
End Sub
Note that you can replace the
variable "p" with any variable of your choice. It will become an array that will
contain all the parameters returned by the event. For example, p(0).Name will be the name of
the first parameter, p(1).Name will be the name of the second parameter, etc., whereas p(0).Value will be the value
of the first parameter, p(1).Value will be the value of the second parameter, etc.
If you don't know what parameters a
given event returns, you can use the following procedure to get a list of all the
parameters with their corresponding values:
Sub COMPONENTNAME_EVENTNAME(p)
Dim i
Dim s
Do Until i >= p.Count
s = s & p(i).Name & " (value = " &
p(i).Value & ")"
s = s & NEWLINE
i = i + 1
Loop
MsgBox "This event has " & CStr(p.Count) & "
parameters."
MsgBox "Those parameters are: " & NEWLINE & NEWLINE
& s
End Sub
where you must replace COMPONENTNAME
with the name that identifies the instance of the component and EVENTNAME with the name of
the event that you wish to analyse (do not replace the keyword "NEWLINE",
because it is a constant that means "line feed and carriage return"!).
How to know the ProgID that corresponds to a given OCX?
If the component has been developed by you with Visual Basic, the ProgID will
follow the PROJECTNAME.CONTROLNAME convention. If someone has
created the component for you, you can ask him to tell you the ProgID. Otherwise, if you
know nothing about the OCX except the filename, you must follow the instructions below to
retrieve its corresponding ProgID.
Note that you
must first install the OCX on your computer. To do so, read the answer to the
question "How to install the components on my computer" above.
After having installed the ocx, you
have mainly two ways to retrieve its ProgID:
1. First way: download the freeware
named "ProgID Browser". You can find a copy here, under the
"Windows" section. The program will show you all the ocx components that are
installed on your computer. Just find the right one and you will read the ProgID from the
panel at the top of the program main window.
Note: The program requires no
installation, but you need the files COMCTL32.ocx and TLBINF32.DLL to be installed on your
computer. If you don't have them, you can download them from the same page where you
downloaded the program.
2. Second way: manually find the ocx
ProgID on the Windows Registry. To do so, click the Start Menu, click "Run...",
type regedit and
then click OK. When the Registry Editor window appears, press F3 and search for your OCX
(enter the filename of the OCX and then click OK). For example, you can search for
MyComponent.ocx. If you cannot find the file, it is very likely that it has not been
installed properly (in that case, read the answer to the question "How to install the
components on my computer" above). The file should be located in the registry under a
folder that has a long name, like "{02BF25D5-8C17-4B23-BC80-D3488ABDDC6B}". That
folder should contain a sub-folder named "ProgID". You will find the ProgID
there.
II.
DESCRIPTION OF EACH FUNCTION
Action.AddComponent
This function allows you to load an ActiveX control (aka "component"), which is
usually associated with a file that has the OCX extension, and that is located inside the
Windows\System or Windows\System32 folder. For example, you can load the Flash component,
as well as any component that you can load from Visual Basic. You can also load components
created by you.
Here is the syntax:
Action.AddComponent
"PROGID", "COMPONENTNAME"
where COMPONENTNAME is a string that will be used to identify the component (you can use
any string of your choice, provided that it does not contain any spaces or special
characters), and PROGID is the native identifier of the component. For example, the PROGID
of Flash is "ShockwaveFlash.ShockwaveFlash". If the component has been developed
by you in Visual Basic, the ProgId will follow the PROJECTNAME.CONTROLNAME convention.
The loaded component will appear at the top-left corner of the game area. By default the
new component will be hidden, but you can change its "visible" property to
"true" to make it become visible. To change its "visible" property,
you can use the following code:
Component("COMPONENTNAME").Visible
= True
where COMPONENTNAME is the string that identifies the component (see above).
To
make the component appear during the transitions, use the advanced syntax:
Action.AddComponent
"PROGID","COMPONENTNAME",OPTION1,OPTION2
where OPTION1 is True or False (default=False) depending on whether the
component should appear in the transitions, and OPTION2 is True or False (default=False)
depending on whether the component should be removed from the background of the
alphablending transitions (useful only for animated components with transparency). If you are not sure, just choose True for OPTION1 and False for OPTION2.
Action.RemoveComponent
This function allows you to remove one of the components that you have created by using
the "Action.AddComponent" function. The syntax is:
Action.RemoveComponent
"COMPONENTNAME"
where COMPONENTNAME is the string that identifies the component (see above).
Action.IsComponentInstalled
This function will return True or False depending on whether a given "PROGID"
exists, which means that the corresponding component has been successfully installed on
the end-user computer. This function is particularly useful if you want to prevent the
"Action.AddComponent" function from displaying an error message in case the
component cannot be loaded. Note that this function is very different from the function
"Action.DoesComponentExist".
The syntax is:
ReturnValue =
Action.IsComponentInstalled("PROGID")
Action.DoesComponentExist
This function will return True or False depending on whether a given
"COMPONENTNAME" has already been used to identify a component (see the
description of the function "Action.AddComponent" for details). Note that this
function is very different from the function "Action.IsComponentInstalled".
The syntax is:
ReturnValue =
Action.DoesComponentExist("COMPONENTNAME")
|