AmigaOS Documentation Wiki - User contributions [en]

AmiWest 2013 Lesson 4

2014-04-13T21:53:33Z

Simon Archer:

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Similar applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions. Aminet has a number
examples of such clients written in ARexx that use the TCP: device
that can be examined.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual filesystem device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one just opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

To begin with, one opens a connection to the internet server as if one
were opening a file. As described above, when Roadshow gets online, it
creates a virtual TCP: device. To open a connection, one opens a file
to the URL and port in question using this format:

<syntaxhighlight>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a websserver.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protoccol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of "HTTP" (or a "Hypertext Transfer Protocol") connection to
a webserver, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets just look at submitting a "GET" request, such
as a web browser, like IBrowse, would do. A simple HTTP version 1.1 GET
request would include the following lines:

<syntaxhighlight>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The <path> would be the rest of the URL (if any) on that system and
<domain> is the name of the server.

Using the "WeatherUnderground" website URL from above and their pathname for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

The GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our
open file handle, as follows:

<syntaxhighlight>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The blank line at the end completes the GET request,
after which the server will reply using the same file handle.

===Listen to the Server===

Once the GET request has been sent to the webserver, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server, you can combine the
domain and path values above and enter them in your web browser:

<syntaxhighlight>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded, viewing the page source (f.e., IBrowse menu item
"Page/Display Source...") will show you the same text that your program
will receive after sending the get request.

As such, your program needs to start reading from the same file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your applcation can parse the received lines for whatever
data your application is tryng to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of these elements are combined in the following example program
"IPClient.c" that asks you for a IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information.

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used and in processing the data sent and received.

Public webservers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any webbrowser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or it invites such
connections (some publish API's for you to make such connections),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecesary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external inputs, your
code should provide for the possibility the connection may not
succeed or that the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make changing those things easy (by the user?).
The parsing strings could be kept in program tooltypes or config
text file, you could provide a GUI for managing the parsing, employ
an external, editable ARexx macro.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demosntrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

· Check stock quotes from a financial site.
· Get package tracking information from a shipping site.
· Check for new emails on a POP email server.
· Convert currencies with a financial or travel web site.
· Check for files on an FTP server.
· Send messages with a SMTP email server.
· Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player?

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then respponds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
if the loop if we read 100 lines - that's a sign something else is
wrong, we should never see that with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use other protocols, we may have to
add our server's "intelligence" elsewhere.

We also do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). In the case of this example, we
will see the entire incoming request printed out on the serial port.
Of course, there's a reason why we have to use the serial for our debug output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of lines
of a very simple webpage to Roadshow and our web visitor:

<syntaxhighlight>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a failsafe). Then we "flush" the output
stream and quit our program.

The request was received, our little webpage sent, we quit and Roadshow takes
care of all the housekeeping.

===EXMAPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
" <TABLE WIDTH=90%><TR><TD><H1>WELCOME</H1> </TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3>AmigaOS IPserver example</TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
" <TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4>And so it begins...</TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this all out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide. Both of these can be configured
using Internet Prefs. You can also make this configuration by editing
the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight>
SYS:Documentation?Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Criticially, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can also make this adjustment to Roadshow's server list by adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga at the port number
following the colon (":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? More Webpages?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an icon
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can respond to web visitors. To dig deeper you can search the
many sources online or in your local bookstore on HTTP communications and
the formatting of HTML webpages. Of course, you should make sure your
server continues outputting the request contents so you know what your server
is getting and should respond to.

===Just Webpages?===

There's also ne reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that your could write a server for. Or you could
create your own online client and server pair of applications that just
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is criticially important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized pathnames and request are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using interprocess
communciations (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each of internet server instance handles an incoming request, gets the information it
needs from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this article.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implrementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosynacracies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

AmigaOS Manual: Workbench Basic Operations

2014-02-01T10:39:39Z

Simon Archer: /* Mouse Pointer */

Before using your Amiga, you should familiarize yourself with the basic Amiga system concepts and techniques provided in this chapter. These include:

* Booting your system
* Using the pointers
* Using the mouse
* Handling disks and using disk drives
* Creating and accessing files and directories

= Booting/Rebooting Your System =

Booting powers on your computer and loads the operating system information from a disk to the computer's memory. Each time the Amiga is booted, the system must find the Amiga system software on a bootable hard disk or floppy disk inserted into a disk drive. If there are no bootable disks when the system is powered on, an animated screen requests that you insert a bootable disk into a floppy drive.

Rebooting resets you computer without turning off the power. This process terminates any active programs and erases any data stored in the Amiga's memory.

For information about booting and rebooting floppy-only systems, see Appendix B.

Each time the Amiga is booted or rebooted, the following events occur:

1. The Amiga executes a script file called the Startup-sequence. The Startup-sequence file contains AmigaDOS commands that load the Amiga software and handle various hardware and software setup tasks.

2. The Startup-sequence executes a script file called User-startup, if you have created it. In general, User-startup files contain your own customized configurations, resident commands, and directory assignments. It also executes a script file called Network-startup. This script is designed to have any programs added to it that may require the networking to be functional before running programs that require it. The script is called in a special way so as not to delay the boot process while the network is initializing, but it will defer programs that rely on the network while it does.
Appendix B offer some instructions and suggestions of items that you can place in the User-startup and Network-startup files.

3. The Amiga Workbench screen appears, as illustrated in Figure 2-1.

[[File:WorkbenchFig2-1.png|center|frame|Workbench Screen]]

4. Workbench runs any programs that are set up in the WBStartup preferences. By adding programs to the WBStartup preferences, you can also customize your system startup.

Do not alter the Startup-sequence file, doing so can prevent the Amiga from booting properly.

To reboot your system:

# Be sure that all disk activity has stopped and that all floppy disk drive and hard disk drive lights are unlit.
# If you are rebooting from a floppy disk drive, insert a copy of the Workbench disk into a floppy disk drive.
# Simultaneously hold down the Ctrl (Control), left Amiga, and right Amiga keys and then release them.

== Special Boot Options ==

Extra memory used for maintaining devices can prevent floppy-based games from running. See Appendix D for information about how to avoid this problem.

= Using the Workbench Pointers =

The Workbench has two pointers: the mouse pointer and the busy pointer.

== Mouse Pointer ==

The mouse pointer is a small movable picture that is used to indicate to the system the location at which you wish to do some operation. By default the mouse pointer is an image of an arrow. The mouse pointer is moved and positioned with the mouse. The tip of the pointer has a hot spot, which is one pixel (a dot of light that makes up the monitor screen display) that the system is programmed to recognize a the pointer's locator. The pointer indicates to the system the position of an item that you wish to work with. Through the mouse, you communicate the action that the system should take on this item. You can change the shape and color of the mouse pointer using the Pointer Preferences editor, described in Chapter 5.

== Busy Pointer ==

The busy pointer, also referred to as the wait pointer, is displayed in place of the mouse pointer to indicate that the system is attempting to execute an instruction. By default the busy pointer is an image of a stopwatch. Most Workbench operations are unavailable while the busy pointer is displayed. However, you can still move, size, and depth-arrange windows with the busy pointer. The appearance of this pointer can also be changed using the Pointer Preferences editor described in Chapter 5.

= Using the Mouse =

The Amiga comes equipped with a mouse, illustrated in Figure 2-2, used to communicate with the system through the pointer. The mouse pointer is positioned by moving the mouse. Manipulating the mouse so that the pointer is located over various objects and pictures on the screen and pressing the mouse buttons tells the Amiga what to do.

[[File:WorkbenchFig2-2.png|center|frame|Amiga Mouse]]

== Holding the Mouse ==

Hold the mouse on a flat surface with the cable extending away from you so that the mouse box rests under the palm of your hand with the buttons under your fingertips. In this position, the left mouse button is the selection button and the right mouse button is the menu button.

== Mouse Operations ==

When using the mouse,

{| class="wikitable"
| Pointing || means moving the mouse so that the tip of the pointer is positioned over an object on the screen. The pointer moves in the same direction you move the mouse. The mouse can be lifted and repositioned at any time. Lifting the mouse does not move the pointer.
|-
| Clicking || means pressing and releasing the selection button.
|-
| Double-Clicking || means clicking the selection button twice in rapid succession. Double-clicking on an icon causes a window to appear or a program to start.
|-
| Holding Down || means pressing the mouse button until your action is completed.
|-
| Dragging || means moving screens, windows, and icons by holding down the selection button and moving the mouse.
|}

== Using the Selection Button ==

The left mouse button is the selection button, used for selecting items on the monitor display for processing. This button is also used to move, or drag, items on the screen. For information about these operations, see Chapter 3.

== Using the Menu Button ==

The right mouse button is the menu button, which is used to display the menu bar and menus and to choose items from them. Menu bars contain the headings of each menu available for a selected window, program, or icon. Menus contain lists of options for the operations that you can do with the selected item.

=== Using Menus ===

Menu bars appear across the top of the screen, containing any menu headings available.

Hold down the menu button to display the menu bar as illustrated in Figure 2-3. Hol down the menu button while pointing to the different menu headings to show the available items listed beneath each. To choose a particular item, move the pointer down and release the menu button when the pointer touches it.

[[File:WorkbenchFig2-3.png|center|frame|Sample Menu Bar and Menu]]

Some menu items have submenus, which are additional related options that appear to the right of the menu item when it is selected. The symbol » after the item name indicates a submenu. If a menu has submenus, select one of the submenu options. Choosing a main menu item without choosing one of its submenus has no effect. In addition to the » symbol, other symbols may appear on the menu:

* An ellipsis (...) follows the name of menu items that open a requester.
* A checkmark in the area to the left of a menu item indicates that the items is an option that is currently selected. When this area is empty, the option is deselected.

To execute several menu options at once, hold down the menu button and, using the selection button, click on the menu options of your choice.

The menu button can also be used to cancel operations being performed by the selection button, such as drag selection.

=== Ghosted Menu Items ===

If a menu item is not available for a particular operation, it is ghosted or displayed less distinctly than the others, as illustrated in Figure 2-4.

[[File:WorkbenchFig2-4.png|center|frame|Ghosted versus Available Menu Items]]

== Canceling an Operation ==

Cancel the operation being performed with the selection button by clicking the menu button while still holding down the selection button. The following operations can be cancelled:

* Selecting
* Dragging
* Drag selection
* Changing the size of a window

== Using the Amiga Without a Mouse ==

All mouse actions can also be done using the keyboard. Certain key combinations allow use of the keyboard to move the pointer, select icons, and choose menu items. Keyboard shortcuts appear in the menu boxes to the right of some options. Holding down the right Amiga key and simultaneously pressing the letter displayed attains the same results as activating that menu option. Using the keyboard shortcuts instead of the menus speeds your work. For a full description of key functions, see the hardware manual for your Amiga model.

= Using Disk Drives =

Disk drives are devices from which information is retrieved or to which information is written or stored. An Amiga can have one or more hard disk drives, as well as floppy disk drives, depending on the model. All Amiga floppy disk drives can use low density floppy disks. However, if you have a high density floppy disk drive on your Amiga, you can also use high density floppy disks. Refer to the hardware manual that came with your system if you are not sure about the type of floppy disk drive you have.

Each disk drive has a device name, such as DF0: for the internal floppy drive. (Additional floppy drives are designated DF1:, DF2:, and DF3:). A disk icon is displayed on the Workbench screen for each disk inserted in a drive and for each hard disk partition.

The device name and the volume name are two ways of identifying a given disk. For most purposes use either name to refer to the disk when entering a path or within a file requester. The device name refers to the disk that is in the specified disk drive. The volume name refers specifically to a particular disk. For example, if you have a floppy disk in device DF0: with a volume name of Mydisk, you can reference it as either DF0: or Mydisk:. Referencing the disk as Mydisk: lets you insert Mydisk into any drive, not only DF0:.

Each drive has an activity light that is lit when the device is in use, either reading or writing data.

{{Note|title=Caution|text=Never reboot or turn off you Amiga and never remove a floppy disk from a floppy disk drive when any of the drive activity lights are lit or you risk damaging the drive and/or the files on the disk.}}

== Inserting Floppy Disks ==

The standard 3.5-inch floppy disk can be inserted only one way. Insert the disk into the disk drive with the label side facing up and the metal end with the indicator arrow entering first.

== Using Floppy Disks ==

Floppy disks must be write-enabled and formatted before information can be written on them. To write-enable a floppy disk, turn the disk to its back side and push the plastic tab in the upper left corner down to cover the hole. Conversely, to write-protect a floppy disk, push the plastic tab up, uncovering the hole Figure 2-5 illustrates the write-enable/protect tab on a floppy disk. Formatting floppy disks is described in Chapter 3.

[[File:WorkbenchFig2-5.png|center|frame|Write Protecting/Enabling Floppy Disks]]

The disk from which information is copied is referred to as the source disk (FROM disk). The disk to which the information is copied is referred to as the destination disk (TO disk). The source disk should always be write-protected to avoid accidental erasure. The destination disk can be a blank disk or a previously used disk whose contents are no longer needed. This disk must be write-enabled to accept the information from the source disk.

== Using the Ram Disk ==

The Ram Disk icon represents RAM:, an area of the Amiga's internal memory that is set up as a file storage device like a disk. Files, directories, and entire floppy disk (available memory permitting) can be copied to RAM: for temporary storage. The Ram Disk serves as a work area that the system can quickly access.

The size of RAM: is dynamic. It is never any larger than necessary to hold its contents. Therefore, it is always 100% full. Its maximum size is limited by the amount of free memory.

The primary advantage of RAM: is speed. Since it is electronic rather than mechanical, storage and retrieval are almost instantaneous. The disadvantage of RAM: is that data stored in RAM: does not survive when the computer is powered down or rebooted. You must save to floppy disk or to hard disk anything in the Ram Disk that you want to use again.

Applications commonly use RAM: to store temporary files created when the program runs or for backup files created when the program is exited. RAM: can also be used as storage for experimental script files, as a destination for testing command output, and when the creation of a file on an actual disk is too slow, risky, or inconvenient.

Be careful when using RAM: for storing important files. If the Amiga loses power, has a software failure, or you reboot, everything stored in RAM: is lost. Be sure when working with RAM: to regularly back up any important files onto disk.

{{Note|You cannot copy a disk to RAM: by dragging the source disk icon over the Ram Disk icon. To copy a disk to RAM:, open the Ram Disk icon and drag the floppy disk icon into the Ram Disk window. This creates a drawer with the name and contents of the floppy disk.}}

== Backup Disks ==

Backup disks ensure against a loss of data in the event of damage, corruption, or accidental erasure of the original disk. We recommend that you make backup copies of important disks and files, following the licensing agreements provided with your applications software. Making and distributing unlicensed copies of disks is a copyright violation known as software piracy. Store your original disks in a safe place and use your backup disks for everyday purposes. For information on making backup copies of your system disks on floppy-only systems, see Appendix B.

= Managing Your Files =

The basic units of data management on your Amiga are files, directories, and drawers. Files are organized collections of data that are given a name and are stored on the system or on removable media. Files are contained in directories or drawers. Directories and drawers are the same thing - a subdivision in your Amiga's filing system that is used to organize files and other directories/drawers (subdirectories).

== Organizing Information on Disks ==

Information should be stored on disk in a logical manner to allow easy access to your files. The Amiga Workbench organizes information into a hierarchical system of drawers.

A drawer - a directory in AmigaDOS - is a container for items that are related. These items can be files and even other drawers.

On any disk you can create multiple drawers containing multiple files, as available disk space allows. Workbench also allows the creation of drawers within drawers, subdrawers or subdirectories, for further file management. Create as many drawers and subdrawers on your disk as needed.

A drawer icon is displayed in the disk window for each drawer created on a particular disk. Each drawer window contains the icons of the files and subdrawers that exist in it.

== Paths ==

A path is a complete description of the location of a particular file on a disk. When a program requests the name of a file for retrieval, specify the file's path, including the volume or device name and all the drawers that lead to that file.

The method for specifying paths varies from program to program. Most programs use a file requester with a scrolling list, in which the disk name, any drawer names, and the file name are displayed. Click on the appropriate names to specify the path. However, for some programs you may have to type in the complete path name.

To enter a complete path:

* Type the name of the disk followed by a colon. This name is the volume name of the disk, such as Mydisk:. You can substitute the disk's device name, such as DF0:, in place of the disk name. However, if you enter the device name rather than the volume name, be sure the correct disk is in that device. Diskname:

* For a file that is not in a drawer, specify the file name after the colon following the disk name to complete the path. Diskname:filename

* For a file in a drawer, after the colon following the disk name specify the drawer name followed by a slash (/) followed by the file name. Diskname:drawername/filename

* If there are more drawers in the path, each drawer must be specified followed by a slash. Diskname:drawername/subdrawername/filename

{{Note|File and drawer names containing spaces can cause recognition problems. We recommend that you avoid using spaces in file or drawer names. If you have trouble referencing a name that contains a space, enclose the entire path in double quotation marks.}}

== File and Drawer Names ==

The following rules apply for naming files and drawers:

* Names can be up to 30 characters long. Names can contain upper case letters and any punctuation marks that are not reserved.
* Colons (:) and slashes (/) are not allowed within a name. These characters are reserved for path statements. However, other non-alphabetic characters can be used.
* The use of spaces before or after names should be avoided due to the possibility of omission.
* Upper and lower case differences (capitalization) are preserved and displayed by the Amiga. However, the system is not case-sensitive: upper and lower case are considered the same.
* Duplicate file names are not allowed within the same drawer. If you save a file with the same name as an existing file in a drawer, it overwrites the original file in that drawer.
* Two files with the same name can exist in separate drawers or within different paths.

== Trashcan ==

The Trashcan is a special drawer that can be placed on a disk for storing files that you no longer needed and may wish to delete. Discard icons or pseudo-icons for the files to be deleted by dragging them into the Trashcan. If the icon to be discarded is a drawer, is associated files are also moved to the Trashcan.

Choosing Empty Trash from the Icons menu deletes the icons and all of their associated files from the Trashcan. Before choosing Empty Trash, you can still recover any of the Trashcan's contents by opening its window and dragging the icons back out.

For more information about putting a Trashcan on a disk, see the Format Disk description in Chapter 3.

= Using Application Software =

Applications are software programs, such as databases, video and sound programs, word processing programs, recreational programs, and educational programs that are available for use on your Amiga. Most Amiga programs use windows, menus, and gadgets in ways very similar to the Workbench programs on your system disks. However, you should always read the documentation that comes with your applications for directions on using unfamiliar menu items and gadgets.

AmigaOS Manual: Workbench Basic Operations

2014-02-01T10:34:46Z

Simon Archer: /* Booting/Rebooting Your System */

Before using your Amiga, you should familiarize yourself with the basic Amiga system concepts and techniques provided in this chapter. These include:

* Booting your system
* Using the pointers
* Using the mouse
* Handling disks and using disk drives
* Creating and accessing files and directories

= Booting/Rebooting Your System =

Booting powers on your computer and loads the operating system information from a disk to the computer's memory. Each time the Amiga is booted, the system must find the Amiga system software on a bootable hard disk or floppy disk inserted into a disk drive. If there are no bootable disks when the system is powered on, an animated screen requests that you insert a bootable disk into a floppy drive.

Rebooting resets you computer without turning off the power. This process terminates any active programs and erases any data stored in the Amiga's memory.

For information about booting and rebooting floppy-only systems, see Appendix B.

Each time the Amiga is booted or rebooted, the following events occur:

1. The Amiga executes a script file called the Startup-sequence. The Startup-sequence file contains AmigaDOS commands that load the Amiga software and handle various hardware and software setup tasks.

2. The Startup-sequence executes a script file called User-startup, if you have created it. In general, User-startup files contain your own customized configurations, resident commands, and directory assignments. It also executes a script file called Network-startup. This script is designed to have any programs added to it that may require the networking to be functional before running programs that require it. The script is called in a special way so as not to delay the boot process while the network is initializing, but it will defer programs that rely on the network while it does.
Appendix B offer some instructions and suggestions of items that you can place in the User-startup and Network-startup files.

3. The Amiga Workbench screen appears, as illustrated in Figure 2-1.

[[File:WorkbenchFig2-1.png|center|frame|Workbench Screen]]

4. Workbench runs any programs that are set up in the WBStartup preferences. By adding programs to the WBStartup preferences, you can also customize your system startup.

Do not alter the Startup-sequence file, doing so can prevent the Amiga from booting properly.

To reboot your system:

# Be sure that all disk activity has stopped and that all floppy disk drive and hard disk drive lights are unlit.
# If you are rebooting from a floppy disk drive, insert a copy of the Workbench disk into a floppy disk drive.
# Simultaneously hold down the Ctrl (Control), left Amiga, and right Amiga keys and then release them.

== Special Boot Options ==

Extra memory used for maintaining devices can prevent floppy-based games from running. See Appendix D for information about how to avoid this problem.

= Using the Workbench Pointers =

The Workbench has two pointers: the mouse pointer and the busy pointer.

== Mouse Pointer ==

The mouse pointer is a small movable picture that is used to indicate to te system the location at which you wish to do some operation. By default the mouse pointer is an image of an arrow. The mouse pointer is moved and positioned with the mouse. The tip of the pointer has a hot spot, which is one pixel (a dot of light that makes up the monitor screen display) that the system is programmed to recognize a the pointer's locator. The pointer indicates to the system the position of an item that you wish to work with. Through the mouse, you communicate the action that the system should take on this item. You can change the shape and color of the mouse pointer using the Pointer Preferences editor, described in Chapter 5.

== Busy Pointer ==

The busy pointer, also referred to as the wait pointer, is displayed in place of the mouse pointer to indicate that the system is attempting to execute an instruction. By default the busy pointer is an image of a stopwatch. Most Workbench operations are unavailable while the busy pointer is displayed. However, you can still move, size, and depth-arrange windows with the busy pointer. The appearance of this pointer can also be changed using the Pointer Preferences editor described in Chapter 5.

= Using the Mouse =

The Amiga comes equipped with a mouse, illustrated in Figure 2-2, used to communicate with the system through the pointer. The mouse pointer is positioned by moving the mouse. Manipulating the mouse so that the pointer is located over various objects and pictures on the screen and pressing the mouse buttons tells the Amiga what to do.

[[File:WorkbenchFig2-2.png|center|frame|Amiga Mouse]]

== Holding the Mouse ==

Hold the mouse on a flat surface with the cable extending away from you so that the mouse box rests under the palm of your hand with the buttons under your fingertips. In this position, the left mouse button is the selection button and the right mouse button is the menu button.

== Mouse Operations ==

When using the mouse,

{| class="wikitable"
| Pointing || means moving the mouse so that the tip of the pointer is positioned over an object on the screen. The pointer moves in the same direction you move the mouse. The mouse can be lifted and repositioned at any time. Lifting the mouse does not move the pointer.
|-
| Clicking || means pressing and releasing the selection button.
|-
| Double-Clicking || means clicking the selection button twice in rapid succession. Double-clicking on an icon causes a window to appear or a program to start.
|-
| Holding Down || means pressing the mouse button until your action is completed.
|-
| Dragging || means moving screens, windows, and icons by holding down the selection button and moving the mouse.
|}

== Using the Selection Button ==

The left mouse button is the selection button, used for selecting items on the monitor display for processing. This button is also used to move, or drag, items on the screen. For information about these operations, see Chapter 3.

== Using the Menu Button ==

The right mouse button is the menu button, which is used to display the menu bar and menus and to choose items from them. Menu bars contain the headings of each menu available for a selected window, program, or icon. Menus contain lists of options for the operations that you can do with the selected item.

=== Using Menus ===

Menu bars appear across the top of the screen, containing any menu headings available.

Hold down the menu button to display the menu bar as illustrated in Figure 2-3. Hol down the menu button while pointing to the different menu headings to show the available items listed beneath each. To choose a particular item, move the pointer down and release the menu button when the pointer touches it.

[[File:WorkbenchFig2-3.png|center|frame|Sample Menu Bar and Menu]]

Some menu items have submenus, which are additional related options that appear to the right of the menu item when it is selected. The symbol » after the item name indicates a submenu. If a menu has submenus, select one of the submenu options. Choosing a main menu item without choosing one of its submenus has no effect. In addition to the » symbol, other symbols may appear on the menu:

* An ellipsis (...) follows the name of menu items that open a requester.
* A checkmark in the area to the left of a menu item indicates that the items is an option that is currently selected. When this area is empty, the option is deselected.

To execute several menu options at once, hold down the menu button and, using the selection button, click on the menu options of your choice.

The menu button can also be used to cancel operations being performed by the selection button, such as drag selection.

=== Ghosted Menu Items ===

If a menu item is not available for a particular operation, it is ghosted or displayed less distinctly than the others, as illustrated in Figure 2-4.

[[File:WorkbenchFig2-4.png|center|frame|Ghosted versus Available Menu Items]]

== Canceling an Operation ==

Cancel the operation being performed with the selection button by clicking the menu button while still holding down the selection button. The following operations can be cancelled:

* Selecting
* Dragging
* Drag selection
* Changing the size of a window

== Using the Amiga Without a Mouse ==

All mouse actions can also be done using the keyboard. Certain key combinations allow use of the keyboard to move the pointer, select icons, and choose menu items. Keyboard shortcuts appear in the menu boxes to the right of some options. Holding down the right Amiga key and simultaneously pressing the letter displayed attains the same results as activating that menu option. Using the keyboard shortcuts instead of the menus speeds your work. For a full description of key functions, see the hardware manual for your Amiga model.

= Using Disk Drives =

Disk drives are devices from which information is retrieved or to which information is written or stored. An Amiga can have one or more hard disk drives, as well as floppy disk drives, depending on the model. All Amiga floppy disk drives can use low density floppy disks. However, if you have a high density floppy disk drive on your Amiga, you can also use high density floppy disks. Refer to the hardware manual that came with your system if you are not sure about the type of floppy disk drive you have.

Each disk drive has a device name, such as DF0: for the internal floppy drive. (Additional floppy drives are designated DF1:, DF2:, and DF3:). A disk icon is displayed on the Workbench screen for each disk inserted in a drive and for each hard disk partition.

The device name and the volume name are two ways of identifying a given disk. For most purposes use either name to refer to the disk when entering a path or within a file requester. The device name refers to the disk that is in the specified disk drive. The volume name refers specifically to a particular disk. For example, if you have a floppy disk in device DF0: with a volume name of Mydisk, you can reference it as either DF0: or Mydisk:. Referencing the disk as Mydisk: lets you insert Mydisk into any drive, not only DF0:.

Each drive has an activity light that is lit when the device is in use, either reading or writing data.

{{Note|title=Caution|text=Never reboot or turn off you Amiga and never remove a floppy disk from a floppy disk drive when any of the drive activity lights are lit or you risk damaging the drive and/or the files on the disk.}}

== Inserting Floppy Disks ==

The standard 3.5-inch floppy disk can be inserted only one way. Insert the disk into the disk drive with the label side facing up and the metal end with the indicator arrow entering first.

== Using Floppy Disks ==

Floppy disks must be write-enabled and formatted before information can be written on them. To write-enable a floppy disk, turn the disk to its back side and push the plastic tab in the upper left corner down to cover the hole. Conversely, to write-protect a floppy disk, push the plastic tab up, uncovering the hole Figure 2-5 illustrates the write-enable/protect tab on a floppy disk. Formatting floppy disks is described in Chapter 3.

[[File:WorkbenchFig2-5.png|center|frame|Write Protecting/Enabling Floppy Disks]]

The disk from which information is copied is referred to as the source disk (FROM disk). The disk to which the information is copied is referred to as the destination disk (TO disk). The source disk should always be write-protected to avoid accidental erasure. The destination disk can be a blank disk or a previously used disk whose contents are no longer needed. This disk must be write-enabled to accept the information from the source disk.

== Using the Ram Disk ==

The Ram Disk icon represents RAM:, an area of the Amiga's internal memory that is set up as a file storage device like a disk. Files, directories, and entire floppy disk (available memory permitting) can be copied to RAM: for temporary storage. The Ram Disk serves as a work area that the system can quickly access.

The size of RAM: is dynamic. It is never any larger than necessary to hold its contents. Therefore, it is always 100% full. Its maximum size is limited by the amount of free memory.

The primary advantage of RAM: is speed. Since it is electronic rather than mechanical, storage and retrieval are almost instantaneous. The disadvantage of RAM: is that data stored in RAM: does not survive when the computer is powered down or rebooted. You must save to floppy disk or to hard disk anything in the Ram Disk that you want to use again.

Applications commonly use RAM: to store temporary files created when the program runs or for backup files created when the program is exited. RAM: can also be used as storage for experimental script files, as a destination for testing command output, and when the creation of a file on an actual disk is too slow, risky, or inconvenient.

Be careful when using RAM: for storing important files. If the Amiga loses power, has a software failure, or you reboot, everything stored in RAM: is lost. Be sure when working with RAM: to regularly back up any important files onto disk.

{{Note|You cannot copy a disk to RAM: by dragging the source disk icon over the Ram Disk icon. To copy a disk to RAM:, open the Ram Disk icon and drag the floppy disk icon into the Ram Disk window. This creates a drawer with the name and contents of the floppy disk.}}

== Backup Disks ==

Backup disks ensure against a loss of data in the event of damage, corruption, or accidental erasure of the original disk. We recommend that you make backup copies of important disks and files, following the licensing agreements provided with your applications software. Making and distributing unlicensed copies of disks is a copyright violation known as software piracy. Store your original disks in a safe place and use your backup disks for everyday purposes. For information on making backup copies of your system disks on floppy-only systems, see Appendix B.

= Managing Your Files =

The basic units of data management on your Amiga are files, directories, and drawers. Files are organized collections of data that are given a name and are stored on the system or on removable media. Files are contained in directories or drawers. Directories and drawers are the same thing - a subdivision in your Amiga's filing system that is used to organize files and other directories/drawers (subdirectories).

== Organizing Information on Disks ==

Information should be stored on disk in a logical manner to allow easy access to your files. The Amiga Workbench organizes information into a hierarchical system of drawers.

A drawer - a directory in AmigaDOS - is a container for items that are related. These items can be files and even other drawers.

On any disk you can create multiple drawers containing multiple files, as available disk space allows. Workbench also allows the creation of drawers within drawers, subdrawers or subdirectories, for further file management. Create as many drawers and subdrawers on your disk as needed.

A drawer icon is displayed in the disk window for each drawer created on a particular disk. Each drawer window contains the icons of the files and subdrawers that exist in it.

== Paths ==

A path is a complete description of the location of a particular file on a disk. When a program requests the name of a file for retrieval, specify the file's path, including the volume or device name and all the drawers that lead to that file.

The method for specifying paths varies from program to program. Most programs use a file requester with a scrolling list, in which the disk name, any drawer names, and the file name are displayed. Click on the appropriate names to specify the path. However, for some programs you may have to type in the complete path name.

To enter a complete path:

* Type the name of the disk followed by a colon. This name is the volume name of the disk, such as Mydisk:. You can substitute the disk's device name, such as DF0:, in place of the disk name. However, if you enter the device name rather than the volume name, be sure the correct disk is in that device. Diskname:

* For a file that is not in a drawer, specify the file name after the colon following the disk name to complete the path. Diskname:filename

* For a file in a drawer, after the colon following the disk name specify the drawer name followed by a slash (/) followed by the file name. Diskname:drawername/filename

* If there are more drawers in the path, each drawer must be specified followed by a slash. Diskname:drawername/subdrawername/filename

{{Note|File and drawer names containing spaces can cause recognition problems. We recommend that you avoid using spaces in file or drawer names. If you have trouble referencing a name that contains a space, enclose the entire path in double quotation marks.}}

== File and Drawer Names ==

The following rules apply for naming files and drawers:

* Names can be up to 30 characters long. Names can contain upper case letters and any punctuation marks that are not reserved.
* Colons (:) and slashes (/) are not allowed within a name. These characters are reserved for path statements. However, other non-alphabetic characters can be used.
* The use of spaces before or after names should be avoided due to the possibility of omission.
* Upper and lower case differences (capitalization) are preserved and displayed by the Amiga. However, the system is not case-sensitive: upper and lower case are considered the same.
* Duplicate file names are not allowed within the same drawer. If you save a file with the same name as an existing file in a drawer, it overwrites the original file in that drawer.
* Two files with the same name can exist in separate drawers or within different paths.

== Trashcan ==

The Trashcan is a special drawer that can be placed on a disk for storing files that you no longer needed and may wish to delete. Discard icons or pseudo-icons for the files to be deleted by dragging them into the Trashcan. If the icon to be discarded is a drawer, is associated files are also moved to the Trashcan.

Choosing Empty Trash from the Icons menu deletes the icons and all of their associated files from the Trashcan. Before choosing Empty Trash, you can still recover any of the Trashcan's contents by opening its window and dragging the icons back out.

For more information about putting a Trashcan on a disk, see the Format Disk description in Chapter 3.

= Using Application Software =

Applications are software programs, such as databases, video and sound programs, word processing programs, recreational programs, and educational programs that are available for use on your Amiga. Most Amiga programs use windows, menus, and gadgets in ways very similar to the Workbench programs on your system disks. However, you should always read the documentation that comes with your applications for directions on using unfamiliar menu items and gadgets.

AmigaOS Manual: Workbench Basic Operations

2014-02-01T10:33:39Z

Simon Archer: /* Booting/Rebooting Your System */

Before using your Amiga, you should familiarize yourself with the basic Amiga system concepts and techniques provided in this chapter. These include:

* Booting your system
* Using the pointers
* Using the mouse
* Handling disks and using disk drives
* Creating and accessing files and directories

= Booting/Rebooting Your System =

Booting powers on your computer and loads the operating system information from a disk to the computer's memory. Each time the Amiga is booted, the system must find the Amiga system software on a bootable hard disk or floppy disk inserted into a disk drive. If there are no bootable disks when the system is powered on, an animated screen requests that you insert a bootable disk into a floppy drive.

Rebooting resets you computer without turning off the power. This process terminates any active programs and erases any data stored in the Amiga's memory.

For information about booting and rebooting floppy-only systems, see Appendix B.

Each time the Amiga is booted or rebooted, the following events occur:

1. The Amiga executes a script file called the Startup-sequence. The Startup-sequence file contains AmigaDOS commands that load the Amiga software and handle various hardware and software setup tasks.

2. The Startup-sequence executes a script file called User-startup, if you have created it. In general, User-startup files contain your own customized configurations, resident commands, and directory assignments. It also executes a script file called Network-startup. This script is designed to have any programs added to it that may require the networking to be functional before running programs that require it. The script is called in a special way so as not to hold up the boot process while the network is "coming up", but it will hold off programs that rely on the network while it does.
Appendix B offer some instructions and suggestions of items that you can place in the User-startup and Network-startup files.

3. The Amiga Workbench screen appears, as illustrated in Figure 2-1.

[[File:WorkbenchFig2-1.png|center|frame|Workbench Screen]]

4. Workbench runs any programs that are set up in the WBStartup preferences. By adding programs to the WBStartup preferences, you can also customize your system startup.

Do not alter the Startup-sequence file, doing so can prevent the Amiga from booting properly.

To reboot your system:

# Be sure that all disk activity has stopped and that all floppy disk drive and hard disk drive lights are unlit.
# If you are rebooting from a floppy disk drive, insert a copy of the Workbench disk into a floppy disk drive.
# Simultaneously hold down the Ctrl (Control), left Amiga, and right Amiga keys and then release them.

== Special Boot Options ==

Extra memory used for maintaining devices can prevent floppy-based games from running. See Appendix D for information about how to avoid this problem.

= Using the Workbench Pointers =

The Workbench has two pointers: the mouse pointer and the busy pointer.

== Mouse Pointer ==

The mouse pointer is a small movable picture that is used to indicate to te system the location at which you wish to do some operation. By default the mouse pointer is an image of an arrow. The mouse pointer is moved and positioned with the mouse. The tip of the pointer has a hot spot, which is one pixel (a dot of light that makes up the monitor screen display) that the system is programmed to recognize a the pointer's locator. The pointer indicates to the system the position of an item that you wish to work with. Through the mouse, you communicate the action that the system should take on this item. You can change the shape and color of the mouse pointer using the Pointer Preferences editor, described in Chapter 5.

== Busy Pointer ==

The busy pointer, also referred to as the wait pointer, is displayed in place of the mouse pointer to indicate that the system is attempting to execute an instruction. By default the busy pointer is an image of a stopwatch. Most Workbench operations are unavailable while the busy pointer is displayed. However, you can still move, size, and depth-arrange windows with the busy pointer. The appearance of this pointer can also be changed using the Pointer Preferences editor described in Chapter 5.

= Using the Mouse =

The Amiga comes equipped with a mouse, illustrated in Figure 2-2, used to communicate with the system through the pointer. The mouse pointer is positioned by moving the mouse. Manipulating the mouse so that the pointer is located over various objects and pictures on the screen and pressing the mouse buttons tells the Amiga what to do.

[[File:WorkbenchFig2-2.png|center|frame|Amiga Mouse]]

== Holding the Mouse ==

Hold the mouse on a flat surface with the cable extending away from you so that the mouse box rests under the palm of your hand with the buttons under your fingertips. In this position, the left mouse button is the selection button and the right mouse button is the menu button.

== Mouse Operations ==

When using the mouse,

{| class="wikitable"
| Pointing || means moving the mouse so that the tip of the pointer is positioned over an object on the screen. The pointer moves in the same direction you move the mouse. The mouse can be lifted and repositioned at any time. Lifting the mouse does not move the pointer.
|-
| Clicking || means pressing and releasing the selection button.
|-
| Double-Clicking || means clicking the selection button twice in rapid succession. Double-clicking on an icon causes a window to appear or a program to start.
|-
| Holding Down || means pressing the mouse button until your action is completed.
|-
| Dragging || means moving screens, windows, and icons by holding down the selection button and moving the mouse.
|}

== Using the Selection Button ==

The left mouse button is the selection button, used for selecting items on the monitor display for processing. This button is also used to move, or drag, items on the screen. For information about these operations, see Chapter 3.

== Using the Menu Button ==

The right mouse button is the menu button, which is used to display the menu bar and menus and to choose items from them. Menu bars contain the headings of each menu available for a selected window, program, or icon. Menus contain lists of options for the operations that you can do with the selected item.

=== Using Menus ===

Menu bars appear across the top of the screen, containing any menu headings available.

Hold down the menu button to display the menu bar as illustrated in Figure 2-3. Hol down the menu button while pointing to the different menu headings to show the available items listed beneath each. To choose a particular item, move the pointer down and release the menu button when the pointer touches it.

[[File:WorkbenchFig2-3.png|center|frame|Sample Menu Bar and Menu]]

Some menu items have submenus, which are additional related options that appear to the right of the menu item when it is selected. The symbol » after the item name indicates a submenu. If a menu has submenus, select one of the submenu options. Choosing a main menu item without choosing one of its submenus has no effect. In addition to the » symbol, other symbols may appear on the menu:

* An ellipsis (...) follows the name of menu items that open a requester.
* A checkmark in the area to the left of a menu item indicates that the items is an option that is currently selected. When this area is empty, the option is deselected.

To execute several menu options at once, hold down the menu button and, using the selection button, click on the menu options of your choice.

The menu button can also be used to cancel operations being performed by the selection button, such as drag selection.

=== Ghosted Menu Items ===

If a menu item is not available for a particular operation, it is ghosted or displayed less distinctly than the others, as illustrated in Figure 2-4.

[[File:WorkbenchFig2-4.png|center|frame|Ghosted versus Available Menu Items]]

== Canceling an Operation ==

Cancel the operation being performed with the selection button by clicking the menu button while still holding down the selection button. The following operations can be cancelled:

* Selecting
* Dragging
* Drag selection
* Changing the size of a window

== Using the Amiga Without a Mouse ==

All mouse actions can also be done using the keyboard. Certain key combinations allow use of the keyboard to move the pointer, select icons, and choose menu items. Keyboard shortcuts appear in the menu boxes to the right of some options. Holding down the right Amiga key and simultaneously pressing the letter displayed attains the same results as activating that menu option. Using the keyboard shortcuts instead of the menus speeds your work. For a full description of key functions, see the hardware manual for your Amiga model.

= Using Disk Drives =

Disk drives are devices from which information is retrieved or to which information is written or stored. An Amiga can have one or more hard disk drives, as well as floppy disk drives, depending on the model. All Amiga floppy disk drives can use low density floppy disks. However, if you have a high density floppy disk drive on your Amiga, you can also use high density floppy disks. Refer to the hardware manual that came with your system if you are not sure about the type of floppy disk drive you have.

Each disk drive has a device name, such as DF0: for the internal floppy drive. (Additional floppy drives are designated DF1:, DF2:, and DF3:). A disk icon is displayed on the Workbench screen for each disk inserted in a drive and for each hard disk partition.

The device name and the volume name are two ways of identifying a given disk. For most purposes use either name to refer to the disk when entering a path or within a file requester. The device name refers to the disk that is in the specified disk drive. The volume name refers specifically to a particular disk. For example, if you have a floppy disk in device DF0: with a volume name of Mydisk, you can reference it as either DF0: or Mydisk:. Referencing the disk as Mydisk: lets you insert Mydisk into any drive, not only DF0:.

Each drive has an activity light that is lit when the device is in use, either reading or writing data.

{{Note|title=Caution|text=Never reboot or turn off you Amiga and never remove a floppy disk from a floppy disk drive when any of the drive activity lights are lit or you risk damaging the drive and/or the files on the disk.}}

== Inserting Floppy Disks ==

The standard 3.5-inch floppy disk can be inserted only one way. Insert the disk into the disk drive with the label side facing up and the metal end with the indicator arrow entering first.

== Using Floppy Disks ==

Floppy disks must be write-enabled and formatted before information can be written on them. To write-enable a floppy disk, turn the disk to its back side and push the plastic tab in the upper left corner down to cover the hole. Conversely, to write-protect a floppy disk, push the plastic tab up, uncovering the hole Figure 2-5 illustrates the write-enable/protect tab on a floppy disk. Formatting floppy disks is described in Chapter 3.

[[File:WorkbenchFig2-5.png|center|frame|Write Protecting/Enabling Floppy Disks]]

The disk from which information is copied is referred to as the source disk (FROM disk). The disk to which the information is copied is referred to as the destination disk (TO disk). The source disk should always be write-protected to avoid accidental erasure. The destination disk can be a blank disk or a previously used disk whose contents are no longer needed. This disk must be write-enabled to accept the information from the source disk.

== Using the Ram Disk ==

The Ram Disk icon represents RAM:, an area of the Amiga's internal memory that is set up as a file storage device like a disk. Files, directories, and entire floppy disk (available memory permitting) can be copied to RAM: for temporary storage. The Ram Disk serves as a work area that the system can quickly access.

The size of RAM: is dynamic. It is never any larger than necessary to hold its contents. Therefore, it is always 100% full. Its maximum size is limited by the amount of free memory.

The primary advantage of RAM: is speed. Since it is electronic rather than mechanical, storage and retrieval are almost instantaneous. The disadvantage of RAM: is that data stored in RAM: does not survive when the computer is powered down or rebooted. You must save to floppy disk or to hard disk anything in the Ram Disk that you want to use again.

Applications commonly use RAM: to store temporary files created when the program runs or for backup files created when the program is exited. RAM: can also be used as storage for experimental script files, as a destination for testing command output, and when the creation of a file on an actual disk is too slow, risky, or inconvenient.

Be careful when using RAM: for storing important files. If the Amiga loses power, has a software failure, or you reboot, everything stored in RAM: is lost. Be sure when working with RAM: to regularly back up any important files onto disk.

{{Note|You cannot copy a disk to RAM: by dragging the source disk icon over the Ram Disk icon. To copy a disk to RAM:, open the Ram Disk icon and drag the floppy disk icon into the Ram Disk window. This creates a drawer with the name and contents of the floppy disk.}}

== Backup Disks ==

Backup disks ensure against a loss of data in the event of damage, corruption, or accidental erasure of the original disk. We recommend that you make backup copies of important disks and files, following the licensing agreements provided with your applications software. Making and distributing unlicensed copies of disks is a copyright violation known as software piracy. Store your original disks in a safe place and use your backup disks for everyday purposes. For information on making backup copies of your system disks on floppy-only systems, see Appendix B.

= Managing Your Files =

The basic units of data management on your Amiga are files, directories, and drawers. Files are organized collections of data that are given a name and are stored on the system or on removable media. Files are contained in directories or drawers. Directories and drawers are the same thing - a subdivision in your Amiga's filing system that is used to organize files and other directories/drawers (subdirectories).

== Organizing Information on Disks ==

Information should be stored on disk in a logical manner to allow easy access to your files. The Amiga Workbench organizes information into a hierarchical system of drawers.

A drawer - a directory in AmigaDOS - is a container for items that are related. These items can be files and even other drawers.

On any disk you can create multiple drawers containing multiple files, as available disk space allows. Workbench also allows the creation of drawers within drawers, subdrawers or subdirectories, for further file management. Create as many drawers and subdrawers on your disk as needed.

A drawer icon is displayed in the disk window for each drawer created on a particular disk. Each drawer window contains the icons of the files and subdrawers that exist in it.

== Paths ==

A path is a complete description of the location of a particular file on a disk. When a program requests the name of a file for retrieval, specify the file's path, including the volume or device name and all the drawers that lead to that file.

The method for specifying paths varies from program to program. Most programs use a file requester with a scrolling list, in which the disk name, any drawer names, and the file name are displayed. Click on the appropriate names to specify the path. However, for some programs you may have to type in the complete path name.

To enter a complete path:

* Type the name of the disk followed by a colon. This name is the volume name of the disk, such as Mydisk:. You can substitute the disk's device name, such as DF0:, in place of the disk name. However, if you enter the device name rather than the volume name, be sure the correct disk is in that device. Diskname:

* For a file that is not in a drawer, specify the file name after the colon following the disk name to complete the path. Diskname:filename

* For a file in a drawer, after the colon following the disk name specify the drawer name followed by a slash (/) followed by the file name. Diskname:drawername/filename

* If there are more drawers in the path, each drawer must be specified followed by a slash. Diskname:drawername/subdrawername/filename

{{Note|File and drawer names containing spaces can cause recognition problems. We recommend that you avoid using spaces in file or drawer names. If you have trouble referencing a name that contains a space, enclose the entire path in double quotation marks.}}

== File and Drawer Names ==

The following rules apply for naming files and drawers:

* Names can be up to 30 characters long. Names can contain upper case letters and any punctuation marks that are not reserved.
* Colons (:) and slashes (/) are not allowed within a name. These characters are reserved for path statements. However, other non-alphabetic characters can be used.
* The use of spaces before or after names should be avoided due to the possibility of omission.
* Upper and lower case differences (capitalization) are preserved and displayed by the Amiga. However, the system is not case-sensitive: upper and lower case are considered the same.
* Duplicate file names are not allowed within the same drawer. If you save a file with the same name as an existing file in a drawer, it overwrites the original file in that drawer.
* Two files with the same name can exist in separate drawers or within different paths.

== Trashcan ==

The Trashcan is a special drawer that can be placed on a disk for storing files that you no longer needed and may wish to delete. Discard icons or pseudo-icons for the files to be deleted by dragging them into the Trashcan. If the icon to be discarded is a drawer, is associated files are also moved to the Trashcan.

Choosing Empty Trash from the Icons menu deletes the icons and all of their associated files from the Trashcan. Before choosing Empty Trash, you can still recover any of the Trashcan's contents by opening its window and dragging the icons back out.

For more information about putting a Trashcan on a disk, see the Format Disk description in Chapter 3.

= Using Application Software =

Applications are software programs, such as databases, video and sound programs, word processing programs, recreational programs, and educational programs that are available for use on your Amiga. Most Amiga programs use windows, menus, and gadgets in ways very similar to the Workbench programs on your system disks. However, you should always read the documentation that comes with your applications for directions on using unfamiliar menu items and gadgets.

AmigaOS Manual: Workbench Basic Operations

2014-02-01T10:32:38Z

Simon Archer:

Before using your Amiga, you should familiarize yourself with the basic Amiga system concepts and techniques provided in this chapter. These include:

* Booting your system
* Using the pointers
* Using the mouse
* Handling disks and using disk drives
* Creating and accessing files and directories

= Booting/Rebooting Your System =

Booting powers on your computer and loads the operating system information from a disk to the computer's memory. Each time the Amiga is booted, the system must find the Amiga system software on a bootable hard disk or floppy disk inserted into a disk drive. If there are no bootable disks when the system is powered on, an animated screen requests that you insert a bootable disk into a floppy drive.

Rebooting resets you computer without turning off the power. This process terminates any active programs and erases any data stored in the Amiga's memory.

For information about booting and rebooting floppy-only systems, see Appendix B.

Each time the Amiga is booted or rebooted, the following events occur:

1. The Amiga executes a script file called the Startup-sequence. The Startup-sequence file contains AmigaDOS commands that load the Amiga software and handle various hardware and software setup tasks.

2. The Startup-sequence executes a script file called User-startup, if you have created it. In general, User-startup files contain your own customized configurations, resident commands, and directory assignments. It also executes a script file called Network-startup. This script is designed to have any programs added to it that may require the networking functional before running programs that require it. The script is called in a special way so as not to hold up the boot process while the network is "coming up", but it will hold off programs that rely on the network while it does.
Appendix B offer some instructions and suggestions of items that you can place in the User-startup and Network-startup files.

3. The Amiga Workbench screen appears, as illustrated in Figure 2-1.

[[File:WorkbenchFig2-1.png|center|frame|Workbench Screen]]

4. Workbench runs any programs that are set up in the WBStartup preferences. By adding programs to the WBStartup preferences, you can also customize your system startup.

Do not alter the Startup-sequence file, doing so can prevent the Amiga from booting properly.

To reboot your system:

# Be sure that all disk activity has stopped and that all floppy disk drive and hard disk drive lights are unlit.
# If you are rebooting from a floppy disk drive, insert a copy of the Workbench disk into a floppy disk drive.
# Simultaneously hold down the Ctrl (Control), left Amiga, and right Amiga keys and then release them.

== Special Boot Options ==

Extra memory used for maintaining devices can prevent floppy-based games from running. See Appendix D for information about how to avoid this problem.

= Using the Workbench Pointers =

The Workbench has two pointers: the mouse pointer and the busy pointer.

== Mouse Pointer ==

The mouse pointer is a small movable picture that is used to indicate to te system the location at which you wish to do some operation. By default the mouse pointer is an image of an arrow. The mouse pointer is moved and positioned with the mouse. The tip of the pointer has a hot spot, which is one pixel (a dot of light that makes up the monitor screen display) that the system is programmed to recognize a the pointer's locator. The pointer indicates to the system the position of an item that you wish to work with. Through the mouse, you communicate the action that the system should take on this item. You can change the shape and color of the mouse pointer using the Pointer Preferences editor, described in Chapter 5.

== Busy Pointer ==

The busy pointer, also referred to as the wait pointer, is displayed in place of the mouse pointer to indicate that the system is attempting to execute an instruction. By default the busy pointer is an image of a stopwatch. Most Workbench operations are unavailable while the busy pointer is displayed. However, you can still move, size, and depth-arrange windows with the busy pointer. The appearance of this pointer can also be changed using the Pointer Preferences editor described in Chapter 5.

= Using the Mouse =

The Amiga comes equipped with a mouse, illustrated in Figure 2-2, used to communicate with the system through the pointer. The mouse pointer is positioned by moving the mouse. Manipulating the mouse so that the pointer is located over various objects and pictures on the screen and pressing the mouse buttons tells the Amiga what to do.

[[File:WorkbenchFig2-2.png|center|frame|Amiga Mouse]]

== Holding the Mouse ==

Hold the mouse on a flat surface with the cable extending away from you so that the mouse box rests under the palm of your hand with the buttons under your fingertips. In this position, the left mouse button is the selection button and the right mouse button is the menu button.

== Mouse Operations ==

When using the mouse,

{| class="wikitable"
| Pointing || means moving the mouse so that the tip of the pointer is positioned over an object on the screen. The pointer moves in the same direction you move the mouse. The mouse can be lifted and repositioned at any time. Lifting the mouse does not move the pointer.
|-
| Clicking || means pressing and releasing the selection button.
|-
| Double-Clicking || means clicking the selection button twice in rapid succession. Double-clicking on an icon causes a window to appear or a program to start.
|-
| Holding Down || means pressing the mouse button until your action is completed.
|-
| Dragging || means moving screens, windows, and icons by holding down the selection button and moving the mouse.
|}

== Using the Selection Button ==

The left mouse button is the selection button, used for selecting items on the monitor display for processing. This button is also used to move, or drag, items on the screen. For information about these operations, see Chapter 3.

== Using the Menu Button ==

The right mouse button is the menu button, which is used to display the menu bar and menus and to choose items from them. Menu bars contain the headings of each menu available for a selected window, program, or icon. Menus contain lists of options for the operations that you can do with the selected item.

=== Using Menus ===

Menu bars appear across the top of the screen, containing any menu headings available.

Hold down the menu button to display the menu bar as illustrated in Figure 2-3. Hol down the menu button while pointing to the different menu headings to show the available items listed beneath each. To choose a particular item, move the pointer down and release the menu button when the pointer touches it.

[[File:WorkbenchFig2-3.png|center|frame|Sample Menu Bar and Menu]]

Some menu items have submenus, which are additional related options that appear to the right of the menu item when it is selected. The symbol » after the item name indicates a submenu. If a menu has submenus, select one of the submenu options. Choosing a main menu item without choosing one of its submenus has no effect. In addition to the » symbol, other symbols may appear on the menu:

* An ellipsis (...) follows the name of menu items that open a requester.
* A checkmark in the area to the left of a menu item indicates that the items is an option that is currently selected. When this area is empty, the option is deselected.

To execute several menu options at once, hold down the menu button and, using the selection button, click on the menu options of your choice.

The menu button can also be used to cancel operations being performed by the selection button, such as drag selection.

=== Ghosted Menu Items ===

If a menu item is not available for a particular operation, it is ghosted or displayed less distinctly than the others, as illustrated in Figure 2-4.

[[File:WorkbenchFig2-4.png|center|frame|Ghosted versus Available Menu Items]]

== Canceling an Operation ==

Cancel the operation being performed with the selection button by clicking the menu button while still holding down the selection button. The following operations can be cancelled:

* Selecting
* Dragging
* Drag selection
* Changing the size of a window

== Using the Amiga Without a Mouse ==

All mouse actions can also be done using the keyboard. Certain key combinations allow use of the keyboard to move the pointer, select icons, and choose menu items. Keyboard shortcuts appear in the menu boxes to the right of some options. Holding down the right Amiga key and simultaneously pressing the letter displayed attains the same results as activating that menu option. Using the keyboard shortcuts instead of the menus speeds your work. For a full description of key functions, see the hardware manual for your Amiga model.

= Using Disk Drives =

Disk drives are devices from which information is retrieved or to which information is written or stored. An Amiga can have one or more hard disk drives, as well as floppy disk drives, depending on the model. All Amiga floppy disk drives can use low density floppy disks. However, if you have a high density floppy disk drive on your Amiga, you can also use high density floppy disks. Refer to the hardware manual that came with your system if you are not sure about the type of floppy disk drive you have.

Each disk drive has a device name, such as DF0: for the internal floppy drive. (Additional floppy drives are designated DF1:, DF2:, and DF3:). A disk icon is displayed on the Workbench screen for each disk inserted in a drive and for each hard disk partition.

The device name and the volume name are two ways of identifying a given disk. For most purposes use either name to refer to the disk when entering a path or within a file requester. The device name refers to the disk that is in the specified disk drive. The volume name refers specifically to a particular disk. For example, if you have a floppy disk in device DF0: with a volume name of Mydisk, you can reference it as either DF0: or Mydisk:. Referencing the disk as Mydisk: lets you insert Mydisk into any drive, not only DF0:.

Each drive has an activity light that is lit when the device is in use, either reading or writing data.

{{Note|title=Caution|text=Never reboot or turn off you Amiga and never remove a floppy disk from a floppy disk drive when any of the drive activity lights are lit or you risk damaging the drive and/or the files on the disk.}}

== Inserting Floppy Disks ==

The standard 3.5-inch floppy disk can be inserted only one way. Insert the disk into the disk drive with the label side facing up and the metal end with the indicator arrow entering first.

== Using Floppy Disks ==

Floppy disks must be write-enabled and formatted before information can be written on them. To write-enable a floppy disk, turn the disk to its back side and push the plastic tab in the upper left corner down to cover the hole. Conversely, to write-protect a floppy disk, push the plastic tab up, uncovering the hole Figure 2-5 illustrates the write-enable/protect tab on a floppy disk. Formatting floppy disks is described in Chapter 3.

[[File:WorkbenchFig2-5.png|center|frame|Write Protecting/Enabling Floppy Disks]]

The disk from which information is copied is referred to as the source disk (FROM disk). The disk to which the information is copied is referred to as the destination disk (TO disk). The source disk should always be write-protected to avoid accidental erasure. The destination disk can be a blank disk or a previously used disk whose contents are no longer needed. This disk must be write-enabled to accept the information from the source disk.

== Using the Ram Disk ==

The Ram Disk icon represents RAM:, an area of the Amiga's internal memory that is set up as a file storage device like a disk. Files, directories, and entire floppy disk (available memory permitting) can be copied to RAM: for temporary storage. The Ram Disk serves as a work area that the system can quickly access.

The size of RAM: is dynamic. It is never any larger than necessary to hold its contents. Therefore, it is always 100% full. Its maximum size is limited by the amount of free memory.

The primary advantage of RAM: is speed. Since it is electronic rather than mechanical, storage and retrieval are almost instantaneous. The disadvantage of RAM: is that data stored in RAM: does not survive when the computer is powered down or rebooted. You must save to floppy disk or to hard disk anything in the Ram Disk that you want to use again.

Applications commonly use RAM: to store temporary files created when the program runs or for backup files created when the program is exited. RAM: can also be used as storage for experimental script files, as a destination for testing command output, and when the creation of a file on an actual disk is too slow, risky, or inconvenient.

Be careful when using RAM: for storing important files. If the Amiga loses power, has a software failure, or you reboot, everything stored in RAM: is lost. Be sure when working with RAM: to regularly back up any important files onto disk.

{{Note|You cannot copy a disk to RAM: by dragging the source disk icon over the Ram Disk icon. To copy a disk to RAM:, open the Ram Disk icon and drag the floppy disk icon into the Ram Disk window. This creates a drawer with the name and contents of the floppy disk.}}

== Backup Disks ==

Backup disks ensure against a loss of data in the event of damage, corruption, or accidental erasure of the original disk. We recommend that you make backup copies of important disks and files, following the licensing agreements provided with your applications software. Making and distributing unlicensed copies of disks is a copyright violation known as software piracy. Store your original disks in a safe place and use your backup disks for everyday purposes. For information on making backup copies of your system disks on floppy-only systems, see Appendix B.

= Managing Your Files =

The basic units of data management on your Amiga are files, directories, and drawers. Files are organized collections of data that are given a name and are stored on the system or on removable media. Files are contained in directories or drawers. Directories and drawers are the same thing - a subdivision in your Amiga's filing system that is used to organize files and other directories/drawers (subdirectories).

== Organizing Information on Disks ==

Information should be stored on disk in a logical manner to allow easy access to your files. The Amiga Workbench organizes information into a hierarchical system of drawers.

A drawer - a directory in AmigaDOS - is a container for items that are related. These items can be files and even other drawers.

On any disk you can create multiple drawers containing multiple files, as available disk space allows. Workbench also allows the creation of drawers within drawers, subdrawers or subdirectories, for further file management. Create as many drawers and subdrawers on your disk as needed.

A drawer icon is displayed in the disk window for each drawer created on a particular disk. Each drawer window contains the icons of the files and subdrawers that exist in it.

== Paths ==

A path is a complete description of the location of a particular file on a disk. When a program requests the name of a file for retrieval, specify the file's path, including the volume or device name and all the drawers that lead to that file.

The method for specifying paths varies from program to program. Most programs use a file requester with a scrolling list, in which the disk name, any drawer names, and the file name are displayed. Click on the appropriate names to specify the path. However, for some programs you may have to type in the complete path name.

To enter a complete path:

* Type the name of the disk followed by a colon. This name is the volume name of the disk, such as Mydisk:. You can substitute the disk's device name, such as DF0:, in place of the disk name. However, if you enter the device name rather than the volume name, be sure the correct disk is in that device. Diskname:

* For a file that is not in a drawer, specify the file name after the colon following the disk name to complete the path. Diskname:filename

* For a file in a drawer, after the colon following the disk name specify the drawer name followed by a slash (/) followed by the file name. Diskname:drawername/filename

* If there are more drawers in the path, each drawer must be specified followed by a slash. Diskname:drawername/subdrawername/filename

{{Note|File and drawer names containing spaces can cause recognition problems. We recommend that you avoid using spaces in file or drawer names. If you have trouble referencing a name that contains a space, enclose the entire path in double quotation marks.}}

== File and Drawer Names ==

The following rules apply for naming files and drawers:

* Names can be up to 30 characters long. Names can contain upper case letters and any punctuation marks that are not reserved.
* Colons (:) and slashes (/) are not allowed within a name. These characters are reserved for path statements. However, other non-alphabetic characters can be used.
* The use of spaces before or after names should be avoided due to the possibility of omission.
* Upper and lower case differences (capitalization) are preserved and displayed by the Amiga. However, the system is not case-sensitive: upper and lower case are considered the same.
* Duplicate file names are not allowed within the same drawer. If you save a file with the same name as an existing file in a drawer, it overwrites the original file in that drawer.
* Two files with the same name can exist in separate drawers or within different paths.

== Trashcan ==

The Trashcan is a special drawer that can be placed on a disk for storing files that you no longer needed and may wish to delete. Discard icons or pseudo-icons for the files to be deleted by dragging them into the Trashcan. If the icon to be discarded is a drawer, is associated files are also moved to the Trashcan.

Choosing Empty Trash from the Icons menu deletes the icons and all of their associated files from the Trashcan. Before choosing Empty Trash, you can still recover any of the Trashcan's contents by opening its window and dragging the icons back out.

For more information about putting a Trashcan on a disk, see the Format Disk description in Chapter 3.

= Using Application Software =

Applications are software programs, such as databases, video and sound programs, word processing programs, recreational programs, and educational programs that are available for use on your Amiga. Most Amiga programs use windows, menus, and gadgets in ways very similar to the Workbench programs on your system disks. However, you should always read the documentation that comes with your applications for directions on using unfamiliar menu items and gadgets.

BOOPSI Popup Menus - Part 3

2013-10-13T14:29:41Z

Simon Archer:

= Author =

Simon Archer 
Copyright (c) 2011 Simon Archer 
Used by Permission

= Introduction =

In parts one and two, we took a look at the new "popup" menu feature of window.class and what extra items could be added and how to deal with them. Since then, some extra features have been added which allows Snapshotting and Unsnapshotting of window.class objects. This will require at least version 53.54, and will be subject to a future update. For now, we shall discover how this feature is used in readiness for that update.

= Overview =
As we saw in part one, there are a number of "default" items we can show in the menu, and we can add items for our own use. We can also enable an automatic way to save window size and position. In order to do this, we need to specify the WINDOW_UniqueID tag when the window object is created (OM_NEW).
While this tag is not directly connected with the windows popup menu, it does affect the menu and the amount of default items.
WINDOW_UniqueID tells window.class that this object has a name, specified by the tag data. This should be a unique name within your application. It is highly possible that your application may open more than one window, and each may have their size and position saved separately by ensuring the string you supply is unique. For example, specifying "MAIN_Window" as the UniqueID for the main window, and "LIST_Window" for another will allow your users to specify different positions and sizes for each window object.

= A Closer Look =
[[File:calculator_menus.png|left]]
As an example of this, we shall use the Calculator utility. Calculator has two modes, and each of these has a separate UniqueID, this means that we can actually save the position and size for each mode.
Here you can see we have some extra menu items, namely: 
'''Snapshot''' 
This will save the window objects size and position to a file stored in ENV(ARC):sys/WindowData. A drawer will be created there with the same name as your application, and the data for this object will be saved inside it with the UniqueID you gave the window object. 
'''Unsnapshot''' 
Just as the data was saved above, this option will remove the size and position data, effectively making the window object use the defaults again. 
'''Restore''' 
This option reloads the saved snapshot data and places the window back to that position. This is useful if you have moved or resized the window, and want to put it back to the last saved position/size.
 
That concludes our look into the window.class popup menu, we hope you found it useful.

BOOPSI Popup Menus - Part 3

2013-10-13T14:27:13Z

Simon Archer:

= Author =

Simon Archer 
Copyright (c) 2011 Simon Archer 
Used by Permission

= Introduction =

In parts one and two, we took a look at the new "popup" menu feature of window.class and what extra items could be added and how to deal with them. Since then, some extra features have been added which allows Snapshotting and Unsnapshotting of window.class objects. This will require at least version 53.54, and will be subject to a future update. For now, we shall discover how this feature is used in readiness for that update.

= Overview =
As we saw in part one, there are a number of "default" items we can show in the menu, and we can add items for our own use. We can also enable an automatic way to save window size and position. In order to do this, we need to specify the WINDOW_UniqueID tag.
While this tag is not directly connected with the windows popup menu, it does affect the menu and the amount of default items.
WINDOW_UniqueID tells window.class that this object has a name, specified by the tag data. This should be a unique name within your application. It is highly possible that your application may open more than one window, and each may have their size and position saved separately by ensuring the string you supply is unique. For example, specifying "MAIN_Window" as the UniqueID for the main window, and "LIST_Window" for another will allow your users to specify different positions and sizes for each window object.

= A Closer Look =
[[File:calculator_menus.png|left]]
As an example of this, we shall use the Calculator utility. Calculator has two modes, and each of these has a separate UniqueID, this means that we can actually save the position and size for each mode.
Here you can see we have some extra menu items, namely: 
'''Snapshot''' 
This will save the window objects size and position to a file stored in ENV(ARC):sys/WindowData. A drawer will be created there with the same name as your application, and the data for this object will be saved inside it with the UniqueID you gave the window object. 
'''Unsnapshot''' 
Just as the data was saved above, this option will remove the size and position data, effectively making the window object use the defaults again. 
'''Restore''' 
This option reloads the saved snapshot data and places the window back to that position. This is useful if you have moved or resized the window, and want to put it back to the last saved position/size.

BOOPSI Popup Menus - Part 3

2013-10-13T14:25:44Z

Simon Archer:

= Author =

Simon Archer 
Copyright (c) 2011 Simon Archer 
Used by Permission

= Introduction =

In parts one and two, we took a look at the new "popup" menu feature of window.class and what extra items could be added and how to deal with them. Since then, some extra features have been added which allows Snapshotting and Unsnapshotting of window.class objects. This will require at least version 53.54, and will be subject to a future update. For now, we shall discover how this feature is used in readiness for that update.

= Overview =
As we saw in part one, there are a number of "default" items we can show in the menu, and we can add items for our own use. We can also enable an automatic way to save window size and position. In order to do this, we need to specify the WINDOW_UniqueID tag.
While this tag is not directly connected with the windows popup menu, it does affect the menu and the amount of default items.
WINDOW_UniqueID tells window.class that this object has a name, specified by the tag data. This should be a unique name within your application. It is highly possible that your application may open more than one window, and each may have their size and position saved separately by ensuring the string you supply is unique. For example, specifying "MAIN_Window" as the UniqueID for the main window, and "LIST_Window" for another will allow your users to specify different positions and sizes for each window object.

= A Closer Look =
[[File:calculator_menus.png|left]]
As an example of this, we shall use the Calculator utility. Calculator has two modes, and each of these has a separate UniqueID, this means that we can actually save the position and size for each mode.
Here you can see we have some extra menu items, namely:
'''Snapshot'''
This will save the window objects size and position to a file stored in ENV(ARC):sys/WindowData. A drawer will be created there with the same name as your application, and the data for this object will be saved inside it with the UniqueID you gave the window object.
'''Unsnapshot'''
Just as the data was saved above, this option will remove the size and position data, effectively making the window object use the defaults again.
'''Restore'''
This option reloads the saved snapshot data and places the window back to that position. This is useful if you have moved or resized the window, and want to put it back to the last saved position/size.

BOOPSI Popup Menus - Part 3

2013-10-13T14:18:49Z

Simon Archer:

BOOPSI Popup Menus - Part 3

2013-10-13T14:18:28Z

Simon Archer:

BOOPSI Popup Menus - Part 3

2013-10-13T14:15:25Z

Simon Archer:

File:Calculator menus.png

2013-10-13T14:14:38Z

Simon Archer: Showing snapshot feature for Calculator

Showing snapshot feature for Calculator

BOOPSI Popup Menus - Part 3

2013-10-13T14:11:36Z

Simon Archer:

BOOPSI Popup Menus - Part 3

2013-10-13T14:08:18Z

Simon Archer:

BOOPSI Popup Menus - Part 2

2013-10-13T13:41:23Z

Simon Archer:

= Author =

Simon Archer 
Copyright (c) 2011 Simon Archer 
Used by Permission

= Introduction =

In part one we took a look at the new "popup" menu feature of window.class and what the default options are and how to use them. In part two, we shall discuss how the application programmer can add items to the popup menu, and be notified when the user has selected one of these custom options.

= Overview =

The popup menu available from the window objects title bar is not designed to be a replacement for the applications menus, it is purely to offer the user some options which are applicable to the window object the menu is attached to. Such options could be offering a "Snapshot" facility where the application could save the current window size and position so that it will always open in the same place and be the same size (''more on that in part 3''). Whatever the options, they should be relevant to the window and its operation. Remember, users are easily confused, so make your custom options simple and plainly obvious!

= Adding items =

The adding of custom options is done via the "Hook" method, and the hook function should use the standard popupmenu.class way of adding items. The hook function is called like so:

<syntaxhighlight>
LONG PopupHook( struct Hook *hook, APTR o, UNUSED APTR reserved )
</syntaxhighlight>

The "hook" parameter is a pointer to the Hook structure used to declare this function, and the "o" parameter is the popupmenu object which you can add items to with PMA_AddItem. You may also use the standard h_Data pointer of the "hook" structure for your own use, such as passing a data pointer so that the hook function may better determine what options to offer.

As with all hook functions, the pointers supplied are guaranteed to be valid when the function is called, but not afterwards. Do NOT cache any of these pointers, as they WILL change with each invocation of the popup menu.

When adding custom items to the popup menu, it is advisable to supply a separator as the first item. This gives the user a visual distinction between the standard items, and the custom ones. For each item you add, you should supply a meaningful PMIA_ID value, as this is returned to you in the window event loop, and it is how your application determines which custom item has been selected by the user. There are no real restrictions on what IDs you can use here, but it is recommended to start the IDs at 1 rather than ZERO.
Also, always add your custom items to the bottom of the item list. The name of the game here is "Consistency", and keeping an overall unform nature to these menus will help the users become accustomed to this new functionality.

The hook function should return the amount of items successfully added to the menu. This is used to verify that an empty menu will not be shown.

So, let's have a look at an example hook function that will add a separator and one custom item to the popup menu:

<syntaxhighlight>
LONG PopupHook( struct Hook *hook, APTR o, UNUSED APTR reserved )
{
LONG added = 0;
Object *item;

/* add a separator to separate custom items from default ones */
if(( item = IIntuition->NewObject( IPopupMenu->POPUPMENU_GetItemClass(), NULL,
PMIA_WideTitleBar, TRUE,
TAG_END )))
{
if(!( IIntuition->IDoMethod( o, PM_INSERT, item, ~0 )))
{
/* we failed to add the item, dispose of it */
IIntuition->DisposeObject( item );
}
else
added++;
}

if(( item = IIntuition->NewObject( IPopupMenu->POPUPMENU_GetItemClass(), NULL,
PMIA_Title, (ULONG) "Snapshot",
PMIA_ID, (ULONG)ID_SNAPSHOT,
TAG_END )))
{
if(!( IIntuition->IDoMethod( o, PM_INSERT, item, ~0 )))
{
/* again, adding the item to the menu failed, so dispose of it here */
IIntuition->DisposeObject( item );
}
else
added++;
}
return added;
}
</syntaxhighlight>

If the items were added successfully, the popup menu will now contain a separator after the last default option, and a new custom "Snapshot" item which the user can select. All the rules of popupmenu.class apply here, which means we can add as many items as are required. This also includes adding sub-items etc. Please refer to the autodoc for popupmenu.class for further information on what can be done.

Now let's look at how we get the notification of this event, and how to deal with it.

= Specifying your hook =

Once you have your hook function created and adding the items that you require, window.class needs to know about it. We do this by initialising a struct Hook, and adding our hook function to it. The code for that can be like so:

<syntaxhighlight>
struct Hook *popuphook;
popuphook = IExec->AllocSysObjectTags( ASOT_HOOK,
ASOHOOK_Entry, mypopupfunction,
ASOHOOK_Subentry, NULL,
ASOHOOK_Data, mydatapointer,
TAG_END );
</syntaxhighlight>

This hook now gets passed to the window.class by passing WINDOW_PopupHook, mypopuphook in the tags when the window object is created.

Obviously, do not forget to

<syntaxhighlight>
IExec->FreeSysObject( ASOT_HOOK, mypopuphook );
</syntaxhighlight>

= Getting custom menu item events =

In part one, we showed how to expand the window event loop to receive the new screen jumping event. In a similar vein, we also need to add a new event type so that we may be notified that the user selected one of our custom menu items. We do this by testing for the WMHI_POPUPMENU event. The enhanced event loop will now look like so:

<syntaxhighlight>
while( !done )
{
IExec->Wait( winsig );

while(( result = IIntuition->IDoMethod( winobj, WM_HANDLEINPUT, code )) != WMHI_LASTMSG )
{
switch( result & WMHI_CLASSMASK )
{
case WMHI_CLOSEWINDOW:
done = TRUE;
break;

case WMHI_ICONIFY:
break;

case WMHI_GADGETUP:
break;

case WMHI_JUMPSCREEN:
break;

case WMHI_POPUPMENU:
break;
}
}
}
</syntaxhighlight>

Earlier we mentioned about supplying meaningful menu item IDs, and this is where they play their part. Once your event loop detects the WMHI_POPUPMENU event, we can get the ID of the menu item selected by using the WMHI_GADGETMASK just like we would for gadgets. Taking our example hook function above into account, the event loop code would be something like this to detect the menu item selected:

<syntaxhighlight>
case WMHI_POPUPMENU:
{
switch( result & WMHI_GADGETMASK )
{
case ID_SNAPSHOT:
/* the code to snapshot the window goes here */
break;

/* we can add the IDs of extra menu items here */
}
break;
}
</syntaxhighlight>

= Summary =

We hope you have found this look at the popupmenu feature of window.class useful. Obviously the example code above is not complete, it is merely to show how the application programmer can go about using this new feature, and the steps required.
A fully working example with source code can be downloaded from [http://codebench.co.uk/os4coding/WindowPopup.lha here], which should give you a good indication of how to adapt your code. You will not be able to compile this code just yet, as a newer SDK will be required than that which is available at the time of writing.

In part 3, we will take a look at some extra functionality that has been added to window.class, and allows saving of window positions. For now, this is purely for reference only, as it will require a newer version of window.class than is currently publicly available.

BOOPSI Popup Menus - Part 2

2013-10-13T13:38:21Z

Simon Archer:

BOOPSI Popup Menus - Part 2

2013-10-13T13:33:49Z

Simon Archer:

= Author =

Simon Archer 
Copyright (c) 2011 Simon Archer 
Used by Permission

= Introduction =

In part one we took a look at the new "popup" menu feature of window.class and what the default options are and how to use them. In part two, we shall discuss how the application programmer can add items to the popup menu, and be notified when the user has selected one of these custom options.

= Overview =

The popup menu available from the window objects title bar is not designed to be a replacement for the applications menus, it is purely to offer the user some options which are applicable to the window object the menu is attached to. Such options could be offering a "Snapshot" facility where the application could save the current window size and position so that it will always open in the same place and be the same size (''more on that in part 3''). Whatever the options, they should be relevant to the window and its operation. Remember, users are easily confused, so make your custom options simple and plainly obvious!

= Adding items =

The adding of custom options is done via the "Hook" method, and the hook function should use the standard popupmenu.class way of adding items. The hook function is called like so:

<syntaxhighlight>
LONG PopupHook( struct Hook *hook, APTR o, UNUSED APTR reserved )
</syntaxhighlight>

The "hook" parameter is a pointer to the Hook structure used to declare this function, and the "o" parameter is the popupmenu object which you can add items to with PMA_AddItem. You may also use the standard h_Data pointer of the "hook" structure for your own use, such as passing a data pointer so that the hook function may better determine what options to offer.

As with all hook functions, the pointers supplied are guaranteed to be valid when the function is called, but not afterwards. Do NOT cache any of these pointers, as they WILL change with each invocation of the popup menu.

When adding custom items to the popup menu, it is advisable to supply a separator as the first item. This gives the user a visual distinction between the standard items, and the custom ones. For each item you add, you should supply a meaningful PMIA_ID value, as this is returned to you in the window event loop, and it is how your application determines which custom item has been selected by the user. There are no real restrictions on what IDs you can use here, but it is recommended to start the IDs at 1 rather than ZERO.
Also, always add your custom items to the bottom of the item list. The name of the game here is "Consistency", and keeping an overall unform nature to these menus will help the users become accustomed to this new functionality.

The hook function should return the amount of items successfully added to the menu. This is used to verify that an empty menu will not be shown.

So, let's have a look at an example hook function that will add a separator and one custom item to the popup menu:

<syntaxhighlight>
LONG PopupHook( struct Hook *hook, APTR o, UNUSED APTR reserved )
{
LONG added = 0;
Object *item;

/* add a separator to separate custom items from default ones */
if(( item = IIntuition->NewObject( IPopupMenu->POPUPMENU_GetItemClass(), NULL,
PMIA_WideTitleBar, TRUE,
TAG_END )))
{
if(!( IIntuition->IDoMethod( o, PM_INSERT, item, ~0 )))
{
/* we failed to add the item, dispose of it */
IIntuition->DisposeObject( item );
}
else
added++;
}

if(( item = IIntuition->NewObject( IPopupMenu->POPUPMENU_GetItemClass(), NULL,
PMIA_Title, (ULONG) "Snapshot",
PMIA_ID, (ULONG)ID_SNAPSHOT,
TAG_END )))
{
if(!( IIntuition->IDoMethod( o, PM_INSERT, item, ~0 )))
{
/* again, adding the item to the menu failed, so dispose of it here */
IIntuition->DisposeObject( item );
}
else
added++;
}
return added;
}
</syntaxhighlight>

If the items were added successfully, the popup menu will now contain a separator after the last default option, and a new custom "Snapshot" item which the user can select. All the rules of popupmenu.class apply here, which means we can add as many items as are required. This also includes adding sub-items etc. Please refer to the autodoc for popupmenu.class for further information on what can be done.

Now let's look at how we get the notification of this event, and how to deal with it.

= Specifying your hook =

Once you have your hook function created and adding the items that you require, window.class needs to know about it. We do this by initialising a struct Hook, and adding our hook function to it. The code for that can be like so:

<syntaxhighlight>
struct Hook *popuphook;
popuphook = IExec->AllocSysObjectTags( ASOT_HOOK,
ASOHOOK_Entry, mypopupfunction,
ASOHOOK_Subentry, NULL,
ASOHOOK_Data, mydatapointer,
TAG_END );
</syntaxhighlight>

This hook now gets passed to the window.class by passing WINDOW_PopupHook, mypopuphook in the tags when the window object is created.

Obviously, do not forget to

<syntaxhighlight>
IExec->FreeSysObject( ASOT_HOOK, mypopuphook );
</syntaxhighlight>

= Getting custom menu item events =

In part one, we showed how to expand the window event loop to receive the new screen jumping event. In a similar vein, we also need to add a new event type so that we may be notified that the user selected one of our custom menu items. We do this by testing for the WMHI_POPUPMENU event. The enhanced event loop will now look like so:

<syntaxhighlight>
while( !done )
{
IExec->Wait( winsig );

while(( result = IIntuition->IDoMethod( winobj, WM_HANDLEINPUT, code )) != WMHI_LASTMSG )
{
switch( result & WMHI_CLASSMASK )
{
case WMHI_CLOSEWINDOW:
done = TRUE;
break;

case WMHI_ICONIFY:
break;

case WMHI_GADGETUP:
break;

case WMHI_JUMPSCREEN:
break;

case WMHI_POPUPMENU:
break;
}
}
}
</syntaxhighlight>

Earlier we mentioned about supplying meaningful menu item IDs, and this is where they play their part. Once your event loop detects the WMHI_POPUPMENU event, we can get the ID of the menu item selected by using the WMHI_GADGETMASK just like we would for gadgets. Taking our example hook function above into account, the event loop code would be something like this to detect the menu item selected:

<syntaxhighlight>
case WMHI_POPUPMENU:
{
switch( result & WMHI_GADGETMASK )
{
case ID_SNAPSHOT:
/* the code to snapshot the window goes here */
break;

/* we can add the IDs of extra menu items here */
}
break;
}
</syntaxhighlight>

= Summary =

We hope you have found this look at the popupmenu feature of window.class useful. Obviously the example code above is not complete, it is merely to show how the application programmer can go about using this new feature, and the steps required.
A fully working example with source code can be downloaded from here, which should give you a good indication of how to adapt your code. You will not be able to compile this code just yet, as a newer SDK will be required than that which is available at the time of writing.

Thanks for looking.

BOOPSI Popup Menus - Part 2

2013-10-13T13:26:00Z

Simon Archer:

= Author =

Simon Archer 
Copyright (c) 2011 Simon Archer 
Used by Permission

= Introduction =

In part one we took a look at the new "popup" menu feature of window.class and what the default options are and how to use them. In part two, we shall discuss how the application programmer can add items to the popup menu, and be notified when the user has selected one of these custom options.

= Overview =

The popup menu available from the window objects title bar is not designed to be a replacement for the applications menus, it is purely to offer the user some options which are applicable to the window object the menu is attached to. Such options could be offering a "Snapshot" facility where the application could save the current window size and position so that it will always open in the same place and be the same size (''more on that in part 3''). Whatever the options, they should be relevant to the window and its operation. Remember, users are easily confused, so make your custom options simple and plainly obvious!

= Adding items =

The adding of custom options is done via the "Hook" method, and the hook function should use the standard popupmenu.class way of adding items. The hook function is called like so:

<syntaxhighlight>
LONG PopupHook( struct Hook *hook, APTR o, UNUSED APTR reserved )
</syntaxhighlight>

The "hook" parameter is a pointer to the Hook structure used to declare this function, and the "o" parameter is the popupmenu object which you can add items to with PMA_AddItem. You may also use the standard h_Data pointer of the "hook" structure for your own use, such as passing a data pointer so that the hook function may better determine what options to offer.

As with all hook functions, the pointers supplied are guaranteed to be valid when the function is called, but not afterwards. Do NOT cache any of these pointers, as they WILL change with each invocation of the popup menu.

When adding custom items to the popup menu, it is advisable to supply a separator as the first item. This gives the user a visual distinction between the standard items, and the custom ones. For each item you add, you should supply a meaningful PMIA_ID value, as this is returned to you in the window event loop, and it is how your application determines which custom item has been selected by the user. There are no real restrictions on what IDs you can use here, but it is recommended to start the IDs at 1 rather than ZERO.
Also, always add your custom items to the bottom of the item list. The name of the game here is "Consistency", and keeping an overall unform nature to these menus will help the users become accustomed to this new functionality.

The hook function should return the amount of items successfully added to the menu. This is used to verify that an empty menu will not be shown.

So, let's have a look at an example hook function that will add a separator and one custom item to the popup menu:

<syntaxhighlight>
LONG PopupHook( struct Hook *hook, APTR o, UNUSED APTR reserved )
{
LONG added = 0;
Object *item;

/* add a separator to separate custom items from default ones */
if(( item = IIntuition->NewObject( IPopupMenu->POPUPMENU_GetItemClass(), NULL,
PMIA_WideTitleBar, TRUE,
TAG_END )))
{
if(!( IIntuition->IDoMethod( o, PM_INSERT, item, ~0 )))
{
/* we failed to add the item, dispose of it */
IIntuition->DisposeObject( item );
}
else
added++;
}

if(( item = IIntuition->NewObject( IPopupMenu->POPUPMENU_GetItemClass(), NULL,
PMIA_Title, (ULONG) "Snapshot",
PMIA_ID, (ULONG)ID_SNAPSHOT,
TAG_END )))
{
if(!( IIntuition->IDoMethod( o, PM_INSERT, item, ~0 )))
{
/* again, adding the item to the menu failed, so dispose of it here */
IIntuition->DisposeObject( item );
}
else
added++;
}
return added;
}
</syntaxhighlight>

If the items were added successfully, the popup menu will now contain a separator after the last default option, and a new custom "Snapshot" item which the user can select. All the rules of popupmenu.class apply here, which means we can add as many items as are required. This also includes adding sub-items etc. Please refer to the autodoc for popupmenu.class for further information on what can be done.

Now let's look at how we get the notification of this event, and how to deal with it.

= Specifying your hook =

Once you have your hook function created and adding the items that you require, window.class needs to know about it. We do this by initialising a struct Hook, and adding our hook function to it. The code for that can be like so:

<syntaxhighlight>
struct Hook *popuphook;
popuphook = IExec->AllocSysObjectTags( ASOT_HOOK,
ASOHOOK_Entry, mypopupfunction,
ASOHOOK_Subentry, NULL,
ASOHOOK_Data, mydatapointer,
TAG_END );
</syntaxhighlight>

This hook now gets passed to the window.class a by passing WINDOW_PopupHook, mypopuphook in the tags when the window object is created.

Obviously, do not forget to

<syntaxhighlight>
IExec->FreeSysObject( ASOT_HOOK, mypopuphook );
</syntaxhighlight>

= Getting custom menu item events =

In part one, we showed how to expand the window event loop to receive the new screen jumping event. In a similar vein, we also need to add a new event type so that we may be notified that the user selected one of our custom menu items. We do this by testing for the WMHI_POPUPMENU event. The enhanced event loop will now look like so:

<syntaxhighlight>
while( !done )
{
IExec->Wait( winsig );

while(( result = IIntuition->IDoMethod( winobj, WM_HANDLEINPUT, code )) != WMHI_LASTMSG )
{
switch( result & WMHI_CLASSMASK )
{
case WMHI_CLOSEWINDOW:
done = TRUE;
break;

case WMHI_ICONIFY:
break;

case WMHI_GADGETUP:
break;

case WMHI_JUMPSCREEN:
break;

case WMHI_POPUPMENU:
break;
}
}
}
</syntaxhighlight>

Earlier we mentioned about supplying meaningful menu item IDs, and this is where they play their part. Once your event loop detects the WMHI_POPUPMENU event, we can get the ID of the menu item selected by using the WMHI_GADGETMASK just like we would for gadgets. Taking our example hook function above into account, the event loop code would something like this to detect the menu item selected:

<syntaxhighlight>
case WMHI_POPUPMENU:
{
switch( result & WMHI_GADGETMASK )
{
case ID_SNAPSHOT:
/* the code to snapshot the window goes here */
break;

/* we can add the IDs of extra menu items here */
}
break;
}
</syntaxhighlight>

= Summary =

We hope you have found this look at the popupmenu feature of window.class useful. Obviously the example code above is not complete, it is merely to show how the application programmer can go about using this new feature, and the steps required.
A fully working example with source code can be downloaded from here, which should give you a good indication of how to adapt your code. You will not be able to compile this code just yet, as a newer SDK will be required than that which is available at the time of writing.

Thanks for looking.

BOOPSI Popup Menus - Part 2

2013-10-13T13:25:34Z

Simon Archer:

= Author =

Simon Archer 
Copyright (c) 2011 Simon Archer 
Used by Permission

= Introduction =

In part one we took a look at the new "popup" menu feature of window.class and what the default options are and how to use them. In part two, we shall discuss how the application programmer can add items to the popup menu, and be notified when the user has selected one of these custom options.

= Overview =

The popup menu available from the window objects title bar is not designed to be a replacement for the applications menus, it is purely to offer the user some options which are applicable to the window object the menu is attached to. Such options could be offering a "Snapshot" facility where the application could save the current window size and position so that it will always open in the same place and be the same size more on that in part 3). Whatever the options, they should be relevant to the window and its operation. Remember, users are easily confused, so make your custom options simple and plainly obvious!

= Adding items =

The adding of custom options is done via the "Hook" method, and the hook function should use the standard popupmenu.class way of adding items. The hook function is called like so:

<syntaxhighlight>
LONG PopupHook( struct Hook *hook, APTR o, UNUSED APTR reserved )
</syntaxhighlight>

The "hook" parameter is a pointer to the Hook structure used to declare this function, and the "o" parameter is the popupmenu object which you can add items to with PMA_AddItem. You may also use the standard h_Data pointer of the "hook" structure for your own use, such as passing a data pointer so that the hook function may better determine what options to offer.

As with all hook functions, the pointers supplied are guaranteed to be valid when the function is called, but not afterwards. Do NOT cache any of these pointers, as they WILL change with each invocation of the popup menu.

When adding custom items to the popup menu, it is advisable to supply a separator as the first item. This gives the user a visual distinction between the standard items, and the custom ones. For each item you add, you should supply a meaningful PMIA_ID value, as this is returned to you in the window event loop, and it is how your application determines which custom item has been selected by the user. There are no real restrictions on what IDs you can use here, but it is recommended to start the IDs at 1 rather than ZERO.
Also, always add your custom items to the bottom of the item list. The name of the game here is "Consistency", and keeping an overall unform nature to these menus will help the users become accustomed to this new functionality.

The hook function should return the amount of items successfully added to the menu. This is used to verify that an empty menu will not be shown.

So, let's have a look at an example hook function that will add a separator and one custom item to the popup menu:

<syntaxhighlight>
LONG PopupHook( struct Hook *hook, APTR o, UNUSED APTR reserved )
{
LONG added = 0;
Object *item;

/* add a separator to separate custom items from default ones */
if(( item = IIntuition->NewObject( IPopupMenu->POPUPMENU_GetItemClass(), NULL,
PMIA_WideTitleBar, TRUE,
TAG_END )))
{
if(!( IIntuition->IDoMethod( o, PM_INSERT, item, ~0 )))
{
/* we failed to add the item, dispose of it */
IIntuition->DisposeObject( item );
}
else
added++;
}

if(( item = IIntuition->NewObject( IPopupMenu->POPUPMENU_GetItemClass(), NULL,
PMIA_Title, (ULONG) "Snapshot",
PMIA_ID, (ULONG)ID_SNAPSHOT,
TAG_END )))
{
if(!( IIntuition->IDoMethod( o, PM_INSERT, item, ~0 )))
{
/* again, adding the item to the menu failed, so dispose of it here */
IIntuition->DisposeObject( item );
}
else
added++;
}
return added;
}
</syntaxhighlight>

If the items were added successfully, the popup menu will now contain a separator after the last default option, and a new custom "Snapshot" item which the user can select. All the rules of popupmenu.class apply here, which means we can add as many items as are required. This also includes adding sub-items etc. Please refer to the autodoc for popupmenu.class for further information on what can be done.

Now let's look at how we get the notification of this event, and how to deal with it.

= Specifying your hook =

Once you have your hook function created and adding the items that you require, window.class needs to know about it. We do this by initialising a struct Hook, and adding our hook function to it. The code for that can be like so:

<syntaxhighlight>
struct Hook *popuphook;
popuphook = IExec->AllocSysObjectTags( ASOT_HOOK,
ASOHOOK_Entry, mypopupfunction,
ASOHOOK_Subentry, NULL,
ASOHOOK_Data, mydatapointer,
TAG_END );
</syntaxhighlight>

This hook now gets passed to the window.class a by passing WINDOW_PopupHook, mypopuphook in the tags when the window object is created.

Obviously, do not forget to

<syntaxhighlight>
IExec->FreeSysObject( ASOT_HOOK, mypopuphook );
</syntaxhighlight>

= Getting custom menu item events =

In part one, we showed how to expand the window event loop to receive the new screen jumping event. In a similar vein, we also need to add a new event type so that we may be notified that the user selected one of our custom menu items. We do this by testing for the WMHI_POPUPMENU event. The enhanced event loop will now look like so:

<syntaxhighlight>
while( !done )
{
IExec->Wait( winsig );

while(( result = IIntuition->IDoMethod( winobj, WM_HANDLEINPUT, code )) != WMHI_LASTMSG )
{
switch( result & WMHI_CLASSMASK )
{
case WMHI_CLOSEWINDOW:
done = TRUE;
break;

case WMHI_ICONIFY:
break;

case WMHI_GADGETUP:
break;

case WMHI_JUMPSCREEN:
break;

case WMHI_POPUPMENU:
break;
}
}
}
</syntaxhighlight>

Earlier we mentioned about supplying meaningful menu item IDs, and this is where they play their part. Once your event loop detects the WMHI_POPUPMENU event, we can get the ID of the menu item selected by using the WMHI_GADGETMASK just like we would for gadgets. Taking our example hook function above into account, the event loop code would something like this to detect the menu item selected:

<syntaxhighlight>
case WMHI_POPUPMENU:
{
switch( result & WMHI_GADGETMASK )
{
case ID_SNAPSHOT:
/* the code to snapshot the window goes here */
break;

/* we can add the IDs of extra menu items here */
}
break;
}
</syntaxhighlight>

= Summary =

We hope you have found this look at the popupmenu feature of window.class useful. Obviously the example code above is not complete, it is merely to show how the application programmer can go about using this new feature, and the steps required.
A fully working example with source code can be downloaded from here, which should give you a good indication of how to adapt your code. You will not be able to compile this code just yet, as a newer SDK will be required than that which is available at the time of writing.

Thanks for looking.

BOOPSI Popup Menus - Part 3

2013-09-26T20:58:07Z

Simon Archer: Created page with " == Currently under construction... =="

== Currently under construction... ==