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 194
