home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 42 / Amiga Format AFCD42 (Issue 126, Aug 1999).iso / -serious- / programming / arexx / rexxbgui / rexxbgui.doc < prev    next >
Encoding:
Text File  |  1999-05-14  |  14.5 KB  |  425 lines
  1. rexxbgui.library version 1.1
  2. Date: April 23, 1999
  3. Copyright © Jilles Tjoelker 1999
  4.  
  5. New in V1.1:
  6. * New functions: bguiwinbusy(), bguiwinready(), bguipages(), bguimx(),
  7.   bguiactivategadget(), bguilist(), bguiaddcondit(), bguilistvaddentry(),
  8.   bguilistvcommand(), bguilistvreplacesel()
  9. * New argument for bgui[hv]group(), equal, to force equal width or height
  10.   of the objects in the group
  11. * New argument for bguiwindow(), pos, to open the window at a different
  12.   place than centred on the screen.
  13. * Some nonfunctional tags removed
  14. * New tags: BT_#?, PAGE_#?, MX_#?, TAG_IGNORE
  15. * Better documentation
  16. * Bug fixed: the library could be flushed from memory when a bguiopen() was
  17.   still outstanding.
  18. * A control-C break is now accepted immediately in bguiwinwaitevent() and
  19.   bguiwait() and passed to ARexx.
  20. * Bug fixed: BGUI 41.10 took the command name, which is always equal to "",
  21.   for the prefs filename. Fixed by temporarily setting the pr_Cli pointer to
  22.   zero.
  23.  
  24. Look in the example scripts for more information.
  25. General ARexx limitation: functions can only have up to 15 arguments.
  26.  
  27. ESCAPE SEQUENCES
  29. Escape sequences can be used in most texts, including labels, frame titles
  30. info object contents and listview entries. Frame titles may have shadow.
  31. Listview entries and labels within objects can be text on background or
  32. filltext on fill; when you change the colours it cannot be restored.
  33. ESC='1b'x or just use the Esc key to put it in a string constant.
  34.  
  35. ESC||ESC no operation; used to separate sequences ending in a digit
  36.          from normal digits.
  37. ESC'u'   underlined on
  38. ESC'b'   bold on
  39. ESC'i'   italics on
  40. ESC'n'   normal text
  41. ESC'd'n  set DrawInfo pen #n (2=text, 3=shine, 4=shadow, 5=selected-gadget
  42.          fill, 6=text on fill, 7=background, 8=important text)
  43. ESC'p'n  set colour #n
  44. ESC'D'n  set DrawInfo pen #n as background
  45. ESC'P'n  set colour #n as background
  46. ESC's'   shadow on (additionally use ESC'd3')
  47. ESC'-'ch turn something off (ch=u/b/i/s)
  48. ESC'c'   centre this and the following lines
  49. ESC'r'   right-justify this and the following lines
  50. ESC'l'   left-justify this and the following lines
  51. '0a'x    new line. This does not work for listview entries and frame titles.
  52.  
  53. FUNCTIONS
  55.  
  56. success=bguiopen([taskname],[noerrorifopenfail])
  58. This function opens bgui.library. Version 41 is required.
  59. taskname indicates the name of the prefs file, default "ARexx".
  60. Predefined are: ID.WIN(CLOSE|NOMORE|INACTIVE|ACTIVE).
  61. If this function has not yet been called, all functions starting with
  62. 'bgui' cause "Error return from function".
  63.  
  64. x=bguiwait()
  66. Wait for most events; Control-C is passed trough to ARexx
  67. (signal on break_c).
  68.  
  69. id=bguiwinevent(winobj,[destvar])
  71. This function does not wait for events.
  72.  
  73. id=bguiwaitwinevent(winobj,[destvar])
  75. This function is much more efficient than the bguiwinevent()/bguiwait()
  76. combination.
  77.  
  78. success=bguiwinopen(winobj)
  80. This function must be used to open a window. When a window object is created,
  81. it does not open automatically, unlike some other GUI engines' behaviour.
  82. This enables you to do things like bguiwintabcycleorder() in time.
  83.  
  84. x=bguiwinclose(winobj)
  86.  
  87. success=bguiwinbusy(winobj)
  89. Use this function to set a busy pointer and zero-size requester that blocks
  90. input on a window. It nests, i.e. the window will not be unblocked until
  91. one bguiwinready() has been done for each bguiwinbusy() executed.
  92.  
  93. success=bguiwinready(winobj)
  95.  
  96. obj=bguiwindow(title,mastergroup,[scalew],[scaleh],[refwin],[scrname],[pos])
  98. scale[wh]: 0% = minimum size, 100% = full screen
  99. Precede scalew and/or scaleh with a minus sign to lock the dimension.
  100. Locking both removes the size gadget.
  101. refwin: the new window object will open on the same screen as refwin
  102. pos 'S' centre on screen
  103.     'M' centre on mouse pointer
  104.     'T' top-left of the screen
  105.     'W' centre on window
  106.     'B' l t w h position in screen (pixel) coordinates
  107.     'R' l t w h centre window on this box
  108.  
  109. info=bguilayout(tag,value,[tag],[value],...)
  111. Concatenate the return value of this to an object. It does not work for
  112. VarSpace members.
  113.  
  114. info=bguivarspace(weight)
  116. A weight controlled spacing in a group; 1<weight<1023
  117. bguilayout() cannot be used on this.
  118.  
  119. obj=bgui[hv]group(objects,[spacing],[offset],[title],[equal])
  121. Double use of objects or forgotten '||' is caught -> error 12.
  122. spacing/offset -1 narrow
  123.                -2 normal
  124.                -3 wide
  125. offset 'F' frame (required for a title)
  126. equal 'W' all objects the same width
  127.       'H' all objects the same height
  128.       'S' all objects the same width and height
  129.  
  130. obj=bguipages(name,objects)
  132. This function only creates OBJ.name, not ID.name.
  133. Do not set PAGE_Active values which are out of range!
  134. The usage of pages increases the number of objects that can be in a window
  135. and therefore object creation time. The BGUI prefs program is an example of
  136. this!
  137.  
  138. obj=bguibutton(name,label)
  140. As other "real" gadget creation functions, this one sets both ID.name
  141. (compare with bguiwinevent() or bguiwinwaitevent() result) and OBJ.name (for
  142. bguiget() and similar functions).
  143.  
  144. Prefix the keyboard shortcut with '_' in label. This also applies to other
  145. gadgets.
  146.  
  147. obj=bguitoggle(name,label,[state])
  149.  
  150. obj=bguicheckbox(name,[label],[state])
  152.  
  153. obj=bguiinfo(name,[label],contents)
  155. Non-clickable information object.
  156.  
  157. obj=bguistring(name,[label],[contents],maxchars)
  159.  
  160. obj=bguiinteger(name,[label],[contents],[maxchars],[min],[max])
  162. It is not guaranteed, that min<=bguiget(int,STRINGA_LongVal)<=max.
  163.  
  164. obj=bguilistview(name,[label],[stem],[type],[ncolumns])
  166. type 'R' read-only
  167.      'S' select (default)
  168.      'D' drag'n'drop
  169. In multi-column listview entries, the columns are separated by a tab
  170. character. Attributes set with escape sequences do not continue from
  171. one column to the next.
  172. Optionally, you can append column weights to ncolumns, e.g. '3 10 45 45' to
  173. create one small column and two wider ones.
  174.  
  175. obj=bguimx(name,[label],stem,[type])
  177. type 'R' radio buttons (default)
  178.      'T' tabs
  179.      'U' upside down tabs
  180.  
  181. res=bguiget(obj,attr)
  183. Error descriptions here:
  184. "Invalid keyword" if you supplied an attribute that RexxBGUI does not know -
  185. see "tags" further on in this file for which attributes are available.
  186. "Error return from function" if the obj parameter was not OK or if the
  187. object did not understand the attribute, for example an attribute of another
  188. gadget class or one that is not gettable;
  189. "Wrong number of arguments" if rm->rm_Action & 0xF is not 2 or if
  190. rm_Args[1] or rm_Args[2] is equal to zero.
  191.  
  192. x=bguiset(obj,[refwin],tag,value,[tag],[value],...)
  194. refwin: window object in which the gadget is located; necessary if you want
  195. visual updating. Specifying another window causes strange results...
  196. If you need to set more than 6 tags, split it out over multiple calls and
  197. omit refwin in all possibly except the last. Put at least one attribute
  198. causing visual update in the last call, if you want any update.
  199.  
  200. gad=bguireq(text,gadgets,[title],[refwin],[scrname])
  202. RequestChoice/rtEZRequest() like requester. Use '|' to separate the gadgets.
  203. An asterisk adds return as a shortcut for the button it stands before and
  204. escape for the last one. Underscores can be used to prefix keyboard shortcuts.
  205. The window specified by refwin will automatically get a busypointer.
  206. Title defaults to refwin's title, or "BGUI Request" or its localized
  207. equivalent if wndobj is not given.
  208. Scrname does not work.
  209. gad: 1 for the first, 2 for the second, etc. and 0 for the last gadget.
  210.  
  211. success=bguiaddmap(srcobj,dstobj,sattr,dattr)
  213. This function connects two objects so srcobj will update dstobj's dattr
  214. when its sattr changes. This happens even without bguiwinevent().
  215.  
  216. Example usages:
  217. Listview with connected string gadget:
  218. call bguiaddmap(obj.listv,obj.str,LISTV_Entry,STRINGA_TextVal)
  219. Listview to select a page (#of listview entries must be #of pages!!!):
  220. call bguiaddmap(obj.listv,obj.pages,LISTV_EntryNumber,PAGE_Active)
  221.  
  222. The number of attributes that can cause notification (sattr) or be updated
  223. (dattr) is more limited than the number that can be used with bguiget() or
  224. bguiset(). If notification does not work, you'll have to fall back to the
  225. latter mechanism.
  226.  
  227. There is no "initial" notification.
  228.  
  229. Notification of LGO attributes may cause a crash. Using bguiset() is safer.
  230.  
  231. success=bguiaddcondit(srcobj,dstobj,iftag,ifval,thtag,thval,eltag,elval)
  233. This function connects two objects so srcobj will update dstobj depending
  234. on its ifattr. This is more or less equivalent to doing this when srcobj's
  235. iftag changes:
  236. IF bguiget(srcobj,iftag)=ifval THEN CALL bguiset(dstobj,thtag,thval),
  237.   ELSE CALL bguiset(dstobj,eltag,elval)
  238. This happens even without bguiwinevent(). See also bguiaddmap().
  239.  
  240. Integer tags only.
  241.  
  242. Always test boolean tags for 0 and never for 1.
  243.  
  244. Example usage:
  245. Yes/No setting that makes a choice impossible:
  246. call bguiaddcondit(obj.check,obj.mx,GA_Selected,0,MX_EnableButton,0,
  247. ,MX_DisableButton,0)
  248.  
  249. MX_DisableButton,n will never change MX_Active. You have to check separately
  250. if the selection is still possible.
  251.  
  252. If you init the checkbox to on, the first MX button will not be enabled
  253. initially. If you init the checkbox to off and set it to on after this call,
  254. it will be OK.
  255.  
  256. count=bguilistvgetentries(listvobj,stemname,[type])
  258. type 'A' all
  259.      'S' selected only
  260.  
  261. success=bguilistvaddentry(listvobj,[refwin],entry,[where],[flags])
  263. where 'H' head
  264.       'T' tail
  265.       'S' sorted
  266.       number add before entry n
  267. flags 'S' select
  268.       'M' multiselect
  269.       '+' make visible by scrolling list if necessary
  270.       '-' do not make visible
  271. 'S' or 'M' makes visible automatically unless disabled with '-'
  272.  
  273. rc=bguilistvcommand(listvobj,[refwin],command)
  275. command 'clear' delete all entries
  276.         'refresh' refresh listview and scroller
  277.         'sort'
  278.         'redraw' redraw all entries only
  279.         'remselected' single-select only; also selects new entry
  280.  
  281. success=bguilistvreplacesel(listvobj,[refwin],new)
  283. Use this function to replace the first selected entry of a listview by another.
  284. If no entry is selected, a new one is added and selected.
  285.  
  286. success=bguiwintabcycleorder(winobj,objects)
  288. RexxBGUI can only check the validity of the objects array to a limited
  289. extent: if a multiple of four spaces is intermixed wrong object pointers
  290. are used and a crash can be expected if tab is pressed in the first gadget.
  291.  
  292. success=bguiactivategadget(gadget,refwin)
  294. This call may fail, although that's usually not a severe problem...
  295. RexxBGUI can only check the validity of the objects to a limited extent.
  296.  
  297. x=bguiclose()
  299. This must be called before exiting the script.
  300.  
  301. success=bguireadentries(filename,stemname)
  303. When using READLN(), EOF cannot be distinguished from an empty line.
  304. Therefore this function is present. It reads lines from a file to a stem
  305. in a format suitable for the listview gadget.
  306.  
  307. stemname=bguilist(stemname,entry0,[entry1],...)
  309. This function allows you to place small lists (<=14 entries) for listviews
  310. directly in the gadget creation function, a bit like in E [e0,e1,...].
  311. It sets stemname.COUNT and stemname.x (0<=x<stemname.COUNT)
  312.  
  313. Example:
  314. ...
  315. bguilistview('switcher',,bguilist('pnames','Single-Select','Multi-Select'))||,
  316. ...
  317. drop pnames. /* not really necessary */
  318.  
  319. x=bguierror(code)
  321. This function causes an ARexx error, e.g. bguierror(12) causes "Error return
  322. from function".
  323.  
  324. TAGS: General information
  326. Types:
  327. INT=integer, may be boolean (0 means false, anything else means true)
  328. STRING=string
  329. OBJECT=4-byte pointer
  330.  
  331. Applicability: ISGNU
  332. I=Init (not applicable for RexxBGUI)
  333. S=Set (bguiset())
  334. G=Get (bguiget())
  335. N=Notify (bguiaddmap() sattr/bguiaddcondit() ifattr)
  336. U=Update (bguiaddmap() dattr/bguiaddcondit() thattr/elattr)
  337. -=not possible
  338. ?=not known to me, try it
  339.  
  340. WINDOW_#? TAGS
  341.  
  342. WINDOW_Window                 OBJECT --G--
  343.  
  344. INFO_#? TAGS
  345.  
  346. INFO_TextFormat               STRING IS--U
  347. INFO_MinLines                 INT
  348. INFO_FixTextWidth             INT
  349.  
  350. STRINGA_#? TAGS
  351.  
  352. STRINGA_TextVal               STRING ISGNU makes string gadget
  353. STRINGA_LongVal               INT    ISGNU makes integer gadget
  354. STRINGA_MaxChars              INT    I-?--
  355. STRINGA_BufferPos             INT    IS??? cursor position
  356. STRINGA_DispPos               INT    IS??? first char visible
  357.  
  358. LGO_#? TAGS
  359.  
  360. LGO_FixWidth                  INT
  361. LGO_FixHeight                 INT
  362. LGO_Weight                    INT
  363. LGO_FixMinWidth               INT
  364. LGO_FixMinHeight              INT
  365. LGO_Align                     INT
  366. LGO_NoAlign                   INT
  367. LGO_FixAspect                 INT
  368. LGO_Visible                   INT
  369.  
  370. LISTV_#? TAGS
  371.  
  372. LISTV_Top                     INT    ISG-U
  373. LISTV_ReadOnly                INT    ISG?? S/U will not change frame
  374. LISTV_MultiSelect             INT    IS?-U
  375. LISTV_Select                  INT    -S--U
  376. LISTV_MakeVisible             INT    -S--U
  377. LISTV_Entry                   STRING ---N-
  378. LISTV_EntryNumber             INT    ---N-
  379. LISTV_LastClicked             STRING --G--
  380. LISTV_LastClickedNum          INT    --G--
  381. LISTV_NewPosition             INT    ---N-
  382. LISTV_NumEntries              INT    --G--
  383. LISTV_MinEntriesShown         INT    ISG??
  384. LISTV_SelectMulti             INT    -S--U
  385. LISTV_SelectNotVisible        INT    -S--U
  386. LISTV_SelectMultiNotVisible   INT    -S--U
  387. LISTV_MultiSelectNoShift      INT    IS--U
  388. LISTV_Deselect                INT    -S--U
  389. LISTV_DropSpot                INT    --G--
  390. LISTV_ShowDropSpot            INT    IS---
  391. LISTV_Columns                 INT    I-G--
  392. LISTV_DragColumns             INT    ISG-U
  393. LISTV_Titles                  STRING I-G-U 41.8 Enforcer hits
  394. LISTV_Titles!                 OBJECT ISG-U static string problem
  395. LISTV_PreClear                INT    ISG--
  396. LISTV_LastColumn              INT    --G--
  397.  
  398. GA_#? TAGS
  399.  
  400. GA_Disabled                   INT    IS?-U
  401. GA_Selected                   INT    ISGNU toggles/checkboxes only
  402.  
  403. BT_#? TAGS
  404.  
  405. BT_LabelClick                 INT    IS---
  406. BT_DragObject                 INT    ISG--
  407. BT_DropObject                 INT    ISG--
  408. BT_Key                        STRING ISG-- set after creating window object only
  409. BT_RawKey                     INT    ISG-- set after creating window object only
  410. BT_Qualifier                  INT    ISG-- set after creating window object only
  411.  
  412. PAGE_#? TAGS
  413.  
  414. PAGE_Active                   INT    ISG?U
  415.  
  416. MX_#? TAGS
  417.  
  418. MX_Active                     INT    ISGNU
  419. MX_DisableButton              INT    IS--U
  420. MX_EnableButton               INT    IS--U
  421.  
  422. TAG_#? TAGS
  423.  
  424. TAG_IGNORE                    INT    IS--U does nothing!
  425.