[futurebasic] QuiXample and DBFD updates

Message: < previous - next > : Reply : Subscribe : Cleanse
Home   : July 2005 : Group Archive : Group : All Groups

From: Alain Pastor <apastor@...>
Date: Thu, 07 Jul 2005 15:35:51 +0200
QuiXample 1.2.6

Originally designed as an Editor plug-in, QuiXample is a plain-text 
search tool featuring an extremely fast engine. On OS X, it can scan the 
overcrowded Examples folder on your hard disk in a blink of an eye.

This new release has been built using the latest DataBrowser For Dummies 
library (see below). A very minor bug has been fixed: the 
active/inactive state of the Search button could have been wrong after a 
Cut or a Paste operation.

English: <http://euro.futurebasic.com/en/res_tools_1.php#QuiXample>
French: <http://euro.futurebasic.com/fr/res_tools_1.php#QuiXample>
Italian: ???


DataBrowser For Dummies 2.0

DBFD is a library of functions that will ease the path to novices in 
their discovery of the DataBrowser, a feature-rich control which is only 
available in Carbon. It is a learning curve flattener even for 
intermediate programmers.

For this version, credits are due to Michael Kluskens who found the 
magic formula for the slider issue, and to Robert Purves who took the 
time to examine the tangled up code of the library.

Novelties:

- Despite the warning by Apple asking the developers not to use the 
slider data type with the DataBrowser control, DBFD 2.0 can alleviate 
your pain and let you bypass that advice. This has been made possible 
with a bit of investigation and the ingenuity of Michael Kluskens. Would 
you believe that there's no less than 3 bugs, courtesy of Apple, in the 
DataBrowser API just for this feature? The BrowserGetValue function from 
the DBFD library transparently corrects 2 of them, while a couple of 
utility functions have been implemented -- thanks to Michael's work -- 
in order to provide you with the correct slider value. You only have to 
use one of those two, depending on your coding preference.

1 - Once you've got the slider value from BrowserGetValue, you can use 
the following function to adjust the value returned:

err = Fn BrowserGetValue( itemData, sliderValue )
err = Fn BrowserAdjustSliderValue( browser, columnID, itemData, 
sliderValue )

2 - You can get the correct value directly returned by BrowserGetValue, 
using the BrowserAdjustSliderMinMax function that tweaks the minimum and 
maximum values of the slider before you get or set the slider value:

err = Fn BrowserAdjustSliderMinMax( browser, columnID , sliderMinValue, 
sliderMaxValue )
err = Fn BrowserSetMinimum( itemData, sliderMinValue )
err = Fn BrowserSetMaximum( itemData, sliderMaxValue )

- New BrowserKill function. Not needed that often, except to avoid a 
possible tiny memory leak when a DataBrowser displays sliders. This 
function is equivalent to a Button Close command.

- New DBFD functions have been introduced to ease the updating, adding 
or removing of a single item in the DataBrowser list:

err = Fn BrowserUpdateOneItem( browser, parentItemID, itemID, columnID )
err = Fn BrowserAddOneItem( browser, parentItemID, itemID )
err = Fn BrowserRemoveOneItem( browser, parentItemID, itemID )

Note: Prior to those functions, you had to define an array of 2 itemIDs 
or a 8-byte pointer (or a handle) just to deal with a unique item. 
Additionally, those functions are helpful to work with individual items 
in a DBFD array of itemIDs.

- A new DBFD function allows you to retrieve the subItemIDs owned by a 
given container:

subItemsHandle = Fn BrowserGetSubItems( browser, parentItemID )

Warning: you must dispose of the handle returned when you're done with 
it and you must keep in mind that the data is formatted to work with the 
other DBFD functions (i.e. the first itemID in the data block is the 
parent itemID of all the itemIDs that follow).

Note: such a handle can easily be converted to an array of itemIDs using 
the Xref@ command. Eg:

Xref@ arrayOfItemIDs( _maxInt ) As DataBrowserItemID

arrayOfItemIDs = Fn BrowserGetSubItems( browser, parentItemID )
Long If arrayOfItemIDs
maxIndexInArray = (Fn GetHandleSize(arrayOfItemIDs)\\ 
Sizeof(DataBrowserItemID) ) - 1
// remove the last item in the array from the container
err = Fn BrowserRemoveOneItem( browser, arrayOfItemIDs(0), 
arrayOfItemIDs(maxIndexInArray) )
End If
DisposeHandle( arrayOfItemIDs )


- New examples that show how to handle checkboxes (included in 
hierarchical lists), popup menus and sliders with the DataBrowser control.

Enhancements:

- Some parts of the code have been streamlined by Robert Purves, and 
more precisely those parts dealing with the hidden installation of the 
whole set of DataBrowser callback procedures. Robert has fixed the 
postProcessDragCallback too.

Note: while nothing will stop you from declaring and installing an 
ItemNotificationWithItem callback procedure/FB function, that feature 
doesn't work currently with Carbon. I have left that possibility for a 
possible future update of the DataBrowser API by Apple.

- Parts of a few functions have been rewritten for security and efficiency.

- Some of the examples have been slightly modified. All the example 
files have been renamed so that it will be easier to see at first glance 
what each of them is supposed to illustrate.

- The files "DataBrowser Callback Templates" and "DataBrowser Library 
Functions"  have been updated and moved to the "Readme Files" folder 
since those documents are just reminders.

Bug fixes:

- Several bad dereferencings of handle have been corrected.

- The "CrosswordHinter_v02b" demo (adapted from an example by Ken 
Schmidheiser) was not working as expected because the output compiled 
file was given the same name as its source code file.

- Example #11 was stating wrongly (or prematurely) that there was a bug 
in the ItemEditText callback procedure. Actually, this callback is meant 
to be used with custom type cells, and not with regular text type cells 
like the example was trying to do.

English: <http://euro.futurebasic.com/en/res_tools_1.php#DBFD>
French: <http://euro.futurebasic.com/fr/res_tools_1.php#DBFD>

Alain