Editing formatString - FilterMeisterWiki

When saving, enter the following:

          ######    ####     _   _  #    #  
           ##  ##    ##     | | | | #   #   
 ##  ##    ##  ##    ##     | |_| | #  #    
 ##  ##    #####     ##     |  _  | ###     
 ######    ##  ##    ##     |_| |_| #  #    
 ##  ##    ##  ##    ##             #   #   
 ##  ##   ######    ####            #    #  
 ##  ##

Visit Preferences to set your user name

= formatString =
== Syntax ==
:{{string formatString(string s)}}
== Arguments ==
:'''s'''
::A string containing 2-character formatting substrings and HTML entity codes
== Return ==
:Returns string s with substitutions made.
== Description ==
:Returns string s with the following substitutions made for the designated 2-character substrings (all of which begin with "!" or "&")

=== Overview ===
:FM deals with 4 different escape characters, which are substituted in 3 separate phases:

:*escape character '\'
::Escape code sequences beginning with '\' are handled by the parser, only during the parsing of string constants (not string variables). FM performs the usual C-language substitutions: '\t' for TAB, '\n' for new-line, '\r' for carriage-return, '\"' for a double-quote, etc.
::The '\' char itself is represented by the escape code '\\'.

:*escape character '%'
::Escape codes beginning with '%' are handled by the next phase, only during processing by built-in functions that take a variable number of arguments (such as setDialogTextv). FM calls the C-library routine sprintf (or some equivalent) which replaces the %-escape codes with formatted representations of the optional arguments according to the C-library conventions: "%d" for a decimal number argument, "%s" for a character string argument, etc.
::The '%' char itself is represented by the escape code "%%".
:*escape characters '!' and '&'
::Escape codes beginning with these characters are processed by the formatString routine during the final pass. 
::Two-character escape codes begining with '!' are substituted with an internal FM text string value: "!A" is replaced with the contents of the built-in string filterAuthorText (which contains the value of the Author: keyword field), "!C" is replaced by the contents of the filterCategoryText string, etc.
::The '!' char itself is represented by the escape code "!!".
::Escape codes beginning with '&' and ending with ';' are HTML entity references. FM replaces the escape code sequence "&quot;" with a double-quote character, "&euro;" with the euro character, etc.
::The '&' char itself is represented by the escape code "&&" or "&amp;".
:In summary, if your character string will be processed by any one of the above 3 passes, the escape character(s) for that pass can be represented by doubling the escape character in question. (If your string will NOT be processed by some particular pass, then the escape character(s) for that pass should NOT be doubled.)

=== ! escape sequences ===
||'''substring''' || '''is replaced by''' ||
||{c} && || "&"  (i.e., a verbatim ampersand) ||
||{c} !! || "!"  (i.e., a verbatim exclamation point) || 
||{c} !A || text specified by the ((Author)) key, obtained from the ((filterAuthorText)) string || 
||{c} !a || text specified by the ((About)) key, obtained from the ((filterAboutText)) string || 
||{c} !C || text specified by the ((Category)) key, obtained from the ((filterCategoryText)) string || 
||{c} !c || text specified by the ((Copyright)) key, obtained from the ((filterCopyrightText)) string || 
||{c} !D || text specified by the ((Description)) key, obtained from the ((filterDescriptionText)) string || 
||{c} !d || text specified by the ((propTitle)) image property, obtained from the ((documentTitleText)) string '''''(not yet implemented)''''' ||
||{c} !F || text specified by the ((Filename)) key, obtained from the ((filterFilenameText)) string || 
||{c} !f || the current Filter Case (e.g., "Flat image, no selection"), obtained from the ((filterCaseText)) string || 
||{c} !H || the name of the Host application (e.g., "Adobe Photoshop"), obtained from the ((filterHostText)) string || 
||{c} !h || the height of the image in pixels, obtained from the ((imageHeight)) variable ||
||{c} !I || the directory in which the plug-in filter was installed, from the ((filterInstallDir)) string '''''(not yet implemented)''''' ||
||{c} !M || the current Image Mode (e.g., "RGB Color"), obtained from the ((filterImageModeText)) string || 
||{c} !m || the current image mode as a decimal integer, obtained from the ((imageMode)) variable ||
||{c} !O || text specified by the ((Organization)) key, obtained from the ((filterOrganizationText)) string ||
||{c} !S || the current host serial number string, obtained from the ((hostSerialString)) string '''''(not yet implemented)''''' ||
||{c} !s || the current host serial number as a decimal value, from the ((hostSerialNumber)) variable '''''(not yet implemented)''''' ||
||{c} !T || text specified by the ((Title)) key, obtained from the ((filterTitleText)) string || 
||{c} !t || text specified by the ((Title)) key as above, with any trailing ellipsis removed || 
||{c} !U || text specified by the ((URL)) key, obtained from the ((filterURLText)) string ||
||{c} !V || text specified by the ((Version)) key, obtained from the ((filterVersionText)) string || 
||{c} !w || the width of the image in pixels, obtained from the ((imageWidth)) variable ||
||{c} !X || the Host architecture of the host system running the plugin (either "32" for a 32-bit system or "64" for a 64-bit system) '''''(implemented in FM mt5c05)''''' ||
||{c} !x || the Target architecture the plugin was compiled for (eg "32" for a 32-bit plugin, "64" for a 64-bit plugin) '''''(implemented in FM mt5c05)''''' ||
||{c} !Y || the current year in decimal (e.g., for use in a Copyright message) '''''(implemented in 1.0 Beta 9.0c)''''' ||
||{c} !z || the current proxy preview zoom factor (1 - 16), from the ((zoomFactor)) variable ||

:Caution: Other substrings beginning with "!" are reserved for future use.

=== HTML entities ===
:formatString also substitutes ISO character codes for the following HTML entity names.

||'''Entity name'''||{c,B}ISO||{B}Character meaning||
||||||{c,I}Common Punctuation||
|| &quote; ||{c} " || double quote ||
|| &amp; ||{c} & || ampersand ||
|| &apos; ||{c} ' || apostrophe ||
|| &hellip; ||{c} … || horizontal ellipsis ||
|| &iquest; ||{c} ¿ || inverted question mark ||
|| &iexcl; ||{c} ¡ || inverted exclamation mark ||
|| &Exclam; ||{c} !! || double exclamation mark ||
|| &sect; ||{c} § || section mark ||
|| &para; ||{c} ¶ || paragraph mark ||
|| &pilcrow; ||{c}  || pilcrow (unfilled paragaph mark) ||
|| &bull; ||{c} • || bullet ||
|| &bull2; ||{c}  || bullet style 2 ||
|| &ibull2; ||{c}  || inverse bullet style 2 ||
||||||{c,I}Currency and Commerce Symbols||
|| &curren; ||{c} ¤ || currency sign ||
|| &cent; ||{c} ¢ || cent sign ||
|| &pound; ||{c} £ || pound sign ||
|| &yen; ||{c} ¥ || Yen sign ||
|| &euro; ||{c} € || Euro sign ||
|| &copy; ||{c} © || copyright ||
|| &reg; ||{c} ® || registered trademark ||
|| &trade; ||{c} ™ || trademark ||
|| &permil; ||{c} ‰ || per mille ||
|| &brvbar; ||{c} ¦ || broken vertical bar ||
|| &ordf; ||{c} ª || feminine ordinal ||
|| &ordm; ||{c} º || masculine ordinal ||
|| &male; ||{c}  || male symbol ||
|| &female; ||{c}  || female symbol ||
||||||{c,I}Science, Logic, and Mathematics Symbols||
|| &lt; ||{c} < || less than ||
|| &gt; ||{c} > || greater than ||
|| &le; ||{c} <= || less or equal (substitute for &#8804;) ||
|| &ge; ||{c} >= || greater or equal (substitute for &#8805;) ||
|| &ne; ||{c} != || not equal (substitute for &#8800;) ||
|| &colone; ||{c} := || (used for colon-equal) ||
|| &Colon; ||{c} :: || (used for double colon) ||
|| &deg; ||{c} ° || degree sign ||
|| &prime; ||{c} ' || prime, minutes, feet ||
|| &Prime; ||{c} " || double prime, seconds, inches ||
|| &not; ||{c} ¬ || logical not ||
|| &plusmn; ||{c} ± || plus-or-minus sign ||
|| &minus; ||{c} - || minus sign (en-dash used as substitute) ||
|| &times; ||{c} × || multiplication symbol (times) ||
|| &divide; ||{c} ÷ || Division sign ||
|| &lowast; ||{c} * || low asterisk (asterisk used as substitute) ||
|| &sdot; ||{c} · || dot operator ||
|| &middot; ||{c} · || vertically centered dot ||
|| &empty; ||{c} Ø || Empty set ||
|| &sim; ||{c} ~ || similar to (tilde used as substitute) ||
|| &frac14; ||{c} ¼ || fraction 1/4 ||
|| &frac12; ||{c} ½ || fraction 1/2 ||
|| &frac34; ||{c} ¾ || fraction 3/4 ||
|| &frasl; ||{c} / || fraction slash (use /) ||
|| &oline; ||{c} ¯ || overline (use macron) ||
|| &micro; ||{c} µ || micro ||
|| &fnof; ||{c} ƒ || f with hook ||
|| &image; ||{c} I || imaginary part (blackletter I) ||
|| &real; ||{c} R || real part (blackletter R) ||
|| &weierp; ||{c} P || Weierstrass powerset (script P) ||
||||||{c,I}Markup-significant and Internationalization Characters|| 
|| &nbsp; ||{c}   || non-breaking space ||
|| &shy; ||{c}  || soft hyphen (never breaks in FM, so never displays) ||
|| &mdash; ||{c} — || em dash ||
|| &ndash; ||{c} – || en dash ||
|| &emsp; ||{c}   || em-space (use normal space) ||
|| &ensp; ||{c}   || en-space (use normal space) ||
|| &thinsp; ||{c}   || thin space (use normal space) ||
|| &zwnj; ||{c}  || zero width non-joiner (no char) ||
|| &zwj; ||{c}  || zero width joiner (no char) ||
||||||{c,I}Spacing Accents, Diaereses and other Diacritical Marks||
|| &acute; ||{c} ´ || acute accent ||
|| &uml; ||{c} ¨ || umlaut (diaeresis) ||
|| &cedil; ||{c} ¸ || spacing cedilla ||
|| &circ; ||{c} ˆ || modifier letter circumflex accent ||
|| &tilde; ||{c} ˜ || small tilde ||
|| &macr; ||{c} ¯ || spacing macron (overhead line) ||
||||||{c,I}Uppercase Accented Letters and Ligatures||
|| &Agrave; ||{c} À || A grave ||
|| &Aacute; ||{c} Á || A acute ||
|| &Acirc; ||{c} Â || A circumflex ||
|| &Atilde; ||{c} Ã || A tilde ||
|| &Auml; ||{c} Ä || A umlaut ||
|| &Aring; ||{c} Å || A ring ||
|| &AElig; ||{c} Æ || A-E ligature ||
|| &Ccedil; ||{c} Ç || C cedilla ||
|| &Egrave; ||{c} È || E grave ||
|| &Eacute: ||{c} É || E acute ||
|| &Ecirc; ||{c} Ê || E circumflex ||
|| &Euml; ||{c} Ë || E umlaut ||
|| &Igrave; ||{c} Ì || I grave ||
|| &Iacute; ||{c} Í || I acute ||
|| &Icirc; ||{c} Î || I circumflex ||
|| &Iuml; ||{c} Ï || I umlaut ||
|| &Ntilde; ||{c} Ñ || N tilde ||
|| &Ograve; ||{c} Ò || O grave ||
|| &Oacute; ||{c} Ó || O acute ||
|| &Ocirc; ||{c} Ô || O circumflex ||
|| &Otilde; ||{c} Õ || O tilde ||
|| &Ouml; ||{c} Ö || O umlaut ||
|| &Oslash; ||{c} Ø || slashed O ||
|| &OElig; ||{c} Œ || O-E ligature ||
|| &Scaron; ||{c} Š || capital S with caron ||
|| &Ugrave; ||{c} Ù || U grave ||
|| &Uacute; ||{c} Ú || U acute ||
|| &Ucirc; ||{c} Û || U circumflex ||
|| &Uuml; ||{c} Ü || U umlaut ||
|| &Yacute; ||{c} Ý || Y acute ||
|| &Yuml; ||{c} Ÿ || capital Y with diaeresis ||
|| &Zcaron; ||{c} Ž || capital Z with caron (not official) ||
|| &ETH; ||{c} Ð || capital letter Eth ||
|| &THORN; ||{c} Þ || capital letter Thorn ||
||||||{c,I}Lowercase Accented Letters and Ligatures||
|| &szlig; ||{c} ß || s-z ligature ||
|| &agrave; ||{c} à || a grave ||
|| &aacute; ||{c} á || a acute ||
|| &acirc; ||{c} â || a circumflex ||
|| &atilde; ||{c} ã || a tilde ||
|| &auml; ||{c} ä || a umlaut ||
|| &aring; ||{c} å || a ring ||
|| &aelig; ||{c} æ || a-e ligature ||
|| &ccedil; ||{c} ç || c cedilla ||
|| &egrave; ||{c} è || e grave ||
|| &eacute; ||{c} é || e acute ||
|| &ecirc; ||{c} ê || e circumflex ||
|| &euml; ||{c} ë || e umlaut ||
|| &igrave; ||{c} ì || i grave ||
|| &iacute; ||{c} í || i acute ||
|| &icirc; ||{c} î || i circumflex ||
|| &iuml; ||{c} ï || i umlaut ||
|| &ntilde; ||{c} ñ || n tilde ||
|| &ograve; ||{c} ò || o grave ||
|| &oacute; ||{c} ó || o acute ||
|| &ocirc; ||{c} ô || o circumflex ||
|| &otilde; ||{c} õ || o tilde ||
|| &ouml; ||{c} ö || o umlaut ||
|| &oslash; ||{c} ø || slashed o ||
|| &oelig; ||{c} œ || small o-e ligature ||
|| &scaron; ||{c} š || small s with caron ||
|| &ugrave; ||{c} ù || u grave ||
|| &uacute; ||{c} ú || u acute ||
|| &ucirc; ||{c} û || u circumflex ||
|| &uuml; ||{c} ü || u umlaut ||
|| &yacute; ||{c} ý || y acute ||
|| &yuml; ||{c} ÿ || y umlaut ||
|| &zcaron; ||{c} ž || small z with caron (not official) ||
|| &eth; ||{c} ð || small letter eth ||
|| &thorn; ||{c} þ || small letter thorn ||
||||||{c,I}Subscripts, Superscripts and Footnotes||
|| &sup1; ||{c} ¹ || superscript 1 ||
|| &sup2; ||{c} ² || superscript 2 ||
|| &sup3; ||{c} ³ || superscript 3 ||
|| &dagger; ||{c} † || dagger ||
|| &Dagger; ||{c} ‡ || double dagger ||
||||||{c,I}Various Quotation Marks||
|| &lsquo; ||{c} ‘ || left single quotation mark ||
|| &rsquo; ||{c} ’ || right single quotation mark ||
|| &sbquo; ||{c} ‚ || single low-9 quotation mark ||
|| &bdquo; ||{c} „ || double low-9 quotation mark ||
|| &ldquo; ||{c} “ || left double quotation mark ||
|| &rdquo; ||{c} ” || right double quotation mark ||
|| &lsaquo; ||{c} ‹ || left single angle quotation ||
|| &rsaquo; ||{c} › || right single angle quotation ||
|| &laquo; ||{c} « || left angle quote ||
|| &raquo; ||{c} » || right angle quote ||
||||||{c,I}Subset of Available Greek Characters||
|| &Alpha; ||{c} A || Alpha (use latin capital A) ||
|| &Beta; ||{c} B || Beta (use latin capital B) ||
|| &Epsilon; ||{c} E || Epsilon (use latin capital E) ||
|| &Zeta; ||{c} Z || Zeta (use latin capital Z) ||
|| &Eta; ||{c} H || Eta (use latin capital H) ||
|| &Iota; ||{c} I || Iota (use latin capital I) ||
|| &Kappa; ||{c} K || Kappa (use latin capital K) ||
|| &Mu; ||{c} M || Mu (use latin capital M) ||
|| &Nu; ||{c} N || Nu (use latin capital N) ||
|| &Omicron; ||{c} O || Omicron (use latin capital O) ||
|| &Rho; ||{c} P || Rho (use latin capital P) ||
|| &Tau; ||{c} T || Tau (use latin capital T) ||
|| &Upsilon; ||{c} Y || Upsilon (use latin capital Y) ||
|| &Chi; ||{c} X || Chi (use latin capital X) ||
|| &beta; ||{c} ß || beta (use sz-ligature; yecch!) ||
|| &mu; ||{c} µ || mu (use &micro;) ||
|| &omicron; ||{c} o || omicron (use small latin o) ||
||||||{c,I}OEM Arrows, Line Drawing and Graphics||
|| &larr; ||{c} &#8592; || leftwards arrow ||
|| &uarr; ||{c} &#8593; || upwards arrow ||
|| &rarr; ||{c} &#8594; || rightwards arrow ||
|| &crarr; ||{c}  || carriage-return arrow (composed by two other graohics) ||
|| &varr; ||{c}  || up/down (vertical) arrow (not official) ||
|| &ltrif; ||{c}  || left-pointing triangle, filled ||
|| &blk14; ||{c}  || lightly shaded box ||
|| &boxv; ||{c}  || box drawing: vertical ||
|| &boxvl; ||{c}  || box drawing: vertical and left ||
|| &boxdl; ||{c}  || box drawing: down and left ||
|| &boxur; ||{c}  || box drawing: up and right ||
|| &boxhu; ||{c}  || box drawing: horizontal and up ||
|| &boxhd; ||{c}  || box drawing: horizontal and down ||
|| &boxvr; ||{c}  || box drawing: vertical and right ||
|| &boxh; ||{c}  || box drawing: horizontal ||
|| &boxvh; ||{c}  || box drawing: vertical and horizontal ||
|| &boxul; ||{c}  || box drawing: up and left ||
|| &boxdr; ||{c}  || box drawing: down and right ||
|| &twonotes; ||{c}  || two beamed 16th notes ||

== Notes ==
:You do not usually need to call formatString() explicitly, since it is implicitly applied in the following cases:

:- when displaying the text label for a dialog control,
:- when displaying the items in a ((LISTBOX)) or ((COMBOBOX)) control,
:- when displaying the dialog caption in the title bar,
:- when displaying text in a Message Box via the ((msgBox))(), ((printf))(), ((Info))(), ((Warn))(), ((Error))(), ((ErrorOk))(), ((YesNo))(), or ((YesNoCancel))() built-in functions,
:- when displaying the prompt in the ((chooseColor))() color-picker dialog box,
:- when specifying the registry path and key names in the Windows Systems Registry access functions,
:- when displaying the About text in the About dialog box.

== Example ==
:For example, the default Dialog text is "!t (!M, !f)", which formatString() translates to something like "My Filter Title (RGB Color, Flat image, no selection)" at run time.
== Also see ==
:((appendEllipsis)), ((stripEllipsis))
== Comments ==
:Everyone can add his comments about his experiences with this function here.
:Tips for using it are welcome, too.

Summary of change:
Add document to category: