The example application we look at will be a simple program with a dialog that allows you to perform domain name lookups on IP addresses and hostnames. The source code and resource file for this application are available in the example1 folder (which you will have to download if you are reading this document over the net and if you want to look at the resources).
We will use the builtin module "socket" that allows a Python program to perform all sorts of networking functions, and we will create the user interface around that. You should be able to run the sample code with the standard Python distribution.
If you are interested in building your own extensions to python you
should check out the companion document Creating Macintosh Python C extensions,
which tells you how to build your own C extension.
There is one fine point that deserves to be mentioned here: resource numbering. Because often your resources will be combined with those that the Python interpreter and various standard modules need you should give your DLOG and DITL resources numbers above 512. 128 and below are reserved for Apple, 128-228 are for extensions like Tk, 228-255 for the Python interpreter and 256-511 for standard modules. If you are writing a module that you will be distributing for inclusion in other people's programs you may want to register a number in the 256-511 range, contact Guido or myself or whoever you think is "in charge" of Python for the Macintosh at the moment. Even though the application we are writing at the moment will keep its resources in a separate resource file it is still a good idea to make sure that no conflicts arise: once you have opened your resource file any attempt by the interpreter to open a dialog will also search your resource file.
Okay, let's have a look at dnslookup-1.rsrc, our resource file. The DLOG and accompanying DITL resource both have number 512. Since ResEdit creates both with default ID=128 you should take care to change the number on both. The dialog itself is pretty basic: two buttons (Lookup and Quit), two labels and two text entry areas, one of which is used for output only. Here's what the dialog will look like at run time
The code itself is contained in the file dnslookup-1.py. Have a copy handy before you read on. The file starts off with a textstring giving a short description. Not many tools do anything with this as yet, but at some point in the future we will have all sorts of nifty class browser that will display this string, so just include it. Just put a short description at the start of each module, class, method and function. After the initial description and some comments, we import the modules we need.
EasyDialogs is a handy standard
module that provides you with routines that put up common text-only
Message(str)displays the message "str" and an OK button,
AskString(prompt, default)asks for a string, displays OK and Cancel buttons,
AskYesNoCancel(question, default)displays a question and Yes, No and Cancel buttons.
Resis a pretty complete interface to the MacOS Resource Manager, described fully in Inside Mac. There is currently no documentation of it, but the Apple documentation (or Think Ref) will help you on your way if you remember two points:
Dlgis an interface to the Dialog manager (with Dialogs being implemented as python objects and routines with Dialog arguments being methods). The sys module you know, I hope. The string module is an often used module that enables you to perform many string related operations. In this case however, we are only using the "digits" constant from the string module. We could have simply defined "digits" as "0123456789". The socket module enables us to perform the domain name lookups. We use two calls from it:
gethostbyaddr()returns the hostname associated with an IP address
gethostbyname()returns the IP address associated with a hostname
On to the main program. We start off with opening our resource file,
which should live in the same folder as the python source. If we
cannot open it we use
EasyDialogs to print a message and
exit. You can try it: just move the resource file somewhere else for a
moment. Then we call do_dialog() to do the real work.
Dlg.GetNewDialog() to open
a dialog window initialized from 'DLOG' resource ID_MAIN and putting
it on screen in the frontmost position. Next, we go into a loop,
Dlg.ModalDialog() to wait for the next user
ModalDialog() will return us the item number that
the user has clicked on (or otherwise activated). It will handle a few
slightly more complicated things also, like the user typing into
simple textfields, but it will not do things like updating
the physical appearance of radio buttons, etc. See Inside Mac or
another programming guide for how to handle this
yourself. Fortunately, our simple application doesn't have to bother with this,
since buttons and textfields are the only active elements we have. So, we do a
simple switch on item number and call the appropriate routine to implement the
action requested. Upon the user pressing "Quit" we simply leave the loop and,
do_dialog(). This will cause the python dialog object
my_dlg to be deleted and the on-screen dialog to disappear.
Time for a warning: be very careful what you do as long as a dialog is on-screen. Printing something, for instance, may suddenly cause the standard output window to appear over the dialog, and since we took no measures to redraw the dialog it will become very difficult to get out of the dialog. Also, command-period may or may not work in this situation. I have also seen crashes in such a situation, probably due to the multiple event loops involved or some oversight in the interpreter. You have been warned.
The implementation of the "Lookup" command can use a bit more
explaining: we get the necessary information with
but now we have to update the on-screen dialog to present this
information to the user. The
GetDialogItem() method of
the dialog returns three bits of information about the given item: its
type, its data handle and its rect (the on-screen
coordinates). We are only interested in the data handle here, on which
SetDialogItemText() to set our new text. Note
here that python programmers need not bother with the C-string versus
pascal-string controversy: the python glue module knows what is needed
and converts the python string to the correct type.
And that concludes our first example of the use of resources and dialogs. Next, you could have a look at the source of EasyDialogs for some examples of using input fields and filterprocs. Or, go on with reading the second part of this document to see how to implement a better version of this application.