Home

U - Atari Documentation Archive

1. L objc_offset Find Object s Screen Position objc_offsett Opcode 44 This function calculates the absolute screen position of an object This func tion is needed because each object s position is stored internally as an offset relative to that of its parent object C binding int status object x y struct object tree T status objc_offset tree object amp x amp y Inputs control 0 44 Opcode control 1 Number of 16 bit inputs in int in array control2 3 Number of 16 bit results in int out array control3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr out array object int in 0 The object whose screen location you wish to find tree addr_in 0 The address of the object tree array which contains the object Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution x int out 1 The horizontal screen position of the ob ject in pixels y int out 2 The vertical screen position of the object in pixels 253 objc order Reorder Child Objects objc order Opcode 45 Moves a child object to a new position relative to its siblings C binding int status object newpos struct object tree status objc_order tree object newpos Inputs control 0 45 Opcode control 1 2 Number of 16 bit inputs in int in array control 2 1 Num
2. Co CECE GEM Graphics Objects whether the mouse was over the button when the press oc curred If it was not it waits for another button press If the user clicks on the EXIT button the program ends Program 4 1 object c t13 199 5 2 4954595 19292959 94259 9 55 52922 99225525241 925 2 55255292 4295229295 1 OBJECT C Demonstrates the use of low level amp Object Library functions on a pre initialized object tree array amp t JETTATTALAKTATTSSAAKASAAAAAATASTLAAAAAKASTTAKSTAKAAATATAAATAATLS SEE Ti define APP INFO define APP NAME Object Example define WDW_CTRLS NAME define EXITBUTN 1 include aesshell c char stringsC EXIT Push Button to Exit OBJECT treet3 lt 1 1 2 G_BOX NONE OUTLINED 2x21199L 6 5 22 19 2 1 1 G BUTTON SELECTABLE DEFAULT EXIT NORMAL strings 9 12 6 8 1 8 1 1 G STRING LASTOB NORMAL strings 1J 1 2 21 12 23 demot m int msgbuf C8 int x y button keys object state evnt nesage amp msgbuf skip the window redraw message for xaBgx lt 3gxe fix object x y width and height treeL xJ ob x cellw tree xJ ob y 2 cellh treet x23J ob width 2 cellw tree xJ ob height cellhj gt draw the object tree objc draw tree 1 work g x work g_y work g w work g h j 4 check for mouse button press over EXIT button
3. Ox BWA Ox IBS x BIBS x C Ox BOSS x BBWS Ox SIGE Ix BIOS Dx BIBS Ox BSO7 Ox BBB x 0x00190 x Bx 2x9 14 Ox xB x 16 x 9x0020 Sx BIOS menu tree TITLE in tree MENUTREE x TITLE in tree MENUTREE t TITLE in tree MENUTREE MENUTREE MENUTREE MENUTREE tree MENUTREE tree MENUTREE STRING STRING STRING STRING STRING in in in in in tree tree tree 9x2C7C 9x616C Ox 2826 90x6974 x2D2D 9x2D2D 90x4927 9x6174 9x4974 9x914B Sx BVO Ox BWS2 Ix IW xDDD xFFFF Qx2000 Ox BIOS 9xFFFF x Ox BOOS x B 2x00 xDDD xFFFF x 1 x xFFFF x 3 x OxFFFF Ix BIOS Ox S932 SxFFFF Ox BIB7 Ox S208 OxFFFF Sy 89S Sx OOOO OxFFFF LDD x 2298 9 9xFFFF x 2 xB B x 2 Free string index Alert string index Free string index x x 2867 9x7465 0x20290 9x2220 x2D2D 9x 2D2D Qx6C6C Ox SD99 9x6565D x x 9x09 2 x S x 9xFFFF 9x BI Sx VOUS SxFFFF x A x x F x 16 xB xFFFF 0x0916 x xFFFF x 16 9x99002 QxFFFF 9x090106 Ix xFFFF 9x902916 2x992FF OxFFFF Ox BSoc Ox SGFF SxFFFF Ix BBid Ax AJAD 9xF
4. define MOUSE CFF graf ouse M OFF L define MOUSE ON graf mouset M ON L define FALSE 2 define TRUE 1 Sdefine MAXOX Y X gt Y 7 X s V definme MINOX Y X lt Y X s Y include aesshell c include dialogl h include file from RCS OBJECT gmenutree pointer to menu object tree OBJECT dialtree pointer to dialog object tree TEDINFO obspec amp pointer to TEDINFO for text object char strptr pointer to text string for text object int agest35J5 9 array for age tally int computerst435 t 3 3 5 array for computer tally char lastxtt1532 7 buffer for last other text int left top demo t int done 2 int msgf8J if rarc load DIALOG1 RSC Load resource file form alert S LOJLFatal ErroriCan t find DIALOGiI RSC file JLAbortJ return 9 Abort if it s not there amp 2 get address of menu tree and dialog tree amp rsrc gaddr R TREE MENUTREE amp menutree 3 rsrc gaddr R TREE DIALTREE amp dialtree 8 get pointer to text objects s text string obspec TEDINFO dialtreeLOTHERTXT23 ob spec strptr obspec 5te ptext pointer to text string amp setrptrt2J 2 clear out string MOUSE OFF Hide the mouse pointer menu bar menutree 1 Show the menu bar amp MOUSE ON 7 Show the mouse pointer Main Program Loop amp
5. Inputs control 0 114 Opcode control 1 1 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control3 1 Number of 32 bit inputs in addr in array controla 0 Number of 32 bit results in addr out array object int in 0 The number array index of the objects whose coordinates are to be converted tree addr in 0 The address of the object tree array which contains the object Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also rsrc_load 303 shel read Find Invoking Program shel_read Opcode 120 This function may be used by a GEM application to discover how it was in voked either from the GEM Desktop or from another application and to read the command tail used when invoking the program This allows the program to return control to the program which called it The shel read function should be called after appl_init but before rsrc_load C binding int status char command 128 tail 128 status shel read command tail Inputs control 0 120 Opcode control 1 0 Number of 16 bit inputs in int zin array control 2 1 Number of 16 bit results in int_out array control 3 2 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr out array command addr in 0 The address of the buffer that will hold the command text st
6. int pointsL43 int X y xr yr grect conv amp pb pb xc points vs cClip handle TRUE points vswr mode handle 1 vsf color handle 1 vsf interior handle 9 14 set fill to hollow t if SELECTED amp pb gt pb_currstate If selected vsf interior handle 1 use solid fill pattern amp vsf perimeter thandie 9 vsl width handie 3 xr2 pb pb w 2 r pb pb h 2 pb pb x xr pb pb y yr f pb pb currstate pb pb currstate v ellarc handle x y xr 2 yr 2 60 399 v ellipse handle x y xr 8 yr 5 uu Y x Y i return 90 gt FE RCAC ARATE End of Dialog2 c X X 5 3 X t 183 CHAPTER 7 In order to run this program you must first construct the resource file DIALOG2 RSC If you have a resource construc tion program you may do so by following the instructions be low If not you may use the RSCBUILD program in Appendix C to build the resource from data At the top right side is a STRING object whose text reads Slider Position Directly below that is a text object with the name NUMBER whose initial text reads 0 To the right of these objects is the slide bar It s composed of two box objects The first SLIDEBAR is a long tall G_BOX with an outside border with a thickness of 1 pixel and it is HOLLOW filled which means that it is transparent Inside this object is its child SLIDER a G_BOX with an inside border with a thick ness of 1 SLIDER
7. Full Box This is the information liae s Up Arron 6 Vertical Slider Down Arrow o6 Size Box Q Left Arron Horizontal Slider Right Arron 24 J3 c 1 x P G a Lo L Starting an Application Title bar The title bar stretches across the top of the win dow and is used to display the name of the window Move bar The move bar occupies the same area as the ti tle bar and has no visible characteristics to distinguish it from the title bar The move bar allows the user to move the win dow around on the screen Information line This line also stretches across the top of the window directly below the title bar It is used by the pro gram to display additional information Close box This is a box the size of a single character lo cated at the left side of the title bar It allows the user to close the window Full box This is a single character located in the right corner of the title bar which allows the user to expand the window to full screen size or to retract it to its original size and position Horizontal and or vertical slide bars These bars stretch across the bottom or right window borders They contain a rectangle called a slider with optional arrows at either end The arrows are used to move through the contents of the win dows a single character at a time while the slider is used to scroll the window contents in arbitrary increments It is also possible to mo
8. wh WF FIRSTXYWH amp wrect g x amp wrect g y amp wrect g w amp wrect g h while wrect g w amp amp wrect g h while not at last rectangle if overlap drect amp wrect check to see if this one s damaged t set_clip amp wrect 4 if it is set clip rectangle display 3 redraw and turn clip off vs Clip handle FALSE int amp wrect n wind get wh WF NEXTXYWH amp wrect g x amp wrect g y t wrect g w amp wrect g_h 3 gt CHAPTER 3 wind update END UPDATE graf mouse M ON x L display int pointsl4 wind get msg 31 WF WORKXYWH amp work g_ amp work g w amp work g hh clear rect amp work 13 grect conv amp work amp points t vef interior handle 2 vsf_style handle 7 msgl3 2 t vsf color handle msgt32 v aellipse handle pointst2J work g work g_w 2 work g h 2 5 4 8 ays VDI points array unlock screen turn mouse pointer back on X draw the window display 4X kwork g y find work area and clear it convert work grect to array set fill type to pattern adjust fill pattern set color w 2 pointsL 1J work g h 2 draw a filled ellipse t 18 gt gt gt gt gt gt gt gt Utility routines used by other functions 4444444 4XX amp amp set clipt r GRECT r int pointsr423 grect canv r
9. 251 obic find Find Objects Under Mouse Pointer objc_find Opcode 43 Finds the topmost object that covers a particular point on the screen usually the spot occupied by the mouse pointer C binding int foundob firstob depth x y struct object tree foundob objc_find tree firstob depth x y Inputs firstob depth tree Results foundob See also wind find 252 control 0 43 Opcode control 1 4 control 2 1 control 3 1 control 4 0 int in 0 int in 1 int in 2 int in 3 addr in 0 int out 0 Number of 16 bit inputs in int in array Number of 16 bit results in int_out array Number of 32 bit inputs in addr in array Number of 32 bit results in addr out array The object number of the first object in the tree to be searched All descendants of this object will be searched as well The number of levels of descent from the original object to search The object itself is zero levels down its immediate children are one level down their children are two levels down and so on The horizontal screen coordinate of the point to be searched The vertical screen coordinate of the point to be searched The address of the object tree array which contains the objects The object number of the object found at the designated screen location If no object was found there 1 is returned d 71 7 Jt d L L t a L L
10. 305 shel write Results status int out 0 See also shel read 306 that follows the name of this program in the command string used to start the program Error status code 0 an error occurred during execution gt 0 no error occurred during execution JS J ze scd m ub Sak dad dJ I CL tt a L L shel find Search for Filename shel find Opcode 124 This function is used to search for a filename It first searches the current di rectory and then each directory in the current search path If it finds the file it returns its full pathname C binding int status char pathname 128 status shel get pathname Inputs control 0 124 Opcode control 0 Number of 16 bit inputs in int Lin array control 2 1 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array pathname addr_in 0 The address of a buffer which initially holds the text string of the name of the file to search for Upon return from this function this buffer will hold the entire pathname of the file including drive specification and directories if the func tion was able to find the file Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution 307 shel envirn Search for Environment String shel
11. In addition to window messages your program should be ready to adjust the slider position in response to changes in the window size or document size As with the slider size however before you make any change in the position of the slider you should first check to make sure that the new posi tion will actually be different than the current one You can determine the current slider position with the WF_HSLIDE and WF_VSLIDE subcommands of wind get wind get wi handle WF VSLIDE amp position amp dummy amp dummy amp dummy wind get wi handle WF HSLIDE amp position amp dummy amp dummy amp dummy where position is the variable in which the current position is returned and dummy is a dummy place holder variable which must be used because wind get always returns exactly four values If the new position is equal to the old one you needn t perform the update Updating the window display The third and final part of maintaining a window that contains scroll bars is updating the window display You will not get a window redraw mes sage when you use wind set to change the size or position of the slider You must take the initiative either to call your re draw routine directly or to send yourself a redraw message In order to calculate where in the document to start the window display you may have to do the reverse of the calculation that you did to find the slider position from the document start window sta
12. Show the mouse pointer amp vsf_interior handle 2 3 Set Fill Pattern for Ellipse Main Program Loop X while done X until user selects Quit item t check menus and keyboard event evnt multi MU MESAG MU KEYBD 2 9 9 evnt button 9 9 0 0 0 evnt mousel 2 0 9 2 90 18 evnt mouse2 8 amp msg evnt_mesg amp 2 9 evnt timer amp dummy amp dummy mouse x y amp dummy 18 mouse button amp amp dumny amp shift keys amp kay evnt keyboard amp dummy 3 number of clicks if event amp MU MESAG if we get a message handle it done handle msg msg if event amp MU KEYBD amp if key check for equivalents done handle key key gt 18 end of main WHILE loop amp menu bar menutree 9 Remove the menu bar gt end of DEMO function 1 Message Handler routine only handles menu messages amp 1 yours should also handle redraws window topping etc handle msg msg int msgr81 int done 2 Switch msgf93 check message type case MN SELECTED if menu message type K switch amp msgL42 X check menu item amp 4 145 case ABOTITEM CHAPTER 5 if About display alert form alertt 9 alert break case PATIITEM drawc7 2 break case PAT2ITEM draw 3 3 break case QUITITEM done 1 break default
13. The array index within the structure of the data whose address is sought 299 Results status address See also rsrc_load 300 rsrc_gaddr int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution addr out 0 The address of the data whose position is specified by index and whose type is spec ified by the type variable Ld cj 1 sail sacd 3 Nu 2 al d tf L CL LL C LE ps rsrc_saddr Store Address of Resource Data rsrc_saddr Opcode 113 This function is used to store the address of a data structure within one of the elements of the arrays that was contained in the resource file that was loaded It s used by rsrc_load to fix the addresses of pointer fields like ob spec te ptext etc It can also be used by an application for example to dynamically change the text field of a string object C binding int status type index long address status rsrc_saddr type index address Inputs control 113 Opcode control 1 2 Number of 16 bit inputs in int in array control 1 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array type int_in 0 A code specifying the type of structure into which the address will be placed Valid code numbers are Type Number Macro N
14. The number of user actions to be recorded Since each action requires six bytes of stor age this number should be no greater than the size of the buffer divided by 6 buffer addr in 0 The address of the buffer where the users re corded actions will be stored Each event is stored as six bytes The first two bytes hold a 16 bit event code 0 timer event mouse button event 2 mouse movement event 3 keyboard event The last four bytes are a 32 bit longword the meaning of which depends on the event Timer Time elapsed in milliseconds Mouse Button Low word button state High word number of clicks Mouse Movement Low word x position High word y position Keyboard Low word character typed High word shift key status Results recorded int out 0 The number of events actually recorded See also appl_tplay 228 b ud Ed Tak Boal A N L cj EL L EL FL L E am appL exit Clean Up Application appl_exit Opcode 19 This function notifies the AES that the application is about to terminate so that the AES can release whatever system resources are allocated to the application C binding int status status appl_exit Inputs control 19 Opcode control 1 0 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control 0 Number of 32 bit inputs in addr_in array control 4 0 Num
15. This is line 1 This is line 2 This is line 3 The final set of square brackets contain the text for the exit buttons A maximum of three exit buttons may be used each of which contains a maximum of 20 characters of text As with the message string the text for each button is separated with a vertical bar character When the alert concludes the number of the exit button 1 2 or 3 is returned in the exitbutn variable Note also that when the alert ends the AES automatically restores the screen rectangle it had covered Since the AES stores the screen background in the menu alert buffer it can use the raster blit functions to replace it without intervention from your program There are two ways to generate an alert string The first is to create it using a resource construction program save it as part of the resource file and then use the rsrc_gaddr func tion with the R_STRING type to find its address The menu program examples in the preceding chapter use this method to 158 u J J J j 3 1 1 L LE L LELLO Interactive Object Handling display the alert boxes for the About menu items The sec ond way is to simply include the string constant as part of your form alert call like this form alert 1 2 To be or not to be That s a question J YES NOI MAYBE This method is used in the menu examples to generate the alert that notifies the user that the resource file can t be loaded since
16. do evnt button 1 1 1 5 amp amp y amp button kkeys object objc find tree 1 x y gt while object EXITBUTN keep checking til we find object 1 show object selected State 2 treel EXITBUTN ob_state SELECTED 7 8 flip SELECTED bit ob jc change tree EXITBUTN work g x wOFk g y work g Ww work g h state 1 gt EKKEATEAKSKAKAKAAEKAK End of Object c 5 25 5 223252222 22 22 22222 125 CHAPTER 4 Please note two points about this program First an array of object structs called tree was declared and initialized at the same time The x y width and height values could not be filled however since there is no way to know in which of the three display resolution modes the program would run To solve this problem the number of character cells the object oc cupies was put into the x y width and height fields Then when the program started each of the x y width and height values was multiplied by the default character cell width or height This produced objects that occupied the same number of character cells regardless of the resolution mode though these objects are twice as wide in low resolution mode since it only provides 40 characters per line Setting up objects in this manner may be easy to demon strate but it s by no means the preferred method Typing all of the data by hand and then manually linking the objects to each other and to their ob spec fields
17. while done until user selects Quit item evnt_mesage msg 8 check menus done handle msg msg amp amp handle messages amp 2 end of main WHILE loop menu bar menutree 2 Remove the menu bar end of DEMO function Message Handler routine only handles menu messages and redraws yours should also handle window topping etc handle msg msg int msgt83 int done 165 pt switch msgt91 check message type case WM_REDRAW if redraw call refresh routine refresh msg 3 GRECT amp msgC41 break case MN_SELECTED if menu message type switch msgl4 7 check menu item amp case SURVITEM Do Survey dialog do dial break case QUUITITEM Quit done 1 break default break 3 end of switch on menu item menu tnormalimenutree msgt31 1 set menu to normal break defaults break end of switch on message type return done j report done status Dialog Handler routine Displays survey form do dial O C w int x y width height exitbutn form center dialtree amp x ky amp width amp height form dial FMD START 9 x y width height objc drawtdialtree ROOT MAX DEPTH x y width height exitbutn form do dialtree OTHERTXT check objs exitbutn check object states etc form
18. xS36C x AF x 4F x ZE OxFFFF Ox 9G19 9x0002 Ox BOGS Ox GOOG 9xFFFF Ox OOGF 9x900900 QxFFFF OxGOOi Ox BOGS QxFFFF 6x 9968 Ox GOA OxFFFF 9x9004 Ox BAGG 9x FFFF 3 Ox AOA s xGO76 6x 9196 Ox Gi9A Ox 6964 9x 99024 90x3054 Ox GBI 9x09003 9x00902 0xe09002 9 x0002 0x0901 OxFFFF Ox S968 9x09000 OxFFFF Ax 6x GOGO OxFFFF 0x0007 9x0000 9xFFFF 9x902006 0 990FF OxFFFF ax 030 Ox DOSA Ox 200C 9x4958 9 6572 9x494F 9x494F 9x002F x 9x1109 9x90014 Ox BGGA 9x1171 LDIR 9x0001 Ox SOSA 9 001C 9x 001 9x9041 9 9001C 9x90001 ex0Qsi 0014 9 00905 9x1191 Ox Gaia Ox Aas Program 3a dialog2 h resource set indices for DIALCG2 DIALOG2 RSC 279976 x Z 1 9x 4954 9x29050 Qx4ES1 9x4ES33 0x900 OxFFFF 9x9001 9x90000 9x90001 xDD 9x009007 9x90005 9x9019 Ox Bags x GOOT Ox 990A 0x00900 0 0039 Ox AIDA 9 0001 Ax BOB x W 3J 270021 adxViogdo x SA 9x0001 0x002 4 Ox6F 73 OxOO4aF Bx S Ox BIBS 9x0091 Ox YX OOO OxFFFF Ox GB Or GOOG OxFFFF Bx BAdsS 90000 OxFFFF 9 09005 D 0000 e9xFFFF x B x 0 xFFFF 9 0007 Bx GINA 8x 376 fx 05 x POOO Ox 2626 ax 6974 x S SA Ox BOGE x N x B 2x A027 Ox GOFF FFFF Bx WMIB2 Sx GIS OxFFFF B
19. 7 2x 1 Sx D 2x 7 2x B x F x C x B x 11 x 4 Ox Visa 9x0001 Ox SFSF Sx SFSF x SESE 9x 4552 9x 3136 9x0041 9x4F77 9x4174 9 7929 9x6C299 9x6329 9x465F 9x 2D2D 90x9090290 9x7920 9x6573 9x6B29 9x2029 9x29 54 9x7373 9x2941 Ox 2953 9x74909 Bx BBWS 9x90901 xB x 9xFFFF 9x990901 x xFFFF x BOSS 9xe0090 9xFFFF Bx BISD x DDOD xFFFF Ox FFD x 9xFFFF Ox VOSA x BIG 9xFFFF Ox E s x xFFFF x A Ox BOSS 9xFFFF 9x0911 9x9018A x xSFSF xSFSF xGEGE 9x29055 2x 31 9x6763 9x6E635 9x6172 QxoS36F 9x 4F4B x 2 9x7229 9x2D2D 0x2044 x312 9x7356F 9x4163 9x 4465 9x2920 9x6F 72 2x6363 x7572 9x90000 Qx090900 9x90911 9x0927 x 9xFFFF x F x xFFFF 9x9090909 Sx BSS 9xFFFF x B8 x QxFFFF 9x99012 9x9gFF 9xFFFF x g 3S x FF 9xFFFF x 3J x xFFFF 9x99090B x xFFFF 9x PIGE x00024 Ox BBWS gxSFSF OxSFSF Ox 6E6E 9x9332 x362D x SASS Ox 645A Sx 6926 9x7265 x 2 x2 54 9x5265 9x2D2D 9x6575 9x2009 2x7279 2x6365 Sx 736B 9x900290 9x79290 9x6375 9x7663 9x9924 9x1182 9x909014 9x9815 9
20. Or the following could be used since in C the string Window Title is treated as a pointer to a static array of the type char wind set wi handle WF NAME Window Title 0 0 Note that you must use a static array since the AES will periodically look at this title in order to redraw the title bar when the window is sized If the array is not permanent the pointer to the string might be rendered invalid In such a case the AES might try to access an invalid string with disastrous results Once you ve set the pointers to the window title and information line strings if necessary you re ready to open the window The format for the wind open call used to per form this function is int status wi handle x y width height status wind open wi handle x y width height where x y width and height describe the initial exterior di mensions of the window These dimensions may be smaller than the full size window described in wind create but they may not exceed those dimensions The status value re turns the error status of the function A 0 indicates that an er ror has occurred while a value greater than 0 means no error As with wind create the dimensions used to describe the window in wind open measure the exterior of the win dow and include the borders and any controls located within those borders Your program however must confine its out put to the interior area of the window so as to
21. The user has dragged the Size Box The handle of the window for which the size change is requested 4 The requested x position of the window s left edge the same as the current window x position 9 The requested y position of the window s top edge the same as the current window y position 6 The requested width of the window 7 The requested window height Word Number Contents 0 28 WM MOVED message The user has dragged the Move Bar 3 The handle of the window whose move bar was dragged 4 The requested x position of the window s left edge 5 The requested y position of the window s top edge 6 The requested width of the window the same as the current width 7 The requested window height the same as the current window height Word Number Contents 0 29 WM NEWTOP message A window has become active 3 The handle of the window that s become active Word Number Contents 0 40 AC OPEN message A desk accessory menu has been selected 4 The menu item number menuid of the desk accessory the user selected Word Number Contents 0 41 AC_CLOSE message An application has closed so desk ac l cessories should release their window handles 3 The menu item number of the desk accessory to be closed See also evnt multi 237 evnt timer Wait for Timer Event evnt timer This functions waits for a specified number of milliseconds to pass before returning C binding int reserved unsigned int timelo timehi reser
22. bath print You pressed s b mouse button s print while the mouse was located at mousex mousey print Shift key status was shiftkey 197 LrEbrc Fecec Chapter 8 Desk Accessories COCOG 4 OCCA tL ft L L b 12 E L The programs discussed so far have been applications run by double clicking their icons from the Desk top As stated early on however GEM supports another type of program as well This type of program is called a desk acces sory because of its ability to run concurrently with the Desk top or any other application program that has installed a menu bar Desk Accessories Desk accessory programs are loaded at boot time These in clude all programs located in the root directory of the boot disk either the floppy disk in the A drive or the C partition on the hard disk which have the extender ACC attached to their names There may be a maximum of six of these pro grams Desk accessory programs are started by selecting the menu item associated with them from the DESK menu at the far left side of the menu bar There are several small but important differences between writing a desk accessory program and writing a normal application The first difference is in the initial code used to start up the program When an application program starts it is given control over the entire Transient Program Area TPA which consists of all of the free system memory Normally the appli cati
23. ds w ds w dS W ds w ds w ds w eds w ds w fre pi pre ge he po fed fre pt j G A fe ds w 128 ds w 128 ds w 128 ds w 128 kK t t6 amp 4 4 AES Data Arrays SETTTTSEATAKKETS ctrl ctr1 ctr11 ctr12 ctrl3 ctrl4s global version count apids private tree resvl resv2 resvs resv4 aintout aintin addrin addrout ds w e dg Ww ds w ds w ds w 9 pt pi ge pe ds w ds w ds w ds 1 ds 1 ds 1 ds 1 ds 1 ds 1 9 po m pt dem de je i pt ds w 8 ds w 18 ds 1 3 ds 1 2 The AES and VDI parameter blocks hold pointers to the starting address of each of the data arrays apb dc 1 ctri global aintin aintout addrin addrout vpb dc 1 contrl intin ptsin intout ptsout amp 1 Misc variables XtX vwkhnd pwkhnd wdwhnd chboxw chboxh cellw cellh ds w 1 dsew 1 ds w pa d8 w d3 wW ds w ds w 9 fre Pen pe d I Lo bd d LU bL UU CECE Starting an Application deskx ds w desky ds w deskw ds w deskh dS w pa M Pe n wor kx eds Ww worky ds w wor kw ds w war kh ds w pa jb jd b xdef demo xdef wdwctr1 xdef wdwtitl xdef wdwinfo xref aes The first part of the program requires a bit of explanation When GEM starts an application program but not a desk ac cessory it allocates all of the system memory to that program Therefore if the program
24. essary to define a relationship between them The first three fields in the data structure for each object are used as pointers to other objects These pointers ob next ob head and ob tail define the relationship between objects and make it possible for example to draw a series of related objects with a single command The system used to link objects is called a binary tree If you look at a diagram of such a tree you ll notice that it re sembles a family tree A family tree starts with the earliest known common ancestor at the top and shows each genera tion branching out downward so that the tree grows larger and larger the farther down you go binary tree works much the same way and even uses the same terminology so that parent objects may spawn groups of related objects which are referred to as their children A struct is a data structure as used in the C programming language Structs might be formed of any kind of data The type of struct is determined by the data it contains Thus if the struct contains object data it is a struct of the object type An object tree is simply an array of object structs The object number of an object is the array index number of that object The root object object number 0 sits at the top of each object tree The screen display rectangle of the root object completely encloses all of the other objects in the tree The largest objects within the root are the sibling objects which are all
25. ing down the Control key and holding down the mouse but ton in the lower right corner of the box This selects the parent object Drag the box to the right so that you make some room for a G_BOX At this point it s probably a good idea to move the second menu item to the clipboard temporarily Next add a G BOX that completely covers the space to the right of the G STRING on the top line Make it foreground color 2 fill style 6 with an outside border of one pixel Next move a G_IBOX to the second line and size it so that it covers the en tire menu line Edit it to remove the border and move it over the top menu line If your editor tells you that the G_IBOX now covers its two siblings and asks if you want to make it 147 CHAPTER 5 their parent answer No You want the three objects to re main siblings so that when the user selects the IBOX all will be highlighted Repeat the process with the second menu item its G_BOX has a foreground color of 2 and a fill pattern of 5 and you ve got a menu with words and pictures on the same line Once you ve set up your menu there are a number of ways you may modify it One way you can change a menu once your program is running is to disable or reenable one or more menu items Disabling a menu item signals the user that a choice is temporarily inappropriate For example if the user starts a new project which hasn t yet been named you might not want to allow the Save option to be used f
26. outstate intLin 3 The ob state flag setting of the object when the mouse pointer with button down is outside of its rectangle tree addr in 0 The address of the object tree array which contains the object Results in or out int_out 0 A code indicating the relative position of the mouse pointer when the user released the left mouse button 0 pointer is outside of object rectangle 1 pointer is inside of object rectangle See also form_do evnt_multi evnt button 274 4 j33 1 J 4 4 Jj LO CLE L 1 L L a graf_slidebox Let the User Drag a Box Object graf slidebox Opcode 76 This function draws a moving box outline which is the same size as a box object slider which is contained within a parent box object slide bar This moving box follows the mouse pointer within the constraints of its con tainer so long as the user holds down the left mouse button When the left mouse button is released the function ends and it returns a code indicating the relative position of the slider object within the slide bar object It should only be called when the program has determined by returns from form do evnt_multi or evnt_button that the mouse pointer is positioned over the object and the left mouse button is down since if the button is up when the call is made the function will end immediately This function can be used for example to implement a slide bar in a dial
27. played If there aren t any editable text fields in the dialog the number 0 should be used tree addr_in 0 The address of the object tree array which is used to draw the dialog d WI Results exitobj int out 0 The object number of the object whose se lection caused the dialog to terminate If a TOUCHEXIT object was double clicked the high bit of this value will be set See also form button form keybd objc_edit evnt_mullti ye a p dJ d B d tm L C form dial Begin or End Dialog form dial Opcode 51 This function can be used to reserve a portion of the screen for the dialog box to release that portion of the screen and to draw an expanding box before the dialog opens and a contracting one after it finishes C binding int status type smallx smally smallw smallh int largex largey largew largeh status form dial type smallx smally smallw smallh largex largey largew largeh Note This binding varies from the one described in the Digital Research documentation which omits the rectangle information for the second rectan gle The binding shown above however conforms to the format actually used in Alcyon C bindings supplied by Atari and all bindings that derive from them such as those used by Megamax C Inputs control 51 Opcode controll1 9 Number of 16 bit inputs in int_in array control 2 1 Numb
28. which is used to display or erase the checkmark in front of menu items The DISABLED flag The DISABLED flag is used to indi cate that an object usually a menu item or button may not be selected The AES draws a DISABLED object faintly by super imposing a crosshatch of white dots over it The form do routine will not allow the user to select a DISABLED object by clicking on it though it will allow the selection of a DEFAULT DISABLED object by pressing Return The OUTLINED and SHADOWED flags The final two states OUTLINED and SHADOWED are used mostly for cos metic enhancement of container type box objects The OUT LINED state causes the AES to draw the object with a thin outline around it Combined with a two or three pixel inner border this gives the object an attractive frame The SHADOWED state causes the AES to draw a drop shadow under the object This is a two pixel line drawn under neath and to the right of the object Root objects of dialog boxes often have a drop shadow under them Object Library Routines The AES provides a number of low level routines for dealing with objects The most basic routine draws an object tree You ll recall that an object tree is a linked array of object data structures It s called objc_draw Here is how it is called int status firstob depth clipx clipy clipw cliph struct object tree status objc_drawitree firstob depth clipx clipy clipw cliph 120 cel aub
29. window ctrl flag move deskx aintin 2 max x move desky aintin 4 amp max y move deskw aintint max width move deskh aintin 8 max height 211 CHAPTER 8 jsr move x bmi aes aintout wdwhnd save window handle wdwerr if negative exit program set window name move move move move move l jsr 105 ctri command wind set 86 ctr11 6 input integers wdwhnd aintin window handle R2 aintint2 subcommand set window name VwdwWtitl aintin 4 amp point to title aes g1 Open the window to 1 4 max size move move move move move move asr move move asr move jer 412901 ctrl9 command wind open 5 ctrii 1 ctr12 1 ouput integers deskx aintin 2 X initial x desky aintin 4 initial y deskw d 41 d9 dO6 aintin 6 initial width deskh d 1 dd dO aintin BG g initial width aes ttt Find window work area size move move move move jer move move move move rts Message S msghand move cmpi bgt bne move cmp bne cmpi beg move jap msg cmpi bne move cmp bne campi bne jap 212 4104 ctrl10 command wind get 42 ctr11 2 input integers 85 ctr12 x 5 ouput integers 4 aintint2 WF WDRKXYWH command aes aintout 2 workx store work x y w h aintout 4 worky aintout workw aintout B workh gt handler subroutine t g msg dS check message type 41 05 AC CLOSE msgS i
30. xref intin xref ptsin xref ctrilQ all of the AES data arrays xref ctr11 xref ctr12 xref ctris xref ctr14 xref aintin xref aintout xref addrin xref deskx xref desky xref deskw xref deskh xref wor kx xref wor ky xref wor kw xref wor kh text demos move 480 d4 x close window flag in d4 create and open second window move 41090 ctrl10 amp command wind create move aS ctr11 9 input integers move 81 ctr12 1 ouput integer move wdwetri aintin window ctrl flag move deskx aintin Z2 max x move desky aintint4 max y move deskw aintin 6 max width move deskh aintin B max height CHAPTER 3 jsr aes move aintout wh2 save window handle amp set window name move HI S cCtrl command wind set move 3 ctril S input integers mova wh2 aintin window handle move 2 aintint2 subcommand set window name move 1 titl2 aintint4 point to title jsr aes kst Open the window move 11 ctr1 command wind open move 5 ctril move 1 ctr12 1 output integers move deskw d asr 2 d add deskx d8 move dO9 aintin 2 initial x deskw 4 deskx mova deskh d asr 42 d9 add desky d move dS aintin 4 initial y deskh 4 desky move deskw d asr bl d move d aintint d initial width deskw 2 move deskh d agr bl d move d aintint8 initial height deskh 2 jer aes main move 8235 ctrl opcode evnt_m
31. 2529 d5 WM REDRAW msg3 retresh Window refresh subroutine refresh turn mouse off move move move move jer lock scren move move move move 4 78 ctr190 command graf mouse 1 ctrii 1 input integers i ctri2 amp 1 output integer 8256 aintin hide the mouse aes 4127 ctr16 command wind update g 1 ctr1i X 1 input integers 41 ctr12 1 output integer fi aintin code BEG UPDATE CHAPTER 3 amp Find first window rectangle refreshi move or beq move move cmp bcs move olap1 move move cap bcs move Olap2 move add move add cap bhi move olap3 sub move move add move add cmp bhi move olap4 sub move or beq 194 ctr19 command wind get 82 ctrl11 amp 2 input integers 5 ctri2 5 ouput integers msg aintin window handle 411 ai ntin 2 WF FIRSTxYUH command aes aintout d aintout 8 d refresh msg 8 d aintout 2 d1 d di olapl di dg msg tig di aintout 4 d2 di d2 olap2 d2 di meg 8 d2 msg 12 d2 aintout 2 d3 aintout 6 d3 d2 d3 olap3 d3 d2 d d2 d2 aintout msg 1 d2 msg 14 d2 aintout 4 d3 aintout 8 d3 d2 d3 ol ap4 d3 d2 d1 d2 d2 aintoutts aintout d2 refresh2 set clip rectangle move move move move move move 129 contrl 8 2 contr11 contri 1 contris 30 contr14 8l intin nd oe Ht 95 9 check for em
32. 812 aintin 2 WF NExTxYWH command aes refreshi 197 ctr1 1 ctri1i 1 ctr12 490 aintin aes 78 ctr1d i ctrii 41 ctr12 9 mm command wind update 1 input integers 1 output integer code END UPDATE command graf mouse 1 input integers 1 output integer 257 aintin hide the mouse aes 4194 ctr19 2 ctrii 5 ctri2 msg aintin 4 aintin 2 g t g Window display subroutine amp K command wind gat 2 input integers S ouput integers WF WD RKXYWH command CHAPTER 3 Jer aes move a ntout 2 workx amp store work x y w h move aintout 4 worky move aintout wor kw move aintout 8 workh set fill pattern to hollow move 23 contrld opcode for set fill type move 29 contrii move 2 contr12 move 1 contr13 one integer in intin move 1 contri4 move H intin select hollow fill type jsr vdi t Storage space and data constants data seven msg ds w 8 wdwtitls dc b First Window titl2 dc b Second Window wdwinfos dc b wdwctrl dc w 35 wh2 ds w end Scroll Bars and Their Messages When you want to display more information than you can fit onscreen at one time you may wish to make the window a view port onto a larger area By using slide bars or scroll bars you allow the user to select which portion of the window s con tents to view As with the other GEM features discussed here actually scrolling the doc
33. As you will see in a later chapter your program may also use the Object Library routine objc_draw to draw part of the window contents The input parameters for this call include the position and size of a clipping rectangle When you use this call therefore you may just give the dimensions of the overlap rectangle as the clip area 60 Ld nd 1 3 1 Ll LI ud ui CECEC LOC T AES Events Each subsequent clipping rectangle is treated in pretty much the same manner as the first You get the next clipping rectangle with the call wind get wi handle WF_NEXTXYWH amp wrec g_x amp wrec g_y amp wrec g_w amp wrec g_h If the width and height of the rectangle aren t 0 which would signify that you ve already received the last rectangle on the list you find the overlap of the window rectangle with the damage rectangle If an overlap rectangle exists you set the clipping rectangle and perform the redraw This process continues until there are no more window rectangles to re fresh At that point you unlock the screen display with a call to wind update wind_update END_UPDATE This lets the AES know that it s safe to drop menus and so on If you forget this call your program won t be able to ac cess any menus After unlocking the screen you should turn on the mouse with a call to graf_mouse graf_mouse M_ON 0x0L To summarize the steps to take when refreshing a win dow display are
34. BS 9x9901C 9x90001 9x11990 9x291C 9x209001 Ox B1A 2x9221 9x6575 9x7728 9x2E2E 9x 2D2D 9x6B290 0x29020 x 2032 x7373 x 204 1 x28044 9x 3529 9x7356F 9x293E 9xSB46 9x2903B 9x6465 9x6F62 9x64290 9x61 ec 9x6563 9x642E 9x2D2D 9x2D2D Qx6D amp 52 OxFFFF x x x 1 x Z x x S Gx BIBS x x x x 9x0009 Px BIBS x x B r Ox J rx D x x xB F 9x2000990 Ox BIOS 9x90012 x S x B Ox E 9x9166 9x0000 9x6B22 x 2 9x2bE99 Sx2D2D 9x 4163 x4465 Sx 28928 9x6F72 9x6363 9x6375 Bx 2982 9x7279 xS1 9x 519D 9x46352 9x 6D6F x GAGS 9x6B6S x656E 9x7420 x7C2D Sx 2D2D 9x 2D2D 9x6572 9x2001 9x BVO Px BIO Sx J Px BIW Ox WISP OxFFFF x x B 0x0007 x 3 1 x xFFFF x x B 9xFFFF Ox 9992 Ox BOOS OxFFFF 9x0094 Ox IDD OxFFFF Ox BIBS Sx BIOS 9x992911 x 9x 9x0913 9x90102 Bx BBO x 2929 Sx 2941 9x 2D2D 9x 2D2D 9x6365 Ox 7S6B x 9929 9x 7929 x 6573 Sx 6B28 9x 2929 Bx 2936 Sx 2828 0x0020 9xSD99 9x2077 Ox 6374 9x7962 2x7473 9x2231 x2D2D x2D2D 9x 2DSD 9x2074 9x00906 x
35. Keeping the initialization code in a reusable file will shorten the sample listings substantially and eliminate retyp ing Be sure the file aesshell c is stored where your compiler can find it either in the same disk and directory as your standard header files or in the same disk and directory as the source code file Program 2 2 is the text of the aesshell c pro gram shell Program 2 2 aesshell c 523X 5252529253225255 952 444532 4XXX5t555X3 525X5 55XXtz5455455554252252525225t15 r X X AESSHELL C Program template to be included with most of the AES example programs Performs init amp rt 1alization functions calls the demo program x X then does the cleanup work amp AXX3A8ESXEEERERERERESSERS SASAAASESSSESARSESESSESESESSOESSEESASRSSERESSESSSES hinclude lt osbind h gt 1 Macro definitions for BIOS calls H include lt gemdefs h gt Flag definitions for Library routines include lt obdefs h gt Object definitions t define DESK The flag for the Desktop Window t idefine ND ERR 9 Error no for no error define APP ERR 1 Error no for failure of appl_init Sdefine VWK ERR 2 Error no for failure of v_opnvwk 8 define WDW ERR 3 X Error no for failure of wi create amp 36 d eed ux e aJ dd x l ani x ud t UL L L OL 0 Starting an Application Global variables For VDI bindings and program routines ex
36. S x x S 0x909012 9x0009 OxFFFF Ox BBV x 9x99012 x S x FF OxFFFF 9x909016 x OxFFFF x 16 Ox OxFFFF 9x909016 x OxFFFF 0x09216 x 9x90011 Ox C Sx 9x90018 2x 24 Bx BIOS 9x4669 9x626F 9x 2D2D 9x2D2D Ox7373 9x29041 9x29044 9x 55290 9x736F x4163 9x 4465 Ox 2829 9x 3961 9x20390 9xSB39 9x6974 9x7C20 9x6F61 9x7C20 0x7869 Sx 2D2D 9x 2D2D QxSBA49 9x6861 9x0019 9x909019 x 11 9x90919 x S L 0x90924 x 9929 9x03901 2x 9 32 9x90019 9x90915 2x11009 9x991C 9x090901 9x90904 9x991C 9x0091 0x0976 9x991C 9x00901 Bx BIRD x9091C 9x0001 x CA 9x909014 2x90001 x DF 9x909014 9x0102 9x00901 9x6C63 9x7974 9x 2D2D 9x 2D2D 9x6F72 9x6555 9x69375 9x20090 9x7279 9x6365 Qx736B x828 8x 7474 9x6174 xSDSB 9x6829 9x6974 9x7264 9x 2929 x7422 9x 2D2D 9x2D2D 9x276UC 9x749D 9x0000 Bx BIDS Sx Bx BIOS Bx BOO4 9x0000 9x09009 9x0002 9x90909C 9x20000 9x09019 9x9002 9x0200 Sx A x Bx DIOS Sx BOC 9xeoo00 Sx x E s x 9x90007 Bx BBWS Bx BIOS Ox Bid Sx BOBO 9x0009 321 s BOBO xFFFF x Ox Oy FFFF 9x99001 Or BIBS 9xFFFF x B
37. The graf_mkstate call provides information about the current position of the mouse pointer on the screen and the current state of the mouse buttons and shift keys Though this is the same kind of information returned by the evnt button and evnt multi calls the difference is that graf mkstate doesn t wait until an event occurs Rather it returns immediately reporting the current status of the mouse buttons and shift keys This makes it suitable for use in a polling routine that checks one or both of the mouse buttons Note that AES input functions like graf_mkstate should never be mixed with VDI functions or GEM will get very confused Your program should use AES input functions or VDI input functions but not both C binding int reserved mousex mousey mousbutn shiftkey reserved graf_mkstate amp mousex amp mousey amp mousbutn amp shiftkey Inputs control 79 Opcode control 0 Number of 16 bit inputs in int in array control 2 5 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array l Results reserved int out 0 Reserved for future use always equals 1 mousex int out 1 The horizontal position of the mouse pointer at the end of the function mousey int out 2 The vertical position of the mouse pointer at the end of the function button int out 3 The final mouse button state 0 both buttons up
38. This element is assigned the variable name gl_apid by the bindings If your C compiler library does not return the correct value you can work around this bug by declarin the external variable gl_apid and getting the value from this variable extern int gl apid int ap id appl_int ap_id gl_apid If you ve registered an application with the AES be sure to unregister it before your application terminates You per form this function with a call to appl_evxit as follows int status status appl_exit 21 CHAPTER 2 Status is an error return code A value of 0 in status indi cates that an error occurred while a positive integer value in dicates that the application exited successfully Opening a Virtual Screen Workstation Since most GEM programs use at least some of the VDI graphics function you ll need to prepare a graphics output environment by opening a VDI screen workstation Though this process is covered in detail in Volume One of this series a brief review follows The VDI call used to open a graphics workstation is v opnvwk It s invoked like this int input 12 int output 57 int handle v opnvwk input amp handle output The input array consists of 12 words of data passed to the VDI to specify the initial default graphics settings for the workstation With two exceptions you can set these to a de fault value of 1 The first of these exceptions is input 10 which is used to s
39. addr_in 3 POKE addrin 12 The following short program shows how to change the shape of the mouse pointer from an arrow to a pointing hand with the graf_mouse call from BASIC 10 apb gb 20 contro PEEK apb 30 global PEEK apb 4 40 gintin PEEK apb 8 50 gintout PEEK apb 12 60 addrin PEEK apb 16 70 addrout PEEK apb 20 80 POKE gintin 3 REM Pointing hand is shape number 3 90 GEMSYS 78 REM call graf_mouse This method of making an AES call from BASIC is similar to that used in the machine language program shown above in that the input parameters are placed directly in the int_in array But you ll also notice that the GEMSYS call takes care of a lot of the detail work First there was no need to POKE a value for the opcode into control 0 because the opcode is passed as part of the GEMSYS call Second the GEMSYS command performs the same tasks as the three lines of ma chine language code It places the address of the parameter block into register d1 places the AES identifier code into d0 and then executes the TRAP 2 statement The original version of ST BASIC doesn t contain any built in commands that perform the same functions as AES calls Although not yet released at the time of this writing the revised MCC BASIC promises to include a few such as ASK 15 CHAPTER 1 MOUSE which returns the current mouse position like graf mkstate And the revised BASIC is slated to inclu
40. amp MU M1 if mouse leaves rectangle change pointer set ptr mx my amp r and reset rectangle to watch gt end of main WHILE loop gt end of demo function amp X 329522223 292 Pointer change routine 5 5 25 2525525222 2525212 set ptr x y r int x y mouse x y GRECT amp r3 new rectangle to watch e t int form if y lt work g_y 4 if above window work area C form 18 set to arrow shape r gt g_x r g y 9 r g w work g w r g h work g y 1 2 else if y lt pointst1J if above center box form 3 set to pointing hand 7 r g x work g x r gt g_y work g y r g w work g_w3 r g h work g_h 3 else if y gt pointst3J3 7 if below center box c form 43 18 set to open hand 47 r g x work g xj r g y work g_y work g h amp 2 3 r g w work g_w r g h work g h 35 3 else if x lt points if left of center box C form 33 set to thin cross hairs r g work g x r g y work g_y 4 waork g h 3 r gt 9_W 2 work g_w 33 r g h work g_h 3 2 else if x gt points 2 if right of center box C form 6j set to thick cross hairs r g X work g_x work g_w 2 3 r gt _y work g_y t work g_h 3 r gt g_Ww work giw 33 r gt g h work g h 3j 2 else if IN center box C form 2553 set
41. amp key evnt keyboard amp dumny 5 number of clicks t 150 MP p P aAa J I OR J s CL L EOL Resource Files and Menus if event amp MU MESAG if we get a message handle it done handle msg if event amp MU KEYBD t if key check for equivalents if key CTRLQ done 1 end of main WHILE loop menu bar menutree 49 Remove the menu bar amp gt end of DEMO function t Message Handler routine only handles menu messages yours should also handle redraws window topping etc handle msg int done switch msogt 1 check message type t case MN SELECTED if menu message type switch msgf41 check menu item case ABOTITEM if About display alert form alert 2 alert break case CHEKITEM Toggle Checkmark if menutreeL CHEKITEMJ ob state amp CHECKED menu icheck menutree CHEKITEM 2 text Check Mark is now turned OFF 1 gt else menu_icheck menutree CHEKITEM 1 text Check Mark is now turned ON 2 2 break cage TOBLITEM draw Pattern 2 t if menutreeLtABLEITEM1 ob state amp DISABLED c menu ienable menutree ABLEITEM 1 menu text manutree TOGLITEM menuoff text Menu Item is now turned ON 2 3 else c menu ienable menutree ABLEITEM menu text inenutree TOGLITEM menuon text Menu Item is now
42. and optionally to redraw it at the same time It s called like this int status object reserved clipx clipy clipw cliph state redraw struct object tree J status objc_change tree object reserved clipx clipy clipw cliph state redraw where tree is a pointer to the object tree object is the number of the object to be changed and state is the new ob state flag value The redraw flag is used to indicate whether or not the object should be immediately redrawn a 1 indicates that the object should be redrawn while a 0 indicates that it should not If the object is redrawn the clipx clipy clipw and cliph variables are used to set the clipping rectangle prior to the redraw The objc_edit function assists in the process of letting the user edit a text object It s the low level routine used by the dialog handler routine form do to implement text editing The syntax of the objc_edit call is int status object char index type struct object tree status objc_edit tree object char amp index type where free is a pointer to the object tree and object is the number of the text object to be edited The char variable con tains the character to be inserted into the text string usually obtained by reading the keyboard and using the result as the input here The index variable does double duty As input it gives the routine the offset that tells it what place in the string is being edited When
43. cause AES won t amp If not full change to full amp else wind set wh WF CURRXYWH full g x full g y full g w full g h ww 488888 routine to handle window refresh WM_REDRAW message 33331911 refreshtwh drect int wh window handle from msgi33 amp GRECT f drect pointer to damage rectangle t GRECT wrect the current window rectangle in rect list x graf mouse M OFF 9L 18 turn off mouse wind update BEG UPDATE lock screen amp wind get get first rectangle wh WF FIRSTXYWH amp wrect g x amp wrect g y amp wrect g w S amp wrect g h while wrect g w amp amp wrect g_h 8 while not at last rectangle C if overlap drect amp wrect 7 check to see if this one s damaged set clip amp wrect if it is set clip rectangle display redraw and turn clip off amp vs_clip handle FALSE int amp 5 amp wrect gt wind get wh WF NEXTXYWH amp wrect g x amp wrect g y amp wrect g_w amp wrect g h 2 wind update END UPDATE unlock screen graf mouse M ON x L turn mouse pointer back on gt Routine to draw the window display 5 5t displayt int pointst423 VDI points array 207 CHAPTER 8 wind get msugL 32 WF WORKXYWH amp work g x amp work g y amp work g w amp work g h IX find work area clear rect amp work 3 IX and clear it amp
44. correct calling sequence In order to perform text editing the Library function form do calls objc_edit with the function type set to ED_INIT to display the cursor in the first field to be edited It then uses an evnt_multi call to read the keyboard among other things When a key is pressed it checks to see if it s one of the special keys such as the cursor or Tab keys used to change to the next text field If not the string is edited by call ing objc_edit with the type flag set to ED CHAR If the field to be edited is changed the cursor is turned off in the current field with the ED END function of objc edit and the whole process is repeated with the next field to be edited The final three basic object functions allow you to reorder the linkages in the object tree array without manually chang ing individual link fields They are most useful for dynami cally allocated object trees such as are used on the GEM 123 CHAPTER 4 Desktop program where it s not possible to determine ahead of time how many file icons will be needed in a window If you set up your object trees ahead of time by using a resource file as is usual you won t have to worry about these calls The first operation is objc_add which is used to add an ob ject as a child of a parent object int status parent child struct object tree status objc_add tree parent child where tree is a pointer to the object tree parent contain
45. event after a specified length of time Since most programs need to check for more than one type of event a function called evnt_multi is provided 53 CHAPTER 3 which may be used to wait for any combination of events In a typical GEM program the main program loop centers around an evnt multi call and the various routines that are used to handle the events returned by this call Message Events In order for a multitasking system such as GEM to be really effective there has to be a way for tasks to communicate with one another so that there s an orderly division of labor GEM provides a message system for intertask communication Each task has its own message pipe in which messages are stored in FIFO First In First Out order When a task asks for its messages the top one is taken from the pipe and moved to a buffer which the task designates The message pipe can hold up to eight 16 byte messages at a time When an applications wants to wait for a message it uses the eunt mesag call whose format is as follows int reserved msgbuf 8 reserved evnt_mesag msgbuf where the msgbuf array is a temporary storage buffer in which the 16 byte message is deposited The reserved variable is al ways equal to 1 The fact that a reserved variable is provided indicates that this function may return some significant value in the future If messages are already waiting in the message pipe the evnt_mesag call will retur
46. grect conv amp work amp points convert work grect to array vsf interior handle 2 set fill type to pattern vsf_etyle handle 7 amp msgf3J 2 adjust fill pattern t vsf color handle msgf3J 3 set color v ellipse handle points 9 work g_w 2 pointst 1J work g h 2 work g_w 2 work g_h 2 3 draw a filled ellipse amp 2 27222222 Utility routines used by other functions 4444444444444 amp set cl p r set clip to specified rectangle GRECT r int pointst41j grect conv r points vs clip handle TRUE points overlap ri r2 compute overlap of two rectangles amp SRECT rl tr2j int x yj x MAX r2 g x r1 g x j y MAX r2 dg_y rl gt g_y 3 r2 g MIN r2 g r2 g w rl g rl g w r2 g h s MIN r2 g y r2 g h rl gt g_y rl g h y3 r2 g 9 xj r2 g y yi returni r2 g Ww gt amp amp r2 g h gt j 3 redraw_msg wh r Send Redraw Message to your own window int wh GRECT r ct int nsgL8 J msgE9J WM REDRAW mggL1J gl apidj msgt2J 2 8 msgt3J why msgl4J3 r g xj asgt3J r g yj masgL J r g wj msg 7 r g hj appl write gl apid 16 amp msg H 18 gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt Some Handy Functions 444444444 X4444 4 8 clear rect r amp clear a rectangle to the backg
47. int in 3 int in 4 int in 5 int_in 6 int in 7 int_in 8 int_in 9 int in 10 int in 11 int in 12 int in 13 int in 14 int in 15 addr in 0 function returns The time period is set by the evnt dclick call The mouse buttons for which the applica tion is waiting 1 left mouse button 2 right mouse button 3 both mouse buttons The button state for which the application is waiting 0 both buttons up left button down right button up 2 right button down left button up 3 both buttons down A code which specifies whether the call is waiting for the mouse pointer to enter or leave the first mouse rectangle 0 waiting for mouse to enter rectangle 1 waiting for mouse to leave rectangle The left coordinate of the first mouse rec tangle in screen pixels The top coordinate of the first mouse rec tangle in screen pixels The width of the first mouse rectangle in screen pixels The height of the first mouse rectangle in screen pixels A code which specifies whether the call is waiting for the mouse pointer to enter or leave the second mouse rectangle 0 waiting for mouse to enter rectangle 1 waiting for mouse to leave rectangle The left coordinate of the second mouse rectangle in screen pixels The top coordinate of the second mouse rectangle in screen pixels The width of the second mouse rectangle in screen pixels The height of the re
48. longer work puzzling the user Therefore it s recommended that your program make periodic AES calls if only to keep the dispatcher working One harmless AES call that you can make is to evnt_timer specifying that your application wishes to wait for a period of zero milliseconds While tasks rotate through the Ready list in a fixed order tasks on the Not Ready list aren t arranged in any particular sequence When an awaited I O event occurs the task waiting for that event is removed from the Not Ready list and added to the bottom of the Ready list Another vital part of the AES is the Screen Manager The Screen Manager is a separate GEM task that shares processor time with the main application program To understand its function you must first realize that many of the user interface features of GEM require coopera tion between GEM and the application program in order to 6 Ott cb hd J e 4 UL L t 77 Co AM LLE oa GEM and the AES work Although most GEM applications share common user interface features such as menus and dialog boxes these fea tures prompt a unique response from each application GEM therefore provides for a division of labor between the AES and the application Since only the application knows what it wants to display it alone is held responsible for everything that goes on in the active topmost window The Screen Manager s job is to mon
49. maximum size window fullw int in 3 The maximum width of the window in pixels fullh int in 4 The maximum height of the window in 284 pixels x end J d dAd b ELLUL lo Lo LS OE KL wind create Results wi handle int out 0 A unique number in the range 0 8 used to identify the window Window handle number 0 is reserved for the Desktop win dow that s managed by the AES If eight windows are already open the maximum under the current version of GEM on the ST a negative value will be returned in dicating that no windows were available and the function failed to allocate a new window See also wind_delete wind open 285 wind open Display a Window wind open Opcode 101 Displays a window in its initial size and position C binding int status wi handle x y width height status wind_open wi_handle x y width height Inputs control 0 101 Opcode control 1 5 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out arra wi_handle int_in 0 The ID number of the window to be opened returned initially by wind create x int_in 1 The initial screen position of the window s left edge y int_in 2 The initial screen position of the window s top edge width int in 3 The initial width of the window
50. messages In an actual application your program would have to deal with all of the window messages as well Program 5 1 menul c Program k 59X Xx55951929222 25222525222529522222 2222 122 32229292225222222222222225252227 t 1 1 MENU1 C Demonstrates handling of simple menus x with keyboard equivalents a TAATTETATATAATSSAAATAAATSASASKATAKAAAASAAAAKEAAKASAATKSAAATEKATEL ATS define APP INFO define APP_ NAME Menu Example 1 define WDwW_ CTRLS NAME 4define MOUSE GFF graf mouse 256 amp dummy gt define MOUSE ON graf mouse 257 amp dummy define CTRLO x18111 keycode for CTRL Q key combo define FIKEY x3B keycode for function key 1 define F2KEY 9x3C200 keycode for function key 2 include aesshell c Hinclude menul h include file from RCS 144 b l LE LII L L L L L t 1 Le Resource Files and Menus int dummy OBJECT menutroee char falert demot int event done 93 int key msgt81 if rsrc load MENU1 RSC Load resource file form alert 3 LOl1tFatal ErroriCan t find MENUi RSC file ICAbortl return 8 Abort if it s not there gt get address of menu tree and alert string rsrc gaddr R_TREE MENUTREE amp menutree rarc gaddr R STRING ABTALERT amp alert MOUSE OFF Hide the mouse pointer menu bar menutree 1 Show the menu bar MOUSE ON
51. move 1 9 resv2 move 1 42 rasv3 move 1 2 resv4 move 19 ctr1d command appl init move 2 ctril no integer input parameters move 41 ctr12 1 integer output parameter move 49 ctr13 no address input parameters move 429 ctr14 no address Gutput parameters jer aes 4 do the call cmpi FFFF apid check to see if init failed g beq apperr and exit if it did 2 Get the physical screen device handle from graf handle move 477 ctr19 command graf handle move 43 ctr12 5 integer output parameters jer aes do the call move aintout pwkhnd save handle and char sizes move aintout 2 cellw move aintout 4 cellh move aintout 4 chboxw move aintout 8 chboxh move SFFFF wdwhnd show that no window is open sti Register our item on the Desk menu move wsS ctri1g command 2 menu register move 41 ctr11 1 integer input parameter mova 41 ctr12 1 integer output parameter move 4 1 ctr13 1 address input parameter move apid aintin application id move nenutxt addrin amp address of menu text item jsr aes move aintout menuid d ond a Lua wb al LL L Ee e d do L Desk Accessories Main accessory loop 253 mains move 23 ctr1d opcode evnt_mesage move 49 ctr11 move 81 ctr12 1 intout move 1 ctris 1 addrin move 2 ctrl4 move 1 msg addrin jer aes move 49 ctr13 jer msghand handle the
52. no error occurred during execution 245 menu tnormal Toggle Menu Title Highlight menu t normal Opcode 33 This function either displays a menu title in normal video or highlights it in reverse video It is most often used to return a menu title to normal video after the program has carried out an action in response to the selection of a menu item C binding int status title setting OBJECT tree status menu_tnormal tree title setting Inputs control 0 33 Opcode control 1 2 Number of 16 bit inputs in int_in array control 2 1 Number of 16 bit results in int_out array control 3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr out z array title int in 0 The object number of the menu title which is to be displayed normally or highlighted setting int in 1 A code which indicates whether the menu title should be highlighted in reverse video or displayed in normal video 0 display in reverse video 1 display in normal video tree addr_in 0 The address of the object tree array which supplies the data for the menu display Results status int out 0 Error status code an error occurred during execution gt 0 no error occurred during execution 246 d 3233 J ERE UL L L t C LCC L menu text Change Menu Item Text menu text Opcode 34 Changes the text of a menu item This allows me
53. points vs clip handle TRUE points 3 overlap r1 r2 compute overlap GRECT tri 5 r2 int x yj X MAX r2 g x r1 59g x y MAX r2 g y r1 9g y t set clip to specified rectangle of two rectangles s r2 g w MIN r2 g x r2 g w rl g x rl 5 g w x3 r2 g h MIN r2 g y r2 g h r1 g y ri g h y3 r2 g Xx xj r2 gt g_y yi returni r2 5 g w gt amp amp r2 g h gt 1 redraw_msg wh r Send Redraw Message to your own window amp int wh GRECT Br int msgtBJ msgt81 WM REDRAW msgL13 gl apidj msg 23 8 msgL51 wh msgC4 r g amsgL33J r g yj msgL6J r 5 g wj msg 7 r 5g i appl_write gl_apid 16 amp mnsg cd ab ud web sd J c d d al L L L LL L L L AES Events Program 3 2 is an abbreviated version of the same pro gram in machine language Program 3 2 message s ATHSKATATKAEKTT SKATERS ASRS SSA ASTS SASSER ASESS REE AAAETE AAS MESSAGE S Shows how to handle window messages FSS SSSS FSS SES ES SESE SES SESS SSS SE SSsSESE SESE SESE SSLE SESS SSF FFF oe ot tt 2x External references Export xdef demo external demo subroutine xdef wdwctrl xdef wdwtitl xdef wdwinfo Import xref vdi xref aes ref contrl2 all of the VDI data arrays xref contrii xref contr12 xref contri xref contr14 xref contrl15 xref contrl
54. relative position of horizontal slider 1 leftmost position 1000 rightmost 9 WF_VSLIDE x relative position of vertical slider 1 top position 1000 bottom 10 WF_TOP x window handle of the top ac tive window 14 WF_NEWDESK The address of an object tree to be used for the Desktop Window back ground x low word y high word of address width number of starting object to draw 15 WF_HSLSIZE x relative size of the horizontal slider compared to the scroll bar 1 minimum size 1 1000 percentage filled in tenths of 1 percent 16 WF_VSLSIZE x relative size of the vertical slider compared to the scroll bar 1 minimum size 1 1000 percentage filled in tenths of 1 percent Again the macro names are synonymous with the field numbers defined in the header file GEMDEFS H A status value of 0 indicates that an error has occurred while a value greater than 0 means no error As with wind_get some of the field types use fewer i in put parameters The two fields of interest here WF NAME and WF_INFO require only a pointer to a text string Since the pointer is a four byte long word it takes the place of both of the integer input values x and y The format used by both of these calls is include lt GEMDEFS H gt static char string Window Title int wi_handle wind_set wi_handle WF NAME string 0 0 J 3 J J J J 3 LL L tL p be C LCE Starting an Application
55. routine C binding There is no official C binding for this routine Therefore if you wish to call it from C you must either write a machine language function to call it write your own bindings or place the correct values into the global arrays directly and then call the crys_if 56 function which can be found in the regular bindings If you choose either of the latter two you must also change the values in entry 56 of the ctrl_cnts array which is in the regular bindings in the file GEMSTART S for the Alcyon compiler to dc b 2 2 1 func 56 Inputs control 0 56 Opcode control 1 2 Number of 16 bit inputs in int in array control 2 2 Number of 16 bit results in int_out array control3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out arra object int in 0 Number of the object clicked on clicks int in 1 Number of mouse button clicks received from evnt multi tree addr_in 0 The address of the object tree array which makes up the dialog box Results continue int_out 0 Flag for exit object selection 0 exit object selected 1 exit object not selected continue obj out int_out 1 Number of the new edit object See also form_do form keybd 267 This function draws a dotted box outline on the screen the upper left corner graf rubberbox Draw a Rubber Box graf rubberbox Opcode 70 of which is fixed but the lower right portion
56. s up Bit Bit Value Key 0 1 1 2 2 4 3 8 See also evnt_multi 232 Right Shift Left Shift Control Alt wk wh ue d d L 1 b LE Ks CEE evnt mouse Wait for Mouse Rectangle Event evnt mouse Opcode 22 This function waits for the mouse pointer to leave or enter a particular rec tangle on the display screen C binding int reserved mflag rectx recty rectw recth mousex mousey button shiftkey reserved evnt mouse mflag rectx recty rectw recth amp mousex amp mousey amp button amp shiftkey Inputs rectx recty recth Results reserved mousex mousey button shiftkey control 0 22 Opcode control 1 5 control 2 5 control 3 0 control 4 0 int in 0 int in 1 int in 2 int in 3 int Lin 4 int out 0 int out 1 int_out 2 int_out 3 int_out 4 Number of 16 bit inputs in int_in array Number of 16 bit results in int_out array Number of 32 bit inputs in addr_in array Number of 32 bit results in addr_out array A code which specifies whether the call is waiting for the mouse pointer to enter the rectangle or leave the rectangle 0 waiting for mouse to enter rectangle 1 waiting for mouse to leave rectangle The left coordinate of the rectangle in screen pixels The top coordinate of the rectangle in screen pixels The width of the rectangle in screen pixels The height of the rectangle
57. trap addq 1 addq mova jsr move beq Starting an Application 42 intin 20 intin 19 2 2 Raster Coordinates 84 ap push getrez command on stack 414 X call XBIOS 2 9p pop command off stack 42 d9 d intin use rez 2 as device ID vdi contrl vwkhnd save virtual workstation handle vwkerr end program if it s zero 99 Find max window size move move move mova jer move move mave move Create move move move move move move move move jer move bmi 184 ctr1 command wind get 2 ctrli 2 input integers H aintin window handle of Desktop 4 aintint2 WF_WORKXYWH command aes aintout 2 deskx store desk x y w h aintoutt 4 desky aintout deskw aintout 8 deskh a window with that max size 41929 ctr19 command wind create 45 ctr11 5 input integers 4 1 ctr12 1 ouput integer wdwctrl aintin window ctrl flag deskx aintin 2 max x desky aintin 4 max y deskw aintin 6 max width deskh aintin 8 max height aes aintout wdwhnd save window handle wdwerr if negative exit program zttk set window name move move move move move l jer 41023 ctr10 amp command wind set 6 ctril 6 input integers wdwhnd aintin window handle 2 aintint2 subcommand set window name 4wdwtitl aintin 4 amp point to title set info line move move 1 jer 3 aintint 2 amp s
58. vsf style msg d9 4 window number 7 d ax 7 42 d6 t 2 d2 intin pattern type vdi set fill color move move addq move jsr 25 contrid opcode for set fill color vsf color msg t de amp window number 431 d g d intin is color number vdi draw an ellipse 0 11 tt 1 J d gq 7l tL L L B a L Desk Accessories move nove move move move il contrid 43 contr15 42 contr11 49 contr13 48 contr14 workw d9 41 209 d9 ptsin 4 workx dd d9 ptsin wor kh d 41 09 d ptsint amp wor ky d d ptsin 2 vdi x x 2 9 9 99 99 99 9 99 9 94 opcode for GDP sub code for ellipse two points in ptsin take window width divide in half for horiz radius of circle add left x of window for center of circle take window height divide in half for vert radius of circle add top y of window for center of circle Close Virtual Screen Workstation subroutine v clsvwk elsvwks move move move jmp 191 contr1d 9 contrii 0 contr1s vdi opcode to contri 9 no points in ptsin no integers in intin gag Make AES function call get after setting parameters aes move 1 mGove w trap rts 1 Make VDI function call apb d1 aescode d 2 amp after setting parameters vdi move l MOVE W tra
59. 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also scrp_read 281 fsel input Display File Selector fsel_input Opcode 90 The File Selector is prepared dialog which displays a disk directory and ob tains a pathname and filename from the user The fsel input function dis plays this dialog monitors the user s interaction with it and returns the path and file names Note that the directory display is limited to 100 files in any directory After the user exits the file selector the AES sends a redraw mes sage to the application to repair the section of the window that was located under the selector dialog box Your program should be prepared to handle that message by repairing the damage fsel_input does to the display Also you should note that fsel_input changes the current VDI clipping rectan gle and doesn t change it back upon exit from the routine Therefore if your program does any VDI rendering after a call to fsel_input you ll probably have to set the clipping rectangle afterward whether you normally use clip ping or not C binding int status exitbutn char path 64 file 13 status fsel input path file amp exitbutn Inputs control 0 90 Opcode control 1 0 Number of 16 bit inputs in int zin array control2 2 Number of 16 bit results in int out array control 3 2 Number of 32 bit inputs in addr in array con
60. 1 left button down right button up 2 right button down left button up 3 both buttons down shiftkey int out 4 The status of the keyboard shift keys Each key is represented by a different bit A 1 in that bit position means that the key is down while a 0 means that it s up Bit Bit Value Key 0 1 Right Shift 1 2 Left Shift 2 4 Control 3 8 Alt See also evnt_button evnt multi 279 scrp read Read Scrap Directory scrp read Opcode 80 By GEM convention a disk may be used for a clipboard function to save data the user selects for a CUT or COPY operation The program writes this data to disk in a file called SCRAP This file may have any of several file name extensions TXT DIF IMG and so on depending on the type of data it contains such as text graphics or spreadsheet data So that other programs may share this data when the program writes the file to disk it gives the AES the pathname of the directory where the file resides by using the scrp_write function When another program wishes to use that data it finds the directory by using scrp_read C binding int status char path 128 status scrp read path Inputs control 0 80 Opcode control 1 0 Number of 16 bit inputs in int Lin array contro2 1 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array addr_in 0
61. 1 2 Left Shift 2 4 Control 3 8 Alt 89 CHAPTER 3 Thus if kstate contains a 4 the Control key was held down when the mouse button was pressed and if it has a value of 12 both Alt and Control were held The final two values that eunt button returns are the coordinates of the mouse pointer at the time the button was pressed Its horizon tal position is returned in mousex and the vertical position in mousey As of this writing there s a serious bug in the evnt_button routine in the TOS ROMs If the mouse pointer is moved into the menu bar while your program is waiting for a mouse button event the machine will lock up The problem would also occur under similar circumstances if you use the eunt_multi call to await a mouse button event There s no way to avoid this problem except to use polling techniques described below rather than waiting for mouse button events Mouse Rectangle Events When the AES waits for a mouse rectangle event it watches the mouse pointer s position and informs you when the pointer enters or leaves a designated area on the screen This elegant system eliminates the need for your program to keep checking the mouse pointer s position To wait for a mouse rectangle event you call eunt mouse in the following format int reserved mflag rectx recty rectw recth mousex mousey button kstate reserved evnt mouse mflag rectx recty rectw recth amp mousex amp mousey amp button a
62. 11 OTHERBOX 12 CANBUTN 16 OKBUTN 17 MENUTREE 1 SURVITEM 16 GUITITEM 17 form dialog FTEXT in tree DIALTREE BUTTON BUTTON BUTTON BOX in BOX in BOX in BOX in BUTTON BUTTON in tree DIALTREE in tree DIALTREE in tree DIALTREE tree DIALTREE tree DIALTREE amp tree DIALTREE tree DIALTREE in tree DIALTREE in tree DIALTREE menu tree STRING STRING in tree MENUTREE in tree MENUTREE x x x x BA x 19 9x09019 x 1 1 9x9219 9x903591 QxOOBD 0x90290 9x0501 8x 9989 0 8914 Ox JIB Sx BOCs 9x991C 90x900901 x F Y x 1C x 1 x 123 9x90901C 9 9090901 9x9014D 2x90901C 90x09091 x11 x 1C x 1 90 9185 9 3I56 9x9001B 9x20000 x S Ix xB x 4 Ox BOOS Ox ZOOS 0x0000 Ox BOSS Ox BIBS 9x909028 x Ox DOBD x ZJA Ox BISO Ox BIOS Bx BVOC 9x0000 x X E x BODD rxr Ox BOOS 9x9 098 Ox BIOS x F Ox BWSO 319 Program C 3 dialog2 dat 5 amp 5 55k 325415259934 25 3 23595532 2 2324 2 2523552525 a amp DIALQS2 DAT t Data for dialog2 rsc t include with RSCBUILD C amp amp STHAERTACAKCAAAAAATA TATA TATE AAAA AAAS define FILENAME 4define FILELEN 419L int rscdatat205 9x90001 x SA x
63. 3 The handle of the window whose horizontal slider was dragged 4 The requested position for the left edge of the slider a number from 0 to 1000 where 0 far left 1000 far right The user dragging the vertical slider generates message 26 WM_VSLID 81 CHAPTER 3 Word Number Contents 0 26 WM_VSLID the message ID number 3 The handle of the window whose vertical slider was dragged 4 The requested position for the top edge of the slider a number from 0 to 1000 where 0 top 1000 bottom Since the number returned in msgbuf 4 is in the proper format you may want to pass the new setting on to wind set unchanged wind set msgbuf 3 WF_VSLIDE msgbuf 4 0 0 0 If the display is comprised of indivisible logical units however you ll want to round the movement of the slider to the nearest such unit If the window display shows lines of text for example you ll want to scroll the display by an even number of text characters One easy way of rounding is to find the window start position that corresponds to slider position and convert that start position back to a slider position How to calculate the window start position will be discussed under the section on refreshing the window display later in this chapter When any of the other events associated with slide bars occurs the Screen Manager sends message 24 WM ARROWED Word Number Contents 0 24 WM ARROWED the message ID number 3 The ha
64. 8 WF HSLIDE x relative position of horizontal slider 1 leftmost position 1000 rightmost 9 WF VSLIDE x relative position of vertical slider 1 top position 1000 bottom 10 WF_TOP x window handle of the top active window 11 WF_FIRSTXYWH Coordinates of the first rectangle in the window s rectangle list 29 CHAPTER 2 Flag Macro Name Information Requested 12 WF NEXTXYWH Coordinates of the next rectangle in the window s rectangle list 13 WF_RESVD Reserved for future use 15 WF_HSLSIZE x relative size of the horizontal slider compared to the scroll bar 1 mini mum size 1 1000 percentage filled in tenths of 1 percent 16 WF_VSLSIZE x relative size of the vertical slider compared to the scroll bar 1 mini mum size 1 1000 percentage filled in tenths of 1 percent 17 WF_SCREEN Address and length of the menu alert buffers x low word of address y high word width low word of length height high word Each of the values for flag has a C macro name that s re lated to its function These macros are defined in the header file GEMDEFS H which is included with most C compilers The flags under consideration here are the ones that return the win dow size These include WF_WORKXYWH WF_CURRXYWH WF_FULLXYWH and WF_PREVXYWH When any of these flags except WE_WORKXYWH is used the function returns the size of the exterior outline of the window This includes the border and any
65. G TITLE The last type of string object is the G TITLE This is a string object which is specially formatted for use in the title bar of menus Its special formatting insures that the menus are redrawn correctly Formatted Text Objects The next group of text objects GL TEXT G_BOXTEXT G_FTEXT and G_FBOXTEXT are a little bit fancier than the previously mentioned string objects All of these objects allow you to select normal or small text different text colors and horizontally justified type In addition two of them allow you to specify ways the user will be able to edit the text string G TEXT and G_BOXTEXT The first two G TEXT and G_BOXTEXT are just fancier versions of the G STRING and G BUTTON types G TEXT is a colored text string while B_BOXTEXT is a formatted text string surrounded by a border These object types can be used in place of the simpler string objects when you want to use a text color other than black a smaller text font size or if you need horizontal positioning to take place when the program executes Since they require more memory than the G STRING and B BUTTON types and because too much color can distract the user you should exercise discretion in the use of these object types 107 CHAPTER 4 G_FTEXT and G_FBOXTEXT G_FTEXT and G_FBOXTEXT are editable versions of G_TEXT and G BOXTEXT This doesn t mean that they re inherently edit able Rather it means that you supply enough information abou
66. If your program handles those messages already then the redraw will be more or less automatic You should make certain that the screen rectangle that you describe in the form dial FMD FINISH call really covers all of your dialog box The x y width and height values re turned by form center allow for the OUTLINED state which is the default for the root object of dialog boxes created with the resource construction programs But it doesn t take outside borders into consideration If you have a thick exterior 163 CHAPTER 6 border you may need to extend the size of the rectangle you describe in form dial FMD FINISH Note however that form dial FMD FINISH always sends redraw messages for an area two pixels wider and higher than the one specified which means that you don t have to allow for the drop shadow under SHADOWED objects Although form dial FMD FINISH was designed for dia log handling you may use it any time you wish to force a re draw This method is much handier than using the message pipe to send a redraw message directly since the AES figures out which windows should get the message and sends them automatically In addition this call forces the AES to redraw the Desktop window in those areas not covered by application windows Since more work is involved this method is a bit slower than sending the redraw messages directly Once your program has exited the dialog there are still some tasks left to perf
67. L L L LE The Graphics Library setpt2 cmp bes move move bra setpt3 move move cmp bhi move bra setpt4 cmp bcs move move bra setpts move move satpt jmp bottom d1 setpt3 84 d7 bottom aintin 12 setpt thirdw aintin 14 top aintin 12 left do setpt4 45 d7 setpt right d9 setpt5 6 d7 right aintin 16 setpto 255 d7 left aintin i setform if below center box set to open hand next 3 all are 1 35 window wide and y is at top if at left of center box set to thin cross hairs if at right of center box set to thick cross hairs if in center box set to custom pointer shape Storage space and data constants wdwtitl wdwinfo wdwctr1 pointer 16 words of color mask data 7DCO 3FEO SiFFS 3FFC 1FFF S FFF S FC 2078 dS w dS w ds w GS W ds w ds w dS W im pe jo je je pes C dc b Mouse Pointer Demonstration dc b Click close box to end 9 dc w 19 dc w 9 9 1 dc w 9 1 dc w FO090 SFS dc w 1FF0 1FF8 dc w 7FFE 3FFF dc w 97FF 01FE 16 words of image data dc w SCEO 7000 dc w 0E20 0410 dc w 2084 1192 dc w 0302 9984 buffer for message event text of window title text of window info line window control flag x and y of hot spot background and foreground pens 1989 iD4g 0028 1148 SAADI 0401 0048 00
68. L LE AES Events Figure 3 1 Some Window Rectangle Possibilities for a Two Window Screen Rectangle 1 i of Window 82 Rectangle 81 of Window 2 R Rectangle 81 n i of Winden 2 and size of the next rectangle of the list When either type of wind get command returns a rectangle with a width and height of 0 you ve reached the end of the list Now that you know what the rectangle list is here is how to use it in your window refresh procedure The next step is to get the first rectangle in the window s rectangle list with the wind get call wind get wi handle WF FIRSTXYWH amp wrec g_x amp wrec g y amp wrec g_w amp wrec g_h Now that you have the position and size of the damage rectangle and the position and size of the first window rectan gle you must check to see if the two rectangles overlap any where If they do this third overlap rectangle marks the area whose display must be updated Figuring out the overlap area is fairly simple The x posi tion is equal to the greater of the two values of the original two rectangles and the y position is equal to the greater of the two original y values To find the width you first find the lesser of the two x width values and then subtract this fig ure from the overlap x To find the height you take the lesser of the two y height values and subtract it from the overlap 59 CHAPTER 3 y In C code the process of f
69. Not Ready list until certain I O events Occur mouse button press mouse movement keypress timer expiration or message events and to pass information about the events back to the application once they do occur Menu Library The routines in this library allow the application to establish and maintain drop down menus Object Library This library contains routines that allow the program to interact with various types of GEM objects GEM objects are data structures that form the basic building blocks of icons menus dialog boxes and alert boxes Form Library This library contains routines that allow the application to display and handle dialog and alert boxes Graphics Library The routines in this library perform some graphics functions mainly related to managing box out lines as they appear on the Desktop and some low level I O functions Scrap Library The functions in this library are used to read and write data to clipboard files on disk Clipboard files store data for interchange among applications File Selector Library This library contains a single rou tine that displays and manages the standard file selection dialog Window Library This library contains routines that sup port the creation and management of overlapping windows Resource Library The functions in this library enable the oo 0 1 54d Jil E J Aad d O L _ L I ET GEM and the AES application to load and use the object
70. Numeric digits 0 9 upper and lowercase alphabetic char acters and the space character All valid DOS pathname characters including the colon and backslash Uppercase alphabetic characters and the space character Numeric digits 0 9 uppercase alphabetic characters and the space character All valid DOS filename characters including the colon and wildcard characters question mark and asterisk All valid DOS pathname characters including the colon the backslash and wildcard characters question mark and asterisk X Any character d Uu ZZ 3 In the telephone number example you would use a vali dation string of 9999999999 since you only want to allow the user to enter a number in the blanks The next field in the TEDINFO structure is te font This field allows you to select the normal sized system font that s used to draw menu items or the small sized font that s used to draw the text under the icons on the Desktop A value of 3 se lects the normal text font while a value of 5 selects the small text font The next field te resud1 is reserved for future use After that comes te just which contains a flag indicating the type of horizontal text justification used A value of 0 selects 109 CHAPTER 4 left justified text a value of 1 selects text that is right justified A value of 2 indicates that the text should be centered The te _color field is a word of bit flags that identif
71. Other Zd7Z computersr51 v gtext handle left top scellh buf sprintf buf Others include Zs lastxt v gtext handle left topt cellh buf 167 CHAPTER 6 sprintf buf Ages v gtext handle left oe buf sprintf buf N 3 vigtext handle left top scellh buf sprintf buf Under 16 d agest223 v gtext handle left top ccellh buf sprintf buf 16 39 Zd ages 123 v_gtext handle left topt cellh buf sprintf buf Over 39 4d agesf 2 vigtext handle left topt cellh buf 18 gt gt gt gt gt gt gt gt Utility routines used by other functions 4 4444444 4444 44 amp set clip r set clip to specified rectangle GRECT r int points 4 grect_convir points vs clipthandle TRUE points 3 everlap ri r2 compute overlap af two rectangles amp GRECT trl amp r2j int x yj x MAX r2 g x r1 5 g x y MAX r2 5g y r1 g y r2 g w MIN r2 g x r2 5g Ww rl 5 g x ri g w xi r2 g h MIN r2 gt g_y r2 g h ri gt g_y ri g h yj r2 g X xj r2 gt g_y yj returni r2 g w gt amp amp r2 gt g_h gt 1 LX EERE EREREAAREKERK End of Dialogi c 92 522 9529 292 In order to run this program it s first necessary to create the resource file DIALOGI RSC This file contains two object trees a dialog tree c
72. Rectangle graf watchbox Opcode 75 This function follows the mouse pointer as it moves in and out of a specified object rectangle so long as the user holds down the left mouse button The caller may specify that the object changes state when the mouse pointer moves on or off of it and the function will redraw the object each time the state change occurs When the left mouse button is released the function ends and it returns a code indicating whether the mouse pointer ended up within the object rectangle or outside It should only be called when the program has determined that the left mouse button is already down by re turns from form do evnt multi or evnt button If it s up the func tion will end as soon as it s called This function is used internally by form do to handle object selection C binding int in or out object instate outstate OBJECT tree in or out graf_watchbox tree object instate outstate Inputs control 0 75 Opcode control l 4 Number of 16 bit inputs in int_in array control 2 1 Number of 16 bit results in int_out array control 3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array reserved int in 0 Reserved for future use object int in 1 The number array index of the object to watch instate int Lin 2 The ob state flag setting of the object when the mouse pointer with button down is inside of its rectangle
73. ST itself As you ll see later size and position information are stored within resources as character positions and are translated to display specific figures automatically when the resource is loaded much as was done manually in the example program in the last chapter Another advantage is that the programmer can experi ment with the size placement and characteristics of objects without having to recompile each time All you have to do is edit the resource file and run the program to see how the changes work Finally the use of resource files makes it easy to create foreign language versions of your program without recompil ing In fact since the user can edit the resource file the lan guage in menus dialog boxes and alerts may be changed without any need for programming experience This makes it possible for the program to be customized by the user For these reasons it s generally preferable to use resource files even if for some reason you think it would be more conven ient to create the object trees within the source code of the program itself Resource Construction Programs Not every C compiler or assembler for the ST comes with a resource construction program but no GEM programmer should be without one The original Resource Construction Set RCS is included with the ST Developers Kit available from Atari along with the Alcyon C compiler The Megamax C compiler package in cludes the Megamax Resource Construction Pro
74. address of your object drawing code in its ub code field Note also that the object drawing code drawcode only has to draw the outline of the ellipse once It uses pb currstate and pb_prevstate to find out whether the code is being called from objc_draw or objc_change If both fields are the same objc_draw was called and the ellipse is drawn If not only the filled ellipse routine is called The filled ellipse routine de termines whether the circle is blacked in Graf_watchbox is the last of the box graphics routines that should be called when the mouse button is first pressed down This routine simply watches the mouse pointer position while the button is held down and reports whether it ends up inside or outside of a particular object rectangle when the user lets the button up The graf_watchbox routine is called by form do to insure that the user in order to select an object has both pressed the mouse button while the pointer was over an object and then let the button up while the pointer was still over that object The most likely use that an applications pro grammer would make of this routine would be in writing his or her own form do routine The syntax for this call is int in Lor out object instate outstate OBJECT tree in or out graf watchbox tree object instate outstate where free is a pointer to the object tree and object is the num ber of the objects whose rectangle you wish to check Th
75. amp boxw amp boxh The physical screen handle is returned in phys handle Before making the v_opnvwk call phys handle should be stored in the variable handle In addition to the the physical screen handle graf handle returns some interesting infor mation about the size of the default system text font used in menus and dialog boxes The width and height of the charac ter cell are returned in cellw and cellh The character cell is the entire space taken up by each character including the inter character spacing The width and height of a box that sur rounds the text cell are returned in chboxw and chboxh The chboxw and chboxh measurements are significant because many GEM Objects are scaled to these sizes For example the window controls such as the title bar close box size box and scroll bars are chboxw wide and chboxh tall Opening a Window The next step in setting up an application is to open an output window Windows are an integral part of the GEM user inter face They are used to divide a single display screen into sepa rate sometimes overlapping sections each surrounded by a visible border This makes it possible for a single application to present several distinct types of information on the same screen For example a program could display help information in one window and data in another Windows also facilitate sharing the display between the application and one or more desk accessories 23 CHAPTER 2 T
76. amp nslide amp nslide amp nslide temp 1000 ttop TROWS SROWS if nslide temp s cslide wind set wi handle WF VSLIDE nslide 9 w gt gt gt gt gt gt gt gt Utility routines used by other functions 4444444444444 amp set _clip r set clip to specified rectangle GRECT r int po ntsL4 3 grect_conv r points vs_clip handle TRUE points overlap ri r2 t compute overlap of two rectangles t GRECT tri r2 int x y x1 ylj x MAX r2 g x ri gt g_x 3 y MAX r2 gt 9_y rl gt g_y r2 g w MIN r2 gt 9_x r2 g Ww ri gt g_x rl gt g w xj r2 g h MIN r2 g y r2 5 g h ri gt g y ri gt g_h y r2 9 xX x r2 gt g_y Y returni r2 g w gt amp amp r2 g h gt 3 Notice that the window display was updated by printing each line of text one after the other using the v_gtext rou tine This process is fairly quick as long as you keep the text aligned on byte boundaries When speed is important how ever you ll want to update a scrolled display by moving the block whose contents remain valid with the VDI raster routine vro cpyfm and then filling in the new data In some cases you may even wish to keep an entire copy of the window s contents stored offscreen in a memory buffer area Then when you want to refresh the window you only have to move the relevant portion of that information using vro
77. appl find Find Application ID appl_find Opcode 13 _ Finds the application ID number of a named application that is currently running in the system The ID number may be used to establish communica tions with this application via the message pipe char name 8 id appl_find name Inputs control 13 Opcode control 1 0 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int_out array control3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array name addr in 0 Address of text string containing the name of the application to be found This text string must contain exactly eight text char acters followed by the NULL ASCII 0 character If the name of the application contains fewer than eight characters spaces must be added to the end of the name to pad it to eight characters Results ap id int out 0 The application ID number of the applica tion that was named If the application is not currently loaded 1 is returned Note It has been reported that sometimes this function will return a valid ID number even after the application requested has been closed See also appL_write appl_init Jt 4 Joo d L L LL LL LO L appL tplay Playback Mouse and Key Macro appl tplay Opcode 14 Plays a recording that has been made of the user s mouse and keyboard in put This function does not
78. bar at the top of the screen The second called the SCREEN is a G_IBOX that covers the rest of the display area excluding the menu bar The BAR and the ACTIVE The BAR is 80 characters wide and is one character plus two pixels high It contains ex actly one child a G_IBOX called the ACTIVE The ACTIVE covers only the portion of the menu bar that actually contains menu title objects It takes its name from the fact that the 140 eb tx 3d d f 1 l i i i NEM Le Ru due De a L L UL Resource Files and Menus Screen Manager activates a menu whenever the mouse pointer enters its rectangle The ACTIVE has as its offspring the vari ous G TITLE objects that represent the menu titles These ob jects should line up side to side and completely cover the ACTIVE The SCREEN The other child of the root object the SCREEN is the parent of the box objects which contain the drop down menus that appear under the menu titles Each drop down is a separate G_BOX child of the SCREEN No single drop down box can be larger than one quarter of the screen display in size since that s the size of the offscreen buffer where the AES temporarily stores what s in the screen display behind the menu The drop down boxes each contain a number of objects usually G_STRINGS that represent the individual menu items These objects should completely cover the drop down s rectangle Because of the rigid hierarchy requirements of
79. bit block int bi pdata pointer to bit image data array int bi wb width of bit image in bytes int bi hi height of bit image in scan lines int bi x Image X offset from start of data block int bi y Image Y offset from start of data block int bi color foreground color of image BITBLK 110 E d dJ J J Jd Le Ss CEC GEM Graphics Objects The bi_pdata field contains a pointer to the bit image data ar ray This array must be composed of 16 bit words Therefore the image s width in pixels must be an even multiple of 16 The bit image data uses a simple coding scheme where each bit repre sents a pixel set to the foreground color 1 or the background color 0 The next field bi wb gives the width of the bit image in bytes Since the data array is composed of words this field must always contain an even number The bi il field contains the height of the bit image in scan lines The fields bi_x and bi y allow you to specify an x and y offset from the beginning of the image data array This allows you to use only a portion of the im age data for the object s bit image The last field bi color allows you to select the color used to draw pixels that represent the bits that are set to 1 Although the image itself is all the same color this color need not be restricted to black Any color register from 0 to 15 is valid although in medium and high resolutions out of
80. bits in the 16 X 16 block are transparent don t replace existing back ground with a new color or opaque replace existing back ground with the pointer background color It also includes the coordinates of the pointer s hot spot or action point The hot spot is the single pixel which is considered to be the pointer s location on the screen even though the pointer may be much larger than a single point On the arrow shaped pointer for example the hot spot is located at the very tip of the arrow If you click on an icon with the tail of the arrow rather than with the point nothing will happen On the bee shaped pointer the hot spot is at the center of the image The layout of the mouse form definition data structure is as follows Element Meaning 0 x position of hot spot 1 y position of hot spot 2 Number of bit planes must be set to 1 3 Background color normally 0 4 Foreground color normally 1 5 20 16 words of color mask data 21 36 16 words of image data 188 al wd E Siok nl JJ L L CL The Graphics Library The x and y coordinates of the hot spot are measured as an offset from the top left corner of the 16 x 16 pixel block The image data block is laid out so that each line of the image is represented by one 16 bit word with the most significant bit of the word representing the leftmost dot and the least sig nificant bit representing the rightmost dot Each bit position tha
81. box 25 66 fuller box See full box GB GEM Base 14 G BOXTEXT 107 G_BUTTON 107 GEM Graphics Environment Manager 3 17 initializing application 21 registering an application 21 starting an application 21 GEM bindings 16 17 97 128 142 calling routines from C 16 17 conventions 142 graphic objects 97 128 GEMDOS 4 156 57 conversion table to PC DOS 156 57 getrez 22 G FBOXTEXT 108 G_FTEXT 108 G_ICON 111 13 global array 10 11 G PROGDEF 113 graf_mouse 50 57 61 187 88 form numbers macro names table 188 Graphics Environment Manager See GEM graphics interface 3 Graphics Library 8 graphics primitives 4 G STRING 107 G_TEXT 107 G TITLE 107 G_USERDEF See G_PROGDEF handle 60 happened 92 HEAD link field 99 HIDETREE 142 horizontal and or vertical slide bars 25 hot spot 188 HSLIDE 78 ICONBLK 111 12 ib char 112 ib_character 112 13 ib_hicon 112 ib_htext 112 ib_pdata 112 ib_pmask 112 ib_ptext 112 ib_wicon 112 ib_wtext 112 ib_xchar 112 ib_xicon 112 ib_xtext 112 ib_ychar 112 ib yicon 112 ib_ytext 112 icons 111 13 image mask 111 information line 25 327 input array 22 input parameter arrays 12 integer data type int See short kernel 5 keyboard events 91 K Resource KRSC 132 LFARROW 78 Line A graphics routines 4 5 machine language AES calls 12 14 macro definitions 55 Megamax C compiler 17 132 Megamax Resource Construction Program MMRCP 132 Menu Alert Buffer 9 menu bar 24 Menu Library 8 menus 140
82. but in medium resolution they appear to be tall and skinny There are several ways to deal with this problem First you can try to make your resource display independent when you create it by keeping object widths smaller than forty characters and using compromise images that are a little shorter and fatter in high resolution than you d normally make them and a little taller and skinnier in medium resolution The second approach is to create separate resource files for the different resolutions To some extent this goes against the basic philosophy of compatibility behind the resource files A third alternative is to place extra image and icon data in the resource and patch the appropriate data into the data struc tures whenever the program comes up in a display resolution mode for which the object trees weren t designed In this last case you might find the rsrc_gaddr and rsrc_saddr calls handy You can use rsrc_gaddr to find the addresses of the alternate data structures and rsrc_saddr to patch them into the existing ones 139 CHAPTER 5 Menus One of GEM s most helpful features is its system of drop down menus These menus are composed of objects whose tree is usually loaded as part of the resource file Once the application installs the menu the menu titles which display the broad categories of selections available appear in the menu bar at the top of the screen When the user moves the mouse pointer over one
83. children of the root object Each of these objects may contain their own smaller child objects The root object like all other objects contains three link age fields at the beginning of its data structure These fields are called ob next ob head and ob tail The NEXT field con tains the object number of the next object which is a child of the same parent as the current object such objects are known as siblings Since the root object by definition has no parent it can have no siblings Therefore its NEXT field contains a 1 which means that there s no link in this direction For objects which do have siblings the NEXT field of each contains the 98 J WR Lp xg ej GEM Graphics Objects object number of the next sibling The last sibling at a particu lar level contains the object number of the parent in its NEXT field If an object has children the root object nearly always has children the HEAD link field contains the object number of the first child and the TAIL field contains the object num ber of the last child To better understand how object trees work it would be use ful to examine one Figure 4 1 shows a sample GEM dialog box This box is made up of seven objects The root object is the G BOX that surrounds all of the other objects which we ll call DIALBOX Object 1 OKBUTTON is the box labeled OK Its sib ling Object 2 PATBOX is the pattern filled box that holds the rest of the objects Its two ch
84. code for the assembler shell program is about twice as long as that of the C shell program But depending on what compiler you use the executable program generated by the as sembler version is at least 50 percent smaller than the C pro gram In order to reduce the size of the assembler source code a number of shortcuts were used Since you know the contents of the AES data arrays like ctrl the name given to the control array at any given time you don t need to fill each member for each function call For example since the input parameters for the graf mouse call used to change the mouse form to an arrow are almost exactly the same as the ones used for the graf_mouse call that turns the mouse back on the only in put variable that is changed between the two calls is aintin the name given to the first element of the int_in array oo _ M 0 6d J use Chapter 3 AES Events Windows Part 2 f LLL LL In older single tasking microcomputer systems it s common for a program to check for input from the user by polling the input devices That means the program sits in a loop continuously checking the device until something hap pens It s sort of like having a telephone without a bell you have to pick it up every few seconds in order not to miss any calls In a single tasking system this kind of programming is appropriate since the processor literally doesn t have anything els
85. d ad ub x c4 a L t L L tt 0t EL GEM Graphics Objects This function draws the object tree whose address is con tained in the pointer tree starting with the object whose index number is in firstob and going down as many generations as specified in the depth variable If you want the whole tree drawn you may use ROOT defined as 0 for firstob and MAX DEPTH defined as 8 in OBDEFS H as the depth vari able This function also allows you to specify a clipping rectan gle whose position and size are given in clipx clipy clipw and cliph Only those portions of objects which are contained within the clipping rectangle will be drawn As explained in connection with window refresh this clipping function can be very handy for redraws of objects contained within windows The error status of the routine is returned in the status vari able As with all of these routines a status of 0 indicates that an error occurred while a positive integer indicates that there was no error Another basic function is used to find the index number of the object located at a certain x y coordinate on the screen This is handy for determining whether the mouse pointer is positioned over an object when the user presses the button This function is called objc_find and its syntax is as follows int foundob firstob depth x y struct object tree foundob objc_find tree firstob depth x y where tree is a pointer to the t
86. exit application cleanup terror int error switch error t Perform as much cleanup as is warranted by the error level Each higher level falls through to subsequent lower levels t case NO_ERR if no error close window wind close wi handle wind deletet wi handle case WDW ERR It couldn t create window close workstation v_cisvwk handle case VWK_ERR If workstation didn t open exit app appl exitt case APP ERR IX if appl init failed exit immediately x J gt 18 2255225222222 5 5 52 5 Some Handy Functions lt lt lt lt lt lt cence sseeec lt K clear rect r clear a rectangle to the background color GRECT tr int pointst41 vsf interiort handle 42 grect_convir amp points vr _recfl handle points 38 J o d x b ow ud c ud 0t L t LL Ci LA E mM Starting an Application grect conv r array convert grect to an array of points amp GRECT tr int array arraytt t r gt g xj Sarray r g yj arraytt r 5 g x r g Ww 1j array r g y r gt g_h i 2 This program is divided into three parts The first init all registers the GEM application opens a Virtual Screen Workstation for possible VDI calls and then creates and opens a window It uses the VDI function vr recfl dis cussed in Volume 1 of this series to clear the work area of the window And
87. filename Inputs control 0 110 Opcode control 1 0 Number of 16 bit inputs in int_in array control 2 1 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array filename addr_in 0 The address of a null terminated text string which contains the path and file name of the resource file to load Results status int_out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also rsrc_gaddr rsrc_saddr rsrc_obfix 297 rsrc free Unload a Resource File rsrc free Opcode 111 This function frees the memory space allocated for the resource file by the rsrc_load call It should be used by an application before loading a re placement resource file and before calling appl_exit to notify the AES that the application is about to terminate C binding int status status rsrc_free Inputs control 0 111 Opcode controli 0 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also rsrc_load 298 t VP uy d L ree EM EWEVEK d
88. form error 53 155 57 263 64 form center 54 161 265 form keybd 55 266 form butn 56 267 grat rubberbox 70 179 80 268 graf_dragbox 71 180 269 70 graf_mbox 72 186 271 graf_growbox 73 186 87 272 graf_shrinkbox 74 186 87 273 graf_watchbox 75 185 86 274 graf_slidebox 76 180 81 275 graf_handle 77 21 276 graf_mouse 78 39 50 57 61 187 88 277 78 graf_mkstate 79 196 97 279 scrp_read 80 280 scrp_write 81 281 fsel_input 90 170 72 282 83 324 d J ee iL t ft LL b RE Li L Function wind create wind open wind close wind delete wind get wind_set wind find wind_update wind calc rsrc_load rsrc_free rsrc_gaddr rsrc_saddr rsrc_obfix shel_read shel_write shel_find shel_envrn Opcode Number 100 101 102 103 104 105 106 107 108 110 111 112 113 114 120 121 124 125 Page 26 28 35 284 85 27 31 33 286 34 35 287 35 288 29 58 289 90 31 33 291 92 293 57 61 294 34 65 295 96 135 36 161 297 136 298 136 37 158 161 299 300 138 39 301 2 138 303 304 305 6 307 308 325 Index AC CLOSE 203 action point See hot spot ACTIVE 140 41 active window 58 AES Event Library 53 AES Graphics Library 8 9 179 97 calling routines from C 16 17 data arrays 10 graf mouse 187 machine language programming 12 14 rectangle list 5
89. get a filename from the user For purposes of brevity this program simply clears the screen when it gets the WM_REFRESH message In your own program you would want to include an entire message handling system that would take care of menu mes sages window topping messages refresh messages and so on Program 6 2 fselect c ETCSTAKTSAKSEKASAKAAKAAKASTEAKAKEAAAASASASACASAEAKAALAKAALATAALTAASTTAT x FSELECT C Demonstrates the use of the File b Selector routine to obtain the pathname of a file amp s 7 EKTATATESATALKAAASSAKEATSATAATALASSSE CATALASE SSAAALETATLRASKAKATTS 4define APP INFO xx Click on the Close Box to exit the program Sdefine APP NAME File Selector Demo define WDW CTRLS NAME CLOSER INFO 172 t 4 M jJ dt EEE d UUUM an C LLC Interactive Object Handling include aesshell c char file 641 IX buffer for name of file selected char pathL64 buffer for search path t char filespec 892 1 buffer for full pathname of file demo C int msg 83 int button 2 patht2JsDgetdrv 0 A amp Get the drive name path 122 1 Dgetpath file 9 and current directory path amp strcat path file fileL 93J 9 3 IX no initial file name strcat path NXX set initial path fsel input path file amp button get file name amp evnt mesage amp msg get the window redraw
90. however offer a more sophisticated class of input output operations which are com monly grouped together under the term graphics interface Computers that offer such an interface allow users to operate programs by manipulating graphics objects on the display screen with a pointing device known as a mouse rather than requiring them to type in carefully worded commands GEM an acronym for Graphics Environment Manager was designed to provide this graphics interface An additional level of system routines it sits on top of the low level input output functions furnished by the computer s own op erating system Because GEM supplements rather than re places the existing operating system it s possible to write old style computer programs on the ST that take text input from the keyboard without using GEM at all These are called TOS Tramiel Operating System programs TOS programs don t take full advantage of the capabilities of the ST GEM programs are easier to operate because of their vi sual orientation as the old saying goes One picture is worth a thousand words Anyone who s ever taken out the garbage should be able to understand the effect of dragging a file on the Desktop Moreover GEM provides a consistent context for program operation Users of GEM programs who want to learn what the various program options are know that they can always find the menu selection on the menu bar at the top of the screen Other stand
91. in array Number of 16 bit results in int out array Number of 32 bit inputs in addr_in array Number of 32 bit results in addr_out array The ID number of the window about which information is to be provided A code indicating the type of information requested Valid numbers include Information Requested Window work area coordinates Window exterior coordinates Previous window exterior coordinates Maximum window exterior coordinates x relative position of horizontal slider 1 leftmost position 1000 rightmost y relative position of vertical slider 1 top position 1000 bottom x window handle of the top active window Coordinates of the first rectangle in the win dow s rectangle list Coordinates of the next rectangle in the win dow s rectangle list Reserved for future use x relative size of the horizontal slider com pared to the scroll bar C1 minimum size 1 1000 percentage filled in tenths of a percent y relative size of the vertical slider compared to the scroll bar 1 minimum size 1 1000 percentage filled in tenths of a percent Address and length of the menu alert buffers x low word of address y high word width low word of length height high word 289 wind get Results Except where noted above in the description of the flag variable int in 1 the four values returned specify the horizontal position vertical position width and hei
92. information stored in re source RSC files This information is used to display menus dialog boxes and so on Shell Library The routines found here deal with loading and running programs The Shell Library allows you to load and run other applications from within an application like the Desktop does At this point you may be wondering where the GEM Desktop fits into the scheme of things Strange as it seems the Desktop is not really an integral part of the GEM AES Rather it is itself an application program and as such it uses GEM the same way your application programs will Of course you should bear in mind that most if not all of the AES Library functions were originally written to facilitate creation of the Desktop application Although most of these library calls are general enough to be of use in almost any application a few are of interest mainly for their use in the Desktop Allocating RAM The parts of the AES discussed so far consist of program code located in the ST s operating system ROM The AES also uses some free system RAM The first RAM area it must allocate is the Menu Alert Buffer As was mentioned above when the user pulls down a menu the Screen Manager automatically saves the portion of the screen that lies under the menu The Menu Alert Buffer is the place where this screen information is stored This buffer has to be large enough to accommodate a quarter of the screen at any one time Since the ST uses
93. is filled with solid black color 1 and has its TOUCHEXIT flag set Finally at the left of the dialog box are three G BOX items stacked one on top of the other These are called OPTION1 OPTION2 and OPTIONS They are HOLLOW filled with an outside border one pixel in thickness and they have the SELECTABLE flag set These objects are used as stand ins for the user defined objects that will be in stalled later in the program since the resource construction programs don t let you create them directly Each of these box objects has a STRING object to the right of it whose text reads OPTIONx where x is the option number Figure 7 1 shows the layout of the dialog as created with the resource construction program left and as displayed by the program once the user defined objects are installed right Figure 7 1 The Dialog Box from Program dialog2 c Slider Position Slider Position g 0 OPTION 9 OPTIONL OPTION CPTIONZ OPTIONS O OPTIONS Er Em 184 a SE j 1 3 Lp d xod I 4 Co LO LL L L L L The Graphics Library As mentioned above the resource construction programs won t let you build user defined objects directly Therefore you have to use GL OBJECTS and change some fields in the object structure First you ve got to change the object type to G_PROGDEF Next you must change the ob spec field to a pointer to an APPLBLK structure This structure should con tain the
94. it Form_ do checks to see which object the pointer is over when the user clicks and selects that object When an ob ject is selected it is redrawn in its highlighted form This usually means that the entire object rectangle is inverted so that each pixel of color is changed to its complement The pro gram may however use its own form of highlighting It can do this either by using TOUCHEXIT objects so that the pro gram regains control and can do its own drawing when the user clicks on them or by using G_PROGDEF type objects so that the program s own routine is called automatically when the object is to be drawn or highlighted As part of its object selection service form do handles the mutual exclude feature of objects whose flag settings in clude RBUTTON in their ob_flags field As explained in Chapter 4 these objects which must all be siblings deselect all others when one is selected Form do respects this flag and makes sure that only one radio button is selected at a time Form do will continue handling input from the user until an exit condition occurs The most common exit condi tion occurs when the user selects an object that has the EXIT 160 fee ow 2 pE Ru dAd ud dd OC L t tf _ LT t L Interactive Object Handling and SELECTABLE flags set in its ob flags field Typically exit objects include buttons that read OK or Cancel If one of these objects has its DEFAULT flag set then
95. l L E de L LL rsrc_gaddr Get Address of Resource Data rsrc_gaddr This function is used to find the address of a data structure within a re source file that was loaded with rsrc_load Opcode 112 12 Opcode Number of 16 bit inputs in int zin array Number of 16 bit results in int out array Number of 32 bit inputs in addr_in array Number of 32 bit results in addr out array A code specifying the type of structure containing the data whose address is to be returned Valid code numbers are Structure Object tree OBJECT TEDINFO ICONBLK BITBLK Pointer to free strings Pointer to free image data Ob spec field of OBJECT Te ptext field of TEDINFO Te_ptmplt field of TEDINFO Te pvalid field of TEDINFO Ib_pmask field of ICONBLK Ib pdata field of ICONBLK Ib ptext field of ICONBLK Bi pdata field of BITBLK Ad frstr the address of a pointer to a free string Ad_frimg the address of a pointer to a free image C binding int status type index long address status rsrc_gaddr type index amp address Inputs control 0 1 control 1 2 control 2 1 control 3 0 control 4 1 type int zin 0 Type Number Macro Name 0 R_TREE 1 R_OBJECT 2 R_TEDINFO 3 R_ICONBLK 4 R_BITBLK 5 R_STRING 6 R_IMAGEDATA 7 R_OBSPEC 8 R_TEPTEXT 9 R_TEPTMPLT 10 R_TEPVALID 11 R_IBPMASK 12 R_IBPDATA 13 R_IBPTEXT 14 R_BIPDATA 15 R_FRSTR 16 R_FRIMG index int_in 1
96. msgbuf 8 int timelo timehi int mousex mousey button shiftkey int keycode clicked happened evnt multi events clicks bmask bstate m1flag m1rectx mlrecty mirectw mirecth m2flag m2rectx m2recty m2rectw m2recth msgbuf timelo timehi amp mousex amp mousey amp button amp shiftkey amp keycode amp clicked Inputs control 0 25 Opcode control 1 16 Number of 16 bit inputs in int_in array control2 7 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array events int in 0 A code which specifies the type of event for which the application is waiting Each event type is represented by a single bit If that bit is set to 1 the function will in clude that event type in the list of events for which it is waiting The bit values for the various events are Bit Bit Value Macro Name Event 0 1 MU KEYBD Keyboard 1 2 MU_BUTTON Mouse button 2 4 MU_M1 Mouse rectangle 1 3 8 MU_M2 Mouse rectangle 2 4 16 MU_MESAG Message 5 32 MU_TIMER Timer clicks int_in 1 The number of clicks to wait for To be more precise the number of times that the mouse button state must match the state flag within a set time period before the 239 evnt multi bmask bstate miflag mirectx mlrecty mirectw mlrecth m2flag m2rectx m2recty m2rectw m2recth timelo timehi msgbuf 240 int in 2
97. out of the range of display memory and cannot be drawn The wind create call uses the standard AES system for specifying the size and position of a window or other rectan gle The four values used to delimit the rectangle are its hori zontal x coordinate vertical y coordinate width and height Those of you who are familiar with the VDI will notice that this system is different from the one used to describe a rectangle to the VDI In that system a pointer to an array holding the x and y coordinates for two opposite corners of the rectangle is used For example you might describe a VDI rectangle by specifying that its top left corner is at coordinate 10 10 and its bottom right corner is at 109 109 For purposes 27 CHAPTER 2 of the AES you would describe that same rectangle by saying that its origin is at 10 10 and its width and height are each 100 units Each system has its advantages The VDI system may be a bit quicker to use for drawing since all of the co ordinates are spelled out The AES system is more flexible however since to move the rectangle you need only change the coordinates of the point of origin To the programmer the most important aspect of the difference between the two sys tems is that some translation is required when performing VDI and AES operations on the same rectangle Because the AES library calls frequently require a rectan gle description some programs make use of a data structure that in
98. range numbers will be converted to 1 black There is another more sophisticated type of bit image ob ject called a G_ICON This type of object not only uses a bit image data array but an image mask as well This image mask allows only the shape of the image to be highlighted when the object is selected The G_ICON image may also contain a bit of explanatory text or an attached title as well as a single text character superimposed somewhere on the image Finally it may specify both the color of foreground and background data bits Examples of icon objects are easy to spot in the GEM Desktop program all of the disk drive trash can file folder and file image are G_ICONS The ob spec field of a G_ICON type object contains a pointer to a data array called an ICONBLK The C language definition for this data structure is typedef struct icon_block int ib_pmask pointer to the image mask data array int ib pdata pointer to the bit image data array char ib ptext pointer to the objects text string int ib chart low byte ASCII character drawn on icon high byte foreground and background colors int ib xchar the X offset of that character int ib ychar the Y offset of the character int ib xicon the X coordinate of the icon int ib yicon the Y coordinate of the icon int ib wicon the width of the icon in pixels 111 CHAPTER 4 int ib hicon
99. set control to a value of 35 1 2 32 C pro grammers can take advantage of the fact that the header file GEMDEFS H which comes supplied with most C compilers contains macro definitions that give names to each of the con trols If your program starts with the directive include lt gemdefs h gt you could create a window with the same set of controls specified above by setting controls to NAME CLOSER I SIZER This expression still equals 35 but it s much easier to understand what the window attributes are when you look at it The other input parameters you must pass to wind create are the window s maximum dimensions This isn t necessarily the size to which the window will be drawn that s determined by the wind_open call as you ll see Since a window s size may be changed under program control this set of parameters is used to specify the largest possible size to which it may be changed This is usually equal to the size of the Desktop window s work area that is all of the display area except for the menu bar at the top of the screen The procedure for finding out the dimensions of the Desktop window s work area will be discussed below Note however that the AES doesn t limit your window size to the size of the Desktop work area It s possible for example to create a window whose work area fills the entire display screen Such a window will have no visible distinguishing marks since the border and control boxes are
100. that it s the de fault object The EXIT flag The EXIT flag indicates that the AES Li brary routine form do will exit a dialog when this object is selected by moving the mouse pointer over it and clicking the left mouse button the SELECTABLE flag must also be set As with default objects the AES makes some exit objects visually distinct by thickening the border surrounding them by one pixel If both flags are set the border around the default object is thickened by two pixels You ll often see a dialog with buttons like OK and CANCEL where the borders of both are thick ened but that of the default button is the thicker of the two The EDITABLE flag The EDITABLE flag is used to indi cate that an object may be edited by user interaction The 117 CHAPTER 4 form do library routine in particular uses this to locate edit able text objects This helps the form do keyboard handler routine to find the next editable text field when the user presses the Tab or Shift Tab key combinations The RBUTTON flag Sometimes in a dialog you wish to present a number of options which are mutually exclusive For example in a communications terminal program you might want to allow the user to set the data transfer speed to 300 1200 or 2400 bits per second Therefore it s handy to be able to indicate that the act of selecting some objects will automati cally deselect others The RBUTTON flag is used for just this purpose It indicat
101. the the current directory folder in which you are 18 No more files int out 0 working This application can t find the folder or file you just tried to access The exit button that the user selected Since the current version of GEM on the ST only displays one button this number isn t significant a an Ld Ll j Mm Mm Sk d LJ L O LL tf LLL form center Center the Dialog Box form center Opcode 54 Changes the x and y coordinates of the root object in a dialog tree so that the dialog box is centered onscreen The function also returns the position and size information for the centered dialog C binding int x y width height OBJECT tree reserved form center tree amp x amp y amp width amp height Inputs control 54 Opcode control 1 0 Number of 16 bit inputs in int in array control 5 Number of 16 bit results in int out array control3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array tree addr in 0 The address of the object tree array which makes up the dialog box Results reserved int out 0 Reserved for future use always equals 1 x int_out 1 The horizontal coordinate of the left edge of the centered dialog rectangle y int_out 2 The vertical coordinate of the top edge of the centered dialog rectangle width int_out 3 The width of the centered dialog rectan gle
102. the height of the icon in pixels int ib xtext the X offset of the text string int ib ytext the Y offset of the text string int ib wtext the width of the text in pixels int ib htext the height of the text in pixels ICONBLK In order for you to understand the contents of the ICONBLK structure you should first understand how the AES draws G_ICON images An icon is composed of two bit im ages the mask and data images The ib pmask field of the ICONBLK contains a pointer to the mask data array while the ib pdata field contains a pointer to the bit image data array When the AES draws the icon it first draws the image mask setting all of the pixels that correspond to 1 bits in the mask to the background color It then draws in the data image setting all of the pixels that correspond to 1 bits in the data to the foreground color When the icon is selected the AES high lights the image by drawing the mask in the foreground color and the data image in the background color The field ib_wicon contains the width of the icon image in pixels Since the mask and image data arrays are composed of 16 bit words this width must be an even multiple of 16 The ib_hicon field contains the height of the icon in pixels The ib xicon and ib yicon fields contain the x and y coordinates of the icon im age relative to the data arrays As mentioned above you may specify a text string to ap pear with t
103. these 1 Turn off the mouse with the graf_mouse call 2 Lock the screen display with the wind_update call 3 Get the first rectangle in the window s rectangle list with the wind_get call 4 If the width and height of this rectangle are greater than 0 calculate the size and position of the overlap rectangle This rectangle is made up of the area where the window rectangle overlaps the damage rectangle If there are no more rectangles in the list the width and height values are 0 go to step 7 9 If the two rectangles did intersect redraw the overlap rec tangle If the program uses the VDI to draw the window contents convert the AES rectangle to an array of points and set a clipping rectangle with the VDI call vs clip If it uses an AES object tree to draw the window contents set the clip area with the objc_draw input parameters If there was no overlap go on without redrawing 61 CHAPTER 3 6 Get the next clipping rectangle with wind get and go back to Step 4 7 Unlock the screen display with wind_update and then turn the mouse back on with graf mouse Handling the WM_REDRAW messages takes care of the case where system events force you to refresh your window There are circumstances however under which you ll have to redraw the window even when you don t get a system mes sage For example you don t get a redraw message for a win dow when you decrease its size but you may want to chan
104. this byte to create their own ex tended object types which contain additional information about the object 103 CHAPTER 4 Box Objects The three box object types are G_BOX B IBOX and B BOXCHAR G_BOX The first G_BOX is a solid rectangle with an optional border The box may be filled either with a solid color or a pattern A G_BOX is generally used as a backdrop on which to place other objects The dialog box illustrated in Figure 4 1 for example uses a G_BOX for the root object ROOTBOX the plain white box on which the entire dialog is mounted It also uses a patterned G_BOX PATBOX as a pat terned backdrop for the three buttons and the text G_IBOX The second type of box object G_IBOX is a transparent box with an optional border If the thickness of the border is set to 0 the box is truly invisible as its name suggests A G_IBOX is most often used to group together other objects For example in the dialog box of Figure 4 1 the three radio buttons marked A B and C are contained in an in visible G_IBOX called INVISBOX Since radio buttons must be siblings as you ll see later on the G_IBOX is used as an in visible common parent Another possible use for a G_IBOX is to group together two or more objects in order to make any of them select all of them For example say that two sibling ob jects one an image and the other a text string are placed near each other If you cover them with a higher numbered sibling G_
105. this call is SISA OF gt c O int status code status wind_update code where status is equal to 0 if an error occurred If there was no error a nonzero quantity will be in status The code value in dicates the function of the call Code Macro Name Function 0 END UPDATE Notifies AES that the application is end ing its window display update 1 BEG_UPDATE Notifies AES that the application is begin ning a window display update 2 END MCTRL Notifies AES that it should once more take control of the mouse when it leaves the active window area 3 BEG_MCTRL Notifies AES that the application is taking control of all mouse functions even when it moves out of the active window CHAPTER 3 The macro names for this function are defined in the file GEMDEFS H For purposes of starting the refresh process use the call wind update BEG UPDATE This call prevents the system from making display changes in the part of the screen being updated Things could get very messy if a menu dropped down on top of your win dow while you were drawing in it Next comes the process known as walking the rectangle list Unless your window is the active topmost window it s possible that part of it is covered by another window The AES doesn t automatically limit your graphics output to the part of the window that s showing Therefore if your program re draws the entire window it s going to destroy parts of other windows Keeping you
106. to restore the pointer again It is necessary to hide the mouse pointer whenever your pro gram does any drawing that might overwrite it since the old background behind the pointer will be restored as soon as the pointer is moved The syntax of the graf mouse call is int status form no formptr 37 status graf mouse form no formptr where form no indicates which form the user wishes to install The valid form numbers and the macro names for them that 187 CHAPTER 7 are found in the GEMDEFS H file are shown below along with a short explanation of the typical usage of these forms Form Number Shape Macro Name Usage 0 Arrow ARROW General purposes 1 Vertical bar I beam TEXT CRSR Text cursor placement 2 Busy bee HOURGLASS Busy signal 3 Pointing hand POINT_HAND Sizing 4 Flat hand FLAT HAND Dragging 5 Thin crosshairs THIN CROSS Drawing 6 Thick crosshairs THICK_CROSS Application specific 7 Outline crosshairs OUTLN CROSS Application specific 255 User defined USER_DEF Application specific 256 Mouse pointer off M_OFF Hide mouse before drawing 257 Mouse pointer on M_ON Restore When form number 255 the user defined pointer im age is selected the formptr value should contain the address of a 37 word data array that provides information about the pointer This information includes the foreground and back ground colors for the pointer the shape of the pointer and a mask which allows you to specify whether the zero
107. turned OFF 1 3 break case ABLEITEM draw Pattern 2 text Thanks for turning me on 1 break case QUITITEM Quit done 2 1 break default break gt end of switch on menu item menu tnormal menutree msgL 3J 1 set menu to normal break 151 CHAPTER 5 defaulti break 2 8 and of switch on message type return done report done status amp Print Text Routine text string color int color char string vet color handle color MOUSE OFF Hide the mouse pointer clear rect amp work clear the area amp v gtext handle 19 cellw 29 cellh string MOUSE ON Show the mouse pointer amp amp SESSKSSSKAKKEKSEAEREEEE End of Menu2 c EXKKKEKEREREREEKERER K In order to run this program you must first create a re source file called MENU2 RSC If you have a resource con struction program you ll need to create an object tree an alert and two free strings The object tree is is a menu tree with the C macro name MENUTREE This menu has three ti tles To the default DESK and FILE titles add an OPTION title Under the DESK menu edit the first item s string to read About Menu2 and give it the C macro name ABOTITEM Edit the item under the FILE menu to read Quit Q and give it the name QUITITEM Next add four items under the OP TION menu The first reads Check Mark and has the name CHEKITEM The second is just a gray separator b
108. type index address where type specifies the type of data structure index gives the position within the data array and address is the variable which holds the address to be placed in the data structure 138 1 Lj d eo fi L LL LC L CL Resource Files and Menus This function is used by the AES when it corrects the address pointers at resource load time but there are instances when you may want to use it yourself in a program Though resource files are made to be as independent of the display resolution as possible there are some situations where objects may not work equally well in all resolutions The first is when using the low resolution display mode The resource construction programs are designed to run in me dium or high resolution modes so most resource files are built on the assumption that an 80 X 25 character display will be used If this isn t the case parts of large object trees might be lost off the edge of the screen The second area of possible incompatibility concerns the aspect ratio of the display Though objects are lined up by character positions the actual image data of G IMAGE or G_ICON object consists of pixels If the aspect ratio of the display is different from the one on which it was created the icons and images may not look right and may not be located in the right spot For example the Desktop program icons for disks files and folders look fine in high or low resolution modes
109. version of the program the default path was set to A N since we are un able make the necessary GEMDOS calls to determine the cur rent path from the first version of STBASIC Figure 6 2 illustrates the file selector dialog box Program 6 3 fselect bas 19 gt EKKSEKEESEKASAACEKASSAASAKSEELKST AKA 20 X FSELECT BAS Demonstrates use of the 3e File Selector Library in ST BASIC x 49 32 52529552223525222525955225222252552522522 9 922552 32 apb gb 62 CONTROL peek apb 79 GLOBAL peek apb 4 82 GINTIN peek apb 8 99 GINTOUT peek apb 12 1299 ADDRINS peek apb 14 112 ADROUT peek apb 22 120 fullw 2 139 PATH 25 A N 3 Set pathname and expand string to 64 characters 142 PATHNAMES PATHS strings 58 chrs 9 199 FILE string i2 chr 9 Set filename to 15 nuls 160 poke ADDRIN varptr PATHNAME 179 poke ADDRIN 4 varptr FILES 189 gemsys 99 Call fsel_input 199 exitbutn peek GINTOUT 2 200 X 2 1 Truncate file name 219 while ASC mid FILE X 1 2 9 m i nd ij 5 73 dl LLL OC L D CUCC Interactive Object Handling XoX 1 wend FILES left FILES X X len PATHNAMES Truncate path name while mids PATHNAMES X 1 lt gt X X 1 wend PATHNAMES left PATHNAMES X Clearw 2 gotoxy 19 19 print PATHNAMES F ILES gotoxy 19 12 Press any key to end Xzinp 2 clearw 2 end Figure 6 2 T
110. wind close msgEL 32 closed 2 TRUE break default break gt return closed y toggle wh routine to handle WM FULLED message int wh GRECT prev curr full get current previous and full size for window wind_get wh WF CURRXYWH amp curr g x amp curr g y amp curr g w amp curr g h wind get wh WF PREVXYUH amp prev g_ amp prev g y amp prev g w amp prev g_h 3 wind get wh WF FULLXYWH amp full g x amp full g y amp full g w amp full g h If full change to previous unless that was full also if Ccurr g x full g x amp amp curr g_y full g y amp amp curr giw full g_w amp amp curr g_h full g_h amp amp prev g x s full g x i prev g y full g y i prev g w full g_w prev g h full g_h gt e of wind_set wh WF_CURRXYWH prev g_ prev g y prev g w prev g_h redraw msg wh prev send a redraw message cause AES won t 3 If not full change to full else wind set ih WF CURRXYWH full g x full g y full g_iw full g h cetresh wh drect routine to handle window refresh WM REDKAW int ah window handle from msgt 51 GKECT amp drect amp pointer to damage rectangle GRECT wrect the current window rectangle in rect list graf mouset t OFF 0L turn off mouse wind update tBEG UPDATE lock screen wind get get first rectangle
111. window controls located in the border such as the title bar or scroll bars When the WF_WORKXYWH flag is used the function returns the size of the interior area of the window only If you restrict your drawing to that rectangle you ll never draw over a window border control box by mistake The other flag values which deal with such information as slider size and position and the rectangle list will be covered in subsequent chapters Note however that some of these func tions return values other than the standard rectangle x y width and height In most cases a single value is returned in place of the x coordinate As stated above a window handle of 0 is reserved for the Desktop window Therefore to find the dimensions of that window which represents the maximum free area available for the applications window you can use the call 30 J I J d 7 P a x wd he dud Re Be Starting an Application include lt GEMDEFS H gt int status deskx desky deskw deskh status wind_get 0 WF_WORKXYWH amp deskx amp desky amp deskw amp deskh The Desktop window dimensions excluding the menu bar will be returned in deskx desky deskw and deskh These values can then be used as the input parameters for the maxi mum window size in wind_create The status value indi cates whether or not there s been an error If status is 0 an error has occurred and if it s greater than 0 there s no error Note also
112. window whose close box was clicked Contents 23 WM_FULLED message The user clicked on the Full Box The handle of the window whose full box was clicked Contents 24 WM ARROWED message The user clicked on a scroll bar or arrow The handle of the window whose scroll bar or arrow was clicked The action requested by the user 0 page up user clicked on scroll bar above vertical slider 1 page down user clicked on scroll bar below vertical slider 2 line up user clicked on up arrow 3 line down user clicked on down arrow 4 page left user clicked on scroll bar left of horizontal slider 5 page right user clicked on scroll bar right of horizontal slider 6 column left user clicked on left arrow 7 column right user clicked on right arrow Contents 25 WM_HSLID message The user wants to move the horizon tal slider The handle of the window whose horizontal slider was dragged The requested position for the left edge of the slider a number in the range 0 1000 where 0 far left 1000 far right J d m4 e z Bened kx Lo Re Be be L L L L evnt mesag Word Number Contents 0 26 WM_VSLID message The user want to move the vertical slider 3 The handle of the window whose vertical slider was dragged 4 The requested position for the top edge of the slider a number in the range 0 1000 where 0 top 1000 bottom Word Number Contents 0 27 WM SIZED message
113. wishes to use the system memory management calls or any of the AES calls that themselves al locate memory it must deallocate all of the memory it isn t actually using at startup time The way to do this is with the XBIOS function SETBLOCK SETBLOCK is used to reserve a specific area of memory for the program and return the re maining RAM area to the Operating System s free memory pool In order to execute this command you must pass the starting address of the area you wish to reserve and the size of the area Please remember that it s only necessary to free memory when you start an application program It s not nec essary to do so with a desk accessory Finding the starting address of program memory isn t dif ficult When you start the program the second word on the stack points to that location Finding the size of the program requires a little more knowledge of how program storage space is allocated The memory area in which a program resides is known as the Transient Program Area TPA At the beginning of the TPA is a 256 byte segment known as the basepage The basepage contains information about the size and address of each program segment as well as the command line that is 47 CHAPTER 2 passed to the program these are the extra characters you type in when you run a TOS Takes Parameters program whose name ends in TTP After the basepage comes the actual pro gram code followed by the data area and the BSS Blo
114. work under the current version of GEM but should be fixed in future versions C binding int actions speed char buffer appl_tplay buffer actions speed Inputs control 14 Opcode control 1 2 Number of 16 bit inputs in int Lin array control 2 1 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr out array actions int in 0 The number of user actions to play back speed int in 1 The speed at which to play them back on a scale of 1 10 000 where 100 equals the original speed at which the actions were performed 50 equals half speed 200 equals double speed and so on buffer addr_in 0 Address of the buffer used to store the re corded user actions Results int out 0 Always equals 1 See also appl trecord 227 appl_trecord Record Mouse and Key Macro appL trecord Opcode 15 Records a specified number of the user s mouse and keyboard input actions This function does not work under the current version of GEM but should be fixed in future versions C binding int actions char buffer appl_trecord buffer actions Inputs control 0 15 Opcode control 1 1 Number of 16 bit inputs in int in array control2 1 Number of 16 bit results in int out array controlj3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr out array actions int_in 0
115. your own application 63 resolution mode 22 23 Resource Construction Set RCS 131 resource files 9 131 39 converting position size values to pixels 138 loading 136 37 store data structure addresses 138 39 structure 134 Tree Index 135 using construction programs 132 34 Resource Library 8 9 root object object number 0 98 RSCBUILD C program 152 R_STRING 137 RTARROW 78 R_TREE 143 rubber box 179 Scrap Library 8 SCREEN 141 screen display unlocking 61 Screen Manager 6 7 56 scroll bars See slide bars separator bar 142 SETBLOCK 48 201 Shell Library 9 short 17 sibling objects 98 sizer control 64 slide bars 78 87 slider 25 78 83 calculating position 81 finding position 82 position 80 83 rounding slider movement 82 size 79 80 slider box 78 snapping 68 startup file 39 static array 33 Status 22 ST BASIC 14 16 array starting addresses 14 ASK MOUSE 15 16 calls 14 16 reading arrays 15 writing arrays 15 struct 98 TAIL field 99 TEDINFO 108 10 timer events 91 92 title bar 25 TOS Tramiel Operating System 3 TOUCHEXIT 118 TPA Transient Program Area 47 201 Tramiel Operating System See TOS Transient Program Area See TPA UPARROW 78 329 USERBLK See APPLBLK user defined objects 113 15 validation characters 109 VDI Virtual Device Interface 4 22 60 converting from AES 60 opening a screen workstation 22 Virtual Device Interface See VDI visual hierarchy 101 v opnvwk 22 vs clip 60 vs color 105 6
116. 1 2x J222 9x90014 9x902901 x DOOD x28272 Ox G3Gi Ox BOC4 0x09019 090x901 0x 1189 9x991C 0x90001 9x09E1 xOGic x 2001 Qx919E x 381C 9x99001 9x9138 0x991C 0x909091 9x9162 0x909014 9x90902 0x2177 9x991C 0x909001 9x90027 OxFFFF 9x BOOo Sx DOGO Ox BOS1 9x90002 90xe200 9x09002 2x290206 x Ox F 9x900902 Bx BOIS 9x BWI Dx BOO Ox BOOS x BVOB Ox 9x900900 9x909D Ox BOBO Gx Ox BIVo Gx BBO x 9x909011 Ox 90x0020 Bx GIWO x x 1 x 9xe2090 Bx WBS Ox 9x90009 QxFFFF Ox BOOS Ox SIO Ox 987 Ox BIO Bx OOOO OxFFFF Ox BOG1 Gx SAS OxFFFF 90x2005 Bx BBOS OxFFFF Ox BOOS x xFFFF x 7 Ox OxFFFF Ox Ox BBWS Ox Bi1A Ox BIBO 9x00905 Sx S Gx 0x0004 x CT Ox G99G QxFFFF 0x9006 9x Sx E 0x09017 0x0009 9xFFFF 9x9917 9x0000 9xFFFF 9x90917 9x09009 OxFFFF 9x0217 Ox xFFFF 90x90017 Ox BOFF OxFFFF Ox D Sx 9x Program 2a dialogl h resource set indices for DIALOGI define define define define define define define define define define define defino define define DIALTREE OTHERTXT 1 YUNGBUTN 4 MIDBUTN 5S OLDBUTN 6 STBOX 9 XLBOX 16 EXIDYBOX
117. 24 x 2829 9x 2034 Ox7373 9x2941 x2 S1 9x6372 9x7465 9x204D x6D75 9x6S56D 9x2965 x 2020 90x2074 9x2D2D x2D2D 9x 45C298 x Bx BOWS 9x0902 Bx BOWS Ox BIOS SxFFFF 9x00909 x 9xFFFF Px BIBS x 9x900908 Sx BVOS Bx BBOO 9xFFFF 9x0901 r OxFFFF x BIOS 9x BIOS OxFFFF 9x 8995 9x BOOS OxFFFF 9x09007 x BFAD 9xFFFF r int rscdata 513J OxB1A6 OxOSFE 9x94902 9x29044 9x6S6E 9x2D2D 90x2044 9x35129 Qx7S3S5F x4163 gx4465 90x20290 9Qx6F72 9x63563 9x75659 Qx6E20 Ox 726E 9 OQx6S6E 9x6C74 9x7329 9x7175 9x20535 gx6oF29 x2D2D x2D2D 9x7265 Sx Px FADD x 2Z 9x29950 x 9xFFFF Px BIB 9x BBS 9xFFFF 9xe9006 9x00909 x F 9x09165 Bx BIOS 9xFFFF 9 09016 Ox BIOS OxFFFF 9x0916 OxOQO00 OxFFFF 9x20916 Bx BIOS 9xFFFF Ox Bib Ox OOFF OxFFFF Sx BSoc Bx Bi1Ad 0x2019 9x29044 97261 9x79351 9x 2D2D 9x63735 9x2009 9x7279 x 6365 Ox736B 9x90020 9x79290 9x6573 9x7426 9x3129 9x290352 0x7929 9x692D 9x616E 90x6976 9x656C Sx 454E x2D2D 9x 2D2D 9x6DA 5 Sx B19c Px BIO 9x 0914 9x90201 Bx 9x0020 x 3J L 9x002B x 2 9x903501 x 9x909014 9x0008 9x0059 x 1C 9x90021 Ox 961 9x90901C 9x90021 9x JBB 9x9901C 9x909021 Ox
118. 30 195 CHAPTER 7 Mouse and Keyboard Input The final graphics routine is used for graphics input which roughly translates to receiving information from the mouse pointer and shift keys The graf_mkstate call provides some of the same information as the evnt button and evnt multi calls The difference is that graf_mkstate doesn t wait until an event occurs Rather it returns immediately reporting the current status of the mouse buttons and shift keys This makes it suitable for use in a polling routine that checks one or both of the mouse buttons The format used for calling for this rou tine is int reserved mousex mousey mousbutn shiftkey reserved graf mkstate amp mousex amp mousey amp mousbutn amp shiftkey where mousex and mousey contain the horizontal and vertical coordinates of the mouse pointer and mousbutn and shiftkey contain information concerning the mouse button and shift key status The mouse button state at the time of the call is re turned in the mousbutn variable The value returned is a 1 if the left button is down 2 if the right button is down or 3 if both are down The shiftkey variable contains a code that tells whether the right Shift key the left Shift key the Control key or the Alt key was pressed at the same time as the mouse but ton Each of the four low bits represents a different key Bit Bit Value Key 0 1 Right Shift 1 2 Left Shift 2 4 Control 3 8 Alt Thus if s
119. 32K of screen memory in all of its resolution modes the Menu Alert Buffer must oc cupy 8K of RAM AES may also need some RAM to load resource files Re source files are data files which define GEM object trees the data structures used to create menus dialog boxes and icons The amount of RAM required depends on the size of the re source files to be loaded Finally GEM may also need to use some free RAM for the Desk Accessory Buffer This is the area used to store up to six desk accessory programs at boot time Desk accessories are separate special programs They can be found on the root di rectory of the startup disk Their file names end in ACC CHAPTER 1 These programs may be run from the Desk menu of another application Using the AES Libraries You may think of the AES Libraries as a collection of subrou tines that you can call from your program In order to pass data to these subroutines and receive data from them in re turn you must allocate storage space in computer memory for a number of data arrays The AES uses information from six different arrays each of which is made up of a number of 16 bit two byte values These arrays are as follows Array Name Size Function global 15 words Global parameters control 5 words Control parameters int in 16 words Input parameter int out 7 words Output parameters addr in 2 long words Input addresses addr_out 1 long word Output addresses The array named global contain
120. 40 0300 0423 0413 0524 0514 0625 0615 075E 071E amp 0826 0817 092A 0918 0A28 0A19 0B29 0810 OC5F OCIF 0D2B 0DID 297E 2900 I 2B7C 2B1C 1A73B 1A1B 1B7D 1BID 273A 271B 2822 2807 lt 333C 330C gt 343E 340E 353F 350F 3920 3900 011B 011B OE08 0E08 537F 531F 1C D 1C0A 0F09 OF09 Shift CTRL ALT 6200 6200 6100 6100 6100 5230 5200 4737 7700 4838 4800 5032 5000 4B34 7300 4D36 7400 ALT 7800 7900 7A00 7B00 7C00 7D00 7E00 7F00 8000 8100 8200 8300 2960 2B5C 1A5B 1B5D 273B 2827 332C 342E 352F 3920 011B 0E08 537F 1COD OF09 screen print left mouse button right mouse button move mouse up move mouse down move mouse right move mouse left Jer pg m u ER s ad i LO L L L L EL Extended Keyboard Codes Numeric Pad Unshifted Shift CTRL ALT 6328 6328 6308 6328 6429 6429 6409 6429 652F 652F 650F 652F 662A 662A 660A 662A 4A2D 4A2D 4A1F 4A2D T 4E2B 4E2B 4E0B 4E2B 712E 712E 710E 712E Enter 720D 720D 720A 720D 0 7030 7030 7010 7030 1 6D31 6D31 6D11 6D31 2 6E32 6E32 6E00 6E32 3 6F33 6F33 6F13 6F33 4 6A34 6A34 6A14 6A34 5 6B35 6B35 6B15 6B35 6 6C36 6C36 6C1E 6C36 7 6737 6737 6717 6737 8 6838 6838 6818 6838 9 6939 6039 6919 6939 Function Keys Unshifted F1 3B00 F2 3C00 F3 3D00 F4 3E00 F5 3F00 F6 4000 F7 4100 F8 4200 F9 4300 F10 4400 Shift 5400 5500 5600 5700 5800 5900 5A00 5B00 5
121. 52 148 50 adding objects 141 42 changing tree to dialog boxes 141 42 creating trees 141 DESK 142 disabling 148 drawing menu bar 143 drop down 140 EDIT 142 FILE 142 finding current settings 149 50 getting tree address 143 installing 143 mouse selection 140 return title to normal video 144 using 143 44 MENUTREE 143 message pipe 54 64 messages 53 78 format 54 55 predefined messages 55 reading directly 64 reading pipe directly 64 refresh messages 56 62 sending 62 64 sending longer messages 55 sending to other applications 63 64 sending to your own application 63 waiting for 64 window 64 78 MN_SELECTED 143 202 3 modeless programs 170 mouse 57 61 88 91 187 88 196 button events 88 changing click speeds 88 changing forms 187 checking current status 196 form definition data structure table 188 rectangle events 90 91 turning off 57 328 turning on 61 waiting for button event 88 89 move bar 25 moving windows 67 msgbuf array 54 multiple events 92 94 multitasking 5 6 breakdown 6 newpos 124 NEXT field 98 Not Ready list 5 OBDEFS H header file 97 ob_head 98 Object Library 8 routines 120 25 object number 98 objects 97 128 bit image 110 13 changing sibling order 124 changing status field 122 children 98 color 104 5 color tables 105 colored text string 107 creating data 131 deleting from tree 124 drawing trees 102 120 21 finding absolute screen position 121 22 finding index numbers from coordi nates 121 fi
122. 52552222925522 2255 22 22222121 amp t DIALOG2 C Demonstrates more sophisticated dialog a box with a slider and user defined objects x a SEATKAAALAEAATARAAAA AAAS AAAAAAAAK AAR AAA SAAT AKASAKA ESATA ATES define AFP INFO define APP NAME Dialog Example 2 define WDW CTRLS NAME define TRUE 1 Hinclude aesshell c include dialog2 h include file from RSC OBJECT tdialtree pointer to dialog object tree TEDINFO obspec pointer to TEDINFO for text object char strptr pointer to text string for text object APPLBLK ublockt31 X APPLBLK defined in OBDEFS H demo 4 int x y width height exitbutn slider pos int drawcodet if rsrc load DIALOG2 RSC Load resource file form alert S tOltFatal ErroriCan t find DIALOS2 RSC file JCAbort return Abort if it s not there gt get address of menu tree and dialog tree rsrc_gaddr R TREE DIALTREE amp dialtree get pointer to text objects s text string obspec TEDINFO dialtreet NUMBERJ ob spec strptr obspec te ptext 8 pointer to text string for sOPTION1 x COPTIONS 1 5 x ublockEx CPTION11 ub code drawcode set drawcode x dialtreetxJ ob spec char amp ublock x CPTIONI1 to userblock dialtreetxJ ob type G PROGDEF change object type H 1 Display dialog box form center dialtree amp x
123. 7 if sized check for min size then resize t msgt63 MAX msgl63J cellwt8 msg 7 MAX msgL7J cellh 4 wind set msgL51 WF CURRXYWH msgL4J msg SJ msgL623 msgl7 3 redraw agg nsgt 531 GRECT 2 amp 089L42 break case WM MOVED if moved make sure the window stays on the Desktop 37 if msgf4 msgl6 gt desk g_x desk g_w msgL4J desk g_x desk g w msgL63 j if msgl SJ msgL7J gt desk g_y desk g_h msg 351 desk g y desk g_h msgr7 wind set msgL3J WF CURRXYUWH msgL42J msgLSJ3 msgt6J msgC73 break case WM FULLED 4 if fulled do toggle routine t toggle msgL523 break case WM CLOSED if closed close window and workstation if msgL 353 wi handle wind close msgt52 wind delete nsgL 523 v Clsvwk handle wi handle NONE 3 break default break 3 ttt Open virtual workstation create and open output window z init out c handle phys handle v opnvwk work in amp handle work out open virtual screen workstation if handle return VWK_ERR if we can t open it return error code Find out the maximum size for a window and open one wind get DESK WF WORKXYUWH amp desk g x amp desk g y amp desk g w amp desk g h find dimensions of Desktop Window wi handle wind create WDW CTRLS desk g x desk g_y desk g_w desk g h j Create a window that size if wi han
124. 8 9xSFSF 9x4354F QxSS6E 9x7663 x 7574 9x7269 9x 4500 9x29045 x Z 2x537 9x2D2D x2D2D 9x6565 9x736B 90x90020 9x79290 9x657535 x 6B29 90x290290 9x 2936 9x99020 x GOID x D Sx BSS2 OxFFFF 9x09015 x 0x0006 9x9901B Qxo00Q 9xFFFF 9x09008 Sx GIDD xFFFF 9x0004 QxO0O0Q OxFFFF Bx BIOS Ox OOFF 9xFFFF x J r FF xFFFF x 8 Bx xFFFF rX E Bx x 1B8A 9x909024 9xSFSF 9x62572 Sx OSGE Ox 4D52 9x 6465 9x 7220 x 6572 x 2053 9x 4578 9x616E 9x2946 9x6163 9x2D2D 9x 2D2D x7373 9x 2941 x 2944 9x 353529 9x736F x4163 8x 4465 9x 2329 9x29051 9x0045 9x209014 9x1102 9x991D x 1 Px GOS2 9x B19 9x99091 9x90962 9x909010 9x09001 9x9971 9x991C 9x00901 9x90907E 9x90014 x LN 9x11901 9x9614 SxSOSi 9x1121 9x991C 9x09201 9x09098 9x2991C 9x909001 x B3S DIALOG1 RSC 9x90188 9x90002 gxSFSF 9x 5029 Ox SESE Sx5554 Sx 7226 Sx 3339 9x73290 9x5499 9x6964 9x6365 9x696C x 65209 9x2D2D 9x 2D2D 9x6F72 x6363 9x635735 9x20900 9x7279 9x6365 9x 736B 9x 8920 Gx 7569 x 3 9xFFFF x 3 9x99098 x 99005 9x20919 x x S Bx 9x909011 gx90005 Ox SGis Bx BBO Sx 9G x BSI2 2gx909091 x B x
125. 8 unregistering an application 21 Alcyon C compiler 17 132 alerts 157 59 creating 158 59 format 157 58 NOTE 158 STOP 158 APPLBLK 113 appl_find 63 Application Environment Services 4 Application Library 8 desk accessories 203 finding memory starting address 47 layout of Transient Program Area in ST memory 48 opening an output window 23 program area total size 48 sending and receiving redraw mes sages 63 system memory management calls 47 appl_read 55 64 appl_write 55 62 63 arrow characters 78 background pens 189 BAR 140 41 basepage 47 Basic Input Output System See BIOS binary tree 98 BIOS Basic Input Output System 4 5 BITBLK 110 11 bi color 111 bi hl 111 bi pdata 111 bi_wb 111 bi x 111 bi_y 111 G_IMAGE 110 326 bit flags 117 19 DEFAULT 117 EDITABLE 119 20 EXIT 117 HIDETREE 119 INDIRECT 119 LASTOB 118 RBUTTON 118 SELECTABLE 117 TOUCHEXIT 118 blit 158 boxes 104 106 109 10 180 82 185 86 borders 106 border thickness 110 color 110 dragging 180 drawing a moving box 186 G_BOX 104 G_BOXCHAR 104 G_IBOX 104 growing 186 87 justifying text 109 10 monitoring mouse position 185 86 moving slider object 181 moving within containers 180 82 pattern 110 shrinking 186 87 specifying text length 110 character cell 23 clipping rectangle 60 61 172 proceeding to next 61 setting 60 close box 25 color mask 189 control array 10 controls 26 controls input parameter 34 C programming 21 39 in
126. 909024 9x0099 9x4669 9x29290 9x092D 9x 2D2D 9x635635 9x6373 9x290900 0x7279 9x6363 9x736B Ox 2 9x7929 9x0920 x2D2D 9x2D2D 9x29049 9x7429 9x 204E Ox 3OSD 9x 7468 9x91F4 Bx BIDS 9x6C6S 9x4162 9x 2D2D 9x2D2D 9x6375 Ox 6B29 Bx 2920 Ox 2833 Ox7373 9x2041 9x2044 Ox 53629 Bx 2943 9x2D2D Ox 2D2D 9x7469 9x 4D65 x6578 9x SB20 Ox 2963 FR ee uu eee ae UL UL EL i _ b 4 LL L 9x6865 90x7969 9x6174 9x S365 Ox 29635 x 2D2D 9x 2D2D Sx 656D x5475 9x 4E29 9xFFFF x Ox S x 1 90x9902 Bx BWI x IWS5 x 8 Sux BOI Sx BOIS Sx BOSS x 90x9909 x Ix B x B Ix G x x D x x 29909 x F Ox DOJO 9 x 9x09012 x B Ix BSSO 0x00906 Ox BOSE Sx VOIP 9x909015 Sx BOO Ix x 12 Ox BODD 3 Resource Files for Sample Programs x 636B 20x6E67 x 6522 Sx6C 5 9x 6ES4 Qx2D2D 9x2D2D x656D 9x726E Bx BVI 9x90001 x x x 3J x x OxFFFF Gx BDO Bx BIOS x BBB7 xI Bx ADOD xFFFF x x GBOB xFFFF x 2 Ox B xFFFF 9x 9 4 Q9x0009 gxFFFF 9QxOOQ06 Bx BODD 9x909011 xDDD x x 13 Ox BWSS Ox BIOS OxFFFF Ox FOGL Sx BOOS OxFFF
127. ATATLATKATAAKAETAAAELAAKAAKAEKAAKSEKAAALTASASK LAKE define APP_INFO define APP NAME Menu Example 2 define WDW CTRLS NAME define MOUSE OFF graf mouse 256 amp dummy define MOUSE ON graf mouse 257 amp dummy define CTRLQ 29x1011 keycode for CTRL Q key combo Hinclude aesshell c Hinclude menu2 h include file from RCS int dummy key msgL 81 char f alert menucn tmenuof f 3 OBJECT amp menutree demo int event done if rsrc load MENU2 RSC Load resource file form alert S LtOJLFatal ErroriCan t find MENU2 RSC file iCAbortI returnt Abort if it s not there gt get address of menu tree alert and item strings rerc_gaddr R TREE MENUTREE amp menutree rsrc_gaddr R_STRING ABTALERT alert rsrc_gaddr R_STRING ONSTRNG amp menuon rerc gaddr R STRING FFSTRNB amp menuoff MOUSE OFF Hide the mouse pointer t menu bar menutree 1 Show the menu ber MOUSE ON Show the mouse pointer Main Program Loop while done 7 until user selects Quit item t t 1 check menus and keyboard event s avnt_multi MU MESASIMU KEYBD 2 0 0 evnt button 2 0 90 0 9 t evnt_mousel 2 0 0 0 0 avnt_mouse2 amp msg evnt masg 9 9 evnt timer amp dummy amp dummy mouse x y t amp dumnmy mouse button amp dumrmy IX shift keys
128. C00 5D00 CTRL 3B00 3C00 3D00 3E00 3F00 4000 4100 4200 4300 4400 ALT 3B00 3C00 3D00 3E00 3F00 4000 4100 4200 4300 4400 313 Appendix C Resource Files for Sample Programs tf LL LLL L ECE L F Our of the sample programs in this book require re source files in order to run For those who have resource con struction programs there is a description of the required resource structure after the source code of each program and in the case of dialog boxes there will be an illustration of the dialog as well For those who don t have a resource construc tion program the best advice is to obtain one as quickly as possible In the meantime however this appendix presents an alternate method of creating the resource files The main program RSCBUILD C merely writes a string of bytes to a disk file The data it writes comes from an array called rscdata which is part of a different file that s included in RSCBUILD C The name of this file depends on which re source you wish to build For example in order to build DIALOGI RSC you would include DIALOG1 DAT in the RSCBUILD C program To create MENU1 RSC you would type in MENU1 DAT and make sure that file is included in RSCBUILD C After you have compiled the program execute it and it will automatically create the resource file on disk Be careful to type in all of the data for the rscdata array correctly so that the resource structure will be prop
129. COMPUTE s Technical Reference Guide ATARI SI VOLUME TWO Sheldon Leemon A practical tutorial and reference to the GEM AES Includes program examples in C BASIC and machine language For the intermediate to advanced Atari ST programmer A COMPUTE Books Publication CEE S ECCLE COMPUTE s Technical Reference Guide ATARI SI VOLUME TWO GEM AES Sheldon Leemon COMPUTE Publications Inc A Capital Citles ABC Inc Company Greensboro North Carolina Copyright 1987 COMPUTE Publications Inc All rights reserved Reproduction or translation of any part of this work beyond that permitted by Sections 107 and 108 of the United States Copyright Act without the permission of the copyright owner is unlawful Printed in the United States of America 10987654321 ISBN 0 87455 114 5 The author and publisher have made every effort in the preparation of this book to insure the ac curacy of the programs and information However the information and programs in this book are sold without warranty either express or implied Neither the author nor COMPUTE Publications Inc will be liable for any damages caused or alleged to be caused directly indirectly incidentally or consequentially by the programs or information in this book The opinions expressed in this book are solely those of the author and are not necessarily those of COMPUTE Publications Inc COMPUTE Publications Inc P
130. E This menu has three titles To the default DESK and FILE titles add a DRAW title Under the DESK menu edit the first item s string to read About Menul and give it the C macro name ABOTITEM Edit the item under the FILE menu to read Quit Q and give it the name QUITITEM Next add two items un der the DRAW menu The first reads Pattern 1 F1 and has the name PATIITEM The second reads Pattern 2 F2 and has the name PAT2ITEM The second object tree is an alert string called ABTALERT Drag four strings to the alert window The first line reads Menu demo with multi object the second reads items and keyboard equivalents and the third reads Select Quit to end The fourth line is made up of dashes The string in the button should be edited to read I ll remember that If you don t have a resource construction program you should get one without further delay but in the meantime you ll be able to build the resource file needed for this ex ample by running the RSCBUILD program in Appendix C The resource file that we created for this program was a bit fancier than the one described above The menu items Pat tern 1 and Pattern 2 each include a colored G_BOX which dis plays the pattern fill To create this kind of a menu item you must first change the type of the tree from menu to dialog in your resource construction program When you display this tree all the drop downs will be visible Get a hold of the drop down box for DRAW by hold
131. EM fea tures must be ready to redraw the contents of each of its windows at any time Because of the nature of the GEM windowing system all or part of a window might be covered or uncovered at any time When that happens the AES takes care of redrawing the window border areas but it s up to the application to redraw the interior display of each of its affected windows You may expect to receive a WM REDRAW message even if your application has only one window and that win dow has no window controls for moving or sizing it The rea son for this is that as long as your window includes a menu bar you might start up a desk accessory that opens windows of its own Your program can expect a window redraw mes sage in any of the following circumstances A new window is opened on the screen e Windows are reordered by sending a new window to the top of the stack as the active window window is made larger in any dimension A window is moved from a position part way off the screen to a position where more of the window is on the screen A window is closed sized down or moved exposing a previ ously covered portion of another window This window doesn t have to belong to your program It may have been opened by another task such as a desk accessory dialog is completed and the dialog box is removed When these or similar events occur the Screen Manager determines which portion of the screen display has been dam aged
132. F Bn BOIS Ox 296D x 2029 x7465 9x 6374 x2E7C Ox 2D2D gx 2D2D 9x6265 9x2904E x 0229 Gx BSOb x S x x S x 18 x xFFFF Ox BOBE x 90x09012 x S x FF xFFFF 0x20016 Ox SOO 9xFFFF 9x29016 x OxFFFF 9x2216 9 x09000 QxFFFF 9x0916 Ox ISSO OxOGi11 Sx OBAC 9x BISO 2x90916 OxBSis Sx BOOS OxFFFF 9x09016 Qx0000 QxFFFF 9x299016 Program 5a menu2 h resource set indices for MENU2 define define define define define define define define define define ftdefine define 9x6172 x616E 90x7874 9x2022 9x2D2D x2D2D Qx2D2D x 7228 x 6579 9x21356 x019 2x019 x 1199 gx20019 9x035291 90x90024 x 3229 9x9 501 x BO32 Ox BO19 Ox BBi1S 9x 1199 Mx BSic x Sx 4D 9x9091C 90x90001 9x 9979 x 9x9091 x AS x LC 9xe0091 x SCD 9x299014 9x909001 Ox VGE2 9x 14 Sx BSBA Ox ED x dic Ox 0221 x 111 OxO0PD1C 9x90001 MENUTREE DESKTITL 3 FIL fITL 4 OPTNTITL S ABOTITEM 8 QUITITEM 17 CHEKITEM 19 TOBLITEM 21 ABLEITEM 22 OFFSTRNG 2 ABTALERT 1 ONSTRNG 2 Sx 6B73 90x6429 Qx2bE7C 9x31735 Qx2D2D Qx2D2D xSDSB 9x7468 9x7420 x 0x0009 9x0906 x Ox DIOS Ox BIS xS Dx BOOS Ox BSS2 Ox BSec Ox BOS 9x09019 x Z x
133. FFF 9x09016 Bx 9x7261 Qx726E gx 2 2 9x746F 9x 2D2D x2D2D Bx 2972 x 2928 Ox 2B4F x iDE x 9x909014 x32801 Ox BODD x020 90x903501 x 2B 9x09020 90x903501 9x 0000 90x909014 9x00908 Sx BOSC xBBic 90x90001 Ox BB64 Sx BSiC 9x99021 x SE 9x0901C x x B8 OxBGic 2x909091 9x11900 9x921C Ox I Ox 1989 x x301 Ox DAFA 9x0901C Ox BBSi 0x9126 323 Function Index Function Opcode Page Number appl_init 10 21 223 appl_read 11 55 64 224 appl_write 12 55 62 63 225 appl_find 13 63 64 226 appl_tplay 14 227 appl_trecord 15 228 appl_exit 19 21 229 evnt_keybd 20 91 230 evnt button 21 88 90 180 231 33 evnt_mouse 22 90 233 34 evnt_mesag 23 54 64 235 37 evnt_timer 24 91 92 218 238 evnt_multi 25 53 54 92 94 123 180 218 239 41 evnt_dclick 26 88 242 menu bar 30 243 menu icheck 31 244 menu ienable 32 148 245 menu tnormal 33 144 246 menu text 34 149 50 247 menu register 35 202 248 objc_add 40 124 249 objc _delete 41 124 250 objc_draw 42 60 119 21 163 185 251 objc_find 43 121 252 objc_offset 44 121 22 253 objc_order 45 124 254 objc_edit 46 122 255 56 objc_change 47 122 164 180 257 form do 50 108 159 61 163 180 218 258 form dial 51 161 64 259 60 form alert 52 157 58 261 62
134. GEM visual constructs such as dialog boxes and menus At the programming level these objects are data struc tures that describe the composition and status of the figures seen on the screen Most definitions concerning objects can be found in the OBDEFS H header file The C definition for an object data structure looks like this typedef struct object int ob next object number of next sibling int ob head object number of first child int ob tail object number of last child unsigned int ob type X type of object BOX CHAR unsigned int ob flags flags for color fill pattern unsigned int ob state flags for how to draw SELECTED and so on char ob spec ADDRESS of object specific info int ob x left edge of object int ob y top edge of object int ob_width width of object int ob height height of object OBJECT Since objects are so important to GEM and since the compo sition of object data structures is somewhat complex each member of the data structure will be explained in detail below 97 CHAPTER 4 Object Tree Structure While the concept of individual objects is a powerful one the way GEM combines objects makes them even more powerful A menu bar for example is made up of a number of individ ual menu title objects and menu item objects But in order for these objects to function together to make up a menu it s nec
135. IBOX both will still show through since the GL LIBOX is transparent But clicking anywhere in the box will highlight both the image and the string G_BOXCHAR The final box object GL BOXCHAR is an opaque box like B BOX only with a single text character drawn in the center of the box The G_BOXCHAR type of object is used by GEM for the various window controls such as the sizer fuller and closer In the example dialog G_ BOXCHARs were used for the three radio buttons BUTNA BUTNB and BUTNC The ob spec field for each of these box type of objects contains two words of data that describe the color of the ob ject and the thickness of its borders The low word is used for the object color 104 d t tI sd JI J d J Ll LS LL LL lL L L L L GEM Graphics Obiects Bit Numbers Contents 0 3 Interior color 0 15 4 6 Interior fill pattern 0 Background color IP HOLLOW 1 6 Dither patterns of increasing darkness IP 1PATT to IP_6PATT 7 Foreground color IP SOLID 7 Writing mode 0 Transparent 1 Replace 8 11 Border Color 0 15 12 15 Text Color 0 15 The names in parentheses next to the interior fill pattern codes are the macro names given for these patterns in OBDEFS H The default colors and their macro names are listed below Color Number Name 0 White Black Red Green Blue Cyan Yellow Magenta Low white light gray Light black dark gray 10 Light red 11 Light green 12 Light
136. LE Mm LR 4 L L graf dragbox Let the User Drag a Box graf dragbox Opcode 71 This function draws a dotted box outline on the screen which stays a fixed distance from the mouse pointer so long as the user holds down the left mouse button This box is dragged within a boundary rectangle defined by the program When the left mouse button is released the function ends and the box is erased This function should only be called when the program has determined that the left mouse button is already down by returns from form do evnt_multi or evnt_button since if it s up the function will end as soon as it s called C binding int status width height beginx beginy int boundx boundy boundw boundh endx endy status graf_dragbox width height beginx beginy boundx boundy boundw boundh amp endx amp endy Inputs control 0 71 Opcode control 8 Number of 16 bit inputs in int in array control 2 3 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr out array width int in 0 The width of the box in pixels height int in 1 The height of the box in pixels beginx int_in 2 The horizontal position of the left edge of the box at the beginning of the call beginy int in 3 The vertical position of the top edge of the box at the beginning of the call boundx int in 4 The horizontal positio
137. Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array clicks int in 0 The number of clicks to wait for To be more precise the number of times that the mouse button state must match the bstate flag within a set time period before the function returns The time period is set by the evnt dclick call bmask int in 1 The mouse buttons for which the opera tion is waiting 1 left mouse button 2 right mouse button 3 both mouse buttons bstate int in 2 The button state for which the application is waiting 0 both buttons up eft button down right button up right button down left button up 1 2 3 both buttons down l Wi Results clicked int out 0 The number of times the mouse button state actually matched bstate This is al ways a number between 1 and the value stored in the variable clicks mousex int out 1 The horizontal position of the mouse pointer at the end of the function mousey int_out 2 The vertical position of the mouse pointer at the end of the function 231 button shiftkey evnt button int out 3 The final mouse button state 0 both buttons up 1 left button down right button up 2 right button down left button up 3 both buttons down int_out 4 The status of the keyboard shift keys Each key is represented by a different bit A 1 in that bit position means that the key is down while a 0 means that it
138. OOD Ox BBB Ox BiAb 3 x FF QxFFFF 9x09019 x FF OxFFFF Os OAL Ox BOFF gxFFFF 0x09015 x x 19909 x 1C 0x900901 x1162 Ox OGic Gx CGA1 x 11353 9x09019 2x900901 9x11900 x E x x 3 1S x 1 Ox GBI 9x09017 09x 0919 x 9x99012 x DDOD APPENDIX C 9x09909 x xFFFF 9x99900 Ox GIAO OxFFFF Ox 8981 Ax BOOS QxFFFF 9x9091 2x909015 Ox BBO 9xFFFF 9x OBIS 2x BOIS QxFFFF x S x xFFFF x9 3 1S 9x20002 9x99E 9x9914 9x9090201 Ox OOFB OxBO14 gx0001 x 11 0 x0019 xl 9x0914 Ox DBO 9x90900 x 16 9 0000 Ox 9x09018 Ox JOJO x20 Ox DODD od dd Program 4a menul h resource set indices for MENU1 define define adefine defina define define define define define MENUTREE DESKTITL 3 FILETITL 4 X DRAWTITL 5 ABOTITEM 8 QUITITEM 17 DRAWPAT1 19 PATLITEM PAT2ITEM menu trae TITLE in tree MENUTREE TITLE in tree MENUTREE TITLE in trea MENUTREE amp STRING in tree MENUTREE STRING in tree MENUTREE t STRING in tree MENUTREE IBOX in tree MENUTREE IBOX in tree MENUTREE define ABTALERT 18 Alert string index Program C 5 menu2 dat AJETTISKTAEAAESAAAETAKAEKAAKASEKAAEEEAREKEKEEEEAE LY LFA 18 MENU2 DAT g Da
139. Polling As mentioned in the section on mouse button events in order to use both mouse buttons in a program you must poll the buttons rather than waiting for button events You ve seen that a timer event of duration 0 returns immedi ately So to continuously check the status of the mouse but tons all you have to do is keep calling evnt_multi in a loop looking for a timer event of 0 The values for button kstate and mousex and mousey will be updated during each call w TERES L4 JJ y y Chapter 4 Pp GEM Graphics Objects L L LE mm LL The concept of GEM graphics objects is the key to the GEM interface These objects may be displayed onscreen as plain boxes boxes with text in them bit images icons or editable text strings Anyone who has used the ST is familiar with these objects For example the drop down menus used by GEM pro grams are composed of GEM objects The menu bar the menu ti tles and each menu item is a separate GEM object Each component in a dialog box or an alert box such as the OK button which is clicked at the end of an operation is a GEM graphics ob ject The icons that appear in the Desktop program representing disk drives files and folders are all GEM objects Even the con trol components in a window such as the close box the size box and move bar are all GEM objects Simply put GEM objects are the basic building blocks for all of the sophisticated
140. S to allocate a window and initial ize the data that the AES uses to keep track of the window It doesn t display the window The format for the wind create call is int wi handle controls fullx fully fullw fullh wi handle wind create controls fullx fully fullw fullh where controls is a bit flag which tells the AES which of the 12 window controls to attach to the window Each of the window controls is assigned a bit If the bit that represents a particular window control is set to 1 that control will be attached to the window The 12 possible window attributes are as follows Bit Bit Value Macro Name Window Control 0 1 0x001 NAME Title bar 1 2 0x002 CLOSER Close box 2 4 0x004 FULLER Full box 3 8 0x008 MOVER Move bar 4 16 0x010 INFO Information line 5 32 0x020 SIZER Size box 6 64 0x040 UPARROW Up arrow for vertical scroll bar 7 128 0x080 DNARROW Down arrow for vertical scroll bar 8 256 0x100 VSLIDE Slider for vertical scroll bar 9 512 0x200 LFARROW Left arrow for horizontal scroll bar 10 1024 0x400 RTARROW Right arrow for horizontal scroll bar 11 2048 0x800 HSLIDE Slider for horizontal scroll 26 bar 37990402 ME E xu wa m L EL L L EL EL E Starting an Application Since each control is represented by a separate bit any or all of the controls can be attached to a given window To cre ate a window that has a title bar a close box and a size box you would
141. SAKEKATAT ETE t4 Program equates bpadr 4 g Stack offset to base page address codelen 12 Base page offset to Code segment length datalen 20 Base page offset to Data segment length bsslen 28 Base page offset to BSS segment length stk 400 amp size of our stack ik bp 100 size of base page setblk 2 4a command number of SETBLOCK function aescode c8 command number for AES call vdicode 73 command number for VDI call External references gx Import xref demo the external demo subroutine 40 Dd ud d d d tL ft L L L Re Re E Starting an Application xref J xraef xraf wdwctr1l wdwtitl wdwinfo amp Export xdef aes xdef vdi xXdef pwkhnd the phyusical workstation handle xdef vwkhnd virtual workstation handle xdaf wdwhnd window handle xdef contrlO ali of the VDI data arrays xdef contr11 exdef contr12 Xdef contr13 xdef contr14 xdef contr1S xdef contrl xdef contr17 xdef contr18 xdaef contr19 J daf contrild xdef contriit J xdef intout xXdef ptsin xdef ptsout xdef ctri X ali of the AES data arrays xdef ctr11 xdef ctr12 xdef ctris xdef ctrl4 xdef aintin xdef aintout xdaf addrin xdef addrout xdef global xdef apid xdef chboxw and miscellaneous work variables xdef chboxh xdef cellw xdef cellh exdef deskx xdef desky xd
142. The address of the buffer into which the scrap directory path will be written Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also scrp_write 280 Jd J 31 4 Jj iL IL t LE li L LL scrp write Write Scrap Directory scrp write Opcode 81 By GEM convention a disk may be used for a clipboard function to save data the user selects for a CUT or COPY operation The program writes this data to disk in a file called SCRAP This file may have any of several file name extensions TXT DIF IMG and so on depending on the type of data it contains such as text graphics or spreadsheet data So that other programs may share this data when the program writes the file to disk it gives the AES the pathname of the directory where the file resides by using the scrp_write function When another program wishes to use that data it finds the directory by using scrp read C binding int status char path 128 status scrp write path Inputs control 81 Opcode control 0 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control3 1 Number of 32 bit inputs in addi in array control 4 0 Number of 32 bit results in addr_out array path addr in 0 Address of the buffer containing the text string which specifies the new scrap direc tory path Results status int out
143. VSLIDE 78 walking the rectangle list 58 WF_HSLIDE 83 WF VSLIDE 83 wind get 29 58 valid flag values table 29 Window Library 8 windows 23 35 56 62 64 68 83 84 186 87 aligning the left edge 68 appearing completely on screen 67 application 24 calculating start position 83 84 closing 34 computing overlap area 59 60 control features 24 25 controlling the work area 65 creating 26 31 creating exploding windows 186 87 exchanging exterior and interior size 65 330 finding dimensions 29 31 finding exterior dimensions 34 finding interior dimensions 33 GEM Desktop 24 handle 28 29 maximum dimensions 27 moving 67 moving to the top 68 opening 31 34 paging through 25 position 27 28 possible attributes 26 27 redrawing 65 66 refreshing 56 62 removing 35 restoring contents 57 sizing 27 64 67 updating the display 83 WM_ARROWED 82 83 WM CLOSED 69 WM FULLED 66 WM HSLID 81 WM MOVED 67 WM_REDRAW 56 57 172 WM REFRESH 172 WMLSIZED 64 67 WM TOPPED 68 WM_VSLID 81 82 XBIOS eXtended Basic Input Output System 4 5 zoom box 162 a uud ud ud y wd a WR wd The Complete GEM AES Reference Intermediate to advanced Atari ST programmers will wel come this exhaustive reference to the ST s friendly inter face the Application Environment Services COMPUTE s Technical Reference Guide Atari ST Volume Two The GEM AES gives you complete information on starting an application a two part explanation of the us
144. _envrn Opcode 125 This function searches the DOS environment for an environment string and returns the address of the byte following that string This is another function which is more applicable to the MS DOS version of GEM than the ST version C binding int reserved char textptr char estring 80 reserved shel_envrn amp textptr estring Inputs control 0 125 Opcode control 0 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control 3 2 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out arra txtptr addr_in 0 The function returns a pointer here to the address in the environment that starts with the character following the requested string If the requested string is not found a value of 0 is returned estring addr_in 1 The address of the buffer which holds the text of the environment string to search for for instance PATH Results reserved int out 0 Reserved for future use always equals 1 308 LE 5k L4 d 7 J dd A d Appendix B Extended Keyboard Codes L LELLE t L EL E The AES keyboard event functions evnt_keybd and evnt multi return a two byte value for every key pressed rather than a simple one byte ASCII code The first byte of this keycode is generally a unique key identifier that refers to the physical key struck regardless of shi
145. a message to the application specifying the menu and item numbers selected Similarly when the user clicks on one of the window controls such as the closer close box the fuller full box the sizer size box scroll bars or arrows the Screen Manager sends the appropriate message to the application If the user drags the window s drag bar the Screen Manager may be able to re draw the window in the new position itself so long as the vis ible portion of the window remains the same The Screen Manager will also notify the application if the user clicks in an 7 CHAPTER 1 inactive window signaling that he or she wishes to make it the active one While the multitasking kernel and the Screen Manager are necessary to the functioning of GEM applications they do their work behind the scenes The programmer doesn t com municate directly with them The portion of the AES that s most accessible to the pro grammer and therefore the part dealt with here in greatest de tail is known as the AES Libraries These are collections of operating system calls that perform tasks related to the setup and operation of the user interface There are eleven different libraries in all Their names and functions are as follows Application Library This library contains routines to reg ister an application with GEM and to send messages back and forth between tasks Event Library The functions found here allow you to put the application on the
146. a new window to be active 22 WM_CLOSED The user has clicked on the close box 23 WM_FULLED The user has clicked on the full box 24 WM ARROWED The user has clicked on the scroll bars or arrows 25 WM HSLID The user wants to move the horizon tal slider 26 WM VSLID The user wants to move the vertical slider 27 WM SIZED The user has dragged the size box 28 WM MOVED The user has dragged the move bar 29 WM NEWTOP A window has become active 40 AC OPEN A desk accessory has been selected from the menu 41 AC CLOSE An application has closed and desk accessories have lost their handles The macro definitions for the names of the various mes sage ID s can be found in the header file GEMDEFS H that comes with most C compilers As you can see 10 of the 13 start with the letters WM which mean that they are window messages Since these messages tell the other half of the win dow management story started in the previous chapter they will be discussed in detail here The other three predefined messages dealing with menus and desk accessories will be covered along with those subjects later 55 CHAPTER 3 Window Display Refresh Messages Perhaps the most important message your program can expect to get is WM REDRAW Most computer applications expect to update the screen display from time to time to reflect changes in the information which the program outputs But any appli cation which takes advantage of the full range of G
147. ace following the next slash in the template Form do also handles a number of cursor and control keystrokes These include the cursor keys Tab Shift Tab De lete Backspace Esc and Return Left and right cursor keys These move the text cursor backwards or forwards through the text field 159 CHAPTER 6 Up and down cursor keys Tab and Shift Tab The down arrow key or Tab key can be used to move the text cursor to the next editable text field The up arrow key or Shift Tab combination can be used to move to the previous text field The cursor moves to the first open character position in the text field Delete and backspace Delete removes the character to the right of the cursor while the backspace key removes the character to the left of the cursor Esc The Esc key clears all characters from the text field Return Return selects the first object with the DEFAULT flag set in its ob flags field This object is highlighted and the form do ends returning the object number of the DE FAULT object If no objects are designated as DEFAULT form do ignores the Return key The other major task that form do performs is handling selection of objects that have the SELECTABLE flag set in their ob flags field These objects may be of the type G_BOX G_BOXTEXT G_BUTTON or even GLIMAGE or G_ICON To select such an object the user moves the mouse pointer over the object presses the left mouse button then re leases
148. aes turn mouse on move 478 ctr19 command graf mouse move 1 ctrli 1 input integers move 41 ctr12 1 output intager mave 4257 aintin hide the mouse inp aes gx Window display subroutine 3 display Find window work area size move 194 ctr1 command wind get move 2 ctrli 2 input integers move uS ctr12 S ouput ntegers move msg 6 aintin move 4 aintint 2 WF WORKXYWH command jsr move move move move CHAPTER 8 aes aintout 2 workx store work x y w h aintout 4 worky aintout workw aintout 8 workh set fill pattern to hollow move move move move move move jsr x clear move move move move move move add subq move move move add subq move jsr 425 contr160 opcode for set fill type B contrl i H contr1i2 1 contrls one integer in intin 81 contr14 H intin select hollow fill type vdi work area of window 114 contri opcode tor fill rectangie vr_recfl 2 centrii X two points in ptsin 8 contri3 3 contr 14 work d dO ptsin wor kw d 81 dg dO ptsin 4 worky d dO ptsin 2 workh de 81 0d d ptsints vdi set fill type to pattern move move move move jer 823 contri opcode for set fill type 49 contrli 41 contr14 42 intin select pattern fill type vdi set type of fill pattern move move mulu add move jer 424 contr129 opcode for set fill style
149. age event ialized data constants dc b Sample Accessory 0 text of menu item dc b Accessory Window 9 text of Ist window title dc w 43 window control flag amp The AES and VDI parameter blocks hold pointers to the starting address of each of the data arrays apb dc 1 ctrl global aintin aintout addrin addrout vpb dc l contrl intin ptsin intout ptsout end 218 33 93 ju d on x dA UL UC C C LLLE Desk Accessories You should be aware of certain problems with desk acces sories in the current preblitter version of GEM First eunt timer behaves somewhat unpredictably from a desk ac cessory and may cause the program to lock up The same is true of the MU TIMER portion of eunt multi Also the nor mal form_2do routine has a tendency to let keystrokes fall through from the accessory to the application This means that if your accessory uses a dialog box with editable text fields some of the keystrokes may not reach those fields but instead they may end up being sent to the main application You should consider writing your own form do in order to get accurate text entry from a desk accessory dialog box at least with the current version of GEM on the ST 219 Li 1 Li LE Appendix A AES Function Reference LC L L L appl_init Initialize Application appl_init Opcode 10 This call registers the applicat
150. alled DIALTREE and a menu tree called MENUTREE The dialog tree sets up a form for a computer survey On the top line is a G STRING that reads COM PUTER SURVEY On the next line is a G STRING that reads Age Next to the G STRING is a borderless G_IBOX that covers the rest of the line Within that box are three radio but tons named YUNGBUTN MIDBUTN and OLDBUTN Each of these buttons have the SELECTABLE and RBUTTON flags set The text of YUNGBUTN reads Under 16 the text of MIDBUTN reads 16 39 and the text of OLDBUTN reads Over 39 On the next line of text down is a G STRING that reads 168 wd ad Qd ou LY xo 3 3 i UL CL CL EL LL L t E Interactive Object Handling Computers Owned Under that string appears four G_BOXes one on top of the other Their names are STBOX XLBOX EXIDYBOX and OTHERBOX Next to the top three boxes are G STRINGS that read Atari ST Atari XL XE and Exidy Sor cerer The fourth box OTHERBOX has a G FTEXT next to it called OTHERTXT The template for this text is Other fol lowed by 12 underscore characters The validation string is 12 n characters and the text is 12 spaces The menu tree has the default DESK and FILE titles with one menu item added to the FILE menu Along with the QUIT item whose name is QUITITEM there s an item that reads Survey whose name is SURVITEM Using any of the re source construction programs it should be fairly easy to create the resource described here If
151. allh int largex largey largew largeh status graf_growbox smallx smally smallw smallh largex largey largew largehy Inputs control 0 73 Opcode control 1 8 Number of 16 bit inputs in int_in array control2 1 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr out array smallx int in 0 The screen position of the left edge of the starting small rectangle smally int_in 1 The screen position of the top edge of the starting small rectangle smallw int_in 2 The width of the starting small box in pixels smallh int in 3 The height of the starting small box in ixels largex int in 4 The screen position of the left edge of the ending large rectangle largey int_in 5 The screen position of the top edge of the ending large rectangle largew int in 6 The width of the ending large box in pixels largeh intLin 7 The height of the ending large box in pixels Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also wind open graf shrinkbox 272 H J gaa J lJ bb ik eel L L graf shrinkbox Draw a Contracting Box graf shrinkbox Opcode 74 Draws and erases a series of increasingly smaller boxes to give the appear ance of a box contractin
152. alue that specifies the key or combination of keys struck and the ASCII value of that combination The first byte usually identifies the key that was struck and isn t affected by shift key combina tions The second byte is the ASCII value of the key combina tion which does depend on the state of the shift keys Shift Control and Alt In most cases the ASCII value in the low byte is what the program is really looking for and the high byte can be ignored Keys which have no ASCII value how ever such as the function keys return a 0 in the low byte and must be read by the high byte alone The entire list of keycodes may be found in Appendix B Timer Events You may use the timer event to wait for a specified period of time The format for the evnt timer call is int reserved unsigned int timelo timehi reserved evnt_timer timelo timehi where timelo and timehi are the low word and high word of an unsigned 32 bit time period expressed in milliseconds This is the opposite of the order the 68000 uses to store a long word so you ll have to split the 32 bit value into two halves before passing it to this function In theory the range of values avail able allow you to time a period from one millisecond to 65 5 91 CHAPTER 3 seconds with this function In practice however you ll find that the ST s internal clock does not have sufficient resolution to time an event more closely than to the nearest five or six millisecon
153. ame Data Structure 0 R_TREE Object tree 1 R_OBJECT OBJECT 2 R_TEDINFO TEDINFO 3 R_ICONBLK ICONBLK 4 R_BITBLK BITBLK 5 R_STRING Pointer to free strings 6 R_IMAGEDATA Pointer to free image data 7 R_OBSPEC Ob_spec field of OBJECT 8 R_TEPTEXT Te_ptext field of TEDINFO 9 R_TEPTMPLT Te_ptmplt field of TEDINFO 10 R_TEPVALID Te_pvalid field of TEDINFO 11 R_IBPMASK Ib_pmask field of ICONBLK 12 R_IBPDATA Ib_pdata field of ICONBLK 13 R_IBPTEXT Ib_ptext field of ICONBLK 14 R_BIPDATA Bi_pdata field of BITBLK 15 R_FRSTR Ad_frstr the address of a pointer to a free string 16 R_FRIMG Ad_frimg the address of a pointer to a free image index int_in 1 The array index within the structure where the address will be placed address addr in 0 The actual address that will be placed within the data structure 301 rsrc_saddr Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also rsrc load rsrc_gaddr 302 pd d d 3j d I NEN ud x ud LL L L Nm f L Lt rsrc_obfix Fix Object Location and Size rsrc_obfix Opcode 114 This function is used to change an object s location and size fields from the character based coordinate system used in resource files to absolute pixels coordinates It is called internally by rsrc_load C binding int status object struct object tree status rsrc_obfix tree object
154. amp y amp width amp height form dial FMD START x y width height objc draw dialtree ROOT MAX DEPTH x y width height Main dialog animation loop 7 Ld xd i t ot ae r 1 td L L L L L EL L LE The Graphics Library until exit button hit while exitbutn form do dialtree 90 EXITBUTN exitbutn amp x7fff mask off top bit of exit object set by clicks on TOUCHEXIT if exitbutn SLIDER if exit object was SLIDER c allow slider to be dragged slider pos 5 graf slidebox dialtreo SLIDEBAR SLIDER 1 set new SLIDER y position use longs to avoid overflow amp dialtreetSLIDERJ ob y long slider_pos X long dialtreeLSLIDEBARJ ob height dialtreetSLIDERJ ob height 1e499g redraw slider in new position objc draw dialtree SLIDEBAR MAX DEPTH x y width height display new postion by changing text of NUMBER object t sprintf strptr 4d slider pos redraw text x and redrawing the object objc_draw dialtree NUMBER MAX DEPTH x y width height end of if TOUCHEXIT end of main WHILE loop form dial FMD FINISH O 0 x y width height 3 end of DEMO function t XXX KK KE KEE Draw user defined object X t k amp tkxs fEXERXTEREXXXEESZZXz k drawcode pb Sample user object drawing amp PARMBLK pb
155. and notes the size and position of the rectangle enclos ing this area Then it checks each open window to see if any portion of the window s work area overlaps that rectangle It then sends the application a separate redraw message for each window that needs to be refreshed The format for this mes sage is as follows Lx XX MEM I ud uj L ELLELE L L L tL AES Events Word Number Contents 20 WM_REDRAW the message ID number The handle of the window whose display needs refreshing The x position of the damaged rectangle The y position of the damaged rectangle The width of the damaged rectangle The height of the damaged rectangle When your program receives the WM REDRAW message there is a set pattern of steps that you must take to restore the contents of that window First you must stabilize the state of the screen so that no changes take place during the update process Turn off the mouse with the graf_mouse call graf_mouse M_OFF 0x0L The reason for hiding the mouse pointer is that the AES stores the image of the rectangle underneath the mouse and restores that image when the mouse is moved If you merely overwrite the mouse with your graphics output the next time the mouse is moved the system will restore the previous im age wiping out a rectangle of your new display The second part of stabilizing the screen display is to lock the screen with the wind_update call The format for
156. annot be opened again until the wind_create call is used to allocate them again C binding int wi handle status status wind delete wi handle Inputs control 0 103 Opcode control 1 1 Number of 16 bit inputs in int Lin array control 2 1 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr iin array control 4 0 Number of 32 bit results in addr_out array wi_handle int in 0 The ID number of the window to be deleted Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also wind create wind_close 288 E 2 ee j a d 4 L t tL t L i irit mM wind get Get Window Information wind get This function can be used to learn about the size and position of the win dow rectangle and its scroll bars C binding int status wi handle flag x y width height status wind get wi handle flag amp x amp y amp width amp height Inputs control 0 control 1 control 2 control 3 control 4 wi handle int in 0 flag Flag o Qo SO Ur i 16 17 int in 1 Macro Name WF_WORKXYWH WF_CURRXYWH WF_PREVXYWH WF_FULLXYWH WF_HSLIDE WF_VSLIDE WF_TOP WF_FIRSTXYWH WF_NEXTXYWH WF_RESVD WF_HSLSIZE WF_VSLSIZE WF_SCREEN li i vt OON Opcode 104 04 Opcode Number of 16 bit inputs in int
157. ar The third reads Turn the Next Item ON and has the name TOGLITEM The fourth is a disabled sting that reads Print Message in faint letters The alert string called called ABTALERT has four string lines The first reads Menu demo with check marks the second reads graying and alternate text and the third reads Select Quit to end The fourth line is made up of dashes The string in the button should be edited to read I ll remember that You ll also have to create two free strings The first is called OFFSTRNG and reads Turn Next Item OFE while the second is called ONSTRNG and reads Turn Next Item ON If you don t have a resource construction program you ll be able to build the resource file needed for this example by running the RSCBUILD C program in Appendix C 152 29323 mm t o MW V ad Chapter 6 Interactive Object Handling Forms and the File Selector L L LL The hi est level of AES object routines are so sophisticated that they re more like large subprograms than simple functions The programs in the Forms and File Selector Library perform all the same functions as the sample object programs from Chapter 4 and more They display a set of ob jects called a form which is loaded as one of the object trees in the resource file They check for significant AES events and handle all of the user s interaction with these objects Finally when they ve detected an event that ends the interact
158. ard features like dialog boxes alert boxes icons and file selectors provide a comfortable frame of reference even when you re using programs you ve never seen before CHAPTER 1 From the programmer s standpoint GEM makes it easy to provide the user with such advanced features as overlapping windows drop down menus and icons These features would be difficult for programmers to implement without the GEM environment GEM also offers portability for programs among the various versions of the ST and also limited portablility to the IBM PC and compatibles GEM also includes facilities to provide output without regard to the device specific resolu tion This is of particular interest now that Atari has an nounced plans to introduce a laser printer The programmer should keep in mind however that portability has its price A more generalized program will al ways be slower and less efficient than a more specific one Al though the ST has a fast and powerful processor its operations will slow down if GEM has to do a lot of internal coordinate conversion and range checking Programmers may find that in some cases they must use more device specific methods to achieve the desired level of performance While portability is nice you ll have to decide what performance compromises are acceptable in order to gain its benefits GEM Organization Though GEM is spoken of as a single entity it s actually made up of a number of parts The two major d
159. as follows Address Element Control Parameter control control 0 Command opcode operation code control 2 control l Number of integer inputs passed in int in control 4 control 2 Number of integer results returned in int out control 6 control 3 Number of input addresses passed in addr in control 8 control 4 Number of addresses returned in addr out The first element of the control array is used to pass the opcode Since all of the AES routines have a common entry 11 CHAPTER 1 point there has to be some way to tell the AES which com mand is to be executed Therefore each command is given an identification number called an opcode These opcodes are grouped by library The Application Library uses opcodes 10 19 the Event Library uses opcodes 20 26 and so on The remaining four elements are used to indicate how an AES call utilizes the parameter arrays int in int out addr in and addr out The two input parameter arrays int in and addr_in are used by the application to pass values to the AES library calls These arrays give the function call information about how the application wants the calls to operate The two output parameter arrays int out and addr_out are used by the AES library to return results to the application The last four control array elements are used to indicate how many pa rameters are being passed in each direction The application uses control 1 to specify the number of input integers be
160. avoid overwrit ing the window borders You can use the wind get function to find the window s interior dimensions as follows Zinclude lt GEMDEFS H gt int status wi handle workx worky workw workh status wind get wi handle WF WORKXYWH amp workx amp worky amp workw amp workh While wind get can be used to find the current interior or exterior dimensions of a window it isn t of much help before you ve created the window Let s say for example that you want to open a window whose interior work area will be 200 X 100 pixels and whose top left corner will be located at 50 50 How can you determine the exterior dimensions of such 33 CHAPTER 2 a window in order to pass them to the wind open call One way is to use the wind calc function Given the win dow control flag and either the interior or exterior dimensions of the window this function can return the opposite set of di mensions Its syntax is int status type controls knownx knowny knownw knownh otherx othery otherw otherh status wind_calc type controls knownx knowy knownw knownh amp otherx amp othery amp otherw amp otherh The dimensions of the known window area are specified by knownx knowny knownw and knownh The function returns the other set of dimensions in otherx othery otherw and otherh Type is a flag byte showing what type of conversion to perform A 0 value means to consider the known dimensions t
161. ays For example to execute the graf mouse command to change the shape of the mouse pointer you would transfer the following values move 78 control Move the graf mouse opcode 78 to control 0 move 1 control 2 Move the length of int Lin array 1 to control 1 move 1 control 4 Move the length of int out array 1 to control 2 move 1 control 6 Move the length of addr_in array 1 to control 3 move 0 control 8 Move the length of addr_out array 0 to control 4 move 3 int_in Move the mouse pointer shape code to int in 0 Now you re ready to call the AES First place the address of the AES parameter block into register d1 Next move the AES identifier code 200 or C8 into register d0 Finally call the AES with a trap 2 instruction This initiates a software generated exception similar to a hardware interrupt that causes execution of an exception handler routine In this case the routine executed is the one whose address is pointed to by the long word beginning at location 136 88 This routine is the one used to handle all GEM VDI and AES calls VDI calls are identified by placing a value of 115 or 73 into register d0 The instruction sequence used for making a AES call looks like this movel apb d1 Move address of AES parameter block to d1 move l C8 d0 Move AES identifier C8 into d0 trap 2 call GEM entry point Please note that the procedures outlined above just cover the steps required t
162. be entered in the text string cursor posi tion after objc_edit has been performed See also form do 256 J d r i i A J LO L L Ee d C obic change Change Object s State Flag objc change Opcode 47 This function is used to change an object s ob state flag Since this change may affect the object s appearance on screen the function allows the pro grammer to request a redraw of the object when its state is changed A clip ping rectangle may also be specified and only objects within this rectangle are redrawn C binding int status object reserved clipx clipy clipw cliph state redraw struct object tree status objc_change tree object reserved clipx clipy clipw cliph state redraw Inputs control 0 47 Opcode control 1 8 Number of 16 bit inputs in int_in array control 2 1 Number of 16 bit results in int_out array control 3 1 Number of 32 bit inputs in addr in array control 4 O Number of 32 bit results in addr out array object int in 0 The object number of the object whose state flag is to be changed reserved int_in 1 Reserved for future use must always be 0 clipx int_in 2 The horizontal coordinate for the left side of the clipping rectangle clipy int_in 3 The vertical coordinate for the top edge of the clipping rectangle clipw int_in 4 The width of the clipping rectangle in screen pixe
163. ber of 16 bit results in int_out array control 3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr out arra object int_in 0 The object number of the child to be moved newpos int_in 1 A code specifying the new position at which to place the object 1 on top 0 on the bottom 1 one from the bottom 2 two from the bottom and so on tree addr_in 0 The address of the object tree array which contains the objects Results status int out 0 Error status code Q an error occurred during execution gt 0 no error occurred during execution See also objc_add objc_delete 3 d 399 d UL LLELE mm mn oe it L L E objc edit Let User Edit Text Objects objc_edit Opcode 46 This function allows the user to edit the text that appears in a G_FTEXT or G FBOXTEXT object It is used by the AES as part of the form do call and is not ordinarily a function that would be used unless the application programmer was writing his or her own version of form do C binding int status object char index type struct object tree status objc_edit tree object char amp index type Note This binding varies from the format specified by the Digital Research documentation which adds a parameter for the ending index to the end of the parameter list The binding shown above however is the one actually supplied by Atari w
164. ber of 32 bit results in addr out array Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also appl_init 229 evnt_keybd Wait for Keyboard Event evnt_keybd Opcode 20 Waits for the user to press any key and returns the appropriate keycode C binding int keycode keycode event_keybd Inputs control 0 20 Opcode control 1 0 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int_out array control 3 0 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array Results keycode int_out 0 Keycode value for the key pressed See Appendix B for meaning of keycodes See also evnt_multi 230 Jod d ul x L LL L UL L EL evnt button Wait for Mouse Button Event evnt button Opcode 21 Waits for the user to press a particular combination of mouse buttons a spec ified number of times and returns information about the mouse button state and the shift key state C binding int clicked clicks bmask bstate int mousex mousey button shiftkey clicked evnt button clicks bmask bstate amp mousex amp mousey amp but ton amp shiftkey Inputs control 21 Opcode control 1 3 Number of 16 bit inputs in int_in array control2 5 Number of 16 bit results in int_out array control 3 0
165. blue 13 Light cyan 14 Light yellow 15 Light magenta wOco 3o9g OS CO ND mm These colors are only the default values The color con tained in any particular color register can be changed by the user at any time from the Control Panel desk accessory These colors may also be changed by a program that uses the vs color command It s worth noting that while any color number in the range 0 15 is valid medium resolution screens can only display the first four colors while monochrome 105 CHAPTER 4 screens are limited to the first two Any out of range selections will be treated as color 1 black on these displays The low byte of the high word of the ob spec field of box objects is used for the thickness of the border 127 to 1 Outside thickness in pixels outward from object s edge 0 No thickness 1to 128 Inside thickness in pixels inward from object s edge Since the VDI drawing routines used to render wide lines only respond to odd numbered settings the border thickness value that you specify should be an odd number The high byte of the high word is used only for the G BOXCHAR object type It contains the ASCII value of the character drawn in the box The chart in Figure 4 3 summa rizes the flags stored in the 32 bit objc_spec field of box objects Figure 4 3 Summary of Flags Stored in 32 Bit Objc Spec Field of Box Objects riting Hode 0 Transparent 1 Replace 31 24 ASCII value Border Thickness Ne
166. cc c acc o sample acc With Alcyon C the linker command would look like the following LINK68 U deskacc 68K accstart deskacc vdibind osbind aesbind libf gemlib libf Remember that the executable program must be named with an extender of ACC instead of PRG In this case the program was given the name SAMPLE ACC A machine language version of this desk accessory pro gram appears below for the benefit of those who choose to program in that language Since machine language programs contain their own startup code that code was merely edited 209 CHAPTER 8 rather than linked with another startup file The program be low contains the startup code and therefore should not be linked with the AESSHELL O object file Unlike the other ma chine language examples in this book it s a complete program by itself Program 8 2 deskacc s kXk5ikXkzki kXkkXxtkXxtzit 2it5Sk ti5tttgXszs SEEXSkkdtkkk kgtS9kkkk5xstkttttfy x DESKACC S Assembly language version of desk accesory program drawn from MESSAGE S x x 355 5395 555XxX542525 55255222 23352425225 354552x5222252322242 2 232332252522 1 X Program equates aescode c8 command number for AES call vdicode 73 command number for VDI call Program starts here Set address of our stack text move I accstk a7 set stack pointer to our stack gg Initialize the application with appl init move 1 40 resvi clear global variables
167. cellh boxw boxh phys_handle graf_handle amp cellw amp cellh amp boxw amp boxh Inputs Results phys_handle cellw cellh boxw boxh 276 controlf0 77 Opcode control 1 0 control 2 5 control 3 0 control 4 0 int out 0 int out 1 int out 2 int out 3 int out 4 Number of 16 bit inputs in int in array Number of 16 bit results in int out array Number of 32 bit inputs in addr_in array Number of 32 bit results in addr out array The VDI handle for the current physical screen workstation The width in pixels of a character cell in the default system font the one used to render text in menus and dialogs The character cell is the entire space taken up by each character including the intercharacter spacing The height in pixels of a character cell in the default system font the one used to render text in menus and dialogs The width in pixels of a box surrounding a character cell in the default system font Several GEM objects such as vertical scroll bars the close box and size box are boxw pixels wide The height in pixels of a box surrounding a character cell in the default system font Several GEM objects such as horizontal scroll bars the title bar information line close box and size box are boxh pixels high cou VE Gd L LO L L LLELLE graf mouse Change the Mouse Pointer graf mouse Opcode 78 Changes the shape o
168. ch indicated whether the item is selected see the SELECTED flag below and redraws the entire object rectangle in reverse video to highlight the object The select mechanism works as a toggle If the object is selected and the user clicks on it it is deselected While the AES takes care of the details of updating the object state flag and the video display it is up to the appli cation to check the SELECTED flag and if it is set perform the specified task The DEFAULT flag A related flag is the DEFAULT flag The form do library function uses this flag in handling key board events during a dialog If the Return key is pressed the de fault object is automatically selected and the dialog is concluded Note that the default object may be selected even if the SELECTABLE flag is not set or if the DISABLED state flag is set and that selecting the default object with the Return key causes the dialog to exit whether or not the EXIT flag is set for this ob ject The AES makes some default objects such as buttons or boxes with an outside border visually distinct by thickening the border surrounding them by one pixel For that reason you should only set the DEFAULT flag for one object in a dialog since the AES will only select the first default object it finds and you don t want to mislead the user into thinking that another one is the default In a dialog you ll often see a button such as OK or CANCEL with a thick box around it indicating
169. ck Stor age Segment which is used to store uninitialized data To find the total size of the program area look in the basepage area to find the size of the code Add that to the size of the data and BSS segments along with the size of the basepage it self Since you need a stack area for the program it makes sense to add the size of the stack to the end of the program and reserve the combined program and stack area together Figure 2 2 Once you calculate this area you can set the stack pointer to the top of program memory and make the SETBLOCK call When that is done continue on with what ever your program does Figure 2 2 Layout of Transient Program Area in ST Memory GEnd of TPA BSS Segment Text Segnent Basepage 28 Length of BSS Segment Basepage 24 Address of BSS Segnent Basepage 20 Length of Data Segnent Basepage 16 Address of Data Segnent Basepage 12 Length of Text Segnent Basepagets Address of Text Segment Basepage 4 Address of End of TPA L Basepage Base Address of TPA High Memory Stack Pointer Low Memory Start of TPA 48 Aod d J3 J A LN EUN zT CLCC Co ba 7 L Starting an Application In order to assemble the aesshell s program with the Alcyon assembler invoke the as68 assembler with the follow ing command as68 u l aesshell s This creates an object file called aesshell o Since this pro gram does not c
170. cludes all of the information required for such a descrip tion This structure is defined in the header file OBDEFS H which is included with most C compilers for the ST as follows typedef struct grect int g x int g y int gw int gh GRECT The use of typedef means that you can declare a structure of the type grect either by using the declaration form struct grect rectangle or the form GRECT rectangle In either case the x coordinate is denoted by rectangle g x the y coordinate by rectangle g y the width by rectangle g_w and the height by rectangle g_h Using such a data structure makes it possible to reference all the necessary information about a rectangle using a single variable or pointer As the function template above shows the wind create function returns a value called wi handle If the function suc cessfully allocates a window the value returned is a unique ID number known as the window handle This window handle is used to identify the window for purposes of the Window Li brary routines which can modify a window or return infor mation about it A handle of 0 is reserved for the GEM 28 Jil Jod dJ J L L L E LL Starting an Application Desktop window A value in the range 1 8 is used for the application windows If the AES is unable to allocate a new window a negative value is returned in wi_handle In the current version of GEM on the ST the AES will only let yo
171. code rsrc objfix 1 ctril 1 intint 1 ctri2 1 intout 481 ctr13 1 addrin 4tree addrin pass tree address d4 aintin use loop index for object number aes d4 fixloop decrement and do again if not done Draw the objects move move move move move move move jar 42 ctr1d opcode objc draw 46 ctr11 6 intin s l aintint 2 draw down one level workx aintin 4 g set clip x y W h worky aintin t workw aintin 8 workh aintin 19 aes 3 Wait for button press loop move move move move move move move jsr 4 21 ctr19 opcode evnt button 3 ctrli 5 ctr12 3 ctris i aintin 1 click left button only 41 aintin 2 41 aintin 4 aes x See if button pressed while mouse was over EXIT object move move move move move move move jsr cmpi bne rts 43 ctr1d opcode objc_find 44 ctr11 41 ctr12 1 ctr13 N aintin start searching at root aintout 2 aintin 4 i use mouse x and y for position aintout 4 aintin s aes 1 aintout object 1 found loop if not chack again ggs Storage space and data constants 127 CHAPTER 4 data seven wdwtitl s wdwinfo wdwetris exitstr pushstrs tree objcli ob jc23 dc b dc b dc w dc b dc bd dc 1 dc 1 dc 1 dc 1 dc 1 dC 1 dc 1 dc 1 Object Example X text of window title 9 1 EXIT 0 text of wi
172. codes to PC DOS codes This is done by reversing the sign of the code from negative to positive and then subtracting 31 DOS ERR TOS ERR 31 The following chart lists the GEMDOS error codes for which form_error prints error specific messages as opposed to TOS error X and gives the complete text of those messages GEMDOS PC DOS Error Number Error Number 33 34 35 36 39 41 42 46 156 2 10 11 15 Error File not found Path not found File handle pool ex hausted no file handles left Access denied wrong attribute or access code Insufficient memory Invalid environment Invalid format Invalid drive specification Error form error Message This application can t find the folder or file you just tried to access This application can t find the folder or file you just tried to access This application doesn t have room to open an other document To make room close any document that you don t need An item with this name already exists in the direc tory or this item is set to Read only status There isn t enough mem ory in your computer for the application you just tried to run There isn t enough mem ory in your computer for the application you just tried to run There isn t enough mem ory in your computer for the application you just tried to run The drive you specified does not exist Check the drive s ide
173. correct bindings 21 startup file 39 ctrl 50 data arrays beginning addresses 12 deallocating memory 47 desk accessories 201 19 entering text strings into menu 202 loading 201 2 menu items 202 3 problems 219 returning to Desktop 203 writing 201 3 J dJ J KE RE RR J 3 LOCEL W de b L i Desk Accessory Buffer 9 10 DESK conventions 142 Desktop 9 Desktop work area 24 dialog boxes 159 64 169 70 animating 159 63 bugs 169 70 deselecting exit button 164 drawing 163 noting new selection settings 164 releasing screen area 163 64 reserving screen area 161 62 reverse zoom box 163 zoom box 162 display screen locking 57 DNARROW 78 double click 118 double click speed setting 88 drag bar 67 drop down menus 140 dummy 16 80 environment services 3 error box 155 Event Library 5 8 events 92 evnt button 88 90 bug 90 button variable 89 clicks 88 exitbutn 158 extended BIOS See XBIOS FIFO First In First Out 54 File Selector 170 75 choosing files 171 deleting wildcards 174 displaying dialog box 171 72 getting a pathname 172 74 getting current directory 173 74 restoring screen display 172 File Selector Library 8 155 75 flag 29 30 foreground pens 189 form dial 161 64 action flags table 162 FMD FINISH 163 FMD_GROW 162 63 FMD SHRINK 163 FMD START 162 forcing a redraw 164 form do 108 159 61 handling object selection 160 61 problems 170 Form Library 8 155 75 forms 155 57 full
174. cpyfm CHAPTER 3 Mouse Button Events The next type of event is the mouse button event This func tion does much more than merely wait for the user to push a button It allows you to specify the particular combination of buttons you are waiting for whether you want those buttons to be pressed or released and the number of button clicks you want to wait for as well To wait for a mouse button event call eunt button int clicked clicks bmask bstate mousex mousey button kstate clicked evnt _button clicks bmask bstate amp mousex amp mousey amp button amp kstate The input parameter clicks lets the AES know the maxi mum number of button clicks you re waiting for If you re in terested in double clicks as well as single clicks enter the number 2 for clicks If you re only interested in single clicks make clicks equal to 1 When a button is first pressed GEM starts timing a short interval For each time that the button goes up and down again during that interval it adds one click to its count The actual number of clicks is returned in the variable clicked GEM doesn t check the number of clicks however if you re waiting for more than one button The length of time during which GEM counts clicks de pends on the current double click speed setting This setting may be changed from the Control Panel desk accessory that comes with the ST to any of four settings It s also possible to change this time interval
175. ctangle second mouse in screen pixels Low word of the 32 bit timer value High word of the 32 bit timer value Together the low and high timer words form a 32 bit timer value which specifies the period of time the function should wait in milliseconds The address of a 16 byte buffer in which the AES will store the message IM ee MM MN JJ eR aud acd Lt L i LO L LEC Results happened mousex mousey button shiftkey int out 0 int out 1 int_out 2 int_out 3 int_out 4 Bit Bit Value Key 0 1 2 3 keycode clicked See also 1 2 4 8 Right Shift Left Shift Control Alt int_out 5 int_out 6 evnt multi A code which specifies the type of event which actually happened The code used is identical to that used for events above The final horizontal position of the mouse pointer _ The final vertical position of the mouse pointer The final mouse button state 0 both buttons up 1 left button down right button up 2 right button down left button up J both buttons down The status of the keyboard shift keys Each key is represented by a different bit A 1 in that bit position means that the key is down while a 0 means that it s up The code number for the key combination pressed by the user See Appendix B for a complete list of keycodes The number of times the mouse button state actually matched bstate This is al ways a number bet
176. ddress pointers to the beginning of each object tree Then it stores the address of the Tree Index array in the ap ptree field of the application s Global data array Since the rsrc_load process allocates some of the com puter s free memory you should always remember to give that memory back when you end your program And though your program will only load one resource file in most cases if you want to load more than one you must unload the first before loading the second In either case the call you use is rsrc_free int status status rsrc_free Once you ve loaded a resource file you can find out the addresses of the various data structures it contains by using the rsrc gaddr Library call The syntax for this call is int status type index long address status rsrc_gaddr type index amp address 136 d 1 REDE U L L4 SA ad x L L EL tL L ll C E Resource Files and Menus where type specifies the type of data structure index gives the po sition within the data array and address is the variable which holds the address to be placed in the data structure The types of data structures whose addresses you may find with this function and the macro names assigned them in the GEMDEFS H header file are as follows Type Number Macro Name Data Structure 0 R TREE Object tree 1 R_OBJECT OBJECT 2 R_TEDINFO TEDINFO 3 R_ICONBLK ICONBLK 4 R_BITBLK BITBLK 5 R_STRING Pointer to free s
177. de re served variables for the data arrays such as GEM ADDRIN GEM ADDROUT GEM CONTRL GEM GLOBAL GEM LINTIN GEM INTOUT and a STATUS variable to re turn information from AES calls Even so BASIC programmers will still have to learn the details of making AES calls if they want to take full advantage of GEM Calling the AES Routines from C It s much easier to make AES function calls from C than from either machine language or BASIC That s because C compiler packages for the ST include one or more function libraries known as GEM bindings These bindings are object code li brary files that define a separate named function for each GEM call When the C program is linked to the proper library files it can call GEM functions as if they were part of the C language These library files also allocate storage space for the data arrays But the programmer is not responsible for placing data directly into these arrays Instead input parameters are passed to the binding functions as part of the function call For example you could execute the graf mouse command performed by the BASIC and machine language programs like this int dummy shape 3 graf_mouse shape amp dummy The function defined as graf_mouse in the library takes the parameter shape that s passed to it puts it in int_in 0 and puts the address of the parameter dummy in addr in 0 It also puts a 1 in control 1 control 2 and control 3 a 0 in con
178. dial FMD FINISH x y width height X Sub function to check dialog objects t5 5 check ob js exitbutn Le int exitbutn int x dialtree BgBxitbutn ob state SELECTED amp de select exit button for x YUNGBUTN xCXOLDBUTNE1 3x check radio buttons amp 1 if dialtreetxJ ob state amp SELECTED if exitbutnzzOKBUTN agestx YUNGBUTN3 increment age dialtreetxJ ob state SELECTED reset buttons Y for xsSTBOX x lt COTHERBOX 1 3x check select boxes X c if dialtreetxJ ob state amp SELECTED if exitbutn OKBUTN computers x STBOXI increment computers dialtree x1 ob state e SELECTED reset buttons 7 J J 14 Interactive Object Handling if strlen strptr gt d amp amp exitbutn OKBUTN strcpy lastxt strptr 4 if string not empty copy strptrr 2129 clear object string i 4288886 Sub function to handle window refresh 2 2 2 925 59 259 refresh wh drect routine to handle window refresh WM REDRAW LO LLL int wh window handle from msgt353 t GRECT amp drect pointer to damage recatangle GRECT wrect amp the current window rectangle in rect list MOUSE OFF turn off mouse wind update BEG UPDATE lock screen wind get get first rectangle wh WF FIRSTXYWH amp wrect g x amp wrect g y amp wrect
179. dle 9 form alert 1 L2JLCan t open accessory No windows left JtOK3 v_clsvwk handle if we can t close workstation return WDOW_ERR 3 and return error code 2 wind set wi handle WF INFO APP INFO 9 9 wind set wi handle WF NAME APP NAME 9 9 t set name and info string for window amp wind open wi handle desk g_x desk g y desk g_w 2 deuk g h 2 j open the window to quarter size tj i ud d xd Se J yak ol it i L hs do i Ll L Desk Accessories return g report no errors amp b routine to handle WM FULLED message t toggle wh int wh GRECT prev curr full get current previous and full size for window wind get iwh WP CURRXYWH amp curr g_x amp curr g y amp curr g_w amp curr g_h 3 wind get wh WF PREVXYWH amp prev g x amp prev g y amp prev g_w amp prev g_h 3 wind get wh KF FULLXYWH amp full g x amp full g y amp full g w amp full g h j If full change to previous unless that was full also if curr g x full g_x amp amp curr g_y full g_y amp amp curr giw 22 full g iw amp amp curr g h 22 full g_h amp amp prev g x 2 full g_x i prev g y 2 full g_y prev g w full g w prev g h full g h c wind set wh WF CURRXYWH prev g x prev g y prev g_w prev g h j redraw msg wh amp prev X send a redraw message
180. dow when the wind set command is used to increase its size In some 65 CHAPTER 3 cases your program may want to reshuffle the display when the window is sized down as well You can accomplish this either by calling the redraw routine directly or by sending yourself a redraw message after changing the size with wind set Another way the user can indicate a desire to change the size of the window is by clicking on the fuller box If the win dow controls flag for your window includes the fuller attribute indicating that the window has a fuller box in the top right corner your program should be prepared to handle message 23 WM FULLED The relevant items in the message buffer for this message are Word Number Contents 0 23 WM_FULLED the message ID number 3 The handle of the window whose full box was clicked The fuller box is supposed to act like a toggle That means if the window isn t at full size when the user clicks on it it s supposed to expand to full size If the window is already at full size when the user clicks the window should contract to its previous size As usual it s up to you to implement this toggle mechanism The AES helps out by keeping track of the window s current size its maximum size and its previous size You may determine all three of these window dimensions by calling wind get with the appropriate subcommand WF_CURRXYWH WF_PREVXYWH or WF_FULLXYWH After you ve found out the size and p
181. ds A timer event can be used to pace the action of your pro gram or to provide a limit on the amount of time that your program will wait for a particular action If you specify a time count of 0 the function returns immediately This do nothing event can be used periodically in your program if no other AES calls are made to maintain Screen Manager function As stated in Chapter 1 the multitasking kernel can only switch tasks when the current one makes an AES call Multiple Events Although each of the event calls was explained separately there s a way to wait for any or all of these events at once The evnt_multi call lets you wait for a timer event keyboard event message event mouse button event and up to two mouse rectangle events all at the same time The format for this call is happened evnt multi events clicks bmask bstate miflag mirectx mlrecty mlrectw mlrecth m2flag m2rectx m2recty m2rectw m2recth msgbuf timelo timehi amp mousex amp mousey amp button amp kstate amp keycode amp clicked Most of these input parameters and output parameters should be familiar from the explanations of the individual event calls Only the variables events and happened are new These are flags which indicate which events you asked to wait for and which events actually occurred Possible flag values include Bit Bit Value Macro Name Event 0 1 MU KEYBD Keyboard 1 2 MU BUTTON Mouse button 2 4 MU_M1 Mouse r
182. e 39 the correct position setting is 1000 39 80 or 487 which is significantly more than double the earlier set ting of 216 Where the portion of the display shown in the window is less than the total amount available for display you can calculate the slider position with this formula position 1000 window start total length length seen where window start represents the position that s displayed at the beginning of the window For example if line 40 of a doc ument were displayed at the top of the window window start would be 39 because it s conventional to start counting the display position at 0 That way if you re at the top of the doc ument the slider position is 0 0 divided by any number is al ways 0 rather than some small fractional position number Remember also that if the length seen is equal to or greater than the total length the slider size is 1000 you must always position the slider at 0 Once you ve calculated the correct slider position you position it with the WF HSLIDE or WF VSLIDE subcommand of wind_set wind set wi handle WF VSLIDE position 0 0 0 wind set wi handle WF HSLIDE position 0 0 0 You ll know it s time to update the position of the slider when you get one of the window messages associated with the scroll bar For example when the horizontal slider is moved message 25 WM_HSLID is sent Word Number Contents 0 25 WM_HSLID the message ID number
183. e WM SIZED message and will have sized the window with wind set When the size of the document changes because the user deleted a line of text for example you should update the slider size only if the change alters the proportions significant ly After calculating the new size check it against the current size You can find the current slider size by using the 79 CHAPTER 3 WF_HSLSIZE and WF VSLSIZE subcommands of wind get wind get wi handle WF VSLSIZE amp size amp dummy amp dummy amp dummy wind get wi handle WF HSLSIZE amp size amp dummy amp dummy amp dummy where size is the variable in which the current size is returned and dummy is a dummy place holder variable which must be used because wind get returns four values If the new size is equal to the old size you needn t update it Slider position The second part of the task of maintain ing scroll bars is keeping track of the slider position As with slider size the slider position setting has a range of 1 1000 But this setting is tricky It doesn t reflect the abso lute position of the slider within the scroll bar Instead it marks the position of the top of the slider bar relative to its possible range of positions Since the slider itself can take up a significant portion of the scroll bar the top of the bar usually can t go down to the bottom of the scroll bar For example if the window display shows 20 lines of a 200 line t
184. e character in an editable text field the machine crashes immediately Although Atari has promised to fix this rather serious flaw in the next version of the operating system programmers might be wary 169 CHAPTER 6 of using this potentially disastrous routine in their programs The most serious problem with form do is that the rou tine takes complete control of the program until the user hits the exit button That means that while form do is executing the user is stuck with providing input to the form and can t do anything else The menu system doesn t work while a dialog is on screen and if the user clicks on an object outside of the dialog box all that happens is that a bell sounds The reason for this is that form do itself uses the evnt multi call and only checks for keyboard and mouse button events The evnt multi call takes place in a loop that keeps repeating until an exit condition occurs Many programmers consciously try to avoid program modes Form do is modal by its very nature since it puts the user into a form input mode where he can do nothing but en ter information and where normal program features like menus don t work Programmers who wish to design modeless programs which allow the user to click on ob jects enter text and use menus all at the same time must therefore write their own form do equivalent integrating its evnt multi call into the program s main evnt multi loop Tim O
185. e current display resolution mode Fi nally you have to calculate all the links that define their vari ous parent child relationships Because objects are an integral part of GEM and because they re so difficult to build from data Digital Research devel oped a system which can create object data The system makes use of Digital Research s Resource Construction Set or a similar program The Resource Construction Set is one of the best fea tures of GEM It takes the effort out of creating objects and it allows you to position them relative to one another change their parent child relationships enter text and set the various attribute flags and object state flags for each object Once you ve created the object data with the program you may save it to a resource file This is a data file ending with the RSC extender For instance STBASIC RSC is the re source file for the STBASIC PRG program When the resource file is created the AES Resource Library routines enable your program to load the file create the object structure data array from the information loaded and find the addresses of indi vidual object trees within that array 131 CHAPTER 5 Using resource files and a resource construction program has several fringe benefits besides making the object creation process quick and easy First it helps make the program more portable both to other machines such as the IBM PC and within the various display resolution modes of the
186. e for the background User Defined Objects The final object type is the most flexible of all It is the user defined object type G PROGDEEF in some versions of the OBDEFS H file the macro name for this type may be G_USERDEF This type allows the programmer to create ob ject types with an appearance different from the standard box string or image objects For example you might create an ob ject type that consists of a box with rounded corners or a circle The ob spec field of a G_PROGDEF object contains a pointer to a data structure called an APPLBLK in some ver sions of OBDEFS H it may be called a USERBLK The C lan guage definition of this data structure is typedef struct appl_blk long ub_code long ub _parm APPLBLK As you can see it consists of two long word values The first is a pointer to the function supplied by the user for draw ing the object The second is a user defined parameter that s passed to the routine when the drawing takes place This pa rameter is passed as part of a larger block of information called a PARMBLK structure The AES calls the user defined drawing function when ever the G_USERDEF needs to be drawn or modified This occurs when the objc_draw routine is used to draw the ob ject or the objc_change routine is used to change its state Say for example the ub code field of an object s APPLBLK points to the function user_draw Whenever that object is due to be drawn
187. e in state and outstate variables should hold the value of the object s ob state flag when the pointer is inside the object rec tangle and when it s outside the rectangle respectively For example a SELECTABLE object will be SELECTED when the pointer is over it and not SELECTED when the pointer is away from it This allows the routine to change the state of the object and redraw it as the pointer is dragged When the user lets the left mouse button up the routine returns a flag in the variable in or out that indicates whether the pointer 185 CHAPTER 7 ended up inside or outside of the object rectangle A value of 0 indicates that it was outside the rectangle while a value of 1 indicates that it ended up inside The last box graphics functions are used mainly for cos metic purposes The first is used to draw the outline of a box moving from one point onscreen to another It does this by drawing a series of boxes from the source point to the destina tion point one by one and then erasing those boxes one at a time in reverse order All of this happens so quickly that the user gets the impression that something is zooming across the screen Unless used to indicate a transition from one window another this effect is mere window dressing and as such is al most always superfluous The function used to create the ef fect is called graf mbox int status width height beginx beginy endx endy Status graf mbox width heig
188. e letter the subdirectory path and the filename using a wild card such as C N WORDPROCN L ETTERS DOC The filename can be used to specify a default file or may be left blank These same two variables are also used by fsel_input to return the path names and filenames selected by the user If the Cancel button was selected however the original values will be unchanged upon exit from this routine The exitbutn variable is where the routine returns the number of the button used to exit the dia log 0 Cancel 1 OK The screen display isn t automatically restored upon com pletion of the fsel input call That s because the dialog box is larger in size than one quarter of the screen so the screen background can t be saved in the menu alert buffer There fore when the function ends the AES determines that the dia log rectangle is dirty and sends a WM_REDRAW to every application whose windows lay within the rectangle If your program is prepared to handle WM_REDRAW messages the display will be cleaned up as part of its routine message handling chores Note however that fsel input changes the current VDI clipping rectangle and doesn t change it back upon exit from the routine Therefore if your program does any VDI rendering after a call to fsel_input you ll probably have to set the clipping rectangle afterward whether you nor mally use clipping or not Program 6 2 demonstrates use of the fsel_input routine to
189. e missing from this shell however so the program will not link properly or run unless you add them yourself You have to add the function named demo and macro definitions for the window characteristics WOW_CTRLS APP NAME and APP_INFO The example will accomplish this through the use of the C include directive to include the file aesshell c at the beginning of most of the sample pro grams The main function of the sample program will be called demo and there will be macro definitions for the window characteristics For example to create a program that CHAPTER 2 does absolutely nothing but open a window and wait for the user to click on its close box you could use the code in Pro gram 2 1 Program 2 1 dummy c 5 5 99595 299595 5 5925 5 924292229292925292535229555492922222 99 5 2552222525255 DUMMY C A short calling program that uses the amp program template AESSHELL C It defines the amp window name and the window controls to be included amp It then waits a while and exits 1 amp 18 X EIS EEE TTT E SEEST FEE FESTE SEEST LETS St I FE define APP INFO Click on the Close Box to exit the program define APP NAME Dummy Title define WDW CTRLS NAMEICLOSERI INFO include aesshell c demot int msgbufL812 evnt mesage amp mnesgbuf skip the window redraw message X evnt_mesage amp magbuf amp wait for the window close message b d
190. e number in word 4 of the message buffer contains the menuid that was returned when the accessory called menu register You should be aware that this practice dif fers from Digital Research s GEM documentation which states that the menu ID is returned in word 3 of the message buffer You should also be aware that the GEM documentation shows the message numbers for AC_OPEN and AC_CLOSE to be 30 and 31 Actually they are 40 and 41 respectively When the user closes the main application program and returns to the Desktop the desk accessory s windows are automatically closed and deleted The AES informs the acces sory that this has happened with the ACC CLOSE message which has the following format Word Number Contents 0 41 AC CLOSE the message ID number 3 The menu item number of the desk accessory whose win dow handles have been lost due to closure of the main application The main difference between a desk accessory program and an application program therefore is that the desk acces sory usually doesn t open a window until its menu item is se lected and that the desk accessory program never ends and returns to the Desktop Though the desk accessory may close its windows or have them closed for it it always remains loaded in memory waiting for the user to select its menu item Therefore desk accessory programs are structured a bit differently from normal applications After a short initializa tion process during which t
191. e of windows and details about GEM graphics objects resource files and desk accessories to name only a few of the topics covered This is the second book in a series of three on the Atari ST The first concerned the Virtual Device Interface VDI COMPUTE s Technical Reference Guide Atari ST Volume Two The GEM AES takes you further into the underpinnings of the GEM interface Here is a list of only a few of the ST features covered in this book e Menus alert boxes and dialog boxes e input output through radio buttons mouse operation and boxes Sample programs written in C machine language and BASIC Resource development programs A complete AES Application Environment Services func tion reference e Full cross referencing of functions by name and opcode Sheldon Leemon has a long standing reputation for accuracy readability and the assurance of expertise In this book he continues his investigation into the inner work ings of one of the most versatile and popular computers on the market 1he Atari ST COMPUTE s Technical Reference Guide Atari ST Vol ume Two The GEM AES is the complete reference guide to the AES the heart of the ST s friendly interface ISBN 0 47455 114 5 19 95 51895 780874551143 i
192. e to do But in a multitasking system even a limited multitasking system such as GEM such programming tech niques aren t adequate While one task sits and waits all of the other tasks are slowed down or shut out completely For tunately GEM provides a much better method of waiting for input known as event oriented waiting Using the AES Event Library routines a program tells the AES that it must wait until a specified event happens The multitasking kernel then puts the program on the Not Ready list and lets the other tasks that are on the Ready list share the processor s time After the specified event occurs the kernel puts the program back on the Ready list and lets it execute again The AES Event Library allows the program to wait for a number of different types of I O events These include the usual types of direct input from the user such as typing on the keyboard moving the mouse and clicking a mouse but ton These I O events also include a more sophisticated indi rect type of input called a message The Screen Manager sends these messages to let the program know that the user has per formed a significant action such as clicking on a window s close box or full box or selecting an item from a drop down menu Messages may also be generated by system events such as the window redraw messages that are sent when a window s graphics have been damaged by moving or sizing other windows The system timer may be used to generate an
193. e top The way to move a window to the top is with the WF TOP subcommand of wind set int wi handle wind set wi handle WF TOP 0 0 0 0 Even if your application only has one window it must al ways be ready to handle the WM TOPPED message if it has a menu bar since a desk accessory may open a second window If no window is made active you may not get any messages from the AES and the user may be locked out of the program 68 du dd J JJ L L L LE L L L L AES Events When the user clicks on the close box in the upper left corner of the window the Screen Manager sends your applica tion message 22 WM_CLOSED The format for this message is Word Number Contents 0 22 WM_CLOSED the message ID number 3 The handle of the window whose close box was clicked When you get this message you should take whatever ac tion is appropriate Most of the time you ll just close the win dow with wind_close wind close msgbuf 3 Sometimes you ll want to put up an alert message like Are you sure Yes No or Save file before closing Yes No Cancel to make sure that the user doesn t accidently exit the program and lose valuable work Other times the WM CLOSED message indicates that the user wants to move back a level For example when you close a folder display window in the Desktop application the window doesn t disap pear but rather displays the contents of the nex
194. ectangle 1 3 8 MU_M2 Mouse rectangle 2 4 16 MU_MESAG Message 5 32 MU_TIMER Timer J me 1 i ig m j A ull LOE CL L LL AES Events These can be joined in any combination For example a value of 19 in the events flag means that you want the AES to wait for message mouse button and keyboard events 16 2 1 Likewise the flag for the actual events that oc curred is returned in the variable happened Since more than one event can happen at the same time it s necessary to ex amine each significant bit of the variable to find all of the events The other variables retain the same meanings they had when used in individual event calls Clicks bmask clicked and bstate are used for mouse button events The variables that start with m1 are for the first set of mouse rectangle events and the ones that start with m2 are for the second set of mouse rectangle events Msgbuf is used for message events keycode for keyboard events and timelo and timeht for timer events Although mousex mousey button and kstate are usually associated with mouse button or mouse rectangle events the values returned in these variables are valid at the conclusion of any evnt_multi call regardless of whether or not a mouse button or mouse rectangle event occurred The GEM literature suggests that you should always use evnt_multi instead of the individual event calls First a well written
195. ef deskw xdef deskh xdef wor kx xdef wor ky xdef wor kw xdef workh 3 Program starts here Get base page address in aS text move l a7 a9 save a7 so we can get the base page address move 1 bpadr aS a5 aS basepage address tg Calculate the total amount of memory used by t our program including stack space in d t total memory used 3 move l codelen a5 d length of code segment add 1 datalen aS dO length of data segment add 1 bsslen asS d6 g length of uninitialized storage segment add 1 stk bp dd g size of the base page our stack 41 CHAPTER 2 Calculate the address of our stack and move it to the stack pointer a7 g move l1 d dl add 1 as5 dl and 1 4 2 di move l di a7 Use the stack address size of program memory program s base address pick off odd bit to make sure that the stack starts on a word boundary it must set stack pointer to our stack which is stk bytes above end of BSS n w n nnn GEMDOS SETBLOCK call to reserve the area of memory actually used for the program and stack and release the rest back to the free memory pool move l d0 sp move 1 a5 tsp g clr w move 4a sp trap 1 add 1 12 sp Sk nitiali move i move 1 move l MOVE l move move move move move jer cmpi beg Got the move move jsr move move move move move push the size of progra
196. elect the graphics coordinate system Initial ize this value to 2 indicating that you wish to use raster co ordinates which correspond to the ST s actual screen dimensions The second exception is input 0 the device ID number On ST systems that have the GDOS extensions loaded this device number specifies the screen resolution mode To find the resolution mode use XBIOS command 4 C programmers can use getrez a macro defined in the file osbinds h to call this function Getrez returns the numbers 0 for lo res 1 for medium res and 2 for high res To get the proper screen device number you must add 2 to the value re turned by getrez include lt osbinds h gt int rez work in 12 rez getrez work in 0 rez 2 22 o AJA 3 ud ned wl wd ud L LL E L L L Starting an Application Machine language programmers can perform the getrez call using the following code move w 4 sp push command number on stack trap 14 call XBIOS addq 2 sp pop command number off the stack The resolution will be returned in register dO The other input value is amp handle This is a pointer to the variable that holds the physical workstation ID number of the screen device In order to discover this workstation handle the AES Graphics Library function graf_handle must be used The format for this call is int phys_handle cellw cellh chboxw chboxh phys_handle graf_handle amp cellw amp cellh
197. ement timer alarm and or a message from an other task Tasks that use these calls to indicate they re wait ing for an I O event are put on the Not Ready list They re inactive until the event they are waiting for occurs All the tasks that are ready to run are kept on the Ready list where they take turns executing The task currently running is at the top of the Ready list When that task makes a call to one of the AES library routines the Dispatcher portion of the kernel takes control as soon as the call is completed If the call was an event call in dicating that this task wants to wait for an I O event the Dis patcher moves the task from the Ready list to the Not Ready list Otherwise it merely terminates execution of the task moves it from the top of the Ready list to the bottom and moves all of the rest of the tasks up one place on the list _ Control is handed over to the new task at the head of the list and it s allowed to run until it makes an AES call Unlike some multitasking systems where each task gets a fixed amount of time to execute the AES dispatcher will not preempt a running task The only way it can get control is for the task to make an AES call Therefore if your application goes for a long time without making an AES call during ex tensive math calculations for example multitasking will break down The Screen Manager task will not run and the GEM features that it handles such as the menu bar will no
198. en that menu item is chosen If any of the drop down box is left exposed the whole box will be inverted when the user moves the mouse over that part In a dialog tree you ll find that all of the objects are drawn at once making it difficult to get at some of the over lapping siblings By setting the HIDETREE attribute flag you should be able to temporarily remove those that are in your way and then reveal them when you re done Once you ve finished editing the tree you should be able to close it and to change it back to a menu tree If you ve obeyed the rules the resource construction program should let you make the change There are certain menu conventions which GEM pro grams should follow in order to promote uniformity The first menu title is customarily set to DESK The DESK drop down box must contain exactly eight menu items The first is usually titled About Program where Program is filled in with the name of the application Note the three dots at the end of this item This is another GEM convention which tells the user that selecting this item leads to a dialog in this case the dia log box which displays the program credits The next item is a line of faint dashes created by setting the DISABLED flag This line is a conventional device called a separator bar which sets off one group of menu options from another The other six objects are dummy strings which the AES fills in with the names of desk accessories that have
199. enable menu icheck actually changes the setting of a single bit in the ob state word In this case it s the CHECKED flag and if you prefer you may change this flag directly as well Another way to indicate the current setting is to change the text of the menu item itself Typically if the option is on the menu item will read Turn this option off and when it s off it will read Turn this option on You can change the text of a G STRING menu item by using the menu_text call int status item char text OBJECT tree status menu text tree item text where tree is a pointer to the menu object tree item is the ob ject number of the text object to change and text is a pointer to the replacement string The size of the replacement string should be the same as the original one If it s longer it may go out of the menu box and onto the desktop If you re planning to use replacement strings include enough space at the end of 149 CHAPTER 5 each menu item so that the drop down box will be large enough to accommodate the longest string Program 5 2 demonstrates how to handle checkmarks disabled menu items and menu items with alternating text Program 5 2 menu2 c 59325235523259292x555259552252225252 25252525253532553 2 14259553255222 4 2212222 25521521 MENU2 C Demonstrates handling of check marks a disabled menu items and alternate text x AFETTEKASSATKTAAKKK
200. er of 16 bit results in int_out array control3 0 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr out array type int in 0 A code which specifies the type of action to take Type Macro Number Name Action 0 FMD_START Reserves the screen area used by the dialog box 1 FMD_GROW Draws expanding box from small to large rectangle 2 FMD SHRINK Draws shrinking box from large to small rectangle 3 FMD_FINISH Frees the screen area used by the dialog box and causes redraw messages to be sent smallx int in 1 The horizontal coordinate of the left edge of the smaller rectangle smally int in 2 The vertical coordinate of the top edge of the smaller rectangle smallw int in 3 The width of the smaller rectangle in screen pixels smallw int_in 4 The height of the smaller rectangle in screen pixels largex int_in 5 The horizontal coordinate of the left edge of the larger rectangle largey int_in 6 The vertical coordinate of the top edge of the larger rectangle 299 largew largeh Results status See also form do 260 int in 7 intLin 8 int out 0 form dial The width of the larger rectangle in screen pixels The height of the larger rectangle in Screen pixels Error status code 0 an error occurred during execution gt 0 no error occurred during execution 4 _ J tl d 79 Joo LL LO L ME uw CL f
201. erating system ROMs Some of the features of this command such as the exit GEM to DOS feature are obviously geared to the MS DOS version of GEM and are not applicable to the ST version C binding int status exitgem graphics isgem char command 128 tail 128 status shel_write exitgem graphics isgem command tail Inputs control 0 121 Opcode control 1 3 Number of 16 bit inputs in int Lin array control 2 1 Number of 16 bit results in int_out array control 3 2 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array exitgem int in 0 A code which indicates whether or not to exit GEM and return to the DOS prompt Obviously inapplicable to the ST where GEM is always present 0 exit GEM AES run another application graphics int in 2 A code which indicates whether the next application to run is a graphics applica tion Inapplicable to the ST which always uses a bitmapped display 0 not a graphics application 1 a graphics application isgem int in 3 A code which specifies whether or not the application to run is a GEM application 0 not a GEM application 1 a GEM application command addr in 0 The address of the buffer that holds the command text string This is the drive specification directory and filename of the application to invoke tail addr_in 1 The address of the buffer that holds the command tail text string This is the text
202. erly recreated Program C 1 rscbuild c ATTETAETAEAAEKAT AAAS ARSATKAAKALKAAL ARES RSCBUILD C Builds resource files for dem include the correct file 1 F S HESSEL SEERE ES SEE 4 include lt osbind h gt include dialogl dat substitute the name of the file you re using here maint int handle error handle Fcreate FILENAME 40 if handle lt puts can t apen that file exit g gt error Fwrite handie FILELEN rscdata j printf We wrote d bytes n error Fclose handle 317 J APPENDIX C Program C 2 dialogl dat ETTEKTTATATATAAATATKATAKAATATASTAAT AAS FA DIALOG1 DAT x Data for dialogl rsc X t include with RSCBUILD C 18 amp SX S9 2t9 9t195959999999 9 24225253229252292 45222 jJ OK define FILENAME defino FILELEN 1294L int rscdatal647 xL 9x9018A Qxo00Q 9xe994F 9xSFSF 9x6E09 9x599090 x 4F 9x6D79 9x7461 9x2F38 9x6372 9x7356B 90x73290 9x092D 9x 2D2D x4163 9x 4465 x 2929 9x 6F72 Ox 6363 x 6573 9x29009 9x7279 Ox 2E2E 2x90951 9xFFFF 9x9090190 9xFFFF 9x SOSE 9xeo000 2x 4 90x90094 x OxFFFF Bx ODID Ix WISP OxFFFF Bx BIS4 Bx BOOS 9xFFFF x B Sx xFFFF x JOC Bx BIOS OxFFFF Ox S98 Ix BISO OxFFFF Ox BOSC Ox BOOS Sx BiAd 9x935096 xX S E 9x746
203. es were mentioned such as the size box and the full box It was also mentioned that these boxes do not perform the indicated functions autonomously In other words if the user clicks the full box the AES doesn t automatically resize the window all by itself Instead the Screen Manager sends a message to the application telling it what the user has done When the pro gram gets this message it can either ignore it or honor it by changing the window using the wind_set function If you ve created a window that includes the sizer control your program should be prepared to deal with message 27 WM SIZED When the user moves the mouse to the size box holds down the left mouse button and drags the mouse the Screen Manager displays an elastic image of a box that follows the mouse indicating the new outlines of the window When the user releases the mouse button the Screen Manager erases the box and sends the application message 27 The contents of the msgbuf message buffer after such a message is received J wt to Ud d ud d d UL LLLE e L LC L AES Events looks like this Word Number Contents 0 27 WM_SIZED the message ID number 3 The handle of the window that was requested to be sized 4 The requested x position of the window s left edge the same as the current window x position 9 The requested y position of the window s top edge the same as the current window y position 6 The reque
204. es that the object is a radio button named for the push buttons on a car radio which pop up when a new one is pushed In order to indicate which other objects share this mutual exclude feature radio buttons must be siblings Radio button objects are normally set up by creating a box ob ject such as a GL BOX or G_IBOX and placing the buttons in side The sample dialog box of Figure 4 1 is arranged this way with BUTNA BUTNB and BUTNC all children of the invisi ble INVISBOX The LASTOB flag The LASTOB flag merely indicates that an object is the last one in its object tree The TOUCHEXIT flag The TOUCHEXIT flag is an inter esting variation on the normal EXIT When this bit is set in an ob ject s ob flag field form do exits as soon as you move the mouse over the object and press the left mouse button It does not wait until the mouse button is let up again as it does for exit ob jects This allows you to create your own scroll bars or other dragable or autorepeat controls within a dialog While the AES doesn t wait for the button to be released on a TOUCHEXIT ob ject it does test to see if it has been released If it finds that the button was released it waits to see if the user double clicks When it detects a double click it sets the high bit of the object number returned from form do Therefore your program code should be prepared to deal with the possibility that the user will double click on a TOUCHEXIT object At the
205. essag move 0 ctril move 1 ctri2 1 intout move 81 ctrl3 1 addrin move 40 ctr14 move 1 nsg addrin Jer aes move 490 ctrl3 jer msghand handle the message cmpi 0 d4 check if window close beq main if not keep going delete window 2 move 193 ctrld command wind delete move 81 ctrll1 move 1 ctr12 move wh2 aintin jap aes amp amp gt gt 7 gt gt gt 7 gt 97 gt End of Main Program Code lt lt lt III RE t Message handler subroutine f msghand move msg dS check message type cmpi 427 45 x WM SIZED bgt msg if greater skip bne msg2 a J 3 3 Jj 4 4 he de Rh Re ie CEL L AES Events msgl move move move move move move move move jmp msg2 capi bne 105 ctr18 command wind set 6 ctrii 6 input integers msg aintin window handle 5 aintint2 subcommand set current size msgt8 aintin 4 mS8g 19 aintin amp msg 12 aintin 48 msg ti14 aintin ie aes 822 d3 amp WM CLOSED msgs Close the Window nove move move move move move move imp msgs cmpi bne move move move move jap nsg4 s cmpi bne jer msgS3s rts 4 102 ctrl19 command wind close 81 ctrl1 1 ctr12 8 ctris u2 ctr14 wh2 aintin 81 d4 aes 21 d5 uM TOPPED msg4 195 ctr1 command wind set 6 ctrii 6 input integers msgt aintin window handle 19 aintin 2 subcommand WF TOP aes
206. ew line The final set of square brackets contains the text for the exit buttons A maximum of three exit buttons may be used each of which contains a maxi mum of 20 characters of text The text for each button is separated with a vertical bar character 261 Results exitbutn 262 int out 0 form alert The exit button selected by the user 1 first exit button 2 second exit button 3 third exit button dild 1 i x d 1 4 form error LL Display an Error Box KE form_error Opcode 53 u Displays an error box which informs the user of a TOS error C binding int exitbutn error exitbutn form_ error error p Inputs control 53 Opcode control 1 1 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int zout array control 3 0 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out arra error int in 0 The TOS error code Actually since GEM was designed with IBM PC DOS in mind this routine expects to get PC DOS error codes rather than the GEMDOS error codes returned on the Atari ST computers In order for form error to print out its error messages correctly you must convert the GEMDOS codes to PC codes This is done by reversing the sign of the code from negative to positive and then sub tracting 31 DOS_ERR TOS_ERR 31 The following chart lists the GEMDOS e
207. ext chapter and it s indicative of the order used to walk the tree Walking the tree is a process by which you start with the root object and visit each of the subordinate objects in turn Using the link fields you can examine each of the objects in the tree by using the following procedure 1 Examine the ob head field of the current object If there s a child visit it by making it the current object Then go back to Step 1 2 If there s no child look at the ob next field If this field con tains a NIL 1 value you re back at the root object and your tour is finished 3 If the value in ob next is not NIL check to see if the object it points to contains the number of the current object in its Object 5 BUTHB Next Tail RENE 100 Jot FEE wail a 32 L Bi tf Ll L L L LE GEM Graphics Objects ob tail field If it does we ve moved back up to the parent of the current object so make it the new current object and go back to Step 2 If the value in ob next is not NIL and does not point to an object whose ob tail is the same as the current object then it points to a sibling object which you haven t visited Visit this object by making it the current one and go back to Step 1 The AES performs many of its tasks by following the ob ject tree For example it can draw the entire tree by starting at the root and then drawing each object it visits as it walks around the t
208. ext document the vertical slider fills 10 percent of the area of the scroll bar That means the top of the slider can never go down more than 90 percent of the way The other 10 percent is taken up by the bar In that situation position 1000 the bottommost position on the bar is 90 percent of the way down the scroll bar If the window displays 20 lines of a 100 line document the slider occupies 20 percent of the area of the scroll bar In that case position 1000 the farthest that the top of the slider can go is only 80 percent of the way down the scroll bar Therefore you must calculate the position of the top of the slider as a fraction of the total available range of motion For example in the case of the 200 line document 20 of which are displayed the total range is 200 20 or 180 lines If line 39 is displayed in the top of the window the bar should be placed at position 1000 39 180 or 216 This position set ting is a little larger than the setting of 200 you d intuitively guess to be the correct setting when the top of the display shows the line that s 20 percent of the way down the docu ment The larger the slide bar gets the larger this discrepancy grows For example if you make the document half as long 80 ed wd ud a cm J uM ed tl wd l t LL L fi i AES Events you d expect the setting to double But if the window shows 20 lines of a 100 line document and the top of the window shows lin
209. f greater exit msgeo if less try next msgt dO is msgt3 menuid menuid d asgS if not exit 4SFFFF wdwhnd is window handle 1 msgS if no window exit 4 FFFF wdwhnd signal that there s no window clsvwk close virtual workstation 449 d5 AC OPEN msg if not try next message type msg 8 d is this our menuid menuid do asogs3 if not exit 4S9FFFF wdwhnd amp is no window open msg3o if not move window to top initout amp if so open vwk and window eck sant d wt 54 J d HE re E Wi t ot L LI Be Desk Accessories 28 d5 amp WM MOVED msg1 if so change size and position 927 dS WM SIZED msg2 4195 ctr19 command wind set 46 ctr11 6 input integers msgt aintin window handle 5 aintin 2 subcommand set current size msgt 8 aintint4 msg 19 aintin msg 12 aintin 8 msgti4 aintin 16 aes 422 d3 amp WM CLOSED msgs Close the Window move move move 192 ctr19 command wind close 4 1 ctr11 41 ctr12 49 ctrl15 490 ctr14 wduhnd aintin aes 23 Delete the Window move jsr move jap mags cmpi bne msg39 418935 ctrl19 command wind delete aes A4 FFFF wdwhnd turn on no window flag clsvwk 421 d35 WM TOPPED asg4 4195 ctr19 command 2 wind set 4s6 ctr11 amp input integers asgt aintin window handle 419 aintin 2 subc
210. f the mouse pointer The caller may request one of eight predefined mouse pointer shapes or a user defined shape made up of a 16 X 16 pixel bit image This function may also be used to erase the mouse pointer before graphics operations are performed and to restore it after they are finished This is necessary because the background behind the pointer is saved in a buffer and restored when the pointer is moved If the mouse pointer isn t turned off during a drawing operation the previous background image behind the pointer may be accidentally restored on top of the new background image created by the drawing operation If an application chooses to change the mouse pointer shape it should only do so when the pointer is within the active topmost window When the pointer leaves the active window the program should change its shape back to an arrow or bee shape 0 or 2 The application can use evnt mouse or evnt multi to track the movement of the mouse in and out of the active window rectangle so as to know when to change mouse shape C binding int status form no formptr 37 status graf_mouse form_no formptr Inputs control 0 78 Opcode contro 1 1 Number of 16 bit inputs in int_in array control 2 1 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array form_no int_in 0 A code indicating the new shape that the mouse
211. f the other box functions the program calls this routine only after it has determined that the user has pressed the left mouse button Typically the program would make this call when form do exits and indicates that the TOUCHEXIT box inside the bar was the exit object The 180 d c wg 3 L GL OC L p The Graphics Library graf_slidebox moves the slider within the bar whenever the mouse pointer moves toward either end of the parent box When the user releases the mouse button the function returns a number indicating the position of the slider within the bar The calling syntax for graf_slidebox is int status parent object orientation OBJECT tree position graf_slidebox tree parent object orientation where tree is a pointer to the object tree array containing the two box objects parent is the number of the parent box object and object is the number of the box object which it contains Orientation is a flag which indicates whether the parent bar is oriented horizontally or vertically If this flag is set to 0 the bar is horizontal and the slider moves left and right If the flag is set to 1 the bar is vertical and the slider moves up and down The final position of the slider is returned in the posi tion variable This value is a number in the range 0 1000 which denotes the position of the center of the slider relative to its parent object If the orientation of the bar is vertical a positi
212. ficant elements of this message are Word Number Contents 28 WM_MOVED the message ID number The handle of the window whose move bar was dragged The requested x position of the window s left edge The requested y position of the window s top edge The requested width of the window the same as the cur rent width The requested window height the same as the current window height SJ ON Ui im C If you re willing to let the user move the window any where on the screen you can merely forward the new window position to the wind_set command using the WE_CURRXYWH subcommand wind_set msgbuf 3 WF_CURRXYWH msgbuf 4 msgbuf 5 msgbuf 6 msgbutf 7 You will probably want to constrain the user s freedom to move windows around on the screen The current version of GEM on the ST won t let you drag a window past the left or top screen borders unless its starting position was beyond those borders But it will let you move a window partially off screen towards the bottom or to the right Therefore you may wish to prevent the user from moving the window past the right or bottom borders To keep the complete window display on screen make its maximum x position equal to the width of the Desktop win dow minus the width of your application window and its 67 CHAPTER 3 maximum y position equal to the height of the Desktop win dow minus the height of your application window Another constraint on window moving that would be
213. formatted text string for which you may specify color font size and horizontal positioning 22 G_BOXTEXT A formatted text string within an opaque box with optional border 23 G_IMAGE A monochrome graphic bit image 24 G_PROGDEF A user defined object type 25 G_IBOX A transparent box with optional border 26 G_BUTTON A G STRING see below with a border around the text 27 G_BOXCHAR A single text character within an opaque box with optional border 28 G STRING A string of black graphics text in the de fault font 29 G_FTEXT An editable text field for which you may specify a template a validation string and an initial value 30 G_FBOXTEXT An editable text field within an opaque box with optional border 31 G_ICON An object consisting of a monochrome bit image and an image mask used for for drawing the image in normal and inverse video modes 32 G_TITLE A specially formatted G_STRING for use in the title bar of menus As you can see the various objects types are mainly made up of combinations of rectangular boxes text forms and bit images Each of the object types will be examined in detail be low At the same time there will be an examination of the ob_spec data field which contains either two words of object specific information or a pointer to an object specific infor mation block A point which may be of interest to you is that the AES doesn t use the top byte of the object type field Pro grammers are free to use
214. from within a program using the eunt_dclick call int speed set speed flag speed set evnt dclick speed flag where flag indicates whether you want to read the current double click setting flag is 0 or make a new setting flag is not 0 If you wish to make a new setting set the speed vari able to a number in the range 0 4 where 0 specifies the long est double click interval and 4 the shortest The setting requested either the current or new setting is returned in the variable speed set Since the speed of the double click setting may affect the speed with which mouse button events are re turned you may wish to change the speed before a mouse button event call and change it back afterwards 88 J E d TEn o te u x4 pe a ee L LE AES Events In the evnt_button call the two input variables bmask and bstate are used to specify which buttons you want to wait for and whether you want to wait for them to go down or up The bmask variable is the one you use to specify which but tons to watch Bit 0 of this word corresponds to the left mouse button and bit 1 to the right mouse button If you want to watch the left button set bmask to 1 If you want to watch the right button you set it to 2 If you want to watch both set it to 3 The bstate variable is used to specify whether you want to wait for the buttons to go down or up You set the appropriate bit to 0 if you want to wait f
215. ft key combinations The second byte is usually the ASCII value of the key com bination which does depend on the state of the shift keys Shift Control and Alt The following table shows the keycodes as four digit hexadecimal numbers for all key and shift combinations Main Keyboard Unshifted NM xXx ecerTOrovos g TAT sy OBO TH 1E61 3062 2E63 2064 1265 2166 2267 2368 1769 246A 256B 266C 326D 316E 186F 1970 1071 1372 1F73 1474 1675 2F76 1177 2D78 1579 2C7A NKXES lt CHVYAOQVOZEMATTLOMNMMONGD H 1E41 3042 2E43 2044 1245 2146 2247 2348 1749 244A 254B 264C 324D 314E 184F 1950 1051 1352 1F53 1454 1655 2F56 1157 2D58 1559 2C5A CTRL 1E01 3002 2E03 2004 1205 2106 2207 2308 1709 240A 250B 260C 320D 310E 180F 1910 1011 1312 1F13 1414 1615 2F16 1117 2D18 1519 2C1A ALT 1E00 3000 2E00 2000 1200 2100 2200 2300 1700 2400 2500 2600 3200 3100 1800 1900 1000 1300 1F00 1400 1600 2F00 1100 2D00 1500 2C00 311 312 Unshifted 1 0231 2 0332 3 0433 4 0534 5 0635 6 0736 7 0837 8 0938 9 0A39 0 0B30 0C2D OD3D i 2960 N 2B5C 1A5B 1B5D 273B f 2827 i 332C 342E 352F Space 3920 Esc 011B Backspace OEO8 Delete 537F Return 1COD Tab OF09 Cursor Pad Unshifted Help 6200 Undo 6100 Insert 5200 Clr Home 4700 Up Arrow 4800 Dn Arrow 5000 Rt Arrow 4B00 Lft Arrow 4D00 APPENDIX B Shift CTRL 021 0211 9 03
216. g from a large size to a smaller size May be used for example before closing a window with wind close to make it look like the window is actually folding in on itself C binding int status smallx smally smallw smallh int largex largey largew largeh status graf_shrinkbox largex largey largew largeh smallx smally smallw smallh Inputs control 0 74 Opcode control 1 8 Number of 16 bit inputs in int_in array control 2 1 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array smallx int_in 0 The screen position of the left edge of the ending small rectangle smally int in 1 The screen position of the top edge of the ending small rectangle smallw int in 2 The width of the ending small box in pixels smallh int in 3 The height of the ending small box in pixels largex int_in 4 The screen position of the left edge of the starting large rectangle largey int_in 5 The screen position of the top edge of the starting large rectangle largew int_in 6 The width of the starting large box in pixels largeh int_in 7 The height of the starting large box in pixels Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also wind close graf_growbox 273 graf watchbox Watch an Object
217. g param eter lists or recursion Second the AES is not reentrant and so you may not call AES routines from within your drawing code VDI routines are all right Finally your routine should always return a value of 0 to the AES This signals that everything s all right If any other value is returned the AES drawing operation will halt and the other objects in the tree won t be drawn Object Flags The next data field in the object structure is called ob flags This field is used to specify attributes for the object which in dicate how the user should be able to interact with it This in teraction is usually carried out by means of AES Library routines such as form do which controls all of the user inter action during dialogs This routine examines the various object flags and implements their functions The object attributes are set up as bit flags which means that each is assigned a bit in the word ob flags If the bit is set to 1 the object has the attribute and if it s reset to 0 the 115 CHAPTER 4 object doesn t The full list of bit flags and the macro name as signed them in the OBDEFS H header file is as follows Bit Bit Number Value 0 1 1 2 2 4 3 8 4 16 5 32 6 64 7 128 8 256 116 Macro Name SELECTABLE DEFAULT EXIT EDITABLE RBUTTON LASTOB TOUCHEXIT HIDETREE INDIRECT Description of Attribute The user can select the object by clicking on it A change in graphic
218. g the program C binding int status showflag OBJECT tree status menu bar tree showflag Inputs control 0 30 Opcode control 1 1 Number of 16 bit inputs in int_in array control 2 1 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array showflag int in 0 A code which determines whether this call causes the menu bar to be displayed or erased 0 erase the menu bar 1 display the menu bar tree addr_in 0 The address of the object tree array which supplies the data for the menu display Results status int_out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution 243 menu icheck Display or Erase Checkmark menu icheck Opcode 31 Displays a checkmark in front of a menu item or erases the checkmark C binding int status item setting OBJECT tree status menu icheck tree item setting Inputs control 0 31 Opcode contro 1 2 Number of 16 bit inputs in int Lin array control 2 1 Number of 16 bit results in int_out array control 3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array item int_in 0 The object number of the menu item setting int in 1 A code indicating whether the specified item should be checked or have its check mark erased erase a checkmark if vi
219. g w amp wrect g h while wrect g w amp amp wrect g h while not at last rectangle c if overlap drect amp wrect check to see if this one s damaged set clip amp wrect if it is set clip rectangle display wh 3 redraw and turn clip off amp vs_clip handle FALSE int amp amp wrect gt wind get wh WF NEXTXYWH amp wrect g x amp wrect g_y amp wrect g w amp wract g h 2 wind_update END_UPDATE unlock screen amp MOUSE ON turn mouse pointer back on 3 amp Subfunction to draw the window display XXS X 5 t display wh draw the window display int wh m L char bufL891 int x y width height wind get wh WF WORKXYWH amp work g x f amp work g y amp work giw amp work g hd find work area clear rect amp work and clear it form center dialtree amp x amp y amp width amp height left x cellw top y cellh sprintf buf Computers v gtext handle left top scellh buf sprint Buf 3 v gtext handle left top scellh buf sprintf buf Atari ST s a d computersr227 v gtext handle left top scellh buf sprintf buf Atari XL XE s ZdX computersEL11 v gtext handle left topt cellh buf sprintf buf Exidy Sorceror s d computersr21 v gtext handle left topt cellh buf sprintf buf
220. gative outside Color Zero none Positive inside of G_BOXCHAR character 0 hollon 1 6 dithered 7 solid Text String Objects The next group of objects G STRING G_BUTTON and G TITLE contain text strings All three of these object types use the plainest text drawn in the default size of the system font with black as the text color and with no special effects such as italics 106 Jo Jo uw E LJ wed xw wal L L L LEL GEM Graphics Objects The ob sp c field of all of the string objects contains a pointer to the string This pointer is the long word address of the first character of the text The string must follow the C lan guage convention of ending in the ASCII 0 character G STRING The G STRING type is used for fixed explanatory text G_BUTTON The G_BUTTON is one of the most fre quently used types of objects It s like a G STRING with a one pixel border drawn around the text As you will see be low the width of this border is increased if certain attribute flags such as DEFAULT are set Buttons are most often used as controls the user can click on For example the OKBUTTON object in the sample tree was a G_BUTTON type of object that the user could click on to end the dialog In addition to buttons that exit the dialog like OK and CANCEL these ob ject types can be used as Boolean on off switches allowing the user to select an option or to deselect it
221. ge that window s contents all the same Likewise you don t get a redraw message when you move the slider in a scroll bar but you ll want to change the window contents then too One way to perform the update is to simply call your window re fresh routine But another alternative is to send yourself a re draw message When the program receives this message the redraw is taken care of by the normal message handler rou tine The main advantage to sending yourself a message when you want to refresh a window is that the AES checks to see if there s already a redraw message waiting in the pipe If there is it merges the two requests by changing the damage rec tangle to one large enough to include the two smaller damage rectangles This helps prevent multiple refreshes Such sequen tial redrawings slow down the program and give it an un professional flickering appearance Sending and Receiving Messages You send your program a message the same way you d send a message to any other task First you create an eight word message in a buffer The standard format is used for this mes sage The first word contains the message ID the second word contains the application ID of the task sending the message the third contains the number of additional bytes past the standard 16 used by the message and the rest contain mes sage specific data After creating the message you send it by using the appl_write function The syntax for this functio
222. ght of a screen rectangle For functions 8 9 10 15 and 16 the value in int out 1 associated with the variable name x has some sig nificance other than being a horizontal screen position value For function number 17 the value in int out 2 is used as the second part of an address For specifics see the descriptions of the various subfunctions status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution x int_out 1 The screen position of the left side of the window rectangle y int_out 2 The screen position of the top edge of the window rectangle width int out 3 The width of the window rectangle in ixels height int_out 4 The height of the window rectangle in pixels See also wind_set 290 ae NM v pe J ds 3 3 d d UL UL L l C C L Me LO L wind_set Change Window Settings wind_set Opcode 105 This function can be used to change a number of settings which affect the way in which a window is displayed C binding int status wi_handle field x y width height status wind set wi handle field x y width height Inputs control 105 Opcode control 1 6 Number of 16 bit inputs in int Lin array control2 1 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr out arra wi ha
223. gram MMRCP If you aren t using either of those development systems Kuma Computers Ltd market a separate resource construction program called K Resource KRSC which can be used with any compiler or assembler Each of these programs has slightly dif ferent features For example KRSC and MMRCP both have built in icon image editors while the RCS does not However RCS and MMRCP both allow the user to load image data that 132 24 LJ Ll i L L ft L E L Resource Files and Menus was created using other programs such as Icon Editor Profes sional Icon Editor or Degas Elite while KRSC does not Under most circumstances however the differences between these programs is not significant All of them perform very well at the basic task of constructing a resource file To build a resource with one of these programs open a resource window and drag one of several different tree icons onto the window These icons represent various types of ob ject trees such as menus or dialogs The distinctions among types of object trees are strictly for the purposes of the resource construction program itself no actual difference exists in the object structure of these trees But such distinctions can help make the resource programs more effective For example when you select a menu tree the program presents a prepared template of text objects arranged as in a typical menu and the program restricts your selection to the ty
224. h these functions are used primarily by the AES during the resource load process you may find use for them in your applications The first is rsrc objfix and it s used to convert an object s position and size values from character units to pixels The syntax for this function call is int status object struct object tree Status rsrc_obfix tree object where tree is a pointer to the array of object structures and object is the index number of the object whose position and size is to be converted While this function is mostly used by the AES when it loads a resource file it could have been used in the example in the previous chapter where an object was created out of initialized data structures Here is how the pro gram could have been modified to take advantage of this func tion This is the section of the program where the position and size of the objects were fixed for x 0 x lt 3 x fix object x y width and height tree x ob_x cellw tree x ob y cellh tree x ob width cellw tree x ob height cellh j to this for x 0 x lt 3 x fix object x y width and height rsrc_objfix tree x In fact that s just what was done in the machine language version of the example The final call is used to store the address of a data struc ture array element in memory It s called rsrc_saddr and its calling sequence is int status type index long address status rsrc saddr
225. he File Selector Dialog Box ITEM SELECTOR Directory C NSTBASICME X mere Selection E o FSELECT Bas VDIPROGS ALERT BASIC BASIC BASIC FSEL FSELECT FSELEET Mun 175 eee eS LELI seer amp Chapter 7 The Graphics Library L UL 1 a LOL Most of the graphics routines that GEM uses are found in the VDI graphics library However a few higher level graphics routines were needed in order to implement the complicated object manipulation routines of the Forms Library and some of the features of the GEM Desktop applications These higher level routines are found in the AES Graph ics Library These functions may appear to be so specialized that their usefulness is not readily apparent When examining them therefore you should focus on the ways these routines are used by the GEM Desktop program Then you should con sider similar ways you might use them in your programs Box Manipulation Many of the AES graphics routines are used to manipulate the rectangular outline of a box drawn on the screen If you stop to think you ll realize how much is done on just the Desktop program with boxes Rectangular shapes are used for win dows icons buttons and slider bars These shapes are moved dragged and sized with the help of the AES graphics routines The first of these routines is used to draw a rubber box This is a box composed of dotted lines The upper left corner of t
226. he box remains fixed but the lower right corner changes position as the user drags the mouse As long as the user holds the left mouse button the box is redrawn whenever the mouse pointer changes positions When the button is released the box is erased The operation of the rubber box routine should be familiar to anyone who has used the size box on a window The name of the routine used to draw the rubber box is graf_rubberbox The syntax for this call is int status x y minw minh endw endh status graf rubberbox x y minw minh amp endw amp endh where x is the x coordinate for the left side of the box and y is the y coordinate of the top of the box The variables minw and minh contain the minimum box width and height respectively When the function ends the current box width and height are 179 CHAPTER 7 returned in endw and endh The function s error status is re turned in the status variable A status of 0 signals that an error occurred during the call while a positive integer means that function completed without error Typically a program will only call this routine when it has determined that the mouse button is down This may be determined by an evnt _multi or evnt button call or by the activation of an object whose TOUCHEXIT flag is set When the call is made the dotted outline of a box is drawn from the coordinates leftx and topy to the current mouse position The function continues to track the m
227. he icon image such as the filename that appears under the file icons on the Desktop This text string is printed using the small size of the system text font The ib ptext field contains a pointer to the null terminated text string itself The ib xtext and ib ytext contain the x and y offsets for the start of the text relative to the upper left corner of the icon itself And the ib wtext and ib htext fields contain the width and height respectively of the text string in pixels You may also specify a text character to appear with the icon image such as the drive numbers that appear on the file drawer icons on the Desktop The low byte of the ib char field contains the ASCII value of the text character to appear with the icon The ib xchar and ib ychar fields contain the x and y offsets for the character relative to the top left corner of the icon Although not noted in the GEM documentation the high byte of the ib character field contains the foreground and 112 u a ee ud J dE ud d uud L LLL Em f L L GEM Graphics Objects background color indices The upper four bits select the fore ground color while the lower four bits select the background color While it s possible to select any combination of fore ground and background colors in order to retain compatibility across display modes and in the interests of good taste you ll almost always want to stick with black for the foreground color and whit
228. here are two types of GEM windows the Desktop window and application windows The Desktop window is controlled by the GEM AES and is present when any GEM application such as the Desktop program is running It covers the entire display area and is divided into two parts the menu bar and the Desktop work area The menu bar stretches across the top line of the screen and is the same height as a character cell in the default text font When a GEM application first starts the menu bar contains the name of the application file The appli cation may request the AES to replace this filename with a drop down menu as will be seen in a later chapter The Desk top work area covers the rest of the display space It provides a background for windows which the application opens The default background appears as a field of light green on a color system and gray on a monochrome system Application windows are opened and controlled by the application In addition to a border these windows may con tain a number of different components located in and around the window borders see Figure 2 1 Most of these allow the user to control certain aspects of the window s appearance and function These control features include a title bar a move bar an information line a close box a full box and horizontal and or vertical slide bars Figure 2 1 The Component Parts of a GEM Window Hove Bar occupies sane space as Title Bar o This is the title bar
229. hey call menu register they en ter an endless loop centered around an evnt multi call which waits among other things for the user to select the accessory s menu item The following C sample program dem onstrates a simple desk accessory It is an adaptation of the message c program found in Chapter 3 203 CHAPTER 8 Program 8 1 deskacc c ATTTEKAATATKTATEKSTATATAAATSSLAAAAATSEALEKTAAKAAATEKEAATAAAAESEKAAS DESKACC C A modification of MESSAGE C to make it g work as a desk accessory ATTTTTTCTTEKTEKTTATAEAAATTTKKAAATATATESASAAAATAAASKA KATATE include lt osbind h gt include lt gemdefs h gt include lt obdefs h gt define define define define define define define define define define define define define Object definitions FALSE TRUE 1 NONE 1 APP INFO APP NAME Accessory Window WDW CTRLS NAME CLOSER SIZER MOVER FULLER MAX X Y OX gt CY XD 2 CY D MINIX Y X lt Y X 3 YO DESK The flag for the Desktop NO ERR 18 Error no for no error APP ERR 1 Error no for failure of VWK ERR 2 18 Error no for failure of WDW ERR 3 Error no for failure of amp Macro definitions for BIOS calls amp Flag definitions for Library routines Window appl_init amp v opnvwk amp wi_create Global variables For VDI bindings and program routines extern i
230. hiftkey contains a 4 the Control key was held down when the mouse button was pressed and if it has a value of 12 both Alt and Control were held down The re served variable is reserved for future use Currently a 1 is al ways returned in the reserved variable Since the current version of ST BASIC doesn t include any commands for checking the mouse the graf_mkstate func tion can be very useful to BASIC programmers The following 196 Ub xad ud ed wb ed ach s wd L L EEL L Et The Graphics Library short sample program shows how to use graf_mkstate from BASIC It merely waits for the user to press a mouse button and then tells him or her which button was pressed the loca tion of the mouse and shift key status code Program 7 4 mous bas 19 20 sg 40 S 69 79 8 99 199 119 128 139 149 158 169 179 189 199 200 219 229 230 apb gb control peek apb global peek apb 4 gintin peek apb 8 gintout peek apb i2 addrin peek apb 16 addrout peek apb 29 fullw 2 clearw 2 gotoxy 1 1 print Press a mouse button to continue 7 7 mousbutn 2 while mousbutn 9 gensys 79 REM call graf_mkstate until a button is pushed mousex peek gintout 2 mousey peek gintout 4 mousbutn peek gintaut t shiftkey peek gintout 8 wend if mousbutn gt then bS the left if mousbutn gt 1 then b the right if mousbutn gt 2 then b
231. his function is int id char name 8 id appl find name where name is a null terminated string containing the filename of the application This string must be exactly eight characters long if the filename is shorter the end of the string should be padded with spaces to bring it to eight characters The applica tion s ID is returned in the variable d If GEM can t find the 63 CHAPTER 3 application a value of 1 is returned If you want to wait for a message event you can use the eunt_mesag command to place the first message in your buffer To read the message pipe directly use the appl_read command The format for this command is int status id length msgbuf status appl read id length msgbuf where id is the application ID for the application whose mes sage pipe you re reading generally your own Length and msgbuf are the length of the message in bytes and a pointer to the message buffer respectively The function returns a sta tus value of 0 if there was an error and it s greater than 0 if there was no error Generally you ll use the appl read func tion when you get a message whose third element contains a number greater than 0 signifying that there are more than 16 bytes in the message You ll use the number of bytes specified in the third element for the length field in appl read Messages for Moving Sizing or Closing a Window In the previous chapter the various window control box
232. ht beginx beginy endx endy where width and height specify the size of the box beginx and beginy its beginning position and endx and endy its final position Note that the Digital Research documentation refers to this function as graf_movebox However the C language bindings released by Atari Corporation with the Alcyon C com piler and libraries derived from Atari s code such as those supplied with the Megamax compiler use the graf_mbox ter minology Therefore in order to link properly with current versions of the library your program must also use the graf_mbox form If in the future Atari decides to change its libraries to conform to its documentation you ll need to change over to graf_movebox as well The last two box graphics calls graf_growbox and graf_shrinkbox are also used mainly for cosmetic purposes These two calls are very similar to the FMD GROW and FMD SHRINK subcommands of the form dial routine They draw a set of expanding or shrinking boxes from one screen rectangle to another like graf mbox using different size boxes You can create exploding windows by calling graf growbox just before wind open and graf_shrinkbox just after wind close The syntax for these two calls are 186 1 iuf bel tel d L Ltt LI rT tC CL L The Graphics Library int status smallx smally smallw smallh int largex largey largew largeh status graf_growb
233. hy insures that smaller objects are al ways drawn after larger objects so the larger parent won t cover up its smaller children As you ll see later the objc_draw function that draws an object tree allows you to specify a clipping rectangle within which the objects will be drawn Because of the tree structure this drawing routine can automatically skip drawing any child object if its parent is not within the clipping rectangle The usefulness of the mouse rectangle event becomes much more apparent when considered in the light of the ob ject tree structure Using parent objects to contain subobjects allows you to divide the screen into large rectangles which can be used as mouse rectangles These can be further subdivided into large areas containing several child objects each Once the user has clicked in the largest rectangle you can follow the object tree into smaller and smaller rectangles eliminating on the way all objects that are not within the parent rectangles This strategy lies at the heart of the point and click operation of GEM 102 3 3 SE wi wt Tok H LL Lo L LE GEM Graphics Objects Types of GEM Objects The ob type field in the object data structure is used to de scribe the type of object The standard GEM object types and their macro names from the OBDEFS H file are as follows Type Macro Number Name Description 20 G_BOX An opaque box with optional border 21 G_TEXT A
234. i y2 h2 olap4 sub di d2 move d2 aintout 8 gt overlap h d2 overlap y or aintout d2 are width and height both g beq refresh2 if so skip redraw and get next rect set clip rectangle move 4 129 contr160 opcode for set clip vas clip move 2 contr11 two points in ptsin move 1420 contr12 move 41 contr13 move 430 contr14 move 1 intin turn clipping on 214 LN 4d LJ ud J 1 a j UL L FL C d e L Desk Accessories mova d ptsin points 91 overlap x add aintout 6 dd subq 1 dd points 2J overlap x w 1 move dO ptsin 4 move di ptsin 2 pointsC1 overlap y add aintout 8 dl subq 1 d1 move di ptsin pointsCS overlap yth i jar vdi redraw the display jsr display turn clipping off move 4 129 contr19 opcoda for set clip vs clip move 2 contrli two points in ptsin move H contr12 move 1 contris move 9 contri4 move 9 intin turn clipping off jer vdi get next window rectangle refresh2 l move 4104 ctrlO command wind get move 2 ctril 2 input integers move 5 ctri2 S ouput integers move msg 6 a ntin amp window handle move 12 aintin 2 amp WF NEXTXYWH command jer aes bra refreshl unlock screen refreshs move 45107 ctr10 amp command wind update move 1 ctrli 1 input integers move 1 ctri2 1 output integer move 0 aintin code END UPDATE jsr
235. ider bar is supposed to represent the percentage of the total display area shown on screen If half of the total display area is shown onscreen at a time the slider bar should fill half the scroll bar The AES allows you to set the size of the bar with a value in the range 1 1000 Each unit corresponds to one tenth of 1 per cent of the total size of the scroll bar A bar size of 1 fills the minimum possible area while a bar size of 1000 fills the en tire slide box If the length of the part of the display that s seen is less than the total length available for display you can calculate the size of the slider with the formula size 1000 length seen total length If you use this formula you must be careful to check that the length seen is less than the total length however or you ll come up with a number larger than 1000 Also you should probably use 32 bit variables for the computation to avoid ex ceeding the size limit of 16 bit integers In C these are vari ables that are declared to be of the type long After you ve computed the relative size of the slider you can set the bar to this size using the WF_VSLSIZE or WF HSLSIZE wind_set function wind set wi handle WF VSLSIZE size 0 0 0 wind set wi handle WF HSLSIZE size 0 0 0 Your program should adjust the size of the slider if either the window or the document changes size If the size of the window changes you ll know because you will have received th
236. ies the color and pattern used for box type objects Its format is ex actly the same as the low word of the ob spec field for the box objects described above The te thickness field is used to describe the thickness of the border surrounding the G_BOXTEXT or G_FBOXTEXT Its format is the same as that of the low byte of the high word of the ob spec for box object negative numbers to 127 show the outside thickness in pixels positive numbers to 128 show the inside thickness in pixels The last two fields in the TEDINFO structure are te_txtlen and te_tmplen These fields specify the length of the text pointed to by te ptext and the length of the template string pointed to by te ptmplt These string sizes should include the null character ASCII 0 used to terminate each string Bit Image Objects and Icons The next object type G_IMAGE is a simple monochrome bit image object This type of object is usually used to display a picture that s not meant to be selected by clicking the mouse on it The reason these objects usually aren t selectable is be cause only a single bit plane image is supplied so selecting them causes the whole rectangle around the image to be in verted Examples of bit image objects are the drawings used to illustrate the Note Wait and Stop alert messages The ob spec field of a G IMAGE contains a pointer to a data structure called a BITBLK The C language definition of this data structure is typedef struct
237. ildren are Object 7 INSTRUCT the SELECT text box and Object 3 a box named INVISBOX Don t strain your eyes looking for INVISBOX as it s name suggests it s invisible This box surrounds its three children the box objects marked A B and C These are Objects 4 5 and 6 which we ll call BUTNA BUTNB and BUTNC respectively Figure 4 1 GEM Dialog Box and Its Contents SELECT Button R B or C Figure 4 2 illustrates the link fields for the seven objects Object 0 the root has no siblings in its NEXT field but its HEAD field points to its first child object 1 and its TAIL field points to its second and last child object 2 Object 1 has no children so HEAD and TAIL contain a 1 but it does have a sibling so NEXT points to object 2 Since object 2 has no 29 CHAPTER 4 more siblings its NEXT field points back to object 0 Its HEAD field points to object 3 its first child and its TAIL field points to object 7 its last child Figure 4 2 Link Fields for Objects in Dialog Box Object 88 Object 81 EXITBUTN f Object 87 INSTRUCT EET i i Object 6 BUTNC 3 4 Object 4 BUTNA Eug 5 ei If you look at the sample object tree you may find the numbering of objects a bit odd with objects 3 and 7 at one level and objects 4 5 and 6 at a lower level This is the order in which these objects are written out by the Resource Con struction program which we ll discuss in the n
238. in dicates the position of the desired data structure within its array For example the ob spec field of a G STRING con tains the index number of the desired string within the string data array instead of the address of that string Another difference is that screen x y width and height values are stored in character units rather than pixel units For example if a G_BOX starts at position 24 32 and each char acter is eight pixels high and eight pixels wide the position stored in the resource is 3 4 This allows the AES to draw the object to scale regardless of the screen display mode in effect at load time assuming an 80 X 25 character display If the object wasn t created on a character boundary the low byte of each rectangle word contains the closest character position while the high byte contains the number of pixels left over The last data structure in the resource file is another one used by the AES when loading the font This structure is called the Tree Index and it contains the index number of each tree s root object in the object array This allows the AES to find the starting address of each object tree in the object array Loading a Resource In order to use the object trees stored in a resource file your program must first load the resource The AES provides a spe cial Library routine for just this purpose called rsrc load The calling sequence for this function is int status char filename status rs
239. in 2 The screen position of the left edge of the known rectangle knowny int in 3 The screen position of the top edge of the known rectangle knownw int in 4 The width of the known rectangle in pixels 295 wind calc knownh int in 5 The height of the known rectangle in pixels Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution otherx int_out 1 The screen position of the left edge of the unknown rectangle othery int_out 2 The screen position of the top edge of the unknown rectangle otherw int_out 3 The width of the unknown rectangle in ixels otherh int_out 4 The height of the unknown rectangle 296 EI 4 i M LLL tT L COL rsrc_load Load a Resource rsrc_load Opcode 110 This function allocates memory for a resource file loads it into memory and performs the steps required to change the file into an object array of the proper format These steps include changing array offsets into absolute ad dresses and character aligned screen references into absolute horizontal and vertical positions The rsrc_load function calls the routines rsrc_obfix and rsrc saddr to perform these conversions Once the resource has been loaded into memory the address of a particular array element may be found using the rsrc_gaddr function C binding int status char filename status rsrc load
240. in pixels height int in 4 The initial height of the window in pixels Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also wind_close wind_create GE eR ed J XLI E I OLL L l L tL L wind close Erase a Window wind close Opcode 102 This call removes a window from the screen Though the window is no longer displayed its resources remain allocated and it may be reopened at any time until the wind delete function is used to release those resources C binding int wi handle status status wind close wi handle Inputs control 0 102 Opcode control 1 1 Number of 16 bit inputs in int Lin array control 1 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array wi_handle int_in 0 The ID number of the window to be closed Results status int_out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also wind open wind delete 287 wind delete Deallocate a Window wind delete Opcode 103 This call is used to release the system resources held by a window The wind close call should first be used to erase the window s screen display Once a window s resources have been released it c
241. in screen pixels Reserved for future use always equals 1 The final horizontal position of the mouse pointer The final horizontal position of the mouse pointer The final mouse button state 0 both buttons up 1 left button down right button up 2 right button down left button up 3 both buttons down The status of the keyboard shift keys Each key is represented by a different bit A 1 in that bit position means that the key is down while a 0 means that it s up 233 Bit Bit Value 0 1 1 2 2 4 3 8 See also evnt_multi 234 evnt mouse Key Right Shift Left Shift Control Alt dJ d d 3 3 LO L LO LL bs L CEE evnt_mesag Wait for Message Event evnt mesag Opcode 23 This function waits for a standard 16 byte message to appear in the message pipe When the message appears it reads the 16 bytes into a buffer Messages can be used by one task to communicate to another task or even to itself For example the AES Screen Manager task sends standard mes sages to let an application know when one of its menu items has been se lected or when one of its windows needs to be redrawn C binding int reserved msgbuf 8 reserved evnt mesag msgbuf Inputs control 0 23 Opcode control 1 0 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results i
242. in screen pixels height int_out 4 The height of the centered dialog rectan gle in screen pixels 265 form keybd Handle form do Events form keybd Opcode 55 This is the routine form do calls after its evnt multi call detects a keypress If this routine detects a control key like the Tab or Up Arrow it select the next editable text object If it detects the Return key it selects the DEFAULT object Otherwise it filters the keystroke and passes the printing key back to the calling routine Since it is such a limited subset of form do functions it is of interest mainly to programmers writing their own form do routine C binding There is no official C binding for this routine Therefore if you wish to call it from C you must either write a machine language function to call it write your own bindings or place the correct values into the global arrays directly and then call the crys_if 55 function which is in the regular bindings If you choose either of the latter two you must also change the values in entry 55 of the ctrl_cnts array which is in the regular bindings in the file GEMSTART S for the Alcyon compiler to dc b 3 3 1 func 55 Inputs control 0 55 Opcode control 1 3 Number of 16 bit inputs in int in array control 2 3 Number of 16 bit results in int_out array control 3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out ar
243. inding int status type controls knownx knowny knownw knownh otherx othery otherw otherh status wind calc type controls knownx knowny knownw knownh amp otherx amp othery amp otherw amp otherh Inputs control 0 108 Opcode control 1 6 Number of 16 bit inputs in int in array control 2 5 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array type int_in 0 A code specifying the type of calculation to perform 0 return border position and size 1 return work position and size controls int_in 1 A code which specifies the window con trol components present in this window Each window control is represented by a bit in this word If the bit which corre sponds to a given control is set to 1 that control is present The bit assignments are Bit Bit Value Macro Name Window Control 0 1 0x001 NAME Title Bar 1 2 0x002 CLOSER Close Box 2 4 0x004 FULLER Full Box 3 8 0x008 MOVER Move Bar 4 16 0x010 INFO Information Line 5 32 0x020 SIZER Size Box 6 64 0x040 UPARROW Up arrow for vertical scroll bar 7 128 0x080 DNARROW Down arrow for vertical scroll bar 8 256 0x100 VSLIDE Slider for vertical scroll bar 9 512 0x200 LFARROW Left arrow for horizontal scroll bar 10 1024 0x400 RTARROW Right arrow for horizontal scroll bar 11 2048 0x800 HSLIDE Slider for horizontal scroll bar knownx int
244. inding the overlap area looks like this define MAX X Y X gt Y 00 00 define MIN X Y X lt Y 00 Y olapx MAX x1 x2 olapy MAX y1 y2 olapw MIN x1 w1 x2 w2 olapx olaph MIN y1 h1 y2 h2 olapy If both the overlap rectangle width and height are greater than 0 then there s an overlap area that needs redrawing Before you do the actual redrawing however you must set a clipping rectangle Clipping confines your graphics output to the specified rectangle When the drawing operation attempts to go outside that rectangle nothing is output If your program uses the VDI to draw the window contents you may set a clipping rectangle with the VDI call vs clip This call takes the form int handle points 4 vs clip handle 1 points where handle is the VDI workstation handle and points is an array containing the coordinates for two opposite corners of the rectangle Note that the VDI representation of a rectangle as an array of points differs from the AES convention of speci fying one point of origin and then specifying the width and height To convert from AES format to VDI format place the rectangle x and y in the first two array elements x width 1 in the next and y height 1 in the last GRECT olap int handle points 4 point 0 olap g_x point 1 olap g_y point 2 olap g_x olap g_w 1 point 3 olap g_y olap g_h 1 vs_clip handle 1 points
245. indow The total text is too large to be displayed on screen at one time In order to see the rest Of the text you must use the right scroll bar s There are three different ways you can scroll the text The first is to click on the up or down arrows This scrolls the text up or down one line Qf course if the first line Of text is already at the top you can t scroll up Nor can you scroll down if you re at the botton of the window j n Mu The second way to scroll is to click on the space between the Slider and the arrow This u moves the text up or down s Dage at a time LL I 4 d bd i a J mal L L L L t mn AES Events The third way is to drag the slider with the mouse This moves the text a proportional distance up or down un 35 demo int done amp close window flag long slsize 4 size of slider vst_alignmant handle 9 5 amp done amp done set text alignment ttop start with top line of text at top of window amp calculate exterior size of window for text wind calc 9 WDW_CTRLS cellw 5 cellh amp S cellw TCOLS 4 cellh SROWS 4 amp work g x amp work g_y amp work g w amp work g_h 3 set the window to that size amp wind set iwi handle WF CURRXYMM work g x work g y work g w work g h j IX find
246. indow to half size do main program loop amp evnt_mesage msg get messages closed handle msg and handle them whilelclosed lt 2 til both windows are closed wind open wi _handle 9 9 9 9 open lst wdw so shell can close wind delete wh2 delete second window gt handle_msg message handler int closed FALSE gwitch mnsgto21 t check message type case WM_REDRAW if redraw call refresh routine refresh msgl3 J GRECT 2 amp msgr41 break case WM TOPPED if topped send to top wind set msgL 323 WF TOP 2 9 break case WM SIZED if sized check for min size then resize msgl6J MAX msgl6 cellwt amp 8 msgt73 MAX msgl7I cellht4 wind set msg 31 WF_CURRXYWH msgt43 msgL523 msgL61 msgt 72 redraw msg msg 3 GRECT msgr42 break case WM MOVED t if moved make sure the window stays on the Desktop if msgC 4J msgt6 gt desk g x desk g_w msg 4J desk g_x desk g_w msgt632 if msg 3J msgl7 gt desk g_y desk g h msg SJ desk g_y desk g_h msgt7 wind set msgEL3J WF CURRXYWH msgC43 msg SJ msgl6 msgt72 break case WM FULLED if fulled do toggle routine toggle msagl33 3 break J e e x ed wil id L E ELL L L L AES Events case WM CLOSED if closed close window and increment count
247. ing passed in the int in array and control 3 to indicate the num ber of addresses being passed in addr_in The AES uses con trol 2 to specify the number of integers being returned in int out and control 4 to specify the number of addresses it has returned in addr out Machine Language AES Calls If you are programming at the machine language level you must explicitly reserve memory space for each of these arrays and put the proper values in each of the memory locations before calling the command The first step is reserving space for each of the data arrays Array Name Storage Space global ds w 15 control ds w 5 int in ds w 16 addr_in ds 1 2 int out ds w 7 addr out ds l 1 Since each AES call uses a fixed number of inputs and outputs it s possible to determine the maximum number of bytes need for these arrays In addition to allocating data array space you must also define an AES parameter block This pa rameter block contains the beginning address of each of the 12 ee LI ai 7 2 973 3 3 T CC GEM and the AES six data arrays apb dc l control global int in int out addr in addr out These addresses must be arranged in the order shown above since the AES uses the parameter block to find the data arrays Once you ve set up the arrays and the parameter block you must place any input parameters into their correct place in the data arr
248. ion they report its results to the application This means that the pro grammer can easily create interactive forms with his or her re source construction program and can let these functions take care of the the job of watching for user input The AES aids the user in filling in the blanks and checking the boxes and provides the results to the application Forms The simplest kind of form is an error box This is a box object which contains an image a text string and a button The im age which appears at the left side of the box is that of a stop sign The text string which appears at the top of the box either contains an explanatory error message or just reads TOS error X where X is a number that corresponds to a TOS sys tem error Finally the button appearing at the bottom of the box reads Cancel This form makes it easy to let the user know when a TOS error occurs When a TOS function returns an er ror number your program can simply call form error which will display the error message box until the user clicks on the Cancel button The syntax for the form error call is int exitbutn error exitbutn form error error where error is the error number Unfortunately GEM is de signed with IBM PC DOS error codes in mind rather than GEMDOS error codes returned on the Atari ST computers 155 CHAPTER 6 Therefore in order for form error to print out its error mes sages correctly you must convert the GEMDOS
249. ion with the AES which then initializes sev eral elements in the application s global data array One of these contains the ID number which the AES assigns to the application This ID number is used by other tasks such as the GEM Screen Manager when they wish to communicate with the application through its message buffer C binding int apiid ap id appl_init Note As of this writing the C bindings do not return the correct value in ap_id Since this value is returned in the global variable gl apid the follow ing work around may be used extern int gl_apid int ap_id appl_int ap id gl_apid Inputs control 10 Opcode controlf1 0 Number of 16 bit inputs in int_in array contro2 1 Number of 16 bit results in int_out array control 0 Number of 32 bit inputs in addr in array control 4 Number of 32 bit results in addr_out array Results ap id int_out 0 Application ID number See also appl_exit 223 appl read Read Message Pipe appl_read Opcode 11 Reads a specified number of bytes from the application s message pipe C binding int status ap id length msgbuf status appl read apLid length msgbuf Inputs control 0 11 control 1 2 control 2 1 control 3 1 control 4 0 ap_id int in 0 length int in 1 msgbuf addr_in 0 Results status int out 0 See also appl write appl_init 224 Opcode Number of 16 bit inputs in int Lin arra
250. ire string is considered to be composed of spaces While this is handy for the programmer if the user edits the first character of the string to this symbol the string will be blank the next time the text object is displayed The next field te_ptmplt is a pointer to the template string This string controls the format in which the text field is displayed It is composed of constant text characters that won t be edited and underscore characters which indicate the posi tion of at which the editable text is entered For example say 108 dd dd am Ael au uet a uut dJ ELL mM CCC CC GEM Graphics Objects that the editable field is being used for the entry of a tele phone number The template string might be Phone Number If the initial string was 1234567890 the text object would be printed as Phone Number 123 456 7890 If the initial string did not have enough characters to fill out the template string the unfilled underscore characters would be printed The third field te pvalid is a pointer to the validation string This is a string that shows which type of character may be entered at a given character position This string is com posed of special validation characters each of which stands for a class of allowable input Validation Character Input Accepted 9 Numeric digits 0 9 only a Upper and lowercase alphabetic characters and the space character
251. is nobody s idea of fun As you ll see in the next chapter there s a much easier and more effective way to create object trees For machine language programmers Program 4 2 is a rough translation of the C sample program above For the sake of brevity the direct manipulation of the object x y width and height fields was skipped in favor of using an AES Li brary routine rsrc_obfix which does the same thing This li brary routine will be discussed in the next chapter Program 4 2 object s RSET TEESERESES ESTE RSES NESS ERD CEST OA EO CER RCC eee 4 OBJECT S Demonstrates low level object calls x x ittk tkz tXxkt 5 5 z1455z429255525225222552222222222222222525525952 2255 2 External references Export xdef demo external demo subroutine xdef wdwuctrl window controls xdef wdwtitl window title string xdef wdwinfo X window info string gi Imports xret aes the AES subroutine xret ctrl and the AES data arrays xref ctr11 xref ctr12 xref ctr13 xref ctrl4 xref addrin 126 NR i 1 m OR IL J LLL s LCC L GEM Graphics Obiects xref text demo aintin aintout workx amp and the window work rectangle worky wor kw wor kh g Fix object position and size from characters to pixels Rove move move move move move 1 fixloop move jsr dbra 2 04 k for three objects 114 ctr1 d op
252. it uses the graf_mouse function to turn off the mouse pointer and change its shape the graff_mouse function will be discussed in greater detail later If the essential initialization steps are not completed suc cessfully init all returns the appropriate error code If no error occurred the user supplied demo routine is executed Finally the cleanup module closes and deletes the window closes the workstation and exits the program A Machine Language Program Shell Setting up a bare bones machine language program is more involved than just translating the corresponding shell c pro gram For one thing C programs usually link in a startup file at the beginning of the program to take care of such mainte nance chores as allocating RAM for a program stack setting the stack pointer to the address of that that stack and return ing any unused RAM to the pool of free memory Programs written with Alcyon C link in the file appstart o or gemstart o at the beginning to take care of these tasks and Megamax C programs get the necessary code from a library module called init o the source code for which is supplied in a file called init c it uses the inline assembly commands But machine language programmers must provide the equivalent functions for each of their programs themselves The other problem is that not all assemblers have an in clude directive so you won t be able to include the text of the shell program in each of our demo
253. ith the Alcyon C compiler and all compilers whose bindings derive from Atari s Inputs controlf0 46 Opcode controlli 4 Number of 16 bit inputs in int in array control2 2 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr out array object int in 0 The object number of the editable text object char int in 1 The text character entered by the user index int in 2 The position of the next character to be entered in the text string cursor position type int in 3 A code specifying the type of operation to perform Valid code numbers include the following Type Macro Number Name Description of Function 0 ED_START Reserved for future use 1 ED INIT Combine the template string of TEDINFO field te_ptmplt with the text string of the te ptext field to display the formatted string and then turn the cursor on 2 ED_CHAR Check the input character against the validation string in TEDINFO field te_pvalid update the te ptext field if the input character is valid and display the changed text 3 ED_END Turn off the text cursor tree addr_in 0 The address of the object tree array which contains the objects 255 objc edit Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution index int out 0 The new position of the next character to
254. itor mouse move ments outside of the active window provide visual feedback where appropriate and report the outcome of the user s activ ity when that activity has some meaning to the application For example say the user moves the mouse to the size box at the bottom right corner of a window border When the mouse pointer moves out of the active area of the window and into the window border the Screen Manager watches it If the user presses the left mouse button while the pointer is over the size box and holds it down while moving the mouse the Screen Manager is responsible for drawing a dotted window outline that follows the mouse pointer When the user releases the mouse button the Screen Manager sends a message to the application telling it the size of the window requested and control returns to the application Then it s up to the program to decide whether to change the size of the window in compli ance with the user s request The Screen Manager s major areas of responsibility are handling the drop down menu system and the window con trols When the mouse pointer crosses into the menu bar the Screen Manager saves the screen rectangle where a menu is to be displayed and then it displays the menu It handles the highlighting of menu items as the pointer travels over them and redisplays the saved screen area if the left mouse button is clicked If the button was clicked while the pointer was over a menu item the Screen Manager sends
255. ivisions are the Vir tual Device Interface VDI and the Application Environment Services AES The VDI was discussed in Volume One of this series It provides a number of low level device independent drawing routines also known as graphics primitives It also supplies some fundamental input functions for receiving data from BE mouse and keyboard The AES provides user interface features called environ ment services These are the features usually associated with GEM drop down menus overlapping windows icons and di alog boxes It S important to understand that ST system software is hi erarchical see Figure 1 1 At the bottom of the hierarchy are the routines known as the BIOS Basic Input Output System XBIOS eXtended BIOS and Line graphics routines These routines communicate directly with the ST hardware and peripherals The GEMDOS Disk Operating System builds on i 70 9 1 u J aa LL U OUO LLELE GEM and the AES the disk access routines in the XBIOS to provide a filing sys tem Similarly the GEM VDI builds upon low level Line A graphics routines to provide higher level device independent graphics routines Finally the GEM AES uses the graphics and input primitives supplied by the VDI to provide a sophisti cated user interface Figure 1 1 Parts of the ST Operating System The AFS is itself made up of a number of parts At the lowest level is the multitasking kernel Its job is
256. ject not an offset from its parent The clipping rec tangle likewise represents a rectangle on the physical screen The last field in the PARMBLK structure is called pb parm and it contains whatever value you placed in the up parm field of the APPLBLK structure To summarize when you define a G_PROGDEF type ob ject you place a pointer to an APPLBK structure in its ob spec field That APPLBLK contains the address of a draw ing routine and a long word parameter When the object must be drawn or when its state field changes the AES calls your drawing routine The AES passes a pointer to your drawing 114 d a B J J Jj J J jJ bt tk L L L fL GEM Graphics Objects routine which points to a PARMBLK containing information about the object s size position and state For example if your APPLBLK points to a drawing routine called user code This routine would be defined like this user code pb PARMBLK pb read parms read whatever parameters necessary from PARMBLK do draw draw the object or whatever else you want to do return 0 your routine should always return a value of zero j A few words of caution are in order about what your drawing code can contain First your routine is being called by the AES and uses the AES s stack Therefore avoid program ming techniques which use a large amount of stack space For instance you will probably want to avoid using lon
257. jsr aes t Do our demo program jsr demo 44 a ak al i J P Y E ck Ld Hine 1 LULL L reo 5 Starting an Application ttt Close the Window move 192 ctri command wind close move 1 ctr11 move 1 ctr12 move 0 ctr13 move H ctr14 move wdwhnd aintin jer aes Delete the Window move 4 195 ctrlO amp command wind delete jsr aes amp x Close Virtual Screen Workstation v_clsvwk wdwerrt move 191 contr19d opcode to contrl move 89 contr11 no points in ptsin mova 9 contr1 3 no integers in intin jsr vdi Finish the application appl exit vwkerrs move 19 ctr19d opcode to contrl nove 40 ctr11 jer aes Exit back to DOS apperr move l 49 a7 Push command number for terminate program trap 1 call GEMDOS Bye bye att Make AES function call after setting parameters aes move l ttapb d1 MOVE W aescode d trap 2 rts xxx Make VDI function call xs after setting parameters vdi move 1 vpb di MOVE W vdicode d trap 2 rts Storage space for AES and VDI call parameters data even CHAPTER 2 4 2 2 VDI Data Arrays 59 contr1 contr18 contr11 contr121 coantr 13 contr14 contr13 contr1 63 contr17 contr18 contr19 contrl 18 contr111 intin intout ptsin ptsout ds w ds w d5 W ds w
258. k is four bytes long you can find the address of each succeeding data array by PEEKing the next four bytes in memory 30 global PEEK apb 4 40 gintin PEEK apb 8 50 gintout PEEK apb 12 60 addrin PEEK apb 16 70 addrout PEEK apb 20 Notice that we used the variable names gintin and gintout for the int_in and int_out arrays That s because the original version of ST BASIC doesn t allow the underscore character in variable names and the names intin and intout are already re served for the data arrays used by the GEM VDI Notice also that we ve placed a pound sign at the end of the variables that 14 Sud uo na LI a7 d T L L ft L E UL GEM and the AES hold the addresses of addr_in and addr_out That s because the values in these arrays are four bytes long By declaring the type of these variables as double precision BASIC will know it should PEEK or POKE four bytes at a time You may read the contents of the various data arrays or write to them by using the PEEK and POKE commands Since each element in gintin and gintout is two bytes long you must multiply the element number by 2 to get the proper offset for the POKE statement Each element in addrin and addrout is four bytes long so you must multiply the element number by 4 to get the proper offset for those arrays To write a value to int out 1 you d POKE gintout t 4 and to write a value to
259. k reliably use it with caution and don t be surprised if it s changed in future versions of the operating system 148 d sf Sod 4 xd ub S Rd J J LLE L L tC EL Resource Files and Menus Some menu selections represent Boolean on off types of choices For example a text editing program might allow you turn a word wrapping feature either on or off If your menu item allows the user to toggle this feature from on to off to on again there s got to be some way of knowing what the current state of affairs in order to determine whether or not to toggle the item One way of letting the user know is to put a check mark next to the text of the menu item when it s selected and to erase it when it s not selected The menu_icheck function al lows you to either place a checkmark next to the text of a menu item or to erase the checkmark The syntax for this call is int status item setting OBJECT tree status menu_icheck tree item setting where free is a pointer to the menu object tree item is the ob ject number of the menu item and setting is a flag indicating whether you want to place the checkmark or remove it A set ting of 1 adds the checkmark and a setting of 0 removes it Since the checkmark is drawn at the left side of the text box you should always leave one or two blank spaces in front of the item s text this will make the menu look better whether or not you use checkmarks As with menu_i
260. ke the appropriate action While you are performing what ever task the user has selected the AES leaves the menu title display highlighted to show that the program is busy pro cessing the menu request When you ve finished you must change the title back to its normal video display with the menu tnormal function The calling format for this function is int status title setting OBJECT tree status menu tnormal tree title setting where free is a pointer to the menu object tree title is the ob ject number of the title and setting is a flag indicating how you want that title displayed If setting contains a value of 1 the title will be drawn in normal video If setting is 0 the title will be highlighted in reverse video Under normal circum stances you ll be using word 3 of the message buffer for the ti tle object number and a setting of 1 Program 5 1 demonstrates some simple menu handling It sets up a menu with three titles and four selectable items The DESK menu contains one item About Menul The FILE menu contains one item Quit C The DRAW menu contains two items Pattern 1 F1 and Pattern 2 F2 The About item on the DESK menu is used to display an alert box those will be covered in more detail in the next chapter the two DRAW items draw patterned ellipses in the program window and the Quit item is used to exit the program Because this is a simpli fied example the handle msg routine only deals with menu
261. ls cliph int in 5 The height of the clipping rectangle in screen pixels state int in 6 The new value for the object s ob_state ag redraw int in 7 code which specifies whether or not the object should be redrawn after the state change 0 no redraw of the object the object is redrawn tree addr_in 0 The address of the object tree array whic contains the objects Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution 257 form do Handle Dialog form do Opcode 50 Form do is like a small subprogram that monitors the user s interaction with a dialog box It handles the selection of objects with the left mouse but ton and also handles the entry of text into the editable text objects Since form do itself calls evnt_multi it takes control of all event waiting This means that menus do not function while form do is executing C binding int exitobj editobj OBJECT tree exitobj form do tree editobj Inputs control 0 50 Opcode control 1 1 Number of 16 bit inputs in int_in array control 2 1 Number of 16 bit results in int_out array control 3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out arra editobj int_in 0 The object number of the editable text field at which the cursor should be posi tioned when the dialog is initially dis
262. ly the initial lines of a desk accessory program would look like this appl_init menuid menu Lregister gl apid Accessory Name The function returns a menu ID number in the menuid variable The ID number is used to identify which menu item was used to start the accessory program This is necessary be cause a single accessory can register more than one menu item For example a single accessory program displays both the control panel and printer setup menu items Note how ever that there are only six menu slots available on the DESK menu When these are used up no additional desk accessories may be loaded This means that each additional menu item used by an accessory reduces the total number of desk acces sories that may be loaded For this reason your accessory should stick to one menu item and use its own system for pre senting multiple functions such as a dialog box The AES uses the message system to inform a desk acces sory when one of its menu items is selected Since the desk accessory has no control over the menu bar it can t use the MN SELECTED message the way regular applications can Instead the AES sends it an AC_OPEN message The format for this message is as follows 202 d eR del ael d J ab ow aed uud he LLL L Et IL Em Desk Accessories Word Number Contents 0 40 AC_OPEN the message ID number 4 The menu item number menuid of the desk accessory the user selected Th
263. m memory first SETBLOCK parameter on the stack push the beginning address of the program memory area 2nd SETBLOCK parameter sp clear a dummy place holder word finally push the GEMDOS command number for the SETBLOCK function call GEMDOS and clear our arguments off the stack ze the application with appl_init s2 resvi clear globa variables 6 resv2 nO resv s 6 resv4 16 ctr1 command appl init s ctrli no integer input parameters amp 1 ctr12 1 integer output parameter 88 ctrl13 no address input parameters 8 ctri4 no address output parameters aes do the call 4 9FFFF apid check to see if init failed apperr and exit if it did physical screen device handle from graf handle 877 ctrl command graf handle 5 ctrl2 amp 5 integer output parameters aes do the call aintout pwkhnd save handle and char sizes aintout 2 cellw aintout 4 cellh aintout chboxw aintout 8 chboxh Open the Virtual Screen Workstation v opnvwk move move move move movea l move initloop move w dbra 199 contr1ad opcode to contr 9 contrlt no points in ptsin 11 contr13 11 integers in intin aintout contrl physical workstation handle to contri 6 Sintin 2 a0 destination address 8 d loop counter 4 1 a29 intin 1 intin 9 1 d2 initloop 33333 JJ dAd E LL EL L CLE L RES nie move MOVE W
264. menu ob ject trees it would be extremely difficult to construct one with out using a resource construction program When you open a menu type tree with a resource con struction program it automatically creates the root object the BAR the SCREEN the ACTIVE and a couple of default menu titles containing appropriate menu items Whenever you create a new menu title the program changes the size of the AC TIVE moves the new title so that it s adjacent to previous ones and creates the drop down box with space for a single menu item In return for this convenience however these programs enforce some restrictions Most only allow you to use G_STRING type objects for menu items While GCSTRINGs are the preferred choice for this task because it s easy for the AES to draw them quickly there are some cases where you might prefer to use box type objects or even icons In order to add non G_STRING objects as menu items with the resource construction programs you must first create the menu tree then close it and change its tree type from menu to dialog At that point you can enlarge the drop down boxes and add any object that you wish Each object how ever should still stretch across the entire width of the drop down box If you want to place two or more siblings side by side on a line make sure that you cover them with another 141 CHAPTER 5 sibling that occupies the whole line so that they all get se lected at the same time wh
265. message and handle it sort of graf mouse tM OFF L amp turn the mouse pointer off clear rect amp work IX clear the area graf mouse M ON L and turn it back on strcpy filespec path copy path to filespec buffer z strlen filespec remove characters from end while z amp amp filespec z 1 s VW 2 73 until you get to backslash amp filespec z2I 9 strcat filespec file and add filename to path print complete path filename v gtextthandle 19x cellw i fcellh filespec evnt nesage amp msg amp wait for the window close message SEREAEEESEEEEAEEEEEEEE End of Fselect c 595 25245345455t92 233222252 Although fsel input takes care of all of the interaction with the user some additional steps are required before and after making the call For one thing the user may have put your program on a second floppy or hard drive so it might be frustrating to find it if you always used the A drive for the de fault search path The safest course of action is to set the de fault search path to the current directory the one from which the program was run In order to find the current directory it s necessary to use a couple of GEMDOS routines The first rou tine is referred to by the macro name Dgetdrv which is defined in the OSBIND H file This call returns the current drive num ber 0 A 1 B and so on The second r
266. message bra main amp and loop back BB gt gt gt gt gt gt gt gt gt gt End of Main Program Code 4 4 444444444 Vh gx Initialize workstation and window tst initouts Open the Virtual Screen Workstation v_opnvwk move 8123 contr1 opcode to contri ig move ag contr11 no points in ptsin move 8 11 contr13 11 integers in intin move pwkhnd contrl amp physical workstation handle to contri 6 movaa l1 intint2 ad amp destination address move 8 dd loop counter initloop MOVE W 1 a amp intin 1 intin 9 1 dbra d initloop move 2 intin 29 intin 190 2 Raster Coordinates MOVE W 4 sp push getrez command on stack trap 14 call XBIGS addq 1 2 5p pop command off stack addq 82 d9 move d intin use rez 2 as device ID jer vdi move contrl1 6 vwkhnd save virtual workstation handle beq vwkerr end program if it s zero Find max window size move 194 ctr1d command wind get move 42 ctr11 2 input integers move aS ctr12 S output integers move 9 aintin window handle of Desktop move 4 aintin 2 WF WORKXYWH command jer aes move aintout 2 deskx store desk x y w h move aintout 4 desky move aintout deskw move aintout 8 deskh tg Create a window with max size move 4 100 ctrlO command wind create move 45 ctr11 5 input integers move 41 ctr12 1 ouput integer move wdwctrl a ntin
267. mp kstate where the mflag input variable is used to indicate whether you want to watch for the pointer entering the area or leaving it A value of 0 means that you want to watch for its entry and a value of 1 means that you want to watch for its exit The x po sition y position width and height of the rectangle are passed in the variables rectx recty rectw and recth As with mouse button events the status of the mouse buttons is returned in the variable button and the status of the shift keys in the variable kstate The meaning of these coded returns is the same as for the mouse button events above GEM reserves a return variable for future use Currently a value of 1 is always returned in reserved 90 tea cg i a ed nd d L oL E tL i E Lh C AES Events Mouse rectangle events have many uses A common one is to notify the program when the mouse enters a particular area of the screen so the program can change the mouse pointer form Rectangle events can also be used to detect any movement of the mouse Simply wait for the pointer to exit from a rectangle one pixel in size and located at the current pointer position Keyboard Events You can wait for the user to press a key on the keyboard by calling the function evnt_keybd The syntax for this function is int keycode keycode evnt_keybd where the variable keycode contains a two byte v
268. n addr_out array msgbuf addr_in 0 The address of a 16 byte buffer in which the AES will store the message Results reserved int out 0 Reserved for future use always equals 1 Upon return from this function a 16 byte message will be stored in the buffer pointed to by msgbuf The general format for AES messages is Element Number Contents 0 Message ID indicates type of message 1 Application ID of message sender 2 Number of additional bytes in message in excess of the standard 16 3 7 Message dependent There are a number of standard AES messages The specific formats for these message are Word Number Contents 0 10 MN SELECTED message A menu item was selected by the user 3 The object number of the menu title that was selected 4 The object number of the menu item that was selected 235 evnt mesag Word Number IO Ul 0 Word Number Word Number Word Number Word Number Word Number Contents 20 WM_REDRAW message A window display needs to be redrawn The handle of the window whose display needs refreshing The x position of the damage rectangle The y position of the damage rectangle The width of the damage rectangle The height of the damage rectangle Contents 21 WM_TOPPED message The user selected a new window to be active The handle of the window the user selected to be active Contents 22 WM CLOSED message The user clicked on the Close Box The handle of the
269. n immediately with the first one If there are no messages in your program s message pipe a call to evnt_mesag will force your program to wait until one is received The values actually placed in the msgbuf array depend on the type of message sent The format for the first three words of each message is standardized Element Number Contents 0 Message ID indicates type of message 1 Application ID of message sender 2 Number of additional bytes in message in excess of the standard 16 3 7 Message dependent S tak Wt o Nw td C tC CE L LE rere AES Events The contents of the last five words of the message vary depending on the message type Although the standard GEM message is only eight words long it s possible to send a longer user defined message to another task using the appl_write function That s why the third word of the standard message format contains the number of additional bytes in the mes sage To receive the rest of the message the task must read the message pipe directly using the appl_read function which will be discussed later on along with appl_write There are 13 predefined AES messages which the Screen Manager task sends to the application These are as follows Message Number Macro Name Message Sent 10 MN SELECTED A menu item was selected by the user 20 WM_REDRAW A window display needs to be redrawn 21 WM TOPPED The user has selected
270. n is int status id length msgbuf status appl_write id length msgbuf 62 Ew ot Sul L4 N A RUM dd COoOoce C L LL EL AES Events where id is the application ID of the task to which you are sending the message length represents the length of the mes sage in bytes 16 is the standard length for an eight word message and msgbuf is a pointer to the buffer which contains the message The value returned in status equals 0 if there was an error in performing the function and it s greater than 0 if no error occurred To send a redraw message to your own application therefore you could use the following code int wi handle The handle of the window to be redrawn GRECT r The redraw rectangle int mse 8 The message buffer msg 0 WM_REDRAW Message type is window redraw message msg 1 gl_apid Application ID stored in Global array msg 2 0 Message is standard 16 bytes long msg 3 wi_handle Handle of window to refresh msp 4 r g x Position and size of redraw rectangle msg 5 r g y msg 6 r g w msg 7 r g h appl_write gl_apid 16 amp msg Sending a message to your own application is easy since a program can always find its own application ID by looking in the global array To send a message to another application however you must first find its application ID using the func tion appl find The syntax for t
271. n of the left edge of the boundary rectangle The box outline cannot be dragged past the borders of this imaginary screen rectangle boundy int in 5 The vertical position of the top edge of the boundary rectangle boundw int_in 6 The width of the boundary rectangle in pixels boundh int_in 7 The height of the boundary rectangle in pixels Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution 269 graf dragbox endx int out 1 The screen position of the box s left edge at the time the user released the left mouse button endy int_out 2 The screen position of the box s top edge at the time the user released the left mouse button See also form do evnt_multi evnt button 270 JS ft d J 4 ud wd dJ J d tL L E EL C EL LL graf mbox Draw a Moving Box graf mbox Opcode 72 Draws and erases a series of box outlines to give the impression of a box moving from one position onscreen to another C binding int status width height beginx beginy endx endy status graf_mbox width height beginx beginy endx endy Note Digital Research documentation refers to this function as graf_movebox However the C language bindings released by Atari Cor poration with the Alcyon C compiler and libraries derived from Atari s code such as those supplied with the Megamax C compiler use the grafzmbox terminolog
272. nding overlapping rectangles 101 2 flags 115 19 formatted text 107 10 formatted text borders 107 icons 111 13 parents 98 position 101 2 sample tree 101 2 siblings 98 size 101 2 states 119 20 text strings 106 7 types 103 user defined 113 15 user editing 122 23 walking the tree 100 101 object states 119 20 CHECKED 120 CROSSED 120 DISABLED 120 OUTLINED 120 SELECTED 119 SHADOWED 120 object trees 9 98 ob next 98 ob_spec 104 5 4 d 1 1 d J3 d LI EL aar i L n L L t ob_states 119 ob_tail 98 ob_type 103 opcode 11 12 output parameter arrays 12 overlap rectangle 62 Parameter Block 15 parameter shape 16 PARMBLK 113 14 pb_currstate 114 pb objc 114 pb_parm 114 pb prevstate 114 pb_tree 114 PEEK 14 phys handle 23 physical screen handle 23 pointers 98 188 89 address 188 shape 189 points 60 polling 53 94 programs aesshell s 40 47 deskacc c 204 9 deskacc s 210 18 dialogl c 164 69 dialog2 c 182 83 dummy c 35 39 dummy s 49 50 fselect bas 174 75 fselect c 172 73 menul c 144 48 menu2 c 150 52 message c 69 72 message s 73 78 mousform c 190 92 mousform s 192 95 object c 125 object s 126 28 scroll c 84 87 RAM Random Access Memory allo cating 9 10 raster coordinates 22 Ready list 5 rectangle list 58 60 finding visible rectangles 58 window refresh procedure 59 rectangles 60 101 2 convert from AES to VDI 60 finding overlapping 101 2 redraw messages 63 65 66 sending to
273. ndle int in 0 The ID number of the window whose settings are to be changed field int in 1 A code which specifies the window setting to change Valid setting changes are Field Number Macro Name Aspect to Change 1 WF_KIND x Window controls flag same as controls for wind create 2 WF_NAME x y Address of string containing the name of the window 3 WF_INFO x y Address of string for the window s information line 5 WF CURRXYWH Window exterior coordinates 8 WF_HSLIDE x relative position of horizontal slider 1 leftmost position 1000 rightmost 9 WF_VSLIDE x relative position of vertical slider 1 top position 1000 bottom 10 WF_TOP x window handle of the top active window 14 WF_NEWDESK The address of an object tree to be used for the Desktop Window background x low word y high word of address width number of starting object to draw 15 WF_HSLSIZE x relative size of the horizontal slider compared to the scroll bar 1 minimum size 1 1000 percentage filled in tenths of a percent 16 WF_VSLSIZE x relative size of the vertical slider com pared to the scroll bar C1 minimum size 1 1000 percentage filled in tenths of a percent 291 wind set X int_in 2 Specific to setting as described above y int_in 3 Specific to setting as described above width int_in 4 Specific to setting as described above height int_in 5 Specific to setting as described above Results
274. ndle of the window whose scroll bar was clicked 4 The action requested by the user 0 Page up user clicked on scroll bar above vertical slider 1 Page down user clicked on scroll bar below vertical slider Line up user clicked on up arrow Line down user clicked on down arrow Page left user clicked on scroll bar left of horizontal slider Page right user clicked on scroll bar right of horizon tal slider Column left user clicked on left arrow Column right user clicked on right arrow N gi A GQ bh d d 3J 1 x d d 0t Lt FL L B e i L L E AES Events As you can see the eight possible cases are represented as subcommands in msgbuf 4 What exactly your program does in response to these messages depends somewhat on the type of information being displayed By convention when the user clicks on an arrow the display should scroll by the smallest indivisible unit If the display is text for example you incre ment or decrement the starting position of the display by one character row or column and move the slider accordingly When the user clicks on the scroll bar between an arrow and the slider you should scroll the display by a larger increment typically the number of units that fit on a display screen Thus if 20 lines of text fit on a screen you might scroll the document by 20 lines Check first to make sure that you re more than 20 lines from the beginning or end of the document
275. ndow info line window control flag Push Button to Exit 6 9 SFFFF L 0090600935 990902FFFF exitstr 0 009UC0996 e9999FFFF pushstr 090010002 00020014 00000010 t00021109 00160090 SFFFFOSIA 00070000 090980001 FFFFOO1C 00200000 0012529090901 MESSER E pap I IP Chapter 5 Resource Files and Menus L Lt mM L L L L L L Building an object tree by calculating the data necessary for each field of each structure in the array can be a long and tedious process Each object requires 11 pieces of data One of those is an ob_spec field which may be a pointer to another data structure such as an ICONBLK which requires another 14 items of information two of which are pointers to image data arrays This means that just one object can have a large quan tity of data associated with it And GEM programs don t just use one or two objects they use dozens Alerts dialog boxes menus all are built of many many objects There are other problems with building objects out of data as well For one thing it s difficult to picture the size and rela tionship of objects based on mere numbers If the object doesn t look quite right you ve got to change the numbers and recompile to try a new combination Moreover as you ve seen from the example program at the end of the previous chapter you have to change the size and position fields for each object based on th
276. nt bne message jsr setptr if so change pointer form bra skip message move msg d if not check message type cmpi 22 d WM CLOSED bne skip move 81 d4 yes set close flag skip cmpi 0 04 check if close flag set beq main if not keep going rts gt gt gt gt gt gt gt gt gt gt End of Main Program Code amp 4 44 44X4 4X k ttg turn mouse off or on or change pointer shape setform move d7 aintin form number bra mousei mousof f move 8256 aintin hide the mouse bra mousel mouson move 257 aintin amp show the mouse mousels move 4378 ctr1 command graf mouse mova 41 ctr11 1 input integers move 4 1 ctr12 1 output integer move 1 ctrl13 1 input address move 1 pointer addrin imp aes EE set pointer form and new rectangle to watch setptr move aintout 2 d0 mouse x position move aintout 4 di1 mouse y position move workw aintin 14 amp next 3 are full window wide cmp worky di above window work area bhi setpt i move 420 d7 if so change form to arrow move 9 aintin 1d move H aintinti2 move worky d2 subq 41 02 move d2 aintin 16 bra setpt setpti move thirdh aintin 16 all of the rest are 1 3 window high move workx aintin i 2 next S start at left cmp top di if above center box bhi setpt2 move 3 d7 set to pointing hand move worky aintint12 bra setpt 194 x ek ab a x s J3 uL i LO LL L
277. nt gl apid The application ID part of the global array int ap id int contr1t1231 1 VDI data arrays intint1283 ptsinC 1283 intoutt1281 ptsout 1281 int phys handle 18 workstation handle for physical screen device handle workstation handle for virtual screen device wi handle IX window handle amp menuid menu id number t msgt83 message buffer int work inEL121 input and output arrays for v_opnvwk work outE 571 GRECT desk work 8 Desktop and application window dimensions amp int cel amp Prag maini m int err if c lw cellh chspcw chspch ram starts here error t Error flag Or init acc size of default character font Initialize application open workstation and open application window amp error while 1 amp forever evnt mesage amp msg 3 handle msg 0 13 If no initialization failures amp get messages and handle them e P d Jd dJ dJ E t L L ttt Em Desk Accessories f8 end of while gt end of if amp end of main amp amp Initialize accessory graphics workstation amp register menu t t init acc int x Initialize the GEM application If this fails return error code amp appl_init ap_id 91_apid if ap_idss 1 return APP ERR Initialize input array ge
278. ntifier or change the drive identifier in the DISK INFOR MATION dialog Jj dJ d3 d Jj L L L L L L de L Interactive Object Handling GEMDOS PC DOS Error Error Error Number Number Error form error Message 47 16 Attempted to remove the You cannot delete the current directory folder in which you are working 49 18 No more files This application can t find the folder or file you just tried to access Although GEM provides codes for more than one exit button the current ST version uses only the Cancel button so that a value of 0 is always returned in exitbutn Alerts The error form is actually a specialized case of a more versatile message display form called the alert Alert boxes are used to inform the user that a situation has arisen in which some im mediate action may be required Alerts make it easy to present to the user a short message and a choice of up to three op tions typical use is verifying that the user really wants to take some irrevocable action such as Loading new data will de stroy current data Do you wish to proceed Yes No Another use of the alert would be to inform the user of an error as in Data file cannot be loaded Cancel The alert box consists of an optional image up to five lines of text and from one to three exit buttons To display the box you use the form alert call whose syntax is int exitbutn default char string exitbutn fo
279. nu selections to change in response to changes in the program context C binding int status item char text OBJECT tree status menu text tree item text Inputs control 34 Opcode control 1 1 Number of 16 bit inputs in int_in array control 2 1 Number of 16 bit results in int out array control3 2 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array item int in 0 The object number of the menu items whose text will be replaced tree addr in 0 The address of the object tree array which supplies the data for the menu display text addr_in 1 The address of the new text string to be used for the menu item The text string should end in the NULL character ASCII 0 and should be no longer than the string which it replaces Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution 247 menu register Add Item to Desk Menu menu register Opcode 35 This function allows a desk accessory to add an item to the DESK menu A single accessory may add more than one item to the menu but all acces sories may only use a total of six menu items C binding extern int gl apid int menuid static char menutext menuid menu register gl apid menutext Inputs control 35 Opcode control 1 Number of 16 bit inputs in int in array control 1 Number of 16 bit results in in
280. number of the editable text object at which the cursor will first be placed If there are no editable text fields you should pass a value of 0 for editobj The exitobj variable contains the number of the object whose selection caused the end of the dialog animation If that object had the TOUCHEXIT flag set and was selected with a double click the high bit of the exitobj field will be set If you use TOUCHEXIT objects and don t care to check for double clicks you may want to mask that bit off before checking the object number When form do terminates the dialog is still displayed onscreen If the dialog has truly concluded it s up to your application to clean up the screen If you had used to FMD GROW subcommand of form dial at the beginning of the dialog you ll want to use the FMD SHRINK subcommand of form dial to reverse the zoom box After that optional step you ll want to use the FMD FINISH subcommand of form dial to release the screen area that had been reserved for the dialog and to re store the screen Since a dialog box can be considerably larger in size than one quarter of the screen it s impossible to store the screen background in the menu alert buffer Therefore the AES cannot automatically restore the screen background at the end of a dialog Instead it considers the screen rectangle described by the form dial FMD FINISH call as damaged and sends redraw messages to all of the windows within this area
281. o be the interior area so that the function returns the exterior dimensions A value of 1 causes the function to return the in terior dimensions of the window The controls input parameter is the same type of flag used by wind create to indicate the types of controls to attach to the window These are significant to calculating the size of the window because their presence may enlarge the border area If a window has a close box title bar move bar or full box this extends the border area at the top of the box to the height of a character box of the default character set This is the value re turned in the chboxh variable by the graf handle call If the window has an information line the top border is enlarged by the height of an additional character cell If there is a vertical slider or up or down arrows the right border is extended to the width of the default character cell This value is returned in the chboxw variable by the graf handle call Finally if there s a size box horizontal slider or right or left arrows the bottom border is extended to the height of the default charac ter cell Closing a Window When you re through using a window for displaying out put you may close it using wind close The format for this call is int wi handle status status wind close wi handle 34 E und aul uad E Jj J J J IO EL L L L L OO L Starting an Application where status contains the er
282. o make the AES call itself Before you get to that stage you must take preparatory steps to set up the program environment for instance allocating stack space and 13 CHAPTER 1 the graphics environment opening a GEM output workstation This will be outlined in the next chapter and illustrated in an example program ST BASIC VDI Calls Making ST BASIC calls employs the same fundamental strat egy for AES calls as making calls from machine language pro grams The only difference is that BASIC does much of the preparatory work for you Since the BASIC interpreter itself must use AES calls it already has set aside memory for the data arrays control global int zin int out addr_in and addr out and has set up a parameter block with the starting address of each of these arrays BASIC assigns the reserved variable GB for GEM Base to the address of the AES Param eter Block This means that the starting address of the control array can be found by using the PEEK command to obtain the address stored at the four bytes starting with address GB In order to PEEK a four byte number in ST BASIC you must specify the address to PEEK as a double precision number This can be done by assigning the value in GB to a variable that has been declared to be double precision 10 apb gb 20 control PEEK apb The pound sign at the end of apb tells BASIC that apb is a double precision variable Since each address found in the Parameter Bloc
283. of these titles the Screen Manager saves the old screen back ground in the menu buffer and draws a box beneath the title This box contains one or more menu items which represent program options that the user may select s the user moves the mouse pointer over a selectable item its text is drawn in reverse video to highlight it The user can click the mouse button over one of these highlighted items to pick it When this happens the Screen Manager restores the background display from the menu buffer and sends a mes sage to the application telling it which menu title and menu item were selected The title belonging to the item you se lected is left highlighted while your program handles the mes sage If the user decides not to select a menu item he or she may get rid of the menu either by replacing it with another or by moving the mouse pointer off the menu bar entirely and clicking the left mouse button All of the data for a menu is contained in a normal GEM object tree But since the AES Screen Manager does so much autonomous manipulation of menus this object tree must fol low a set format Since the menu system uses objects that can be located in the menu bar or anywhere else on screen the root object of the menu is a G_BOX that covers the entire display area of the screen This root object has exactly two children whose rectangles cover the root object completely The first called the BAR is a GL BOX that covers the whole menu
284. of the ST s fast friendly GEM interface with a thorough examination of the Application Environment Services AES This book will help you to understand the AES Using the AES will enable you to make your ST programs as friendly and cooperative with the user as the intuitive GEM environ ment can make them COMPUTEY s Technical Reference Guide Atari ST Volume Two The GEM AES explains ST multitasking window opera tion dialog boxes alert boxes menus input and output The latter half of this book is a complete reference to AES func tions listed according to opcode along with an alphabetical in dex These functions are complete with C bindings an explanation of input and results and more In each chapter functions are covered individually in de tail with examples of their use culminating in fully com mented sample programs written in C machine language and BASIC If you are an ST programmer this is the reference you have been looking for lt sees ea Chapter 1 GEM and the AES IO t to L UL L t Although many people think of GEM as a computer operating system Digital Research Inc DRI the creators of GEM prefer to call it an operating environment Traditional microcomputer operating systems provide access to the most basic I O Input Output devices like the keyboard display screen and disk drives but they only support the transfer of text characters Newer microcomputers
285. of the child object to be added tree addr_in 0 The address of the object tree array which contains the objects Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also objc_delete 249 objc delete Delete an Object from a Tree objc_delete Opcode 41 Deletes a child object from an object tree by unlinking it from its parent ob ject and sibling objects if any This function is not normally used by the applications programmer if a resource construction program is used to create the object trees C binding int status object struct object tree status objc_delete tree object Inputs control 0 41 Opcode control 1 Number of 16 bit inputs in int_in array control 2 1 Number of 16 bit results in int out array control3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr out array object int_in 0 The object number of the object to be deleted tree addr_in 0 The address of the object tree array which contains the objects Results status int zout 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also objc_add 250 T ee Gl ud d oad d d LL E LL L L objc draw Draw an Object Tree objc draw Opcode 42 This function draws all objects in an entire object tree
286. of the screen and changes the pointer shape as it moves into the areas above below to the right and to the left of the box When the pointer moves into the box itself it changes to the user defined shape whose data is stored in the array called pointer This pointer is supposed to look like the ST mouse itself though the resemblance is better in high or low resolution mode than in medium resolution 189 Program 7 2 mousform c 5 t 95955959295595 55 5952 952522 595 295925252525242 25252 52495925924525 2 55925252 5225222 MOUSFORM C shows how to change the mouse pointer g 1 shape as the pointer moves around the screen amp amp 3 5395 939 35599 3 51951241525225225522929229292 555 19225592 595552 5 1925929225955 25 t959559252 525 3 define APP INFO sg Click on the Close Box to exit the program 4 Sdefine APP NAME Mouse Form Demonstration Program ttdefine WDW CTRLS NAME CLOSER INFO include aesshell c t Data for our own custom mouse pointer t int pointerL 37j s 8 1 x and y of hot spot 9 1 background and foreground pens 16 words of color mask data OxFO00 OxFBOO Ox70CO0 x3FE x 1FF Ox1lFF8G Ox1FF8 OxSFFC 9x7FFE x3FFF Ox1FFF OxOFFF 0x07FF OxO1FE OxOOFC 0x90078B 16 words of image data 0xCOOO0 0 7000 Ox10890 O0x1D40 0x0E20 0x0410 0x0528 0x1148 9x2084 0x1102 OxO0n01 0x0401 0x0302 Ox0084 0x0040 O
287. of which follows the mouse pointer so long as the user holds down the left mouse button When the left mouse button is released the function ends and the box is erased This func tion should only be called when the program has determined that the left mouse button is already down by returns from form do evnt multi or evnt button since if it is up the function will end as soon as it s called C binding int status x y minw minh endw endh status graf rubberbox x y minw minh amp endw amp endh Inputs See also control 0 control 3 control 4 e27 4 control 2 3 0 0 int in 0 int in 1 int in 2 int in 3 int out 0 int out 1 int out 2 0 Opcode Number of 16 bit inputs in int in array Number of 16 bit results in int out array Number of 32 bit inputs in addr in array Number of 32 bit results in addr out array The horizontal screen coordinate of the left edge of the box The vertical screen coordinate of the top edge of the box The box s minimum width in pixels The box s minimum height in pixels Error status code 0 an error occurred during execution gt 0 no error occurred during execution The width of the box at the time the user released the left mouse button The height of the box at the time the user released the left mouse button form do evnt multi evnt button cd md t4 x el iu 1 23 LLE
288. og by making the slider a TOUCHEXIT object C binding int status parent object orientation OBJECT tree position graf_slidebox tree parent object orientation Inputs control 0 76 Opcode control 1 3 Number of 16 bit inputs in int_in array control2 1 Number of 16 bit results in int_out array control 3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array parent int_in 0 The number array index of the parent box object slide bar object int_in 1 The number array index of the child box object slider orientation int_in 2 A code indicating the orientation of the slide bar rectangle 0 horizontal slider moves left right 1 vertical slider moves up down tree addr in 0 The address of the object tree array which contains the objects Results position int_out 0 A code indicating the position of the slider object relative to the parent slide bar This code is a number in the range 0 1000 where depending on orientation 0 left or top 1000 right or bottom 275 graf handle Get the Physical Screen Handle graf handle This function returns the VDI handle number for the current physical screen workstation along with some information about the default system font The physical screen workstation is needed in order to open a virtual screen workstation with the v_opnvwk call C binding Opcode 77 int phys handle cellw
289. ommand WF TOP aes 42290 d5 WM REDRAW asgS refresh Window refresh subroutine 22 refresh turn mouse off move 4 78 ctr190 command 2 graf mouse move 1 ctr1l1 g 1 input integers move d4 1 ctr12 1 output integer move 4256 aintin amp hide the mouse jer aes lock screen 213 CHAPTER 8 move 4 107 ctr10 command wind update move 1 ctrii 1 input integers move 1 ctri2 1 output integer move i aintin code BES_UPDATE Jer aes Find first window rectangle move i 1d04 ctrlO command wind get move 2 ctrii 2 input integers move 5 ctri2 5 ouput integers move msg aintin window handle move 811 aintin 2 WF FIRSTXYWH command Jer aes retcesh1 amp sheck for empty rectangie move aintout sd dtl or aintout d d beq ret resh3 4 1f empty at end so quit move msg 8 du move aintout 2 d1 cmp d dl MAX xl x2 bcs olap1 move di d9 overlap x is in d olapl move msgt id di move aintout 4 d2 cmp di d2 bes olap2 move d2 d1 overlap y is in di Olap2 move msgt8 d2 add msgti2 d2 move aintout 2 d3 add aintout 6 ds cap d2 d3 bhi olap3 move d3 d2 d2 MIN ix1 w1 x2tw2 ol ap3 sub d d2 move d2 aintout t overlap w d2 overlap x move msgt ig d2 d2 yi add msg 14 d2 hi move aintout 4 d3 d y2 add aintout t8 d3 h2 cmp d2 d3 bhi olap4 move d d2 d2 MIN C yl h
290. on of 0 indicates that the slider is at the top of the bar while a position of 1000 indicates that it s at the bottom If its orientation is horizontal a position of 0 indicates that the slider is at the left of the bar while a position of 1000 indi cates that it s at the right Although graf_slidebox draws the dotted outline of a moving box while the user drags the mouse it does not actu ally move the slider object after the user lets go Therefore your program must move the slider by calculating a new object ob_y or object ob_x position and by using objc_draw to redraw both the parent slide bar object and the slider that s contained in it The calculation is very similar to that used for window sliders For a vertical slider the formula would look like this tree SLIDER ob_y long slider_pos long tree SLIDEBAR Ob height tree SLIDER ob height 1000 The casts to type long are used to avoid overflow in the multiplication and division Program 7 1 demonstrates how to use the graf_slidebox function in conjunction with a TOUCHEXIT slider object to implement a slide bar in a dialog 181 CHAPTER 7 box It also demonstrates how to implement user defined ob ject types In this dialog box there are three user defined se lection buttons that are drawn as circles when not selected and as filled circles when selected Program 7 1 dialog2 c 5kt kt 5552525555252552552525525522252522522252525 29 525525 2
291. on will give back any memory that isn t used for program code data or the stack It does this either in a machine lan guage SETBLOCK call or in a C module that is linked in before the program object module For example Alcyon C us ers must always link the file GEMSTART O or APPSTART O before the program module In Megamax C the file INIT O which is part of the SYSLIB library is linked in automatically A desk accessory however isn t assigned any free mem ory when it s loaded at boot time Therefore a different startup module must be used so the desk accessory doesn t try to give back extra memory that isn t there In the case of Alcyon C you must link the module ACCSTART O first in place of GEMSTART O or APPSTART O With Megamax C 201 CHAPTER 8 you have to link in the ACC L library file after your program object file This will automatically override the INIT O module in the SYSLIB library Since desk accessory programs are started from the DESK menu they need a way to enter text strings into the menu They do this using the menu register call The syntax for this call is extern int gl apid int menuid static char menutext menuid menu register gl apid menutext where gl apid is the application ID number which is assigned to the desk accessory and stored in its global array when it calls appl_init Menutext is a pointer to the null terminated character array that holds the text of the menu item Normal
292. ontain the demo subroutine or the window def inition constants it won t link and run properly In order to get it to function you must create another object module that contains that subroutine n example of this is Program 2 4 dummy s Program 2 4 dummy s 44535 54325595323555x525 22 21222232252235525955252235552 27 252522222252222592255 1 1 DUmmY S Just waits for user to click close box t x SVPTERSATTELATASLTTAAAAKATALTALALKSKAAKAARARAAAKAKAKAAAAKA AAA External References 4 Export xdef demo xdef wdwetrl xdef wdwtiti xdef wdwinfo Import xref aes xrot ctrie xref ctrli xref ctr12 xref ctrisS xref ctri4 Xref addrin etext demo jer demol jsr demol demols move 23 ctris move 9 ctrii move 1 ctri2 move 1 ctris move 49 ctr14 move 1 finsgbuf addrin jmp aes 49 CHAPTER 2 amp Storage space and data constants data even megbuf ds w 8 wdwtitl dc b Test Window 49 wdwinfo dc b Info Line wdwetrl de w 55 end Assemble this file in the same way to create the dummy o file Next use the linker to join the two object modules The command line to use is link68 u dummy 68k aesshell dummy This creates the dummy 68k file a program module that must be modified to run under GEMDOS using the relmod program relmod dummy This produces the dummy prg program file that can be ex ecuted from the desktop You may have noticed that the source
293. or in any branch of the tree It also allows the specification of a clipping rectangle and will only draw those objects which fall within the rectangle C binding int status firstob depth clipx clipy clipw cliph struct object tree status objc_drawi tree firstob depth clipx clipy clipw cliph Inputs control 0 42 Opcode contro 6 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr out array firstob int_in 0 The object number of the first object in the tree to be drawn All descendants of this object will be drawn as well depth int in 1 The number of levels of descent from the original object to draw The object itself is zero levels down its immediate children are one level down their children are two levels down and so on clipx int in 2 The horizontal coordinate for the left side of the clipping rectangle clipy int_in 3 The vertical coordinate for the top edge of the clipping rectangle clipw int_in 4 The width of the clipping rectangle in screen pixels cliph int_in 5 The height of the clipping rectangle in screen pixels tree addr_in 0 The address of the object tree array which contains the objects Results status int_out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution
294. or the button to be released or 1 if you want to wait for it to be pressed The mouse button event will only occur when the condi tions specified in bstate for the buttons specified in bmask happen at the same time This means that you can wait for the left button or the right button to go up or down or you can wait for both You cannot however wait for either the left or right button to change state This makes its impossible for a program to watch for more than one mouse button condition using the standard event driven input scheme In order to use both buttons you will have to return to the polling type of in put discussed at the beginning of this chapter A polling tech nique will be discussed under the section on the evnt multi call below The actual mouse button state at the end of the double click interval is returned in the button variable As with the bstate variable the value is 1 if the left button is down 2 if the right button is down or 3 if both are down By checking the mouse button status the program can determine whether the user merely clicked the button or is holding it down In addi tion to the mouse button status the Shift key status is also re ported The kstate variable contains a code that tells whether the right Shift key the left Shift key Control key or Alt key was pressed at the same time as the mouse button Each of the four low bits represents a different key Bit Bit Value Key 0 1 Right Shift
295. orcing the user to use Save As And if the user hasn t entered any infor mation since starting the project you might want to prevent the use of either Save or Save As To disable a menu you use the menu ienable function whose syntax is as follows int status item setting OBJECT tree status menu ienable tree item setting where tree is a pointer to the menu tree item is the object number of the menu item to change and setting is a flag which indicates whether you wish to enable or disable that menu item setting of 0 indicates that you want the menu item disabled while a setting of 1 directs the AES to reenable that item What the menu ienable call actually does is change the DISABLED flag If you prefer you may also change this by using objc_change or by writing a new value directly to the ob state member of the object structure When the DISABLED bit is set the AES draws the affected menu item faintly and won t allow the user to select that item The menu ienable call normally works for menu items only and doesn t work for menu titles There is however an undocumented feature in the current version of GEM which allows you to disable an entire title If you call menu zienable with the top bit of object number set to 1 the menu title will be drawn faintly and the AES won t drop down its menu box when the user moves the mouse pointer over it Since this is an undocumented feature which may not wor
296. orm alert Display an Alert Box form alert Opcode 52 Displays an alert box and returns the user s response to the alert C binding int exitbutn default char string exitbutn form_alert default string Inputs control 0 52 Opcode control 1 1 Number of 16 bit inputs in int_in array control 2 1 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr iin array control 4 0 Number of 32 bit results in addr out array default int_in 0 The default exit button which will be se lected if the user presses the Return key 0 no default exit button 1 first exit button 2 second exit button 3 third exit button string addr_in 0 The address of the null terminated string containing the alert text The format for this string is Icon_number Message text Exit button text This string is separated into three parts each set off by square brackets The first item icon number is a single numeric digit indicating which image if any should be displayed at the left side of the alert box The choices are Icon Number Image Meaning 0 None 1 Exclamation point in diamond Note 2 Question mark in yield sign triangle Wait 3 Octagonal stop sign Stop The second set of square brackets holds the text message This message is limited to a maximum of five lines each of which may contain a maxi mum of 40 characters The vertical bar character l is used to indicate the start of a n
297. orm First you should deselect the exit button You can do this either by using the objc_change rou tine or by directly resetting the SELECTED bit of the objects ob state field If you fail to do this the next time the dialog is displayed it will come up with the object used to exit the dia log highlighted in inverse video You must also note new selection settings for all the sig nificant objects in the dialog That includes any text that may have been entered into editable text objects You should prob ably transfer all the new settings to a separate array which keeps track of current settings That way your program won t have to keep checking the object fields to find the settings Also this practice will allow you to undo changes the user makes if he or she exits the dialog with the Cancel button in stead of OK Program 6 1 demonstrates some of the common features of dialog box handling Program 6 1 dialog1 c 5 5 5 5 55 532392353 5525255229 325X X535295529925 5259592 9222322252223222 95222 24225 7 t t fT v LF DIALOG1 C Demonstrates handling of simple dialog box with buttons boxes and editable text amp 1 g k 55292525529925 525523255225252552359222522595325 5552592 29224525352592222 5422521 Hdefine APP INFO define APP NAME Dialog Example 1 define WDW_CTRLS NAME 164 La mt ul tae td A dd dd Lo i Lo RB E i ft UL L Interactive Object Handling
298. osition of these rectan gles you can check to see if the current size equals the maxi mum size If it doesn t you may set the window to maximum size using wind_set If it s already at that size you may use wind set to change to the previous size The subcommand to use is WF_CURRXYWH wind set wi handle WF CURRXYWH newx newy neww newh Since you use wind_set to change the window size in response to the WM FULLED message just as you do for the WML_SIZED message the same rules about redraw messages apply If you increase the window size your program will get a redraw message If you decrease its size it won t get a re draw message Therefore if you want to redraw after making 66 gt d 339 J ed VILI LI a AES Events the window smaller either call the redraw routine directly or send yourself a redraw message after changing the size with wind set Not only may GEM windows be sized but they may be moved as well When the user places the mouse pointer on the drag bar holds down the left button and moves the mouse the Screen Manager draws a dotted window outline that moves with the mouse This outline shows the new win dow position When the user lets go of the mouse button the Screen Manager sends the program message 28 WM MOVED Any program that has a window with the mover attribute in its control word should be ready to handle the WM MOVED message The signi
299. ost Office Box 5406 Greensboro NC 27403 919 275 9809 is a Capital Cities ABC Inc company and is not associated with any man ufacturer of personal computers Atari ST ST BASIC 520ST 1040ST and TOS are trademarks or registered trademarks of Atari Corporation GEM is a trademark of Dig ital Research Inc d J J i d 7 3 3j LL i i p a LL LU Contents POIGWOIG 1239 merde rbd quen ta Vase bed inda V Chapters I GEM and the AES 1 SENERE ARE nas 1 2 Starting an Application Windows Part 1 19 3 AES Events Windows Part 2 esse eeeees 51 4 GEM Graphics Objects 0 00 ccs eee eee es 95 5 Resource Files and Menus sees 129 6 Interactive Object Handling Forms and the File siis Ape MN DM Oar O o 153 7 The Graphics Library cece eee ceeeeees 177 8 Desk Accessories 199 Appendices A AES Function Reference lluuuuuu 221 B Extended Keyboard Codes 309 C Resource Files for Sample Programs 317 Function Index soles ba wee hae dd aan do ORC 324 Index io na Vac RA Pip b tes awed esa ii gu 326 L 4 it t L t L Foreword This is the second book in a series of three on the Atari ST The first concerned the VDI the Virtual Device Interface COMPUTEN s Technical Reference Guide Atari ST Volume Two The GEM AES takes you further into the underpinnings
300. ouse pointer until the user re leases the left mouse button The grafdragbox function allows the user to drag a box within a boundary rectangle such as a window or dialog box As with graf_rubberbox this function should not be started until the program has determined that the user has pressed the left mouse button down When the function is called it draws the box outline and redraws the box whenever the mouse pointer moves within the boundary rectangle until the left mouse button is released When the function ends it erases the box outline and returns the ending position of the box The syntax for the graf_dragbox call is int status width height beginx beginy int boundx boundy boundw boundh endx endy status graf dragbox width height beginx beginy boundx boundy boundw boundh amp endx amp endy where width and height specify the size of the box The vari ables beginx and beginy contain the starting position of the box while the variables boundx boundy boundw and boundh describe the position and size of the boundary rectangle When the user releases the mouse button the function returns the ending mouse position in the variables endx and endy The next box function graf_slidebox is also used to move a box within a container This function however is ob ject oriented The function moves a box object called a slider that is located within a parent box object known as the bar As with some o
301. outine is called Dgetpath Given a pointer to a 64 byte buffer and a drive number 0 current drive 1 A this routine places a 173 CHAPTER 6 string which specifies the directory path in the buffer In the example program above these two routines are used to build the default pathname Another bit of manipulation is needed after fsel_input returns the pathname and filename chosen Since the path specifier will usually contain a wildcard for the filename you have to eliminate each character from the end of the path string until you come to the backslash character You can then tack on the filename to the end of the pathname Although the File Selector does provide a uniform method for obtaining a filename from the user it has some limitations Chief among these is the fact that the filename window will only hold 100 entries This means that if there are more than 100 files in a directory the user won t be able to view the last ones Also the file selector doesn t give the user any feedback on which drives are currently available For these reasons some programmers prefer to use their own file selection dia logs If you are planning to do so however it would probably be a good idea to keep the form and function of this dialog as close to the standard one as possible The fsel_input routine is one that can be profitably used from a BASIC program Program 6 3 demonstrates how to use this call from BASIC Note that in this
302. ox smallx smally smallw smallh largex largey largew largeh status graf_shrinkbox largex largey largew largeh smallx smally smallw smallh where smallx smally smallw and smallh specify the size and position of the smaller rectangle and largex largey largew and largeh give the size and position of the larger rectangle The status variable contains a 0 if an error occurred during the call otherwise it contains a nonzero integer Mouse Form One of the most commonly used AES Graphics Library call is the one that changes the shape of the mouse pointer In GEM the shape of the mouse pointer can be used to indicate what kind of action will take place when the user moves the mouse For example a pointing hand is often used for selection or for sizing a rectangle while a flat hand can indicate that dragging will take place When a program starts up from the GEM Desktop the mouse pointer takes the form of the busy bee which indicates that the program is busy working and the user will have to wait until it s finished to begin input Normally the program will change this pointer to the general purpose arrow shape as soon as the program is ready for input To do this it uses the call graf_mouse This routine allows the program to set the mouse pointer shape to one of eight predefined forms or to a user defined 16 X 16 pixel bit mapped image It also can be used to temporarily eliminate the mouse pointer display and
303. p rts 338 Storage space for program stack AES and VDI call parameters fvpb dl vdi code d 42 amp and miscellaneous program variables b838 even accstks ds l ds 1 256 amp program stack i 99 2 VDI Data Arrays 83833 338883 contr1 contr 6 contrli contr12 contrl3 contr14 contr13 contri s contr17 contr18 contr19 contr112 contr111 d amp w ds w ds w ds w ds w ds w ds w ds w ds w ds w d6 w ds w fue et Gub pub Gub Pu jet fee pee Bet fee due 217 CHAPTER 8 intin ds w 128 intout ds w 128 ptsin ds w 128 ptsout ds w 128 1 92 24 14 4 4 AES Data Arrays 5 292t 22225222 25 ctrl ctr19 ds w i etrli ds w i ctri2 ds w i ctrl3 dg w 1 ctrl4s dS 1 giobal version ds w i count ds w 1 apid ds w 1 private d5 1 1 tree dS 1 1 regvli dS5 1 1 reouv2 ds l 1 resvss ds l 1 resv4 Gs i 1 aintout ds w 8 aintin ds w 18 addrin ds 1 3 addrout ds 1 2 28828 Misc vwkhnd pwkhnd wdwhnd chboxw chboxh cellw cellh deskx desky deskw daskh workx worky wor kw wor kh msg menuid ds w ds w dS W dg W ds w 05 Ww dS w dS W dS wW dS W d5 w ds ds w dS W variables 33333332 ds w 1 ds w 1 ds w b be p P gt pe o j gt pa je fee D S55 55 35t55 Init data seven menutxts wdwtitl wdwetris buffer for mess
304. pe of text objects found within menus The dialog tree can contain any object but all objects are positioned so that their borders are aligned with even text character positions The free or panel tree can contain any object at any pixel position The various resource programs also allow you to edit alert strings as well as free text strings and free images those not contained within an object tree When you drag a tree icon to the resource window you create the root object for that tree usually a G_BOX with an outlined border To add children to the tree you drag icons representing the various object types to a position in which they re completely enclosed by the root object You may create children for these objects also by drag ging additional icons into their rectangles Once you ve added these objects to the tree edit them as you see fit You can drag them to a new position with the mouse change their size by dragging their lower right hand corner or edit their attribute and flags Simply double click on the object to open a dialog box From that dialog box you can set or reset each flag indi vidually In RCS version 2 you highlight the icon by clicking on it and then select the appropriate flags from pop up menus located on a control panel This allows you to experiment with the size placement and attributes of the objects interactively immediately viewing any changes you make 133 CHAPTER 5 When you re finished
305. pointer to user defined shape 191 CHAPTER 7 r gt g_x points looks like the mouse sort of r gt g_y po ntst113 r gt g_w a points 4J pointst93 1 regen pointsL33 points i1 1 graf_mouse form pointer gt amp end of set ptr s EREEKETEKAEEREEAKESEK End of Mousform c t 592 t2 t95t tt Program 7 3 is a machine language version of the same program Program 7 3 mousform s 195 92141 12 15199959559 2292 92925 2222292 220922 2291205 2929240060 51 22 229222 253 x t MOUSFORM S Shows how to change pointer shape x amp g 9 99592 52292252292222 952 592 292 5 555 X222592524t2592 t 424292522 422 22225 External references t Export xdef demo external demo subroutine xdef wdwctrl xdef wdwtitl xdef wdwinfo 3 Import xref vdi xref aes xref vwkhnd virtual workstation handle xref contri all af the VDI data arrays xref contr11 xref contr12 xretf contr13 xref contr14 xref contr1S xref contrld xref intin xret ptsin xref Ctrl g all of the AES data arrays xref ctr11 xraf ctr12 xref ctri3 xref ctr14 xref aintin xref aintout xref addrin xref deskx xref desky xref deskw xrot deskh xref wor kx xref wor ky xref wor kw xref wor kh 192 i lI 2 E d ik x a d RER ECL EL UL UC rtt The Graphics Library etext demo move move move move move sub
306. pointer will assume Valid code numbers include Form Number Shape Macro Name Usage 0 Arrow ARROW General purposes 1 Vertical bar I beam TEXT CRSR Text cursor placement 2 Bee HOURGLASS Busy signal 3 Pointing hand POINT HAND Sizing 4 Flat hand FLAT_HAND Dragging 5 Thin crosshairs THIN CROSS Drawing 6 Thick crosshairs THICK_CROSS Application specific 7 Outline crosshairs OUTLN_CROSS Application specific 255 User defined USER__DEF Application specific 256 Mouse pointer off M_OFF Hide mouse before drawing 257 Mouse pointer on M_ON Restore 277 graf mouse formptr Element Number 0 1 2 3 4 5 20 21 36 Results status 278 addr_in 0 The address of a 37 word array that con tains the data for the custom pointer shape If one of the predefined shapes is requested this value may be set to OL If a custom pointer is desired the data array must first be set up and its beginning ad dress placed here The format for this ar ray is Description of Contents X position of hot spot Y position of hot spot Number of bit planes must be set to 1 Background color normally 0 Foreground color normally 1 16 words of color mask data 16 words of image data int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution d JS jJ 2 JS J J 3 j L LEELEE CO CEL graf mkstate Get Mouse and Shift Key Status graf mkstate Opcode 79
307. program usually allows for more than one kind of input from the user Second evnt_multi allows you to use the timer in conjunction with other events This makes it pos sible to set a time limit on waiting so that if the user doesn t respond within some reasonable time your program can re cover and help him out rather than wait forever There is a penalty for using evnt_multi from C how ever Because of the large number of input parameters it takes time to push them all on the stack for the library function and then it takes the library function time to pull them from the stack place them in the proper data arrays make the call and move the values that were returned from the data arrays back to the output variables Since the library routine in the bindings has to be pre pared for the unlikely case that you ll want all of the events checked at the same time you must always supply some value for all of the input parameters whether you use them or not and the bindings must move all of those values whether they re used or not As a result evnt_multi can be sluggish 93 CHAPTER 3 particularly when you re closely tracking mouse movement for instance When your application requires faster performance it may be beneficial to skip the library routines and write your own machine language interface that moves the necessary values to the int in and addr_in data arrays before giving the TRAP command that calls the AES
308. programs Instead assem ble the shell program separately and link the resulting object file with the demo program object files Since the shell program refers to the demo subroutine in 39 CHAPTER 2 the demo program file and the demo programs refer to the VDI data arrays defined in the shell program use the xdef and xref directives to help resolve these external references The xref directive tells the assembler that the symbol is de fined in another object file while xdef tells it that this symbol will be used by another object file All of the machine language examples in this book have been created to be assembled with the Megamax C compiler If you have the Alcyon compiler use this short batch file to as semble the machine language programs with Alcyon as68 1 u l1 s link68 u 961 68k 901 relmod 1 rm 1 68k rm 961 0 wait 961 Type in this file with your editor and save it to disk with the filename AES BAT Next call the batch environment by double clicking on the Alcyon system file BATCH TTP For parameters type AES filename where filename is the name of the source file you want to assemble Program 2 3 is the assembler shell program aesshell s Program 2 3 aesshell s 55555 55X3252525522522525222222255222 252 52525559552 4255222452252525 x AESSHELL S Shell program to be linked with all k assembly language example programs Li x KETITTAESKSAAKTSAASATAATATSATAHTKAAAKTKKATTAT
309. pty rectangle amp if empty at end so quit amp x MAX xl x2 overlap x is in d overlap y is in di d2 MIN xitwi x2 w2 overlap w d2 overlap x d2 yl hl d3 y2 h2 d2 MIN y1 hl y2 h2 overlap h d2 overlap y are width and height both if so skip redraw and get next rect opcode for set clip two points in ptsin vs clip turri Clipping on JJ Jo J zd oe dJ move add subq move move add subq move jsr L L E d ptsin aintout d9 1 d dO ptsin 4 di ptsin 2 aintout 8 dl 61 d1 di ptsin vdi redraw the display jsr display turn clipping off move move move nove move move jer 129 contriG 2 contri1i 486 contr12 1 contrisS 0 contri4 H intin vdi amp get next window rectangle refresh2 move move move move move jsr bra unlock screen refreshs move move move move jer x turn mouse move move move move jmp move move move move move LL L display amp Find window work area size on 4104 ctr10 command 2 ctrli S ctr12 msgt aintin window x AES Events pointe overlap x points 2 overlap x w i pointsti1J overlap y amp pointsL5 overlap yth 1 opcode for set clip vs clip two points in ptsin turn clipping off wind get integers integers handle 2 input 3 ouput
310. r break default break J return done refresh wh drect routine to handle window refresh WM REDRAW 4 7 int whj amp window handle from msgt323 GRECT drect pointer to damage rectangle GRECT wrect the current window rectangle in rect list 2 graf mouse M OFF 9L turn off mouse wind update BEG UPDATE lock screen amp wind get amp get first rectangle wh WF FIRSTXYWH amp wrect g x amp wrect g y amp wrect g w amp wrect g h while wrect g w amp amp wrect g h while not at last rectangle if overlap drect amp wrect check to see if this one s damaged set clip amp wrect if it is set clip rectangle display 3 redraw and turn clip off vs Clip handle FALSE int amp wrect gt wind get wh WF NEXTXYWH amp wrect g x amp wrect g_y amp wrect g_w amp wrect g_h 3 wind update END UPDATE unlock screen X graf mause M ON x L turn mouse pointer back on amp 3 display draw the window display int x 3 print each visible line of text starting with ttop for x 9 x lt SROUS x vigtext handle work g x cellh x work g y texttttop x23 Ww d L L LALL AES Events move slide move the slider to match ttop t int cslide nslide long temp wind get wi handle WF VSLIDE amp cslide
311. r graphics output within the visible portion of your window is strictly your program s responsibility The AES helps you in this task however by keeping what s known as a rectangle list When a window is partially obscured GEM di vides the visible portion of the window into the least possible number of nonoverlapping rectangles For example if two windows on the screen overlap at a corner the visible portion of the top window will consist of one rectangle while the visi ble portion of the bottom window will be divided into two rectangles If the top window overlaps a side of the bottom window the visible portion of the bottom window will be di vided into three rectangles If the top window is entirely con tained within the bottom one the visible part of the bottom window will be divided into four parts As you increase the number of windows the combinations increase as well See Figure 3 1 To find the list of visible rectangles for a particular window you use the wind get command As you may re member from the previous chapter this command contains two subcommands which are of interest here One is WF FIRSTXYWH and the other is WF NEXTXYWH WF FIRSTXYWH returns the position and size of the first rectangle WF_NEXTXYWH returns the position and size of the next rectangle in the list Each subsequent call to wind get with the WF NEXTXYWH subcommand returns the position 58 Eq wy g s Em L L L Ls Ll
312. r menu tree defined in the H file created by the resource construction program When you ve got the address of the menu tree you re ready to tell the AES to install your menu You do this using the menu bar call whose syntax is as follows int status showflag OBJECT tree status menu bar tree showflag where tree is a pointer to an object tree in the example above you would use amp menuaddr for that pointer Showflag indicates whether you want to draw the menu bar or erase it When you wish to install the menu bar set showflag to 1 At the end of your program before calling appl_exit you should erase the menu bar by calling menu bar once again only this time with showflag set to 0 Once you ve called menu bar the AES draws your menu bar at the top of the screen and begins to handle user interaction with the menus When the user moves the mouse pointer to the ACTIVE the AES drops down the proper menu When the user selects a menu item the AES sends your pro gram message number 10 MN SELECTED The format for this message is Word Number Contents 0 10 MN SELECTED a menu item was selected by the user 3 The object number of the menu title that was selected 4 The object number of the menu item that was selected When your program receives this message via an eunt multi or eunt message call you ll generally check word 4 of the message buffer to see what item was selected and 143 CHAPTER 5 ta
313. ray edit_obj int in 0 Number of the text object currently being edited next obj int in 1 Flag for change in edited object number keyin int_in 2 Keycode received from evnt _multi tree addr_in 0 The address of the object tree array which makes up the dialog box Results int_out 0 continue int_out 1 obj_out int out 2 keyout continue int out 0 Flag for exit object selection 0 exit object selected 1 exit object not selected continue obj out int out 1 Number of new edit object keyout int out 2 Processed keycode A 0 indicates that this function has handled it and no further processing is required for this key See also form do form butn 266 ee BR Ed sd 4 J Ld d Lo L ho Re A LO LLLE form butn Handle form do Mouse Events form butn Opcode 56 This function is called by form do when its evnt_multi call detects a mouse button press First objc_find is used to locate the object Then form butn is called This routine highlights the object if it s SELECTABLE and not DISABLED and performs the deselect function for radio buttons It sets an exit flag for EXIT or TOUCHEXIT objects If the object was EDIT ABLE it returns the initial object number and if not it zeros it out so that form do won t change the object Since this is such a limited subset of form do functions it s of interest mainly to programmers writing their own form do
314. rc_load filename where filename is a pointer to a null terminated string that 135 CHAPTER 5 contains the name of the resource file This name is usually the same as that of the application only with an extender of RSC instead of PRG For example RCS RSC is the resource file for the Resource Construction Set program filename RCS PRC If you don t specify a directory path GEMDOS will look for the the resource file in the same directory as the applica tion which is the usual state of affairs If the rsrc_load rou tine is unable to find the resource file or is unable to load it properly for any other reason a value of 0 is returned in the status variable Your program will want to check this variable after attempting a resource load since you ll want to notify the user with an alert box and terminate the program at once if the resource file didn t load properly When the AES loads a resource file it finds the size of the file allocates enough free memory to hold it and then reads the contents of the file into the allocated space Next the AES changes the data structures that were loaded into memory It converts the size and position values stored in character units back into pixel units based on the current default character size It replaces the array offset val ues in the OBJECT TEDINFO INCONBLK and BITBLK struc tures with actual address pointers It replaces the array offset values in the Tree Index with actual a
315. ree Your own program can also use these links to perform a specified operation on all of the members of a tree such as changing all of their status flags Although the scheme used to link GEM objects together may seem complex it actually simplifies many tasks which the AES must perform To understand how you must look at the last four fields of the object structure TN Object Size and Position The final four fields of the object structure contain the position and size of the object expressed in the standard format of x posi tion y position width and height In this case however the x and y positions don t represent an absolute pixel coordinate Rather the position is specified as an offset from the x y position of its parent object whose own x y position is an offset from its parent s position Thus each object inherits the origin position of its parent Changing the position of a parent object also changes the positions of all of its descendants The relative positioning of objects within their parent s rectangle is just one aspect of the principle known as the vi sual hierarchy of GEM objects This principle states that the rectangle of each parent object completely contains the rectan gles of all of its children Since each parent rectangle contains all of its child rectangles it stands to reason that when the parent object moves so must the children One of the most important tasks which the AES must per form in order
316. ree you want to search firstob is the index number of the object you wish to begin the search with and depth is number of generations down the tree you wish to search The variables x and y hold the screen coordi nates of the object you re searching for usually the current x and y positions of the mouse pointer If objc_find locates an object at those coordinates it returns the object number of the last object found in the foundob variable If it doesn t find any objects there it returns a value of 1 The objc_offset function is the opposite of objc_find It starts with the object number and returns the absolute screen position of that object This function is necessary because you can t determine the x and y coordinates of an object just by looking in the ob_x and ob y fields of its object structure The positions stored there are relative offsets from the object s par ent so to determine its absolute position you must add all of 121 CHAPTER 4 the offsets of each preceding generation to the x and y position of the root The syntax for the objc_offset call is int status object x y struct object tree status objc_offset tree object amp x amp y where tree is a pointer to the object array object is the index number of the object whose position is desired and x and y are the variables in which that position is returned The objc change function is used to change the ob status field of an object
317. registered their menu entries The next menu title should be FILE The drop down for this title should contain entries like New Open Save Save As and Quit Some of these items may contain a symbol next to the text such as Open O This shows the user that there are keyboard equivalents to this menu item In the example shown the user could hold down the Control key and press the letter O and it would have the same effect as if the Open item had been selected from the menu The next title to use if appropriate is EDIT This contains items such as Cut Copy Paste and Delete From there on the menu title selection is up to you One thing that you should keep in mind when creating menus however is to keep them short If you find that you need more than eight or nine menu items you may want to consider going to a dialog box instead of a menu 142 d i Jo j aa MERET l Jd L LLC C t L Resource Files and Menus Using Menus Once you ve created your menu tree with the resource con struction program of your choice the next step is installing it from your program After you ve loaded the resource file with rsrc_load the next step is to retrieve the address of the menu tree with the rsrc gaddr call long menuaddr rsrc_gaddr R_TREE MENUTREE amp menuaddr R_TREE is a macro name defined in GEMDEFS H and MENUTREE is a macro name for the root object of you
318. ren a member of the original GEM design team has posted an excellent example of a user defined form do routine in the Utilities Data Library DL 3 area of the Atari16 Forum on the CompuServe Information Service The source code can be found in the file named GMCL13 C The File Selector The final type of interactive form which the AES provides is the File Selector The Library routine fsel_input displays a complete prefabricated dialog box The purpose of this dialog is to provide a standard method for showing the user the con tents of a disk and allowing the selection of one of the files on that disk The dialog box displayed by fsel input is shown in Figure 6 1 The current search path drive name and subdirectories if any is shown on the line beneath the title Directory The di rectories and files found there are displayed in the window which is located in the lower left corner of the dialog box A solid block with a white diamond shape in it appears before the names of directories to distinguish them from files There is a scroll bar at the side of the window which may be used 170 al el SM v NNNM d t 3 tl t r Interactive Object Handling Figure 6 1 Dialog Box Displayed from the Program dialog1 c COMPUTER SURVEY Rge Under 16 Conputers Dwned m atari ST Atari XL XE Exidy Sorcerer Bl Other cr to view additional names if there are more than can fi
319. ring This is the drive specification directory and filename of the application that invoked the current program If the current program was loaded from the DESKTOP program only a carriage return character will be returned in this buffer tail addr in 1 The address of the buffer that will hold the command tail text string This is the text that followed the name of this pro gram in the command string used to start the program Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also shel_write 304 b m i j E HERRE A Xl dod C E L hus Ree Wee Rae des shel write Run Another Application shel_write Opcode 121 This function is used to select an application other than the GEM DESKTOP program to load and run after the program terminates n other words you may use this command to chain programs so that when one terminates the other begins directly without first returning to the DESKTOP Typically this function is used in conjunction with OUTPUT PRG the program which sends graphics output to the printer Since OUTPUT PRG relies on the GDOS which has not been officially released as of this writing it s difficult to say how this function will be used on the ST version of GEM Moreover this function does not work reliably in the current preblitter version of the op
320. rk inLOlJaGetrez 0 2 set screen device ID according to amp resolution mode for x21 x 198 wark inUx 121 set other input values to default v Oopnvwk work in amp handle work out open virtual screen workstation if handle return VWK_ERR j if we can t open it return error code CHAPTER 2 Find out the maximum size for a window and open one wind_get DESK WF WORKXYWH amp desk g x amp desk g_y amp desk g w amp desk g h find dimensions of Desktop Window wi handle wind create WDW CTRLS desk g x desk g y desk g w desk g h 13 Create a window that size amp if wi handle 9 return WDW ERR IX if we can t return error code wind set wi handle WF INFO APP_INFO 9 wind Set wi handle WF NAME APP NAME 20 90 set name and info string for window amp wind open wi handle desk g x desk g y desk g w desk g_h IX open the window to full size Clear the work area of the window wind get wi handle WF W RKXYWH amp work g_x S amp work g y amp work g Ww amp work g h j find out the size of its work area t graf mouse M OFF L turn the mouse pointer off X clear rect amp work clear the area graf mouse ARROW L change the pointer to an arrow graf nouse M ON 2L IX and turn it back on return Report no errors amp Close and delete window close workstation
321. rm alert default string where default is the number of the default exit button Since there may be up to three exit buttons with which the user may close the alert box the default should be a number in the range 1 3 The variable string is a pointer to a specially for matted text string which describes the image if any the mes sage text and the exit buttons The format for this string is Icon_number Message text Exit button text This string is separated into three parts each of which is set off by square brackets The first item icon number is a 157 CHAPTER 6 single numeric digit indicating which image if any should be displayed at the left side of the alert box The choices are Image Number Image Meaning 0 None 1 Exclamation point in diamond Note 2 Question mark in yield sign triangle Wait 3 Octagonal stop sign Stop These images are used to indicate alerts of increasing im portance The NOTE alert may be used to pass information that s only of casual interest to the user while the STOP alert should be reserved for the situation where data may be lost if the user proceeds The second set of square brackets holds the text message This message is limited to a maximum of five lines each of which may contain a maximum of 40 characters The vertical bar character is used to indicate the start of a new line For example the string This is line 1 This is line 2 This is line 3 prints in an alert as
322. rned by GEM and it shows how many applications can run concurrently under this version of GEM Since the current ST does not support full multitasking only one main application can run at a time The third element ap id is where GEM stores the unique application ID number that identifies this application The ID number can be used when passing mes sages to this application from another task such as a desk ac cessory This ID number is the same number that is supposed to be returned by the appl_init call but some versions of the C language bindings don t correctly return the ID number Since appl_init does place the ID number in the global ar ray an application can find it out by reading that array di rectly The C library assigns the name gl apid to the ap_id element so a C application can find out its value by declaring gl_apid as an external int and using the contents of that variable The rest of the global array is made up of 32 bit long words The ap private element is reserved for use by the application any four bytes of data as determined by the pro grammer may be stored here The ap ptree element is where the AES stores a pointer to the header of the object tree loaded with the rsrc_load call The other four elements are reserved for future use The second data array used by the AES is named control and it consists of five elements each two bytes in length The information stored in each of these elements is
323. ror status of the call 0 means there was an error while a value greater than 0 indicates no error Wind_close removes the window s display from the screen by sending a message to the other windows on the screen to update their display If the window wasn t covering any application windows its image is replaced by the Desktop background While wind close removes the window display from the screen the window remains allocated and may be reopened at any time by a call to wind open In order to re move the window completely you must call wind delete as follows int wi handle status status wind delete wi handle Once you ve deleted a window you must use wind_create to reallocate it before you can open it again You should always remember to close and delete all of your windows before your program terminates Closing them will remove their image from the screen and deleting them will return the resources they use to the system A C Program Shell Since most of the subsequent example programs use much of the same program code for initialization and cleanup it would be repetitive to include the text of that code in every example Instead the steps necessary to open a virtual workstation and a window are listed below in the form of a short program named aesshell c All this program does is perform AES and VDI initialization open a window call a function named demo close the window and exit A few things ar
324. round color amp GRECT r m int points 4 3 vsf interior handle 9 grect conv r amp points vr racfl handle points bd 208 zl o x td f ud 3 L LL Pe Et L L Desk Accessories grect cenvir array convert grect to an array of points GRECT r int farray farray r g x3 Sarray a r g yj Sarraytt r 5 g x r gt g w 1 array r g y r gt g_h 1j gt t tt 9 2t1 End of Deskacc c 9 1 t9 222212 225 9 2 This program combines most of the AESSHELL C and MESSAGE C programs into one The standard AESSHELL C file could not be included this time because it opens its win dow right away In this combined file only part of the original initialization routine is performed immediately The virtual window and workstation are opened when the program gets the AC_OPEN message Also the cleanup routine is elimi nated since the program never ends Instead the evnt_mesage routine is part of an endless loop in which events are received and handled Most of the event handling is the same though routines have been added to handle the messages AC OPEN and AC_CLOSE and the WM CLOSED message handler has been changed to close the window and virtual workstation and delete the window Remember that linking this program is different from a normal application With the Megamax linker the program command line reads MMLINK deska
325. rror codes for which form_error prints error specific mes sages messages as opposed to TOS error X and gives the complete text of those messages GEMDOS PC DOS Error Error Number Number Error form_error Message 33 2 File not found This application can t find the folder or file you just tried to access 34 3 Path not found This application can t find the folder or file you just tried to access 35 4 File handle pool ex This application doesn t hausted no file have room to open another handles left document To make room close any document that you don t need t CL tz 263 form error GEMDOS PC DOS Error Number 36 Results exitbutn Error Number Error form error Message 5 Access denied wrong An item with this name al attribute or access ready exists in the directory code or this item is set to Read only status 8 Insufficient memory There isn t enough memory in your computer for the application you just tried to run 10 Invalid environment There isn t enough memory 11 Invalid format 15 Invalid drive in your computer for the application you just tried to run There isn t enough memory in your computer for the application you just tried to run The drive you specified specification does not exist Check the drive s identifier or change the drive identifier in the DISK INFORMATION dialog 16 Attempted to remove You cannot delete
326. rsion number int rsh object object block offset int rsh_tedinfo TEDINFO block offset int rsh_iconblk ICONBLK block offset int rsh bitblk BITBLK block offset int rsh frstr Free String block offset int rsh_string String block offset int rsh imdata image data block offset int rsh_frimg free image data block offset int rsh_trindex tree index block offset int rsh_nobs number of objects int rsh ntree number of trees int rsh_nted number of TEDINFOs int rsh_nib number of ICONBLKs int rsh_nbb number of BITBLKs int rsh_nstring number of strings int rsh_nimages number of images int rsh rssize total size of the resource in bytes 134 LS ELE J NEN td L L LOCO LL L LELEL Resource Files and Menus Following the resource header are the actual data arrays that make up the objects First comes an array of strings fol lowed by an array of BITBLKs an array of image data an ar ray of ICONBLKs an array of TEDINFOs and finally the array of OBJECTS There are important differences between the data arrays stored in the resource file and those stored in the actual object array used by the AES Object Library routines First as noted above the resource file doesn t contain the actual pointers used by the ob spec field or other data struc tures Instead these fields contain an index number which
327. rt slider position total length length seen 1000 83 CHAPTER 3 Again window start counts the top of the document as 0 and you ll probably want to use 32 bit variables in order to avoid exceeding the limits of 16 bit arithmetic Once you have the window start position you ll want to save it That way if the user clicks on one of the arrows you can simply increment or decrement it by 1 and redraw and if the window size changes you can begin the window in the same place Program 3 3 shows how to handle the messages associ ated with maintaining the scroll bar Program 3 3 scroll c SHAERRARSKACKES KARE RAKAA ERA RAR AKER EKER RARER EKER ERASER EKER RATE EEE HK x SCROLL C Demonstrates how to manage scroll bars in a window amp x x UMESEKEKAEE KSA KAK TREE KAKA KEARSE RAE KAKA K TERE ERATE KEE REET tdefine FALSE tHdefine TRUE 1 tidefine APP INFO define APP NAME Scroll Window Example define WDW CTRLS NAME CLOSER VSLIDE UPARRGW DNARROM define MAX X Y OX gt Y X 2 Y define MINOR Y X lt Y X s Y D define TROWS 28 total number of text row define TCOLS 35696 total number of text columns 5 define SROWS 9 number of rows seen at a time Winclude aesshell c int ms9f81 message buffer int ttop the top line of text currently in the window amp char XtextLTROWSJ This is a sample help w
328. s such as color inversion should in dicate the selected state The user can select the object from a dialog by pressing Return key There must only be only one object with this flag per tree and some graphic change such as thickening of the button border should indi cate that this object is the default Selecting this object indicates that the user wishes to exit the dialog Indicates the user is able to edit the object in some way such as chang ing the text string This object is one of a set of radio buttons Radio buttons are sibling objects whose selection is mutually exclusive selecting one automati cally deselects the others The object is the last one in the ob ject tree Indicates that the form do rou tine will return control to the pro gram as soon as the user presses the mouse button with the mouse touching the object without wait ing for the button to be released as with EXIT Makes a subtree invisible Object li brary calls will not draw or find the object or any of its children This flag to show that the value in ob spec is actually a pointer to the real value of ob spec RE ad sed ind s eL wb 4 x LCL f LLL L GEM Graphics Objects The SELECTABLE flag The SELECTABLE flag is an im portant one If this flag is set the user can select the object by moving the mouse pointer over it and clicking the left mouse button When this happens the AES changes the flag whi
329. s breaks draw Pattern 1 draw Pattern 2 IX Quit gt end of switch on menu item amp menu_tnormal menutree msgC 3J 1 set menu to normal break default break 3 end of switch on message type return done report done status gt amp Keyboard Handler routine checks for keyboard equivalents of menu selections handle key key int key 3 int done 93 switch key lt case FIKEY draw 7 2 break case F2KEY draw 5 3 3 breaks case CTRLAQ done 1 break defaults break check key code draw Pattern 1 draw Pattern 2 Quit x gt 7 7 end of switch on key return done Ellipse Drawing Routine draw pattern color int pattern color 3 vsf_style handle pattern 3 vef color handle color MOUSE OFF t Hide the mouse pointer v ellipse handle work g x work g w 2 work g_ytwork g_h 2 MOUSE GN work g w 2 work g h 2 j Show the mouse pointer 599539 9 9592929595222242 End of Menul c 5353 92 292252 259 146 m NE NN 333 NE NNI ft LLL a L LLLE Resource Files and Menus In order to run this program you must first create a re source file called MENU1 RSC If you have a resource con struction program you ll need to create two object trees The first is a menu tree with the C macro name MENUTRE
330. s certain information about GEM and the application which must be available to all of the library routines The array contains nine elements the first three of which consist of two byte words The rest are four byte long words These elements are as follows Address Element Name Contents global global 0 ap_version The GEM AES version number global 2 global 1 ap count The maximum number of concurrent applications sup ported by this GEM version global 4 global 2 ap id A unique ID number for the currently active application used to pass messages to it global 6 global 3 4 ap_private A private storage place to be used by the application global 10 global 5 6 ap_ptree A pointer to the address of the header of the object tree loaded with rsrc load global 14 global 7 8 ap lresv Reserved for future use 0 global 18 global 9 10 ap 2resv Reserved for future use 0 global 22 global 11 12 ap_3resv Reserved for future use 0 global 26 global 13 14 ap_4resv Reserved for future use 0 10 o D poo i s iL IL tL tL pan L GEM and the AES As you can see there are official GEM names for each of these elements The first ap version is an internal GEM AES version number supplied by GEM after an application is ini tialized with the appl_init call The version in use at the time of this writing was 288 The second ap count is also re tu
331. s of rectangles you must supply dummy parameters as place hold ers when you use the other two action types For example a typical FMD START command would take the form form dial FMD START 0 0 0 0 x y width height The next step is completely optional If you wish you may call form dial using the FAD_GROW subcommand This step animates a zoom box which moves and grows from the first rectangle to the second one While this may add a bit of visual appeal to your program it also causes a slight delay which may irritate the more advanced user Generally it s best not to include it unless it gives the user some meaningful information For example if the user double clicks on an icon to open a dialog box then it may be helpful to show the dia log box exploding from that icon to show the relationship between the two If the dialog box was started up from a menu item however it really doesn t add anything to show the box exploding from the menu since the menu item disap pears before you can tell where the zoom box is coming from 162 J d 4d J asi 7 uk a vmi ad ft LCL L L L TT 1L Interactive Object Handling Finally you draw the dialog box using the objc_draw command and animate it using form do The syntax for the form do call is int exitobj editobj OBJECT tree exitobj form do tree editobj where tree is a pointer to the dialog s object tree and editobj is the object
332. s the object number of the parent object to which you wish to link the child and child contains the object number of the child you wish to link in Likewise you can remove an object from a tree altogether by using the objc delete function int status object struct object tree status objc_delete tree object where tree is a pointer to the object tree and object contains the object number of the object to be removed Finally you may change an object s order in relation to its siblings by using the objc_order function int status object newpos struct object tree status objc_order tree object newpos where tree is a pointer to the object tree object is the number of the object to reorder and newpos is a flag which indicates how to reorder this object s siblings A value of 0 specifies that the object is to be moved to the end of the chain of siblings 1 specifies that it be moved to a position second from the end of the chain and so on A value of 1 can be used to indicate that the object should be moved to the position of first sibling in the chain Program 4 1 written in C demonstrates the use of objc_draw and objc_find two of the more commonly used low level object functions It displays an object tree that consists of three objects a root box a text string and a but ton It then waits for a mouse button press and checks to see 124 m ot det xe ud fd LLL
333. screen rather than in the middle The next step is to use the form dial call to reserve the screen area in which the dialog is to be displayed The syntax for this call is int status action smallx smally smallw smallh int largex largey largew largeh status form dial action smallx smally smallw smallh largex largey largew largeh where action is a flag which indicates the type of action you wish to take and the two sets of rectangle information give the smallest and largest dimensions of the dialog box The 161 CHAPTER 6 four valid action type flags and the macro names for them defined in the GEMDEFS H file are as follows Type Number Macro Name Action 0 FMD_START Reserves the screen area used by the dia log box 1 FMD GROW Draws expanding box from small to large rectangle 2 FMD_SHRINK Draws shrinking box from large to small rectangle 3 FMD_FINISH Frees the screen area used by the dialog box and causes redraw messages to be sent The type of action that is appropriate at this stage of the dialog presentation is FMD START which reserves the screen area that will be used by the dialog box If you ve read the of ficial GEM documentation you may have noticed that the syntax for the C binding shown there includes only one set of rectangle parameters The actual binding however uses the format shown above Although only the two middle action types FMD_GROW and FMD_SHRINK use both set
334. sible 1 display a checkmark in front of the item tree addr in 0 The address of the object tree array which supplies the data for the menu display Results status intzout 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also appL exit 244 wk o4 ul E d J Lo Lodo amp LR L L ft L menu ienable Enable or Disable Menu Item menu ienable Opcode 32 Disables the selection of a menu item or enables its selection When the menu item is disabled its text is grayed out that is printed in faint characters C binding int status item setting OBJECT tree status menu ienable tree item setting Inputs control 0 32 Opcode control 1 2 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr out arra item int_in 0 The object number of the item to be dis abled or enabled setting int in 1 A code which indicates whether selection of the menu item is to be disabled or enabled 0 selection of the menu item is disabled 1 selection of the menu item is enabled tree addr_in 0 The address of the object tree array which supplies the data for the menu display Results status int out 0 Error status code 0 an error occurred during execution gt 0
335. slider size and set it slsize 1000 SROWS TROWS wind set wi handle WF VSLSIZE int slsize 9 wind get wi handle WF WORKXYWH amp work g x amp work g y amp work g w amp work g h find work area do main program loop amp c evnt nesag msg get message done handle nsg O j and handle them 2 while done 3 til window is closed 3 handle msg message handler int done FALSE long temp Switch msgL22 check message type t case WM REDRAW 1 if redraw call refresh routine refresh msgL 53 GRECT amp msgEL42 break case WM TOPPED if topped send to top t wind set msgL53 WF TOP 9 break case WM CLOSED if closed set flag done TRUE break case WM VSLID slide bar was dragged temp msgL4J TROWS SROWS 1002 calc ttop ttop temp refresh wi handle amp work redraw window move slide and move slider break 85 CHAPTER 3 J Case WM ARROWED arrow was clicked switch msgL41 case 90 page upt ttop MAX 8 ttop SROUS break case 1 page downs ttop MIN TROWS SROWS ttop SROWS break case 21 row up ttop MAX S ttop 1 break case 3 row down amp ttop MIN TROWS SROWS ttopti s tit break default break 2 retfresh wi handle amp work redraw window move slidet move the slide
336. status int_out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution See also wind get 292 E UL UL L L EC wind find Find Window Under Mouse Pointer wind find Opcode 106 This function determines which window is currently under the mouse pointer either the Desktop window handle 0 or one of the application windows whose handles are assigned by the wind create call C binding int wi handle mousex mousey wi handle wind find mousex mousey Inputs control 106 Opcode control 2 Number of 16 bit inputs in int in array control2 1 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array mousex int in 0 The horizontal screen position of the mouse pointer mousey int in 1 The vertical screen position of the mouse pointer Results wi_handle int_out 0 The ID number of the window located at the specified position See also objc_find 293 wind update Lock or Release Screen for Update wind update Opcode 107 This function is normally used to notify the AES prior to a screen update so the AES won t change the screen display in that area by dropping down a menu for example It can also be used by an application to take complete control of all mouse functions even when the mouse is loca
337. sted width of the window 7 The requested window height If you re willing to let the user size the window arbitrarily you can just forward the window dimensions received in the message to the wind_set command which will resize the window to those dimensions wind set msgbuf 3 WE_CURRXYWH msgbuf 4 msgbuf 5 msgbuf 6 msgbuf 7 GEM itself constrains the sizing of a window to a limited degree It won t allow a window larger than the screen or so small that the scroll bar controls located in the window bor ders are totally obscured You may wish to set your own minimum and maximum size limits or you may want your program to adjust the sizing request before passing it on to wind set For example if you re working with a text based application you may want to limit window sizing to an even multiple of the default charac ter cell size or to even 16 bit boundaries Printing graphics text is much faster when each line of text starts on a 16 bit bound ary Just remember that the rectangle returned by the WML_SIZED message describes the exterior dimensions of the window including the border area If your program is inter ested in controlling the interior or work area of the window use the wind calc function to convert the requested size from exterior to interior size adjust that size and then use wind_calc to convert back before passing the dimensions to the wind_set call A Redraw request is generated for a win
338. t move divu move add move move move move move move sub 1 move divu move add move move move move move move move jer H d4 close window flag in d4 mousof f 6 contr19 cpcode for polyline 5 contrll amp number of points in ptsin 4 9 contr13 no integer parameters in intin vwkhnd contrl1 amp 6 virtual workstation handle d d wor kw de find left side of box 3 d dO thirdw war kx d9 d left d0 ptsin d9 ptsin 12 dO ptsin i 6 thirdw d9 find right side of box d right d ptsint 4 d ptsin 8 d d workh d f find top side of box 85 d d thirdh worky d8 d top d ptsin 2 d8 ptsint dO ptsin 18 thardh d find bottom side of box d bottom d ptsin i1 d ptsin 14 vdi draw box find current mouse position move move move move jsr 4 79 ctr19 opcode graf mkstate 8 ctrii no intins 5 ctr12 amp 5 intout 8 ctris addrin aes Kk set pointer shape accordingly isr isr setptr mouson z main program loop nove move 1 move 425 ctrli opcode evnt multi 16 ctrl1 87 ctr12 1 intout 1 ctr135 1 addrin 10 ctr14 20 aintin waiting for message or rect msg addrin message buffer address 1 aintin s mouse rectangle 1 flag 1 193 CHAPTER 7 jsr aes move 420 ctrl13 move aintout d5 cmpi 4 05 did we get a mouse rectangle eve
339. t contains a 1 is colored with the foreground pen and each bit position that contains a 0 is colored either with the back ground pen or whatever color is displayed by the existing background depending on the color mask The color mask is used to define the shape of the pointer without regard to color information Those bit positions con taining a 1 are considered to be inside the pointer They will be colored with the foreground pen if the corresponding bit positions in the image data also contain a 1 They will be col ored with the background pen if the corresponding bit posi tions in the image data contain a 0 Those bit positions which contain a 0 are considered to be outside the pointer image and therefore are transparent Whatever background image exists on the screen will continue to be displayed at these points It is important to use both foreground and background pens in your pointer in order to insure that it remains visible against any kind of background Even though the normal sys tem pointers such as the arrow appear to be black only there is actually a thin white line surrounding them This makes it possible for the user to see the arrow even when it s in front of a solid black background Program 7 2 written in C shows how to use evnt mouse or the mouse rectangle function of evnt_multi to track the mouse pointer and change its shape as it moves into different regions of the screen It draws a box in the center
340. t highest sub directory This kind of ambiguity can confuse the user so use caution when defining the close box to mean anything other than getting rid of the window If you plan to allow the user to reopen the window then you don t have to delete it immediately But you should re member to delete it before you close the application Program 3 1 a C program shows how to handle window messages that request you to redraw size full close or top a window Program 3 1 message c X amp X t titt 9 3X 545 355X 554t55t55 92X4 42 2525352243552525523 5535 5525x452925255525252252222955255 MESSAGE C Demonstrates the various window messages t 1 your program might receive and how to handle them S XX9 53X9 955 523555553255255522552525525x225552555555253222352 235522235 define FALSE define TRUE 1 define APP INFO define APP NAME First Window define WDW CTRLS NAME CLOSER I SI ZER MOVER FULLER 8define MAXOX Y OX gt C X CY defime MIN X Y X lt Y X s Y CHAPTER 3 include aesshell c int wh2 msgL83 second window handle message buffer demot c int closed 9 wh22wind create WDW CTRLS desk g x desk g y desk g w desk g h j Create another window wind set wh2 WF NAME Second Window 3 2 t set name for window wind _open wh2 desk g_x desk g_w 4 desk g_y desk g_h 4 desk g w 2 desk g_h 2 open the w
341. t in the box If the user wishes to view a different drive or directory he or she may change the display by clicking on the Directory blank and typing in a new file specification such as A N or C N PROGRAMS After typing in the new path the user clicks anywhere within the filename window and the AES updates its contents according to the new specification If the user wishes to see the contents of any subdirectory whose name is in the window he or she only has to click on the directory name and the Directory specification will automatically be changed to show the contents of that subdirectory A file may be selected in several ways The user may type in the name of the file in the space marked Selection and then click on the OK button or press Return A second way to se lect the file would be to click on the name of the file in the window which will cause that filename to appear in the Se lection blank and then click on the OK button or press Re turn Another way would be to double click on the name of the file which will both select it and choose OK To display the File Selector dialog you use the fsel_input call whose syntax is as follows int status exitbutn char path 64 file 13 status fsel input path file amp exitbutn 171 CHAPTER 6 where path is a pointer to a string which contains the initial pathname and file is a pointer to a string which contains the default filename The path string contains the driv
342. t out array control3 1 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array gl_apid int_in 0 The application ID number This value should be returned by appL init but currently the bindings only place it in the global variable gl apid menutext addr_in 0 The starting address of the null terminated text string used for the menu item Results menuid int out 0 The desk accessory s menu ID number Valid ID numbers in the range 0 5 n ID number of 1 means that there is no room on the menu for this item 248 of E ad d J LUO L L tL UL L Lo 8 objc add Add an Object to a Tree objc_add Opcode 40 Adds an object to an object tree by linking it in with the parent object and other sibling objects if any This function is not normally used by the appli cations programmer if a resource construction program is used to create the object trees binding int status parent child struct object tree status objc_add tree parent child nputs control 0 40 Opcode control 1 2 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control 3 1 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array parent intLin 0 The object number of the parent to which a child object will be added child int_in 1 The object number
343. t the physical workstation handle but don t open the Virtual Screen Workstation for VDI calls amp phys handle graf handle amp cellw amp cellh amp chspcw amp chspch get physical screen device handle amp work int190322 use Raster Coordinates work intOJcGetrez 4234 set screen device ID according to t resolution mode for x21 x lt i work_in x 1 1 set other input values to default menuid menu register ap id Sample Accessory t register our menu wi handle NONE return t Report no errors gt amp amp Message Handler Routine 231 handle msg amp message handler long x3 switch msgl check message type case AC OPEN if msgf4J 2menuid if cur menu item was picked if wi handle NONE if there s no window init out O0 create one X else bring it to the front else wind set wi handle WF TOP 2 D 9 break case AC CLOSE 18 if a window was open change handle to NONE to show that the AES has taken it away from us iti msg 3Joemaenuid amp amp wi handle ic NGNE C v_clavwk handle wi handle NONE gt case WM REDRAW 18 if redraw call refresh routine refresh asgCt53 GRECT amp msgl4 break case WM_TOPPED if topped send to top wind set msgL3J WF TOP 90 break 205 2 CHAPTER 8 case WM SIZED
344. t them to allow Library routines like form do which handles all dialog activity to supervise editing by the user The editing information you supply consists of a template which determines the text format a validation string that shows which characters may be entered in which positions and an initial or default value for the string Editing and display information is stored in a data struc ture called a TEDINFO The ob_spec field of text type objects contains a pointer to the object s TEDINFO The C language definition of this data structure is as follows typedef struct text_edinfo char te_ptext pointer to the actual text string char te ptmplt pointer to format template char te_pvalid pointer to validation string int te font font size 3 normal 5 small int te resvd1 reserved word int te just horizontal justification left right int te color color information word int te resvd2 reserved word int te thickness border thickness int te txtlen length of text string ant te tmplen length of template string TEDINFO The first three fields are four byte pointers to text strings The first te ptext is a pointer to the actual text string This string may be composed of either text characters or blank spaces Note that the commercial at sign is treated as a special case If it appears as the first character in the string the ent
345. ta for menu2 rsc 4 include with RSCBUILD C x 3999259299359392592259595222222222225229 2 2222 2222 252 define FILENAME MENU2 RSC define FILELEN 1958L int rscdata 534J 9x0091 2x02090 x BID 2x220 9x6F7S x 2D2D 9x2D2D 9x736F x416535 9x4465 9x29020 9x6F72 2x65635 9x6575 Gx 2692 9x 6865 x2D2D 9x0020 9x6D29 9x7373 90x7429 x4D65 Bx B28 9x90428 9x942C Qx204F 9x7429 9x2D2D 9x2D99 9x7279 9x635653 Ox7S6B 9x0929 9x7929 9 637535 9x6B29 9x2020 Qx656B 9x 2D2D 9x2054 9x4F4E 9x6167 9x4974 9x6E75 9x9209 9x90017 0x29044 9x7074 9x4D63 9x 2D2D 2x202 9x29051 9x7373 Ox 2941 Ox 2944 9x 3429 9x7356F 9x41635 9x8175 9x204D x2D2D x 7572 Bx 2989 9x6309 x6S6D Ox 2064 9x9209 9x09091 9x6575 Bx SIF Ox 6E75 x2D2D 8x 4465 9x 2028 9x6F72 Ox6363 Ox 6373 Bx 2980 9x7279 9x 6365 9x6974 9x6172 9x 2D2D Gx 6E29 Ox 2928 x 2929 Ox 204F Ox 656D Ox B298 Ox DWI 9x6B29 BxSE7S Ox 322E 9x 2D2D 9x7356B 9x0029 9x79240 9x6575 x 6B28 9x2929 9x2935 2x7373 x 2828 x ABI Qx2D2D 9x4E65 9x5972 9x5475 Gx 4646 9x6F29 Qx91F4 Bx x 2Z Bx 2 Qx2E2E 9x2D2D 9x2041 9x2944 9x 3229 Ox7S6F 9x4163 8x 4465 Ox 2829 9x6F72 xSES1 9x 2D2D x2D2D 947874 9x696E 9x726E x SB 9x7769 Qx
346. ted outside of the active application window in the menu bar for example C binding int status code status wind update code Inputs control 0 107 Opcode control 1 1 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array code int_in 0 A code which specifies the function this call will perform Valid code numbers are Code Macro Name Function 0 J BEG UPDATE Notifies AES that the application is beginning a window display update 1 END UPDATE Notifies AES that the application is ending its win dow display update 2 BEG MCTRL Notifies AES that the application is taking control of all mouse functions even when it moves out of the active window 3 END MCTRL Notifies AES that it should once more take control of the mouse when it leaves the active window area Results status int out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution 294 3590 9 J Lae 4 ll UL L ft L L L1 Ae Ae lo wind calc Calculate Window Area wind_calc Opcode 108 Given the size and position of either the window s border rectangle or work rectangle and its window control components this function calculates the size and position of the opposite rectangle C b
347. terminate all of the window resources should be released by using the wind delete call C binding int wi handle controls fullx fully fullw fullh wi_handle wind create controls fullx fully fullw fullh Inputs control 0 100 Opcode control 1 5 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr_out array controls int_in 0 A code which specifies the window con trol components which will be present in this window Each window control is rep resented by a bit in this word If the bit which corresponds to a given control is set to 1 that control is present The bit as signments are Bit Bit Value Macro Name Window Control 0 1 0x001 NAME Title bar 1 2 0x002 CLOSER Close box 2 4 0x004 FULLER Full box 3 8 0x008 MOVER Move bar 4 16 0x010 INFO Information line 5 32 0x020 SIZER Size box 6 64 0x040 UPARROW Up arrow for vertical scroll bar 7 128 0x080 DNARROW Down arrow for vertical scroll bar 8 256 0x100 VSLIDE Slider for vertical scroll bar 9 512 0x200 LFARROW Left arrow for horizontal scroll bar 10 1024 0x400 RTARROW Right arrow for horizontal scroll bar 11 2048 0x800 HSLIDE Slider for horizontal scroll bar fullx int_in 1 The screen position of the left edge of the maximum size window fully int in 2 The screen position of the top edge of the
348. tern int gl apid t The application ID part of the global array int ap id int contriC1i2 VDI data arrays intinL 1281 ptsinL 1281 intout 1281 ptsout L 1281 int phys handle workstation handle for physical screen device handle workstation handle for virtual screen device wi handle X window handle amp int work inL 121 input and output arrays for v opnvwk amp work out t 371 GRECT desk work Desktop and application window dimensions amp v r int cellw cellh chspcw chspch size of default character font t Program starts here amp main c int error Error flag error s init all Initialize application open workstation 18 and open application window if error demo If no initialization failures run demo amp cleanup error Close window workstation and application Initialize application open graphics workstation and open window init a11 0 int x3 int pointsL 41 Initialize the GEM application If this fails return error code appl i nit ap id gl apidj if ap_id 1 return APP ERR Initialize input array get the physical workstation handle and open the Virtual Screen Workstation for VDI calls amp handle phys handle graf handle amp cellw amp cellh amp chspcw amp chspch get physical screen device handle work int191 2 1 use Raster Coordinates wo
349. that if you make this call using the subcommand WF_CURRXYWH instead of WE_WORKXYWH you get the entire screen size including the menu bar Opening a Window Just creating a window doesn t cause that window to be dis played on screen For that you must open the window using wind_open If however you specified in the wind_create function that the window controls attached to this window should include either a title bar or information line there s one additional step that you must take before opening the window You must tell the window where to find the text for the information line or window title The call to use for this purpose is wind set The syntax for this call is int status wi handle field x y width height status wind set wi handle field x y width height Just as the wind get call retrieves several different bits of information about the window wind_set allows you to change various aspects of the window s appearance Select the aspect you wish to change with the field parameter This pa rameter may have any of the following values Field Number Name Aspect to Change 1 WF KIND x Window controls flag same as controls for wind create 2 WF NAME x y Address of string containing the name of the window 3 WF_INFO x y Address of string for the win dow s information line 5 WF_CURRXYWH Window exterior coordinates CHAPTER 2 Field Number Name Aspect to Change 8 WF_HSLIDE x
350. the AES calls user draw and passes it a 113 CHAPTER 4 pointer to a PARMBLK structure The C language definition of this structure is typedef struct parm_blk OBJECT pb_tree Pointer to the object tree containing this object int pb objc This object s index in the tree int pb prevstate The object s previous old state field int pb currstate The objects current new state field int pb x The position and size of the object pb y pb_w pb h int pb xc The position and size of the clip rectangle pb yc pb wc pb hc long pb_parm The contents of the ub parm field in the APPLBLK PARMBLK This structure gives the drawing function much of the infor mation needed to draw the object The pb tree field contains a pointer to the object tree that contains this object and the pb_objc contains the object number of that object within the tree The pb_prevstate and pb currstate fields contain the previous and cur rent values for the object s state flag the possible state values will be discussed below If the previous and current states are the same the application is drawing the object If they are different the application is changing the object s state The next eight words contain rectangle information for the object and for the current clipping rectangle The object s x and y positions given here represent the actual pixel position of the ob
351. the function concludes it returns the new index number in this variable Finally the type variable 122 d vd j jJ J sb wd l LE bl d e ks tL tL L L GEM Graphics Objects contains a flag that indicates the type of editing function to be performed The editing functions available are shown below Type Number Macro Name Description of Function 0 ED START Reserved for future use 1 ED_INIT Combine the template string of TEDINFO field te_ptmplt with the text string of the te_ptext field to display the formatted string and then turn the cursor on 2 ED_ CHAR Check the input character against the valida tion string in TEDINFO field te_pvalid up date the te_ptext field if the input character is valid and display the changed text 3 ED_END Turn off the text cursor You may notice that the C calling sequence for objc_edit above differs from the Digital Research documentation In that version there are separate parameters for the text string index you input and the index returned by the program The extra index pointer is added to the end of the parameter list As of this writ ing however the Alcyon C bindings from Atari and those derived from those bindings such as the Megamax compiler use the same index pointer for input and output If you have problems making this function work correctly from C you should examine either the source or a disassembly of your bindings to determine the
352. the user can exit form_do by pressing the Return key Finally if an object has the TOUCHEXIT flag set form do will exit as soon as the user moves the mouse pointer to the object and presses the button down This allows the programmer to create draggable object types by seizing control when the user starts to drag the object When form do exits it returns the object number of the object whose selection terminated the form do call There is a set procedure to follow when using form do to animate a dialog First load the resource file with the rsrc_load call Next find the address of the dialog tree with the rsrc_gaddr call Then use the form center command to center the dialog box on screen The syntax for this call is int x y width height OBJECT tree reserved form center tree amp x amp y amp width amp height where free is a pointer to the dialog object tree and x y width and height are the variables in which the routine returns the position and size of the centered dialog box This routine computes the top left coordinates at which the dialog box will be centered on screen and writes those coordinates into the ob_x and ob_y fields of the root object This step is necessary because the root objects created by the resource construction programs are all positioned at 0 0 If you don t center these objects before displaying them dialog boxes will always be drawn in the top left corner of the
353. to maintain the system of GEM objects is find ing which object rectangles if any overlap a given x y location on the screen The hierarchy of GEM objects greatly 101 CHAPTER 4 simplifies this task by breaking the screen down into a num ber of significant rectangles The largest of these is the rectan gle of the root object If the location doesn t lie within the root rectangle it can t coincide with any object in that tree If it s within the root the AES then checks it against the rectangles of the first level of siblings If it lies within one of those rect angles the AES keeps moving down the tree until it finds the smallest object whose rectangle contains the point in question But if the point doesn t lie within the rectangle of a par ticular parent object the AES can forego checking any of its children since none of the children can contain a point that isn t located within the parent You should note that while the object tree hierarchy insures that a child will be selected over its parent it doesn t prevent two siblings from overlapping If they do and the user clicks in the overlap area the AES will find the last or rightmost sibling according to the tree dia gram That s why you can use an L_BOX sibling to cover other siblings so that all will appear to be selected at once as you ll see later in the section on box type objects The tree structure also helps the AES in drawing object trees The visual hierarc
354. to provide GEM with a limited form of multitasking Multitasking allows processing time to be divided between the primary applica tion the desk accessory programs and the AES Screen Man ager discussed below so that they all appear to be running at the same time Of course the ST s 68000 microprocessor can t execute instructions for more than one task at a time but because it operates at a high rate of speed it s possible to switch between tasks quickly enough to give the user the im pression that they re running simultaneously The scheduling system for tasks is fairly simple The ker nel maintains two lists of tasks the Ready list and the Not Ready list In order to understand the difference between the two you must first know something about GEM events In single tasking microcomputer systems a program finds out about an I O event such as the user pressing a key on the keyboard by continuously checking the status of the I O de vice until a specified event occurs The processor is on hold waiting until it receives input Multitasking systems use a more efficient process They suspend a task that s waiting for some I O event by placing it on the Not Ready list Then the other tasks take turns running until the event occurs GEM provides a number of system calls for just this pur pose These calls are part of the Event Library and they allow CHAPTER 1 an application to wait for a keypress mouse button press mouse mov
355. trings 6 R_IMAGEDATA Pointer to free image data 7 R_OBSPEC Ob spec field of OBJECT 8 R_TEPTEXT Te_ptext field of TEDINFO 9 R_TEPTMPLT Te ptmplt field of TEDINFO 10 R_TEPVALID Te_pvalid field of TEDINFO 11 R_IBPMASK Ib_pmask field of ICONBLK 12 R_IBPDATA Ib_pdata field of ICONBLK 13 R_IBPTEXT Ib_ptext field of ICONBLK 14 R_BIPDATA Bi_pdata field of BITBLK 15 R_FRSTR Ad_frstr the address of a pointer to a free string 16 R_FRIMG Ad_frimg the address of a pointer to a free image In practice you ll be using rsrc_gaddr most often for data structure type R_TREE the object tree Once you have the address of the object tree you can use the object index numbers to access the individual objects Another type that you may use is R STRING which can be used to get a pointer to an alert string Alert strings are stored as free strings by the resource construction programs The other data structure types are there primarily for the AES which uses them when it fixes pointers in those data struc tures at resource load time When you re using rsrc gaddi remember that the input value amp address is a pointer to a long value which itself may be a pointer So if you substitute a pointer for the long value address you still must use a pointer to that pointer for the input value as shown below OBJECT tree rsrc_gaddr R_TREE MENUTREE amp tree 137 CHAPTER 5 Two Resource Library functions remain to be discussed Thoug
356. trol 4 0 Number of 32 bit results in addr_out array path addr_in 0 The address of the buffer that holds the text string which specifies the path for the directory that s initially displayed in the dialog This path name should use wildcards in the filename position for in stance A UTILITIES or C NGAMES PRG The call returns the user s final pathname selection in this same buffer file addr_in 1 The address of the buffer that holds the text string which specifies the initial file selection that s displayed in the dialog box The call returns the user s final file name selection in this same buffer 282 J il J JJ d t d d 14 L L L tL ft LL fsel_input Results status int_out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution exitbutn int_out 1 A code which specifies the exit button which the user selected in order to end the dialog 0 Cancel 1 OK 283 wind create Allocate a Window wind create Opcode 100 This function allocates the necessary resources for a window of a given max imum size having certain specified attributes It returns a window handle that is used to identify the window This function does not actually display the window on the screen however The wind_open function is used for that purpose Before the appl_exit call is made to indicate that the applica tion is about to
357. trol 4 and places the command opcode 78 in control 0 The function graf mouse then loads registers d0 and d1 with the proper values and executes a TRAP 2 instruction In short it takes over all of the repetitive steps associated with making GEM calls allowing the programmer to concentrate on the es sential aspects of the function Making GEM calls from C is easy It s because of this and because C programs are relatively small and quick compared to other high level languages C has become the language of tout ed LL w T L L L LE GEM and the AES choice for software development on the ST Most of the exam ples in this book are written in C On occasion however ma chine language and BASIC examples will be included as well to show how the C examples could be translated The C func tion names will be used as they appear in the official Digital Research GEM bindings since they have been adopted by the manufacturers of most other C compilers as well Refer to the user s manual of your particular C compiler for specific infor mation concerning the C function names The C programs in this book are designed to work specifi cally with the Alcyon C compiler the one officially supported by Atari and with Megamax C which also provides a very complete development environment For these compilers the integer data type int refers to a 16 bit word of data Other compilers such as La
358. ttice C use a 32 bit integer as the default data type When compiling the programs in this book with such compilers you should substitute the word short for each reference to int For the sake of simplicity we have not used the portability macros such as WORD which use the C pre processor to define a 16 bit data type that will be valid for any compiler but you are free to do so Chapter 2 Starting an Application Windows Part 1 LL L EL E The first step in starting a GEM application is to initialize it with a call to the AES Application Library routine appl init This call registers the application with the AES which then initializes several items in the global data array One of these is an application ID number which the AES as signs to the application This ID number is used by other tasks the GEM Screen Manager for instance when they wish to communicate with the application through its message buffer The C format for the call is int ap id ap id appl_init where ap id is supposed to be the application ID number Note however that as of this writing the bindings for all C compilers which derive from source code supplied by Atari such as Alcyon and Megamax C do not correctly return the application ID number Instead these bindings always return a value of 1 in the variable ap_id The actual ID number is however correctly stored in the third element of the global ar ray
359. u create up to eight appli cation windows This number includes the windows that are opened by desk accessories If you want your program to work with desk accessories leave some of the available windows for them The GEM Desktop program limits itself to four win dows so that the other four can be used by desk accessories If a negative handle is returned by wind_create you may wish to display an alert telling the user to close a window and try again if possible As stated above most windows are created with a maxi mum size that matches that of the Desktop window s work area One way of finding out the dimensions of that rectangle is to use the wind get function This function can be used to return any of several items of information concerning a win dow Its syntax is int status wi handle flag x y width height status wind get wi handle flag amp x amp y amp width amp height where wi_handle is the window handle returned by wind create which identifies the window The next input parameter flag determines what kind of information is re turned about the window The following table shows the valid values for flag and the information returned by the call when each flag is used Flag Macro Name Information Requested 4 WF_WORKXYWH_ Window work area coordinates 5 WF CURRXYWH Window exterior coordinates 6 WF PREVXYWH Previous window exterior coordinates 7 WFL FULLXYWH Maximum window exterior coordinates
360. ubcommand set info line tudwinfo aintint4 g point to info text amp Open the window 191 ctrig amp command wind open 5 ctrii 41 ctr12 1 ouput integers deskx aintin 2 initial x desky aintin 4 amp initial y deskw aintint initial width deskh aintin 8G initial height CHAPTER 2 g Find window work area size move 184 ctri command wind get move 482 ctr11i 2 input integers move 5 ctri2 5 ouput integers move 4 aintin 2 WF WORKXYUWH command jsr aes move aintout 2 workx store work x y w h move aintout 4 worky move aintout workw move a ntout 8 workh set fill color to white move 25 contrl opcode for set fill color vsf color move 2 contrl2 move 1 contrls move 1 contrl4 move 6 intin select white jer vdi gt turn mouse off move 78 ctrid command graf_mouse move i ctril 1 input integers move i ctri2 i output integer move 256 aintin hide the mouse jsr aes X fall work area of window with white move 114 contr1 9 opcode for fill rectangle vr recfl1 move 8i2 contrli1 move 0 contris move 90 contr14 move wOr kx d move dO ptsin add wor kw d subq 1 d move d ptsin 4 move wor ky d mave d ptsin 2 add wor kh d subq 1 dd move dd ptsin s jer vdi change mouse to arrow move 49 aintin set mouse to arrow shape jer aes turn mouse back on move 4237 aintin show the mouse
361. ument is the responsibility of your program but GEM helps out by providing a standard frame work within which scrolling may be implemented The standard GEM scroll bar consists of three elements a movable bar called a slider a long rectangular box the slider moves within and arrow characters at either end of the rec tangular box These elements can be added to the window by specifying the elements LFARROW HSLIDE RTARROW and or the elements UPARROW VSLIDE DNARROW as part of the window controls flag used by wind create When a window contains all three elements for instance the LFARROW HSLIDE and the RTARROW the user can take three types of action First the user can drag the slider by positioning the mouse pointer over it holding the left button down and moving the mouse Second the user can click on either arrow indicating that the contents of the window are to be moved a character at a time Or third the user can click on the scroll bar between the slider and the arrow indicating that 78 Jot J J RE J 1 Ll mM LC t L L 0L L EL AES Events the contents of the window are to be moved a page at a time All of these events generate window messages These mes sages will be discussed in detail below In order to maintain slider bars in a GEM application you must perform three tasks Slider size First you must keep track of the slider size The portion of the scroll bar that s filled by the sl
362. valuable to your program would be to align the left edge of the window on a 16 bit word boundary By rounding the co ordinates for the left edge of the window to an even multiple of 16 you make it easier for GEM to move the window con tents quickly since it eliminates a considerable amount of bit shifting and masking operations Aligning an image to an even 8 byte or 16 byte boundary is known as snapping Usually when you use the CURRXYWH subcommand of wind set to move the window the AES will perform a raster copy operation that will move the window s contents automat ically The only time you ll get a refresh message for the moved window is if the window is partially offscreen so that the AES doesn t have access to the complete contents of the window If you prevent the user from moving the window partially offscreen a move operation will never generate a re draw message for the window that you ve moved When the AES wants your application to move one of its windows to the top of the screen and become the active win dow it sends message 21 WM TOPPED This happens when the user selects a window to be active by clicking within its area or when the current active window is closed by its appli cation or desk accessory The format for the WM TOPPED message is Word Number Contents 0 21 WM_TOPPED the message ID number 3 The handle of the window the user clicked in When you get this message you should move the window to th
363. ve through the window a page at a time by clicking on the part of the bar located between the slider and the arrows Note that in most cases the AES itself does not respond to the user s request For example the AES does not close the window when the user clicks on the close box nor size it when the user drags the size box Instead it sends a message to the program notifying it of the user s actions The AES message system will be discussed in Chapter 3 The rest of the window the area inside the borders is the application s work space Windows appear to divide the screen into separate areas but these divisions are only logical constructs not physical fact GEM provides the framework for windowing but it s up to the AES and the application pro gram to actually manage the windows and their contents The AES is responsible for drawing and maintaining the window borders and the controls placed within them The application is responsible for everything that goes on inside the work 25 CHAPTER 2 space The program must keep track of the size and position of the active topmost window and make certain that it re stricts its output to the confines of the work area Otherwise the window s borders would be no more substantial than lines drawn on the screen Window Creation The first step in displaying a window is to define its maximum size and composition with the Window Library call wind_create This function causes the AE
364. ved evnt timer timelo timehi Inputs timelo timehi Results reserved See also evnt multi 238 control 0 2 control 1 2 control 2 1 control 3 0 control 4 0 int in 0 int in 1 int out 0 Opcode 24 4 Opcode Number of 16 bit inputs in int in array Number of 16 bit results in int out array Number of 32 bit inputs in addr_in array Number of 32 bit results in addr out arra Low word of the 32 bit timer value High word of the 32 bit timer value Together the low and high timer words form a 32 bit timer value which specifies the period of time the function should wait in milliseconds Reserved for future use always returns a 1 ach aad x aed ub ou ud and aed CL ee ee L L LE LL evnt multi Wait for Multiple Event evnt multi Opcode 25 This function allows the application to wait for multiple event types at the same time The application can specify that it wishes to wait for keyboard events mouse button events up to two mouse rectangle events message events and or timer events The function returns as soon as any one of the specified events occurs When the call ends the mouse x and y position mouse button state and shift key state are returned regardless of the type of events requested C binding int happened events clicks bmask bstate int m1flag mlrectx mlrecty mlrectw m1recth int m2flag m2rectx m2recty m2rectw m2recth int
365. very least it should mask off the top bit of the object number returned by form do if it doesn t care about double clicks Of course you can always use the double click condition to enhance the function of the object like allowing the user to double click on a filename to open the file immediately 118 d ddd 1 2 wd ll iL LL EL bt t L L GEM Graphics Objects The HIDETREE flag The HIDETREE flag is used to make part of an object tree invisible Whenever the objc_draw or objc_find routines are called the AES will not draw or find this object or any of its descendants The INDIRECT flag Finally the INDIRECT flag is used to change the meaning of the ob spec field When INDIRECT is set ob spec is interpreted as a pointer to the actual ob_spec data This allows you make the actual ob spec part of a larger block of user defined data with the new ob_spec a pointer to that data block Object States The final field in the object structure is called ob states The state of an object determines what the application does with it as well as the way it s drawn by the library routine objc_draw This field like the flags field is made up of bit flags The vari ous flags and their macro names from the OBDEFS H header file are listed below Bit Bit Macro Number Value Name Description 0 1 SELECTED The object is highlighted usually by inverting the foreground and background colors 1 2 CROSSED For a box t
366. ween 1 and the value stored in the variable clicks evnt_keybd evnt button evnt_mouse evnt_mesag evnt_timer 241 evnt dclick Set Double Click Speed evnt dclick Opcode 26 Reads the current setting of the double click interval the amount of time which a mouse button event will wait for multiple clicks or changes that setting C binding int speed set speed flag speed set evnt_dclick speed flag Inputs control 26 Opcode contro 2 Number of 16 bit inputs in int in array control 2 1 Number of 16 bit results in int out array control3 0 Number of 32 bit inputs in addr_in array control 4 0 Number of 32 bit results in addr_out array speed int in 0 The new double click speed A number in the range 0 4 where 0 is the slowest speed and 4 the fastest speed flag int in 1 A code which specifies whether you wish to read the current setting or to change it 0 set a new speed 1 read the current speed Results speed set int out 0 The existing or new double click setting See also evnt_mouse evnt multi 242 E RE d Jt tI J Ll i L E Lo Go L X menu bar Display or Erase Menu Bar menu bar Opcode 30 This function is used to display an application s menu bar or to erase that menu bar The menu erase function should always be used before changing menu bars and before the appl_exit call made prior to exitin
367. with one object tree you can add more trees until you create all the objects used in your pro gram When you re satisfied with the results you may save the resource file In addition if you ve created names for the various objects the program will save those in a separate file for future editing sessions and it will also save a header file containing macro definitions which match the names to the corresponding object numbers The Resource Construction Set also allows you to save a file containing C language defini tions for all of the objects and their associated data structures Structure of Resource Files Many of the fields included in object structures contain the ab solute memory addresses of other data structures But it s im possible to know in advance the absolute memory address at which the resource file will be loaded because that depends on the program size and which desk accessory programs and fonts are loaded Therefore in addition to the object structure data and associated data structures the resource file must also contain information that allows the AES to patch in the abso lute addresses where necessary This information is contained in the resource header a data structure located at the very be ginning of each resource file This structure consists of an ar ray of words containing the size of the other data structures and their offsets within the resource file Its C language defini tion is int rsh_vrsn ve
368. x GBG4 90000 xFFFF Di BGs s 00900 O gt FFFF 2 0097 exeoFF g FFFF Qxe006 1xSoFF x 0024 Ox Bx 3000 9x696F 9x 494F 90x0029 x 1186 0x2014 9x09012 9041191 0x0014 9x0001 9x0024 9 900195 x L Ox 3J SxAgic 0 0001 9x0049 Qx021C OxI 0x11901 Qxnp514 2x02035 9 11601 DIALTREE SL IDEBAR SLIDER EXITBUTN NUMBER OPTIONI1 OPTION2 OPTIONS 1 2 3 4 9 1 1 e 9 farm dialog BOX in tree DIALTREE BOX in tree DIALTREE BUTTON in tree DIALTREE amp TEXT in tree DIALTREE BOX in tree DIALTREE BOX in tree DIALTREE x BOX in tree DIALTREE t Gx JOSA Ox BOBO Ox GOGO Ox 6ESA x 4E32 9x BGI Bx Ox 92GB Ox GSS ex902020 0x90040 Ox BOA 0x09012 x Ox OBOE Bx GOOD Gx GO 9x 9608 Bx GSA 0 90900 9xe02A Ox BOGS Ox Ovai 2940000 Qxaoo3 JJ J J 3 J J J J J fr ECL L C L L L Resource Files for Sample Programs Program C 4 menul dat 95 3595 335529593 22232 959599 4 222132222 22222 2 22 2 222 MENU1 DAT amp t Data for menui rse x include with RSCBUILD C amp amp 9 332 1323 29 3 5593 99552395229229222922922294 224924222252525 define FILENAME MENU1 RSC define FILELEN 1926L 9x900901 Ox91A6 x OODD 9x2090 9x204D 9x 2D2D 90x0020 9x7929 9x637535 9x6B
369. x0030 3j int pointsri123 array of points for box amp demot int event done 98 int dummy msgt81 int mx myj GRECT rj mouse rectangle to watch set points for center rectangle points 8 points 61 points 8 work g_x work g w 3 pointsL1J pointsl3 points 9 work g y work g_h 3 points 2 points 4 work g x work gw 2 3 3 points 5J points 73J work g_y work g h 12 3 draw box find mouse position and set pointer shape accordingly graf nouse M FF 9L j v pline handle 5 points graf nkstate amp mx amp my amp dummy amp dummy 3 set ptr mx my kr graf mousetM ON 9L Main Program Loop t while done until user clicks on close box check messages and mouse rectangle event evnt multi ML MESAGIMLI M1 2 9 0 evnt button 1 r g Xx r g y r g w r g h evnt mousei1 9 0 0 0 9 evnt_mouse2 amp msg IX evnt mesg t 2 9 evnt timer amp mx amp my mouse x y amp dummy mouse button amp dummy shift keys amp 190 Nox oa e ad d J dJ d m LI L L L IL L L The Graphics Library amp dummy 18 evnt keyboard amp dumny 3 number of clicks if event amp MU_MESAG if we get a window close message if msg J WM CLOSED we re done amp done 1 if event
370. x018A 9x991C x 1 x 1128 Ox BSiA SxBOS1i 9490906B Qx9918 9x99921 9x9979 9x991C 9x09901 9x1121 9409014 x29091 9x11901 9x909014 9x2990291 9x9 28F 9x9091C 9x90001 90x99A4 x 1A x 1 x 1 18A Ox BOW Ox SFSF OxSFSF x 6E6E 2 9x 5645 Ox 3339 Qx4356F 9x90041 9x9384C x 6372 9x4463 9x6869 9x6E74 9x 2D2D Qx6B29 Gx 2926 x 2832 9x73575 Sx 2841 9x 2844 9x 35520 9x736F 9x792E Sx BOSS Dx BOO Ox BOWS 9x900902 0x9 O0QC x 9x99097 9x9997 9x0911 0xe206 x A 9x99011 9x2208 9 909002 9x990909 x A 9x9097 9x99001 x C 9x99007 90x209091 Ox990E 9x9099C Ox SSIS 9x990190 x C x S x J 3 3 3 J J L Ehe de d E Tf tC Et SxFFFF 9 x09011 Bx BOO 9x909092 Ox BIO Ox BOOS OxFFFF Ox BISS Ox BOO 9x20996 Ox B31 Ix BIOS 9xFFFF 9x0009 9 x0090 9xFFFF 9x0992 0x909990 9xFFFF 90x0904 x JOID OxFFFF Ox DBS Ox BBS Ox BB1S x BIOS Ox BWSO OxFFFF Ox GOS 3 Resource Files for Sample Programs OxFFFF 9x 9998 Ox SIO x 2 x B S x xFFFF Ox BODb Ox Ox SIRF Gx S Ox BOFF OxFFFF OxBG17 Ix BIOS OxFFFF 9x9017 Ox BOSS OxFFFF 9x09017 9x200090 9xFFFF 9x909017 Ox VOI 9x909011 x D 9xe000 9xFFFF x D xJ21A x 99
371. y Number of 16 bit results in int out array Number of 32 bit inputs in addr_in array Number of 32 bit results in addr out array ID of application whose message pipe is to be read normally the application s own Number of bytes to read from message pipe Address of the buffer used to store the bytes that are read from the message pipe Error status code 0 an error occurred during execution gt 0 no error occurred during execution g e tl ed pi mm b La uw L L LL appl write Write to Message Pipe appl_write Opcode 12 Writes a specified number of bytes to an application s message pipe C binding int status ap Lid length msgbuf status appl_write ap_id length msgbuf Inputs control 0 1 control 1 2 control 2 1 control 3 1 control 4 0 ap id int_in 0 length int in 1 msgbuf addr_in 0 Results status i int out 0 See also appl_read app _init 2 Opcode Number of 16 bit inputs in int_in array Number of 16 bit results in int out array Number of 32 bit inputs in addr in array Number of 32 bit results in addr out arra ID of application whose message pipe was written to normally another application s ID Number of bytes to written to message pipe Address of the buffer where the bytes to write are stored Error status code 0 an error occurred during execution gt 0 no error occurred during execution 225
372. y Therefore in order to link properly with current versions of the library your program must also use the graf_mbox form If in the future Atari decides to change its libraries to conform to its documentation you ll need to change over to graf_movebox as well Inputs control 0 72 Opcode control 1 6 Number of 16 bit inputs in int in array control2 1 Number of 16 bit results in int out array control 3 0 Number of 32 bit inputs in addr in array control 4 0 Number of 32 bit results in addr out arra width int_in 0 The width of the box in pixels height int_in 1 The height of the box in pixels beginx int_in 2 The screen position of the left edge of the first rectangle beginy int_in 3 The screen position of the top edge of the first rectangle endx int_in 4 The screen position of the left edge of the final rectangle endy int_in 5 The screen position of the top edge of the final rectangle Results status int_out 0 Error status code 0 an error occurred during execution gt 0 no error occurred during execution 271 graf growbox Draw an Expanding Box graf growbox Opcode 73 Draws and erases a series of increasingly larger boxes to give the appear ance of a box expanding from a small size to a larger size May be used for example before opening a window with the wind open call to make the window look as if it s exploding open C binding int status smallx smally smallw sm
373. you can t very well get this string from the re source file Dialog Boxes The final type of form the dialog box is much more flexible than simple error boxes or alerts Dialog boxes may contain any number of GEM objects of any type They may be used to present a large number of on off selection buttons along with mutually exclusive radio buttons They may include neatly for matted text strings into which the user may enter information via the keyboard And as you will see with a little work they can even contain more sophisticated constructs such as slide bars The Form Library routine form do is used to animate a dialog once it s been displayed In most cases form do han dles all the user s interaction with the objects in the dialog For example if there are any formatted text objects in the dia log G_FTEXT or G_FBOXTEXT form do positions the text cursor at the first editable field and handles all the key board input from the user If the user enters a valid text char acter one that matches the criteria of the validation string form do inserts it into the text string If the user types an invalid character form ado ignores that character If the user types an invalid character that s part of the template form ado moves the cursor to the first space past that tem plate character For example if the template string is Date __ _ when the user enters a slash the cursor moves to the sp
374. you don t have a resource con struction program you ll need to create the resource file from data arrays as shown in Appendix C There are several interesting points to note about this pro gram First note how the text of the editable string was reset by assigning a pointer to this string named strptr and then setting the first character of the string to ASCII 0 with the statement strptr 0 0 This insures that when the dialog comes up the editable text string will be blank and the cursor will be positioned at the first character of the string Before you clear out the string however copy the last string entered into the lastxt array using the C function strcpy Another important point to note is how the program takes advantage of the object tree structure in tallying the votes from the form Since the objects YUNGBUTN MIDBUTN and OLDBUTN are contiguous in the object array it s possible to check their SELECTED flags by using a loop that runs from object YUNGBUTN to object OLDBUTN The same is true of the G BOX objects STBOX XLBOX EXIDYBOX and OTHERBOX You should create these objects one after the other with the resource construction program in order to in sure that they have consecutive object numbers Although dialog boxes are an easy way to receive input from the user they do have some drawbacks For one thing there are some bugs in the current preblitter implementation For example if the user enters the underscor
375. ype object indicates that an X is drawn in the box 2 4 CHECKED Indicates that a text object such as a menu title is drawn with a checkmark in front of it 3 8 DISABLED Indicates that the object typically a menu title is drawn faintly by masking out every other pixel 4 16 OUTLINED _ An outline is drawn around a box object 5 32 SHADOWED The object usually a box is drawn with a drop shadow The SELECTED flag The SELECTED flag indicates that the user has selected this object usually by moving the mouse pointer over it and clicking the left button during the course of a dialog When the objc_state function is used to change an object s state to selected the AES visually highlights the ob ject usually by inverting the foreground and background col ors in its rectangle Icons are the exception to this rule in that 119 CHAPTER 4 their image and mask colors are inverted not the colors of their entire rectangle The CROSSED and CHECKED flags The CROSSED and CHECKED flags are generally used to manage an alter nate system of highlighting a selected object CROSSED is used with filled box objects to draw an X in the box using the background color By setting the TOUCHEXIT flag the appli cation can easily toggle the CROSSED flag turning the X on or off The CHECKED flag is used with text boxes such as those found in menu items It places a checkmark in front of the text The Menu Library routines include menu_icheck

U - Atari Documentation Archive

Contents

Download Pdf Manuals

Related Search

Related Contents