*****************************************************************
***                 Coder AkelPad plugin v20.0                ***
*****************************************************************

2007-2017 Shengalts Aleksander aka Instructor (Shengalts@mail.ru)


*** 描述 ***

编程的附加功能。


*** 函数 ***

Coder::HighLight
语法高亮显示。

Coder::CodeFold
代码折叠的支持。

Coder::AutoComplete
自动完成是项省时的功能。函数将一个短缩变为一个文本块。例如，当编辑 C++ 文件时，如果您键入 "for" 并按下热键 (默认值 Ctrl+空格)，"for" 将会扩大到下列字符串:
for (; ; )
{
}

Coder::Settings
设置对话框。


*** 设置 ***

使用列表完成:
一个变量 - 使用一个文本块替换缩写。
不止一个变量 - 显示可用于替换的缩写列表。

无列表的完成 / 转到新的位置:
一个变量或精确匹配 - 使用一个文本块替换缩写。
不止一个变量 - 传递热键供程序作下一步操作。
替换之后 - 转到文本块的下列位置。

转到之前的位置:
转到文本块之前的位置。

保存已键入符号的大小写:
保存大小写仅当文件无语法主题，要强制为所有文档不更改已键入符号的大小写的话，使用 Shift+Enter 从列表中选择。


*** 外部调用 Coder::HighLight ***

Call("Coder::HighLight", 2, "#RRGGBB", "#RRGGBB", FLAGS, FONTSTYLE, ID, "TEXT", TEXTLENGTH)
  参数:
    2
      标记选定或指定的文本。
    "#RRGGBB"
      文本颜色，"0" 表示忽略。
    "#RRGGBB"
      背景颜色，"0" 表示忽略。
    FLAGS (下列的和):
      1  区分大小写 (默认值)。
      2  "TEXT" 参数为正则表达式。
      4  整个单词。
         默认值: 1。
    FONTSTYLE (下列之一):
      0  忽略 (默认值)。
      1  常规。
      2  粗体。
      3  斜体。
      4  粗斜体。
    ID
      标记 ID (默认值为 -1)。如果值为 -1，将自动分配。
    "TEXT"
      要标记的文本。如果有指定，忽略选定区域。
    TEXTLEN
      文本长度 (默认值为 -1)。如果值为 -1，文本字符串在遇到 NULL 符号时终止。
  例:
    Call("Coder::HighLight", 2, "#000000", "#9BFF9B", 1, 0, 1)

Call("Coder::HighLight", 3, ID, "#RRGGBB", "#RRGGBB")
  参数:
    3
      取消标记文本。
    ID
      标记 ID (默认值为 0)。如果为零就去除所有标记。
      如果值为 -1，根据颜色删除自动分配的 ID。
      如果值为 -2，就删除选定文本的标记。
    "#RRGGBB"
      文本颜色，如果值为 "0" 时忽略。
    "#RRGGBB"
      背景颜色，如果值为 "0" 时忽略。
  例:
    Call("Coder::HighLight", 3, 0)

Call("Coder::HighLight", 4, ID, "#RRGGBB", "#RRGGBB", DIRECTION)
  参数:
    4
      查找标记。
    ID
      标记 ID (默认值为 0)。如果为零，查找任何标记。
      如果为 -1，自动根据颜色查找已分配 ID。
      如果为 -2, 查找选定文本的标记。
    "#RRGGBB"
      文本颜色，如果值为 "0" 时忽略。
    "#RRGGBB"
      背景颜色，如果值为 "0" 时忽略。
    DIRECTION (下列之一):
      0 向下查找 (默认值)。
      1 向上查找。
  例:
    Call("Coder::HighLight", 4, 0, 0, 0, 1)


*** 外部调用 Coder::CodeFold ***

Call("Coder::CodeFold", 1, *WINDOW)
  参数:
    1
      显示/隐藏列表。
    *WINDOW
      选项参数。指针指向一个接收泊坞式窗口句柄的变量。
  例 (获得泊坞式窗口句柄):
    WScript.Echo(GetCodeFoldWindow());

    function GetCodeFoldWindow()
    {
      var lpWnd;
      var hWnd=0;

      if (lpWnd=AkelPad.MemAlloc(_X64?8:4 /*sizeof(HWND)*/))
      {
        AkelPad.CallW("Coder::CodeFold", 1, lpWnd);
        hWnd=AkelPad.MemRead(lpWnd, 2 /*DT_QWORD*/);
        AkelPad.MemFree(lpWnd);
      }
      return hWnd;
    }


Call("Coder::CodeFold", 2)
  参数:
    2
      转到规则。


*** 外部调用 Coder::Settings ***

Call("Coder::Settings", 1, "EXTENSION")
  参数:
    1
      根据扩展手动设置语法主题。
    "EXTENSION"
      扩展名，例: "html"。如果缺少扩展参数将取消手动主题设置。
      如果扩展参数等于 "?"，就认为文档无主题。

Call("Coder::Settings", 2, *USECACHE)
  参数:
    2
      更新缓存。
    *USECACHE
      可选参数。指针指向一个接收缓存类型。下列值之一:
      0  //UC_NONE   无缓存。
      1  //UC_FAST   快速缓存。
      2  //UC_SMART  智能缓存。

Call("Coder::Settings", 3, PAGE)
  参数:
    3
      在指定页打开设置对话框。
    PAGE
      零基于页索引。

Call("Coder::Settings", 4, FLAGS, "FILE")
  参数:
    4
      导出文本到 RTF。
    FLAGS (下面的和):
         1  导出到文件。
        16  复制到剪贴板。
        32  使用文本填充纯文本格式的剪贴板。必须和 16 组合使用。
        64  使用带格式的文本填充纯文本格式的剪贴板。必须和 16 组合使用。
       256  导出选定区域的文本的颜色。
       512  导出当前行的颜色。
      1024  导出交替行的颜色。
      2048  不导出基本文本颜色。
      4096  不导出基本背景颜色。
     65536  仅导出选定区域。默认情况是导出选定区域或如果选定区域为空时导出文档的全部。
    131072  强制导出文档的全部。默认情况是导出选定区域或如果选定区域为空时导出文档的全部。
             默认值: 16+32=48。
    "FILE"
      导出到的文件。如果标记为 1 时使用。默认情况是打开选择文件的对话框。

Call("Coder::Settings", 5, "COLORTHEME")
  参数:
    5
      设置颜色主题。
    "COLORTHEME"
      颜色主题名称，例如: "Bespin"。

Call("Coder::Settings", 6, "ALIAS")
  参数:
    6
      根据别名手动设置语法主题。
    "ALIAS"
      别名，例: ".html". 如果别名参数被省略，手动主题设置将被取消。
      如果别名参数等于 "?"，文档将被定义为无主题文档。

Call("Coder::Settings", 12, "ALIAS", *BOOL)
  参数:
    12
      根据别名检查语法主题活动情况。使用 Scripts 插件。
    "ALIAS"
      别名, 例: ".html"。
    *BOOL
      指针指向一个接收语法主题活动性的变量。
  例:
    WScript.Echo(CheckAlias(".html"));

    function CheckAlias(pAlias)
    {
      var lpActive;
      var bActive=false;

      if (lpActive=AkelPad.MemAlloc(4 /*sizeof(BOOL)*/))
      {
        AkelPad.CallW("Coder::Settings", 12, pAlias, lpActive);
        bActive=AkelPad.MemRead(lpActive, 3 /*DT_DWORD*/);
        AkelPad.MemFree(lpActive);
      }
      return bActive;
    }

Call("Coder::Settings", 14, "COLORTHEME", *BOOL)
  参数:
    14
      根据名称检查颜色主题活动情况。使用 Scripts 插件。
    "COLORTHEME"
      颜色主题名称，例: "Bespin"。
    *BOOL
      指针指向一个接收颜色主题活动性的变量。
  例:
    WScript.Echo(CheckVarTheme("Bespin"));

    function CheckVarTheme(pVarTheme)
    {
      var lpActive;
      var bActive=false;

      if (lpActive=AkelPad.MemAlloc(4 /*sizeof(BOOL)*/))
      {
        AkelPad.CallW("Coder::Settings", 14, pVarTheme, lpActive);
        bActive=AkelPad.MemRead(lpActive, 3 /*DT_DWORD*/);
        AkelPad.MemFree(lpActive);
      }
      return bActive;
    }

Call("Coder::Settings", 16, WINDOW, *SYNTAXFILE, SYNTAXFILELENGTH)
  参数:
    16
      根据窗口句柄获取语法文件名称。使用 Scripts 插件。
    WINDOW
      编辑窗口句柄。如果为 零 就使用活动的编辑窗口。
    *SYNTAXFILE
      指针指向一个接收语法文件名称的缓存。
    SYNTAXFILELENGTH
      可以接收的 SYNTAXFILE 最大符号数。
  例:
    WScript.Echo(GetSyntaxFile(0));

    function GetSyntaxFile(hWndEdit)
    {
      var pSyntaxFile="";
      var lpSyntaxFile;

      if (lpSyntaxFile=AkelPad.MemAlloc(256 * 2 /*sizeof(wchar_t)*/))
      {
        AkelPad.CallW("Coder::Settings", 16, hWndEdit, lpSyntaxFile, 256);
        pSyntaxFile=AkelPad.MemRead(lpSyntaxFile, 1 /*DT_UNICODE*/);
        AkelPad.MemFree(lpSyntaxFile);
      }
      return pSyntaxFile;
    }

Call("Coder::Settings", 18, WINDOW, DOCUMENT, *ALIAS, *ALIASLENGTH)
  参数:
    18
      根据窗口句柄获得别名。使用 Scripts 插件。
    WINDOW
      编辑窗口句柄。如果为 零 就使用活动的编辑窗口。
    DOCUMENT
      编辑文档句柄。如果为 零 就自动检测。
    *ALIAS
      指针指向一个接收别名的缓存。可以为 NULL。
    *ALIASLENGTH
      指针指向一个接收已复制到 ALIAS 的符号数。可以为 NULL。
  例:
    WScript.Echo(GetAlias(0, 0));

    function GetAlias(hWndEdit, hDocEdit)
    {
      var pAlias="";
      var lpAlias;

      if (lpAlias=AkelPad.MemAlloc(256 * 2 /*sizeof(wchar_t)*/))
      {
        AkelPad.CallW("Coder::Settings", 18, hWndEdit, hDocEdit, lpAlias, 0);
        pAlias=AkelPad.MemRead(lpAlias, 1 /*DT_UNICODE*/);
        AkelPad.MemFree(lpAlias);
      }
      return pAlias;
    }

Call("Coder::Settings", 20, WINDOW, *COLORTHEME, COLORTHEMELENGTH)
  参数:
    20
      根据窗口句柄获得颜色主题名称。使用 Scripts 插件。
    WINDOW
      编辑窗口的句柄。如果为 零 就使用活动的编辑窗口。
    *COLORTHEME
      指针指向一个接收颜色主题名称的缓存。
    COLORTHEMELENGTH
      COLORTHEME 可以接收的最大符号数。
  例:
    WScript.Echo(GetVarTheme(0));

    function GetVarTheme(hWndEdit)
    {
      var pVarTheme="";
      var lpVarTheme;

      if (lpVarTheme=AkelPad.MemAlloc(256 * 2 /*sizeof(wchar_t)*/))
      {
        AkelPad.CallW("Coder::Settings", 20, hWndEdit, lpVarTheme, 256);
        pVarTheme=AkelPad.MemRead(lpVarTheme, 1 /*DT_UNICODE*/);
        AkelPad.MemFree(lpVarTheme);
      }
      return pVarTheme;
    }

Call("Coder::Settings", 22, WINDOW, DOCUMENT, "VARNAME", *VARVALUE, *VARVALUELENGTH)
  参数:
    22
      根据窗口句柄从颜色主题中获得变量值。使用 Scripts 插件。
    WINDOW
      编辑窗口的句柄。如果为 零 就使用活动的编辑窗口。
    DOCUMENT
      编辑文档句柄。如果为 零 就自动检测。
    "VARNAME"
      变量名，例: "AutoComplete_Indent"。
    *VARVALUE
      指针指向一个接收变量值的缓存。
    *VARVALUELENGTH
      指针指向一个接收已复制到 VARVALUE 的符号数。可以为 NULL。
  例:
    WScript.Echo(GetVariable(0, 0, "STR"));

    function GetVariable(hWndEdit, hDocEdit, pVarName)
    {
      var pVarValue="";
      var lpVarValue;

      if (lpVarValue=AkelPad.MemAlloc(32 * 2 /*sizeof(wchar_t)*/))
      {
        AkelPad.CallW("Coder::Settings", 22, hWndEdit, hDocEdit, pVarName, lpVarValue);
        pVarValue=AkelPad.MemRead(lpVarValue, 1 /*DT_UNICODE*/);
        AkelPad.MemFree(lpVarValue);
      }
      return pVarValue;
    }


*** 缓存文件的结构 ***

[Cache]
bat.coder=257CB20001CEE2DA:"*.bat" "*.cmd"
cpp.coder=DCD8500001CF30A3,1:"*.cpp" "*.c"

cpp.coder
  语法文件。
DCD8500001CF30A3
  cpp.coder 的修改时间。
1
  可选手动参数。如果为 1，那么不从 cpp.coder 更新文件类型信息。
"*.cpp" "*.c"
  文件类型。

*** 使用于 *.coder 文件中的层次结构的说明 ***

Rule ID, Parent ID
  被指定 Rule ID 标识符的是父级规则。而被指定 Parent ID 标识符的是子规则，仅在父级规则中适用。

  例如：分隔符 "/" 仅在 "<" 和 ">" 之间才被发现和高亮显示为 "#FF0000"。
  Quotes:
  ;===================================================================================
  ;Flags  Font    Color   Color   Quote   Quote   Escape  Quote   Quote   Parent  Rule
  ;       style   text    bkgrnd  start   end     char    include exclude ID      ID
  ;===================================================================================
  ;5=1+4
  5       0       0       0       "<"     ">"     ""      ""      ""      0       123

  Delimiters:
  ;===============================================
  ;Flags  Font    Color   Color   Char(s)   Parent
  ;       style   text    bkgrnd            ID
  ;===============================================
  1       0       #FF0000 0       "/"       123

  - 多条规则可以使用同一 Rule ID 标识符。在这种情况下，在 Parent ID 指定了这个标识符的子规则在任何父级中都适用。
  - "Delimiters:" 段落中使用的 Parent ID 可以来自于 "Quotes:"、"QuotesRE:"、"Folds:"。
  - "Words:" 段落中使用的 Parent ID 可以来自于 "Quotes:"、"QuotesRE:"、"Folds:"。
  - "Quotes:" 段落中使用的 Parent ID 可以来自于 "Quotes:"、"QuotesRE:"、"Folds:"。
  - "QuotesRE:" 段落中使用的 Parent ID 可以来自于 "Quotes:"、"QuotesRE:"、"Folds:"。
  - "Folds:" 段落中使用的 Parent ID 仅来自于 "Folds:"。
  - 如果 Parent ID 为 0 (默认值):
    - 规则生效于无样式引用 ("Quotes:", "QuotesRE:")中。
    - 规则在样式引用 ("Quotes:", "QuotesRE:")中被忽略。
    - 规则生效于无样式折叠 ("Folds:") 中。
    - 仅来自 "Folds:" 的规则生效于样式折叠 ("Folds:") 中，而其他段落的被忽略。
  - 如果 Parent ID 为 -1, 那么规则可能不属于所有父级标识符 (Rule ID) > 0 的。
  - 如果 Parent ID 为 -2:
    - 在父级标识符 (Rule ID) == 0 中，规则被忽略。
    - 在父级标识符 (Rule ID) > 0 中:
      - 规则标识符 (Rule ID) 被省略，规则被执行。
      - 规则标识符 (Rule ID) <> 父级标识符 (Rule ID)时，规则被执行。
      - 规则标识符 (Rule ID) == 父级标识符 (Rule ID)时，规则被忽略。
  - 如果 Parent ID为 -3:
    - 在父级标识符 (Rule ID) == 0 中, 将把 Parent ID 当作等于 0 看待。
    - 在父级标识符 (Rule ID) > 0 中:
      - 规则标识符 (Rule ID) 被忽略，规则被执行。
      - 规则标识符 (Rule ID) <> 父级标识符 (Rule ID)时，规则被执行。
      - 规则标识符 (Rule ID) == 父级标识符 (Rule ID)时，规则被忽略。

Rule file
  Rule file - 作为一个单独模块，来自于其它特定语法规则的 .coder 文件。

  - 根据折叠起始和折叠结束表达式匹配的文本将会根据当前 .coder 文件和规则文件的内容来高亮显示。
  - 在字符串文件规则中规定了特定的 .coder 文件，例如："cpp.coder" 或别名格式为: "alias: .cpp"。
  - 示例请参阅 html.coder。


*** 用于 Coder::Settings 主题的几个变量的说明 ***

自动选区标记:
  HighLight_AutoMarkFlags
    标记 (下列成员之和):
    1  区分大小写 (默认值)。
    2  整字匹配。
       默认值: 1。
  HighLight_AutoMarkFontStyle
    字形 (下列之一):
    0  忽略 (默认值)。
    1  常规。
    2  粗体。
    3  斜体。
    4  粗斜体。
  HighLight_AutoMarkTextColor
    文本颜色。如果为 0，将使用默认值。
  HighLight_AutoMarkBkColor
    背景颜色。如果为 0，将使用默认值。

用于插件 LineBoard 的变量:
  LineBoard_TextColor
    文本颜色。如果为 0 就不设置。
  LineBoard_BkColor
    文本背景颜色。如果为 0 就不设置。
  LineBoard_BorderColor
    边框颜色。如果为 0 就不设置。
  LineBoard_BookmarkTextColor
    书签文本颜色。如果为 0 就不设置。
  LineBoard_BookmarkBkColor
    书签背景颜色。如果为 0 就不设置。
  LineBoard_BookmarkBorderColor
    书签边框颜色。如果为 0 就不设置。
  LineBoard_LineUnsavedColor
    未保存行的颜色。如果为 0 就不设置。
  LineBoard_LineSavedColor
    已保存行的颜色。如果为 0 就不设置。
  LineBoard_RulerScaleColor
    比例标尺颜色。如果为 0 就不设置。
  LineBoard_RulerCaretColor
    插入点标尺颜色。如果为 0 就不设置。

用于插件 SpecialChar 的变量:
  SpecialChar_BasicFontStyle
    常规字形 (下列之一):
    0  忽略 (默认值)。
    1  常规。
    2  粗体。
    3  斜体。
    4  粗斜体。
  SpecialChar_BasicTextColor
    常规文本颜色。如果为 0 就不设置。
  SpecialChar_BasicBkColor
    常规背景颜色。如果为 0 就不设置。
  SpecialChar_SelFontStyle
    选定区域中的字形 (下列之一):
    0  忽略 (默认值)。
    1  常规。
    2  粗体。
    3  斜体。
    4  粗斜体。
  SpecialChar_SelTextColor
    选定文本的颜色。如果为 0 就不设置。
  SpecialChar_SelBkColor
    选定文本的背景颜色。如果为 0 就不设置。

用于插件 Sessions 的变量:
  Sessions_ListTextColor
    列表文本颜色。如果为 0 就不设置。
  Sessions_ListBkColor
    列表背景颜色。如果为 0 就不设置。
