|
(SST) ShlWAPIFunctionInfo Version 1.0 |
|---|---|
| Developer Reference |
| Generates a preliminary, unique name for a new TListItem caption. |
| Scope |
|---|
| Public (i.e. this method can be referenced from any code, including that in other units, with access to the TSSTAdvancedListView object of interest). |
| Syntax | |
|---|---|
| Function GetNextNewFunctionName(ainitialindx : INTEGER; VAR anewfunctionnum : INTEGER; VAR anewname : STRING; acharsettype : TSSTCharSetType) : INTEGER; | |
| Parameters | |
|---|---|
| ainitialindx [in] | The index of the TListItem at which to start testing the newly generated names for uniqueness. This value should be 0 if a unique name should be returned and the TListView already contains items at the time of the call. |
| anewfunctionnum [in/out] | A signed, 32-bit, integer value that is formatted as text and appended to the first part of the preliminary name, in order to make it unique. The function increments this variable until a value was found, with which it was able to form a unique (i.e. nonexistent) caption. However, the current implementation of the function increments this value only up to 99. |
| anewname [out] | A string variable into which the method writes the generated name. |
| acharsettype [in] | A value of type TSSTCharSetType that specifies whether to append an A, denoting an ANSI function, or W, denoting a WCHAR/Unicode function, to the name. Alternatively this value can be csTypeNone, in which case neither an A, nor a W will terminate the string returned in the anewname parameter. |
| Return Values |
|---|
| If the method was able to generate the requested (unique) name, it returns ERROR_SUCCESS (= 0), if not, -1 (= $FFFF FFFF). |
| Remarks |
|---|
| The specific nature of this method can only be readily understood in the context of the SST ShlWAPIFunctionInfo application. This, in order to make allowances for additional functions in future versions of Microsoft's ShlWAPI.dll, affords the user the possiblity to add items to its Main Window's Function Names List View. The item captions in the Function Names List View being the function names that the application tests a dll for. It is in this context and to make keeping track of the added function names easier for the user, that the method generates names that are numbered, and depending on the parameters whith which it is called, unique. |
| The method generates the returned name according to the following schema; the hard-coded string "NewFunctionName" (without the quotation marks), the two digit, string representation of a value between 0 and 99, and depending on if csTypeAnsi or csTypeWCHAR is specified in the acharsettype parameter, an uppercase a ("A") or w ("W") (both, without the quotation marks). The optionally terminating characters (i.e. "A" or "W", also withoud the quotation marks) serve to identify the function as either the ANSI or Unicode version. This is part of the Microsoft naming conventions for functions that have string parameters and simplifies discerning functions that have to be called with ANSI, from those that have to be called with Unicode, strings. |
| The current implementation of the method always replaces the input string. If the method succeeds, it overwrites the anewname parameter with the generated name. If it fails, the input string is replaced by an empty (i.e. 0 length) string. |
| Example |
|---|
| The latter two of the three procedures, in the sample code below, were taken from the source code of the SST ShlWAPIFunctionInfo's main window/form (TForm1). |
| PROCEDURE TForm1.AddNeutralFunctionName(Sender : TObject); VAR newfunctionnum : INTEGER; VAR newcaption : STRING; VAR getcaptionretval : INTEGER; VAR newlvitem : TListItem; BEGIN newfunctionnum := 0; newcaption := ''; getcaptionretval := 0; newlvitem := NIL; newfunctionnum := 1; getcaptionretval := TSSTAdvancedListView(ListView1).GetNextNewFunctionName(0, newfunctionnum, newcaption, csTypeNone); IF getcaptionretval = ERROR_SUCCESS THEN BEGIN TRY newlvitem := ListView1.Items.Add(); newlvitem.Caption := newcaption; EXCEPT getcaptionretval := - 1; END; END; IF getcaptionretval <> ERROR_SUCCESS THEN ShowMessage('Can''t add function name'); END; PROCEDURE TForm1.AddANSIFunctionName(Sender : TObject); VAR newfunctionnum : INTEGER; VAR newcaption : STRING; VAR getcaptionretval : INTEGER; VAR newlvitem : TListItem; BEGIN newfunctionnum := 0; newcaption := ''; getcaptionretval := 0; newlvitem := NIL; newfunctionnum := 1; getcaptionretval := TSSTAdvancedListView(ListView1).GetNextNewFunctionName(0, newfunctionnum, newcaption, csTypeANSI); IF getcaptionretval = ERROR_SUCCESS THEN BEGIN TRY newlvitem := ListView1.Items.Add(); newlvitem.Caption := newcaption; EXCEPT getcaptionretval := - 1; END; END; IF getcaptionretval <> ERROR_SUCCESS THEN ShowMessage('Can''t add function name'); END; PROCEDURE TForm1.AddWCHARFunctionName(Sender : TObject); VAR newfunctionnum : INTEGER; VAR newcaption : STRING; VAR getcaptionretval : INTEGER; VAR newlvitem : TListItem; BEGIN newfunctionnum := 0; newcaption := ''; getcaptionretval := 0; newlvitem := NIL; newfunctionnum := 1; getcaptionretval := TSSTAdvancedListView(ListView1).GetNextNewFunctionName(0, newfunctionnum, newcaption, csTypeWCHAR); IF getcaptionretval = ERROR_SUCCESS THEN BEGIN TRY newlvitem := ListView1.Items.Add(); newlvitem.Caption := newcaption; EXCEPT getcaptionretval := - 1; END; END; IF getcaptionretval <> ERROR_SUCCESS THEN ShowMessage('Can''t add function name'); END; |
| Called one after the other, in order or their implementation (i.e. AddNeutralFunctionName, followed by AddANSIFunctionName, and AddWCHARFunctionName), the procedures above would add three TListItems named NewFunctionName01, NewFunctionName01A, and NewFunctionName01W to the TListView, ListView1. Assuming that these items are not renamed, calling the procedures a second time would add another three items, this time with the captions NewFunctionName02, NewFunctionName02A, and NewFunctionName02W. This could be repeated (a) further 97 times until GetNextNewFunctionName would fail, due to the limitation imposed on the numerical part (e.g. "01", "42", "56", etc. ) of the name. |
| Requirements | |
|---|---|
| Unit | (Declared and implemented in) SSTNewUnit.pas |
| Library | SSTNewUnit.dcu/SSTNewUnit.obj |
| Unicode | Implemented as ANSI version only. |
| See Also |
|---|
| TSSTAdvancedListView, Methods, FindText, TSSTCharSetType. |
| Windows APIs: ListView_GetNextItem. |
|
Document/Contents version 1.00 Page/URI last updated on April 28, 2022 |
Copyright © Stoelzel Software Technologie (SST) 2010 - 2017 |
Suggestions and comments mail to: webmaster@stoelzelsoftwaretech.com |