@compass-framework/core 1.2.59 → 1.2.61

package/@types/{View.d.ts → view/View.d.ts}

@@ -5,278 +5,656 @@ import {
 } from "@compass-framework/library";
 
 import { ViewOverlay } from "./ViewOverlay";
-import { Context } from "./Context";
-import { Configuration } from "./Configuration";
-import { Rect } from "./Rect";
-import { AttributeSet } from "./AttributeSet";
-import { Canvas } from "./Canvas";
-import { Transformation } from "./Transformation";
-import { KeyEvent } from "./KeyEvent";
-import { Drawable } from "./Drawable";
+import { Context } from "../content/Context";
+import { Configuration } from "../content/Configuration";
+import { Rect } from "../canvas/Rect";
+import { AttributeSet } from "../content/AttributeSet";
+import { Canvas } from "../canvas/Canvas";
+import { Transformation } from "../animation/Transformation";
+import { KeyEvent } from "../event/KeyEvent";
+import { Drawable } from "../drawable/Drawable";
 import { Outline } from "./Outline";
 import { ViewTreeObserver } from "./ViewTreeObserver";
 import { ViewGroup } from "./ViewGroup";
-import { Animation } from "./Animation";
-import { MotionEvent } from "./MotionEvent";
-import { Matrix } from "./Matrix";
-import { Resources } from "./Resources";
+import { Animation } from "../animation/Animation";
+import { MotionEvent } from "../event/MotionEvent";
+import { Matrix } from "../canvas/Matrix";
+import { Resources } from "../content/Resources";
 import { ViewParent } from "./ViewParent";
 import { ViewOutlineProvider } from "./ViewOutlineProvider";
-import { DisplayMetrics } from "./DisplayMetrics";
-import { IWindow } from "./IWindow";
+import { DisplayMetrics } from "../content/DisplayMetrics";
+import { Window } from "../window/Window";
 
 /**
  * 基础视图，负责测量、布局、绘制与事件分发。
  */
 export declare class View implements Drawable.Callback {
+  /**
+   * 根据测量规格解析最终尺寸。
+   */
   public static resolveSize(size: number, measureSpec: number): number;
+  /**
+   * 从测量规格中提取测量模式。
+   */
   public static getMode(measureSpec: number): number;
+  /**
+   * 根据期望尺寸与测量规格计算默认尺寸。
+   */
   public static getDefaultSize(size: number, measureSpec: number): number;
 
+  /**
+   * 不可见但仍占用布局空间。
+   */
   public static INVISIBLE: number;
+  /**
+   * 不可见且不占用布局空间。
+   */
   public static GONE: number;
+  /**
+   * 可见。
+   */
   public static VISIBLE: number;
 
+  /**
+   * 使用运行时上下文构造视图。
+   */
   public constructor(context: Context);
+  /**
+   * 使用上下文与属性集合构造视图。
+   */
   public constructor(context: Context, attrs: AttributeSet);
 
+  /**
+   * 通知宿主指定 Drawable 需要重绘。
+   */
   public invalidateDrawable(who: Drawable): void;
 
+  /**
+   * 在指定时间调度 Drawable 的回调。
+   */
   public scheduleDrawable(who: Drawable, what: Runnable, when: number): void;
 
+  /**
+   * 取消已调度的 Drawable 回调。
+   */
   public unScheduleDrawable(who: Drawable, what: Runnable): void;
 
+  /**
+   * 返回视图是否可获取焦点。
+   */
   public isFocusable(): boolean;
 
+  /**
+   * 返回触摸模式下是否可获取焦点。
+   */
   public isFocusableInTouchMode(): boolean;
 
+  /**
+   * 返回视图当前是否拥有焦点。
+   */
   public isFocused(): boolean;
 
+  /**
+   * 标记视图需要重绘。
+   */
   public invalidate(): void;
 
+  /**
+   * 标记视图轮廓需要重新计算。
+   */
   public invalidateOutline(): void;
 
+  /**
+   * 根据宽高测量规格测量视图。
+   */
   public measure(widthMeasureSpec: number, heightMeasureSpec: number): void;
 
+  /**
+   * 将视图布局到指定边界。
+   */
   public layout(left: number, top: number, right: number, bottom: number): void;
 
+  /**
+   * 将视图绘制到指定画布。
+   */
   public draw(canvas: Canvas): void;
 
+  /**
+   * 按数字 ID 查找子视图。
+   */
   public findViewById(id: number): View;
+  /**
+   * 按字符串 ID 查找子视图。
+   */
   public findViewById(id: string): View;
 
+  /**
+   * 按标签查找第一个匹配的子视图。
+   */
   public findViewByTag(tag: string): View;
 
+  /**
+   * 按标签查找所有匹配的子视图。
+   */
   public findViewsByTag(tag: string): ArrayList<View>;
 
+  /**
+   * 将任务投递到视图消息队列，返回是否投递成功。
+   */
   public post(action:Runnable): boolean;
 
+  /**
+   * 移除尚未执行的投递任务，返回是否移除成功。
+   */
   public removeCallbacks(action: Runnable): boolean;
 
+  /**
+   * 返回视图或其子孙是否拥有焦点。
+   */
   public hasFocus(): boolean;
 
+  /**
+   * 请求父视图重新测量并布局。
+   */
   public requestLayout(): void;
 
+  /**
+   * 请求获取焦点，返回是否成功。
+   */
   public requestFocus(): boolean;
 
+  /**
+   * 清除当前焦点。
+   */
   public clearFocus(): void;
 
+  /**
+   * 添加附着/分离窗口状态变化监听器。
+   */
   public addOnAttachStateChangeListener(listener:View.OnAttachStateChangeListener): void;
 
+  /**
+   * 移除附着/分离窗口状态变化监听器。
+   */
   public removeOnAttachStateChangeListener(listener:View.OnAttachStateChangeListener): void;
 
+  /**
+   * 添加布局变化监听器。
+   */
   public addOnLayoutChangeListener(listener: View.OnLayoutChangeListener): void;
 
+  /**
+   * 移除布局变化监听器。
+   */
   public removeOnLayoutChangeListener(listener: View.OnLayoutChangeListener): void;
 
+  /**
+   * 滚动到指定绝对位置。
+   */
   public scrollTo(x: number, y: number): void;
 
+  /**
+   * 相对当前滚动位置偏移指定距离。
+   */
   public scrollBy(x: number, y: number): void;
 
+  /**
+   * 触发点击回调。
+   */
   public performClick(): void;
 
+  /**
+   * 启动视图动画。
+   */
   public startAnimation(animation:Animation) : void;
 
+  /**
+   * 测量回调，子类在此计算自身尺寸。
+   */
   public onMeasure(widthMeasureSpec: number, heightMeasureSpec: number): void;
 
+  /**
+   * 绘制回调，子类在此绘制自身内容。
+   */
   public onDraw(canvas: Canvas): void;
 
+  /**
+   * 布局回调，子类在此安排子视图位置。
+   */
   public onLayout(changed: boolean, left: number, top: number, right: number, bottom: number): void;
 
+  /**
+   * 设备或主题等配置变化时回调。
+   */
   public onConfigurationChanged(newConfig: Configuration): void;
 
+  /**
+   * 屏幕密度变化时回调。
+   */
   public onDensityMetricsChanged(newConfig: Configuration): void;
 
+  /**
+   * 返回视图透明度，取值范围为 0–1。
+   */
   public getAlpha(): number;
 
+  /**
+   * 返回视图宽度。
+   */
   public getWidth(): number;
 
+  /**
+   * 返回视图高度。
+   */
   public getHeight(): number;
 
+  /**
+   * 返回视图变换矩阵。
+   */
   public getMatrix(): Matrix;
 
+  /**
+   * 返回父视图。
+   */
   public getParent(): ViewParent;
 
+  /**
+   * 返回视图 ID。
+   */
   public getId(): number;
 
+  /**
+   * 返回变换枢轴点的 X 坐标。
+   */
   public getPivotX(): number;
 
+  /**
+   * 返回变换枢轴点的 Y 坐标。
+   */
   public getPivotY(): number;
 
+  /**
+   * 返回视图在父容器中的 X 坐标。
+   */
   public getX(): number;
 
+  /**
+   * 返回视图在父容器中的 Y 坐标。
+   */
   public getY(): number;
 
+  /**
+   * 返回当前显示度量。
+   */
   public getDisplayMetrics(): DisplayMetrics;
 
+  /**
+   * 返回水平滚动偏移。
+   */
   public getScrollX(): number;
 
+  /**
+   * 返回垂直滚动偏移。
+   */
   public getScrollY(): number;
 
+  /**
+   * 返回父视图。
+   */
   public getParent(): ViewParent;
 
+  /**
+   * 返回可见性，取值为 VISIBLE、INVISIBLE 或 GONE。
+   */
   public getVisibility(): number;
 
+  /**
+   * 返回布局参数。
+   */
   public getLayoutParams(): ViewGroup.LayoutParams;
 
+  /**
+   * 返回关联的运行时上下文。
+   */
   public getContext(): Context;
 
+  /**
+   * 返回背景 Drawable。
+   */
   public getBackground(): Drawable;
 
+  /**
+   * 返回绕枢轴点的旋转角度（度）。
+   */
   public getRotation(): number;
 
+  /**
+   * 返回水平平移量。
+   */
   public getTranslationX(): number;
 
+  /**
+   * 返回垂直平移量。
+   */
   public getTranslationY(): number;
 
+  /**
+   * 返回水平缩放比例。
+   */
   public getScaleX(): number;
 
+  /**
+   * 返回垂直缩放比例。
+   */
   public getScaleY(): number;
 
+  /**
+   * 返回建议的最小宽度。
+   */
   public getMinimumWidth(): number;
 
+  /**
+   * 返回建议的最小高度。
+   */
   public getMinimumHeight(): number;
 
+  /**
+   * 返回视图标签。
+   */
   public getTag(): string;
 
+  /**
+   * 返回视图叠加层。
+   */
   public getOverlay(): ViewOverlay;
 
+  /**
+   * 返回视图树观察者。
+   */
   public getViewTreeObserver(): ViewTreeObserver;
 
+  /**
+   * 返回轮廓提供者。
+   */
   public getOutlineProvider(): ViewOutlineProvider;
 
+  /**
+   * 将视图在屏幕上的位置写入长度为 2 的数组。
+   */
   public getLocationOnScreen(location: number[]): void;
 
+  /**
+   * 返回上内边距。
+   */
   public getPaddingTop(): number;
 
+  /**
+   * 返回下内边距。
+   */
   public getPaddingBottom(): number;
 
+  /**
+   * 返回附着窗口时的临时绘制与变换信息。
+   */
   public getAttachInfo(): View.AttachInfo;
 
+  /**
+   * 返回左内边距。
+   */
   public getPaddingLeft(): number;
 
+  /**
+   * 返回右内边距。
+   */
   public getPaddingRight(): number;
 
+  /**
+   * 返回关联的资源管理器。
+   */
   public getResources(): Resources;
 
+  /**
+   * 返回未经缩放换算的左内边距。
+   */
   public getRawPaddingLeft(): number;
 
+  /**
+   * 返回未经缩放换算的上内边距。
+   */
   public getRawPaddingTop(): number;
 
+  /**
+   * 返回未经缩放换算的右内边距。
+   */
   public getRawPaddingRight(): number;
 
+  /**
+   * 返回未经缩放换算的下内边距。
+   */
   public getRawPaddingBottom(): number;
 
+  /**
+   * 设置前景 Drawable。
+   */
   public setForeground(foreground: Drawable): void;
 
+  /**
+   * 设置是否处于悬停状态。
+   */
   public setHovered(hovered: boolean): void;
 
+  /**
+   * 设置变换枢轴点的 X 坐标。
+   */
   public setPivotX(x: number): void;
 
+  /**
+   * 设置变换枢轴点的 Y 坐标。
+   */
   public setPivotY(y: number): void;
 
+  /**
+   * 设置水平缩放比例。
+   */
   public setScaleX(x: number): number;
 
+  /**
+   * 设置垂直缩放比例。
+   */
   public setScaleY(y: number): number;
 
+  /**
+   * 设置是否启用绘制缓存。
+   */
   public setDrawingCacheEnabled(enabled: boolean): void;
 
+  /**
+   * 设置纯色背景。
+   */
   public setBackgroundColor(color: number): void;
 
+  /**
+   * 设置背景 Drawable。
+   */
   public setBackgroundDrawable(drawable: Drawable): void;
 
+  /**
+   * 设置视图是否跳过自身绘制。
+   */
   public setWillNotDraw(willNotDraw: boolean) :void;
 
+  /**
+   * 设置测量后的宽高，通常在 onMeasure 中调用。
+   */
   public setMeasuredDimension(measuredWidth: number, measuredHeight: number): void;
 
+  /**
+   * 设置建议的最小宽度。
+   */
   public setMinimumWidth(minWidth: number): void;
 
+  /**
+   * 设置建议的最小高度。
+   */
   public setMinimumHeight(minHeight: number): void;
 
+  /**
+   * 设置视图透明度，取值范围为 0–1。
+   */
   public setAlpha(alpha: number): void;
 
+  /**
+   * 设置可见性，取值为 VISIBLE、INVISIBLE 或 GONE。
+   */
   public setVisibility(visibility: number): void;
 
+  /**
+   * 设置视图标签。
+   */
   public setTag(tag: string): void;
 
+  /**
+   * 设置轮廓提供者。
+   */
   public setOutlineProvider(provider: ViewOutlineProvider): void;
 
+  /**
+   * 设置视图是否可获取焦点。
+   */
   public setFocusable(focusable: boolean): void;
 
+  /**
+   * 设置触摸模式下是否可获取焦点。
+   */
   public setFocusableInTouchMode(focusableInTouchMode: boolean): void;
 
+  /**
+   * 设置点击事件监听器。
+   */
   public setOnClickListener(l: View.OnClickListener): void;
 
+  /**
+   * 设置 inflate 完成回调监听器。
+   */
   public setOnFinishInflateListener(l: View.OnFinishInflateListener): void;
 
+  /**
+   * 设置按键事件监听器。
+   */
   public setOnKeyListener(l: View.OnKeyListener): void;
 
+  /**
+   * 设置触摸事件监听器。
+   */
   public setOnTouchListener(l: View.OnTouchListener): void;
 
+  /**
+   * 设置视图是否可点击。
+   */
   public setClickable(clickable: boolean): void;
 
+  /**
+   * 设置通用运动事件监听器。
+   */
   public setOnGenericMotionListener(l: View.OnGenericMotionListener): void;
 
+  /**
+   * 设置四周内边距。
+   */
   public setPadding(left: number, top: number, right: number, bottom: number): void;
 
+  /**
+   * 设置布局参数。
+   */
   public setLayoutParams(params: ViewGroup.LayoutParams): void;
 
+  /**
+   * 设置绕枢轴点的旋转角度（度）。
+   */
   public setRotation(rotation: number): void;
 
+  /**
+   * 设置是否按轮廓裁剪绘制内容。
+   */
   public setClipToOutline(clipToOutline: boolean): void;
 
+  /**
+   * 设置水平平移量。
+   */
   public setTranslationX(translationX: number): void;
 
+  /**
+   * 设置垂直平移量。
+   */
   public setTranslationY(translationY: number): void;
 
+  /**
+   * 设置悬停事件监听器。
+   */
   public setOnHoverListener(l: View.OnHoverListener): void;
 
+  /**
+   * 设置悬停时的鼠标光标样式。
+   */
   public setHoverCursor(cursor: string): void;
 
+  /**
+   * 设置悬停时显示的 Drawable。
+   */
   public setHoverDrawable(drawable: Drawable): void;
 
+  /**
+   * 设置焦点变化监听器。
+   */
   public setOnFocusChangeListener(l: View.OnFocusChangeListener): void;
 }
 
+/**
+ * View 相关嵌套类型。
+ */
 export declare namespace View {
   /**
    * 按圆角半径生成视图轮廓的 OutlineProvider。
    */
   export class ViewRadiusOutlineProvider extends ViewOutlineProvider {
+    /**
+     * 使用视图及四个圆角半径构造轮廓提供者。
+     */
     public constructor(view: View, ltr: number, lbr: number, rtr: number, rbr: number);
 
+    /**
+     * 设备或主题等配置变化时回调。
+     */
     public onConfigurationChanged(newConfig: Configuration): void;
 
+    /**
+     * 将视图外形轮廓写入指定 Outline。
+     */
     public getOutline(view: View, outline: Outline): void;
 
+    /**
+     * 同时设置四个圆角半径。
+     */
     public setRadius(value: number): void;
 
+    /**
+     * 设置左下圆角半径。
+     */
     public setLeftBottomRadius(value: number): void;
 
+    /**
+     * 设置左上圆角半径。
+     */
     public setLeftTopRadius(value: number): void;
 
+    /**
+     * 设置右下圆角半径。
+     */
     public setRightBottomRadius(value: number): void;
 
+    /**
+     * 设置右上圆角半径。
+     */
     public setRightTopRadius(value: number): void;
   }
 
@@ -284,20 +662,44 @@ export declare namespace View {
    * 视图附着窗口时的临时绘制与变换信息。
    */
   export class AttachInfo {
+    /**
+     * 返回透明区域定位用的临时坐标数组。
+     */
     public getTransparentLocation(): Array<number>;
 
+    /**
+     * 返回临时变换矩阵。
+     */
     public getTmpMatrix(): Matrix;
 
+    /**
+     * 返回子视图失效定位用的临时坐标数组。
+     */
     public getInvalidateChildLocation(): Array<number>;
 
-    public getWindow(): IWindow;
+    /**
+     * 返回所属窗口。
+     */
+    public getWindow(): Window;
 
+    /**
+     * 返回临时轮廓对象。
+     */
     public getTmpOutline(): Outline;
 
+    /**
+     * 返回变换定位用的临时坐标数组。
+     */
     public getTmpTransformLocation(): Array<number>;
 
+    /**
+     * 返回变换计算用的临时矩形。
+     */
     public getTmpTransformRect(): Rect;
 
+    /**
+     * 返回当前变换信息。
+     */
     public getTransformation(): Transformation;
   }
 
@@ -305,20 +707,50 @@ export declare namespace View {
    * 测量规格工具，编码尺寸与测量模式。
    */
   export class MeasureSpec {
+    /**
+     * 测量模式在规格值中的位移位数。
+     */
     public static MODE_SHIFT: number;
+    /**
+     * 测量模式掩码。
+     */
     public static MODE_MASK: number;
+    /**
+     * 未指定模式，父视图未施加约束。
+     */
     public static UNSPECIFIED: number;
+    /**
+     * 精确模式，子视图必须等于给定尺寸。
+     */
     public static EXACTLY: number;
+    /**
+     * 至多模式，子视图不得超过给定尺寸。
+     */
     public static AT_MOST: number;
 
+    /**
+     * 将尺寸与测量模式编码为测量规格。
+     */
     public static makeMeasureSpec(size: number, mode: number): number;
 
+    /**
+     * 创建安全的测量规格，避免溢出。
+     */
     public static makeSafeMeasureSpec(size: number, mode: number): number;
 
+    /**
+     * 从测量规格中提取测量模式。
+     */
     public static getMode(measureSpec: number): number;
 
+    /**
+     * 从测量规格中提取尺寸。
+     */
     public static getSize(measureSpec: number): number;
 
+    /**
+     * 按增量调整测量规格中的尺寸。
+     */
     public static adjust(measureSpec: number, delta: number): number;
   }
 
@@ -326,8 +758,14 @@ export declare namespace View {
    * 视图附着/分离窗口状态变化监听器。
    */
   export interface OnAttachStateChangeListener {
+    /**
+     * 视图附着到窗口时回调。
+     */
     onViewAttachedToWindow(v: View): void;
 
+    /**
+     * 视图从窗口分离时回调。
+     */
     onViewDetachedFromWindow(v: View): void;
   }
   /**
@@ -339,6 +777,9 @@ export declare namespace View {
    * 触摸事件监听器。
    */
   export interface OnTouchListener {
+    /**
+     * 处理触摸事件，返回是否已消费。
+     */
     onTouch(v: View, event: MotionEvent): boolean;
   }
   /**
@@ -350,6 +791,9 @@ export declare namespace View {
    * 点击事件监听器。
    */
   export interface OnClickListener {
+    /**
+     * 视图被点击时回调。
+     */
     onClick(v: View): void;
   }
   /**
@@ -361,6 +805,9 @@ export declare namespace View {
    * 悬停事件监听器。
    */
   export interface OnHoverListener {
+    /**
+     * 处理悬停事件，返回是否已消费。
+     */
     onHover(v: View, event: MotionEvent): boolean;
   }
   /**
@@ -372,6 +819,9 @@ export declare namespace View {
    * 按键事件监听器。
    */
   export interface OnKeyListener {
+    /**
+     * 处理按键事件，返回是否已消费。
+     */
     onKey(v: View, keyCode: number, event: KeyEvent): boolean;
   }
   /**
@@ -383,6 +833,9 @@ export declare namespace View {
    * 焦点变化监听器。
    */
   export interface OnFocusChangeListener {
+    /**
+     * 焦点变化时回调。
+     */
     onFocusChange(v: View, hasFocus: boolean): void;
   }
   /**
@@ -394,6 +847,9 @@ export declare namespace View {
    * 通用运动事件监听器。
    */
   export interface OnGenericMotionListener {
+    /**
+     * 处理通用运动事件，返回是否已消费。
+     */
     onGenericMotion(v: View, event: MotionEvent): boolean;
   }
   /**
@@ -405,6 +861,9 @@ export declare namespace View {
    * 布局尺寸或位置变化监听器。
    */
   export interface OnLayoutChangeListener {
+    /**
+     * 布局边界变化时回调，参数为新旧左、上、右、下坐标。
+     */
     onLayoutChange(v: View, left: number, top: number, right: number, bottom: number, oldLeft: number, oldTop: number, oldRight: number, oldBottom: number):void;
   }
   /**
@@ -416,6 +875,9 @@ export declare namespace View {
    * 视图完成 inflate 后的回调监听器。
    */
   export interface OnFinishInflateListener {
+    /**
+     * 视图 inflate 完成时回调。
+     */
     onViewFinishInflate(v: View): void;
   }
   /**