﻿/*
	Copyright by FrankHB 2009 - 2013.

	This file is part of the YSLib project, and may only be used,
	modified, and distributed under the terms of the YSLib project
	license, LICENSE.TXT.  By continuing to use, modify, or distribute
	this file you indicate that you have read the license and
	understand and accept it fully.
*/

/*!	\file YSLib.txt
\ingroup Documentation
\brief YSLib 及相关库的细节汇总和暂定说明。
\version r1378
\author FrankHB <frankhb1989@gmail.com>
\since 早于 build 132
\par 创建时间:
	2009-12-02 05:14:30 +0800
\par 修改时间:
	2013-04-20 17:36 +0800
\par 字符集:
	UTF-8
\par 模块名称:
	Documentation::YSLib
*/


/*
@0 体例和适用范围：
以字符 @ 起始的行作为章节标题。
单独一行“//[”表示引用文本段落起始；单独一行“//]”表示引用文本段落终止。
本文档适用于 YSLib 。

@1 Shell 消息列表：

//全局系统消息。
//除另有说明外，一般用作队列消息。

//空消息。参考优先级 0xF0 。
//参数类型 void 。
//通常除了对消息计数外，应被无条件忽略。
SM_NULL					0x0000

// Shell 设置消息。参考优先级 0x80 。
//参数类型 shared_ptr<Shell> 。
//指示 Shell 切换，控制权移交给目标 Shell 。参数是目标 Shell 句柄。
SM_SET					0x0003

// UI 消息。

// Shell 绘制消息。参考优先级 0xE0 。
//参数类型 shared_ptr<Desktop> 。
//用于绘制对应的桌面。具体行为由 Shell 派生类定义（例如对于已知的多个桌面，参数可能会被忽略）。
SM_PAINT				0x000F

// 调度消息。

//退出消息。参考优先级 0xFF 。
//参数类型 int 。
//终止进程。通过调用 PostQuitMessage 函数产生。参数被传递作为退出码。
SM_QUIT					0x0012

//任务消息。参考优先级 0x20 。
//参数类型 std::function<void()> 。
//调用参数指定的函数，一般作为后台任务。应注意保持相关对象的有效的生存期，如无法满足应从消息队列中移除。
SM_TASK					0x0016

// Shell 通用交互消息。

// Shell 扩展消息。

//输入消息。参考优先级 0x40 。
//参数类型 void 。
//指示输入设备接收用户输入并产生输入事件。
SM_INPUT				0x00FF

@2 当前非确定上层实现注意事项：

@2.1 ShellHelper ：
注意严格禁止 CallStored 在未生效前被调用多次以免破坏消息队列。

@2.2 后台任务：
注意生存期。

@3 初始化：
初始化由 Helper进行。

@3.1 配置：
自 build 300 起，配置不再硬编码，初始化时读取配置文件的内容。
读取行为、配置文件格式和默认配置见以下说明。

@3.1.1 build 343 前：
配置文件路径 "config.txt" 。
若配置不存在则首先生成。
要求配置文件为 UTF-8 编码（实际当内容仅含 ASCII 字符时，允许 ANSI 兼容编码），否则出错。
读取的默认配置内容和之前硬编码项相同。
默认配置如下：
//[
H:\NDS\EFSRoot\Data\
H:\NDS\EFSRoot\Font\FZYTK.TTF
H:\NDS\EFSRoot\Font\

//]

@3.1.2 build 343 起：
配置文件路径 "yconf.txt" ，格式和之前不兼容。
若配置不存在则首先使用 NPL 生成。
要求配置文件为 UTF-8 编码（实际当内容仅含 ASCII 字符时，允许 ANSI 兼容编码），否则出错。
读取的默认配置内容中项的值和之前相同。
生成的默认配置如下：
//[
YFramework
(
	DataDirectory "H:\NDS\EFSRoot\Data\\"
)
(
	FontDirectory "H:\NDS\EFSRoot\Font\\"
)
(
	FontFile "H:\NDS\EFSRoot\Font\FZYTK.TTF"
)

//]

@3.1.2 build 344 起：
增加无名节点配置支持。
生成的默认配置不变，但支持以下形式（直接编辑或追加其它配置项时变换为此形式）：
//[

(
	YFramework
	(
		DataDirectory "H:\NDS\EFSRoot\Data\\"
	)
	(
		FontDirectory "H:\NDS\EFSRoot\Font\\"
	)
	(
		FontFile "H:\NDS\EFSRoot\Font\FZYTK.TTF"
	)
)
//]

@4 计划 GUI 测试项目 ShlExplorer ：

@4.1 基本部件测试：
 Label 、 Button 、 Window 等基本控件的静态显示。

@4.2 隐含部件测试（非单独测试，作为正常功能集成使用）：
 Button 功能。
 CheckBox 功能。
 ListBox 功能（含 VerticalTrack 和 VerticalScrollBar 功能）。
 FileBox 功能。
 ProgressBar 功能。

@4.3 部件综合测试：
 显示/隐藏控件。
顶层控件测试：菜单和子菜单测试。

@4.4 进阶互斥测试组：

@4.4.1 显示：
屏幕直接绘制。
动态 FPS 显示。

@4.4.2 屏幕接触移动：
边界测试：移动接触点记录 Enter 和 Leave 事件参数。
拖放测试：拖动控件（ Button 和 Window 等）。

@4.4.3 背景变换：
背景色变换。
背景图像替换。

@5 DS 测试项目 ShlReader ：
文本阅读器和十六进制阅读器。

@5.1 文本浏览：
支持 txt 、 c 、 cpp 、 ini 等后缀按文本打开。
使用随机载入复杂度为 O(1) 的算法，缓冲时间和文本文件大小无关。

@5.1.1 编码支持：
支持带 BOM 的 UTF-8 、 UCS2-LE 、 UCS2-BE 、 UCS-4LE 、 UCS-4BE 编码。
不带 BOM 的编码只读取文件起始字节（至多 64 个）判断为 UTF-8 或 GBK 。
按 GBK 打开时，可以顺序阅读，但不保证随机定位后读取的内容正常（GBK 无法保证随机定位时一定能选取到字符起始字节）。
模拟器上读取 GBK 编码文件极慢（可能需要等待数十秒），因为需要在二进制文件中载入编码表，属于正常情况。

@5.1.2 操作说明：
上下换行，左右翻页， LR 调整行距， XY 调整字体 。
 Start 开启自动滚屏（可在设置界面配置以行为单位或以像素为单位平滑滚屏以及滚屏时间间隔），任意其它输入停止。
点击屏幕显示/隐藏显示状态和详细功能按钮的阅读框。
点击阅读框中的进度随机定位。
点击 M 按钮打开菜单。
点击 S 按钮打开设置面板。
点击 I 按钮打开文件和阅读位置信息。
点击 B 按钮打开书签面板。焦点在书签列表框外时可以按键盘滚动并在上屏浏览文本。
点击 R 按钮返回。
点击 ←→ 按钮前进/后退（切换最近浏览位置）。
其它功能，如切换字体和背景颜色等，使用菜单（ M 按钮）选择“设置”进入详细设置界面自定义。

@5.1.3 设置和配置：

@5.1.3.1 build 345 起：
支持选择设置保存为配置项到配置文件。配置文件仅当进入文本阅读器时会被读取，正常退出时会被写入。
打开 Shell 读取文件时自动载入配置，若不存在则生成并追加（但配置不存在且打开的文件是配置文件时会导致读写冲突，无法响应）。
退出 Shell 时保存配置。
生成的默认配置如下：
//[
(
	YReader
	(
		ReaderSetting
		(
			DownColor "192 216 240"
		)
		(
			FontColor "0 0 0"
		)
		(
			FontFamily "SimSun"
		)
		(
			FontSize "14"
		)
		(
			ScrollDuration "1000"
		)
		(
			SmoothScroll "1"
		)
		(
			SmoothScrollDuration "80"
		)
		(
			UpColor "240 216 192"
		)
	)
)
//]

@5.1.3.2 build 400 起：
追加书签读取和写入支持，保存至 YReader 下 Bookmarks 节点，形如：
Bookmarks
(
	"F:\Programing\NDS\YSTest\CC BY-SA 3.0 legalcode.txt" "173 743 0 3578 "
)
整数值表示在文件的字节位置。
空白符除了作为间隔以外会被忽略。以空白符分组后，非整数值起始的项时此项和之后所有项都会被删除。

@6 测试注记：
示例测试项目 YSTest 包含 @4 和 @5 提到的测试。
自 build 363 起关于界面包含编译时间，因此原则上不会有相同的二进制文件。

@6.1 执行覆盖：
二进制相同的映像不重复测试。
 build 132 前的所有版本、 build 398 及之前的 DS 提交版本（除 build 387 rev 20[release] ）经过 iDSL+DSTT 实机测试。
所有 DS 版本经过 PC 测试。测试环境 Windows 7 Ultimate x64 + DeSmuME(x86/x64) 0.9.6 或以上（含 SVN 版本）。
所有 MinGW32 版本经过 PC 测试。测试环境 Windows 7 Ultimate x64 。

@6.1.1 非正式支持平台：
 2013-02-13: ArchLinux x86-64 使用 wine-1.5.23 测试 MinGW32 平台版本 b346 、 b352 、 b360 、 b372 和 b379 可正常载入配置和退出，但打开文件时候程序失败。

*/

////

