Amiga Elysian Archive/AmigaElysianArchive.iso/prog/source/cxercise.lha/READ.ME

Text File | 1987-04-20 | 9KB | 191 lines

Amiga Tech User's Group                                 C Special Interest Group


In this directory you'll find 4 executable programs (SimpleWindow1.c, 2.c,
3.c and my version of the menu program presented in the Jan/Feb issue of
Amiga World) along with their source files.  However the source to
'SimpleWindow2' is a hidden file; it's name is made up of non-printable
characters, so it won't be seen in a dir command.  The idea is that if you
are given the source to SimpleWindow 1 & 3, that you write your own program
to duplicate the function of SimpleWindow2.  If you become totally frustrated
by not being able to accomplish the task,  give me a call at [phone]
and I'll tell you the name of the hidden file, so you can RENAME it to some-
thing usable like "SimpleWindow2.c".

First make a backup of this disk (or this directory if you're short on disks)
Then delete the executables from the backup disk (or directory).  Now run the
SimpleWindow1 program from the original disk:

1> cd "to whatever directory SimpleWindow1 is in" <RETURN>
1> simplewindow1 <RETURN>

A window should pop-up on the WorkBench screen, and go away after a few
seconds.

1> simplewindow2 <RETURN>

A window with a close box, front/back gadgets and a dragbar will pop-up, and
a short message is displayed in the body of the window.  You will have to
click in the close box to get it to go away.

1> simplewindow3 <RETURN>

A new screen will cover the WorkBench screen, a window with all the system
gadgets attached will appear on the new screen and some text will be written
into both the screen and the window.  Again click the close box to quit.

Now let's make sure you can get the compiler to compile the first program.
If you have LC 3.1 you will need to setup the compiler environment, which is
best done by modifying your startup-sequence to do this at boot up.  Consult
the installation section of the LC manual (pgs 1-6).  Once this is done, the
command I used to compile all programs here was:

1> lc -L filename <RETURN>

The '-L' causes the linker to automatically be invoked when the program suc-
cessfully compiles.  For some reason, the 'L' must be CAPITALIZED, or BLink
won't be executed.

If you have LC 3.03 the following commands should work:

1> lc filename <RETURN>
1> blink from c.o,filename.o to filename library Amiga.lib,lc.lib <RETURN>

If you don't have BLink, you can use ALink with the same parameters as Blink.


Next let's discuss the programs.  Print them out with the following command:

1> type SampleWindow1.c to PRT: opt n

Repeat for SampleWindow3.c.

This will give you line-numbered listings which I will refer to here.

Looking at SimpleWindow1.c (SW1.c from now on), it starts with a short comment.
In C a comment starts with a slash ('/') and an asterisk ('*'), the text of the
comment, followed by an asterisk and a slash.

On line 9, '#include <exec/types.h>' causes the file 'types.h' in the sub-
directory 'exec' to be compiled as part of this program.  Line 10 does the same
for 'intuition.h' within the 'intuition' sub-directory.  The '.h' files define
various structures and constants that are common to many Amiga programs and
the Amiga's system software.

Line 11 defines 'IntuitionBase' as a pointer to a structure called
'IntuitionBase'.  All Intuition routines require this item to be defined and
initialized before they can be used.  Your programs will not use this variable
directly, but any Intuition routines linked in from 'Amiga.lib' will use it to
establish the location of the entrypoint to each routine (the routines linked
in from 'Amiga.lib' only provide run-time linkage to the actual library rou-
tines).

Line 30 defines 'SampleWindow' as an instance of a NewWindow structure, and
initializes it.  By changing these values and recompiling, the window will
open with the reflected changes in force.  See the "Intuition Reference
Manual" pages 66-68 for the various settings of 'SampleWindow.Flags', which
enable various gadgets, display modes and refresh modes.  See pages 65-70
for info on the NewWindow structure in general.

Line 46 defines the logical entrypoint 'main' and is where your program
starts running.  The physical entrypoint to a program is the first instruction
in 'c.o' which is linked in front of your program's code and provides various
initialization, it then calls main() and when main() returns executes some
cleanup code and exits.  I have defined main() as a 'void' function which
means main() can't return a value to the Amiga's operating system.

Line 50 & 51 define two local variables for main()'s use.

Lines 58-60 is an 'if' statement that initializes 'IntuitionBase' with the
returned value of the OpenLibrary() call.  The '(struct IntuitionBase *)'
is a "cast" operation that tells the compiler to convert (if necessary)
the return value from OpenLibrary() to a pointer to an IntuitionBase struct.
The assignment is then compared with 'NULL' which forms the basis of the if
statement's test.  I generally AND (the '&&' logical operator) a bunch of
OpenXX() function calls together in one if statement (see lines 76-79 of
SW3.c), since I don't like calling a function to kill off my program
('exit()') and I don't like excessive nesting of if statements.  It can be
a nuissance however, to keep all the left and right parentheses properly
paired.  SW1.c has only two OpenXX() function calls so I went ahead and
nested the if statments.

Lines 62-64 is the second 'if statement/OpenXX()' call that opens a window,
and checks to see if the window opened.

Lines 65-66 is just a time-delay loop (which by the way is very processor
inefficient) that doesn't do anything but count to one million using the
variable 'i'.

lines 66 on, close the window and the Intuition library and exit.


SimpleWindow2's abilities are somewhere between SW1 & SW3.


SimpleWindow3 shows how to write text into both screens & windows, the
window has all the system gadgets attached and it opens it's own screen
instead of using the workbench screen.

Lines 16-20 shows the definition of the 'IntuiText' structure, which is used
to write text to a 'RastPort'.

Lines 22-29 define an instance of a NewScreen structure which I called 'NS'.

Line 63 defines 'MyIM' as a place to store a copy of an IntuiMessage.

Line 68 defines the screen pointer that will point to our screen.

Line 69 defines a pointer to IntuiMessages that we will be receiving.
Well, one message anyway.

Line 76-79 again my 'if OpenXX()' logic.

Line 82 looks like a string variable assignment, and in most other languages
it would be.  In C however, this statment merely sets IntuiText.IText to
the address of the first byte of the literal.  The literal itself is stored
in an initialized data hunk,  and never moves or gets copied at all!

Lines 83 & 84 setup pixel coordinates for the starting location of where the
text will be written.  These coordinates are relative to the rastport where
the text is to be written, if it is a screen's rastport LeftEdge will specify
how far (in pixels) the text will be writtten from the leftedge of the screen.
The TopEdge specifies how far down the text will be written.

Line 85 makes the PrintIText() call to display the text.

Line 91 sets the screen pointer within our NewWindow structure to point to
our newly opened screen, so that Intuition will put our window on our screen.
This is the only item that couldn't be pre-initialized since we don't know
where our screen's 'Screen' structure will be stored in memory.

Line 93 makes sure our window opens before proceeding.

Lines 96-100 sets up & prints some text in the newly opened window.
Notice the change of FrontPen to 3 which is orange.

Lines 104-120 is the main IntuiMessage processing "loop" of the program.
In this program it will only execute once because the only message we will
ever receive is the CLOSEWINDOW message.  The reason being, that this is
the only type of message that we told Intuition that we wanted to be
informed of in the IDCMPFlags field of our SampleWindow structure.

Line 105 waits until a message arrives at our Window's UserPort. When the
WaitPort() function returns, we then must get the message's address with the
'IntuiMessage = (struct IntuiMessage *) GetMsg(Window->UserPort);' call on
line 106. Line 107 copies the content of the message to our local data hunk.
Notice the use of the '*' in front of 'IntuiMessage', this causes the data
being pointed to, to be assigned, not the address of the data.

Line 108 ReplyMsg() is called to let Intuition know that we've received it's
message, and can now reclaim the memory that the message is stored in.

Line 120 tests our copy of the message to see if it is a CLOSEWINDOW message.
In this program it has to be, but in more elaborate programs there might be
menu events, mouse events, keyboard events etc.  Each input event generates
a message of a certain class that has to be checked so it can be properly
processed.  Other input event classes should be checked for and processed
within the 'do { } while (MyIM.Class != CLOSEWINDOW);' loop.

Line 122-127 is the cleanup an exit part of the program.