Fish 'n' More 2

home *** CD-ROM | disk | FTP | other *** search

/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / graphics / utilities / gadgeted / gadgeted.doc < prev next >

Wrap

Text File | 1991-01-17 | 31KB | 653 lines

- GadgetED version 2.0 - © Copyright 1990 Jaba Development written in Aztec C version 5.0a by Jan van den Baard DISCLAIMER ---------------------------------------------------------------------------- The author is NOT responsible for the suitability or accuracy of this documentation and/or the program(s) it describes. Any damage sustained by the use or misuse of this documentation and/or the program(s) it describes is the responsibilty of the user her/him self. ---------------------------------------------------------------------------- COPYRIGHT ---------------------------------------------------------------------------- GadgetED, © Copyright 1990-91 by Jaba Development. All rights reserved. This program may be distributed non-commercially only providing that the source code, documentation and copyright notice remains intact. This program is FREEWARE so no financial donation is neacecary (but welcome). ---------------------------------------------------------------------------- TABLE OF CONTENTS: OVERVIEW I REQUIREMENTS II STARTING GADGETED III THE PROJECT MENU IV THE GADGETS MENU V THE FPEN & BPEN MENUS VI THE GENEATED SOURCE VII COMPILING VIII HISTORY IX NOTES X ---------------------------------------------------------------------------- I. OVERVIEW ---------------------------------------------------------------------------- GadgetED is designed to save the Amiga programmer a lot of time in creating intuition gadgets. This version of GadgetED has the following features: o - editing gadgets for a workbench or a custom screen. o - editing gadgets for a window or a requester. o - full control over the window flags. o - adding, modifying, moving and deleting texts for gadgets and window. o - adding, editing, moving, re-sizing, deleting and copying of gadgets. o - loading IFF-ILBM brushes as gadget rendering. o - loading IFF-ILBM colormaps for custom screens. o - a palette editor to create your own custom colors. o - title line gadget information. o - fully mouse and keyboard controlled. o - generation of source code in C or Assembler. o - binary saving for later loading and editing. ---------------------------------------------------------------------------- II. REQUIREMENTS ---------------------------------------------------------------------------- GadgetED was programmed in Aztec C V5.0a on an Amiga 500 Kick 1.3 with 2 Meg memory and a 20Meg HardDisk but it should run on a standard 512 K machine. What you do need to work with GadgetED is a C Compiler and/or an Assembler with all the standard include files. GadgetED also requires a copy of the "tool.library", which is also on this disk, to be copied into the LIBS: directory of the GadgetED boot disk. ---------------------------------------------------------------------------- III. STARTING GADGETED ---------------------------------------------------------------------------- GadgetED can be run from the CLI or the workbench. If you run GadgetED from the workbench all you have to do is double-click the "GadgetED" icon or one of the "GE" icons. If you want to run GadgetED from the CLI just type "GadgetED [filename]" where "filename" is an optional name of the "GE" file you want to edit. When you have started GadgetED without a filename a little window opens in the middle of the screen with the following gadgets: WINDOW - selecting this gadget tell's GadgetED that you want to edit gadgets for a window. REQUESTER - selecting this gadget tell's GadgetED that you want to edit gadgets for a requester. 1 - custom screen, depth = 1, 2 colors. 2 - custom screen, depth = 2, 4 colors. 3 - custom screen, depth = 3, 8 colors. 4 - custom screen, depth = 4, 16 colors. (SLOWS UP THE 68000) 5 - custom screen, depth = 5, 32 colors. WORKBENCH - if you select this gadget GadgetED still opens it's own screen but the colors are the same as your workbench and the generated structures will be for the workbench screen. When you are done click "OK" and a screen opens with a little window on it. If you click on "CANCEL" you leave the program again. NOTE: If you have selected to edit gadgets for a requester you will see a window with a colored rectangle in it. This rectangle represents the requester you are working on. You can size and position the window in order to get the requester how and where you want it. Now let's create our first gadget. Move the mouse pointer to where you want the top-left corner of the gadget to be and click the left mouse button. If you look at the screen title now you will see some information displayed. This information means, from left to right: o - the mouse pointer X coordinate. o - the mouse pointer Y coordinate. o - the gadget left edge. o - the gadget top edge. o - the gadget width. o - the gadget height. NOTE: The values are relative to the top-left corner of the window/requester This information is important to place and size your gadget exactly the way it should be. If you move the mouse pointer the values in the info-line will change and a box will follow the mouse pointer relative to the top-left corner. This box represents the gadget. When the box is the way you want the gadget to be you must click the left mouse button again and the gadget will be added to the window or requester. Now you have created your first gadget with GadgetED so let's take a look at the menus to see what else you can do. ---------------------------------------------------------------------------- IV. THE PROJECT MENU ---------------------------------------------------------------------------- This menu consists of the following items: About: <right Amiga ?> Function: display information about the copyright, the author and the language GadgetED was programmed in. Just click on the CONTINUE gadget to get rid of it. New: <right Amiga N> Function: erases all gadgets and changes made sofar and resets the display to the default. If the changes made where not saved a requester opens telling you this and asking you if you really want to do this. Click on the NO gadget if you made a mistake by calling this function otherwise click on the YES gadget. NOTE: If you proceed with this function and the changes where not saved there is no way to get back the information. Load: <right Amiga L> Function: This opens the file requester. In this file requester you can type or select the name of the 'GE' file you want to load. NOTE: The program only loads 'GE' files. If you try to load a file that is not a 'GE' file a requester appears telling you that the file you have selected was of an Unknown type. When the file you have selected is successfully loaded. The screen displays now displays the gadgets e.c.t. found in the file. Save: <right Amiga S> Function: This opens the file requester in which you can type or select a name under which the current display is saved. You should always save the display before you exit the program. This ensures the file is always up to date. If you do not save the display before quiting the program any changes made since the last time you saved will be lost. Generate Source: C: <right Amiga C> Function: This generates the source code in C of the display edited sofar. In the file requester you can type or select the name under which the generated source code is saved. Assembler: <right Amiga A> Function: As with C only the generated source code is in MC68000 Assembler. Preferences: <right Amiga P> Function: This is used to (un)set certan preferred program flags. It opens a window with the following gadgets: Skip zero bit-planes : This tell's GadgetED to skip any image bit- planes that only contains zero's. This will reduce the size of the image data source GadgetED generates. Auto Gadget -> Image size: This tell's GadgetED to automaticly adjust the dimensions of the gadget to the dimensions of the loaded image. Image Copy : This tell's GadgetED to also copy any images that might be attached to a gadget. WINDOW or REQUESTER : Switch from editing gadgets for a window to editing gadgets for a requester or viceversa. Save : Save the preferences to a file called 'DEVS:GadgetED.PREFS'. Use : Set the preferences in the program. Save & Use : Both save and set these preferences. Close WorkBench or Open WorkBench: Function: This enables you to close/open the workbench screen. You can close the workbench screen if your (!!computer!!) memory is running a little low. NOTE: It's only possible to close the workbench screen if there are no programs running that use the workbench screen. This means that if you started GadgetED from the CLI it isn't possible to close the workbench screen because the CLI is a program that makes use of the workbench screen. Quit: <right Amiga Q> Function: Quits GadgetED if you select YES in the requester that opened to ask you to if you really want to do this. ---------------------------------------------------------------------------- V. THE GADGETS MENU ---------------------------------------------------------------------------- In this menu a lot of functions are defined which asks you to pick a gadget to perform a certain action. If you accidently activated one of these functions you can press the 'ESC' key instead of selecting a gadget to exit this function. The following items are defined in this menu: Move a gadget: <F1> Function: When 'Move a gadget' is selected the message 'PICK GADGET TO MOVE' is displayed in the screen title bar. Now click on the gadget you want to move and the title will display the information of the selected gadget. Now move the box which represents the gadget with the mouse to it's new location and click on the left mouse button and the gadget is moved to the new location. Size a gadget: <F2> Function: When the message 'PICK GADGET TO RE-SIZE' is displayed you can click on the gadget you want to re-size. Again the gadget infor- mation is displayed in the screen title. Now move the mouse pointer to size the box until it has the size you want the gadget to be. Just click the left mouse button and the gadget is re- sized. Copy a gadget: <F3> Function: This function enables you to make a copy of a gadget. Once the message 'PICK GADGET TO COPY' is displayed you can click on the gadget you want to copy. If the gadget has Images attached to it and 'Image Copy' was switched on in the preferences window these images will also be copied. Otherwise the copied gadget will have a border as gadget render. Move the box representing the copy to the location you want it and click the left mouse button. Delete a gadget: <F4> Function: When the message 'PICK GADGET TO DELETE' is displayed you can click on the gadget you want to delete and it's gone. NOTE: Once the gadget is deleted there is no turning back. Edit a gadget: <F5> Function: This function enables you to edit the complete set of gadget flags intuition has to offer and some other special things. When the message 'PICK GADGET TO EDIT' is displayed in the screen title you can click on the gadget to edit. Now a window is opened with the following gadgets in it: Under FLAGS: GADGHNONE - nothing happens to the gadget when it is selected. GADGHCOMP - the gadget hitbox is displayed complemented when the gadget is selected. GADGHBOX - a box is drawed around the gadget when it is selected. GRELBOTTOM - the gadget top edge is relative to the bottom of the window. GRELRIGHT - the gadget left edge is relative to the right of the window. GRELWIDTH - the gadget width is relative to the window width. GRELHEIGHT - the gadget height is relative to the window height. SELECTED - the gadget is displayed in selected mode. GADGDISABLED - the gadget cannot be selected. This flag will only be set in the source code. Under ACTIVATION: TOGGLESELECT - the gadget can switched to selected mode by clicking on it and to unselected mode by clicking on it again. RELVERIFY - intuition waits to send a message until the left mouse button is released with the pointer still above the gadget. GADGIMMEDIATE - intuition sends a message as soon as this gadget is selected. RIGHTBORDER - the gadget is placed in the right window border. LEFTBORDER - the gadget is placed in the left window border. TOPBORDER - the gadget is placed in to top window border. BOTTOMBORDER - the gadget is place in the bottom window border. ENDGADGET - this gadget closes a requester FOLLOWMOUSE - this gadget signals the window when the mouse moves. Under PROP SPECIAL: AUTOKNOB - intuition provides the gadget with it's own knob FREEHORIZ - the knob may be moved horizontally. FREEVERT - the knob may be moved vertically. PROPBORDERLESS - intuition does not draw a border around the gadget. HBODY - enter the steps the prop gadget can take horizontal here. VBODY - enter the steps the prop gadget can take vertical here. Under STRING SPECIAL: UNDOBUFFER - create an undo buffer for this gadget. STRINGCENTER - the string is centered in the gadget. STRINGRIGHT - the string starts at the right of the gadget. LONGINT - allow numbers to be entered. ALTKEYMAP - this gadget has it's own keymap. SIZE - enter the maximum amount of characters that can be typed in this gadget here. Under SOURCE LABEL NAME: In this string gadget you can type in the name of the gadget that it will have in the generated source code. NOTE: Any spaces found in this name will be replaced by a '_'. Avoid using names that are the same as symbols and commands of the target language. Under GADGET TYPE: BOOL - make this gadget a boolean gadget. PROPORTIONAL - make this gadget a prop gadget. STRING - make this gadget a string gadget. BORDERONLY - this is a special flag not defined by intuition but it is used to tell GadgetED only to generate the border structure of this gadget in the source code. This flag can only be set on a BOOL gadget that has no texts or images attached to it. GZZGADGET - this flag should be set with gadgets that are in the border of a GIMMEZEROZERO window. Selecting OK will set the flags edited to the gadget and selecting CANCEL will resume to editing without setting the edited flags. Gadget text: Add a text: <F6> Function: This enables you to add texts to a gadget. When the message 'PICK GADGET TO ADD TEXT' is displayed in the screen title you can click on the gadget to which a text should be added. In the window that now opens the following gadgets are displayed: Under Enter or edit text : In this string gadget you must type the text you want to add to the gadget. Under DrawModes: JAM1 - only the frontpen color is used. JAM2 - both the front and back pens are used. COMPLEMENT - complements the colors used. INVERSVID - swaps the front and back pen colors. Selecting CANCEL will resume to editing without adding the text to the gadget. Selecting OK will close the text window and if you move the mouse pointer in your edit window you will see the text next to the pointer. Now move the text to where you want it to be and click the left mouse button and the text is added to the gadget. NOTE: If you didn't type a text in the string gadget the function is canceled even if you have selected OK. Modify a text: Function: When the message 'PICK GADGET TO MODIFY TEXT' is displayed you can click on the gadget which has a text you want to modify. A window in which all the texts added to the gadget are listed is opened. If the text you want to modify is not displayed in the list use the prop gadget to scroll the list until it is displayed. Now click on OK and the same window as with 'Add a text' is opened only the text and it's drawmodes are preset. Now modify what you want and click on OK and the text is modified. Delete a text: Function: When the message 'PICK GADGET TO DELETE TEXT' is displayed in the screen title click on the gadget witch has the text you want to delete. Now the 'text selector' is opened in which you can select the text you want to delete. Click on OK and the text is gone. Move a text: Function: When the message 'PICK GADGET TO MOVE TEXT' is displayed you can click on the gadget which has the text you want to move. In the 'text selector' that opens you can select the text you want to move. Now select OK and if you move the mouse pointer inside the edit window and you will see the text next to the pointer. Move the text to it's new location and click the left mouse button and the text is moved. IFF Image Render: Load Gadget Image: <F7> Function: When the message 'PICK GADGET TO RENDER' is displayed click on the gadget you want to attach an IFF Image to. In the file requester you can type or select the name of the IFF ILBM file you want to load. If the loading was successfull the gadget now displays the image loaded. NOTE: Only IFF ILBM files can be loaded as gadget rendering. Load Select Image: <F8> Function: When the message 'PICK GADGET TO SELECT RENDER' is displayed click on the gadget you want to attach an IFF Image to. In the file requester you can type or select the name of the IFF ILBM file you want to load. When the loading was successfull you can click on the gadget and you will see the Image loaded. NOTE: Only IFF ILBM files can be loaded as select rendering. You cannot load a select image to a gadget that has no gadget render image attached to it. Delete Images: Function: When the message 'PICK GADGET TO DELETE IMAGES' is displayed click on the gadget which has the images you want deleted and they are gone. NOTE: Both the GadgetRender AND the SelectRender Images are deleted. Load (IFF) ColorMap: <F9> Function: This function is only available when you are editing gadgets for a custom screen. In the file requester you can type or select the name of the IFF ILBM file which contains the colors you want set in your edit screen. If the loading was successfull the colors in the file are now set in the edit screen. Edit ColorMap: <F10> Function: This function is only available when you are editing gadgets for a custom screen. In the palette editor you can edit each color of the edit screen. With the R, G and B prop gadgets you can set the RED, GREEN and BLUE values of the selected color. With the 2,4,8,16 or 32 (depending on the screen depth) colored gadgets below you can select the color to edit. Selecting OK will set the edited colors in the edit screen and resume to editing. RESET will reset the colors as they where before you have entered the palette editor. CANCEL will resume to editing without setting the edited colors. Refresh all gadgets: <HELP> Function: If for some reason the display is distorted you can call this function to redraw the entire display. Depending on wether you are editing gadgets for a window or a requester the next item will read: Window or Requester: The items 'Add a text', 'Modify a text', 'Delete a text' and 'Move a text' perform the same action as the function in 'Gadget text' with the exeption that the texts are assigned to the window or requester rather that to a gadget. When you are editing gadgets for a window two items are displayed: Edit Flags: <right Amiga F> Function: This will bring up a window in which all the intuition window Flags are displayed: WINDOWSIZING - the window sizing gadget is included. WINDOWDRAG - the window can be draged aroung with the title bar. WINDOWDEPTH - the window can be put on top or below another window. WINDOWCLOSE - the close window gadget is included. SIZEBRIGHT - the sizing gadget is placed in the right window border. SIZEBBOTTOM - the sizing gadget is placed in the bottom window border. NOCAREREFRESH - intuition does not send a message to the window if a refresh is neacecary. SIMPLE_REFRESH - intuition does no refreshing at all. the program must refresh the window itself when neacecary. SMART_REFRESH - any overlapped part of the window will be bufferd and restored when possible. SUPER_BITMAP - the window can handle a graphics display that is larger than the window itself. BACKDROP - the window is always behind all other windows. GIMMEZERZERO - the window border is handled extra. BORDERLESS - the window border is not displayed. ACTIVATE - the window is activated as soon as it opens. REPORTMOUSE - the mouse pointer position is always reported. RMBTRAP - the possibility to get a message if the right mouse button is pressed. this can only be used if there are no menus attached to the window. NOTE: Only WINDOWSIZING, WINDOWDRAG, WINDOWDEPTH, WINDOWCLOSE, SIZEBRIGHT and SIZEBBOTTOM are actualy set when GadgetEd is running. All the other flags are only generated in the source code. Edit IDCMP: <right Amiga I> Function: This opens a window in which you can set the IDCMP flags of the window. The following gadgets are displayed in the window: SIZEVERIFY - signal if the user is trying to resize the window. NEWSIZE - signal if the user has resized the window. REFRESHWINDOW - signal if the window must be refreshed. ACTIVEWINDOW - signal if the window is activated. INACTIVEWINDOW - signal if the window is deactivated. GADGETDOWN - signal if a gadget is pressed. GADGETUP - signal is a gadget is released. CLOSEWINDOW - signal if the closewindow gadget is selected. REQSET - signal if a requester opened on the window. REQCLEAR - signal if the last requester is closed. REQVERIFY - signal if a requester try's to open in the window. MENUPICK - signal if a menu was picked. MENUVERIFY - signal if the user try's to pick a menu. MOUSEBUTTONS - signal if a mouse button is pressed or released. MOUSEMOVE - signal if the mouse was moved. NOTE: The REPORTMOUSE flag should be set in the window or the FOLLOWMOUSE in a gadget. DELTAMOVE - signal if the mouse had moved. the position is relative to the previous position. INTUITICKS - signal every 1/50 second. The message must be replyed before another INTUITICKS message is signaled. NEWPREFS - signal if the preferences were changed. DISKINSERTED - signal if a disk was inserted into one of the drives. DISKREMOVED - signal if a disk was removed from one of the drives. RAWKEY - signal if a key was pressed. the code is the 'RAW' key code. VANILLAKEY - signal if a key was pressed. the code is the 'treated' ASCII value of the key. WBENCHMESSAGE - signal a workbench message LONELYMESSAGE - signal a non IDCMP message NOTE: None of the above flags are actualy set in GadgetED but they are generated in the source code. Title - Type the Window Title in here. Label - Type the source label name in here. Detail - The window DetailPen. Block - The window BlockPen MinX - The minimum width of the window. MinY - The minimum height of the window. MaxX - The maximum width of the window. MaxY - The maximum height of the window. Selecting CANCEL will prevent the changes to be set. OK sets the changes in the flags e.c.t. and will resume editing. When you are editing gadgets for a requester: Set BackFill: <right Amiga B> Function: This enables you to set the backfill color of the requester. The color used is set by the BPen menu (see THE FPEN & BPEN MENUS) ---------------------------------------------------------------------------- VI. THE FPEN AND BPEN MENUS ---------------------------------------------------------------------------- When one of these two menus are selected you will see a row of 2,4,8,16 or 32 (depending on the screen depth) colored items. These items represent the colors of the edit screen. With the items in the FPen menu you can set the active FrontPen color. All gadgets added will have a border in this color and all texts added will have this color as the FrontPen color. With the items in the BPen menu you can set the active BackPen color. All texts added will have this color as the BackPen color. The active BackPen color is also used to set the BackFill color of the requester. ---------------------------------------------------------------------------- VII. THE GENERATED SOURCE CODE ---------------------------------------------------------------------------- The following defenitions are made at the end of the generated source: NEWWINDOW or REQUESTER - a pointer to the NewWindow or Requester structure. FIRSTGADGET - a pointer to the first gadget in the list. If there where texts added to the window or requester: FIRSTTEXT - a pointer to the first text in the list. If there where 'BORDERONLY' gadgets defined: FIRSTBORDER - a pointer to the first border in the list. If you have edited gadgets for on a custom screen: NEWSCREEN - a pointer to the NewScreen structure. COLORCOUNT - the number of colors in the screen. An array named 'Colors' of USHORT values containing the colors which where on the edit screen. These colors can be set by a simple LoadRGB4() call. If you have edited gadgets for a window and you have attached texts and/or 'BORDERONLY' gadgets to the window a special gadget is placed at the end of the gadgetlist. This gadget is only there to draw the borders and the texts when the window is opened or when the gadgets are refreshed. The GadgetID's are defined as following: Label_ID This means that if you, for example, added a gadget with the label "UP" than "UP_ID" will represents this gadget it's ID. The best way to see what the source looks like is to create some gadgets and let GadgetED generate the source and then look at it. Bassicly all you need to remember are the labels you give your gadgets to be able to acces all of the structures etc. that are linked to these gadgets. I don't really know if the generated C source compiles under lattice , I don't have lattice, but it should give no problems whatsoever. ---------------------------------------------------------------------------- VIII. COMPILING ---------------------------------------------------------------------------- If you have the make utility type: make pre ged Otherwise copile the "defs.h" file with the "-ho defs.pre" option and all other files with the "-so -hi defs.pre" options and then link them together. ---------------------------------------------------------------------------- IX. HISTORY ---------------------------------------------------------------------------- VERSION 1.0 -> Let's not talk about this! VERSION 2.0 -> First release, let's see how it goes. ---------------------------------------------------------------------------- X. NOTES ---------------------------------------------------------------------------- If you take a good look at the supplied source code I'm sure you are ready to throw up but this is what source looks like after a mere 30.000.000.000 changes! My advice to you is too think real hard about what a program must be able to do !!!!BEFORE!!!! you start to code it. Although this is version 2.0 af GadgetED it is the first release. I wish to add Modula and/or OBERON support in the future if only I knew how to declare all of the stuctures etc. in these languages. If you find bugs, I bet you will, or you have ideas to make the program more user-friendly, please report to me at the following adress: Jan van den Baard Bakkerstraat 176 3082 HE, Rotterdam Holland.