| 1 | <HTML><HEAD><TITLE>Using python to create Macintosh applications, part one</TITLE></HEAD>
|
|---|
| 2 | <BODY>
|
|---|
| 3 |
|
|---|
| 4 | <H1>Using python to create Macintosh applications, part one</H1>
|
|---|
| 5 | <HR>
|
|---|
| 6 |
|
|---|
| 7 | This document will show you how to create a simple mac-style
|
|---|
| 8 | application using Python. We will glance at how to use dialogs and
|
|---|
| 9 | resources. <p>
|
|---|
| 10 |
|
|---|
| 11 | The example application we look at will be a simple program with a
|
|---|
| 12 | dialog that allows you to perform domain name lookups on IP addresses
|
|---|
| 13 | and hostnames.
|
|---|
| 14 | The <A HREF="example1/dnslookup-1.py">source code</A> and
|
|---|
| 15 | <A HREF="example1/dnslookup-1.rsrc">resource file</A>
|
|---|
| 16 | for this application are available in the <A
|
|---|
| 17 | HREF="example1">example1</A> folder (which you will have to download
|
|---|
| 18 | if you are reading this document over the net and if you want to look
|
|---|
| 19 | at the resources). <p>
|
|---|
| 20 |
|
|---|
| 21 | We will use the builtin module "socket" that allows a
|
|---|
| 22 | Python program to perform all sorts of networking functions, and we
|
|---|
| 23 | will create the user interface around that. You should be able to run
|
|---|
| 24 | the sample code with the standard Python distribution.<p>
|
|---|
| 25 |
|
|---|
| 26 | <CITE>
|
|---|
| 27 | If you are interested in building your own extensions to python you
|
|---|
| 28 | should check out the companion document <A
|
|---|
| 29 | HREF="plugins.html">Creating Macintosh Python C extensions</A>,
|
|---|
| 30 | which tells you how to build your own C extension.
|
|---|
| 31 | <p>
|
|---|
| 32 | </CITE>
|
|---|
| 33 |
|
|---|
| 34 | <H2><A NAME="dialog-resources">Creating dialog resources</A></H2>
|
|---|
| 35 |
|
|---|
| 36 | Let us start with the creative bit: building the dialogs and creating
|
|---|
| 37 | an icon for our program. For this you need ResEdit, and a reasonable
|
|---|
| 38 | working knowledge of how to use it. "Inside Mac" or various books on
|
|---|
| 39 | macintosh programming will help here. <p>
|
|---|
| 40 |
|
|---|
| 41 | There is one fine point that deserves to be mentioned here: <A
|
|---|
| 42 | NAME="resource-numbering">resource numbering</A>. Because often your
|
|---|
| 43 | resources will be combined with those that the Python interpreter and
|
|---|
| 44 | various standard modules need you should give your DLOG and DITL
|
|---|
| 45 | resources numbers above 512. 128 and below are reserved for Apple,
|
|---|
| 46 | 128-228 are for extensions like Tk,
|
|---|
| 47 | 228-255 for the Python interpreter and 256-511 for standard
|
|---|
| 48 | modules. If you are writing a module that you will be distributing for
|
|---|
| 49 | inclusion in other people's programs you may want to register a number
|
|---|
| 50 | in the 256-511 range, contact Guido or myself or whoever you think is
|
|---|
| 51 | "in charge" of Python for the Macintosh at the moment. Even though the
|
|---|
| 52 | application we are writing at the moment will keep its resources in a
|
|---|
| 53 | separate resource file it is still a good idea to make sure that no
|
|---|
| 54 | conflicts arise: once you have opened your resource file any attempt
|
|---|
| 55 | by the interpreter to open a dialog will also search your resource
|
|---|
| 56 | file. <p>
|
|---|
| 57 |
|
|---|
| 58 | Okay, let's have a look at dnslookup-1.rsrc, our resource file.
|
|---|
| 59 | The DLOG and accompanying DITL resource both have number 512. Since
|
|---|
| 60 | ResEdit creates both with default ID=128 you should take care to
|
|---|
| 61 | change the number on both. The dialog itself is pretty basic: two
|
|---|
| 62 | buttons (Lookup and Quit), two labels and
|
|---|
| 63 | two text entry areas, one of which is used for output only. Here's what
|
|---|
| 64 | the dialog will look like at run time<p>
|
|---|
| 65 | <div align=center>
|
|---|
| 66 | <img width=324 height=189 src="example1/dnslookup-1.gif" alt="dialog image">
|
|---|
| 67 | </div>
|
|---|
| 68 | <p>
|
|---|
| 69 |
|
|---|
| 70 | <H2><A NAME="modal-dialog">An application with a modal dialog</A></H2>
|
|---|
| 71 |
|
|---|
| 72 | Next, we will have to write the actual application. For this example,
|
|---|
| 73 | we will use a modal dialog. This means that we will put up the dialog
|
|---|
| 74 | and go into a loop asking the dialog manager for events (buttons
|
|---|
| 75 | pushed). We handle the actions requested by the user until the Quit
|
|---|
| 76 | button is pressed, upon which we exit our loop (and the program). This
|
|---|
| 77 | way of structuring your program is actually rather antisocial, since
|
|---|
| 78 | you force the user to do whatever you, the application writer, happen
|
|---|
| 79 | to want. A modal dialog leaves no way of escape whatsoever (except
|
|---|
| 80 | command-option-escape), and is usually not a good way to structure
|
|---|
| 81 | anything but the most simple questions. Even then: how often have you
|
|---|
| 82 | been confronted with a dialog asking a question that you could not
|
|---|
| 83 | answer because the data you needed was obscured by the dialog itself?
|
|---|
| 84 | In the next example we will look at an application that does pretty
|
|---|
| 85 | much the same as this one but in a more user-friendly way. <p>
|
|---|
| 86 |
|
|---|
| 87 | The code itself is contained in the file <A
|
|---|
| 88 | HREF="example1/dnslookup-1.py"> dnslookup-1.py</A>. Have
|
|---|
| 89 | a copy handy before you read on. The file starts off with a
|
|---|
| 90 | textstring giving a short description. Not many tools do anything with
|
|---|
| 91 | this as yet, but at some point in the future we <EM>will</EM> have all
|
|---|
| 92 | sorts of nifty class browser that will display this string, so just
|
|---|
| 93 | include it. Just put a short description at the start of each module,
|
|---|
| 94 | class, method and function. After the initial description and some
|
|---|
| 95 | comments, we import the modules we need. <p>
|
|---|
| 96 |
|
|---|
| 97 | <A NAME="easydialogs"><CODE>EasyDialogs</CODE></A> is a handy standard
|
|---|
| 98 | module that provides you with routines that put up common text-only
|
|---|
| 99 | modal dialogs:
|
|---|
| 100 | <UL>
|
|---|
| 101 | <LI> <CODE>Message(str)</CODE>
|
|---|
| 102 | displays the message "str" and an OK button,
|
|---|
| 103 | <LI> <CODE>AskString(prompt, default)</CODE>
|
|---|
| 104 | asks for a string, displays OK and Cancel buttons,
|
|---|
| 105 | <LI> <CODE>AskYesNoCancel(question, default)</CODE>
|
|---|
| 106 | displays a question and Yes, No and Cancel buttons.
|
|---|
| 107 | </UL>
|
|---|
| 108 |
|
|---|
| 109 | <A NAME="res"><CODE>Res</CODE></A> is a pretty complete interface to
|
|---|
| 110 | the MacOS Resource Manager, described fully in Inside Mac. There is
|
|---|
| 111 | currently no documentation of it, but the Apple documentation (or
|
|---|
| 112 | Think Ref) will help you on your way if you remember two points:
|
|---|
| 113 | <UL>
|
|---|
| 114 | <LI> Resources are implemented as Python objects, and each routine
|
|---|
| 115 | with a resource first argument is implemented as a python method.
|
|---|
| 116 | <LI> When in doubt about the arguments examine the routines docstring,
|
|---|
| 117 | as in <CODE>print Res.OpenResFile.__doc__</CODE>
|
|---|
| 118 | </UL>
|
|---|
| 119 |
|
|---|
| 120 | Similarly, <A NAME="dlg"><CODE>Dlg</CODE></A> is an interface to the
|
|---|
| 121 | Dialog manager (with Dialogs being implemented as python objects and
|
|---|
| 122 | routines with Dialog arguments being methods). The sys module you
|
|---|
| 123 | know, I hope. The string module is an often used module that enables
|
|---|
| 124 | you to perform many string related operations. In this case however, we
|
|---|
| 125 | are only using the "digits" constant from the string module. We could
|
|---|
| 126 | have simply defined "digits" as "0123456789". The socket module enables
|
|---|
| 127 | us to perform the domain name lookups. We
|
|---|
| 128 | use two calls from it:
|
|---|
| 129 | <UL>
|
|---|
| 130 | <LI> <CODE>gethostbyaddr()</CODE>
|
|---|
| 131 | returns the hostname associated with an IP address
|
|---|
| 132 | <LI> <CODE>gethostbyname()</CODE>
|
|---|
| 133 | returns the IP address associated with a hostname
|
|---|
| 134 | </UL>
|
|---|
| 135 |
|
|---|
| 136 | Next in the source file we get definitions for our dialog resource
|
|---|
| 137 | number and for the item numbers in our dialog. These should match the
|
|---|
| 138 | situation in our resource file dnslookup-1.rsrc,
|
|---|
| 139 | obviously.<p>
|
|---|
| 140 |
|
|---|
| 141 | On to the main program. We start off with opening our resource file,
|
|---|
| 142 | which should live in the same folder as the python source. If we
|
|---|
| 143 | cannot open it we use <CODE>EasyDialogs</CODE> to print a message and
|
|---|
| 144 | exit. You can try it: just move the resource file somewhere else for a
|
|---|
| 145 | moment. Then we call do_dialog() to do the real work. <p>
|
|---|
| 146 |
|
|---|
| 147 | <CODE>Do_dialog()</CODE> uses <CODE>Dlg.GetNewDialog()</CODE> to open
|
|---|
| 148 | a dialog window initialized from 'DLOG' resource ID_MAIN and putting
|
|---|
| 149 | it on screen in the frontmost position. Next, we go into a loop,
|
|---|
| 150 | calling <CODE>Dlg.ModalDialog()</CODE> to wait for the next user
|
|---|
| 151 | action. <CODE>ModalDialog()</CODE> will return us the item number that
|
|---|
| 152 | the user has clicked on (or otherwise activated). It will handle a few
|
|---|
| 153 | slightly more complicated things also, like the user typing into
|
|---|
| 154 | simple textfields, but it will <EM>not</EM> do things like updating
|
|---|
| 155 | the physical appearance of radio buttons, etc. See Inside Mac or
|
|---|
| 156 | another programming guide for how to handle this
|
|---|
| 157 | yourself. Fortunately, our simple application doesn't have to bother with this,
|
|---|
| 158 | since buttons and textfields are the only active elements we have. So, we do a
|
|---|
| 159 | simple switch on item number and call the appropriate routine to implement the
|
|---|
| 160 | action requested. Upon the user pressing "Quit" we simply leave the loop and,
|
|---|
| 161 | hence, <CODE>do_dialog()</CODE>. This will cause the python dialog object
|
|---|
| 162 | <CODE>my_dlg</CODE> to be deleted and the on-screen dialog to disappear. <p>
|
|---|
| 163 |
|
|---|
| 164 | <A NAME="dialog-warning">Time for a warning</A>: be very careful what
|
|---|
| 165 | you do as long as a dialog is on-screen. Printing something, for
|
|---|
| 166 | instance, may suddenly cause the standard output window to appear over
|
|---|
| 167 | the dialog, and since we took no measures to redraw the dialog it will
|
|---|
| 168 | become very difficult to get out of the dialog. Also, command-period
|
|---|
| 169 | may or may not work in this situation. I have also seen crashes in
|
|---|
| 170 | such a situation, probably due to the multiple event loops involved or
|
|---|
| 171 | some oversight in the interpreter. You have been warned. <p>
|
|---|
| 172 |
|
|---|
| 173 | The implementation of the "Lookup" command can use a bit more
|
|---|
| 174 | explaining: we get the necessary information with <CODE>dnslookup()</CODE>
|
|---|
| 175 | but now we have to update the on-screen dialog to present this
|
|---|
| 176 | information to the user. The <CODE>GetDialogItem()</CODE> method of
|
|---|
| 177 | the dialog returns three bits of information about the given item: its
|
|---|
| 178 | type, its data handle and its rect (the on-screen <CODE>x,y,w,h</CODE>
|
|---|
| 179 | coordinates). We are only interested in the data handle here, on which
|
|---|
| 180 | we call <CODE>SetDialogItemText()</CODE> to set our new text. Note
|
|---|
| 181 | here that python programmers need not bother with the C-string versus
|
|---|
| 182 | pascal-string controversy: the python glue module knows what is needed
|
|---|
| 183 | and converts the python string to the correct type. <p>
|
|---|
| 184 |
|
|---|
| 185 | And that concludes our first example of the use of resources and
|
|---|
| 186 | dialogs. Next, you could have a look at the source of EasyDialogs for
|
|---|
| 187 | some examples of using input fields and filterprocs. Or, go on with
|
|---|
| 188 | reading the <A HREF="example2.html">second part</A> of this document
|
|---|
| 189 | to see how to implement a better version of this application.<p>
|
|---|
| 190 |
|
|---|
| 191 | </BODY>
|
|---|
| 192 | </HTML>
|
|---|
| 193 |
|
|---|
