Hi Paolo and Laurent,
Laurent Godard wrote:
>> ...
>> mArgs1(9).Name = "SearchItem.SearchFlags"
>> mArgs1(9).Value = 65536
>> ...
>
> sounds like the sum of this
> ref/com/sun/star/util/SearchFlags.html
Yep.
>> mArgs1(12).Name = "SearchItem.Locale"
>> mArgs1(12).Value = 255
>> mArgs1(13).Name = "SearchItem.ChangedChars"
>> mArgs1(13).Value = 2
>> mArgs1(14).Name = "SearchItem.DeletedChars"
>> mArgs1(14).Value = 2
>> mArgs1(15).Name = "SearchItem.InsertedChars"
>> mArgs1(15).Value = 2
>> mArgs1(16).Name = "SearchItem.TransliterateFlags"
>> mArgs1(16).Value = 1280
>> mArgs1(17).Name = "SearchItem.Command"
>> mArgs1(17).Value = 3
>>
>
> ref/com/sun/star/util/SearchOptions.html#searchFlag
>
> You may also have a look at
> /OpenOffice.org2.0_SDK/docs/common/ref/com/sun/star/util/SearchOptions-xref.html
Yes, you've hit the nail on the top. :-)
The parameter "SearchItem" contains the members of a SearchOptions
struct and the properties of a SearchDescriptor service.
>> I guess that I will find the same problem with other dispatches so I'm
>> looking
>> for documentation about dispatch params
There is no explicit documentation, this API was never intended for
writing macros, it is used internally for GUI components and for the
recording of macros.
> May we find interresting information in the source code ?
Yes. Use the source, Luke! :-)
> where should we start ?
So you want a five minutes crash course in dispatching? Let's try! :-)
As an example, take the current topic: searching.
Each dispatch function is defined in one of your so called "sdi" files,
here it's in framework/sfx2/sdi/sfx.sdi. We have similar files in the
modules svx, sw, sc, sd, sch and starmath (in the "sdi" sub folders).
I rearranged the line breaks for better readability and used quoting to
prevent line breaking by the mail client:
> SfxVoidItem ExecuteSearch FID_SEARCH_NOW(SvxSearchItem SearchItem
> SID_SEARCH_ITEM, SfxBoolItem Quiet SID_SEARCH_QUIET )
> [
> /* flags: */
> AutoUpdate = FALSE,
> Cachable = Cachable,
> FastCall = FALSE,
> HasCoreId = FALSE,
> HasDialog = FALSE,
> ReadOnlyDoc = TRUE,
> Toggle = FALSE,
> Container = FALSE,
> RecordAbsolute = FALSE,
> RecordPerSet;
> Synchron;
>
> /* config: */
> AccelConfig = FALSE,
> MenuConfig = FALSE,
> StatusBarConfig = FALSE,
> ToolBoxConfig = FALSE,
> GroupId = GID_EDIT;
> ]
We call this the definition of a "slot". You can ignore everything
between the square brackets, it's internal stuff.
The name of the slot is what you know from the dispatch command, here
it's "ExecuteSearch".
The FID_SEARCH_NOW behind the name is an internal number that the
framework needs for quick searching. In older times we used these
numbers for dispatching ("slot:xxxx") but meanwhile they are deprecated
and will vanish at some time. So just ignore them.
Behind the "FID_SEARCH_NOW" you find parameters in round brackets, they
mark this slot as a "function". Other slots don't have round brackets
and so they are "properties", not functions, example (here the internal
stuff is omitted):
> SfxBoolItem DesignerDialog SID_STYLE_DESIGNER
> [
> ]
This is a property slot and setting the property it is done by executing
the dispatch ".uno:DesignerDialog" with a parameter with the same name
as the slot and the type that you can read before the name (SfxBoolItem
-> Boolean). BTW: executing the slot without a parameter toggles the
state of the property (here: the visibility of the Stylist).
In case of the "ExecuteSearch" function slot we also have a type before
the name (again internal stuff omitted):
> SfxVoidItem ExecuteSearch FID_SEARCH_NOW(SvxSearchItem SearchItem
> SID_SEARCH_ITEM, SfxBoolItem Quiet SID_SEARCH_QUIET )
> [
> ]
The preceeding type "SfxVoidItem" denotes the return type of the
function, something that is available only internally but not via API,
so you can just ignore it.
Now about the parameters of the function. While most functions don't
have parameters and so end with "()", some have, like "ExecuteSearch".
All parameters are described in the same way:
SvxSearchItem SearchItem SID_SEARCH_ITEM
InternalType Name ID
The name is - as you might expect - the name you find in the recorded
macro, the ID is again something used only internally.
The type of the parameter needs some translation because it is an
internal type name. Most of them are pretty clear (SfxBoolItem,
SfxStringItem etc.), but there are also some complex ones. These complex
items also are defined in the sdi files. Here's the definition of the
"SvxSearchItem" used in our definition above (again it's taken from
sfx.sdi):
> struct SvxSearch
> {
> INT16 StyleFamily MID_SEARCH_STYLEFAMILY;
> UINT16 CellType MID_SEARCH_CELLTYPE;
> BOOL RowDirection MID_SEARCH_ROWDIRECTION;
> BOOL AllTables MID_SEARCH_ALLTABLES;
> BOOL Backward MID_SEARCH_BACKWARD;
> BOOL Pattern MID_SEARCH_PATTERN;
> BOOL Content MID_SEARCH_CONTENT;
> BOOL AsianOptions MID_SEARCH_ASIANOPTIONS;
> INT16 AlgorithmType MID_SEARCH_ALGORITHMTYPE;
> INT32 SearchFlags MID_SEARCH_FLAGS;
> String SearchString MID_SEARCH_SEARCHSTRING;
> String ReplaceString MID_SEARCH_REPLACESTRING;
> INT16 Locale MID_SEARCH_LOCALE;
> INT32 ChangedChars MID_SEARCH_CHANGEDCHARS;
> INT32 DeletedChars MID_SEARCH_DELETEDCHARS;
> INT32 InsertedChars MID_SEARCH_INSERTEDCHARS;
> INT32 TransliterateFlags MID_SEARCH_TRANSLITERATEFLAGS;
> INT16 Command MID_SEARCH_COMMAND;
> };
>
> item SvxSearch SvxSearchItem;
The first part defines a struct "SvxSearch", the second parts defines a
synonym for it in the framework internal world called SvxSearchItem and
that's the name you find in the parameter definitions.
You can see that a lot of parameters from the recorded macro appear as
members of the struct, also expressed by their Basic names like
"SearchItem.Locale".
Internally we use this struct and the macro recorder disassembles is and
writes each single member as such a "flat" parameter, OTOH when the
dispatching code receives them reconstructs the struct. For both steps
the information from the SDI files is used (in a binary compiled form).
As an example, the parameter "SearchItem.Locale" is the member "Locale"
of the parameter "SearchItem" that is of type "SvxSearchItem". I hope
you get it from the quoted definitions.
The numbers in each line defining a member again are internally used
ones but might become interesting if you need to know how those members
are treated internally. But this should be discussed on a case to case
base. For our current case here's the relevant source code that does the
named internal conversions (taken from sfx2/source/control/srchitem.cxx:
> sal_Bool SvxSearchItem::QueryValue( com::sun::star::uno::Any& rVal, BYTE
> nMemberId ) const
> {
> sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);
> nMemberId &= ~CONVERT_TWIPS;
> switch ( nMemberId )
> {
> case MID_SEARCH_COMMAND:
> rVal <<= (sal_Int16) nCommand; break;
> case MID_SEARCH_STYLEFAMILY:
> rVal <<= (sal_Int16) eFamily; break;
> case MID_SEARCH_CELLTYPE:
> rVal <<= (sal_Int32) nCellType; break;
> case MID_SEARCH_ROWDIRECTION:
> rVal <<= (sal_Bool) bRowDirection; break;
> case MID_SEARCH_ALLTABLES:
> rVal <<= (sal_Bool) bAllTables; break;
> case MID_SEARCH_BACKWARD:
> rVal <<= (sal_Bool) bBackward; break;
> case MID_SEARCH_PATTERN:
> rVal <<= (sal_Bool) bPattern; break;
> case MID_SEARCH_CONTENT:
> rVal <<= (sal_Bool) bContent; break;
> case MID_SEARCH_ASIANOPTIONS:
> rVal <<= (sal_Bool) bAsianOptions; break;
> case MID_SEARCH_ALGORITHMTYPE:
> rVal <<= (sal_Int16) aSearchOpt.algorithmType; break;
> case MID_SEARCH_FLAGS:
> rVal <<= aSearchOpt.searchFlag; break;
> case MID_SEARCH_SEARCHSTRING:
> rVal <<= aSearchOpt.searchString; break;
> case MID_SEARCH_REPLACESTRING:
> rVal <<= aSearchOpt.replaceString; break;
> case MID_SEARCH_CHANGEDCHARS:
> rVal <<= aSearchOpt.changedChars; break;
> case MID_SEARCH_DELETEDCHARS:
> rVal <<= aSearchOpt.deletedChars; break;
> case MID_SEARCH_INSERTEDCHARS:
> rVal <<= aSearchOpt.insertedChars; break;
> case MID_SEARCH_TRANSLITERATEFLAGS:
> rVal <<= aSearchOpt.transliterateFlags; break;
> case MID_SEARCH_LOCALE:
> {
> sal_Int16 nLocale;
> if (aSearchOpt.Locale.Language.getLength() ||
> aSearchOpt.Locale.Country.getLength() )
> nLocale = ConvertIsoNamesToLanguage(
> aSearchOpt.Locale.Language, aSearchOpt.Locale.Country );
> else
> nLocale = LANGUAGE_NONE;
> rVal <<= nLocale;
> break;
> }
> default:
> DBG_ERROR( "Unknown MemberId" );
> return sal_False;
> }
>
> return sal_True;
> }
>
> sal_Bool SvxSearchItem::PutValue( const com::sun::star::uno::Any& rVal, BYTE
> nMemberId )
> {
> sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);
> nMemberId &= ~CONVERT_TWIPS;
> sal_Bool bRet = sal_False;
> sal_Int32 nInt;
> switch ( nMemberId )
> {
> case MID_SEARCH_COMMAND:
> bRet = (rVal >>= nInt); nCommand = (sal_uInt16) nInt; break;
> case MID_SEARCH_STYLEFAMILY:
> bRet = (rVal >>= nInt); eFamily = (SfxStyleFamily) (sal_Int16)
> nInt; break;
> case MID_SEARCH_CELLTYPE:
> bRet = (rVal >>= nInt); nCellType = (sal_uInt16) nInt; break;
> case MID_SEARCH_ROWDIRECTION:
> bRet = (rVal >>= bRowDirection); break;
> case MID_SEARCH_ALLTABLES:
> bRet = (rVal >>= bAllTables); break;
> case MID_SEARCH_BACKWARD:
> bRet = (rVal >>= bBackward); break;
> case MID_SEARCH_PATTERN:
> bRet = (rVal >>= bPattern); break;
> case MID_SEARCH_CONTENT:
> bRet = (rVal >>= bContent); break;
> case MID_SEARCH_ASIANOPTIONS:
> bRet = (rVal >>= bAsianOptions); break;
> case MID_SEARCH_ALGORITHMTYPE:
> bRet = (rVal >>= nInt); aSearchOpt.algorithmType =
> (::com::sun::star::util::SearchAlgorithms) (sal_Int16) nInt; break;
> case MID_SEARCH_FLAGS:
> bRet = (rVal >>= aSearchOpt.searchFlag); break;
> case MID_SEARCH_SEARCHSTRING:
> bRet = (rVal >>= aSearchOpt.searchString); break;
> case MID_SEARCH_REPLACESTRING:
> bRet = (rVal >>= aSearchOpt.replaceString); break;
> case MID_SEARCH_CHANGEDCHARS:
> bRet = (rVal >>= aSearchOpt.changedChars); break;
> case MID_SEARCH_DELETEDCHARS:
> bRet = (rVal >>= aSearchOpt.deletedChars); break;
> case MID_SEARCH_INSERTEDCHARS:
> bRet = (rVal >>= aSearchOpt.insertedChars); break;
> case MID_SEARCH_TRANSLITERATEFLAGS:
> bRet = (rVal >>= aSearchOpt.transliterateFlags); break;
> case MID_SEARCH_LOCALE:
> {
> bRet = (rVal >>= nInt);
> if ( bRet )
> {
> if ( nInt == LANGUAGE_NONE )
> {
> aSearchOpt.Locale = ::com::sun::star::lang::Locale();
> }
> else
> {
> String sLanguage, sCountry;
> ConvertLanguageToIsoNames( (sal_Int16) nInt, sLanguage,
> sCountry );
> aSearchOpt.Locale.Language = sLanguage;
> aSearchOpt.Locale.Country = sCountry;
> }
> }
> break;
> }
> default:
> DBG_ERROR( "Unknown MemberId" );
> }
>
> return bRet;
> }
First you can see that the C++ class name is what you find as the last
entry of the struct definition. The shown methods show you that some of
the parameters are converted into a SearchOptions struct. It's not
always that clear but at least sometimes. :-) But it also possible that
there is no UNO API at all that you can use to replace the dispatch call
(e.g. clipboard functions) or there is one but the dispatch
implementation does not use it and so you can't find any help in the
source code.
I hope that this small introduction is of help.
Best regards,
Mathias
--
Mathias Bauer - OpenOffice.org Application Framework Project Lead
Please reply to the list only, [EMAIL PROTECTED] is a spam sink.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
