++ +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
+modal dialogs:
+
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.
+Res is 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:
+print Res.OpenResFile.__doc__
+Dlg is 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.
+
+Do_dialog() uses 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,
+calling Dlg.ModalDialog() to wait for the next user
+action. 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,
+hence, 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 dnslookup()
+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 x,y,w,h
+coordinates). We are only interested in the data handle here, on which
+we call 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.
+ + + +