Reference List Window Library -turn page- Reference List Utility Library

Contents | Start

The Utility Library

5. Utility Library
Reference List Utility Library


This chapter offers you additional EasyGem commands, which are helpful to you when programming your computer but do not concern menus, dialog boxes, or windows.

Get_Mouse R Mouse_X,R Mouse_Y[,R Mouse_But]
Queries mouse position in global coordinates and mouse button status.

This procedure delivers the position for the mouse on the real screen and therefore corresponds to the BASIC functions MOUSEX and MOUSEY. However, the position is always indicated in global coordinates, while the BASIC functions return the mouse position in local coordinates of the currently active Omikron Basic output window. If no Omikron Basic output windows have been set up, then both values are of course identical.
Another option is to determine the mouse button status at the same time. The value returned in Mouse_But has here the same meaning as with the BASIC function MOUSEBUT.
Sometimes it might be necessary to know the mouse position in local coordinates to the currently active window. It is possible to calculate this position yourself, but to facilitate this task and making it easier, EasyGem offers its own procedure. This procedure functions analogous to Get_Mouse; however, it also supplies the mouse position in the currently active windows in local coordinates. Zero point is in this case the inner left, upper corner of the window. Please remember that an eventually existing info line already belongs to the window content.

Get_Mouse_Local R Mouse_X,R Mouse_Y[,R Mouse_But]
Queries mouse position in local coordinates as well as mouse button status.

You probably already noticed that in some other programs the mouse cursor changes its shape depending on the task and application being performed (e.g., cross or wristwatch instead of arrow). This can be achieved through the following EasyGem command:
Set_Cursor Cursor_No
Set shape of mouse cursor.

In Cursor_No, you can pass a number between 0 and 4 or 128 and 255, which corresponds to the following shapes:

0 The default arrow cursor.
1 The so-called I-beam cursor. This shape is usually used for word processing.
2 The cross cursor. It consists of a little cross and usually finds application in graphics programs.
3 The plus cursor. As can be deducted from its name, this cursor symbol looks like a plus sign. One should choose this shape if certain areas are to be selected.
4 The watch cursor has the shape of a wristwatch and signals that an operation requiring a bit more time is being executed.
128-255 These numbers correspond to a cursor shape that is located as a resource of the type "crsr" in the resource fork of your program. The value 128 is by default connected to the Berkhan cursor, which you already know from the Omikron Basic program.
Nevertheless, you can also use a resource editor (e.g., ResEdit by Apple) and modify this cursor or define additional cursor shapes with higher numbers.

Easy_Alert Defaultbutton,Boxstring$[,R Button]  
Display an alert box.

This procedure corresponds to the BASIC command FORM_ALERT. It is feasible that future versions of EasyGem will offer Easy_Alert with improved characteristics (e.g., movable title bar). Therefore, we would already recommend the present use of Easy_Alert instead of FORM_ALERT.

Easy_Fsel R Fsspec$,R Reply$,Title$,R Sel
Display a fileselect box.

The command Easy_Fsel displays a fileselect box on the screen, just as the BASIC command FILESELECT does. Since we expect to expand this command in future EasyGem versions as well, we recommend to substitute FILESELECT with Easy_Fsel already at this point in time.
The meaning of the individual variables is as follows:
Fsspec$ A file name can be passed in Fsspec$ when StandardPutFile (Sel=1) is used. This file name is then entered into the fileselect box as the default name.
The FileSpecificationRecord of the chosen file will be returned in
Fsspec$ after the box has been exited.
Reply$ If StandardGetFile (Sel=0) is used, a file type list may be passed in Reply$ (e.g., "TEXTPICT"). In that case, only the file types indicated in this list are actually displayed.
This variable always contains the FileReplyRecord after
Easy_Fsel has been returned. The FileReplyRecord yields additional information such as e.g., file type about the chosen file. See also: Omikron Basic Manual, the chapter discussing the most important data structures of the MacOS.

Attention: If System 8.5 or higher is installed a modified FileRelpyRecord is returned (as with Easy_Fnav).
Title$ Title$ - in conjunction with StandardPutFile (Sel=1) - may be used to define a title above the file name. When using StandardGetFile (Sel=0), this variable has no significance.
Sel This variable may be used on the one hand to determine if you want to load a file (Sel=0) or save a file (Sel=1), on the other hand, it will yield information about whether the fileselect box was exited with 'Cancel.' In that case, Sel=0 and otherwise Sel=1.

If you have installed System 8.5 or higher, it is better to use the File Navigation Services, because this offers significantly expanded options to select files, folders, volumes, or any type of object. It is even possible to open several files at once. The depicted Fileselectbox features a slider bar by default and can be resized by using a sizer located in the lower right corner. The File Navigation Services remember these settings individually for every program so that the box will be displayed with the correct settings every time it is opened. It is also possible to use this Fileselectbox and switch to other programs while the box is open.

Starting with EasyGem 4.0, the File Navigation Services can be accessed with the following command:

Easy_Fnav R Fsspec$,R Reply$,Prompt$[,Title$[,X,Y]],R Sel
Displays a new file selection box.

The individual variables have the following meaning:
Fsspec$ A FileSpecificationRecord can be passed in this string when called. This specifies which folder content is displayed when opening the box. Fsspec$="" has the effect that the path with the same Sel number utilized for the last call is displayed. If the path information in Fsspec$ is invalid the desktop is used as the default path.

Easy_Fnav makes it possible to select more than one file at the same time (Sel=0 or Sel=2). This is the reason why, in this case, Fsspec$ contains a chain of FileSpecificationRecords after reentry. Every individual FileSpecificationRecord is here exactly 70 bytes long. If nothing has been selected then Fsspec$="" applies.
Reply$ If Sel=0 or Sel=2 applies, then a file type list can be passed in this string, which may be used to specify the file types to be displayed in the box. For example, in case of Reply$="TEXTPICTOBAS" only text files, pictures of the type 'PICT', and Omikron Basic token code files would be displayed. If Reply$="", then all file types are displayed.

Note: Use a pop-up menu in the Fileselectbox to change the display option even after opening.

In case of
Sel=1, you can use Reply$ to pass a default name to be used for saving the file. This name is entered into the Easy_Fnav box but can also still be changed by the user.

The value of
Reply$ has no input significance for the other Easy_Fnav types.

After reentry,
Reply$ contains the FileReplyRecord. The structure is different for Easy_Fnav than for Easy_Fsel. You do not require the FileReplyRecord for normal applications. Detailed information about the exact meaning is supplied in "Inside Macintosh, Programming with Navigation Services."
Prompt$ This is a string output in the Fileselectbox.
Title$ Window title of the Fileselect box.
X X-position of the upper left corner of the Fileselectbox.
Y Y-position of the upper left corner of the Fileselectbox.
Sel A value between 0 and 6 must be passed in this variable during input. This determines which box type will be opened. The individual values have the following meaning:

0: Opens one or several files at once
1: Saves a file
2: Selects one or several files at once
3: Selects a volume
4: Selects a folder
5: Selects any desired object
6: Creates a new folder

The variable contains the value 0 after the reentry, if the box has been exited with [Cancel]; otherwise the number of selected objects.

Remember to have a look at the "Easy_Fnav.BAS" program in the DEMO folder. It shows you how to call the different variations and how to determine the selected objects after the reentry.
If the File Navigation Services are not present, the old Fileselectbox is automatically displayed.

Warning: The File Navigation Services function correctly only if you give your program a signature (COMPILER "Signature XXXX"). This also applies to Easy_Fsel, if System 8.5 or later has been installed, because Easy_Fsel is then automatically rerouted to Easy_Fnav.

Since modern computers have colored displays by default, programmers are faced with the problem on how to offer the user a simple way to select a specific color (e.g., for a text or drawing pen). The following EasyGem command offers the possibility to call up a dialog box, which is then used to choose a variety of colors easily and simply.

Pick_Color X,Y,Prompt$,Color_In,Color_Out,R Button
Display the color picker dialog box.

The meaning of the individual variables is as follows:
X,Y This is used to determine where on the screen the dialog box is supposed to appear. X and Y define the upper left-hand corner of the dialog box. If X=0 and Y=0, the dialog box will be displayed centered.
Prompt$ This parameter may be used to pass a prompt. A prompt is a short text, which is shown in the upper part of the dialog box (e.g., "Please choose a color, ").
Color indexes (a number between 0 and 255) have to be passed in this parameter. Color_In then contains the index of the input color. The corresponding color hue or tint is shown in the upper right-hand side of the dialog box. The chosen color is registered in Color_Out, if the box has been exited using 'OK', otherwise Color_Out will not change the color.
Button This variable equals zero if Pick_Color has been exited using 'Cancel,' otherwise it is unequal zero.

The color picker dialog box allows the user to choose colors in various different color spaces (e.g., RGB, CYMK, HLS, etc.), which therefore represents a very professional type of color selection. But please remember that depending on the set pixel depths not all desired colors can actually be realized on screen.

Especially in the case of scientific applications, it is often necessary or desired to depict a data set of a two-dimensional field (measuring or computational data) in color, because this facilitates any interpretation of the data significantly. This task is child's play using the following procedure.

Display_Data &Dat(,),Dat_W,Dat_S,&Col(),Ix,Iy,Iw,Ih,X,Y,W,H
Display data set.

The meaning of the individual parameters is as follows:
Dat(,) This fields contains the measured or computed values, which you would like to use for the visualization. The field has to be an integer field (byte, short or long), since the values are after all going to be interpreted as an index within a color palette and only whole numbers may be used for that purpose.
Byte fields are quite sufficient for most applications. This enables the use of 256 different colors. Some special circumstances, however, might benefit from using short integers (up to 32768 colors) or long integers (practically an unlimited number of colors). If your source data is located in a floating point field, you have to transfer them into an integer field first and renormalize them during the transfer in such a way that only positive numbers occur in an interval, for which the color map has been defined in
Dat_W This is the width of a row, i.e., the value of the first index for which the field Dat(,) has been dimensioned, plus one. For example: DIM Dat(639,399):Dat_W=640
Dat_S This parameter indicates how many bytes are taken by a field element. Here, in the case of byte fields, 1 has to be passed, in the case of short integer fields 2, and 4 when dealing with long integer fields.
Col() This field has to be a long integer field and contains the colors in RGB values. Each field element occupies four bytes. The first byte is free. With 256 colors or less, it is here possible to enter, e.g., an index. The red component is located in the second byte, the green component in the third, and the blue component of the color belonging to the corresponding index in the fourth (each 0 to $FF).

Important: A color has to be defined in Col() for each value in Dat(,). Therefore, Col() has to be at least dimensioned to the largest of the values contained in Dat(,) and has to be filled with meaningful color values.
Ix,Iy,Iw,Ih These four parameters determine which part of the field passed in Dat(,) is supposed to be depicted. The values are to be understood in terms of field indices. For example: If the the data is contained in a matrix such as Dat(639,399) and you indicate Ix=160 and Iw=320, then these field elements with a first index greater or equal 160 and less than 480 are used for the depiction. Iy and Ih determine the interval for the second index accordingly.
X,Y,W,H These four parameters define the target area on the active graphics port (set with Gwin_Activate, Win_Activate or GRAF_PORT). If Iw<>W or Ih<>H, then the picture will be shaped in such a ways as to make it fit precisely into the target area.

This is a very powerful procedure, which will facilitate and ease many tasks. However, it is also very easily possible to crash your computer if false parameters are passed. Special attention should be paid to Dat(,) - it should not contain any negative values. Also, make sure that Dat_W and Dat_S are correct and that Col() was dimensioned sufficiently.
Ample BASIC memory has to be allocated for this task with
COMPILER "BAS_MEM X" since most of the employed fields have to be rather large to effect a detailed depiction on the screen. An alternate option is to request memory directly from the Mac OS and to deposit your data there the same way one would deposit data in a two-dimensional field. Use the command MAC_OS Handle;1,"NewHandle",Size for this task. This function returns the handle (pointer to a pointer) of the requested memory. This handle can then be passed to the procedure Display_Data instead of &Dat(,). However, do not forget to lock the memory area using MAC_OS ;1,"HLock",Handle before using it. The advantage of this method is that the memory does not have to be from the limited BASIC memory, but rather may originate in the application heap or any other free memory section. The Mac OS functions required for this task are described in further detail in "Inside Macintosh, Memory."
The program EasyFractal.BAS in the DEMO folder shows one of the possible application uses for the procedure

Sometimes it is advantageous to exchange data between different programs or to affect changes in a program using another program. For example, a user might want to open a file, which cannot be interpreted by your program. Here it might be easiest to send a message to another suitable program to open the desired file. This communication between different programs is not easy to program, because it requires a rather complicated data structure. Anybody wanting to exhaust all options and is not afraid of using programming similar to C++ should have a look at "Inside Macintosh, Interapplication Communication." All others can avail themselves of a command integrated into EasyGem, which will start other programs, open that program's files, and can exit these other programs as well.

This procedure is as follows:

Event_Send Signature,Event_Type,Fsspec$,R Oserr
Sends event.

The individual variables have the following meaning:
Signature The signature of a program is a 32-bit number, usually with a series of 4 encoded letters. For example, Omikron Basic has the signature CVIL("OmBa") and the finder the signature CVIL("MACS"). Use Signature to determine the recipient of the message. The program has to be already running or it cannot receive any messages.

Note: If your objective is to open a file by another program and you do not know if that program is already running, you should send the message back to the Finder (Signature = CVIL("MACS")), because the Finder will certainly be running. The Finder then searches for the creator of this file, starts it if necessary, and then initiates the opening of your file.
Event_Type Use the event type to specify what is to take place. There are 3 basic options that should be understood by any program:

Event_Type =
: Opens document.
CVIL("pdoc"): Prints document.
CVIL("quit"): Ends program.

Note: If all you want to do is start another program without passing a file to open at that time you can use an "odoc" event by specifying the program file itself as the document file and then send this message to the Finder.
Fsspec$ This FileSpecificationRecord is used to specify which file is to be opened or printed. Here, you should always pass a complete FileSpecificationRecord, because the receiving program cannot know the folder in which the file is located.
Oserr An error number is returned in this variable if the message could not be send. The most frequent errors are as follows:

-609 : Signature does not exist.
-903 : Recipient does not have a 'SIZE' resource (this is required for a program to receive high level events). The 'SIZE' resource is automatically created by Omikron Basic Compiler.

More details about all possible error messages can be found in "Inside Macintosh, Interapplication Communication."

Remember to have a look at the "Event_Send.BAS" program in the DEMO folder.
A non-modal dialog box opens after the start of this program, which contains three buttons and one pop-up menu.
Use the uppermost button to select the recipient. The default setting is the Finder. If you are clicking on this button, a Fileselectbox opens and you can then specify a different program as the recipient. The program has to be already running or it cannot receive any messages.
Use the pop-up menu to select one of three event types:
The button underneath the pop-up menu functions the same way as the first button. This button determines the object to be send to the recipient. The standard setting is here a text file called "DummyText.TXT."

Leave the settings as they are for now and just click on 'Send'. The Finder will be informed that it is to open the file named "DummyText.TXT." Since this is a "SimpleText" file, the Finder first starts the program "SimpleText" and then makes this program open the file "DummyText.TXT." Now a window containing the sample text should open on screen.

Now click on the upper button in the dialog box and select the program "SimpleText" as the recipient. The program is located on the Macintosh CD in the "Apple Extras:SimpleText" folder. Use the pop-up menu to now select the event type 'Exit Application' ("quit" event). Click on 'Send'. SimpleText now receives the message to terminate itself.

Warning: Never send a "quit" event to the Finder. This would cause the Finder to close and all icons and Finder windows would disappear from the desktop. The Finder window would no longer be accessible as well so that no file operations could be carried out, no programs could be started, etc. The worst case scenario would entail having to restart your computer.

Reference List Window Library -turn page- Reference List Utility Library

Contents | Start

© 1998-2000 Berkhan-Software | Home