AmigActive 15

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

/ AmigActive 15 / AACD15.ISO / AACD / Programming / BGUI / AutoDoc / RexxBGUI.doc < prev next >

Wrap

Text File | 2000-05-09 | 22.8 KB | 640 lines

rexxbgui.library version 4.0 Date: June 24, 1999 Copyright © Jilles Tjoelker 1999 New in V4.0: * Version number bumped because of new functions. * Added image buttons. * Added a simple file requester function. * Added a function to set up listview control with the arrow keys. * Bug fixed: I once disabled CYC_Active but forgot to enable it again. New in V3.0: * Version number bumped because of new functions. * Added separators and cycle gadgets. * Added version testing functions bguirexxversion() and bguiversion(). New in V2.0: * Version number bumped because of new functions. * Added menus. * Added progress bar (suggested by Ingo Musquinier) and indicator. * Bug fixed: bguiwindow() did not get the argument count correctly. This caused problems, because ARexx does not clear extra argument slots but instead leaves in them what values happen to be contained in them from previous function calls. New in V1.1: * New functions: bguiwinbusy(), bguiwinready(), bguipages(), bguimx(), bguiactivategadget(), bguilist(), bguiaddcondit(), bguilistvaddentry(), bguilistvcommand(), bguilistvreplacesel() * New argument for bgui[hv]group(), equal, to force equal width or height of the objects in the group * New argument for bguiwindow(), pos, to open the window on another position than centred on the screen * Some nonfunctional tags removed * New tags: BT_#?, PAGE_#?, MX_#?, TAG_IGNORE * Better documentation * Bug fixed: the library could be flushed from memory when a bguiopen() was still outstanding. * A control-C break is now accepted immediately in bguiwinwaitevent() and bguiwait() and passed to ARexx. * Bug fixed: BGUI 41.10 took the command name, which is always equal to "", for the prefs filename. Fixed by temporarily setting the pr_Cli pointer to zero. Look in the example scripts for more information. General ARexx limitation: functions can only have up to 15 arguments. ESCAPE SEQUENCES Escape sequences can be used in most texts, including labels, frame titles info object contents and listview entries. Frame titles may have shadow. Listview entries and labels within objects can be text on background or filltext on fill; when you change the colours it cannot be restored. ESC='1b'x or just use the Esc key to put it in a string constant. ESC||ESC no operation; used to separate sequences ending in a digit from normal digits. ESC'u' underlined on (do not use for indicating a hotkey) ESC'b' bold on ESC'i' italics on ESC'z' underscore on (can indicate the hotkey for a gadget, only visual though, use BT_Key to make it work) ESC'n' normal text ESC'd'n set DrawInfo pen #n (2=text, 3=shine, 4=shadow, 5=selected gadget fill, 6=text on fill, 7=background, 8=important text) ESC'p'n set colour #n ESC'D'n set DrawInfo pen #n as background ESC'P'n set colour #n as background ESC's' shadow on (additionally use ESC'd3') ESC'-'ch turn something off (ch=u/b/i/s/z) ESC'c' centre this and the following lines ESC'r' right-justify this and the following lines ESC'l' left-justify this and the following lines '0a'x new line. This does not work for listview entries and frame titles. FUNCTIONS success=bguiopen([taskname],[noerrorifopenfail]) This function opens bgui.library. Version 41 is required. taskname indicates the name of the prefs file, default "ARexx". Predefined are: ID.WIN(CLOSE|NOMORE|INACTIVE|ACTIVE). If this function has not yet been called, all functions starting with 'bgui' cause "Error return from function". x=bguiwait() Wait for most events; Control-C is passed trough to ARexx (signal on break_c). id=bguiwinevent(winobj,[destvar]) This function does not wait for events. id=bguiwaitwinevent(winobj,[destvar]) This function is much more efficient than the bguiwinevent()/bguiwait() combination. success=bguiwinopen(winobj) This function must be used to open a window. When a window object is created, it does not open automatically, unlike some other GUI engines' behaviour. This enables you to do things like bguiwintabcycleorder() in time. x=bguiwinclose(winobj) success=bguiwinbusy(winobj) Use this function to set a busy pointer and zero-size requester that blocks input on a window. It nests, i.e. the window will not be unblocked until one bguiwinready() has been done for each bguiwinbusy() executed. success=bguiwinready(winobj) obj=bguiwindow(title,mastergroup,[scalew],[scaleh],[refwin],[scrname],[pos],[menu]) scale[wh]: 0% = minimum size, 100% = full screen Precede scalew and/or scaleh with a minus sign to lock the dimension. Locking both removes the size gadget. refwin: the new window object will open on the same screen as refwin pos 'S' centre on screen 'M' centre on mouse pointer 'T' top-left of the screen 'W' centre on window 'B' l t w h position in screen (pixel) coordinates 'R' l t w h centre window on this box '*' (anywhere) do not activate window upon opening (doesn't really fit here but this saves arguments) menu: concatenate bguimenu() results info=bguilayout(tag,value,[tag],[value],...) Concatenate the return value of this to an object. It does not work for VarSpace members. info=bguivarspace(weight) A weight controlled spacing in a group; 1<weight<1023 bguilayout() cannot be used on this. obj=bgui[hv]group(objects,[spacing],[offset],[title],[equal]) Double use of objects or forgotten '||' is caught -> error 12. spacing/offset -1 narrow -2 normal (default, unlike groupclass itself) -3 wide offset 'F' frame (required for a title) equal 'W' all objects the same width 'H' all objects the same height 'S' all objects the same width and height obj=bguipages(name,objects) This function only creates OBJ.name, not ID.name. Do not set PAGE_Active values which are out of range! The usage of pages increases the number of objects that can be in a window and therefore object creation time. The BGUI prefs program is an example of this! obj=bguibutton(name,label) As other "real" gadget creation functions, this one sets both ID.name (compare with bguiwinevent() or bguiwinwaitevent() result) and OBJ.name (for bguiget() and similar functions). Prefix the keyboard shortcut with '_' in label. This also applies to other gadgets. Take care that all shortcuts are different! BGUI does not check this (MUI doesn't either). This type of bug is present in much software. obj=bguitoggle(name,label,[state]) obj=bguicheckbox(name,[label],[state]) obj=bguiibutton(name,itype,idata,[label],[lplace]) Image button. itype 'B' BGUI built-in 'I' icon 'M' bitmap image 'V' vector (not yet implemented) '-' (anywhere) no frame '*' (anywhere) no spacing between frame and image idata (itype='B') number, 'F'=getfile, 'P'=popup, 'D'=getpath (itype='I') filename without .info (itype='M') one or two results of bguiimage() (normal & selected) (itype='V') string lplace 'L' left (default) 'R' right 'A' above 'B' below obj=bguiinfo(name,[label],contents) Non-clickable information object. obj=bguistring(name,[label],[contents],maxchars) obj=bguiinteger(name,[label],[contents],[maxchars],[min],[max]) It is not guaranteed, that min<=bguiget(int,STRINGA_LongVal)<=max. obj=bguilistview(name,[label],[stem],[type],[ncolumns]) type 'R' read-only 'S' select (default) 'D' drag'n'drop In multi-column listview entries, the columns are separated by a tab character. Attributes set with escape sequences do not continue from one column to the next. Optionally, you can append column weights to ncolumns, e.g. '3 10 45 45' to create one small column and two wider ones. obj=bguimx(name,[label],stem,[type]) type 'R' radio buttons (default) 'T' tabs 'U' upside down tabs The number of entries is limited to 63 (it must fit on the screen, so it's not much of a limitation) obj=bguicycle(name,[label],stem,[type]) type 'P' force popup regardless of BGUI prefs 'N' popup if enabled in BGUI prefs (default) Pop on active setting is taken from BGUI prefs The number of entries is limited to 63 (BGUI popup cycles truncate a list that doesn't fit on the screen, so it's not much of a limitation) obj=bguiprogress(name,[label],min,max,[format],[type]) format: C-style format string for text in the gadget. Use %ld as a placeholder for the number. Other percent signs must be doubled. Other possibilities: "%03ld" forces a field size of three digits and pads on the left with zeroes. "%lD" formats the number according to the language selected and works only if locale.library is installed. "%lx" creates a hexadecimal format. BGUI 41.10 draws the text in the last colour used (if done=max then the progress bar colour else the background colour) because of a bug, therefore the format string should begin with ESC'd2'ESC||ESC (not necessarily 2). ESC'D'n is also recommended if the text should be always visible on two colour screens or screens with strange pens (e.g. non-newlook (no 3D look)). If you don't want the problems of a format string, then you can use bguiaddmap() to put the number in an indicator next to the progress bar. type 'H' horizontal 'V' vertical The amount done is set to zero or the minimum. obj=bguiindicator(name,[label],min,max,[level],[justify],[format]) Textual level indication gadget. justify 'L' left (default) 'C' centre 'R' right format: the same thing as in bguiprogress() except that setting colours is not necessary and that it has a default "%ld". obj=bguihseparator([title]) Horizontal separator line with optional title. Use in vertical groups only. This function does not take a name argument because modifying the object is not supported by RexxBGUI and not useful anyway. obj=bguivseparator() Vertical separator line. Use in horizontal groups only. This function does not take a name argument because modifying the object is not supported by RexxBGUI and not useful anyway. res=bguiget(obj,attr) Error descriptions here: "Invalid keyword" if you supplied an attribute that RexxBGUI does not know - see "tags" further on in this file for which attributes are available. "Error return from function" if the obj parameter was not OK or if the object did not understand the attribute, for example an attribute of another gadget class or one that is not gettable; "Wrong number of arguments" if rm->rm_Action & 0xF is not 2 or if rm_Args[1] or rm_Args[2] is equal to zero. x=bguiset(obj,[refwin],tag,value,[tag],[value],...) refwin: window object in which the gadget is located; necessary if you want visual updating. Specifying another window causes strange results... If you need to set more than 6 tags, split it out over multiple calls and omit refwin in all possibly except the last. Put at least one attribute causing visual update in the last call, if you want any update. gad=bguireq(text,gadgets,[title],[refwin],[scrname]) RequestChoice/rtEZRequest() like requester. Use '|' to separate the gadgets. An asterisk adds return as a shortcut for the button it stands before and escape for the last one. Underscores can be used to prefix keyboard shortcuts. The window specified by refwin will automatically get a busypointer. Title defaults to refwin's title, or "BGUI Request" or its localized equivalent if wndobj is not given. Scrname does not work. gad: 1 for the first, 2 for the second, etc. and 0 for the last gadget. success=bguiaddmap(srcobj,dstobj,sattr,dattr) This function connects two objects so srcobj will update dstobj's dattr when its sattr changes. This happens even without bguiwinevent(). Example usages: Listview with connected string gadget: call bguiaddmap(obj.listv,obj.str,LISTV_Entry,STRINGA_TextVal) Listview to select a page (#of listview entries must be #of pages!!!): call bguiaddmap(obj.listv,obj.pages,LISTV_EntryNumber,PAGE_Active) The number of attributes that can cause notification (sattr) or be updated (dattr) is more limited than the number that can be used with bguiget() or bguiset(). If notification does not work, you'll have to fall back to the latter mechanism. There is no "initial" notification. Notification of LGO attributes may cause a crash. Using bguiset() is safer. success=bguiaddcondit(srcobj,dstobj,iftag,ifval,thtag,thval,eltag,elval) This function connects two objects so srcobj will update dstobj depending on its ifattr. This is more or less equivalent to doing this when srcobj's iftag changes: IF bguiget(srcobj,iftag)=ifval THEN CALL bguiset(dstobj,thtag,thval), ELSE CALL bguiset(dstobj,eltag,elval) This happens even without bguiwinevent(). See also bguiaddmap(). Integer tags only. Always test boolean tags for 0 and never for 1. Example usage: Yes/No setting that makes a choice impossible: call bguiaddcondit(obj.check,obj.mx,GA_Selected,0,MX_EnableButton,0, ,MX_DisableButton,0) MX_DisableButton,n will never change MX_Active. You have to check separately if the selection is still possible. If you init the checkbox to on, the first MX button will not be enabled initially. If you init the checkbox to off and set it to on after this call, it will be OK. count=bguilistvgetentries(listvobj,stemname,[type]) type 'A' all 'S' selected only success=bguilistvaddentry(listvobj,[refwin],entry,[where],[flags]) where 'H' head 'T' tail 'S' sorted number add before entry n flags 'S' select 'M' multiselect '+' make visible by scrolling list if necessary '-' do not make visible 'S' or 'M' makes visible automatically unless disabled with '-' rc=bguilistvcommand(listvobj,[refwin],command) command 'clear' delete all entries 'refresh' refresh listview and scroller 'sort' 'redraw' redraw all entries only 'remselected' also selects new entry success=bguilistvreplacesel(listvobj,[refwin],new) Use this function to replace the first selected entry of a listview by another. If no entry is selected, a new one is added and selected. success=bguiwintabcycleorder(winobj,objects) RexxBGUI can only check the validity of the objects array to a limited extent: if a multiple of four spaces is intermixed wrong object pointers are used and a crash can be expected if tab is pressed in the first gadget. image=bguiimage(left,top,width,height,depth,data,planepick,planeonoff) Creates an Image structure and returns the pointer. Use this for the idata parameter of bguiibutton() if itype='M'. Create these function calls with the MakeImage program. nm=bguimenu(type,[label],[commkey],[flags],[mutualexclude],[id]) Creates a NewMenu structure. Concatenate some of these and pass the result to bguiwindow(). If IDs (bguiwinevent()) are to be shared between gadgets and menuitems, create the gadgets first. Do not give a checkbox and a CHECKIT|TOGGLE item the same ID as it will be impossible to distinguish type '1' menu title '2' item '3' subitem Omitting label gives a separator bar (automatically disabled). commkey: RAmiga-... shortcut flags 'DISABLED' 'CHECKIT' can be checked (not unchecked) 'CHECKED' has checkmark 'TOGGLE' specify CHECKIT too mutualexclude: selecting this CHECKIT item deselects these items (bit #x means item #x) id: may be either a number or a name of a variable number: selecting the item generates this ID variable: generate a new ID and store it in the variable Therefore you can write bguimenu(...,id.quit) and it will automatically share its ID with a gadget's, if it is present. Example: menu=bguimenu(1,'Project')||, bguimenu(2,'About...','?',,,id.about)||, bguimenu(2)||, bguimenu(2,'Quit','Q',,,id.quit)||, bguimenu(1,'Testing')||, bguimenu(2,'Have your cake',,'CHECKIT CHECKED','10'b,id.hyc)||, bguimenu(2,'Eat it too',,'CHECKIT','01'b,id.eit)||, bguimenu(2,'On or off???',,'CHECKIT TOGGLE',,id.ooo)||, bguimenu(2)||, bguimenu(2,'Subitems')||, bguimenu(3,'Subitem #1','1',,,id.sub1)||, bguimenu(3,'Subitem #2','2',,,id.sub2)||, bguimenu(3,'Subitem #3','3','DISABLED',,id.sub3) success=bguiwindisablemenu(winobj,id,state) success=bguiwincheckitem(winobj,id,state) rc=bguiwinmenudisabled(winobj,id) rc 1 disabled 0 enabled -1 unknown menu/no menus at all attached to window rc=bguiwinitemchecked(winobj,id) rc 1 checked 0 not checked -1 unknown menu/no menus at all attached to window success=bguiactivategadget(gadget,refwin) This call may fail, although that's usually not a severe problem... RexxBGUI can only check the validity of the objects to a limited extent. x=bguiclose() This MUST be called before exiting the script. success=bguireadentries(filename,stemname) When using READLN(), EOF cannot be distinguished from an empty line. Therefore this function is present. It reads lines from a file to a stem in a format suitable for the listview gadget. stemname=bguilist(stemname,entry0,[entry1],...) This function allows you to place small lists (<=14 entries) for listviews directly in the gadget creation function, a bit like in E [e0,e1,...]. It sets stemname.COUNT and stemname.x (0<=x<stemname.COUNT) Example: ... bguilistview('switcher',,bguilist('pnames','Single-Select','Multi-Select'))||, ... drop pnames. /* not really necessary */ x=bguilistvcontrol([listvobj],[winobj],[arrows_id],[enter_id]) This function will cause the arrow keys up and down to control the the listview. They do only in the window specified. You can receive events for the arrow keys and for return and enter keys. You can specify either a number or a variable name which will receive a newly generated ID. Leaving out all arguments turns off this feature. If an argument is left out, (but there are arguments at all), that setting is not changed. Never ever set winobj if listvobj is invalid. Initially, winobj is zero and the other values are undefined. path=bguifilereq([path],[title],[winobj],[flags],[patvar]) Subsequent calls will remember the path, the pattern and the requester's position and size, but not the title, the window object pointer and the flags. winobj: window object pointer. The requester will open on the same screen and the window will be locked like bguiwinbusy(). flags 'DOSAVEMODE' 'DOPATTERNS' pattern gadget; a pattern may be used without it 'DRAWERSONLY' 'FILTERDRAWERS' 'REJECTICONS' patvar: name of a variable that contains the pattern. When the requester is closed, the possibly changed pattern is stored in it. If the variable does not exist, the argument is used literally as a pattern, but the changed pattern is not stored in any variable. If the requester was cancelled, the function returns the empty string, else it returns the path (the drawer and file concatenated with a slash in between if necessary). x=bguierror(code) This function causes an ARexx error, e.g. bguierror(12) causes "Error return from function". result=bguirexxversion([version],[revision]) Syntax #1: available=bguirexxversion(version,[revision]) Syntax #2: version=bguirexxversion() /* could return '3.0' */ result=bguiversion([version],[revision]) Syntax #1: available=bguiversion(version,[revision]) Syntax #2: version=bguiversion() /* could return '41.8' */ TAGS: General information Types: INT=integer, may be boolean (0 means false, anything else means true) STRING=string OBJECT=4-byte pointer Applicability: ISGNU I=Init (not applicable for RexxBGUI) S=Set (bguiset()) G=Get (bguiget()) N=Notify (bguiaddmap() sattr/bguiaddcondit() ifattr) U=Update (bguiaddmap() dattr/bguiaddcondit() thattr/elattr) -=not possible ?=not known to me, try it WINDOW_#? TAGS WINDOW_Window OBJECT --G-- INFO_#? TAGS INFO_TextFormat STRING IS--U INFO_MinLines INT INFO_FixTextWidth INT STRINGA_#? TAGS STRINGA_TextVal STRING ISGNU makes string gadget STRINGA_LongVal INT ISGNU makes integer gadget STRINGA_MaxChars INT I-?-- STRINGA_BufferPos INT IS??? cursor position STRINGA_DispPos INT IS??? first char visible LGO_#? TAGS LGO_FixWidth INT LGO_FixHeight INT LGO_Weight INT LGO_FixMinWidth INT LGO_FixMinHeight INT LGO_Align INT LGO_NoAlign INT LGO_FixAspect INT 65536*x+y 41.8 only LGO_Visible INT LISTV_#? TAGS LISTV_Top INT ISG-U LISTV_ReadOnly INT ISG?? S/U will not change frame LISTV_MultiSelect INT IS?-U LISTV_Select INT -S--U LISTV_MakeVisible INT -S--U LISTV_Entry STRING ---N- LISTV_EntryNumber INT ---N- LISTV_LastClicked STRING --G-- LISTV_LastClickedNum INT --G-- LISTV_NewPosition INT ---N- LISTV_NumEntries INT --G-- LISTV_MinEntriesShown INT ISG?? LISTV_SelectMulti INT -S--U LISTV_SelectNotVisible INT -S--U LISTV_SelectMultiNotVisible INT -S--U LISTV_MultiSelectNoShift INT IS--U LISTV_Deselect INT -S--U LISTV_DropSpot INT --G-- LISTV_ShowDropSpot INT IS--- LISTV_Columns INT I-G-- LISTV_DragColumns INT ISG-U LISTV_Titles STRING I-G-U 41.8 Enforcer hits LISTV_Titles! OBJECT ISG-U static string problem LISTV_PreClear INT ISG-- LISTV_LastColumn INT --G-- GA_#? TAGS GA_Disabled INT IS?-U GA_Selected INT ISGNU toggles/checkboxes only BT_#? TAGS BT_LabelClick INT IS--- BT_DragObject INT ISG-- BT_DropObject INT ISG-- BT_Key STRING ISG-- set after creating window object only BT_RawKey INT ISG-- set after creating window object only BT_Qualifier INT ISG-- set after creating window object only PAGE_#? TAGS PAGE_Active INT ISG?U MX_#? TAGS MX_Active INT ISGNU MX_DisableButton INT IS--U MX_EnableButton INT IS--U CYC_#? TAGS CYC_Active INT ISGNU PROGRESS_#? TAGS PROGRESS_Min INT IS--- PROGRESS_Max INT IS--- PROGRESS_Done INT ISGNU INDIC_#? TAGS INDIC_Level INT IS--U TAG_#? TAGS TAG_IGNORE INT IS--U does nothing!