Creative Computers/CreativeComputers.iso/commercial/inovatronics/candodemo/testdrivemanual/testdrive1.doc

Text File | 1994-11-17 | 26KB | 606 lines

**** CANDO TEST DRIVE #1

    When you first start CanDo, your Card's default window is
low-resolution, 320 by 200, with 16 Colors.  However, you can tell
CanDo to open a Window of any dimension and display mode supported by
the Amiga Operating System or you can simply tell it to use a standard
Picture as a background.  When a picture window is used, CanDo will
automatically load and display the picture in your Card's Window and
set the color palette.  You will use a picture window for this
example.  Click the Window Icon on the main Panel.

    See Picture "Images/WindowIcon"

    This will display the Window Editor.  Change the Window Title from
"Unnamed..." to "Test Drive 1"

    See Picture "Images/WindowTitle"

Click on the Dimension Button.

    See Picture "Images/Dimension"

    This will display the Dimension Requester.  This Requester allows
you to specify the Dimensions and the number of colors for your window
or you can specify a Picture.  The Dimension and number of colors will
be determined by the picture.

    The button entitled "Unnamed" below "Picture" indicates there is
not yet a Picture specified for the window.  Click on the "Unnamed"
Button.

    See Picture "Images/UnnamedPicture"

    This will bring up CanDo's File Requester.  The Title at the top
will say "Image Requester".  The File field displays the selected File
Name.  Select Backdrop1.PIC by clicking on it in the list of files.
Click on the Show Picture Button.  This allows you to preview the
picture.

    This picture is a simple brown rectangle with a black drop shadow.
This type of picture can be used for creating many kinds of attractive
applications.  When you are ready to proceed, click anywhere on the
picture.

    This will return you to the File Requester.  When you Click Ok you
will return to the Dimension Requester.  Notice the button, which said
"Unnamed", is now highlighted with the text "Backdrop1.Pic".  This
verifies you now have a Picture window.  Click Ok and return to the
Window Editor.  You will explore the other aspects of the Window
Editor later.  Click Ok.  This will return you to the Main Panel and
display your new window.  Click on the Screen Up/Down Button so you
can see more of your window.

    See Picture "Images/UpDownIcon"

    The picture you previewed should now be shown along with window
borders, a Close Button, and a window title of "Test Drive 1".  This
is the canvas to which you will be adding various "Objects" while
learning about CanDo.

    The first thing you will do is add a button to your window.  On
the Main Panel, click on the Screen Up/Down Button to raise the Main
Panel, click on Add Icon and then click on the Button Icon.

    See Picture "Images/AddIcon"
    See Picture "Images/ButtonIcon"

    A requester appears with a brief description, which will serve as
a reminder of what you need to do to add a button.  The process for
defining the button area is to position a cross-hair pointer to where
you want the upper left corner; press and hold the left mouse button;
drag the pointer to the right and down; when the rectangle is the size
and shape you wish, release the mouse button.

    Click Ok on the reminder requester.  CanDo's Main Panel will
completely disappear.  Your mouse pointer is now a cross-hair.

    Notice a pair of numbers which follow the mouse pointer.  These
numbers are the "Coordinates" of the current mouse position.  The
first number is the horizontal position (distance from the left), and
the second number is the vertical position (distance from the top).

    Position the cross-hairs where the coordinates will be near 90,50.
This will be near the upper left corner of the brown box.

    Click and Hold the left mouse button.  Notice the numbers with the
mouse button have changed to 1,1.  These numbers represent the size of
the button area.

    Drag the cross-hairs down and to the right about an inch in both
directions.  When you release the mouse button, the Button Editor will
appear.

    The default border for a button is a simple outline.  This is
indicated by the text OUTLINE in the button below the "Border" title.
Click on the OUTLINE button.

    See Picture "Images/OutlineBorder"

    This will display the Border Requester.  This requester contains
twelve border styles you can use.  The title "Outline" is highlighted
indicating it is the currently selected border style.  Click on the
Bevel style.

    See Picture "Images/BevelBorder"

    This will cause the title "Bevel", above the sample border, to
become highlighted.  The Bevel style uses two colors.  They can be any
color in the color palette.  The colors in the palette are shown along
the bottom of the screen.  Click on a couple of these colors.  Notice
the color changes in the displayed borders.  The color in the 1st
color selector (the TV looking box in the Border Requester) will
reflect the selected color.  Click on White in the color palette.  Now
Click on the 2nd Color Selector.

    See Picture "Images/2ColorSelectors"

    This will cause a black outline to appear around the 2nd Color
Selector.  Click on various colors in the color palette and observe
the changes in the sample borders.  Now Click on Black (3rd from left)
in the color palette.  Look at the Bevel border example.  This is the
natural appearance of the Bevel Style:  a light shade on the top and
left, and a dark shade on the bottom and the right.  Click on the Ok
Button.

    This will bring you back to the Button Editor.  Click Ok.  This
will return you to the Main Panel and your window will now contain
your new button.  Click on Browse.

    Click on your newly created button.  While in "Browse" Mode, you
can test your application.  You have not told your button to do
anything yet, so it will simply change color when you click on it.
Click on the Edit Button.

    See Picture "Images/BrowseIcon"

    Notice both the Edit Button and the Design Button have become
highlighted.  When you click on your button, while in "Design" mode,
you will automatically go to the Button Editor.

    See Picture "Images/EditIcon"

    You will be instructing your button to display a Text message when
you click and "Release" on it.  CanDo allows you to define an action
for each of the Amiga supported actions for a button:  Click, Drag,
Release, and DoubleClick.  The Release action is commonly used in
Amiga applications for allowing the user to click on a button, change
their mind, and remove the mouse pointer before releasing the mouse
button; thus avoiding the button's action.  You will be using the
Release action for this button.

    If you have not done so already, click on your button.  When the
Button Editor appears, click on the Release button under Scripts.

    See Picture "Images/Release"

    This will bring up the Script Editor.  At this point you could
type in the instructions to print a text message on the screen.
However, CanDo has some tools to help you write scripts for some
common activities.  These tools are called Editor Tools (not all of
CanDo's Editor Tools have been included in the Test Drive).  Along the
right edge of the Script Editor are four Editor Tool Icons.  Using the
Slider, on the far right, you can find additional Editor Tool Icons.

    Using the Editor Tool Slider, locate the Print Text Editor Tool
Icon and click on it.

    See Picture "Images/Text_ET_Icon"

    The Print Text Requester will appear.  Click on the "Set Text and
Font..." button.

    See Picture "Images/SetTextAndFont"

    This will bring up the Font/Text Requester.  Enter "The Button Got
Clicked!" into the Text Field and press Return.  Notice the example
text on your window.  This is what the text will look like when it is
printed.  Click on the Outlined Button.

    See Picture "Images/Outlined"

    Click the Ok Button.  This will return you to the Print Text
Requester.  Now, click the "Set Position..." button.

    See Picture "Images/SetPosition"

    The Script Editor will disappear allowing you to position a
rectangle the size and shape of your text message.  Position the box
to the right of your button near 350,50.  These coordinate numbers
will tag along with your mouse pointer.  Click and release the mouse
pointer when it is properly positioned.  This will return you to the
Print Text Requester.  You can repeat either of these two steps if you
feel you need to try again.  When you are ready, click the Ok button.
The following script will be inserted into the script Editor.

    SetPrintFont "topaz",8
    SetPrintStyle OUTLINE,2,3
    SetPen 1,0
    SetDrawMode JAM1
    PrintText "The Button Got Clicked!",350,50

    Using CanDo's Editor Tools not only makes it easy to accomplish
many commonly needed activities, but it allows you to learn some the
scripting commands without taking a programming course.

    Additional Help is available.  DoubleClick on the PrintText
Command in the last line of the script.  CanDo's Help system gives a
brief description of the Commands, Functions, and System Variables.
If you wish, explore the Help system (red text allows you to jump to
the associated description).  When you are ready, Click on Exit Help.

    See Picture "Images/ExitHelp"

    Click Ok on the Script Editor window.  Notice the Release Button
on the Button Editor is now highlighted.  This indicates it contains a
script.  Click Ok to return to the Main Panel and then click on the
Browse button.

    See Picture "Images/BrowseIcon"

    Now Click on your button.  Ta Da!  Congratulations, you have now
tackled the most fundamental step in creating a CanDo application (or
an Amiga application for that matter).  You have created an interface
(as simple as that may be) which silently waits for "something" to
happen (a button click) and then does a specified action.

    As you add additional Objects, you simply instruct them what to do
when "something" happens.  This is what makes CanDo fundamentally
different from traditional programming languages such as BASIC or even
the newer Iconic Flow charting languages.  Those languages require you
to construct a complicated set of tests to determine "what happened"
before you get started telling it "what to do".

    Before you add more Objects, lets show you how you can
automatically put some text in your Button area.  Click on the Edit
Button and then the button on your window.

    See Picture "Images/EditIcon"

    Click on the box next to "Text" in the Button Editor.

    See Picture "Images/TextAndBox"

    This will display the Font/Text Requester.  Enter "My Button" into
the Text Field and click the Shadowed Button.

    See Picture "Images/ShadowedStyle"

    The sample text in your window should now show a white "My Button"
with a black shadow.  Now click Ok and return to the Button Editor
Requester.  Notice the Checkmark in the box next to Text.  This
indicates it is now a Text Button.  The area of the button will
conform to the size and shape of the Text (the text can include
leading and trailing spaces to make it longer).

    Click on the button BEVEL under title Border.

    See Picture "Images/BevelBorder"

    Click on the Shadow Border Style and then Ok.

    See Picture "Images/ShadowBorderStyle"

    Click Ok on the Button Editor and then Browse when you return to
the Main Panel.  Your Button looks different but it will still print
the same message when you click on it.

    Lets add a Text Field to the Window.  It will allow you to type a
text message into it.  Many CanDo applications use Text Fields as the
primary means for asking the user for information.  A script can get
the text from a Field and do all sorts of things with it.  In this
example, you will do something simple.  Your script will set the
Window Title to the Text entered into the Field.

    Click "Add" then the Field button on the Main Panel.

    See Picture "Images/AddIcon"
    See Picture "Images/FieldIcon"

    As when creating buttons, the Main Panel will disappear allowing
you to position the cross-hairs where you want the upper left corner
of the Field.  Position the cross-hairs under your button near the
coordinates 90,90.  Press and hold the left mouse button and drag the
mouse to the right.  Unlike buttons, Fields have a fixed height so you
will only be defining the width.  Drag the mouse to the right until
the width is about 200, then release the mouse button.

    When the Field Editor Requester appears, click on the Border
Button entitled OUTLINE.

    See Picture "Images/OutlineBorder"

    The new 2.0 Operating System introduced several new border styles
to be used in specific situations.  CanDo allows you to utilize these
new border styles even if you are not using the 2.0 Operating System.
On the bottom row there are two Double border styles.  The one on the
left is the old one which was available prior to 2.0.  The one on the
right is the one which should be used for Fields.  While you can use
many of the other styles (Bevel, Heavy, Checkbox, Rollo, and Button do
not work well with Fields) it is "suggested" you use the new Double
border style.  Click on the new Double border style.

    See Picture "Images/DoubleBevelStyle"

    Click on Ok.  This will return you to the Field Editor Requester.
Now you can specify an action which will occur when the user of your
application presses the Return Key while the field is selected.  Click
on the Return Button.

    See Picture "Images/ReturnButton"

    This will display the Script Editor.  You want your script to set
the Window Title Bar to contain the Text entered into the Field.  Type
the following line.

    SetWindowTitle TextFrom("Field#1")

    The TextFrom portion is a built in Function in CanDo.  It returns
the current text from the Text Field Name specified within the
parenthesis.  The Field you are creating is called "Field#1".  This is
verified by the title in the Script Editor.

    The SetWindowTitle Command sets the Window title to a group of
characters.  A grouping of characters is called a Character String or
just a String.  In this example, the string is provided by the
TextFrom function.  When this command is performed, the TextFrom
Function will retrieve the text from "Field#1" and will be displayed
in the Window Title.  The characters "Field#1" is a String telling the
TextFrom Function the Name of the Field to get the character string
from.

    If you wish, you can doubleclick on SetWindowTitle or TextFrom to
see what the Help System tells you about them.

    When you are ready, click the Ok button on the Script Editor.
This will return you to the Field Editor Requester.  Notice the Return
Button is highlighted indicating there is a "Return" script.  Click
Ok.  This will return you to the Main Panel and display your new
field.

    Click on the Browse Button on the Main Panel and then click in
your new field.  Enter the Text "Hello Out There!" or whatever you
wish into the field.  When you press Return, the text will appear in
the window title.  You can repeat this as many times as you wish.
When you are ready click on Add then the Key Icon on the Main Panel.

    See Picture "Images/AddIcon"
    See Picture "Images/KeyIcon"

    Now you are going to make something happen when a key on the is
pressed.  The KeyInput Object Editor Requester allows you to specify
the key or key combination you wish to define.

    The Qualifier field allows you to specify things like SHIFT for
the shift keys, ALT for one of the Alt keys.  The Key Code allows you
to specify any of the other "typing" keys on your keyboard.  For this
example, you are going to play a sound when the Help key is pressed
without any "Qualifier" Keys.  Click in the Key Code Field and enter
the text Help.

    See Picture "Images/KeyCodeHelp"

    Keys usually do something when the key is first pressed, as
opposed to buttons which do something when they are released.
Therefore, click on the Pressed button.

    See Picture "Images/PressedButton"

    This will display the Script Editor.  Move the Editor Tool Slider
to the bottom to find the Play Sound Editor tool and click on it.

    See Picture "Images/Sound_ET_Icon"

    This will display the Play Sound Requester.  Click on the "Set the
filename..." button.

    See Picture "Images/SetFilenameButton"

    This will display the File Requester.  Click on the file name
"DogBark.snd".  If you click the Play Sound Button you will hear a
digitized audio sample of Tim Martin doing a pretty good job imitating
a dog.  Click on the Ok button.  This will return you to the Play
Sound Requester.  You don't need to set the volume or channel so click
Ok to return to the Script Editor.  Click Ok again to return to the
KeyInput Object Editor.  Finally, click Ok to return to the Main
Panel.

    Click on the Browse button and press the Help Key on the keyboard
a couple of times.

    Now lets have a little fun!  The one thing I'm sure you've always
wanted is to paint a picture and erase it every time you remove and
insert a disk.  Click on the Disk Icon on the Main Panel.

    See Picture "Images/DiskIcon"

    This brings up the Disk Object Editor Requester.  Click on the
button "When a disk is removed".  This brings up the Script Editor.
Click on the Paint Editor Tool Icon.

    See Picture "Images/Paint_ET_Icon"

    This will bring up the Paint Editor Tool Requester.

    See Picture "Images/PaintEditorTool"

    Hopefully you are familiar with using a paint program on the
Amiga.  The Paint Editor Tool acts like a paint program except with
one major difference:  Script Commands are created to reproduce the
actions you take.

    Like most paint programs, the best way to learn is to play with
it.  Try out the various paint tools.  If you don't like what you see,
use the Undo tool.  Unlike most Undo tools, it has a complete history
allowing you to undo as many actions as you wish.

    Draw as much as you want, keeping in mind Script Commands will be
created for every action you take.  When you are ready click Ok.  This
will take you back to the Script Editor.  Depending on how much you
painted, you could have a script which borders on huge.  But that's
Ok, you didn't have to type a thing.

    Click Ok to return to the Disk Object Editor.  Now click the
button "When a disk is inserted".  Click on the Paint Editor Icon
again.  This time, simply click on the CLR button.

    See Picture "Images/ClrButton"

    Click Ok to return to the Script Editor.  This created a
ClearWindow Command.  Click Ok returning to the Disk Object Editor.
Click Ok again to return once again to the Main Panel.

    Click on the Browse button.  Now remove and insert a Disk a couple
of times.

    So far, you've been adding everything to a single card.  Adding
objects to a Card creates an "interface" for the user of your
application.  Having additional Cards in your Deck allows you to
easily change "interfaces".  Next, you are going to create a second
card with a text editor, and button on each Card which allows you to
switch between the two.

    Click on the Edit Card Icon.

    See Picture "Images/CardIcon"

    This Brings up the list of Cards.  Buttons are provided for adding
new Cards, and editing, deleting, and duplicating existing ones.  The
Arrows allow you to reorder the cards.  Click on Add.

    See Picture "Images/AddCard"

    This brings up the Card Editor.  There are a number of scripts
associated with a Card.  For now, you do not have to do anything with
these.  Click Ok to return to the Card Editor Requester.  The List now
contains two entries.  Card#2 is Highlighted, indicating it is the
current Card.  Click on Exit to return to the Main Panel.

    Your new Card does not have any objects.  The window initially
inherits the first card's Picture.  However, you can change any of the
window setting for the new card without effecting the first Card.
These window setting will work fine for what you are doing so there is
no need to change them.

    Click on the Add button and the Document Icon on the Main Panel.

    See Picture "Images/AddIcon"
    See Picture "Images/DocumentIcon"

    This will lower the Main Panel allowing you to define the area for
your Document.  Position the cross-hairs near 90,50.  Press and hold
the left mouse button.  Drag the mouse to the right and down until the
width and height are close to 465,115 and release the mouse button.

    This will bring up the Document Object Editor.  Select the
Document Field, under the Name Field, and enter "s:Startup-Sequence".

    See Picture "Images/DocumentStartup"

    You can enter any name in the Document Field.  However, if the
name you enter is an existing File, it will automatically be loaded.
If the Name does not match an existing File, the Document will
initially be empty.  Entering "S:Startup-Sequence" allows us to look
at the startup sequence you used when starting up your Amiga.

    Click on the Border Button.  This will bring up the now familiar
Border Requester.  Select the New Double border style (the one on the
right) and click Ok.  This will bring you back to the Document Object
Editor.  Click Ok to create your new Document Object and to return to
the Main Panel.

    Click on Browse and then in your new Document.  The Document
should be displaying your Startup-Sequence.  You should be able to
move around and modify the Text.  Never fear:  it will not modify the
one saved on Disk.  If you wanted, it would be easy to add a save
option.  However, for this example we won't tread down the murky path
of modifying a Startup-Sequence.

    Now, click on the Previous Card Button on the Main Panel.

    See Picture "Images/PreviousIcon"

    This will return you to the original Card.  Click on the Previous
Card Button again.  Because you were on the first Card, it will move
you to the last Card.  The last Card in the Deck is Card#2.  You
should see the Startup-Sequence Document again.

    The Card Buttons allow you, the designer, to move to any card in
the Deck.  However, if a user was to run this deck without CanDo,
there would not be anyway to move between Cards.  This is because you
have not added anything to do this.

    You need a button on each Card to move to the other.  Lets start
by adding one to the current Card.  Click on Add and then the Button
Icons on the Main Panel.

    Position the cross-hairs near the upper right corner of the window
at the coordinates 590,15.  Click and and release the mouse button.
You are going to be making an Image Button.  Because the size is
determined by the image, the size you specify when defining the button
is not used.

    When the Button Editor appears, click on the box next to Image.

    See Picture "Images/ImageBox"

    This will bring up the Image Button Requester.  Click on the
Unnamed Button.

    See Picture "Images/UnnamedImage"

    This will bring up the File Requester.  This requester allows you
to select a Brush File created by a Paint program.  Select the brush
called "left1.br".  Click on the "Show Brush" button.  This will
display a yellow arrow in the center of your window.  Click on the
arrow to return to the File Requester.  Click Ok to return to the
Image Button Requester.  Click Ok again to return to the Button
Editor.

    The Current Highlight is Complement.  This means the button will
change (complement) colors when you click on it.  An Image Button has
an additional Highlight option which shows an alternate Brush Image
when it is clicked.  Lets use this option.  Click on the COMPLEMENT
Button.

    See Picture "Images/ComplementHighlight"

    Click on the Undefined button under the "Another Image" title.

    See Picture "Images/AnotherImage"

    This will bring up the File Requester again.  This time select the
"left2.br" and click Ok.  Click Ok on the Highlight Style Requester to
return to the Button Editor.

    Now to tell the button "what to do" when it is selected.  Click on
the Release Button.  This will bring up the Script Editor.  Click on
the Card Editor Tool Icon.

    See Picture "Images/Card_ET_Icon"

    This Editor Tool allows you to create all kinds of ways of moving
from one Card to another.  Click on the "Prev" button.

    See Picture "Images/PrevButton"

    This will create a single command which will cause your deck to
move to the Previous Card when this button is selected.  Click Ok to
return to the Button Editor.  Click Ok once more to return to the Main
Panel.

    You should see our bright yellow arrow in the upper right corner.
Click on Browse, and then the yellow arrow button you just made.  Ta
Da!  You are now on the first card.  Now you need to add the same
thing to this card.  However, you don't need to go to all that work
again.  Click on the Previous Card Button on the Main Panel to move
back to the other Card.

    You are now going to use a Menu Option to copy the arrow button
and paste it to the first card.  The Main Panel should be the active
window, but just in case, click on a portion which does not have a
Button (the grey under the Screen Up/Down button is a good area).

    Press and hold the right mouse button.  You should see four Menu
Titles.  Position the mouse on the one titled "Mode".  Select Copy.
Your Mouse pointer should now include the text "Copy".  This lets you
know you are in Copy Mode.  Click on the yellow arrow button.  The
yellow arrow button is now in the Copy/Paste Buffer.

    Click on the Previous Card Button on the Main Panel.  This will
display the First Card.  Now Select Paste from the Mode Menu.  This
will bring up the Button Editor.  This allows us to change the button
before it is created.  You won't need to change anything so click Ok.

    Now select Browse on the Main Panel.  You can now easily move
between your two Cards.

    Well, Congratulations.  You have completed the first Test Drive.
While you may have not created the most useful application, you have
learned the basics for creating real applications using CanDo.

    Take a break and have a sandwich or whatever you do when you pull
over for a pitstop.  The second Test Drive will take about hour to
complete.