 |
 |
|
|
|
|
|
 |
Contents
1. IntroductionThis document describes the PopChar Pro Programming Interface. You will need this information only if you are an application developer and can't get PopChar Pro to work with your application using standard techniques. Before you take advantage of the Programming Interface, you should first try to solve the problem by following the General Guidelines. If that doesn't work, consult the next sections about How PopChar Pro Works and on the PopChar Pro Gestalt Record. If you need further help, please contact:
2. General GuidelinesIf you are an application developer, you can make your application work well with PopChar Pro by following a few simple rules (see also the Black List):
If you cannot follow these rules for some reason, read the next sections about how to control PopChar Pro from within your application. 3. How PopChar Pro WorksPopChar Pro patches a couple of traps to perform additional operations when the user selects a menu item from the menu bar. Some of these patches deal with special cases only (for example, to "read" the font name in the toolbar of Microsoft applications). There are only two patches that are important for you: 3.1. The MenuSelect PatchWhen your application detects a click in the menu bar, it should first update its menus and then call MenuSelect. PopChar Pro uses a head patch to find the current font before the PopChar Pro menu is pulled down. Note that this must be done in every case (even when the user clicks the File or Edit menu) because the user might change his/her mind and move the pointer to the PopChar Pro menu. The MenuSelect patch performs the following task:
Please note that a specific font requested by an application (step 2) currently overrides manual font selection. This may change in future releases. 3.2. The GetNextEvent PatchWhen the user selects a character from the PopChar Pro menu, that character is placed in an internal data structure. When GetNextEvent (or WaitNextEvent, which calls GetNextEvent) is called the next time, PopChar Pro's GetNextEvent patch returns a keyDown event for that character. In this event record, the character code, when and where fields are correctly filled in. The modifiers field is set to 0, and the key code is set to 0. If your application relies on key codes instead of character codes, it will not be able to process keyDown events generated by PopChar Pro. If necessary, your application can check the key code to determine if a keyDown event was generated by keyboard input or by PopChar Pro. There is only one case in which this distinction will not work: When the user hits the "A" key on the keyboard without holding any modifier keys, an event with the character code "a" and the key code 0 will be generated. Please note that the key code 0 does not necessarily mean that PopChar Pro generated the keyDown event; other system extensions may use the same techniques, so the key code 0 just means "not a real keyboard event". 4. The PopChar Pro Gestalt RecordWhen PopChar Pro loads, it installs a gestalt selector "PopÇ" ($506F7082). The value returned by the Gestalt function is a locked handle (of type PopGestaltHnd) to a record with the following structure:
TYPE
PopGestaltRecord = RECORD
popGestaltVersion: Integer;
popPublicVersion: Integer;
popCharVersion: Integer;
popCharVersionStr: Str15;
popCharFileSpec: FSSpec;
fontToUse:Integer;
moreData: ARRAY [1..1] OF Integer;
END;
PopGestaltPtr = ^ PopGestaltRecord;
PopGestaltHnd = ^ PopGestaltP
Note that the actual record contains more undocumented fields for internal use (as indicated by the moreData field). popGestaltVersion contains a version number of the entire gestalt record (including the undocumented fields). This field is used internally to verify compatibility of the individual parts of the PopChar Pro package. Your application should not depend on a specific value stored in popGestaltVersion. popPublicVersion contains a version number of the public fields (i.e., those listed in the above record declaration). In PopChar Pro 1.0.x, 1.1, and 1.1.1, popPublicVersion has the value 0. In future versions, this number will increase when additional fields are made available for public access. Such fields will be inserted after fontToUse (to preserve the order of fields published in previous versions). You can then check the value of popPublicVersion to test the availability of additional fields. For now, you can assume that the fields popGestaltVersion thru fontToUse are always available. popCharVersion contains the PopChar Pro version number in hexadecimal format. Version 1.0 is identified by the value $0100, version 1.0.1 is denoted by $0101, and so forth. popCharVersionStr contains the PopChar Pro version number in string format. Version 1.1.1 is identified by the value "1.1.1". popCharFileSpec contains the file specification record of the PopChar Pro control panel. fontToUse contains the font ID of the font to be used by PopChar Pro. This field normally has the value –1, indicating that the font determination algorithm outlined in section 3.1) is to be used. If PopChar Pro finds any other value in this field during a call of MenuSelect, it interprets that value as a font ID and displays the corresponding font. IMPORTANT: Do not modify any fields except fontToUse. 5. Accessing the PopChar Pro Gestalt RecordTo access the PopChar Pro gestalt record and to test whether PopChar Pro is installed, use the following procedure: CONST popGestaltSelector = 'PopÇ'; VAR popPtr: PopGestaltPtr; {global variable} FUNCTION PopGestaltPointer: PopGestaltPtr; VAR pgh: PopGestaltHnd; BEGIN IF Gestalt(popGestaltSelector, LongInt(pgh))=noErr THEN PopGestaltPointer := pgh^ ELSE PopGestaltPointer := NIL {PopChar Pro not installed} END; BEGIN {startup code of your application} InitializeToolbox; popPtr := PopGestaltPointer; ... PopGestaltPointer returns the address of the gestalt record if PopChar Pro is installed. If PopChar Pro is not installed, NIL is returned. You can safely call PopGestaltPointer in the startup code of your application and store the returned value in a global variable for future use. The gestalt handle (pgh) is locked; the gestalt record will thus not move in memory. 6. Specifying the Current FontWhen the General Guidelines and the hints in the Black List don't work for you, your application can explicitly tell PopChar Pro which font to use. Here is how you can achieve that. When your application detects a click in the menu bar, it should first update its menus, then determine in which font the character generated by the next keystroke will appear, and finally tell PopChar Pro to use that font before calling MenuSelect. The following program fragment shows a typical sequence for specifying the font to be used by PopChar Pro:
PROCEDURE DoMouseDown (theEvent: EventRecord);
VAR
theWindow: WindowPtr;
global: Point;
wLoc: Integer;
menuResult: LongInt;
BEGIN
global := theEvent.where;
wLoc := FindWindow(global, theWindow);
CASE wLoc OF
inMenuBar: BEGIN
UpdateMenuItems;
SetPopCharFont;
menuResult := MenuSelect(global);
IF HiWord(menuResult)<>0 THEN
HandleMenu(menuResult);
END;
...
..
The procedure SetPopCharFont can be implemented in the following way: PROCEDURE SetPopCharFont; VAR currentFont: Integer; BEGIN IF popPtr<>NIL THEN BEGIN {only if PopChar Pro is installed} currentFont := FontUsedForNextKeyStroke; popPtr^.fontToUse := currentFont END END; Important:
7. The PopChar Pro FloaterWhen PopChar Pro's floating window is open, the window should also update to font changes even when the user does not pull down a menu from the menu bar. To achieve that, the PopChar Pro Floater application generates fake clicks in the menu bar twice a second as long as the floating window is open and no other user events occured during the past 0.5 sec. Your application will receive these clicks automatically when it calls GetNextEvent or WaitNextEvent. These fake clicks cannot be distinguished from real clicks. Your application will process them as usual and update the check marks in its menus (or call SetPopCharFont) before calling MenuSelect. The call to MenuSelect will have no visual effect; it lets PopChar Pro recognize the current font and immediately returns with the function result 0 as if the user had released the mouse button outside the menu. If PopChar Pro's floating window is open, update events can occur when the floating window is moved, collapsed, closed, or when the window's size changes as the result of a font change. Your application should therefore process update events whenever possible. Your application will handle such update events anyway when it goes through its main event loop. However, when a modal dialog is open, other windows may appear partially blank when the floating window goes away. You can avoid such "white spaces" by writing a filter procedure for all modal dialogs. If the filter procedure detects an update event that belongs to an open window of your application, it should call an update procedure that redraws the window's content between calls of BeginUpdate and EndUpdate. 8. The Black ListThis section lists a couple of absolutely forbidden things that should not happen in a "PopChar-Pro-aware" application.
|
| site map |
