|
1 <HTML><HEAD><TITLE>Using FrameWork and TextEdit</TITLE></HEAD> |
|
2 <BODY> |
|
3 <H1>Using FrameWork and TextEdit</H1> |
|
4 <HR> |
|
5 |
|
6 In this document we use the <CODE>FrameWork</CODE> and <CODE>TextEdit</CODE> |
|
7 modules to create a simple text editor. The functionality |
|
8 of the editor is very basic: you can open multiple files, type text and use |
|
9 cut/copy/paste. The main intention is to explain the use of FrameWork, really. <p> |
|
10 |
|
11 <H2>FrameWork</H2> |
|
12 |
|
13 The FrameWork module provides you with a skeleton application. It declares a |
|
14 number of classes suitable for subclassing in your application, thereby |
|
15 releaving you of the burden of doing all event handling, etc. yourself. For a |
|
16 real understanding you will have to browse the source. Here is a short overview |
|
17 of the classes and what functionality they provide. |
|
18 |
|
19 <dl> |
|
20 <dt> <CODE>Application</CODE> |
|
21 <dd> |
|
22 This is the toplevel class you will override. It maintains the menu bar and contains |
|
23 the main event handling code. Normal use is to override the <code>__init__</code> routine |
|
24 to do your own initializations and override <code>makeusermenus</code> to create your menus |
|
25 (your menu callback routines may be here too, but this is by no means necessary). |
|
26 The event handling code can be overridden at various levels, from very low-level (the |
|
27 <code>dispatch</code> method) to intermedeate level (<code>do_keyDown</code>, for instance) |
|
28 to high-level (<code>do_key</code>). The application class knows about the <code>Window</code> |
|
29 objects you create, and will forward events to the appropriate window (So, normally you |
|
30 would have a <code>do_key</code> method in your window object, not your application object). |
|
31 |
|
32 <dt> <CODE>MenuBar</CODE>, <CODE>Menu</CODE> and <CODE>MenuItem</CODE> |
|
33 <dd> |
|
34 These classes (and a few friends like <CODE>SubMenu</CODE>) handle your menus. You would not |
|
35 normally override them but use them as-is. The idiom for creating menus is a bit strange, |
|
36 see the test code at the bottom of FrameWork for sample use. The apple menu is handled for you |
|
37 by <CODE>MenuBar</CODE> and <CODE>Application</CODE>. |
|
38 |
|
39 <dt> <CODE>Window</CODE> |
|
40 <dd> |
|
41 The basic window. Again, a class that you normally subclass in your application, possibly |
|
42 multiple times if you have different types of windows. The init call instantiates the data |
|
43 structure but actually opening the window is delayed until you call <code>open</code>. Your |
|
44 open method should call <code>do_postopen</code> to let the base class handle linking in to |
|
45 the application object. Similarly with <code>close</code> and <code>do_postclose</code>. The |
|
46 rest of the code is mainly event-oriented: you override <code>do_postresize</code>, |
|
47 <code>do_contentclick</code>, <code>do_update</code>, <code>do_activate</code> |
|
48 and <code>do_key</code> to "do your thing". When these methods are called the relevant environment |
|
49 has been setup (like <code>BeginDrawing</code> has been called for updates, etc). |
|
50 |
|
51 <dt> <CODE>windowbounds</CODE> |
|
52 <dd> |
|
53 Not a class but a function: you pass it a width and height and it will return you a rectangle |
|
54 you can use to create your window. It will take care of staggering windows and it will try |
|
55 to fit the window on the screen (but the resulting rect will <em>always</em> have the size you |
|
56 specify). |
|
57 |
|
58 <dt> <CODE>ControlsWindow</CODE> |
|
59 <dd> |
|
60 A subclass of Window which automatically handles drawing and clicking for controls. You override |
|
61 the same methods as for Window (if you need to: control-related things are done automatically) and |
|
62 <code>do_controlhit</code>. |
|
63 |
|
64 <dt> <CODE>ScrolledWindow</CODE> |
|
65 <dd> |
|
66 A subclass of ControlsWindow, a window with optional scrollbars. If you override <code>do_activate</code> |
|
67 or <code>do_postresize</code> you must call the ScrolledWindow methods at the end of your override. |
|
68 You call <code>scrollbars</code> to enable/disable scrollbars and <code>updatescrollbars</code> to |
|
69 update them. You provide <code>getscrollbarvalues</code> to return the current x/y values (a helper |
|
70 method <code>scalebarvalues</code> is available) and <code>scrollbarcallback</code> to update your |
|
71 display after the user has used the scrollbars. |
|
72 |
|
73 <dt> <CODE>DialogWindow</CODE> |
|
74 <dd> |
|
75 A modeless dialog window initialized from a DLOG resource. See the |
|
76 <A HREF="example2.html">second Interslip example</A> for its useage. |
|
77 </dl> |
|
78 |
|
79 <H2>A sample text editor</H2> |
|
80 |
|
81 Let us have a look at <A HREF="textedit/ped.py">ped.py</A> (in the Demo:textedit folder), the Pathetic |
|
82 EDitor. It has multiple windows, cut/copy/paste and keyboard input, but that is about all. It looks |
|
83 as if you can resize the window but it does not work. Still, it serves as an example. |
|
84 |
|
85 Ped creates two classes, <code>TEWindow</code> and <code>Ped</code>. Let us start with the latter one, |
|
86 which is a subclass of <code>FrameWork.Application</code> and our main application. The init function |
|
87 has little to do aside from the standard init: it remembers a window sequence number (for untitled windows), |
|
88 and sets things up for menu disable to work. Remember, the <code>makeusermenus</code> is called |
|
89 automatically. <p> |
|
90 |
|
91 <code>Makeusermenus</code> creates the <code>File</code> and <code>Edit</code> menus. It also initializes |
|
92 a couple of lists that are used later to correctly enable and disable menu items (and complete menus) depending |
|
93 on whether a window is open, text is selected, etc. The callback functions for the menu items are |
|
94 all methods of this class. <p> |
|
95 |
|
96 <code>Updatemenubar</code> handles greying out (and re-enabling) of menu items depending on whether there |
|
97 is a current window and its state. <p> |
|
98 |
|
99 The rest of the methods are all callbacks and simple to understand. They check whether there is an active |
|
100 window (and complain loudly if there is none: the corresponding menu entry should have been disabled |
|
101 in that case!) and call the appropriate window method. Only the <code>_open</code> method (the common code |
|
102 for <code>Open</code> and <code>New</code>) deserves some mention. It instantiates a <code>TEWindow</code> |
|
103 object and opens it with the title, filename and contents of the file to edit. Note that FrameWork takes |
|
104 care of remembering the window object. A minor note on opening the file in binary mode: this is because |
|
105 TextEdit expects MacOS style carriage-return terminated lines, not python/unix/C style newline-terminated |
|
106 lines. <p> |
|
107 |
|
108 Oh yes: the <code>quit</code> callback does a little magic too. It closes all windows, and only if this |
|
109 succeeds it actually quits. This gives the user a chance to cancel the operation if some files are unsaved. |
|
110 <p> |
|
111 |
|
112 Lastly, there is the <code>idle</code> method, called by the Application base class when no event |
|
113 is available. It is forwarded to the active window, so it can blink the text caret. <p> |
|
114 |
|
115 The <code>TEWindow</code> object handles a single window. Due to this structuring it is absolutely no |
|
116 problem to have multiple windows open at the same time (although a real application should exercise care when |
|
117 two windows refer to the same document). TEWindow uses the standard init code inherited from |
|
118 <code>ScrolledWindow</code>, and sets itself up at the time of the <code>open</code> call. It obtains screen |
|
119 coordinates, opens the window, creates rectangles for TextEdit to work in (the magical number <code>15</code> |
|
120 here is the size of a normal scroll bar: unfortunately there is no symbolic constant for it), |
|
121 creates the TextEdit object and initializes it with our data. Finally, the scroll bars are created (the |
|
122 initial values will be obtained automatically through <code>getscrollbarvalues</code>) and we activate |
|
123 ourselves (this is unfortunately not done automatically by the MacOS event handling code). <p> |
|
124 |
|
125 <code>Do_idle</code> simply calls the TextEdit routine that blinks the cursor. <code>Getscrollbarvalues</code> |
|
126 returns the current X and Y scrollbar values, scaled to <code>0..32767</code>. For X we return <code>None</code>, |
|
127 which means "no scrollbar, please", for Y we use the scaler provided by <code>ScrolledWindow</code>. <p> |
|
128 |
|
129 <code>Scrollbar_callback</code> is called when the user uses the scrollbar. It is passed a string <code>'x'</code> |
|
130 or <code>'y'</code>, one of <code>'set', '-', '--', '+', '++'</code> and (for <code>set</code>) an absolute |
|
131 value. Note that the sign of the value passed to <code>TEPinScroll</code> is counter-intuitive. <p> |
|
132 |
|
133 <code>do_activate</code> (de)activates the scrollbars and calls the relevant TextEdit routine. Moreover, it |
|
134 tells the application object if we are now the active window, and updates the menubar. The next few methods |
|
135 are update and menu callbacks, and pretty straightforward. Note that <code>do_close</code> can |
|
136 return without closing the window (if the document is changed and the users cancels out of the operation). |
|
137 Also note the "magic" in <code>menu_save_as</code> |
|
138 that set the correct window title. <p> |
|
139 |
|
140 Things get moderately interesting again at the cut/copy/paste handling, since the TextEdit scrap is |
|
141 separate from the desktop scrap. For that reason there are various calls to routines that move the scrap |
|
142 back and forth. <code>Have_selection</code> is called by the menubar update code to determine whether cut and |
|
143 copy should be enabled. <p> |
|
144 |
|
145 Understanding the main program is left as an exercise to the reader. <p> |
|
146 |
|
147 <hr> |
|
148 That's all for this example, you could now continue with the <A HREF="waste.html">next example</A>, where we use WASTE, a more-or-less |
|
149 TextEdit compatible library with more functionality, to rebuild our editor. Or you can |
|
150 return to the <A HREF="index.html">table of contents</A> to pick another topic. <p> |