API How To PDF Print E-mail

NOTE: The new description delimiter for all modes is the tilde ( ~ ) . Yes, this also replaces the use of # in difficult Batch type declarations. This allows us to use # in descriptions. The drawback is that you can't use a tilde within descriptions or function declarations.
As of version 2.4, HTML tag descriptions must now be in the following format table<:Creates a table~cellpadding,cellspacing,align
Note also that LOCAL AUTOCOMPLETE listings (read further for details) MUST begin with a dot at the start of the line.

ZionEdit will parse standard Scintilla type call tip files, but in true ZionEdit style adds a few nifty extensions of its own , but before we get into that what are Call Tips and AutoComplete anyway?

A Call Tip (CT) is a hint that pops up over a function name when typed. The hint reminds you of the arguments the function can take etc. Note that along with the CT you may get a more detailed description in the yellow Info Bar at the top or bottom of the screen.

AutoComplete (AC) is a popup listbox that offers possible completions for the character(s) you typed.
AC comes in two broad categories:

  • Global AC
  • Local or Object, AC
  • Global AC is simply word completion after you type a certain amount of characters (that number is set in Settings | Global Options). It can sometimes be annoying because it doesn't really know the context in which you are typing, it just says, "there's a word I know, let's complete it!" It has it's benefits though for long words.
  • The smarter kind of AutoComplete is Local AC (or Object AC). Local AC will popup a list specific to the object, type or special character typed. It is also called Local Object Completion depending on what state my brain was in. I will try to stick to Local AC. So here are the different types of Local AC:
    • Object Member Completion–Activated with a dot ( . ) is for general class objects and will list Methods (functions) or properties of the object. Note that since I won't know what the object name will be, in the api file, list the class or type name with the method or property. Example: wxString.Len() . then associate your current object to the type with the menu option "SpecialOps | Associate Identifier to Type".
      So let's say you have an wxString object declared like this:
      wxString aString; You then created the association of aString to wxString. Now whenever you type aString. you will get the AutoComplete list for wxString! Not bad for a "light" editor huh?
    • Object Pointer Completion–Activated with ( -> ). This is effectively the same as Object Member Completion - just activated in a different way.
    • Scope Member Completion–Activated with two colons ( :: ). This is for globally scoped functions like: wxString::Format()
    • CSS Value Completion–Activated with one colon ( : ). This will list the CSS value option for the current attribute.
    • CSS Additional Attribute Completion–Activated with a semi-colon ( ; ).
    • HTML Tag Completion–Activated with an open tag ( < ) then a single character typed
    • HTML Attribute Completion–Activated with a space.
    • HTML Attribute Value Completion–Activated with an equal ( = ).
    • You get the idea ;-)

C Style Call Tips

The simplest syntax to parse is the standard C like function call:
MyFunction( int a, int b )~Does something with 'a' and 'b'
There are a few things to note here:

  1. The function declaration is listed without the return type.
  2. The first ')' will indicate the end of the function listing. The tilde ( ~ ) will indicate the beginning of the description.
    A space could be used instead of a tilde, but it is now recommended to use the tidle for all description separators. Here's why:
    Zion can now display descriptions in AutoComplete (AC) listings. If your function is object based meaning there is a dot in the function listing like:
    rs.MoveNext()~Moves to the next record...  the description for the function can also be displayed in the AutoComplete listing for rs. So after typing rs. to get the AC listing, as you arrow down you will see description for MoveNext before actually selecting the function!
    If there were two functions with the same name (called overloads)
    Example:
    rs.MoveNext()  and
    rs.MoveNext(Amount as Integer)
    the description shown in the AC list is for both functions. Hence it is called an Overload Description.. So here is how to fully enable the above functions for overload descriptions:
    rs.MoveNext()~Moves to another record~Moves to the Next Record
    rs.MoveNext(Amount as Integer)~Moves to record offset specified by Amount
    Here's the deal The first overload listed will carry the overload description between the first and second tilde, while the overload specific description is after the first tilde. The second overload will just carry it's own description.
    Remember if there are no overloads then you can use a single tilde with a description and it will apply to both the overload description in the AC and the description listed in the function's call tip. See the testCarObj listing in the c.api for a live example.
    Get in the habit of using Tilde ( ~ ) as your description separator.
  3. Function listings are line-based. The entire declaration and description must be placed on one line.
  4. Descriptions can include basic pre-HTML4.0 tags, definitely no styles or XHTML allowed. See the included file: wxHtmlSupportedTags.txt for the full list.
  5. Call Tip descriptions should not include loose '>' and '<' unless used to specific HTML formatting. Rather use ">" and "<" respectively. For a list of special characters supported by wxHTML, type & on a new line in HTML mode, then watch the yellow Info Bar as you scroll through the list. If the special char is displayed as a symbol/sign it is supported, otherwise it is not.

Okay so that was the "simple stuff". It gets more interesting...

BATCH Style Call Tips

Batch style syntax is an older style that most modern languages left for good reason. Generally a function is separated from its parameters by a space. e.g.
FOR /F ["options"] %variable IN (file-set | "string" | 'command') DO command
We know the function is "FOR", but where does the parameters end and the description start? The char. ~ was therefore chosen as the declaration to description delimiter. This is different than the way SciTE seems to do it. I believe they use a semicolon and a space -- too messy, too errorprone as ';' is used often within some batch style declarations.

  • ~ is the highest priority delimiter for both Batch and C-like function call tips. So a line like this:
    ReDim [Preserve] varname(subscripts)[, varname(subscripts)] ... ~Preserves the data within...
    will not split on the first ')' found, but on the ~.

LOCAL OBJECT COMPLETION/ LOCAL AUTOCOMPLETE

Local AC is AutoComp activated by a special char like  .  or  :  and the api listing should follow the format discussed below.

The change is that local autocomp lines must begin with a dot ( . ) The old method (without a dot at the start) Will NOT work, but a '.' should be the first character on a local autocomp line.

ZionEdit object completion features are very, very, very sweet. Lets use the JavaScript API file for examples. Consider the following two lines:
docoument.close()
.document.alinkColor One is a function declaration, and the other a property or object member declaration. Zion will automatically list both when "document." is typed! Sweet, but not very sweet? Check this out: Zion allows you to list object members in short cut form like this:
.document.activeElement,alinkColor,bgColor
Getting impressed? There's more:
=color:htmlColors
!color.bgColor,backgroundColor,alinkColor
The first line will supply all the standard html color names via the pseudo word "htmlColors". Now instead of expanding out all 147 colors for all color type attributes, we create ALIASES to the one attribute "color" and now whenever you type lets say: document.alinkColor = cornflowerblue was typed all with autocomplete help!

Generally, Local Object AC descriptions can include any character except commas ( , ) and tildes ( ~ ) . HTML tag descriptions have an additional limitation – they cannot contain periods (dots) or they will be mistaken as a general object member listing.

LOCAL AUTOCOMPLETE SAMPLE (Try these live in C++ mode – just type testCarObj.)

#Object with single member listing
.testCarObj.color

#Object with single member listing with description. '~' is the description separator
.testCarObj.length~From bumper to bumper

#multiple listing without descript. Comma ( , ) is the member items separator – NO SPACES allowed
.testCarObj.make,model,engineSize,engineType

#multiple listing with descript. SPACES are allowed in description ONLY
.testCarObj.brakeType~whether disc or drum,doorLocks~power or manual,airconditioning

#pushing the limits of chars allowed in description. Descriptions can include any char except '.' and ','
.testCarObj.val12~Let's see; what kind of description should I give?

#Global AC, is AutoComp activated after a number of regular alpha numeric chars typed. List them one word per line:
testAutoCompString
testOfGlobalAutoComp

LIMITATIONS

ZionEdit will create automatic associations of declared type to known type in only two cases:
  1. When an id attribute and value are typed within a standard HTML tag (that is, a JavaScript id.)
  2. When an id attribute and value are typed within an ASP.NET tag
Otherwise, even if you type for example: wxString str; the association will not be made. There a too many variables (pun intended). Being a "light" editor, Zion will not make assumptions about your variable declarations, nor will it continually scan your file for possible declaration changes. A simple manual approach is provided:
Highlight/select the declared identifier – in this case str, then do "Associate Identifier to Type" (Ctrl-Alt-A) and choose wxString from the list.
(When listing methods or properties of a class in an API File, list with the class name, that is in the format classname.method or  classname.property. You don't want to use the object name declared later, but the classname itself. Later we can maually associate an object to the class.)

ADDITIONAL NOTES

  • Multiple API Files can be included simultaneously. Zion uses the concept of a master or "toplevel" call tip file for each Syntax Mode. For example, the toplevel api file for HTML mode is html.api. This master file can include other sub api files. Sub api files can be quickly commented out with a "#" placed at the very start of the line. This is very useful for HTML mode in particular that can included so many other programming languages. In fact for performance reasons it is best to comment out of the toplevel file any included API files you do not use.
  • To see the top-level api file for your language mode choose Options|Settings. It will be listed just below the checkboxes.

  • One way to learn how Call Tips / Auto Complete are done is by looking at the example API files provided. My listings are not meant to be exhaustive, though a few (like html tags) maybe, but are meant to cover all the different types of Call Tips / AutoComplete supported by ZionEdit.
  • Another useful exercise is to choose Help | Dump CallTip Structs from Zion's menu. This will dump all the data hashes used for Call Tips and AutoComplete to the current edit window. When compared with your api file, you can see how (and if :-) your intended Call Tip got parsed and stored.
  • Thanks to Vaclav Slavik for the wxHTML control used in Popup Tips
  • Most HTML reference info gleaned from O'Reilly's "Dynamic HTML - The Definitive Reference" ISBN-13: 978-0-596-52740-2

See www.zionedit.org Docs for the latest, most complete documentation.

Created with ZionEdit - www.zionedit.org
 
< Prev   Next >
[ Back ]
Best viewed with Firefox