NewGui 3.1 (Pre-Release) -==========- 1. What is NewGUI ? 2. Whats the difference between NewGUI and other GUI-Creators? 3. How to program NewGUI 3.1 The procedures 3.1.1 guiinitA() 3.1.2 guimessage() 3.1.3 cleangui() 3.1.4 newguiA() 3.1.5 ng_getattrsA() 3.1.6 ng_setattrsA() 3.2 All Tags with short description 3.3 All Gui-Elements 3.3.1 Basics in GUI-programing with NewGUI 3.3.2 Groups 3.3.3 Elements 3.4 Plugin - Programing 3.4.1 Plugin - Object 3.4.2 after_reply() 3.4.3 clear_render() 3.4.4 render() 3.4.5 gtrender() 3.4.6 will_resize() 3.4.7 min_size() 3.4.8 isgtgadget() 3.4.9 disable() 3.4.A message_test() 3.4.B message_action() 3.4.C handlednd() 3.4.D performdnd() 3.4.E dnd_xchange() 3.7 The modular concept behind NewGUI 3.6 Error-codes 4. Copyright 5. About 1. What is NewGUI? -==================- NewGUI is a Modul for the Language >Amiga E< which should made the programing of GUIs easyier to developers. NewGUI has a lot of features (for example Drag'N'Drop, ARexx-Port, Online-help...) which made the GUI powerful and high-standart but the developing-work and time as few as possible low. The first version was at the beginning of 1995 ready, but the first 4-5 versions were not so good (the had a ugly GUI-Engine and it costs a lot of time to program a GUI...). With the time NewGUI grows and the idea behind NewGUI gets much clearer out of the module. In the end of 1997 the EasyGUI-Source gets free available and i had taken it (not copied it or such a thing!) for making my existing GUI-Engine Syntax- comapible to EasyGUI (so "old" GUI-Descriptions could used with NewGUI). The Plugin-Interface from NewGUI was mixed with that one from EasyGUI and the result was a high powerful Interface with a lot of more features as the one from EasyGUI (Drag'N'Drop...). A few people will say that NewGUI is a simple copy from EasyGUI,but it isn`t - no part and no line of Source is copied! The source was only a little help for me when i started to make the engine syntax-compatible! This people want have to get the NewGUI-Source to see how NewGUI works, but i don`t give it for free because in that case the same thing happens like with some ported PC-Games (...D**M) and a lot of copies came out... it NewGUI is a simple copy from EasyGUI in your oppinion than take the EasyGUI-source and try to get all the features from NewGUI into EasyGUI.. good luck (if it is really to made...). 2. What is the difference between NewGUI and other GUI-Creators? -================================================================- The first difference is that NewGUI isn`t a shared-library but a linkable Module-Class, this could be a disadvantage as good as a advantage. In both case it is sure that NewGUI isn`t so overloaded with "features" like (in my oppinion) MUI ans others... because: why needs a little tool (for example a Version-Tool) a gui with all these features (like commoditie-support...), by the way - MUI handles its "Gadgets" in a own way, the aren`t Intuition-Gadgets (if you don`t believe go to AmiNET, search for a tool calles >ShowGadgets< and let this tool show you all Buttons in a MUI- Window, the result would be: only the scroller/slider-Gadgets will appear!). Thats the main-reason why MUI needs so much RAM and CPU- Time - NewGUI uses GadTools.library and thats the reason why it will be compatible to other OS-Versions (like 3.5 or 4.0 !?) and so it takes profit from every expansion or from every new feature from gadtools.library automatically! But its the programers part to choose his prefered engine, because the GUI-Creator which does everything and all perfect in programers and users-Part isn`t developed, yet. (And this should be the task of a OS-Programmer and not the task from an Third-Party-Developer!) 3. How to program NewGUI -========================- 3.1 procedures: =============== 3.1.1 guiinitA() ---------------- SYNTAX: guihandle:=guiinitA(taglist,maingh=NIL) PARAMETER: taglist = PTR to a tagliste which describes the environment and the GUI itselves maingh = Do not use (for internal use only!!!!) RETURN: guihandle = PTR to a >guihandle< object FUNCTION: Opens a GUI from the given tags (it is possible to open more than one window width the tag NG_NEXTGUI), in all cases this two tag must be given (at all time!): NG_GUI, NG_GUIID BUGS: No bugs reported LOOK ALSO: newguiA() / guimessage() / cleangui() 3.1.2 guimessage() ------------------ SYNTAX: return:=guimessage(guihandle) PARAMETER: guihandle = PTR to the main-guihandle (when using the multi- window-support, otherwinse PTR to the guihandle from the gui which should be processed) RETURN: return = Return-code from the gui (maybe 0 which means that the GUI should be closed or y other value defined as action in a GUI-Element) FUNCTION: Gets messages from the gui and process them (reply, analyse ect...) BUGS: No bugs reported LOOK ALSO: guiinitA() / cleangui() 3.1.3 cleangui() ---------------- SYNTAX: cleangui(guihandle,all=FALSE) PARAMETER: guihandle = PTR to the main-guihandle (when using the multi- window-support, otherwinse PTR to the guihandle from the gui which should be processed) all = If this value is TRUE then all GUIs linked to this GUI will be closed RETURN: None FUNCTION: Closes one specific guihandle or all guis if all = TRUE BUGS: No bugs reported LOOK ALSO: guiinitA() / guimessage() 3.1.4 newguiA() --------------- SYNTAX: return:=newguiA(taglist,getghproc) PARAMETER: taglist = PTR to a tagliste which describes the environment and the GUI itselves getghproc = PTR to a procedure which should get the PTR to the guihandle and the screens-PTR from our GUI. The Syntax from this procedure must be: getghproc(guihandle,screen) ATTENTION! No returnvalue!!! RETURN: return = Return-code from the gui (maybe 0 which means that the GUI should be closed or y other value defined as action in a GUI-Element) FUNCTION: It is a summary from guiinitA(), guimessage() and cleangui(), but with additional features like Fallback to topaz/8 ROMfont if the gui couldn`t open on the screen (in the case that the given font is to large!), at least this two tags must be given (at all time!): NG_GUI, NG_GUIID BUGS: No bugs reported LOOK ALSO: guiinitA() / guimessage() / cleangui() 3.1.5 ng_getattrsA() -------------------- SYNTAX: return:=ng_getattrsA(taglist) PARAMETER: taglist = PTR to a taglist which had all the Information for this procedure (which value should be returned ect..) RETURN: return = Return-value (or PTR ect...), this is specific from the tags given in the taglist, look at the description from the tag for more information! FUNCTION: With this procedure the developer is able to get values and data from the GUI (like Gadget-Datas ect...) At least this two tags must be given: NG_GUI, NG_GUIID BUGS: No bugs reported LOOK ALSO: ng_setattrsA() / guiinitA() / newguiA() 3.1.6 ng_setattrsA() -------------------- SYNTAX: return:=ng_setattrsA(taglist) PARAMETER: taglist = PTR to a taglist which had all the Information for this procedure (which value should be changed ect..) RETURN: return = Return-value (succes of the change ), this is specific from the tags given in the taglist, look at the description from the tag for more information! FUNCTION: With this procedure you are able to change values and data from the gui (like Gadget-Data...) At least this two tags must be given: NG_GUI, NG_GUIID BUGS: No bugs reported LOOK ALSO: ng_getattrsA() / guiinitA() / newguiA() 3.2 All Tags (with Description) =============================== NG_WINDOWTITLE The text which should be displayed in the Windows Dragbar NG_WINDOWLEFT X-offset from the left-upper corner of the window, this tag isn`t necessary, if it is not given the window will be displayed in the middle of the screen. NG_WINDOWTOP Y-offset from the left-upper corner of the window, this tag isn`t necessary, if it is not given the window will be displayed in the middle of the screen. NG_WINDOWMAXWIDTH Maximal width of the window NG_WINDOWMAXHEIGHT Maximal height of the window NG_WINDOWWIDTH Width of the window (The calculation of the width should be NewGUI`s task because a wrong value could produce trah in the GUI!) NG_WINDOWHEIGHT Height of the window (The calculation of the width should be NewGUI`s task because a wrong value could produce trah in the GUI!) NG_WINDOWTYPE The type of the Window, the following types are allowed WTYPE_BASIC - Only a border at the window, no Dragbar, Title or Systemgadget available! WTYPE_NOSIZE - All system gadgets but no Size-gadget WTYPE_COMPLETE - A foll Intuition-Window with all gadgets NG_SCREEN PTR to a screen which should be used but must already open, it isn`t closed after cleangui()1 NG_CLONESCREEN Opens a own Screen, all values which aren`t given (through the taglist) are taken from the Workbench`s-Screen. NewGUI is also able to open the Windows on a public-Screen, which Name must be given in NG_PUBSCREEN and one additional Tag (NG_OPENPUBSCREEN) must be given. NG_SCR_WIDTH With of the Screen (if this Tag isn`t given this value is taken from the Workbench-screen) NG_SCR_HEIGHT Height of the Screen (if this Tag isn`t given this value is taken from the Workbench-screen) NG_SCR_DEPTH Depth (in Bitplanes!) of the Screen (if this Tag isn`t given this value is taken from the Workbench-screen) NG_SCR_PENS The Drawpens of the Screen (look at intuition-autodoc!) (if this Tag isn`t given this value is taken from the Workbench-screen) NG_SCR_MODEID The ScreenMode-ID for this Screen (if this Tag isn`t given this value is taken from the Workbench-screen) NG_SCR_TITLE The text which should be displayed in the title-bar of the Screen (if this tag isn`t given, the title-bar would also be displayed but it will be empty!) NG_SCR_PUBNAME Public-name for our screen or the name of a Pubscreen on which we should open our windows (For this a additional Tag [NG_OPENPUBSCREEN] must be given!) NG_SCR_TAGS More Tags for the Screen (must be a taglist [or a PTR to a taglist] with SA_xxx-Tags, show intuition/screens for details!) NG_OPENPUBSCREEN If this tag is given and if it is TRUE, then we try to open the Windows on another Publicscreen which name must be given in NG_PUBNAME!) NG_USEMAINSCREEN Only useful with Multi-window-support! Our Window should use the same screen as the main-gui NG_GUI GUI-Description (look unter 3.3 for details!) NG_DUMMY Only useful with Multi-window-support! Special parameter for NG_GUI which must be given instead of a GUI-Description if a backdrop-Window without any GUI-Elements should be opened. (All other Features are opened, too - like ARexx-Port, Screen ect...) This is useful because the Menu could be made available all the time even if no Window (with a GUI) is open! NG_GUIID The ID of the GUI, the first GUI must have the ID with the value 1 (ONE) and the others should be defined with the ENUM-symbol (ENUM GUI_MAIN = 1, GUI_SECOND...) NG_DOUBLEGUI This tags allows a GUI to open twice on the Screen, useful for Requester ect... ATTENTION! This tag isn`t tested, so use it with care! NG_NEXTGUI PTR to another full taglist for another GUI (full means that every needed Tag must be given!) look at the examples to show how it works! NG_AUTOOPEN Only useful with Multi-window-support! If this tag is TRUE then this GUI should be already opened at the beginning. If it is not given then you must use the tag NG_OPENGUI with ng_setattrsA() to open this gui! NG_TEXTATTR PTR to a textattr (show at graphics/text), the window uses this Font for the output! NG_FONT_NAME Name of a font which should be used with this window, this font is opened and closed automatically if it is necessary! Only useful together with the tag NG_FONT_SIZE! ATTENTION! At the moment the use of NG_FONT_NAME and NG_FONT_SIZE with the modul ng_guitask() which runs the gui in a seperate Task causes a unusual things like the system hanging... But only with this Modul... i`m tracking this bug down as fast as it is possible! NG_FONT_SIZE height of the font which should used Only useful together with the tag NG_FONT_SIZE! ATTENTION! At the moment the use of NG_FONT_NAME and NG_FONT_SIZE with the modul ng_guitask() which runs the gui in a seperate Task causes a unusual things like the system hanging... But only with this Modul... i`m tracking this bug down as fast as it is possible! NG_USEMAINFONT Only useful with Multi-window-support! If this tag is given, this window uses the same font as the main-window (even if the main-window is a backdrop window!) NG_MENU PTR to an gadtools-newmenu-structure (object). Here you could add a menu-description to a NewGUI-Window! NG_USEMAINMENU Says that NewGUI should use the MenuStrip from the first GUI (Main) for this GUI, too! NG_HELPGUIDE Name from an AmigaGUIDE-Text which should be used for the online-help for this window (every window could have its own online-help-text!) NG_DATA Own Data, this is given to every procedure (action-Value) which NewGUI calls from the GUI NG_ONCLOSE PTR to a procedure (which could be different for every window) which will be called if the CloseGadget from the window is clicked by the user, this procedure says what NewGUI should do and must have the following Syntax: return:=onclose(guihandle) IMPORTANT! return must only have one of there Values: -1 = Do nothing (let the window open) 0 = Close all Guis -2 = Close only "our" window (the window whose Close- Gadget was clicked!) NG_ONTICK PTR to a procedure which will be called at every INTUITICK, this procedure must have the Syntax: ontick(info,guihandle) info = Value from NG_DATA guihandle = PTR to the guihandle where the Tag NG_ONTICK was given (not to the main-guihandle!!!) NG_ONHIDE PTR to a procedure which will be called AFTER a hideaction (NG_HIDE with ng_setattrsA()) here you could do such things like append a App-Icon ect... but you must return quickly and you are not allowed to wait for something in this procedure! NG_ONAPPEAR PTR to a procedure which will be called before the gui appears (call was: NG_APPEAR with ng_setattsA()). Here you could remove the AppIcon or so... This procedure should as fast and as small as possible! You have to return quickly! NG_REXXNAME Name (String or Text) of our ARexx-Port, this Port will automatically be opened! NG_REXXPROC PTR to a procedure which analyses the ARexx-Messages, show at the AFC-Class/Rexxer-Doc for more details NG_GETRX Here you get a PTR to the AFC-Rexxer-Class, this is only meant for sending ARexx-Messages not to receive (this is the task of NewGUI!!!) NG_FILLHOOK PTR to a procedure which task it is to fill a group or the Window-Background, this procedure must have this Syntax: fill(rastport,x,y,width,height,type) rastport = PTR to the rastport of the window x,y,width,heigt = The field which sould be filled type = NG_FILL_WINDOW = Window-background FILLGROUP1 - FILLGROUP6 = A Group should be filled (you could do here anything like BitMapfilling, or just a RectFill ect...) show the examples and the source for ng_fillhook() for more details! NG_FILL_WINDOW Parameter for the procedure called by NG_FILLHOOK NG_KEYFILTER PTR to a procedure to filter Key-Events (for example to scroll up/down a listview or something with the cursor keys), this procedure is called with this syntax: keyfilter(code,raw) code = Key-code (Vanilla- Rawkey) raw = TRUE if it is a Rawkey and FALSE for a Vanillakey NG_PALETTE PTR to a procedure which sets up the screens palette before any window is opened, this procedure is called with th following syntax: setpalette(screen,depth) screen = PTR to the screen which the palette should be set for depth = depth of this screen in bitplanes NG_PREFSPROC PTR to a procedure which should save the preferences of the windows (and the screen), this procedure is called for every window (equal if it is open or closed!) with this syntax save(screen,id,x,y,width,height,open) screen = PTR to the screen id = NG_GUIID of the window x,y = left-top-edge coordinates of the window width = Width of the window height = height of the window open = TRUE if the window is actually open and FALSE if it is closed this time ATTENTION! It could be that x,y,width,height are -1, than this windows wasn`t open at all! This means also that this window should get the size from the NewGUI- Engine (it opens in the middle of the visible Part from the screen), but in all this cases open will be FALSE! NG_GETSCREEN (Only for ng_getattrsA()) Returns the PTR to the used screen NG_GETGUI (Only for ng_getattrsA()) Returns a PTR to the guihandle which belongs to NG_GUIID NG_CHANGEWINDOW (Only for ng_setattrsA()) Changes something in the window, the following Tags are allowed: NG_WINDOWTITLE NG_WINDOWLEFT NG_WINDOWTOP NG_WINDOWMAXWIDTH NG_WINDOWMAXHEIGHT NG_WINDOWWIDTH NG_WINDOWHEIGHT NG_CHANGEMENU (Only for ng_setattrsA()) Changes the Menu which belongs to NG_GUIID NG_CHANGEGUI (Only for ng_setattrsA()) Changes something in the GUI-Description, the following Tags are allowed: NG_OPENGUI NG_CLOSEGUI NG_CLOSECHILDS NG_NEWGUI NG_BLOCKGUI NG_UNBLOCKGUI NG_RESET NG_CHANGEGAD (Only for ng_setattrsA()) Change a Gadget (NOTE: at NG_GADGET there must be a PTR to the element (for example gadptr:=[STR,...]) not to a real GadTools-Gadget!!! This Tags are allowed NG_GETGADGET NG_DISABLE NG_ENABLE NG_GADGET NG_NEWDATA NG_SELECTED NG_VISIBLE NG_LABELS NG_TOP NG_TOTAL NG_CHANGETICKER (Only for ng_setattrsA()) Changes the procedure which will be executed at every IDCMP_INTUITICK-Message, if the given value = TRUE than NO Procedure will be executed! NG_OPENGUI (Only for ng_setattrsA()) Only useful with MultiWindow-Support! Opens the GUI which belongs to NG_GUIID (ATTENTION, the ID must be given with NG_GUIID!!!) NG_CLOSEGUI (Only for ng_setattrsA()) Only useful with MultiWindow-Support! Closes the GUI which belongs to NG_GUIID (This does not remove the GUI from the list!) NG_CLOSECHILDS (Only for ng_setattrsA()) Only useful with MultiWindow-Support! Like NG_CLOSEGUI for every Window but not for the Main-Window (equal it the Main-Window (1) is a Backdrop-window!) NG_NEWGUI (Only for ng_setattrsA()) Changes the GUI-Description, the new GUI-Descrtiption must be given over witwh NG_NEWDATA NG_BLOCKGUI (Only for ng_setattrsA()) Blocks the window belonging to NG_GUIID NG_UNBLOCKGUI (Only for ng_setattrsA()) Removes the blocking of the window belonging to NG_GUIID NG_RESET (Only for ng_setattrsA()) Resets the complete GUI (All Windows, the Screen ect...) will be closed and reopened again (for example if there are new Prefs...) NG_REFRESHGUI (Only for ng_setattrsA()) Refreshes the window (GUI) belonging to NG_GUIID NG_GADGET (Only for ng_setattrsA() and ng_getattrsA()) PTR to the Gui-Element which should be changed ect... button:=[BUTTON,{action},'text'....] NG_GETGADDATA (Only for ng_getattrsA()) Returns the Gadgetdata from an STR or INTEGER-Gadget, othe Gadgets are ignored, gadgetPTR must be given with NG_GADGET NG_GETGADGET (Only for ng_getattrsA()) Gets a real PTR to a real GadTools-Gadget from an NewGUI gadget-PTR (PTR to a Gui-Element). ATTENTION! Use it only if you exactly know what you`r doing! NG_DISABLE (Only for ng_setattrsA()) Disables the Element given with NG_GADGET, it is equal if the element is a Gadget or a Plugin. NG_ENABLE (Only for ng_setattrsA()) Enables the Gadget again, the NewGUI-Gadget-PTR must be given with NG_GADGET NG_NEWDATA (Only for ng_setattrsA()) Type of Data to change, allowed Tags are: NG_SELECTED NG_VISIBLE NG_LABELS NG_TOP NG_TOTAL NG_SELECTED (Only for ng_setattrsA()) Sets the selected-Item on a ListView-Gadget NG_VISIBLE (Only for ng_setattrsA()) Sets the GTLV_MAKEVISIBLE-Tag at an ListView-Gadget or resets the Visible-Value at an SCROLL-Gadget NG_LABELS (Only for ng_setattrsA()) Changes the Labels at a ListView-gadget NG_TOP (Only for ng_setattrsA()) Sets the TOP-Value from an SCROLL-Gadget NG_TOTAL (Only for ng_setattrsA()) Sets the TOTAL-Value from an SCROLL-Gadget NG_FINDDROPBOX (INTERN) - IMPORTANT! Do not use! only for NG_MOUSEX (INTERN) - internal use! This Tags need NG_MOUSEY (INTERN) - values and constants which aren`t exported outside the module! NG_SHOWGUIDE (Only for ng_setattrsA()) Shows the MAIN-Node from the Online-Help-Guide NG_SAVEPREFS Calls the Procedure which saves the preferences (this procedure will be called for every window!) NG_HIDE Hides all windows and the screen, but the ARexx-Port is open, IMPORTANT! the procedure guimessage() must be called as often as possible to receive and reply ARexx-messages! NG_APPEAR Reopens the window and the screen with the old values and old positions! NG_APPENDGUI -> Old Function Appends a guihandle manually to the gui-list, use this Tag with care and do not rely on it! NG_REMOVEGUI -> Old Function Removes a guihandle from the guilist, handle with care! NG_REMOVECHILDS -> Old Function Removes all child-Windows from the guilist! ATTENTION! Do not use this tag if you are using MultiWindow-Support with NG_NEXTGUI,... !!!! Because this funtion could make some trash! NG_SENDREXX \ Old Functions! NG_RX_RETURNCODE } Please use NG_GETRX and the AFC/Rexxer NG_RX_RESULT / look into the manual for details! NG_DROPPROC PTR to a Procedure which will be called if a dropdown was inside a window but not on a DropBox (like WB App-Windows but only Programminternal!). This Procedure will be called with this syntax: droproc(gui,plug) gui = PTR to the gui where the dropdown was in plug = PTR to the Plugin which produces the Dropdown NG_REDRAW Redraws a plugin safely. This tag needs a PTR to an existant Plugin in the TAG_DATA (Parameter) field. This function calls gtrender (if necessary) or the normal render method, but befor calling this methods the clear_render() methord will be called. 3.3 All Gui-Elements ==================== 3.3.1 Basics in GUI-programing with NewGUI ------------------------------------------ At NewGUI there are no fix coordinates for every element of the GUI (like in GadTools...), the whole GUI is defined in a E-List. This List is sorted in Groups and Elements. There are groups which fills the background (maybe with bitmaps or only with patterns!) or groups which draws a Bevelbox outside the elements in it... Each group could have a lot of sub-groups but the developer should have care of the stack (but no one of my programms had to reset the stack-size even if the gui is large!). The List must have the following arguments: [ELEMENT/GROUP, arguments or more goups...] NOTE: Have care of the Brackets, they are a little bit tricky sometimes and then the Compiler shows an error (for example if you define a group end the last element has a , a the end ( [COLS,[BUTTON...],[BUTTON...],] )! 3.3.2 Groups ------------ ROWS - (active group) All elements (or sub-groups) are ordered under each other (in rows!) EQROWS - (active group) Same as ROWS, but all elements (or subgroups) should have the same size (to look good!) COLS - (active group) Opposit to ROWS, all elements (or subgroups) are ordered side by side (in columns) EQCOLS - (active group) Same as COLS, but all elements (or subgroups) should have the same size! BEVEL - (passive group) Draws a Bevel (Box) outside the next given group (must be a group, elements direct are NOT allowed here!) BEVELR - (passive group) Same as BEVEL, but the Box is drawed recessed! FILLGROUPx - (passive group) Calls for the next given group (must be a group, elements aren`t allowed directly!) the fillhook-procedure. x stands for 1-6! DBEVEL - (passive group) Like BEVEL, only 2 Boxes are drawed (Like a Box at a STRING- Gadget!) DBEVELR - (passive group) Like DBEVEL, only this 2 Boxes are recessed! DROP - (passive group) Initialises a drop-group around the given Element! ATTENTION! Only one Element is allowed! With this group it is possible to add drop-support to NewGUI- Gadgets (like STRINGs). This drop-support is available for the most GUI-elements (but NOT for Buttons, Bars and Groups... this makes no sense!) At this time it isn`t possible to add complex features to one gui-element (such as allocate and enqueue a new node with the data from the plugin to a ListView-Gadget...), but simpler things are possible (like copy a string to a string-gadget, display the plugins-string in a text-gadget or set slider-values...). A drop has the following effects to the gui-elements: INTEGER - The Value in >dnd_num< of the plugin is copied to the gadgets-number CHECK - Is the Value in >dnd_num< is zero then this gadget will be unchecked, else it will be checked (ATTENTION! This isn`t fully tested, it could happen that this won`t work but the function GetTagData() and the value 0 in the Tags-Data field is a bit difficult...) MX - The Number in >dnd_num< says which element from the Gadget is active CYCLE - The Value in >dnd_num< says which field of this gadget will be shown PALETTE - The value says which color-field is active NUM - The Number in >dnd_num< will be displayed in the Gadget SLIDE - The sliders-knob will be set to the value >dnd_num< LISTV - The Value in >dnd_num< says which element of the gadget is currently selected STR - The text/string in >dnd_text< of the plugin will be copied into the gadgets-string TEXT - The text/string in >dnd_text< will be shown in the gadget 3.3.3 Elements -------------- Basic-Variables - - - - - - - - * = This variable isn`t necessary but needed if this feature (like disabling or online-help) should been used proc = Procedure which should been called if this element is selected (ATTENTION! This valiable must be in {}-Brackets!) ...text = Text for this element (... could be left/right or only text!) data = User- (own-)data, this will be a argument for the proc key = Shortcut (hotkey) for this element (Must be in apostrophes, like 'Q' for _Quit!) help = Name of a Node in a AmigaGuide-Text (must be the help- guide given at the Tags!), this Node will be called and displayed if the User pressed the HELP-Key while the Mousepointer is over the element! (Must be a string or a text in apostrophes!) disables = This Variable (BOOL) says that this Element should been disabled at the beginning or not, this could be changed with ng_setattrsA() and NG_DISABLE or NG_ENABLE! list = E-List (typed-List) which must be ended with NIL! execlist = Double-linked-Exec-List (look under exec/lists->lh and exec/nodes->ln!) lefttext = Flag (not a String or a text!) which says that the given text should been displayed on the left side of the gadget instead of the right side! rel = relative Size of this element (minimal Size!) test it out! relx = relative width (minimal Size) rely = relative height (minimal Size) str = E-String (ATTENTION, no text [with apostrophes) allowed here!! only an real E-String or a PTR to an E-String!!!) current = Value saying which element is currently active ( for example in a ListView-Gadget!) or which position is the Slider/Scroller-Knob at the beginning! Elements: - - - - - [BUTTON,action,intext,data*,key*,help*,disabled*] Simple Button which has a fixed size [CHECK,action,righttext,checked,lefttext,data*,key*,help*,disabled*] Boolean Element (box with or without a symbol) checked = Starting-Value (TRUE = set or FALSE = not set!) [INTEGER,action,lefttext,num,rel,data*,key*,help*,disable+*] Input-Element for values (0...9) num = Value or a PTR to a variable for the starting-value [LISTV,action,text,relx,rely,execlist,readbool,selected,current, data*,key*,help*,disabled*] A "simple" ListView-Gadget (scrollable list with a scroll-bar on the right side) readbool = Bool which says that this list is readonly (if TRUE, else the list is clickable too!) selected = Says that the selected element should be marked (with a bar in the back!) [MX,action,righttext,list,lefttext,current,data*,key*,*help,disabled*] Multiple-Element switch (but only one element could be active!), the elements are shown under each other, the active is marked [CYCLE,action,lefttext,elist,current,data*,key*,help*,disabled*] Multiple-Element switch in one button (the elements cycle around, the active is the shown element!) [PALETTE,action,lefttext,depth,relx,rely,current,data*,key*,help*,disable*] Color-select-gadget depth = "Depth" (number of colors) in bitplanes [SCROLL,action,vert,total,top,visible,relsize,data*,key*,help*,disable*] scroller gadget vert = Bool (says that this gadget should be drawn vatikally if TRUE else it is drawn horizontally) top = Above-Value (minimal) total = Maximal-Value (Bottom-Value) visible = Current - Position [SLIDE,action,lefttext,vert,min,max,current,rel,format,data*,key*, help*,disabled*] slider-Gadget (like a scroller only with 2 arrows on the right) vert = Bool (says that this gadget should be drawn vatikally if TRUE else it is drawn horizontally) min = smallest value max = biggest value format = Output Format (like WriteF(), for example '\d[3]') could be a text (in apostrophes) or a String or even NIL if no output is wished! [STR,action,lefttext,str,max,rel,over*,data*,key*,help,*disabled] Input-Element for Text/Strings (A-Z, a-z, 0-9, "!-*#...) max = maximum number of chars which could be given over = overwrite-mode (active if TRUE, else = inactive!) [TEXT,text,lefttext,border,rel] Output for Strings/Text border = Says that a Bevelbox (border) should benn drawed outside the text-variable (TRUE if it should be) [NUM,int,lefttext,border,rel] Output-element for Numbers border = Says that a Bevelbox (border) should benn drawed outside the integer-variable (TRUE if it should be) [SBUTTON,action,intext,data*,key*,help*,disabled*] A button (like BUTTON), but it could been resized in the width! [RBUTTON,action,intext,data*,key*,help*,disabled*] A button (like BUTTON), but it could been resized in the height! [PLUGIN,action,plugin_object,*disabled] Plugin-Object, show under 3.4 (Plugin-Programing) for details! [BAR] Draws a Bar which automatically detects in which direction it should been drawed [BARR] Like BAR, only this Bar comes out (like a Border outside a STRING- Box!) 3.4 Plugin - Programing ======================= Basic things: ------------- The developer of Plugins has some little rules which must normally be followed to prevent bugs/errors or similar and to made the programing of this plugin for "normal" programers (application developers) easier: - The plugins name should be very short but say all it need and shouldn`t had the word _plug (or similar) at the beginning / end - The constructor (the method which initialises the plugin) must have the same name as the plugins-object - The destructors (the method which is called by E if the object/plugin is killed/freed) name must be >end< - The use of private variables from the plugin is forbidden, because they could change from release to release - If plugin-data should be changes, the plugin should provide a function like setattrs or setattrsA (this is not really neccesarry, but recommended) - If plugin-data should returned back a method like getattrs or getattrsA should be provided by the plugin (this is also not needed but recommended) - A constant must be defined with the name of the plugin (the object itselfs or something similar) with the same value as the constant >PLUGIN< in the NewGUI- module (you could do it like that: CONST RAWPLUGIN = PLUGIN) - never ever call the render() or gtrender() methods for other Plugins by yourself (it is allowed for the own render()/gtrender()-methods but not recommented!), use ng_setattrsA() with the tag NG_REDRAW instead!!! 3.4.1 Plugin - Object x = left edge from the Plugin y = top edge from the Plugin xs = Width of the Plugin ys = Height of the Plugin gh = PTR to the guihandle which the plugin belongs to dis = disabled-Flag (TRUE if the Plugin should be disabled) type = Type of Plugin (only necessary for Drag'N'Drop, allowed Tags are: DND_DROPBOX - Elements could only dropped on this Plugin DND_DRAGBOX - Elements could only dragged on this Plugin DND_DRAGDROPBOX - Elements could be dragged on dropped on this Plugin dnd_dest = Was there a sucessful drop, than this field in the Plugin which has made the Drop (and Drag) is a PTR to the DropBox-Plugin dnd_info = Says which elements for Drag'N'Drop are available, this must be: DND_INFO_IMAGE - Bitmap-Image DND_INFO_TEXT - String/Text You could add them (with +) if both are available! dnd_text = PTR to the Text for the Dragging (Attention, if there is a dnd_image too the image will be taken for the Drag!) dnd_textlen = Length of the dnd_text in Chars dnd_image = PTR to the Image for displaying (not for Drag!) dnd_selectimage = PTR to the Image for the Drag (and selected!) dnd_data = Own Data (maybe a PTR to a object ect...) 3.4.2 after_reply() SYNTAX: after_reply() This procedure will be called if ANY (!) message is replyed. Handle this Procedure with care, because it could slow down the system if you use it often and with slow code! You have to check if you are allowed to execute your own code (maybe you define a new variable at the object and set it TRUE (in message_test()) if the message was for you, otherwise you should exit the procedure as fast as possible! ATTENTION! No Arguments or Resultparameter allowed! 3.4.3 clear_render() SYNTAX: clear_render(win) Our Plugin-Space (in the window) should be cleared or a gadget (BOOPSI ect...) should be removed from the window. This Procedure will be called BEFORE render() or gtrender() Parameter: win = PTR to our window 3.4.4 render() SYNTAX: render(ta,x,y,xs,ys,win) This Procedure is the real heart from the Plugin because it draws everything into the window or append a Gadget ect... Parameter: ta = Textattr (rastport/text), you could use it with textlen() to get the length of a string x,y = left-top-edge of our window xs = Width of our Box ys = Height of our Box win = PTR to our window (for example to get the PTR to the rastport for drawing) 3.4.5 gtrender() SYNTAX: gl=gtrender(gl,vis,ta,x,y,xs,ys,win) Special Render-procedure for the use with gadtools-gadgets, if you want to use it, you have to set the isgtgadget() (3.4.8) to the returnvalue TRUE!!) Parameter: gl = PTR to the actual window-Gadgetlist vis = PTR to the Visual-Info from the Screen ta = Textattr (rastport/text), you could use it with textlen() to get the length of a string x,y = left-top-edge of our window xs = Width of our Box ys = Height of our Box win = PTR to our window (for example to get the PTR to the rastport for drawing) Return: gl = PTR to the new Gadget-List (returnvalue from the last CreateGadgetA()-Call!!) IMPORTANT!!!! 3.4.6 will_resize() SYNTAX: ret=will_resize() Returns if our Plugin could resize and if it could be it says to which direction! Return: ret = May be: RESIZEX = only the width could change! RESIZEY = only the height could change! RESIZEXANDY = We are freely resizeable! 3.4.7 min_size() SYNTAX: x,y=min_size(ta,fh) We must return the minimal size which are needed for the plugin. Parameter: ta = Textattr (rastport/text), you could use it with textlen() to get the length of a string fh = Height of the used Font in pixel Return: x = Minimal width in pixel for our Plugin y = Minimal height in pixel for our Plugin 3.4.8 isgtgadget() SYNTAX: ret=isgtgadget() This procedure has (normally) no really function, but it must return TRUE if we want to use gtrender() instead of render() (Necessary for the use of GadTools-Gadgets) Return: ret = TRUE if gtrender() should used or FALSE if render() should used 3.4.9 disable() SYNTAX: disable(disabled) This procedure will be called if our Plugin should be disabled or enabled. We have to modify the value self.dis in our Object and dis- or enable the Plugin-Item (Image, Button ect...) Parameter: disabled = TRUE if our Plugin should be displayed as disabled and no action should happen to it or FALSE if all actions (Drag'N'Drop ect... ) are allowed and our plugin should be displayed normally 3.4.A message_test() SYNTAX: ret=message_text(imsg,win) This procedure must check if the message is for our Plugin (maybe a BUTTONDOWN/BUTTONUP Message or so!) this should be done as fast as possible because the message isn`t replyed this time and if this time a lot of action happens the GUI slows down! Thats the reason why no output (render ect...) should be done here, use after_reply() (3.4.2) or even better use message_action() (3.4.B)! If you whish to use the Drag'N'Drop-Feature, you had to call the procedure self.handlednd(imsg) (look under 3.4.C) Parameter: imsg = Intuimessage (IMPORTANT! Do not change anything in the message or belonging to it, if you had to change something make a copy of it!) you could use it to get the type of message (IDCMP_xxx), but DO NOT REPLY THE MESSAGE!!!! (NewGUI will do that automatically and it will crash if you had already replyed the msg!) win = PTR to our window Return: ret = TRUE if the message was for our Plugin or FALSE if the message was`n for us...! 3.4.B message_action() SYNTAX: ret=message_action(class,qualifier,code,win) Here you could do some output (like drawing or rendering) and you could choose if the action-Procedure from the plugin will be called or not! If you wish to use the Drag'N'Drop-Feature you have to call the procedure self.dnd_xchange() (3.4.E) Parameter: class = Copy of intuimessage.class qualifier = copy of intuimessage.qualifier code = copy of intuimessage.code win = PTR to our window Return: ret = TRUE if the action-Procedure should be called or FALSE if the procedure shouldn`t called at all! 3.4.C handlednd() SYNTAX: ret=handlednd(imsg) This Procedure will be called by message_test() (3.4.A) and should do all Drag'N'Drop-Stuff and check if a drop happened. Parameter: imsg = intuimessage Return: ret = TRUE if a dropdown was successful or FALSE if there wasn't a Drop or if the Drop was outside a Drop-Box or a drop-sensitive window! 3.4.D performdnd() SYNTAX: x,y=performdnd(win) This Procedure does the handling of the Drag until a drop happens or the user releases the mouse-button. There are a procedure with the most important things (including source) unter the name "ng_performdnd", you could change it if you wish or if you need some other things (like GELs-Support...) Parameter: win = PTR to our own Window Return: x,y = Last position from your Mouse-Pointer (if the user releases the Button), you could get it at window.mousex and window.mousey 3.4.E dnd_xchange() SYNTAX: ret=dnd_xchange(plug,called) This procedure is called after a successful drop and should do the transfer of data between the drag- and the dropbox. There are one example called "ng_dnd_xchange" (with Source) there you could have a look into the Basic-Exchange-Functions! This procedure will be called from message_action() (3.4.B) Parameter: plug = PTR to our Plugin (for details look into the ng_dnd_xchange()-Source!) called = Must be TRUE if this procedure was called from another dnd_xchange()-Procedure, else FALSE Return: ret = Return-Code (have a look inside ng_dnd_xchange())!!! 3.7 The modular concept behind NewGUI ===================================== Since Version 3.1 from NewGUI it is totally modular programmed and modified, so that it is very easy to link own code into NewGUI (such as the Drag'N'Drop Functions, the Fill-Function, Prefs-Funktion or Palette-Function...). There`s also an extendet Plugin-Interface (with Drag'N'Drop) which is much more flexible as the one in the Versions before, but the Plugins must be recompiled to work correctly! (I think this is done in a minute or so!) There could now a lot of things be done which couldn't done with the old Interface (like the call of ScrollRaster() ect...)! 3.6 Error-codes =============== ERR_NG_MENU The GadTools-Menu couldn`t be generated or linked to the window ERR_NG_BIG The Gui is too big for the used screen (maybe the user uses a ugly screenmode or there is a design-error in the gui). ERR_NG_VISUAL The Visual-Info from the workscreen couldn`t be opened (maybe the screen is Locked or not open!) ERR_NG_WINOPEN A window couldn't been opened (maybe too few RAM?!) ERR_NG_LIB A needed library couldn't opened (like utility.library, gadtools.library...) ERR_NG_SCREEN The screen couldn't be opened or the used pubscreen isn't available! ERR_NG_MSGPORT Couldn't create the message-port or no more free sigal-bits! ERR_NG_CONTEXT The gadtools-context couldn't been generated (maybe Memory low?!) ERR_NG_GUI Error in the GUI-Description, it couldn`t linked to the window (Maybe design-error...) ERR_NG_SYNTAX Error in the GUI-Description, maybe you have used illegal values or wrong type or variable for a element ERR_NG_FEWARGS One Element in the GUI has too few arguments! ERR_NG_PLUGIN The Plugins-PTR is NIL (maybe not enaugh Memory or a plugin- internal error and the plugin isn`t created correctly!) ERR_NG_CREATEGAD One GadTools-Gadget couldn`t generated (maybe a design-error or too few memory free!) ERR_NG_END Internal-constant, you could use it like TAG_USER (utility- library) to add your own error-Codes! 4. Copyright -============- NewGUI is registered and copyrighted by THE DARK FRONTIER Software- entwicklungen. The Development (1994-1998) and the spreading of this Product is strictly controlled, but it could be that a bug is inside, if this happends at your Computer, feel free to report it to the bugreport-adress at (5) and we will correct the error as fast as it is possible to us. NewGUI is MailWare, that means NewGUI doesn`t cost anything, but the Developer which use it has to write a short E-Mail (or Postcard) to the Adress listed at (5). We handle your Adress and Information only for internal use and we will delete it (if you wish) after a few days. If you wish it, you could register NewGUI, also this doesn`t cost any money (only a Mail or Postcard), this is only for us to see how many people uses NewGUI. And you could take part at the automatically Update-Service (you will get a mail if there are new Versions of NewGUI on the Homepage or in the AmiNet). You are also allowed to use and get BETA-Versions of NewGUI!) 5. About -========- NewGUI was developed by: THE DARK FRONTIER Softwareentwicklungen Grundler Mathias Am Hofgraben 2 67378 Zeiskam Germany Fax : ++49(0)7274-8774 EMail: frontier@starbase.inka.de (Questions to TDF-Products) bugreport@starbase.inka.de (Bug- and Error-messaged) grundler@starbase.inka.de (Personal) register@starbase.inka.de (To register products) WWW : Under Development...