💾 Archived View for spam.works › mirrors › textfiles › apple › DOCUMENTATION › guimaster captured on 2023-06-16 at 21:19:49.
-=-=-=-=-=-=-
<Shaston 8>
;;;;;;;;;;;;;;;;;;;; ;;;; ;;;; ;;;;;;;;;;;;;;;;;;;;
;;;; ;;;; Master ;;;; ;;;;
;;;; ;;;;;;;;;;;;; ;;;; v1.0 ;;;; ;;;;
;;;; ;;;; ;;;; ;;;; ;;;;
;;;;;;;;;;;;;;;;;;;; ;;;;;;;;;;;;;;;;;;;; ;;;;;;;;;;;;;;;;;;;;
by Kris Olsson
-=-=-=--=-=-=-
(c) 1991
a -=Kurono Katana=- production
From the author of ChronosII, the ultimate menu bar
clock/calendar/chronograph!
I. What is GUIMaster?
About a month ago, a friend of mine was telling me how nice it would be
if he could spruce up the GS GUI (Graphic User Interface). Maybe change an arrow here, shade in a check box there, change the close boxes on all thewindows. At first I thought that would be a nice idea, and left it at that. Four days ago (Jan. 1, 1991), however, as I was flipping through GS toolbox reference manuals, I noticed that there were commands built into the toolbox that let me do some of what my friend had suggested a month ago. Some days later, I finished programming. The result: GUIMaster.
GUIMaster lets you change nearly every component of your GS desktop: scroll bars, check boxes, radio buttons, regular buttons, the menu bar, the window size box, and the window close and zoom boxes. Not only can change the way they look, however, you can change their colors, too.
II. Detailed Installation Instructions
Here are explicit instructions on how to install GUIMaster:
1) Launch the Finder
2) Open your boot disk
3) Open the System, then System.Setup folder. System.Setup should be your top window.
4) Copy "GUIMaster" into System.Setup.
5) Create a folder and name it "GUIFiles" in the System.Setup directory.
6) Copy the necessary GUI files into the folder.
E.g.,If you wish to install a GUIFile called "LacquerGUI" (the one provided),
copy all the files beginning with "LacquerGUI" into the folder
you have just created (for LacquerGUI, this includes LacquerGUI.w
and LacquerGUI.c). Suffixed files are "support" files. The unsuffixed
file is the "main" file.
7) Copy the file "MasterGUI" into the folder.
8) Copy the file "GUISetup" into your NDA folder.
You are finished. If for any reason, GUIMaster cannot read or interpret the
"main" file, or if the MasterGUI file is corrupted, you will be presented with
the "standard" GS desktop.
III. Creating your own GUI Files
This part gets a little technical.
At this point, there is no way for the ordinary GS user to create his or her own "custom GUI files". In the future, if people show interest in the program (by paying the ShareWare fee {I'll get to that later} or by sending me comments, suggestions, etc.), I will write a GUI editor using the standard GS desktop, which will be able to create GUIMaster compatible files.
If you are an ordinary user, and not interested in the technical mumbo-jumbo,
skip to section IV.
A Little About the "Main" and "Support" Files
-----------------------------------------
The "main" file stores all the color code information for the GS desktop, in addition to storing the file names of the "support" files. "Main" files are of filetype $C4. (Maybe in the future also by the three letter code GUI!)
"Support" files are merely the font files used to replace the standard GS controls and window icons. However, these font files must be created by modifying the provided standard control and window files, as they use custom boundaries, etc. The file names of the standard control and window files are "StandardControl" and "StandardWindow" respectively. Once again, "Support" files are standard GS font files; filetype $C8. In addition, to standardize things, and can be edited with any GS font editor. Created "support" files should be given the name of the "main" file that they are associated with, suffixed with either a ".w" (for the window font), or ".c" (for the control font).
Writing "Main" Files
-------------------
To understand how to write a main file, it is best to look at an example.
The following is the source code for LacquerGUI (written in standard
ORCA/M source), with added comments:
keep LacquerGUI ;redundant if using included
;EXEC File (see later on), otherwise set
;to name for finished "main" file.
GUI start ;the label for the start
;directive can be anything
currentversion equ $0100 ;$0100=v1.0 This is the current
;version of the program at the time
;of this writing.
;----Header Information----
signature dc c'GUIM' ;shows that this is a GUIMaster file
version dc i'currentversion' ;the current version (see equate above)
; The following is a 129-byte block holding the pathname of the "support" file
; containing the control icons. It begins with a standard Pascal string
; of x characters, and then a "ds" of 129-(x+1) bytes is added after it.
; The pathname MUST start with "*/system/system.setup/guifiles/", and then
; MUST be immediately followed by the FILENAME of file.
; ---Note---
; If your GUI does not have any control icons, just use "ds 129" and GUIMaster
; will use standard icons.
controlpath dc i1'43'
dc c'*/system/system.setup/guifiles/LacquerGUI.c'
ds 85
; The following is a 129-byte block holding the pathname of the "support" file
; containing the window icons. It begins with a standard Pascal string
; of x characters, and then a "ds" of 129-(x+1) bytes is added after it.
; The pathname MUST start with "*/system/system.setup/guifiles/", and then
; MUST be immediately followed by the FILENAME of file.
; ---Note---
; If your GUI does not have any window icons, just use "ds 129" and GUIMaster
; will use standard icons.
windowpath dc i1'43'
dc c'*/system/system.setup/guifiles/LacquerGUI.w'
ds 85
;----Control Definition----
MenuColors dc i'%0000000000001111' ;GUIMaster uses standard
dc i'%0000000011110000' ;control color tables.
dc i'%0000000000110000' ;Please consult your
ButtonColors dc i'%0000000000000000' ;Apple IIGS ToolBox Reference
dc i'%0000000011110000' ;Manuals for more information
dc i'%0000000000000000' ;(its a lot of info!).
dc i'%0000000011110000'
dc i'%0000000000001111'
CheckBoxColors ds 2
dc i'%0000000011110000'
dc i'%0000000000001111'
dc i'%0000000011110000'
IconButtonColors dc i'%0000000000000000' ;Not implemented at this time.
dc i'%0000000011110000' ;Can be set to anything.
dc i'%0000000000000000'
dc i'%0000000011110000'
dc i'%0000000000001111'
ListColors dc i'%0000000000000000'
dc i'%0000000000000000'
dc i'%0000000000000011'
dc i'%0000000000000011'
dc i'%0000000000000000'
PopUpColors dc i'%0000000011110000' ;Not implemented at this time.
dc i'%0000000000001111' ;Can be set to anything.
dc i'%0000000000110000'
RadioColors ds 2
dc i'%0000000011110000'
dc i'%0000000000001111'
dc i'%0000000011110000'
ScrollBarColors dc i'%0000000000110000'
dc i'%0000000000001111'
dc i'%0000000000001111'
ds 2
dc i'%000000000011000000'
ds 2
dc i'%0000000000001111'
dc i'%0000000011000000'
SizeBoxColors dc i'%0000000000110000'
dc i'%0000000000001111'
dc i'%0000000000001111'
;----Window Definition----
WindowColors dc i'%0000000000110000'
dc i'%0000111100001111'
dc i'%0000000000000000'
dc i'%1100000011111111'
dc i'%0000000011110000'
TextEditColors ds 4 ;first two textedit colors from color
end ;record not implemented yet
Saving Your Source
------------------
Once you have finished writing your source code, save it as how you plan to name the finished "main" file, with the suffix ".src", e.g., I saved "LacquerGUI" as "LacquerGUI.src". This will provide compatibility with the enclosed EXEC file.
The EXEC File and Assembling Your "Main" File Source Code
----------------------------------------------------
Encluded with this archive is an EXEC file for use in assembling your source
into GUIMaster readable code.
To use the macro, enter "GUIExec" followed by a space and the name that you plan to use for your "main" file (see Saving Your Source, earlier on), e.g., for a source code file called "LacquerGUI.src", to be compiled into a GUIMaster "main" file called "LacquerGUI", enter "GUIExec LacquerGUI". The "main" file that you wanted will then be generated and saved on your disk.
----Note----
Do NOT type "GUIExec" and follow it with the name of your source code or GUIExec will delete your code! E.g., Do NOT type "GUIExec LacquerGUI.src" if LacquerGUI.src is the name of your source code; type "GUIExec LacquerGUI".
To manually assemble your source code, type:
ASML +M "name of your source code"
MakeBin "name your file was 'kept' as" (using the keep primitive in the source)
FileType "the name your file was 'kept' as" $c4
This will also create GUIMaster compatible code.
Making "Support" Files
----------------------
See the A Little About the "Main" and "Support" Files section for details.
Installing Your New GUI
-----------------------
Follow standard GUI-installing instructions, aforementioned.
IV. Selecting Which GUI File to Use
Select this NDA "GUI Setup" to choose your GUI file. Make sure that you select a GUI File in the "GUIFiles" directory (see the installation section for more info).
In the future I'd like to write a cdev to do the work of this NDA, but I have no information on how to write a cdev (living in Japan leaves me out of touch).
V. Where it Doesn't Work and Future Upgrades
GUIMaster has trouble with new, extended controls implemented in system v5.0 and up. Unfortunately, this includes the new TextEdit controls and pop-up menus.
I tried very hard to implement support for these controls in this version, but could not. As a result, you cannot change the color of pop-up menus, or the frame or background of TextEdit controls. In addition, scroll bars that are part of the TextEdit control will appear in the usual GS desktop colors and format, although the icons will remain the same in.
Another drawback was unavoidable short of rewriting Apple's code for the list control: the list control cannot support a dithered frame. As a result, if you use dithered colors for your scroll bar, they may not blend in well with your list.
I also tried to add provisions for a default "desk pattern" to appear, but despite my efforts to do so with the new _MessageCenter message type 2, I could not get this feature to work. (As a result of this, I have included a file called "DeskPicture" on this disk which works nicely with the LacqueredGUI GUI, through the use of a desk picture displayer such as DeskPicInit.)
Using this with programs that rewrite different parts of the two icon sets may cause an icon that you originally drew to take on a different shape. A good example of this is with AWGS v1.0 v (...?). In the telecomm module, among others, the resize window icon is replaced with a smaller one. I have just figured out a way to circumvent this minor annoyance and will include it in the next release.
There is only one actual inexplicable problem ("bug" if you will) with this program: when using AWGS v1.0 v(...?), various custom list records (such as the file requester list) will have some foreground and background colors swapped. I have no idea why. I don't know if this bug is present in v1.1; I was loaned my version from a friend of mine. If anyone knows why this happens, or if it happens in the latest release of AWGS, please write and tell me why, so I can fix it.
Future upgrades, in addition to attempting to fix the "bugs" and "shortcomings" present in this version, will probably include the aforementioned GUI Setup cdev in place of the NDA, and a desktop GUI-creation application.
There have been no other conflicts, unwarranted crashes, etc.
I plan to make all future upgrades of this program free, except for the cost of a disk and postage, to all registered users. I will notify registered users when an upgrade is available.
VI. ShareWare Fee and Final Notes
The ShareWare fee for this program is $5-$10, depending on how much you think
it is worth (more is also accepted!). I spent 5 LOOONG days writing this init file, a total of about 30 hours! Please be honest and pay the ShareWare fee if you think the program is worth it. Otherwise, delete all your copies of it.
Please give unaltered copies of the archive that this file came in to every GS
owner you know!
The money I receive from this and my other ShareWare programs will go towards
my programming. For further projects I have in mind, please see the "FutureProjects" file. I don't want to bore you here, but I think I have some pretty interesting projects, so it'll pay to send in the ShareWare!.
My addresses:
America:Kris Olsson Japan:Kris Olsson
American Embassy Grew Tower 5051
Box 215 Roppongi 2-1-1
APO San Francisco, CA 96503 Minato-ku
Tokyo 103
If you find a bug, have a suggestion or complaint, or have created a nice GUI file, please write to me.
Enjoy!
Apple II Infintum!